abraunegg-onedrive/docs/application-config-options.md

Application Configuration Options for the OneDrive Client for Linux

Application Version

Before reading this document, please ensure you are running application version or greater. Use onedrive --version to determine what application version you are using and upgrade your client if required.

Table of Contents

• Configuration File Options
  • application_id
  • azure_ad_endpoint
  • azure_tenant_id
  • bypass_data_preservation
  • check_nomount
  • check_nosync
  • classify_as_big_delete
  • cleanup_local_files
  • connect_timeout
  • data_timeout
  • debug_https
  • disable_download_validation
  • disable_notifications
  • disable_upload_validation
  • display_running_config
  • dns_timeout
  • download_only
  • drive_id
  • dry_run
  • enable_logging
  • force_http_11
  • ip_protocol_version
  • local_first
  • log_dir
  • monitor_fullscan_frequency
  • monitor_interval
  • monitor_log_frequency
  • no_remote_delete
  • operation_timeout
  • rate_limit
  • read_only_auth_scope
  • remove_source_files
  • resync
  • resync_auth
  • skip_dir
  • skip_dir_strict_match
  • skip_dotfiles
  • skip_file
  • skip_size
  • skip_symlinks
  • space_reservation
  • sync_business_shared_items
  • sync_dir
  • sync_dir_permissions
  • sync_file_permissions
  • sync_root_files
  • threads
  • upload_only
  • user_agent
  • webhook_enabled
  • webhook_expiration_interval
  • webhook_listening_host
  • webhook_listening_port
  • webhook_public_url
  • webhook_renewal_interval
• Command Line Interface (CLI) Only Options
  • CLI Option: --auth-files
  • CLI Option: --auth-response
  • CLI Option: --confdir
  • CLI Option: --create-directory
  • CLI Option: --create-share-link
  • CLI Option: --destination-directory
  • CLI Option: --display-config
  • CLI Option: --display-sync-status
  • CLI Option: --display-quota
  • CLI Option: --force
  • CLI Option: --force-sync
  • CLI Option: --get-file-link
  • CLI Option: --get-sharepoint-drive-id
  • CLI Option: --list-shared-items
  • CLI Option: --logout
  • CLI Option: --modified-by
  • CLI Option: --monitor | -m
  • CLI Option: --print-access-token
  • CLI Option: --reauth
  • CLI Option: --remove-directory
  • CLI Option: --single-directory
  • CLI Option: --source-directory
  • CLI Option: --sync | -s
  • CLI Option: --sync-shared-files
  • CLI Option: --verbose | -v+
  • CLI Option: --with-editing-perms
• Depreciated Configuration File and CLI Options
  • force_http_2
  • min_notify_changes
  • CLI Option: --synchronize

Configuration File Options

application_id

Description: This is the config option for application id that used used to identify itself to Microsoft OneDrive. In some circumstances, it may be desirable to use your own application id. To do this, you must register a new application with Microsoft Azure via https://portal.azure.com/, then use your new application id with this config option.

Value Type: String

Default Value: d50ca740-c83f-4d1b-b616-12c519384f0c

Config Example: application_id = "d50ca740-c83f-4d1b-b616-12c519384f0c"

azure_ad_endpoint

Description: This is the config option to change the Microsoft Azure Authentication Endpoint that the client uses to conform with data and security requirements that requires data to reside within the geographic borders of that country.

Value Type: String

Default Value: Empty - not required for normal operation

Valid Values: USL4, USL5, DE, CN

Config Example: azure_ad_endpoint = "DE"

azure_tenant_id

Description: This config option allows the locking of the client to a specific single tenant and will configure your client to use the specified tenant id in its Azure AD and Graph endpoint URIs, instead of "common". The tenant id may be the GUID Directory ID or the fully qualified tenant name.

Value Type: String

Default Value: Empty - not required for normal operation

Config Example: azure_tenant_id = "example.onmicrosoft.us" or azure_tenant_id = "0c4be462-a1ab-499b-99e0-da08ce52a2cc"

Important

Must be configured if 'azure_ad_endpoint' is configured.

bypass_data_preservation

Description: This config option allows the disabling of preserving local data by renaming the local file in the event of data conflict. If this is enabled, you will experience data loss on your local data as the local file will be over-written with data from OneDrive online. Use with care and caution.

Value Type: Boolean

Default Value: False

Config Example: bypass_data_preservation = "false" or bypass_data_preservation = "true"

check_nomount

Description: This config option is useful to prevent application startup & ongoing use in 'Monitor Mode' if the configured 'sync_dir' is a separate disk that is being mounted by your system. This option will check for the presence of a .nosync file in your mount point, and if present, abort any sync process to preserve data.

Value Type: Boolean

Default Value: False

Config Example: check_nomount = "false" or check_nomount = "true"

CLI Option: --check-for-nomount

Tip

Create a .nosync file in your mount point before you mount your disk so that this .nosync file visible, in your mount point if your disk is unmounted at any point to preserve your data when you enable this option.

check_nosync

Description: This config option is useful to prevent the sync of a local directory to Microsoft OneDrive. It will not check for this file online to prevent the download of directories to your local system.

Value Type: Boolean

Default Value: False

Config Example: check_nosync = "false" or check_nosync = "true"

CLI Option Use: --check-for-nosync

Important

Create a .nosync file in any local directory that you wish to not sync to Microsoft OneDrive when you enable this option.

classify_as_big_delete

