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).
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. |
[General] section |
|||
---|---|---|---|
Variable | Default | Meaning | ||
chunkSize |
10000000 (10 MB) |
Specifies the chunk size of uploaded files in bytes. The client will dynamically adjust this size within the maximum and minimum bounds (see below). | |
maxChunkSize |
100000000 (100 MB) |
Specifies the maximum chunk size of uploaded files in bytes. | |
minChunkSize |
1000000 (1 MB) |
Specifies the minimum chunk size of uploaded files in bytes. | |
targetChunkUploadDuration |
6000 (1 minute) |
Target duration in milliseconds for chunk uploads. The client adjusts the chunk size until each chunk upload takes approximately this long. Set to 0 to disable dynamic chunk sizing. | |
promptDeleteAllFiles |
true |
If a UI prompt should ask for confirmation if it was detected that all files and folders were deleted. | |
timeout |
300 |
The timeout for network connections in seconds. | |
moveToTrash |
false |
If non-locally deleted files should be moved to trash instead of deleting them completely. This option only works on linux | |
showExperimentalOptions |
false |
Whether to show experimental options that are still undergoing testing in the user interface. Turning this on does not enable experimental behavior on its own. It does enable user inferface options that can be used to opt in to experimental features. | |
showMainDialogAsNormalWindow |
false |
Whether the main dialog should be shown as a normal window even if tray icons are available. |
[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/Debian
$ sudo add-apt-repository ppa:nextcloud-devs/client
$ sudo apt update
$ sudo apt install nextcloud-client
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.