Advanced client options

INTRODUCTION

For advanced configuration, there are two files located:

  • In the root of the odrive folder for desktops
  • In the [user home folder]/.odrive-agent folder for odrive Agents (ex: ~/.odrive-agent/)

odrive_user_general_conf.txt - The configuration items in this file are available to all users.

odrive_user_premium_conf.txt - The configuration items in this file are available to Premium subscribers.

🚧

Important Note:

The default settings are intended to satisfy the needs of the vast majority of odrive users and should not be modified in most cases. Deviating from the defaults can create issues with odrive functionality and performance if they are set incorrectly, or beyond acceptable thresholds.

If your version of the configuration file(s) do not have all of the listed features, make sure you are running the latest version of odrive. If you are, delete the current configuration files and they will be automatically regenerated within a few seconds.

To make changes to the advanced settings:
  • Open up the desired file in a text editor
  • Change the value of the parameter you want to modify
  • Save the file
  • Restart odrive (only needed for settings to take effect on older client versions)

GENERAL SETTINGS

odrive_user_general_conf.txt

allowFlagged

default: false

Some storage providers may flag certain files that they feel are unsafe. odrive respects this flag, by default.

You can override this behavior and allow these flagged files to be downloaded by chaning the default value of 'false' to 'true'.

Only supported on Google Drive, at this time

allowOldDownload

default: false

By default, the odrive client will not automatically download and replace a local file if the remote file is seen as an older version. This behavior was added to address issues where users were inadvertently copying older files on top of newer files and then those were distributed to everyone who was sharing that storage. We've found that users rarely ever want to overwrite a newer file with an older one, but it can happen accidentally and cause data loss if the remote storage does not support versioning.

When a scenario where an older remote file is detected, that remote file will be held in the "not allowed" queue.

To enable behavior where older files will overwrite newer local files, change the default value of 'false' to 'true'

allowZeroByteUpdate

default: false

As a safety mechanism, updating the content of an existing file to 0 bytes is disallowed. If desired, you can turn off this protective measure by changing this setting to true.

disableAutoupdateRestart

default: false

When the sync app detects that an autoupdate is available, it will download the update and restart the app immediately to apply the update. Disabling the autoupdate restart will still result in the update being downloaded, but the app will not restart itself to apply the update. The update is applied when the app next restarts (either by user action or after a reboot, etc.).

disableConflictDetectionAll

default: false

You can now turn off conflict detection entirely by setting this configuration option to true. See also the "disableConflictDetectionStrict" below for an additonal option.

When conflict detection is disabled, your sync client will always upload your version up to your connected remote storage. If your remote storage source has version tracking, you may be able to identify and obtain any prior versions that your upload may have overwritten by accessing your remote storage through its own web client.

disableConflictDetectionStrict

default: false

The default conflict handling setting is "strict" mode. You can now set it for non-strict by setting this configuration option to true. Non-strict will not detect a conflict if either dates or the sizes are the same.

If the "disableConflictDetectionAll" setting is true to disable conflict detection in its entirety, then this setting is ignored and its value does not matter.

disableFSEvents

default: false

odrive utilizes filesystem events to help detect local changes. The events are sent to odrive from the operating system and provide notification of adds, deletes, moves, and updates. This provides the ability for odrive to react quickly to changes and ensure that your data is uploaded as quickly as possible.

There are some scenarios where it may be helpful to disable these filesystem events. If disabled, odrive will rely on periodic scans of the local filesystem to detect changes. Some scenarios where this can be useful is during bulk operations, to reduce event feedback, or in cases where a user is rapidly making and saving file edits causing odrive to upload more frequently than desired. To account for the lack of immediate events, you may also want to adjust the localScanIntervalSecs option to a lower number, like 600 (10 minutes).

disableLocalFileUpdates

default: false

Turn this setting on to prevent Sync from making any content updates to local files when changes are detected on the remote storage. Note that new files, moves, renames, and deletes detected on the remote side will still reflect to local.

disableRemoteFileUpdates

default: false

Turn this setting on to prevent Sync from making any content updates to remote files when changes are detected on your local computer. Note that new files, moves, renames, and deletes detected on the local disk will still reflect to remote cloud storage.

disableSparse

default: false

Sparse files are a special file type that allows native representation of file size without taking up actual disk space. odrive utilizes sparse files for placeholders, which allows the remote file size to be listed locally while still maintaining zero impact on the local disk space.

Disabling sparse files will revert to the previous placeholder behavior, where placeholders are shown as 0 bytes instead of representing the remote size. This change is not retroactive, so any placeholders that were already created using the new method will still show size and vice-versa.