Description: This config option defines the number of children in a path that is locally removed which will be classified as a 'big data delete' to safeguard large data removals - which are typically accidental local delete events.

Value Type: Integer

Default Value: 1000

Config Example: classify_as_big_delete = "2000"

CLI Option Use: --classify-as-big-delete 2000

Note

If this option is triggered, you will need to add --force to force a sync to occur.

cleanup_local_files

Description: This config option provides the capability to cleanup local files and folders if they are removed online.

Value Type: Boolean

Default Value: False

Config Example: cleanup_local_files = "false" or cleanup_local_files = "true"

CLI Option Use: --cleanup-local-files

Important

This configuration option can only be used with 'download_only'. It cannot be used with any other application option.

connect_timeout

Description: This configuration setting manages the TCP connection timeout duration in seconds for HTTPS connections to Microsoft OneDrive when using the curl library (CURLOPT_CONNECTTIMEOUT).

Value Type: Integer

Default Value: 10

Config Example: connect_timeout = "15"

data_timeout

Description: This setting controls the timeout duration, in seconds, for when data is not received on an active connection to Microsoft OneDrive over HTTPS when using the curl library, before that connection is timeout out.

Value Type: Integer

Default Value: 240

Config Example: data_timeout = "300"

debug_https

Description: This setting controls whether the curl library is configured to output additional data to assist with diagnosing HTTPS issues and problems.

Value Type: Boolean

Default Value: False

Config Example: debug_https = "false" or debug_https = "true"

CLI Option Use: --debug-https

Warning

Whilst this option can be used at any time, it is advisable that you only use this option when advised as this will output your Authorization: bearer - which is your authentication token to Microsoft OneDrive.

disable_download_validation

Description: This option determines whether the client will conduct integrity validation on files downloaded from Microsoft OneDrive. Sometimes, when downloading files, particularly from SharePoint, there is a discrepancy between the file size reported by the OneDrive API and the byte count received from the SharePoint HTTP Server for the same file. Enable this option to disable the integrity checks performed by this client.

Value Type: Boolean

Default Value: False

Config Example: disable_download_validation = "false" or disable_download_validation = "true"

CLI Option Use: --disable-download-validation

Caution

If you're downloading data from SharePoint or OneDrive Business Shared Folders, you might find it necessary to activate this option. It's important to note that any issues encountered aren't due to a problem with this client; instead, they should be regarded as issues with the Microsoft OneDrive technology stack. Enabling this option disables all download integrity checks.

disable_notifications

Description: This setting controls whether GUI notifications are sent from the client to your display manager session.

Value Type: Boolean

Default Value: False

Config Example: disable_notifications = "false" or disable_notifications = "true"

CLI Option Use: --disable-notifications

disable_upload_validation

Description: This option determines whether the client will conduct integrity validation on files uploaded to Microsoft OneDrive. Sometimes, when uploading files, particularly to SharePoint, SharePoint will modify your file post upload by adding new data to your file which breaks the integrity checking of the upload performed by this client. Enable this option to disable the integrity checks performed by this client.

Value Type: Boolean

Default Value: False

Config Example: disable_upload_validation = "false" or disable_upload_validation = "true"

CLI Option Use: --disable-upload-validation

Caution

If you're uploading data to SharePoint or OneDrive Business Shared Folders, you might find it necessary to activate this option. It's important to note that any issues encountered aren't due to a problem with this client; instead, they should be regarded as issues with the Microsoft OneDrive technology stack. Enabling this option disables all upload integrity checks.

display_running_config

Description: This option will include the running config of the application at application startup. This may be desirable to enable when running in containerised environments so that any application logging that is occuring, will have the application configuration being consumed at startup, written out to any applicable log file.

Value Type: Boolean

Default Value: False

Config Example: display_running_config = "false" or display_running_config = "true"

CLI Option Use: --display-running-config

dns_timeout

Description: This setting controls the libcurl DNS cache value. By default, libcurl caches this info for 60 seconds. This libcurl DNS cache timeout is entirely speculative that a name resolves to the same address for a small amount of time into the future as libcurl does not use DNS TTL properties. We recommend users not to tamper with this option unless strictly necessary.

Value Type: Integer

Default Value: 60

Config Example: dns_timeout = "90"

download_only

Description: This setting forces the client to only download data from Microsoft OneDrive and replicate that data locally. No changes made locally will be uploaded to Microsoft OneDrive when using this option.

Value Type: Boolean

Default Value: False

Config Example: download_only = "false" or download_only = "true"

CLI Option Use: --download-only

drive_id

Description: This setting controls the specific drive identifier the client will use when syncing with Microsoft OneDrive.

Value Type: String

Default Value: None

Config Example: drive_id = "b!bO8V6s9SSk9R7mWhpIjUrotN73WlW3tEv3OxP_QfIdQimEdOHR-1So6CqeG1MfDB"

Note

This option is typically only used when configuring the client to sync a specific SharePoint Library. If this configuration option is specified in your config file, a value must be specified otherwise the application will exit citing a fatal error has occured.

dry_run

Description: This setting controls the application capability to test your application configuration without actually performing any actual activity (download, upload, move, delete, folder creation).

Value Type: Boolean

Default Value: False

Config Example: dry_run = "false" or dry_run = "true"

CLI Option Use: --dry-run

enable_logging

Description: This setting controls the application logging all actions to a separate file. By default, all log files will be written to /var/log/onedrive, however this can changed by using the 'log_dir' config option

Value Type: Boolean

Default Value: False

