Client Applications

Nuxeo Drive

Updated: September 11, 2020

Installation

Installing Nuxeo Drive on Your Computer

If you try to synchronize a folder and you haven't installed the Nuxeo Drive client yet or haven't provided your credentials to the Nuxeo Drive client, you are automatically directed to the Nuxeo Drive home tab to install it.

download-document-web-ui.png
macOS

download-document-web-ui.png
Linux

download-document-web-ui.png
Windows

Installing Nuxeo Drive Addon

This addon requires no specific installation steps. It can be installed like any other package with nuxeoctl command line or from the Update Center.

After Nuxeo Drive has been installed on the server, a Nuxeo Drive tab in the user Home, from which you can see what Nuxeo spaces are synchronized with Drive.

Starting Nuxeo Drive

After you installed Nuxeo Drive, you need to start it manually.

Start Nuxeo Drive like any other application:

  • On macOS, Nuxeo Drive is in the Applications directory.
    When you double click on the icon the first time, a security message appears. This is normal, jus click on Open.
  • On Windows, Nuxeo Drive is started from Start > Programs > Nuxeo > Nuxeo Drive.

Upgrading Nuxeo Drive

When a new version of Nuxeo Drive is available, a message is displayed at the bottom of the systray menu.

  1. Click on the upgrade message at the bottom of the systray menu.
  2. If you want Nuxeo Drive to update silently the next time, check the box Automatically update Drive in the General tab.
  3. Click on the green icon. Nuxeo Drive is updated and automatically restarted.

Configuration

Settings

Accessing the Settings Window

macOS

  1. Click on the the icon (or on old versions) in the systray.
  2. Click on the icon and on the Settings menu item.
    The Settings window is displayed.

Windows

  1. Right-click on the the icon (or on old versions) in the systray.
  2. Click on the icon and on the Settings menu item.
    The Settings window is displayed.

The Nuxeo Drive settings window shows four tabs that enable you to customize the behavior of your Nuxeo Drive:

Graphical User Interface

  • General
    This is where you select the general behavior of your Nuxeo Drive: what language to use, the update policy, etc.

  • Features
    This is where you can turn on/off the features available on your application.

  • Accounts
    Set up one or several Nuxeo Platform accounts to synchronize with Nuxeo Drive.

  • About
    Information about the Nuxeo Drive version and license.

Managing Local Nuxeo Drive Accounts

You can use Nuxeo Drive to synchronize content from several Nuxeo Platform applications. This means that you can set up several accounts on Nuxeo Drive. Accounts are managed from the Accounts tab of the Settings window.

Adding a New Account

