Advanced Usage¶
Options¶
You have the option of starting your Nextcloud desktop client with the
nextcloud
command. The following options are supported:
nextcloud -h
ornextcloud --help
- Displays all command options.
The other options are:
--logwindow
- Opens a window displaying log output.
--logfile
<filename>- Write log output to the file specified. To write to stdout, specify - as the filename.
--logdir
<name>- Writes each synchronization log output in a new file in the specified directory.
--logexpire
<hours>- Removes logs older than the value specified (in hours). This command is
used with
--logdir
. --logflush
- Clears (flushes) the log file after each write action.
--logdebug
- Also output debug-level messages in the log (equivalent to setting the env var QT_LOGGING_RULES=”qt.*=true;*.debug=true”).
--confdir
<dirname>- Uses the specified configuration directory.
--background
- Launch the application in the background (i.e. without opening the main dialog).
Mass Deployment And Account Creation¶
It is possible to perform mass deployment of the Nextcloud desktop client by passing certain command-line parameters from the deployment step to Nextcloud desktop client executable after the initial setup. This will allow desktop client to generate a config (.cfg) file that will be used during subsequent launches. A config file will have a corresponding account written into it similar to if you have added it manually via the desktop client’s UI. The desktop client will exit with code 0 if account has been added successfully, or 1 in case of failure. Detailed failure message is printed to the desktop client logs.
The following parameters are supported:
--userid
- (required) userId (username as on the server) to pass when creating an account via command-line.
--apppassword
- (required) appPassword to pass when creating an account via command-line (see the
login-flow
section in server documentation on how to generate the app password). --localdirpath
- (optional) path where to create a local sync folder when creating an account via command-line. If skipped, then default local sync folder path (/home/<userid>/Nextcloud<n> for Linux/mac or C:/<userid>/Nextcloud<n> for Windows) will be generated by desktop client.
--isvfsenabled
- (optional) whether to set a VFS or non-VFS folder (1 for ‘yes’ or 0 for ‘no’) when creating an account via command-line. Default is 0.
--remotedirpath
- (optional) path to a remote subfolder when creating an account via command-line. e.g. If the server has folders “/Photos”, “/Documents”, “/Music” you can pass “/Music” and then this folder will get set up as remote root.
--serverurl
- (required) a server URL to use when creating an account via command-line. (NOTE: There is another parameter supported by Nextcloud desktop client
--overrideserverurl
but it SHOULD NOT be used here as it is intended for setup via UI with wizard)
Examples:
C:\Program Files\Nextcloud\nextcloud.exe" --userid admin --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 --localdirpath "D:\\Nextcloud-sync-folder" --remotedirpath /Music --serverurl "https://cloud.example.com" --isvfsenabled 1"
- this will create a config file for user admin on the server https://cloud.example.com and set a remote root folder to “Music”, the local sync folder will get created with VFS mode.- For Linux and mac the same example as above will work but
nextcloud.exe path
and--localdirpath
value should get changed to platform specific format (e.g.no .exe extension
and/home/<user folder>
format)
Configuration File¶
The Nextcloud Client reads a configuration file. You can locate this configuration file as follows:
- On Linux distributions:
$HOME/.config/Nextcloud/nextcloud.cfg
- On Microsoft Windows systems:
%APPDATA%\Nextcloud\nextcloud.cfg
- On macOS systems:
$HOME/Library/Preferences/Nextcloud/nextcloud.cfg
The configuration file contains settings using the Microsoft Windows .ini file format. You can overwrite changes using the Nextcloud configuration dialog.
Note
Use caution when making changes to the Nextcloud Client configuration file. Incorrect settings can produce unintended results.
Some interesting values that can be set on the configuration file are:
[Nextcloud] section |
||
---|---|---|
Variable | Default | Meaning |
remotePollInterval |
30000 |
Specifies the poll time for the remote repository in milliseconds. |
forceSyncInterval |
7200000 |
The duration of no activity after which a synchronization run shall be triggered automatically. |
fullLocalDiscoveryInterval |
3600000 |
The interval after which the next synchronization will perform a full local discovery. |
notificationRefreshInterval |
300000 |
Specifies the default interval of checking for new server notifications in milliseconds. |
[Proxy] section |
||
---|---|---|
Variable | Default | Meaning |
host |
127.0.0.1 |
The address of the proxy server. |
port |
8080 |
The port were the proxy is listening. |
type |
2 |
0 for System Proxy. |
1 for SOCKS5 Proxy. |
||
2 for No Proxy. |
||
3 for HTTP(S) Proxy. |
Environment Variables¶
The behavior of the client can also be controlled using environment variables. The value of the environment variables overrides the values in the configuration file.
The environment variables are:
- OWNCLOUD_CHUNK_SIZE (default: 5242880; 5 MiB) – Specifies the chunk size of uploaded files in bytes. Increasing this value may help with synchronization problems in certain configurations.
- OWNCLOUD_TIMEOUT (default: 300 s) – The timeout for network connections in seconds.
- OWNCLOUD_CRITICAL_FREE_SPACE_BYTES (default: 50*1000*1000 bytes) - The minimum disk space needed for operation. A fatal error is raised if less free space is available.
- OWNCLOUD_FREE_SPACE_BYTES (default: 250*1000*1000 bytes) - Downloads that would reduce the free space below this value are skipped. More information available under the “Low Disk Space” section.
- OWNCLOUD_MAX_PARALLEL (default: 6) - Maximum number of parallel jobs.
- OWNCLOUD_BLACKLIST_TIME_MIN (default: 25 s) - Minimum timeout for blacklisted files.
- OWNCLOUD_BLACKLIST_TIME_MAX (default: 24*60*60 s; one day) - Maximum timeout for blacklisted files.
Nextcloud Command Line Client¶
The Nextcloud Client packages contain a command line client, nextcloudcmd
, that can
be used to synchronize Nextcloud files to client machines.
nextcloudcmd
performs a single sync run and then exits the synchronization
process. In this manner, nextcloudcmd
processes the differences between
client and server directories and propagates the files to bring both
repositories to the same state. Contrary to the GUI-based client,
nextcloudcmd
does not repeat synchronizations on its own. It also does not
monitor for file system changes.
Install nextcloudcmd
¶
CentOS
$ sudo yum -y install epel-release
$ sudo yum -y install nextcloud-client
Ubuntu
$ sudo add-apt-repository ppa:nextcloud-devs/client
$ sudo apt update
$ sudo apt install nextcloud-client
Debian
$ sudo apt install nextcloud-desktop-cmd
Refer to the link
- https://nextcloud.com/install/#install-clients
- https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client
- https://pkgs.alpinelinux.org/packages?name=nextcloud-client
- https://help.nextcloud.com/t/linux-packages-status/10216
To invoke nextcloudcmd
, you must provide the local and the remote repository
URL using the following command:
nextcloudcmd [OPTIONS...] sourcedir nextcloudurl
where sourcedir
is the local directory and nextcloudurl
is
the server URL.
Other command line switches supported by nextcloudcmd
include the following:
--path
- Overrides default remote root folder to a specific subfolder on the server(e.g.: /Documents would sync the Documents subfolder on the server)
--user
,-u
[user]
- Use
user
as the login name. --password
,-p
[password]
- Use
password
as the password. -n
- Use
netrc (5)
for login. --non-interactive
- Do not prompt for questions.
--silent
,--s
- Inhibits verbose log output.
--trust
- Trust any SSL certificate, including invalid ones.
--httpproxy http://[user@pass:]<server>:<port>
- Uses
server
as HTTP proxy. --exclude [file]
- Exclude list file
--unsyncedfolders [file]
- File containing the list of un-synced remote folders (selective sync)
--max-sync-retries [n]
- Retries maximum n times (defaults to 3)
-h
- Sync hidden files, do not ignore them
Credential Handling¶
nextcloudcmd
requires the user to specify the username and password using the standard URL pattern, e.g.,
$ nextcloudcmd /home/user/my_sync_folder https://carla:secret@server/nextcloud
To synchronize the Nextcloud directory Music
to the local directory
media/music
, through a proxy listening on port 8080
, and on a gateway
machine using IP address 192.168.178.1
, the command line would be:
$ nextcloudcmd --httpproxy http://192.168.178.1:8080 --path /Music \
$HOME/media/music \
https://server/nextcloud
nextcloudcmd
will prompt for the user name and password, unless they have
been specified on the command line or -n
has been passed.
Exclude List¶
nextcloudcmd
requires access to an exclude list file. It must either be
installed along with nextcloudcmd
and thus be available in a system location,
be placed next to the binary as sync-exclude.lst
or be explicitly specified
with the --exclude
switch.
Example¶
- Synchronize a local directory to the specified directory of the nextcloud server
$ nextcloudcmd --path /<Directory_that_has_been_created> /home/user/<my_sync_folder> \
https://<username>:<secret>@<server_address>
Low Disk Space¶
When disk space is low the Nextcloud Client will be unable to synchronize all files. This section describes its behavior in a low disk space situation as well as the options that influence it.
- Synchronization of a folder aborts entirely if the remaining disk space falls below 50 MB. This threshold can be adjusted with the
OWNCLOUD_CRITICAL_FREE_SPACE_BYTES
environment variable. - Downloads that would reduce the free disk space below 250 MB will be skipped or aborted. The download will be retried regularly and other synchronization is unaffected. This threshold can be adjusted with the
OWNCLOUD_FREE_SPACE_BYTES
environment variable.
Wizard Account Setup Command-line Options¶
If you want to automate an Account Setup Wizard to allow the user skip entering server URL and local sync folder path in UI, you can use command-line parameters. When you specify both, the desktop client’s Account Setup Wizard will jump straight to opening a browser for account authentication/connection without the need of entering any of the connection details. The local sync folder will also be selected to the one you specify instead of using default path (/home/Nextcloud)
The following parameters are supported:
--overridelocaldir
- specify a local dir to be used in the account setup wizard (e.g.: /home/nextcloud-sync-folder)
--overrideserverurl
- specify a server URL to use for the force override to be used in the account setup wizard (e.g.: https://cloud.example.com)
Examples:
- ``C:Program FilesNextcloudnextcloud.exe” –overridelocaldir “D:/work/nextcloud-sync-folder” –overrideserverurl https://cloud.example.com
- For Linux and mac the same example as above will work but
nextcloud.exe path
and--overridelocaldir
value should get changed to platform specific format (e.g.no .exe extension
and/home/<user folder>
format)