Config Example: enable_logging = "false" or enable_logging = "true"

CLI Option Use: --enable-logging

Important

Additional configuration is potentially required to configure the default log directory. Refer to the Enabling the Client Activity Log section in usage.md for details

force_http_11

Description: This setting controls the application HTTP protocol version. By default, the application will use libcurl defaults for which HTTP prodocol version will be used to interact with Microsoft OneDrive. Use this setting to downgrade libcurl to only use HTTP/1.1.

Value Type: Boolean

Default Value: False

Config Example: force_http_11 = "false" or force_http_11 = "true"

CLI Option Use: --force-http-11

ip_protocol_version

Description: This setting controls the application IP protocol that should be used when communicating with Microsoft OneDrive. The default is to use IPv4 and IPv6 networks for communicating to Microsoft OneDrive.

Value Type: Integer

Default Value: 0

Valid Values: 0 = IPv4 + IPv6, 1 = IPv4 Only, 2 = IPv6 Only

Config Example: ip_protocol_version = "0" or ip_protocol_version = "1" or ip_protocol_version = "2"

Important

In some environments where IPv4 and IPv6 are configured at the same time, this causes resolution and routing issues to Microsoft OneDrive. If this is the case, it is advisable to change 'ip_protocol_version' to match your environment.

local_first

Description: This setting controls what the application considers the 'source of truth' for your data. By default, what is stored online will be considered as the 'source of truth' when syncing to your local machine. When using this option, your local data will be considered the 'source of truth'.

Value Type: Boolean

Default Value: False

Config Example: local_first = "false" or local_first = "true"

CLI Option Use: --local-first

log_dir

Description: This setting controls the custom application log path when 'enable_logging' has been enabled. By default, all log files will be written to /var/log/onedrive.

Value Type: String

Default Value: None

Config Example: log_dir = "~/logs/"

CLI Option Use: --log-dir "~/logs/"

monitor_fullscan_frequency

Description: This configuration option controls the number of 'monitor_interval' iterations between when a full scan of your data is performed to ensure data integrity and consistency.

Value Type: Integer

Default Value: 12

Config Example: monitor_fullscan_frequency = "24"

CLI Option Use: --monitor-fullscan-frequency '24'

Note

By default without configuration, 'monitor_fullscan_frequency' is set to 12. In this default state, this means that a full scan is performed every 'monitor_interval' x 'monitor_fullscan_frequency' = 3600 seconds. This setting is only applicable when running in --monitor mode. Setting this configuration option to '0' will disable the full scan of your data online.

monitor_interval

Description: This configuration setting determines how often the synchronisation loops run in --monitor mode, measured in seconds. When this time period elapses, the client will check for online changes in Microsoft OneDrive, conduct integrity checks on local data and scan the local 'sync_dir' to identify any new content that hasn't been uploaded yet.

Value Type: Integer

Default Value: 300

Config Example: monitor_interval = "600"

CLI Option Use: --monitor-interval '600'

Note

A minimum value of 300 is enforced for this configuration setting.

monitor_log_frequency

Description: This configuration option controls the suppression of frequently printed log items to the system console when using --monitor mode. The aim of this configuration item is to reduce the log output when near zero sync activity is occuring.

Value Type: Integer

Default Value: 12

Config Example: monitor_log_frequency = "24"

CLI Option Use: --monitor-log-frequency '24'

Usage Example:

By default, at application start-up when using --monitor mode, the following will be logged to indicate that the application has correctly started and has performed all the initial processing steps:

Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
Configuring Global Azure AD Endpoints
Sync Engine Initialised with new Onedrive API instance
All application operations will be performed in: /home/user/OneDrive
OneDrive synchronisation interval (seconds): 300
Initialising filesystem inotify monitoring ...
Performing initial syncronisation to ensure consistent local state ...
Starting a sync with Microsoft OneDrive
Fetching items from the OneDrive API for Drive ID: b!bO8V6s9SSk9R7mWhpIjUrotN73WlW3tEv3OxP_QfIdQimEdOHR-1So6CqeG1MfDB ..
Processing changes and items received from Microsoft OneDrive ...
Performing a database consistency and integrity check on locally stored data ... 
Scanning the local file system '~/OneDrive' for new data to upload ...
Performing a final true-up scan of online data from Microsoft OneDrive
Fetching items from the OneDrive API for Drive ID: b!bO8V6s9SSk9R7mWhpIjUrotN73WlW3tEv3OxP_QfIdQimEdOHR-1So6CqeG1MfDB ..
Processing changes and items received from Microsoft OneDrive ...
Sync with Microsoft OneDrive is complete

Then, based on 'monitor_log_frequency', the following output will be logged until the suppression loop value is reached:

Starting a sync with Microsoft OneDrive
Syncing changes from Microsoft OneDrive ...
Sync with Microsoft OneDrive is complete

Note

The additional log output Performing a database consistency and integrity check on locally stored data ... will only be displayed when this activity is occuring which is triggered by 'monitor_fullscan_frequency'.

Note

If verbose application output is being used (--verbose), then this configuration setting has zero effect, as application verbose output takes priority over application output surpression.

no_remote_delete

Description: This configuration option controls whether local file and folder deletes are actioned on Microsoft OneDrive.

Value Type: Boolean

Default Value: False

Config Example: local_first = "false" or local_first = "true"

CLI Option Use: --no-remote-delete

Important

This configuration option can only be used in conjunction with --upload-only

operation_timeout

