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.

• Important Notes
  • Memory Usage
  • Upgrading from the 'skilion' Client
  • Guidelines for Local File and Folder Naming in the Synchronisation Directory
  • Compatibility with curl
• First Steps
  • Authorise the Application with Your Microsoft OneDrive Account
  • Display Your Applicable Runtime Configuration
  • Understanding OneDrive Client for Linux Operational Modes
    • Standalone Synchronisation Operational Mode (Standalone Mode)
    • Ongoing Synchronisation Operational Mode (Monitor Mode)
• Using the OneDrive Client for Linux to synchronise your data
  • Increasing application logging level
  • Using 'Client Side Filtering' rules to determine what should be synced with Microsoft OneDrive
  • Testing your configuration
  • Performing a sync with Microsoft OneDrive
  • Performing a single directory synchronisation with Microsoft OneDrive
  • Performing a 'one-way' download synchronisation with Microsoft OneDrive
  • Performing a 'one-way' upload synchronisation with Microsoft OneDrive
  • Performing a selective synchronisation via 'sync_list' file
  • Performing a --resync
  • Performing a --force-sync without a --resync or changing your configuration
  • Enabling the Client Activity Log
    • Client Activity Log Example:
    • Client Activity Log Differences
  • GUI Notifications
  • Handling a Microsoft OneDrive Account Password Change
  • Determining the synchronisation result
• Frequently Asked Configuration Questions
  • How to change the default configuration of the client?
  • How to change where my data from Microsoft OneDrive is stored?
  • How to change what file and directory permissions are assigned to data that is downloaded from Microsoft OneDrive?
  • How are uploads and downloads managed?
  • How to only sync a specific directory?
  • How to 'skip' files from syncing?
  • How to 'skip' directories from syncing?
  • How to 'skip' .files and .folders from syncing?
  • How to 'skip' files larger than a certain size from syncing?
  • How to 'rate limit' the application to control bandwidth consumed for upload & download operations?
  • How can I prevent my local disk from filling up?
  • How does the client handle symbolic links?
  • How to synchronise OneDrive Personal Shared Folders?
  • How to synchronise OneDrive Business Shared Items (Files and Folders)?
  • How to synchronise SharePoint / Office 365 Shared Libraries?
  • How to Create a Shareable Link?
  • How to Synchronise Both Personal and Business Accounts at once?
  • How to Synchronise Multiple SharePoint Libraries simultaneously?
  • How to Receive Real-time Changes from Microsoft OneDrive Service, instead of waiting for the next sync period?
  • How to initiate the client as a background service?
    • OneDrive service running as root user via init.d
    • OneDrive service running as root user via systemd (Arch, Ubuntu, Debian, OpenSuSE, Fedora)
    • OneDrive service running as root user via systemd (Red Hat Enterprise Linux, CentOS Linux)
    • OneDrive service running as a non-root user via systemd (All Linux Distributions)
    • OneDrive service running as a non-root user via systemd (with notifications enabled) (Arch, Ubuntu, Debian, OpenSuSE, Fedora)
    • OneDrive service running as a non-root user via runit (antiX, Devuan, Artix, Void)
  • How to start a user systemd service at boot without user login?
  • How to access Microsoft OneDrive service through a proxy
  • How to set up SELinux for a sync folder outside of the home folder
• Advanced Configuration of the OneDrive Client for Linux
• Overview of all OneDrive Client for Linux CLI Options

Starting with version 2.5.x, the application has been completely rewritten. It is crucial to understand the memory requirements to ensure the application runs smoothly on your system.

During a --resync or full online scan, the OneDrive Client may use approximately 1GB of memory for every 100,000 objects stored online. This is because the client retrieves data for all objects via the OneDrive API before processing them locally. Once this process completes, the memory is freed. To avoid performance issues, ensure your system has sufficient available memory. If the system starts using swap space due to insufficient free memory, this can significantly slow down the application and impact overall performance.

To avoid potential system instability or the client being terminated by your Out-Of-Memory (OOM) process monitors, please ensure your system has sufficient memory allocated or configure adequate swap space.

The 'skilion' version has a significant number of issues in how it manages the local sync state. When upgrading from the 'skilion' client to this client, it's recommended to stop any service or OneDrive process that may be running. Once all OneDrive services are stopped, make sure to remove any old client binaries from your system.

To ensure seamless synchronisation with Microsoft OneDrive, it's critical to adhere strictly to the prescribed naming conventions for your files and folders within the sync directory. The guidelines detailed below are designed to preempt potential sync failures by aligning with Microsoft Windows Naming Conventions, coupled with specific OneDrive restrictions.

• Invalid Characters:
  • Avoid using the following characters in names of files and folders: " * : < > ? / \ |
  • Names should not start or end with spaces
  • Names should not end with a fullstop / period character .
• Prohibited Names:
  • Certain names are reserved and cannot be used for files or folders: .lock, CON, PRN, AUX, NUL, COM0 - COM9, LPT0 - LPT9, desktop.ini, any filename starting with ~$
  • The text sequence _vti_ cannot appear anywhere in a file or directory name
  • A file and folder called forms is unsupported at the root level of a synchronisation directory
• Path Length
  • All files and folders stored in your 'sync_dir' (typically ~/OneDrive) must not have a path length greater than:
    • 400 characters for OneDrive Business & SharePoint
    • 430 characters for OneDrive Personal

