onedrive Documentation

File: README.md Copy Chapter

OneDrive Client for Linux

A fully featured, free, and actively maintained Microsoft OneDrive client that seamlessly supports OneDrive Personal, OneDrive for Business, Microsoft 365 (formerly Office 365), and SharePoint document libraries.

Designed for maximum flexibility and reliability, this powerful and highly configurable client works across all major Linux distributions, FreeBSD and OpenBSD. It can also be deployed in containerised environments using Docker or Podman. Supporting both one-way and two-way synchronisation modes, the client provides secure and efficient file syncing with Microsoft OneDrive services — tailored to suit both desktop and server environments.

Project Background Copy Chapter

This project originated as a fork of the skilion client in early 2018, after a number of proposed improvements and bug fixes — including Pull Requests #82 and #314 — were not merged and development activity of the skilion client had largely stalled. While it’s unclear whether the original developer was unavailable or had stepped away from the project - bug reports and feature requests remained unanswered for extended periods. In 2020, the original developer (skilion) confirmed they had no intention of maintaining or supporting their work (reference).

The original skilion repository was formally archived and made read-only on GitHub in December 2024. While still publicly accessible as a historical reference, an archived repository is no longer maintained, cannot accept contributions, and reflects a frozen snapshot of the codebase. The last code change to the skilion client was merged in November 2021; however, active development had slowed significantly well before then. As such, the skilion client should no longer be considered current or supported — particularly given the major API changes and evolving Microsoft OneDrive platform requirements since that time.

Under the terms of the GNU General Public License (GPL), forking and continuing development of open source software is fully permitted — provided that derivative works retain the same license. This client complies with the original GPLv3 licensing, ensuring the same freedoms granted by the original project remain intact.

Since forking in early 2018, this client has evolved into a clean re-imagining of the original codebase, resolving long-standing bugs and adding extensive new functionality to better support both personal and enterprise use cases to interact with Microsoft OneDrive from Linux, FreeBSD and OpenBSD platforms.

Features Copy Chapter

Broad Microsoft OneDrive Compatibility Copy Section

• Works with OneDrive Personal, OneDrive for Business, and Microsoft SharePoint Libraries.
• Full support for shared folders and files across both Personal and Business accounts.
• Supports single-tenant and multi-tenant Microsoft Entra ID environments.
• Compatible with national cloud deployments:
  • Microsoft Cloud for US Government
  • Microsoft Cloud Germany
  • Azure/Office 365 operated by VNET in China

Flexible Synchronisation Modes Copy Section

• Bi-directional sync (default) - keeps local and remote data fully aligned.
• Upload-only mode - only uploads local changes; does not download remote changes.
• Download-only mode - only downloads remote changes; does not upload local changes.
• Dry-run mode - test configuration changes safely without modifying files.
• Safe conflict handling minimises data loss by creating local backups whenever this is determined to be the safest conflict-resolution strategy.

Client-Side Filtering & Granular Sync Control Copy Section

• Comprehensive rules-based client-side filtering (inclusions, exclusions, wildcard *, globbing **).
• Filter specific files, folders, or patterns to tailor precisely what is synced with Microsoft OneDrive.
• Efficient cached sync state for fast decision-making during large or complex sync sets.

Real-Time Monitoring & Online Change Detection Copy Section

• Near real-time processing of cloud-side changes using native WebSocket support.
• Webhook support for environments where WebSockets are unsuitable (manual setup).
• Real-time local change monitoring via inotify.

Data Safety, Recovery & Integrity Protection Copy Section

• Implements the FreeDesktop.org Trash specification, enabling recovery of items deleted locally due to online deletion.
• Strong safeguards to prevent accidental remote deletion or overwrite after configuration changes.
• Interruption-tolerant uploads and downloads, automatically resuming transfers.
• Integrity validation for every file transferred.

Modern Authentication Support Copy Section

• Standard OAuth2 Native Client Authorisation Flow (default), supporting browser-based login, multi-factor authentication (MFA), and modern Microsoft account security requirements.
• OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts, ideal for headless systems, servers, and terminal-only environments.
• Intune Single Sign-On (SSO) using the Microsoft Identity Device Broker (IDB) via D-Bus, enabling seamless enterprise authentication without manual credential entry.

Performance, Efficiency & Resource Management Copy Section

• Multi-threaded file transfers for significantly improved sync speeds.
• Bandwidth rate limiting to control network consumption.
• Highly efficient processing with state caching, reducing API traffic and improving performance.

Desktop Integration & User Experience Copy Section

• libnotify desktop notifications for sync events, warnings, and errors.
• Registers the OneDrive folder as a sidebar location in supported file managers, complete with a distinctive icon.
• Works seamlessly in GUI and headless/server environments. A GUI is only required for Intune SSO, notifications, and sidebar integration; all other features function without graphical support.

What's missing Copy Chapter

• Ability to encrypt/decrypt files on-the-fly when uploading/downloading files from OneDrive
• Support for Windows 'On-Demand' functionality so file is only downloaded when accessed locally

External Enhancements Copy Chapter

• A GUI for configuration management: OneDrive Client for Linux GUI
• Colorful log output terminal modification: OneDrive Client for Linux Colorful log Output
• System Tray Icon: OneDrive Client for Linux System Tray Icon

Frequently Asked Questions Copy Chapter

Refer to Frequently Asked Questions

Have a question Copy Chapter

If you have a question or need something clarified, please raise a new discussion post here

Supported Application Version Copy Chapter

Support is only provided for the current application release version or newer 'master' branch versions.

The current release version is:

To check your version, run: onedrive --version. Ensure you are using the current release or compile the latest version from the master branch if needed.

If you are using an older version, you must upgrade to the current release or newer to receive support.

Documentation and Configuration Assistance Copy Chapter

OneDrive Client for Linux includes a rich set of documentation covering installation, configuration options, advanced usage, and integrations. These resources are designed to help new users get started quickly and to give experienced users full control over advanced behaviour. If you are changing configuration, running in production, or using Business/SharePoint features, you should be reading these documents. All documentation is maintained in the docs/ directory of this repository.

Getting Started Copy Section

Installation

Learn how to install the client on various systems — from distribution packages to building from source. Please read the Install Guide

Basic Usage & Configuration

Covers initial authentication, default settings, basic operational instructions, frequently asked 'how to' questions, and how to tailor the application configuration. Please read the Usage Guide

Advanced Configuration Copy Section

Application Configuration Options

Full reference for every config option (with descriptions, defaults, and examples) to customise sync behaviour precisely. Please read the Application Configuration Options Guide

Advanced Usage

Tips for creating multiple config profiles, custom sync rules, daemon setups, selective sync, dual-booting with Microsoft Windows and more. Please read the Advanced Usage Guide

Special Use Cases Copy Section

Business Shared Items

Configuring sync for OneDrive Business shared items (files and folders). Please read the Business Shared Items Guide

SharePoint & Office 365 Libraries

Instructions for syncing SharePoint document libraries (Business or Education tenants). Please read the SharePoint Library Guide

National Cloud support

Instructions for environments like Microsoft Cloud Germany or US Government cloud endpoints. Please read the National Cloud Deployment Guide

Container Support Copy Section

Docker

How to run the OneDrive client in a Docker container. Please read the Docker Guide

Podman

How to run the OneDrive client with Podman. Please read the Podman Guide

Basic Troubleshooting Steps Copy Chapter

If you encounter any issues running the application, please follow these steps before raising a bug report:

1. Check the application version
   Run onedrive --version to confirm which version you are using.

   • Ensure you are running the latest release.
   • If you are already on the latest release but still experiencing issues, manually build the client from the master branch to test against the very latest code. This includes fixes for bugs discovered since the last tagged release.
   • If you are using Docker or Podman, ensure you are using the 'edge' Docker Tag. Do not use the 'latest' Docker Tag.

2. Run in verbose mode
   Use the --verbose option to provide greater clarity and detailed logging about the issue you are facing.

   If you are using Docker or Podman, use the ONEDRIVE_VERBOSE environment variable to increase logging verbosity.

3. Test with IPv4 only
   Configure the application to use IPv4 network connectivity only, then retest. See the 'ip_protocol_version' option documentation for assistance.

4. Test with HTTP/1.1 and IPv4
   Configure the application to use HTTP/1.1 over IPv4 only, then retest. See the 'force_http_11' option documentation for assistance.

5. Verify cURL and libcurl versions
   If the above steps do not resolve your issue, upgrade both curl and libcurl to the latest versions provided by the curl developers.

   • See Compatibility with curl for details on curl bugs that impact this client.
   • Refer to the official cURL Releases page for version information.

6. Perform a --resync
   In some cases, a --resync is needed to ensure your data is correctly synced. This option instructs the client to delete its local state database and fully rebuild it from the current online OneDrive contents. This is a powerful recovery and re-alignment action that should be used sparingly and with care.

   • See Performing a --resync for further details.

7. Open a new issue
   If the problem persists after completing the steps above, proceed to Reporting an Issue or Bug below and open a new issue with the requested details and logs.

Reporting an Issue or Bug Copy Chapter

[!IMPORTANT]
Please ensure the problem is a software bug. For installation issues, distribution package/version questions, or dependency problems, start a Discussion instead of filing a bug report.

If you encounter a bug, you can report it on GitHub. Before opening a new issue report:

1. Complete the Basic Troubleshooting Steps
   Confirm you’ve run through all steps in the section above.

2. Search existing issues
   Check both Open and Closed issues for a similar problem to avoid duplicates.

3. Use the issue template
   Open a new bug report using the issue template and fill in all fields. Complete detail helps us reproduce your environment and replicate the issue.

4. Generate a debug log
   Follow this process to create a debug log.

   • If you are concerned about personal or business sensitive data in the debug log, you may:
     • Create a new OneDrive account, configure the client to use it, use dummy data to simulate your environment, and reproduce the issue; or
     • Provide an NDA or confidentiality agreement for signature prior to sharing sensitive logs.

5. Share the debug log securely

   • Do not post debug logs publicly. Debug logs can include sensitive details (file paths, filenames, API endpoints, environment info, etc.).
   • Send the log via email to [email protected] using a trusted email account.
   • Archive and password-protect the log before sending (e.g. .zip with AES or .7z):
     • Example (zip with password): zip -e onedrive-debug.zip onedrive-debug.log
     • Example (7z with password): 7z a -p onedrive-debug.7z onedrive-debug.log
   • Send the password out-of-band (OOB) — not in the same email as the archive. Email [email protected] to arrange an OOB method (e.g. separate email thread, phone/SMS, or agreed channel).
   • If you require an NDA, attach your NDA or confidentiality agreement to your email. It will be reviewed and signed prior to exchanging sensitive data.

What to include in your bug report Copy Section

When raising a new bug report, please include all details requested in the issue template, such as:

• A clear description of the problem and how to reproduce it
• Your operating system and installation method
• OneDrive account type and client version
• Application configuration and cURL version
• Sync directory location, system mount points, and partition types
• A full debug log, shared securely as described above

Providing complete information makes it much easier to understand, reproduce, and resolve your issue quickly.

[!NOTE]
Submitting a bug report starts a collaboration. To help us help you, please:

• Stay available to answer questions or provide clarifications if needed
• Test and confirm fixes in your own environment when a pull request (PR) is created for your issue

[!TIP]
Reports with missing details are much harder to investigate. Sharing as much as you can up front gives the best chance of a fast and accurate fix.

Known issues Copy Chapter

Lists common limitations, known problems, diagnostics, and workarounds. Please read the Known Issues Advice

File: Readme.md Copy Chapter

OneDrive Client for Linux

A fully featured, free, and actively maintained Microsoft OneDrive client that seamlessly supports OneDrive Personal, OneDrive for Business, Microsoft 365 (formerly Office 365), and SharePoint document libraries.

Designed for maximum flexibility and reliability, this powerful and highly configurable client works across all major Linux distributions, FreeBSD and OpenBSD. It can also be deployed in containerised environments using Docker or Podman. Supporting both one-way and two-way synchronisation modes, the client provides secure and efficient file syncing with Microsoft OneDrive services — tailored to suit both desktop and server environments.

Project Background Copy Chapter

This project originated as a fork of the skilion client in early 2018, after a number of proposed improvements and bug fixes — including Pull Requests #82 and #314 — were not merged and development activity of the skilion client had largely stalled. While it’s unclear whether the original developer was unavailable or had stepped away from the project - bug reports and feature requests remained unanswered for extended periods. In 2020, the original developer (skilion) confirmed they had no intention of maintaining or supporting their work (reference).

The original skilion repository was formally archived and made read-only on GitHub in December 2024. While still publicly accessible as a historical reference, an archived repository is no longer maintained, cannot accept contributions, and reflects a frozen snapshot of the codebase. The last code change to the skilion client was merged in November 2021; however, active development had slowed significantly well before then. As such, the skilion client should no longer be considered current or supported — particularly given the major API changes and evolving Microsoft OneDrive platform requirements since that time.

Under the terms of the GNU General Public License (GPL), forking and continuing development of open source software is fully permitted — provided that derivative works retain the same license. This client complies with the original GPLv3 licensing, ensuring the same freedoms granted by the original project remain intact.

Since forking in early 2018, this client has evolved into a clean re-imagining of the original codebase, resolving long-standing bugs and adding extensive new functionality to better support both personal and enterprise use cases to interact with Microsoft OneDrive from Linux, FreeBSD and OpenBSD platforms.

Features Copy Chapter

Broad Microsoft OneDrive Compatibility Copy Section

• Works with OneDrive Personal, OneDrive for Business, and Microsoft SharePoint Libraries.
• Full support for shared folders and files across both Personal and Business accounts.
• Supports single-tenant and multi-tenant Microsoft Entra ID environments.
• Compatible with national cloud deployments:
  • Microsoft Cloud for US Government
  • Microsoft Cloud Germany
  • Azure/Office 365 operated by VNET in China

Flexible Synchronisation Modes Copy Section

• Bi-directional sync (default) - keeps local and remote data fully aligned.
• Upload-only mode - only uploads local changes; does not download remote changes.
• Download-only mode - only downloads remote changes; does not upload local changes.
• Dry-run mode - test configuration changes safely without modifying files.
• Safe conflict handling minimises data loss by creating local backups whenever this is determined to be the safest conflict-resolution strategy.

Client-Side Filtering & Granular Sync Control Copy Section

• Comprehensive rules-based client-side filtering (inclusions, exclusions, wildcard *, globbing **).
• Filter specific files, folders, or patterns to tailor precisely what is synced with Microsoft OneDrive.
• Efficient cached sync state for fast decision-making during large or complex sync sets.

Real-Time Monitoring & Online Change Detection Copy Section

• Near real-time processing of cloud-side changes using native WebSocket support.
• Webhook support for environments where WebSockets are unsuitable (manual setup).
• Real-time local change monitoring via inotify.

Data Safety, Recovery & Integrity Protection Copy Section

• Implements the FreeDesktop.org Trash specification, enabling recovery of items deleted locally due to online deletion.
• Strong safeguards to prevent accidental remote deletion or overwrite after configuration changes.
• Interruption-tolerant uploads and downloads, automatically resuming transfers.
• Integrity validation for every file transferred.

Modern Authentication Support Copy Section

• Standard OAuth2 Native Client Authorisation Flow (default), supporting browser-based login, multi-factor authentication (MFA), and modern Microsoft account security requirements.
• OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts, ideal for headless systems, servers, and terminal-only environments.
• Intune Single Sign-On (SSO) using the Microsoft Identity Device Broker (IDB) via D-Bus, enabling seamless enterprise authentication without manual credential entry.

Performance, Efficiency & Resource Management Copy Section

• Multi-threaded file transfers for significantly improved sync speeds.
• Bandwidth rate limiting to control network consumption.
• Highly efficient processing with state caching, reducing API traffic and improving performance.

Desktop Integration & User Experience Copy Section

• libnotify desktop notifications for sync events, warnings, and errors.
• Registers the OneDrive folder as a sidebar location in supported file managers, complete with a distinctive icon.
• Works seamlessly in GUI and headless/server environments. A GUI is only required for Intune SSO, notifications, and sidebar integration; all other features function without graphical support.

What's missing Copy Chapter

• Ability to encrypt/decrypt files on-the-fly when uploading/downloading files from OneDrive
• Support for Windows 'On-Demand' functionality so file is only downloaded when accessed locally

External Enhancements Copy Chapter

• A GUI for configuration management: OneDrive Client for Linux GUI
• Colorful log output terminal modification: OneDrive Client for Linux Colorful log Output
• System Tray Icon: OneDrive Client for Linux System Tray Icon

Frequently Asked Questions Copy Chapter

Refer to Frequently Asked Questions

Have a question Copy Chapter

If you have a question or need something clarified, please raise a new discussion post here

Supported Application Version Copy Chapter

Support is only provided for the current application release version or newer 'master' branch versions.

The current release version is:

To check your version, run: onedrive --version. Ensure you are using the current release or compile the latest version from the master branch if needed.

If you are using an older version, you must upgrade to the current release or newer to receive support.

Documentation and Configuration Assistance Copy Chapter

OneDrive Client for Linux includes a rich set of documentation covering installation, configuration options, advanced usage, and integrations. These resources are designed to help new users get started quickly and to give experienced users full control over advanced behaviour. If you are changing configuration, running in production, or using Business/SharePoint features, you should be reading these documents. All documentation is maintained in the docs/ directory of this repository.

Getting Started Copy Section

Installation

Learn how to install the client on various systems — from distribution packages to building from source. Please read the Install Guide

Basic Usage & Configuration

Covers initial authentication, default settings, basic operational instructions, frequently asked 'how to' questions, and how to tailor the application configuration. Please read the Usage Guide

Advanced Configuration Copy Section

Application Configuration Options

Full reference for every config option (with descriptions, defaults, and examples) to customise sync behaviour precisely. Please read the Application Configuration Options Guide

