Add back documentation details after being missed from v2.4.25 -> v2.…

…5.x document changes (#2872) * Add back documentation details after being missed from v2.4.25 -> v2.5.x document changes
abraunegg · Oct 1, 2024 · 6827af9 · 6827af9
1 parent 90556fd
commit 6827af9
Showing 1 changed file with 220 additions and 1 deletion.
diff --git a/docs/usage.md b/docs/usage.md
@@ -15,6 +15,7 @@ Before reading this document, please ensure you are running application version
   - [Understanding OneDrive Client for Linux Operational Modes](#understanding-onedrive-client-for-linux-operational-modes)
     - [Standalone Synchronisation Operational Mode (Standalone Mode)](#standalone-synchronisation-operational-mode-standalone-mode)
     - [Ongoing Synchronisation Operational Mode (Monitor Mode)](#ongoing-synchronisation-operational-mode-monitor-mode)
+- [Using the OneDrive Client for Linux to synchronise your data](#using-the-onedrive-client-for-linux-to-synchronise-your-data)
   - [Increasing application logging level](#increasing-application-logging-level)
   - [Using 'Client Side Filtering' rules to determine what should be synced with Microsoft OneDrive](#using-client-side-filtering-rules-to-determine-what-should-be-synced-with-microsoft-onedrive)
   - [Testing your configuration](#testing-your-configuration)
@@ -59,6 +60,10 @@ Before reading this document, please ensure you are running application version
     - [OneDrive service running as a non-root user via systemd (with notifications enabled) (Arch, Ubuntu, Debian, OpenSuSE, Fedora)](#onedrive-service-running-as-a-non-root-user-via-systemd-with-notifications-enabled-arch-ubuntu-debian-opensuse-fedora)
     - [OneDrive service running as a non-root user via runit (antiX, Devuan, Artix, Void)](#onedrive-service-running-as-a-non-root-user-via-runit-antix-devuan-artix-void)
   - [How to start a user systemd service at boot without user login?](#how-to-start-a-user-systemd-service-at-boot-without-user-login)
+  - [How to access Microsoft OneDrive service through a proxy](#how-to-access-microsoft-onedrive-service-through-a-proxy)
+  - [How to set up SELinux for a sync folder outside of the home folder](#how-to-set-up-selinux-for-a-sync-folder-outside-of-the-home-folder)
+- [Advanced Configuration of the OneDrive Client for Linux](#advanced-configuration-of-the-onedrive-client-for-linux)
+- [Overview of all OneDrive Client for Linux CLI Options](#overview-of-all-onedrive-client-for-linux-cli-options)
 
 ## Important Notes
 
@@ -254,6 +259,8 @@ Once these values are changed, you will need to restart your client so that the
 
 To make these changes permanent on your system, refer to your OS reference documentation.
 
+## Using the OneDrive Client for Linux to synchronise your data
+
 ### Increasing application logging level
 When running a sync (`--sync`) or using monitor mode (`--monitor`), it may be desirable to see additional information regarding the progress and operation of the client. For example, for a `--sync` command, this would be:
 ```text
@@ -1067,4 +1074,216 @@ In some situations, it may be necessary for the systemd service to start without
 To address this issue, you need to reconfigure your 'user' account so that the systemd services you've created launch without the need for you to log in to your system:
 ```text
 loginctl enable-linger <your_user_name>
-```
+```
+
+### How to access Microsoft OneDrive service through a proxy
+If you have a requirement to run the client through a proxy, there are a couple of ways to achieve this:
+
+#### Option 1: Use '.bashrc' to specify the proxy server details
+Set proxy configuration in `~/.bashrc` to allow the 'onedrive' application to use a specific proxy server:
+```text
+# Set the HTTP proxy
+export http_proxy="http://your.proxy.server:port"
+
+# Set the HTTPS proxy
+export https_proxy="http://your.proxy.server:port"
+```
+
+Once you've edited your `~/.bashrc` file, run the following command to apply the changes:
+```
+source ~/.bashrc
+```
+
+#### Option 2: Update the 'systemd' service file to include the proxy server details
+If running as a systemd service, edit the applicable systemd service file to include the proxy configuration information:
+```text
+[Unit]
+Description=OneDrive Client for Linux
+Documentation=https://github.com/abraunegg/onedrive
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+........
+Environment="HTTP_PROXY=http://your.proxy.server:port"
+Environment="HTTPS_PROXY=http://your.proxy.server:port"
+ExecStart=/usr/local/bin/onedrive --monitor
+........
+
+```
+> [!NOTE]
+> After modifying the service files, you will need to run `sudo systemctl daemon-reload` to ensure the service file changes are picked up. A restart of the OneDrive service will also be required to pick up the change to send the traffic via the proxy server
+
+### How to set up SELinux for a sync folder outside of the home folder
+
+If SELinux is enforced and the sync folder is outside of the home folder, as long as there is no policy for cloud file service providers, label the file system folder to `user_home_t`.
+```text
+sudo semanage fcontext -a -t user_home_t /path/to/onedriveSyncFolder
+sudo restorecon -R -v /path/to/onedriveSyncFolder
+```
+To remove this change from SELinux and restore the default behaviour:
+```text
+sudo semanage fcontext -d /path/to/onedriveSyncFolder
+sudo restorecon -R -v /path/to/onedriveSyncFolder
+```
+
+## Advanced Configuration of the OneDrive Client for Linux
+
+Refer to [advanced-usage.md](advanced-usage.md) for further details on the following topics:
+
+* Configuring the client to use multiple OneDrive accounts / configurations
+* Configuring the client to use multiple OneDrive accounts / configurations using Docker
+* Configuring the client for use in dual-boot (Windows / Linux) situations
+* Configuring the client for use when 'sync_dir' is a mounted directory
+* Upload data from the local ~/OneDrive folder to a specific location on OneDrive
+
+## Overview of all OneDrive Client for Linux CLI Options
+Below is a comprehensive list of all available configuration options for the OneDrive Client for Linux, as shown by the output of `onedrive --help`. These commands provide a range of options for synchronising, monitoring, and managing files between your local system and Microsoft's OneDrive cloud service.
+
+The following configuration options are available:
+```text
+onedrive - A client for the Microsoft OneDrive Cloud Service
+
+  Usage:
+    onedrive [options] --sync
+      Do a one time synchronization
+    onedrive [options] --monitor
+      Monitor filesystem and sync regularly
+    onedrive [options] --display-config
+      Display the currently used configuration
+    onedrive [options] --display-sync-status
+      Query OneDrive service and report on pending changes
+    onedrive -h | --help
+      Show this help screen
+    onedrive --version
+      Show version
+
+  Options:
+
+  --auth-files ARG
+      Perform authentication not via interactive dialog but via files read/writes to these files.
+  --auth-response ARG
+      Perform authentication not via interactive dialog but via providing the response url directly.
+  --check-for-nomount
+      Check for the presence of .nosync in the syncdir root. If found, do not perform sync.
+  --check-for-nosync
+      Check for the presence of .nosync in each directory. If found, skip directory from sync.
+  --classify-as-big-delete ARG
+      Number of children in a path that is locally removed which will be classified as a 'big data delete'
+  --cleanup-local-files
+      Cleanup additional local files when using --download-only. This will remove local data.
+  --confdir ARG
+      Set the directory used to store the configuration files
+  --create-directory ARG
+      Create a directory on OneDrive - no sync will be performed.
+  --create-share-link ARG
+      Create a shareable link for an existing file on OneDrive
+  --debug-https
+      Debug OneDrive HTTPS communication.
+  --destination-directory ARG
+      Destination directory for renamed or move on OneDrive - no sync will be performed.
+  --disable-download-validation
+      Disable download validation when downloading from OneDrive
+  --disable-notifications
+      Do not use desktop notifications in monitor mode.
+  --disable-upload-validation
+      Disable upload validation when uploading to OneDrive
+  --display-config
+      Display what options the client will use as currently configured - no sync will be performed.
+  --display-quota
+      Display the quota status of the client - no sync will be performed.
+  --display-running-config
+      Display what options the client has been configured to use on application startup.
+  --display-sync-status
+      Display the sync status of the client - no sync will be performed.
+  --download-only
+      Replicate the OneDrive online state locally, by only downloading changes from OneDrive. Do not upload local changes to OneDrive.
+  --dry-run
+      Perform a trial sync with no changes made
+  --enable-logging
+      Enable client activity to a separate log file
+  --force
+      Force the deletion of data when a 'big delete' is detected
+  --force-http-11
+      Force the use of HTTP 1.1 for all operations
+  --force-sync
+      Force a synchronization of a specific folder, only when using --sync --single-directory and ignore all non-default skip_dir and skip_file rules
+  --get-O365-drive-id ARG
+      Query and return the Office 365 Drive ID for a given Office 365 SharePoint Shared Library (DEPRECATED)
+  --get-file-link ARG
+      Display the file link of a synced file
+  --get-sharepoint-drive-id ARG
+      Query and return the Office 365 Drive ID for a given Office 365 SharePoint Shared Library
+  --help -h
+      This help information.
+  --list-shared-items
+      List OneDrive Business Shared Items
+  --local-first
+      Synchronize from the local directory source first, before downloading changes from OneDrive.
+  --log-dir ARG
+      Directory where logging output is saved to, needs to end with a slash.
+  --logout
+      Logout the current user
+  --modified-by ARG
+      Display the last modified by details of a given path
+  --monitor -m
+      Keep monitoring for local and remote changes
+  --monitor-fullscan-frequency ARG
+      Number of sync runs before performing a full local scan of the synced directory
+  --monitor-interval ARG
+      Number of seconds by which each sync operation is undertaken when idle under monitor mode.
+  --monitor-log-frequency ARG
+      Frequency of logging in monitor mode
+  --no-remote-delete
+      Do not delete local file 'deletes' from OneDrive when using --upload-only
+  --print-access-token
+      Print the access token, useful for debugging
+  --reauth
+      Reauthenticate the client with OneDrive
+  --remove-directory ARG
+      Remove a directory on OneDrive - no sync will be performed.
+  --remove-source-files
+      Remove source file after successful transfer to OneDrive when using --upload-only
+  --resync
+      Forget the last saved state, perform a full sync
+  --resync-auth
+      Approve the use of performing a --resync action
+  --single-directory ARG
+      Specify a single local directory within the OneDrive root to sync.
+  --skip-dir ARG
+      Skip any directories that match this pattern from syncing
+  --skip-dir-strict-match
+      When matching skip_dir directories, only match explicit matches
+  --skip-dot-files
+      Skip dot files and folders from syncing
+  --skip-file ARG
+      Skip any files that match this pattern from syncing
+  --skip-size ARG
+      Skip new files larger than this size (in MB)
+  --skip-symlinks
+      Skip syncing of symlinks
+  --source-directory ARG
+      Source directory to rename or move on OneDrive - no sync will be performed.
+  --space-reservation ARG
+      The amount of disk space to reserve (in MB) to avoid 100% disk space utilisation
+  --sync -s
+      Perform a synchronisation with Microsoft OneDrive
+  --sync-root-files
+      Sync all files in sync_dir root when using sync_list.
+  --sync-shared-files
+      Sync OneDrive Business Shared Files to the local filesystem
+  --syncdir ARG
+      Specify the local directory used for synchronisation to OneDrive
+  --synchronize
+      Perform a synchronisation with Microsoft OneDrive (DEPRECATED)
+  --upload-only
+      Replicate the locally configured sync_dir state to OneDrive, by only uploading local changes to OneDrive. Do not download changes from OneDrive.
+  --verbose -v+
+      Print more details, useful for debugging (repeat for extra debugging)
+  --version
+      Print the version and exit
+  --with-editing-perms
+      Create a read-write shareable link for an existing file on OneDrive when used with --create-share-link <file>
+```
+
+Refer to [application-config-options.md](application-config-options.md) for in-depth details on all application options.