Description: This configuration option controls the maximum amount of time (seconds) a file operation is allowed to take. This includes DNS resolution, connecting, data transfer, etc. We recommend users not to tamper with this option unless strictly necessary. This option controls the CURLOPT_TIMEOUT setting of libcurl.

Value Type: Integer

Default Value: 3600

Config Example: operation_timeout = "3600"

rate_limit

Description: This configuration option controls the bandwidth used by the application, per thread, when interacting with Microsoft OneDrive.

Value Type: Integer

Default Value: 0 (unlimited, use available bandwidth per thread)

Valid Values: Valid tested values for this configuration option are as follows:

• 131072 = 128 KB/s - absolute minimum for basic application operations to prevent timeouts
• 262144 = 256 KB/s
• 524288 = 512 KB/s
• 1048576 = 1 MB/s
• 10485760 = 10 MB/s
• 104857600 = 100 MB/s

Config Example: rate_limit = "131072"

read_only_auth_scope

Description: This configuration option controls whether the OneDrive Client for Linux operates in a totally in read-only operation.

Value Type: Boolean

Default Value: False

Config Example: read_only_auth_scope = "false" or read_only_auth_scope = "true"

Important

When using 'read_only_auth_scope' you also will need to remove your existing application access consent otherwise old authentication consent will be valid and will be used. This will mean the application will technically have the consent to upload data until you revoke this consent.

remove_source_files

Description: This configuration option controls whether the OneDrive Client for Linux removes the local file post successful transfer to Microsoft OneDrive.

Value Type: Boolean

Default Value: False

Config Example: remove_source_files = "false" or remove_source_files = "true"

CLI Option Use: --remove-source-files

Important

This configuration option can only be used in conjunction with --upload-only

resync

Description: This configuration option controls whether the known local sync state with Microsoft OneDrive is removed at application startup. When this option is used, a full scan of your data online is performed to ensure that the local sync state is correctly built back up.

Value Type: Boolean

Default Value: False

Config Example: resync = "false" or resync = "true"

CLI Option Use: --resync

Caution

It's highly recommended to use this option only if the application prompts you to do so. Don't blindly use this option as a default option. If you alter any of the subsequent configuration items, you will be required to execute a --resync to make sure your client is syncing your data with the updated configuration:

• drive_id
• sync_dir
• skip_file
• skip_dir
• skip_dotfiles
• skip_symlinks
• sync_business_shared_items
• Creating, Modifying or Deleting the 'sync_list' file

resync_auth

Description: This configuration option controls the approval of performing a 'resync' which can be beneficial in automated environments.

Value Type: Boolean

Default Value: False

Config Example: resync_auth = "false" or resync_auth = "true"

CLI Option Use: --resync-auth

Tip