Advanced Usage

Tips for creating multiple config profiles, custom sync rules, daemon setups, selective sync, dual-booting with Microsoft Windows and more. Please read the Advanced Usage Guide

Special Use Cases Copy Section

Business Shared Items

Configuring sync for OneDrive Business shared items (files and folders). Please read the Business Shared Items Guide

SharePoint & Office 365 Libraries

Instructions for syncing SharePoint document libraries (Business or Education tenants). Please read the SharePoint Library Guide

National Cloud support

Instructions for environments like Microsoft Cloud Germany or US Government cloud endpoints. Please read the National Cloud Deployment Guide

Container Support Copy Section

Docker

How to run the OneDrive client in a Docker container. Please read the Docker Guide

Podman

How to run the OneDrive client with Podman. Please read the Podman Guide

Basic Troubleshooting Steps Copy Chapter

If you encounter any issues running the application, please follow these steps before raising a bug report:

1. Check the application version
   Run onedrive --version to confirm which version you are using.

   • Ensure you are running the latest release.
   • If you are already on the latest release but still experiencing issues, manually build the client from the master branch to test against the very latest code. This includes fixes for bugs discovered since the last tagged release.
   • If you are using Docker or Podman, ensure you are using the 'edge' Docker Tag. Do not use the 'latest' Docker Tag.

2. Run in verbose mode
   Use the --verbose option to provide greater clarity and detailed logging about the issue you are facing.

   If you are using Docker or Podman, use the ONEDRIVE_VERBOSE environment variable to increase logging verbosity.

3. Test with IPv4 only
   Configure the application to use IPv4 network connectivity only, then retest. See the 'ip_protocol_version' option documentation for assistance.

4. Test with HTTP/1.1 and IPv4
   Configure the application to use HTTP/1.1 over IPv4 only, then retest. See the 'force_http_11' option documentation for assistance.

5. Verify cURL and libcurl versions
   If the above steps do not resolve your issue, upgrade both curl and libcurl to the latest versions provided by the curl developers.

   • See Compatibility with curl for details on curl bugs that impact this client.
   • Refer to the official cURL Releases page for version information.

6. Perform a --resync
   In some cases, a --resync is needed to ensure your data is correctly synced. This option instructs the client to delete its local state database and fully rebuild it from the current online OneDrive contents. This is a powerful recovery and re-alignment action that should be used sparingly and with care.

   • See Performing a --resync for further details.

7. Open a new issue
   If the problem persists after completing the steps above, proceed to Reporting an Issue or Bug below and open a new issue with the requested details and logs.

Reporting an Issue or Bug Copy Chapter

[!IMPORTANT]
Please ensure the problem is a software bug. For installation issues, distribution package/version questions, or dependency problems, start a Discussion instead of filing a bug report.

If you encounter a bug, you can report it on GitHub. Before opening a new issue report:

1. Complete the Basic Troubleshooting Steps
   Confirm you’ve run through all steps in the section above.

2. Search existing issues
   Check both Open and Closed issues for a similar problem to avoid duplicates.

3. Use the issue template
   Open a new bug report using the issue template and fill in all fields. Complete detail helps us reproduce your environment and replicate the issue.

4. Generate a debug log
   Follow this process to create a debug log.

   • If you are concerned about personal or business sensitive data in the debug log, you may:
     • Create a new OneDrive account, configure the client to use it, use dummy data to simulate your environment, and reproduce the issue; or
     • Provide an NDA or confidentiality agreement for signature prior to sharing sensitive logs.

5. Share the debug log securely

   • Do not post debug logs publicly. Debug logs can include sensitive details (file paths, filenames, API endpoints, environment info, etc.).
   • Send the log via email to [email protected] using a trusted email account.
   • Archive and password-protect the log before sending (e.g. .zip with AES or .7z):
     • Example (zip with password): zip -e onedrive-debug.zip onedrive-debug.log
     • Example (7z with password): 7z a -p onedrive-debug.7z onedrive-debug.log
   • Send the password out-of-band (OOB) — not in the same email as the archive. Email [email protected] to arrange an OOB method (e.g. separate email thread, phone/SMS, or agreed channel).
   • If you require an NDA, attach your NDA or confidentiality agreement to your email. It will be reviewed and signed prior to exchanging sensitive data.

What to include in your bug report Copy Section

When raising a new bug report, please include all details requested in the issue template, such as:

• A clear description of the problem and how to reproduce it
• Your operating system and installation method
• OneDrive account type and client version
• Application configuration and cURL version
• Sync directory location, system mount points, and partition types
• A full debug log, shared securely as described above

Providing complete information makes it much easier to understand, reproduce, and resolve your issue quickly.

[!NOTE]
Submitting a bug report starts a collaboration. To help us help you, please:

• Stay available to answer questions or provide clarifications if needed
• Test and confirm fixes in your own environment when a pull request (PR) is created for your issue

[!TIP]
Reports with missing details are much harder to investigate. Sharing as much as you can up front gives the best chance of a fast and accurate fix.

Known issues Copy Chapter

Lists common limitations, known problems, diagnostics, and workarounds. Please read the Known Issues Advice

File: readme.md Copy Chapter

OneDrive Client for Linux

A fully featured, free, and actively maintained Microsoft OneDrive client that seamlessly supports OneDrive Personal, OneDrive for Business, Microsoft 365 (formerly Office 365), and SharePoint document libraries.

Designed for maximum flexibility and reliability, this powerful and highly configurable client works across all major Linux distributions, FreeBSD and OpenBSD. It can also be deployed in containerised environments using Docker or Podman. Supporting both one-way and two-way synchronisation modes, the client provides secure and efficient file syncing with Microsoft OneDrive services — tailored to suit both desktop and server environments.

Project Background Copy Chapter

This project originated as a fork of the skilion client in early 2018, after a number of proposed improvements and bug fixes — including Pull Requests #82 and #314 — were not merged and development activity of the skilion client had largely stalled. While it’s unclear whether the original developer was unavailable or had stepped away from the project - bug reports and feature requests remained unanswered for extended periods. In 2020, the original developer (skilion) confirmed they had no intention of maintaining or supporting their work (reference).

The original skilion repository was formally archived and made read-only on GitHub in December 2024. While still publicly accessible as a historical reference, an archived repository is no longer maintained, cannot accept contributions, and reflects a frozen snapshot of the codebase. The last code change to the skilion client was merged in November 2021; however, active development had slowed significantly well before then. As such, the skilion client should no longer be considered current or supported — particularly given the major API changes and evolving Microsoft OneDrive platform requirements since that time.

Under the terms of the GNU General Public License (GPL), forking and continuing development of open source software is fully permitted — provided that derivative works retain the same license. This client complies with the original GPLv3 licensing, ensuring the same freedoms granted by the original project remain intact.

Since forking in early 2018, this client has evolved into a clean re-imagining of the original codebase, resolving long-standing bugs and adding extensive new functionality to better support both personal and enterprise use cases to interact with Microsoft OneDrive from Linux, FreeBSD and OpenBSD platforms.

Features Copy Chapter

Broad Microsoft OneDrive Compatibility Copy Section

• Works with OneDrive Personal, OneDrive for Business, and Microsoft SharePoint Libraries.
• Full support for shared folders and files across both Personal and Business accounts.
• Supports single-tenant and multi-tenant Microsoft Entra ID environments.
• Compatible with national cloud deployments:
  • Microsoft Cloud for US Government
  • Microsoft Cloud Germany
  • Azure/Office 365 operated by VNET in China

Flexible Synchronisation Modes Copy Section

• Bi-directional sync (default) - keeps local and remote data fully aligned.
• Upload-only mode - only uploads local changes; does not download remote changes.
• Download-only mode - only downloads remote changes; does not upload local changes.
• Dry-run mode - test configuration changes safely without modifying files.
• Safe conflict handling minimises data loss by creating local backups whenever this is determined to be the safest conflict-resolution strategy.

Client-Side Filtering & Granular Sync Control Copy Section

• Comprehensive rules-based client-side filtering (inclusions, exclusions, wildcard *, globbing **).
• Filter specific files, folders, or patterns to tailor precisely what is synced with Microsoft OneDrive.
• Efficient cached sync state for fast decision-making during large or complex sync sets.

Real-Time Monitoring & Online Change Detection Copy Section

• Near real-time processing of cloud-side changes using native WebSocket support.
• Webhook support for environments where WebSockets are unsuitable (manual setup).
• Real-time local change monitoring via inotify.

Data Safety, Recovery & Integrity Protection Copy Section

• Implements the FreeDesktop.org Trash specification, enabling recovery of items deleted locally due to online deletion.
• Strong safeguards to prevent accidental remote deletion or overwrite after configuration changes.
• Interruption-tolerant uploads and downloads, automatically resuming transfers.
• Integrity validation for every file transferred.

Modern Authentication Support Copy Section

• Standard OAuth2 Native Client Authorisation Flow (default), supporting browser-based login, multi-factor authentication (MFA), and modern Microsoft account security requirements.
• OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts, ideal for headless systems, servers, and terminal-only environments.
• Intune Single Sign-On (SSO) using the Microsoft Identity Device Broker (IDB) via D-Bus, enabling seamless enterprise authentication without manual credential entry.

Performance, Efficiency & Resource Management Copy Section

• Multi-threaded file transfers for significantly improved sync speeds.
• Bandwidth rate limiting to control network consumption.
• Highly efficient processing with state caching, reducing API traffic and improving performance.

Desktop Integration & User Experience Copy Section

• libnotify desktop notifications for sync events, warnings, and errors.
• Registers the OneDrive folder as a sidebar location in supported file managers, complete with a distinctive icon.
• Works seamlessly in GUI and headless/server environments. A GUI is only required for Intune SSO, notifications, and sidebar integration; all other features function without graphical support.

What's missing Copy Chapter

• Ability to encrypt/decrypt files on-the-fly when uploading/downloading files from OneDrive
• Support for Windows 'On-Demand' functionality so file is only downloaded when accessed locally

External Enhancements Copy Chapter

• A GUI for configuration management: OneDrive Client for Linux GUI
• Colorful log output terminal modification: OneDrive Client for Linux Colorful log Output
• System Tray Icon: OneDrive Client for Linux System Tray Icon

Frequently Asked Questions Copy Chapter

Refer to Frequently Asked Questions

Have a question Copy Chapter

If you have a question or need something clarified, please raise a new discussion post here

Supported Application Version Copy Chapter

Support is only provided for the current application release version or newer 'master' branch versions.

The current release version is:

To check your version, run: onedrive --version. Ensure you are using the current release or compile the latest version from the master branch if needed.

If you are using an older version, you must upgrade to the current release or newer to receive support.

Documentation and Configuration Assistance Copy Chapter

OneDrive Client for Linux includes a rich set of documentation covering installation, configuration options, advanced usage, and integrations. These resources are designed to help new users get started quickly and to give experienced users full control over advanced behaviour. If you are changing configuration, running in production, or using Business/SharePoint features, you should be reading these documents. All documentation is maintained in the docs/ directory of this repository.

Getting Started Copy Section

Installation

Learn how to install the client on various systems — from distribution packages to building from source. Please read the Install Guide

Basic Usage & Configuration

Covers initial authentication, default settings, basic operational instructions, frequently asked 'how to' questions, and how to tailor the application configuration. Please read the Usage Guide

Advanced Configuration Copy Section

Application Configuration Options

Full reference for every config option (with descriptions, defaults, and examples) to customise sync behaviour precisely. Please read the Application Configuration Options Guide

Advanced Usage

Tips for creating multiple config profiles, custom sync rules, daemon setups, selective sync, dual-booting with Microsoft Windows and more. Please read the Advanced Usage Guide

Special Use Cases Copy Section

Business Shared Items

Configuring sync for OneDrive Business shared items (files and folders). Please read the Business Shared Items Guide

SharePoint & Office 365 Libraries

Instructions for syncing SharePoint document libraries (Business or Education tenants). Please read the SharePoint Library Guide

National Cloud support

Instructions for environments like Microsoft Cloud Germany or US Government cloud endpoints. Please read the National Cloud Deployment Guide

Container Support Copy Section

Docker

How to run the OneDrive client in a Docker container. Please read the Docker Guide

Podman

How to run the OneDrive client with Podman. Please read the Podman Guide

Basic Troubleshooting Steps Copy Chapter

If you encounter any issues running the application, please follow these steps before raising a bug report:

1. Check the application version
   Run onedrive --version to confirm which version you are using.

   • Ensure you are running the latest release.
   • If you are already on the latest release but still experiencing issues, manually build the client from the master branch to test against the very latest code. This includes fixes for bugs discovered since the last tagged release.
   • If you are using Docker or Podman, ensure you are using the 'edge' Docker Tag. Do not use the 'latest' Docker Tag.

2. Run in verbose mode
   Use the --verbose option to provide greater clarity and detailed logging about the issue you are facing.

   If you are using Docker or Podman, use the ONEDRIVE_VERBOSE environment variable to increase logging verbosity.

3. Test with IPv4 only
   Configure the application to use IPv4 network connectivity only, then retest. See the 'ip_protocol_version' option documentation for assistance.

4. Test with HTTP/1.1 and IPv4
   Configure the application to use HTTP/1.1 over IPv4 only, then retest. See the 'force_http_11' option documentation for assistance.

5. Verify cURL and libcurl versions
   If the above steps do not resolve your issue, upgrade both curl and libcurl to the latest versions provided by the curl developers.

   • See Compatibility with curl for details on curl bugs that impact this client.
   • Refer to the official cURL Releases page for version information.

6. Perform a --resync
   In some cases, a --resync is needed to ensure your data is correctly synced. This option instructs the client to delete its local state database and fully rebuild it from the current online OneDrive contents. This is a powerful recovery and re-alignment action that should be used sparingly and with care.

   • See Performing a --resync for further details.

7. Open a new issue
   If the problem persists after completing the steps above, proceed to Reporting an Issue or Bug below and open a new issue with the requested details and logs.

Reporting an Issue or Bug Copy Chapter

[!IMPORTANT]
Please ensure the problem is a software bug. For installation issues, distribution package/version questions, or dependency problems, start a Discussion instead of filing a bug report.

If you encounter a bug, you can report it on GitHub. Before opening a new issue report:

1. Complete the Basic Troubleshooting Steps
   Confirm you’ve run through all steps in the section above.

2. Search existing issues
   Check both Open and Closed issues for a similar problem to avoid duplicates.

3. Use the issue template
   Open a new bug report using the issue template and fill in all fields. Complete detail helps us reproduce your environment and replicate the issue.

4. Generate a debug log
   Follow this process to create a debug log.

   • If you are concerned about personal or business sensitive data in the debug log, you may:
     • Create a new OneDrive account, configure the client to use it, use dummy data to simulate your environment, and reproduce the issue; or
     • Provide an NDA or confidentiality agreement for signature prior to sharing sensitive logs.

5. Share the debug log securely

   • Do not post debug logs publicly. Debug logs can include sensitive details (file paths, filenames, API endpoints, environment info, etc.).
   • Send the log via email to [email protected] using a trusted email account.
   • Archive and password-protect the log before sending (e.g. .zip with AES or .7z):
     • Example (zip with password): zip -e onedrive-debug.zip onedrive-debug.log
     • Example (7z with password): 7z a -p onedrive-debug.7z onedrive-debug.log
   • Send the password out-of-band (OOB) — not in the same email as the archive. Email [email protected] to arrange an OOB method (e.g. separate email thread, phone/SMS, or agreed channel).
   • If you require an NDA, attach your NDA or confidentiality agreement to your email. It will be reviewed and signed prior to exchanging sensitive data.

What to include in your bug report Copy Section

When raising a new bug report, please include all details requested in the issue template, such as:

• A clear description of the problem and how to reproduce it
• Your operating system and installation method
• OneDrive account type and client version
• Application configuration and cURL version
• Sync directory location, system mount points, and partition types
• A full debug log, shared securely as described above

Providing complete information makes it much easier to understand, reproduce, and resolve your issue quickly.

[!NOTE]
Submitting a bug report starts a collaboration. To help us help you, please:

• Stay available to answer questions or provide clarifications if needed
• Test and confirm fixes in your own environment when a pull request (PR) is created for your issue

[!TIP]
Reports with missing details are much harder to investigate. Sharing as much as you can up front gives the best chance of a fast and accurate fix.

Known issues Copy Chapter

Lists common limitations, known problems, diagnostics, and workarounds. Please read the Known Issues Advice

File: ci/e2e/README-rerun.md Copy Chapter

E2E automatic failure rerun support

This folder now supports a two-pass CI model:

1. Run the primary E2E suite normally using ci/e2e/run.py
2. Parse results.json and automatically rerun only failed cases/scenarios with debug enabled using ci/e2e/rerun_failures.py

Primary run Copy Chapter

python3 -u ci/e2e/run.py

Automatic debug rerun Copy Chapter

python3 -u ci/e2e/rerun_failures.py   --results ci/e2e/out/results.json   --output-subdir debug-rerun   --run-label debug-rerun

This will:

• read the failed cases from the primary results.json
• narrow the rerun to only failed case IDs
• narrow scenario-based cases to only failed scenario IDs when available
• rerun with debug verbosity enabled
• write rerun outputs into ci/e2e/out/debug-rerun/

Direct filtered reruns Copy Chapter

Rerun one case Copy Section

python3 -u ci/e2e/run.py --case-id 0024 --debug --output-subdir tc0024-debug

Rerun multiple cases Copy Section

python3 -u ci/e2e/run.py --case-id 0002,0021,0024 --debug --output-subdir targeted-debug

Rerun only selected scenarios Copy Section

python3 -u ci/e2e/run.py   --case-id 0002,0021   --scenario 0002:SL-0004,SL-0018   --scenario 0021:RT-0001   --debug   --output-subdir targeted-scenarios-debug