Should a file or folder infringe upon these naming conventions or restrictions, synchronisation will skip the item, indicating an invalid name according to Microsoft Naming Convention. The only remedy is to rename the offending item. This constraint is by design and remains firm.

The above guidelines are essential for maintaining synchronisation integrity with Microsoft OneDrive. Adhering to them ensures your files and folders sync without issue. For additional details, consult the following resources:

• Microsoft Windows Naming Conventions
• Restrictions and limitations in OneDrive and SharePoint

Adherence to these guidelines is not optional but mandatory to avoid sync disruptions.

If your system uses curl < 7.47.0, curl will default to HTTP/1.1 for HTTPS operations, and the client will follow suit, using HTTP/1.1.

For systems running curl >= 7.47.0 and < 7.62.0, curl will prefer HTTP/2 for HTTPS, but it will still use HTTP/1.1 as the default for these operations. The client will employ HTTP/1.1 for HTTPS operations as well.

However, if your system employs curl >= 7.62.0, curl will, by default, prioritise HTTP/2 over HTTP/1.1. In this case, the client will utilise HTTP/2 for most HTTPS operations and stick with HTTP/1.1 for others. Please note that this distinction is governed by the OneDrive platform, not our client.

If you explicitly want to use HTTP/1.1, you can do so by using the --force-http-11 flag or setting the configuration option force_http_11 = "true". This will compel the application to exclusively use HTTP/1.1. Otherwise, all client operations will align with the curl default settings for your distribution.

WARNING: Your curl/libcurl version (curl.version.number) has known HTTP/2 bugs that impact the use of this application.
         Please report this to your distribution and request that they provide a newer curl version for your platform or upgrade this yourself.
         Downgrading all application operations to use HTTP/1.1 to ensure maximum operational stability.
         Please read https://github.com/abraunegg/onedrive/blob/master/docs/usage.md#compatibility-with-curl for more information.

force_http_11 = "true"
ip_protocol_version = "1"

WARNING: Your curl/libcurl version (curl.version.number) has known operational bugs that impact the use of this application.
         Please report this to your distribution and request that they provide a newer curl version for your platform or upgrade this yourself.

Once you've installed the application, you'll need to authorise it using your Microsoft OneDrive Account. This can be done by simply running the application without any additional command switches.

Please be aware that some companies may require you to explicitly add this app to the Microsoft MyApps portal. To add an approved app to your apps, click on the ellipsis in the top-right corner and select "Request new apps." On the next page, you can add this app. If it's not listed, you should make a request through your IT department.

When you run the application for the first time, you'll be prompted to open a specific URL using your web browser, where you'll need to log in to your Microsoft Account and grant the application permission to access your files. After granting permission to the application, you'll be redirected to a blank page. Simply copy the URI from the blank page and paste it into the application.

Example:

[user@hostname ~]$ onedrive
Authorise this app by visiting:

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

Enter the response URI from your browser:  https://login.microsoftonline.com/common/oauth2/nativeclient?code=<redacted>

The application has been successfully authorised, but no additional command switches were provided.

Please use 'onedrive --help' for further assistance on how to run this application.

To verify the configuration that the application will use, use the following command:

onedrive --display-config

This command will display all the relevant runtime interpretations of the options and configurations you are using. An example output is as follows:

Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
onedrive version                             = vX.Y.Z-A-bcdefghi
Config path                                  = /home/user/.config/onedrive
Config file found in config path             = true
Config option 'drive_id'                     = 
Config option 'sync_dir'                     = ~/OneDrive
...
Config option 'webhook_enabled'              = false

There are two modes of operation when using the client:

1. Standalone sync mode that performs a single sync action against Microsoft OneDrive.
2. Ongoing sync mode that continuously syncs your data with Microsoft OneDrive.

This method of use can be employed by issuing the following option to the client:

onedrive --sync

For simplicity, this can be shortened to the following:

onedrive -s

This method of use can be utilised by issuing the following option to the client:

onedrive --monitor

For simplicity, this can be shortened to the following:

onedrive -m

Two common errors can occur when using monitor mode:

• Initialisation failure
• Unable to add a new inotify watch

Both of these errors are local environment issues, where the following system variables need to be increased as the current system values are potentially too low:

• fs.file-max
• fs.inotify.max_user_watches

To determine what the existing values are on your system, use the following commands:

sysctl fs.file-max
sysctl fs.inotify.max_user_watches

Alternatively, when running the client with increased verbosity (see below), the client will display what the current configured system maximum values are:

...
All application operations will be performed in: /home/user/OneDrive
OneDrive synchronisation interval (seconds): 300
Maximum allowed open files:                 393370   <-- This is the current operating system fs.file-max value
Maximum allowed inotify watches:            29374    <-- This is the current operating system fs.inotify.max_user_watches value
Initialising filesystem inotify monitoring ...
...

To determine what value to change to, you need to count all the files and folders in your configured 'sync_dir':

cd /path/to/your/sync/dir
ls -laR | wc -l

To make a change to these variables using your file and folder count, use the following process:

sudo sysctl fs.file-max=<new_value>
sudo sysctl fs.inotify.max_user_watches=<new_value>

Once these values are changed, you will need to restart your client so that the new values are detected and used.

To make these changes permanent on your system, refer to your OS reference documentation.

When running a sync (--sync) or using monitor mode (--monitor), it may be desirable to see additional information regarding the progress and operation of the client. For example, for a --sync command, this would be:

onedrive --sync --verbose

Furthermore, for simplicity, this can be simplified to the following:

onedrive -s -v

Client Side Filtering in the context of the OneDrive Client for Linux refers to user-configured rules that determine what files and directories the client should upload or download from Microsoft OneDrive. These rules are crucial for optimising synchronisation, especially when dealing with large numbers of files or specific file types. The OneDrive Client for Linux offers several configuration options to facilitate this:

• check_nosync: This option allows you to create a .nosync file in local directories, to skip that directory from being included in sync operations.
• skip_dir: This option allows the user to specify directories that should not be synchronised with OneDrive. It's particularly useful for omitting large or irrelevant directories from the sync process.
• skip_dotfiles: Dotfiles, usually configuration files or scripts, can be excluded from the sync. This is useful for users who prefer to keep these files local.
• skip_file: Specific files can be excluded from synchronisation using this option. It provides flexibility in selecting which files are essential for cloud storage.
• skip_size: Skip files greater than this specific size (in MB)
• skip_symlinks: Symlinks often point to files outside the OneDrive directory or to locations that are not relevant for cloud storage. This option prevents them from being included in the sync.

Additionally, the OneDrive Client for Linux allows the implementation of Client Side Filtering rules through a 'sync_list' file. This file explicitly states which directories or files should be included in the synchronisation. By default, any item not listed in the 'sync_list' file is excluded. This method offers a more granular approach to synchronisation, ensuring that only the necessary data is transferred to and from Microsoft OneDrive.

These configurable options and the 'sync_list' file provide users with the flexibility to tailor the synchronisation process to their specific needs, conserving bandwidth and storage space while ensuring that important files are always backed up and accessible.

You can test your configuration by utilising the --dry-run CLI option. No files will be downloaded, uploaded, or removed; however, the application will display what 'would' have occurred. For example:

onedrive --sync --verbose --dry-run
Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
Using 'user' Config Dir: /home/user/.config/onedrive
DRY-RUN Configured. Output below shows what 'would' have occurred.
DRY-RUN: Copying items.sqlite3 to items-dryrun.sqlite3 to use for dry run operations
DRY RUN: Not creating backup config file as --dry-run has been used
DRY RUN: Not updating hash files as --dry-run has been used
Checking Application Version ...
Attempting to initialise the OneDrive API ...
Configuring Global Azure AD Endpoints
The OneDrive API was initialised successfully
Opening the item database ...
Sync Engine Initialised with new Onedrive API instance
Application version:  vX.Y.Z-A-bcdefghi
Account Type:         <account-type>
Default Drive ID:     <drive-id>
Default Root ID:      <root-id>
Remaining Free Space: 1058488129 KB
All application operations will be performed in: /home/user/OneDrive
Fetching items from the OneDrive API for Drive ID: <drive-id> ..
...
Performing a database consistency and integrity check on locally stored data ... 
Processing DB entries for this Drive ID: <drive-id>
Processing ~/OneDrive
The directory has not changed
...
Scanning local filesystem '~/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: <drive-id> ..

Sync with Microsoft OneDrive is complete

By default, all files are downloaded in ~/OneDrive. This download location is controlled by the 'sync_dir' config option.

After authorising the application, a sync of your data can be performed by running:

onedrive --sync

This will synchronise files from your Microsoft OneDrive account to your ~/OneDrive local directory or to your specified 'sync_dir' location.

onedrive --sync --local-first

In some cases, it may be desirable to synchronise a single directory under ~/OneDrive without having to change your client configuration. To do this, use the following command:

onedrive --sync --single-directory '<dir_name>'

In some cases, it may be desirable to 'download only' from Microsoft OneDrive. To do this, use the following command:

onedrive --sync --download-only

This will download all the content from Microsoft OneDrive to your ~/OneDrive location. Any files that are deleted online will remain locally and will not be removed.

onedrive --sync --download-only --cleanup-local-files

In certain scenarios, you might need to perform an 'upload only' operation to Microsoft OneDrive. This means that you'll be uploading data to OneDrive, but not synchronising any changes or additions made elsewhere. Use this command to initiate an upload-only synchronisation:

onedrive --sync --upload-only

onedrive --sync --upload-only --no-remote-delete

Selective synchronisation allows you to sync only specific files and directories. To enable selective synchronisation, create a file named sync_list in your application configuration directory (default is ~/.config/onedrive).

Each line of the 'sync_list' file represents a relative path from your sync_dir. All files and directories not matching any line of the file will be skipped during all operations.

Additionally, the use of / is critically important to determine how a rule is interpreted. It is very similar to ** wildcards, for those that are familiar with globbing patterns. Here is an example of sync_list:

