Before reading this document, please ensure you are running application version 
onedrive --version to determine what application version you are using and upgrade your client if required.
- 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
- create_new_file_version
- data_timeout
- debug_https
- disable_download_validation
- disable_notifications
- disable_permission_set
- disable_upload_validation
- display_running_config
- display_transfer_metrics
- dns_timeout
- download_only
- drive_id
- dry_run
- enable_logging
- force_http_11
- ip_protocol_version
- local_first
- log_dir
- max_curl_idle
- monitor_fullscan_frequency
- monitor_interval
- monitor_log_frequency
- no_remote_delete
- notify_file_actions
- operation_timeout
- permanent_delete
- 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
- transfer_order
- upload_only
- user_agent
- webhook_enabled
- webhook_expiration_interval
- webhook_listening_host
- webhook_listening_port
- webhook_public_url
- webhook_renewal_interval
- write_xattr_data
- 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
- Deprecated Configuration File and CLI Options
Description: This is the config option for application id that 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"
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"
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.
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"
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.
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.
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.
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.
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"
Description: This setting controls how the application handles the Microsoft SharePoint feature which modifies all PDF, MS Office & HTML files post upload, effectively breaking the integrity of your data online. By default, when the application determines that this feature has modified your file post upload, the now online modified file will be downloaded. When this option is enabled, rather than downloading the file, a new online file version is created which negates the download of the modified file.
Value Type: Boolean
Default Value: False
Config Example: create_new_file_version = "false" or create_new_file_version = "true"
CLI Option Use: None - this is a config file option only
Important
If you enable 'disable_upload_validation' via disable_upload_validation = "true" there is zero facility to determine if a file was modified post upload. As such, the application will default to the state that the upload integrity check has failed. When create_new_file_version = "false" your uploaded file will be downloaded regardless of the online modification state.
Warning
When this option is set to 'true', new file versions will be created online which will count towards your Microsoft OneDrive Quota.
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: 60
Config Example: data_timeout = "300"
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.
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.
Caution
If you are using OneDrive Business Accounts and your organisation implements Azure Information Protection, these AIP files will report as one size & hash online, but when downloaded, will report a totally different size and hash.
By default these files will fail integrity checking and be deleted, meaning that AIP files will not reside on your platform.
When you enable this option, the AIP files will download to your platform, however, if there are any other genuine download failures where the size and hash are different, these too will be retained locally meaning you may experience data integrity loss. Use this option with extreme caution.
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
Description: This setting controls whether the application will set the permissions on files and directories using the values of 'sync_dir_permissions' and 'sync_file_permissions'. When this option is enabled, file system permission inheritance will be used to assign the permissions for your data. This option may be useful if the file system configured does not allow setting of POSIX permissions.
Value Type: Boolean
Default Value: False
Config Example: disable_permission_set = "false" or disable_permission_set = "true"
CLI Option Use: None - this is a config file option only
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.
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 occurring, 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
Description: This option will display file transfer metrics when enabled.
Value Type: Boolean
Default Value: False
Config Example: display_transfer_metrics = "false" or display_transfer_metrics = "true"
Output Example: Transfer Metrics - File: path/to/file.data | Size: 35768 Bytes | Duration: 2.27 Seconds | Speed: 0.02 Mbps (approx)
CLI Option Use: None - this is a config file option only
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"
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
Important
When using this option, the default mode of operation is to not clean up local files that have been deleted online. This ensures that the local data is an archive of what was stored online. To cleanup local files use --cleanup-local-files.
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 occurred.
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
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
Description: This setting controls the application HTTP protocol version. By default, the application will use libcurl defaults for which HTTP protocol 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
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.
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
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/"
Description: This configuration option controls the number of seconds that elapse after a cURL engine was last used before it is considered stale and destroyed. Evidence suggests that some upstream network devices ignore the cURL keep-alive setting and forcibly close the active TCP connection when idle.
Value Type: Integer
Default Value: 120
Config Example: monitor_fullscan_frequency = "120"
CLI Option Use: None - this is a config file option only
Important
It is strongly recommended not to modify this setting without conducting thorough network testing. Changing this option may lead to unexpected behaviour or connectivity issues, especially if upstream network devices handle idle connections in non-standard ways.
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.
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.
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 occurring.
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 synchronisation 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 occurring 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 suppression.
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
Description: This configuration option controls whether the client will log via GUI notifications successful actions that the client performs.
Value Type: Boolean
Default Value: False
Config Example: notify_file_actions = "true"
Note
GUI Notification Support must be compiled in first, otherwise this option will have zero effect and will not be used.
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"
Description: Permanently delete an item online when it is removed locally. When using this method, they're permanently removed and aren't sent to the Microsoft OneDrive Recycle Bin. Therefore, permanently deleted drive items can't be restored afterward. Online data loss MAY occur in this scenario.
Value Type: Boolean
Default Value: False
Config Example: permanent_delete = "true"
CLI Option Use: None - this is a config file option only
Important
The Microsoft OneDrive API for this capability is also very narrow:
| Account Type | Config Option is Supported |
|---|---|
| Personal | ❌ |
| Business | ✔ |
| SharePoint | ✔ |
| Microsoft Cloud Germany | ✔ |
| Microsoft Cloud for US Government | ❌ |
| Azure and Office365 operated by VNET in China | ❌ |
When using this config option against an unsupported Personal Accounts the following message will be generated:
WARNING: The application is configured to permanently delete files online; however, this action is not supported by Microsoft OneDrive Personal Accounts.
When using this config option against a supported account the following message will be generated:
WARNING: Application has been configured to permanently remove files online rather than send to the recycle bin. Permanently deleted items can't be restored.
WARNING: Online data loss MAY occur in this scenario.
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"
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.
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
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
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.
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.
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
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.
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"
Important
Entries for 'skip_file' are relative to your 'sync_dir' path.
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.
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'
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.
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 (expressed as Bytes when using --display-config)
Config Example: space_reservation = "100"
CLI Option Use: --space-reservation '100'
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.
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.
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.
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.
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.
Description: This configuration option controls the number of 'threads' for upload and download operations when files need to be transferred 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.
Description: This configuration option controls the transfer order of files between your local system and Microsoft OneDrive.
Value Type: String
Default Value: default
Config Example:
transfer_order = "size_asc"
transfer_order = "size_dsc"
transfer_order = "name_asc"
transfer_order = "name_dsc"
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.
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
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 = "https://<your.fully.qualified.domain.name>/webhooks/onedrive"
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.
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 adding the following 'proxy' configuration options to your nginx configuration file:
server {
listen 443;
server_name <your.fully.qualified.domain.name>;
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/
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"
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.
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.
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:
webhook_public_url = "https://<your.fully.qualified.domain.name>/webhooks/onedrive"
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"
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"
Description: This setting enables writing xattr values detailing the 'createdBy' and 'lastModifiedBy' information provided by the OneDrive API
Value Type: Boolean
Default Value: False
Config Example: write_xattr_data = "false" or write_xattr_data = "true"
CLI Option Use: None - this is a config file option only
xattr Data Example:
user.onedrive.createdBy="Account Display Name"
user.onedrive.lastModifiedBy="Account Display Name"
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.
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/authorize?client_id=d50ca740-c83f-4d1b-b616-12c519384f0c&scope=Files.ReadWrite%20Files.ReadWrite.All%20Sites.ReadWrite.All%20offline_access&response_type=code&prompt=login&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 authentication access request.
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 omitted, the application default configuration directory will be used.
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'.
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.
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'.
Description: This CLI option will display the effective application configuration
Usage Example: onedrive --display-config
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'
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
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.
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 proceed 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.
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'
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'
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 ([email protected])
-----------------------------------------------------------------------------------
Shared File: no_download_access.docx
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared File: online_access_only.txt
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared File: read_only.txt
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared File: qewrqwerwqer.txt
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared File: dummy_file_to_share.docx
Shared By: testuser2 testuser2 ([email protected])
-----------------------------------------------------------------------------------
Shared Folder: Sub Folder 2
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared File: file to share.docx
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
Shared Folder: Top Folder
Shared By: test user ([email protected])
-----------------------------------------------------------------------------------
...
Description: This CLI option removes this clients authentication status with Microsoft OneDrive. Any further application use will require the application to be re-authenticated with Microsoft OneDrive.
Usage Example: onedrive --logout
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'
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
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 inadvertently exposed this token.
Description: This CLI option controls the ability to re-authenticate your client with Microsoft OneDrive.
Usage Example: onedrive --reauth
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'.
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'.
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'.
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
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.
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
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.
The following configuration options are no longer supported:
Description: Force the use of HTTP/2 for all operations where applicable
Deprecated Config Example: force_http_2 = "true"
Deprecated 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 configuration option is no longer required.
Description: Minimum number of pending incoming changes necessary to trigger a GUI desktop notification.
Deprecated Config Example: min_notify_changes = "50"
Deprecated 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.
Description: Perform a synchronisation with Microsoft OneDrive
Deprecated CLI Option: --synchronize
Reason for depreciation: --synchronize has been deprecated in favour of --sync or -s