When you add a new account you need to provide the following information:

  • URL: Type the URL of your Nuxeo application, either the domain name only (example.org) or partial URL (https://example.org) or a full URL (https://example.org/nuxeo).
  • Folder: Select where you want your Nuxeo Drive folder to be created.

Clicking on Connect will open your browser to the login page. Sign-in and you will be redirected to Drive.

The creation of a new account triggers the following actions:

  • A Nuxeo Drive folder is created at the location you chose (see section Accessing the Nuxeo Drive Folder).
  • Nuxeo Drive starts synchronizing the Nuxeo workspaces or folders you indicated as synchronized in the Nuxeo Platform. It will automatically update content when there is a modification on the server.
  • In the Nuxeo Drive tab in your Home, an authentication token corresponding to the computer you are synchronizing from is displayed. The list of synchronized folders is displayed in the Synchronization roots section of the tab.

Deleting an Account

You can delete accounts from your Nuxeo Drive at any time by clicking on the Delete account button of the corresponding account, in the Settings window. The local Nuxeo Drive folder is not deleted.

Changing the Nuxeo Drive Language

By default, Nuxeo Drive is available in English.

To change the language of Nuxeo Drive:

  1. Open the Nuxeo Drive Settings window.
  2. Click on the General tab.
  3. In the Language drop down list, select the language you want to use.
    The Settings window language is immediately changed.

Configuration Parameters

Starting with Nuxeo Drive 4.0, invalid parameter names and values will make the program to stop. This is a quality check to ensure a good experience.

Nuxeo Drive has different parameters that you can set up through:

  • The REST API endpoint /drive/configuration served by the server (since NXP-22946 and Drive 3.0.0).
  • The command line.
  • A registry key inside HKEY_CURRENT_USER\Software\Nuxeo\Drive (since Drive 3.1.0, Windows only).
  • A config.ini file that can be located in different places:
    • next to the Nuxeo Drive executable
    • from the $HOME/.nuxeo-drive folder
    • from the current working directory

Each of these ways overrides the previous one.

Names and Values

Parameter names are quite flexible. There is no differentiation between lowercase and uppercase, nor between hyphens and underscores. For instance, you can specify ssl-no-verify, ssl_no_verify, ssl_no-verify or SSL_No_verify, it will be the same result.

Parameter values are taken as is, except for booleans. In that case, you can specify, in lowercase or uppercase:

  • true, 1, on, yes or oui to enable
  • false, 0, off, no or non to disable

Value Types

  • bool: boolean
  • int: integer
  • list: list of strings (one item by line)
  • str: string

Available Parameters

Parameter Default Value Type Version Added Description
behavior ... map 4.4.2 Application behavior that can be turned on/off on-demand. That parameter cannot be set via the local configuration file: only the server has rights to define it.
big-file 300 int 4.1.4 File size in MiB. Files bigger than this limit are considered "big". This implies few tweaks in the synchronization engine like bypassing most of the expensive and time-consuming digest computations. It is a tradeoff to handle large files as best effort.
ca-bundle None str 4.0.2 File or directory with certificates of trusted CAs. If set, ssl-no-verify has no effect. See the requests documentation for more details.
channel centralized str 4.0.2 Update channel. Can be centralized, release, beta or alpha.
chunk_limit 20 int 4.1.2 Size in MiB above which files will be uploaded in chunks (if chunk_upload is True). Has to be above 0.
chunk_size 20 int 4.1.2 Size of the chunks in MiB. Has to be above 0 and lower or equal to 20.
chunk_upload True bool 4.1.2 Activate the upload in chunks for files bigger than chunk_limit.
client_version None str 4.2.0 Force the client version to run when using the centralized update channel (must be >= 4.2.0).
delay 30 int 2 Delay in seconds before each remote check (calling the NuxeoDrive.GetChangeSummary operation).
feature ... map 4.4.2 Application features that can be turned on/off on-demand.
force-locale None str 2 Force the reset to the language.
handshake-timeout 60 int 2 Define the handshake timeout in seconds.
ignored-files ... list 2.4.1 File names to ignore while syncing.
ignored-prefixes ... list 2.4.1 File prefixes to ignore while syncing.
ignored-suffixes ... list 2.4.1 File suffixes to ignore while syncing.
locale en str 2 Set up the language if not already defined. This can also be set up by the user from the Settings window.
log-filename None str 2 The name of the log file.
log-level-console WARNING str 2 Define level for console log. Can be DEBUG, INFO, WARNING, ERROR. TRACE level has been deprecated since 4.1.0, and will be treated as DEBUG.
log-level-file INFO str 2 Define level for file log. Can be DEBUG, INFO, WARNING, ERROR. TRACE level has been deprecated since 4.1.0, and will be treated as DEBUG.
max-errors 3 int 2 Define the maximum number of retries before considering the file as in error.
nofscheck False bool 2.0.911 Disable the standard check for binding, to allow installation on network filesystem.
proxy-server None str 2 Define the address of the proxy server (e.g. http://proxy.example.com:3128). This can also be set up by the user from the Settings window.
ssl-no-verify False bool 4.0.1 Define if SSL errors should be ignored. Highly unadvised to enable this option.
sync-and-quit False bool 4.2.0 Launch the synchronization and then exit the application.
timeout 30 int 2 Define the socket timeout in seconds.
tmp_file_limit 10.0 float 4.1.4 File size in MiB. Files smaller than this limit will be written at once to the file rather than chunk by chunk.
update-check-delay 3600 int 2 Define the auto-update check delay in seconds. 0 means disabled.
update-site-url URL str 2 Configure a custom update website. See Nuxeo Drive Update Site for more details.
use-analytics False bool 4.1.0 Share anonymous usage analytics to help the developers build the best experience for you.
use-sentry True bool 4.1.0 Allow sharing error reports when something unusual happen.

Obsolete Parameters

Parameter Default Value Version Removed New Option Name New Default Value
beta-update-site-url URL (str) 4.0.2 None None
beta-channel False (bool) 4.0.2 channel release (str)
consider-ssl-errors True (bool) 4.0.1 ssl-no-verify False (bool)
debug False (bool) 4.0.0 None None
max-sync-step 10 (int) 4.1.3 None None
proxy-exceptions None (str) 4.0.0 None None
proxy-type None (str) 4.0.0 None None

Other changes:

  • channel was set to "release" in 4.0.2. It then changed to "centralized" in 4.2.0.

Behaviors

The application can be tweaked using on-demand on/off options via the behavior parameter. As this is targeting server actions, this parameter cannot be set via the local configuration file but only via the server configuration one.

Available behaviors:

Parameter Default Value (bool) Version Added Description
server_deletion true 4.4.2 Allow or disallow server deletions.

Here is how to tweak behaviors via the server configuration file:

{
  "behavior": {
    "server-deletion": true
  }
}

Features

Several features can be turned on/off on-demand via the feature parameter. This parameter can be set via the local configuration file and the server configuration one.

If the same feature is defined locally and remotely, then only the local value will be taken into account.

Available features:

Parameter Default Value (bool) Version Added Description
auto_update true 4.4.2 Allow or disallow auto-updates.
direct_edit true 4.4.2 Allow or disallow Direct Edit.
direct_transfer true 4.4.2 Allow or disallow Direct Transfer.
s3 true 4.4.2 Allow or disallow using Amazon S3 direct uploads.

Here is how to tweak features via the local configuration file:

[DEFAULT]
env = myFeatures

[myFeatures]
; (other parameters...)
feature.auto-update     = true
feature.direct-edit     = true
feature.direct-transfer = true
feature.s3              = true

Here is how to tweak features via the server configuration file:

{
  // (other parameters...)
  "feature": {
    "auto-update"     : true,
    "direct-edit"     : true,
    "direct-transfer" : true,
    "s3"              : true
  }
}

Command Line Arguments

When used as a command line argument you need to prefix with the long argument modifier --, e.g.: --log-level-file=DEBUG.

Configuration File

The format of the config.ini file is as following:

[DEFAULT]
env = custom

[no-updates]
; Unused section
update-check-delay = 0

[custom]
ca_bundle = C:\certificates\terena-ssl.crt
debug = False
feature.auto-update = true
log-level-file = DEBUG
ignored_suffixes =
    .bak
    .tmp
    .XXX

The env option from the [DEFAULT] section defines in which section looking for options. Here, options defined in the [custom] section will be taken into account.

Interpolation

If you are using special characters in values like:

ca_bundle = %userprofile%\.certificates

You may end up on such error:

configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%userprofile%/.certificates'

This is a special processing done by the configuration parser named values interpolation.

In that case, just double the percent sign:

ca_bundle = %%userprofile%%\.certificates

Nuxeo Drive and Audit Logs

Nuxeo Drive makes an extensive use of audit logs to get a summary of the server-side changes.

Since Nuxeo Platform 7.3 we chose to use Elasticsearch as a default back end for audit logs. This improves scalability especially when using Nuxeo Drive with a large set of users.

That's why we strongly recommend to keep this default configuration, but you can still disable Elasticsearch for Audit Logs.

Uninstalling Nuxeo Drive

To uninstall Nuxeo Drive from your computer, you need to remove the following items:

  • The .nuxeo-drive hidden folder where logs are stored
  • The Nuxeo Drive client application
  • The Nuxeo Drive local folder, only if you want to get rid of all the synchronized files and folders.

Uninstalling Nuxeo Drive on macOS

To uninstall Nuxeo Drive:

  1. Quit Nuxeo Drive:

    1. Click on the icon in the system tray.
    2. Click on Quit in the menu.
  2. Open a terminal and execute the following command:

     rm -rf ~/.nuxeo-drive
    
  3. Remove Nuxeo Drive from your applications like you usually remove any application.

  4. Delete the Nuxeo Drive item from your Favorites in the Finder.

At this point you have uninstalled the Nuxeo Drive program and its configuration. If you want to get rid of the synchronized data you also need to delete the Nuxeo Drive folder like you delete any regular folder.

Uninstalling Nuxeo Drive on Windows

To uninstall Nuxeo Drive:

  1. Quit Nuxeo Drive:

    1. Click on the icon in the system tray.
    2. Click on Quit in the menu.

      At this point you can check that there are no ndrive.exe remaining processes in the Processes tab of the Windows Task Manager that you can open by typing Ctrl + Shift + Esc. If you find such processes, kill them manually by right-clicking on their name and clicking on End Process.

  2. Uninstall the Nuxeo Drive application like a regular program using the Control Panel.

At this point you have uninstalled the Nuxeo Drive program and its configuration. If you want to get rid of the synchronized data you also need to delete the Nuxeo Drive folder like you delete any regular Windows folder.

We'd love to hear your thoughts!

All fields required