opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/rclone-cli/references/providers/onedrive.md

@@ -0,0 +1,1322 @@
+---
+title: "Microsoft OneDrive"
+description: "Rclone docs for Microsoft OneDrive"
+versionIntroduced: "v1.24"
+---
+
+> **Official documentation:** [https://rclone.org/onedrive/](https://rclone.org/onedrive/)
+# Microsoft OneDrive
+
+Paths are specified as `remote:path`
+
+Paths may be as deep as required, e.g. `remote:directory/subdirectory`.
+
+## Configuration
+
+The initial setup for OneDrive involves getting a token from
+Microsoft which you need to do in your browser.  `rclone config` walks
+you through it.
+
+Here is an example of how to make a remote called `remote`.  First run:
+
+```console
+rclone config
+```
+
+This will guide you through an interactive setup process:
+
+```text
+e) Edit existing remote
+n) New remote
+d) Delete remote
+r) Rename remote
+c) Copy remote
+s) Set configuration password
+q) Quit config
+e/n/d/r/c/s/q> n
+name> remote
+Type of storage to configure.
+Enter a string value. Press Enter for the default ("").
+Choose a number from below, or type in your own value
+[snip]
+XX / Microsoft OneDrive
+   \ "onedrive"
+[snip]
+Storage> onedrive
+Microsoft App Client Id
+Leave blank normally.
+Enter a string value. Press Enter for the default ("").
+client_id>
+Microsoft App Client Secret
+Leave blank normally.
+Enter a string value. Press Enter for the default ("").
+client_secret>
+Edit advanced config? (y/n)
+y) Yes
+n) No
+y/n> n
+Remote config
+Use web browser to automatically authenticate rclone with remote?
+ * Say Y if the machine running rclone has a web browser you can use
+ * Say N if running rclone on a (remote) machine without web browser access
+If not sure try Y. If Y failed, try N.
+y) Yes
+n) No
+y/n> y
+If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth
+Log in and authorize rclone for access
+Waiting for code...
+Got code
+Choose a number from below, or type in an existing value
+ 1 / OneDrive Personal or Business
+   \ "onedrive"
+ 2 / Sharepoint site
+   \ "sharepoint"
+ 3 / Type in driveID
+   \ "driveid"
+ 4 / Type in SiteID
+   \ "siteid"
+ 5 / Search a Sharepoint site
+   \ "search"
+Your choice> 1
+Found 1 drives, please select the one you want to use:
+0: OneDrive (business) id=b!Eqwertyuiopasdfghjklzxcvbnm-7mnbvcxzlkjhgfdsapoiuytrewqk
+Chose drive to use:> 0
+Found drive 'root' of type 'business', URL: https://org-my.sharepoint.com/personal/you/Documents
+Is that okay?
+y) Yes
+n) No
+y/n> y
+Configuration complete.
+Options:
+- type: onedrive
+- token: {"access_token":"youraccesstoken","token_type":"Bearer","refresh_token":"yourrefreshtoken","expiry":"2018-08-26T22:39:52.486512262+08:00"}
+- drive_id: b!Eqwertyuiopasdfghjklzxcvbnm-7mnbvcxzlkjhgfdsapoiuytrewqk
+- drive_type: business
+Keep this "remote" remote?
+y) Yes this is OK
+e) Edit this remote
+d) Delete this remote
+y/e/d> y
+```
+
+See the [remote setup docs](/remote_setup/) for how to set it up on a
+machine without an internet-connected web browser available.
+
+Note that rclone runs a webserver on your local machine to collect the
+token as returned from Microsoft. This only runs from the moment it
+opens your browser to the moment you get back the verification
+code.  This is on `http://127.0.0.1:53682/` and this it may require
+you to unblock it temporarily if you are running a host firewall.
+
+Once configured you can then use `rclone` like this (replace `remote` with the
+name you gave your remote):
+
+List directories in top level of your OneDrive
+
+```console
+rclone lsd remote:
+```
+
+List all the files in your OneDrive
+
+```console
+rclone ls remote:
+```
+
+To copy a local directory to an OneDrive directory called backup
+
+```console
+rclone copy /home/source remote:backup
+```
+
+### Getting your own Client ID and Key
+
+rclone uses a default Client ID when talking to OneDrive, unless a custom
+`client_id` is specified in the config. The default Client ID and Key are
+shared by all rclone users when performing requests.
+
+You may choose to create and use your own Client ID, in case the default one
+does not work well for you. For example, you might see throttling.
+
+#### Creating Client ID for OneDrive Personal
+
+To create your own Client ID, please follow these steps:
+
+1. Open <https://portal.azure.com/?quickstart=true#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview>
+  and then under the `Add` menu click `App registration`.
+   - If you have not created an Azure account, you will be prompted to. This is free,
+   but you need to provide a phone number, address, and credit card for identity
+   verification.
+2. Enter a name for your app, choose account type `Accounts in any organizational
+   directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts
+   (e.g. Skype, Xbox)`,
+  select `Web` in `Redirect URI`, then type (do not copy and paste)
+  `http://localhost:53682/` and click Register. Copy and keep the
+  `Application (client) ID` under the app name for later use.
+3. Under `manage` select `Certificates & secrets`, click `New client secret`.
+  Enter a description (can be anything) and set `Expires` to 24 months.
+  Copy and keep that secret *Value* for later use (you *won't* be able to see
+  this value afterwards).
+4. Under `manage` select `API permissions`, click `Add a permission` and select
+  `Microsoft Graph` then select `delegated permissions`.
+5. Search and select the following permissions: `Files.Read`, `Files.ReadWrite`,
+  `Files.Read.All`, `Files.ReadWrite.All`, `offline_access`, `User.Read` and
+  `Sites.Read.All` (if custom access scopes are configured, select the
+  permissions accordingly). Once selected click `Add permissions` at the bottom.
+
+Now the application is complete. Run `rclone config` to create or edit a OneDrive
+remote. Supply the app ID and password as Client ID and Secret, respectively.
+rclone will walk you through the remaining steps.
+
+The access_scopes option allows you to configure the permissions requested by rclone.
+See [Microsoft Docs](https://docs.microsoft.com/en-us/graph/permissions-reference#files-permissions)
+for more information about the different scopes.
+
+The `Sites.Read.All` permission is required if you need to
+[search SharePoint sites when configuring the remote](https://github.com/rclone/rclone/pull/5883).
+However, if that permission is not assigned, you need to exclude `Sites.Read.All`
+from your access scopes or set `disable_site_permission` option to true in the
+advanced options.
+
+#### Creating Client ID for OneDrive Business
+
+The steps for OneDrive Personal may or may not work for OneDrive Business,
+depending on the security settings of the organization.
+A common error is that the publisher of the App is not verified.
+
+You may try to [verify you account](https://docs.microsoft.com/en-us/azure/active-directory/develop/publisher-verification-overview),
+or try to limit the App to your organization only, as shown below.
+
+1. Make sure to create the App with your business account.
+2. Follow the steps above to create an App. However, we need a different account
+   type here: `Accounts in this organizational directory only (*** - Single tenant)`.
+   Note that you can also change the account type after creating the App.
+3. Find the [tenant ID](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant)
+   of your organization.
+4. In the rclone config, set `auth_url` to `https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize`.
+5. In the rclone config, set `token_url` to `https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token`.
+
+Note: If you have a special region, you may need a different host in step 4 and 5.
+Here are [some hints](https://github.com/rclone/rclone/blob/bc23bf11db1c78c6ebbf8ea538fbebf7058b4176/backend/onedrive/onedrive.go#L86).
+
+### Using OAuth Client Credential flow
+
+OAuth Client Credential flow will allow rclone to use permissions
+directly associated with the Azure AD Enterprise application, rather
+that adopting the context of an Azure AD user account.
+
+This flow can be enabled by following the steps below:
+
+1. Create the Enterprise App registration in the Azure AD portal and obtain a
+   Client ID and Client Secret as described above.
+2. Ensure that the application has the appropriate permissions and they are
+   assigned as *Application Permissions*
+3. Configure the remote, ensuring that *Client ID* and *Client Secret* are
+   entered correctly.
+4. In the *Advanced Config* section, enter `true` for `client_credentials` and
+   in the `tenant` section enter the tenant ID.
+
+When it comes to choosing the type of the connection work with the
+client credentials flow. In particular the "onedrive" option does not
+work. You can use the "sharepoint" option or if that does not find the
+correct drive ID type it in manually with the "driveid" option.
+
+To back up any user's data using this flow, grant your Azure AD
+application the necessary Microsoft Graph *Application permissions*
+(such as `Files.Read.All`, `Sites.Read.All` and/or `Sites.Selected`).
+With these permissions, rclone can access drives across the tenant,
+but it needs to know *which user or drive* you want. Supply a specific
+`drive_id` corresponding to that user's OneDrive, or a SharePoint site
+ID for SharePoint libraries. You can obtain a user's drive ID using
+Microsoft Graph (e.g. `/users/{userUPN}/drive`) and then configure it
+in rclone. Once the correct drive ID is provided, rclone will back up
+that user's data using the app-only token without requiring their
+credentials.
+
+**NOTE** Assigning permissions directly to the application means that
+anyone with the *Client ID* and *Client Secret* can access your
+OneDrive files. Take care to safeguard these credentials.
+
+### Modification times and hashes
+
+OneDrive allows modification times to be set on objects accurate to 1
+second.  These will be used to detect whether objects need syncing or
+not.
+
+OneDrive Personal, OneDrive for Business and Sharepoint Server support
+[QuickXorHash](https://docs.microsoft.com/en-us/onedrive/developer/code-snippets/quickxorhash).
+
+Before rclone 1.62 the default hash for Onedrive Personal was `SHA1`.
+For rclone 1.62 and above the default for all Onedrive backends is
+`QuickXorHash`.
+
+Starting from July 2023 `SHA1` support is being phased out in Onedrive
+Personal in favour of `QuickXorHash`. If necessary the
+`--onedrive-hash-type` flag (or `hash_type` config option) can be used
+to select `SHA1` during the transition period if this is important
+your workflow.
+
+For all types of OneDrive you can use the `--checksum` flag.
+
+### --fast-list
+
+This remote supports `--fast-list` which allows you to use fewer
+transactions in exchange for more memory. See the [rclone
+docs](/docs/#fast-list) for more details.
+
+This must be enabled with the `--onedrive-delta` flag (or `delta =
+true` in the config file) as it can cause performance degradation.
+
+It does this by using the delta listing facilities of OneDrive which
+returns all the files in the remote very efficiently. This is much
+more efficient than listing directories recursively and is Microsoft's
+recommended way of reading all the file information from a drive.
+
+This can be useful with `rclone mount` and [rclone rc vfs/refresh
+recursive=true](/rc/#vfs-refresh)) to very quickly fill the mount with
+information about all the files.
+
+The API used for the recursive listing (`ListR`) only supports listing
+from the root of the drive. This will become increasingly inefficient
+the further away you get from the root as rclone will have to discard
+files outside of the directory you are using.
+
+Some commands (like `rclone lsf -R`) will use `ListR` by default - you
+can turn this off with `--disable ListR` if you need to.
+
+### Restricted filename characters
+
+In addition to the [default restricted characters set](/overview/#restricted-characters)
+the following characters are also replaced:
+
+| Character | Value | Replacement |
+| --------- |:-----:|:-----------:|
+| "         | 0x22  | ＂          |
+| *         | 0x2A  | ＊          |
+| :         | 0x3A  | ：          |
+| <         | 0x3C  | ＜          |
+| >         | 0x3E  | ＞          |
+| ?         | 0x3F  | ？          |
+| \         | 0x5C  | ＼          |
+| \|        | 0x7C  | ｜          |
+
+File names can also not end with the following characters.
+These only get replaced if they are the last character in the name:
+
+| Character | Value | Replacement |
+| --------- |:-----:|:-----------:|
+| SP        | 0x20  | ␠           |
+| .         | 0x2E  | ．          |
+
+File names can also not begin with the following characters.
+These only get replaced if they are the first character in the name:
+
+| Character | Value | Replacement |
+| --------- |:-----:|:-----------:|
+| SP        | 0x20  | ␠           |
+| ~         | 0x7E  | ～          |
+
+Invalid UTF-8 bytes will also be [replaced](/overview/#invalid-utf8),
+as they can't be used in JSON strings.
+
+### Deleting files
+
+Any files you delete with rclone will end up in the trash.  Microsoft
+doesn't provide an API to permanently delete files, nor to empty the
+trash, so you will have to do that with one of Microsoft's apps or via
+the OneDrive website.
+
+<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/onedrive/onedrive.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
+### Standard options
+
+Here are the Standard options specific to onedrive (Microsoft OneDrive).
+
+#### --onedrive-client-id
+
+OAuth Client Id.
+
+Leave blank normally.
+
+Properties:
+
+- Config:      client_id
+- Env Var:     RCLONE_ONEDRIVE_CLIENT_ID
+- Type:        string
+- Required:    false
+
+#### --onedrive-client-secret
+
+OAuth Client Secret.
+
+Leave blank normally.
+
+Properties:
+
+- Config:      client_secret
+- Env Var:     RCLONE_ONEDRIVE_CLIENT_SECRET
+- Type:        string
+- Required:    false
+
+#### --onedrive-region
+
+Choose national cloud region for OneDrive.
+
+Properties:
+
+- Config:      region
+- Env Var:     RCLONE_ONEDRIVE_REGION
+- Type:        string
+- Default:     "global"
+- Examples:
+  - "global"
+    - Microsoft Cloud Global
+  - "us"
+    - Microsoft Cloud for US Government
+  - "de"
+    - Microsoft Cloud Germany (deprecated - try global region first).
+  - "cn"
+    - Azure and Office 365 operated by Vnet Group in China
+
+#### --onedrive-tenant
+
+ID of the service principal's tenant. Also called its directory ID.
+
+Set this if using
+- Client Credential flow
+
+
+Properties:
+
+- Config:      tenant
+- Env Var:     RCLONE_ONEDRIVE_TENANT
+- Type:        string
+- Required:    false
+
+### Advanced options
+
+Here are the Advanced options specific to onedrive (Microsoft OneDrive).
+
+#### --onedrive-token
+
+OAuth Access Token as a JSON blob.
+
+Properties:
+
+- Config:      token
+- Env Var:     RCLONE_ONEDRIVE_TOKEN
+- Type:        string
+- Required:    false
+
+#### --onedrive-auth-url
+
+Auth server URL.
+
+Leave blank to use the provider defaults.
+
+Properties:
+
+- Config:      auth_url
+- Env Var:     RCLONE_ONEDRIVE_AUTH_URL
+- Type:        string
+- Required:    false
+
+#### --onedrive-token-url
+
+Token server url.
+
+Leave blank to use the provider defaults.
+
+Properties:
+
+- Config:      token_url
+- Env Var:     RCLONE_ONEDRIVE_TOKEN_URL
+- Type:        string
+- Required:    false
+
+#### --onedrive-client-credentials
+
+Use client credentials OAuth flow.
+
+This will use the OAUTH2 client Credentials Flow as described in RFC 6749.
+
+Note that this option is NOT supported by all backends.
+
+Properties:
+
+- Config:      client_credentials
+- Env Var:     RCLONE_ONEDRIVE_CLIENT_CREDENTIALS
+- Type:        bool
+- Default:     false
+
+#### --onedrive-upload-cutoff
+
+Cutoff for switching to chunked upload.
+
+Any files larger than this will be uploaded in chunks of chunk_size.
+
+This is disabled by default as uploading using single part uploads
+causes rclone to use twice the storage on Onedrive business as when
+rclone sets the modification time after the upload Onedrive creates a
+new version.
+
+See: https://github.com/rclone/rclone/issues/1716
+
+
+Properties:
+
+- Config:      upload_cutoff
+- Env Var:     RCLONE_ONEDRIVE_UPLOAD_CUTOFF
+- Type:        SizeSuffix
+- Default:     off
+
+#### --onedrive-chunk-size
+
+Chunk size to upload files with - must be multiple of 320k (327,680 bytes).
+
+Above this size files will be chunked - must be multiple of 320k (327,680 bytes) and
+should not exceed 250M (262,144,000 bytes) else you may encounter \"Microsoft.SharePoint.Client.InvalidClientQueryException: The request message is too big.\"
+Note that the chunks will be buffered into memory.
+
+Properties:
+
+- Config:      chunk_size
+- Env Var:     RCLONE_ONEDRIVE_CHUNK_SIZE
+- Type:        SizeSuffix
+- Default:     10Mi
+
+#### --onedrive-drive-id
+
+The ID of the drive to use.
+
+Properties:
+
+- Config:      drive_id
+- Env Var:     RCLONE_ONEDRIVE_DRIVE_ID
+- Type:        string
+- Required:    false
+
+#### --onedrive-drive-type
+
+The type of the drive (personal | business | documentLibrary).
+
+Properties:
+
+- Config:      drive_type
+- Env Var:     RCLONE_ONEDRIVE_DRIVE_TYPE
+- Type:        string
+- Required:    false
+
+#### --onedrive-root-folder-id
+
+ID of the root folder.
+
+This isn't normally needed, but in special circumstances you might
+know the folder ID that you wish to access but not be able to get
+there through a path traversal.
+
+
+Properties:
+
+- Config:      root_folder_id
+- Env Var:     RCLONE_ONEDRIVE_ROOT_FOLDER_ID
+- Type:        string
+- Required:    false
+
+#### --onedrive-access-scopes
+
+Set scopes to be requested by rclone.
+
+Choose or manually enter a custom space separated list with all scopes, that rclone should request.
+
+
+Properties:
+
+- Config:      access_scopes
+- Env Var:     RCLONE_ONEDRIVE_ACCESS_SCOPES
+- Type:        SpaceSepList
+- Default:     Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access
+- Examples:
+  - "Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access"
+    - Read and write access to all resources
+  - "Files.Read Files.Read.All Sites.Read.All offline_access"
+    - Read only access to all resources
+  - "Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All offline_access"
+    - Read and write access to all resources, without the ability to browse SharePoint sites.
+    - Same as if disable_site_permission was set to true
+
+#### --onedrive-disable-site-permission
+
+Disable the request for Sites.Read.All permission.
+
+If set to true, you will no longer be able to search for a SharePoint site when
+configuring drive ID, because rclone will not request Sites.Read.All permission.
+Set it to true if your organization didn't assign Sites.Read.All permission to the
+application, and your organization disallows users to consent app permission
+request on their own.
+
+Properties:
+
+- Config:      disable_site_permission
+- Env Var:     RCLONE_ONEDRIVE_DISABLE_SITE_PERMISSION
+- Type:        bool
+- Default:     false
+
+#### --onedrive-expose-onenote-files
+
+Set to make OneNote files show up in directory listings.
+
+By default, rclone will hide OneNote files in directory listings because
+operations like "Open" and "Update" won't work on them.  But this
+behaviour may also prevent you from deleting them.  If you want to
+delete OneNote files or otherwise want them to show up in directory
+listing, set this option.
+
+Properties:
+
+- Config:      expose_onenote_files
+- Env Var:     RCLONE_ONEDRIVE_EXPOSE_ONENOTE_FILES
+- Type:        bool
+- Default:     false
+
+#### --onedrive-server-side-across-configs
+
+Deprecated: use --server-side-across-configs instead.
+
+Allow server-side operations (e.g. copy) to work across different onedrive configs.
+
+This will work if you are copying between two OneDrive *Personal* drives AND the files to
+copy are already shared between them. Additionally, it should also function for a user who
+has access permissions both between Onedrive for *business* and *SharePoint* under the *same
+tenant*, and between *SharePoint* and another *SharePoint* under the *same tenant*. In other
+cases, rclone will fall back to normal copy (which will be slightly slower).
+
+Properties:
+
+- Config:      server_side_across_configs
+- Env Var:     RCLONE_ONEDRIVE_SERVER_SIDE_ACROSS_CONFIGS
+- Type:        bool
+- Default:     false
+
+#### --onedrive-list-chunk
+
+Size of listing chunk.
+
+Properties:
+
+- Config:      list_chunk
+- Env Var:     RCLONE_ONEDRIVE_LIST_CHUNK
+- Type:        int
+- Default:     1000
+
+#### --onedrive-no-versions
+
+Remove all versions on modifying operations.
+
+Onedrive for business creates versions when rclone uploads new files
+overwriting an existing one and when it sets the modification time.
+
+These versions take up space out of the quota.
+
+This flag checks for versions after file upload and setting
+modification time and removes all but the last version.
+
+**NB** Onedrive personal can't currently delete versions so don't use
+this flag there.
+
+
+Properties:
+
+- Config:      no_versions
+- Env Var:     RCLONE_ONEDRIVE_NO_VERSIONS
+- Type:        bool
+- Default:     false
+
+#### --onedrive-hard-delete
+
+Permanently delete files on removal.
+
+Normally files will get sent to the recycle bin on deletion. Setting
+this flag causes them to be permanently deleted. Use with care.
+
+OneDrive personal accounts do not support the permanentDelete API,
+it only applies to OneDrive for Business and SharePoint document libraries.
+
+
+Properties:
+
+- Config:      hard_delete
+- Env Var:     RCLONE_ONEDRIVE_HARD_DELETE
+- Type:        bool
+- Default:     false
+
+#### --onedrive-link-scope
+
+Set the scope of the links created by the link command.
+
+Properties:
+
+- Config:      link_scope
+- Env Var:     RCLONE_ONEDRIVE_LINK_SCOPE
+- Type:        string
+- Default:     "anonymous"
+- Examples:
+  - "anonymous"
+    - Anyone with the link has access, without needing to sign in.
+    - This may include people outside of your organization.
+    - Anonymous link support may be disabled by an administrator.
+  - "organization"
+    - Anyone signed into your organization (tenant) can use the link to get access.
+    - Only available in OneDrive for Business and SharePoint.
+
+#### --onedrive-link-type
+
+Set the type of the links created by the link command.
+
+Properties:
+
+- Config:      link_type
+- Env Var:     RCLONE_ONEDRIVE_LINK_TYPE
+- Type:        string
+- Default:     "view"
+- Examples:
+  - "view"
+    - Creates a read-only link to the item.
+  - "edit"
+    - Creates a read-write link to the item.
+  - "embed"
+    - Creates an embeddable link to the item.
+
+#### --onedrive-link-password
+
+Set the password for links created by the link command.
+
+At the time of writing this only works with OneDrive personal paid accounts.
+
+
+Properties:
+
+- Config:      link_password
+- Env Var:     RCLONE_ONEDRIVE_LINK_PASSWORD
+- Type:        string
+- Required:    false
+
+#### --onedrive-hash-type
+
+Specify the hash in use for the backend.
+
+This specifies the hash type in use. If set to "auto" it will use the
+default hash which is QuickXorHash.
+
+Before rclone 1.62 an SHA1 hash was used by default for Onedrive
+Personal. For 1.62 and later the default is to use a QuickXorHash for
+all onedrive types. If an SHA1 hash is desired then set this option
+accordingly.
+
+From July 2023 QuickXorHash will be the only available hash for
+both OneDrive for Business and OneDrive Personal.
+
+This can be set to "none" to not use any hashes.
+
+If the hash requested does not exist on the object, it will be
+returned as an empty string which is treated as a missing hash by
+rclone.
+
+
+Properties:
+
+- Config:      hash_type
+- Env Var:     RCLONE_ONEDRIVE_HASH_TYPE
+- Type:        string
+- Default:     "auto"
+- Examples:
+  - "auto"
+    - Rclone chooses the best hash
+  - "quickxor"
+    - QuickXor
+  - "sha1"
+    - SHA1
+  - "sha256"
+    - SHA256
+  - "crc32"
+    - CRC32
+  - "none"
+    - None - don't use any hashes
+
+#### --onedrive-av-override
+
+Allows download of files the server thinks has a virus.
+
+The onedrive/sharepoint server may check files uploaded with an Anti
+Virus checker. If it detects any potential viruses or malware it will
+block download of the file.
+
+In this case you will see a message like this
+
+    server reports this file is infected with a virus - use --onedrive-av-override to download anyway: Infected (name of virus): 403 Forbidden:
+
+If you are 100% sure you want to download this file anyway then use
+the --onedrive-av-override flag, or av_override = true in the config
+file.
+
+
+Properties:
+
+- Config:      av_override
+- Env Var:     RCLONE_ONEDRIVE_AV_OVERRIDE
+- Type:        bool
+- Default:     false
+
+#### --onedrive-delta
+
+If set rclone will use delta listing to implement recursive listings.
+
+If this flag is set the onedrive backend will advertise `ListR`
+support for recursive listings.
+
+Setting this flag speeds up these things greatly:
+
+    rclone lsf -R onedrive:
+    rclone size onedrive:
+    rclone rc vfs/refresh recursive=true
+
+**However** the delta listing API **only** works at the root of the
+drive. If you use it not at the root then it recurses from the root
+and discards all the data that is not under the directory you asked
+for. So it will be correct but may not be very efficient.
+
+This is why this flag is not set as the default.
+
+As a rule of thumb if nearly all of your data is under rclone's root
+directory (the `root/directory` in `onedrive:root/directory`) then
+using this flag will be a big performance win. If your data is
+mostly not under the root then using this flag will be a big
+performance loss.
+
+It is recommended if you are mounting your onedrive at the root
+(or near the root when using crypt) and using rclone `rc vfs/refresh`.
+
+
+Properties:
+
+- Config:      delta
+- Env Var:     RCLONE_ONEDRIVE_DELTA
+- Type:        bool
+- Default:     false
+
+#### --onedrive-metadata-permissions
+
+Control whether permissions should be read or written in metadata.
+
+Reading permissions metadata from files can be done quickly, but it
+isn't always desirable to set the permissions from the metadata.
+
+
+Properties:
+
+- Config:      metadata_permissions
+- Env Var:     RCLONE_ONEDRIVE_METADATA_PERMISSIONS
+- Type:        Bits
+- Default:     off
+- Examples:
+  - "off"
+    - Do not read or write the value
+  - "read"
+    - Read the value only
+  - "write"
+    - Write the value only
+  - "read,write"
+    - Read and Write the value.
+  - "failok"
+    - If writing fails log errors only, don't fail the transfer
+
+#### --onedrive-encoding
+
+The encoding for the backend.
+
+See the [encoding section in the overview](/overview/#encoding) for more info.
+
+Properties:
+
+- Config:      encoding
+- Env Var:     RCLONE_ONEDRIVE_ENCODING
+- Type:        Encoding
+- Default:     Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8,Dot
+
+#### --onedrive-description
+
+Description of the remote.
+
+Properties:
+
+- Config:      description
+- Env Var:     RCLONE_ONEDRIVE_DESCRIPTION
+- Type:        string
+- Required:    false
+
+### Metadata
+
+OneDrive supports System Metadata (not User Metadata, as of this writing) for
+both files and directories. Much of the metadata is read-only, and there are some
+differences between OneDrive Personal and Business (see table below for
+details).
+
+Permissions are also supported, if `--onedrive-metadata-permissions` is set. The
+accepted values for `--onedrive-metadata-permissions` are "`read`", "`write`",
+"`read,write`", and "`off`" (the default). "`write`" supports adding new permissions,
+updating the "role" of existing permissions, and removing permissions. Updating
+and removing require the Permission ID to be known, so it is recommended to use
+"`read,write`" instead of "`write`" if you wish to update/remove permissions.
+
+Permissions are read/written in JSON format using the same schema as the
+[OneDrive API](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/resources/permission?view=odsp-graph-online),
+which differs slightly between OneDrive Personal and Business.
+
+Example for OneDrive Personal:
+```json
+[
+	{
+		"id": "1234567890ABC!123",
+		"grantedTo": {
+			"user": {
+				"id": "ryan@contoso.com"
+			},
+			"application": {},
+			"device": {}
+		},
+		"invitation": {
+			"email": "ryan@contoso.com"
+		},
+		"link": {
+			"webUrl": "https://1drv.ms/t/s!1234567890ABC"
+		},
+		"roles": [
+			"read"
+		],
+		"shareId": "s!1234567890ABC"
+	}
+]
+```
+
+Example for OneDrive Business:
+```json
+[
+	{
+		"id": "48d31887-5fad-4d73-a9f5-3c356e68a038",
+		"grantedToIdentities": [
+			{
+				"user": {
+					"displayName": "ryan@contoso.com"
+				},
+				"application": {},
+				"device": {}
+			}
+		],
+		"link": {
+			"type": "view",
+			"scope": "users",
+			"webUrl": "https://contoso.sharepoint.com/:w:/t/design/a577ghg9hgh737613bmbjf839026561fmzhsr85ng9f3hjck2t5s"
+		},
+		"roles": [
+			"read"
+		],
+		"shareId": "u!LKj1lkdlals90j1nlkascl"
+	},
+	{
+		"id": "5D33DD65C6932946",
+		"grantedTo": {
+			"user": {
+				"displayName": "John Doe",
+				"id": "efee1b77-fb3b-4f65-99d6-274c11914d12"
+			},
+			"application": {},
+			"device": {}
+		},
+		"roles": [
+			"owner"
+		],
+		"shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U"
+	}
+]
+```
+
+To write permissions, pass in a "permissions" metadata key using this same
+format. The [`--metadata-mapper`](https://rclone.org/docs/#metadata-mapper) tool can
+be very helpful for this.
+
+When adding permissions, an email address can be provided in the `User.ID` or
+`DisplayName` properties of `grantedTo` or `grantedToIdentities`. Alternatively,
+an ObjectID can be provided in `User.ID`. At least one valid recipient must be
+provided in order to add a permission for a user. Creating a Public Link is also
+supported, if `Link.Scope` is set to `"anonymous"`.
+
+Example request to add a "read" permission with `--metadata-mapper`:
+
+```json
+{
+    "Metadata": {
+        "permissions": "[{\"grantedToIdentities\":[{\"user\":{\"id\":\"ryan@contoso.com\"}}],\"roles\":[\"read\"]}]"
+    }
+}
+```
+
+Note that adding a permission can fail if a conflicting permission already
+exists for the file/folder.
+
+To update an existing permission, include both the Permission ID and the new
+`roles` to be assigned. `roles` is the only property that can be changed.
+
+To remove permissions, pass in a blob containing only the permissions you wish
+to keep (which can be empty, to remove all.) Note that the `owner` role will be
+ignored, as it cannot be removed.
+
+Note that both reading and writing permissions requires extra API calls, so if
+you don't need to read or write permissions it is recommended to omit
+`--onedrive-metadata-permissions`.
+
+Metadata and permissions are supported for Folders (directories) as well as
+Files. Note that setting the `mtime` or `btime` on a Folder requires one extra
+API call on OneDrive Business only.
+
+OneDrive does not currently support User Metadata. When writing metadata, only
+writeable system properties will be written -- any read-only or unrecognized keys
+passed in will be ignored.
+
+TIP: to see the metadata and permissions for any file or folder, run:
+
+```
+rclone lsjson remote:path --stat -M --onedrive-metadata-permissions read
+```
+
+Here are the possible system metadata items for the onedrive backend.
+
+| Name | Help | Type | Example | Read Only |
+|------|------|------|---------|-----------|
+| btime | Time of file birth (creation) with S accuracy (mS for OneDrive Personal). | RFC 3339 | 2006-01-02T15:04:05Z | N |
+| content-type | The MIME type of the file. | string | text/plain | **Y** |
+| created-by-display-name | Display name of the user that created the item. | string | John Doe | **Y** |
+| created-by-id | ID of the user that created the item. | string | 48d31887-5fad-4d73-a9f5-3c356e68a038 | **Y** |
+| description | A short description of the file. Max 1024 characters. No longer supported by Microsoft. | string | Contract for signing | N |
+| id | The unique identifier of the item within OneDrive. | string | 01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K | **Y** |
+| last-modified-by-display-name | Display name of the user that last modified the item. | string | John Doe | **Y** |
+| last-modified-by-id | ID of the user that last modified the item. | string | 48d31887-5fad-4d73-a9f5-3c356e68a038 | **Y** |
+| malware-detected | Whether OneDrive has detected that the item contains malware. | boolean | true | **Y** |
+| mtime | Time of last modification with S accuracy (mS for OneDrive Personal). | RFC 3339 | 2006-01-02T15:04:05Z | N |
+| package-type | If present, indicates that this item is a package instead of a folder or file. Packages are treated like files in some contexts and folders in others. | string | oneNote | **Y** |
+| permissions | Permissions in a JSON dump of OneDrive format. Enable with --onedrive-metadata-permissions. Properties: id, grantedTo, grantedToIdentities, invitation, inheritedFrom, link, roles, shareId | JSON | {} | N |
+| shared-by-id | ID of the user that shared the item (if shared). | string | 48d31887-5fad-4d73-a9f5-3c356e68a038 | **Y** |
+| shared-owner-id | ID of the owner of the shared item (if shared). | string | 48d31887-5fad-4d73-a9f5-3c356e68a038 | **Y** |
+| shared-scope | If shared, indicates the scope of how the item is shared: anonymous, organization, or users. | string | users | **Y** |
+| shared-time | Time when the item was shared, with S accuracy (mS for OneDrive Personal). | RFC 3339 | 2006-01-02T15:04:05Z | **Y** |
+| utime | Time of upload with S accuracy (mS for OneDrive Personal). | RFC 3339 | 2006-01-02T15:04:05Z | **Y** |
+
+See the [metadata](/docs/#metadata) docs for more info.
+
+<!-- autogenerated options stop -->
+
+### Impersonate other users as Admin
+
+Unlike Google Drive and impersonating any domain user via service accounts,
+OneDrive requires you to authenticate as an admin account, and manually setup
+a remote per user you wish to impersonate.
+
+1. In [Microsoft 365 Admin Center](https://admin.microsoft.com), open each user
+   you need to "impersonate" and go to the OneDrive section. There is a heading
+   called "Get access to files", you need to click to create the link, this
+   creates the link of the format
+   `https://{tenant}-my.sharepoint.com/personal/{user_name_domain_tld}/` but also
+   changes the permissions so you your admin user has access.
+2. Then in powershell run the following commands:
+
+   ```console
+   Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force
+   Import-Module Microsoft.Graph.Files
+   Connect-MgGraph -Scopes "Files.ReadWrite.All"
+   # Follow the steps to allow access to your admin user
+   # Then run this for each user you want to impersonate to get the Drive ID
+   Get-MgUserDefaultDrive -UserId '{emailaddress}'
+   # This will give you output of the format:
+   # Name     Id                                                                 DriveType CreatedDateTime
+   # ----     --                                                                 --------- ---------------
+   # OneDrive b!XYZ123                                                           business  14/10/2023    1:00:58 pm
+   ```
+
+3. Then in rclone add a onedrive remote type, and use the `Type in driveID`
+   with the DriveID you got in the previous step. One remote per user. It will
+   then confirm the drive ID, and hopefully give you a message of
+   `Found drive "root" of type "business"` and then include the URL of the format
+   `https://{tenant}-my.sharepoint.com/personal/{user_name_domain_tld}/Documents`
+
+## Limitations
+
+If you don't use rclone for 90 days the refresh token will
+expire. This will result in authorization problems. This is easy to
+fix by running the `rclone config reconnect remote:` command to get a
+new token and refresh token.
+
+### Naming
+
+Note that OneDrive is case insensitive so you can't have a
+file called "Hello.doc" and one called "hello.doc".
+
+There are quite a few characters that can't be in OneDrive file
+names.  These can't occur on Windows platforms, but on non-Windows
+platforms they are common.  Rclone will map these names to and from an
+identical looking unicode equivalent.  For example if a file has a `?`
+in it will be mapped to `？` instead.
+
+### File sizes
+
+The largest allowed file size is 250 GiB for both OneDrive Personal and OneDrive
+for Business [(Updated 13 Jan 2021)](https://support.microsoft.com/en-us/office/invalid-file-names-and-file-types-in-onedrive-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa?ui=en-us&rs=en-us&ad=us#individualfilesize).
+
+### Path length
+
+The entire path, including the file name, must contain fewer than 400
+characters for OneDrive, OneDrive for Business and SharePoint Online. If you
+are encrypting file and folder names with rclone, you may want to pay attention
+to this limitation because the encrypted names are typically longer than the
+original ones.
+
+### Number of files
+
+OneDrive seems to be OK with at least 50,000 files in a folder, but at
+100,000 rclone will get errors listing the directory like `couldn’t
+list files: UnknownError:`.  See
+[#2707](https://github.com/rclone/rclone/issues/2707) for more info.
+
+An official document about the limitations for different types of OneDrive can
+be found [here](https://support.office.com/en-us/article/invalid-file-names-and-file-types-in-onedrive-onedrive-for-business-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa).
+
+## Versions
+
+Every change in a file OneDrive causes the service to create a new
+version of the file.  This counts against a users quota.  For
+example changing the modification time of a file creates a second
+version, so the file apparently uses twice the space.
+
+For example the `copy` command is affected by this as rclone copies
+the file and then afterwards sets the modification time to match the
+source file which uses another version.
+
+You can use the `rclone cleanup` command (see below) to remove all old
+versions.
+
+Or you can set the `no_versions` parameter to `true` and rclone will
+remove versions after operations which create new versions. This takes
+extra transactions so only enable it if you need it.
+
+**Note** At the time of writing Onedrive Personal creates versions
+(but not for setting the modification time) but the API for removing
+them returns "API not found" so cleanup and `no_versions` should not
+be used on Onedrive Personal.
+
+### Disabling versioning
+
+Starting October 2018, users will no longer be able to
+disable versioning by default. This is because Microsoft has brought
+an
+[update](https://techcommunity.microsoft.com/t5/Microsoft-OneDrive-Blog/New-Updates-to-OneDrive-and-SharePoint-Team-Site-Versioning/ba-p/204390)
+to the mechanism. To change this new default setting, a PowerShell
+command is required to be run by a SharePoint admin. If you are an
+admin, you can run these commands in PowerShell to change that
+setting:
+
+1. `Install-Module -Name Microsoft.Online.SharePoint.PowerShell` (in case you
+   haven't installed this already)
+2. `Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking`
+3. `Connect-SPOService -Url https://YOURSITE-admin.sharepoint.com -Credential YOU@YOURSITE.COM`
+   (replacing `YOURSITE`, `YOU`, `YOURSITE.COM` with the actual values; this will
+   prompt for your credentials)
+4. `Set-SPOTenant -EnableMinimumVersionRequirement $False`
+5. `Disconnect-SPOService` (to disconnect from the server)
+
+*Below are the steps for normal users to disable versioning. If you don't see
+the "No Versioning" option, make sure the above requirements are met.*
+
+User [Weropol](https://github.com/Weropol) has found a method to disable
+versioning on OneDrive
+
+1. Open the settings menu by clicking on the gear symbol at the top of the
+   OneDrive Business page.
+2. Click Site settings.
+3. Once on the Site settings page, navigate to Site Administration > Site libraries
+   and lists.
+4. Click Customize "Documents".
+5. Click General Settings > Versioning Settings.
+6. Under Document Version History select the option No versioning.
+   Note: This will disable the creation of new file versions, but will not remove
+   any previous versions. Your documents are safe.
+7. Apply the changes by clicking OK.
+8. Use rclone to upload or modify files. (I also use the --no-update-modtime flag)
+9. Restore the versioning settings after using rclone. (Optional)
+
+## Cleanup
+
+OneDrive supports `rclone cleanup` which causes rclone to look through
+every file under the path supplied and delete all version but the
+current version. Because this involves traversing all the files, then
+querying each file for versions it can be quite slow. Rclone does
+`--checkers` tests in parallel. The command also supports `--interactive`/`i`
+or `--dry-run` which is a great way to see what it would do.
+
+```text
+rclone cleanup --interactive remote:path/subdir # interactively remove all old version for path/subdir
+rclone cleanup remote:path/subdir               # unconditionally remove all old version for path/subdir
+```
+
+**NB** Onedrive personal can't currently delete versions
+
+## Troubleshooting
+
+### Excessive throttling or blocked on SharePoint
+
+If you experience excessive throttling or is being blocked on SharePoint then
+it may help to set the user agent explicitly with a flag like this:
+`--user-agent "ISV|rclone.org|rclone/v1.55.1"`
+
+The specific details can be found in the Microsoft document:
+[Avoid getting throttled or blocked in SharePoint Online](https://docs.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online#how-to-decorate-your-http-traffic-to-avoid-throttling)
+
+### Unexpected file size/hash differences on Sharepoint
+
+It is a
+[known](https://github.com/OneDrive/onedrive-api-docs/issues/935#issuecomment-441741631)
+issue that Sharepoint (not OneDrive or OneDrive for Business) silently modifies
+uploaded files, mainly Office files (.docx, .xlsx, etc.), causing file size and
+hash checks to fail. There are also other situations that will cause OneDrive to
+report inconsistent file sizes. To use rclone with such
+affected files on Sharepoint, you
+may disable these checks with the following command line arguments:
+
+```text
+--ignore-checksum --ignore-size
+```
+
+Alternatively, if you have write access to the OneDrive files, it may be possible
+to fix this problem for certain files, by attempting the steps below.
+Open the web interface for [OneDrive](https://onedrive.live.com) and find the
+affected files (which will be in the error messages/log for rclone). Simply click
+on each of these files, causing OneDrive to open them on the web. This will cause
+each file to be converted in place to a format that is functionally equivalent
+but which will no longer trigger the size discrepancy. Once all problematic files
+are converted you will no longer need the ignore options above.
+
+### Replacing/deleting existing files on Sharepoint gets "item not found"
+
+It is a [known](https://github.com/OneDrive/onedrive-api-docs/issues/1068) issue
+that Sharepoint (not OneDrive or OneDrive for Business) may return "item not
+found" errors when users try to replace or delete uploaded files; this seems to
+mainly affect Office files (.docx, .xlsx, etc.) and web files (.html, .aspx, etc.).
+As a workaround, you may use
+the `--backup-dir <BACKUP_DIR>` command line argument so rclone moves the
+files to be replaced/deleted into a given backup directory (instead of directly
+replacing/deleting them). For example, to instruct rclone to move the files into
+the directory `rclone-backup-dir` on backend `mysharepoint`, you may use:
+
+```text
+--backup-dir mysharepoint:rclone-backup-dir
+```
+
+### access\_denied (AADSTS65005)
+
+```text
+Error: access_denied
+Code: AADSTS65005
+Description: Using application 'rclone' is currently not supported for your organization [YOUR_ORGANIZATION] because it is in an unmanaged state. An administrator needs to claim ownership of the company by DNS validation of [YOUR_ORGANIZATION] before the application rclone can be provisioned.
+```
+
+This means that rclone can't use the OneDrive for Business API with your account.
+You can't do much about it, maybe write an email to your admins.
+
+However, there are other ways to interact with your OneDrive account. Have a look
+at the WebDAV backend: <https://rclone.org/webdav/#sharepoint>
+
+### invalid\_grant (AADSTS50076)
+
+```text
+Error: invalid_grant
+Code: AADSTS50076
+Description: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '...'.
+```
+
+If you see the error above after enabling multi-factor authentication for your
+account, you can fix it by refreshing your OAuth refresh token. To do that, run
+`rclone config`, and choose to edit your OneDrive backend. Then, you don't need
+to actually make any changes until you reach this question:
+`Already have a token - refresh?`. For this question, answer `y` and go through
+the process to refresh your token, just like the first time the backend is
+configured. After this, rclone should work again for this backend.
+
+### Invalid request when making public links
+
+On Sharepoint and OneDrive for Business, `rclone link` may return an "Invalid
+request" error. A possible cause is that the organisation admin didn't allow
+public links to be made for the organisation/sharepoint library. To fix the
+permissions as an admin, take a look at the docs:
+[1](https://docs.microsoft.com/en-us/sharepoint/turn-external-sharing-on-or-off),
+[2](https://support.microsoft.com/en-us/office/set-up-and-manage-access-requests-94b26e0b-2822-49d4-929a-8455698654b3).
+
+### Can not access `Shared` with me files
+
+Shared with me files is not supported by rclone
+[currently](https://github.com/rclone/rclone/issues/4062), but there is a workaround:
+
+1. Visit [https://onedrive.live.com](https://onedrive.live.com/)
+2. Right click a item in `Shared`, then click `Add shortcut to My files` in the context
+    ![make_shortcut](https://user-images.githubusercontent.com/60313789/206118040-7e762b3b-aa61-41a1-8649-cc18889f3572.png "Screenshot (Shared with me)")
+3. The shortcut will appear in `My files`, you can access it with rclone, it
+   behaves like a normal folder/file.
+    ![in_my_files](https://i.imgur.com/0S8H3li.png "Screenshot (My Files)")
+    ![rclone_mount](https://i.imgur.com/2Iq66sW.png "Screenshot (rclone mount)")
+
+### Live Photos uploaded from iOS (small video clips in .heic files)
+
+The iOS OneDrive app introduced [upload and storage](https://techcommunity.microsoft.com/t5/microsoft-onedrive-blog/live-photos-come-to-onedrive/ba-p/1953452)
+of [Live Photos](https://support.apple.com/en-gb/HT207310) in 2020.
+The usage and download of these uploaded Live Photos is unfortunately still
+work-in-progress and this introduces several issues when copying, synchronising
+and mounting – both in rclone and in the native OneDrive client on Windows.
+
+The root cause can easily be seen if you locate one of your Live Photos in the
+OneDrive web interface. Then download the photo from the web interface. You
+will then see that the size of downloaded .heic file is smaller than the size
+displayed in the web interface. The downloaded file is smaller because it only
+contains a single frame (still photo) extracted from the Live Photo (movie)
+stored in OneDrive.
+
+The different sizes will cause `rclone copy/sync` to repeatedly recopy
+unmodified photos something like this:
+
+```text
+DEBUG : 20230203_123826234_iOS.heic: Sizes differ (src 4470314 vs dst 1298667)
+DEBUG : 20230203_123826234_iOS.heic: sha1 = fc2edde7863b7a7c93ca6771498ac797f8460750 OK
+INFO  : 20230203_123826234_iOS.heic: Copied (replaced existing)
+```
+
+These recopies can be worked around by adding `--ignore-size`. Please note that
+this workaround only syncs the still-picture not the movie clip,
+and relies on modification dates being correctly updated on all files in all situations.
+
+The different sizes will also cause `rclone check` to report size errors something
+like this:
+
+```text
+ERROR : 20230203_123826234_iOS.heic: sizes differ
+```
+
+These check errors can be suppressed by adding `--ignore-size`.
+
+The different sizes will also cause `rclone mount` to fail downloading with an
+error something like this:
+
+```text
+ERROR : 20230203_123826234_iOS.heic: ReadFileHandle.Read error: low level retry 1/10: unexpected EOF
+```
+
+or like this when using `--cache-mode=full`:
+
+```text
+INFO  : 20230203_123826234_iOS.heic: vfs cache: downloader: error count now 1: vfs reader: failed to write to cache file: 416 Requested Range Not Satisfiable:
+ERROR : 20230203_123826234_iOS.heic: vfs cache: failed to download: vfs reader: failed to write to cache file: 416 Requested Range Not Satisfiable:
+```