Environment-driven controls Copy Chapter

These are also supported if you prefer using workflow env vars:

• E2E_DEBUG=1
• E2E_OUTPUT_SUBDIR=<subdir>
• E2E_RUN_LABEL=<label>
• E2E_SKIP_SUITE_CLEANUP=1
• E2E_SELECTED_CASES=0002,0021
• E2E_SELECTED_SCENARIOS_JSON={"0002": ["SL-0004"], "0021": ["RT-0001"]}

File: docs/advanced-usage.md Copy Chapter

Advanced Configuration of the OneDrive Client for Linux

This document covers the following scenarios:

• 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

Configuring the client to use multiple OneDrive accounts / configurations Copy Chapter

Essentially, each OneDrive account or SharePoint Shared Library which you require to be synced needs to have its own and unique configuration, local sync directory and service files. To do this, the following steps are needed:

1. Create a unique configuration folder for each onedrive client configuration that you need
2. Copy to this folder a copy of the default configuration file
3. Update the default configuration file as required, changing the required minimum config options and any additional options as needed to support your multi-account configuration
4. Authenticate the client using the new configuration directory
5. Test the configuration using '--display-config' and '--dry-run'
6. Sync the OneDrive account data as required using --synchronize or --monitor
7. Configure a unique systemd service file for this account configuration

1. Create a unique configuration folder for each onedrive client configuration that you need Copy Section

Make the configuration folder as required for this new configuration, for example:

mkdir ~/.config/my-new-config

2. Copy to this folder a copy of the default configuration file Copy Section

Copy to this folder a copy of the default configuration file by downloading this file from GitHub and saving this file in the directory created above:

wget https://raw.githubusercontent.com/abraunegg/onedrive/master/config -O ~/.config/my-new-config/config

3. Update the default configuration file Copy Section

The following config options must be updated to ensure that individual account data is not cross populated with other OneDrive accounts or other configurations:

• sync_dir

Other options that may require to be updated, depending on the OneDrive account that is being configured:

• drive_id
• application_id
• sync_business_shared_folders
• skip_dir
• skip_file
• Creation of a 'sync_list' file if required
• Creation of a 'business_shared_folders' file if required

4. Authenticate the client Copy Section

Authenticate the client using the specific configuration file:

onedrive --confdir="~/.config/my-new-config"

You will be asked to open a specific URL by using your web browser where you will have to login into your Microsoft Account and give the application the permission to access your files. After giving permission to the application, you will be redirected to a blank page. Copy the URI of the blank page into the application.

[user@hostname ~]$ onedrive --confdir="~/.config/my-new-config"
Configuration file successfully loaded
Configuring Global Azure AD Endpoints
Authorize this app visiting:

https://.....

Enter the response uri:

5. Display and Test the configuration Copy Section

Test the configuration using '--display-config' and '--dry-run'. By doing so, this allows you to test any configuration that you have currently made, enabling you to fix this configuration before using the configuration.

Display the configuration

onedrive --confdir="~/.config/my-new-config" --display-config

Test the configuration by performing a dry-run

onedrive --confdir="~/.config/my-new-config" --synchronize --verbose --dry-run

If both of these operate as per your expectation, the configuration of this client setup is complete and validated. If not, amend your configuration as required.

6. Sync the OneDrive account data as required Copy Section

Sync the data for the new account configuration as required:

onedrive --confdir="~/.config/my-new-config" --synchronize --verbose

or

onedrive --confdir="~/.config/my-new-config" --monitor --verbose

• --synchronize does a one-time sync
• --monitor keeps the application running and monitoring for changes both local and remote

7. Automatic syncing of new OneDrive configuration Copy Section

In order to automatically start syncing your OneDrive accounts, you will need to create a service file for each account. From the applicable 'systemd folder' where the applicable systemd service file exists:

• RHEL / CentOS: /usr/lib/systemd/system
• Others: /usr/lib/systemd/user and /lib/systemd/system

Step1: Create a new systemd service file Copy Section

Red Hat Enterprise Linux, CentOS Linux

Copy the required service file to a new name:

sudo cp /usr/lib/systemd/system/onedrive.service /usr/lib/systemd/system/onedrive-my-new-config

or

sudo cp /usr/lib/systemd/system/[email protected] /usr/lib/systemd/system/[email protected]

Others such as Arch, Ubuntu, Debian, OpenSuSE, Fedora

Copy the required service file to a new name:

sudo cp /usr/lib/systemd/user/onedrive.service /usr/lib/systemd/user/onedrive-my-new-config.service

or

sudo cp /lib/systemd/system/[email protected] /lib/systemd/system/[email protected]

Step 2: Edit new systemd service file Copy Section

Edit the new systemd file, updating the line beginning with ExecStart so that the confdir mirrors the one you used above:

ExecStart=/usr/local/bin/onedrive --monitor --confdir="/full/path/to/config/dir"

Example:

ExecStart=/usr/local/bin/onedrive --monitor --confdir="/home/myusername/.config/my-new-config"

[!IMPORTANT]
When running the client manually, --confdir="~/.config/...... is acceptable. In a systemd configuration file, the full path must be used. The ~ must be manually expanded when editing your systemd file.

Step 3: Enable the new systemd service Copy Section

Once the file is correctly edited, you can enable the new systemd service using the following commands.

Red Hat Enterprise Linux, CentOS Linux

systemctl enable onedrive-my-new-config
systemctl start onedrive-my-new-config

Others such as Arch, Ubuntu, Debian, OpenSuSE, Fedora

systemctl --user enable onedrive-my-new-config
systemctl --user start onedrive-my-new-config

or

systemctl --user enable [email protected]
systemctl --user start [email protected]

Step 4: Viewing systemd status and logs for the custom service Copy Section

Viewing systemd service status - Red Hat Enterprise Linux, CentOS Linux

systemctl status onedrive-my-new-config

Viewing systemd service status - Others such as Arch, Ubuntu, Debian, OpenSuSE, Fedora

systemctl --user status onedrive-my-new-config

Viewing journalctl systemd logs - Red Hat Enterprise Linux, CentOS Linux

journalctl --unit=onedrive-my-new-config -f

Viewing journalctl systemd logs - Others such as Arch, Ubuntu, Debian, OpenSuSE, Fedora

journalctl --user --unit=onedrive-my-new-config -f

Step 5: (Optional) Run custom systemd service at boot without user login Copy Section

In some cases it may be desirable for the systemd service to start without having to login as your 'user'

All the systemd steps above that utilise the --user option, will run the systemd service as your particular user. As such, the systemd service will not start unless you actually login to your system.

To avoid this issue, you need to reconfigure your 'user' account so that the systemd services you have created will startup without you having to login to your system:

loginctl enable-linger <your_user_name>

Example:

alex@ubuntu-headless:~$ loginctl enable-linger alex

Repeat these steps for each OneDrive new account that you wish to use.

Configuring the client to use multiple OneDrive accounts / configurations using Docker Copy Chapter

In some situations it may be desirable to run multiple Docker containers at the same time, each with their own configuration.

To run the Docker container successfully, it needs two unique Docker volumes to operate:

• Your configuration Docker volumes
• Your data Docker volume

When running multiple Docker containers, this is no different - each Docker container must have it's own configuration and data volume.

High level steps: Copy Section

1. Create the required unique Docker volumes for the configuration volume
2. Create the required unique local path used for the Docker data volume
3. Start the multiple Docker containers with the required configuration for each container

Create the required unique Docker volumes for the configuration volume

Create the required unique Docker volumes for the configuration volume(s):

docker volume create onedrive_conf_sharepoint_site1
docker volume create onedrive_conf_sharepoint_site2
docker volume create onedrive_conf_sharepoint_site3
...
docker volume create onedrive_conf_sharepoint_site50

Create the required unique local path used for the Docker data volume

Create the required unique local path used for the Docker data volume

mkdir -p /use/full/local/path/no/tilde/SharePointSite1
mkdir -p /use/full/local/path/no/tilde/SharePointSite2
mkdir -p /use/full/local/path/no/tilde/SharePointSite3
...
mkdir -p /use/full/local/path/no/tilde/SharePointSite50

Start the Docker container with the required configuration (example)

docker run -it --name onedrive -v onedrive_conf_sharepoint_site1:/onedrive/conf -v "/use/full/local/path/no/tilde/SharePointSite1:/onedrive/data" driveone/onedrive:latest
docker run -it --name onedrive -v onedrive_conf_sharepoint_site2:/onedrive/conf -v "/use/full/local/path/no/tilde/SharePointSite2:/onedrive/data" driveone/onedrive:latest
docker run -it --name onedrive -v onedrive_conf_sharepoint_site3:/onedrive/conf -v "/use/full/local/path/no/tilde/SharePointSite3:/onedrive/data" driveone/onedrive:latest
...
docker run -it --name onedrive -v onedrive_conf_sharepoint_site50:/onedrive/conf -v "/use/full/local/path/no/tilde/SharePointSite50:/onedrive/data" driveone/onedrive:latest

[!TIP]
To avoid 're-authenticating' and 'authorising' each individual Docker container, if all the Docker containers are using the 'same' OneDrive credentials, you can reuse the 'refresh_token' from one Docker container to another by copying this file to the configuration Docker volume of each Docker container.

If the account credentials are different .. you will need to re-authenticate each Docker container individually.

Configuring the client for use in dual-boot (Windows / Linux) situations Copy Chapter

When dual booting Windows and Linux, depending on the Windows OneDrive account configuration, the 'Files On-Demand' option may be enabled when running OneDrive within your Windows environment.

When this option is enabled in Windows, if you are sharing this location between your Windows and Linux systems, all files will be a 0 byte link, and cannot be used under Linux.

To fix the problem of windows turning all files (that should be kept offline) into links, you have to uncheck a specific option in the onedrive settings window. The option in question is Save space and download files as you use them.

To find this setting, open the onedrive pop-up window from the taskbar, click "Help & Settings" > "Settings". This opens a new window. Go to the tab "Settings" and look for the section "Files On-Demand".

After unchecking the option and clicking "OK", the Windows OneDrive client should restart itself and start actually downloading your files so they will truly be available on your disk when offline. These files will then be fully accessible under Linux and the Linux OneDrive client.

Accessing Windows OneDrive Files from Linux (Dual-Boot Setup) Copy Section

When dual-booting between Windows and Linux, accessing OneDrive-synced folders stored on an NTFS partition can be problematic. This is primarily due to Microsoft OneDrive's use of reparse points when the Files On-Demand feature is enabled in Windows. These reparse points can render files inaccessible from Linux, even after disabling Files On-Demand, because the reparse metadata may persist.

Solution: Use the ntfs-3g-onedrive Plugin

The 'ntfs-3g-onedrive' plugin is designed to address this issue. It modifies the behavior of the ntfs-3g driver to correctly handle OneDrive's reparse points, allowing you to access your OneDrive files from Linux.

[!IMPORTANT]
The configuration and installation of the 'ntfs-3g-onedrive' driver update on your platform is beyond the scope of this documentation and repository.

For assistance please seek support via the 'ntfs-3g' GitHub project.

Configuring the client for use when 'sync_dir' is a mounted directory Copy Chapter

In some environments, your setup might be that your configured 'sync_dir' is pointing to another mounted file system - a NFS|CIFS location, an external drive (USB stick, eSATA etc). As such, you configure your 'sync_dir' as follows:

sync_dir = "/path/to/mountpoint/OneDrive"

The issue here is - how does the client react if the mount point gets removed - network loss, device removal?

The client has zero knowledge of any event that causes a mountpoint to become unavailable, thus, the client (if you are running as a service) will assume that you deleted the files, thus, will go ahead and delete all your files on OneDrive. This is most certainly an undesirable action.

There are a few options here which you can configure in your 'config' file to assist you to prevent this sort of item from occurring:

1. classify_as_big_delete
2. check_nomount
3. check_nosync

[!NOTE]
Before making any change to your configuration, stop any sync process & stop any onedrive systemd service from running.

classify_as_big_delete Copy Section

By default, this uses a value of 1000 files|folders. An undesirable unmount if you have more than 1000 files, this default level will prevent the client from executing the online delete. Modify this value up or down as desired

check_nomount & check_nosync Copy Section

When configuring the OneDrive client to use a directory on a mounted volume (e.g., external disk, USB device, network share), it is essential to guard against accidental sync deletion if the mount point becomes unavailable.

If a mount is lost or not yet available at the time of sync, the 'sync_dir' may appear empty, leading the client to delete the corresponding online content. To safely prevent this, enable the following configuration options:

check_nomount = "true"
check_nosync  = "true"

These settings instruct the client to:

• Check for the presence of a .nosync file in the 'sync_dir' before syncing
• Halt syncing immediately if the file is detected, assuming the mount has failed or not available

How the `.nosync` file works

1. The .nosync file is placed on the local filesystem, in the exact directory that will later be covered by the mounted volume.
2. Once the external device is mounted, that directory (and the .nosync file) becomes hidden by the mount.
3. If the mount disappears or fails, the .nosync file becomes visible again.
4. The OneDrive client detects this and stops syncing, preventing accidental deletions due to the mount being unavailable.

Scenario 1: 'sync_dir' points directly to a mounted path

sync_dir = "/mnt/external/path/to/users/data/location/OneDrive"
check_nomount = "true"
check_nosync  = "true"

Step 1: Before mounting the device, prepare the .nosync file

sudo mkdir -p /mnt/external/path/to/users/data/location/OneDrive
sudo touch /mnt/external/path/to/users/data/location/OneDrive/.nosync

Step 2: Test the 'onedrive' Client

onedrive -s

with the output

...
Configuring Global Azure AD Endpoints
ERROR: .nosync file found in directory mount point. Aborting application startup process to safeguard data.
Attempting to perform a database vacuum to optimise database
...

Step 3: Mount your device (e.g., via systemd, fstab, or manually)

sudo mount /dev/sdX1 /mnt/external

Result:
The OneDrive client will now treat /mnt/external/path/to/users/data/location/OneDrive as the sync_dir. If the mount is ever lost, the .nosync file becomes visible again, and syncing is halted.

Scenario 2: 'sync_dir' is a symbolic link to a mounted directory

sync_dir = "~/OneDrive"
check_nomount = "true"
check_nosync  = "true"

and

$ ls -l ~/OneDrive
lrwxrwxrwx 1 user user 29 Jul 25 14:44 OneDrive -> /mnt/external/path/to/users/data/location/OneDrive

Step 1: Before mounting the device, prepare the .nosync file

sudo mkdir -p /mnt/external/path/to/users/data/location/OneDrive
sudo touch /mnt/external/path/to/users/data/location/OneDrive/.nosync

Step 2: Test the 'onedrive' Client

onedrive -s

with the output

...
Configuring Global Azure AD Endpoints
ERROR: .nosync file found in directory mount point. Aborting application startup process to safeguard data.
Attempting to perform a database vacuum to optimise database
...

Step 3: Mount your device (e.g., via systemd, fstab, or manually)

sudo mount /dev/sdX1 /mnt/external

Result:
Your symlinked ~/OneDrive path will now point into the mounted filesystem. If the mount goes missing, the .nosync file reappears via the symlink, and the client halts syncing automatically.

Upload data from the local ~/OneDrive folder to a specific location on OneDrive Copy Chapter

In some environments, you may not want your local ~/OneDrive folder to be uploaded directly to the root of your OneDrive account online.

Unfortunately, the OneDrive API lacks any facility to perform a re-direction of data during upload.

The workaround for this is to structure your local filesystem and reconfigure your client to achieve the desired goal.

High level steps: Copy Section

1. Create a new folder, for example /opt/OneDrive
2. Configure your application config 'sync_dir' to look at this folder
3. Inside /opt/OneDrive create the folder you wish to sync the data online to, for example: /opt/OneDrive/RemoteOnlineDestination
4. Configure the application to only sync /opt/OneDrive/RemoteDestination via 'sync_list'
5. Symbolically link ~/OneDrive -> /opt/OneDrive/RemoteOnlineDestination

Outcome: Copy Section

• Your ~/OneDrive will look / feel as per normal
• The data will be stored online under /RemoteOnlineDestination

Testing: Copy Section

• Validate your configuration with onedrive --display-config
• Test your configuration with onedrive --dry-run

File: docs/application-config-options.md Copy Chapter

Application Configuration Options for the OneDrive Client for Linux

Application Version Copy Chapter

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 Copy Chapter

• Configuration File Options
  • application_id
  • azure_ad_endpoint
  • azure_tenant_id
  • bypass_data_preservation
  • check_nomount
  • check_nosync
  • classify_as_big_delete
  • cleanup_local_files
  • connect_timeout
  • create_new_file_version
  • data_timeout
  • debug_https
  • delay_inotify_processing
  • disable_download_validation
  • disable_notifications
  • disable_permission_set
  • disable_upload_hash_streaming
  • disable_upload_validation
  • disable_version_check
  • disable_websocket_support
  • display_manager_integration
  • display_running_config
  • display_transfer_metrics
  • dns_timeout
  • download_only
  • drive_id
  • dry_run
  • enable_logging
  • file_fragment_size
  • force_http_11
  • force_session_upload
  • inotify_delay
  • ip_protocol_version
  • local_first
  • log_dir
  • max_curl_idle
  • mirror_local_state
  • monitor_authoritative_sync
  • monitor_fullscan_frequency
  • monitor_interval
  • monitor_log_frequency
  • no_remote_delete
  • notify_file_actions
  • operation_timeout
  • permanent_delete
  • rate_limit
  • read_only_auth_scope
  • recycle_bin_path
  • remove_source_files
  • resync
  • resync_auth
  • skip_dir
  • skip_dir_strict_match
  • skip_dotfiles
  • skip_file
  • skip_size
  • skip_symlinks
  • space_reservation
  • sync_business_shared_items
  • sync_dir
  • sync_dir_permissions
  • sync_file_permissions
  • sync_root_files
  • threads
  • transfer_order
  • upload_only
  • use_device_auth
  • use_intune_sso
  • use_recycle_bin
  • user_agent
  • webhook_enabled
  • webhook_expiration_interval
  • webhook_listening_host
  • webhook_listening_port
  • webhook_public_url
  • webhook_renewal_interval
  • write_xattr_data