# sync_list supports comments
#
# The ordering of entries is highly recommended - exclusions before inclusions
#
# Exclude temp folder(s) or file(s) under Documents folder(s), anywhere in OneDrive
!Documents/temp*
#
# Exclude secret data folder in root directory only
!/Secret_data/*
#
# Include everything else in root directory
# - Use 'sync_root_files' or --sync-root-files option
# Do not use /* as this will include everything including items you are expecting to be excluded
#
# Include my Backup folder(s) or file(s) anywhere on OneDrive
Backup
#
# Include my Backup folder in root
/Backup/
#
# Include Documents folder(s) anywhere in OneDrive
Documents/
#
# Include all PDF files in Documents folder(s), anywhere in OneDrive
Documents/*.pdf
#
# Include this single document in Documents folder(s), anywhere in OneDrive
Documents/latest_report.docx
#
# Include all Work/Project directories or files, inside 'Work' folder(s), anywhere in OneDrive
Work/Project*
#
# Include the 'Blog' directory, but exclude 'Parent' and any other children of the parent
# .
# ├── Parent
# │   ├── Blog
# │   │   ├── random_files
# │   │   │   ├── CZ9aZRM7U1j7pM21fH0MfP2gywlX7bqW
# │   │   │   └── k4GptfTBE2z2meRFqjf54tnvSXcXe30Y
# │   │   └── random_images
# │   │       ├── cAuQMfX7qsMIOmzyQYdELikZwsXeCYsL
# │   │       └── GqjZuo7UBB0qjYM2WUcZXOvToAhCQ29M
# │   └── other_stuffs
/Parent/Blog/*
#
# Include all "notes.txt" files, anywhere in OneDrive
notes.txt
#
# Include /Blender in the ~OneDrive root but not if elsewhere in OneDrive
/Blender
#
# Include these directories(or files) in 'Pictures' folder(s), that have a space in their name
Pictures/Camera Roll
Pictures/Saved Pictures
#
# Include these names if they match any file or folder
Cinema Soc
Codes
Textbooks
Year 2

The following are supported for pattern matching and exclusion rules:

• Use the * to wildcard select any characters to match for the item to be included
• Use either ! or - characters at the start of the line to exclude an otherwise included item

sync_root_files = "true"

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

Additionally, you might opt for a --resync if you think it's necessary to ensure your data remains in sync. If you're using this switch simply because you're unsure of the sync status, you can check the actual sync status using --display-sync-status.

When you use --resync, you'll encounter the following warning and advice:

Using --resync will delete your local 'onedrive' client state, so there won't be a record of your current 'sync status.'
This may potentially overwrite local versions of files with older versions downloaded from OneDrive, leading to local data loss.
If in doubt, back up your local data before using --resync.

Are you sure you want to proceed with --resync? [Y/N] 

To proceed with --resync, you must type 'y' or 'Y' to allow the application to continue.

In some cases and situations, you may have configured the application to skip certain files and folders using 'skip_file' and 'skip_dir' configuration. You then may have a requirement to actually sync one of these items, but do not wish to modify your configuration, nor perform an entire --resync twice.

The --force-sync option allows you to sync a specific directory, ignoring your 'skip_file' and 'skip_dir' configuration and negating the requirement to perform a --resync.

To use this option, you must run the application manually in the following manner:

onedrive --sync --single-directory '<directory_to_sync>' --force-sync <add any other options needed or required>

When using --force-sync, you'll encounter the following warning and advice:

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

Using --force-sync will reconfigure the application to use defaults. This may have unknown future impacts.
By proceeding with this option, you accept any impacts, including potential data loss resulting from using --force-sync.

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

To proceed with --force-sync, you must type 'y' or 'Y' to allow the application to continue.

When running onedrive, all actions can be logged to a separate log file. This can be enabled by using the --enable-logging flag or by adding enable_logging = "true" to your 'config' file.

By default, log files will be written to /var/log/onedrive/ and will be in the format of %username%.onedrive.log, where %username% represents the user who ran the client to allow easy sorting of user to client activity log.

ERROR: Unable to access /var/log/onedrive
ERROR: Please manually create '/var/log/onedrive' and set appropriate permissions to allow write access
ERROR: The requested client activity log will instead be located in your user's home directory

On many systems, ensuring that the log directory exists can be achieved by performing the following:

sudo mkdir /var/log/onedrive
sudo chown root:users /var/log/onedrive
sudo chmod 0775 /var/log/onedrive

Additionally, you need to ensure that your user account is part of the 'users' group:

cat /etc/group | grep users

If your user is not part of this group, then you need to add your user to this group:

sudo usermod -a -G users <your-user-name>

If you need to make a group modification, you will need to 'logout' of all sessions / SSH sessions to log in again to have the new group access applied.

If the client is unable to write the client activity log, the following error message will be printed:

ERROR: Unable to write the activity log to /var/log/onedrive/%username%.onedrive.log
ERROR: Please set appropriate permissions to allow write access to the logging directory for your user account
ERROR: The requested client activity log will instead be located in your user's home directory

If you receive this error message, you will need to diagnose why your system cannot write to the specified file location.

An example of a client activity log for the command onedrive --sync --enable-logging is below:

2023-Sep-27 08:16:00.1128806    Configuring Global Azure AD Endpoints
2023-Sep-27 08:16:00.1160620    Sync Engine Initialised with new Onedrive API instance
2023-Sep-27 08:16:00.5227122    All application operations will be performed in: /home/user/OneDrive
2023-Sep-27 08:16:00.5227977    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:16:00.7780979    Processing changes and items received from Microsoft OneDrive ...
2023-Sep-27 08:16:00.7781548    Performing a database consistency and integrity check on locally stored data ... 
2023-Sep-27 08:16:00.7785889    Scanning the local file system '~/OneDrive' for new data to upload ...
2023-Sep-27 08:16:00.7813710    Performing a final true-up scan of online data from Microsoft OneDrive
2023-Sep-27 08:16:00.7814668    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:16:01.0141776    Processing changes and items received from Microsoft OneDrive ...
2023-Sep-27 08:16:01.0142454    Sync with Microsoft OneDrive is complete

An example of a client activity log for the command onedrive --sync --verbose --enable-logging is below:

2023-Sep-27 08:20:05.4600464    Checking Application Version ...
2023-Sep-27 08:20:05.5235017    Attempting to initialise the OneDrive API ...
2023-Sep-27 08:20:05.5237207    Configuring Global Azure AD Endpoints
2023-Sep-27 08:20:05.5238087    The OneDrive API was initialised successfully
2023-Sep-27 08:20:05.5238536    Opening the item database ...
2023-Sep-27 08:20:05.5270612    Sync Engine Initialised with new Onedrive API instance
2023-Sep-27 08:20:05.9226535    Application version:  vX.Y.Z-A-bcdefghi
2023-Sep-27 08:20:05.9227079    Account Type:         <account-type>
2023-Sep-27 08:20:05.9227360    Default Drive ID:     <redacted>
2023-Sep-27 08:20:05.9227550    Default Root ID:      <redacted>
2023-Sep-27 08:20:05.9227862    Remaining Free Space: <space-available>
2023-Sep-27 08:20:05.9228296    All application operations will be performed in: /home/user/OneDrive
2023-Sep-27 08:20:05.9228989    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:20:06.2076569    Performing a database consistency and integrity check on locally stored data ... 
2023-Sep-27 08:20:06.2077121    Processing DB entries for this Drive ID: <redacted>
2023-Sep-27 08:20:06.2078408    Processing ~/OneDrive
2023-Sep-27 08:20:06.2078739    The directory has not changed
2023-Sep-27 08:20:06.2079783    Processing Attachments
2023-Sep-27 08:20:06.2080071    The directory has not changed
2023-Sep-27 08:20:06.2081585    Processing Attachments/file.docx
2023-Sep-27 08:20:06.2082079    The file has not changed
2023-Sep-27 08:20:06.2082760    Processing Documents
2023-Sep-27 08:20:06.2083225    The directory has not changed
2023-Sep-27 08:20:06.2084284    Processing Documents/file.log
2023-Sep-27 08:20:06.2084886    The file has not changed
2023-Sep-27 08:20:06.2085150    Scanning the local file system '~/OneDrive' for new data to upload ...
2023-Sep-27 08:20:06.2087133    Skipping item - excluded by sync_list config: ./random_25k_files
2023-Sep-27 08:20:06.2116235    Performing a final true-up scan of online data from Microsoft OneDrive
2023-Sep-27 08:20:06.2117190    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:20:06.5049743    Sync with Microsoft OneDrive is complete

Despite application logging being enabled as early as possible, the following log entries will be missing from the client activity log when compared to console output:

No user configuration file:

No user or system config file found, using application defaults
Using 'user' configuration path for application state data: /home/user/.config/onedrive
Using the following path to store the runtime application log: /var/log/onedrive

User configuration file:

Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
Using 'user' configuration path for application state data: /home/user/.config/onedrive
Using the following path to store the runtime application log: /var/log/onedrive

To enable GUI notifications, you must compile the application with GUI Notification Support. Refer to GUI Notification Support for details. Once compiled, GUI notifications will work by default in the display manager session under the following conditions:

• A D-Bus message bus daemon must be running.
• The environment variables XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS must be set.

Without these conditions met, GUI notifications will not function even if the support is compiled in.

Once these conditions have been met, the following application events will trigger a GUI notification within the display manager session by default:

• Aborting a sync if .nosync file is found
• Skipping a particular item due to an invalid name
• Skipping a particular item due to an invalid symbolic link
• Skipping a particular item due to an invalid UTF sequence
• Skipping a particular item due to an invalid character encoding sequence
• Cannot create remote directory
• Cannot upload file changes (free space issue, breaches maximum allowed size, breaches maximum OneDrive Account path length)
• Cannot delete remote file / folder
• Cannot move remote file / folder
• When a re-authentication is required
• When a new client version is available
• Files that fail to upload
• Files that fail to download

Additionally, GUI notifications can also be sent for the following activities:

• Successful file download
• Successful file upload
• Successful deletion locally (files and folders)
• Successful deletion online (files and folders)

To enable these specific notifications, add the following to your 'config' file:

notify_file_actions = "true"

If you change your Microsoft OneDrive Account Password, the client will no longer be authorised to sync, and will generate the following error upon next application run:

AADSTS50173: The provided grant has expired due to it being revoked, a fresh auth token is needed. The user might have changed or reset their password. The grant was issued on '<date-and-timestamp>' and the TokensValidFrom date (before which tokens are not valid) for this user is '<date-and-timestamp>'.

ERROR: You will need to issue a --reauth and re-authorise this client to obtain a fresh auth token.

To re-authorise the client, follow the steps below:

1. If running the client as a system service (init.d or systemd), stop the applicable system service
2. Run the command onedrive --reauth. This will clean up the previous authorisation, and will prompt you to re-authorise the client as per initial configuration. Please note, if you are using --confdir as part of your application runtime configuration, you must include this when telling the client to re-authenticate.
3. Restart the client if running as a system service or perform the standalone sync operation again

The application will now sync with OneDrive with the new credentials.

When the client has finished syncing without errors, the following will be displayed:

Sync with Microsoft OneDrive is complete

If any items failed to sync, the following will be displayed:

Sync with Microsoft OneDrive has completed, however there are items that failed to sync.

A file list of failed upload or download items will also be listed to allow you to determine your next steps.

In order to fix the upload or download failures, you may need to:

• Review the application output to determine what happened
• Re-try your command utilising a resync to ensure your system is correctly synced with your Microsoft OneDrive Account

Configuration is determined by three layers, and applied in the following order:

• Application default values
• Values that are set in the configuration file
• Values that are passed in via the command line at application runtime. These values will override any configuration file set value.

The default application values provide a reasonable operational default, and additional configuration is entirely optional.

If you want to change the application defaults, you can download a copy of the config file into your application configuration directory. Valid default directories for the config file are:

• ~/.config/onedrive
• /etc/onedrive

mkdir -p ~/.config/onedrive
wget https://raw.githubusercontent.com/abraunegg/onedrive/master/config -O ~/.config/onedrive/config

For full configuration options and CLI switches, please refer to application-config-options.md

By default, the location where your Microsoft OneDrive data is stored, is within your Home Directory under a directory called 'OneDrive'. This replicates as close as possible where the Microsoft Windows OneDrive client stores data.

To change this location, the application configuration option 'sync_dir' is used to specify a new local directory where your Microsoft OneDrive data should be stored.

The following are the application default permissions for any new directory or file that is created locally when downloaded from Microsoft OneDrive:

• Directories: 700 - This provides the following permissions: drwx------
• Files: 600 - This provides the following permissions: -rw-------

These default permissions align to the security principal of 'least privilege' so that only you should have access to your data that you download from Microsoft OneDrive.

To alter these default permissions, you can adjust the values of two configuration options as follows. You can also use the Unix Permissions Calculator to help you determine the necessary new permissions.

sync_dir_permissions = "700"
sync_file_permissions = "600"

The system manages downloads and uploads using a multi-threaded approach. Specifically, the application utilises by default 8 threads (a maximum of 16 can be configured) for these processes. This thread count is preset and cannot be modified by users. This design ensures efficient handling of data transfers.

There are two methods to achieve this:

• Employ the '--single-directory' option to only sync this specific path
• Employ 'sync_list' as part of your 'config' file to configure what files and directories to sync, and what should be excluded

There are two methods to achieve this:

• Employ 'skip_file' as part of your 'config' file to configure what files to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded

There are three methods available to 'skip' a directory from the sync process:

• Employ 'skip_dir' as part of your 'config' file to configure what directories to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded
• Employ 'check_nosync' as part of your 'config' file and a '.nosync' empty file within the directory to exclude to skip that directory

There are three methods to achieve this:

• Employ 'skip_file' or 'skip_dir' to configure what files or folders to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded
• Employ 'skip_dotfiles' as part of your 'config' file to skip any dot file (for example: .Trash-1000 or .xdg-volume-info) from syncing to OneDrive

Use skip_size = "value" as part of your 'config' file where files larger than this size (in MB) will be skipped.

To optimise Internet bandwidth usage during upload and download processes, include the 'rate_limit' setting in your configuration file. This setting controls the bandwidth allocated to each thread.

By default, 'rate_limit' is set to '0', indicating that the application will utilise the maximum available bandwidth across all threads.

To check the current 'rate_limit' value, use the --display-config command.

By default, the application will reserve 50MB of disk space to prevent your filesystem from running out of disk space.

This default value can be modified by adding the 'space_reservation' configuration option and the applicable value as part of your 'config' file.

You can review the value being used when using --display-config.

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.

As such, there are only two methods to support symbolic links with this client:

1. Follow the Linux symbolic link and upload whatever the local symbolic link is pointing to to Microsoft OneDrive. This is the default behaviour.
2. Skip symbolic links by configuring the application to do so. When skipping, no data, no link, no reference is uploaded to OneDrive.

Use 'skip_symlinks' as part of your 'config' file to configure the skipping of all symbolic links while syncing.

Folders shared with you can be synchronised by adding them to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the folder you want to synchronise, and then click on "Add to my OneDrive".

Folders shared with you can be synchronised by adding them to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the folder you want to synchronise, and then click on "Add to my OneDrive".

Files shared with you can be synchronised using two methods:

1. Add a shortcut link to the file to your OneDrive folder online
2. Sync the actual file locally using the configuration option to sync OneDrive Business Shared Files.

Refer to business-shared-items.md for further details.

There are two methods to achieve this:

• SharePoint library can be directly added to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the SharePoint Library you want to synchronise, and then click on "Add to my OneDrive".
• Configure a separate application instance to only synchronise that specific SharePoint Library. Refer to sharepoint-libraries.md for configuration assistance.

In certain situations, you might want to generate a shareable file link and provide this link to other users for accessing a specific file.

To accomplish this, employ the following command:

onedrive --create-share-link <path/to/file>

To make the shareable link a read-write link, execute the following command:

onedrive --create-share-link <path/to/file> --with-editing-perms

You need to set up separate instances of the application configuration for each account.

Refer to advanced-usage.md for guidance on configuration.

For each SharePoint Library, configure a separate instance of the application configuration.

Refer to advanced-usage.md for configuration instructions.

Refer to webhooks.md for configuration instructions.

There are a few ways to employ onedrive as a service:

• via init.d
• via systemd
• via runit

chkconfig onedrive on
service onedrive start

To view the logs, execute:

tail -f /var/log/onedrive/<username>.onedrive.log

To alter the 'user' under which the client operates (typically root by default), manually modify the init.d service file and adjust daemon --user root onedrive_service.sh to match the correct user.

Initially, switch to the root user with su - root, then activate the systemd service:

systemctl --user enable onedrive
systemctl --user start onedrive

To monitor the service's status, use the following:

systemctl --user status onedrive.service

To observe the systemd application logs, use:

journalctl --user-unit=onedrive -f

Failed to connect to bus: No such file or directory

export XDG_RUNTIME_DIR="/run/user/$UID"
export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"

To examine the systemd application logs, run:

journalctl --unit=onedrive@<username> -f

systemctl enable onedrive
systemctl start onedrive

To view the systemd application logs, execute:

journalctl --unit=onedrive -f

In some instances, it is preferable to run the OneDrive client as a service without the 'root' user. Follow the instructions below to configure the service for your regular user login.

1. As the user who will run the service, launch the application in standalone mode, authorize it for use, and verify that synchronization is functioning as expected:

onedrive --sync --verbose

2. After validating the application for your user, switch to the 'root' user, where is your username from step 1 above.

systemctl enable onedrive@<username>.service
systemctl start onedrive@<username>.service

3. To check the service's status for the user, use the following:

systemctl status onedrive@<username>.service

To observe the systemd application logs, use:

journalctl --unit=onedrive@<username> -f

In some scenarios, you may want to receive GUI notifications when using the client as a non-root user. In this case, follow these steps:

1. Log in via the graphical UI as the user you want to enable the service for.
2. Disable any onedrive@ service files for your username, e.g.:

sudo systemctl stop [email protected]
sudo systemctl disable [email protected]

3. Enable the service as follows:

systemctl --user enable onedrive
systemctl --user start onedrive

To check the service's status for the user, use the following:

systemctl --user status onedrive.service

To view the systemd application logs, execute:

journalctl --user-unit=onedrive -f

1. Create the following folder if it doesn't already exist: /etc/sv/runsvdir-<username>

• where <username> is the USER targeted for the service
• e.g., # mkdir /etc/sv/runsvdir-nolan

2. Create a file called run under the previously created folder with executable permissions

   • # touch /etc/sv/runsvdir-<username>/run
   • # chmod 0755 /etc/sv/runsvdir-<username>/run

3. Edit the run file with the following contents (permissions needed):

#!/bin/sh
export USER="<username>"
export HOME="/home/<username>"

groups="$(id -Gn "${USER}" | tr ' ' ':')"
svdir="${HOME}/service"

exec chpst -u "${USER}:${groups}" runsvdir "${svdir}"

• Ensure you replace <username> with the USER set in step #1.

4. Enable the previously created folder as a service

• # ln -fs /etc/sv/runsvdir-<username> /var/service/

5. Create a subfolder in the USER's HOME directory to store the services (or symlinks)

   • $ mkdir ~/service

6. Create a subfolder specifically for OneDrive

• $ mkdir ~/service/onedrive/

7. Create a file called run under the previously created folder with executable permissions

   • $ touch ~/service/onedrive/run
   • $ chmod 0755 ~/service/onedrive/run

8. Append the following contents to the run file

#!/usr/bin/env sh
exec /usr/bin/onedrive --monitor

• In some scenarios, the path to the onedrive binary may vary. You can obtain it by running $ command -v onedrive.

9. Reboot to apply the changes

10. Check the status of user-defined services

• $ sv status ~/service/*

In some situations, it may be necessary for the systemd service to start without requiring your 'user' to log in.

To address this issue, you need to reconfigure your 'user' account so that the systemd services you've created launch without the need for you to log in to your system:

loginctl enable-linger <your_user_name>

If you have a requirement to run the client through a proxy, there are a couple of ways to achieve this:

Set proxy configuration in ~/.bashrc to allow the 'onedrive' application to use a specific proxy server:

# Set the HTTP proxy
export http_proxy="http://your.proxy.server:port"

# Set the HTTPS proxy
export https_proxy="http://your.proxy.server:port"

Once you've edited your ~/.bashrc file, run the following command to apply the changes:

source ~/.bashrc

If running as a systemd service, edit the applicable systemd service file to include the proxy configuration information:

[Unit]
Description=OneDrive Client for Linux
Documentation=https://github.com/abraunegg/onedrive
After=network-online.target
Wants=network-online.target

[Service]
........
Environment="HTTP_PROXY=http://your.proxy.server:port"
Environment="HTTPS_PROXY=http://your.proxy.server:port"
ExecStart=/usr/local/bin/onedrive --monitor
........

If SELinux is enforced and the sync folder is outside of the home folder, as long as there is no policy for cloud file service providers, label the file system folder to user_home_t.

sudo semanage fcontext -a -t user_home_t /path/to/onedriveSyncFolder
sudo restorecon -R -v /path/to/onedriveSyncFolder

To remove this change from SELinux and restore the default behaviour:

sudo semanage fcontext -d /path/to/onedriveSyncFolder
sudo restorecon -R -v /path/to/onedriveSyncFolder

Refer to advanced-usage.md for further details on the following topics:

• Configuring the client to use multiple OneDrive accounts / configurations
• Configuring the client to use multiple OneDrive accounts / configurations using Docker
• Configuring the client for use in dual-boot (Windows / Linux) situations
• Configuring the client for use when 'sync_dir' is a mounted directory
• Upload data from the local ~/OneDrive folder to a specific location on OneDrive

Below is a comprehensive list of all available configuration options for the OneDrive Client for Linux, as shown by the output of onedrive --help. These commands provide a range of options for synchronising, monitoring, and managing files between your local system and Microsoft's OneDrive cloud service.

The following configuration options are available:

onedrive - A client for the Microsoft OneDrive Cloud Service

  Usage:
    onedrive [options] --sync
      Do a one time synchronization
    onedrive [options] --monitor
      Monitor filesystem and sync regularly
    onedrive [options] --display-config
      Display the currently used configuration
    onedrive [options] --display-sync-status
      Query OneDrive service and report on pending changes
    onedrive -h | --help
      Show this help screen
    onedrive --version
      Show version

  Options:

  --auth-files ARG
      Perform authentication not via interactive dialog but via files read/writes to these files.
  --auth-response ARG
      Perform authentication not via interactive dialog but via providing the response url directly.
  --check-for-nomount
      Check for the presence of .nosync in the syncdir root. If found, do not perform sync.
  --check-for-nosync
      Check for the presence of .nosync in each directory. If found, skip directory from sync.
  --classify-as-big-delete ARG
      Number of children in a path that is locally removed which will be classified as a 'big data delete'
  --cleanup-local-files
      Cleanup additional local files when using --download-only. This will remove local data.
  --confdir ARG
      Set the directory used to store the configuration files
  --create-directory ARG
      Create a directory on OneDrive - no sync will be performed.
  --create-share-link ARG
      Create a shareable link for an existing file on OneDrive
  --debug-https
      Debug OneDrive HTTPS communication.
  --destination-directory ARG
      Destination directory for renamed or move on OneDrive - no sync will be performed.
  --disable-download-validation
      Disable download validation when downloading from OneDrive
  --disable-notifications
      Do not use desktop notifications in monitor mode.
  --disable-upload-validation
      Disable upload validation when uploading to OneDrive
  --display-config
      Display what options the client will use as currently configured - no sync will be performed.
  --display-quota
      Display the quota status of the client - no sync will be performed.
  --display-running-config
      Display what options the client has been configured to use on application startup.
  --display-sync-status
      Display the sync status of the client - no sync will be performed.
  --download-only
      Replicate the OneDrive online state locally, by only downloading changes from OneDrive. Do not upload local changes to OneDrive.
  --dry-run
      Perform a trial sync with no changes made
  --enable-logging
      Enable client activity to a separate log file
  --force
      Force the deletion of data when a 'big delete' is detected
  --force-http-11
      Force the use of HTTP 1.1 for all operations
  --force-sync
      Force a synchronization of a specific folder, only when using --sync --single-directory and ignore all non-default skip_dir and skip_file rules
  --get-O365-drive-id ARG
      Query and return the Office 365 Drive ID for a given Office 365 SharePoint Shared Library (DEPRECATED)
  --get-file-link ARG
      Display the file link of a synced file
  --get-sharepoint-drive-id ARG
      Query and return the Office 365 Drive ID for a given Office 365 SharePoint Shared Library
  --help -h
      This help information.
  --list-shared-items
      List OneDrive Business Shared Items
  --local-first
      Synchronize from the local directory source first, before downloading changes from OneDrive.
  --log-dir ARG
      Directory where logging output is saved to, needs to end with a slash.
  --logout
      Logout the current user
  --modified-by ARG
      Display the last modified by details of a given path
  --monitor -m
      Keep monitoring for local and remote changes
  --monitor-fullscan-frequency ARG
      Number of sync runs before performing a full local scan of the synced directory
  --monitor-interval ARG
      Number of seconds by which each sync operation is undertaken when idle under monitor mode.
  --monitor-log-frequency ARG
      Frequency of logging in monitor mode
  --no-remote-delete
      Do not delete local file 'deletes' from OneDrive when using --upload-only
  --print-access-token
      Print the access token, useful for debugging
  --reauth
      Reauthenticate the client with OneDrive
  --remove-directory ARG
      Remove a directory on OneDrive - no sync will be performed.
  --remove-source-files
      Remove source file after successful transfer to OneDrive when using --upload-only
  --resync
      Forget the last saved state, perform a full sync
  --resync-auth
      Approve the use of performing a --resync action
  --single-directory ARG
      Specify a single local directory within the OneDrive root to sync.
  --skip-dir ARG
      Skip any directories that match this pattern from syncing
  --skip-dir-strict-match
      When matching skip_dir directories, only match explicit matches
  --skip-dot-files
      Skip dot files and folders from syncing
  --skip-file ARG
      Skip any files that match this pattern from syncing
  --skip-size ARG
      Skip new files larger than this size (in MB)
  --skip-symlinks
      Skip syncing of symlinks
  --source-directory ARG
      Source directory to rename or move on OneDrive - no sync will be performed.
  --space-reservation ARG
      The amount of disk space to reserve (in MB) to avoid 100% disk space utilisation
  --sync -s
      Perform a synchronisation with Microsoft OneDrive
  --sync-root-files
      Sync all files in sync_dir root when using sync_list.
  --sync-shared-files
      Sync OneDrive Business Shared Files to the local filesystem
  --syncdir ARG
      Specify the local directory used for synchronisation to OneDrive
  --synchronize
      Perform a synchronisation with Microsoft OneDrive (DEPRECATED)
  --upload-only
      Replicate the locally configured sync_dir state to OneDrive, by only uploading local changes to OneDrive. Do not download changes from OneDrive.
  --verbose -v+
      Print more details, useful for debugging (repeat for extra debugging)
  --version
      Print the version and exit
  --with-editing-perms
      Create a read-write shareable link for an existing file on OneDrive when used with --create-share-link <file>

Refer to application-config-options.md for in-depth details on all application options.