* Update docs
56 KiB
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
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
Additional Usage Requirement: 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
Important
Additional Usage Requirement: Create a
.nosync
file in your mount point before you mount your disk so that this is visible, in your mount point if your disk is unmounted.
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
Additional Usage Requirement: 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
Additional Usage Requirement: 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
Additional Usage Requirement: 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
Important
Additional Usage Notes: 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
Tip
Additional Usage Notes: 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.
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
Additional Usage Notes: 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.
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"
Additional Usage Notes: 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
Additional Usage Notes: Additional configuration is potentially required to configure the default log directory. Refer to usage.md for details (ADD LINK)
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"
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes:
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
Additional Usage Notes: 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"
Additional Usage Notes: 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
Additional Usage Notes: 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
Additional Usage Notes: 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
Additional Usage Notes: In certain automated environments (assuming you know what you're doing due to 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'
Additional Usage Notes: 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
Additional Usage Notes: 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'
Additional Usage Notes: 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
Additional Usage Notes: 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
Additional Usage Notes: 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.
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'
Additional Usage Notes: After changing this option, you will be required to perform a resync.
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"
Additional Usage Notes: 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"
Additional Usage Notes: 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
Additional Usage Notes: 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"
Additional Usage Notes: 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 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
Additional Usage Notes: 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"
Additional Usage Notes: The current value conforms the the Microsoft Graph API documentation for presenting an appropriate 'User-Agent' header and aligns to the registered 'application_id' that this application uses.
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/"
Additional Usage Notes:
etting 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
Note: A valid HTTPS certificate is required for your public-facing URL if using nginx.
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.
Additional Usage Notes: 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"
Additional Usage Notes: 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
Additional Usage Notes: 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>
Additional Usage Notes: Typically, unless the application client identifier, authentication scopes are being modified or a specific Azure Tenant is being specified, the authentication URL will mostlikely 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/'
Additional Usage Notes: 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/'
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes: 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
Additional Usage Notes: 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
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes: 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
Additional Usage Notes: 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/'
Additional Usage Notes: 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'
Additional Usage Notes: 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'
Additional Usage Notes: 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
Additional Usage Notes: 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
Additional Usage Notes: 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