• Command Line Interface (CLI) Only Options
  • CLI Option: --auth-files
  • CLI Option: --auth-response
  • CLI Option: --confdir
  • CLI Option: --create-directory
  • CLI Option: --create-share-link
  • CLI Option: --destination-directory
  • CLI Option: --display-admin-consent-url
  • CLI Option: --display-config
  • CLI Option: --display-sync-status
  • CLI Option: --display-quota
  • CLI Option: --download-file
  • 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: --share-password
  • CLI Option: --single-directory
  • CLI Option: --source-directory
  • CLI Option: --sync | -s
  • CLI Option: --sync-shared-files
  • CLI Option: --verbose | -v+
  • CLI Option: --with-editing-perms
• Deprecated Configuration File and CLI Options
  • force_http_2
  • min_notify_changes

Configuration File Options Copy Chapter

application_id Copy Section

Description: This is the config option for application id that used to identify itself to Microsoft OneDrive. In some circumstances, it may be desirable to use your own application id. To do this, you must register a new application with Microsoft Azure via https://portal.azure.com/, then use your new application id with this config option. You can find instructions for configuring your own app registration in national-cloud-deployments.md even if you don't necessarily configure it for a national cloud environment.

Value Type: String

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

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

azure_ad_endpoint Copy Section

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 Copy Section

Description: This configuration option restricts authentication and token acquisition to a specific Microsoft Entra ID tenant. When configured, the client will use the specified tenant identifier when constructing Microsoft Entra ID authentication endpoints and tenant-specific Microsoft Graph API requests, rather than using the multi-tenant common endpoint.

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]
This option must be configured when using azure_ad_endpoint or the --display-admin-consent-url CLI option.

[!NOTE]
This option is commonly used in Microsoft 365 Business, Enterprise, Education, Government, and other managed Microsoft Entra ID environments where authentication must be restricted to a specific tenant rather than using the multi-tenant common endpoint.

bypass_data_preservation Copy Section

Description: This config option disables safeBackup data preservation when the client detects that unique local file content would otherwise be displaced during conflict resolution or reconciliation. By default, replacement-style conflicts preserve the existing local content as a verified safeBackup copy before a validated replacement is committed. The online-deleted/local-modified conflict is the intentional exception where the local file is renamed to safeBackup while the online deletion is honoured.

When this option is enabled, those preservation operations are bypassed. This can allow local content to be overwritten or removed without a recoverable safeBackup. Use with extreme care and caution.

Value Type: Boolean

Default Value: False

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

check_nomount Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option: --check-for-nomount

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

check_nosync Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --check-for-nosync

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

classify_as_big_delete Copy Section

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

Value Type: Integer

Default Value: 1000

Config Example: classify_as_big_delete = "2000"

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

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

cleanup_local_files Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --cleanup-local-files

[!IMPORTANT]
This configuration option can only be used with --download-only. It cannot be used with any other application option.

[!NOTE]
In --monitor mode, authoritative cleanup cadence for --download-only --cleanup-local-files is configured by the monitor_authoritative_sync option.

connect_timeout Copy Section

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"

create_new_file_version Copy Section

Description: This setting controls how the application handles the Microsoft SharePoint feature which modifies all PDF, MS Office & HTML files post upload, effectively breaking the integrity of your data online. By default, when the application determines that this feature has modified your file post upload, the now online modified file will be downloaded. When this option is enabled, rather than downloading the file, a new online file version is created which negates the download of the modified file.

Value Type: Boolean

Default Value: False

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

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

[!IMPORTANT]
If you enable 'disable_upload_validation' via disable_upload_validation = "true" there is zero facility to determine if a file was modified post upload. As such, the application will default to the state that the upload integrity check has failed. When create_new_file_version = "false" your uploaded file will be downloaded regardless of the online modification state.

[!WARNING]
When this option is set to 'true', new file versions will be created online which will count towards your Microsoft OneDrive Quota.

data_timeout Copy Section

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

Value Type: Integer

Default Value: 60

Config Example: data_timeout = "300"

debug_https Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --debug-https

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

delay_inotify_processing Copy Section

Description: This setting controls whether 'inotify' events should be delayed or not. This option should only ever be enabled when attempting to reduce the impact of editors like Obsidian which constantly write change to disk in an atomic fashion.

Value Type: Boolean

Default Value: False

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

[!NOTE]
If you enable this option you must also enable 'force_session_upload' to ensure that your data uploads are done in a manner that editors, like Obsidian expect.

disable_download_validation Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --disable-download-validation

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

[!CAUTION]
If you are using OneDrive Business Accounts and your organisation implements Azure Information Protection, these AIP files will report as one size & hash online, but when downloaded, will report a totally different size and hash.

By default these files will fail integrity checking and be deleted, meaning that AIP files will not reside on your platform.

When you enable this option, the AIP files will download to your platform, however, if there are any other genuine download failures where the size and hash are different, these too will be retained locally meaning you may experience data integrity loss. Use this option with extreme caution.

disable_notifications Copy Section

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_permission_set Copy Section

Description: This setting controls whether the application will set the permissions on files and directories using the values of 'sync_dir_permissions' and 'sync_file_permissions'. When this option is enabled, file system permission inheritance will be used to assign the permissions for your data. This option may be useful if the file system configured does not allow setting of POSIX permissions.

Value Type: Boolean

Default Value: False

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

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

disable_upload_hash_streaming Copy Section

Description: This setting controls whether the client uses hash values calculated while streaming file uploads. When set to false, the client will use upload-streamed hash values where available and valid, falling back to the traditional local hash generation path if upload hash streaming is unavailable or fails. When set to true, the client will ignore hash values calculated during upload streaming and will always generate upload hashes using the traditional local file hash generation path. This option is primarily intended as a compatibility and diagnostic fail-safe for upload scenarios where Microsoft OneDrive or SharePoint may modify uploaded file content or metadata after upload, causing the hash later reported by Microsoft Graph to differ from the hash calculated during the upload stream.

Value Type: Boolean

Default Value: False

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

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

disable_upload_validation Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --disable-upload-validation

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

disable_version_check Copy Section

Description: This option determines whether the client will check the GitHub API for the current application version and grace period of running older application versions

Value Type: Boolean

Default Value: False

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

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

disable_websocket_support Copy Section

Description: This option disables the built-in WebSocket support that leverages RFC6455 to communicate with the Microsoft Graph API Service, providing near real-time notifications of online changes.

Value Type: Boolean

Default Value: False

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

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

display_manager_integration Copy Section

Description: Controls whether the client integrates the configured 'sync_dir' with the desktop’s file manager (e.g. Nautilus for GNOME, Dolphin for KDE), adding it as a “special place” in the sidebar and setting a custom OneDrive folder icon where supported.

Value Type: Boolean

Default Value: False

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

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

display_running_config Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --display-running-config

display_transfer_metrics Copy Section

Description: This option will display file transfer metrics when enabled.

Value Type: Boolean

Default Value: False

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

Output Example: Transfer Metrics - File: path/to/file.data | Size: 35768 Bytes | Duration: 2.27 Seconds | Speed: 0.02 Mbps (approx)

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

dns_timeout Copy Section

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 Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --download-only

[!IMPORTANT]
When using this option, the default mode of operation is to not clean up local files that have been deleted online. This ensures that the local data is an archive of what was stored online. To cleanup local files use --cleanup-local-files.

drive_id Copy Section

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

Value Type: String

Default Value: None

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

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

dry_run Copy Section

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 Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --enable-logging

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

file_fragment_size Copy Section

Description: This option controls the fragment size when uploading large files to Microsoft OneDrive. The value specified is in MB.

Value Type: Integer

Default Value: 10

Minimum Value: 10

Maximum Value: 60

Config Example: file_fragment_size = "25"

CLI Option Use: --file-fragment-size = '25'

[!NOTE]
Microsoft OneDrive requires that the file fragment size be an exact multiple of 320 KiB. The default value is an exact multiple of this required value. Additional exact multiple options are:
15, 20, 25, 30, 35, 40, 45, 50, 55

force_http_11 Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --force-http-11

force_session_upload Copy Section

Description: This option, when enabled, forces the client to use a 'session' upload, which, when the 'file' is uploaded by the session, this includes the local timestamp of the file.

Value Type: Boolean

Default Value: False

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

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

inotify_delay Copy Section

Description: This option specifies the number of seconds 'inotify' events are paused before they are processed by this client. This value is used to overcome aggressive write applications such as Obsidian which write each keystroke in an atomic manner to the local disk. Due to this atomic write, each 'save' causes the existing file to be deleted and replaced with a new file, which this client sees as multiple constant 'inotify' events.

Value Type: Integer

Default Value: 5

Maximum Value: 15

Config Example: inotify_delay = "10"

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

[!NOTE]
This option is only used if 'delay_inotify_processing' is enabled, otherwise this option is ignored.

ip_protocol_version Copy Section

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

Value Type: Integer

Default Value: 0

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

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

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

local_first Copy Section

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 Copy Section

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/"

max_curl_idle Copy Section

Description: This configuration option controls the number of seconds that elapse after a cURL engine was last used before it is considered stale and destroyed. Evidence suggests that some upstream network devices ignore the cURL keep-alive setting and forcibly close the active TCP connection when idle.

Value Type: Integer

Default Value: 120

Config Example: max_curl_idle = "120"

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

[!IMPORTANT]
It is strongly recommended not to modify this setting without conducting thorough network testing. Changing this option may lead to unexpected behaviour or connectivity issues, especially if upstream network devices handle idle connections in non-standard ways.

mirror_local_state Copy Section

Description: When used with local_first = "true" or --local-first, the local filesystem is treated as the authoritative source of truth and Microsoft OneDrive is reconciled to match the local state. Any files or directories that exist online but do not exist locally will be removed from Microsoft OneDrive rather than downloaded to the local filesystem. This option is intended for users who require the online state to become an exact mirror of the local filesystem, including the removal of remote-only content.

Value Type: Boolean

Default Value: False

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

CLI Option Use: --mirror-local-state

[!IMPORTANT]
This option requires local_first = "true" or the use of --local-first.

This option cannot be used with --upload-only.

Enabling this option may result in the permanent removal of files and directories from Microsoft OneDrive that do not exist locally. It is strongly recommended to first validate the intended actions using --dry-run.

monitor_authoritative_sync Copy Section

Description: This configuration option controls the authoritative cleanup behaviour in --monitor mode when using --download-only --cleanup-local-files.

Value Type: String

Default Value: monitor_and_signal

Config Example: monitor_authoritative_sync = "monitor_fullscan_frequency"

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

Valid Values:

monitor_and_signal
monitor_interval
monitor_fullscan_frequency

[!NOTE]
This option is only applicable when using --monitor --download-only --cleanup-local-files. In all other scenarios, this setting is ignored.

[!NOTE]
This option controls when local cleanup is treated as authoritative in monitor mode for --download-only --cleanup-local-files.

Valid values:

• monitor_and_signal

  • Authoritative cleanup is performed on scheduled monitor interval syncs and on API-signal-triggered syncs.
  • This is the default behaviour.
  • This is the most aggressive mode and may increase Microsoft Graph API usage when push notifications are frequent.

• monitor_interval

  • Authoritative cleanup is performed on scheduled monitor interval syncs only.
  • API-signal-triggered syncs remain faster and defer authoritative local cleanup until the next scheduled monitor interval.

• monitor_fullscan_frequency

  • Authoritative cleanup is performed only when the monitor_fullscan_frequency cadence is reached.
  • API-signal-triggered syncs and normal scheduled monitor interval syncs remain faster between authoritative cleanup passes.
  • When using this policy, a monitor_fullscan_frequency value greater than 0 defers authoritative cleanup to that cadence.
  • When using this policy, a monitor_fullscan_frequency value of 0 makes cleanup authoritative on every monitor sync cycle.
  • This zero-value behaviour applies only to the authoritative cleanup cadence used by monitor_authoritative_sync = "monitor_fullscan_frequency". It does not mean that scheduled online full-scan true-up is enabled when monitor_fullscan_frequency = "0".

monitor_fullscan_frequency Copy Section

Description: This configuration option controls the number of scheduled monitor_interval sync cycles between online full-scan true-up passes when running in --monitor mode.

Value Type: Integer

Default Value: 12

Config Example: monitor_fullscan_frequency = "24"

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

[!NOTE]
This option controls the online full-scan true-up cadence. An online full-scan true-up is when the client deliberately does not use the stored Microsoft Graph /delta link for that pass and instead performs a broader online reconciliation pass to ensure local and online state remain consistent.

By default, monitor_fullscan_frequency is set to 12. With the default monitor_interval value of 300 seconds, this means an online full-scan true-up is scheduled approximately every:

text Copy

monitor_interval * monitor_fullscan_frequency
300 * 12 = 3600 seconds

Setting this option to 0 disables the scheduled online full-scan true-up in normal monitor operation.

[!IMPORTANT]
This option does not disable the local database consistency and integrity check.

The log message:

text Copy

Performing a database consistency and integrity check on locally stored data

refers to local database/filesystem validation. It may appear during normal sync processing and should not be used as proof that an online full-scan true-up has occurred.

To diagnose whether an online full-scan true-up is occurring, use debug logging and check for messages such as:

text Copy

Full Scan Frequency Loop Number: ...
Perform a Full Scan True-Up: true|false
Performing a full scan of online data to ensure consistent local state
Using database stored deltaLink
Using cached deltaLink

monitor_interval Copy Section

Description: This configuration setting determines how often scheduled synchronisation loops run in --monitor mode when the client is otherwise idle, measured in seconds. When this interval elapses, the client will perform a monitor sync cycle. This may include checking for online changes in Microsoft OneDrive, conducting integrity checks on local data, and scanning the local sync_dir to identify new local content that has not yet been uploaded.

Value Type: Integer

Default Value: 300

Config Example: monitor_interval = "600"

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

[!IMPORTANT]
A minimum value of 300 is enforced for this configuration setting.

[!NOTE]
monitor_interval is the scheduled idle interval. A sync cycle may also be triggered earlier by local filesystem activity or by Microsoft OneDrive API signals via WebSocket or webhook support.

monitor_log_frequency Copy Section

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

Value Type: Integer

Default Value: 12

Config Example: monitor_log_frequency = "24"

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

Usage Example:

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

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

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

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

[!NOTE]
The additional log output Performing a database consistency and integrity check on locally stored data ... refers to the local database/filesystem consistency pass. This activity is part of normal sync processing and is not controlled by monitor_fullscan_frequency.

monitor_log_frequency only controls suppression of repeated normal monitor output when the client is not running in verbose mode. It does not change the sync logic.

[!NOTE]
If verbose application output is being used (--verbose), then this configuration setting has zero effect, as application verbose output takes priority over application output suppression.

no_remote_delete Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --no-remote-delete

[!IMPORTANT]
This configuration option can only be used in conjunction with --upload-only

notify_file_actions Copy Section

Description: This configuration option controls whether the client will log via GUI notifications successful actions that the client performs.

Value Type: Boolean

Default Value: False

Config Example: notify_file_actions = "true"

[!NOTE]
GUI Notification Support must be compiled in first, otherwise this option will have zero effect and will not be used.

operation_timeout Copy Section

Description: This configuration option controls the maximum total time (in seconds) that any network operation is allowed to take. This limit applies to the entire request, including DNS resolution, connection setup, TLS negotiation, and data transfer. This option maps directly to libcurl’s CURLOPT_TIMEOUT.

Value Type: Integer

Default Value: 0 (no timeout)

Config Example: operation_timeout = "3600"

[!IMPORTANT]
Setting a non-zero value will cause libcurl to abort the operation once the specified time has elapsed — even if data is still flowing normally.
For large file downloads, particularly on slower connections, enabling a finite timeout may cause transfers to be terminated prematurely.

It is strongly recommend to leave this option at its default of 0 unless you specifically require a hard global time limit.

permanent_delete Copy Section

Description: Permanently delete an item online when it is removed locally. When using this method, they're permanently removed and aren't sent to the Microsoft OneDrive Recycle Bin. Therefore, permanently deleted drive items can't be restored afterward. Online data loss MAY occur in this scenario.

Value Type: Boolean

Default Value: False

Config Example: permanent_delete = "true"

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

[!IMPORTANT]
The Microsoft OneDrive API for this capability is also very narrow:

Account Type	Config Option is Supported
Personal	❌
Business	✔
SharePoint	✔
Microsoft Cloud Germany	✔
Microsoft Cloud for US Government	❌
Azure and Office365 operated by VNET in China	❌

When using this config option against an unsupported Personal Accounts the following message will be generated:

text Copy

WARNING: The application is configured to permanently delete files online; however, this action is not supported by Microsoft OneDrive Personal Accounts.

When using this config option against a supported account the following message will be generated:

text Copy

WARNING: Application has been configured to permanently remove files online rather than send to the recycle bin. Permanently deleted items can't be restored.
WARNING: Online data loss MAY occur in this scenario.

rate_limit Copy Section

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 Copy Section

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

Value Type: Boolean

Default Value: False

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

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

recycle_bin_path Copy Section

Description: This configuration option allows you to specify the 'Recycle Bin' path for the application.

Value Type: String

Default Value: None however the application will use ~/.local/share/Trash as the pre-defined default so that files will be placed in the correct location for your user profile.

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

Config Example: recycle_bin_path = "/path/to/desired/location/"

remove_source_files Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --remove-source-files

[!IMPORTANT]
This configuration option can only be used in conjunction with --upload-only

remove_source_folders Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --remove-source-folders