To disable, change the default value of 'false' to 'true'

ignoreSizeMismatch

default: false

odrive has an extra check on download to make sure that the downloaded file size matches what the remote storage is reporting. If it doesn’t match odrive will abort the download. In some cases a storage provider may consistently misreport the correct size of a file, preventing it from being downloaded. In this case you will get an error pop-up indicating that there was a size mismatch. If you continue to get this error for specific files, you may need to temporarily enable this feature to get past the error.

To enable, change the default value of 'false' to 'true'.

localScanIntervalSecs

*default: 5400 or 1200

This setting can be used to change the interval at which odrive periodically scans for local changes. The default is 5400 seconds (90 minutes) in the odrive desktop clients and 1200 seconds (20 minutes) in the odrive agents. This should not need to be changed in most circumstances.

Change the default value to your desired number.

maxDownloadRetries

default: 3

odrive will transparently retry file downloads for transient errors. This setting can be used to adjust the number of retries attempted before giving up.

Change the default value of '3' to your desired number.

osTrashOverride

default: 0

This is a way to control what odrive does with files that need to be deleted on your computer (e.g. if a remote storage delete comes down and needs to reflect to your local machine).

The settings work as follows:

  • 0 is default (always send to OS trash/recycle bin and trigger an error if it can't).
  • 1 will bypass the OS trash/recycle bin (permanent delete) if there is an error sending to the trash/recycle bin.
  • 2 will always bypass the OS trash/recycle bin (permanent delete)

processMemoryLimitMBytes

default: 3584

Over time the odrive app may accumulate a fair amount of memory overhead when dealing with large scale repositories and operations. This setting acts as a "release valve" if the memory pressure exceeds the set value. The vast majority of users will never encounter this, but this can be useful for those that are dealing with extremely large datasets or performing very large bulk operations.

Important Note: Setting this value too low can hinder odrive's ability to function correctly.

suppressTrashNotifications

default: false

odrive will display a notification when local items have been detected as deleted and are being held in the odrive trash. This setting can be used to disable these notifications.

To enable, change the default value of 'false' to 'true'

suppressUrgentNotifications

default: false

Set to true to disable hard pop-up window notifications from the odrive app when an urgent warning needs to be communicated. When urgent notifications are disabled, a soft OS notification will be fired instead.

PREMIUM SETTINGS

odrive_user_premium_conf.txt
PREMIUM FEATURE

The settings below require a premium subscription to work.

allowSyncToOdriveFolderNameMismatch

default: false

When this setting is False (as it is by default), the rules for selecting your local and remote folder locations for the "Sync to odrive" feature should remain the same as outlined in the documentation.

When set to True, you are allowed to specify a local folder and remote folder which do not have matching names. As long as both folders exist, we will allow directly mapping that local folder to the specified remote folder. We won't try to create a new folder in the remote folder with matching name as your local folder.

autoEmptyTrashIntervalMins

default: -1

This setting allows you to control the auto empty trash value if you do not want to be constrained by the values presented in the app menu (which only shows: After 15 mins, 1 hour, or 1 day). If the default value of -1 is used, then whatever is set from the menu will be used.

autoUnsyncThresholdHours

default: -1

This setting allows you to control the auto unsync threshold value if you do not want to be constrained by the values presented in the app menu (which only shows: After 1 day, 1 week, or 1 month). If the default value of -1 is used, then whatever is set from the menu will be used.

autoUnsyncUseAccess

default: false

Set this to true to use the last accessed time from the filesystem as the autounsync indicator, instead of the default last sync activity. Keep in mind that this could result in files not unsyncing, at all, if there are background processes that routinely scan the files on your local filesystem. The "sync activity log" records all autounsync activity and shows Modified, Accessed, and Created information. This can be used to help determine if enabling this setting will work for your needs.

backupDisableMerge

default: false

Set this to true to prevent setting a backup destination folder that is not empty.

backupIntervalMinutes

default: 1440

Backup jobs run daily by default. You can change the setting to some other value in minutes, if desired. This time interval is the time between when a backup job run finishes and the next run is kicked off.

blackListContains, blackListExtensions, blackListNames, blackListPrefixes

These settings allow you to specify custom blacklist patterns for files and folders. Please click here for more information.

blackListExtensionsRemove, blackListNamesRemove, blackListPrefixesRemove

These settings can create an override to remove specified blacklisted extensions, names, and prefixes that odrive implements by default. Overriding the system defaults should be extremely uncommon. For a list of the system default blacklist settings, click here.

disableEncryptedNames

default: false

Set this to true for odrive Encryption to not scramble file names and folders. The file content will be still be encrypted, as it was before. File and folder names will appear with a ".oenc" extension to indicate these are items within an Encryptor container. It is important that the ".oenc" extension is not removed or changes on the remote storage, or else odrive will be unable to properly identify the encrypted content.

disableLocalItemDeletes

default: false

Turn this to true to prevent odrive from reflecting deletes to your local computer.

disableRemoteItemDeletes

default: false

Turn this to true to prevent odrive from reflecting deletes to your remote storage.

forgetEncPassphrase

default: false

By default, odrive will save your Encryptor passphrases locally in the client (your passphrase is never transmitted to any remote server) so that you do not need to enter them whenever odrive starts. This setting can be used to disable saving the Encryptor passphrase when you are requested to enter it for Encryptor folders. If enabled, you will need to enter the passphrase every time odrive is started and you want to access your encrypted content.

To enable, change the default value of 'false' to 'true'

ignoreEncryptionHashCheck

default: false

odrive utilizes a strict hash check for odrive-encrypted (Encryptor) files to ensure that the encrypted files have not been externally modified. If the hash for the current file does not match what is expected, the download will not succeed. This setting can be used to ignore hash mismatches and still allow file downloads (and decryption, if possible). This should never need to be set, in normal circumstances, and you should consult with the odrive support team before enabling this setting.

initialUploadBatchSize, maxConcurrentDownloads, maxConcurrentJobs, maxConcurrentUploads, maxTransferMBytes

These settings allow you to tweak the upload and download behavior of your odrive client.

initialUploadBatchSize

default: 1

This setting represents the initial number of files that odrive will attempt to upload concurrently. The default value is 1. odrive will upload the number defined, analyze its performance, and then scale-up when appropriate. This setting can be used for large file uploads on high-speed, high-bandwidth network connections to prevent the need to wait for a single large file to finish uploading before scaling up. The maxConcurrentUploads and maxTransferBytes settings may need to be adjusted to coincide with changes to this setting, as well.

Change the default value of '1' to your desired number.

maxConcurrentDownloads

default: 4

This setting represents the maximum number of concurrent downloads in a "job" (there can be multiple jobs, depending on what the maxConcurrentJobs setting is and how odrive has processed your requests). For example, a right-click->sync action on a folder to recursively download that folder is considered one "job".

Change the default value of '4' to your desired number.

maxConcurrentJobs

default: 4

This setting represents the maximum number of "jobs" that can run concurrently. A job is generally associated with a upload or download action within a single mount (sync to odrive) or folder heiracrchy. Each refresh job has its own upload/download limits, as defined by the 'maxConcurrentUploads' and 'maxConcurrentDownloads' settings. This setting can be used, for example, to restrict the total number of jobs to 1 to guarantee that you can only have one total concurrent upload, globally.

Change the default value of '4' to your desired number.

maxConcurrentUploads

default: 4

This setting represents the maximum number of concurrent uploads in a "job" (there can be multiple jobs, depending on what the maxConcurrentJobs setting is and how odrive has processed your requests). Generally, jobs are allocated to mounts and directory structures. For example, adding a new folder (with files and folders underneath) will usually be processed as one "job".

Change the default value of '4' to your desired number.

maxTransferMBytes

default: 256

This setting represents the maximum size (in MB) allowed for concurrent transfers. Uploads and downloads are counted separately. This option is used by odrive to keep large file transfers under control. Users who have access to very high-speed, very high-bandwidth connections may want to increase this. Conversely, users with very low-bandwidth or very low-speed connections may want to reduce this.

Change the default value of '256' to your desired number.

remoteScanIntervalMins

default: 840

This setting represents the time interval in minutes between remote scans which walk the entire remote file listing in each linked storage to look for changes.

🚧

Considerations for setting the remote scan interval

This is a global setting; you cannot specify different remote scan intervals for different storage links.

The remote scan job should not run frequently, as it is a costly operation which will make many API calls to your remote storage services, especially if you have large nested folder structures on your linked storage accounts.

The remote scan is a security blanket to get back in sync / correct any discrepancies in folders you do not regularly browse into or refresh. It is particularly useful for storage sources which do not have more efficient API methods to check for changes.

Storage sources which have dedicated calls for change detection (i.e. most modern cloud storage providers) get updated much more frequently through a separate mechanism. So setting a low remote scan interval does not necessarily improve responsiveness to remote changes. If you have further questions about how to choose an optimal setting for your particular configuration, please feel free to contact us by sending an email to [email protected].

Change the default value of '840' to your desired number.

Please note that the interval cannot be set below 5 minutes.