In certain automated environments (assuming you know what you're doing due to using automation), to avoid the 'proceed with acknowledgement' resync requirement, this option allows you to automatically acknowledge the resync prompt.

skip_dir

Description: This configuration option controls whether the application skips certain directories from being synced. Directories can be specified in 2 ways:

• As a single entry. This will search the respective path for this entry and skip all instances where this directory is present, where ever it may exist.
• As a full path entry. This will skip the explicit path as set.

Important: Entries for 'skip_dir' are relative to your 'sync_dir' path.

Value Type: String

Default Value: Empty - not required for normal operation

Config Example:

Patterns are case insensitive. * and ? wildcards characters are supported. Use | to separate multiple patterns.

skip_dir = "Desktop|Documents/IISExpress|Documents/SQL Server Management Studio|Documents/Visual Studio*|Documents/WindowsPowerShell|.Rproj-user"

The 'skip_dir' option can also be specified multiple times within your config file, for example:

skip_dir = "SkipThisDirectoryAnywhere"
skip_dir = ".SkipThisOtherDirectoryAnywhere"
skip_dir = "/Explicit/Path/To/A/Directory"
skip_dir = "/Another/Explicit/Path/To/Different/Directory"

This will be interpreted the same as:

skip_dir = "SkipThisDirectoryAnywhere|.SkipThisOtherDirectoryAnywhere|/Explicit/Path/To/A/Directory|/Another/Explicit/Path/To/Different/Directory"

CLI Option Use: --skip-dir 'SkipThisDirectoryAnywhere|.SkipThisOtherDirectoryAnywhere|/Explicit/Path/To/A/Directory|/Another/Explicit/Path/To/Different/Directory'

Note

This option is considered a 'Client Side Filtering Rule' and if configured, is utilised for all sync operations. If using the config file and CLI option is used, the CLI option will replace the config file entries. After changing or modifying this option, you will be required to perform a resync.

skip_dir_strict_match

Description: This configuration option controls whether the application performs strict directory matching when checking 'skip_dir' items. When enabled, the 'skip_dir' item must be a full path match to the path to be skipped.

Value Type: Boolean

Default Value: False

Config Example: skip_dir_strict_match = "false" or skip_dir_strict_match = "true"

CLI Option Use: --skip-dir-strict-match

skip_dotfiles

Description: This configuration option controls whether the application will skip all .files and .folders when performing sync operations.

Value Type: Boolean

Default Value: False

Config Example: skip_dotfiles = "false" or skip_dotfiles = "true"

CLI Option Use: --skip-dot-files

Note

This option is considered a 'Client Side Filtering Rule' and if configured, is utilised for all sync operations. After changing this option, you will be required to perform a resync.

skip_file

Description: This configuration option controls whether the application skips certain files from being synced.

Value Type: String

Default Value: ~*|.~*|*.tmp|*.swp|*.partial

Config Example:

Patterns are case insensitive. * and ? wildcards characters are supported. Use | to separate multiple patterns.

By default, the following files will be skipped:

• Files that start with ~
• Files that start with .~ (like .~lock.* files generated by LibreOffice)
• Files that end in .tmp, .swp and .partial

Files can be skipped in the following fashion:

• Specify a wildcard, eg: '*.txt' (skip all txt files)
• Explicitly specify the filename and it's full path relative to your sync_dir, eg: '/path/to/file/filename.ext'
• Explicitly specify the filename only and skip every instance of this filename, eg: 'filename.ext'

skip_file = "~*|/Documents/OneNote*|/Documents/config.xlaunch|myfile.ext|/Documents/keepass.kdbx"

The 'skip_file' option can be specified multiple times within your config file, for example:

skip_file = "~*|.~*|*.tmp|*.swp"
skip_file = "*.blah"
skip_file = "never_sync.file"
skip_file = "/Documents/keepass.kdbx"

This will be interpreted the same as:

skip_file = "~*|.~*|*.tmp|*.swp|*.blah|never_sync.file|/Documents/keepass.kdbx"

CLI Option Use: --skip-file '~*|.~*|*.tmp|*.swp|*.blah|never_sync.file|/Documents/keepass.kdbx'

Note

This option is considered a 'Client Side Filtering Rule' and if configured, is utilised for all sync operations. If using the config file and CLI option is used, the CLI option will replace the config file entries. After changing or modifying this option, you will be required to perform a resync.

skip_size

Description: This configuration option controls whether the application skips syncing certain files larger than the specified size. The value specified is in MB.

Value Type: Integer

Default Value: 0 (all files, regardless of size, are synced)

Config Example: skip_size = "50"

CLI Option Use: --skip-size '50'

skip_symlinks

Description: This configuration option controls whether the application will skip all symbolic links when performing sync operations. Microsoft OneDrive has no concept or understanding of symbolic links, and attempting to upload a symbolic link to Microsoft OneDrive generates a platform API error. All data (files and folders) that are uploaded to OneDrive must be whole files or actual directories.

Value Type: Boolean

Default Value: False

Config Example: skip_symlinks = "false" or skip_symlinks = "true"

CLI Option Use: --skip-symlinks

Note

This option is considered a 'Client Side Filtering Rule' and if configured, is utilised for all sync operations. After changing this option, you will be required to perform a resync.

space_reservation

Description: This configuration option controls how much local disk space should be reserved, to prevent the application from filling up your entire disk due to misconfiguration

Value Type: Integer

Default Value: 50 MB (expressesed as Bytes when using --display-config)

Config Example: space_reservation = "100"

CLI Option Use: --space-reservation '100'

sync_business_shared_items

Description: This configuration option controls whether OneDrive Business | Office 365 Shared Folders, when added as a 'shortcut' to your 'My Files', will be synced to your local system.

Value Type: Boolean

Default Value: False

Config Example: sync_business_shared_items = "false" or sync_business_shared_items = "true"

CLI Option Use: none - this is a config file option only

Note

This option is considered a 'Client Side Filtering Rule' and if configured, is utilised for all sync operations. After changing this option, you will be required to perform a resync.

Caution

This option is not backwards compatible with any v2.4.x application version. If you are enabling this option on any system running v2.5.x application version, all your application versions being used everywhere must be v2.5.x codebase.

sync_dir

Description: This configuration option determines the location on your local filesystem where your data from Microsoft OneDrive will be saved.

Value Type: String

Default Value: ~/OneDrive

Config Example: sync_dir = "~/MyDirToSync"

CLI Option Use: --syncdir '~/MyDirToSync'

Caution

After changing this option, you will be required to perform a resync. Do not change or modify this option without fully understanding the implications of doing so.

sync_dir_permissions

Description: This configuration option defines the directory permissions applied when a new directory is created locally during the process of syncing your data from Microsoft OneDrive.

Value Type: Integer

Default Value: 700 - This provides the following permissions: drwx------

Config Example: sync_dir_permissions = "700"

Important

Use the Unix Permissions Calculator to help you determine the necessary new permissions. You will need to manually update all existing directory permissions if you modify this value.

sync_file_permissions

Description: This configuration option defines the file permissions applied when a new file is created locally during the process of syncing your data from Microsoft OneDrive.

Value Type: Integer

Default Value: 600 - This provides the following permissions: -rw-------

Config Example: sync_file_permissions = "600"

Important

Use the Unix Permissions Calculator to help you determine the necessary new permissions. You will need to manually update all existing directory permissions if you modify this value.

sync_root_files

Description: This configuration option manages the synchronisation of files located in the 'sync_dir' root when using a 'sync_list.' It enables you to sync all these files by default, eliminating the need to repeatedly modify your 'sync_list' and initiate resynchronisation.

Value Type: Boolean

Default Value: False

Config Example: sync_root_files = "false" or sync_root_files = "true"

CLI Option Use: --sync-root-files

Important

Although it's not mandatory, it's recommended that after enabling this option, you perform a --resync. This ensures that any previously excluded content is now included in your sync process.

threads

Description: This configuration option controls the number of 'threads' for upload and download operations when files need to be transfered between your local system and Microsoft OneDrive.

Value Type: Integer

Default Value: 8

Maximum Value: 16

Config Example: threads = "16"

Warning

Increasing the threads beyond the default will lead to increased system utilisation and local TCP port use, which may lead to unpredictable behaviour and/or may lead application stability issues.

upload_only

Description: This setting forces the client to only upload data to Microsoft OneDrive and replicate the locate state online. By default, this will also remove content online, that has been removed locally.

Value Type: Boolean

Default Value: False

Config Example: upload_only = "false" or upload_only = "true"

CLI Option Use: --upload-only

Important

To ensure that data deleted locally remains accessible online, you can use the 'no_remote_delete' option. If you want to delete the data from your local storage after a successful upload to Microsoft OneDrive, you can use the 'remove_source_files' option.

user_agent

Description: This configuration option controls the 'User-Agent' request header that is presented to Microsoft Graph API when accessing the Microsoft OneDrive service. This string lets servers and network peers identify the application, operating system, vendor, and/or version of the application making the request. We recommend users not to tamper with this option unless strictly necessary.

Value Type: String

Default Value: ISV|abraunegg|OneDrive Client for Linux/vX.Y.Z-A-bcdefghi

Config Example: user_agent = "ISV|CompanyName|AppName/Version"

Important

The default 'user_agent' value conforms to specific Microsoft requirements to identify as an ISV that complies with OneDrive traffic decoration requirements. Changing this value potentially will impact how Microsoft see's your client, thus your traffic may get throttled. For further information please read: https://learn.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online

webhook_enabled

Description: This configuration option controls the application feature 'webhooks' to allow you to subscribe to remote updates as published by Microsoft OneDrive. This option only operates when the client is using 'Monitor Mode'.

Value Type: Boolean

Default Value: False

Config Example: The following is the minimum working example that needs to be added to your 'config' file to enable 'webhooks' successfully:

webhook_enabled = "true"
webhook_public_url = "http://<your_host_ip>:8888/"

Note

Setting webhook_enabled = "true" enables the webhook feature in 'monitor' mode. The onedrive process will listen for incoming updates at a configurable endpoint, which defaults to 0.0.0.0:8888. The webhook_public_url must be set to an public-facing url for Microsoft to send updates to your webhook.

If your host is directly exposed to the Internet, the webhook_public_url can be set to http://<your_host_ip>:8888/ to match the default endpoint. In this case, it is also advisable to configure a reverse proxy like nginx to proxy the traffic to the client. For example, below is a nginx config snippet to proxy traffic into the webhook:

server {
	listen 80;
	location /webhooks/onedrive {
		proxy_http_version 1.1;
		proxy_pass http://127.0.0.1:8888;
	}
}

With nginx running, you can configure 'webhook_public_url' to https://<public_facing_url_to_reach_your_webhook>/webhooks/onedrive

Important

A valid HTTPS certificate is required for your public-facing URL if using nginx. Self signed certificates will be rejected. Consider using https://letsencrypt.org/ to utilise free SSL certificates for your public-facing URL.

Tip

If you receive this application error: Subscription validation request failed. Response must exactly match validationToken query parameter. the most likely cause for this error will be your nginx configuration.

To resolve this configuration issue, potentially investigate the following configuration for nginx:

server {
	listen 80;
	location /webhooks/onedrive {
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Original-Request-URI $request_uri;
		proxy_read_timeout 300s;
		proxy_connect_timeout 75s;
		proxy_buffering off;
		proxy_http_version 1.1;
		proxy_pass http://127.0.0.1:8888;
	}
}

For any further nginx configuration assistance, please refer to: https://docs.nginx.com/

webhook_expiration_interval

Description: This configuration option controls the frequency at which an existing Microsoft OneDrive webhook subscription expires. The value is expressed in the number of seconds before expiry.

Value Type: Integer

Default Value: 600

Config Example: webhook_expiration_interval = "1200"

webhook_listening_host

Description: This configuration option controls the host address that this client binds to, when the webhook feature is enabled.

Value Type: String

Default Value: 0.0.0.0

Config Example: webhook_listening_host = "" - this will use the default value. webhook_listening_host = "192.168.3.4" - this will bind the client to use the IP address 192.168.3.4.

Note

Use in conjunction with 'webhook_listening_port' to change the webhook listening endpoint.

webhook_listening_port

Description: This configuration option controls the TCP port that this client listens on, when the webhook feature is enabled.

Value Type: Integer

Default Value: 8888

Config Example: webhook_listening_port = "9999"

Note

Use in conjunction with 'webhook_listening_host' to change the webhook listening endpoint.

webhook_public_url

Description: This configuration option controls the URL that Microsoft will send subscription notifications to. This must be a valid Internet accessible URL.

Value Type: String

Default Value: empty

Config Example:

• If your host is directly connected to the Internet: webhook_public_url = "http://<your_host_ip>:8888/"
• If you are using nginx to reverse proxy traffic from the Internet: webhook_public_url = "https://<public_facing_url_to_reach_your_webhook>/webhooks/onedrive"

webhook_renewal_interval

Description: This configuration option controls the frequency at which an existing Microsoft OneDrive webhook subscription is renewed. The value is expressed in the number of seconds before renewal.

Value Type: Integer

Default Value: 300

Config Example: webhook_renewal_interval = "600"

webhook_retry_interval

Description: This configuration option controls the frequency at which an existing Microsoft OneDrive webhook subscription is retried when creating or renewing a subscription failed. The value is expressed in the number of seconds before retry.

Value Type: Integer

Default Value: 60

Config Example: webhook_retry_interval = "120"

Command Line Interface (CLI) Only Options

CLI Option: --auth-files

Description: This CLI option allows the user to perform application authentication not via an interactive dialog but via specific files that the application uses to read the authentication data from.

Usage Example: onedrive --auth-files authUrl:responseUrl

Important

The authorisation URL is written to the specified 'authUrl' file, then onedrive waits for the file 'responseUrl' to be present, and reads the authentication response from that file. Example:

onedrive --auth-files '~/onedrive-auth-url:~/onedrive-response-url' 
Reading configuration file: /home/alex/.config/onedrive/config
Configuration file successfully loaded
Configuring Global Azure AD Endpoints
Client requires authentication before proceeding. Waiting for --auth-files elements to be available.

At this point, the client has written the file ~/onedrive-auth-url which contains the authentication URL that needs to be visited to perform the authentication process. The client will now wait and watch for the presence of the file ~/onedrive-response-url.

Visit the authentication URL, and then create a new file called ~/onedrive-response-url with the response URI. Once this has been done, the application will acknowledge the presence of this file, read the contents, and authenticate the application.

Sync Engine Initialised with new Onedrive API instance

 --sync or --monitor switches missing from your command line input. Please add one (not both) of these switches to your command line or use 'onedrive --help' for further assistance.

No OneDrive sync will be performed without one of these two arguments being present.

CLI Option: --auth-response

Description: This CLI option allows the user to perform application authentication not via an interactive dialog but via providing the authentication response URI directly.

Usage Example: onedrive --auth-response https://login.microsoftonline.com/common/oauth2/nativeclient?code=<redacted>

Tip

Typically, unless the application client identifier has been modified, authentication scopes are being modified or a specific Azure Tenant is being specified, the authentication URL will most likely be as follows:

https://login.microsoftonline.com/common/oauth2/v2.0/authorise?client_id=22c49a0d-d21c-4792-aed1-8f163c982546&scope=Files.ReadWrite%20Files.ReadWrite.all%20Sites.ReadWrite.All%20offline_access&response_type=code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

With this URL being known, it is possible ahead of time to request an authentication token by visiting this URL, and performing the authenticaton access request.

CLI Option: --confdir

Description: This CLI option allows the user to specify where all the application configuration and relevant components are stored.

Usage Example: onedrive --confdir '~/.config/onedrive-business/'

Important

If using this option, it must be specified each and every time the application is used. If this is ommited, the application default configuration directory will be used.

CLI Option: --create-directory

Description: This CLI option allows the user to create the specified directory path on Microsoft OneDrive without performing a sync.

Usage Example: onedrive --create-directory 'path/of/new/folder/structure/to/create/'

Important

The specified path to create is relative to your configured 'sync_dir'.

CLI Option: --create-share-link

Description: This CLI option enables the creation of a shareable file link that can be provided to users to access the file that is stored on Microsoft OneDrive. By default, the permissions for the file will be 'read-only'.

Usage Example: onedrive --create-share-link 'relative/path/to/your/file.txt'

Important

If writable access to the file is required, you must add --with-editing-perms to your command. See below for details.

CLI Option: --destination-directory

Description: This CLI option specifies the 'destination' portion of moving a file or folder online, without performing a sync operation.

Usage Example: onedrive --source-directory 'path/as/source/' --destination-directory 'path/as/destination'

Important

All specified paths are relative to your configured 'sync_dir'.

CLI Option: --display-config

Description: This CLI option will display the effective application configuration

Usage Example: onedrive --display-config

CLI Option: --display-sync-status

Description: This CLI option will display the sync status of the configured 'sync_dir'

Usage Example: onedrive --display-sync-status

Tip

This option can also use the --single-directory option to determine the sync status of a specific directory within the configured 'sync_dir'

CLI Option: ---display-quota

Description: This CLI option will display the quota status of the account drive id or the configured 'drive_id' value

Usage Example: onedrive --display-quota

CLI Option: --force

Description: This CLI option enables the force the deletion of data when a 'big delete' is detected.

Usage Example: onedrive --sync --verbose --force

Important

This option should only be used exclusively in cases where you've initiated a 'big delete' and genuinely intend to remove all the data that is set to be deleted online.

CLI Option: --force-sync

Description: This CLI option enables the syncing of a specific directory, using the Client Side Filtering application defaults, overriding any user application configuration.

Usage Example: `onedrive --sync --verbose --force-sync --single-directory 'Data'

Note

When this option is used, you will be presented with the following warning and risk acceptance:

WARNING: Overriding application configuration to use application defaults for skip_dir and skip_file due to --synch --single-directory --force-sync being used

The use of --force-sync will reconfigure the application to use defaults. This may have untold and unknown future impacts.
By proceeding in using this option you accept any impacts including any data loss that may occur as a result of using --force-sync.

Are you sure you wish to proceed with --force-sync [Y/N] 

To procceed with this sync task, you must risk accept the actions you are taking. If you have any concerns, first use --dry-run and evaluate the outcome before proceeding with the actual action.

CLI Option: --get-file-link

Description: This CLI option queries the OneDrive API and return's the WebURL for the given local file.

Usage Example: onedrive --get-file-link 'relative/path/to/your/file.txt'

Important

The path that you should use must be relative to your 'sync_dir'

CLI Option: --get-sharepoint-drive-id

Description: This CLI option queries the OneDrive API and return's the Office 365 Drive ID for a given Office 365 SharePoint Shared Library that can then be used with 'drive_id' to sync a specific SharePoint Library.

Usage Example: onedrive --get-sharepoint-drive-id '*' or onedrive --get-sharepoint-drive-id 'PointPublishing Hub Site'

CLI Option: --list-shared-items

Description: This CLI option lists all OneDrive Business Shared items with your account. The resulting list shows shared files and folders that you can configure this client to sync.

Usage Example: onedrive --list-shared-items

Example Output:

...
Listing available OneDrive Business Shared Items:

-----------------------------------------------------------------------------------
Shared File:     large_document_shared.docx
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     no_download_access.docx
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     online_access_only.txt
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     read_only.txt
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     qewrqwerwqer.txt
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     dummy_file_to_share.docx
Shared By:       testuser2 testuser2 (testuser2@domain.tld)
-----------------------------------------------------------------------------------
Shared Folder:   Sub Folder 2
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared File:     file to share.docx
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
Shared Folder:   Top Folder
Shared By:       test user (testuser@domain.tld)
-----------------------------------------------------------------------------------
...

CLI Option: --logout

Description: This CLI option removes this clients authentictaion status with Microsoft OneDrive. Any further application use will requrie the application to be re-authenticated with Microsoft OneDrive.

Usage Example: onedrive --logout

CLI Option: --modified-by

Description: This CLI option queries the OneDrive API and return's the last modified details for the given local file.

Usage Example: onedrive --modified-by 'relative/path/to/your/file.txt'

Important

The path that you should use must be relative to your 'sync_dir'

CLI Option: --monitor | -m

Description: This CLI option controls the 'Monitor Mode' operational aspect of the client. When this option is used, the client will perform on-going syncs of data between Microsoft OneDrive and your local system. Local changes will be uploaded in near-realtime, whilst online changes will be downloaded on the next sync process. The frequency of these checks is governed by the 'monitor_interval' value.

Usage Example: onedrive --monitor or onedrive -m

CLI Option: --print-access-token

Description: Print the current access token being used to access Microsoft OneDrive.

Usage Example: onedrive --verbose --verbose --debug-https --print-access-token

Caution

Do not use this option if you do not know why you are wanting to use it. Be highly cautious of exposing this object. Change your password if you feel that you have inadvertantly exposed this token.

CLI Option: --reauth

Description: This CLI option controls the ability to re-authenticate your client with Microsoft OneDrive.

Usage Example: onedrive --reauth

CLI Option: --remove-directory

Description: This CLI option allows the user to remove the specified directory path on Microsoft OneDrive without performing a sync.

Usage Example: onedrive --remove-directory 'path/of/new/folder/structure/to/remove/'

Important

The specified path to remove is relative to your configured 'sync_dir'.

CLI Option: --single-directory

Description: This CLI option controls the applications ability to sync a specific single directory.

Usage Example: onedrive --sync --single-directory 'Data'

Important

The path specified is relative to your configured 'sync_dir' path. If the physical local path 'Folder' to sync is ~/OneDrive/Data/Folder then the command would be --single-directory 'Data/Folder'.

CLI Option: --source-directory

Description: This CLI option specifies the 'source' portion of moving a file or folder online, without performing a sync operation.

Usage Example: onedrive --source-directory 'path/as/source/' --destination-directory 'path/as/destination'

Important

All specified paths are relative to your configured 'sync_dir'.

CLI Option: --sync | -s

Description: This CLI option controls the 'Standalone Mode' operational aspect of the client. When this option is used, the client will perform a one-time sync of data between Microsoft OneDrive and your local system.

Usage Example: onedrive --sync or onedrive -s

CLI Option: --sync-shared-files

Description: Sync OneDrive Business Shared Files to the local filesystem.

Usage Example: onedrive --sync --sync-shared-files

Important

To use this option you must first enable 'sync_business_shared_items' within your application configuration. Please read 'business-shared-items.md' for more information regarding this option.

CLI Option: --verbose | -v+

Description: This CLI option controls the verbosity of the application output. Use the option once, to have normal verbose output, use twice to have debug level application output.

Usage Example: onedrive --sync --verbose or onedrive --monitor --verbose

CLI Option: --with-editing-perms

Description: This CLI option enables the creation of a writable shareable file link that can be provided to users to access the file that is stored on Microsoft OneDrive. This option can only be used in conjunction with --create-share-link

Usage Example: onedrive --create-share-link 'relative/path/to/your/file.txt' --with-editing-perms

Important

Placement of --with-editing-perms is critical. It must be placed after the file path as per the example above.

Depreciated Configuration File and CLI Options

The following configuration options are no longer supported:

force_http_2

Description: Force the use of HTTP/2 for all operations where applicable

Depreciated Config Example: force_http_2 = "true"

Depreciated CLI Option: --force-http-2

Reason for depreciation: HTTP/2 will be used by default where possible, when the OneDrive API platform does not downgrade the connection to HTTP/1.1, thus this confuguration option is no longer required.

min_notify_changes

Description: Minimum number of pending incoming changes necessary to trigger a GUI desktop notification.

Depreciated Config Example: min_notify_changes = "50"

Depreciated CLI Option: --min-notify-changes '50'

Reason for depreciation: Application has been totally re-written. When this item was introduced, it was done so to reduce spamming of all events to the GUI desktop.

CLI Option: --synchronize

Description: Perform a synchronisation with Microsoft OneDrive

Depreciated CLI Option: --synchronize

Reason for depreciation: --synchronize has been depreciated in favour of --sync or -s