[!IMPORTANT]
This configuration option can only be used in conjunction with --upload-only --remove-source-files

[!IMPORTANT]
The directory structure will only be removed if it is empty.

resync Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --resync

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

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

[!IMPORTANT]
The increased activity against the Microsoft Graph API when using this option may trigger HTTP 429 (throttling) responses during the synchronisation process.

resync_auth Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --resync-auth

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

skip_dir Copy Section

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

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

[!IMPORTANT]
Entries for 'skip_dir' are relative to your 'sync_dir' path.

Value Type: String

Default Value: Empty - not required for normal operation

Config Example:

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

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

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

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

This will be interpreted the same as:

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

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

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

skip_dir_strict_match Copy Section

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 Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --skip-dot-files

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

skip_file Copy Section

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

Value Type: String

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

By default, the following files will be skipped:

The following suggested skip file patterns are not included in the default configuration but could also be considered for skipping:

[!IMPORTANT]
If you define your own 'skip_file' configuration, the default settings listed above will be overridden. It is strongly recommended that you explicitly include the default 'skip_file' rules alongside your custom entries to ensure temporary and/or transient files are still correctly skipped.

Config Example:

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

Files can be skipped in the following fashion:

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

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

[!IMPORTANT]
Entries for 'skip_file' are relative to your 'sync_dir' path.

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

# Defaults - always keep
skip_file = "~*|.~*|*.tmp|*.swp|*.partial"
# Custom 'skip_file' additions
skip_file = "*.blah"
skip_file = "never_sync.file"
skip_file = "/Documents/keepass.kdbx"

This will be interpreted the same as:

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

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

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

skip_size Copy Section

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'

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

skip_symlinks Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --skip-symlinks

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

space_reservation Copy Section

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

Value Type: Integer

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

Config Example: space_reservation = "100"

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

sync_business_shared_items Copy Section

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

Value Type: Boolean

Default Value: False

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

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

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

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

sync_dir Copy Section

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

Value Type: String

Default Value: ~/OneDrive

Config Example: sync_dir = "~/MyDirToSync"

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

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

sync_dir_permissions Copy Section

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

Value Type: Integer

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

Config Example: sync_dir_permissions = "700"

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

sync_file_permissions Copy Section

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

Value Type: Integer

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

Config Example: sync_file_permissions = "600"

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

sync_root_files Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --sync-root-files

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

threads Copy Section

Description: This configuration option controls the number of worker threads used for parallel upload and download operations when transferring files between your local system and Microsoft OneDrive. Each thread handles a discrete portion of the workload, improving performance when used appropriately. All non-transfer operations, such as folder listings (/children), delta queries (/delta), and metadata requests are processed serially on a single thread.

Value Type: Integer

Default Value: 8

Maximum Value: 16

Config Example: threads = "16"

CLI Option Use: --threads '16'

[!NOTE]
The default value of 8 threads is based on the average number of physical CPU cores found in consumer and workstation-grade Intel and AMD processors released from approximately 2012 through 2025. This includes laptops, desktops, and server-grade CPUs where 4–8 physical cores are typical.

In extensive testing, configuring the application with more than 16 threads — regardless of available physical CPU cores — frequently caused the Microsoft OneDrive service to become blocked due to excessive API request volume.

[!NOTE]
The threads setting only affects file transfer operations. All API operations outside of upload/download operations are single-threaded.

This option allows the alignment to Microsoft’s Graph API guidance which recommends limiting concurrent requests to 5–10. The default of 8 provides a safe and performant baseline.

[!IMPORTANT]
For optimal performance and application stability, the number of threads should not exceed the number of physical CPU cores available to the system. Setting the thread count too high can result in CPU contention, increased context switching, and reduced throughput due to over-scheduling.

If running inside a container or virtual machine, ensure that the container/VM has sufficient allocated CPU cores before increasing this setting.

[!IMPORTANT]
If the configured threads value (default or manual) exceeds the number of available CPU cores, the application will issue a warning similar to the following:

text Copy

WARNING: Configured 'threads = 8' exceeds available CPU cores (CPU_COUNT).
         This may lead to reduced performance, CPU contention, and instability. For best results, set 'threads' no higher than the number of physical CPU cores.

If this warning message appears during application startup, you must review and adjust your threads setting to match the number of physical CPU cores on your system to avoid degraded performance or instability.

[!IMPORTANT]
The application fully implements Microsoft’s throttling requirements for handling 429 and 503 response codes by:

• Handles 429 and 503 responses using exponential backoff
• Respects Retry-After headers provided by the API for the required back off period
• Limits concurrency to the recommended limits

If you receive this application output:

text Copy

Handling a Microsoft Graph API HTTP 429 Response Code (Too Many Requests) - Internal Thread ID: AbCdEfGhIjKlMnOp

Reduce your configured 'threads' value or raise a support ticket with Microsoft

[!WARNING]
Increasing or keeping the thread count beyond the default or available physical CPU cores will also result in higher system resource utilisation, particularly in terms of CPU load and local TCP port consumption. On lower-spec systems or in constrained environments, this may lead to network saturation, unpredictable behaviour, increase in throttling behaviour by Microsoft or application crashes due to resource exhaustion.

transfer_order Copy Section

Description: This configuration option controls the transfer order of files between your local system and Microsoft OneDrive.

Value Type: String

Default Value: default

Config Example:

Transfer by size, smallest first

transfer_order = "size_asc"

Transfer by size, largest first

transfer_order = "size_dsc"

Transfer by file name sorted A to Z

transfer_order = "name_asc"

Transfer by file name sorted Z to A

transfer_order = "name_dsc"

upload_only Copy Section

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

Value Type: Boolean

Default Value: False

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

CLI Option Use: --upload-only

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

use_device_auth Copy Section

Description: Enable this option to authenticate using the Microsoft OAuth2 Device Authorisation Flow (device_code grant). This flow allows the client to initiate a sign-in process without launching a web browser directly — ideal for headless systems or remote sessions. A short code and URL will be provided for the user to complete authentication via a separate browser-enabled device.

Value Type: Boolean

Default Value: False

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

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

[!IMPORTANT]
This option is fully supported for Microsoft Entra ID (Work/School) accounts. For personal Microsoft accounts (e.g., @outlook.com or @hotmail.com), this method of authentication is not supported. Please use the interactive interactive authentication method (default) to authenticate this application.

use_intune_sso Copy Section

Description: Enable this option to authenticate using Intune Single Sign-On (SSO) via the Microsoft Identity Device Broker over D-Bus. This method is suitable for environments where the system is Intune-enrolled and allows seamless token retrieval without requiring browser interaction.

Value Type: Boolean

Default Value: False

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

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

[!NOTE]
The installation and configuration of Intune for your platform is beyond the scope of this documentation.

use_recycle_bin Copy Section

Description: This configuration option controls the application function to move online deleted files to a 'Recycle Bin' on your system. This allows you to review online deleted data manually before this is purged from your actual system.

Value Type: Boolean

Default Value: False

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

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

user_agent Copy Section

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

Value Type: String

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

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

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

webhook_enabled Copy Section

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

Value Type: Boolean

Default Value: False

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

webhook_enabled = "true"
webhook_public_url = "https://<your.fully.qualified.domain.name>/webhooks/onedrive"

[!NOTE]
Setting webhook_enabled = "true" enables the webhook feature in 'monitor' mode. The onedrive process will listen for incoming updates at a configurable endpoint, which defaults to 0.0.0.0:8888.

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

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

To resolve this configuration issue, potentially investigate adding the following 'proxy' configuration options to your nginx configuration file:

text Copy

server {
	listen 443;
server_name <your.fully.qualified.domain.name>;
	location /webhooks/onedrive {
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Original-Request-URI $request_uri;
		proxy_read_timeout 300s;
		proxy_connect_timeout 75s;
		proxy_buffering off;
		proxy_http_version 1.1;
		proxy_pass http://127.0.0.1:8888;
	}
}

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

webhook_expiration_interval Copy Section

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 Copy Section

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

Value Type: String

Default Value: 0.0.0.0

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

[!NOTE]
Use in conjunction with 'webhook_listening_port' to change the webhook listening endpoint.

webhook_listening_port Copy Section

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

Value Type: Integer

Default Value: 8888

Config Example: webhook_listening_port = "9999"

[!NOTE]
Use in conjunction with 'webhook_listening_host' to change the webhook listening endpoint.

webhook_public_url Copy Section

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

Value Type: String

Default Value: empty

Config Example:

webhook_public_url = "https://<your.fully.qualified.domain.name>/webhooks/onedrive"

webhook_renewal_interval Copy Section

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 Copy Section

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"

write_xattr_data Copy Section

Description: This setting enables writing xattr values detailing the 'createdBy' and 'lastModifiedBy' information provided by the OneDrive API

Value Type: Boolean

Default Value: False

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

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

xattr Data Example:

user.onedrive.createdBy="Account Display Name"
user.onedrive.lastModifiedBy="Account Display Name"

Command Line Interface (CLI) Only Options Copy Chapter

CLI Option: --auth-files Copy Section

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

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

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

text Copy

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.

text Copy

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 Copy Section

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

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

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

text Copy

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=d50ca740-c83f-4d1b-b616-12c519384f0c&scope=Files.ReadWrite%20Files.ReadWrite.All%20Sites.ReadWrite.All%20offline_access&response_type=code&prompt=login&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

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

CLI Option: --confdir Copy Section

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

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

[!IMPORTANT]
If using this option, it must be specified each and every time the application is used. If this is omitted, the application default configuration directory will be used.

CLI Option: --create-directory Copy Section

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

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

[!IMPORTANT]
The specified path to create is relative to your configured 'sync_dir'.

CLI Option: --create-share-link Copy Section

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

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

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

CLI Option: --destination-directory Copy Section

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

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

[!IMPORTANT]
All specified paths are relative to your configured 'sync_dir'.

CLI Option: --display-admin-consent-url Copy Section

Description: This CLI option displays a tenant-specific Microsoft Entra ID administrator consent URL for environments where administrator approval is required before users can authenticate and use the client.

Usage Example: onedrive --display-admin-consent-url

[!IMPORTANT]
This option does not authenticate the user and does not generate a refresh token.

The generated URL must be opened by a Microsoft Entra ID administrator to grant tenant-wide consent for the application. Nothing from this process needs to be pasted back into the client.

After administrator consent has been granted, users must complete the normal authentication process by running onedrive or onedrive --reauth.

[!IMPORTANT]
This option requires 'azure_tenant_id' to be configured.

The tenant identifier is used only to generate the Microsoft Entra ID administrator consent endpoint. The OAuth native-client redirect URI must remain the registered application redirect URI:

https://login.microsoftonline.com/common/oauth2/nativeclient

Do not manually replace common in the redirect URI with the tenant ID unless you are using your own custom Microsoft Entra ID application registration and that exact redirect URI has been registered for that application.

CLI Option: --display-config Copy Section

Description: This CLI option will display the effective application configuration

Usage Example: onedrive --display-config

CLI Option: --display-sync-status Copy Section

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

Usage Example: onedrive --display-sync-status

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

CLI Option: --display-quota Copy Section

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: --download-file Copy Section

Description: This CLI option will download a single file based on the online path. No sync will be performed.

Usage Example: onedrive --download-file 'path/to/your/file/online'

CLI Option: --force Copy Section

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

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

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

CLI Option: --force-sync Copy Section

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

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

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

text Copy

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

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

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

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

CLI Option: --get-file-link Copy Section

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

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

[!IMPORTANT]
The path that you should use must be relative to your 'sync_dir'

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

Description: This CLI option queries the OneDrive API and return's the Microsoft 365 Drive ID for a given SharePoint document 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 Copy Section

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

Usage Example: onedrive --list-shared-items

Example Output:

...
Listing available OneDrive Business Shared Items:

-----------------------------------------------------------------------------------
Shared File:     large_document_shared.docx
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     no_download_access.docx
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     online_access_only.txt
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     read_only.txt
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     qewrqwerwqer.txt
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     dummy_file_to_share.docx
Shared By:       testuser2 testuser2 ([email protected])
-----------------------------------------------------------------------------------
Shared Folder:   Sub Folder 2
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared File:     file to share.docx
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
Shared Folder:   Top Folder
Shared By:       test user ([email protected])
-----------------------------------------------------------------------------------
...

CLI Option: --logout Copy Section

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

Usage Example: onedrive --logout

CLI Option: --modified-by Copy Section

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

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

[!IMPORTANT]
The path that you should use must be relative to your 'sync_dir'

CLI Option: --monitor | -m Copy Section

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 Copy Section

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

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

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

CLI Option: --reauth Copy Section

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

Usage Example: onedrive --reauth

CLI Option: --remove-directory Copy Section

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

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

[!IMPORTANT]
The specified path to remove is relative to your configured 'sync_dir'.

CLI Option: --share-password Copy Section

Description: This CLI option enables the creation of a shareable file link that can only be accessed by providing the valid password. This option can only be used in conjunction with --create-share-link

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

CLI Option: --single-directory Copy Section

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

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

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

CLI Option: --source-directory Copy Section

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

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

[!IMPORTANT]
All specified paths are relative to your configured 'sync_dir'.

CLI Option: --sync | -s Copy Section

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 Copy Section

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

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

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

CLI Option: --verbose | -v+ Copy Section

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 Copy Section

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

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

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

Deprecated Configuration File and CLI Options Copy Chapter

The following configuration options are no longer supported:

force_http_2 Copy Section

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

Deprecated Config Example: force_http_2 = "true"

Deprecated CLI Option: --force-http-2

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

min_notify_changes Copy Section

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

Deprecated Config Example: min_notify_changes = "50"

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

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

File: docs/application-security.md Copy Chapter

OneDrive Client for Linux Application Security

This document details the following information:

• Why is this application an 'unverified publisher'?
• Application Security and Permission Scopes
• How to change Permission Scopes
• How to review your existing application access consent

Why is this application an 'unverified publisher'? Copy Chapter

Publisher Verification, as per the Microsoft process has actually been configured, and, actually has been verified!

Verified Publisher Configuration Evidence Copy Section

As per the image below, the Azure portal shows that the 'Publisher Domain' has actually been verified:

• The 'Publisher Domain' is: https://abraunegg.github.io/
• The required 'Microsoft Identity Association' is: https://abraunegg.github.io/.well-known/microsoft-identity-association.json

Application Security and Permission Scopes Copy Chapter

There are 2 main components regarding security for this application:

• Azure Application Permissions
• User Authentication Permissions

Keeping this in mind, security options should follow the security principal of 'least privilege':

The principle that a security architecture should be designed so that each entity
is granted the minimum system resources and authorizations that the entity needs
to perform its function.

Reference: https://csrc.nist.gov/glossary/term/least_privilege

As such, the following API permissions are used by default:

Default Azure Application Permissions Copy Section

Default User Authentication Permissions Copy Section

When a user authenticates with Microsoft OneDrive, additional account permissions are provided by service to give the user specific access to their data. These are delegated permissions provided by the platform:

When these delegated API permissions are combined, these provide the effective authentication scope for the OneDrive Client for Linux to access your data. The resulting effective 'default' permissions will be:

These 'default' permissions will allow the OneDrive Client for Linux to read, write and delete data associated with your OneDrive Account.

How are the Authentication Scopes used? Copy Chapter

When using the OneDrive Client for Linux, the above authentication scopes will be presented to the Microsoft Authentication Service (login.microsoftonline.com), where the service will validate the request and provide an applicable token to access Microsoft OneDrive with. This can be illustrated as the following:

This is similar to the Microsoft Windows OneDrive Client:

In a business setting, IT staff who need to authorise the use of the OneDrive Client for Linux in their environment can be assured of its safety. The primary concern for IT staff should be securing the device running the OneDrive Client for Linux. Unlike in a corporate environment where Windows devices are secured through Active Directory and Group Policy Objects (GPOs) to protect corporate data on the device, it is beyond the responsibility of this client to manage security on Linux devices.

Configuring read-only access to your OneDrive data Copy Chapter

In some situations, it may be desirable to configure the OneDrive Client for Linux totally in read-only operation.

To change the application to 'read-only' access, add the following to your configuration file:

read_only_auth_scope = "true"

This will change the user authentication scope request to use read-only access.

[!IMPORTANT]
When changing this value, you must re-authenticate the client using the --reauth option to utilise the change in authentication scopes.

When using read-only authentication scopes, the uploading of any data or local change to OneDrive will fail with the following error:

2022-Aug-06 13:16:45.3349625    ERROR: Microsoft OneDrive API returned an error with the following message:
2022-Aug-06 13:16:45.3351661      Error Message:    HTTP request returned status code 403 (Forbidden)
2022-Aug-06 13:16:45.3352467      Error Reason:     Access denied
2022-Aug-06 13:16:45.3352838      Error Timestamp:  2022-06-12T13:16:45
2022-Aug-06 13:16:45.3353171      API Request ID:   <redacted>

As such, it is also advisable for you to add the following to your configuration file so that 'uploads' are prevented:

download_only = "true"

[!IMPORTANT]
Additionally 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. See below on how to remove your prior application consent.

Reviewing your existing application access consent Copy Chapter

To review your existing application access consent, you need to access the following URL: https://account.live.com/consent/Manage

From here, you are able to review what applications have been given what access to your data, and remove application access as required.

File: docs/build-rpm-howto.md Copy Chapter

RPM Package Build Process

The instructions below have been tested on the following systems:

• CentOS Stream release 9

These instructions should also be applicable for RedHat & Fedora platforms, or any other RedHat RPM based distribution.

Prepare Package Development Environment Copy Chapter

Install Development Dependencies Copy Section

Install the following dependencies on your build system:

sudo yum groupinstall -y 'Development Tools'
sudo yum install -y libcurl-devel
sudo yum install -y sqlite-devel
sudo yum install -y libnotify-devel
sudo yum install -y dbus-devel
sudo yum install -y wget
mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}

Install DMD Compiler for Linux Copy Section

Install the latest DMD Compiler for Linux from https://dlang.org/download.html using the Fedora/CentOS x86_64 link.

Illustrated below is the installation using the minimum supported compiler. You should always install the latest version of the compiler for your platform when manually building an RPM.

sudo yum install -y https://downloads.dlang.org/releases/2.x/2.091.1/dmd-2.091.1-0.fedora.x86_64.rpm

Build RPM from spec file using the DMD Compiler Copy Chapter

Build the RPM from the provided spec file:

wget https://github.com/abraunegg/onedrive/archive/refs/tags/v2.5.6.tar.gz -O ~/rpmbuild/SOURCES/v2.5.6.tar.gz
wget https://raw.githubusercontent.com/abraunegg/onedrive/master/contrib/spec/onedrive.spec.in -O ~/rpmbuild/SPECS/onedrive.spec
rpmbuild -ba ~/rpmbuild/SPECS/onedrive.spec --define 'dcompiler dmd'

RPM Build Example Results Copy Section

Below are example output results of building, installing and running the RPM package on the respective platforms:

CentOS Stream release 9 RPM Build Process

/* Detailed source-code truncated for AI context efficiency. */

CentOS Stream release 9 RPM Package Install Process

/* Detailed source-code truncated for AI context efficiency. */

Build RPM from SRPM using mock Copy Chapter

Install mock on your platform Copy Section

Use the following installation instructions to install 'mock' on your platform:

sudo yum install epel-release
sudo yum install mock
sudo yum install -y wget
mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}

Configure mock Copy Section

Add your user to the mock group:

sudo usermod -a -G mock $USER

[!NOTE]
Log out and back in for the group membership changes to take effect.

Build a Source RPM (SRPM) file Copy Section

Build the SRPM from the provided spec file:

wget https://github.com/abraunegg/onedrive/archive/refs/tags/v2.5.6.tar.gz -O ~/rpmbuild/SOURCES/v2.5.6.tar.gz
wget https://raw.githubusercontent.com/abraunegg/onedrive/master/contrib/spec/onedrive.spec.in -O ~/rpmbuild/SPECS/onedrive.spec
rpmbuild -bs ~/rpmbuild/SPECS/onedrive.spec

[!NOTE]
This will build a SRPM to the following location: /home/alex/rpmbuild/SRPMS/onedrive-2.5.6-1.el9.src.rpm

This SRPM will be used in the examples below:

Build Fedora 42 RPM using mock Copy Section

/* Detailed source-code truncated for AI context efficiency. */

File: docs/business-shared-items.md Copy Chapter

How to sync OneDrive Business Shared Items

[!CAUTION]
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.

[!CAUTION]
This feature has been 100% re-written from v2.5.0 onwards and is not backwards compatible with v2.4.x client versions. If enabling this feature, you must upgrade to v2.5.0 or above on all systems that are running this client.

An additional pre-requisite before using this capability in v2.5.0 and above is for you to revert any v2.4.x Shared Business Folder configuration you may be currently using, including, but not limited to:

• Removing sync_business_shared_folders = "true|false" from your 'config' file
• Removing the 'business_shared_folders' file
• Removing any local data | shared folder data from your configured 'sync_dir' to ensure that there are no conflicts or issues.
• Removing any configuration online that might be related to using this feature prior to v2.5.0

Process Overview Copy Chapter

Syncing OneDrive Business Shared Folders requires additional configuration for your 'onedrive' client:

1. From the OneDrive web interface, review the 'Shared' objects that have been shared with you.
2. Select the applicable folder, and click the 'Add shortcut to My files', which will then add this to your 'My files' folder
3. Update your OneDrive Client for Linux 'config' file to enable the feature by adding sync_business_shared_items = "true". Adding this option will trigger a --resync requirement.
4. Test the configuration using '--dry-run'
5. Remove the use of '--dry-run' and sync the OneDrive Business Shared folders as required

Enable syncing of OneDrive Business Shared Items via config file Copy Section

sync_business_shared_items = "true"

Disable syncing of OneDrive Business Shared Items via config file Copy Section

sync_business_shared_items = "false"

Syncing OneDrive Business Shared Folders Copy Chapter

Use the following steps to add a OneDrive Business Shared Folder to your account:

1. Login to Microsoft OneDrive online, and navigate to 'Shared' from the left hand side pane

2. Select the respective folder you wish to sync, and click the 'Add shortcut to My files' at the top of the page

3. The final result online will look like this:

When using Microsoft Windows, this shared folder will appear as the following:

4. Sync your data using onedrive --sync --verbose. If you have just enabled the sync_business_shared_items = "true" configuration option, you will be required to perform a resync. During the sync, the selected shared folder will be downloaded:

...
Processing API Response Bundle: 1 - Quantity of 'changes|items' in this bundle to process: 4
Finished processing /delta JSON response from the OneDrive API
Processing 3 applicable changes and items received from Microsoft OneDrive
Processing OneDrive JSON item batch [1/1] to ensure consistent local state
Creating local directory: ./my_shared_folder
Quota information is restricted or not available for this drive.
Syncing this OneDrive Business Shared Folder: my_shared_folder
Fetching /delta response from the OneDrive API for Drive ID: b!BhWyqa7K_kqXqHtSIlsqjR5iJogxpWxDradnpVGTU2VxBOJh82Y6S4he4rdnGPBT
Processing API Response Bundle: 1 - Quantity of 'changes|items' in this bundle to process: 6
Finished processing /delta JSON response from the OneDrive API
Processing 6 applicable changes and items received from Microsoft OneDrive
Processing OneDrive JSON item batch [1/1] to ensure consistent local state
Creating local directory: ./my_shared_folder/asdf
Creating local directory: ./my_shared_folder/original_data
Number of items to download from OneDrive: 3
Downloading file: my_shared_folder/my_folder/file_one.txt ... done
Downloading file: my_shared_folder/my_folder/file_two.txt ... done
Downloading file: my_shared_folder/original_data/file1.data ... done
Performing a database consistency and integrity check on locally stored data
...

When this is viewed locally, on Linux, this shared folder is seen as the following:

Any shared folder you add can utilise any 'client side filtering' rules that you have created.

Syncing OneDrive Business Shared Files Copy Chapter

There are two methods to support the syncing OneDrive Business Shared Files with the OneDrive Application

1. Add a 'shortcut' to your 'My Files' for the file, which creates a URL shortcut to the file which can be followed when using a Linux Window Manager (Gnome, KDE etc) and the link will open up in a browser. Microsoft Windows only supports this option.
2. Use --sync-shared-files option to sync all files shared with you to your local disk. If you use this method, you can utilise any 'client side filtering' rules that you have created to filter out files you do not want locally. This option will create a new folder locally, with sub-folders named after the person who shared the data with you.

Syncing OneDrive Business Shared Files using Option 1 Copy Section

1. As per the above method for adding folders, select the shared file, then select to 'Add shortcut' to the file

2. The final result online will look like this:

When using Microsoft Windows, this shared file will appear as the following:

3. Sync your data using onedrive --sync --verbose. If you have just enabled the sync_business_shared_items = "true" configuration option, you will be required to perform a resync.

...
All application operations will be performed in the configured local 'sync_dir' directory: /home/alex/OneDrive
Fetching /delta response from the OneDrive API for Drive ID: b!bO8V7s9SSk6r7mWHpIjURotN33W1W2tEv3OXV_oFIdQimEdOHR-1So7CqeT1MfHA
Processing API Response Bundle: 1 - Quantity of 'changes|items' in this bundle to process: 2
Finished processing /delta JSON response from the OneDrive API
Processing 1 applicable changes and items received from Microsoft OneDrive
Processing OneDrive JSON item batch [1/1] to ensure consistent local state
Number of items to download from OneDrive: 1
Downloading file: ./file to share.docx.url ... done
Syncing this OneDrive Business Shared Folder: my_shared_folder
Fetching /delta response from the OneDrive API for Drive ID: b!BhWyqa7K_kqXqHtSIlsqjR5iJogxpWxDradnpVGTU2VxBOJh82Y6S4he4rdnGPBT
Processing API Response Bundle: 1 - Quantity of 'changes|items' in this bundle to process: 0
Finished processing /delta JSON response from the OneDrive API
No additional changes or items that can be applied were discovered while processing the data received from Microsoft OneDrive
Quota information is restricted or not available for this drive.
Performing a database consistency and integrity check on locally stored data
Processing DB entries for this Drive ID: b!BhWyqa7K_kqXqHtSIlsqjR5iJogxpWxDradnpVGTU2VxBOJh82Y6S4he4rdnGPBT
Quota information is restricted or not available for this drive.
...

When this is viewed locally, on Linux, this shared folder is seen as the following:

Any shared file link you add can utilise any 'client side filtering' rules that you have created.

Syncing OneDrive Business Shared Files using Option 2 Copy Section

[!IMPORTANT]
When using option 2, all files that have been shared with you will be downloaded by default. To reduce this, first use --list-shared-items to list all shared items with your account, then use 'client side filtering' rules such as 'sync_list' configuration to selectively sync all the files to your local system.

1. Review all items that have been shared with you by using onedrive --list-shared-items. This should display output similar to the following:

/* Detailed source-code truncated for AI context efficiency. */

2. If applicable, add entries to a 'sync_list' file, to only sync the shared files that are of importance to you.

3. Run the command onedrive --sync --verbose --sync-shared-files to sync the shared files to your local file system. This will create a new local folder called 'Files Shared With Me', and will contain sub-directories named after the entity account that has shared the file with you. In that folder will reside the shared file:

/* Detailed source-code truncated for AI context efficiency. */

When this is viewed locally, on Linux, this 'Files Shared With Me' and content is seen as the following:

Unfortunately there is no Microsoft Windows equivalent for this capability.

Known Issues Copy Chapter

Shared folders, shared with you from people outside of your 'organisation' are unable to be synced. This is due to the Microsoft Graph API not presenting these folders.

Shared folders that match this scenario, when you view 'Shared' via OneDrive online, will have a 'world' symbol as per below:

This issue is being tracked by: #966

File: docs/client-architecture.md Copy Chapter

OneDrive Client for Linux Application Architecture

How does the client work at a high level? Copy Chapter

The client utilises the 'libcurl' library to communicate with Microsoft OneDrive via the Microsoft Graph API. The diagram below shows this high level interaction with the Microsoft and GitHub API services online:

Depending on your operational environment, it is possible to 'tweak' the following options which will modify how libcurl operates with it's interaction with Microsoft OneDrive services:

• Downgrade all HTTPS operations to use HTTP1.1 (Config Option: force_http_11)
• Control how long a specific transfer should take before it is considered too slow and aborted (Config Option: operation_timeout)
• Control libcurl handling of DNS Cache Timeout (Config Option: dns_timeout)
• Control the maximum time allowed for the connection to be established (Config Option: connect_timeout)
• Control the timeout for activity on an established HTTPS connection (Config Option: data_timeout)
• Control what IP protocol version should be used when communicating with OneDrive (Config Option: ip_protocol_version)
• Control what User Agent is presented to Microsoft services (Config Option: user_agent)

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

Diving a little deeper into how the client operates, the diagram below outlines at a high level the operational workflow of the OneDrive Client for Linux, demonstrating how it interacts with the OneDrive API to maintain synchronisation, manage local and cloud data integrity, and ensure that user data is accurately mirrored between the local filesystem and OneDrive cloud storage.

The application operational processes have several high level key stages:

1. Access Token Validation: Initially, the client validates its access and the existing access token, refreshing it if necessary. This step ensures that the client has the required permissions to interact with the OneDrive API.

2. Query Microsoft OneDrive API: The client queries the /delta API endpoint of Microsoft OneDrive, which returns JSON responses. The /delta endpoint is particularly used for syncing changes, helping the client to identify any updates in the OneDrive storage.

3. Process JSON Responses: The client processes each JSON response to determine if it represents a 'root' or 'deleted' item. Items not marked as 'root' or 'deleted' are temporarily stored for further processing. For 'root' or 'deleted' items, the client processes them immediately, otherwise, the client evaluates the items against client-side filtering rules to decide whether to discard them or to process and save them in the local database cache for actions like creating directories or downloading files.

4. Local Cache Database Processing for Data Integrity: The client processes its local cache database to validate known local state against the local filesystem and Microsoft OneDrive metadata. This stage helps detect state inconsistencies and ensures that the client has an accurate view of items already known to the application. Upload decisions for new local content are handled separately by the local filesystem scan.

5. Local Filesystem Scanning: The client scans the local filesystem for new files or folders. Each new item is checked against client-side filtering rules. If an item passes the filtering, it is uploaded to OneDrive. Otherwise, it is discarded if it doesn't meet the filtering criteria.

6. Final Data True-Up: Lastly, the client queries the /delta link for a final true-up, processing any further online JSON changes if required. This ensures that the local and OneDrive storages are fully synchronised.

What are the operational modes of the client? Copy Chapter

There are 2 main operational modes that the client can utilise:

1. Standalone sync mode that performs a single sync action against Microsoft OneDrive. This method is used when you utilise --sync.
2. Ongoing sync mode that continuously syncs your data with Microsoft OneDrive and utilises 'inotify' to watch for local system changes. This method is used when you utilise --monitor.

By default, both sync modes (--sync and --monitor)treat the data stored online in Microsoft OneDrive as the 'source-of-truth'. This means the client will first examine your OneDrive account for any changes (additions, modifications, deletions) and apply those changes to your local file system. After this, any local changes are uploaded, and finally, a second check ensures your local state matches the online state. This mirrors the behaviour of the Microsoft OneDrive Client for Windows.

When using the client with the --local-first option, the sync flow is reversed. The client treats your local files as the 'source-of-truth'. Local changes are processed first and pushed to Microsoft OneDrive online. Only after local changes have been uploaded will the client check for any remote changes (this includes online additions, modifications and deletions) and apply those to your local system as needed, ensuring the final local state is consistent with that what is now online.

[!IMPORTANT]
When using --sync --local-first, a locally deleted file will only be deleted online if it was already in sync with its online counterpart.

• If the file was never synced, the client cannot know that the corresponding online file should be removed. In this case, the online file may be downloaded again
• Using --resync makes this behaviour more likely because it wipes all local knowledge of what was previously synced, so local deletions will not be recognised

When using --monitor --local-first, file system watches (via inotify) will detect local deletions. This event will automatically trigger removal of the online file, and if exists and matches the local data, the file online will be removed.

[!IMPORTANT]
Using a network mount point such as NFS, CIFS, SMB, Windows Network Share or Samba Network Share as your sync_dir has significant change-detection and performance implications.

These network-backed filesystems should be treated as not providing reliable or complete inotify support for this client. inotify support is essential for Monitor Mode to detect local filesystem changes in real time.

Some network mount configurations may generate inotify events for changes made by the same host that is running this client. For example, creating or modifying a file from the local machine against a mounted CIFS/SMB share may appear to work when tested with tools such as inotifywait.

However, this does not mean the network mount provides reliable inotify behaviour for synchronisation purposes. Changes made directly on the NAS (such as Synology File Station or similar), file server, Windows share host, or from another device or client accessing the same share may not generate any inotify events on the host running this client. In those cases, the client receives no immediate local filesystem notification at all.

In this configuration, synchronisation between the local filesystem and Microsoft OneDrive must rely on scheduled monitor sync cycles controlled by monitor_interval, rather than immediate local filesystem event detection.

On very large sync trees this can be expensive, because the local database consistency check and local filesystem scan must validate state across the mounted filesystem. Network-backed filesystems are often significantly slower than local disks for metadata-heavy operations.

This limitation is caused by network filesystem and operating system notification behaviour, and is outside the control of this client.

For large datasets, local storage is strongly preferred. If a network-backed sync_dir is required, test Monitor Mode behaviour, inotifywait behaviour, and scan duration carefully before relying on it for unattended operation.

OneDrive Client for Linux High Level Activity Flows Copy Chapter

The diagrams below show the high level process flow and decision making when running the application

Main functional activity flows Copy Section

Processing a potentially new local item Copy Section

Processing a potentially changed local item Copy Section

Download a file from Microsoft OneDrive Copy Section

Upload a modified file to Microsoft OneDrive Copy Section

Upload a new local file to Microsoft OneDrive Copy Section

Determining if an 'item' is synchronised between Microsoft OneDrive and the local file system Copy Section

Determining if an 'item' is excluded due to 'Client Side Filtering' rules Copy Section

By default, the OneDrive Client for Linux will sync all files and folders between Microsoft OneDrive and the local filesystem.

Client Side Filtering in the context of this client 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:

• 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_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.

This exclusion process can be illustrated by the following activity diagram. A 'true' return value means that the path being evaluated needs to be excluded:

Understanding how the client processes online state Copy Chapter

When you see Fetching items from the OneDrive API for Drive ID: or Generating a /delta response from the OneDrive API for this Drive ID: the client isn’t stuck—it’s working through paged change sets from Microsoft Graph using your current delta token, reconciling them with the local database, and safely scheduling work. Microsoft Graph returns paged results and signals either @odata.nextLink (more pages to fetch) or @odata.deltaLink (caught up; keep this token for next time) - the client follows those links until it reaches a stable point. Page sizing and paging behaviour are controlled by the Microsoft Graph API service.

The client performs several different reconciliation activities during a sync cycle. These should not all be described as a "full scan". An online full-scan true-up, a local database consistency check and a local filesystem scan are separate activities with different purposes.

What a typical cycle looks like Copy Section

1. Fetching online state
   • Application Output: Fetching items from the OneDrive API for Drive ID: … or Generating a /delta response from the OneDrive API for this Drive ID:
   • The client normally requests the next page of changes using the current Microsoft Graph /delta token.
   • If an online full-scan true-up is required, the client deliberately does not use the stored /delta token for that pass.
2. Processing received items
   • Application Output: Processing N applicable changes and items received from Microsoft OneDrive
   • Each item received is classified (add/update/delete/excluded), matched against local state, and queued for action.
3. Execute required actions
   • Download new or modified files, delete local data that has been deleted online, and create new local directories.
4. Database Integrity
   • Application Output: Performing a database consistency and integrity check on locally stored data
   • This validates the local database state against the local filesystem to prevent state corruption.
   • This is a local database/filesystem validation pass. It is not the same as an online full-scan true-up.
5. Local scan for new local data
   • Application Output: Scanning the local file system '…' for new data to upload
   • Traverse the local filesystem, honouring client side filtering rules, to identify new local data that may need to be uploaded.
6. True-Up
   • Application Output: Performing a last examination of the most recent online data within Microsoft OneDrive to complete the reconciliation process
   • Final online examination to ensure that recent Microsoft OneDrive state has been reconciled.

Monitor mode full-scan cadence Copy Section

In --monitor mode, synchronisation can be triggered by more than one source:

• the configured monitor_interval has elapsed;
• a local filesystem event has been detected by the monitor engine;
• a Microsoft OneDrive API signal has been received via WebSocket or webhook support.

monitor_interval controls the scheduled idle sync interval. It does not prevent a sync from occurring earlier when a local filesystem event or Microsoft OneDrive API signal is received.

monitor_fullscan_frequency controls the scheduled online full-scan true-up cadence in --monitor mode. It does not disable the local database consistency and integrity check, and it does not disable the local filesystem scan used to identify local data that may need to be uploaded.

The following log message refers to local database/filesystem validation, not an online full-scan true-up:

Performing a database consistency and integrity check on locally stored data

To confirm whether an online full-scan true-up is occurring, use debug logging and check for messages such as:

Full Scan Frequency Loop Number: ...
Perform a Full Scan True-Up: true|false
Performing a full scan of online data to ensure consistent local state
Using database stored deltaLink
Using cached deltaLink

Why first runs or --resync take longer Copy Section

A first run (or a deliberate --resync) must enumerate the entire tree to establish a known-good baseline; subsequent incremental runs are much faster because the delta token limits work to just the changes since last time.

What affects performance the most Copy Section

• Item count & Online structure: Many folders and files dominate metadata work leading to more metadata churn
• Network: Latency and throughput directly affect how quickly we can iterate Microsoft Graph API responses and transfer content.
• Local Disk & filesystem: SSDs perform metadata and DB work far faster than spinning disks or remote mounts. Your filesystem type (e.g., ext4, XFS, ZFS) matters and should be tuned appropriately.
• Network-backed sync_dir: NFS, CIFS, SMB, Windows Network Share and Samba Network Share mounts can be slow for metadata-heavy operations and should be treated as not providing usable inotify support for this client.
• File Indexing: Disable File Indexing (Tracker, Baloo, Searchmonkey, Pinot and others) as these are adding latency and disk I/O to your operations slowing down your performance.
• CPU & memory: Classification and hashing are CPU-bound; insufficient RAM or swap can slow DB and traversal work.

Delta Response vs Generated Delta Response Copy Chapter

By default, the client uses Microsoft Graph’s /delta to retrieve changes efficiently. In a few situations, however, using /delta would be wrong or unsafe for your intent. In those cases the client generates a delta by walking the relevant online subtree and synthesising the current state before reconciling it locally. This is intentionally slower but correct.

When the client deliberately generates a delta Copy Section

• Some national cloud deployments where a needed delta endpoint/feature isn’t available. Capabilities differ by resource and cloud; when a required delta isn’t available, we walk the tree and synthesise the change set.
• The use of --single-directory scope. A naïve drive-level /delta can include changes outside your intended scope. Generating a delta ensures only the in-scope subtree is considered.
• The use of --download-only --cleanup-local-files. Raw /delta may replay online delete/replace churn that would remove valid local files you intend to keep. The client therefore uses generated delta for authoritative cleanup passes. In --monitor mode, the authoritative cadence is controlled by monitor_authoritative_sync and may defer local delete cleanup between authoritative passes.
• The use of 'Shared Folders'. Calling /delta on a shared path can be rooted at the owner’s drive, so your filters may not match what you see as “the shared folder”. Generated delta walks the shared subtree and normalises paths so the queue reflects what’s truly shared with you.

File conflict handling - default operational modes Copy Chapter

When using the default operational modes (--sync or --monitor) the client reconciles Microsoft OneDrive changes with the local filesystem while protecting unique local file content from being silently displaced.

The local database provides the last known in-sync baseline for a tracked file. When an online replacement is available, the client evaluates three states at the replacement commit boundary:

• the current canonical local file
• the last known in-sync database record, when one exists
• the incoming authoritative online file

A replacement-style safeBackup is required only when the canonical local file contains content that is different from both the incoming online file and the last known in-sync database baseline. If the local file still matches the database baseline, it has not been independently modified and can be replaced without a safeBackup. If the local content already matches the incoming online content, no safeBackup is required.

When --resync is used, the previous database state is intentionally discarded. This means the client cannot use the old database baseline to decide whether a same-path local file contains unique data. The online state is authoritative, but --resync itself does not create a safeBackup. If the local file content already matches the online content, the database and metadata are rebuilt without creating a safeBackup or replacing identical bytes. If the local content differs from the online content, the local file is preserved before the authoritative online version is committed.

Transactional safeBackup preservation Copy Section

For normal replacement/conflict workflows, the client keeps the canonical pathname present until the replacement is ready:

1. Download the online replacement to <canonical>.partial.
2. Validate the HTTP result and downloaded content.
3. Re-evaluate the canonical local file immediately before commit.
4. If unique local content must be preserved, create a verified safeBackup copy while leaving the canonical file in place.
5. Recheck that the canonical file did not change during preservation.
6. Atomically promote the validated .partial file to the canonical pathname.

If download, validation, preservation, or final promotion fails, the existing canonical file is retained. A required safeBackup failure prevents the replacement from being committed.

The intentional exception is an online deletion where the tracked local file has independently changed since the last in-sync state. There is no online replacement in that workflow, so the modified local file is renamed to safeBackup and the online deletion is honoured.

[!IMPORTANT]
In v2.5.3 and above, preserved files use the following naming pattern:

filename-hostname-safeBackup-number.file_extension

For example:

text Copy

-rw-------.  1 alex alex 53402 Sep 21 08:25 file5.data
-rw-------.  1 alex alex 53423 Nov 13 18:18 file5-onedrive-client-dev-safeBackup-0001.data
-rw-------.  1 alex alex 53422 Nov 13 18:19 file5-onedrive-client-dev-safeBackup-0002.data

If an existing same-device safeBackup already matches the current canonical file content and metadata, the client can reuse that preservation rather than creating another numbered duplicate.

In client versions v2.5.2 and below, preserved conflict files used the older naming convention:

filename-hostname-number.file_extension

resulting in backup filenames of the following format:

text Copy

-rw-------.  1 alex alex 53402 Sep 21 08:25 file5.data
-rw-------.  1 alex alex 53432 Nov 14 05:22 file5-onedrive-client-dev-2.data
-rw-------.  1 alex alex 53435 Nov 14 05:24 file5-onedrive-client-dev-3.data
-rw-------.  1 alex alex 53419 Nov 14 05:22 file5-onedrive-client-dev.data

[!CAUTION]
Conflict preservation can be disabled with bypass_data_preservation:

text Copy

bypass_data_preservation = "true"

When enabled, the client does not create a safeBackup where preservation would normally be required. Local data may therefore be overwritten or removed during reconciliation. Use with extreme care and caution.

[!TIP]
If safeBackup files should remain local rather than being uploaded to Microsoft OneDrive, use skip_file, for example:

text Copy

skip_file = "~*|.~*|*.tmp|*.swp|*.partial|*-safeBackup-*"

This retains the application defaults and adds an exclusion for generated safeBackup files.

Default Operational Modes - Conflict Handling Copy Section

Scenario

1. Create a local file
2. Perform a sync with Microsoft OneDrive using onedrive --sync
3. Modify file online
4. Modify file locally with different data|contents
5. Perform a sync with Microsoft OneDrive using onedrive --sync

Evidence of Conflict Handling

/* Detailed source-code truncated for AI context efficiency. */

Default Operational Modes - Conflict Handling with --resync Copy Section

Scenario

1. Create a local file
2. Perform a sync with Microsoft OneDrive using onedrive --sync
3. Modify file online
4. Modify file locally with different data|contents
5. Perform a sync with Microsoft OneDrive using onedrive --sync --resync

Evidence of Conflict Handling

/* Detailed source-code truncated for AI context efficiency. */

File conflict handling - local-first operational mode Copy Chapter

When using --local-first as your operational parameter the client application is now using your local filesystem data as the 'source-of-truth' as to what should be stored online.

However, Microsoft OneDrive has no concept of the client's local_first policy. When a locally modified file collides with a newer different online version, the client must preserve the local bytes before resolving the online conflict. Replacement-style preservation uses a verified safeBackup copy while keeping the canonical pathname present until the replacement is ready.

Additionally, when using --resync you are deleting the known application state, thus, the application has zero reference as to what was previously in sync with the local file system.

When --resync is also used, the previous local database baseline is discarded. The current online object is authoritative for same-path conflicts, including when --local-first is configured; however, identical local and online content is reconciled without creating a safeBackup.

Local First Operational Modes - Conflict Handling Copy Section

Scenario

1. Create a local file
2. Perform a sync with Microsoft OneDrive using onedrive --sync --local-first
3. Modify file locally with different data|contents
4. Modify file online with different data|contents
5. Perform a sync with Microsoft OneDrive using onedrive --sync --local-first

Evidence of Conflict Handling

/* Detailed source-code truncated for AI context efficiency. */

Local First Operational Modes - Conflict Handling with --resync Copy Section

Scenario

1. Create a local file
2. Perform a sync with Microsoft OneDrive using onedrive --sync --local-first
3. Modify file locally with different data|contents
4. Modify file online with different data|contents
5. Perform a sync with Microsoft OneDrive using onedrive --sync --local-first --resync

Evidence of Conflict Handling

/* Detailed source-code truncated for AI context efficiency. */

Client Functional Component Architecture Relationships Copy Chapter

The diagram below shows the main functional relationship of application code components, and how these relate to each relevant code module within this application:

Database Schema Copy Chapter

The diagram below shows the database schema that is used within the application

File: docs/contributing.md Copy Chapter

OneDrive Client for Linux: Coding Style Guidelines

Introduction Copy Chapter

This document outlines the coding style guidelines for code contributions for the OneDrive Client for Linux.

These guidelines are intended to ensure the codebase remains clean, well-organised, and accessible to all contributors, new and experienced alike.

Code Layout Copy Chapter

[!NOTE]
When developing any code contribution, please utilise either Microsoft Visual Studio Code or Notepad++.

Indentation Copy Section

Most of the codebase utilises tabs for space indentation, with 4 spaces to a tab. Please keep to this convention.

Line Length Copy Section

Try and keep line lengths to a reasonable length. Do not constrain yourself to short line lengths such as 80 characters. This means when the code is being displayed in the code editor, lines are correctly displayed when using screen resolutions of 1920x1080 and above.

If you wish to use shorter line lengths (80 characters for example), please do not follow this sort of example:

...
	void functionName(
		string somevar,
		bool someOtherVar,
		cost(char) anotherVar=null
	){
....

Coding Style | Braces Copy Section

Please use 1TBS (One True Brace Style) which is a variation of the K&R (Kernighan & Ritchie) style. This approach is intended to improve readability and maintain consistency throughout the code.

When using this coding style, even when the code of the if, else, for, or function definition contains only one statement, braces are used to enclose it.

// What this if statement is doing
	if (condition) {
		// The condition was true
		.....
	} else {
		// The condition was false
		.....
	}

	// Loop 10 times to do something
	for (int i = 0; i < 10; i++) {
		// Loop body
	}

	// This function is to do this
	void functionExample() {
		// Function body
	}

Naming Conventions Copy Chapter

Variables and Functions Copy Section

Please use camelCase for variable and function names.

Classes and Interfaces Copy Section

Please use PascalCase for classes, interfaces, and structs.

Constants Copy Section

Use uppercase with underscores between words.

Documentation Copy Chapter

Language and Spelling Copy Section

To maintain consistency across the project's documentation, comments, and code, all written text must adhere to British English spelling conventions, not American English. This requirement applies to all aspects of the codebase, including variable names, comments, and documentation.

For example, use "specialise" instead of "specialize", "colour" instead of "color", and "organise" instead of "organize". This standard ensures that the project maintains a cohesive and consistent linguistic style.

Code Comments Copy Section

Please comment code at all levels. Use // for all line comments. Detail why a statement is needed, or what is expected to happen so future readers or contributors can read through the intent of the code with clarity.

If fixing a 'bug', please add a link to the GitHub issue being addressed as a comment, for example:

...
	// Before discarding change - does this ID still exist on OneDrive - as in IS this 
	// potentially a --single-directory sync and the user 'moved' the file out of the 'sync-dir' to another OneDrive folder
	// This is a corner edge case - https://github.com/skilion/onedrive/issues/341

	// What is the original local path for this ID in the database? Does it match 'syncFolderChildPath'
	if (itemdb.idInLocalDatabase(driveId, item["id"].str)){
		// item is in the database
		string originalLocalPath = computeItemPath(driveId, item["id"].str);
...

All code should be clearly commented.

Application Logging Output Copy Section

If making changes to any application logging output, please first discuss this either via direct communication or email.

For reference, below are the available application logging output functions and examples:

// most used
	addLogEntry("Basic 'info' message", ["info"]); .... or just use addLogEntry("Basic 'info' message");
	addLogEntry("Basic 'verbose' message", ["verbose"]);
	addLogEntry("Basic 'debug' message", ["debug"]);
	
	// GUI notify only
	addLogEntry("Basic 'notify' ONLY message and displayed in GUI if notifications are enabled", ["notify"]);
	
	// info and notify
	addLogEntry("Basic 'info and notify' message and displayed in GUI if notifications are enabled", ["info", "notify"]);
	
	// log file only
	addLogEntry("Information sent to the log file only, and only if logging to a file is enabled", ["logFileOnly"]);
	
	// Console only (session based upload|download)
	addLogEntry("Basic 'Console only with new line' message", ["consoleOnly"]);
	
	// Console only with no new line
	addLogEntry("Basic 'Console only with no new line' message", ["consoleOnlyNoNewLine"]);

Documentation Updates Copy Section

If the code changes any of the functionality that is documented, it is expected that any PR submission will also include updating the respective section of user documentation and/or man page as part of the code submission.

Development Testing Copy Chapter

Whilst there are more modern D compilers available, ensuring client build compatibility with older platforms is a key requirement.

The issue stems from Debian and Ubuntu LTS versions - such as Ubuntu 20.04. It's ldc package is only v1.20.1 , thus, this is the minimum version that all compilation needs to be tested against.

The reason LDC v1.20.1 must be used, is that this is the version that is used to compile the packages presented at OpenSuSE Build Service - which is where most Debian and Ubuntu users will install the client from.

It is assumed here that you know how to download and install the correct LDC compiler for your platform.

Submitting a PR Copy Chapter

When submitting a PR, please provide your testing evidence in the PR submission of what has been fixed, in the format of:

Without PR Copy Section

Application output that is doing whatever | or illustration of issue | illustration of bug

With PR Copy Section

Application output that is doing whatever | or illustration of issue being fixed | illustration of bug being fixed

Please also include validation of compilation using the minimum LDC package version.

To assist with your testing validation against the minimum LDC compiler version, a script as per below could assist you with this validation:

#!/bin/bash
  
PR=<Your_PR_Number>

rm -rf ./onedrive-pr${PR}
git clone https://github.com/abraunegg/onedrive.git onedrive-pr${PR}
cd onedrive-pr${PR}
git fetch origin pull/${PR}/head:pr${PR}
git checkout pr${PR}

# MIN LDC Version to compile
# MIN Version for ARM / Compiling with LDC
source ~/dlang/ldc-1.20.1/activate

# Compile code with specific LDC version
./configure --enable-debug --enable-notifications; make clean; make;
deactivate
./onedrive --version

Optional GitHub Actions smoke testing Copy Section

The smoke-test workflow validates simple monitor-mode behaviour including clean shutdown against a disposable OneDrive Personal test account.

This workflow requires the following GitHub Environment secret:

• Environment name: smoke-test
• Secret name: SMOKE_PERSONAL_REFRESH_TOKEN

For security reasons, GitHub does not provide repository secrets to workflows triggered from forked pull requests. External contributors who want to run this smoke test must configure this secret in their own fork. The refresh token must be treated as a credential and must only be generated from a disposable test account.

To configure this in your fork:

1. Create a disposable OneDrive Personal test account.
2. Authenticate the client manually.
3. Copy the contents of the generated refresh_token file.
4. In GitHub, create an Environment called smoke-test.
5. Add an Environment secret named SMOKE_PERSONAL_REFRESH_TOKEN.
6. Re-run the smoke-test workflow in your fork.

If this secret is not available, the smoke-test workflow is skipped for forked pull requests.

References Copy Chapter

• D Language Official Style Guide: https://dlang.org/dstyle.html
• British English spelling conventions: https://www.collinsdictionary.com/

File: docs/docker.md Copy Chapter

Run the OneDrive Client for Linux under Docker

This client can be run as a Docker container, with 3 available container base options for you to choose from:

These containers offer a simple monitoring-mode service for the OneDrive Client for Linux.

The instructions below have been validated on:

• Fedora 40

The instructions below will utilise the 'edge' tag, however this can be substituted for any of the other docker tags such as 'latest' from the table above if desired.

The 'edge' Docker Container will align closer to all documentation and features, where as 'latest' is the release version from a static point in time. The 'latest' tag however may contain bugs and/or issues that will have been fixed, and those fixes are contained in 'edge'.

Additionally there are specific version release tags for each release. Refer to https://hub.docker.com/r/driveone/onedrive/tags for any other Docker tags you may be interested in.

[!NOTE]
The below instructions for docker has been tested and validated when logging into the system as an unprivileged user (non 'root' user).

High Level Configuration Steps Copy Chapter

1. Install 'docker' as per your distribution platform's instructions if not already installed.
2. Configure 'docker' to allow non-privileged users to run Docker commands
3. Disable 'SELinux' as per your distribution platform's instructions
4. Test 'docker' by running a test container without using sudo
5. Prepare the required docker volumes to store the configuration and data
6. Run the 'onedrive' container and perform authorisation
7. Running the 'onedrive' container under 'docker'

Configuration Steps Copy Chapter

1. Install 'docker' on your platform Copy Section

Install Docker for your system using the official instructions found at https://docs.docker.com/engine/install/.

[!CAUTION]
If you are using Ubuntu or any distribution based on Ubuntu, do not install Docker from your distribution's repositories, as they may contain obsolete versions. Instead, you must install Docker using the packages provided directly by Docker.

2. Configure 'docker' to allow non-privileged users to run Docker commands Copy Section

Read https://docs.docker.com/engine/install/linux-postinstall/ to configure the 'docker' user group with your user account to allow your non 'root' user to run 'docker' commands.

3. Disable SELinux on your platform Copy Section

In order to run the Docker container, SELinux must be disabled. Without doing this, when the application is authenticated in the steps below, the following error will be presented:

ERROR: The local file system returned an error with the following message:
  Error Message:    /onedrive/conf/refresh_token: Permission denied

The database cannot be opened. Please check the permissions of ~/.config/onedrive/items.sqlite3

The only known work-around for the above problem at present is to disable SELinux. Please refer to your distribution platform's instructions on how to perform this step.

• Fedora: https://docs.fedoraproject.org/en-US/quick-docs/selinux-changing-states-and-modes/#_disabling_selinux
• Red Hat Enterprise Linux: https://access.redhat.com/solutions/3176

Post disabling SELinux and reboot your system, confirm that getenforce returns Disabled:

$ getenforce
Disabled

If you are still experiencing permission issues despite disabling SELinux, please read https://www.redhat.com/sysadmin/container-permission-denied-errors

4. Test 'docker' on your platform Copy Section

Ensure that 'docker' is running as a system service, and is enabled to be activated on system reboot:

sudo systemctl enable --now docker

Test that 'docker' is operational for your 'non-root' user, as per below:

[alex@fedora-40-docker-host ~]$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
719385e32844: Pull complete 
Digest: sha256:88ec0acaa3ec199d3b7eaf73588f4518c25f9d34f58ce9a0df68429c5af48e8d
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

[alex@fedora-40-docker-host ~]$

5. Configure the required docker volumes Copy Section

The 'onedrive' Docker container requires 2 docker volumes to operate:

• Config Volume
• Data Volume

The first volume is the configuration volume that stores all the applicable application configuration + current runtime state. In a non-containerised environment, this normally resides in ~/.config/onedrive - in a containerised environment this is stored in the volume tagged as /onedrive/conf

The second volume is the data volume, where all your data from Microsoft OneDrive is stored locally. This volume is mapped to an actual directory point on your local filesystem and this is stored in the volume tagged as /onedrive/data

5.1 Prepare the 'config' volume

Create the 'config' volume with the following command:

docker volume create onedrive_conf

This will create a docker volume labeled onedrive_conf, where all configuration of your onedrive account will be stored. You can add a custom config file in this location at a later point in time if required.

5.2 Prepare the 'data' volume

Create the 'data' volume with the following command:

docker volume create onedrive_data

This will create a docker volume labeled onedrive_data and will map to a path on your local filesystem. This is where your data from Microsoft OneDrive will be stored. Keep in mind that:

• The owner of this specified folder must not be root
• The owner of this specified folder must have permissions for its parent directory
• Docker will attempt to change the permissions of the volume to the user the container is configured to run as

[!IMPORTANT]
Issues occur when this target folder is a mounted folder of an external system (NAS, SMB mount, USB Drive etc) as the 'mount' itself is owed by 'root'. If this is your use case, you must ensure your normal user can mount your desired target without having the target mounted by 'root'. If you do not fix this, your Docker container will fail to start with the following error message:

bash Copy

ROOT level privileges prohibited!

6. First run of Docker container under docker and performing authorisation Copy Section

The 'onedrive' client within the container first needs to be authorised with your Microsoft account. This is achieved by initially running docker in interactive mode.

Run the docker image with the commands below and make sure to change the value of ONEDRIVE_DATA_DIR to the actual onedrive data directory on your filesystem that you wish to use (e.g. export ONEDRIVE_DATA_DIR="/home/abraunegg/OneDrive").

[!IMPORTANT]
The 'target' folder of ONEDRIVE_DATA_DIR must exist before running the docker container. The script below will create 'ONEDRIVE_DATA_DIR' so that it exists locally for the docker volume mapping to occur.

It is also a requirement that the container be run using a non-root uid and gid, you must insert a non-root UID and GID (e.g. export ONEDRIVE_UID=1000 and export ONEDRIVE_GID=1000). The script below will use id to evaluate your system environment to use the correct values.

export ONEDRIVE_DATA_DIR="${HOME}/OneDrive"
export ONEDRIVE_UID=`id -u`
export ONEDRIVE_GID=`id -g`
mkdir -p ${ONEDRIVE_DATA_DIR}
docker run -it --name onedrive -v onedrive_conf:/onedrive/conf \
    -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" \
    -e "ONEDRIVE_UID=${ONEDRIVE_UID}" \
    -e "ONEDRIVE_GID=${ONEDRIVE_GID}" \
    driveone/onedrive:edge

When the Docker container successfully starts:

• You will be asked to open a specific link using your web browser
• Login to your Microsoft Account and give the application the permission
• After giving the permission, you will be redirected to a blank page
• Copy the URI of the blank page into the application prompt to authorise the application

Once the 'onedrive' application is authorised, the client will automatically start monitoring your ONEDRIVE_DATA_DIR for data changes to be uploaded to OneDrive. Files stored on OneDrive will be downloaded to this location.

If the client is working as expected, you can detach from the container with CTRL+P, CTRL+Q.

6.1. Read-Only / Upload-Only Sync Scenarios

If you are running the Docker container in upload-only mode and want to ensure that the OneDrive client cannot modify the original source files, the data directory must be mounted as read-only.

This is controlled at the container mount level, not by ownership (chown) or permissions (chmod) inside the container.

If this is your desired configuration, you must mount your 'ONEDRIVE_DATA_DIR' with read-only permissions to ensure your data source is immutable and cannot be changed. Augment the above script in the following manner:

export ONEDRIVE_DATA_DIR="${HOME}/OneDrive"
export ONEDRIVE_UID=`id -u`
export ONEDRIVE_GID=`id -g`
mkdir -p ${ONEDRIVE_DATA_DIR}
docker run -it --name onedrive -v onedrive_conf:/onedrive/conf \
    -v "${ONEDRIVE_DATA_DIR}:/onedrive/data:ro" \
    -e "ONEDRIVE_UID=${ONEDRIVE_UID}" \
    -e "ONEDRIVE_GID=${ONEDRIVE_GID}" \
	-e ONEDRIVE_UPLOADONLY=1 \
    driveone/onedrive:edge

[!NOTE]
Essentially, any Docker command where you are mounting your 'ONEDRIVE_DATA_DIR', you need to append :ro to the /onedrive/data specification to ensure your data directory is mounted in Docker as read-only volume.

7. Running the 'onedrive' container under 'docker' Copy Section

7.1 Check if the monitor service is running

docker ps -f name=onedrive

7.2 Show 'onedrive' runtime logs

docker logs onedrive

7.3 Stop running 'onedrive' container

docker stop onedrive

7.4 Start 'onedrive' container

docker start onedrive

7.5 Remove 'onedrive' container

docker rm -f onedrive

Customising OneDrive Runtime Behaviour in Docker Copy Section

When running the OneDrive client inside Docker, the container always starts via entrypoint.sh, which ensures that the following arguments are added automatically:

--confdir /onedrive/conf --syncdir /onedrive/data

This design guarantees that:

• Your configuration files persist in the /onedrive/conf volume.
• Your synchronised data persists in the /onedrive/data volume.
• The container behaves consistently across hosts, upgrades, and architectures.

Because these arguments are always supplied, any sync_dir or confdir values defined in the configuration file are overridden at runtime by design. This avoids confusion and ensures predictable behaviour. These specific paths are the bind-mounts between container and host and should not be changed manually.

Default Docker volume behaviour

By default, Docker bind mounts and volumes are mounted read-write inside the container. This means that, unless explicitly restricted, the container process may create, modify, rename, or delete files within the mounted directory, subject to normal filesystem permissions.

Using read-only mounts

If you want to prevent the container from modifying the mounted data (for example, in upload-only or backup-style scenarios), the bind mount must be explicitly marked as read-only using the :ro mount option. A read-only mount enforces immutability at the container boundary and cannot be overridden from inside the container, regardless of ownership or permissions.

Supported ways to customise runtime behaviour Copy Section

There are two supported mechanisms for adjusting how the client runs inside Docker:

1. Docker environment variables
   Many client options are exposed as environment variables in a reproducible way. For example:

   shell Copy

   -e ONEDRIVE_DOWNLOADONLY=1
   -e ONEDRIVE_SYNC_ONCE=1
   -e ONEDRIVE_VERBOSE=1

   See the full list here:
   👉 Supported Docker environment variables

2. Configuration file inside /onedrive/conf
   For permanent or advanced options not covered by environment variables, you can create or edit the client configuration file in the mounted config directory.
   Documentation:
   👉 Editing the running configuration and using a config file

[!IMPORTANT]
Do not manually add --syncdir or --confdir when overriding the container command.

If you do:

• You bypass the entrypoint.sh logic that manages UID/GID mapping, privilege dropping, and environment translation.
• You risk syncing data to the wrong location (~/OneDrive inside the container) or creating incorrect file ownership on the host.

Instead:

• Use existing Docker environment variables for controling specific application functionality.
• Use a config file and or 'sync_list' file inside /onedrive/conf for advanced configuration.

How to use Docker-compose Copy Section

You can utilise docker-compose if available on your platform if you are able to use docker compose schemas > 3.

In the following example it is assumed you have a ONEDRIVE_DATA_DIR environment variable and have already created the onedrive_conf volume.

You can also use docker bind mounts for the configuration folder, e.g. export ONEDRIVE_CONF="${HOME}/OneDriveConfig".

version: "3"
services:
    onedrive:
        image: driveone/onedrive:edge
        restart: unless-stopped
        environment:
            - ONEDRIVE_UID=${PUID}
            - ONEDRIVE_GID=${PGID}
        volumes: 
            - onedrive_conf:/onedrive/conf
            - ${ONEDRIVE_DATA_DIR}:/onedrive/data

[!IMPORTANT]
Before you run the container using your compose file you must first authenticate the client following step 6 above.
Failure to perform this step before running your container using your compose file will see your container detail that an invalid response uri was entered.

Editing the running configuration and using a 'config' file Copy Section

The 'onedrive' client should run in default configuration, however you can change this default configuration by placing a custom config file in the onedrive_conf docker volume. First download the default config from here
Then put it into your onedrive_conf volume path, which can be found with:

docker volume inspect onedrive_conf

Or you can map your own config folder to the config volume. Make sure to copy all files from the docker volume into your mapped folder first.

The detailed document for the config can be found here: Application Configuration Options for the OneDrive Client for Linux

Syncing multiple accounts Copy Section

There are many ways to do this, the easiest is probably to do the following:

1. Create a second docker config volume (replace Work with your desired name): docker volume create onedrive_conf_Work
2. And start a second docker monitor container (again replace Work with your desired name):

export ONEDRIVE_DATA_DIR_WORK="/home/abraunegg/OneDriveWork"
mkdir -p ${ONEDRIVE_DATA_DIR_WORK}
docker run -it --restart unless-stopped --name onedrive_Work -v onedrive_conf_Work:/onedrive/conf -v "${ONEDRIVE_DATA_DIR_WORK}:/onedrive/data" driveone/onedrive:edge

Run or update the Docker container with one script Copy Section

If you are experienced with docker and onedrive, you can use the following script:

# Update ONEDRIVE_DATA_DIR with correct OneDrive directory path
ONEDRIVE_DATA_DIR="${HOME}/OneDrive"
# Create directory if non-existent
mkdir -p ${ONEDRIVE_DATA_DIR} 

firstRun='-d'
docker pull driveone/onedrive:edge
docker inspect onedrive_conf > /dev/null 2>&1 || { docker volume create onedrive_conf; firstRun='-it'; }
docker inspect onedrive > /dev/null 2>&1 && docker rm -f onedrive
docker run $firstRun --restart unless-stopped --name onedrive -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Supported Docker Environment Variables Copy Chapter

Environment Variables Usage Examples Copy Section

Verbose Output:

docker container run -e ONEDRIVE_VERBOSE=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Debug Output:

docker container run -e ONEDRIVE_DEBUG=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a --resync:

docker container run -e ONEDRIVE_RESYNC=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a --resync and --verbose:

docker container run -e ONEDRIVE_RESYNC=1 -e ONEDRIVE_VERBOSE=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a --logout:

docker container run -it -e ONEDRIVE_LOGOUT=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a --logout and re-authenticate:

docker container run -it -e ONEDRIVE_REAUTH=1 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a sync using ONEDRIVE_SINGLE_DIRECTORY:

docker container run -e ONEDRIVE_SINGLE_DIRECTORY="path/which/needs/to/be/synced" -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

Perform a sync specifying UID and GID:

docker container run -e ONEDRIVE_UID=9999 -e ONEDRIVE_GID=9999 -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" driveone/onedrive:edge

[!IMPORTANT]
Is using a Docker Environment Variable that requires you to specify a 'path' (ONEDRIVE_AUTHFILES, ONEDRIVE_AUTHRESPONSE, ONEDRIVE_SINGLE_DIRECTORY), the placement of quotes around the path is critically important.

Please ensure you are formatting the option correctly:

text Copy

-e OPTION="path/which/needs/to/be/synced"

Please also ensure that the path specified complies with the actual application usage argument. Please read the relevant config option advice in the CLI Option Documentation

Building a custom Docker image Copy Chapter

Build Environment Requirements Copy Section

• Build environment must have at least 1GB of memory & 2GB swap space

You can validate your build environment memory status with the following command:

cat /proc/meminfo | grep -E 'MemFree|Swap'

This should result in the following similar output:

MemFree:         3704644 kB
SwapCached:            0 kB
SwapTotal:       8117244 kB
SwapFree:        8117244 kB

If you do not have enough swap space, you can use the following script to dynamically allocate a swapfile for building the Docker container:

cd /var 
sudo fallocate -l 1.5G swapfile
sudo chmod 600 swapfile
sudo mkswap swapfile
sudo swapon swapfile
# make swap permanent
sudo nano /etc/fstab
# add "/swapfile swap swap defaults 0 0" at the end of file
# check it has been assigned
swapon -s
free -h

If you are running a Raspberry Pi, you will need to edit your system configuration to increase your swapfile:

• Modify the file /etc/dphys-swapfile and edit the CONF_SWAPSIZE, for example: CONF_SWAPSIZE=2048.

[!IMPORTANT]
A reboot of your Raspberry Pi is required to make this change effective.

Building and running a custom Docker image Copy Section

You can also build your own image instead of pulling the one from hub.docker.com:

git clone https://github.com/abraunegg/onedrive
cd onedrive
docker build . -t local-onedrive -f contrib/docker/Dockerfile
docker container run -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" local-onedrive:latest

There are alternate, smaller images available by using Dockerfile-debian or Dockerfile-alpine. These multi-stage builder pattern Dockerfiles require Docker version at least 17.05.

How to build and run a custom Docker image based on Debian Copy Section

docker build . -t local-onedrive-debian -f contrib/docker/Dockerfile-debian
docker container run -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" local-onedrive-debian:latest

How to build and run a custom Docker image based on Alpine Linux Copy Section

docker build . -t local-onedrive-alpine -f contrib/docker/Dockerfile-alpine
docker container run -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" local-onedrive-alpine:latest

How to build and run a custom Docker image for ARMHF (Raspberry Pi) Copy Section

Compatible with:

• Raspberry Pi
• Raspberry Pi 2
• Raspberry Pi Zero
• Raspberry Pi 3
• Raspberry Pi 4

docker build . -t local-onedrive-armhf -f contrib/docker/Dockerfile-debian
docker container run -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" local-onedrive-armhf:latest

How to build and run a custom Docker image for AARCH64 Platforms Copy Section

docker build . -t local-onedrive-aarch64 -f contrib/docker/Dockerfile-debian
docker container run -v onedrive_conf:/onedrive/conf -v "${ONEDRIVE_DATA_DIR}:/onedrive/data" local-onedrive-aarch64:latest

How to support double-byte languages Copy Section

In some geographic regions, you may need to change and/or update the locale specification of the Docker container to better support the local language used for your local filesystem. To do this, follow the example below:

FROM driveone/onedrive

ENV DEBIAN_FRONTEND noninteractive

RUN apt-get update
RUN apt-get install -y locales

RUN echo "ja_JP.UTF-8 UTF-8" > /etc/locale.gen && \
    locale-gen ja_JP.UTF-8 && \
    dpkg-reconfigure locales && \
    /usr/sbin/update-locale LANG=ja_JP.UTF-8

ENV LC_ALL ja_JP.UTF-8

The above example changes the Docker container to support Japanese. To support your local language, change ja_JP.UTF-8 to the required entry.