rclone(1)

📦 version 1.69.3, in ubuntu stonking

💖 rclone(1) — General Commands Manual 💖

okay bestie, sit down, hydrate, because we are about to talk about the single most iconic file-management tool in the entire cloud. this is the manual page for rclone. yes THE rclone. the one the cool sysadmins whisper about. let's get into it 🫶

✨ NAME ✨

rclone — manage files on cloud storage. that's it. that's the whole job. 💅

🎀 SYNOPSIS 🎀

lowkey the whole vibe in one block:

Usage:
  rclone [flags]
  rclone [command]

Available commands:
  about       Get quota information from the remote.
  authorize   Remote authorization.
  backend     Run a backend-specific command.
  bisync      Perform bidirectional synchronization between two paths.
  cat         Concatenates any files and sends them to stdout.
  check       Checks the files in the source and destination match.
  checksum    Checks the files in the destination against a SUM file.
  cleanup     Clean up the remote if possible.
  completion  Output completion script for a given shell.
  config      Enter an interactive configuration session.
  copy        Copy files from source to dest, skipping identical files.
  copyto      Copy files from source to dest, skipping identical files.
  copyurl     Copy the contents of the URL supplied content to dest:path.
  cryptcheck  Cryptcheck checks the integrity of an encrypted remote.
  cryptdecode Cryptdecode returns unencrypted file names.
  dedupe      Interactively find duplicate filenames and delete/rename them.
  delete      Remove the files in path.
  deletefile  Remove a single file from remote.
  gendocs     Output markdown docs for rclone to the directory supplied.
  gitannex    Speaks with git-annex over stdin/stdout.
  hashsum     Produces a hashsum file for all the objects in the path.
  help        Show help for rclone commands, flags and backends.
  link        Generate public link to file/folder.
  listremotes List all the remotes in the config file and defined in environment variables.
  ls          List the objects in the path with size and path.
  lsd         List all directories/containers/buckets in the path.
  lsf         List directories and objects in remote:path formatted for parsing.
  lsjson      List directories and objects in the path in JSON format.
  lsl         List the objects in path with modification time, size and path.
  md5sum      Produces an md5sum file for all the objects in the path.
  mkdir       Make the path if it doesn't already exist.
  mount       Mount the remote as file system on a mountpoint.
  move        Move files from source to dest.
  moveto      Move file or directory from source to dest.
  ncdu        Explore a remote with a text based user interface.
  obscure     Obscure password for use in the rclone config file.
  purge       Remove the path and all of its contents.
  rc          Run a command against a running rclone.
  rcat        Copies standard input to file on remote.
  rcd         Run rclone listening to remote control commands only.
  rmdir       Remove the empty directory at path.
  rmdirs      Remove empty directories under the path.
  selfupdate  Update the rclone binary.
  serve       Serve a remote over a protocol.
  settier     Changes storage class/tier of objects in remote.
  sha1sum     Produces an sha1sum file for all the objects in the path.
  size        Prints the total size and number of objects in remote:path.
  sync        Make source and dest identical, modifying destination only.
  test        Run a test command
  touch       Create new file or change file modification time.
  tree        List the contents of the remote in a tree like fashion.
  version     Show the version number.

Use "rclone [command] --help" for more information about a command.
Use "rclone help flags" for to see the global flags.
Use "rclone help backends" for a list of supported services.

like... look at that list. it's giving main character energy honestly. every single one of those is a whole command with its own entire personality. 🔥

🌈 NAME (again, yes really) 🌈

Rclone — syncs your files to cloud storage 🌸

here's your little table of contents bestie, tap through:

About rclone
What can rclone do for you?
What features does rclone have?
What providers does rclone support?
Download
Install
Donate.

💫 About rclone 💫

so like. rclone is a command-line program for managing files on cloud storage. no cap. it's a feature-rich alternative to cloud vendors' web storage interfaces — you know, the ones with the seventeen-click upload flow and the ads. 🙈

over 70 cloud storage products support rclone, including S3 object stores, business & consumer file storage services, and also standard transfer protocols. seventy. plus. obsessed. 👑

🦋 DESCRIPTION 🦋

okay so rclone has powerful cloud equivalents to the unix commands rsync, cp, mv, mount, ls, ncdu, tree, rm, and cat. if you already know your way around a shell, congrats, you basically already know rclone. it's giving "we have rsync at home" except the rsync at home is actually better and also talks to the cloud. 💅

rclone's familiar syntax includes shell pipeline support, and the legendary --dry-run protection. it gets used at the command line, in scripts, or via its API. wherever you are, rclone is there.

people call rclone "The Swiss army knife of cloud storage" and "Technology indistinguishable from magic". and honestly? both. both are true. ✨

rclone really looks after your data. like, genuinely, it's so protective of your files. it preserves timestamps and verifies checksums at all times. all the time!! it doesn't skip.

transfers over limited bandwidth, intermittent connections, or connections subject to quota can be restarted, from the last good file transferred. internet died halfway through a 400GB upload? not the end of the world bestie, you pick up right where you left off. 🫶

you can check the integrity of your files. and where possible, rclone employs server-side transfers to minimise local bandwidth use, and it'll transfer from one provider to another without using local disk. it's like it teleports your files directly between clouds. iconic behaviour.

Virtual backends wrap local and cloud file systems to apply encryption, compression, chunking, hashing and joining. 🧚

rclone can mount any local, cloud or virtual filesystem as a disk on Windows, macOS, linux and FreeBSD, and it also serves these over SFTP, HTTP, WebDAV, FTP and DLNA.

rclone is mature, open-source software that was originally inspired by rsync and written in Go. the friendly support community is familiar with varied use cases. official Ubuntu, Debian, Fedora, Brew and Chocolatey repos include rclone. for the latest version, downloading from rclone.org is recommended. 📥

rclone is widely used on Linux, Windows and Mac. third-party developers create innovative backup, restore, GUI and business process solutions using the rclone command line or API.

and then, the thesis statement: rclone does the heavy lifting of communicating with cloud storage. periodt. 💅

🎀 What can rclone do for you? 🎀

rclone helps you:

Backup (and encrypt) files to cloud storage
Restore (and decrypt) files from cloud storage
Mirror cloud data to other cloud services or locally
Migrate data to the cloud, or between cloud storage vendors
Mount multiple, encrypted, cached or diverse cloud storage as a disk
Analyse and account for data held on cloud storage using lsf, ljson, size, ncdu
Union file systems together to present multiple local and/or cloud file systems as one

okay that's just a list of superpowers honestly. 💖

🌸 Features 🌸

🔥 Transfers

MD5, SHA1 hashes are checked at all times for file integrity
Timestamps are preserved on files
Operations can be restarted at any time
Can be to and from network, e.g. two different cloud providers
Can use multi-threaded downloads to local disk
Copy new or changed files to cloud storage
Sync (one way) to make a directory identical
Bisync (two way) to keep two directories in sync bidirectionally
Move files to cloud storage deleting the local after verification
Check hashes and for missing/extra files
Mount your cloud storage as a network disk
Serve local or remote files over HTTP/WebDav/FTP/SFTP/DLNA
Experimental Web based GUI

the experimental GUI is giving "trust me bro it works" but we love her anyway 🙈

👑 Supported providers 👑

heads up bestie, there are many others built on standard protocols such as WebDAV or S3 that work out of the box. but here's the whole list:

1Fichier
Akamai Netstorage
Alibaba Cloud (Aliyun) Object Storage System (OSS)
Amazon S3
Backblaze B2
Box
Ceph
China Mobile Ecloud Elastic Object Storage (EOS)
Arvan Cloud Object Storage (AOS)
Citrix ShareFile
Cloudflare R2
Cloudinary
DigitalOcean Spaces
Digi Storage
Dreamhost
Dropbox
Enterprise File Fabric
Fastmail Files
Files.com
FTP
Gofile
Google Cloud Storage
Google Drive
Google Photos
HDFS
Hetzner Storage Box
HiDrive
HTTP
iCloud Drive
ImageKit
Internet Archive
Jottacloud
IBM COS S3
IDrive e2
IONOS Cloud
Koofr
Leviia Object Storage
Liara Object Storage
Linkbox
Linode Object Storage
Magalu
Mail.ru Cloud
Memset Memstore
Mega
Memory
Microsoft Azure Blob Storage
Microsoft Azure Files Storage
Microsoft OneDrive
Minio
Nextcloud
OVH
Blomp Cloud Storage
OpenDrive
OpenStack Swift
Oracle Cloud Storage Swift
Oracle Object Storage
Outscale
ownCloud
pCloud
Petabox
PikPak
Pixeldrain
premiumize.me
put.io
Proton Drive
QingStor
Qiniu Cloud Object Storage (Kodo)
Quatrix by Maytech
Rackspace Cloud Files
rsync.net
Scaleway
Seafile
Seagate Lyve Cloud
SeaweedFS
Selectel
SFTP
Sia
SMB / CIFS
StackPath
Storj
Synology
SugarSync
Tencent Cloud Object Storage (COS)
Uloz.to
Uptobox
Wasabi
WebDAV
Yandex Disk
Zoho WorkDrive
The local filesystem

name a storage service. go on. i'll wait. 🍓

🧚 Virtual providers 🧚

these backends don't store your stuff so much as they adapt or modify other storage providers. they're the styling layer, the filter, the fit check:

Alias: Rename existing remotes
Cache: Cache remotes (DEPRECATED)
Chunker: Split large files
Combine: Combine multiple remotes into a directory tree
Compress: Compress files
Crypt: Encrypt files
Hasher: Hash files
Union: Join multiple remotes to work together

just so we're clear, Cache is marked DEPRECATED in the original. don't come for me, i'm just the messenger. 💀

⭐ Links ⭐

Home page
GitHub project page for source and bug tracker
Rclone Forum
Downloads

that's part 1 bestie, and there is so much more coming. more parts, more flags, more everything. stay tuned 💜

✨ Usage ✨

Okay so rclone is a command line program to manage files on cloud storage 💖 once you've downloaded and installed it, this is where you go to learn how to actually use it: initial configuration, what the basic syntax looks like, and a lil tour of the various subcommands and the various options and more. iykyk ✨

🎀 Configure 🎀

First things first bestie — you gotta configure rclone. The object storage systems have genuinely complicated authentication, so all of that lives in a config file. (Peep the --config entry for how to find the config file and choose its location 👀)

The easiest way to make the config is to run rclone with the config option:

rclone config

For the detailed instructions, see below 👇

1Fichier
Akamai Netstorage
Alias
Amazon S3
Backblaze B2
Box
Chunker - transparently splits large files for other remotes
Citrix ShareFile
Compress
Cloudinary
Combine
Crypt - to encrypt other remotes
DigitalOcean Spaces
Digi Storage
Dropbox
Enterprise File Fabric
Files.com
FTP
Gofile
Google Cloud Storage
Google Drive
Google Photos
Hasher - to handle checksums for other remotes
HDFS
Hetzner Storage Box
HiDrive
HTTP
iCloud Drive
Internet Archive
Jottacloud
Koofr
Linkbox
Mail.ru Cloud
Mega
Memory
Microsoft Azure Blob Storage
Microsoft Azure Files Storage
Microsoft OneDrive
OpenStack Swift / Rackspace Cloudfiles / Blomp Cloud Storage / Memset Memstore
OpenDrive
Oracle Object Storage
Pcloud
PikPak
Pixeldrain
premiumize.me
put.io
Proton Drive
QingStor
Quatrix by Maytech
rsync.net
Seafile
SFTP
Sia
SMB
Storj
SugarSync
Union
Uloz.to
Uptobox
WebDAV
Yandex Disk
Zoho WorkDrive
The local filesystem

Like… that's the whole roster 💅 every last one of them, we did not skip a single one 🫶

🌈 Basic syntax 🌈

Rclone syncs a directory tree from one storage system to another. That's the whole plot 🦋

Its syntax goes like this:

rclone subcommand [options] <parameters> <parameters...>

A subcommand is the rclone operation you need (e.g. sync, copy, ls). It's literally the "what are we doing today" of the command ✨

An option is a single letter flag (e.g. -v) or a group of single letter flags (e.g. -Pv) or a long flag (e.g. --progress). No options are required — they're opt-in, no peer pressure here. Options can come after the subcommand, or in between parameters too, or on the end. But only global options can be used before the subcommand. And anything after a -- option will not be interpreted as an option, so if you need to add a parameter that starts with a -, put a -- on its own first, like:

rclone lsf -- -directory-starting-with-dash

A parameter is usually a file path or rclone remote, e.g. /path/to/file or remote:path/to/file, but it can be other things too — the subcommand help will tell you what. No guessing, bestie 💅

Source and destination paths are specified by the name you gave the storage system in the config file, then the sub path, e.g. drive:myfolder to look at myfolder in Google drive. And you can define as many storage paths as you like in the config file — go off, honestly 👑

⚠️ Please use the --interactive/-i flag while learning rclone to avoid accidental data loss. Fr fr, protect your files, we are NOT doing tragedy today 😭

💫 Subcommands 💫

rclone uses a system of subcommands. For example:

rclone ls remote:path # lists a remote
rclone copy /local/path remote:path # copies /local/path to the remote
rclone sync --interactive /local/path remote:path # syncs /local/path to the remote

👑 rclone config 👑

Enter an interactive configuration session. Main character energy, truly 🌟

🍓 Synopsis 🍓

Enter an interactive configuration session where you can setup new remotes and manage existing ones. You may also set or remove a password to protect your configuration.

rclone config [flags]

💖 Options 💖

-h, --help — help for config

See the global flags page for global options not listed here.

🌸 See Also 🌸

rclone - Show help for rclone commands, flags and backends.
rclone config create - Create a new remote with name, type and options.
rclone config delete - Delete an existing remote.
rclone config disconnect - Disconnects user from remote
rclone config dump - Dump the config file as JSON.
rclone config edit - Enter an interactive configuration session.
rclone config encryption - set, remove and check the encryption for the config file
rclone config file - Show path of configuration file in use.
rclone config password - Update password in an existing remote.
rclone config paths - Show paths used for configuration, cache, temp etc.
rclone config providers - List in JSON format all the providers and options.
rclone config reconnect - Re-authenticates user with remote.
rclone config redacted - Print redacted (decrypted) config file, or the redacted config for a single remote.
rclone config show - Print (decrypted) config file, or the config for a single remote.
rclone config touch - Ensure configuration file exists.
rclone config update - Update options in an existing remote.
rclone config userinfo - Prints info about logged in user of remote.

💖 rclone copy 💖

Copy files from source to dest, skipping identical files.

✨ Synopsis

Copy the source over to the destination. It does not transfer files that are identical on source and destination — it checks by size and modification time, or by MD5SUM. It also doesn't delete anything from the destination. If you do want dest to get pruned so it matches source exactly, that's the sync command's whole thing, bestie, not this one.

Heads up, it's always the contents of the directory that gets copied, never the directory itself. So like, when source:path is a directory, it's the contents of source:path that go over — not the directory's name plus its contents. 🫶

Trying to copy single files? Use copyto for that instead, okurrr.

If dest:path doesn't exist yet, no stress — it gets created and the source:path contents just move in. ✨

Like, for example:

rclone copy source:sourcepath dest:destpath

Say sourcepath is holding two files, right:

sourcepath/one.txt
sourcepath/two.txt

Then this copies them to:

destpath/one.txt
destpath/two.txt

and not to:

destpath/sourcepath/one.txt
destpath/sourcepath/two.txt

If you already know rsync: rclone always acts like you wrote a trailing / — aka "copy the contents of this directory." That's true for every single command, and it's true whether you're talking about the source or the destination. No cap. 💅

Peep the --no-traverse option for controlling whether rclone lists the destination directory at all. Pass that when you're copying a small number of files into a huge destination and it can speed transfers up massively. Iconic behavior tbh.

So like, if you've got a ton of files in /path/to/src but only a few of them change every day, you can copy all the recently-changed files super efficiently like this:

rclone copy --max-age 24h --no-traverse /path/to/src remote:

Rclone will sync the modification times of files and directories when the backend supports that. If you need metadata syncing though, go use the --metadata flag. 🌸

Note that the modification time and metadata for the root directory will not be synced. See https://github.com/rclone/rclone/issues/7652 for more info.

Note: use the -P/--progress flag to watch real-time transfer stats. 👀

Note: use the --dry-run flag or the --interactive/-i flag to test without copying a single thing. Safety first, bestie. 🎀

rclone copy source:path dest:path [flags]

🦋 Options

--create-empty-src-dirs — Create empty source dirs on destination after copy
-h, --help — help for copy

Options shared with other commands are coming up next — read on. See the global flags page for global options that aren't listed here.

🧚 Copy Options

Flags for anything which can copy a file 💖

--check-first — Do all the checks before starting transfers
-c, --checksum — Check for changes with size & checksum (if available, or fallback to size only)
--compare-dest stringArray — Include additional server-side paths during comparison
--copy-dest stringArray — Implies --compare-dest but also copies files from paths into destination
--cutoff-mode HARD|SOFT|CAUTIOUS — Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD)
--ignore-case-sync — Ignore case when synchronizing
--ignore-checksum — Skip post copy check of checksums
--ignore-existing — Skip all files that exist on destination
--ignore-size — Ignore size when skipping, use modtime or checksum
-I, --ignore-times — Don't skip items that match size and time — transfer all unconditionally
--immutable — Do not modify files, fail if existing files have been modified
--inplace — Download directly to destination file instead of atomic download to temp/rename
-l, --links — Translate symlinks to/from regular files with a .rclonelink extension
--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)
--max-duration Duration — Maximum duration rclone will transfer data for (default 0s)
--max-transfer SizeSuffix — Maximum size of data to transfer (default off)
-M, --metadata — If set, preserve metadata when copying objects
--modify-window Duration — Max time diff to be considered the same (default 1ns)
--multi-thread-chunk-size SizeSuffix — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi)
--multi-thread-cutoff SizeSuffix — Use multi-thread downloads for files above this size (default 256Mi)
--multi-thread-streams int — Number of streams to use for multi-thread downloads (default 4)
--multi-thread-write-buffer-size SizeSuffix — In memory buffer size for writing when in multi-thread mode (default 128Ki)
--no-check-dest — Don't check the destination, copy regardless
--no-traverse — Don't traverse destination file system on copy
--no-update-dir-modtime — Don't update directory modification times
--no-update-modtime — Don't update destination modtime if files identical
--order-by string — Instructions on how to order the transfers, e.g. 'size,descending'
--partial-suffix string — Add partial-suffix to temporary file name when --inplace is not used (default ".partial")
--refresh-times — Refresh the modtime of remote files
--server-side-across-configs — Allow server-side operations (e.g. copy) to work across different configs
--size-only — Skip based on size only, not modtime or checksum
--streaming-upload-cutoff SizeSuffix — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki)
-u, --update — Skip files that are newer on the destination

🌈 Important Options

Important flags that are useful for most commands, fr fr.

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

Flags for filtering directory listings 🍓

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

💜 Listing Options

Flags for listing directories 💅

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

⭐ See Also

rclone — Show help for rclone commands, flags and backends.

💅 rclone sync

Make source and dest identical, modifying destination only.

✨ Synopsis

okay so this one is the main character of the rclone commands and you need to respect her 💅 sync pushes your source over to the destination until they're literally identical, and it only ever changes the destination — never the source. If a file is already the same on both sides (it checks by size and modification time, or MD5SUM) it just doesn't bother transferring it. The destination gets fully updated to match source, including deleting files when necessary (except duplicate objects, more on that below 🫶). If you do NOT want files deleted from the destination, bestie please use the copy command instead.

⚠️ Important: this can cause data loss, so test first with the --dry-run or the --interactive/-i flag. no cap, do the dry run first fr fr 😭

rclone sync --interactive SOURCE remote:DESTINATION

Notably, files in the destination won't get deleted if there were any errors at any point. And duplicate objects (files with the same name, on those providers that support it) are also not yet handled. 🙈

The way that this works: it's always the contents of the directory that get synced, never the directory itself. So when source:path is a directory, it's the contents of source:path that get copied, not the directory name plus its contents. If you're unsure, go read the extended explanation over in the copy command. 🦋

If dest:path doesn't exist, it gets created and the source:path contents go live there. 💖

It is not possible to sync overlapping remotes. However, you may exclude the destination from the sync with a filter rule, or by putting an exclude-if-present file inside the destination directory, and then sync to a destination that is inside the source directory. periodt.

Rclone will sync the modification times of files and directories if the backend supports it. If metadata syncing is what you need, then use the --metadata flag. ✨

Note that the modification time and metadata for the root directory will not be synced. See https://github.com/rclone/rclone/issues/7652 for more info.

Note: Use the -P/--progress flag to view real-time transfer statistics 👑

Note: Use the rclone dedupe command to deal with "Duplicate object/directory found in source/destination - ignoring" errors. See this forum post for more info.

🎀 Logger Flags

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name you give them (or to stdout if it's -). What they write is described in the help below. For example --differ will write all paths which are present on both the source and destination but different. 💅

The --combined flag will write a file (or stdout) which contains all file paths with a symbol and then a space and then the path, to tell you what happened to it. These are reminiscent of diff files, lowkey iconic.

= path — means path was found in source and destination and was identical
- path — means path was missing on the source, so only in the destination
+ path — means path was missing on the destination, so only in the source
* path — means path was present in source and destination but different.
! path — means there was an error reading or hashing the source or dest.

The --dest-after flag writes a list file using the same format flags as lsf (including customizable options for hash, modtime, etc.) Conceptually it is similar to rsync's --itemize-changes, but not identical — it should output an accurate list of what will be on the destination after the sync. 🍓

Note that these logger flags have a few limitations, and certain scenarios are not currently supported:

--max-duration / CutoffModeHard
--compare-dest / --copy-dest
server-side moves of an entire dir at once
High-level retries, because there would be duplicates (use --retries 1 to disable)
Possibly some unusual error scenarios

Also note that each file is logged during the sync, as opposed to after, so it is most useful as a predictor of what SHOULD happen to each file (which may or may not match what actually DID.) 💀

rclone sync source:path dest:path [flags]

🌈 Options

--absolute — Put a leading / in front of path names
--combined string — Make a combined report of changes to this file
--create-empty-src-dirs — Create empty source dirs on destination after sync
--csv — Output in CSV format
--dest-after string — Report all files that exist on the dest post-sync
--differ string — Report all non-matching files to this file
-d, --dir-slash — Append a slash to directory names (default true)
--dirs-only — Only list directories
--error string — Report all files with errors (hashing or reading) to this file
--files-only — Only list files (default true)
-F, --format string — Output format - see lsf help for details (default "p")
--hash h — Use this hash when h is used in the format MD5|SHA-1|DropboxHash (default "md5")
-h, --help — help for sync
--match string — Report all matching files to this file
--missing-on-dst string — Report all files missing from the destination to this file
--missing-on-src string — Report all files missing from the source to this file
-s, --separator string — Separator for the items in the format (default ";")
-t, --timeformat string — Specify a custom time format, or 'max' for max precision supported by remote (default: 2006-01-02 15:04:05)

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

🦋 Copy Options

Flags for anything which can copy a file ✨

--check-first — Do all the checks before starting transfers
-c, --checksum — Check for changes with size & checksum (if available, or fallback to size only)
--compare-dest stringArray — Include additional server-side paths during comparison
--copy-dest stringArray — Implies --compare-dest but also copies files from paths into destination
--cutoff-mode HARD|SOFT|CAUTIOUS — Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD)
--ignore-case-sync — Ignore case when synchronizing
--ignore-checksum — Skip post copy check of checksums
--ignore-existing — Skip all files that exist on destination
--ignore-size — Ignore size when skipping use modtime or checksum
-I, --ignore-times — Don't skip items that match size and time - transfer all unconditionally
--immutable — Do not modify files, fail if existing files have been modified
--inplace — Download directly to destination file instead of atomic download to temp/rename
-l, --links — Translate symlinks to/from regular files with a '.rclonelink' extension
--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)
--max-duration Duration — Maximum duration rclone will transfer data for (default 0s)
--max-transfer SizeSuffix — Maximum size of data to transfer (default off)
-M, --metadata — If set, preserve metadata when copying objects
--modify-window Duration — Max time diff to be considered the same (default 1ns)
--multi-thread-chunk-size SizeSuffix — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi)
--multi-thread-cutoff SizeSuffix — Use multi-thread downloads for files above this size (default 256Mi)
--multi-thread-streams int — Number of streams to use for multi-thread downloads (default 4)
--multi-thread-write-buffer-size SizeSuffix — In memory buffer size for writing when in multi-thread mode (default 128Ki)
--no-check-dest — Don't check the destination, copy regardless
--no-traverse — Don't traverse destination file system on copy
--no-update-dir-modtime — Don't update directory modification times
--no-update-modtime — Don't update destination modtime if files identical
--order-by string — Instructions on how to order the transfers, e.g. 'size,descending'
--partial-suffix string — Add partial-suffix to temporary file name when --inplace is not used (default ".partial")
--refresh-times — Refresh the modtime of remote files
--server-side-across-configs — Allow server-side operations (e.g. copy) to work across different configs
--size-only — Skip based on size only, not modtime or checksum
--streaming-upload-cutoff SizeSuffix — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki)
-u, --update — Skip files that are newer on the destination

💜 Sync Options

Flags used for sync commands 👑

--backup-dir string — Make backups into hierarchy based in DIR
--delete-after — When synchronizing, delete files on destination after transferring (default)
--delete-before — When synchronizing, delete files on destination before transferring
--delete-during — When synchronizing, delete files during transfer
--fix-case — Force rename of case insensitive dest to match source
--ignore-errors — Delete even if there are I/O errors
--max-delete int — When synchronizing, limit the number of deletes (default -1)
--max-delete-size SizeSuffix — When synchronizing, limit the total size of deletes (default off)
--suffix string — Suffix to add to changed files
--suffix-keep-extension — Preserve the extension when using --suffix
--track-renames — When synchronizing, track file renames and do a server-side move if possible
--track-renames-strategy string — Strategies to use when synchronizing using track-renames hash|modtime|leaf (default "hash")

⭐ Important Options

Important flags useful for most commands 🌸

-n, --dry-run — the trial run, bestie. You get the whole whole experience with zero permanent changes — nothing actually gets written anywhere 💅
-i, --interactive — turns on interactive mode 🫶
-v, --verbose count — prints lots more stuff. Repeat the flag for even more stuff. Yes it stacks. Yes that's on purpose 🌸

Flags for filtering directory listings — aka: who's getting an invite to the listing party and who's getting left on read 💀

--delete-excluded — deletes files on the dest that got excluded from the sync 😭 like, it's a delete, be so serious before you run it
--exclude stringArray — excludes files matching a pattern
--exclude-from stringArray — reads your exclude patterns from a file instead (use - to read from stdin)
--exclude-if-present stringArray — excludes directories if that filename is present inside them
--files-from stringArray — reads a list of source-file names from a file (use - to read from stdin)
--files-from-raw stringArray — same thing but with no processing of the lines at all, raw as it gets (use - to read from stdin)
-f, --filter stringArray — adds a file filtering rule ✨
--filter-from stringArray — reads file filtering patterns from a file (use - to read from stdin)
--ignore-case — ignore case in filters, so it's case insensitive fr
--include stringArray — includes files matching a pattern
--include-from stringArray — reads your include patterns from a file (use - to read from stdin)
--max-age Duration — only transfers files younger than this; give it s, or a suffix like ms|s|m|h|d|w|M|y (default off)
--max-depth int — if set, caps the recursion depth right there (default -1)
--max-size SizeSuffix — only transfers files smaller than this, in KiB or with a B|K|M|G|T|P suffix (default off)
--metadata-exclude stringArray — excludes metadatas matching a pattern
--metadata-exclude-from stringArray — reads metadata exclude patterns from a file (use - to read from stdin)
--metadata-filter stringArray — adds a metadata filtering rule 💫
--metadata-filter-from stringArray — reads metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — includes metadatas matching a pattern
--metadata-include-from stringArray — reads metadata include patterns from a file (use - to read from stdin)
--min-age Duration — only transfers files older than this, in s or with a suffix like ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — only transfers files bigger than this, in KiB or with a B|K|M|G|T|P suffix (default off)

📁 Listing Options 📁

Flags for listing directories — for when you just wanna look 👀

--default-time Time — the time to show when the modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — uses a recursive list if the backend has one available; it eats more memory but makes way fewer transactions 🔥 trade your RAM for speed, iconic behaviour honestly

👀 See Also 👀

rclone — show help for rclone commands, flags and backends. The gateway drug, the main character of the whole thing 👑

rclone move

Move files from source to dest. like, physically relocating them bestie 💅

Synopsis

Moves the contents of the source directory to the destination directory. Rclone will error if the source and destination overlap and the remote doesn't support a server-side directory move operation. no overlap bestie, we don't do that here

Want to move single files? Use the moveto command instead. different girl, different job ✨

If no filters are in use and if it's possible, this will server-side move source:path into dest:path. After this, source:path will no longer exist. 💀 gone. deleted. vaporized.

Otherwise, for each file in source:path selected by the filters (if any), this will move it into dest:path. If possible a server-side move will be used, otherwise it will copy it (server-side if possible) into dest:path then delete the original (only if no errors on copy) in source:path. copy first, delete second, that's the safe order periodt

If you want to delete empty source directories after move, use the --delete-empty-src-dirs flag. bye bye empty folders 🎀

See the --no-traverse option for controlling whether rclone lists the destination directory or not. Supplying this option when moving a small number of files into a large destination can speed transfers up greatly. 🔥

Rclone will sync the modification times of files and directories if the backend supports it. If metadata syncing is required then use the --metadata flag. iykyk

Note that the modification time and metadata for the root directory will not be synced. See https://github.com/rclone/rclone/issues/7652 for more info.

Important: Since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. girl please, dry run first, i am BEGGING 😭

Note: Use the -P/--progress flag to view real-time transfer statistics. watch it happen in real time, it's giving main character energy ✨

rclone move source:path dest:path [flags]

Options

--create-empty-src-dirs — Create empty source dirs on destination after move 🎀
--delete-empty-src-dirs — Delete empty source dirs after move 🧹
-h, --help — help for move

Options shared with other commands are described next. See the global flags page for global options not listed here. there's more, keep scrolling bestie 👑

Copy Options

Flags for anything which can copy a file 🦋

--check-first — Do all the checks before starting transfers measure twice, transfer once
-c, --checksum — Check for changes with size & checksum (if available, or fallback to size only)
--compare-dest stringArray — Include additional server-side paths during comparison
--copy-dest stringArray — Implies --compare-dest but also copies files from paths into destination
--cutoff-mode HARD|SOFT|CAUTIOUS — Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD)
--ignore-case-sync — Ignore case when synchronizing
--ignore-checksum — Skip post copy check of checksums living dangerously tbh
--ignore-existing — Skip all files that exist on destination
--ignore-size — Ignore size when skipping use modtime or checksum
-I, --ignore-times — Don't skip items that match size and time - transfer all unconditionally everything gets sent. everything.
--immutable — Do not modify files, fail if existing files have been modified
--inplace — Download directly to destination file instead of atomic download to temp/rename
-l, --links — Translate symlinks to/from regular files with a .rclonelink extension
--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)
--max-duration Duration — Maximum duration rclone will transfer data for (default 0s)
--max-transfer SizeSuffix — Maximum size of data to transfer (default off)
-M, --metadata — If set, preserve metadata when copying objects ✨
--modify-window Duration — Max time diff to be considered the same (default 1ns)
--multi-thread-chunk-size SizeSuffix — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi)
--multi-thread-cutoff SizeSuffix — Use multi-thread downloads for files above this size (default 256Mi)
--multi-thread-streams int — Number of streams to use for multi-thread downloads (default 4)
--multi-thread-write-buffer-size SizeSuffix — In memory buffer size for writing when in multi-thread mode (default 128Ki)
--no-check-dest — Don't check the destination, copy regardless
--no-traverse — Don't traverse destination file system on copy
--no-update-dir-modtime — Don't update directory modification times
--no-update-modtime — Don't update destination modtime if files identical
--order-by string — Instructions on how to order the transfers, e.g. 'size,descending'
--partial-suffix string — Add partial-suffix to temporary file name when --inplace is not used (default ".partial")
--refresh-times — Refresh the modtime of remote files
--server-side-across-configs — Allow server-side operations (e.g. copy) to work across different configs
--size-only — Skip based on size only, not modtime or checksum
--streaming-upload-cutoff SizeSuffix — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki)
-u, --update — Skip files that are newer on the destination

Important Options

Important flags useful for most commands 👑

-n, --dry-run — Do a trial run with no permanent changes the safest girlypop move
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more) spam it for maximum tea

Flags for filtering directory listings 🧚

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories 🍓

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

✨ rclone delete ✨

okay bestie so this one removes the files in path 💅

🌸 Synopsis 🌸

it removes the files in path. and here's the tea: unlike purge it obeys include/exclude filters, so you can use it to selectively delete files 😌

and listen — rclone delete only deletes files but leaves the directory structure alone. if you wanna delete a directory and all of its contents, that's the purge command's whole thing 🫶

if you supply the --rmdirs flag, it will remove all empty directories along with it. you can also use the separate command rmdir or rmdirs to delete empty directories only ✨

so for example, to delete all files bigger than 100 MiB, you may first wanna check what would be deleted (use either of these, queen):

rclone --min-size 100M lsl remote:path
rclone --dry-run --min-size 100M delete remote:path

then proceed with the actual delete:

rclone --min-size 100M delete remote:path

that reads "delete everything with a minimum size of 100 MiB", hence delete all files bigger than 100 MiB 💀

Important: since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. no cap, this is the one 😭

rclone delete remote:path [flags]

🎀 Options 🎀

-h, --help — help for delete
--rmdirs — rmdirs removes empty directories but leaves root intact

options shared with other commands are described next. see the global flags page for global options not listed here 👑

💖 Important Options 💖

important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

💜 Listing Options 💜

flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🌈 See Also 🌈

rclone — Show help for rclone commands, flags and backends.

💅 rclone purge 💅

Remove the path and all of its contents. iconically destructive, we love a clean slate (respectfully, back it up first) 💖

✨ Synopsis ✨

remove the path and all of its contents. and here's the crucial part bestie: this does not obey include/exclude filters — everything will be removed 💀 use the delete command if you wanna selectively delete files. to delete empty directories only, use command rmdir or rmdirs 🎀

the concurrency of this operation is controlled by the --checkers global flag. however, some backends will implement this command directly, in which case --checkers will be ignored 🫶

Important: since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. fr fr, do the dry run 🙈

rclone purge remote:path [flags]

🎀 Options 🎀

-h, --help — help for purge

options shared with other commands are described next. see the global flags page for global options not listed here 👑

💖 Important Options 💖

important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🌈 See Also 🌈

rclone — Show help for rclone commands, flags and backends.

🧚 rclone mkdir 🧚

Make the path if it doesn't already exist. just manifesting a directory, lowkey the easiest one here ✨

rclone mkdir remote:path [flags]

🎀 Options 🎀

-h, --help — help for mkdir

options shared with other commands are described next. see the global flags page for global options not listed here 👑

💖 Important Options 💖

important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🌈 See Also 🌈

rclone — Show help for rclone commands, flags and backends.

⭐ rclone rmdir ⭐

Remove the empty directory at path. she's gotta be actually empty or she stays, periodt 😌

🌸 Synopsis 🌸

this removes empty directory given by path. will not remove the path if it has any objects in it, not even empty subdirectories. use command rmdirs (or delete with option --rmdirs) to do that 👑

to delete a path and any objects in it, use purge command 🌈

rclone rmdir remote:path [flags]

🎀 Options 🎀

-h, --help — help for rmdir

options shared with other commands are described next. see the global flags page for global options not listed here 👑

💖 Important Options 💖

important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🌈 See Also 🌈

rclone — Show help for rclone commands, flags and backends.

rclone check 💅

Checks the files in the source and destination match.

✨ Synopsis ✨

Okay bestie, so check does exactly what it says on the tin — it peeks at your source and your destination and tells you whether they match. It compares sizes and hashes (that's MD5 or SHA1) and logs a whole report of the files that don't line up. And the best part? It is a total soft touch — it does not alter the source or the destination. Not even a little. 🌸

If you're rocking a crypt remote, there's a dedicated command just for you called cryptcheck, and that one can actually check the checksums of the encrypted files. iykyk 🧚

Slap on the --size-only flag and it'll only compare sizes, not hashes — so it's giving "quick vibe check" energy. Use that one when you're in a hurry. ⚡

Add --download and it'll literally download the data from both remotes and compare them on the fly. This is lowkey a lifesaver for remotes that don't support hashes, or if you're the type who really wants to verify all the data with your own eyeballs. 😌

If you pass --checkfile HASH with a valid hash name, then source:path has to point at a text file in the SUM format. That's the rule, bestie, no cap.

Pass --one-way and it only checks that the files in the source match up with the files in the destination — not the other way around. Which means: extra files chillin' in the destination that aren't in the source? Not detected. They just sneak by. 👀

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags all write paths — one per line — into the file name you hand them (or to stdout if you pass -). Full details on what each one spits out are down in the help below. So for example, --differ will write every path that's present on both the source and the destination but is different. Periodt.

And then there's --combined, which writes a file (or stdout) containing every single file path with a little symbol, then a space, then the path — telling you what happened to it. These are very reminiscent of diff files, if diff files were cute. 💖

= path means path was found in source and destination and was identical
- path means path was missing on the source, so only in the destination
+ path means path was missing on the destination, so only in the source
* path means path was present in source and destination but different.
! path means there was an error reading or hashing the source or dest.

The default number of parallel checks is 8. See the --checkers=N option for more info, bestie. 🦋

rclone check source:path dest:path [flags]

🎀 Options 🎀

-C, --checkfile string — Treat source:path as a SUM file with hashes of the given type
--combined string — Make a combined report of changes to this file
--differ string — Report all non-matching files to this file
--download — Check by downloading rather than with hash
--error string — Report all files with errors (hashing or reading) to this file
-h, --help — help for check
--match string — Report all matching files to this file
--missing-on-dst string — Report all files missing from the destination to this file
--missing-on-src string — Report all files missing from the source to this file
--one-way — Check one way only, source files must exist on remote

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

Check Options

Flags used for check commands

--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🌈 See Also 🌈

rclone - Show help for rclone commands, flags and backends.

rclone ls 👑

List the objects in the path with size and path.

✨ Synopsis ✨

Okay so ls lists all the objects in the source path straight to standard output in a human-readable format, showing the size and the path. And yes bestie, it recurses by default — it goes deep. 🕳️

$ rclone ls swift:bucket
    60295 bevajer5jef
    90613 canole
    94467 diwogej7
    37600 fubuwic

Any of the filtering options can be applied to this command. Every single one. Go wild. 💅

There are several related list commands, and they're all giving their own little moment:

ls to list size and path of objects only
lsl to list modification time, size and path of objects only
lsd to list directories only
lsf to list objects and directories in easy to parse format
lsjson to list objects and directories in JSON format

So ls, lsl and lsd are designed to be human-readable. lsf is designed to be both human and machine-readable. And lsjson? That one's designed to be machine-readable, periodt. 🤖

Heads up though: ls and lsl recurse by default — so use --max-depth 1 to stop the recursion. The other list commands, lsd, lsf and lsjson, do not recurse by default, so use -R to make them recurse. The way they're all so different... iconic honestly. 🌸

Also, listing a nonexistent directory will produce an error — except for remotes which can't have empty directories (e.g. s3, swift, or gcs — the bucket-based remotes). Those ones just can't relate. 🙈

rclone ls remote:path [flags]

🎀 Options 🎀

-h, --help — help for ls

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🌈 See Also 🌈

rclone - Show help for rclone commands, flags and backends.

🎀 rclone lsd 🎀

List all directories/containers/buckets in the path. yes bestie we're just listing the folders today 💅

Synopsis

okay so it lists the directories in the source path straight to standard output. it does not recurse by default — if you want it to dig down into subfolders, hit it with the -R flag, periodt.

it shows you four things about each directory: the total size of the directory (if known, -1 if not), the modification time (if known, the current time if not), the number of objects in the directory (if known, -1 if not), and then the name. like, for example 🌸

$ rclone lsd swift:
      494000 2018-04-26 08:43:20     10000 10000files
          65 2018-04-26 08:43:20         1 1File

orrr ✨

$ rclone lsd drive:test
          -1 2016-10-17 17:41:53        -1 1000files
          -1 2017-01-03 14:40:54        -1 2500files
          -1 2017-07-08 14:39:28        -1 4000files

if all you want is the directory names, no cap, just use rclone lsf --dirs-only 🫶

any of the filtering options can be applied to this command, iykyk.

there are several related list commands, lemme introduce the whole squad 💖

ls to list size and path of objects only
lsl to list modification time, size and path of objects only
lsd to list directories only
lsf to list objects and directories in easy to parse format
lsjson to list objects and directories in JSON format

ls, lsl, lsd are designed to be human-readable. lsf is designed to be human and machine-readable. lsjson is designed to be machine-readable. it's giving "different tools for different vibes" 🌈

heads up: ls and lsl recurse by default — use --max-depth 1 to stop the recursion going feral.

the other list commands lsd, lsf, lsjson do not recurse by default — use -R to make them recurse.

listing a nonexistent directory will produce an error, except for remotes which can't have empty directories (like s3, swift, or gcs — the bucket-based remotes). those ones just vibe. 🙈

rclone lsd remote:path [flags]

Options

-h, --help — help for lsd
-R, --recursive — Recurse into the listing

Options shared with other commands are described next. See the global flags page for global options not listed here.

Flags for filtering directory listings 👑

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories 💅

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🦋 rclone lsl 🦋

List the objects in path with modification time, size and path. the full receipts version of ls bestie 💖

Synopsis

Lists the objects in the source path to standard output in a human readable format — that's modification time, size and path all up in there. and it recurses by default, so it'll just keep going down, no permission needed. ✨

eg 🌸

$ rclone lsl swift:bucket
    60295 2016-06-25 18:55:41.062626927 bevajer5jef
    90613 2016-06-25 18:55:43.302607074 canole
    94467 2016-06-25 18:55:43.046609333 diwogej7
    37600 2016-06-25 18:55:40.814629136 fubuwic

any of the filtering options can be applied to this command. slay.

there are several related list commands — here's the whole crew again 🫶

ls to list size and path of objects only
lsl to list modification time, size and path of objects only
lsd to list directories only
lsf to list objects and directories in easy to parse format
lsjson to list objects and directories in JSON format

ls, lsl, lsd are designed to be human-readable. lsf is designed to be human and machine-readable. lsjson is designed to be machine-readable. iconic trio behavior ngl 🌈

heads up again: ls and lsl recurse by default — use --max-depth 1 to stop the recursion.

the other list commands lsd, lsf, lsjson do not recurse by default — use -R to make them recurse.

rclone lsl remote:path [flags]

Options

-h, --help — help for lsl

Options shared with other commands are described next. See the global flags page for global options not listed here.

Flags for filtering directory listings 👑

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories 💅

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

💅 rclone md5sum

okay bestie, gather round — this one makes an md5sum file for literally every object chilling in the path. 🎀

✨ Synopsis ✨

So here's the deal: it produces an md5sum file for all the objects in the path, and it's in the same format the standard md5sum tool spits out. no cap, identical vibes.

By default the hash is requested from the remote. If MD5 isn't supported by the remote, no hash will be returned — that's just how it is. But with the download flag? The file gets downloaded from the remote and hashed locally, which enables MD5 for literally any remote. 💖

For other algorithms, go peek at the hashsum command. Running rclone md5sum remote:path is equivalent to running rclone hashsum MD5 remote:path. iykyk.

This command can also hash data received on standard input (stdin), by not passing a remote:path, or by passing a hyphen as remote:path when there is data to read (if not, the hyphen will be treated literally, as a relative path). 🫶

rclone md5sum remote:path [flags]

🎀 Options 🎀

--base64 — Output base64 encoded hashsum
-C, --checkfile _string_ — Validate hashes against a given SUM file instead of printing them
--download — Download the file and hash it locally; if this flag is not specified, the hash is requested from the remote
-h, --help — help for md5sum
--output-file _string_ — Output hashsums to a file rather than the terminal

Options shared with other commands are described next. See the global flags page for global options not listed here. 👑

Flags for filtering directory listings 🦋

--delete-excluded — Delete files on dest excluded from sync
--exclude _stringArray_ — Exclude files matching pattern
--exclude-from _stringArray_ — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present _stringArray_ — Exclude directories if filename is present
--files-from _stringArray_ — Read list of source-file names from file (use - to read from stdin)
--files-from-raw _stringArray_ — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter _stringArray_ — Add a file filtering rule
--filter-from _stringArray_ — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include _stringArray_ — Include files matching pattern
--include-from _stringArray_ — Read file include patterns from file (use - to read from stdin)
--max-age _Duration_ — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth _int_ — If set limits the recursion depth to this (default -1)
--max-size _SizeSuffix_ — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude _stringArray_ — Exclude metadatas matching pattern
--metadata-exclude-from _stringArray_ — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter _stringArray_ — Add a metadata filtering rule
--metadata-filter-from _stringArray_ — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include _stringArray_ — Include metadatas matching pattern
--metadata-include-from _stringArray_ — Read metadata include patterns from file (use - to read from stdin)
--min-age _Duration_ — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size _SizeSuffix_ — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

💜 Listing Options 💜

Flags for listing directories ✨

--default-time _Time_ — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🔥 See Also 🔥

rclone — Show help for rclone commands, flags and backends.

👑 rclone sha1sum

And now for sha1sum's moment, because she also ate. 🍓

✨ Synopsis ✨

Produces an sha1sum file for all the objects in the path. This is in the same format as the standard sha1sum tool produces. 💅

By default, the hash is requested from the remote. If SHA-1 is not supported by the remote, no hash will be returned. With the download flag, the file will be downloaded from the remote and hashed locally, enabling SHA-1 for any remote. 🌈

For other algorithms, see the hashsum command. Running rclone sha1sum remote:path is equivalent to running rclone hashsum SHA1 remote:path. fr fr.

This command can also hash data received on standard input (stdin), by not passing a remote:path, or by passing a hyphen as remote:path when there is data to read (if not, the hyphen will be treated literally, as a relative path). 🧚

(and yes bestie, this command can also hash data received on STDIN, if not passing a remote:path — she said it twice, we love a queen who repeats herself. 💖)

rclone sha1sum remote:path [flags]

🎀 Options 🎀

--base64 — Output base64 encoded hashsum
-C, --checkfile _string_ — Validate hashes against a given SUM file instead of printing them
--download — Download the file and hash it locally; if this flag is not specified, the hash is requested from the remote
-h, --help — help for sha1sum
--output-file _string_ — Output hashsums to a file rather than the terminal

Options shared with other commands are described next. See the global flags page for global options not listed here. ⭐

Flags for filtering directory listings 🦋

--delete-excluded — Delete files on dest excluded from sync
--exclude _stringArray_ — Exclude files matching pattern
--exclude-from _stringArray_ — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present _stringArray_ — Exclude directories if filename is present
--files-from _stringArray_ — Read list of source-file names from file (use - to read from stdin)
--files-from-raw _stringArray_ — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter _stringArray_ — Add a file filtering rule
--filter-from _stringArray_ — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include _stringArray_ — Include files matching pattern
--include-from _stringArray_ — Read file include patterns from file (use - to read from stdin)
--max-age _Duration_ — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth _int_ — If set limits the recursion depth to this (default -1)
--max-size _SizeSuffix_ — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude _stringArray_ — Exclude metadatas matching pattern
--metadata-exclude-from _stringArray_ — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter _stringArray_ — Add a metadata filtering rule
--metadata-filter-from _stringArray_ — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include _stringArray_ — Include metadatas matching pattern
--metadata-include-from _stringArray_ — Read metadata include patterns from file (use - to read from stdin)
--min-age _Duration_ — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size _SizeSuffix_ — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

💜 Listing Options 💜

Flags for listing directories ✨

--default-time _Time_ — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🔥 See Also 🔥

rclone — Show help for rclone commands, flags and backends.

🌸 rclone size 🌸

Prints the total size and number of objects in remote:path. Like, a lil headcount for your files, bestie 💖

✨ Synopsis ✨

It counts up all the objects in the path and adds up the total size, then prints the result to standard output. That's it, that's the whole job 💅

By default the output is in human-readable format, but it shows values in both</> human-readable format and the raw numbers (heads up: the global option --human-readable is not considered here, so don't come for it). If you want JSON instead, use the option --json to format the output as JSON.

It recurses by default! 🌈 Use --max-depth 1 to stop the recursion, if you just want the top layer.

Some backends do not always provide file sizes — Google Photos and Google Docs are the classic examples, iykyk. 😭 When that happens rclone will show a notice in the log telling you how many such files it ran into, and it counts them in as empty files in the output of the size command. Not ideal, not a crime, just how it is.

rclone size remote:path [flags]

🎀 Options 🎀

-h, --help — help for size, the lil "what does this do again" button 🫶
--json — Format output as JSON ✨

The options shared with other commands are coming up next. For global options that aren't listed here, go check the global flags page 👑

Flags for filtering directory listings — your lil bouncers at the door 🚪

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

⭐ Listing Options ⭐

Flags for listing directories — the vibes-only view of your folders 📁

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

💜 See Also 💜

rclone — Show help for rclone commands, flags and backends.

👑 rclone version 👑

Show the version number. The classic "wait what am I even running" moment 💀

✨ Synopsis ✨

It shows the rclone version number, the go version, the build target OS and architecture, the runtime OS and kernel version and bitness, the build tags, and the type of executable (static or dynamic). Basically a whole little ID card for your binary 🪪

For example:

$ rclone version
rclone v1.55.0
- os/version: ubuntu 18.04 (64 bit)
- os/kernel: 4.15.0-136-generic (x86_64)
- os/type: linux
- os/arch: amd64
- go/version: go1.16
- go/linking: static
- go/tags: none

Note: before rclone version 1.55 the os/type and os/arch lines were merged, and the “go/version” line was tagged as “go version”. History, bestie 📜

If you supply the –check flag, then it will do an online check to compare your version with the latest release and the latest beta. Living on the edge, respectfully 🫡

$ rclone version --check
yours:  1.42.0.6
latest: 1.42          (released 2018-06-16)
beta:   1.42.0.5      (released 2018-06-17)

Or:

$ rclone version --check
yours:  1.41
latest: 1.42          (released 2018-06-16)
  upgrade: https://downloads.rclone.org/v1.42
beta:   1.42.0.5      (released 2018-06-17)
  upgrade: https://beta.rclone.org/v1.42-005-g56e1e820

rclone version [flags]

🎀 Options 🎀

--check — Check for new version 🔥
-h, --help — help for version

For global options that aren't listed here, check the global flags page 💖

💜 See Also 💜

rclone — Show help for rclone commands, flags and backends.

🧚 rclone cleanup 🧚

Clean up the remote if possible. Yes, like actually tidying your room for once ✨

✨ Synopsis ✨

Clean up the remote if possible. This empties the trash or deletes old file versions. Not supported by all remotes, so don't be shocked if your backend just says no 🙈

rclone cleanup remote:path [flags]

🎀 Options 🎀

-h, --help — help for cleanup

The options shared with other commands are described next. For global options not listed here, the global flags page has you 🫶

💖 Important Options 💖

Important flags useful for most commands — the holy trinity, no cap 🔥

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

💜 See Also 💜

rclone — Show help for rclone commands, flags and backends.

💖 rclone dedupe 💖

Interactively find duplicate filenames and delete/rename them. periodt.

✨ Synopsis ✨

okay so bestie, by default dedupe is gonna interactively hunt down files with duplicate names and offer to delete all but one or rename them so they're different. That whole vibe is called deduping by name.

ngl, deduping by name is only useful with a small group of backends (e.g. Google Drive, Opendrive) that can have duplicate file names. It can be run on wrapping backends (e.g. crypt) if they wrap a backend which supports duplicate file names.

However if --by-hash is passed in then dedupe will find files with duplicate hashes instead which will work on any backend which supports at least one hash. This can be used to find files with duplicate content. This is known as deduping by hash. ✨

If deduping by name, first rclone will merge directories with the same name. It will do this iteratively until all the identically named directories have been merged. like it literally will not stop until they're merged.

Next, if deduping by name, for every group of duplicate file names / hashes, it will delete all but one identical file it finds without confirmation. This means that for most duplicated files the dedupe command will not be interactive.

dedupe considers files to be identical if they have the same file path and the same hash. If the backend does not support hashes (e.g. crypt wrapping Google Drive) then they will never be found to be identical. If you use the --size-only flag then files will be considered identical if they have the same size (any hash will be ignored). This can be useful on crypt backends which do not support hashes.

Next rclone will resolve the remaining duplicates. Exactly which action is taken depends on the dedupe mode. By default, rclone will interactively query the user for each one.

Important: Since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. 🚨 do not skip this step bestie

Here is an example run.

Before - with duplicates

$ rclone lsl drive:dupes
  6048320 2016-03-05 16:23:16.798000000 one.txt
  6048320 2016-03-05 16:23:11.775000000 one.txt
   564374 2016-03-05 16:23:06.731000000 one.txt
  6048320 2016-03-05 16:18:26.092000000 one.txt
  6048320 2016-03-05 16:22:46.185000000 two.txt
  1744073 2016-03-05 16:22:38.104000000 two.txt
   564374 2016-03-05 16:22:52.118000000 two.txt

Now the dedupe session

$ rclone dedupe drive:dupes
2016/03/05 16:24:37 Google drive root 'dupes': Looking for duplicates using interactive mode.
one.txt: Found 4 files with duplicate names
one.txt: Deleting 2/3 identical duplicates (MD5 "1eedaa9fe86fd4b8632e2ac549403b36")
one.txt: 2 duplicates remain
  1:      6048320 bytes, 2016-03-05 16:23:16.798000000, MD5 1eedaa9fe86fd4b8632e2ac549403b36
  2:       564374 bytes, 2016-03-05 16:23:06.731000000, MD5 7594e7dc9fc28f727c42ee3e0749de81
s) Skip and do nothing
k) Keep just one (choose which in next step)
r) Rename all to be different (by changing file.jpg to file-1.jpg)
s/k/r> k
Enter the number of the file to keep> 1
one.txt: Deleted 1 extra copies
two.txt: Found 3 files with duplicate names
two.txt: 3 duplicates remain
  1:       564374 bytes, 2016-03-05 16:22:52.118000000, MD5 7594e7dc9fc28f727c42ee3e0749de81
  2:      6048320 bytes, 2016-03-05 16:22:46.185000000, MD5 1eedaa9fe86fd4b8632e2ac549403b36
  3:      1744073 bytes, 2016-03-05 16:22:38.104000000, MD5 851957f7fb6f0bc4ce76be966d336802
s) Skip and do nothing
k) Keep just one (choose which in next step)
r) Rename all to be different (by changing file.jpg to file-1.jpg)
s/k/r> r
two-1.txt: renamed from: two.txt
two-2.txt: renamed from: two.txt
two-3.txt: renamed from: two.txt

The result being

$ rclone lsl drive:dupes
  6048320 2016-03-05 16:23:16.798000000 one.txt
   564374 2016-03-05 16:22:52.118000000 two-1.txt
  6048320 2016-03-05 16:22:46.185000000 two-2.txt
  1744073 2016-03-05 16:22:38.104000000 two-3.txt

Dedupe can be run non interactively using the --dedupe-mode flag or by using an extra parameter with the same value. ur welcome.

--dedupe-mode interactive - interactive as above.
--dedupe-mode skip - removes identical files then skips anything left.
--dedupe-mode first - removes identical files then keeps the first one.
--dedupe-mode newest - removes identical files then keeps the newest one.
--dedupe-mode oldest - removes identical files then keeps the oldest one.
--dedupe-mode largest - removes identical files then keeps the largest one.
--dedupe-mode smallest - removes identical files then keeps the smallest one.
--dedupe-mode rename - removes identical files then renames the rest to be different.
--dedupe-mode list - lists duplicate dirs and files only and changes nothing.

For example, to rename all the identically named photos in your Google Photos directory, do

rclone dedupe --dedupe-mode rename "drive:Google Photos"

rclone dedupe rename "drive:Google Photos"

rclone dedupe [mode] remote:path [flags]

🎀 Options 🎀

--by-hash — Find identical hashes rather than names
--dedupe-mode string — Dedupe mode interactive|skip|first|newest|oldest|largest|smallest|rename (default "interactive")
-h, --help — help for dedupe

Options shared with other commands are described next. See the global flags page for global options not listed here.

💅 Important Options 💅

Important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🦋 See Also 🦋

rclone — Show help for rclone commands, flags and backends.

💖 rclone about 💖

Get quota information from the remote. ✨

✨ Synopsis ✨

Prints quota information about a remote to standard output. The output is typically used, free, quota and trash contents. like a lil receipt for ur cloud.

E.g. Typical output from rclone about remote: is:

Total:   17 GiB
Used:    7.444 GiB
Free:    1.315 GiB
Trashed: 100.000 MiB
Other:   8.241 GiB

Where the fields are:

Total: Total size available.
Used: Total size used.
Free: Total space available to this user.
Trashed: Total space used by trash.
Other: Total amount in other storage (e.g. Gmail, Google Photos).
Objects: Total number of objects in the storage.

All sizes are in number of bytes.

Applying a --full flag to the command prints the bytes in full, e.g.

Total:   18253611008
Used:    7993453766
Free:    1411001220
Trashed: 104857602
Other:   8849156022

A --json flag generates conveniently machine-readable output, e.g.

{
    "total": 18253611008,
    "used": 7993453766,
    "trashed": 104857602,
    "other": 8849156022,
    "free": 1411001220
}

Not all backends print all fields. Information is not included if it is not provided by a backend. Where the value is unlimited it is omitted. if it's unlimited, rclone just doesn't say anything, iconic.

Some backends does not support the rclone about command at all, see complete list in documentation.

rclone about remote: [flags]

🎀 Options 🎀

--full — Full numbers instead of human-readable
-h, --help — help for about
--json — Format output as JSON

See the global flags page for global options not listed here.

🦋 See Also 🦋

rclone — Show help for rclone commands, flags and backends.

💖 rclone authorize 💖

Remote authorization. 🔐

✨ Synopsis ✨

Remote authorization. Used to authorize a remote or headless rclone from a machine with a browser - use as instructed by rclone config.

The command requires 1-3 arguments:

fs name (e.g., "drive", "s3", etc.)
Either a base64 encoded JSON blob obtained from a previous rclone config session
Or a client_id and client_secret pair obtained from the remote service

Use --auth-no-open-browser to prevent rclone to open auth link in default browser automatically.

Use --template to generate HTML output via a custom Go template. If a blank string is provided as an argument to this flag, the default template is used.

rclone authorize <fs name> [base64_json_blob | client_id client_secret] [flags]

🎀 Options 🎀

--auth-no-open-browser — Do not automatically open auth link in default browser
-h, --help — help for authorize
--template string — The path to a custom Go template for generating HTML responses

See the global flags page for global options not listed here.

🦋 See Also 🦋

rclone — Show help for rclone commands, flags and backends.

💖 rclone backend 💖

Run a backend-specific command. iykyk

✨ Synopsis ✨

This runs a backend-specific command. The commands themselves (except for "help" and "features") are defined by the backends and you should see the backend docs for definitions.

You can discover what commands a backend implements by using

rclone backend help remote:
rclone backend help <backendname>

You can also discover information about the backend using (see operations/fsinfo in the remote control docs for more info).

rclone backend features remote:

Pass options to the backend command with -o. This should be key=value or key, e.g.:

rclone backend stats remote:path stats -o format=json -o long

Pass arguments to the backend by placing them on the end of the line

rclone backend cleanup remote:path file1 file2 file3

Note to run these commands on a running backend then see backend/command in the rc docs.

rclone backend <command> remote:path [opts] <args> [flags]

🎀 Options 🎀

-h, --help — help for backend
--json — Always output in JSON format
-o, --option stringArray — Option in the form name=value or name

Options shared with other commands are described next. See the global flags page for global options not listed here.

💅 Important Options 💅

Important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🦋 See Also 🦋

rclone — Show help for rclone commands, flags and backends.

💖 rclone bisync 💖

Perform bidirectional synchronization between two paths. 🔄

✨ Synopsis ✨

Perform bidirectional synchronization between two paths.

Bisync is giving bidirectional cloud sync in rclone, bestie. 💖 It retains the Path1 and Path2 filesystem listings from the prior run. On each successive run it will:

list files on Path1 and Path2, and check for changes on each side. Changes include New, Newer, Older, and Deleted files. 👀
Propagate changes on Path1 to Path2, and vice-versa. 🔁

Bisync is in beta and is considered an advanced command, so use with care. 😭 Make sure you have read and understood the entire manual (especially the Limitations section) before using, or data loss can result. Questions can be asked in the Rclone Forum. 💬

See full bisync description for details. 📖

rclone bisync remote1:path1 remote2:path2 [flags]

Options ✨

--backup-dir1 string — --backup-dir for Path1. Must be a non-overlapping path on the same remote. 🚫
--backup-dir2 string — --backup-dir for Path2. Must be a non-overlapping path on the same remote. 🚫
--check-access — Ensure expected RCLONE_TEST files are found on both Path1 and Path2 filesystems, else abort. 🛑
--check-filename string — Filename for --check-access (default: RCLONE_TEST). 📝
--check-sync string — Controls comparison of final listings: true|false|only (default: true) (default "true"). 🔍
--compare string — Comma-separated list of bisync-specific compare options ex. 'size,modtime,checksum' (default: 'size,modtime'). 🧐
--conflict-loser ConflictLoserAction — Action to take on the loser of a sync conflict (when there is a winner) or on both files (when there is no winner): , num, pathname, delete (default: num). ⚔️
--conflict-resolve string — Automatically resolve conflicts by preferring the version that is: none, path1, path2, newer, older, larger, smaller (default: none) (default "none"). 🕊️
--conflict-suffix string — Suffix to use when renaming a --conflict-loser. Can be either one string or two comma-separated strings to assign different suffixes to Path1/Path2. (default: 'conflict') 🏷️
--create-empty-src-dirs — Sync creation and deletion of empty directories. (Not compatible with --remove-empty-dirs) 📁
--download-hash — Compute hash by downloading when otherwise unavailable. (warning: may be slow and use lots of data!) ⚠️
--filters-file string — Read filtering patterns from a file. 📄
--force — Bypass --max-delete safety check and run the sync. Consider using with --verbose. 💪
-h, --help — help for bisync. 🆘
--ignore-listing-checksum — Do not use checksums for listings (add --ignore-checksum to additionally skip post-copy checksum checks). 🚫
--max-lock Duration — Consider lock files older than this to be expired (default: 0 (never expire)) (minimum: 2m) (default 0s). ⏳
--no-cleanup — Retain working files (useful for troubleshooting and testing). 🧹
--no-slow-hash — Ignore listing checksums only on backends where they are slow. 🐢
--recover — Automatically recover from interruptions without requiring --resync. 🔄
--remove-empty-dirs — Remove ALL empty directories at the final cleanup step. 🗑️
--resilient — Allow future runs to retry after certain less-serious errors, instead of requiring --resync. Use at your own risk! 😬
-1, --resync — Performs the resync run. Equivalent to --resync-mode path1. Consider using --verbose or --dry-run first. 🔁
--resync-mode string — During resync, prefer the version that is: path1, path2, newer, older, larger, smaller (default: path1 if --resync, otherwise none for no resync.) (default "none"). 🧭
--slow-hash-sync-only — Ignore slow checksums for listings and deltas, but still consider them during sync calls. 🐌
--workdir string — Use custom working dir - useful for testing. (default: {WORKDIR}). 📂

Options shared with other commands are described next. See the global flags page for global options not listed here. 🌍

Copy Options 🫶

Flags for anything which can copy a file.

--check-first — Do all the checks before starting transfers. ✅
-c, --checksum — Check for changes with size & checksum (if available, or fallback to size only). 🔍
--compare-dest stringArray — Include additional server-side paths during comparison. 🧐
--copy-dest stringArray — Implies --compare-dest but also copies files from paths into destination. 📥
--cutoff-mode HARD|SOFT|CAUTIOUS — Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD). 🛑
--ignore-case-sync — Ignore case when synchronizing. 🔠
--ignore-checksum — Skip post copy check of checksums. 🚫
--ignore-existing — Skip all files that exist on destination. 🚫
--ignore-size — Ignore size when skipping use modtime or checksum. 📏
-I, --ignore-times — Don't skip items that match size and time - transfer all unconditionally. 🕰️
--immutable — Do not modify files, fail if existing files have been modified. 🔒
--inplace — Download directly to destination file instead of atomic download to temp/rename. ⚡
-l, --links — Translate symlinks to/from regular files with a .rclonelink extension. 🔗
--max-backlog int — Maximum number of objects in sync or check backlog (default 10000). 📚
--max-duration Duration — Maximum duration rclone will transfer data for (default 0s). ⏱️
--max-transfer SizeSuffix — Maximum size of data to transfer (default off). 📦
-M, --metadata — If set, preserve metadata when copying objects. 🏷️
--modify-window Duration — Max time diff to be considered the same (default 1ns). ⏳
--multi-thread-chunk-size SizeSuffix — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi). 🧵
--multi-thread-cutoff SizeSuffix — Use multi-thread downloads for files above this size (default 256Mi). 🚀
--multi-thread-streams int — Number of streams to use for multi-thread downloads (default 4). 🌊
--multi-thread-write-buffer-size SizeSuffix — In memory buffer size for writing when in multi-thread mode (default 128Ki). 🧠
--no-check-dest — Don't check the destination, copy regardless. 🙈
--no-traverse — Don't traverse destination file system on copy. 🚶
--no-update-dir-modtime — Don't update directory modification times. 📁
--no-update-modtime — Don't update destination modtime if files identical. 🕰️
--order-by string — Instructions on how to order the transfers, e.g. 'size,descending'. 🔢
--partial-suffix string — Add partial-suffix to temporary file name when --inplace is not used (default ".partial"). 📝
--refresh-times — Refresh the modtime of remote files. 🔄
--server-side-across-configs — Allow server-side operations (e.g. copy) to work across different configs. 🌐
--size-only — Skip based on size only, not modtime or checksum. 📏
--streaming-upload-cutoff SizeSuffix — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki). 📤
-u, --update — Skip files that are newer on the destination. ⏫

Important Options 🔥

Important flags useful for most commands.

-n, --dry-run — Do a trial run with no permanent changes. 🧪
-i, --interactive — Enable interactive mode. 💬
-v, --verbose count — Print lots more stuff (repeat for more). 📢

Flags for filtering directory listings.

--delete-excluded — Delete files on dest excluded from sync. 🗑️
--exclude stringArray — Exclude files matching pattern. 🚫
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin). 📄
--exclude-if-present stringArray — Exclude directories if filename is present. 📁
--files-from stringArray — Read list of source-file names from file (use - to read from stdin). 📄
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin). 📄
-f, --filter stringArray — Add a file filtering rule. ➕
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin). 📄
--ignore-case — Ignore case in filters (case insensitive). 🔠
--include stringArray — Include files matching pattern. ✅
--include-from stringArray — Read file include patterns from file (use - to read from stdin). 📄
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off). ⏳
--max-depth int — If set limits the recursion depth to this (default -1). 📏
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off). 📦
--metadata-exclude stringArray — Exclude metadatas matching pattern. 🚫
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin). 📄
--metadata-filter stringArray — Add a metadata filtering rule. ➕
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin). 📄
--metadata-include stringArray — Include metadatas matching pattern. ✅
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin). 📄
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off). ⏳
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off). 📦

🐱 rclone cat

Ok bestie, this one concatenates any files and sends them to stdout. That's it, that's the whole vibe: file go in, file come out. ✨

🌸 Synopsis

Sends any files to standard output.

Wanna dump one single file? Iconic. Do this:

rclone cat remote:path/to/file

Wanna dump any file in dir or its subdirectories? Also iconic:

rclone cat remote:path/to/dir

Wanna dump every .txt file in dir or its subdirectories? Slay:

rclone --include "*.txt" cat remote:path/to/dir

Use the --head flag to print characters only at the start, --tail for the end and --offset and --count to print a section in the middle. 🎀 Note that if offset is negative it will count from the end, so --offset -1 --count 1 is equivalent to --tail 1. No cap.

Use the --separator flag to print a separator value between files. Be suuuure to shell-escape special characters. For example, to print a newline between files, use:

bash:

rclone --include "*.txt" --separator $'\n' cat remote:path/to/dir

powershell:

rclone --include "*.txt" --separator "`n" cat remote:path/to/dir

rclone cat remote:path [flags]

💅 Options

--count int — Only print N characters (default -1)
--discard — Discard the output instead of printing. like, it read the file for the plot and then forgot about it 🫶
--head int — Only print the first N characters
-h, --help — help for cat
--offset int — Start printing at offset N (or from end if -ve)
--separator string — Separator to use between objects when printing multiple files
--tail int — Only print the last N characters

Options shared with other commands are described next. See the global flags page for global options not listed here.

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

📋 Listing Options

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

👀 See Also

rclone — Show help for rclone commands, flags and backends.

🧮 rclone checksum

Checks the files in the destination against a SUM file. Detective mode: activated 🔍✨

🌸 Synopsis

Checks that hashsums of destination files match the SUM file. It compares hashes (MD5, SHA1, etc) and logs a report of files which don't match. It doesn't alter the file system — it's all vibes and no consequences, purely observational, main character energy only.

The sumfile is treated as the source and the dst:path is treated as the destination for the purposes of the output. iykyk.

If you supply the --download flag, it will download the data from the remote and calculate the content hash on the fly. This can be useful for remotes that don't support hashes or if you really want to check all the data. (yes bestie, all of it. every last byte 😭)

Note that hash values in the SUM file are treated as case insensitive.

If you supply the --one-way flag, it will only check that files in the source match the files in the destination, not the other way around. This means that extra files in the destination that are not in the source will not be detected. 🙈

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name (or stdout if it is -) supplied. What they write is described in the help below. For example --differ will write all paths which are present on both the source and destination but different.

The --combined flag will write a file (or stdout) which contains all file paths with a symbol and then a space and then the path to tell you what happened to it. These are reminiscent of diff files. Ok so here's the legend:

= path means path was found in source and destination and was identical
- path means path was missing on the source, so only in the destination
+ path means path was missing on the destination, so only in the source
* path means path was present in source and destination but different.
! path means there was an error reading or hashing the source or dest.

The default number of parallel checks is 8. See the --checkers=N option for more information.

rclone checksum <hash> sumfile dst:path [flags]

💅 Options

--combined string — Make a combined report of changes to this file
--differ string — Report all non-matching files to this file
--download — Check by hashing the contents
--error string — Report all files with errors (hashing or reading) to this file
-h, --help — help for checksum
--match string — Report all matching files to this file
--missing-on-dst string — Report all files missing from the destination to this file
--missing-on-src string — Report all files missing from the source to this file
--one-way — Check one way only, source files must exist on remote

Options shared with other commands are described next. See the global flags page for global options not listed here.

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

📋 Listing Options

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

👀 See Also

rclone — Show help for rclone commands, flags and backends.

🐚 rclone completion

Output completion script for a given shell. Tab-completion but make it fashion 💅✨

🌸 Synopsis

Generates a shell completion script for rclone. Run with --help to list the supported shells. (yes, --help is the vibes-finder here, go look 👀)

💅 Options

-h, --help — help for completion

See the global flags page for global options not listed here.

👀 See Also

rclone — Show help for rclone commands, flags and backends.
rclone completion bash — Output bash completion script for rclone.
rclone completion fish — Output fish completion script for rclone. 🐟
rclone completion powershell — Output powershell completion script for rclone.
rclone completion zsh — Output zsh completion script for rclone.

✨ rclone completion bash ✨

Output bash completion script for rclone. 💖

🦋 SYNOPSIS 🦋

Generates a bash shell autocompletion script for rclone. no cap.

By default, when run without any arguments,

rclone completion bash

the generated script will be written to

/etc/bash_completion.d/rclone

and so rclone will probably need to be run as root, or with sudo. it's giving "please respect my permissions" energy honestly 🙈

If you supply a path to a file as the command line argument, then the generated script will be written to that file, in which case you should not need root privileges. slay.

If output_file is -, then the output will be written to stdout. love that for us ⭐

If you have installed the script into the default location, you can logout and login again to use the autocompletion script.

Alternatively, you can source the script directly

. /path/to/my_bash_completion_scripts/rclone

and the autocompletion functionality will be added to your current shell. literally instant glow-up ✨

rclone completion bash [output_file] [flags]

🎀 OPTIONS 🎀

-h, --help — help for bash

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone completion - Output completion script for a given shell.

🐟 rclone completion fish 🐟

Output fish completion script for rclone. 💜

🌸 SYNOPSIS 🌸

Generates a fish autocompletion script for rclone.

This writes to /etc/fish/completions/rclone.fish by default so will probably need to be run with sudo or as root, e.g.

sudo rclone completion fish

Logout and login again to use the autocompletion scripts, or source them directly

. /etc/fish/completions/rclone.fish

If you supply a command line argument the script will be written there.

If output_file is -, then the output will be written to stdout. 🫶

rclone completion fish [output_file] [flags]

🎀 OPTIONS 🎀

-h, --help — help for fish

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone completion - Output completion script for a given shell.

💙 rclone completion powershell 💙

Output powershell completion script for rclone. 👑

🧚 SYNOPSIS 🧚

Generate the autocompletion script for powershell.

To load completions in your current shell session:

rclone completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile. main character setup fr fr 💅

If output_file is - or missing, then the output will be written to stdout.

rclone completion powershell [output_file] [flags]

🎀 OPTIONS 🎀

-h, --help — help for powershell

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone completion - Output completion script for a given shell.

🦄 rclone completion zsh 🦄

Output zsh completion script for rclone. ⭐

💜 SYNOPSIS 💜

Generates a zsh autocompletion script for rclone.

This writes to /usr/share/zsh/vendor-completions/_rclone by default so will probably need to be run with sudo or as root, e.g.

sudo rclone completion zsh

Logout and login again to use the autocompletion scripts, or source them directly

autoload -U compinit && compinit

If you supply a command line argument the script will be written there.

If output_file is -, then the output will be written to stdout. 💖

rclone completion zsh [output_file] [flags]

🎀 OPTIONS 🎀

-h, --help — help for zsh

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone completion - Output completion script for a given shell.

🌟 rclone config create 🌟

Create a new remote with name, type and options. we are BIRTHING a remote, bestie 👑

🌸 SYNOPSIS 🌸

Create a new remote of name with type and options. The options should be passed in pairs of key value or as key=value.

For example, to make a swift remote of name myremote using auto config you would do:

rclone config create myremote swift env_auth true
rclone config create myremote swift env_auth=true

So for example if you wanted to configure a Google Drive remote but using remote authorization you would do this:

rclone config create mydrive drive config_is_local=false

Note that if the config process would normally ask a question the default is taken (unless --non-interactive is used). Each time that happens rclone will print or DEBUG a message saying how to affect the value taken.

If any of the parameters passed is a password field, then rclone will automatically obscure them if they aren't already obscured before putting them in the config file. protective king behavior 🫶

NB If the password parameter is 22 characters or longer and consists only of base64 characters then rclone can get confused about whether the password is already obscured or not and put unobscured passwords into the config file. 😭 If you want to be 100% certain that the passwords get obscured then use the --obscure flag, or if you are 100% certain you are already passing obscured passwords then use --no-obscure. You can also set obscured passwords using the rclone config password command.

The flag --non-interactive is for use by applications that wish to configure rclone themselves, rather than using rclone's text based configuration questions. If this flag is set, and rclone needs to ask the user a question, a JSON blob will be returned with the question in it.

This will look something like (some irrelevant detail removed):

{
    "State": "*oauth-islocal,teamdrive,,",
    "Option": {
        "Name": "config_is_local",
        "Help": "Use web browser to automatically authenticate rclone with remote?\n * Say Y if the machine running rclone has a web browser you can use\n * Say N if running rclone on a (remote) machine without web browser access\nIf not sure try Y. If Y failed, try N.\n",
        "Default": true,
        "Examples": [
            {
                "Value": "true",
                "Help": "Yes"
            },
            {
                "Value": "false",
                "Help": "No"
            }
        ],
        "Required": false,
        "IsPassword": false,
        "Type": "bool",
        "Exclusive": true,
    },
    "Error": "",
}

The format of Option is the same as returned by rclone config providers. The question should be asked to the user and returned to rclone as the --result option along with the --state parameter.

The keys of Option are used as follows:

Name - name of variable - show to user
Help - help text. Hard wrapped at 80 chars. Any URLs should be clicky.
Default - default value - return this if the user just wants the default.
Examples - the user should be able to choose one of these
Required - the value should be non-empty
IsPassword - the value is a password and should be edited as such
Type - type of value, eg bool, string, int and others
Exclusive - if set no free-form entry allowed only the Examples
Irrelevant keys Provider, ShortOpt, Hide, NoPrefix, Advanced

If Error is set then it should be shown to the user at the same time as the question.

rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"

Note that when using --continue all passwords should be passed in the clear (not obscured). Any default config values should be passed in with each invocation of --continue.

At the end of the non interactive process, rclone will return a result with State as empty string.

If --all is passed then rclone will ask all the config questions, not just the post config questions. Any parameters are used as defaults for questions as usual.

Note that bin/config.py in the rclone source implements this protocol as a readable demonstration.

rclone config create name type [key value]* [flags]

🎀 OPTIONS 🎀

--all — Ask the full set of config questions
--continue — Continue the configuration process with an answer
-h, --help — help for create
--no-obscure — Force any passwords not to be obscured
--non-interactive — Don't interact with user and return questions
--obscure — Force any passwords to be obscured
--result string — Result - use with --continue
--state string — State - use with --continue

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.

💀 rclone config delete 💀

Delete an existing remote. bye bestie, it's not you it's the config file 🥀

rclone config delete name [flags]

🎀 OPTIONS 🎀

-h, --help — help for delete

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.

🔌 rclone config disconnect 🔌

Disconnects user from remote

🦋 SYNOPSIS 🦋

This disconnects the remote: passed in to the cloud storage system.

This normally means revoking the oauth token.

To reconnect use rclone config reconnect.

rclone config disconnect remote: [flags]

🎀 OPTIONS 🎀

-h, --help — help for disconnect

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.

📤 rclone config dump 📤

Dump the config file as JSON. raw. unfiltered. iconic ✨

rclone config dump [flags]

🎀 OPTIONS 🎀

-h, --help — help for dump

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.

🎨 rclone config edit 🎨

Enter an interactive configuration session.

🌸 SYNOPSIS 🌸

Enter an interactive configuration session where you can setup new remotes and manage existing ones. You may also set or remove a password to protect your configuration. self-care honestly 💅

rclone config edit [flags]

🎀 OPTIONS 🎀

-h, --help — help for edit

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.

🔐 rclone config encryption 🔐

set, remove and check the encryption for the config file

🧚 SYNOPSIS 🧚

This command sets, clears and checks the encryption for the config file using the subcommands below.

🎀 OPTIONS 🎀

-h, --help — help for encryption

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone config - Enter an interactive configuration session.
rclone config encryption check - Check that the config file is encrypted
rclone config encryption remove - Remove the config file encryption password
rclone config encryption set - Set or change the config file encryption password

🎀 rclone config encryption check

Check that the config file is encrypted 💅

✨ Synopsis ✨

Okay so this one literally checks that your config file is encrypted and that you can actually decrypt it. 🫶

It's gonna try to decrypt the config using the password you hand it.

If decryption fails it will return a non-zero exit code if you're using --password-command. Otherwise? It'll just prompt you again for the password. 🙈

And if the config file is not encrypted at all, it returns a non zero exit code. periodt.

rclone config encryption check [flags]

🌸 Options 🌸

-h, --help — help for check

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config encryption - set, remove and check the encryption for the config file

🦋 rclone config encryption remove

Remove the config file encryption password 🌈

✨ Synopsis ✨

Remove the config file encryption password. yes bestie, we're taking it off.

This removes the config file encryption, returning it to un-encrypted. 😌

If --password-command is in use, this will be called to supply the old config password.

And if the config wasn't encrypted in the first place? No error, no drama — this command will do nothing. 💅

rclone config encryption remove [flags]

🌸 Options 🌸

-h, --help — help for remove

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config encryption - set, remove and check the encryption for the config file

👑 rclone config encryption set

Set or change the config file encryption password 🔥

✨ Synopsis ✨

This command sets or changes the config file encryption password. glow up for your config fr fr.

If there was no config password set then it sets a new one. Otherwise it changes the existing config password. ✨

Note that if you are changing an encryption password using --password-command then this will be called once to decrypt the config using the old password and then again to read the new password to re-encrypt the config. Two calls, no cap.

When --password-command is called to change the password then the environment variable RCLONE_PASSWORD_CHANGE=1 will be set. So if changing passwords programmatically you can use the environment variable to distinguish which password you must supply. iykyk 💅

Alternatively you can remove the password first (with rclone config encryption remove), then set it again with this command which may be easier if you don't mind the unencrypted config file being on the disk briefly. 🫣

rclone config encryption set [flags]

🌸 Options 🌸

-h, --help — help for set

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config encryption - set, remove and check the encryption for the config file

🌸 rclone config file

Show path of configuration file in use. bestie wants to know where the config lives 🥺

rclone config file [flags]

🌸 Options 🌸

-h, --help — help for file

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

💀 rclone config password

Update password in an existing remote. yes it's giving legacy energy 🙈

✨ Synopsis ✨

Update an existing remote's password. The password should be passed in pairs of key password or as key=password. The password should be passed in in clear (unobscured).

For example, to set password of a remote of name myremote you would do:

rclone config password myremote fieldname mypassword
rclone config password myremote fieldname=mypassword

This command is obsolete now that "config update" and "config create" both support obscuring passwords directly. not me telling you to move on but like... move on 💅

rclone config password name [key value]+ [flags]

🌸 Options 🌸

-h, --help — help for password

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

🧚 rclone config paths

Show paths used for configuration, cache, temp etc. all the little spots your stuff hides 🌈

rclone config paths [flags]

🌸 Options 🌸

-h, --help — help for paths

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

⭐ rclone config providers

List in JSON format all the providers and options. every single one, main character catalog energy 👑

rclone config providers [flags]

🌸 Options 🌸

-h, --help — help for providers

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

🔥 rclone config reconnect

Re-authenticates user with remote. time for a little refresh bestie ✨

✨ Synopsis ✨

This reconnects remote: passed in to the cloud storage system.

To disconnect the remote use "rclone config disconnect".

This normally means going through the interactive oauth flow again. round two, and yes you have to sit through it 🫠

rclone config reconnect remote: [flags]

🌸 Options 🌸

-h, --help — help for reconnect

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

🙈 rclone config redacted

Print redacted (decrypted) config file, or the redacted config for a single remote. the ✨ shareable ✨ version

✨ Synopsis ✨

This prints a redacted copy of the config file, either the whole config file or for a given remote.

The config file will be redacted by replacing all passwords and other sensitive info with XXX. cute little censoring moment 💅

This makes the config file suitable for posting online for support.

It should be double checked before posting as the redaction may not be perfect. ⚠️ bestie please triple check it, do not be posting your secrets fr fr 😭

rclone config redacted [<remote>] [flags]

🌸 Options 🌸

-h, --help — help for redacted

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

💜 rclone config show

Print (decrypted) config file, or the config for a single remote. the unredacted, unfiltered truth 🫶

rclone config show [<remote>] [flags]

🌸 Options 🌸

-h, --help — help for show

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

🍓 rclone config touch

Ensure configuration file exists. like, manifesting it into existence but make it filesystem 🌸

rclone config touch [flags]

🌸 Options 🌸

-h, --help — help for touch

See the global flags page for global options not listed here.

💖 See Also 💖

rclone config - Enter an interactive configuration session.

✨ rclone config update ✨

bestie this is THE command for giving your remote a lil glow-up 💅 updating its options, no drama, we love to see it.

📖 Synopsis 📖

Update an existing remote's options. The options should be passed in pairs of key value or as key=value.

For example, to update the env_auth field of a remote of name myremote you would do:

rclone config update myremote env_auth true
rclone config update myremote env_auth=true

If the remote uses OAuth the token will be updated, if you don't require this add an extra parameter thus:

rclone config update myremote env_auth=true config_refresh_token=false

If any of the parameters passed is a password field, then rclone will automatically obscure them if they aren't already obscured before putting them in the config file.

🚨 NB bestie listen UP 🚨 If the password parameter is 22 characters or longer and consists only of base64 characters then rclone can get confused about whether the password is already obscured or not and put unobscured passwords into the config file. If you want to be 100% certain that the passwords get obscured then use the --obscure flag, or if you are 100% certain you are already passing obscured passwords then use --no-obscure. You can also set obscured passwords using the rclone config password command.

This will look something like (some irrelevant detail removed):

{
    "State": "*oauth-islocal,teamdrive,,",
    "Option": {
        "Name": "config_is_local",
        "Help": "Use web browser to automatically authenticate rclone with remote?\n * Say Y if the machine running rclone has a web browser you can use\n * Say N if running rclone on a (remote) machine without web browser access\nIf not sure try Y. If Y failed, try N.\n",
        "Default": true,
        "Examples": [
            {
                "Value": "true",
                "Help": "Yes"
            },
            {
                "Value": "false",
                "Help": "No"
            }
        ],
        "Required": false,
        "IsPassword": false,
        "Type": "bool",
        "Exclusive": true,
    },
    "Error": "",
}

The keys of Option are used as follows:

Name — name of variable - show to user
Help — help text. Hard wrapped at 80 chars. Any URLs should be clicky.
Default — default value - return this if the user just wants the default.
Examples — the user should be able to choose one of these
Required — the value should be non-empty
IsPassword — the value is a password and should be edited as such
Type — type of value, eg bool, string, int and others
Exclusive — if set no free-form entry allowed only the Examples
Irrelevant keys Provider, ShortOpt, Hide, NoPrefix, Advanced

If Error is set then it should be shown to the user at the same time as the question.

rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"

Note that when using --continue all passwords should be passed in the clear (not obscured). Any default config values should be passed in with each invocation of --continue.

At the end of the non interactive process, rclone will return a result with State as empty string.

If --all is passed then rclone will ask all the config questions, not just the post config questions. Any parameters are used as defaults for questions as usual.

Note that bin/config.py in the rclone source implements this protocol as a readable demonstration. 🐍

rclone config update name [key value]+ [flags]

🎀 Options 🎀

--all — Ask the full set of config questions
--continue — Continue the configuration process with an answer
-h, --help — help for update
--no-obscure — Force any passwords not to be obscured
--non-interactive — Don't interact with user and return questions
--obscure — Force any passwords to be obscured
--result string — Result - use with --continue
--state string — State - use with --continue

See the global flags page for global options not listed here. (yes, there's a whole other page for the global ones, go look 👀)

👑 See Also 👑

rclone config - Enter an interactive configuration session.

🦋 rclone config userinfo 🦋

Prints info about logged in user of remote. who ARE you, bestie? let's find out 💖

📖 Synopsis 📖

This prints the details of the person logged in to the cloud storage system.

rclone config userinfo remote: [flags]

🎀 Options 🎀

-h, --help — help for userinfo
--json — Format output as JSON

See the global flags page for global options not listed here. (again, global flags live on their own page, iykyk 🌈)

👑 See Also 👑

rclone config - Enter an interactive configuration session.

✨ rclone copyto ✨

okay bestie so this one copies files from source to dest and skips the ones that are literally identical 💖 no cap.

📖 Synopsis 💫

If source:path is a file or a directory then it copies it to a file or directory named dest:path.

This is how you upload single files to somewhere that isn't their current name, which is genuinely so useful. If the source is a directory then it acts exactly like the copy command — like, the same same.

rclone copyto src dst

where src and dst are rclone paths, either remote:path or /path/to/local or C:.

This will:

if src is file
    copy it to dst, overwriting an existing file if it exists
if src is directory
    copy it to dst, overwriting existing files if they exist
    see copy command for full details

This doesn't transfer files that are identical on src and dst, testing by size and modification time or MD5SUM. It doesn't delete files from the destination. like it's not gonna touch your dest's extra files, she's not that kind of girl.

If you are looking to copy just a byte range of a file, please see rclone cat –offset X –count Y' 🌸

Note: Use the -P/--progress flag to view real-time transfer statistics 🔥

rclone copyto source:path dest:path [flags]

🎀 Options 🎀

-h, --help — help for copyto 🫶

Options shared with other commands are described next. See the global flags page for global options not listed here.

💅 Copy Options 💅

Flags for anything which can copy a file ✨

--check-first — Do all the checks before starting transfers
-c, --checksum — Check for changes with size & checksum (if available, or fallback to size only)
--compare-dest stringArray — Include additional server-side paths during comparison
--copy-dest stringArray — Implies --compare-dest but also copies files from paths into destination
--cutoff-mode HARD|SOFT|CAUTIOUS — Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD)
--ignore-case-sync — Ignore case when synchronizing
--ignore-checksum — Skip post copy check of checksums
--ignore-existing — Skip all files that exist on destination
--ignore-size — Ignore size when skipping use modtime or checksum
-I, --ignore-times — Don't skip items that match size and time - transfer all unconditionally
--immutable — Do not modify files, fail if existing files have been modified
--inplace — Download directly to destination file instead of atomic download to temp/rename
-l, --links — Translate symlinks to/from regular files with a .rclonelink extension
--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)
--max-duration Duration — Maximum duration rclone will transfer data for (default 0s)
--max-transfer SizeSuffix — Maximum size of data to transfer (default off)
-M, --metadata — If set, preserve metadata when copying objects
--modify-window Duration — Max time diff to be considered the same (default 1ns)
--multi-thread-chunk-size SizeSuffix — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi)
--multi-thread-cutoff SizeSuffix — Use multi-thread downloads for files above this size (default 256Mi)
--multi-thread-streams int — Number of streams to use for multi-thread downloads (default 4)
--multi-thread-write-buffer-size SizeSuffix — In memory buffer size for writing when in multi-thread mode (default 128Ki)
--no-check-dest — Don't check the destination, copy regardless
--no-traverse — Don't traverse destination file system on copy
--no-update-dir-modtime — Don't update directory modification times
--no-update-modtime — Don't update destination modtime if files identical
--order-by string — Instructions on how to order the transfers, e.g. 'size,descending'
--partial-suffix string — Add partial-suffix to temporary file name when --inplace is not used (default .partial)
--refresh-times — Refresh the modtime of remote files
--server-side-across-configs — Allow server-side operations (e.g. copy) to work across different configs
--size-only — Skip based on size only, not modtime or checksum
--streaming-upload-cutoff SizeSuffix — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki)
-u, --update — Skip files that are newer on the destination

👑 Important Options 👑

Important flags useful for most commands 💖

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

Flags for filtering directory listings 🌈

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

🍓 Listing Options 🍓

Flags for listing directories 🎀

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🌟 See Also 🌟

rclone - Show help for rclone commands, flags and backends.

🌈 rclone copyurl 🌈

Copy the contents of the URL supplied content to dest:path. it's giving "download but make it elegant" 💅

📖 Synopsis 💫

Download a URL's content and copy it to the destination without saving it in temporary storage. iconic behaviour honestly, no middleman, no leftovers 🧚

Setting --auto-filename will attempt to automatically determine the filename from the URL (after any redirections) and used in the destination path.

With --header-filename in addition, if a specific filename is set in HTTP headers, it will be used instead of the name from the URL. With --print-filename in addition, the resulting file name will be printed.

Setting --no-clobber will prevent overwriting file on the destination if there is one with the same name. bestie-protection protocol 🫶

Setting --stdout or making the output file name - will cause the output to be written to standard output.

😭 Troubleshooting 😭

If you can't get rclone copyurl to work then here are some things you can try — lowkey these fix it like 90% of the time:

--disable-http2 rclone will use HTTP2 if available - try disabling it
--bind 0.0.0.0 rclone will use IPv6 if available - try disabling it
--bind ::0 to disable IPv4
--user agent curl - some sites have whitelists for curl's user-agent - try that
Make sure the site works with curl directly

rclone copyurl https://example.com dest:path [flags]

🎀 Options 🎀

-a, --auto-filename — Get the file name from the URL and use it for destination file path
--header-filename — Get the file name from the Content-Disposition header
-h, --help — help for copyurl
--no-clobber — Prevent overwriting file with same name
-p, --print-filename — Print the resulting name from --auto-filename
--stdout — Write the output to stdout rather than a file

Options shared with other commands are described next. See the global flags page for global options not listed here.

👑 Important Options 👑

Important flags useful for most commands 💖

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

🌟 See Also 🌟

rclone - Show help for rclone commands, flags and backends.

🦋 rclone cryptcheck 🦋

Cryptcheck is the vibe check for your encrypted remote — it verifies the integrity of an encrypted remote, bestie. 💖

✨ Synopsis ✨

It checks a remote against a crypted remote. It's literally the equivalent of running rclone check, but it can actually check the checksums of the encrypted remote. Iconic.

For it to work, the underlying remote of the cryptedremote: must support some kind of checksum. No checksum, no party. 😭

The way it works: it reads the nonce from each file on the cryptedremote: and uses that to encrypt each file on the remote:. Then it checks the checksum of the underlying file on the cryptedremote: against the checksum of the file it just encrypted. So smart, honestly.

Use it like this:

rclone cryptcheck /path/to/files encryptedremote:path

You can also use it like this, but heads up — that will involve downloading all the files in remote:path:

rclone cryptcheck remote:path encryptedremote:path

After it has run it will log the status of the encryptedremote:.

If you supply the --one-way flag, it will only check that files in the source match the files in the destination, not the other way around. Which means extra files in the destination that aren't in the source will not be detected. 🫣

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name (or stdout if it is -) supplied. What they write is described in the help below. For example --differ will write all paths which are present on both the source and destination but different.

The --combined flag will write a file (or stdout) which contains all file paths with a symbol and then a space and then the path to tell you what happened to it. These are reminiscent of diff files. 🔥

= path means path was found in source and destination and was identical
- path means path was missing on the source, so only in the destination
+ path means path was missing on the destination, so only in the source
* path means path was present in source and destination but different.
! path means there was an error reading or hashing the source or dest.

The default number of parallel checks is 8. See the --checkers=N option for more information.

rclone cryptcheck remote:path cryptedremote:path [flags]

✨ Options ✨

--combined string — Make a combined report of changes to this file
--differ string — Report all non-matching files to this file
--error string — Report all files with errors (hashing or reading) to this file
-h, --help — help for cryptcheck
--match string — Report all matching files to this file
--missing-on-dst string — Report all files missing from the destination to this file
--missing-on-src string — Report all files missing from the source to this file
--one-way — Check one way only, source files must exist on remote

Options shared with other commands are described next. See the global flags page for global options not listed here.

🌈 Check Options 🌈

Flags used for check commands

--max-backlog int — Maximum number of objects in sync or check backlog (default 10000)

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

🎀 Listing Options 🎀

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

💜 See Also 💜

rclone - Show help for rclone commands, flags and backends.

🦋 rclone cryptdecode 🦋

Cryptdecode returns unencrypted file names. Decoding era fr fr. ✨

✨ Synopsis ✨

Returns unencrypted file names when provided with a list of encrypted file names. List limit is 10 items. (Ten, bestie, that's the cap. 💅)

If you supply the --reverse flag, it will return encrypted file names.

Use it like this:

rclone cryptdecode encryptedremote: encryptedfilename1 encryptedfilename2

rclone cryptdecode --reverse encryptedremote: filename1 filename2

Another way to accomplish this is by using the rclone backend encode (or decode) command. See the documentation on the crypt overlay for more info.

rclone cryptdecode encryptedremote: encryptedfilename [flags]

✨ Options ✨

-h, --help — help for cryptdecode
--reverse — Reverse cryptdecode, encrypts filenames

See the global flags page for global options not listed here.

💜 See Also 💜

rclone - Show help for rclone commands, flags and backends.

🦋 rclone deletefile 🦋

Remove a single file from remote. Just one. Singular. The main character of deletions. 👑

✨ Synopsis ✨

Remove a single file from remote. Unlike delete it cannot be used to remove a directory and it doesn't obey include/exclude filters — if the specified file exists, it will always be removed. No filter, no negotiation. 😤

rclone deletefile remote:path [flags]

✨ Options ✨

-h, --help — help for deletefile

Options shared with other commands are described next. See the global flags page for global options not listed here.

🌈 Important Options 🌈

Important flags useful for most commands

-n, --dry-run — Do a trial run with no permanent changes
-i, --interactive — Enable interactive mode
-v, --verbose count — Print lots more stuff (repeat for more)

💜 See Also 💜

rclone - Show help for rclone commands, flags and backends.

🦋 rclone gendocs 🦋

Output markdown docs for rclone to the directory supplied. Documentation slay. 📝

✨ Synopsis ✨

This produces markdown docs for the rclone commands to the directory supplied. These are in a format suitable for hugo to render into the rclone.org website.

rclone gendocs output_directory [flags]

✨ Options ✨

-h, --help — help for gendocs

See the global flags page for global options not listed here.

💜 See Also 💜

rclone - Show help for rclone commands, flags and backends.

🦋 rclone gitannex 🦋

Speaks with git-annex over stdin/stdout. So demure, so communicative. 🫶

✨ Synopsis ✨

Rclone's gitannex subcommand enables git-annex to store and retrieve content from an rclone remote. It is meant to be run by git-annex, not directly by users. So like, don't just grab it and run it yourself, okay bestie? 🙈

🌸 Installation on Linux 🌸

Skip this step if your version of git-annex is 10.20240430 or newer. Otherwise, you must create a symlink somewhere on your PATH with a particular name. This symlink helps git-annex tell rclone it wants to run the "gitannex" subcommand.

# Create the helper symlink in "$HOME/bin".
ln -s "$(realpath rclone)" "$HOME/bin/git-annex-remote-rclone-builtin"

# Verify the new symlink is on your PATH.
which git-annex-remote-rclone-builtin

Add a new remote to your git-annex repo. This new remote will connect git-annex with the rclone gitannex subcommand.

Start by asking git-annex to describe the remote's available configuration parameters.

# If you skipped step 1:
git annex initremote MyRemote type=rclone --whatelse

# If you created a symlink in step 1:
git annex initremote MyRemote type=external externaltype=rclone-builtin --whatelse

NOTE: If you're porting an existing git-annex-remote-rclone remote to use rclone gitannex, you can probably reuse the configuration parameters verbatim without renaming them. Check parameter synonyms with --whatelse as shown above.

The following example creates a new git-annex remote named "MyRemote" that will use the rclone remote named "SomeRcloneRemote". That rclone remote must be one configured in your rclone.conf file, which can be located with rclone config file.

git annex initremote MyRemote         \
    type=external                     \
    externaltype=rclone-builtin       \
    encryption=none                   \
    rcloneremotename=SomeRcloneRemote \
    rcloneprefix=git-annex-content    \
    rclonelayout=nodir

Before you trust this command with your precious data, be sure to test the remote. This command is very new and has not been tested on many rclone backends. Caveat emptor! 😭

git annex testremote MyRemote

Happy annexing! 🎉

rclone gitannex [flags]

✨ Options ✨

-h, --help — help for gitannex

See the global flags page for global options not listed here.

💜 See Also 💜

rclone - Show help for rclone commands, flags and backends.

🌸 rclone hashsum 🌸

okay bestie, this one produces a hashsum file for literally every object in the path. it's giving ✨checksum vibes✨

✨ SYNOPSIS ✨

Produces a hash file for all the objects in the path using the hash named. The output is in the same format as the standard md5sum/sha1sum tool. no cap 💅

By default, the hash is requested from the remote. If the hash is not supported by the remote, no hash will be returned. But with the download flag, the file will be downloaded from the remote and hashed locally, enabling any hash for any remote. the way that works... iconic honestly 🫶

For the MD5 and SHA1 algorithms there are also dedicated commands, md5sum and sha1sum.

Run without a hash to see the list of all supported hashes, e.g.

$ rclone hashsum
Supported hashes are:
  * md5
  * sha1
  * whirlpool
  * crc32
  * sha256

Then

$ rclone hashsum MD5 remote:path

Note that hash names are case insensitive and values are output in lower case. lowercase girlies rise 👑

rclone hashsum [<hash> remote:path] [flags]

💖 OPTIONS 💖

--base64 — Output base64 encoded hashsum (she's encoded, she's fancy ✨)
-C, --checkfile string — Validate hashes against a given SUM file instead of printing them
--download — Download the file and hash it locally; if this flag is not specified, the hash is requested from the remote
-h, --help — help for hashsum
--output-file string — Output hashsums to a file rather than the terminal

Options shared with other commands are described next. See the global flags page for global options not listed here.

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

🎀 LISTING OPTIONS 🎀

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

🌈 SEE ALSO 🌈

rclone — Show help for rclone commands, flags and backends.

💜 rclone link 💜

Generate public link to file/folder. sharing is caring bestie 🫶

✨ SYNOPSIS ✨

Create, retrieve or remove a public link to the given file or folder.

rclone link remote:path/to/file
rclone link remote:path/to/folder/
rclone link --unlink remote:path/to/folder/
rclone link --expire 1d remote:path/to/file

If you supply the --expire flag, it will set the expiration time, otherwise it will use the default (100 years). a literal century, okay 💀 Note not all backends support the --expire flag — if the backend doesn't support it then the link returned won't expire.

Use the --unlink flag to remove existing public links to the file or folder. Note not all backends support --unlink flag — those that don't will just ignore it. they're pretending they didn't hear you 🙈

If successful, the last line of the output will contain the link. Exact capabilities depend on the remote, but the link will always by default be created with the least constraints — e.g. no expiry, no password protection, accessible without account. lowkey the most unlocked version of a link ✨

rclone link remote:path [flags]

💖 OPTIONS 💖

--expire Duration — The amount of time that the link will be valid (default off)
-h, --help — help for link
--unlink — Remove existing public link to file/folder

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone — Show help for rclone commands, flags and backends.

👑 rclone listremotes 👑

List all the remotes in the config file and defined in environment variables. roll call, everyone say present 📣

✨ SYNOPSIS ✨

Lists all the available remotes from the config file, or the remotes matching an optional filter.

Prints the result in human-readable format by default, and as a simple list of remote names, or if used with flag --long a tabular format including the remote names, types and descriptions. Using flag --json produces machine-readable output instead, which always includes all attributes — including the source (file or environment). she's thorough, she's detailed, she ate 💅

Result can be filtered by a filter argument which applies to all attributes, and/or filter flags specific for each attribute. The values must be specified according to regular rclone filtering pattern syntax.

rclone listremotes [<filter>] [flags]

💖 OPTIONS 💖

--description string — Filter remotes by description
-h, --help — help for listremotes
--json — Format output as JSON
--long — Show type and description in addition to name
--name string — Filter remotes by name
--order-by string — Instructions on how to order the result, e.g. 'type,name=descending'
--source string — Filter remotes by source, e.g. 'file' or 'environment'
--type string — Filter remotes by type

See the global flags page for global options not listed here.

🌈 SEE ALSO 🌈

rclone — Show help for rclone commands, flags and backends.

🌈 rclone lsf 🌈

List directories and objects in remote:path formatted for parsing. — bestie this is the one you want when a script needs to read the output, not your eyeballs 👀✨

📜 Synopsis 📜

List what's chillin' in your source path (directories and objects) straight to standard output, in a form that's easy-peasy for scripts to parse 🫶. By default you just get the names of the objects and directories, one per line. And yeah — directories get a / suffix, no cap 💅

Like, for example:

$ rclone lsf swift:bucket
bevajer5jef
canole
diwogej7
ferejej3gux/
fubuwic

Use the --format option to control what actually gets listed. Default is just the path, but babes you can use these parameters to boss the output around:

p — path
s — size
t — modification time
h — hash
i — ID of object
o — Original ID of underlying object
m — MimeType of object if known
e — encrypted name
T — tier of storage if known, e.g. "Hot" or "Cool"
M — Metadata of object in JSON blob format, eg {"key":"value"}

So if you wanted the path, size and modification time, you'd use --format "pst" 🌸 — or maybe --format "tsp" to yeet the path to the last position, iconiqué.

Eg:

$ rclone lsf  --format "tsp" swift:bucket
2016-06-25 18:55:41;60295;bevajer5jef
2016-06-25 18:55:43;90613;canole
2016-06-25 18:55:43;94467;diwogej7
2018-04-26 08:50:45;0;ferejej3gux/
2016-06-25 18:55:40;37600;fubuwic

If you drop h into the format you'll get the MD5 hash by default, but use the --hash flag to switch up which hash you actually want 🦋. Heads up though: this can come back as an empty string if it isn't available on the object (and for directories too), as "ERROR" if there was an error reading it from the object, and as "UNSUPPORTED" if that object simply does not support that hash type 😭

Like, to emulate the md5sum command you can do:

rclone lsf -R --hash MD5 --format hp --separator "  " --files-only .

Eg:

$ rclone lsf -R --hash MD5 --format hp --separator "  " --files-only swift:bucket
7908e352297f0f530b84a756f188baa3  bevajer5jef
cd65ac234e6fea5925974a51cdd865cc  canole
03b5341b4f234b9d984d03ad076bae91  diwogej7
8fd37c3810dd660778137ac3a66cc06d  fubuwic
99713e14a4c4ff553acaf1930fad985b  gixacuh7ku

(Though lowkey rclone md5sum . is an easier way of typing this 💀)

By default the separator is ; but bestie you can change that with the --separator flag. Oh and psa: separators aren't escaped in the path, so putting it last is a solid strategy, fr fr 🎀

Eg:

$ rclone lsf  --separator "," --format "tshp" swift:bucket
2016-06-25 18:55:41,60295,7908e352297f0f530b84a756f188baa3,bevajer5jef
2016-06-25 18:55:43,90613,cd65ac234e6fea5925974a51cdd865cc,canole
2016-06-25 18:55:43,94467,03b5341b4f234b9d984d03ad076bae91,diwogej7
2018-04-26 08:52:53,0,,ferejej3gux/
2016-06-25 18:55:40,37600,8fd37c3810dd660778137ac3a66cc06d,fubuwic

You can also output in CSV standard format 📊 — which will escape things in " if they contain ,

Eg:

$ rclone lsf --csv --files-only --format ps remote:path
test.log,22355
test.sh,449
"this file contains a comma, in the file name.txt",6

Ngl the --absolute parameter is so useful for making lists of files to pass to an rclone copy with the --files-from-raw flag 👑

For example, to find all the files modified within one day and copy only those (without traversing the whole entire directory structure, we love efficiency):

rclone lsf --absolute --files-only --max-age 1d /path/to/local > new_files
rclone copy --files-from-raw new_files /path/to/local remote:path

The default time format is '2006-01-02 15:04:05' ⏰. Other formats can be specified with the --time-format flag. Examples:

rclone lsf remote:path --format pt --time-format 'Jan 2, 2006 at 3:04pm (MST)'
rclone lsf remote:path --format pt --time-format '2006-01-02 15:04:05.000000000'
rclone lsf remote:path --format pt --time-format '2006-01-02T15:04:05.999999999Z07:00'
rclone lsf remote:path --format pt --time-format RFC3339
rclone lsf remote:path --format pt --time-format DateOnly
rclone lsf remote:path --format pt --time-format max

--time-format max will automatically truncate 2006-01-02 15:04:05.000000000 down to the maximum precision supported by the remote 💅✨

Any of the filtering options can be applied to this command, btw 😌

There are several related list commands:

ls to list size and path of objects only
lsl to list modification time, size and path of objects only
lsd to list directories only
lsf to list objects and directories in easy to parse format
lsjson to list objects and directories in JSON format

ls, lsl, lsd are designed to be human-readable. lsf is designed to be human and machine-readable 🌈. lsjson is designed to be machine-readable 🤖

Note that ls and lsl recurse by default — use --max-depth 1 to stop the recursion 🙈

The other list commands lsd, lsf, lsjson do not recurse by default — use -R to make them recurse 🌀

Listing a nonexistent directory will produce an error 💀 — except for remotes which can't have empty directories (e.g. s3, swift, or gcs — the bucket-based remotes).

rclone lsf remote:path [flags]

✨ Options ✨

--absolute — Put a leading / in front of path names
--csv — Output in CSV format
-d, --dir-slash — Append a slash to directory names (default true)
--dirs-only — Only list directories
--files-only — Only list files
-F, --format string — Output format - see help for details (default "p")
--hash h — Use this hash when h is used in the format MD5|SHA-1|DropboxHash (default "md5")
-h, --help — help for lsf
-R, --recursive — Recurse into the listing
-s, --separator string — Separator for the items in the format (default ";")
-t, --time-format string — Specify a custom time format, or 'max' for max precision supported by remote (default: 2006-01-02 15:04:05)

Options shared with other commands are described next 👇 See the global flags page for global options not listed here.

Flags for filtering directory listings, bestie ✨

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

📂 Listing Options 📂

Flags for listing directories 🎀

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

👀 See Also 👀

rclone — Show help for rclone commands, flags and backends.

okay that's the whole lsf vibe check slayed 💖 keep scrolling bestie, there's so much more where that came from 🦋✨

💖 rclone lsjson 💖

List directories and objects in the path in JSON format. ✨

🌸 Synopsis 🌸

okay bestie, this one's the machine-readable one — it lists directories and objects in the path, but as JSON. no cap. 🦋

The output is an array of Items, where each Item looks like this:

{
  "Hashes" : {
     "SHA-1" : "f572d396fae9206628714fb2ce00f72e94f2258f",
     "MD5" : "b1946ac92492d2347c6235b4d2611184",
     "DropboxHash" : "ecb65bb98f9d905b70458986c39fcbad7715e5f2fcc3b1f07767d7c83e2438cc"
  },
  "ID": "y2djkhiujf83u33",
  "OrigID": "UYOJVTUW00Q1RzTDA",
  "IsBucket" : false,
  "IsDir" : false,
  "MimeType" : "application/octet-stream",
  "ModTime" : "2017-05-31T16:15:57.034468261+01:00",
  "Name" : "file.txt",
  "Encrypted" : "v0qpsdq8anpci8n929v3uu9338",
  "EncryptedPath" : "kja9098349023498/v0qpsdq8anpci8n929v3uu9338",
  "Path" : "full/path/goes/here/file.txt",
  "Size" : 6,
  "Tier" : "hot",
}

The exact set of properties included depends on the backend 💅:

The property IsBucket will only be included for bucket-based remotes, and only for directories that are buckets. It will always be omitted when value is not true.
Properties Encrypted and EncryptedPath will only be included for encrypted remotes, and (as mentioned below) only if the --encrypted option is set.

Different options may also affect which properties are included 🎀:

If --hash is not specified, the Hashes property will be omitted. The types of hash can be specified with the --hash-type parameter (which may be repeated). If --hash-type is set then it implies --hash.
If --no-modtime is specified then ModTime will be blank. This can speed things up on remotes where reading the ModTime takes an extra request (e.g. s3, swift).
If --no-mimetype is specified then MimeType will be blank. This can speed things up on remotes where reading the MimeType takes an extra request (e.g. s3, swift).
If --encrypted is not specified the Encrypted and EncryptedPath properties will be omitted — even for encrypted remotes. 😭
If --metadata is set then an additional Metadata property will be returned. This will have metadata in rclone standard format as a JSON object.

The default is to list directories and files/objects, but this can be changed with the following options 🫶:

If --dirs-only is specified then directories will be returned only, no files/objects.
If --files-only is specified then files will be returned only, no directories.

If --stat is set then the the output is not an array of items, but instead a single JSON blob will be returned about the item pointed to. This will return an error if the item isn't found, however on bucket based backends (like s3, gcs, b2, azureblob etc) if the item isn't found it will return an empty directory, as it isn't possible to tell empty directories from missing directories there. (yes, that's the actual behavior, iykyk 💀)

The Path field will only show folders below the remote path being listed. If "remote:path" contains the file "subfolder/file.txt", the Path for "file.txt" will be "subfolder/file.txt", not "remote:path/subfolder/file.txt". When used without --recursive the Path will always be the same as Name. ✨

The time is in RFC3339 format with up to nanosecond precision. The number of decimal digits in the seconds will depend on the precision that the remote can hold the times, so if times are accurate to the nearest millisecond (e.g. Google Drive) then 3 digits will always be shown ("2017-05-31T16:15:57.034+01:00") whereas if the times are accurate to the nearest second (Dropbox, Box, WebDav, etc.) no digits will be shown ("2017-05-31T16:15:57+01:00"). precision queen behavior 👑

The whole output can be processed as a JSON blob, or alternatively it can be processed line by line as each item is written on individual lines (except with --stat).

Any of the filtering options can be applied to this command. 💅

There are several related list commands 🌈

ls to list size and path of objects only
lsl to list modification time, size and path of objects only
lsd to list directories only
lsf to list objects and directories in easy to parse format
lsjson to list objects and directories in JSON format

ls,lsl,lsd are designed to be human-readable. lsf is designed to be human and machine-readable. lsjson is designed to be machine-readable. (three different love languages fr fr)

Note that ls and lsl recurse by default — use --max-depth 1 to stop the recursion.

The other list commands lsd,lsf,lsjson do not recurse by default — use -R to make them recurse.

Listing a nonexistent directory will produce an error except for remotes which can't have empty directories (e.g. s3, swift, or gcs — the bucket-based remotes). 🙈

rclone lsjson remote:path [flags]

✨ Options ✨

--dirs-only — Show only directories in the listing
--encrypted — Show the encrypted names
--files-only — Show only files in the listing
--hash — Include hashes in the output (may take longer)
--hash-type stringArray — Show only this hash type (may be repeated)
-h, --help — help for lsjson
-M, --metadata — Add metadata to the listing
--no-mimetype — Don't read the mime type (can speed things up)
--no-modtime — Don't read the modification time (can speed things up)
--original — Show the ID of the underlying Object
-R, --recursive — Recurse into the listing
--stat — Just return the info for the pointed to file

Options shared with other commands are described next. See the global flags page for global options not listed here. 🧚

Flags for filtering directory listings

--delete-excluded — Delete files on dest excluded from sync
--exclude stringArray — Exclude files matching pattern
--exclude-from stringArray — Read file exclude patterns from file (use - to read from stdin)
--exclude-if-present stringArray — Exclude directories if filename is present
--files-from stringArray — Read list of source-file names from file (use - to read from stdin)
--files-from-raw stringArray — Read list of source-file names from file without any processing of lines (use - to read from stdin)
-f, --filter stringArray — Add a file filtering rule
--filter-from stringArray — Read file filtering patterns from a file (use - to read from stdin)
--ignore-case — Ignore case in filters (case insensitive)
--include stringArray — Include files matching pattern
--include-from stringArray — Read file include patterns from file (use - to read from stdin)
--max-age Duration — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--max-depth int — If set limits the recursion depth to this (default -1)
--max-size SizeSuffix — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
--metadata-exclude stringArray — Exclude metadatas matching pattern
--metadata-exclude-from stringArray — Read metadata exclude patterns from file (use - to read from stdin)
--metadata-filter stringArray — Add a metadata filtering rule
--metadata-filter-from stringArray — Read metadata filtering patterns from a file (use - to read from stdin)
--metadata-include stringArray — Include metadatas matching pattern
--metadata-include-from stringArray — Read metadata include patterns from file (use - to read from stdin)
--min-age Duration — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
--min-size SizeSuffix — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

🦋 Listing Options 🦋

Flags for listing directories

--default-time Time — Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
--fast-list — Use recursive list if available; uses more memory but fewer transactions

👑 See Also 👑

rclone — Show help for rclone commands, flags and backends.

💜 rclone mount 💜

Mount the remote as file system on a mountpoint. 🔥

🌸 Synopsis 🌸

rclone mount allows Linux, FreeBSD, macOS and Windows to mount any of Rclone's cloud storage systems as a file system with FUSE. your cloud, but make it a whole drive bestie 💅

First set up your remote using rclone config. Check it works with rclone ls etc.

On Linux and macOS, you can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the --daemon flag to force background mode. On Windows you can run mount in foreground only, the flag is ignored.

In background mode rclone acts as a generic Unix mount program: the main program starts, spawns background rclone process to setup and maintain the mount, waits until success or timeout and exits with appropriate code (killing the child process if it fails).

On Linux/macOS/FreeBSD start the mount like this, where /path/to/local/mount is an empty existing directory:

rclone mount remote:path/to/files /path/to/local/mount

On Windows you can start a mount in different ways. See below for details. If foreground mount is used interactively from a console window, rclone will serve the mount and occupy the console so another window should be used to work with the mount until rclone is interrupted e.g. by pressing Ctrl+C. 😭

The following examples will mount to an automatically assigned drive, to specific drive letter X:, to path C:\path\parent\mount (where parent directory or drive must exist, and mount must not exist, and is not supported when mounting as a network drive), and the last example will mount as network share \\cloud\remote and map it to an automatically assigned drive:

rclone mount remote:path/to/files *
rclone mount remote:path/to/files X:
rclone mount remote:path/to/files C:\path\parent\mount
rclone mount remote:path/to/files \\cloud\remote

When the program ends while in foreground mode, either via Ctrl+C or receiving a SIGINT or SIGTERM signal, the mount should be automatically stopped. ✨

When running in background mode the user will have to stop the mount manually:

Linux

fusermount -u /path/to/local/mount #... or on some systems fusermount3 -u /path/to/local/mount

OS X or Linux when using nfsmount

umount /path/to/local/mount


Lowkey the `umount` can straight up fail, bestie 😭 — like when the mountpoint is busy. When that happens? It's *your* responsibility to stop the mount manually, fr fr. No shame, we've all been there 💅.

The size of the mounted file system gets set based on info pulled from the remote — literally the same thing the `rclone about` command hands back. Remotes with unlimited storage might only report the used size, and in that case an extra 1 PiB of free space gets assumed ✨. And if the remote doesn't support the about feature *at all*? Then 1 PiB is set as both the total **and** the free size. Iconic, honestly 🫶.

### Installing on Windows 💻

To run `rclone mount` on Windows you're gonna need to download and install WinFsp.

WinFsp is an open-source Windows File System Proxy, and it makes writing user space file systems for Windows easy-peasy 🎀. It gives you a FUSE emulation layer that rclone uses in combination with `cgofuse`. Both of these packages are by Bill Zissimopoulos, who was *so* helpful during the implementation of `rclone mount` for Windows. King behavior 👑.

### Mounting modes on windows 🪟

Unlike other operating systems, Microsoft Windows gives you a different filesystem type for network drives vs fixed drives. It optimises access on the assumption that fixed disk drives are fast and reliable, while network drives have relatively high latency and less reliability. Some settings can also be differentiated between the two types — for example, that Windows Explorer should just display icons and not create preview thumbnails for image and video files on network drives.

In most cases rclone will mount the remote as a normal, fixed disk drive by default. **But** you can also choose to mount it as a remote network drive — often described as a network share 🌈. If you mount an rclone remote using the default fixed drive mode and you get unexpected program errors, freezes or other issues, consider mounting as a network drive instead. Vibe check your setup, bestie 🔥.

When mounting as a fixed disk drive you can either mount to an unused drive letter, or to a path representing a nonexistent subdirectory of an existing parent directory or drive. Using the special value `*` will tell rclone to automatically assign the next available drive letter, starting with `Z:` and moving backward. Examples:

rclone mount remote:path/to/files * rclone mount remote:path/to/files X: rclone mount remote:path/to/files C:\path\parent\mount rclone mount remote:path/to/files X:


Option `--volname` can be used to set a custom volume name for the mounted file system 💖. The default is to use the remote name and path.

To mount as a network drive, you can add option `--network-mode` to your mount command. Mounting to a directory path is **not** supported in this mode — it's a limitation Windows imposes on junctions — so the remote must always be mounted to a drive letter 🚨.

rclone mount remote:path/to/files X: --network-mode


A volume name specified with `--volname` will be used to create the network share path. A complete UNC path, such as `\\cloud\remote`, optionally with path `\\cloud\remote\madeup\path`, will be used as is. Any other string will be used as the share part, after a default prefix `\\server\`. If no volume name is specified then `\\server\share` will be used. You *must* make sure the volume name is unique when you're mounting more than one drive, or else the mount command will fail ⚠️. The share name gets treated as the volume label for the mapped drive, shown in Windows Explorer etc, while the complete `\\server\share` will be reported as the remote UNC path by `net use` etc — just like a normal network drive mapping.

If you specify a full network share UNC path with `--volname`, this will implicitly set the `--network-mode` option, so the following two examples have the same result:

rclone mount remote:path/to/files X: --network-mode rclone mount remote:path/to/files X: --volname \server\share


You may also specify the network share UNC path as the mountpoint itself 👀. Then rclone will automatically assign a drive letter, same as with `*`, and use that as the mountpoint, and instead use the UNC path specified as the volume name — as if it were specified with the `--volname` option. This will also implicitly set the `--network-mode` option. Which means the following two examples have the same result:

rclone mount remote:path/to/files \cloud\remote rclone mount remote:path/to/files * --volname \cloud\remote


There is **yet another** way to enable network mode, and to set the share path, and that is to pass the "native" libfuse/WinFsp option directly: `--fuse-flag --VolumePrefix=\server\share`. Note that the path must be with just a single backslash prefix in this case 🙈.

> Note: In previous versions of rclone this was the only supported method.

Read more about drive mapping 💅.

See also Limitations section below.

### Windows filesystem permissions 🔐

The FUSE emulation layer on Windows must convert between the POSIX-based permission model used in FUSE, and the permission model used in Windows — which is based on access-control lists (ACL).

The mounted filesystem will normally get three entries in its access-control list (ACL), representing permissions for the POSIX permission scopes: Owner, group and others. By default, the owner and group will be taken from the current user, and the built-in group "Everyone" will be used to represent others. The user/group can be customized with FUSE options "UserName" and "GroupName", e.g. `-o UserName=user123 -o GroupName="Authenticated Users"`. The permissions on each entry will be set according to options `--dir-perms` and `--file-perms`, which takes a value in traditional Unix numeric notation ✨.

The default permissions corresponds to `--file-perms 0666 --dir-perms 0777`, i.e. read and write permissions to everyone. This means you will **not** be able to start any programs from the mount 😭. To be able to do that you must add execute permissions, e.g. `--file-perms 0777 --dir-perms 0777` to add it to everyone. If the program needs to write files, chances are you will have to enable VFS File Caching as well (see also limitations). Note that the default write permission has some restrictions for accounts other than the owner — specifically it lacks the "write extended attributes", as explained next 👑

The mapping of permissions is not always trivial, and the result you see in Windows Explorer may not be exactly like you expected 🙃. For example, when setting a value that includes write access for the group or others scope, this will be mapped to individual permissions "write attributes", "write data" and "append data", but **not** "write extended attributes". Windows will then show this as basic permission "Special" instead of "Write", because "Write" also covers the "write extended attributes" permission. When setting digit 0 for group or others, to indicate no permissions, they will still get individual permissions "read attributes", "read extended attributes" and "read permissions". This is done for compatibility reasons, e.g. to allow users without additional permissions to be able to read basic metadata about files like in Unix 🌸.

WinFsp 2021 (version 1.9) introduced a new FUSE option "FileSecurity", that allows the complete specification of file security descriptors using SDDL 🎀. With this you get detailed control of the resulting permissions, compared to use of the POSIX permissions described above, and no additional permissions will be added automatically for compatibility with Unix. Some example use cases will following.

If you set POSIX permissions for only allowing access to the owner, using `--file-perms 0600 --dir-perms 0700`, the user group and the built-in "Everyone" group will still be given some special permissions, as described above. Some programs may then (incorrectly) interpret this as the file being accessible by everyone — for example an SSH client may warn about "unprotected private key file" 💀. You can work around this by specifying `-o FileSecurity="D:P(A;;FA;;;OW)"`, which sets file all access (FA) to the owner (OW), and nothing else.

When setting write permissions then, except for the owner, this does not include the "write extended attributes" permission, as mentioned above. This may prevent applications from writing to files, giving permission denied error instead 😤. To set working write permissions for the built-in "Everyone" group, similar to what it gets by default but with the addition of the "write extended attributes", you can specify `-o FileSecurity="D:P(A;;FRFW;;;WD)"`, which sets file read (FR) and file write (FW) to everyone (WD). If file execute (FX) is also needed, then change to `-o FileSecurity="D:P(A;;FRFWFX;;;WD)"`, or set file all access (FA) to get full access permissions, including delete, with `-o FileSecurity="D:P(A;;FA;;;WD)"` 🔥.

### Windows caveats ⚠️

Drives created as Administrator are **not** visible to other accounts — not even an account that was elevated to Administrator with the User Account Control (UAC) feature 😱. A result of this is that if you mount to a drive letter from a Command Prompt run as Administrator, and then try to access the same drive from Windows Explorer (which does not run as Administrator), you will not be able to see the mounted drive. It's giving ghost drive fr fr 👻.

If you don't need to access the drive from applications running with administrative privileges, the easiest way around this is to always create the mount from a non-elevated command prompt. Simple as that 💅.

To make mapped drives available to the user account that created them regardless if elevated or not, there is a special Windows setting called linked connections that can be enabled. Slay 🫶.

---

So yeah — you *can* make a drive mount available to literally everyone on the system by running the process that creates it as the built-in <cyan>SYSTEM</cyan> account. There are a few ways to pull this off:

- Use the command-line utility **PsExec**, from Microsoft's Sysinternals suite — it's got an option `-s` that starts processes as the SYSTEM account.
- Run the mount command from a **Windows Scheduled Task**, or a **Windows Service**, set up to run as the SYSTEM account.
- Use the **WinFsp.Launcher** infrastructure.

Read more in the install documentation. 📖

> Heads up bestie: when you run rclone as another user, it will **not** use the configuration file from your profile unless you tell it to with the `--config` option. Also, it's now the SYSTEM account that holds the owner permissions, and other accounts get permissions according to the group or others scopes. Like we mentioned above, those won't get the "write extended attributes" permission, and that may stop you from writing to files. Work around it with the `FileSecurity` option — see the example above. 💅

Oh and p.s. — mapping to a **directory path** instead of a drive letter does **not** suffer from those same limitations. Slay. ✨

### 🍎 Mounting on macOS

You can mount on macOS three ways: via the **built-in NFS server**, **macFUSE** (also known as osxfuse), or **FUSE-T**.

- **macFUSE** is a traditional FUSE driver that uses a macOS kernel extension (kext).
- **FUSE-T** is an alternative FUSE system which "mounts" via an NFSv4 local server.

### 🌈 Unicode Normalization

It is **highly recommended** to keep the default of `--no-unicode-normalization=false` for all mount and serve commands on macOS. For details, see vfs-case-sensitivity. Don't fight it, bestie, just leave it alone. 🫶

### 🌸 NFS mount

This method spins up an NFS server using the `serve nfs` command and mounts it to the specified mountpoint. If you run this in background mode using `--daemon`, you'll need to send a `SIGTERM` signal to the rclone process using the `kill` command to stop the mount.

Note that `--nfs-cache-handle-limit` controls the maximum number of cached file handles stored by the nfsmount caching handler. Do **not** set this too low or you may get errors when you try to access files. The default is `1000000`, but consider lowering this limit if the server's system resource usage is causing problems.

### 🧚 macFUSE Notes

If you install macFUSE using dmg packages from the website, rclone will find the macFUSE libraries without any further intervention. ✨ But if macFUSE is installed using the **macports** package manager, you need these extra steps:

sudo mkdir /usr/local/lib cd /usr/local/lib sudo ln -s /opt/local/lib/libfuse.2.dylib


### 💀 FUSE-T Limitations, Caveats, and Notes

There are some limitations, caveats, and notes about how it works. These are current as of FUSE-T version `1.0.14`.

### 🕰️ ModTime update on read

As per the FUSE-T wiki:

File access and modification times cannot be set separately as it seems to be an issue with the NFS client which always modifies both. Can be reproduced with touch -m' and touch -a' commands


This means that viewing files with various tools — notably macOS Finder — will cause rclone to update the modification time of the file. And *that* may make rclone upload a full new copy of the file. 😭 No cap, that's a whole re-upload just from looking at it.

### 🔒 Read Only mounts

When you mount with `--read-only`, attempts to write to files will fail **silently**, as opposed to with a clear warning like in macFUSE. So like… nothing tells you why. Rude.

### 🙈 Limitations

Without the use of `--vfs-cache-mode` this can only write files sequentially, and it can only seek when reading. Which means **many applications won't work** with their files on an rclone mount unless you use `--vfs-cache-mode writes` or `--vfs-cache-mode full`. See the VFS File Caching section for more info.

> When using NFS mount on macOS, if you don't specify `--vfs-cache-mode` the mount point will be **read-only**.

The bucket-based remotes (e.g. `Swift`, `S3`, `Google Compute Storage`, `B2`) do not support the concept of empty directories, so empty directories will have a tendency to just… disappear once they fall out of the directory cache. Poof. 💨

When `rclone mount` is invoked on Unix with the `--daemon` flag, the main rclone program will wait for the background mount to become ready, or until the timeout specified by the `--daemon-wait` flag. On Linux it can check mount status using ProcFS, so the flag in fact sets the **maximum** time to wait, while the real wait can be less. On macOS / BSD the time to wait is **constant** and the check is only performed at the end. So we advise you to set the wait time on macOS reasonably. ⏰

Only supported on **Linux, FreeBSD, OS X and Windows** at the moment.

### ⚔️ rclone mount vs rclone sync/copy

File systems expect things to be 100% reliable, whereas cloud storage systems are a long way from 100% reliable. The `rclone sync`/`rclone copy` commands cope with this with *lots* of retries. However `rclone mount` can't use retries in the same way without making local copies of the uploads. Look at the VFS File Caching for solutions to make mount more reliable.

### 🗂️ Attribute caching

You can use the flag `--attr-timeout` to set the time the kernel caches the attributes (size, modification time, etc.) for directory entries.

The default is `1s`, which caches files just long enough to avoid too many callbacks to rclone from the kernel.

In theory `0s` should be the correct value for filesystems which can change outside the control of the kernel. However this causes quite a few problems such as rclone using too much memory, rclone not serving files to samba, and excessive time listing directories.

The kernel can cache the info about a file for the time given by `--attr-timeout`. You may see **corruption** if the remote file changes length during this window. It will show up as either a truncated file or a file with garbage on the end. With `--attr-timeout 1s` this is very unlikely but not impossible. The higher you set `--attr-timeout` the more likely it is. The default setting of "1s" is the lowest setting which mitigates the problems above.

If you set it higher (`10s` or `1m` say) then the kernel will call back to rclone less often, making it more efficient — however there is more chance of the corruption issue above. 👀

If files don't change on the remote outside of the control of rclone then there is **no chance** of corruption. ✨

This is the same as setting the `attr_timeout` option in `mount.fuse`.

### 🎀 Filters

Note that **all** the rclone filters can be used to select a subset of the files to be visible in the mount.

### ⚙️ systemd

When running `rclone mount` as a systemd service, it's possible to use `Type=notify`. In this case the service will enter the started state after the mountpoint has been successfully set up. Units having the `rclone mount` service specified as a requirement will see all files and folders immediately in this mode.

> Note that systemd runs mount units **without any environment variables**, including `PATH` or `HOME`. This means tilde (`~`) expansion will not work, and you should provide `--config` and `--cache-dir` explicitly as absolute paths via rclone arguments. Since mounting requires the `fusermount` or `fusermount3` program, rclone will use the fallback PATH of `/bin:/usr/bin` in this scenario. Please make sure `fusermount`/`fusermount3` is present on this PATH.

### 🛠️ Rclone as Unix mount helper

The core Unix program `/bin/mount` normally takes the `-t FSTYPE` argument, then runs the `/sbin/mount.FSTYPE` helper program passing it mount options as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) behaves in a similar way.

rclone by default expects GNU-style flags `--key val`. To run it as a mount helper you should symlink the rclone binary to `/sbin/mount.rclone` and optionally `/usr/bin/rclonefs`, e.g. `ln -s /usr/bin/rclone /sbin/mount.rclone`. rclone will detect it and translate command-line arguments appropriately. Iconic behaviour honestly. 👑

Now you can run classic mounts like this:

mount sftp1:subdir /mnt/data -t rclone -o vfs_cache_mode=writes,sftp_key_file=/path/to/pem


or create systemd mount units:

/etc/systemd/system/mnt-data.mount

[Unit] Description=Mount for /mnt/data [Mount] Type=rclone What=sftp1:subdir Where=/mnt/data Options=rw,_netdev,allow_other,args2env,vfs-cache-mode=writes,config=/etc/rclone.conf,cache-dir=/var/rclone


optionally accompanied by a systemd automount unit:

/etc/systemd/system/mnt-data.automount

[Unit] Description=AutoMount for /mnt/data [Automount] Where=/mnt/data TimeoutIdleSec=600 [Install] WantedBy=multi-user.target


or add a line like this in `/etc/fstab`:

sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2env,vfs_cache_mode=writes,config=/etc/rclone.conf,cache_dir=/var/cache/rclone 0 0


or use classic Automountd. Remember to provide explicit `config=...,cache-dir=...` as a workaround for mount units being run without `HOME`.

Rclone in the mount helper mode will split the `-o` argument(s) by comma, replace `_` by `-` and prepend `--` to get the command-line flags. Options containing commas or spaces can be wrapped in single or double quotes. Any inner quotes inside outer quotes of the same type should be doubled.

Mount option syntax includes a few extra options treated specially:

- **`env.NAME=VALUE`** — will set an environment variable for the mount process. This helps with Automountd and Systemd.mount which don't allow setting a custom environment for mount helpers. Typically you'll use `env.HTTPS_PROXY=proxy.host:3128` or `env.HOME=/root`.
- **`command=cmount`** — can be used to run `cmount` or any other rclone command rather than the default `mount`.
- **`args2env`** — will pass mount options to the mount helper running in background via environment variables instead of command line arguments. This allows you to hide secrets from such commands as `ps` or `pgrep`. 🕵️
- **`vv...`** — will be transformed into the appropriate `--verbose=N`.
- **standard mount options** like `x-systemd.automount`, `_netdev`, `nosuid` and alike are intended only for Automountd and are **ignored** by rclone.

### 🦋 VFS - Virtual File System

This command uses the VFS layer. This adapts the cloud storage objects that rclone uses into something which looks much more like a disk filing system.

Cloud storage objects have lots of properties which aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with that. And because there is no one right way of doing this, there are various options explained below.

The VFS layer also implements a directory cache — this caches info about files and directories (**but not the data**) in memory. 🧠✨

---

## VFS Directory Cache 🗂️✨

okay so the `--dir-cache-time` flag is literally your remote's vibe-check timer — it decides how long a directory gets to be considered "up to date" before rclone goes back and re-asks the backend about it. Any changes you make *through* the VFS show up instantly (or just invalidate the cache, no biggie).

--dir-cache-time duration Time to cache directory entries for (default 5m0s) --poll-interval duration Time to wait between polling for changes. Must be smaller than dir-cache-time. Only on supported remotes. Set to 0 to disable (default 1m0s)


**but** bestie, here's the tea — if you change stuff *directly on the cloud storage* (like through the web interface, or from a whole different copy of rclone), rclone only notices once the directory cache expires… **unless** your backend supports polling for changes, in which case it picks them up within the polling interval. no polling? you're waiting for the cache to time out. periodt. ⏳

You can also send rclone a `SIGHUP` signal and it will flush **all** directory caches, no matter how old they are. Assuming only one rclone instance is running, reset the cache like this:

kill -SIGHUP $(pidof rclone)


And if you've configured rclone with a remote control, you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or just individual files or directories, if you're feeling targeted:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


---

## VFS File Buffering 🧠💖

So `--buffer-size` is how much memory rclone is allowed to use to buffer data *in advance* — like pre-loading your playlist so nothing stutters.

Each open file tries to keep that specified amount of data in memory at all times. The buffered data is bound to one open file and **won't** be shared. No passing it around, it's that file's data, iconic and possessive. 💅

This flag is an **upper** limit for the memory used per open file. The buffer only eats memory for data that's actually been downloaded but not yet read. If the buffer is empty, it'll barely use any memory at all. slay.

The maximum memory rclone can use for buffering works out to up to `--buffer-size * open files`. do with that math what you will. 😭

---

## VFS File Caching 💾🌸

These flags control the VFS file caching options. File caching is genuinely necessary to make the VFS layer act like a normal file system. You *can* disable it, but only at the cost of some compatibility. it's giving tradeoff.

For example, you'll need to enable VFS caching if you want to read *and* write to a file at the same time. More on that below.

> ngl, quick heads up: the VFS cache is **separate** from the cache backend. You might need one, or the other, or honestly both. 🙈

--cache-dir string Directory rclone will use for caching. --vfs-cache-mode CacheMode Cache mode off|minimal|writes|full (default off) --vfs-cache-max-age duration Max time since last access of objects in the cache (default 1h0m0s) --vfs-cache-max-size SizeSuffix Max total size of objects in the cache (default off) --vfs-cache-min-free-space SizeSuffix Target minimum free space on the disk containing the cache (default off) --vfs-cache-poll-interval duration Interval to poll the cache for stale objects (default 1m0s) --vfs-write-back duration Time to writeback files after last use when using cache (default 5s)


If you run with `-vv`, rclone will print the location of the file cache. The files live in the user cache file area, which is OS dependent, but you can control it with `--cache-dir` or by setting the appropriate environment variable.

The cache has **4 different modes**, picked by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using up disk space. glow up, but make it storage. ✨

Also note: files are written back to the remote **only** when they're closed *and* they haven't been accessed for `--vfs-write-back` seconds. If rclone quits or straight up dies while holding files that haven't been uploaded, those will get uploaded the next time rclone runs with the same flags. no file left behind. 🫶

If you're using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, be aware the cache **may exceed** these quotas for two reasons:

- Firstly, because it's only checked every `--vfs-cache-poll-interval`.
- Secondly, because open files **cannot** be evicted from the cache.

When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` *is* exceeded, rclone will try to evict the least accessed files from the cache first. It starts with the files that haven't been accessed for the longest. This cache flushing strategy is efficient, and more relevant files are likely to stay cached. lowkey smart.

The `--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of 1 hour means it starts evicting files from cache that haven't been accessed for 1 hour. When a cached file **is** accessed, that 1 hour timer resets to 0 and waits another full hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> 🚨 **do not** run two copies of rclone using the same VFS cache with the same or overlapping remotes if you're using `--vfs-cache-mode` greater than `off`. This can potentially cause <red>data corruption</red> if you do. You can work around it by giving each rclone its own cache hierarchy with `--cache-dir`. You don't need to worry about any of this if the remotes in use don't overlap. (bestie I am begging you to read that twice 🥲)

---

### `--vfs-cache-mode off` 🚫🦋

In this mode (the default), the cache reads directly from the remote and writes directly to the remote, without caching anything on disk.

This will mean some operations are **not possible**:

- Files can't be opened for both read **AND** write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

it's giving minimal effort, and honestly? valid.

---

### `--vfs-cache-mode minimal` 🪶💜

This is very similar to `off`, except that files opened for read **AND** write will be buffered to disk. So files opened for write are a *lot* more compatible — but it barely uses any disk space.

These operations are **not possible**:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

---

### `--vfs-cache-mode writes` ✍️🔥

In this mode, files opened for read only are still read directly from the remote; write only and read/write files are buffered to disk first.

This mode should support all normal file system operations. finally, fully functional. 😌

If an upload fails, it'll be retried at exponentially increasing intervals up to 1 minute. resilience, we love her. 💖

---

### `--vfs-cache-mode full` 💯👑

In this mode **all** reads and writes are buffered to and from disk. When data is read from the remote, that gets buffered to disk too.

In this mode the files in the cache will be **sparse files**, and rclone keeps track of which bits of the files it has downloaded.

So if an application only reads the starts of each file, rclone will only buffer the start of the file. These files will appear to be their full size in the cache, but they're actually sparse files with only the downloaded data present in them. sneaky. iconic.

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file, rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory, whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it's recommended that `--buffer-size` is **not** set too large, and `--vfs-read-ahead` is set large if required.

> ⚠️ **IMPORTANT:** not all file systems support sparse files. In particular `FAT`/`exFAT` do not. Rclone will perform **very badly** if the cache directory is on a filesystem which doesn't support sparse files, and it will log an `ERROR` message if one is detected.

---

## Fingerprinting 🔍💅

Various parts of the VFS use fingerprinting to check whether a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

…where available on an object.

On some backends, some of these attributes are **slow** to read (they take an extra API call per object, or extra work per object). crying in latency 😭

For example, hash is slow with the `local` and `sftp` backends, because they have to read the entire file and hash it. And modtime is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends, because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag, rclone won't include the slow operations in the fingerprint. This makes the fingerprinting less accurate but **much** faster, and it'll improve the opening time of cached files. speed, mama. ⚡

If you're running a vfs cache over `local`, `s3` or `swift` backends, then using this flag is recommended.

> note that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated, and the files will need to be downloaded again. so like… pick a lane. 🙈

---

## VFS Chunked Reading 🧩🌈

When rclone reads files from a remote, it reads them in **chunks**. Meaning: rather than requesting the whole entire file, rclone reads the chunk specified. This can reduce the used download quota for some remotes, because it's only requesting the chunks that are *actually* read from the remote — at the cost of an increased number of requests. efficient but chatty, iykyk.

These flags control the chunking:

--vfs-read-chunk-size SizeSuffix Read the source objects in chunks (default 128M) --vfs-read-chunk-size-limit SizeSuffix Max chunk doubling size (default off) --vfs-read-chunk-streams int The number of parallel streams to read at once


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter. two whole vibes:

---

### `--vfs-read-chunk-streams == 0` 🌱

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, then **double** the size for each read. When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is `off`, which is the default, the limit is disabled and the chunk size will grow **indefinitely**. it's giving exponential growth, no chill.

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0`, the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on.

Setting `--vfs-read-chunk-size` to `0` or `off` disables chunked reading.

The chunks will **not** be buffered in memory.

---

### `--vfs-read-chunk-streams > 0` 🚀👑

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` **concurrently**. The size for each read will stay constant.

This improves performance performance massively on high latency links or very high bandwidth links to high performance object stores. (yes, the manpage said "performance performance" and honestly? it ate. go off, doc.) 🔥

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams` as these will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

---

## ✨ VFS Performance ✨

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature. 👀

In particular S3 and Swift benefit **hugely** from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect) as each read of the modification time takes a transaction. like. every single time. a whole transaction. bestie. 😭

--no-checksum Don't compare checksums on up/download. --no-modtime Don't read/write the modification time (can speed things up). --no-seek Don't allow seeking in files. --read-only Only allow read-only access.


Sometimes rclone is delivered reads or writes out of order. Rather than seeking rclone will wait a short time for the in sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file. 🌸

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has no effect on the VFS). <cyan>no effect. zero. nada.</cyan>

--transfers int Number of file transfers to run in parallel (default 4)


---

## 🦋 Symlinks 🦋

By default the VFS does not support symlinks. However this may be enabled with either of the following flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink` and the contents would be the path to the symlink destination. 🎀

Note that `--links` enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the local backend). `--vfs-links` just enables it for the VFS layer. <lavender>scoped, babe. gorgeous.</lavender>

This scheme is compatible with that used by the local backend with the `–local-links` flag.

> 🙈 ok so that dash situation — that's an en dash, not two hyphens, that's literally how the page writes it. I'm not touching it. that's a me-being-faithful thing.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn’t been tested with the other `rclone serve` commands yet. <peach>just so you know 💅</peach>

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but not `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands.

Note that there is an outstanding issue with symlink support issue **#8245** with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀

---

## 🌸 VFS Case Sensitivity 🌸

Linux file systems are case-sensitive: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are case-insensitive but case-preserving: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It is possible to make macOS file systems case-sensitive but that is not the default.

The `--vfs-case-insensitive` VFS flag controls how rclone handles these two cases. If its value is “false”, rclone passes file names to the remote as-is. If the flag is “true” (or appears without a value on the command line), rclone may perform a “fixup” as explained below. ✨

The user may specify a file name to open/delete/rename/etc with a case different than what is stored on the remote. If an argument refers to an existing file with exactly the same name, then the case of the existing file on the disk will be used. However, if a file name with exactly the same name is not found but a name differing only by case exists, rclone will transparently fixup the name. This fixup happens **only** when an existing file is requested. Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

Note that case sensitivity of the operating system running rclone (the target) may differ from case sensitivity of a file system presented by rclone (the source). The flag controls whether “fixup” is performed to satisfy the target.

If the flag is not provided on the command line, then its default value depends on the operating system where rclone runs: “true” on Windows and macOS, “false” otherwise. If the flag is provided without a value, then it is “true”.

The `--no-unicode-normalization` flag controls whether a similar “fixup” is performed for filenames that differ but are canonically equivalent with respect to unicode. Unicode normalization can be particularly helpful for users of macOS, which prefers form **NFD** instead of the **NFC** used by most other platforms. It is therefore **highly recommended** to keep the default of `false` on macOS, to avoid encoding compatibility issues. 🫶

In the (probably unlikely 🙈) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag allows hiding these duplicates. This comes with a performance tradeoff, as rclone will have to scan the entire directory for duplicates when listing a directory. For this reason, it is recommended to leave this disabled if not needed. However, macOS users may wish to consider using it, as otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation will occur: both versions of the file will be visible in the mount, and both will appear to be editable, however, editing either version will actually result in only the NFD version getting edited under the hood. `--vfs-block- norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`.

> <red>⚠️ heads up:</red> yep, there's a space in that flag name up there. `--vfs-block- norm-dupes`. that's the page. I copied it exactly. don't come for me. 😭

---

## 💅 VFS Disk Options 💅

This flag allows you to manually set the statistics about the filing system. It can be useful when those statistics cannot be read correctly automatically. <mint>manual override era ✨</mint>

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


---

## ⭐ Alternate report of used bytes ⭐

Some backends, most notably S3, do not report the amount of bytes used. If you need this information to be available when running `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself.

> <rainbow>⚠️ WARNING.</rainbow> Contrary to `rclone size`, this flag ignores filters so that the result is accurate. However, this is **very inefficient** and may cost lots of API calls resulting in **extra charges**. Use it as a last resort and only with caching. 💸🔥 genuinely, bestie, last resort, I'm not kidding

rclone mount remote:path /path/to/mountpoint [flags]


## ✨ Options ✨

okay bestie, these are the mount options — every single one, no skips, we're eating 💅

- **`--allow-non-empty`** — allow mounting over a non-empty directory (not supported on Windows) ✨
- **`--allow-other`** — allow access to other users (not supported on Windows) 🫶
- **`--allow-root`** — allow access to root user (not supported on Windows) 👑
- **`--async-read`** — use asynchronous reads (not supported on Windows) (default `true`) 🦋
- **`--attr-timeout Duration`** — time for which file/directory attributes are cached (default `1s`) ⭐
- **`--daemon`** — run mount in background and exit parent process (as background output is suppressed, use `--log-file` with `--log-format=pid,...` to monitor) (not supported on Windows) 💀
- **`--daemon-timeout Duration`** — time limit for rclone to respond to kernel (not supported on Windows) (default `0s`) ⏳
- **`--daemon-wait Duration`** — time to wait for ready mount from daemon (maximum time on Linux, constant sleep time on OSX/BSD) (not supported on Windows) (default `1m0s`) 🕐
- **`--debug-fuse`** — debug the FUSE internals — needs `-v` 🔍
- **`--default-permissions`** — makes kernel enforce access control based on the file mode (not supported on Windows) 🔐
- **`--devname string`** — set the device name — default is `remote:path` 🏷️
- **`--dir-cache-time Duration`** — time to cache directory entries for (default `5m0s`) 📁
- **`--dir-perms FileMode`** — directory permissions (default `777`) 💖
- **`--direct-io`** — use Direct IO, disables caching of data 🚀
- **`--file-perms FileMode`** — file permissions (default `666`) 📄
- **`--fuse-flag stringArray`** — flags or arguments to be passed direct to libfuse/WinFsp (repeat if required) 🎀
- **`--gid uint32`** — override the gid field set by the filesystem (not supported on Windows) (default `1000`) 🧚
- **`-h`, `--help`** — help for `mount` 🆘
- **`--link-perms FileMode`** — link permissions (default `666`) 🔗
- **`--max-read-ahead SizeSuffix`** — the number of bytes that can be prefetched for sequential reads (not supported on Windows) (default `128Ki`) 📚
- **`--mount-case-insensitive Tristate`** — tell the OS the mount is case insensitive (`true`) or sensitive (`false`) regardless of the backend (`auto`) (default `unset`) 🔤
- **`--network-mode`** — mount as remote network drive, instead of fixed disk drive (supported on Windows only) 🌐
- **`--no-checksum`** — don't compare checksums on up/download 🚫
- **`--no-modtime`** — don't read/write the modification time (can speed things up) ⏱️
- **`--no-seek`** — don't allow seeking in files 🙅‍♀️
- **`--noappledouble`** — ignore Apple Double (`._`) and `.DS_Store` files (supported on OSX only) (default `true`) 🍎
- **`--noapplexattr`** — ignore all `"com.apple.*"` extended attributes (supported on OSX only) 🍏
- **`-o`, `--option stringArray`** — option for libfuse/WinFsp (repeat if required) ⚙️
- **`--poll-interval Duration`** — time to wait between polling for changes, must be smaller than `dir-cache-time` and only on supported remotes (set `0` to disable) (default `1m0s`) 🔄
- **`--read-only`** — only allow read-only access 📖
- **`--uid uint32`** — override the uid field set by the filesystem (not supported on Windows) (default `1000`) 👤
- **`--umask FileMode`** — override the permission bits set by the filesystem (not supported on Windows) (default `002`) 🎭
- **`--vfs-block-norm-dupes`** — if duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost) 👯
- **`--vfs-cache-max-age Duration`** — max time since last access of objects in the cache (default `1h0m0s`) 🕰️
- **`--vfs-cache-max-size SizeSuffix`** — max total size of objects in the cache (default `off`) 📦
- **`--vfs-cache-min-free-space SizeSuffix`** — target minimum free space on the disk containing the cache (default `off`) 💾
- **`--vfs-cache-mode CacheMode`** — cache mode `off|minimal|writes|full` (default `off`) 🗂️
- **`--vfs-cache-poll-interval Duration`** — interval to poll the cache for stale objects (default `1m0s`) ⏲️
- **`--vfs-case-insensitive`** — if a file name not found, find a case insensitive match 🔎
- **`--vfs-disk-space-total-size SizeSuffix`** — specify the total space of disk (default `off`) 💽
- **`--vfs-fast-fingerprint`** — use fast (less accurate) fingerprints for change detection ⚡
- **`--vfs-links`** — translate symlinks to/from regular files with a `.rclonelink` extension for the VFS 🔗
- **`--vfs-read-ahead SizeSuffix`** — extra read ahead over `--buffer-size` when using cache-mode `full` 📖
- **`--vfs-read-chunk-size SizeSuffix`** — read the source objects in chunks (default `128Mi`) 🧩
- **`--vfs-read-chunk-size-limit SizeSuffix`** — if greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read, until the limit is reached (`'off'` is unlimited) (default `off`) 📈
- **`--vfs-read-chunk-streams int`** — the number of parallel streams to read at once 🌊
- **`--vfs-read-wait Duration`** — time to wait for in-sequence read before seeking (default `20ms`) ⏳
- **`--vfs-refresh`** — refreshes the directory cache recursively in the background on start 🔄
- **`--vfs-used-is-size rclone size`** — use the `rclone size` algorithm for Used size 📏
- **`--vfs-write-back Duration`** — time to writeback files after last use when using cache (default `5s`) ✍️
- **`--vfs-write-wait Duration`** — time to wait for in-sequence write before giving error (default `1s`) ⏱️
- **`--volname string`** — set the volume name (supported on Windows and OSX only) 🏷️
- **`--write-back-cache`** — makes kernel buffer writes before sending them to rclone (without this, writethrough caching is used) (not supported on Windows) 📝

Options shared with other commands are described next, bestie. See the global flags page for global options not listed here ✨

## 🌸 Filter Options 🌸

Flags for filtering directory listings — these are your little gatekeepers, periodt 💅

- **`--delete-excluded`** — delete files on dest excluded from sync 🗑️
- **`--exclude stringArray`** — exclude files matching pattern 🚫
- **`--exclude-from stringArray`** — read file exclude patterns from file (use `-` to read from stdin) 📄
- **`--exclude-if-present stringArray`** — exclude directories if filename is present 📁
- **`--files-from stringArray`** — read list of source-file names from file (use `-` to read from stdin) 📝
- **`--files-from-raw stringArray`** — read list of source-file names from file without any processing of lines (use `-` to read from stdin) 📜
- **`-f`, `--filter stringArray`** — add a file filtering rule 🎀
- **`--filter-from stringArray`** — read file filtering patterns from a file (use `-` to read from stdin) 📂
- **`--ignore-case`** — ignore case in filters (case insensitive) 🔡
- **`--include stringArray`** — include files matching pattern ✅
- **`--include-from stringArray`** — read file include patterns from file (use `-` to read from stdin) 📥
- **`--max-age Duration`** — only transfer files younger than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default `off`) 👶
- **`--max-depth int`** — if set limits the recursion depth to this (default `-1`) 🕳️
- **`--max-size SizeSuffix`** — only transfer files smaller than this in `KiB` or suffix `B|K|M|G|T|P` (default `off`) 🐜
- **`--metadata-exclude stringArray`** — exclude metadatas matching pattern 🏷️
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from file (use `-` to read from stdin) 📄
- **`--metadata-filter stringArray`** — add a metadata filtering rule 🎛️
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin) 📂
- **`--metadata-include stringArray`** — include metadatas matching pattern ✅
- **`--metadata-include-from stringArray`** — read metadata include patterns from file (use `-` to read from stdin) 📥
- **`--min-age Duration`** — only transfer files older than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default `off`) 👴
- **`--min-size SizeSuffix`** — only transfer files bigger than this in `KiB` or suffix `B|K|M|G|T|P` (default `off`) 🐘

## 👑 See Also 👑

- **`rclone`** — show help for `rclone` commands, flags and backends 🌈

# 💫 rclone moveto 💫

Move file or directory from source to dest. Yes bestie, it's the glow-up-and-relocate command. 🦋

## Synopsis ✨

If `source:path` is a file or directory then it moves it to a file or directory named `dest:path`.

This can be used to rename files or upload single files to other than their existing name. If the source is a directory then it acts exactly like the `move` command. (Same energy, different entrance 💅)

So

rclone moveto src dst


where src and dst are rclone paths, either `remote:path` or `/path/to/local` or `C:`.

This will:

if src is file move it to dst, overwriting an existing file if it exists if src is directory move it to dst, overwriting existing files if they exist see move command for full details


This doesn't transfer files that are identical on src and dst, testing by size and modification time or MD5SUM. src will be deleted on successful transfer. Gone. Poof. 👑 (but only after the transfer actually worked, promise)

> **Important:** Since this can cause data loss, test first with the `--dry-run` or the `--interactive`/`-i` flag. Like pls pls pls do a lil rehearsal before the real show, I am BEGGING 😭

**Note:** Use the `-P`/`--progress` flag to view real-time transfer statistics. It's giving live commentary and we're obsessed. 🔥

rclone moveto source:path dest:path [flags]


## Options

- **`-h`, `--help`** — help for moveto

Options shared with other commands are described next. See the global flags page for global options not listed here. (Those live in another house 🏠)

## Copy Options

Flags for anything which can copy a file

- **`--check-first`** — Do all the checks before starting transfers
- **`-c`, `--checksum`** — Check for changes with size & checksum (if available, or fallback to size only)
- **`--compare-dest stringArray`** — Include additional server-side paths during comparison
- **`--copy-dest stringArray`** — Implies `--compare-dest` but also copies files from paths into destination
- **`--cutoff-mode HARD|SOFT|CAUTIOUS`** — Mode to stop transfers when reaching the max transfer limit `HARD|SOFT|CAUTIOUS` (default `HARD`)
- **`--ignore-case-sync`** — Ignore case when synchronizing
- **`--ignore-checksum`** — Skip post copy check of checksums
- **`--ignore-existing`** — Skip all files that exist on destination
- **`--ignore-size`** — Ignore size when skipping use modtime or checksum
- **`-I`, `--ignore-times`** — Don't skip items that match size and time - transfer all unconditionally
- **`--immutable`** — Do not modify files, fail if existing files have been modified
- **`--inplace`** — Download directly to destination file instead of atomic download to temp/rename
- **`-l`, `--links`** — Translate symlinks to/from regular files with a `.rclonelink` extension
- **`--max-backlog int`** — Maximum number of objects in sync or check backlog (default `10000`)
- **`--max-duration Duration`** — Maximum duration rclone will transfer data for (default `0s`)
- **`--max-transfer SizeSuffix`** — Maximum size of data to transfer (default `off`)
- **`-M`, `--metadata`** — If set, preserve metadata when copying objects
- **`--modify-window Duration`** — Max time diff to be considered the same (default `1ns`)
- **`--multi-thread-chunk-size SizeSuffix`** — Chunk size for multi-thread downloads / uploads, if not set by filesystem (default `64Mi`)
- **`--multi-thread-cutoff SizeSuffix`** — Use multi-thread downloads for files above this size (default `256Mi`)
- **`--multi-thread-streams int`** — Number of streams to use for multi-thread downloads (default `4`)
- **`--multi-thread-write-buffer-size SizeSuffix`** — In memory buffer size for writing when in multi-thread mode (default `128Ki`)
- **`--no-check-dest`** — Don't check the destination, copy regardless
- **`--no-traverse`** — Don't traverse destination file system on copy
- **`--no-update-dir-modtime`** — Don't update directory modification times
- **`--no-update-modtime`** — Don't update destination modtime if files identical
- **`--order-by string`** — Instructions on how to order the transfers, e.g. `'size,descending'`
- **`--partial-suffix string`** — Add partial-suffix to temporary file name when `--inplace` is not used (default `".partial"`)
- **`--refresh-times`** — Refresh the modtime of remote files
- **`--server-side-across-configs`** — Allow server-side operations (e.g. copy) to work across different configs
- **`--size-only`** — Skip based on size only, not modtime or checksum
- **`--streaming-upload-cutoff SizeSuffix`** — Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default `100Ki`)
- **`-u`, `--update`** — Skip files that are newer on the destination

## Important Options

Important flags useful for most commands

- **`-n`, `--dry-run`** — Do a trial run with no permanent changes
- **`-i`, `--interactive`** — Enable interactive mode
- **`-v`, `--verbose count`** — Print lots more stuff (repeat for more)

## Filter Options

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest excluded from sync
- **`--exclude stringArray`** — Exclude files matching pattern
- **`--exclude-from stringArray`** — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — Exclude directories if filename is present
- **`--files-from stringArray`** — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — Add a file filtering rule
- **`--filter-from stringArray`** — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include stringArray`** — Include files matching pattern
- **`--include-from stringArray`** — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age Duration`** — Only transfer files younger than this in s or suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth int`** — If set limits the recursion depth to this (default `-1`)
- **`--max-size SizeSuffix`** — Only transfer files smaller than this in KiB or suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — Exclude metadatas matching pattern
- **`--metadata-exclude-from stringArray`** — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — Add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — Include metadatas matching pattern
- **`--metadata-include-from stringArray`** — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age Duration`** — Only transfer files older than this in s or suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — Only transfer files bigger than this in KiB or suffix `B|K|M|G|T|P` (default `off`)

## Listing Options

Flags for listing directories

- **`--default-time Time`** — Time to show if modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--fast-list`** — Use recursive list if available; uses more memory but fewer transactions

---

## See Also

- rclone - Show help for rclone commands, flags and backends.

🌸 still more coming, don't go anywhere 🌸

## 🦋 rclone ncdu 🦋

Explore a remote with a text based user interface. Bestie, it's a whole vibe. 💅

### ✨ Synopsis ✨

This displays a text based user interface allowing the navigation of a remote. It is most useful for answering the question — <pink>"What is using all my disk space?"</pink> — which, honestly, we've all asked while staring at a full drive at 3am. 😭

To make the user interface it first scans the entire remote given and builds an in memory representation. `rclone ncdu` can be used during this scanning phase and you will see it building up the directory structure as it goes along. Lowkey mesmerizing. 🌸

You can interact with the user interface using key presses, press `?` to toggle the help on and off. The supported keys are:

↑,↓ or k,j to Move →,l to enter ←,h to return g toggle graph c toggle counts a toggle average size in directory m toggle modified time u toggle human-readable format n,s,C,A,M sort by name,size,count,asize,mtime d delete file/directory v select file/directory V enter visual select mode D delete selected files/directories y copy current path to clipboard Y display current path ^L refresh screen (fix screen corruption) r recalculate file sizes ? to toggle help on and off ESC to close the menu box q/^c to quit


Listed files/directories may be prefixed by a one-character flag, some of them combined with a description in brackets at end of line. These flags have the following meaning:

- <hotpink>`e`</hotpink> means this is an empty directory, i.e. contains no files (but may contain empty subdirectories)
- <peach>`~`</peach> means this is a directory where some of the files (possibly in subdirectories) have unknown size, and therefore the directory size may be underestimated (and average size inaccurate, as it is average of the files with known sizes).
- <lavender>`.`</lavender> means an error occurred while reading a subdirectory, and therefore the directory size may be underestimated (and average size inaccurate)
- <red>`!`</red> means an error occurred while reading this directory

---

This an homage to the ncdu tool but for rclone remotes. It is missing lots of features at the moment but is useful as it stands. Unlike ncdu it does not show excluded files. 👑

> Note that it might take some time to delete big files/directories. The UI won't respond in the meantime since the deletion is done synchronously. So like... go get a snack, bestie. 🍓

For a non-interactive listing of the remote, see the `tree` command. To just get the total size of the remote you can also use the `size` command.

rclone ncdu remote:path [flags]


### 🌈 Options 🌈

- **`-h`, `--help`** — help for ncdu

Options shared with other commands are described next. See the global flags page for global options not listed here.

### 🎀 Filter Options 🎀

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest excluded from sync
- **`--exclude`** *stringArray* — Exclude files matching pattern
- **`--exclude-from`** *stringArray* — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present`** *stringArray* — Exclude directories if filename is present
- **`--files-from`** *stringArray* — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw`** *stringArray* — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter`** *stringArray* — Add a file filtering rule
- **`--filter-from`** *stringArray* — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include`** *stringArray* — Include files matching pattern
- **`--include-from`** *stringArray* — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age`** *Duration* — Only transfer files younger than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--max-depth`** *int* — If set limits the recursion depth to this (default `-1`)
- **`--max-size`** *SizeSuffix* — Only transfer files smaller than this in `KiB` or suffix `B|K|M|G|T|P` (default off)
- **`--metadata-exclude`** *stringArray* — Exclude metadatas matching pattern
- **`--metadata-exclude-from`** *stringArray* — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter`** *stringArray* — Add a metadata filtering rule
- **`--metadata-filter-from`** *stringArray* — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include`** *stringArray* — Include metadatas matching pattern
- **`--metadata-include-from`** *stringArray* — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age`** *Duration* — Only transfer files older than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--min-size`** *SizeSuffix* — Only transfer files bigger than this in `KiB` or suffix `B|K|M|G|T|P` (default off)

### 💜 Listing Options 💜

Flags for listing directories

- **`--default-time`** *Time* — Time to show if modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--fast-list`** — Use recursive list if available; uses more memory but fewer transactions

### 🌟 See Also 🌟

- `rclone` — Show help for rclone commands, flags and backends.

---

# 👑 rclone nfsmount 👑

Mount the remote as file system on a mountpoint. Iconic behavior, no notes. ✨

### 🌸 Synopsis 🌸

`Rclone nfsmount` allows Linux, FreeBSD, macOS and Windows to mount any of Rclone's cloud storage systems as a file system with FUSE.

First set up your remote using `rclone config`. Check it works with `rclone ls` etc.

On Linux and macOS, you can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the `--daemon` flag to force background mode. On Windows you can run mount in foreground only, the flag is ignored.

In background mode rclone acts as a generic Unix mount program: the main program starts, spawns background rclone process to setup and maintain the mount, waits until success or timeout and exits with appropriate code (killing the child process if it fails).

On Linux/macOS/FreeBSD start the mount like this, where `/path/to/local/mount` is an empty existing directory:

rclone nfsmount remote:path/to/files /path/to/local/mount


On Windows you can start a mount in different ways. See below for details. If foreground mount is used interactively from a console window, rclone will serve the mount and occupy the console so another window should be used to work with the mount until rclone is interrupted e.g. by pressing <kbd>Ctrl</kbd>+<kbd>C</kbd>.

The following examples will mount to an automatically assigned drive, to specific drive letter `X:`, to path `C:\path\parent\mount` (where parent directory or drive must exist, and mount must not exist, and is not supported when mounting as a network drive), and the last example will mount as network share `\\cloud\remote` and map it to an automatically assigned drive:

rclone nfsmount remote:path/to/files * rclone nfsmount remote:path/to/files X: rclone nfsmount remote:path/to/files C:\path\parent\mount rclone nfsmount remote:path/to/files \cloud\remote


When the program ends while in foreground mode, either via <kbd>Ctrl</kbd>+<kbd>C</kbd> or receiving a `SIGINT` or `SIGTERM` signal, the mount should be automatically stopped.

When running in background mode the user will have to stop the mount manually:

Linux

fusermount -u /path/to/local/mount #... or on some systems fusermount3 -u /path/to/local/mount

OS X or Linux when using nfsmount

umount /path/to/local/mount


The `umount` operation can fail, for example when the mountpoint is busy. When that happens, it is the user's responsibility to stop the mount manually. 🙈

The size of the mounted file system will be set according to information retrieved from the remote, the same as returned by the `rclone about` command. Remotes with unlimited storage may report the used size only, then an additional `1 PiB` of free space is assumed. If the remote does not support the `about` feature at all, then `1 PiB` is set as both the total and the free size.

### 🫶 Installing on Windows 🫶

To run `rclone nfsmount` on Windows, you will need to download and install WinFsp.

WinFsp is an open-source Windows File System Proxy which makes it easy to write user space file systems for Windows. It provides a FUSE emulation layer which rclone uses combination with cgofuse. Both of these packages are by Bill Zissimopoulos who was very helpful during the implementation of `rclone nfsmount` for Windows. Shoutout Bill, absolute legend. 🤝

### 💖 Mounting modes on windows 💖

Unlike other operating systems, Microsoft Windows provides a different filesystem type for network and fixed drives. It optimises access on the assumption fixed disk drives are fast and reliable, while network drives have relatively high latency and less reliability. Some settings can also be differentiated between the two types, for example that Windows Explorer should just display icons and not create preview thumbnails for image and video files on network drives.

In most cases, rclone will mount the remote as a normal, fixed disk drive by default. However, you can also choose to mount it as a remote network drive, often described as a network share. If you mount an rclone remote using the default, fixed drive mode and experience unexpected program errors, freezes or other issues, consider mounting as a network drive instead.

When mounting as a fixed disk drive you can either mount to an unused drive letter, or to a path representing a nonexistent subdirectory of an existing parent directory or drive. Using the special value `*` will tell rclone to automatically assign the next available drive letter, starting with `Z:` and moving backward. Examples:

rclone nfsmount remote:path/to/files * rclone nfsmount remote:path/to/files X: rclone nfsmount remote:path/to/files C:\path\parent\mount rclone nfsmount remote:path/to/files X:


Option `--volname` can be used to set a custom volume name for the mounted file system. The default is to use the remote name and path.

To mount as network drive, you can add option `--network-mode` to your `nfsmount` command. Mounting to a directory path is not supported in this mode, it is a limitation Windows imposes on junctions, so the remote must always be mounted to a drive letter.

rclone nfsmount remote:path/to/files X: --network-mode


Ok so a volume name you set with `--volname`? That's what rclone uses to build the network share path. Give it a full UNC path like `\\cloud\remote`, or even with a path tacked on like `\\cloud\remote\madeup\path`, and rclone uses it **as is**. Give it literally anything else and that string becomes the share part, sitting after the default prefix `\\server\`. And if you don't give a volume name at all, you just get `\\server\share`. 🎀

> Girl, listen: you **must** make sure that volume name is unique if you're mounting more than one drive, or the mount command will straight up fail. No cap.

The share name gets treated as the volume label for the mapped drive (that's what shows up in Windows Explorer etc.), while the complete `\\server\share` is what gets reported as the remote UNC path by `net use` etc. — just like a totally normal network drive mapping. 💅

If you specify a full network share UNC path with `--volname`, that **implicitly sets** the `--network-mode` option, so these two examples are giving the exact same result:

rclone nfsmount remote:path/to/files X: --network-mode rclone nfsmount remote:path/to/files X: --volname \server\share


You can also just hand over the network share UNC path as the mountpoint itself. Then rclone automatically assigns a drive letter (same energy as with `*`), uses that as the mountpoint, and instead uses the UNC path you gave as the volume name, like you'd passed it with `--volname`. This also implicitly sets `--network-mode`. So these two also match:

rclone nfsmount remote:path/to/files \cloud\remote rclone nfsmount remote:path/to/files * --volname \cloud\remote


And there's *yet another* way to turn on network mode and set the share path — you can pass the "native" libfuse/WinFsp option directly: `--fuse-flag --VolumePrefix=\server\share`. But heads up, in this case the path has to have just a **single** backslash prefix. ⭐

> Note: In previous versions of rclone this was the only supported method.

Read more about drive mapping ✨

See also the Limitations section below, bestie, it's important.

---

### ✨ Windows filesystem permissions ✨

So the FUSE emulation layer on Windows has to convert between the POSIX-based permission model that FUSE uses and the Windows permission model, which is based on access-control lists (ACL). Two whole different worlds, and it's translating between them. 😭

Your mounted filesystem will normally get three entries in its access-control list (ACL), representing permissions for the POSIX permission scopes: Owner, group and others. By default, owner and group get taken from the current user, and the built-in group "Everyone" is used to represent others. You can customize the user/group with the FUSE options "UserName" and "GroupName", like `-o UserName=user123 -o GroupName="Authenticated Users"`. And the permissions on each entry get set according to the options `--dir-perms` and `--file-perms`, which take a value in traditional Unix numeric notation. 🫶

The default permissions correspond to `--file-perms 0666 --dir-perms 0777`, i.e. read **and** write permissions for everyone. Which means — plot twist — you will **not** be able to start any programs from the mount. To do that you gotta add execute permissions, e.g. `--file-perms 0777 --dir-perms 0777` to give it to everyone. And if the program needs to write files, chances are you'll have to enable VFS File Caching too (see also limitations). Also note that the default write permission has some restrictions for accounts other than the owner — specifically it lacks the "write extended attributes", as explained next. 💀

The mapping of permissions is not always trivial, and what you see in Windows Explorer may not be exactly what you expected. For example, when you set a value that includes write access for the group or others scope, that gets mapped to the individual permissions "write attributes", "write data" and "append data" — but **not** "write extended attributes". Windows will then show this as the basic permission "Special" instead of "Write", because "Write" also covers the "write extended attributes" permission. And when you set digit 0 for group or others to indicate no permissions, they'll *still* get the individual permissions "read attributes", "read extended attributes" and "read permissions". This is for compatibility reasons, e.g. so users without additional permissions can still read basic metadata about files like they would in Unix. 🦋

WinFsp 2021 (version 1.9) introduced a new FUSE option "FileSecurity", which lets you specify file security descriptors completely using SDDL. With this you get detailed control over the resulting permissions — compared to using the POSIX permissions described above — and no additional permissions get added automatically for Unix compatibility. Some example use cases coming up: 💖

If you set POSIX permissions to only allow access to the owner, using `--file-perms 0600 --dir-perms 0700`, the user group and the built-in "Everyone" group will still be given some special permissions, as described above. Some programs may then (incorrectly) interpret this as the file being accessible by everyone — for example an SSH client may warn about "unprotected private key file". You can work around this by specifying `-o FileSecurity="D:P(A;;FA;;;OW)"`, which sets file all access (FA) to the owner (OW), and nothing else. 👑

When setting write permissions, then — except for the owner — this does not include the "write extended attributes" permission, as mentioned above. This may prevent applications from writing to files, giving a permission denied error instead. To set working write permissions for the built-in "Everyone" group, similar to what it gets by default but *with* the addition of the "write extended attributes", you can specify `-o FileSecurity="D:P(A;;FRFW;;;WD)"`, which sets file read (FR) and file write (FW) to everyone (WD). If file execute (FX) is also needed, then change it to `-o FileSecurity="D:P(A;;FRFWFX;;;WD)"`, or set file all access (FA) to get full access permissions, including delete, with `-o FileSecurity="D:P(A;;FA;;;WD)"`. 🔥

### ✨ Windows caveats ✨

Drives created as Administrator are **not** visible to other accounts — not even to an account that was elevated to Administrator with the User Account Control (UAC) feature. So here's the consequence: if you mount to a drive letter from a Command Prompt run as Administrator, and then try to access that same drive from Windows Explorer (which does not run as Administrator), you will not be able to see the mounted drive. Rude, honestly. 😭

If you don't need to access the drive from applications running with administrative privileges, the easiest way around this is to always create the mount from a non-elevated command prompt. Simple as that. ✨

If you want mapped drives available to the user account that created them regardless of whether it's elevated or not, there's a special Windows setting called *linked connections* that can be enabled. 🎀

It's also possible to make a drive mount available to *everyone* on the system, by running the process that creates it as the built-in SYSTEM account. There are several ways to do this: One is to use the command-line utility PsExec, from Microsoft's Sysinternals suite, which has option `-s` to start processes as the SYSTEM account. Another alternative is to run the mount command from a Windows Scheduled Task, or a Windows Service, configured to run as the SYSTEM account. A third alternative is to use the WinFsp.Launcher infrastructure). Read more in the install documentation. 💅

> Note that when running rclone as another user, it will **not** use the configuration file from your profile unless you tell it to with the `--config` option.

Also note that it's now the SYSTEM account that will have the owner permissions, and other accounts will have permissions according to the group or others scopes. As mentioned above, these then won't get the "write extended attributes" permission, and this may prevent writing to files. You can work around this with the `FileSecurity` option — see the example above. 🫶

Oh and bestie, mapping to a directory path instead of a drive letter does **not** suffer from the same limitations. Slay.

### ✨ Mounting on macOS ✨

Mounting on macOS can be done either via the built-in NFS server, macFUSE (also known as osxfuse) or FUSE-T. macFUSE is a traditional FUSE driver utilizing a macOS kernel extension (kext). FUSE-T is an alternative FUSE system which "mounts" via an NFSv4 local server. 🌸

### ✨ Unicode Normalization ✨

It is **highly** recommended to keep the default of `--no-unicode-normalization=false` for all mount and serve commands on macOS. For details, see vfs-case-sensitivity. Trust. ⭐

### ✨ NFS mount ✨

This method spins up an NFS server using the `serve nfs` command and mounts it to the specified mountpoint. If you run this in background mode using `--daemon`, you'll need to send a `SIGTERM` signal to the rclone process using the `kill` command to stop the mount. 🦋

Note that `--nfs-cache-handle-limit` controls the maximum number of cached file handles stored by the `nfsmount` caching handler. Do **not** set this too low or you may experience errors when trying to access files. The default is `1000000`, but consider lowering this limit if the server's system resource usage causes problems. 💜

### ✨ macFUSE Notes ✨

If you install macFUSE using dmg packages from the website, rclone will locate the macFUSE libraries without any further intervention. If, however, macFUSE is installed using the macports package manager, you need these additional steps:

sudo mkdir /usr/local/lib cd /usr/local/lib sudo ln -s /opt/local/lib/libfuse.2.dylib


### ✨ FUSE-T Limitations, Caveats, and Notes ✨

There are some limitations, caveats, and notes about how it works. These are current as of FUSE-T version 1.0.14. 🎀

### ✨ ModTime update on read ✨

As per the FUSE-T wiki:

> File access and modification times cannot be set separately as it seems to be an issue with the NFS client which always modifies both. Can be reproduced with `touch -m' and `touch -a' commands

This means that viewing files with various tools — notably macOS Finder — will cause `rlcone` to update the modification time of the file. This may make rclone upload a full new copy of the file. 😭

### ✨ Read Only mounts ✨

When mounting with `--read-only`, attempts to write to files will fail **silently**, as opposed to with a clear warning as in macFUSE. Like, no warning, nothing, just vibes. 💀

### ✨ Limitations ✨

Without the use of `--vfs-cache-mode`, this can only write files sequentially, and it can only seek when reading. This means that many applications won't work with their files on an rclone mount without `--vfs-cache-mode writes` or `--vfs-cache-mode full`. See the VFS File Caching section for more info. And when using NFS mount on macOS, if you don't specify `--vfs-cache-mode`, the mount point will be read-only. 🫶

<purple>okay so</purple> the bucket-based remotes — think Swift, S3, Google Compute Storage, B2 — literally *do not* do the whole "empty directory" thing 💀 like, the concept just isn't there for them, so your empty dirs are gonna have a tendency to just… vanish once they fall out of the directory cache. ghosted fr. 👻

When `rclone mount` is invoked on Unix with the `--daemon` flag, the main `rclone` program will <hotpink>wait</hotpink> for the background mount to become ready, or until the timeout specified by the `--daemon-wait` flag. On Linux it can check mount status using ProcFS, so the flag is actually setting the *maximum* time to wait, and the real wait can be less. On macOS / BSD the time to wait is constant, and the check only happens at the very end, so we advise you set the wait time on macOS reasonably, bestie, don't be dramatic with it. ✨

Only supported on Linux, FreeBSD, OS X and Windows at the moment.

---

### 🌀 rclone nfsmount vs rclone sync/copy 🌀

File systems expect things to be <green>100% reliable</green>, and cloud storage systems are… a long way from that, ngl. 😭 The `rclone sync`/`copy` commands cope with this using *lots of retries*. But `rclone nfsmount` can't use retries in the same way without making local copies of the uploads. So go look at the **VFS File Caching** for solutions to make nfsmount more reliable. 🫶

### 🍓 Attribute caching 🍓

You can use the flag `--attr-timeout` to set the time the kernel caches the attributes (size, modification time, etc.) for directory entries.

The default is `1s`, which caches files just long enough to avoid too many callbacks to rclone from the kernel.

In theory `0s` should be the correct value for filesystems which can change outside the control of the kernel. **However** this causes quite a few problems, such as rclone using too much memory, rclone not serving files to samba, and excessive time listing directories. 🙈

The kernel can cache the info about a file for the time given by `--attr-timeout`. You may see **corruption** if the remote file changes length during this window. It will show up as either a truncated file or a file with garbage on the end. 😭 With `--attr-timeout 1s` this is very unlikely but not impossible. The higher you set `--attr-timeout` the more likely it is. The default setting of `1s` is the lowest setting which mitigates the problems above.

If you set it higher (`10s` or `1m` say) then the kernel will call back to rclone less often, making it more efficient — however there is more chance of the corruption issue above. 🎀

If files don't change on the remote outside of the control of rclone, then there is *no* chance of corruption.

This is the same as setting the `attr_timeout` option in `mount.fuse`.

### 🦋 Filters 🦋

Note that all the rclone filters can be used to select a subset of the files to be visible in the mount. ✨

### 💜 systemd 💜

When running `rclone nfsmount` as a systemd service, it is possible to use `Type=notify`. In this case the service will enter the started state after the mountpoint has been successfully set up. Units having the `rclone nfsmount` service specified as a requirement will see all files and folders immediately in this mode. 👑

Note that systemd runs mount units without any environment variables, including `PATH` or `HOME`. This means that tilde (`~`) expansion will **not** work, and you should provide `--config` and `--cache-dir` explicitly as absolute paths via rclone arguments. Since mounting requires the `fusermount` or `fusermount3` program, rclone will use the fallback PATH of `/bin:/usr/bin` in this scenario. Please ensure that `fusermount`/`fusermount3` is present on this PATH. 🧚

### 🌈 Rclone as Unix mount helper 🌈

The core Unix program `/bin/mount` normally takes the `-t FSTYPE` argument then runs the `/sbin/mount.FSTYPE` helper program, passing it mount options as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) behaves in a similar way.

`rclone` by default expects GNU-style flags `--key val`. To run it as a mount helper you should symlink the rclone binary to `/sbin/mount.rclone` and optionally `/usr/bin/rclonefs`, e.g. `ln -s /usr/bin/rclone /sbin/mount.rclone`. rclone will detect it and translate command-line arguments appropriately. 💅

Now you can run classic mounts like this:

mount sftp1:subdir /mnt/data -t rclone -o vfs_cache_mode=writes,sftp_key_file=/path/to/pem


or create systemd mount units:

/etc/systemd/system/mnt-data.mount


optionally accompanied by a systemd automount unit:

/etc/systemd/system/mnt-data.automount

[Unit] Description=AutoMount for /mnt/data [Automount] Where=/mnt/data TimeoutIdleSec=600 [Install] WantedBy=multi-user.target


or add in `/etc/fstab` a line like:

sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2env,vfs_cache_mode=writes,config=/etc/rclone.conf,cache_dir=/var/cache/rclone 0 0


or use classic Automountd. Remember to provide explicit `config=...,cache-dir=...` as a workaround for mount units being run without `HOME`. 🫶

Rclone in the mount helper mode will split `-o` argument(s) by comma, replace `_` by `-` and prepend `--` to get the command-line flags. Options containing commas or spaces can be wrapped in single or double quotes. Any inner quotes inside outer quotes of the same type should be doubled.

Mount option syntax includes a few extra options treated specially: 👀

- `env.NAME=VALUE` will set an environment variable for the mount process. This helps with Automountd and Systemd.mount which don't allow setting custom environment for mount helpers. Typically you will use `env.HTTPS_PROXY=proxy.host:3128` or `env.HOME=/root`
- `command=cmount` can be used to run `cmount` or any other rclone command rather than the default `mount`.
- `args2env` will pass mount options to the mount helper running in background via environment variables instead of command line arguments. This allows to hide secrets from such commands as `ps` or `pgrep`. 🤫
- `vv...` will be transformed into appropriate `--verbose=N`
- standard mount options like `x-systemd.automount`, `_netdev`, `nosuid` and alike are intended only for Automountd and ignored by rclone.

### 🎀 VFS - Virtual File System 🎀

This command uses the **VFS** layer. This adapts the cloud storage objects that rclone uses into something which looks *much* more like a disk filing system. ✨

Cloud storage objects have lots of properties which aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with that. Because there is no one right way of doing this there are various options explained below.

The VFS layer also implements a directory cache — this caches info about files and directories (but **not** the data) in memory. 🧠

### 🌸 VFS Directory Cache 🌸

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately or invalidate the cache.


However, changes made directly on the cloud storage by the web interface or a different copy of rclone will only be picked up once the directory cache expires, **if** the backend configured does not support polling for changes. If the backend supports polling, changes will be picked up within the polling interval. ⏰

You can send a `SIGHUP` signal to rclone for it to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


### 💖 VFS File Buffering 💖

The `--buffer-size` flag determines the amount of memory that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared.

This flag is an **upper limit** for the used memory per open file. The buffer will only use memory for data that is downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used.

The maximum memory used by rclone for buffering can be up to `--buffer-size` * open files.

### 🦋 VFS File Caching 🦋

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled at the cost of some compatibility. 😬

For example, you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details.

Note that the VFS cache is **separate** from the cache backend, and you may find that you need one or the other or both. 👀


If run with `-vv` rclone will print the location of the file cache. The files are stored in the user cache file area, which is OS dependent but can be controlled with `--cache-dir` or setting the appropriate environment variable. 📁

The cache has 4 different modes, selected by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. 💾

Note that files are written back to the remote only when they are closed *and* if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. 🔥

If you're rocking `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, heads up bestie: the cache can absolutely blow past those quotas, and there are two reasons why. One, it's only checked every `--vfs-cache-poll-interval`. Two, open files literally cannot be evicted from the cache, no matter how hard you beg. When those limits get exceeded, rclone starts evicting the least accessed files first — it goes for whatever hasn't been touched for the longest. This flushing strategy is efficient and it means the actually-relevant files tend to stay cached. 💅

Then there's `--vfs-cache-max-age`, which evicts files once that much time has passed since they were last accessed. Default is 1 hour, so after an hour of nobody touching a file, it's out. Touch a cached file and the timer resets to 0, and it waits another full hour before getting evicted. Write the time in standard notation: `s`, `m`, `h`, `d`, `w`. ⏰

> ⚠️ Do **not** run two copies of rclone sharing the same VFS cache with the same or overlapping remotes if you're using `--vfs-cache-mode > off`. That can genuinely cause **data corruption**, no exaggeration. Workaround: give each rclone its own cache hierarchy via `--cache-dir`. If your remotes don't overlap, you're totally fine, no worries. 🫶

---

## ✨ VFS Cache Modes ✨

### `--vfs-cache-mode off` 🚫

The default, and the no-frills option: the cache reads straight from the remote and writes straight to the remote, zero disk caching involved.

Which means some operations just… aren't happening:

- Files can't be opened for **both** read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried 😭

### `--vfs-cache-mode minimal` 🍓

Basically "off" but with a glow-up: files opened for read AND write get buffered to disk. So write-opened files are way more compatible, and you burn the minimum amount of disk space.

Still not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

### `--vfs-cache-mode writes` ✍️

Here, read-only files still come straight off the remote, but write-only and read/write files get buffered to disk first.

This mode should support all normal file system operations. Periodt.

If an upload fails, it gets retried at exponentially increasing intervals, up to 1 minute. 🔁

### `--vfs-cache-mode full` 👑

Everything — all reads *and* all writes — gets buffered to and from disk. Even data read from the remote is buffered to disk too.

In this mode the files in the cache are **sparse files**, and rclone keeps track of which bits it's actually downloaded.

So if an app only reads the beginnings of files, rclone only buffers the start of each file. Those files *look* full-size in the cache, but they're sparse files containing only the data that's been downloaded.

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file, rclone reads `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` part is buffered in memory, while the `--vfs-read-ahead` part is buffered on disk.

When you're using this mode, it's recommended you don't set `--buffer-size` too large, and set `--vfs-read-ahead` large if you need it.

> 🔥 **IMPORTANT**: not all file systems support sparse files. FAT/exFAT in particular do **not**. Rclone will perform *very badly* if the cache directory lives on a filesystem without sparse file support, and it'll log an `ERROR` message if it detects one.

---

## 🌈 Fingerprinting 🌈

Various parts of the VFS use fingerprinting to figure out whether a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

…where available on an object, iykyk.

On some backends, some of these attributes are *slow* to read — they cost an extra API call per object, or extra work per object.

For example, hash is slow with the `local` and `sftp` backends because they have to read the entire file and hash it. And modtime is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag, rclone won't include those slow operations in the fingerprint. That makes the fingerprinting less accurate but **much** faster, and it'll improve the opening time of cached files. 🏎️

If you're running a vfs cache over `local`, `s3` or `swift` backends, using this flag is recommended.

> Note: if you change the value of this flag, the fingerprints of the files in the cache may be invalidated, and those files will need to be downloaded again. 🫠

---

## 🧚 VFS Chunked Reading 🧚

When rclone reads files from a remote, it reads them in chunks. Meaning: instead of requesting the whole file, rclone requests the specified chunk. This can reduce your download quota on some remotes by only requesting the chunks that actually get read — at the cost of more requests overall.

These flags control the chunking:


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter.

### `--vfs-read-chunk-streams == 0`

Rclone starts by reading a chunk of size `--vfs-read-chunk-size`, then **doubles** the size for each read. When `--vfs-read-chunk-size-limit` is specified and greater than `--vfs-read-chunk-size`, the chunk size for each open file only keeps doubling until it hits that value. If the value is "off" — which is the default — the limit is disabled and the chunk size will grow indefinitely.

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0`, these parts get downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, you'd get `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on. 📈

Setting `--vfs-read-chunk-size` to `0` or `"off"` disables chunked reading.

The chunks will not be buffered in memory.

### `--vfs-read-chunk-streams > 0`

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` **concurrently**. Each read stays at a constant size.

This improves performance massively on high latency links, or very high bandwidth links to high performance object stores. 🚀

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams`, since these depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3), a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3, the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

---

## ⭐ VFS Performance ⭐

These flags enable/disable VFS features for performance or other reasons. See also the chunked reading feature above.

In particular, S3 and Swift benefit hugely from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect), because every single read of the modification time costs a transaction. 💸


Sometimes rclone gets reads or writes delivered out of order. Rather than seeking, rclone will wait a short time for the in-sequence read or write to show up. These flags only kick in when you're *not* using an on-disk cache file.

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When you're using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache. (The related global flag `--checkers` has **no effect** on the VFS.)

--transfers int Number of file transfers to run in parallel (default 4)


---

## 💜 Symlinks 💜

By default the VFS does **not** support symlinks. But you can turn it on with either of these flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


Since most cloud storage systems don't support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file that appears as a symlink `link-to-file.txt` gets stored on cloud storage as `link-to-file.txt.rclonelink`, and its contents are the path to the symlink destination. 🪄

Note that `--links` enables symlink translation **globally** in rclone — that includes any backend which supports the concept (say, the local backend). `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with the one used by the local backend with the `--local-links` flag.

The `--vfs-links` flag was designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet. 🙈

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example, given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but **not** `linked-dir/file.txt`. That's not a problem for the tested commands, but it may be for other commands.

> Note: there's an outstanding issue with symlink support, issue #8245, involving duplicate files being created when symlinks are moved into directories where there's a file of the same name (or vice versa). 💀

---

## 🦋 VFS Case Sensitivity 🦋

Linux file systems are case-sensitive: two files can differ only by case, and the exact case must be used when opening a file.

<pink>okay so</pink> bestie, let's talk about <purple>cases</purple>, and no I don't mean the court kind 💅

File systems in modern Windows are **case-insensitive but case-preserving** — which like, sounds contradictory but it totally isn't: you can open an existing file using <cyan>any</cyan> case you want, but the exact case that was used to create the file gets preserved and stays available for programs to query. The one thing you *can't* do is have two files sitting in the same directory that differ only by case. Not allowed. Blocked. 🚫

Usually file systems on macOS are case-insensitive too. You *can* make macOS file systems case-sensitive but that's not the default, so don't act surprised. 🙈

The `--vfs-case-insensitive` VFS flag is the queen that controls how rclone handles these two cases 👑 If its value is `false`, rclone passes file names to the remote **as-is** — no edits, no notes. If the flag is `true` (or it shows up on the command line with no value at all, in which case it's just vibe-checked as true), rclone may perform a **"fixup"** as explained below. ✨

So here's the fixup tea ☕ The user may specify a file name to open/delete/rename/etc with a case different than what's stored on the remote. If an argument refers to an existing file with *exactly* the same name, then the case of the existing file on the disk is what gets used. But if a file name with exactly the same name isn't found, and a name differing only by case *does* exist, rclone will transparently fixup the name. This fixup happens **only when an existing file is requested** — new files don't get this treatment. Case sensitivity of file names created anew by rclone is controlled by the underlying remote, periodt.

Note that case sensitivity of the operating system running rclone (the **target**) may differ from case sensitivity of a file system presented by rclone (the **source**). The flag controls whether "fixup" is performed to satisfy the target. 🎯

If the flag isn't provided on the command line, then its default value depends on the operating system where rclone runs: `true` on Windows and macOS, `false` otherwise. And if the flag *is* provided but without a value, then it's `true`.

The `--no-unicode-normalization` flag controls whether a similar "fixup" is performed for filenames that differ but are **canonically equivalent** with respect to unicode. Unicode normalization can be particularly helpful for users of macOS, which prefers form **NFD** instead of the **NFC** used by most other platforms. It is therefore **highly recommended** to keep the default of `false` on macOS, to avoid encoding compatibility issues. Like, fr fr, just leave it alone 🫶

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag allows hiding these duplicates. But bestie, this comes with a **performance tradeoff** — rclone will have to scan the *entire* directory for duplicates when listing a directory. For this reason, it's recommended to leave this disabled if not needed. 😮‍💨 However, macOS users may wish to consider using it, because otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an <red>odd situation</red> will occur: both versions of the file will be visible in the mount, and both will appear to be editable, however, editing either version will actually result in only the NFD version getting edited under the hood. `--vfs-block-norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`. 💀

---

### 💾 VFS Disk Options 💾

This flag lets you **manually set** the statistics about the filing system. It can be useful when those statistics cannot be read correctly automatically. Sometimes the numbers just don't wanna cooperate, y'know? 🎀

- **`--vfs-disk-space-total-size`** — Manually set the total disk space size (example: `256G`, default: `-1`)

---

### 📊 Alternate report of used bytes 📊

Some backends, most notably **S3**, do not report the amount of bytes used. Rude of them, honestly. 😤 If you need this information to be available when running `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself.

> <red>WARNING.</red> Contrary to `rclone size`, this flag **ignores filters** so that the result is accurate. However, this is very inefficient and may cost lots of API calls resulting in **extra charges**. 💸 Use it as a last resort and only with caching.

rclone nfsmount remote:path /path/to/mountpoint [flags]


## ✨ Options ✨

okay so these are the knobs for `nfsmount`, and there are... a LOT. buckle up bestie 🎀

- **`--addr string`** — <cyan>IPaddress:Port</cyan> or `:Port` to bind the server to 💅
- **`--allow-non-empty`** — let it mount over a directory that already has stuff in it (not supported on Windows) 🙈
- **`--allow-other`** — let other users get in on this (not supported on Windows)
- **`--allow-root`** — let the root user in too (not supported on Windows)
- **`--async-read`** — use asynchronous reads (not supported on Windows) (default `true`)
- **`--attr-timeout Duration`** — how long file/directory attributes stay cached (default `1s`) ⏳
- **`--daemon`** — run the mount in the background and let the parent process dip (because background output is suppressed, use `--log-file` with `--log-format=pid,...` if you wanna watch it) (not supported on Windows) 👻
- **`--daemon-timeout Duration`** — the time limit for rclone to respond to the kernel (not supported on Windows) (default `0s`)
- **`--daemon-wait Duration`** — how long to wait for the daemon to give you a ready mount (that's a maximum on Linux, but a constant sleep time on OSX/BSD) (not supported on Windows) (default `1m0s`) ⏰
- **`--debug-fuse`** — debug the FUSE internals — heads up, this needs `-v` 🔍
- **`--default-permissions`** — makes the kernel enforce access control based on the file mode (not supported on Windows)
- **`--devname string`** — set the device name — the default is `remote:path`
- **`--dir-cache-time Duration`** — how long to cache directory entries for (default `5m0s`)
- **`--dir-perms FileMode`** — directory permissions (default `777`)
- **`--direct-io`** — use Direct IO, which disables caching of data 🚫
- **`--file-perms FileMode`** — file permissions (default `666`)
- **`--fuse-flag stringArray`** — flags or arguments passed straight through to libfuse/WinFsp (repeat it if you need to)
- **`--gid uint32`** — override the gid field the filesystem set (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for `nfsmount` 🫶
- **`--link-perms FileMode`** — link permissions (default `666`)
- **`--max-read-ahead SizeSuffix`** — how many bytes can be prefetched for sequential reads (not supported on Windows) (default `128Ki`)
- **`--mount-case-insensitive Tristate`** — tell the OS whether the mount is case insensitive (`true`) or sensitive (`false`), regardless of what the backend says (`auto`) (default `unset`)
- **`--network-mode`** — mount it as a remote network drive instead of a fixed disk drive (Windows only)
- **`--nfs-cache-dir string`** — the directory the NFS handle cache will use, if you set it
- **`--nfs-cache-handle-limit int`** — the max number of file handles cached at the same time (min `5`) (default `1000000`) 😳
- **`--nfs-cache-type memory|disk|symlink`** — the type of NFS handle cache to use (default `memory`)
- **`--no-checksum`** — don't compare checksums on up/download
- **`--no-modtime`** — don't read/write the modification time (this can speed things up, fr fr) ⚡
- **`--no-seek`** — don't allow seeking in files
- **`--noappledouble`** — ignore Apple Double (`._`) and `.DS_Store` files (OSX only) (default `true`) 🍎
- **`--noapplexattr`** — ignore every `"com.apple.*"` extended attribute (OSX only)
- **`-o`, `--option stringArray`** — option for libfuse/WinFsp (repeat it if you need to)
- **`--poll-interval Duration`** — how long to wait between polling for changes; it has to be smaller than `dir-cache-time`, and only on supported remotes (set `0` to disable it) (default `1m0s`)
- **`--read-only`** — only allow read-only access 🔒
- **`--sudo`** — use `sudo` to run the mount/umount commands as root.
- **`--uid uint32`** — override the uid field the filesystem set (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — override the permission bits the filesystem set (not supported on Windows) (default `002`)
- **`--vfs-block-norm-dupes`** — if duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (heads up: this may cost you performance) 💀
- **`--vfs-cache-max-age Duration`** — max time since last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — max total size of objects in the cache (default `off`)
- **`--vfs-cache-min-free-space SizeSuffix`** — the target minimum free space on the disk that holds the cache (default `off`)
- **`--vfs-cache-mode CacheMode`** — cache mode `off|minimal|writes|full` (default `off`)
- **`--vfs-cache-poll-interval Duration`** — interval to poll the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — if a file name isn't found, go find a case insensitive match 🔍
- **`--vfs-disk-space-total-size SizeSuffix`** — specify the total space of the disk (default `off`)
- **`--vfs-fast-fingerprint`** — use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — translate symlinks to/from regular files with a `.rclonelink` extension for the VFS 🔗
- **`--vfs-read-ahead SizeSuffix`** — extra read ahead over `--buffer-size` when using `cache-mode full`
- **`--vfs-read-chunk-size SizeSuffix`** — read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — if it's greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read until you hit the limit (`'off'` means unlimited) (default `off`)
- **`--vfs-read-chunk-streams int`** — the number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — how long to wait for an in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — refreshes the directory cache recursively in the background on start 🔄
- **`--vfs-used-is-size rclone size`** — use the `rclone size` algorithm for Used size
- **`--vfs-write-back Duration`** — how long to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — how long to wait for an in-sequence write before giving an error (default `1s`)
- **`--volname string`** — set the volume name (Windows and OSX only)
- **`--write-back-cache`** — makes the kernel buffer writes before sending them to rclone (without this, writethrough caching is used) (not supported on Windows)

Options shared with other commands are described next. See the global flags page for global options not listed here.

### 🌈 Filter Options 🌈

Flags for filtering directory listings, bestie — this is how you tell rclone what to actually look at 👀

- **`--delete-excluded`** — delete files on dest that were excluded from sync
- **`--exclude stringArray`** — exclude files matching the pattern
- **`--exclude-from stringArray`** — read file exclude patterns from a file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — exclude directories if the filename is present
- **`--files-from stringArray`** — read the list of source-file names from a file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — read the list of source-file names from a file without any processing of the lines (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule
- **`--filter-from stringArray`** — read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — ignore case in filters (case insensitive) 🙃
- **`--include stringArray`** — include files matching the pattern
- **`--include-from stringArray`** — read file include patterns from a file (use `-` to read from stdin)
- **`--max-age Duration`** — only transfer files younger than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth int`** — if set, limits the recursion depth to this (default `-1`)
- **`--max-size SizeSuffix`** — only transfer files smaller than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — exclude metadatas matching the pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — include metadatas matching the pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` to read from stdin)
- **`--min-age Duration`** — only transfer files older than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — only transfer files bigger than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)

### 🫶 See Also 🫶

- `rclone` — Show help for rclone commands, flags and backends.

---

# 🔐 rclone obscure 🔐

Obscure password for use in the rclone config file.

## ✨ Synopsis ✨

so in the rclone config file, human-readable passwords get obscured. the way that happens is rclone encrypts them and writes them out in base64. <red>this is NOT a secure way of encrypting these passwords</red>, because rclone can decrypt them right back — the whole point is to prevent "eyedropping", aka someone just *seeing* a password in the rclone config file by accident. periodt.

Lots of equally important things (like access tokens) are **not** obscured in the config file. but ngl, it is very hard to shoulder surf a 64 character hex token. 💅

This command can also take a password through <kbd>STDIN</kbd> instead of an argument, if you pass a hyphen as the argument. It'll use the first line of <kbd>STDIN</kbd> as the password, not including the trailing newline.

echo "secretpassword" | rclone obscure -


If there's no data on <kbd>STDIN</kbd> to read, `rclone obscure` will default to obfuscating the hyphen itself. 🙈

If you want to encrypt the config file then please use config file encryption — see `rclone config` for more info. 🔥

rclone obscure password [flags]


## ✨ Options ✨

- **`-h`, `--help`** — help for `obscure` 🎀

See the global flags page for global options not listed here.

## 🫶 See Also 🫶

- `rclone` — Show help for rclone commands, flags and backends.

# <pink>rclone rc</pink> 💅

okay bestie, this one is literally "run a command against a running rclone." It's the remote-control hotline.

## Synopsis

This runs a command against a running rclone. Use the `--url` flag to specify an non default URL to connect on. This can be either a `":port"` which is taken to mean `"http://localhost:port"` or a `"host:port"` which is taken to mean `"http://host:port"`.

A username and password can be passed in with `--user` and `--pass`.

Note that `--rc-addr`, `--rc-user`, `--rc-pass` will be read also for `--url`, `--user`, `--pass`.

The `--unix-socket` flag can be used to connect over a unix socket like this:

start server on /tmp/my.socket

rclone rcd --rc-addr unix:///tmp/my.socket

Connect to it

rclone rc --unix-socket /tmp/my.socket core/stats


Arguments should be passed in as `parameter=value`.

The result will be returned as a JSON object by default.

The `--json` parameter can be used to pass in a JSON blob as an input instead of `key=value` arguments. This is the only way of passing in more complicated values.

The `-o`/`--opt` option can be used to set a key `"opt"` with key, value options in the form `-o key=value` or `-o key`. It can be repeated as many times as required. This is useful for rc commands which take the `"opt"` parameter which by convention is a dictionary of strings.

-o key=value -o key2


Will place this in the `"opt"` value

{"key":"value", "key2","")


The `-a`/`--arg` option can be used to set strings in the `"arg"` value. It can be repeated as many times as required. This is useful for rc commands which take the `"arg"` parameter which by convention is a list of strings.

-a value -a value2


Will place this in the `"arg"` value

["value", "value2"]


Use `--loopback` to connect to the rclone instance running `rclone rc`. This is very useful for testing commands without having to run an rclone rc server, e.g.:

rclone rc --loopback operations/about fs=/


Use `rclone rc` to see a list of all possible commands.

rclone rc commands parameter [flags]


## Options

- **`-a`, `--arg stringArray`** — Argument placed in the `"arg"` array
- **`-h`, `--help`** — help for `rc`
- **`--json string`** — Input JSON - use instead of key=value args
- **`--loopback`** — If set connect to this rclone instance not via HTTP
- **`--no-output`** — If set, don't output the JSON result
- **`-o`, `--opt stringArray`** — Option in the form `name=value` or `name` placed in the `"opt"` array
- **`--pass string`** — Password to use to connect to rclone remote control
- **`--unix-socket string`** — Path to a unix domain socket to dial to, instead of opening a TCP connection directly
- **`--url string`** — URL to connect to rclone remote control (default `"http://localhost:5572/"`)
- **`--user string`** — Username to use to rclone remote control

See the global flags page for global options not listed here.

## See Also

- `rclone` — Show help for rclone commands, flags and backends.

---

# <pink>rclone rcat</pink> 🐱

Copies standard input to file on remote.

## Synopsis

Reads from standard input (`stdin`) and copies it to a single remote file.

echo "hello world" | rclone rcat remote:path/to/file ffmpeg - | rclone rcat remote:path/to/file


If the remote file already exists, it will be overwritten.

`rcat` will try to upload small files in a single request, which is usually more efficient than the streaming/chunked upload endpoints, which use multiple requests. Exact behaviour depends on the remote. What is considered a small file may be set through `--streaming-upload-cutoff`. Uploading only starts after the cutoff is reached or if the file ends before that. The data must fit into RAM. The cutoff needs to be small enough to adhere the limits of your remote, please see there. Generally speaking, setting this cutoff too high will decrease your performance.

Use the `--size` flag to preallocate the file in advance at the remote end and actually stream it, even if remote backend doesn't support streaming.

`--size` should be the exact size of the input stream in bytes. If the size of the stream is different in length to the `--size` passed in then the transfer will likely fail.

Note that the upload cannot be retried because the data is not stored. If the backend supports multipart uploading then individual chunks can be retried. If you need to transfer a lot of data, you may be better off caching it locally and then `rclone move` it to the destination which can use retries.

rclone rcat remote:path [flags]


## Options

- **`-h`, `--help`** — help for `rcat`
- **`--size int`** — File size hint to preallocate (default `-1`)

Options shared with other commands are described next. See the global flags page for global options not listed here.

## Important Options

Important flags useful for most commands

- **`-n`, `--dry-run`** — Do a trial run with no permanent changes
- **`-i`, `--interactive`** — Enable interactive mode
- **`-v`, `--verbose count`** — Print lots more stuff (repeat for more)

## See Also

- `rclone` — Show help for rclone commands, flags and backends.

# ✨ rclone rcd ✨

<pink>okay BESTIE</pink> so `rclone rcd` runs rclone so it does <hotpink>nothing</hotpink> except listen for remote control commands. That's the whole job. That's the assignment. And it ate. 💅

---

## 🌸 Synopsis 🌸

This runs rclone so that it <purple>only</purple> listens to remote control commands.

It's useful when you're controlling rclone via the <cyan>rc API</cyan>. iykyk.

If you pass in a path to a directory, rclone will serve that directory for <green>GET</green> requests on the URL passed in. It will *also* open the URL in the browser when rclone is run. (Not me opening a browser unprompted 😭 iconic behaviour fr.)

See the <lavender>rc documentation</lavender> for more info on the rc flags.

rclone rcd <path to files to serve>* [flags]


---

## 🎀 Server options 🎀

Use `--rc-addr` to specify which IP address and port the server should listen on, eg `--rc-addr 1.2.3.4:8000` or `--rc-addr :8080` to listen to all IPs. By default it <yellow>only</yellow> listens on `localhost`. You can use port `:0` to let the OS choose an available port. (let the OS decide, she's the main character now 💅)

If you set `--rc-addr` to listen on a public or LAN accessible IP address then using <hotpink>Authentication</hotpink> is advised — see the next section for info. Seriously bestie, lock the door. 🫶

You can use a unix socket by setting the url to `unix:///path/to/socket` or just by using an absolute path name.

`--rc-addr` may be repeated to listen on multiple IPs/ports/sockets. <mint>Socket activation</mint>, described further below, can also be used to accomplish the same.

`--rc-server-read-timeout` and `--rc-server-write-timeout` can be used to control the timeouts on the server. <purple>Note that this is the total time for a transfer.</purple>

`--rc-max-header-bytes` controls the maximum number of bytes the server will accept in the HTTP header.

`--rc-baseurl` controls the URL prefix that rclone serves from. By default rclone will serve from the root. If you used `--rc-baseurl "/rclone"` then rclone would serve from a URL starting with `/rclone/`. This is useful if you wish to proxy rclone serve. Rclone automatically inserts leading and trailing `/` on `--rc-baseurl`, so `--rc-baseurl "rclone"`, `--rc-baseurl "/rclone"` and `--rc-baseurl "/rclone/"` are all treated identically. <pink>Slash-agnostic queen.</pink> ✨

---

## 🔐 TLS (SSL) 🔐

By default this will serve over <mint>http</mint>. If you want you can serve over <mint>https</mint>. You will need to supply the `--rc-cert` and `--rc-key` flags. If you wish to do client side certificate validation then you will need to supply `--rc-client-ca` also.

`--rc-cert` must be set to the path of a file containing either a PEM encoded certificate, or a concatenation of that with the CA certificate. `--rc-key` must be set to the path of a file with the PEM encoded private key. If setting `--rc-client-ca`, it should be set to the path of a file with PEM encoded client certificate authority certificates.

`--rc-min-tls-version` is minimum TLS version that is acceptable. Valid values are `tls1.0`, `tls1.1`, `tls1.2` and `tls1.3` (default `tls1.0`). (yes bestie, `tls1.0` is the default and yes that's giving 2011, but that's what it says 👑)

---

## 🦋 Socket activation 🦋

Instead of the listening addresses specified above, rclone will listen to <hotpink>all FDs passed by the service manager</hotpink>, if any (and <red>ignore</red> any arguments passed by `--rc-addr`).

This allows rclone to be a socket-activated service. It can be configured with `.socket` and `.service` unit files as described in `https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html`

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command:

systemd-socket-activate -l 8000 -- rclone serve


This will socket-activate rclone on the <cyan>first connection to port 8000 over TCP</cyan>.

### 💜 Template 💜

`--rc-template` allows a user to specify a custom markup template for HTTP and WebDAV serve functions. The server exports the following markup to be used within the template to server pages:

- `.Name` — The full path of a file/directory.
- `.Title` — Directory listing of `.Name`
- `.Sort` — The current sort used. This is changeable via `?sort=` parameter
  - Sort Options: `namedirfirst,name,size,time` (default `namedirfirst`)
- `.Order` — The current ordering used. This is changeable via `?order=` parameter
  - Order Options: `asc,desc` (default `asc`)
- `.Query` — Currently unused.
- `.Breadcrumb` — Allows for creating a relative navigation
  - `.Link` — The relative to the root link of the Text.
  - `.Text` — The Name of the directory.
- `.Entries` — Information about a specific file/directory.
  - `.URL` — The `url` of an entry.
  - `.Leaf` — Currently same as `URL` but intended to be `just` the name.
  - `.IsDir` — Boolean for if an entry is a directory or not.
  - `.Size` — Size in Bytes of the entry.
  - `.ModTime` — The UTC timestamp of an entry.

The server also makes the following functions available so that they can be used within the template. These functions help extend the options for dynamic rendering of HTML. They can be used to render HTML based on specific conditions.

- `afterEpoch` — Returns the time since the epoch for the given time.
- `contains` — Checks whether a given substring is present or not in a given string.
- `hasPrefix` — Checks whether the given string begins with the specified prefix.
- `hasSuffix` — Checks whether the given string end with the specified suffix.

---

## 🔑 Authentication 🔑

By default this will serve files <red>without needing a login</red>. (bestie. bestie please. 🙈)

You can either use an <cyan>htpasswd</cyan> file which can take lots of users, or set a single username and password with the `--rc-user` and `--rc-pass` flags.

If no static users are configured by either of the above methods, and client certificates are required by the `--client-ca` flag passed to the server, the client certificate <purple>common name</purple> will be considered as the username.

Use `--rc-htpasswd /path/to/htpasswd` to provide an htpasswd file. This is in standard apache format and supports <mint>MD5</mint>, <mint>SHA1</mint> and <mint>BCrypt</mint> for basic authentication. <yellow>Bcrypt is recommended.</yellow>

To create an htpasswd file:

touch htpasswd htpasswd -B htpasswd user htpasswd -B htpasswd anotherUser


The password file can be updated while rclone is running. ✨ (live edits, she's flexible)

Use `--rc-realm` to set the authentication realm.

Use `--rc-salt` to change the password hashing salt from the default.

---

## ⭐ Options ⭐

- **`-h`, `--help`** — help for rcd

Options shared with other commands are described next. See the global flags page for global options not listed here.

### 🌈 RC Options 🌈

Flags to control the Remote Control API 💅

- **`--rc`** — Enable the remote control server
- **`--rc-addr`** *stringArray* — IPaddress:Port or :Port to bind server to (default `localhost:5572`)
- **`--rc-allow-origin`** *string* — Origin which cross-domain request (CORS) can be executed from
- **`--rc-baseurl`** *string* — Prefix for URLs - leave blank for root
- **`--rc-cert`** *string* — TLS PEM key (concatenation of certificate and CA certificate)
- **`--rc-client-ca`** *string* — Client certificate authority to verify clients with
- **`--rc-enable-metrics`** — Enable the Prometheus metrics path at the remote control server
- **`--rc-files`** *string* — Path to local files to serve on the HTTP server
- **`--rc-htpasswd`** *string* — A htpasswd file - if not provided no authentication is done
- **`--rc-job-expire-duration`** *Duration* — Expire finished async jobs older than this value (default `1m0s`)
- **`--rc-job-expire-interval`** *Duration* — Interval to check for expired async jobs (default `10s`)
- **`--rc-key`** *string* — TLS PEM Private key
- **`--rc-max-header-bytes`** *int* — Maximum size of request header (default `4096`)
- **`--rc-min-tls-version`** *string* — Minimum TLS version that is acceptable (default `"tls1.0"`)
- **`--rc-no-auth`** — Don't require auth for certain methods
- **`--rc-pass`** *string* — Password for authentication
- **`--rc-realm`** *string* — Realm for authentication
- **`--rc-salt`** *string* — Password hashing salt (default `"dlPL2MqE"`)
- **`--rc-serve`** — Enable the serving of remote objects
- **`--rc-serve-no-modtime`** — Don't read the modification time (can speed things up)
- **`--rc-server-read-timeout`** *Duration* — Timeout for server reading data (default `1h0m0s`)
- **`--rc-server-write-timeout`** *Duration* — Timeout for server writing data (default `1h0m0s`)
- **`--rc-template`** *string* — User-specified template
- **`--rc-user`** *string* — User name for authentication
- **`--rc-web-fetch-url`** *string* — URL to fetch the releases for webgui (default `"https://api.github.com/repos/rclone/rclone-webui-react/releases/latest"`)
- **`--rc-web-gui`** — Launch WebGUI on localhost
- **`--rc-web-gui-force-update`** — Force update to latest version of web gui
- **`--rc-web-gui-no-open-browser`** — Don't open the browser automatically
- **`--rc-web-gui-update`** — Check and update to latest version of web gui

---

## 👀 See Also 👀

- `rclone` — Show help for rclone commands, flags and backends.

<pink>bestie</pink> we're doing <hotpink>`rclone rmdirs`</hotpink> now and it's genuinely the "girl who cleans up after the party" of commands 💅

# 🌸 rclone rmdirs 🌸

Remove empty directories under the path. That's it. That's the whole job. She's a <purple>specialist</purple> 🎀

## ✨ Synopsis ✨

okay so this <hotpink>recursively</hotpink> removes any empty directories (including directories that only contain empty directories, like a little nesting-doll situation 🪆) that it finds under the path. The root path itself will <bold>also</bold> be removed if it is empty — <red>unless</red> you supply the `--leave-root` flag. Protect that root, queen 👑

Use the command `rmdir` to delete <italic>just</italic> the empty directory given by path, no recursion, no extras. Different girl, different vibe.

This is so useful for tidying up remotes that rclone has left a lot of empty directories in 🌪️ For example the `delete` command will delete files but leave the directory structure (unless you used it with option `--rmdirs`). So you get the files gone but the skeleton still standing there like 😭

This will delete `--checkers` directories <cyan>concurrently</cyan> so if you have thousands of empty directories, consider increasing this number. Parallelism, periodt ⚡

To delete a path and <bold>any objects in it</bold>, use the `purge` command instead. rmdirs is the gentle one, purge is the whole thing gone 🫣

rclone rmdirs remote:path [flags]


## ✨ Options ✨

- **`-h`, `--help`** — help for rmdirs, obviously 💖
- **`--leave-root`** — Do not remove root directory if empty. Keeps the mothership alive 🛸

Options shared with other commands are described next. See the global flags page for global options not listed here.

## 💅 Important Options 💅

Important flags useful for most commands — the little essentials, iykyk

- **`-n`, `--dry-run`** — Do a trial run with no permanent changes. Practice mode, no consequences 🙈
- **`-i`, `--interactive`** — Enable interactive mode. She asks before she acts 🥺
- **`-v`, `--verbose count`** — Print lots more stuff (repeat for more). Stack it, `-vv`, `-vvv`, go off 🔥

## 🦋 See Also 🦋

- `rclone` — Show help for rclone commands, flags and backends.

---

# 👑 rclone selfupdate 👑

Update the rclone binary. Glow up on demand ✨

## ✨ Synopsis ✨

This command downloads the latest release of rclone and replaces the currently running binary. The download is verified with a hashsum and cryptographically signed signature; see the release signing docs for details 🔐 No cap, it's secure.

If used without flags (or with the implied `--stable` flag), this command will install the latest <green>stable</green> release. However, some issues may be fixed (or features added) only in the latest <yellow>beta</yellow> release. In such cases you should run the command with the `--beta` flag, i.e. `rclone selfupdate --beta`. You can check in advance what version would be installed by adding the `--check` flag, then repeat the command without it when you are satisfied 👀 peek before you commit.

Sometimes the rclone team may recommend you a concrete beta or stable rclone release to troubleshoot your issue or add a bleeding edge feature. The `--version VER` flag, if given, will update to the concrete version instead of the latest one. If you omit micro version from *VER* (for example `1.53`), the latest matching micro version will be used. Bestie picky about versions? Say less 🎯

Upon successful update rclone will print a message that contains a previous version number. You will need it if you later decide to revert your update for some reason. Then you'll have to note the previous version and run the following command: `rclone selfupdate [--beta] OLDVER`. If the old version contains only dots and digits (for example `v1.54.0`) then it's a stable release so you won't need the `--beta` flag. Beta releases have an additional information similar to `v1.54.0-beta.5111.06f1c0c61`. (if you are a developer and use a locally built rclone, the version number will end with `-DEV`, you will have to rebuild it as it obviously can't be distributed).

If you previously installed rclone via a package manager, the package may include local documentation or configure services. You may wish to update with the flag `--package deb` or `--package rpm` (whichever is correct for your OS) to update these too. This command with the default `--package zip` will update only the rclone executable so the local manual may become inaccurate after it 😬 keep your docs in sync, bestie.

The `rclone mount` command may or may not support extended FUSE options depending on the build and OS. `selfupdate` will refuse to update if the capability would be discarded. She's not about to downgrade your features, no ma'am 🚫

> Note: Windows forbids deletion of a currently running executable so this command will rename the old executable to `rclone.old.exe` upon success. Windows being Windows 💀

Please note that this command was not available before rclone version <hotpink>1.55</hotpink>. If it fails for you with the message `unknown command "selfupdate"` then you will need to update manually following the install instructions located at `https://rclone.org/install/` 📝

rclone selfupdate [flags]


## ✨ Options ✨

- **`--beta`** — Install beta release. Living on the edge 🌈
- **`--check`** — Check for latest release, do not download. Window shopping ✨
- **`-h`, `--help`** — help for selfupdate 🎀
- **`--output string`** — Save the downloaded binary at a given path (default: replace running binary)
- **`--package string`** — Package format: `zip|deb|rpm` (default: `zip`)
- **`--stable`** — Install stable release (this is the default). The safe pick 💖
- **`--version string`** — Install the given rclone version (default: latest)

See the global flags page for global options not listed here.

## 🦋 See Also 🦋

- `rclone` — Show help for rclone commands, flags and backends.

---

# 🌈 rclone serve 🌈

Serve a remote over a protocol. She's a hostess with the mostest 🫶

## ✨ Synopsis ✨

Serve a remote over a given protocol. Requires the use of a subcommand to specify the protocol, e.g.

rclone serve http remote:


Each subcommand has its own options which you can see in their help. So many little menus, pick your fav 💅

rclone serve <protocol> [opts] <remote> [flags]


## ✨ Options ✨

- **`-h`, `--help`** — help for serve ✨

See the global flags page for global options not listed here.

## 🦋 See Also 🦋

- `rclone` — Show help for rclone commands, flags and backends.
- `rclone serve dlna` — Serve *remote:path* over DLNA
- `rclone serve docker` — Serve any remote on docker's volume plugin API.
- `rclone serve ftp` — Serve *remote:path* over FTP.
- `rclone serve http` — Serve the remote over HTTP.
- `rclone serve nfs` — Serve the remote as an NFS mount
- `rclone serve restic` — Serve the remote for restic's REST API.
- `rclone serve s3` — Serve *remote:path* over s3.
- `rclone serve sftp` — Serve the remote over SFTP.
- `rclone serve webdav` — Serve *remote:path* over WebDAV.

---

# 🎀 rclone serve dlna 🎀

Serve *remote:path* over DLNA

## ✨ Synopsis ✨

Run a DLNA media server for media stored in an rclone remote. Many devices, such as the <purple>Xbox</purple> and <cyan>PlayStation</cyan>, can automatically discover this server in the LAN and play audio/video from it. <green>VLC</green> is also supported 🎬 Service discovery uses UDP multicast packets (SSDP) and will thus <bold>only work on LANs</bold>. Local girls only, she doesn't do long distance 🏠

Rclone will list all files present in the remote, without filtering based on media formats or file extensions. Additionally, there is no media transcoding support. This means that some players might show files that they are not able to play back correctly 😭 she'll serve it, doesn't mean your TV can eat it.

Rclone will add external subtitle files (`.srt`) to videos if they have the same filename as the video file itself (except the extension), either in the same directory as the video, or in a "Subs" subdirectory. Subtitles matched, iconically 💬

## ✨ Server options ✨

Use `--addr` to specify which IP address and port the server should listen on, e.g. `--addr 1.2.3.4:8000` or `--addr :8080` to listen to all IPs.

Use `--name` to choose the friendly server name, which is by default "rclone (hostname)" 💖

Use `--log-trace` in conjunction with `-vv` to enable additional debug logging of all UPNP traffic. Detective mode 🔍

## 🌸 VFS - Virtual File System 🌸

This command uses the VFS layer. This adapts the cloud storage objects that rclone uses into something which looks much more like a disk filing system. Glow up, cloud objects ✨

Cloud storage objects have lots of properties which aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with that 😤 Because there is no one right way of doing this there are various options explained below.

The VFS layer also implements a directory cache — this caches info about files and directories (but not the data) in memory.

## 🌸 VFS Directory Cache 🌸

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately or invalidate the cache.


However, changes made directly on the cloud storage by the web interface or a different copy of rclone will only be picked up once the directory cache expires if the backend configured does not support polling for changes. If the backend supports polling, changes will be picked up within the polling interval ⏰ she's not psychic if your backend won't tell her.

You can send a <hotpink>SIGHUP</hotpink> signal to rclone for it to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


## 🌸 VFS File Buffering 🌸

The `--buffer-size` flag determines the amount of memory, that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared. No sharing, that's her data 🔒

This flag is a upper limit for the used memory per open file. The buffer will only use memory for data that is downloaded but not not yet read. If the buffer is empty, only a small amount of memory will be used.

The maximum memory used by rclone for buffering can be up to `--buffer-size * open files`. Math! Do the math bestie 🧮

## 🌸 VFS File Caching 🌸

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled at the cost of some compatibility.

For example you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details.

Note that the VFS cache is <bold>separate</bold> from the cache backend and you may find that you need one or the other or both 👯‍♀️


and that's the section bestie, more coming in the next part 💖🦋

So yeah, if you run with `-vv` rclone will literally print out where the file cache is living. 💅 The files get stored in the user cache file area — which is OS dependent, rude — but you can control it with `--cache-dir` or by setting the appropriate environment variable.

The cache has **4** different modes, picked with `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes… at the cost of your disk space. It's giving ✨tradeoffs✨.

Okay important: files are written back to the remote **only when they are closed** and **if they haven't been accessed for `--vfs-write-back` seconds**. And if rclone gets quit or straight up dies with files that haven't been uploaded yet, don't panic — those will be uploaded next time rclone is run with the same flags. 🫶

If you're using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, bestie, note that the cache may go over these quotas, for two reasons:

- it's only checked every `--vfs-cache-poll-interval`, so it's lowkey just vibing in between checks
- open files **cannot** be evicted from the cache. Periodt.

When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the **least accessed** files from the cache first. It starts with the files that haven't been accessed for the longest. This cache flushing strategy is efficient and more relevant files are likely to remain cached. 👑

`--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of **1 hour** will start evicting files from cache that haven't been accessed for 1 hour. When a cached file is accessed, the 1 hour timer is reset to 0 and it will wait for 1 more hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> ⚠️ You should **not** run two copies of rclone using the same VFS cache with the same or overlapping remotes if using `--vfs-cache-mode` > off. This can potentially cause **data corruption** if you do. 💀 You can work around this by giving each rclone its own cache hierarchy with `--cache-dir`. You don't need to worry about this if the remotes in use don't overlap.

---

### 🧊 `--vfs-cache-mode off`

In this mode (**the default**), the cache will read directly from the remote and write directly to the remote, without caching anything on disk. Straight up no middleman.

This will mean some operations are **not** possible:

- Files can't be opened for both read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried 😭

### 🪶 `--vfs-cache-mode minimal`

This is very similar to "off" except that files opened for read AND write will be buffered to disk. So files opened for write are a lot more compatible, but it uses the **minimal** disk space. Little snack, not a whole meal.

These operations are not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

### ✍️ `--vfs-cache-mode writes`

In this mode, files opened for read only are still read directly from the remote — but write only and read/write files are buffered to disk first.

This mode should support all normal file system operations. 💯

If an upload fails, it will be retried at **exponentially increasing intervals up to 1 minute**.

### 🌈 `--vfs-cache-mode full`

In this mode, **all** reads and writes are buffered to and from disk. When data is read from the remote, this is buffered to disk as well.

In this mode the files in the cache will be **sparse files**, and rclone will keep track of which bits of the files it has downloaded. Not me keeping receipts on every byte 🙈

So if an application only reads the starts of each file, then rclone will only buffer the start of the file. These files will appear to be their full size in the cache, but they will be sparse files with only the data that has been downloaded present in them.

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file, rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered **in memory**, whereas the `--vfs-read-ahead` is buffered **on disk**.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> IMPORTANT: not all file systems support sparse files. In particular **FAT/exFAT do not**. 😭 Rclone will perform very badly if the cache directory is on a filesystem which doesn't support sparse files, and it will log an `ERROR` message if one is detected.

### 🔍 Fingerprinting

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

…where available on an object.

On some backends, some of these attributes are slow to read (they take an extra API call per object, or extra work per object).

For example `hash` is slow with the `local` and `sftp` backends, since they have to read the entire file and hash it. And `modtime` is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends, because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag, then rclone will **not** include the slow operations in the fingerprint. This makes the fingerprinting less accurate but **much faster**, and will improve the opening time of cached files. Speed > accuracy sometimes, it's giving main character energy 🔥

If you are running a vfs cache over `local`, `s3` or `swift` backends, then using this flag is recommended.

Note that if you change the value of this flag, the fingerprints of the files in the cache may be **invalidated** and the files will need to be downloaded again. 🫠

### 📦 VFS Chunked Reading

When rclone reads files from a remote, it reads them in **chunks**. So rather than requesting the whole entire file, rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read — at the cost of an increased number of requests.

These flags control the chunking:

- **`--vfs-read-chunk-size`** *SizeSuffix* — read the source objects in chunks (default `128M`)
- **`--vfs-read-chunk-size-limit`** *SizeSuffix* — max chunk doubling size (default `off`)
- **`--vfs-read-chunk-streams`** *int* — the number of parallel streams to read at once

The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter.

#### 🧮 `--vfs-read-chunk-streams == 0`

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then **double** the size for each read. When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is "off", which is the default, the limit is disabled and the chunk size will grow indefinitely.

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0` the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on.

Setting `--vfs-read-chunk-size` to `0` or `"off"` disables chunked reading.

The chunks will **not** be buffered in memory.

#### 🚀 `--vfs-read-chunk-streams > 0`

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` **concurrently**. The size for each read will stay constant.

This improves performance massively on high latency links or very high bandwidth links to high performance object stores. Ate, no crumbs. 💅

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams`, as these will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

### ⚡ VFS Performance

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature.

In particular **S3** and **Swift** benefit hugely from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect), as each read of the modification time takes a transaction. Ouch. 💸

- **`--no-checksum`** — don't compare checksums on up/download.
- **`--no-modtime`** — don't read/write the modification time (can speed things up).
- **`--no-seek`** — don't allow seeking in files.
- **`--read-only`** — only allow read-only access.

Sometimes rclone is delivered reads or writes **out of order**. Rather than seeking, rclone will wait a short time for the in-sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file.

- **`--vfs-read-wait`** *duration* — time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-write-wait`** *duration* — time to wait for in-sequence write before giving error (default `1s`)

When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has **no effect** on the VFS).

- **`--transfers`** *int* — number of file transfers to run in parallel (default `4`)

### 🔗 Symlinks

By default the VFS does **not** support symlinks. However this may be enabled with either of the following flags:

- **`--links`** — translate symlinks to/from regular files with a `.rclonelink` extension.
- **`--vfs-links`** — translate symlinks to/from regular files with a `.rclonelink` extension for the VFS

As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink`, and the contents would be the path to the symlink destination. Sneaky but iconic 🎀

Note that `--links` enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the `local` backend). `--vfs-links` just enables it for the **VFS layer**.

This scheme is compatible with that used by the `local` backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet. 🫣

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree

The VFS will resolve `linked-dir` correctly, but nope, not `linked-dir/file.txt`. 😭 It's not a problem for the tested commands but might be for other commands, so like… keep that in mind bestie.

Also heads up: there's an outstanding issue with symlink support — issue **#8245** — where duplicate files get created when symlinks are moved into directories where there's a file of the same name (or the other way around). So yeah, that's a thing. 💀

## 🌸 VFS Case Sensitivity 🌸

So Linux file systems are **case-sensitive**: two files can differ *only* by case, and you have to use the exact case when opening a file. No shortcuts. Periodt.

Modern Windows file systems are **case-insensitive but case-preserving**: like, existing files can be opened using any case (slay), but the exact case used to create the file is preserved and programs can query it. And no, you can't have two files in the same directory that differ only by case. Nope.

macOS file systems are usually case-insensitive. You *can* make them case-sensitive, but that's not the default, so don't come for me.

The **`--vfs-case-insensitive`** VFS flag controls how rclone handles these two situations. If its value is **`false`**, rclone passes file names to the remote as-is. If the flag is **`true`** (or shows up without a value on the command line), rclone may perform a "fixup" — more on that below. 💅

Okay so here's the tea: you might tell rclone to open/delete/rename/etc a file name with a different case than what's actually stored on the remote. If an argument refers to an existing file with the *exact* same name, then the case of the existing file on the disk wins. But if a file with exactly that name isn't found, and a name differing only by case *does* exist, rclone will transparently fixup the name. ✨ This fixup happens **only** when an existing file is requested. Case sensitivity of file names created fresh by rclone is controlled by the underlying remote.

Lowkey important: case sensitivity of the OS running rclone (the target) may differ from case sensitivity of the file system rclone is presenting (the source). The flag controls whether "fixup" gets performed to satisfy the target.

If the flag isn't provided on the command line, its default value depends on the OS where rclone runs: **`true`** on Windows and macOS, **`false`** otherwise. And if the flag is provided *without* a value, then it's **`true`**.

Now the **`--no-unicode-normalization`** flag controls whether a similar "fixup" happens for filenames that differ but are canonically equivalent with respect to unicode. Unicode normalization is especially helpful for macOS girlies, since macOS prefers form **NFD** instead of the **NFC** used by most other platforms. So it's *highly* recommended to keep the default of **false** on macOS, to avoid encoding compatibility issues. 🫶

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the **`--vfs-block-norm-dupes`** flag lets you hide these duplicates. But — performance tradeoff alert 🚨 — rclone will have to scan the entire directory for duplicates whenever it lists a directory. So yeah, it's recommended to leave this disabled if you don't need it. That said, macOS users might wanna consider turning it on, because otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation happens: both versions of the file are visible in the mount, and both *appear* editable, but editing either one actually only results in the NFD version getting edited under the hood. 😭 `--vfs-block-norm-dupes` prevents this confusion by detecting the scenario, hiding the duplicates, and logging an error — similar to how this is handled in `rclone sync`.

## 🎀 VFS Disk Options 🎀

This flag lets you manually set the statistics about the filing system. It's useful when those statistics can't be read correctly automatically. Iconic for when the auto-detection is giving nothing.

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


## 💖 Alternate report of used bytes 💖

Some backends — most notably S3 — do **not** report the amount of bytes used. So if you need this info available when running `df` on the filesystem, pass the flag **`--vfs-used-is-size`** to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself. ✨

> **WARNING.** Contrary to `rclone size`, this flag ignores filters so that the result is accurate. However, this is very inefficient and may cost lots of API calls resulting in extra charges. 💸 Use it as a **last resort** and only with caching.

rclone serve dlna remote:path [flags]


## ✨ Options ✨

- **`--addr string`** — The ip:port or :port to bind the DLNA http server to (default `":7879"`)
- **`--announce-interval Duration`** — The interval between SSDP announcements (default `12m0s`)
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default `5m0s`)
- **`--dir-perms FileMode`** — Directory permissions (default `777`)
- **`--file-perms FileMode`** — File permissions (default `666`)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for dlna
- **`--interface stringArray`** — The interface to use for SSDP (repeat as necessary)
- **`--link-perms FileMode`** — Link permissions (default `666`)
- **`--log-trace`** — Enable trace logging of SOAP traffic
- **`--name string`** — Name of DLNA server
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default `1m0s`)
- **`--read-only`** — Only allow read-only access
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default `002`)
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default `off`)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default `off`)
- **`--vfs-cache-mode CacheMode`** — Cache mode `off|minimal|writes|full` (default `off`)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default `off`)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a `.rclonelink` extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over `--buffer-size` when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read, until the limit is reached ('off' is unlimited) (default `off`)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the `rclone size` algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default `1s`)

Options shared with other commands are described next. See the global flags page for global options not listed here. 🌈

## 🦋 Filter Options 🦋

Flags for filtering directory listings

- **`--delete-excluded`** — bestie, this one deletes the files on the *dest* that got excluded from the sync. yes, really. excluded from sync ≠ safe. 💀
- **`--exclude stringArray`** — exclude files matching a pattern ✨
- **`--exclude-from stringArray`** — read your file of exclude patterns from a file (pass `-` and it'll slurp them from stdin) 🍓
- **`--exclude-if-present stringArray`** — nukes a directory if that filename is chillin' in it
- **`--files-from stringArray`** — read the list of source-file names from a file (`-` = stdin, queen) 💅
- **`--files-from-raw stringArray`** — same but literally *no* processing of the lines at all (also `-` for stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule, your own little law 🎀
- **`--filter-from stringArray`** — read file filtering patterns from a file (`-` = stdin again)
- **`--ignore-case`** — ignore case in filters, so it's case insensitive, periodt
- **`--include stringArray`** — include files matching pattern 🫶
- **`--include-from stringArray`** — read file include patterns from a file (`-` = stdin, iykyk)
- **`--max-age Duration`** — only transfer files *younger* than this; give it seconds or a suffix `ms|s|m|h|d|w|M|y` (default `off`) ⭐
- **`--max-depth int`** — if you set it, it caps the recursion depth right there (default `-1`)
- **`--max-size SizeSuffix`** — only transfer files *smaller* than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — exclude metadatas matching a pattern 🙈
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (`-` = stdin!)
- **`--metadata-filter stringArray`** — add a metadata filtering rule, iconic
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (`-` = stdin)
- **`--metadata-include stringArray`** — include metadatas matching pattern 🌈
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (`-` = stdin)
- **`--min-age Duration`** — only transfer files *older* than this; seconds or suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — only transfer files *bigger* than this, in KiB or suffix `B|K|M|G|T|P` (default `off`) 🔥

---

# 🌸 See Also 🌸

- **`rclone serve`** — Serve a remote over a protocol. that's the whole vibe 💖

---

# 🐳 rclone serve docker 🐳

Serve any remote on docker's volume plugin API. no cap, that's the main character move here.

## ✨ Synopsis ✨

This command implements the Docker volume plugin API, letting docker use rclone as its data storage mechanism for all the various cloud providers out there. rclone provides the docker volume plugin based on it. 💅

So to make a docker plugin, somebody's gotta create a Unix or TCP socket that Docker will go looking for when you use the plugin — and then it sits there listening for commands from the docker daemon and runs the corresponding code whenever it's needed. Docker plugins can run as a managed plugin under the control of the docker daemon, or as an independent native service. And for testing? You can literally just run it straight from the command line. Example time, bestie:

sudo rclone serve docker --base-dir /tmp/rclone-volumes --socket-addr localhost:8787 -vv


Running `rclone serve docker` will create that socket, listening for commands from Docker to create the necessary Volumes. Normally you do **not** need to give the `--socket-addr` flag. The API listens on the unix domain socket at `/run/docker/plugins/rclone.sock`. In the example above though, rclone will create a TCP socket *and* a little file at `/etc/docker/plugins/rclone.spec` containing the socket address. Why `sudo`? Because both of those paths are writeable only by the root user. 💀

If you later decide to change the listening socket, the docker daemon must be restarted to reconnect to `/run/docker/plugins/rclone.sock` or to parse the new `/etc/docker/plugins/rclone.spec`. Until you restart it, any volume-related docker command will just... timeout trying to reach the old socket. rude.

> Running directly is supported on **Linux only** — not on Windows or MacOS. This is not a problem with managed plugin mode, which is described in detail in the full documentation. ✨

The command will create volume mounts under the path given by `--base-dir` (by default `/var/lib/docker-volumes/rclone`, which is available only to root) and it maintains the JSON formatted file `docker-plugin.state` in the rclone cache directory, with book-keeping records of created and mounted volumes. 📝

All mount and VFS options are submitted by the docker daemon via API, but you can also hand it defaults on the command line, plus set the path to the config file and cache directory, or adjust logging verbosity. your call, bestie 🎀

## 🦋 VFS - Virtual File System 🦋

This command uses the VFS layer. It adapts the cloud storage objects that rclone uses into something that looks *much* more like a disk filing system. the glow-up is real.

Cloud storage objects have lots of properties that just aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with all of that. And because there's no one right way of doing it, there are various options explained below. 🤷

The VFS layer also implements a directory cache — this caches info about files and directories (but *not* the data) in memory. 💾

## 🎀 VFS Directory Cache 🎀

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately, or invalidate the cache. iconic.


However — changes made directly on the cloud storage, like by the web interface or a different copy of rclone, will only get picked up once the directory cache expires, *if* the backend configured doesn't support polling for changes. If the backend *does* support polling, then changes get picked up within the polling interval. ⭐

You can send a `SIGHUP` signal to rclone to make it flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control, then you can use `rclone rc` to flush the *whole* directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


## 💜 VFS File Buffering 💜

The `--buffer-size` flag determines the amount of memory that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared. no sharing, that's not the vibe.

This flag is an upper limit for the used memory per open file. The buffer will only use memory for data that is downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used. chill.

The maximum memory used by rclone for buffering can be up to `--buffer-size * open files`. 😭 (do the math before you open 500 files, bestie)

## 🫶 VFS File Caching 🫶

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It *can* be disabled, at the cost of some compatibility. your funeral, lowkey.

For example, you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details.

> Note that the VFS cache is separate from the cache backend, and you may find that you need one or the other or both. ✨


If run with `-vv`, rclone will print the location of the file cache. The files are stored in the user cache file area, which is OS dependent but can be controlled with `--cache-dir` or by setting the appropriate environment variable. 🍓

The cache has 4 different modes, selected by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. trade-offs, bestie, trade-offs.

Note that files are written back to the remote only when they are closed **and** if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. 🙈

If using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, note that the cache may exceed these quotas for two reasons. First: because it is only checked every `--vfs-cache-poll-interval`. Second: because open files cannot be evicted from the cache. When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. rclone will start with files that haven't been accessed for the longest. This cache flushing strategy is efficient, and more relevant files are likely to remain cached. slay. 👑

The `--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of 1 hour will start evicting files from cache that haven't been accessed for 1 hour. When a cached file is accessed, the 1 hour timer is reset to 0 and will wait for 1 more hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`. ⏰

> You should **not** run two copies of rclone using the same VFS cache with the same or overlapping remotes if using `--vfs-cache-mode > off`. This can potentially cause data corruption if you do. 💀 You can work around this by giving each rclone its own cache hierarchy with `--cache-dir`. You don't need to worry about this if the remotes in use don't overlap.

## 🌈 –vfs-cache-mode off 🌈

In this mode (the default), the cache will read directly from the remote and write directly to the remote without caching anything on disk. living dangerously, I respect it.

This will mean some operations are not possible:

- Files can't be opened for both read AND write 😭
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

### 🎀 `--vfs-cache-mode minimal` 🎀

Okay so this one is basically `off`'s slightly-more-grown-up sibling bestie. The one glow-up: files opened for read **AND** write get buffered to disk. Which means files opened for write are *a lot* more compatible, and it barely uses any disk space. Lowkey the budget icon. 💅

But bestie, these operations are just... not happening:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

---

### 🌸 `--vfs-cache-mode writes` 🌸

In this mode, files opened for **read only** are still read directly from the remote. But write only + read/write files get buffered to disk first. 🫶

This mode should support all normal file system operations, periodt.

And if an upload fails? It gets retried at exponentially increasing intervals up to 1 minute. Obsessed with the persistence fr fr. ✨

---

### 👑 `--vfs-cache-mode full` 👑

Full mode is the main character. In this mode ALL reads and writes are buffered to and from disk. And when data is read from the remote, that gets buffered to disk too. 💖

In this mode the files in the cache will be **sparse files**, and rclone will keep track of which bits of the files it has downloaded.

So if an application only reads the starts of each file, then rclone will only buffer the start of the file. These files will *appear* to be their full size in the cache, but they're actually sparse files with only the data that has been downloaded present in them. Sneaky but slay. 🦋

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> **IMPORTANT** not all file systems support sparse files. In particular FAT/exFAT do not. Rclone will perform very badly if the cache directory is on a filesystem which doesn't support sparse files and it will log an `ERROR` message if one is detected. 😭

---

### 🧚 Fingerprinting 🧚

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

...where available on an object.

On some backends some of these attributes are slow to read (they take an extra API call per object, or extra work per object). 🐌

For example hash is slow with the `local` and `sftp` backends as they have to read the entire file and hash it, and modtime is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will **not** include the slow operations in the fingerprint. This makes the fingerprinting less accurate but much faster and will improve the opening time of cached files. ⚡

If you are running a vfs cache over `local`, `s3` or `swift` backends then using this flag is recommended.

> Note that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again. 🙈

---

### 🌈 VFS Chunked Reading 🌈

When rclone reads files from a remote it reads them in **chunks**. This means that rather than requesting the whole file rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read, at the cost of an increased number of requests. ✨

These flags control the chunking:

- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default 128M)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — Max chunk doubling size (default off)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once

The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter.

---

### 💅 `--vfs-read-chunk-streams` == 0 💅

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then double the size for each read. When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is "off", which is the default, the limit is disabled and the chunk size will grow indefinitely. 📈

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0` the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on. Math girlies rise up 🧮✨

Setting `--vfs-read-chunk-size` to `0` or "off" disables chunked reading.

The chunks will not be buffered in memory.

---

### 🔥 `--vfs-read-chunk-streams` > 0 🔥

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` **concurrently**. The size for each read will stay constant.

This improves performance massively on high latency links or very high bandwidth links to high performance object stores. 🚀

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams` as these will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput. 💪

---

### ⭐ VFS Performance ⭐

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature.

In particular S3 and Swift benefit **hugely** from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect) as each read of the modification time takes a transaction. 💸

- **`--no-checksum`** — Don't compare checksums on up/download.
- **`--no-modtime`** — Don't read/write the modification time (can speed things up).
- **`--no-seek`** — Don't allow seeking in files.
- **`--read-only`** — Only allow read-only access.

Sometimes rclone is delivered reads or writes out of order. Rather than seeking rclone will wait a short time for the in sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file. 🫶

- **`--vfs-read-wait duration`** — Time to wait for in-sequence read before seeking (default 20ms)
- **`--vfs-write-wait duration`** — Time to wait for in-sequence write before giving error (default 1s)

When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has no effect on the VFS).

- **`--transfers int`** — Number of file transfers to run in parallel (default 4)

---

### 🦋 Symlinks 🦋

By default the VFS does **not** support symlinks. However this may be enabled with either of the following flags:

- **`--links`** — Translate symlinks to/from regular files with a '.rclonelink' extension.
- **`--vfs-links`** — Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS

As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink` and the contents would be the path to the symlink destination. 🎀

Note that `--links` enables symlink translation globally in rclone — this includes any backend which supports the concept (for example the `local` backend). `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with that used by the local backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet.

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but not `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands.

> Note that there is an outstanding issue with symlink support issue #8245 with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀

---

### 🌸 VFS Case Sensitivity 🌸

Linux file systems are **case-sensitive**: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are **case-insensitive but case-preserving**: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It is possible to make macOS file systems case-sensitive but that is not the default. 🍓

The `--vfs-case-insensitive` VFS flag controls how rclone handles these two cases. If its value is "false", rclone passes file names to the remote as-is. If the flag is "true" (or appears without a value on the command line), rclone may perform a "fixup" as explained below.

The user may specify a file name to open/delete/rename/etc with a case different than what is stored on the remote. If an argument refers to an existing file with exactly the same name, then the case of the existing file on the disk will be used. However, if a file name with exactly the same name is not found but a name differing only by case exists, rclone will transparently fixup the name. This fixup happens only when an existing file is requested. Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

Note that case sensitivity of the operating system running rclone (the target) may differ from case sensitivity of a file system presented by rclone (the source). The flag controls whether "fixup" is performed to satisfy the target. 💖

If the flag is not provided on the command line, then its default value depends on the operating system where rclone runs: "true" on Windows and macOS, "false" otherwise. If the flag is provided without a value, then it is "true". 🫶

<purple>ok so quick recap bestie:</purple> the `--no-unicode-normalization` flag is the one that decides whether we do the same lil “fixup” thing for filenames that are different but canonically equivalent in unicode-land. <cyan>Unicode normalization is a whole vibe for macOS girlies</cyan>, because macOS is obsessed with form NFD while basically everyone else is on NFC. So on macOS you <hotpink>really really</hotpink> want to keep the default of `false`, or you're gonna get encoding compatibility drama. periodt.

And in the (probably never, but like… never say never) situation where a directory ends up with multiple duplicate filenames *after* we apply case and unicode normalization, the `--vfs-block-norm-dupes` flag lets you hide those dupes. 💅 Heads up though: it's a performance tradeoff, because rclone has to scan the **entire** directory looking for dupes every time it lists it. So if you don't need it, leave it off, okay? <yellow>BUT</yellow> — macOS users might wanna consider it, because otherwise, if a remote dir has both NFC and NFD versions of the same filename, you get the weirdest situation: both versions show up in the mount, both look editable, but editing *either* one actually only edits the NFD version under the hood. 😭 `--vfs-block-norm-dupes` stops that confusion by detecting the scenario, hiding the duplicates, and logging an error — same energy as how rclone sync handles it. <rainbow>slay</rainbow>

### 🩷 VFS Disk Options 🩷

This flag lets you manually set the stats about the filesystem. highkey useful when those stats just won't read correctly on their own. 🙈

- **`--vfs-disk-space-total-size`** — Manually set the total disk space size (example: `256G`, default: `-1`)

### ⭐ Alternate report of used bytes ⭐

Some backends — most notably S3, hi bestie 👋 — do not report the amount of bytes used. So if you need that info to show up when you run `df` on the filesystem, you pass the flag `--vfs-used-is-size` to rclone. With that flag set, instead of trusting the backend to tell you, rclone scans the whole remote kinda like `rclone size` does and computes the total used space all by itself. 🧚

> <red>WARNING.</red> Unlike `rclone size`, this flag ignores filters so the result is accurate. But it is **very inefficient** and may cost you a *lot* of API calls, which means extra charges. 💀 Use it as a last resort and only with caching.

rclone serve docker [flags]


## 🎀 Options 🎀

- **`--allow-non-empty`** — Allow mounting over a non-empty directory (not supported on Windows)
- **`--allow-other`** — Allow access to other users (not supported on Windows)
- **`--allow-root`** — Allow access to root user (not supported on Windows)
- **`--async-read`** — Use asynchronous reads (not supported on Windows) (default `true`)
- **`--attr-timeout Duration`** — Time for which file/directory attributes are cached (default `1s`)
- **`--base-dir string`** — Base directory for volumes (default `"/var/lib/docker-volumes/rclone"`)
- **`--daemon`** — Run mount in background and exit parent process (as background output is suppressed, use `--log-file` with `--log-format=pid,...` to monitor) (not supported on Windows)
- **`--daemon-timeout Duration`** — Time limit for rclone to respond to kernel (not supported on Windows) (default `0s`)
- **`--daemon-wait Duration`** — Time to wait for ready mount from daemon (maximum time on Linux, constant sleep time on OSX/BSD) (not supported on Windows) (default `1m0s`)
- **`--debug-fuse`** — Debug the FUSE internals - needs `-v`
- **`--default-permissions`** — Makes kernel enforce access control based on the file mode (not supported on Windows)
- **`--devname string`** — Set the device name - default is `remote:path`
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default `5m0s`)
- **`--dir-perms FileMode`** — Directory permissions (default `777`)
- **`--direct-io`** — Use Direct IO, disables caching of data
- **`--file-perms FileMode`** — File permissions (default `666`)
- **`--forget-state`** — Skip restoring previous state
- **`--fuse-flag stringArray`** — Flags or arguments to be passed direct to libfuse/WinFsp (repeat if required)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for docker
- **`--link-perms FileMode`** — Link permissions (default `666`)
- **`--max-read-ahead SizeSuffix`** — The number of bytes that can be prefetched for sequential reads (not supported on Windows) (default `128Ki`)
- **`--mount-case-insensitive Tristate`** — Tell the OS the mount is case insensitive (`true`) or sensitive (`false`) regardless of the backend (`auto`) (default `unset`)
- **`--network-mode`** — Mount as remote network drive, instead of fixed disk drive (supported on Windows only)
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--no-spec`** — Do not write spec file
- **`--noappledouble`** — Ignore Apple Double (`._`) and `.DS_Store` files (supported on OSX only) (default `true`)
- **`--noapplexattr`** — Ignore all `"com.apple.*"` extended attributes (supported on OSX only)
- **`-o`, `--option stringArray`** — Option for libfuse/WinFsp (repeat if required)
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than `dir-cache-time` and only on supported remotes (set `0` to disable) (default `1m0s`)
- **`--read-only`** — Only allow read-only access
- **`--socket-addr string`** — Address `<host:port>` or absolute path (default: `/run/docker/plugins/rclone.sock`)
- **`--socket-gid int`** — GID for unix socket (default: current process GID) (default `1000`)
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default `002`)
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default `off`)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default `off`)
- **`--vfs-cache-mode CacheMode`** — Cache mode `off|minimal|writes|full` (default `off`)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default `off`)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a `.rclonelink` extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over `--buffer-size` when using cache-mode `full`
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read, until the limit is reached (`'off'` is unlimited) (default `off`)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the `rclone size` algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default `1s`)
- **`--volname string`** — Set the volume name (supported on Windows and OSX only)
- **`--write-back-cache`** — Makes kernel buffer writes before sending them to rclone (without this, writethrough caching is used) (not supported on Windows)

Options shared with other commands are described next, bestie. 👑 See the global flags page for global options not listed here.

---

### 🌈 Filter Options 🌈

Flags for filtering directory listings

- **`--delete-excluded`** — deletes the files on the dest that got excluded from the sync. yes, actually deletes. be careful 💀
- **`--exclude stringArray`** — exclude files that match this pattern
- **`--exclude-from stringArray`** — read your exclude patterns out of a file (use `-` to read them from stdin)
- **`--exclude-if-present stringArray`** — nope out of a whole directory if this filename is sitting in it
- **`--files-from stringArray`** — read the list of source-file names from a file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — same thing but with zero processing of the lines (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule
- **`--filter-from stringArray`** — read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — ignore case in filters, she's case insensitive and unbothered
- **`--include stringArray`** — include files matching this pattern
- **`--include-from stringArray`** — read file include patterns from a file (use `-` to read from stdin)
- **`--max-age Duration`** — only transfer files *younger* than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth int`** — if you set it, it caps the recursion depth right there (default `-1`)
- **`--max-size SizeSuffix`** — only transfer files *smaller* than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — exclude metadatas matching this pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — include metadatas matching this pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` to read from stdin)
- **`--min-age Duration`** — only transfer files *older* than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — only transfer files *bigger* than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)

---

### 🌈 See Also 🌈

- `rclone serve` — Serve a remote over a protocol.

---

# 🍓 rclone serve ftp 🍓

## 📜 Synopsis 📜

okay bestie, this one runs a whole entire **basic FTP server** so you can serve a remote over the FTP protocol. you can peek at it with a FTP client, or you can literally just make yourself a remote of type FTP and read from it and write to it like it's nothing. iconic behaviour honestly ✨

## 🔧 Server options 🔧

use `--addr` to pick which IP address and port the server should be listening on, like `--addr 1.2.3.4:8000`, or `--addr :8080` if you want it listening on all the IPs. default vibe? it only listens on localhost. and you can use port `:0` to let the OS pick an available port for you, which is lowkey the move 🎀

> if you set `--addr` to listen on a public or LAN accessible IP address, then using Authentication is advised — go read the next section, fr fr.

## 🔐 Authentication 🔐

by default this serves files with absolutely no login needed. open house. no bouncer.

you can set a single username and password with the `--user` and `--pass` flags. that's the whole guest list, one person, but it counts 💅

## 🗂 VFS - Virtual File System 🗂

this command rides on the VFS layer. what that does is adapt the cloud storage objects rclone uses into something that looks *way* more like a disk filing system, so your boring old file expectations don't get hurt too bad.

here's the tea though: cloud storage objects have a bunch of properties that are simply not disk-file properties. you can't extend them, you can't write to the middle of them, so the VFS layer has to cope with all of that. and because there is no one single correct way of doing the coping, there are various options, explained below 🌸

the VFS layer also implements a **directory cache** — it caches info about files and directories (but not the data, never the data) in memory.

## 🕰 VFS Directory Cache 🕰

with the `--dir-cache-time` flag you control how long a directory gets to be considered up to date before rclone goes and refreshes it from the backend. anything you change *through* the VFS shows up immediately, or it invalidates the cache.


but listen — if somebody changes stuff **directly** on the cloud storage, like through the web interface or a different copy of rclone, you're only gonna pick that up once the directory cache expires... *unless* the backend you configured supports polling for changes. if it does support polling, you'll catch those changes within the polling interval. no cap 🫶

you can also send a `SIGHUP` signal to rclone to make it flush all directory caches, no matter how old they are. assuming only one rclone instance is running, you reset the cache like this:

kill -SIGHUP $(pidof rclone)


and if you configured rclone with a remote control, you can use `rclone rc` to flush the entire directory cache:

rclone rc vfs/forget


or just individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


## 🧺 VFS File Buffering 🧺

the `--buffer-size` flag decides how much memory is used to buffer data in advance.

every open file is gonna try and keep that specified amount of data in memory at all times. and that buffered data is bound to *one* open file — it does not get shared. no community buffer, sorry 🧚

this flag is an **upper limit** for the memory used per open file. the buffer only actually uses memory for data that's been downloaded but not yet read. so if the buffer is empty, only a tiny bit of memory gets used. obsessed with the efficiency tbh.

the maximum memory rclone uses for buffering can be up to `--buffer-size` × open files. do the math before you go wild.

## 💾 VFS File Caching 💾

these flags control the VFS file caching options. file caching is genuinely necessary to make the VFS layer look compatible with a normal file system. you *can* disable it, but the price is some compatibility. your call, bestie.

for example, you'll need VFS caching enabled if you want to read and write to a file at the same time. more deets below 👇

> just so you know — the VFS cache is **separate** from the cache backend. you may find you need one of them, the other one, or both. they are not the same thing and they are not dating.


if you run with `-vv`, rclone prints the location of the file cache. the files live in the user cache file area, which is OS dependent, but you can steer it with `--cache-dir` or by setting the appropriate environment variable.

the cache has **4** different modes, picked with `--vfs-cache-mode`. the higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. trade-offs, always trade-offs 💅

> note that files are written back to the remote only when they're closed, and only if they haven't been accessed for `--vfs-write-back` seconds. if rclone quits or dies while files haven't been uploaded yet, those will get uploaded the next time rclone runs with the same flags. no lost files, just delayed ones.

if you're using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, heads up that the cache may exceed those quotas for two reasons. one, because it's only checked every `--vfs-cache-poll-interval`. two, because **open files cannot be evicted from the cache**. when `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. it starts with whichever files haven't been accessed for the longest. this flushing strategy is efficient, and more relevant files are likely to stay cached. queen shit honestly 👑

`--vfs-cache-max-age` evicts files from the cache once the set time since last access has passed. the default of 1 hour means it'll start evicting files cache that haven't been touched for 1 hour. when a cached file *is* accessed, that 1 hour timer resets to 0 and waits another hour before evicting. you specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> ⚠️ you should **NOT** run two copies of rclone using the same VFS cache with the same or overlapping remotes if you're using `--vfs-cache-mode > off`. like, genuinely, this can potentially cause **data corruption**. if you have to, work around it by giving each rclone its own cache hierarchy with `--cache-dir`. and if the remotes in use don't overlap at all, you don't need to worry about any of this 🫶

### 🚫 –vfs-cache-mode off 🚫

in this mode (the default!) the cache reads directly from the remote and writes directly to the remote, caching absolutely nothing on disk. zero. nada.

which means some operations are simply not possible:

- Files can't be opened for both read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

### 🍃 –vfs-cache-mode minimal 🍃

this is very similar to "off", except that files opened for read AND write will be buffered to disk. so files opened for write are a lot more compatible now, and it uses the minimal amount of disk space. cute and cheap.

these operations are still not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

### ✍️ –vfs-cache-mode writes ✍️

in this mode, files opened read only are still read straight from the remote — but write only and read/write files get buffered to disk first.

this mode should support all normal file system operations. finally, no notes.

and if an upload fails? it gets retried at exponentially increasing intervals up to 1 minute. she's persistent 💖

### 🌟 –vfs-cache-mode full 🌟

in this mode **all** reads and writes are buffered to and from disk. and when data is read from the remote, that gets buffered to disk as well.

in this mode the files in the cache will be **sparse files**, and rclone keeps track of which bits of the files it has actually downloaded. so if an application only reads the starts of each file, rclone will only buffer the start of the file. these files will *appear* to be their full size in the cache, but they're sparse files with only the downloaded data actually present in them. it's giving illusions, it's giving sleight of hand ✨

This mode is *the* moment — it should support all normal file system operations, and other than that it's identical to `--vfs-cache-mode writes`. 💅

When rclone reads a file it reads `--buffer-size` **plus** `--vfs-read-ahead` bytes ahead. The `--buffer-size` bit gets buffered in **memory**, whereas the `--vfs-read-ahead` bit gets buffered **on disk**. 🧠✨

So when you're living in this mode, the recommendation is: don't set `--buffer-size` too large, and set `--vfs-read-ahead` large if you need it.

> 🚨 **IMPORTANT** bestie: not all file systems support sparse files. FAT/exFAT in particular? They do **not**. Rclone will perform *very badly* if the cache directory is on a filesystem that doesn't support sparse files, and it will log an `ERROR` message if one is detected.

### 🦋 Fingerprinting 🦋

Various parts of the VFS use fingerprinting to check if a local file copy has changed relative to a remote file. Fingerprints get made from:

- `size`
- modification time
- `hash`

...where available on an object. 👑

On some backends, some of these attributes are *slow* to read — they take an extra API call per object, or extra work per object. 😭

For example `hash` is slow with the `local` and `sftp` backends, because they have to read the entire file and hash it. And modtime is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends, because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will **not** include the slow operations in the fingerprint. That makes the fingerprinting less accurate but *much* faster, and it will improve the opening time of cached files. ⚡

If you're running a vfs cache over `local`, `s3` or `swift` backends, then using this flag is recommended. 💖

> Note: if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again. 🫠

### 🔥 VFS Chunked Reading 🔥

When rclone reads files from a remote it reads them in chunks. So instead of requesting the whole file, rclone reads the chunk specified. This can reduce the used download quota for some remotes, since it only requests chunks from the remote that are actually read — at the cost of an increased number of requests. 🌀

These flags control the chunking:

- **`--vfs-read-chunk-size`** *SizeSuffix* — read the source objects in chunks (default `128M`)
- **`--vfs-read-chunk-size-limit`** *SizeSuffix* — max chunk doubling size (default `off`)
- **`--vfs-read-chunk-streams`** *int* — the number of parallel streams to read at once

The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter. 👀

### ✨ `--vfs-read-chunk-streams` == 0 ✨

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then **double the size for each read**. When `--vfs-read-chunk-size-limit` is specified, and it's greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is "off" — which is the default — the limit is disabled and the chunk size will grow indefinitely. 📈

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0` the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on.

Setting `--vfs-read-chunk-size` to `0` or "off" disables chunked reading.

The chunks will **not** be buffered in memory. 💭

### 💜 `--vfs-read-chunk-streams` > 0 💜

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` *concurrently*. The size for each read will stay constant.

This improves performance massively on high latency links, or on very high bandwidth links to high performance object stores. 🚀

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams`, because those will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting. 🔥

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

### 🌈 VFS Performance 🌈

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature. ✨

In particular S3 and Swift benefit hugely from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect), because each read of the modification time takes a transaction. 💸

- **`--no-checksum`** — don't compare checksums on up/download.
- **`--no-modtime`** — don't read/write the modification time (can speed things up).
- **`--no-seek`** — don't allow seeking in files.
- **`--read-only`** — only allow read-only access.

Sometimes rclone is delivered reads or writes **out of order**. Rather than seeking, rclone will wait a short time for the in-sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file. ⏳

- **`--vfs-read-wait`** *duration* — time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-write-wait`** *duration* — time to wait for in-sequence write before giving error (default `1s`)

When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has **no effect** on the VFS). 📤

- **`--transfers`** *int* — number of file transfers to run in parallel (default `4`)

### 🎀 Symlinks 🎀

By default the VFS does **not** support symlinks. However this may be enabled with either of the following flags:

- **`--links`** — translate symlinks to/from regular files with a `.rclonelink` extension.
- **`--vfs-links`** — translate symlinks to/from regular files with a `.rclonelink` extension for the VFS

As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink`, and the contents would be the path to the symlink destination. 🔗

Note that `--links` enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the `local` backend). `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with the one used by the local backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`. 👑

It hasn't been tested with the other `rclone serve` commands yet. 🙈

A limitation of the current implementation is that it expects the *caller* to resolve sub-symlinks. For example, given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but **not** `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands.

Note that there is an outstanding issue with symlink support — issue #8245 — with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀

### 🌸 VFS Case Sensitivity 🌸

Linux file systems are case-sensitive: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are case-insensitive but case-preserving: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It's possible to make macOS file systems case-sensitive, but that is not the default.

The `--vfs-case-insensitive` VFS flag controls how rclone handles these two cases. If its value is "false", rclone passes file names to the remote as-is. If the flag is "true" (or appears without a value on the command line), rclone may perform a "fixup" as explained below. ✨

The user may specify a file name to open/delete/rename/etc with a case different than what is stored on the remote. If an argument refers to an existing file with exactly the same name, then the case of the existing file on the disk will be used. However, if a file name with exactly the same name is not found but a name differing only by case exists, rclone will transparently fixup the name. This fixup happens only when an existing file is requested. Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

Note that case sensitivity of the operating system running rclone (the target) may differ from case sensitivity of a file system presented by rclone (the source). The flag controls whether "fixup" is performed to satisfy the target.

If the flag is not provided on the command line, then its default value depends on the operating system where rclone runs: "true" on Windows and macOS, "false" otherwise. If the flag is provided without a value, then it is "true".

The `--no-unicode-normalization` flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent with respect to unicode. Unicode normalization can be particularly helpful for users of macOS, which prefers form NFD instead of the NFC used by most other platforms. It is therefore **highly recommended** to keep the default of `false` on macOS, to avoid encoding compatibility issues. 🍓

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag allows hiding these duplicates. This comes with a performance tradeoff, as rclone will have to scan the entire directory for duplicates when listing a directory. For this reason, it is recommended to leave this disabled if not needed. However, macOS users may wish to consider using it, as otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation will occur: both versions of the file will be visible in the mount, and both will appear to be editable, however, editing either version will actually result in only the NFD version getting edited under the hood. `--vfs-block-norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`.

### 💅 VFS Disk Options 💅

This flag allows you to manually set the statistics about the file system. It can be useful when those statistics cannot be read correctly automatically.

- **`--vfs-disk-space-total-size SizeSuffix`** — you hand-set the total size of the disk yourself (like `256G`, default: `-1` meaning "nah, don't")

---

## 🫖 Alternate report of used bytes

Some backends — <hotpink>S3 bestie, I'm looking at you</hotpink> — just *will not* tell you how many bytes are used. Rude of them honestly. So if you want that number to actually show up when you run `df` on the filesystem, pass `--vfs-used-is-size` to rclone. With that flag on, instead of vibing and hoping the backend reports it, rclone will scan the whole remote — basically like `rclone size` does — and compute the total used space all by itself. 💪

> **WARNING.** Unlike `rclone size`, this flag **ignores filters** so the result is accurate. But that accuracy costs you: it's *very* inefficient and may burn a ton of API calls, which means <red>extra charges</red>. Treat it as an absolute last resort and only ever use it with caching. 😭

---

## 🔐 Auth Proxy

If you pass the parameter `--auth-proxy /path/to/program`, then rclone will use that program to generate backends on the fly, and those backends are what gets used to authenticate incoming requests. It's a simple JSON-based protocol: input goes on <cyan>STDIN</cyan>, output comes back on <cyan>STDOUT</cyan>. Clean, iconic, no cap. ✨

**PLEASE NOTE:** `--auth-proxy` and `--authorized-keys` cannot be used together. If `--auth-proxy` is set, the authorized keys option will just be ignored. 💅

There's an example program `bin/test_proxy.py` in the rclone source code if you wanna peek at how it's done.

So the program's whole job is: take a `user` and `pass` from the input, and turn those into the config for a backend, printed on `STDOUT` in JSON format. That config gets any default parameters for the backend added to it — but it will **not** use configuration from environment variables or command line options. Making a complete config is entirely the proxy program's job, bestie. 👑

This config you generate **must** have this extra parameter:

- `_root` — root to use for the backend

And it **may** have this parameter:

- `_obscure` — comma separated strings for parameters to obscure

If password authentication was used by the client, the input to the proxy process (on `STDIN`) would look something like this:

{ "user": "me", "pass": "mypassword" }


If public-key authentication was used by the client, the input to the proxy process (on `STDIN`) would look something like this:

{ "user": "me", "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf" }


And as an example, you'd return this on `STDOUT`:

{ "type": "sftp", "_root": "", "_obscure": "pass", "user": "me", "pass": "mypassword", "host": "sftp.example.com" }


What this means: an SFTP backend would be created **on the fly** for the `user` and `pass`/`public_key` returned in the output, pointed at the host given. Note that since `_obscure` is set to `pass`, rclone will obscure the `pass` parameter before creating the backend — which is required for sftp backends. 🧚

The program can manipulate the supplied `user` however it wants. For example, to proxy to many different sftp backends, you could make the `user` be `user@example.com`, then set the `host` to `example.com` in the output and the `user` to `user`. For security you'd probably want to restrict the host to a limited list. 🔒

Note that an internal cache is <purple>keyed on `user`</purple>, so only use *that* for configuration — <red>don't use `pass` or `public_key`</red>. This also means that if a user's password or public-key changes, the cache will need to expire (which takes **5 mins**) before it takes effect. ⏳

This can be used to build general-purpose proxies to any kind of backend that rclone supports. Slay. 💅

rclone serve ftp remote:path [flags]


---

## ✨ Options ✨

- **`--addr string`** — IPaddress:Port or :Port to bind server to (default `"localhost:2121"`)
- **`--auth-proxy string`** — A program to use to create the backend from the auth
- **`--cert string`** — TLS PEM key (concatenation of certificate and CA certificate)
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default `5m0s`)
- **`--dir-perms FileMode`** — Directory permissions (default `777`)
- **`--file-perms FileMode`** — File permissions (default `666`)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for ftp
- **`--key string`** — TLS PEM Private key
- **`--link-perms FileMode`** — Link permissions (default `666`)
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--pass string`** — Password for authentication (empty value allow every password)
- **`--passive-port string`** — Passive port range to use (default `"30000-32000"`)
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default `1m0s`)
- **`--public-ip string`** — Public IP address to advertise for passive connections
- **`--read-only`** — Only allow read-only access
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default `002`)
- **`--user string`** — User name for authentication (default `"anonymous"`)
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default `off`)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default `off`)
- **`--vfs-cache-mode CacheMode`** — Cache mode `off|minimal|writes|full` (default `off`)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default `off`)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a `'.rclonelink'` extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over `--buffer-size` when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read, until the limit is reached (`'off'` is unlimited) (default `off`)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the rclone size algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default `1s`)

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

---

## 🎀 Filter Options

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest excluded from sync
- **`--exclude stringArray`** — Exclude files matching pattern
- **`--exclude-from stringArray`** — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — Exclude directories if filename is present
- **`--files-from stringArray`** — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — Add a file filtering rule
- **`--filter-from stringArray`** — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include stringArray`** — Include files matching pattern
- **`--include-from stringArray`** — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age Duration`** — Only transfer files younger than this in s or suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth int`** — If set limits the recursion depth to this (default `-1`)
- **`--max-size SizeSuffix`** — Only transfer files smaller than this in KiB or suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — Exclude metadatas matching pattern
- **`--metadata-exclude-from stringArray`** — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — Add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — Include metadatas matching pattern
- **`--metadata-include-from stringArray`** — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age Duration`** — Only transfer files older than this in s or suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — Only transfer files bigger than this in KiB or suffix `B|K|M|G|T|P` (default `off`)

---

## 👀 See Also

- `rclone serve` — Serve a remote over a protocol.

---

# 🌈 rclone serve http

Serve the remote over HTTP. 🌐

## 📜 Synopsis

Run a basic web server to serve a remote over HTTP. You can open it up in a web browser, or you can make a remote of type `http` and read from it. Both ways, whatever. ✨

You can use the filter flags (like `--include`, `--exclude`) to control what actually gets served. 💅

The server will log errors. Use `-v` to see access logs. 👀

`--bwlimit` will be respected for file transfers. Use `--stats` to control the stats printing. 📊

## ✨ Server options ✨

Use `--addr` to specify which IP address and port the server should listen on, eg `--addr 1.2.3.4:8000` or `--addr :8080` to listen to all IPs. By default it only listens on localhost. You can use port `:0` to let the OS choose an available port. 🎯

If you set `--addr` to listen on a public or LAN accessible IP address then using Authentication is advised — see the next section for info. 🔐

You can use a unix socket by setting the url to `unix:///path/to/socket` or just by using an absolute path name. 🦋

`--addr` may be repeated to listen on multiple IPs/ports/sockets. Socket activation, described further below, can also be used to accomplish the same. 💅

`--server-read-timeout` and `--server-write-timeout` can be used to control the timeouts on the server. Note that this is the total time for a transfer. ⏳

`--max-header-bytes` controls the maximum number of bytes the server will accept in the HTTP header. 📏

`--baseurl` controls the URL prefix that rclone serves from. By default rclone will serve from the root. If you used `--baseurl "/rclone"` then rclone would serve from a URL starting with “/rclone/”. This is useful if you wish to proxy rclone serve. Rclone automatically inserts leading and trailing “/” on `--baseurl`, so `--baseurl "rclone"`, `--baseurl "/rclone"` and `--baseurl "/rclone/"` are all treated identically. 🔥

---

## 🔒 TLS (SSL) 🔒

By default this will serve over http. If you want you can serve over https. You will need to supply the `--cert` and `--key` flags. If you wish to do client side certificate validation then you will need to supply `--client-ca` also. 🌈

`--cert` must be set to the path of a file containing either a PEM encoded certificate, or a concatenation of that with the CA certificate. `--key` must be set to the path of a file with the PEM encoded private key. If setting `--client-ca`, it should be set to the path of a file with PEM encoded client certificate authority certificates. 🔑

`--min-tls-version` is minimum TLS version that is acceptable. Valid values are “tls1.0”, “tls1.1”, “tls1.2” and “tls1.3” (default “tls1.0”). ⭐

---

## 🔌 Socket activation 🔌

Instead of the listening addresses specified above, rclone will listen to all FDs passed by the service manager, if any (and ignore any arguments passed by `--addr`). 🫶

This allows rclone to be a socket-activated service. It can be configured with `.socket` and `.service` unit files as described in `https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html` 💖

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command

systemd-socket-activate -l 8000 -- rclone serve


This will socket-activate rclone on the first connection to port 8000 over TCP. 🚀

### 🎀 Template 🎀

`--template` allows a user to specify a custom markup template for HTTP and WebDAV serve functions. The server exports the following markup to be used within the template to server pages: ✨

- `.Name` — The full path of a file/directory.
- `.Title` — Directory listing of `.Name`
- `.Sort` — The current sort used. This is changeable via `?sort=` parameter Sort Options: `namedirfirst,name,size,time` (default `namedirfirst`)
- `.Order` — The current ordering used. This is changeable via `?order=` parameter Order Options: `asc,desc` (default `asc`)
- `.Query` — Currently unused.
- `.Breadcrumb` — Allows for creating a relative navigation
  - `.Link` — The relative to the root link of the Text.
  - `.Text` — The Name of the directory.
- `.Entries` — Information about a specific file/directory.
  - `.URL` — The `url' of an entry.
  - `.Leaf` — Currently same as `URL' but intended to be `just' the name.
  - `.IsDir` — Boolean for if an entry is a directory or not.
  - `.Size` — Size in Bytes of the entry.
  - `.ModTime` — The UTC timestamp of an entry.

The server also makes the following functions available so that they can be used within the template. These functions help extend the options for dynamic rendering of HTML. They can be used to render HTML based on specific conditions. 💜

- `afterEpoch` — Returns the time since the epoch for the given time.
- `contains` — Checks whether a given substring is present or not in a given string.
- `hasPrefix` — Checks whether the given string begins with the specified prefix.
- `hasSuffix` — Checks whether the given string end with the specified suffix.

---

## 🔐 Authentication 🔐

By default this will serve files without needing a login. 🙈

You can either use an htpasswd file which can take lots of users, or set a single username and password with the `--user` and `--pass` flags. 👑

If no static users are configured by either of the above methods, and client certificates are required by the `--client-ca` flag passed to the server, the client certificate common name will be considered as the username. 🎫

Use `--htpasswd /path/to/htpasswd` to provide an htpasswd file. This is in standard apache format and supports MD5, SHA1 and BCrypt for basic authentication. Bcrypt is recommended. 💅

To create an htpasswd file:

touch htpasswd htpasswd -B htpasswd user htpasswd -B htpasswd anotherUser


The password file can be updated while rclone is running. 🔄

Use `--realm` to set the authentication realm. 🌸

Use `--salt` to change the password hashing salt from the default. 🧂

---

## 🗂️ VFS - Virtual File System 🗂️

This command uses the VFS layer. This adapts the cloud storage objects that rclone uses into something which looks much more like a disk filing system. 🍓

Cloud storage objects have lots of properties which aren’t like disk files — you can’t extend them or write to the middle of them, so the VFS layer has to deal with that. Because there is no one right way of doing this there are various options explained below. 😭

The VFS layer also implements a directory cache — this caches info about files and directories (but not the data) in memory. 🧠

---

## 📁 VFS Directory Cache 📁

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately or invalidate the cache. ✨


However, changes made directly on the cloud storage by the web interface or a different copy of rclone will only be picked up once the directory cache expires if the backend configured does not support polling for changes. If the backend supports polling, changes will be picked up within the polling interval. ⏰

You can send a SIGHUP signal to rclone for it to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this: 💥

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache: 🫧

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


---

## 💾 VFS File Buffering 💾

The `--buffer-size` flag determines the amount of memory, that will be used to buffer data in advance. 🧚

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won’t be shared. 🔗

This flag is a upper limit for the used memory per open file. The buffer will only use memory for data that is downloaded but not not yet read. If the buffer is empty, only a small amount of memory will be used. 🪶

The maximum memory used by rclone for buffering can be up to `--buffer-size` * open files. 🔢

---

## 🗃️ VFS File Caching 🗃️

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled at the cost of some compatibility. 💀

For example you’ll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details. 👀

Note that the VFS cache is separate from the cache backend and you may find that you need one or the other or both. 🤔


<pink>okay so</pink> if you run rclone with `-vv`, it'll print out the location of the file cache for you 💖 That cache lives in the user cache file area, which is OS dependent, but bestie you can totally control it with `--cache-dir` or by setting the appropriate environment variable ✨

The cache has <hotpink>4</hotpink> different modes that you pick with `--vfs-cache-mode` 💅 The higher the cache mode, the more compatible rclone becomes — at the cost of using more disk space. Tradeoffs, we love them.

> Heads up 🫶 files only get written back to the remote when they're **closed** *and* if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies while holding files that haven't been uploaded yet, those files will be uploaded the next time rclone runs with the same flags. No cap.

If you're using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, note that the cache may exceed these quotas for <purple>two</purple> reasons. First: it's only checked every `--vfs-cache-poll-interval`. Second: open files cannot be evicted from the cache, periodt. When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first 💀 It starts with the files that haven't been accessed for the longest. This cache flushing strategy is efficient, and the more relevant files are likely to stay cached 🌸

The `--vfs-cache-max-age` flag will evict files from the cache after the set time since last access has passed. The default value of `1 hour` will start evicting files from the cache that haven't been accessed for 1 hour. When a cached file is accessed, the 1 hour timer resets to 0 and it waits for 1 more hour before evicting 🕰️ Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> <red>Girl, do NOT do this:</red> you should not run two copies of rclone using the same VFS cache with the same or overlapping remotes if you're using `--vfs-cache-mode > off` 😭 This can potentially cause data corruption if you do. You can work around it by giving each rclone its own cache hierarchy with `--cache-dir` 💅 You don't need to worry about this if the remotes in use don't overlap — slay.

### 🎀 `--vfs-cache-mode off` 🎀

In this mode (the default), the cache reads directly from the remote and writes directly to the remote without caching anything on disk. Which means some operations are simply not possible:

- Files can't be opened for both read AND write 😭
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried 💀

### 🎀 `--vfs-cache-mode minimal` 🎀

This is very similar to "off", except that files opened for read AND write will be buffered to disk ✨ Which means files opened for write are a *lot* more compatible — but it uses the minimal disk space.

These operations are not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried 😭

### 🎀 `--vfs-cache-mode writes` 🎀

In this mode, files opened read only are still read directly from the remote, while write only and read/write files are buffered to disk first 💖

This mode should support all normal file system operations 👑

If an upload fails, it will be retried at exponentially increasing intervals, up to 1 minute 🔥

### 🎀 `--vfs-cache-mode full` 🎀

In this mode, all reads and writes are buffered to and from disk. When data is read from the remote, this is buffered to disk as well ✨

In this mode the files in the cache will be **sparse files**, and rclone keeps track of which bits of the files it has downloaded 🧚

So if an application only reads the starts of each file, then rclone will only buffer the start of the file. These files will appear to be their full size in the cache, but they will be sparse files with only the data that has been downloaded present in them 👑

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead 💅 The `--buffer-size` is buffered in memory, whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> <red>IMPORTANT:</red> not all file systems support sparse files. In particular `FAT`/`exFAT` do not 😭 Rclone will perform very badly if the cache directory is on a filesystem which doesn't support sparse files, and it will log an `ERROR` message if one is detected 💀

## 🔍 Fingerprinting 🔍

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file 💖 Fingerprints are made from:

- size
- modification time
- hash

...where available on an object.

On some backends some of these attributes are slow to read (they take an extra API call per object, or extra work per object) 🐌

For example, hash is slow with the `local` and `sftp` backends, since they have to read the entire file and hash it. And modtime is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends, because they need to do an extra API call to fetch it 😮‍💨

If you use the `--vfs-fast-fingerprint` flag, then rclone will not include the slow operations in the fingerprint ✨ This makes the fingerprinting less accurate, but much faster, and it'll improve the opening time of cached files 💅

If you are running a vfs cache over `local`, `s3` or `swift` backends, then using this flag is recommended 👑

> Note: if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again 🙈

## 🌈 VFS Chunked Reading 🌈

When rclone reads files from a remote, it reads them in chunks 💖 So rather than requesting the whole file, rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read — at the cost of an increased number of requests.

These flags control the chunking:


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter 👀

### `--vfs-read-chunk-streams == 0`

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then double the size for each read 📈 When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is "off", which is the default, the limit is disabled and the chunk size will grow indefinitely 🚀

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0`, the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on ✨

Setting `--vfs-read-chunk-size` to `0` or `"off"` disables chunked reading 💅

The chunks will not be buffered in memory.

### `--vfs-read-chunk-streams > 0`

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` concurrently 🔥 The size for each read will stay constant.

This improves performance massively on high latency links, or very high bandwidth links to high performance object stores 👑

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams`, since these will depend on the backend in use and the latency to the backend 🧪

For high performance object stores (eg AWS S3), a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M` ✨ In testing with AWS S3, the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

## 🚀 VFS Performance 🚀

These flags may be used to enable/disable features of the VFS for performance or other reasons 💅 See also the chunked reading feature.

In particular S3 and Swift benefit *hugely* from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect), since each read of the modification time takes a transaction 💸


Sometimes rclone is delivered reads or writes out of order 👀 Rather than seeking, rclone will wait a short time for the in-sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file:

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache 💖 (The related global flag `--checkers` has no effect on the VFS, ngl.)

--transfers int Number of file transfers to run in parallel (default 4)


## 🦋 Symlinks 🦋

By default the VFS does not support symlinks 🙈 However, this may be enabled with either of the following flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


Since most cloud storage systems don't support symlinks directly, rclone stores the symlink as a normal file with a special extension ✨ So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink`, and the contents would be the path to the symlink destination 💅

Note that `--links` enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the `local` backend) 🌍 `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with that used by the local backend with the `--local-links` flag 🤝

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs` 👑

It hasn't been tested with the other `rclone serve` commands yet 🧪

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks 😭 For example, given this directory tree

. ├── dir │ └── file.txt └── linked-dir -> dir


So like, the VFS *will* correctly resolve `linked-dir` but <red>NOT</red> `linked-dir/file.txt`. Is that a vibe killer? Not for the commands they tested, but it might bite other commands, ngl. 🙈

> Heads up bestie: there's a known issue with symlink support — issue **#8245** — where duplicate files get created when symlinks get moved into directories that already have a file of the same name (or the other way round). Not us being dramatic, that's just what happens. 💀

## 🌸 VFS Case Sensitivity 🌸

Okay so this part is giving *very* important energy, listen up. 🎀

Linux file systems are **case-sensitive**: two files can differ only by case, and you literally must use the exact case when opening a file. No shortcuts, no "close enough."

File systems on modern Windows are **case-insensitive but case-preserving**: you can open existing files with any case you want, but the exact case that was used when the file was created is preserved and available for programs to query. You are **not** allowed to have two files in the same directory that differ only by case.

macOS file systems are usually case-insensitive. Yeah you *can* make macOS file systems case-sensitive, but that's not the default, so don't expect it.

The **`--vfs-case-insensitive`** VFS flag controls how rclone handles these two situations. Let's break it down:

- If the value is `false`, rclone passes file names to the remote **as-is**. No editing, no touching up. ✨
- If the flag is `true` (or if it just shows up on the command line with no value at all), rclone may perform a "**fixup**," explained below.

The user can specify a file name to open/delete/rename/etc with a case **different** from what's stored on the remote. And here's the trick: if an argument refers to an existing file with **exactly the same name**, then the case of the existing file on the disk will be used. But if a file name with exactly the same name is *not* found, and a name differing **only by case** does exist, rclone will transparently fixup the name. 🪄

This fixup only happens when an existing file is requested, mmkay? Case sensitivity of file names created **anew** by rclone is controlled by the underlying remote.

> Lowkey important: case sensitivity of the operating system running rclone (the **target**) may differ from case sensitivity of the file system presented by rclone (the **source**). The flag controls whether that "fixup" happens so the target is satisfied. Two different things, don't mix them up bestie. 🫶

If the flag isn't provided on the command line, its default value depends on the operating system where rclone runs:

- `true` on Windows and macOS
- `false` otherwise

And if the flag *is* provided but with no value? Then it's `true`.

Now, the **`--no-unicode-normalization`** flag controls whether a similar "fixup" is done for filenames that differ but are **canonically equivalent** with respect to unicode. Unicode normalization is especially helpful for macOS girlies, because macOS prefers form **NFD** instead of the **NFC** that basically everyone else uses. So it is <hotpink>highly recommended</hotpink> to keep the default of `false` on macOS, to avoid encoding compatibility issues. Don't be a hero. 💅

In the (probably unlikely) event that a directory has multiple **duplicate** filenames after applying case and unicode normalization, the **`--vfs-block-norm-dupes`** flag lets you hide those duplicates. Cute, right? But — performance tradeoff incoming — rclone has to scan the **entire** directory for duplicates every time it lists a directory. So if you don't need it, leave it disabled. Simple as.

Though macOS users *may* want to consider using it, because otherwise: if a remote directory contains both **NFC** and **NFD** versions of the same filename, an odd situation occurs — both versions of the file will be visible in the mount, and both will appear to be editable, BUT editing either version will actually result in only the **NFD** version getting edited under the hood. 😭 Spooky. `--vfs-block-norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`. Slay.

## 🦋 VFS Disk Options 🦋

This flag lets you **manually** set the statistics about the filing system. Super useful when those statistics just cannot be read correctly automatically, iykyk.

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


## 💜 Alternate report of used bytes 💜

Some backends — most notably **S3** — do not report the amount of bytes used. Rude. 🙄

So if you need that info to be available when running `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report that info, rclone will scan the **whole remote** similar to `rclone size` and compute the total used space itself.

> <red>WARNING.</red> Contrary to `rclone size`, this flag **ignores filters** so that the result is accurate. But bestie, this is *very* inefficient and may cost **lots** of API calls, which means extra charges. 💸 Use it as a last resort, and only with caching. Periodt.

## 👑 Auth Proxy 👑

If you supply the parameter `--auth-proxy /path/to/program` then rclone will use that program to generate backends **on the fly**, which then get used to authenticate incoming requests. It's a simple JSON based protocol with input on `STDIN` and output on `STDOUT`. Very demure, very protocol. 🎀

> PLEASE NOTE: `--auth-proxy` and `--authorized-keys` **cannot** be used together. If `--auth-proxy` is set, the authorized keys option will be **ignored**. No cap.

There's an example program `bin/test_proxy.py` in the rclone source code if you wanna peek. 👀

So what's the program's job? It takes a `user` and `pass` on the input and turns those into the config for a backend on `STDOUT` in JSON format. That config will have any default parameters for the backend added, but it will **not** use configuration from environment variables or command line options — making a complete config is the proxy program's job, not rclone's. 🤝

The config generated **must** have this extra parameter:

- `_root` — root to use for the backend

And it **may** have this parameter:

- `_obscure` — comma separated strings for parameters to obscure

If password authentication was used by the client, input to the proxy process (on `STDIN`) would look similar to this:

{ "user": "me", "pass": "mypassword" }


If public-key authentication was used by the client, input to the proxy process (on `STDIN`) would look similar to this:

{ "user": "me", "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf" }


And as an example, it'd return this on `STDOUT`:

{ "type": "sftp", "_root": "", "_obscure": "pass", "user": "me", "pass": "mypassword", "host": "sftp.example.com" }


Which means: an **SFTP** backend would be created on the fly for the `user` and `pass`/`public_key` returned in the output, to the host given. ✨ And note that since `_obscure` is set to `pass`, rclone will **obscure** the `pass` parameter before creating the backend (which is required for sftp backends, so don't skip it).

The program can manipulate the supplied `user` in any way — for example, to make a proxy to many different sftp backends, you could make the user be `user@example.com` and then set the host to `example.com` in the output and the user to `user`. For security you'd *probably* want to restrict the host to a limited list. 🔐

> Note that an internal cache is keyed on `user`, so **only** use that for configuration — do **not** use `pass` or `public_key`. This also means that if a user's password or public-key is changed, the cache will need to expire (which takes **5 mins**) before it takes effect. Tick tock bestie. ⏰

This can be used to build general purpose proxies to **any** kind of backend that rclone supports. Main character energy fr fr. 💅

rclone serve http remote:path [flags]


---

## 🔧 Options

okay bestie, here's the whole flag buffet for real, no skips 💅

- **`--addr stringArray`** — the `IPaddress:Port`, `:Port` or `[unix://]/path/to/socket` you want the server bound to (default `[127.0.0.1:8080]`)
- **`--allow-origin string`** — the Origin that cross-domain requests (CORS) are allowed to come from
- **`--auth-proxy string`** — a program used to build the backend out of the auth
- **`--baseurl string`** — prefix for URLs, leave it blank if you want root
- **`--cert string`** — path to the TLS PEM public key certificate file (it can also hold intermediate/CA certificates, no cap)
- **`--client-ca string`** — path to a TLS PEM CA file with the certificate authorities used to verify clients
- **`--dir-cache-time Duration`** — how long directory entries get cached (default `5m0s`)
- **`--dir-perms FileMode`** — directory permissions (default `777`)
- **`--file-perms FileMode`** — file permissions (default `666`)
- **`--gid uint32`** — override the gid field the filesystem sets (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for `http`
- **`--htpasswd string`** — an htpasswd file; if you don't give one, literally no authentication happens 🙈
- **`--key string`** — path to the TLS PEM private key file
- **`--link-perms FileMode`** — link permissions (default `666`)
- **`--max-header-bytes int`** — biggest allowed size of a request header (default `4096`)
- **`--min-tls-version string`** — the lowest TLS version that's acceptable (default `"tls1.0"`)
- **`--no-checksum`** — don't compare checksums on up/download
- **`--no-modtime`** — don't read/write the modification time (can speed things up ✨)
- **`--no-seek`** — don't allow seeking in files
- **`--pass string`** — password for authentication
- **`--poll-interval Duration`** — how long to wait between polling for changes; it must be smaller than `dir-cache-time` and only works on supported remotes (set `0` to disable) (default `1m0s`)
- **`--read-only`** — only allow read-only access
- **`--realm string`** — realm for authentication
- **`--salt string`** — password hashing salt (default `"dlPL2MqE"`)
- **`--server-read-timeout Duration`** — timeout for the server reading data (default `1h0m0s`)
- **`--server-write-timeout Duration`** — timeout for the server writing data (default `1h0m0s`)
- **`--template string`** — a user-specified template
- **`--uid uint32`** — override the uid field the filesystem sets (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — override the permission bits the filesystem sets (not supported on Windows) (default `002`)
- **`--user string`** — user name for authentication
- **`--vfs-block-norm-dupes`** — if duplicate filenames live in the same directory (after normalization), log an error and hide the duplicates (may cost you performance)
- **`--vfs-cache-max-age Duration`** — max time since the last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — max total size of objects in the cache (default `off`)
- **`--vfs-cache-min-free-space SizeSuffix`** — target minimum free space on the disk holding the cache (default `off`)
- **`--vfs-cache-mode CacheMode`** — cache mode `off|minimal|writes|full` (default `off`)
- **`--vfs-cache-poll-interval Duration`** — interval for polling the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — if a file name isn't found, go find a case-insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — specify the total space of the disk (default `off`)
- **`--vfs-fast-fingerprint`** — use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — translate symlinks to/from regular files with a `.rclonelink` extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — extra read ahead over `--buffer-size` when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — if it's greater than `--vfs-read-chunk-size`, double the chunk size after every chunk read until you hit the limit (`'off'` means unlimited) (default `off`)
- **`--vfs-read-chunk-streams int`** — the number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — time to wait for an in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — use the `rclone size` algorithm for the Used size
- **`--vfs-write-back Duration`** — time to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — time to wait for an in-sequence write before throwing an error (default `1s`)

The options that are shared with other commands get described right below this. And for the global options that aren't listed here, go peek at the global flags page, bestie 🫶

---

## 🌸 Filter Options 🌸

these are the flags for filtering your directory listings, icons only ✨

- **`--delete-excluded`** — delete files on dest that got excluded from the sync
- **`--exclude stringArray`** — exclude files matching a pattern
- **`--exclude-from stringArray`** — read file exclude patterns from a file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — exclude directories if the filename is present
- **`--files-from stringArray`** — read the list of source-file names from a file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — read the list of source-file names from a file with zero processing of the lines (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule
- **`--filter-from stringArray`** — read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — ignore case in filters (case insensitive, duh)
- **`--include stringArray`** — include files matching a pattern
- **`--include-from stringArray`** — read file include patterns from a file (use `-` to read from stdin)
- **`--max-age Duration`** — only transfer files younger than this, in `s` or with an `ms|s|m|h|d|w|M|y` suffix (default `off`)
- **`--max-depth int`** — if set, limits the recursion depth to this (default `-1`)
- **`--max-size SizeSuffix`** — only transfer files smaller than this, in `KiB` or with a `B|K|M|G|T|P` suffix (default `off`)
- **`--metadata-exclude stringArray`** — exclude metadatas matching a pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — include metadatas matching a pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` to read from stdin)
- **`--min-age Duration`** — only transfer files older than this, in `s` or with an `ms|s|m|h|d|w|M|y` suffix (default `off`)
- **`--min-size SizeSuffix`** — only transfer files bigger than this, in `KiB` or with a `B|K|M|G|T|P` suffix (default `off`)

---

## 👀 See Also 👀

- **`rclone serve`** — Serve a remote over a protocol.

---

# 🧚 rclone serve nfs 🧚

Serve the remote as an NFS mount — yes ma'am, NFS, we're doing it 💖

## 📖 Synopsis 📖

Create an NFS server that serves the given remote over the network. It's giving "your remote, but make it mountable."

This implements an NFSv3 server to serve any rclone remote via NFS.

The main character reason this command even exists is so the mount command can work on recent macOS versions, where installing FUSE is, like, soooo cumbersome 😭.

> Real talk: this server does **not** implement any authentication at all, so literally any client can get at your data. To limit access you can run `serve nfs` on the loopback address, or rely on secure tunnels (such as SSH), or use firewalling. Periodt.

For that exact reason, by default a random TCP port gets chosen and the loopback interface is used as the listening address — meaning it's only available to the local machine. If you want other machines to reach the NFS mount over the local network, you have to specify the listening address and port yourself with the `--addr` flag.

Modifying files through the NFS protocol requires VFS caching. Usually you'll need to specify `--vfs-cache-mode` in order to be able to write to the mountpoint (`full` is recommended). If you don't specify a VFS cache mode, the mount will be read-only.

`--nfs-cache-type` controls what type of NFS handle cache you get. By default this is `memory`, where new handles get randomly allocated whenever they're needed 🙈 These get stored in memory. So if the server restarts, the handle cache is gone and connected NFS clients start getting stale handle errors.

`--nfs-cache-type disk` uses an on-disk NFS handle cache. Rclone hashes the path of the object and stores it in a file named after the hash. These hashes live on disk in the directory controlled by `--cache-dir`, or you can name the exact directory with `--nfs-cache-dir`. Using this means the NFS server can be restarted whenever you want without affecting the connected clients 👑

`--nfs-cache-type symlink` is similar to `--nfs-cache-type disk` in that it uses an on-disk cache, but the cache entries are held as symlinks. Rclone uses the handle of the underlying file as the NFS handle, which improves performance. This sort of cache can't be backed up and restored, because the underlying handles will change. It's Linux only, and it requires running rclone as root or with `CAP_DAC_READ_SEARCH`. You can give rclone that extra permission by doing this to the rclone binary:

sudo setcap cap_dac_read_search+ep /path/to/rclone


`--nfs-cache-handle-limit` controls the maximum number of cached NFS handles the caching handler will store. Don't set this too low or you may hit errors when trying to access files 😬 The default is `1000000`, but consider lowering this limit if the server's system resource usage starts causing problems. This is only used by the `memory` type cache.

To serve NFS over the network, use the following command:

rclone serve nfs remote: --addr 0.0.0.0:$PORT --vfs-cache-mode=full


---

This is the port you can flex in the mount command, bestie. Wanna mount the server on Linux/macOS? Say less:

mount -t nfs -o port=$PORT,mountport=$PORT,tcp $HOSTNAME:/ path/to/mountpoint


<pink>`$PORT`</pink> is the exact same port number you used in the `serve nfs` command, and <pink>`$HOSTNAME`</pink> is the network address of the machine that `serve nfs` was running on. Matchy-matchy, that's the vibe. ✨

> 🚨 Real talk: this command is **only available on Unix platforms**. Windows girlies, this ain't for you, sorry not sorry. 💀

### VFS - Virtual File System 🦋

Okay so this command rides the VFS layer. What's VFS? It's the glow-up that turns the cloud storage objects rclone uses into something that actually looks like a disk filing system. Main character energy fr.

But here's the tea: cloud storage objects have a LOT of properties that are just NOT like disk files. You can't extend them, you can't write to the middle of them, and the VFS layer has to deal with all of that drama. And because there is literally no one right way of doing it, there are a bunch of options explained below. Pick your fighter. 💅

Oh and the VFS layer also implements a **directory cache** — this caches info about files and directories (but *not* the data, don't get it twisted) in memory.

### VFS Directory Cache 🎀

Using the `--dir-cache-time` flag, you get to control how long a directory is considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately or invalidate the cache. Iconic behaviour.


But watch out — changes made *directly* on the cloud storage, like through the web interface or a different copy of rclone, will only be picked up once the directory cache expires, **if** the backend you configured doesn't support polling for changes. If the backend *does* support polling, changes get picked up within the polling interval. No cap. 🔥

You can send a `SIGHUP` signal to rclone to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or just individual files or directories if you're being picky about it:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


### VFS File Buffering 🌸

The `--buffer-size` flag determines the amount of memory that'll be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. And the buffered data is bound to one open file — it won't be shared. Every file is its own independent queen. 👑

This flag is an upper limit for the used memory *per open file*. The buffer will only use memory for data that is downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used — she's chill like that.

The maximum memory used by rclone for buffering can be up to `--buffer-size` * open files.

### VFS File Caching 💖

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system, and it can be disabled at the cost of some compatibility. Trade-offs, babe.

For example you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details.

> ✨ Note that the VFS cache is separate from the cache backend and you may find that you need one or the other or both. Two different things, both valid, both slaying.


If run with `-vv` rclone will print the location of the file cache. The files are stored in the user cache file area which is OS dependent but can be controlled with `--cache-dir` or setting the appropriate environment variable. You got options, bestie.

The cache has **4** different modes selected by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. Everything in life is a trade-off smh.

Note that files are written back to the remote **only when they are closed** and if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. She remembers. 🫶

If using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, note that the cache may exceed these quotas for two reasons. Firstly because it is only checked every `--vfs-cache-poll-interval`. Secondly because open files cannot be evicted from the cache. When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. rclone will start with files that haven't been accessed for the longest. This cache flushing strategy is efficient and more relevant files are likely to remain cached. Smart AND pretty. 💅

The `--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of **1 hour** will start evicting files from cache that haven't been accessed for 1 hour. When a cached file is accessed the 1 hour timer is reset to 0 and will wait for 1 more hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> 💀 DANGER ZONE: You should **not** run two copies of rclone using the same VFS cache with the same or overlapping remotes if using `--vfs-cache-mode > off`. This can potentially cause **data corruption** if you do. You can work around this by giving each rclone its own cache hierarchy with `--cache-dir`. You don't need to worry about this if the remotes in use don't overlap. Periodt.

### –vfs-cache-mode off 🍓

In this mode (the **default**) the cache will read directly from the remote and write directly to the remote without caching anything on disk. Zero disk drama, but it comes at a price.

This will mean some operations are not possible:

- Files can't be opened for both read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

### –vfs-cache-mode minimal 🌈

This is very similar to "off" except that files opened for read AND write will be buffered to disk. This means that files opened for write will be a lot more compatible, but it uses the minimal disk space. Efficiency queen. ✨

These operations are not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

### –vfs-cache-mode writes 🎀

In this mode, files opened for read only are still read directly from the remote — but write only and read/write files are buffered to disk first.

This mode should support all normal file system operations. She's versatile like that.

If an upload fails it will be retried at exponentially increasing intervals up to **1 minute**.

### –vfs-cache-mode full 👑

In this mode, all reads and writes are buffered to and from disk. When data is read from the remote this is buffered to disk as well. Full commitment, no half measures.

In this mode the files in the cache will be **sparse files** and rclone will keep track of which bits of the files it has downloaded.

So if an application only reads the starts of each file, then rclone will only buffer the start of the file. These files will appear to be their full size in the cache, but they're sparse files with only the data that has been downloaded present in them. Illusion, but make it storage-efficient. 💅

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> 😭 **IMPORTANT: not all file systems support sparse files.** In particular `FAT/exFAT` do not. Rclone will perform very badly if the cache directory is on a filesystem which doesn't support sparse files and it will log an `ERROR` message if one is detected. Consider yourself warned, bestie.

### Fingerprinting 🧚

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

— where available on an object.

On some backends some of these attributes are slow to read (they take an extra API call per object, or extra work per object). Ugh, the audacity.

For example `hash` is slow with the `local` and `sftp` backends as they have to read the entire file and hash it, and `modtime` is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will not include the slow operations in the fingerprint. This makes the fingerprinting less accurate but much faster and will improve the opening time of cached files. Speed over precision, we love to see it. 🔥

If you are running a vfs cache over `local`, `s3` or `swift` backends then using this flag is **recommended**.

> ⭐ Note that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again. So maybe don't flip-flop on it, okay?

### VFS Chunked Reading 💜

When rclone reads files from a remote it reads them in **chunks**. This means that rather than requesting the whole file, rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read — at the cost of an increased number of requests. Small sips, not the whole drink. 🍓

These flags control the chunking:


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter.

### `--vfs-read-chunk-streams == 0` 🌸

Bestie, here's the tea ☕ — rclone starts by reading one chunk that's exactly `--vfs-read-chunk-size` big, and then it **doubles** that size on every single read. And if you've set `--vfs-read-chunk-size-limit` *and* it's bigger than `--vfs-read-chunk-size`, then the chunk size for each open file keeps doubling and doubling — but only until it hits that limit. If the value is `off` (which, heads up, is the default 💅), then there's no limit at all and the chunk size just grows forever, no cap, no chill.

So with `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0`, the parts that get downloaded are: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on, forever. But when you set `--vfs-read-chunk-size-limit 500M` instead, you'd get 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so on. She grows, she stops. Iconic. ✨

Set `--vfs-read-chunk-size` to `0` or `off` and chunked reading is just **off**, periodt.

> Also important: the chunks are **not** buffered in memory. No hoarding, no storage, she streams and moves on.

### `--vfs-read-chunk-streams > 0` 🔥

Now THIS is the glow-up. When this is greater than `0`, rclone reads `--vfs-read-chunk-streams` chunks **concurrently**, each one `--vfs-read-chunk-size` big. And the size for each read just stays constant — no doubling shenanigans.

This massively improves performance on high latency links, or on very high bandwidth links to high performance object stores. It's giving main character energy for your throughput fr fr.

Ngl you're gonna need to do some experimentation to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams`, because both of them depend on the backend you're using and the latency to that backend. Science, bestie 🧚

For high performance object stores (eg AWS S3), a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

---

## VFS Performance 👑

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature.

In particular S3 and Swift benefit hugely from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect) as each read of the modification time takes a transaction. Every. Single. Time. 😭


Sometimes rclone is delivered reads or writes out of order. Rather than seeking, rclone will wait a short time for the in-sequence read or write to come in. These flags only come into effect when not using an on disk cache file.

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has **no** effect on the VFS). Yeah, none. Don't bother. 💀

--transfers int Number of file transfers to run in parallel (default 4)


---

## Symlinks 🦋

By default the VFS does not support symlinks. But babes, you can turn that on with either of these flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


Since most cloud storage systems don't support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file that shows up as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink`, and the contents of that file would be the path to the symlink destination. Cute, right? 💖

Note that `--links` enables symlink translation **globally** in rclone — and that includes any backend which supports the concept (for example the local backend). `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with that used by the local backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet. 🙈

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but **not** `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands.

> Note that there's an outstanding issue with symlink support, issue #8245, with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). Keep an eye on it 👀

---

## VFS Case Sensitivity 🌈

Linux file systems are **case-sensitive**: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are **case-insensitive but case-preserving**: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It *is* possible to make macOS file systems case-sensitive but that is not the default.

The `--vfs-case-insensitive` VFS flag controls how rclone handles these two cases. If its value is `false`, rclone passes file names to the remote as-is. If the flag is `true` (or appears without a value on the command line), rclone may perform a "fixup" as explained below.

The user may specify a file name to open/delete/rename/etc with a case different than what is stored on the remote. If an argument refers to an existing file with exactly the same name, then the case of the existing file on the disk will be used. However, if a file name with exactly the same name is not found but a name differing only by case exists, rclone will transparently fixup the name. This fixup happens only when an existing file is requested. Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

Note that case sensitivity of the operating system running rclone (the target) may differ from case sensitivity of a file system presented by rclone (the source). The flag controls whether "fixup" is performed to satisfy the target.

If the flag is not provided on the command line, then its default value depends on the operating system where rclone runs: `true` on Windows and macOS, `false` otherwise. If the flag is provided without a value, then it is `true`.

The `--no-unicode-normalization` flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent with respect to unicode. Unicode normalization can be particularly helpful for users of macOS, which prefers form NFD instead of the NFC used by most other platforms. It is therefore highly recommended to keep the default of `false` on macOS, to avoid encoding compatibility issues. Bestie, just leave it. 😌

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag allows hiding these duplicates. This comes with a performance tradeoff, as rclone will have to scan the entire directory for duplicates when listing a directory. For this reason, it is recommended to leave this disabled if not needed. However, macOS users may wish to consider using it, as otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation will occur: both versions of the file will be visible in the mount, and both will appear to be editable, however, editing either version will actually result in only the **NFD** version getting edited under the hood. `--vfs-block-norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`. Not me getting gaslit by my own mount 💀

---

## VFS Disk Options 💾

This flag allows you to manually set the statistics about the filing system. It can be useful when those statistics cannot be read correctly automatically.

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


---

## Alternate report of used bytes 🍓

Some backends, most notably S3, do not report the amount of bytes used. If you need this information to be available when running `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself.

> **WARNING.** Contrary to `rclone size`, this flag ignores filters so that the result is accurate. However, this is **very inefficient** and may cost lots of API calls resulting in extra charges. Use it as a last resort and only with caching. Please bestie, I'm begging, don't rawdog your API bill 😭

rclone serve nfs remote:path [flags]


### 🌸 OPTIONS 🌸

okay bestie, here's the full menu of nfs knobs, and yes, you're gonna read all of them 💅

- **`--addr string`** — the <cyan>IPaddress:Port</cyan> or <cyan>:Port</cyan> you want the server bound to. that's it, that's the whole vibe.
- **`--dir-cache-time Duration`** — how long directory entries get to chill in the cache (default <hotpink>`5m0s`</hotpink>) ✨
- **`--dir-perms FileMode`** — permissions that directories get (default <hotpink>`777`</hotpink>)
- **`--file-perms FileMode`** — permissions that files get (default <hotpink>`666`</hotpink>)
- **`--gid uint32`** — overrides the `gid` field that the filesystem set (not supported on Windows, sorry windows girlies 😭) (default <hotpink>`1000`</hotpink>)
- **`-h`, `--help`** — help for nfs, the classic 🫶
- **`--link-perms FileMode`** — permissions for links (default <hotpink>`666`</hotpink>)
- **`--nfs-cache-dir string`** — the directory the NFS handle cache uses, if you set it. if you don't, it just does its own thing ✨
- **`--nfs-cache-handle-limit int`** — max file handles cached at the same time, and heads up, the minimum is 5 (default <hotpink>`1000000`</hotpink>)
- **`--nfs-cache-type memory|disk|symlink`** — what kind of NFS handle cache you want to use (default <hotpink>`memory`</hotpink>)
- **`--no-checksum`** — no comparing checksums on up/download. skipping the math, love that for you 🦋
- **`--no-modtime`** — don't read or write the modification time, which can speed things up (main character efficiency ✨)
- **`--no-seek`** — don't allow seeking in files. no scrubbing, it's giving linear only 💀
- **`--poll-interval Duration`** — how long to wait between polling for changes. important: it **must** be smaller than `dir-cache-time`, and it only works on supported remotes (set it to 0 to disable it entirely) (default <hotpink>`1m0s`</hotpink>)
- **`--read-only`** — only allow read-only access. nobody's touching anything 🔒
- **`--uid uint32`** — overrides the `uid` field the filesystem set (not supported on Windows) (default <hotpink>`1000`</hotpink>)
- **`--umask FileMode`** — override the permission bits the filesystem set (not supported on Windows) (default <hotpink>`002`</hotpink>)
- **`--vfs-block-norm-dupes`** — if duplicate filenames exist in the same directory (after normalization), it logs an error and hides the dupes. fair warning: it may have a performance cost 😬
- **`--vfs-cache-max-age Duration`** — max time since last access of objects in the cache (default <hotpink>`1h0m0s`</hotpink>)
- **`--vfs-cache-max-size SizeSuffix`** — max total size of objects in the cache (default <hotpink>`off`</hotpink>)
- **`--vfs-cache-min-free-space SizeSuffix`** — target minimum free space on whatever disk is holding the cache (default <hotpink>`off`</hotpink>)
- **`--vfs-cache-mode CacheMode`** — cache mode, and the options are <cyan>`off|minimal|writes|full`</cyan> (default <hotpink>`off`</hotpink>)
- **`--vfs-cache-poll-interval Duration`** — how often to poll the cache for stale objects (default <hotpink>`1m0s`</hotpink>)
- **`--vfs-case-insensitive`** — if a file name isn't found, go find a case insensitive match instead 🔍
- **`--vfs-disk-space-total-size SizeSuffix`** — specify the total space of the disk (default <hotpink>`off`</hotpink>)
- **`--vfs-fast-fingerprint`** — use fast, less accurate fingerprints for change detection. speed over precision, a tradeoff bestie ✨
- **`--vfs-links`** — translate symlinks to/from regular files with a <cyan>'.rclonelink'</cyan> extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — extra read ahead on top of `--buffer-size` when you're using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — read the source objects in chunks (default <hotpink>`128Mi`</hotpink>)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — if this is greater than `--vfs-read-chunk-size`, the chunk size doubles after each chunk read until it hits the limit (<cyan>`'off'`</cyan> means unlimited) (default <hotpink>`off`</hotpink>)
- **`--vfs-read-chunk-streams int`** — how many parallel streams to read at once 🌈
- **`--vfs-read-wait Duration`** — how long to wait for an in-sequence read before seeking (default <hotpink>`20ms`</hotpink>)
- **`--vfs-refresh`** — refreshes the directory cache recursively in the background on start. it's giving proactive 💅
- **`--vfs-used-is-size rclone size`** — use the `rclone size` algorithm for the Used size
- **`--vfs-write-back Duration`** — time to writeback files after last use when using cache (default <hotpink>`5s`</hotpink>)
- **`--vfs-write-wait Duration`** — time to wait for an in-sequence write before it gives you an error (default <hotpink>`1s`</hotpink>)

---

Options shared with other commands are described next. and if you're looking for global options that aren't listed here, go check the global flags page, okay? 🫶

### 🎀 Filter Options 🎀

flags for filtering directory listings — aka, you get to be picky about what shows up, and honestly, good for you 👑

- **`--delete-excluded`** — delete files on dest that were excluded from sync
- **`--exclude stringArray`** — exclude files matching a pattern
- **`--exclude-from stringArray`** — read file exclude patterns from a file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — exclude directories if that filename is present
- **`--files-from stringArray`** — read a list of source-file names from a file (use `-` to read from stdin)
- **`--files-from-raw stringArray`** — read a list of source-file names from a file **without any processing of lines** (use `-` to read from stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule
- **`--filter-from stringArray`** — read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — ignore case in filters (case insensitive, obviously 💅)
- **`--include stringArray`** — include files matching a pattern
- **`--include-from stringArray`** — read file include patterns from a file (use `-` to read from stdin)
- **`--max-age Duration`** — only transfer files younger than this, in `s` or with a suffix of `ms|s|m|h|d|w|M|y` (default <hotpink>`off`</hotpink>)
- **`--max-depth int`** — if set, limits the recursion depth to this (default <hotpink>`-1`</hotpink>)
- **`--max-size SizeSuffix`** — only transfer files smaller than this, in `KiB` or with a suffix of `B|K|M|G|T|P` (default <hotpink>`off`</hotpink>)
- **`--metadata-exclude stringArray`** — exclude metadatas matching a pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — include metadatas matching a pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` to read from stdin)
- **`--min-age Duration`** — only transfer files older than this, in `s` or with a suffix of `ms|s|m|h|d|w|M|y` (default <hotpink>`off`</hotpink>)
- **`--min-size SizeSuffix`** — only transfer files bigger than this, in `KiB` or with a suffix of `B|K|M|G|T|P` (default <hotpink>`off`</hotpink>)

### 👑 See Also 👑

- `rclone serve` — Serve a remote over a protocol.

# 💖 `rclone serve restic` 💖

Serve the remote for restic's REST API. Yes bestie, you read that right, rclone is about to become a whole backup backend. 🎀

---

## ✨ Synopsis ✨

Run a basic web server to serve a remote over restic's REST backend API over HTTP. This allows restic to use rclone as a data storage mechanism for cloud providers that restic does not support directly. 🦋

Restic is a command-line program for doing backups. And now it can back its whole self onto *your* rclone remote. Iconic behavior, honestly.

The server will log errors. Use `-v` to see access logs. 👀

`--bwlimit` will be respected for file transfers. Use `--stats` to control the stats printing. ✨

---

## 🌸 Setting up rclone for use by restic 🌸

First set up a remote for your chosen cloud provider. That's the whole vibe, step one.

Once you have set up the remote, check it is working with, for example `rclone lsd remote:`. You may have called the remote something other than `remote:` - just substitute whatever you called it in the following instructions. No cap, just swap the name. 💅

Now start the rclone restic server

rclone serve restic -v remote:backup


Where you can replace `backup` in the above by whatever path in the remote you wish to use.

By default this will serve on `localhost:8080` you can change this with use of the `--addr` flag.

You might wish to start this server on boot. Lowkey a good idea tbh.

Adding `--cache-objects=false` will cause rclone to stop caching objects returned from the List call. Caching is normally desirable as it speeds up downloading objects, saves transactions and uses very little memory. So like, only turn it off if you have a reason?? 🙈

---

## 🦋 Setting up restic to use rclone 🦋

Now you can follow the restic instructions on setting up restic.

Note that you will need restic 0.8.2 or later to interoperate with rclone. Old restic? It's not going to work, bestie. Get the upgrade. 😭

For the example above you will want to use `http://localhost:8080/` as the URL for the REST server.

For example:

$ export RESTIC_REPOSITORY=rest:http://localhost:8080/ $ export RESTIC_PASSWORD=yourpassword $ restic init created restic backend 8b1a4b56ae at rest:http://localhost:8080/

Please note that knowledge of your password is required to access the repository. Losing your password means that your data is irrecoverably lost. $ restic backup /path/to/files/to/backup scan [/path/to/files/to/backup] scanned 189 directories, 312 files in 0:00 [0:00] 100.00% 38.128 MiB / 38.128 MiB 501 / 501 items 0 errors ETA 0:00 duration: 0:00 snapshot 45c8fdd8 saved


Look at that `snapshot 45c8fdd8 saved` — that's your data surviving. Main character energy fr fr. 💖

---

## 🎀 Multiple repositories 🎀

Note that you can use the endpoint to host multiple repositories. Do this by adding a directory name or path after the URL. Note that these **must** end with `/`. Eg

$ export RESTIC_REPOSITORY=rest:http://localhost:8080/user1repo/

backup user1 stuff

$ export RESTIC_REPOSITORY=rest:http://localhost:8080/user2repo/

backup user2 stuff


One server, many repos. We love a multitasker. 👑

---

## 💜 Private repositories 💜

The `--private-repos` flag can be used to limit users to repositories starting with a path of `/<username>/`.

---

## ⭐ Server options ⭐

Use `--addr` to specify which IP address and port the server should listen on, eg `--addr 1.2.3.4:8000` or `--addr :8080` to listen to all IPs. By default it only listens on localhost. You can use port `:0` to let the OS choose an available port.

> If you set `--addr` to listen on a public or LAN accessible IP address then using Authentication is advised - see the next section for info. 🔥 Don't be out here exposing your backups to the whole internet, bestie.

You can use a unix socket by setting the url to `unix:///path/to/socket` or just by using an absolute path name.

`--addr` may be repeated to listen on multiple IPs/ports/sockets. Socket activation, described further below, can also be used to accomplish the same.

`--server-read-timeout` and `--server-write-timeout` can be used to control the timeouts on the server. Note that this is the total time for a transfer.

`--max-header-bytes` controls the maximum number of bytes the server will accept in the HTTP header.

`--baseurl` controls the URL prefix that rclone serves from. By default rclone will serve from the root. If you used `--baseurl "/rclone"` then rclone would serve from a URL starting with `/rclone/`. This is useful if you wish to proxy rclone serve. Rclone automatically inserts leading and trailing `/` on `--baseurl`, so `--baseurl "rclone"`, `--baseurl "/rclone"` and `--baseurl "/rclone/"` are all treated identically. So chill, it's not gonna fight you about slashes. 🫶

---

## 🔒 TLS (SSL) 🔒

By default this will serve over http. If you want you can serve over https. You will need to supply the `--cert` and `--key` flags. If you wish to do client side certificate validation then you will need to supply `--client-ca` also.

`--cert` must be set to the path of a file containing either a PEM encoded certificate, or a concatenation of that with the CA certificate. `--key` must be set to the path of a file with the PEM encoded private key. If setting `--client-ca`, it should be set to the path of a file with PEM encoded client certificate authority certificates.

`--min-tls-version` is minimum TLS version that is acceptable. Valid values are `tls1.0`, `tls1.1`, `tls1.2` and `tls1.3` (default `tls1.0`).

---

## 🌈 Socket activation 🌈

Instead of the listening addresses specified above, rclone will listen to all FDs passed by the service manager, if any (and ignore any arguments passed by `--addr`).

This allows rclone to be a socket-activated service. It can be configured with `.socket` and `.service` unit files as described in `https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html`

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command

systemd-socket-activate -l 8000 -- rclone serve


This will socket-activate rclone on the first connection to port 8000 over TCP. 🧚

---

## 🍓 Authentication 🍓

By default this will serve files without needing a login. (Which is fine on localhost, less fine elsewhere. You know the vibe.)

You can either use an htpasswd file which can take lots of users, or set a single username and password with the `--user` and `--pass` flags.

If no static users are configured by either of the above methods, and client certificates are required by the `--client-ca` flag passed to the server, the client certificate common name will be considered as the username.

Use `--htpasswd /path/to/htpasswd` to provide an htpasswd file. This is in standard apache format and supports MD5, SHA1 and BCrypt for basic authentication. Bcrypt is recommended. 💅

To create an htpasswd file:

touch htpasswd htpasswd -B htpasswd user htpasswd -B htpasswd anotherUser


The password file can be updated while rclone is running. Live updates, we love to see it. ✨

Use `--realm` to set the authentication realm.

Use `--salt` to change the password hashing salt from the default.

rclone serve restic remote:path [flags]


---

## 💅 Options 💅

- **`--addr stringArray`** — IPaddress:Port, :Port or [unix://]/path/to/socket to bind server to (default `[127.0.0.1:8080]`)
- **`--allow-origin string`** — Origin which cross-domain request (CORS) can be executed from
- **`--append-only`** — Disallow deletion of repository data
- **`--baseurl string`** — Prefix for URLs - leave blank for root
- **`--cache-objects`** — Cache listed objects (default `true`)
- **`--cert string`** — Path to TLS PEM public key certificate file (can also include intermediate/CA certificates)
- **`--client-ca string`** — Path to TLS PEM CA file with certificate authorities to verify clients with
- **`-h`, `--help`** — help for restic
- **`--htpasswd string`** — A htpasswd file - if not provided no authentication is done
- **`--key string`** — Path to TLS PEM private key file
- **`--max-header-bytes int`** — Maximum size of request header (default `4096`)
- **`--min-tls-version string`** — Minimum TLS version that is acceptable (default `"tls1.0"`)
- **`--pass string`** — Password for authentication
- **`--private-repos`** — Users can only access their private repo
- **`--realm string`** — Realm for authentication
- **`--salt string`** — Password hashing salt (default `"dlPL2MqE"`)
- **`--server-read-timeout Duration`** — Timeout for server reading data (default `1h0m0s`)
- **`--server-write-timeout Duration`** — Timeout for server writing data (default `1h0m0s`)
- **`--stdio`** — Run an HTTP2 server on stdin/stdout
- **`--user string`** — User name for authentication

See the global flags page for global options not listed here. 👑

---

## 👀 See Also 👀

- `rclone serve` - Serve a remote over a protocol.

---

# 🔥 `rclone serve s3` 🔥

Serve `remote:path` over s3. Okay this one is genuinely so fun.

---

## ✨ Synopsis ✨

`serve s3` implements a basic s3 server that serves a remote via s3. This can be viewed with an s3 client, or you can make an s3 type remote to read and write to it with rclone. 🦋

> `serve s3` is considered **Experimental** so use with care. Bestie. Please. It's in the name. 🙈

S3 server supports Signature Version 4 authentication. Just use `--auth-key accessKey,secretKey` and set the Authorization header correctly in the request. (See the AWS docs).

`--auth-key` can be repeated for multiple auth pairs. If `--auth-key` is not provided then `serve s3` will allow anonymous access. (Anonymous! Just letting anyone in! Vibe check says be careful. 💀)

Please note that some clients may require HTTPS endpoints. See the SSL docs for more information.

This command uses the VFS directory cache. All the functionality will work with `--vfs-cache-mode off`. Using `--vfs-cache-mode full` (or writes) can be used to cache objects locally to improve performance.

Use `--force-path-style=false` if you want to use the bucket name as a part of the hostname (such as `mybucket.local`)

Use `--etag-hash` if you want to change the hash uses for the ETag. Note that using anything other than MD5 (the default) is likely to cause problems for S3 clients which rely on the Etag being the MD5. Note the exact wording there — **likely to cause problems**, so don't come crying to me. 😭

---

## 🌸 Quickstart 🌸

For a simple set up, to serve `remote:path` over s3, run the server like this:

rclone serve s3 --auth-key ACCESS_KEY_ID,SECRET_ACCESS_KEY remote:path


For example, to use a simple folder in the filesystem, run the server with a command like this:

rclone serve s3 --auth-key ACCESS_KEY_ID,SECRET_ACCESS_KEY local:/path/to/folder


The `rclone.conf` for the server could look like this:

[local] type = local


The local configuration is optional though. If you run the server with a `remote:path` like `/path/to/folder` (without the `local:` prefix and without an `rclone.conf` file), rclone will fall back to a default configuration, which will be visible as a warning in the logs. But it will run nonetheless. She's resilient like that. 💅

This will be compatible with an rclone (client) remote configuration which is defined like this:

[serves3] type = s3 provider = Rclone endpoint = http://127.0.0.1:8080/ access_key_id = ACCESS_KEY_ID secret_access_key = SECRET_ACCESS_KEY use_multipart_uploads = false


lowkey important note bestie: setting `use_multipart_uploads = false` is there to work around a bug 🐛 which will be fixed in due course, okurrr.

---

### 💀 Bugs 💀

When you're uploading multipart files, `serve s3` holds **all the parts in memory** (check issue #7453 for the receipts 📝). This is a limitation of the library rclone uses for serving S3, and hopefully it gets fixed at some point. fingers crossed 🫶

Multipart server side copies **do not work** (see #7454 📌). These take a *very* long time and eventually fail 💀. The default threshold for multipart server side copies is `5G`, which is the maximum it can be, so files above this size will fail to be server side copied. the way that's just the ceiling, no wiggle room 😭

For a current list of `serve s3` bugs see the *serve s3 bug category* on GitHub.

### 🌸 Limitations 🌸

`serve s3` will treat **all directories in the root as buckets** and ignore all files in the root. You can use `CreateBucket` to create folders under the root, but you can't create empty folders under other folders not in the root. that's just how it is ✨

When using `PutObject` or `DeleteObject`, rclone will automatically create or clean up empty folders. If you don't want it cleaning up empty folders automatically, use `--no-cleanup`.

When using `ListObjects`, rclone will use `/` when the delimiter is empty. This reduces backend requests with no effect on most operations, but if the delimiter is something other than `/` and empty, rclone will do a full recursive search of the backend, which can take some time ⏳. so like, heads up.

Versioning is **not currently supported**. 🚫

Metadata will only be saved in memory — other than the rclone mtime metadata, which will be set as the modification time of the file.

### 👑 Supported operations 👑

`serve s3` currently supports the following operations.

- **Bucket**
  - `ListBuckets`
  - `CreateBucket`
  - `DeleteBucket`
- **Object**
  - `HeadObject`
  - `ListObjects`
  - `GetObject`
  - `PutObject`
  - `DeleteObject`
  - `DeleteObjects`
  - `CreateMultipartUpload`
  - `CompleteMultipartUpload`
  - `AbortMultipartUpload`
  - `CopyObject`
  - `UploadPart`

Any other operations will return error `Unimplemented`. sorry babes, that's the boundary 💅

### 🔐 Authentication 🔐

By default this will serve files without needing a login. wide open, no gatekeeping 🚪

You can either use an **htpasswd** file, which can take lots of users, or set a single username and password with the `--user` and `--pass` flags.

If no static users are configured by either of the above methods, and client certificates are required by the `--client-ca` flag passed to the server, the client certificate common name will be considered as the username.

Use `--htpasswd /path/to/htpasswd` to provide an htpasswd file. This is in standard apache format and supports **MD5**, **SHA1** and **BCrypt** for basic authentication. Bcrypt is recommended. (bcrypt ate, no crumbs 💅)

To create an htpasswd file:

touch htpasswd htpasswd -B htpasswd user htpasswd -B htpasswd anotherUser


The password file can be updated while rclone is running. live edits, we love to see it ✨

Use `--realm` to set the authentication realm.

Use `--salt` to change the password hashing salt from the default.

### 🖥️ Server options 🖥️

Use `--addr` to specify which IP address and port the server should listen on, eg `--addr 1.2.3.4:8000` or `--addr :8080` to listen to all IPs. By default it only listens on <cyan>localhost</cyan>. You can use port `:0` to let the OS choose an available port. let the OS pick, she's got taste 💁‍♀️

If you set `--addr` to listen on a public or LAN accessible IP address then using Authentication is advised — see the next section for info.

> bestie, real talk: exposing this on a public/LAN IP without auth is giving yikes 😬 go read the Authentication section.

You can use a **unix socket** by setting the url to `unix:///path/to/socket` or just by using an absolute path name.

`--addr` may be repeated to listen on multiple IPs/ports/sockets. Socket activation, described further below, can also be used to accomplish the same.

`--server-read-timeout` and `--server-write-timeout` can be used to control the timeouts on the server. Note that this is the **total time for a transfer**.

`--max-header-bytes` controls the maximum number of bytes the server will accept in the HTTP header.

`--baseurl` controls the URL prefix that rclone serves from. By default rclone will serve from the root. If you used `--baseurl "/rclone"` then rclone would serve from a URL starting with `/rclone/`. This is useful if you wish to proxy rclone serve. Rclone automatically inserts leading and trailing `/` on `--baseurl`, so `--baseurl "rclone"`, `--baseurl "/rclone"` and `--baseurl "/rclone/"` are all treated identically. same thing, three outfits, iconic 🎀

### 🔒 TLS (SSL) 🔒

By default this will serve over **http**. If you want you can serve over **https**. You will need to supply the `--cert` and `--key` flags. If you wish to do client side certificate validation then you will need to supply `--client-ca` also.

`--cert` must be set to the path of a file containing either a PEM encoded certificate, or a concatenation of that with the CA certificate. `--key` must be set to the path of a file with the PEM encoded private key. If setting `--client-ca`, it should be set to the path of a file with PEM encoded client certificate authority certificates.

`--min-tls-version` is minimum TLS version that is acceptable. Valid values are `tls1.0`, `tls1.1`, `tls1.2` and `tls1.3` (default `tls1.0`).

### 🔌 Socket activation 🔌

Instead of the listening addresses specified above, rclone will listen to all FDs passed by the service manager, if any (and **ignore any arguments passed by `--addr`**). yeah, ignore, it said what it said 💅

This allows rclone to be a socket-activated service. It can be configured with `.socket` and `.service` unit files as described in `https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html`

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command

systemd-socket-activate -l 8000 -- rclone serve


This will socket-activate rclone on the first connection to port 8000 over TCP.

---

# 🦋 VFS - Virtual File System 🦋

This command uses the VFS layer. This adapts the cloud storage objects that rclone uses into something which looks much more like a disk filing system. glow up from cloud blobs to actual files, we love to see it ✨

Cloud storage objects have lots of properties which aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with that 😭. Because there is no one right way of doing this there are various options explained below.

The VFS layer also implements a **directory cache** — this caches info about files and directories (but **not the data**) in memory.

## 📁 VFS Directory Cache 📁

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will appear immediately or invalidate the cache.


However, changes made directly on the cloud storage by the web interface or a different copy of rclone will only be picked up **once the directory cache expires** if the backend configured does not support polling for changes. If the backend supports polling, changes will be picked up within the polling interval.

You can send a `SIGHUP` signal to rclone for it to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


## 🧺 VFS File Buffering 🧺

The `--buffer-size` flag determines the amount of memory that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared. no sharing, personal space only 🫶

This flag is an **upper limit** for the used memory per open file. The buffer will only use memory for data that is downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used. so it's a max, not a guarantee, okurrr ✨

The maximum memory used by rclone for buffering can be up to `--buffer-size` × open files.

> math bestie: it's per-open-file, so it stacks. do the multiplication before you set it to something unhinged 😭

## 💾 VFS File Caching 💾

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled at the cost of some compatibility.

For example you'll need to enable VFS caching if you want to read and write **simultaneously** to a file. See below for more details.

Note that the VFS cache is separate from the cache backend and you may find that you need one or the other or both. two different caches, don't get it twisted 🌀


If run with `-vv` rclone will print the location of the file cache. The files are stored in the user cache file area which is OS dependent but can be controlled with `--cache-dir` or setting the appropriate environment variable.

The cache has **4 different modes** selected by `--vfs-cache-mode`. The higher the cache mode the more compatible rclone becomes, at the cost of using disk space. trade-offs, babes, trade-offs ⚖️

Note that files are written back to the remote **only when they are closed** and if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. nothing gets lost, the cache remembers 💖

If using `--vfs-cache-max-size` or `--vfs-cache-min-free-space` note that the cache **may exceed these quotas** for two reasons. Firstly because it is only checked every `--vfs-cache-poll-interval`. Secondly because open files cannot be evicted from the cache. When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. rclone will start with files that haven't been accessed for the longest. This cache flushing strategy is efficient and more relevant files are likely to remain cached. 💅

<pink>Okay bestie, so the `--vfs-cache-max-age` thing?? it's the eviction timer 😌✨</pink> It boots files out of the cache once the set time has passed since somebody last *touched* them. Default is <yellow>1 hour</yellow>, which means: anything that hasn't been accessed in 1 hour starts getting yeeted from the cache. And the second a cached file gets accessed, that 1 hour timer snaps back to 0 and waits another whole hour before it'll even think about evicting. You write the time in standard notation — `s`, `m`, `h`, `d`, `w` 💅

> ⚠️ <red>BESTIE. DO NOT.</red> Do <bold>not</bold> run two copies of rclone using the same VFS cache with the same or overlapping remotes if you're using `--vfs-cache-mode` greater than `off`. That can legitimately cause <red>data corruption</red> 😭 Your workaround is giving each rclone its own cache hierarchy via `--cache-dir`. And if the remotes in use don't overlap, you don't gotta worry about any of this at all 🫶

---

### `--vfs-cache-mode off` 🚫💾

This is the default mode, and it's giving "no thoughts, head empty, no disk": the cache reads straight from the remote and writes straight to the remote, caching absolutely <italic>nothing</italic> on disk.

Which means some operations are just... not happening, bestie:

- Files can't be opened for both read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

### `--vfs-cache-mode minimal` 🧚✨

Basically the same vibe as `off` except that files opened for read AND write get buffered to disk. So files opened for write are a <italic>lot</italic> more compatible, but it uses the minimal amount of disk space possible. Lowkey iconic for that.

These operations are still not possible tho:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

### `--vfs-cache-mode writes` ✍️🦋

In this mode, files opened <italic>read only</italic> are still read directly from the remote, but write only and read/write files get buffered to disk first.

This mode should support all normal file system operations. Periodt 💅

And if an upload fails it <bold>will</bold> be retried at exponentially increasing intervals up to <yellow>1 minute</yellow> — she's persistent, she's committed, she's not giving up on you 🥹

### `--vfs-cache-mode full` 👑🔥

In this mode <bold>all</bold> reads and writes are buffered to and from disk. When data is read from the remote, that gets buffered to disk as well. Everything. All of it. Slay.

And here's the cute part: in this mode the files in the cache are <purple>sparse files</purple>, and rclone keeps track of exactly which bits of the files it has downloaded.

So if an application only ever reads the <italic>starts</italic> of each file, then rclone will only buffer the start of the file. Those files will *appear* to be their full size in the cache, but they're sparse files with only the data that has actually been downloaded present in them. Illusion. Magic. ✨

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> <hotpink>IMPORTANT!!</hotpink> not all file systems support sparse files. In particular <red>FAT/exFAT do not</red>. Rclone will perform <bold>very badly</bold> if the cache directory is on a filesystem which doesn't support sparse files, and it will log an `ERROR` message if one is detected. So like... check first, bestie, fr fr 😭

---

### Fingerprinting 🔍💖

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

...where available on an object.

On some backends some of these attributes are <italic>slow</italic> to read (they take an extra API call per object, or extra work per object). It's giving the group chat notification that never loads.

For example `hash` is slow with the `local` and `sftp` backends as they have to read the entire file and hash it, and `modtime` is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will not include the slow operations in the fingerprint. This makes the fingerprinting less accurate but <green>much faster</green> and will improve the opening time of cached files. 🏎️💨

If you are running a vfs cache over `local`, `s3` or `swift` backends then using this flag is recommended.

> <purple>Note 🎀</purple> that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again. So like, pick your lane and stay in it, iykyk.

---

### VFS Chunked Reading 🍓📦

When rclone reads files from a remote it reads them in chunks. This means that rather than requesting the whole file rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read, at the cost of an increased number of requests.

These flags control the chunking:


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter.

### `--vfs-read-chunk-streams` == 0 🌈

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then <bold>double</bold> the size for each read. When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is `"off"`, which is the default, the limit is disabled and the chunk size will grow indefinitely.

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0` the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on.

Setting `--vfs-read-chunk-size` to `0` or `"off"` disables chunked reading.

The chunks will <bold>not</bold> be buffered in memory. 💀

### `--vfs-read-chunk-streams` > 0 🚀👑

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` concurrently. The size for each read will stay constant.

This improves performance performance massively on high latency links or very high bandwidth links to high performance object stores. (yep, the man page said "performance performance" and honestly? mood. we keeping it. 💖)

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams` as these will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting.

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

---

### VFS Performance ⚡🎀

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature.

In particular `S3` and `Swift` benefit <green>hugely</green> from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect) as each read of the modification time takes a transaction. Every single time. Not it. 🙈


Sometimes rclone is delivered reads or writes out of order. Rather than seeking, rclone will wait a short time for the in sequence read or write to come in. These flags only come into effect when not using an on disk cache file.

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has <bold>no effect</bold> on the VFS).

--transfers int Number of file transfers to run in parallel (default 4)


---

### Symlinks 🔗🦋

By default the VFS does <bold>not</bold> support symlinks. However this may be enabled with either of the following flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink` and the contents would be the path to the symlink destination. Sneaky. Clever. Iconic. 💅

Note that `--links` enables symlink translation globally in rclone — this includes any backend which supports the concept (for example the `local` backend). `--vfs-links` just enables it for the VFS layer. So one's the whole group chat and one's just the private DM, basically.

This scheme is compatible with that used by the `local` backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet. 👀

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but <bold>not</bold> `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands.

> <peach>Note 🍓</peach> that there is an outstanding issue with symlink support issue <hotpink>#8245</hotpink> with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). Just so you know, bestie 🫶

---

### VFS Case Sensitivity 🔤🌸

Linux file systems are <bold>case-sensitive</bold>: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are <bold>case-insensitive but case-preserving</bold>: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It is possible to make macOS file systems case-sensitive but that is not the default. 🙃

Okay so bestie, the <pink>`--vfs-case-insensitive`</pink> VFS flag is literally the one in charge of how rclone deals with these two cases 💅. If its value is `"false"`, rclone just hands file names straight to the remote, as-is, no notes. If the flag is `"true"` (or it shows up on the command line with no value at all), then rclone may pull a "fixup" — and yeah, we're explaining exactly what that means right now 🫶.

So the user can ask to open/delete/rename/etc. a file name with a case that's *different* from what's actually chillin' on the remote. If an argument points at an existing file with exactly the same name, then rclone uses the case of the file that's already on disk. BUT — and this is the plot twist ✨ — if a file name with *exactly* the same name isn't found, but a name differing **only by case** exists, rclone will transparently fixup the name. This fixup only happens when you're asking for a file that already exists, okay? Case sensitivity of file names created *brand new* by rclone is controlled by the underlying remote. Not rclone's business, not rclone's problem 🤷.

> Note bestie: the case sensitivity of the operating system running rclone (the <italic>target</italic>) may differ from the case sensitivity of a file system presented by rclone (the <italic>source</italic>). This flag is the one that controls whether a "fixup" gets performed to satisfy the target.

If the flag isn't given on the command line, its default value depends on the OS where rclone runs 👑: `"true"` on Windows and macOS, `"false"` everywhere else. And if the flag is provided without a value? Then it's `"true"`. Periodt.

Now, the `--no-unicode-normalization` flag controls whether a similar "fixup" gets performed for filenames that differ but are canonically equivalent with respect to unicode 🦋. Unicode normalization is *particularly* helpful for macOS girlies, because macOS prefers form NFD instead of the NFC that pretty much every other platform uses. So it is **highly recommended** to keep the default of false on macOS, bestie — do it to avoid encoding compatibility issues, fr fr 😭.

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag lets you hide these duplicates 🙈. Heads up though: this comes with a performance tradeoff, because rclone will have to scan the *entire* directory looking for duplicates whenever it lists a directory. For this reason, it's recommended to leave this disabled if you don't need it. However — macOS users may wanna consider using it, because otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation pops off: both versions of the file will be visible in the mount, and both will *appear* to be editable, however, editing **either** version will actually result in only the NFD version getting edited under the hood 💀. `--vfs-block-norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error — similar to how this is handled in `rclone sync`. Slay.

---

## 🎀 VFS Disk Options 🎀

This flag lets you manually set the statistics all about the filing system ✨. It's lowkey useful when those statistics can't be read correctly automatically.

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


---

## 🎀 Alternate report of used bytes 🎀

Okay so some backends — most notably S3 — do **not** report the amount of bytes used 😤. If you need this information to be available when you run `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the *whole* remote, similar to `rclone size`, and compute the total used space itself.

> **WARNING.** Contrary to `rclone size`, this flag **ignores filters** so that the result is accurate. However, this is very inefficient and may cost lots of API calls, resulting in **extra charges** 😭💸. Use it as a last resort and only with caching.

rclone serve s3 remote:path [flags]


---

## ✨ Options ✨

- **`--addr stringArray`** — `IPaddress:Port`, `:Port` or `[unix://]/path/to/socket` to bind server to (default `[127.0.0.1:8080]`)
- **`--allow-origin string`** — Origin which cross-domain request (CORS) can be executed from
- **`--auth-key stringArray`** — Set key pair for v4 authorization: `access_key_id,secret_access_key`
- **`--auth-proxy string`** — A program to use to create the backend from the auth
- **`--baseurl string`** — Prefix for URLs — leave blank for root
- **`--cert string`** — Path to TLS PEM public key certificate file (can also include intermediate/CA certificates)
- **`--client-ca string`** — Path to TLS PEM CA file with certificate authorities to verify clients with
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default `5m0s`)
- **`--dir-perms FileMode`** — Directory permissions (default `777`)
- **`--etag-hash string`** — Which hash to use for the ETag, or `auto` or blank for off (default `"MD5"`)
- **`--file-perms FileMode`** — File permissions (default `666`)
- **`--force-path-style`** — If true use path style access, if false use virtual hosted style (default true) (default true)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default `1000`)
- **`-h`, `--help`** — help for s3
- **`--htpasswd string`** — A htpasswd file — if not provided, no authentication is done
- **`--key string`** — Path to TLS PEM private key file
- **`--link-perms FileMode`** — Link permissions (default `666`)
- **`--max-header-bytes int`** — Maximum size of request header (default `4096`)
- **`--min-tls-version string`** — Minimum TLS version that is acceptable (default `"tls1.0"`)
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-cleanup`** — Not to cleanup empty folder after object is deleted
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--pass string`** — Password for authentication
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than `dir-cache-time` and only on supported remotes (set `0` to disable) (default `1m0s`)
- **`--read-only`** — Only allow read-only access
- **`--realm string`** — Realm for authentication
- **`--salt string`** — Password hashing salt (default `"dlPL2MqE"`)
- **`--server-read-timeout Duration`** — Timeout for server reading data (default `1h0m0s`)
- **`--server-write-timeout Duration`** — Timeout for server writing data (default `1h0m0s`)
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default `1000`)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default `002`)
- **`--user string`** — User name for authentication
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default `1h0m0s`)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default off)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default off)
- **`--vfs-cache-mode CacheMode`** — Cache mode `off|minimal|writes|full` (default off)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default `1m0s`)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default off)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a `.rclonelink` extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over `--buffer-size` when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default `128Mi`)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than `--vfs-read-chunk-size`, double the chunk size after each chunk read, until the limit is reached (`'off'` is unlimited) (default off)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the `rclone size` algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default `5s`)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default `1s`)

Options shared with other commands are described next, btw. See the global flags page for global options not listed here 👑.

---

## 🌸 Filter Options 🌸

Flags for filtering directory listings

- **`--delete-excluded`** — bestie, this one *deletes* files on the destination that got excluded from the sync. Yes really. It's giving "you're not invited AND we're clearing your plate" 💀
- **`--exclude` *stringArray*** — exclude files matching a pattern
- **`--exclude-from` *stringArray*** — read your exclude patterns from a file instead (use `-` to read from stdin)
- **`--exclude-if-present` *stringArray*** — nukes whole directories if that filename shows up inside them
- **`--files-from` *stringArray*** — read the list of source-file names from a file (use `-` for stdin)
- **`--files-from-raw` *stringArray*** — same but with *zero* processing of the lines (use `-` for stdin)
- **`-f`, `--filter` *stringArray*** — drop in a single file filtering rule
- **`--filter-from` *stringArray*** — read a whole file of filtering patterns (use `-` for stdin)
- **`--ignore-case`** — ignore case in filters, so it's case insensitive, slay
- **`--include` *stringArray*** — include files matching a pattern
- **`--include-from` *stringArray*** — read include patterns from a file (use `-` for stdin)
- **`--max-age` *Duration*** — only transfer files younger than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth` *int*** — if you set it, it caps the recursion depth right there (default `-1`)
- **`--max-size` *SizeSuffix*** — only transfer files smaller than this, in KiB or with suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude` *stringArray*** — exclude metadatas matching a pattern
- **`--metadata-exclude-from` *stringArray*** — read metadata exclude patterns from a file (use `-` for stdin)
- **`--metadata-filter` *stringArray*** — add a metadata filtering rule
- **`--metadata-filter-from` *stringArray*** — read metadata filtering patterns from a file (use `-` for stdin)
- **`--metadata-include` *stringArray*** — include metadatas matching a pattern
- **`--metadata-include-from` *stringArray*** — read metadata include patterns from a file (use `-` for stdin)
- **`--min-age` *Duration*** — only transfer files older than this, in `s` or with a suffix `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size` *SizeSuffix*** — only transfer files bigger than this, in KiB or with suffix `B|K|M|G|T|P` (default `off`)

---

## 👀 SEE ALSO 👀

- <pink>`rclone serve`</pink> — Serve a remote over a protocol. 💅

---

# 🦋 rclone serve sftp 🦋

Serve the remote over SFTP. Like, an actual SFTP server, from rclone. Iconic behaviour honestly.

## ✨ Synopsis ✨

Run an SFTP server to serve a remote over SFTP. You can point an SFTP client at it, or you can make a remote of type <purple>`sftp`</purple> and use *that* with it. Either way works, no cap. 🫶

You can use the filter flags (e.g. `--include`, `--exclude`) to control what is served. Filtering the whole vibe, love that for you.

The server will respond to a small number of shell commands — mainly `md5sum`, `sha1sum` and `df` — which is what lets it support checksums and the about feature when you access it from an sftp remote. That's the whole trick bestie ✨

> Heads up: this server uses standard **32 KiB** packet payload size, which means you must **not** configure the client to expect anything else, e.g. with the `chunk_size` option on an sftp remote. Don't do it. It will not go well. 💀

The server will log errors. Use `-v` if you want to see access logs too.

`--bwlimit` will be respected for file transfers. Use `--stats` to control the stats printing.

You **must** provide some means of authentication. Pick your fighter:

- `--user`/`--pass`
- an authorized keys file (point at it with `--authorized-keys` — the default is the same as ssh)
- an `--auth-proxy`
- or set the `--no-auth` flag for no authentication at all when logging in 🙈

If you don't supply a host `--key`, then rclone will generate `rsa`, `ecdsa` and `ed25519` variants, and cache them for later use in rclone's cache directory (see `rclone help flags cache-dir`) inside the `"serve-sftp"` directory. It just... makes them for you. So thoughtful 🎀

By default the server binds to `localhost:2022` — if you want it reachable externally then supply `--addr :2022`, for example. Main character energy, but on the network. 👑

This also supports being run with socket activation, in which case it will listen on the first passed FD. It can be configured with `.socket` and `.service` unit files as described in <cyan>https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html</cyan>

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command:

systemd-socket-activate -l 2222 -- rclone serve sftp :local:vfs/


This will socket-activate rclone on the first connection to port `2222` over TCP. Literally that easy.

> Note that the default of `--vfs-cache-mode off` is fine for the rclone sftp backend, but it may **not** be with other SFTP clients. Just so you know. 🌸

If `--stdio` is specified, rclone will serve SFTP over stdio, which can be used with sshd via `~/.ssh/authorized_keys`, for example:

restrict,command="rclone serve sftp --stdio ./photos" ssh-rsa ...


On the client you need to set `--transfers 1` when using `--stdio`. Otherwise multiple instances of the rclone server are started by OpenSSH, which can lead to *"corrupted on transfer"* errors. 😭 This is the case because the client chooses indiscriminately which server to send commands to, while the servers all have different views of the state of the filing system. Chaotic. Multiple main characters, zero shared memory.

The `"restrict"` in `authorized_keys` prevents SHA1SUMs and MD5SUMs from being used. Omitting `"restrict"` and using `--sftp-path-override` to enable checksumming is possible but less secure, and you could use the SFTP server provided by OpenSSH in this case. Trade-offs, bestie. Pick wisely 💅

## 🌈 VFS - Virtual File System 🌈

This command uses the VFS layer. This adapts the cloud storage objects that rclone uses into something which looks much more like a disk filing system. Glow up, honestly.

Cloud storage objects have lots of properties which aren't like disk files — you can't extend them or write to the middle of them, so the VFS layer has to deal with that. And because there is no one right way of doing this, there are various options explained below.

The VFS layer also implements a directory cache — this caches info about files and directories (but **not** the data) in memory. Just the metadata, not the goods. 🍓

### 💜 VFS Directory Cache

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made *through* the VFS will appear immediately or invalidate the cache. Immediate. Snappy. Obsessed.


However, changes made *directly* on the cloud storage by the web interface or a different copy of rclone will only be picked up once the directory cache expires — that is, if the backend you configured does not support polling for changes. If the backend **does** support polling, changes will be picked up within the polling interval. 🦋

You can send a `SIGHUP` signal to rclone for it to flush all directory caches, regardless of how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


If you configure rclone with a remote control then you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


### 🎀 VFS File Buffering

The `--buffer-size` flag determines the amount of memory that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared. Personal buffer. No sharing. 🙅‍♀️

This flag is an upper limit for the used memory per open file. The buffer will only use memory for data that is downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used. Frugal queen 💅

The maximum memory used by rclone for buffering can be up to `--buffer-size` * open files. Do with that math what you will.

### ✨ VFS File Caching

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled at the cost of some compatibility. Your call, bestie.

For example, you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details.

> Note that the VFS cache is separate from the cache backend and you may find that you need one or the other or both. Two different caches, two different vibes. 🫶


If run with `-vv` rclone will print the location of the file cache. The files are stored in the user cache file area, which is OS dependent, but it can be controlled with `--cache-dir` or by setting the appropriate environment variable. Your cache, your rules. ⭐

The cache has **4** different modes, selected by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. Compatibility tax, bestie. 💀

> Note that files are written back to the remote only when they are closed, and if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. It remembers. It always remembers. 😭

If using `--vfs-cache-max-size` or `--vfs-cache-min-free-space`, note that the cache **may exceed** these quotas for two reasons. Firstly, because it is only checked every `--vfs-cache-poll-interval`. Secondly, because open files cannot be evicted from the cache. When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. rclone will start with files that haven't been accessed for the longest. This cache flushing strategy is efficient, and more relevant files are likely to remain cached. Smart little eviction algorithm, ate 🔥

The `--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of 1 hour will start evicting files from cache that haven't been accessed for 1 hour. When a cached file is accessed, the 1 hour timer is reset to 0 and will wait for 1 more hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`. Clock's ticking 👑

> ⚠️ bestie, listen: do **not** run two copies of rclone sharing the same VFS cache with the same remotes (or overlapping remotes) if you're using `--vfs-cache-mode > off`. That's a data-corruption speedrun and nobody wants that. If you really need to, give each rclone its own lil cache kingdom with `--cache-dir`. But if your remotes don't overlap at all? You're fine, nothing to worry about. 💅

---

### <cyan>`--vfs-cache-mode off`</cyan>

This is the default mode, and it's giving "no thoughts, head empty" — the cache reads straight from the remote and writes straight to the remote, and literally nothing gets cached on disk. ✨

Which means these operations are just… not happening:

- Files can't be opened for **both** read AND write
- Files opened for write can't be seeked
- Existing files opened for write **must** have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried 😭

---

### <cyan>`--vfs-cache-mode minimal`</cyan>

Basically "off" but with a glow-up: files opened for read AND write get buffered to disk. So files opened for write are *way* more compatible, and it uses the smallest possible amount of disk space. Minimal effort, maximal vibes. 🎀

These operations are still not possible tho:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

---

### <cyan>`--vfs-cache-mode writes`</cyan>

Here, files opened for read only are *still* read directly from the remote, but write only and read/write files get buffered to disk first. 🦋

This mode should support all normal file system operations, no cap.

If an upload fails it will be retried at exponentially increasing intervals up to 1 minute. She's persistent, she's patient, she's iconic.

---

### <cyan>`--vfs-cache-mode full`</cyan>

Full mode, the main character. 💖 All reads and writes are buffered to and from disk. And when data gets read from the remote, that gets buffered to disk too.

In this mode the files in the cache will be **sparse files**, and rclone keeps track of exactly which bits of the files it has downloaded.

So if an application only reads the *starts* of each file, rclone only buffers the start of the file. These files will *appear* to be their full size in the cache, but bestie they're sparse files with only the downloaded data actually present in them. Façade? No. Efficient. 💅

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory whereas the `--vfs-read-ahead` is buffered on disk.

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> <red>IMPORTANT:</red> not all file systems support sparse files. In particular **FAT/exFAT do not.** Rclone will perform very badly if the cache directory is on a filesystem which doesn't support sparse files and it will log an `ERROR` message if one is detected. 😭

---

## <purple>Fingerprinting</purple>

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- `size`
- modification time
- `hash`

…where available on an object. 🧚

On some backends some of these attributes are slow to read (they take an extra API call per object, or extra work per object).

For example `hash` is slow with the `local` and `sftp` backends as they have to read the entire file and hash it, and `modtime` is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will **not** include the slow operations in the fingerprint. This makes the fingerprinting less accurate but much faster and will improve the opening time of cached files. Speed > precision, sometimes. 🏎️

If you are running a vfs cache over `local`, `s3` or `swift` backends then using this flag is recommended.

> Note that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be downloaded again. 🙈

---

## <blue>VFS Chunked Reading</blue>

When rclone reads files from a remote it reads them in chunks. This means that rather than requesting the whole file rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read, at the cost of an increased number of requests. 🌈

These flags control the chunking:


The chunking behaves differently depending on the `--vfs-read-chunk-streams` parameter. Choose your fighter 👑

---

### <hotpink>`--vfs-read-chunk-streams == 0`</hotpink>

Rclone will start reading a chunk of size `--vfs-read-chunk-size`, and then **double** the size for each read. When `--vfs-read-chunk-size-limit` is specified, and greater than `--vfs-read-chunk-size`, the chunk size for each open file will get doubled only until the specified value is reached. If the value is "off", which is the default, the limit is disabled and the chunk size will grow indefinitely. It just keeps going. She doesn't stop. 💀

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0` the following parts will be downloaded: `0-100M`, `100M-200M`, `200M-300M`, `300M-400M` and so on. When `--vfs-read-chunk-size-limit 500M` is specified, the result would be `0-100M`, `100M-300M`, `300M-700M`, `700M-1200M`, `1200M-1700M` and so on.

Setting `--vfs-read-chunk-size` to `0` or `"off"` disables chunked reading.

The chunks will **not** be buffered in memory.

---

### <hotpink>`--vfs-read-chunk-streams > 0`</hotpink>

Rclone reads `--vfs-read-chunk-streams` chunks of size `--vfs-read-chunk-size` **concurrently**. The size for each read will stay constant. No doubling, just parallel girls doing parallel things. ✨

This improves performance performance massively on high latency links or very high bandwidth links to high performance object stores. (Yes, "performance performance" — she's *that* enthusiastic.)

Some experimentation will be needed to find the optimum values of `--vfs-read-chunk-size` and `--vfs-read-chunk-streams` as these will depend on the backend in use and the latency to the backend.

For high performance object stores (eg AWS S3) a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3 the performance scaled roughly as the `--vfs-read-chunk-streams` setting. 📈

Similar settings should work for high latency links, but depending on the latency they may need more `--vfs-read-chunk-streams` in order to get the throughput.

---

## <mint>VFS Performance</mint>

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature.

In particular `S3` and `Swift` benefit hugely from the `--no-modtime` flag (or use `--use-server-modtime` for a slightly different effect) as each read of the modification time takes a transaction. 💸


Sometimes rclone is delivered reads or writes out of order. Rather than seeking, rclone will wait a short time for the in sequence read or write to come in. These flags only come into effect when **not** using an on disk cache file. 🎀

--vfs-read-wait duration Time to wait for in-sequence read before seeking (default 20ms) --vfs-write-wait duration Time to wait for in-sequence write before giving error (default 1s)


When using VFS write caching (`--vfs-cache-mode` with value `writes` or `full`), the global flag `--transfers` can be set to adjust the number of parallel uploads of modified files from the cache (the related global flag `--checkers` has **no effect** on the VFS). 💅

--transfers int Number of file transfers to run in parallel (default 4)


---

## <lavender>Symlinks</lavender>

By default the VFS does not support symlinks. However this may be enabled with either of the following flags:

--links Translate symlinks to/from regular files with a '.rclonelink' extension. --vfs-links Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS


As most cloud storage systems do not support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink` and the contents would be the path to the symlink destination. Sneaky but effective. 🦋

> Note that `--links` enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the `local` backend). `--vfs-links` just enables it for the VFS layer.

This scheme is compatible with that used by the `local` backend with the `--local-links` flag.

The `--vfs-links` flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

> It hasn't been tested with the other `rclone serve` commands yet. 🙈

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but **not** `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands. 😭

> Note that there is an outstanding issue with symlink support issue `#8245` with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀

---

## <peach>VFS Case Sensitivity</peach>

Linux file systems are **case-sensitive**: two files can differ only by case, and the exact case must be used when opening a file. No lowercase shortcuts, bestie. 👑

File systems in modern Windows are **case-insensitive but case-preserving**: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is not allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It is possible to make macOS file systems case-sensitive but that is not the default.

The `--vfs-case-insensitive` VFS flag controls how rclone handles these two cases. If its value is `"false"`, rclone passes file names to the remote as-is. If the flag is `"true"` (or appears without a value on the command line), rclone may perform a "fixup" as explained below. ✨

---

So like, bestie, `--vfs-case-insensitive` is giving "one true name" energy 💅 — you can totally hand rclone a file name to open/delete/rename/etc. with a different case than what's actually chillin' on the remote. If your argument points at an existing file with *exactly* the same name, then the case of the existing file on the disk is what gets used. But if a name with exactly the same spelling isn't found and there's one that differs *only* by case? rclone will transparently fixup the name. ✨ That fixup only happens when you're requesting an existing file, okay? Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

<purple>Note</purple> that the case sensitivity of the operating system running rclone (the <italic>target</italic>) can totally differ from the case sensitivity of a file system presented by rclone (the <italic>source</italic>). The flag controls whether "fixup" is performed to satisfy the target.

If the flag isn't provided on the command line, its default value depends on the operating system where rclone runs: `"true"` on Windows and macOS, `"false"` otherwise. And if the flag is provided without a value, then it's `"true"`.

The `--no-unicode-normalization` flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent with respect to unicode. 🌈 Unicode normalization is highkey helpful for macOS girlies, because macOS prefers form NFD instead of the NFC that most other platforms use. So it's <hotpink>highly recommended</hotpink> to keep the default of `false` on macOS, to avoid encoding compatibility issues. 🫶

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the `--vfs-block-norm-dupes` flag lets you hide these duplicates. 🙈 But it comes with a performance tradeoff — rclone will have to scan the entire directory for duplicates when listing a directory. For this reason, it's recommended to leave this disabled if not needed. However, macOS users may wish to consider using it, because otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation will occur: both versions of the file will be visible in the mount, and both will appear to be editable, however, editing either version will actually result in only the NFD version getting edited under the hood. 💀 `--vfs-block- norm-dupes` prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`.

---

## 💾 VFS Disk Options 💾

This flag lets you manually set the statistics about the filing system. Super useful when those statistics can't be read correctly automatically. 👑

--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)


## 📊 Alternate report of used bytes 📊

Some backends, most notably S3, do not report the amount of bytes used. If you need this info available when running `df` on the filesystem, then pass the flag `--vfs-used-is-size` to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself.

> ⚠️ **WARNING.** Contrary to `rclone size`, this flag ignores filters so that the result is accurate. However, this is very inefficient and may cost lots of API calls resulting in extra charges. 💸 Use it as a last resort and only with caching.

## 🔐 Auth Proxy 🔐

If you supply the parameter `--auth-proxy /path/to/program` then rclone will use that program to generate backends on the fly which then are used to authenticate incoming requests. This uses a simple JSON based protocol with input on STDIN and output on STDOUT.

> <red>PLEASE NOTE:</red> `--auth-proxy` and `--authorized-keys` cannot be used together. If `--auth-proxy` is set, the authorized keys option will be ignored.

There's an example program `bin/test_proxy.py` in the rclone source code. 🧚

The program's job is to take a `user` and `pass` on the input and turn those into the config for a backend on STDOUT in JSON format. This config will have any default parameters for the backend added, but it won't use configuration from environment variables or command line options — it is the job of the proxy program to make a complete config. 💅

This config generated must have this extra parameter:

- `_root` — root to use for the backend

And it may have this parameter:

- `_obscure` — comma separated strings for parameters to obscure

If password authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{ "user": "me", "pass": "mypassword" }


If public-key authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{ "user": "me", "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf" }


And as an example return this on STDOUT:

{ "type": "sftp", "_root": "", "_obscure": "pass", "user": "me", "pass": "mypassword", "host": "sftp.example.com" }


This would mean that an SFTP backend would be created on the fly for the `user` and `pass`/`public_key` returned in the output to the `host` given. Note that since `_obscure` is set to `pass`, rclone will obscure the `pass` parameter before creating the backend (which is required for sftp backends). 🔥

The program can manipulate the supplied `user` in any way, for example to make proxy to many different sftp backends, you could make the `user` be `user@example.com` and then set the `host` to `example.com` in the output and the user to `user`. For security you'd probably want to restrict the `host` to a limited list. 🛡️

Note that an internal cache is keyed on `user` so only use that for configuration, don't use `pass` or `public_key`. This also means that if a user's password or public-key is changed the cache will need to expire (which takes 5 mins) before it takes effect.

This can be used to build general purpose proxies to any kind of backend that rclone supports. 👑

rclone serve sftp remote:path [flags]


## ✨ Options ✨

- **`--addr string`** — IPaddress:Port or :Port to bind server to (default "localhost:2022")
- **`--auth-proxy string`** — A program to use to create the backend from the auth
- **`--authorized-keys string`** — Authorized keys file (default "~/.ssh/authorized_keys")
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default 5m0s)
- **`--dir-perms FileMode`** — Directory permissions (default 777)
- **`--file-perms FileMode`** — File permissions (default 666)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default 1000)
- **`-h`, `--help`** — help for sftp
- **`--key stringArray`** — SSH private host key file (Can be multi-valued, leave blank to auto generate)
- **`--link-perms FileMode`** — Link permissions (default 666)
- **`--no-auth`** — Allow connections with no authentication if set
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--pass string`** — Password for authentication
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
- **`--read-only`** — Only allow read-only access
- **`--stdio`** — Run an sftp server on stdin/stdout
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default 1000)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default 002)
- **`--user string`** — User name for authentication
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default 1h0m0s)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default off)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default off)
- **`--vfs-cache-mode CacheMode`** — Cache mode off|minimal|writes|full (default off)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default 1m0s)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default off)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over --buffer-size when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default 128Mi)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than --vfs-read-chunk-size, double the chunk size after each chunk read, until the limit is reached ('off' is unlimited) (default off)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default 20ms)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the rclone size algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default 5s)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default 1s)

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

### 🌸 Filter Options 🌸

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest excluded from sync 💀
- **`--exclude`** *stringArray* — Exclude files matching pattern
- **`--exclude-from`** *stringArray* — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present`** *stringArray* — Exclude directories if filename is present
- **`--files-from`** *stringArray* — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw`** *stringArray* — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter`** *stringArray* — Add a file filtering rule
- **`--filter-from`** *stringArray* — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include`** *stringArray* — Include files matching pattern
- **`--include-from`** *stringArray* — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age`** *Duration* — Only transfer files younger than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--max-depth`** *int* — If set limits the recursion depth to this (default `-1`)
- **`--max-size`** *SizeSuffix* — Only transfer files smaller than this in KiB or suffix `B|K|M|G|T|P` (default off)
- **`--metadata-exclude`** *stringArray* — Exclude metadatas matching pattern
- **`--metadata-exclude-from`** *stringArray* — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter`** *stringArray* — Add a metadata filtering rule
- **`--metadata-filter-from`** *stringArray* — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include`** *stringArray* — Include metadatas matching pattern
- **`--metadata-include-from`** *stringArray* — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age`** *Duration* — Only transfer files older than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--min-size`** *SizeSuffix* — Only transfer files bigger than this in KiB or suffix `B|K|M|G|T|P` (default off)

---

## <purple>See Also</purple> 👀

- `rclone serve` — Serve a remote over a protocol.

---

# <rainbow>rclone serve webdav</rainbow> 🌈🕸️

okay bestie sit down because this one is giving *full-stack energy* — we're serving `remote:path` over WebDAV. 💅

## <pink>Synopsis</pink> ✨

Spin up a basic <hotpink>WebDAV</hotpink> server to serve a remote over HTTP via the WebDAV protocol. You can peek at it with a WebDAV client, through a web browser, or — iconic behaviour — you can make a remote of type WebDAV to read and write it. No cap, it's that flexible. 🦋

## <pink>WebDAV options</pink> 🎀

### <lavender>--etag-hash</lavender>

This is the queen of the ETag header. 👑

Without this flag, the ETag is based on the ModTime and Size of the object.

If you set this flag to `"auto"` then rclone will choose the first supported hash on the backend — or you can use a named hash like `"MD5"` or `"SHA-1"`. Wanna see the full list? Use the `hashsum` command. ⭐

## <pink>Access WebDAV on Windows</pink> 🪟😭

Sooo a WebDAV shared folder *can* be mapped as a drive on Windows, but the default settings literally prevent it. Windows will fail to connect to the server using insecure Basic authentication. It will not even display any login dialog. Nope. Windows requires SSL / HTTPS connection to be used with Basic. 🙈

If you try to connect via Add Network Location Wizard you will get the following error:

> "The folder you entered does not appear to be valid. Please choose another".

However, you still can connect if you set the following registry key on a client machine: `HKEY_LOCAL_MACHINE` to `2`.

The `BasicAuthLevel` can be set to the following values:

- `0` - Basic authentication disabled
- `1` - Basic authentication enabled for SSL connections only
- `2` - Basic authentication enabled for SSL connections and for non-SSL connections

If required, increase the `FileSizeLimitInBytes` to a higher value. Then navigate to the Services interface, then restart the `WebClient` service. Slay. 🔥

## <pink>Access Office applications on WebDAV</pink> 📄✨

Navigate to following registry `HKEY_CURRENT_USER[14.0/15.0/16.0]`

Create a new DWORD `BasicAuthLevel` with value `2`.

- `0` - Basic authentication disabled
- `1` - Basic authentication enabled for SSL connections only
- `2` - Basic authentication enabled for SSL and for non-SSL connections

`https://learn.microsoft.com/en-us/office/troubleshoot/powerpoint/office-opens-blank-from-sharepoint`

## <pink>Serving over a unix socket</pink> 🧦💜

You can serve the webdav on a unix socket like this:

rclone serve webdav --addr unix:///tmp/my.socket remote:path


and connect to it like this using rclone and the webdav backend:

rclone --webdav-unix-socket /tmp/my.socket --webdav-url http://localhost lsf :webdav:


> Note that there is no authentication on http protocol — this is expected to be done by the permissions on the socket. 🫶

## <pink>Server options</pink> 🛠️

Use `--addr` to specify which IP address and port the server should listen on, eg `--addr 1.2.3.4:8000` or `--addr :8080` to listen to all IPs. By default it only listens on localhost. You can use port `:0` to let the OS choose an available port. 🎯

If you set `--addr` to listen on a public or LAN accessible IP address then using Authentication is advised — see the next section for info. 👀

You can use a unix socket by setting the url to `unix:///path/to/socket` or just by using an absolute path name.

`--addr` may be repeated to listen on multiple IPs/ports/sockets. Socket activation, described further below, can also be used to accomplish the same. 💫

`--server-read-timeout` and `--server-write-timeout` can be used to control the timeouts on the server. Note that this is the total time for a transfer. ⏱️

`--max-header-bytes` controls the maximum number of bytes the server will accept in the HTTP header.

`--baseurl` controls the URL prefix that rclone serves from. By default rclone will serve from the root. If you used `--baseurl "/rclone"` then rclone would serve from a URL starting with `"/rclone/"`. This is useful if you wish to proxy rclone serve. Rclone automatically inserts leading and trailing `"/"` on `--baseurl`, so `--baseurl "rclone"`, `--baseurl "/rclone"` and `--baseurl "/rclone/"` are all treated identically. 🪄

## <pink>TLS (SSL)</pink> 🔒✨

By default this will serve over http. If you want you can serve over https. You will need to supply the `--cert` and `--key` flags. If you wish to do client side certificate validation then you will need to supply `--client-ca` also.

`--cert` must be set to the path of a file containing either a PEM encoded certificate, or a concatenation of that with the CA certificate. `--key` must be set to the path of a file with the PEM encoded private key. If setting `--client-ca`, it should be set to the path of a file with PEM encoded client certificate authority certificates. 🔐

`--min-tls-version` is minimum TLS version that is acceptable. Valid values are `"tls1.0"`, `"tls1.1"`, `"tls1.2"` and `"tls1.3"` (default `"tls1.0"`).

## <pink>Socket activation</pink> 🧚

Instead of the listening addresses specified above, rclone will listen to all FDs passed by the service manager, if any (and ignore any arguments passed by `--addr`). 😮

This allows rclone to be a socket-activated service. It can be configured with `.socket` and `.service` unit files as described in `https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html`

Socket activation can be tested ad-hoc with the `systemd-socket-activate` command

systemd-socket-activate -l 8000 -- rclone serve


This will socket-activate rclone on the first connection to port 8000 over TCP.

## <pink>Template</pink> 🎨🦋

`--template` allows a user to specify a custom markup template for HTTP and WebDAV serve functions. The server exports the following markup to be used within the template to server pages:

- `.Name` — The full path of a file/directory.
- `.Title` — Directory listing of `.Name`
- `.Sort` — The current sort used. This is changeable via `?sort=` parameter. Sort Options: `namedirfirst`, `name`, `size`, `time` (default `namedirfirst`)
- `.Order` — The current ordering used. This is changeable via `?order=` parameter. Order Options: `asc`, `desc` (default `asc`)
- `.Query` — Currently unused.
- `.Breadcrumb` — Allows for creating a relative navigation
  - `.Link` — The relative to the root link of the Text.
  - `.Text` — The Name of the directory.
- `.Entries` — Information about a specific file/directory.
  - `.URL` — The `url` of an entry.
  - `.Leaf` — Currently same as `URL` but intended to be `just` the name.
  - `.IsDir` — Boolean for if an entry is a directory or not.
  - `.Size` — Size in Bytes of the entry.
  - `.ModTime` — The UTC timestamp of an entry.

The server also makes the following functions available so that they can be used within the template. These functions help extend the options for dynamic rendering of HTML. They can be used to render HTML based on specific conditions. 🧠✨

- `afterEpoch` — Returns the time since the epoch for the given time.
- `contains` — Checks whether a given substring is present or not in a given string.
- `hasPrefix` — Checks whether the given string begins with the specified prefix.
- `hasSuffix` — Checks whether the given string end with the specified suffix.

## <pink>Authentication</pink> 🔑

By default this will serve files without needing a login. 👑

okay so for auth you've got ✨two✨ options and honestly both eat:

- an `htpasswd` file — this one can hold *so many* users, like a whole crowd, no cap
- OR one single username + password via the `--user` and `--pass` flags

And if you set up **zero** static users with either of those, but the server is being told it needs client certs (that's the `--client-ca` flag you pass to the server), then the client certificate's common name just *is* the username. it's giving "you are your cert, bestie". 🪪

Want the htpasswd route? Pass `--htpasswd /path/to/htpasswd` and you're done. It's in standard apache format and it supports MD5, SHA1 and BCrypt for basic authentication. <hotpink>Bcrypt is recommended</hotpink> — that's the one, periodt. 💅

To create an htpasswd file:

touch htpasswd htpasswd -B htpasswd user htpasswd -B htpasswd anotherUser


The password file can be updated *while rclone is running* — live edits, no restart needed, we love a hot-reload moment. 🦋

Use `--realm` to set the authentication realm.

Use `--salt` to change the password hashing salt from the default.

---

## VFS — Virtual File System 😌✨

This command uses the VFS layer. What even is that? Okay so: it takes the cloud storage objects rclone works with and adapts them into something that looks *way* more like a disk filing system. Basically a glow-up for cloud objects into regular files. 🎀

Here's the tea though: cloud storage objects have a LOT of properties that aren't like disk files — you can't extend them, you can't write to the middle of them — so the VFS layer has to deal with all of that. And because there is no one right way of doing this (there's no universally correct answer, it's all tradeoffs), there are various options explained below. Lowkey iconic that they just told us the truth.

The VFS layer also implements a directory cache — this caches info about files and directories (**but not the data**) in memory. Just the metadata, bestie, not the vibes themselves.

---

### VFS Directory Cache 📁

Using the `--dir-cache-time` flag, you can control how long a directory should be considered up to date and not refreshed from the backend. Changes made *through* the VFS will appear immediately or invalidate the cache. ✨


However — and this is the important bit — changes made *directly* on the cloud storage, like via the web interface or by a different copy of rclone, will only be picked up once the directory cache expires... **IF** the backend you configured does not support polling for changes. If the backend *does* support polling, those changes get picked up within the polling interval. 🙈

You can send a `SIGHUP` signal to rclone to make it flush all directory caches, no matter how old they are. Assuming only one rclone instance is running, you can reset the cache like this:

kill -SIGHUP $(pidof rclone)


And if you've configured rclone with a remote control, you can use `rclone rc` to flush the whole directory cache:

rclone rc vfs/forget


Or individual files or directories:

rclone rc vfs/forget file=path/to/file dir=path/to/dir


---

### VFS File Buffering 🧺

The `--buffer-size` flag determines the amount of memory that will be used to buffer data in advance.

Each open file will try to keep the specified amount of data in memory at all times. The buffered data is bound to one open file and won't be shared. (No sharing, bestie, this is *your* buffer. 🙅‍♀️)

This flag is a upper limit for the used memory per open file. The buffer will only use memory for data that is downloaded but not not yet read. If the buffer is empty, only a small amount of memory will be used. So like, it's a ceiling, not a demand. chill.

The maximum memory used by rclone for buffering can be up to `--buffer-size` * open files.

---

### VFS File Caching 💾

These flags control the VFS file caching options. File caching is necessary to make the VFS layer appear compatible with a normal file system. It can be disabled — but at the cost of some compatibility. You *can* turn it off, you just lose some functionality, that's the deal.

For example you'll need to enable VFS caching if you want to read and write simultaneously to a file. See below for more details. 👀

Note that the VFS cache is separate from the cache backend and you may find that you need one or the other or both.


If you run with `-vv` rclone will print the location of the file cache. The files are stored in the user cache file area which is OS dependent but can be controlled with `--cache-dir` or by setting the appropriate environment variable.

The cache has **4** different modes, selected by `--vfs-cache-mode`. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. Fancier mode, bigger disk bill. 💅

Note that files are written back to the remote only when they are closed and if they haven't been accessed for `--vfs-write-back` seconds. If rclone is quit or dies with files that haven't been uploaded, these will be uploaded next time rclone is run with the same flags. so don't panic if it crashes mid-upload, it remembers. 🫶

If using `--vfs-cache-max-size` or `--vfs-cache-min-free-space` note that the cache **may exceed these quotas** for two reasons. Firstly because it is only checked every `--vfs-cache-poll-interval`. Secondly because open files cannot be evicted from the cache. So it's a soft limit, not a hard wall, bestie.

When `--vfs-cache-max-size` or `--vfs-cache-min-free-space` is exceeded, rclone will attempt to evict the least accessed files from the cache first. rclone will start with files that haven't been accessed for the longest. This cache flushing strategy is efficient and more relevant files are likely to remain cached. it's basically "last opened, first evicted", very fair. ✨

The `--vfs-cache-max-age` will evict files from the cache after the set time since last access has passed. The default value of 1 hour will start evicting files from cache that haven't been accessed for 1 hour. When a cached file is accessed the 1 hour timer is reset to 0 and will wait for 1 more hour before evicting. Specify the time with standard notation: `s`, `m`, `h`, `d`, `w`.

> ⚠️ **You should NOT run two copies of rclone using the same VFS cache with the same or overlapping remotes if using `--vfs-cache-mode > off`.** This can potentially cause **data corruption** if you do. 😭 You can work around this by giving each rclone its own cache hierarchy with `--cache-dir`. You don't need to worry about this if the remotes in use don't overlap.

---

### –vfs-cache-mode off 🌚

In this mode (the default) the cache will read directly from the remote and write directly to the remote without caching anything on disk. zero bytes on your disk, maximum directness.

This will mean some operations are not possible:

- Files can't be opened for both read AND write
- Files opened for write can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files open for read with `O_TRUNC` will be opened write only
- Files open for write only will behave as if `O_TRUNC` was supplied
- Open modes `O_APPEND`, `O_TRUNC` are ignored
- If an upload fails it can't be retried

so yeah... very "do one thing at a time" energy.

---

### –vfs-cache-mode minimal 🐣

This is very similar to "off" except that files opened for read AND write will be buffered to disk. This means that files opened for write will be a lot more compatible, but uses the minimal disk space. tiny disk footprint, way more chill behaviour.

These operations are not possible:

- Files opened for write only can't be seeked
- Existing files opened for write must have `O_TRUNC` set
- Files opened for write only will ignore `O_APPEND`, `O_TRUNC`
- If an upload fails it can't be retried

---

### –vfs-cache-mode writes ✍️

In this mode files opened for read only are still read directly from the remote, write only and read/write files are buffered to disk first. reads stay direct, writes get buffered, cute split. 🌸

This mode should support all normal file system operations. slay.

If an upload fails it will be retried at exponentially increasing intervals up to 1 minute. 🔁

---

### –vfs-cache-mode full 👑

In this mode all reads and writes are buffered to and from disk. When data is read from the remote this is buffered to disk as well. everything, buffered, all of it.

In this mode the files in the cache will be **sparse files** and rclone will keep track of which bits of the files it has downloaded.

So if an application only reads the starts of each file, then rclone will only buffer the start of the file. These files will appear to be their full size in the cache, but they will be sparse files with only the data that has been downloaded present in them. it *looks* full-sized, it *is* mostly holes. fake it till you make it vibes. 💅

This mode should support all normal file system operations and is otherwise identical to `--vfs-cache-mode writes`.

When reading a file rclone will read `--buffer-size` plus `--vfs-read-ahead` bytes ahead. The `--buffer-size` is buffered in memory whereas the `--vfs-read-ahead` is buffered on disk. one in RAM, one on disk, bestie. ✨

When using this mode it is recommended that `--buffer-size` is not set too large and `--vfs-read-ahead` is set large if required.

> <red>**IMPORTANT**</red> not all file systems support sparse files. In particular **FAT/exFAT do not.** Rclone will perform **very badly** if the cache directory is on a filesystem which doesn't support sparse files and it will log an `ERROR` message if one is detected. 😭 Do not do this, fr fr.

---

### Fingerprinting 🔍

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. Fingerprints are made from:

- size
- modification time
- hash

...where available on an object.

On some backends some of these attributes are **slow to read** — they take an extra API call per object, or extra work per object. 💀

For example `hash` is slow with the `local` and `sftp` backends as they have to read the entire file and hash it, and `modtime` is slow with the `s3`, `swift`, `ftp` and `qinqstor` backends because they need to do an extra API call to fetch it.

If you use the `--vfs-fast-fingerprint` flag then rclone will not include the slow operations in the fingerprint. This makes the fingerprinting less accurate but much faster and will improve the opening time of cached files. tradeoff city, but usually worth it.

If you are running a vfs cache over `local`, `s3` or `swift` backends then using this flag is recommended.

> Note that if you change the value of this flag, the fingerprints of the files in the cache may be invalidated and the files will need to be **downloaded again**. 😬 so pick one and stay there.

---

### VFS Chunked Reading 🍫

When rclone reads files from a remote it reads them in chunks. This means that rather than requesting the whole file, rclone reads the chunk specified. This can reduce the used download quota for some remotes by requesting only chunks from the remote that are actually read — at the cost of an increased number of requests. fewer bytes, more requests, that's the trade. ✨

These flags control the chunking:

- **`--vfs-read-chunk-size`** *SizeSuffix* — read the source objects in chunks (default `128M`)
- **`--vfs-read-chunk-size-limit`** *SizeSuffix* — max chunk doubling size (default `off`)
- **`--vfs-read-chunk-streams`** *int* — the number of parallel streams to read at once

Right, so the chunking itself lowkey changes depending on what you set <pink>`--vfs-read-chunk-streams`</pink> to. Two whole moods:

---

## <cyan>`--vfs-read-chunk-streams` == 0</cyan> 🧊
> this is the "grow the chunk, bestie" era

Rclone starts off by reading a chunk that's the size of <pink>`--vfs-read-chunk-size`</pink>, and then it **doubles** that size for every single read. ✨

When <pink>`--vfs-read-chunk-size-limit`</pink> is specified, and it's greater than <pink>`--vfs-read-chunk-size`</pink>, the chunk size for each open file gets doubled **only until** it hits that specified value. If the value is `"off"` — which is the default, no cap — the limit is disabled and the chunk size just grows forever and ever, main character antics, no ceiling. 💅

With `--vfs-read-chunk-size 100M` and `--vfs-read-chunk-size-limit 0`, here's the download sequence you get:

- `0-100M`
- `100M-200M`
- `200M-300M`
- `300M-400M`
- and so on

Now swap in `--vfs-read-chunk-size-limit 500M` and it becomes:

- `0-100M`
- `100M-300M`
- `300M-700M`
- `700M-1200M`
- `1200M-1700M`
- and so on

Setting <pink>`--vfs-read-chunk-size`</pink> to `0` or `"off"` disables chunked reading entirely. Gone. Poof. 🫶

And heads up: the chunks are **not** buffered in memory. Nope, not a single one. 🧚

---

## <cyan>`--vfs-read-chunk-streams` > 0</cyan> 🚀
> this is the "go parallel or go home" era

Rclone reads <pink>`--vfs-read-chunk-streams`</pink> chunks, each of size <pink>`--vfs-read-chunk-size`</pink>, **concurrently**. And the size for each read stays constant — no doubling, we're stable here. 😌

This improves performance massively on high latency links, or on very high bandwidth links to high performance object stores. It's giving *actual* glow up.

Some experimentation will be needed to find the optimum values of <pink>`--vfs-read-chunk-size`</pink> and <pink>`--vfs-read-chunk-streams`</pink>, because these depend on the backend you're using and the latency to that backend. So yeah, tune it, queen. 🔧

For high performance object stores (eg AWS S3), a reasonable place to start might be `--vfs-read-chunk-streams 16` and `--vfs-read-chunk-size 4M`. In testing with AWS S3, the performance scaled roughly as the <pink>`--vfs-read-chunk-streams`</pink> setting. 📈

Similar settings should work for high latency links too, but depending on the latency they may need **more** <pink>`--vfs-read-chunk-streams`</pink> in order to get the throughput.

---

## <purple>VFS Performance</purple> ⚡

These flags may be used to enable/disable features of the VFS for performance or other reasons. See also the chunked reading feature. 👀

In particular **S3** and **Swift** benefit hugely from the <pink>`--no-modtime`</pink> flag (or use <pink>`--use-server-modtime`</pink> for a slightly different effect), because every single read of the modification time takes a transaction. Every. Single. One. 😭

- **`--no-checksum`** — Don't compare checksums on up/download.
- **`--no-modtime`** — Don't read/write the modification time (can speed things up).
- **`--no-seek`** — Don't allow seeking in files.
- **`--read-only`** — Only allow read-only access.

Sometimes rclone is delivered reads or writes **out of order**. Rather than seeking, rclone will wait a short time for the in-sequence read or write to come in. These flags only come into effect when not using an on disk cache file. 🕐

- **`--vfs-read-wait`** *duration* — Time to wait for in-sequence read before seeking (default `20ms`)
- **`--vfs-write-wait`** *duration* — Time to wait for in-sequence write before giving error (default `1s`)

When using VFS write caching (<pink>`--vfs-cache-mode`</pink> with value `writes` or `full`), the global flag <pink>`--transfers`</pink> can be set to adjust the number of parallel uploads of modified files from the cache. And btw — the related global flag <pink>`--checkers`</pink> has **no effect** on the VFS. Not a vibe, just a fact. 🙈

- **`--transfers`** *int* — Number of file transfers to run in parallel (default `4`)

---

## <hotpink>Symlinks</hotpink> 🪄

By default the VFS does **not** support symlinks. However, this may be enabled with either of the following flags:

- **`--links`** — Translate symlinks to/from regular files with a `.rclonelink` extension.
- **`--vfs-links`** — Translate symlinks to/from regular files with a `.rclonelink` extension for the VFS

Since most cloud storage systems don't support symlinks directly, rclone stores the symlink as a normal file with a special extension. So a file which appears as a symlink `link-to-file.txt` would be stored on cloud storage as `link-to-file.txt.rclonelink`, and the contents would be the path to the symlink destination. Sneaky but iconic. 💅

Note that <pink>`--links`</pink> enables symlink translation **globally** in rclone — this includes any backend which supports the concept (for example the local backend). <pink>`--vfs-links`</pink> just enables it for the VFS layer. Big difference, bestie.

This scheme is compatible with that used by the local backend with the `--local-links` flag. 🤝

The <pink>`--vfs-links`</pink> flag has been designed for `rclone mount`, `rclone nfsmount` and `rclone serve nfs`.

It hasn't been tested with the other `rclone serve` commands yet. 🧪 (so like, tread carefully?)

A limitation of the current implementation is that it expects the caller to resolve sub-symlinks. For example, given this directory tree:

. ├── dir │ └── file.txt └── linked-dir -> dir


The VFS will correctly resolve `linked-dir` but **not** `linked-dir/file.txt`. This is not a problem for the tested commands but may be for other commands. 🫠

> Note that there is an outstanding issue with symlink support — issue **#8245** — with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀

---

## <lavender>VFS Case Sensitivity</lavender> 🔠

Linux file systems are **case-sensitive**: two files can differ only by case, and the exact case must be used when opening a file.

File systems in modern Windows are **case-insensitive but case-preserving**: although existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. It is *not* allowed for two files in the same directory to differ only by case.

Usually file systems on macOS are case-insensitive. It is possible to make macOS file systems case-sensitive but that is **not** the default.

The <pink>`--vfs-case-insensitive`</pink> VFS flag controls how rclone handles these two cases. If its value is `"false"`, rclone passes file names to the remote as-is. If the flag is `"true"` (or appears without a value on the command line), rclone may perform a **"fixup"** as explained below. ✨

The user may specify a file name to open/delete/rename/etc with a case different than what is stored on the remote. If an argument refers to an existing file with exactly the same name, then the case of the existing file on the disk will be used. However, if a file name with exactly the same name is not found but a name differing only by case exists, rclone will transparently fixup the name. This fixup happens **only** when an existing file is requested. Case sensitivity of file names created anew by rclone is controlled by the underlying remote.

Note that case sensitivity of the operating system running rclone (the target) may differ from case sensitivity of a file system presented by rclone (the source). The flag controls whether "fixup" is performed to satisfy the target. 🤔

If the flag is not provided on the command line, then its default value depends on the operating system where rclone runs: `"true"` on Windows and macOS, `"false"` otherwise. If the flag is provided without a value, then it is `"true"`.

The <pink>`--no-unicode-normalization`</pink> flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent with respect to unicode. Unicode normalization can be particularly helpful for users of macOS, which prefers form **NFD** instead of the **NFC** used by most other platforms. It is therefore highly recommended to keep the default of `false` on macOS, to avoid encoding compatibility issues. 🙏

In the (probably unlikely) event that a directory has multiple duplicate filenames after applying case and unicode normalization, the <pink>`--vfs-block-norm-dupes`</pink> flag allows hiding these duplicates. This comes with a performance tradeoff, as rclone will have to scan the entire directory for duplicates when listing a directory. For this reason, it is recommended to leave this disabled if not needed. However, macOS users may wish to consider using it, as otherwise, if a remote directory contains both NFC and NFD versions of the same filename, an odd situation will occur: both versions of the file will be visible in the mount, and both will appear to be editable — however, editing either version will actually result in only the NFD version getting edited under the hood. 👀 <pink>`--vfs-block-norm-dupes`</pink> prevents this confusion by detecting this scenario, hiding the duplicates, and logging an error, similar to how this is handled in `rclone sync`.

---

## <mint>VFS Disk Options</mint> 💾

This flag allows you to manually set the statistics about the filing system. It can be useful when those statistics cannot be read correctly automatically. Sometimes the numbers are just lying, y'know? 😤

- **`--vfs-disk-space-total-size`** — Manually set the total disk space size (example: `256G`, default: `-1`)

---

## <peach>Alternate report of used bytes</peach> 🍓

Some backends, most notably **S3**, do not report the amount of bytes used. If you need this information to be available when running `df` on the filesystem, then pass the flag <pink>`--vfs-used-is-size`</pink> to rclone. With this flag set, instead of relying on the backend to report this information, rclone will scan the whole remote similar to `rclone size` and compute the total used space itself. 🔍

> **WARNING.** Contrary to `rclone size`, this flag ignores filters so that the result is accurate. However, this is **very inefficient** and may cost lots of API calls resulting in **extra charges**. Use it as a last resort and only with caching. 💸

---

## <purple>Auth Proxy</purple> 🔐

If you supply the parameter `--auth-proxy /path/to/program` then rclone will use that program to generate backends on the fly, which then are used to authenticate incoming requests. This uses a simple JSON based protocol with input on <cyan>STDIN</cyan> and output on <cyan>STDOUT</cyan>. ✨

> **PLEASE NOTE:** `--auth-proxy` and `--authorized-keys` cannot be used together. If `--auth-proxy` is set, the authorized keys option will be ignored. 🚫

There is an example program `bin/test_proxy.py` in the rclone source code.

The program's job is to take a `user` and `pass` on the input and turn those into the config for a backend on <cyan>STDOUT</cyan> in JSON format. This config will have any default parameters for the backend added, but it won't use configuration from environment variables or command line options — it is the job of the proxy program to make a complete config. 📝

This config generated must have this extra parameter:

- `_root` — root to use for the backend

And it may have this parameter:

- `_obscure` — comma separated strings for parameters to obscure

If password authentication was used by the client, input to the proxy process (on <cyan>STDIN</cyan>) would look similar to this:

{ "user": "me", "pass": "mypassword" }


If public-key authentication was used by the client, input to the proxy process (on <cyan>STDIN</cyan>) would look similar to this:

so <italic>and as an example</italic> return this on STDOUT 👇

{ "type": "sftp", "_root": "", "_obscure": "pass", "user": "me", "pass": "mypassword", "host": "sftp.example.com" }


This would mean that an SFTP backend would be created <pink>on the fly</pink> for the user and pass/public_key returned in the output to the host given. Note that since _obscure is set to pass, rclone will obscure the pass parameter before creating the backend (which is required for sftp backends).

The program can manipulate the supplied user in any way, for example to make proxy to many different sftp backends, you could make the user be `user@example.com` and then set the host to `example.com` in the output and the user to `user`. For security you'd probably want to restrict the host to a limited list. 🔒

Note that an internal cache is keyed on user so only use that for configuration, <red>don't</red> use pass or public_key. This also means that if a user's password or public-key is changed the cache will need to expire (which takes <yellow>5 mins</yellow>) before it takes effect. ⏳

This can be used to build general purpose proxies to any kind of backend that rclone supports. <rainbow>iconic behaviour honestly</rainbow> ✨

rclone serve webdav remote:path [flags]


---

## ✨ Options ✨

- **`--addr stringArray`** — IPaddress:Port, :Port or [unix://]/path/to/socket to bind server to (default [127.0.0.1:8080])
- **`--allow-origin string`** — Origin which cross-domain request (CORS) can be executed from
- **`--auth-proxy string`** — A program to use to create the backend from the auth
- **`--baseurl string`** — Prefix for URLs - leave blank for root
- **`--cert string`** — Path to TLS PEM public key certificate file (can also include intermediate/CA certificates)
- **`--client-ca string`** — Path to TLS PEM CA file with certificate authorities to verify clients with
- **`--dir-cache-time Duration`** — Time to cache directory entries for (default 5m0s)
- **`--dir-perms FileMode`** — Directory permissions (default 777)
- **`--disable-dir-list`** — Disable HTML directory list on GET request for a directory
- **`--etag-hash string`** — Which hash to use for the ETag, or auto or blank for off
- **`--file-perms FileMode`** — File permissions (default 666)
- **`--gid uint32`** — Override the gid field set by the filesystem (not supported on Windows) (default 1000)
- **`-h`, `--help`** — help for webdav
- **`--htpasswd string`** — A htpasswd file - if not provided no authentication is done
- **`--key string`** — Path to TLS PEM private key file
- **`--link-perms FileMode`** — Link permissions (default 666)
- **`--max-header-bytes int`** — Maximum size of request header (default 4096)
- **`--min-tls-version string`** — Minimum TLS version that is acceptable (default "tls1.0")
- **`--no-checksum`** — Don't compare checksums on up/download
- **`--no-modtime`** — Don't read/write the modification time (can speed things up)
- **`--no-seek`** — Don't allow seeking in files
- **`--pass string`** — Password for authentication
- **`--poll-interval Duration`** — Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
- **`--read-only`** — Only allow read-only access
- **`--realm string`** — Realm for authentication
- **`--salt string`** — Password hashing salt (default "dlPL2MqE")
- **`--server-read-timeout Duration`** — Timeout for server reading data (default 1h0m0s)
- **`--server-write-timeout Duration`** — Timeout for server writing data (default 1h0m0s)
- **`--template string`** — User-specified template
- **`--uid uint32`** — Override the uid field set by the filesystem (not supported on Windows) (default 1000)
- **`--umask FileMode`** — Override the permission bits set by the filesystem (not supported on Windows) (default 002)
- **`--user string`** — User name for authentication
- **`--vfs-block-norm-dupes`** — If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
- **`--vfs-cache-max-age Duration`** — Max time since last access of objects in the cache (default 1h0m0s)
- **`--vfs-cache-max-size SizeSuffix`** — Max total size of objects in the cache (default off)
- **`--vfs-cache-min-free-space SizeSuffix`** — Target minimum free space on the disk containing the cache (default off)
- **`--vfs-cache-mode CacheMode`** — Cache mode off|minimal|writes|full (default off)
- **`--vfs-cache-poll-interval Duration`** — Interval to poll the cache for stale objects (default 1m0s)
- **`--vfs-case-insensitive`** — If a file name not found, find a case insensitive match
- **`--vfs-disk-space-total-size SizeSuffix`** — Specify the total space of disk (default off)
- **`--vfs-fast-fingerprint`** — Use fast (less accurate) fingerprints for change detection
- **`--vfs-links`** — Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS
- **`--vfs-read-ahead SizeSuffix`** — Extra read ahead over --buffer-size when using cache-mode full
- **`--vfs-read-chunk-size SizeSuffix`** — Read the source objects in chunks (default 128Mi)
- **`--vfs-read-chunk-size-limit SizeSuffix`** — If greater than --vfs-read-chunk-size, double the chunk size after each chunk read, until the limit is reached ('off' is unlimited) (default off)
- **`--vfs-read-chunk-streams int`** — The number of parallel streams to read at once
- **`--vfs-read-wait Duration`** — Time to wait for in-sequence read before seeking (default 20ms)
- **`--vfs-refresh`** — Refreshes the directory cache recursively in the background on start
- **`--vfs-used-is-size rclone size`** — Use the rclone size algorithm for Used size
- **`--vfs-write-back Duration`** — Time to writeback files after last use when using cache (default 5s)
- **`--vfs-write-wait Duration`** — Time to wait for in-sequence write before giving error (default 1s)

Options shared with other commands are described next. See the global flags page for global options not listed here. 🫶

## 🌸 Filter Options 🌸

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest excluded from sync
- **`--exclude stringArray`** — Exclude files matching pattern
- **`--exclude-from stringArray`** — Read file exclude patterns from file (use - to read from stdin)
- **`--exclude-if-present stringArray`** — Exclude directories if filename is present
- **`--files-from stringArray`** — Read list of source-file names from file (use - to read from stdin)
- **`--files-from-raw stringArray`** — Read list of source-file names from file without any processing of lines (use - to read from stdin)
- **`-f`, `--filter stringArray`** — Add a file filtering rule
- **`--filter-from stringArray`** — Read file filtering patterns from a file (use - to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include stringArray`** — Include files matching pattern
- **`--include-from stringArray`** — Read file include patterns from file (use - to read from stdin)
- **`--max-age Duration`** — Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
- **`--max-depth int`** — If set limits the recursion depth to this (default -1)
- **`--max-size SizeSuffix`** — Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
- **`--metadata-exclude stringArray`** — Exclude metadatas matching pattern
- **`--metadata-exclude-from stringArray`** — Read metadata exclude patterns from file (use - to read from stdin)
- **`--metadata-filter stringArray`** — Add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — Read metadata filtering patterns from a file (use - to read from stdin)
- **`--metadata-include stringArray`** — Include metadatas matching pattern
- **`--metadata-include-from stringArray`** — Read metadata include patterns from file (use - to read from stdin)
- **`--min-age Duration`** — Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
- **`--min-size SizeSuffix`** — Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

## 👀 See Also 👀

- rclone serve - Serve a remote over a protocol.

---

# 🎀 rclone settier 🎀

Changes storage class/tier of objects in remote.

## 💫 Synopsis 💫

Changes storage tier or class at remote if supported. Few cloud storage services provides different storage classes on objects, for example AWS S3 and Glacier, Azure Blob storage - Hot, Cool and Archive, Google Cloud Storage, Regional Storage, Nearline, Coldline etc.

> ⚠️ Note that, certain tier changes make objects <red>not available to access immediately</red>. For example tiering to archive in azure blob storage makes objects in frozen state, user can restore by setting tier to Hot/Cool, similarly S3 to Glacier makes object inaccessible.`true` (bestie that trailing `true` is literally in there, we don't ask questions 😭)

You can use it to tier single object ✨

rclone settier Cool remote:path/file


Or use rclone filters to set tier on only specific files 💅

rclone --include "*.txt" settier Hot remote:path/dir


Or just provide remote directory and all files in directory will be tiered 🌈

rclone settier tier remote:path/dir

rclone settier tier remote:path [flags]


## ✨ Options ✨

- **`-h`, `--help`** — help for settier

See the global flags page for global options not listed here.

## 💖 See Also 💖

- rclone - Show help for rclone commands, flags and backends.

# 🌸 rclone test 🌸

Run a test command ✨

## Synopsis

Rclone test is literally where you go to run test commands. Pick which one you want with the subcommand, like this bestie:

rclone test memory remote:


Every subcommand has its own lil options and you can see them all in its own help. 💖

> NB bestie, be **careful** running these commands — they may do strange things 😭, so reading their docs first is highly recommended. No cap.

## Options

- **`-h`, `--help`** — help for test

See the global flags page for global options not listed here.

## See Also

- `rclone` - Show help for rclone commands, flags and backends.
- `rclone test changenotify` - Log any change notify requests for the remote passed in.
- `rclone test histogram` - Makes a histogram of file name characters.
- `rclone test info` - Discovers file name or other limitations for paths.
- `rclone test makefile` - Make files with random contents of the size given
- `rclone test makefiles` - Make a random file hierarchy in a directory
- `rclone test memory` - Load all the objects at `remote:path` into memory and report memory stats.

---

# 🦋 rclone test changenotify 🦋

Log any change notify requests for the remote passed in. 👀

rclone test changenotify remote: [flags]


## Options

- **`-h`, `--help`** — help for changenotify
- **`--poll-interval` *Duration*** — Time to wait between polling for changes (default `10s`)

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 💜 rclone test histogram 💜

Makes a histogram of file name characters. 📊

## Synopsis

This command outputs JSON which shows the histogram of characters used in filenames in the `remote:path` specified.

The data doesn't contain any identifying information but it's lowkey useful for the rclone devs when they're building filename compression. 🫶

rclone test histogram [remote:path] [flags]


## Options

- **`-h`, `--help`** — help for histogram

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 🔥 rclone test info 🔥

Discovers file name or other limitations for paths.

## Synopsis

This one finds out what filenames and upload methods are actually possible to write to the paths you pass in, and how long they can be. It can take some time ngl. It will write test files into the `remote:path` you passed in. Then it outputs a bit of go code for each one. 💅

> NB this can create **undeletable files** and other hazards 💀 — use with care, fr fr.

rclone test info [remote:path]+ [flags]


## Options

- **`--all`** — Run all tests
- **`--check-base32768`** — Check can store all possible base32768 characters
- **`--check-control`** — Check control characters
- **`--check-length`** — Check max filename length
- **`--check-normalization`** — Check UTF-8 Normalization
- **`--check-streaming`** — Check uploads with indeterminate file size
- **`-h`, `--help`** — help for info
- **`--keep-test-files`** — Keep test files after execution
- **`--upload-wait` *Duration*** — Wait after writing a file (default `0s`)
- **`--write-json` *string*** — Write results to file

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 🎀 rclone test makefile 🎀

Make files with random contents of the size given ✨

rclone test makefile <size> [<file>]+ [flags]


## Options

- **`--ascii`** — Fill files with random ASCII printable bytes only
- **`--chargen`** — Fill files with a ASCII chargen pattern
- **`-h`, `--help`** — help for makefile
- **`--pattern`** — Fill files with a periodic pattern
- **`--seed` *int*** — Seed for the random number generator (`0` for random) (default `1`)
- **`--sparse`** — Make the files sparse (appear to be filled with ASCII `0x00`)
- **`--zero`** — Fill files with ASCII `0x00`

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 🌈 rclone test makefiles 🌈

Make a random file hierarchy in a directory 🗂️✨

rclone test makefiles <dir> [flags]


## Options

- **`--ascii`** — Fill files with random ASCII printable bytes only
- **`--chargen`** — Fill files with a ASCII chargen pattern
- **`--files` *int*** — Number of files to create (default `1000`)
- **`--files-per-directory` *int*** — Average number of files per directory (default `10`)
- **`--flat`** — If set create all files in the root directory
- **`-h`, `--help`** — help for makefiles
- **`--max-depth` *int*** — Maximum depth of directory hierarchy (default `10`)
- **`--max-file-size` *SizeSuffix*** — Maximum size of files to create (default `100`)
- **`--max-name-length` *int*** — Maximum size of file names (default `12`)
- **`--min-file-size` *SizeSuffix*** — Minimum size of file to create
- **`--min-name-length` *int*** — Minimum size of file names (default `4`)
- **`--pattern`** — Fill files with a periodic pattern
- **`--seed` *int*** — Seed for the random number generator (`0` for random) (default `1`)
- **`--sparse`** — Make the files sparse (appear to be filled with ASCII `0x00`)
- **`--zero`** — Fill files with ASCII `0x00`

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 🧚 rclone test memory 🧚

Load all the objects at `remote:path` into memory and report memory stats. 🧠✨

rclone test memory remote:path [flags]


## Options

- **`-h`, `--help`** — help for memory

See the global flags page for global options not listed here.

## See Also

- `rclone test` - Run a test command

---

# 👑 rclone touch 👑

Create new file or change file modification time. ⏰

## Synopsis

Set the modification time on file(s) as specified by `remote:path` to have the current time.

If `remote:path` does not exist then a zero sized file will be created — unless `--no-create` or `--recursive` is provided.

If `--recursive` is used then it recursively sets the modification time on all existing files that is found under the path. Filters are supported bestie, and you can test with the `--dry-run` or the `--interactive`/`-i` flag. 🫶

If `--timestamp` is used then it sets the modification time to that time instead of the current time. Times may be specified as one of:

- `YYMMDD'` - e.g. `17.10.30`
- `YYYY-MM-DDTHH:MM:SS'` - e.g. `2006-01-02T15:04:05`
- `YYYY-MM-DDTHH:MM:SS.SSS'` - e.g. `2006-01-02T15:04:05.123456789`

Note that the value of `--timestamp` is in UTC. If you want local time then add the `--localtime` flag. 🌍

rclone touch remote:path [flags]


## Options

- **`-h`, `--help`** — help for touch
- **`--localtime`** — Use localtime for timestamp, not UTC
- **`-C`, `--no-create`** — Do not create the file if it does not exist (implied with `--recursive`)
- **`-R`, `--recursive`** — Recursively touch all files
- **`-t`, `--timestamp` *string*** — Use specified time instead of the current time of day

Options shared with other commands are described next. See the global flags page for global options not listed here.

## Important Options

Important flags useful for most commands 💅

- **`-n`, `--dry-run`** — Do a trial run with no permanent changes
- **`-i`, `--interactive`** — Enable interactive mode
- **`-v`, `--verbose` *count*** — Print lots more stuff (repeat for more)

## Filter Options

Flags for filtering directory listings 🕵️

- **`--delete-excluded`** — Delete files on dest excluded from sync
- **`--exclude` *stringArray*** — Exclude files matching pattern
- **`--exclude-from` *stringArray*** — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present` *stringArray*** — Exclude directories if filename is present
- **`--files-from` *stringArray*** — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw` *stringArray*** — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter` *stringArray*** — Add a file filtering rule
- **`--filter-from` *stringArray*** — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include` *stringArray*** — Include files matching pattern
- **`--include-from` *stringArray*** — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age` *Duration*** — Only transfer files younger than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--max-depth` *int*** — If set limits the recursion depth to this (default `-1`)
- **`--max-size` *SizeSuffix*** — Only transfer files smaller than this in KiB or suffix `B|K|M|G|T|P` (default off)
- **`--metadata-exclude` *stringArray*** — Exclude metadatas matching pattern
- **`--metadata-exclude-from` *stringArray*** — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter` *stringArray*** — Add a metadata filtering rule
- **`--metadata-filter-from` *stringArray*** — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include` *stringArray*** — Include metadatas matching pattern
- **`--metadata-include-from` *stringArray*** — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age` *Duration*** — Only transfer files older than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--min-size` *SizeSuffix*** — Only transfer files bigger than this in KiB or suffix `B|K|M|G|T|P` (default off)

## Listing Options

Flags for listing directories 📂

- **`--default-time` *Time*** — Time to show if modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--fast-list`** — Use recursive list if available; uses more memory but fewer transactions

## See Also

- `rclone` - Show help for rclone commands, flags and backends.

---

# 🍓 rclone tree 🍓

List the contents of the remote in a tree like fashion. 🌳

## Synopsis

Lists the contents of a remote in a similar way to the unix `tree` command.

For example 🔍

$ rclone tree remote:path / ├── file1 ├── file2 ├── file3 └── subdir ├── file4 └── file5

1 directories, 5 files


You can use any of the filtering options with the tree command (e.g. `--include` and `--exclude`. You can also use `--fast-list`.

The tree command has *so* many options for controlling the listing, and they're compatible with the regular `tree` command — so like, you can include file sizes with `--size` and it just works 💖. But heads up bestie: **not all of them have short options**, because they'd beef with rclone's own short options. iykyk.

For a more interactive navigation of the remote, go check out the `ncdu` command instead. It's giving ✨ explore mode ✨.

rclone tree remote:path [flags]


### 🌳 Options

- **`-a`, `--all`** — All files are listed (list `.` files too) 👀
- **`-d`, `--dirs-only`** — List directories only
- **`--dirsfirst`** — List directories before files (and `-U` disables this)
- **`--full-path`** — Print the full path prefix for each file
- **`-h`, `--help`** — help for `tree`
- **`--level`** *int* — Descend only *level* directories deep
- **`-D`, `--modtime`** — Print the date of last modification.
- **`--noindent`** — Don't print indentation lines
- **`--noreport`** — Turn off the file/directory count at the end of the tree listing
- **`-o`, `--output`** *string* — Output to file instead of stdout
- **`-p`, `--protections`** — Print the protections for each file.
- **`-Q`, `--quote`** — Quote filenames with double quotes.
- **`-s`, `--size`** — Print the size in bytes of each file.
- **`--sort`** *string* — Select sort: `name`, `version`, `size`, `mtime`, `ctime`
- **`--sort-ctime`** — Sort files by last status change time
- **`-t`, `--sort-modtime`** — Sort files by last modification time
- **`-r`, `--sort-reverse`** — Reverse the order of the sort
- **`-U`, `--unsorted`** — Leave files unsorted
- **`--version`** — Sort files alphanumerically by version

Options shared with other commands are described next. Peep the global flags page for global options that aren't listed here 👑

### 🎀 Filter Options

Flags for filtering directory listings

- **`--delete-excluded`** — Delete files on dest that are excluded from sync
- **`--exclude`** *stringArray* — Exclude files matching pattern
- **`--exclude-from`** *stringArray* — Read file exclude patterns from file (use `-` to read from stdin)
- **`--exclude-if-present`** *stringArray* — Exclude directories if filename is present
- **`--files-from`** *stringArray* — Read list of source-file names from file (use `-` to read from stdin)
- **`--files-from-raw`** *stringArray* — Read list of source-file names from file without any processing of lines (use `-` to read from stdin)
- **`-f`, `--filter`** *stringArray* — Add a file filtering rule
- **`--filter-from`** *stringArray* — Read file filtering patterns from a file (use `-` to read from stdin)
- **`--ignore-case`** — Ignore case in filters (case insensitive)
- **`--include`** *stringArray* — Include files matching pattern
- **`--include-from`** *stringArray* — Read file include patterns from file (use `-` to read from stdin)
- **`--max-age`** *Duration* — Only transfer files younger than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--max-depth`** *int* — If set, limits the recursion depth to this (default `-1`)
- **`--max-size`** *SizeSuffix* — Only transfer files smaller than this in KiB or suffix `B|K|M|G|T|P` (default off)
- **`--metadata-exclude`** *stringArray* — Exclude metadatas matching pattern
- **`--metadata-exclude-from`** *stringArray* — Read metadata exclude patterns from file (use `-` to read from stdin)
- **`--metadata-filter`** *stringArray* — Add a metadata filtering rule
- **`--metadata-filter-from`** *stringArray* — Read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include`** *stringArray* — Include metadatas matching pattern
- **`--metadata-include-from`** *stringArray* — Read metadata include patterns from file (use `-` to read from stdin)
- **`--min-age`** *Duration* — Only transfer files older than this in `s` or suffix `ms|s|m|h|d|w|M|y` (default off)
- **`--min-size`** *SizeSuffix* — Only transfer files bigger than this in KiB or suffix `B|K|M|G|T|P` (default off)

### 🌈 Listing Options

Flags for listing directories

- **`--default-time`** *Time* — Time to show if modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--fast-list`** — Use recursive list if available; uses more memory but fewer transactions

### 💅 See Also

- `rclone` - Show help for rclone commands, flags and backends.

---

## 🫶 Copying single files

Okay so normally rclone syncs or copies **directories**. But — plot twist — if the source remote points to a *file*, rclone will just copy that one file 🍓. The destination remote has to point to a directory though. If it doesn't, rclone will hit you with the error `Failed to create file system for "remote:file": is a file not a directory`. Not a vibe, but there it is.

For example, suppose you have a remote with a file in it called `test.jpg`. Then you could copy just that file like this:

rclone copy remote:test.jpg /tmp/download


The file `test.jpg` will be placed inside `/tmp/download`. Iconic.

This is equivalent to specifying

rclone copy --files-from /tmp/files remote: /tmp/download


Where `/tmp/files` contains the single line

test.jpg


It is recommended to use `copy` when copying individual files, **not** `sync`. They have pretty much the same effect but `copy` will use a lot less memory. So like, be kind to your RAM bestie 😭.

---

## 🧚 Syntax of remote paths

The syntax of the paths passed to the rclone command are as follows. Buckle up, it's giving lore drop ✨.

### `/path/to/dir`

This refers to the local file system.

On Windows, `\` may be used instead of `/` in **local paths only** — non local paths must use `/`. See the local filesystem documentation for more about Windows-specific paths.

These paths needn't start with a leading `/` — if they don't, then they will be relative to the current directory. Cute and flexible 💖.

### `remote:path/to/dir`

This refers to a directory `path/to/dir` on `remote:` as defined in the config file (configured with `rclone config`).

### `remote:/path/to/dir`

On most backends this refers to the same directory as `remote:path/to/dir` and that format should be preferred 👑. But on a very small number of remotes (FTP, SFTP, Dropbox for business) this will refer to a *different* directory. On these, paths without a leading `/` will refer to your "home" directory and paths with a leading `/` will refer to the root. So like, check which one you're on, fr fr.

### `:backend:path/to/dir`

This is an advanced form for creating remotes on the fly 🔥. `backend` should be the name or prefix of a backend (the `type` in the config file) and all the configuration for the backend should be provided on the command line (or in environment variables).

Here are some examples:

rclone lsd --http-url https://pub.rclone.org :http:


To list all the directories in the root of `https://pub.rclone.org/`.

rclone lsf --http-url https://example.com :http:path/to/dir


To list files and directories in `https://example.com/path/to/dir/`.

rclone copy --http-url https://example.com :http:path/to/dir /tmp/dir


To copy files and directories in `https://example.com/path/to/dir` to `/tmp/dir`.

rclone copy --sftp-host example.com :sftp:path/to/dir /tmp/dir


To copy files and directories from `example.com` in the relative directory `path/to/dir` to `/tmp/dir` using sftp.

---

## 🌸 Connection strings

The above examples can also be written using a connection string syntax. So instead of providing the arguments as command line parameters `--http-url https://pub.rclone.org` they are provided as part of the remote specification as a kind of connection string 💫.

rclone lsd ":http,url='https://pub.rclone.org':" rclone lsf ":http,url='https://example.com':path/to/dir" rclone copy ":http,url='https://example.com':path/to/dir" /tmp/dir rclone copy :sftp,host=example.com:path/to/dir /tmp/dir


These can apply to modify existing remotes as well as create new remotes with the on the fly syntax ✨. This example is equivalent to adding the `--drive-shared-with-me` parameter to the remote `gdrive:`.

rclone lsf "gdrive,shared_with_me:path/to/dir"


The major advantage to using the connection string style syntax is that it **only applies to the remote**, not to all the remotes of that type on the command line. A common confusion is this attempt to copy a file shared on google drive to the normal drive which does not work because the `--drive-shared-with-me` flag applies to both the source and the destination. 💀

rclone copy --drive-shared-with-me gdrive:shared-file.txt gdrive:


However using the connection string syntax, this **does** work 🎉.

rclone copy "gdrive,shared_with_me:shared-file.txt" gdrive:


> Note that the connection string only affects the options of the immediate backend. If for example `gdriveCrypt` is a crypt based on `gdrive`, then the following command will not work as intended, because `shared_with_me` is ignored by the crypt backend:

rclone copy "gdriveCrypt,shared_with_me:shared-file.txt" gdriveCrypt:


The connection strings have the following syntax

remote,parameter=value,parameter2=value2:path/to/dir :backend,parameter=value,parameter2=value2:path/to/dir


If the parameter has a `:` or `,` then it must be placed in quotes `"` or `'`, so

remote,parameter="colon:value",parameter2="comma,value":path/to/dir :backend,parameter='colon:value',parameter2='comma,value':path/to/dir


If a quoted value needs to include that quote, then it should be doubled, so

remote,parameter="with""quote",parameter2='with''quote':path/to/dir


This will make `parameter` be `with"quote` and `parameter2` be `with'quote`.

If you leave off the `=parameter` then rclone will substitute `=true` which works very well with flags 🫶. For example, to use s3 configured in the environment you could use:

rclone lsd :s3,env_auth:


Which is equivalent to

rclone lsd :s3,env_auth=true:


> Note that on the command line you might need to surround these connection strings with `"` or `'` to stop the shell interpreting any special characters within them.

If you are a shell master then you'll know which strings are OK and which aren't, but if you aren't sure then enclose them in `"` and use `'` as the inside quote. This syntax works on all OSes 💅.

rclone copy ":http,url='https://example.com':path/to/dir" /tmp/dir


On Linux/macOS some characters are still interpreted inside `"` strings in the shell (notably `\` and `$` and `"`) so if your strings contain those you can swap the roles of `"` and `'` thus. (This syntax does **not** work on Windows.)

rclone copy ':http,url="https://example.com":path/to/dir' /tmp/dir


---

## 💜 Connection strings, config and logging

If you supply extra configuration to a backend by command line flag, environment variable or connection string then rclone will add a suffix based on the hash of the config to the name of the remote, eg

rclone -vv lsf --s3-chunk-size 20M s3:


Has the log message

That `DEBUG` line looks like

DEBUG : s3: detected overridden config - adding "{Srj1p}" suffix to name


and it's there so rclone can tell the modified remote apart from the unmodified remote when it's caching the backends 💅 it's literally just so the two versions don't get their wires crossed in the cache.

You should only ever see it in the logs, bestie. Nowhere else. Not a vibe, not a problem, just a log.

So this means the on-the-fly backends, like

rclone -vv lsf :s3,env_auth:


will get their own names, like

DEBUG : :s3: detected overridden config - adding "{YTu53}" suffix to name


## ✨ Valid remote names ✨

Remote names are **case sensitive**, and they gotta follow these rules, no cap:

- May contain number, letter, `_`, `-`, `.`, `+`, `@` and space.
- May not start with `-` or space.
- May not end with space.

Starting with rclone version **1.61**, any Unicode numbers and letters are allowed 😌 while in older versions it was limited to plain ASCII (`0-9`, `A-Z`, `a-z`). So if you use the same rclone configuration from different shells, which may be configured with different character encoding, you have to be cautious and only use characters that are possible to write in *all* of them. This is mostly a problem on Windows, where the console traditionally uses a non-Unicode character set — defined by the so-called “code page”. 😭

Do **not** use single character names on Windows, fr fr, because it creates ambiguity with Windows drives' names. Like, a remote called `C` is indistinguishable from the C drive. Rclone will always assume that a single letter name refers to a drive. 🙈

## 🐚 Quoting and the shell 🐚

When you're typing commands into your computer you're using something called the command line shell, and it interprets various characters in an OS specific way. Rude of it honestly.

Here are some gotchas that will help users who aren't familiar with the shell rules 💖

### 🐧 Linux / OSX 🐧

If your names have spaces or shell metacharacters (e.g. `*`, `?`, `$`, `'`, `"`, etc.) then you **must** quote them. Use single quotes `'` by default.

rclone copy 'Important files?' remote:backup


If you want to send a `'` you will need to use `"`, e.g.

rclone copy "O'Reilly Reviews" remote:backup


The rules for quoting metacharacters are complicated and if you want the full details you'll have to consult the manual page for your shell. Not me, bestie, that's between you and `man bash`. 😌

### 🪟 Windows 🪟

If your names have spaces in you need to put them in `"`, e.g.

rclone copy "E:\folder name\folder name\folder name" remote:backup


If you are using the root directory on its own then **don't** quote it (see #464 for why), e.g.

rclone copy E:\ remote:backup


## 📁 Copying files or directories with `:` in the names 📁

rclone uses `:` to mark a remote name. Which is iconic of it, but `:` is also a valid filename component in non-Windows OSes. So the remote name parser will only search for a `:` up to the first `/`. Meaning: if you need to act on a file or directory like that, use the full path starting with a `/`, or use `./` as a current directory prefix. 💅

So to sync a directory called `sync:me` to a remote called `remote:` use

rclone sync --interactive ./sync:me remote:path

or

rclone sync --interactive /full/path/to/sync:me remote:path


## ⚡ Server Side Copy ⚡

Most remotes (but not all — go check the overview) support server-side copy.

This means if you want to copy one folder to another then rclone won't download all the files and re-upload them; it will instruct the server to copy them in place. Obsessed with the efficiency honestly. 🔥

Eg

rclone copy s3:oldbucket s3:newbucket


Will copy the contents of `oldbucket` to `newbucket` without downloading and re-uploading.

Remotes which don't support server-side copy will download and re-upload in this case. Their loss.

Server side copies are used with `sync` and `copy` and will be identified in the log when using the `-v` flag. The `move` command may also use them if the remote doesn't support server-side move directly. This is done by issuing a server-side copy then a delete, which is *much* quicker than a download and re-upload. 🌸

Server side copies will only be attempted if the remote names are the same.

This can be used when scripting to make aged backups efficiently, e.g.

rclone sync --interactive remote:current-backup remote:previous-backup rclone sync --interactive /path/to/files remote:current-backup


## 🏷️ Metadata support 🏷️

Metadata is data about a file (or directory) which isn't the contents of the file (or directory). Normally rclone only preserves the modification time and the content (MIME) type where possible.

Rclone supports preserving *all* the available metadata on files and directories when using the `--metadata` or `-M` flag. 💖

Exactly what metadata is supported and what that support means depends on the backend. Backends that support metadata have a metadata section in their docs and are listed in the features table (Eg `local`, `s3`).

Some backends don't support metadata, some only support metadata on files, and some support metadata on both files and directories.

Rclone only supports a **one-time** sync of metadata. This means metadata will be synced from the source object to the destination object only when the source object has changed and needs to be re-uploaded. If the metadata subsequently changes on the source object without changing the object itself, then it won't be synced to the destination object. This is in line with the way rclone syncs Content-Type without the `--metadata` flag. 🫶

Using `--metadata` when syncing from local to local will preserve file attributes such as file mode, owner, extended attributes (not Windows).

Note that arbitrary metadata may be added to objects using the `--metadata-set` key=value flag when the object is first uploaded. This flag can be repeated as many times as necessary. So many times. Go off. ✨

The `--metadata-mapper` flag can be used to pass the name of a program in which can transform metadata when it is being copied from source to destination.

Rclone supports `--metadata-set` and `--metadata-mapper` when doing sever side Move and server side Copy, but **not** when doing server side DirMove (renaming a directory) as this would involve recursing into the directory. Note that you can disable DirMove with `--disable DirMove` and rclone will revert back to using Move for each individual object where `--metadata-set` and `--metadata-mapper` are supported.

### Types of metadata 💜

Metadata is divided into two type. System metadata and User metadata.

Metadata which the backend uses itself is called **system metadata**. For example on the local backend the system metadata `uid` will store the user ID of the file when used on a unix based platform.

Arbitrary metadata is called **user metadata** and this can be set however is desired.

When objects are copied from backend to backend, they will attempt to interpret system metadata if it is supplied. Metadata may change from being user metadata to system metadata as objects are copied between different backends. For example copying an object from s3 sets the content-type metadata. In a backend which understands this (like `azureblob`) this will become the Content-Type of the object. In a backend which doesn't understand this (like the local backend) this will become user metadata. However should the local object be copied back to s3, the Content-Type will be set correctly. Glow up, metadata. 🌈

### Metadata framework 🎀

Rclone implements a metadata framework which can read metadata from an object and write it to the object when (and only when) it is being uploaded.

This metadata is stored as a dictionary with string keys and string values.

There are some limits on the names of the keys (these may be clarified further in the future).

- must be lower case
- may be `a-z` `0-9` containing `.` `-` or `_`
- length is backend dependent

Each backend can provide system metadata that it understands. Some backends can also store arbitrary user metadata.

Where possible the key names are standardized, so, for example, it is possible to copy object metadata from s3 to azureblob for example and metadata will be translated appropriately. 💅

Some backends have limits on the size of the metadata and rclone will give errors on upload if they are exceeded.

### Metadata preservation 🦋

The goal of the implementation is to

1. Preserve metadata if at all possible
2. Interpret metadata if at all possible

The consequences of 1 is that you can copy an S3 object to a local disk then back to S3 losslessly. Likewise you can copy a local file with file attributes and xattrs from local disk to s3 and back again losslessly.

The consequence of 2 is that you can copy an S3 object with metadata to Azureblob (say) and have the metadata appear on the Azureblob object also. Ate. 👑

### Standard system metadata ⭐

Here is a table of standard system metadata which, if appropriate, a backend may implement.

- `mode` — File type and mode: octal, unix style — example: `0100664`
- `uid` — User ID of owner: decimal number — example: `500`
- `gid` — Group ID of owner: decimal number — example: `500`
- `rdev` — Device ID (if special file) => hexadecimal — example: `0`
- `atime` — Time of last access: RFC 3339 — example: `2006-01-02T15:04:05.999999999Z07:00`
- `mtime` — Time of last modification: RFC 3339 — example: `2006-01-02T15:04:05.999999999Z07:00`
- `btime` — Time of file creation (birth): RFC 3339 — example: `2006-01-02T15:04:05.999999999Z07:00`
- `utime` — Time of file upload: RFC 3339 — example: `2006-01-02T15:04:05.999999999Z07:00`
- `cache-control` — `Cache-Control` header — example: `no-cache`
- `content-disposition` — `Content-Disposition` header — example: `inline`
- `content-encoding` — `Content-Encoding` header — example: `gzip`
- `content-language` — `Content-Language` header — example: `en-US`
- `content-type` — `Content-Type` header — example: `text/plain`

The metadata keys `mtime` and `content-type` will take precedence if supplied in the metadata over reading the Content-Type or modification time of the source object.

Hashes are **not** included in system metadata as there is a well defined way of reading those already. 💀

## ✨ Options ✨

okay so rclone has a <pink>whole</pink> bunch of options that control its behaviour, bestie, and honestly they're the main character of this whole page 💅

Options that take parameters can have the values passed in <hotpink>two ways</hotpink>: `--option=value` or `--option value`. But <purple>boolean</purple> (true/false) options are built a little different from everything else — `--boolean` sets the option to `true`, and just <italic>not</italic> having the flag sets it to `false`. You can also do `--boolean=false` or `--boolean=true`. 💖

> careful though: `--boolean false` is **NOT valid** 😭 it gets parsed as `--boolean` and then the `false` gets parsed as an extra command line argument for rclone. no cap.

Options documented to take a `stringArray` parameter accept <cyan>multiple</cyan> values. To pass more than one value, just repeat the option; for example:

--include value1 --include value2


---

### ⏰ Time or duration options ⏰

`TIME` or `DURATION` options can be given as a <mint>duration string</mint> or a <mint>time string</mint>. fr fr, both work.

A duration string is a possibly <italic>signed</italic> sequence of decimal numbers, each with optional fraction and a unit suffix, like `300ms`, `-1.5h` or `2h45m` ✨ Default units are seconds, or you can use these abbreviations:

- `ms` — Milliseconds
- `s` — Seconds
- `m` — Minutes
- `h` — Hours
- `d` — Days
- `w` — Weeks
- `M` — Months
- `y` — Years

These can also be specified as an <purple>absolute time</purple> in the following formats:

- RFC3339 — e.g. `2006-01-02T15:04:05Z` or `2006-01-02T15:04:05+07:00`
- ISO8601 Date and time, local timezone — `2006-01-02T15:04:05`
- ISO8601 Date and time, local timezone — `2006-01-02 15:04:05`
- ISO8601 Date — `2006-01-02` (YYYY-MM-DD)

---

### 📏 Size options 📏

Options that use `SIZE` use <hotpink>KiB</hotpink> (multiples of 1024 bytes) by default. But you can slap a suffix on: `B` for Byte, `K` for KiB, `M` for MiB, `G` for GiB, `T` for TiB and `P` for PiB. These are the <italic>binary</italic> units, e.g. 1, 2\*\*10, 2\*\*20, 2\*\*30 respectively. iconic. 🫶

---

### 🗂️ `--backup-dir=DIR`

When you're using `sync`, `copy` or `move`, any files that <red>would have been overwritten or deleted</red> get moved — in their original hierarchy — into this directory. so nothing is ever really gone, bestie 💀

If `--suffix` is set, then the moved files will have the suffix added to them. And if there's already a file with the same path (after the suffix has been added) in `DIR`, then it will be <yellow>overwritten</yellow>.

The remote in use must support <purple>server-side move or copy</purple> and you must use the <hotpink>same remote</hotpink> as the destination of the sync. The backup directory must <bold>not</bold> overlap the destination directory unless it's excluded by a filter rule.

For example:

rclone sync --interactive /path/to/local remote:current --backup-dir remote:old


will sync `/path/to/local` to `remote:current`, but for any files that would have been updated or deleted they'll be stored in `remote:old`.

If you're running rclone from a script, you might want to use <italic>today's date</italic> as the directory name passed to `--backup-dir` to store the old files, or you might want to pass `--suffix` with today's date. cute and organized ✨

See `--compare-dest` and `--copy-dest`.

---

### 🔌 `--bind string`

Local address to bind to for outgoing connections. This can be an IPv4 address (`1.2.3.4`), an IPv6 address (`1234::789A`) or a host name. If the host name doesn't resolve, or resolves to <red>more than one</red> IP address, it will give an error. ngl that's strict.

You can use `--bind 0.0.0.0` to force rclone to use IPv4 addresses and `--bind ::0` to force rclone to use IPv6 addresses. <cyan>vibe check passed</cyan> 🌈

---

### 🚦 `--bwlimit=BANDWIDTH_SPEC`

This option controls the bandwidth limit. For example:

--bwlimit 10M


would mean limit the upload <italic>and</italic> download bandwidth to 10 MiB/s. NB this is <hotpink>bytes</hotpink> per second, not bits per second 👑 To use a single limit, specify the desired bandwidth in KiB/s, or use a suffix `B|K|M|G|T|P`. The default is `0`, which means <green>no limit</green> — go wild.

The upload and download bandwidth can be specified separately, as `--bwlimit UP:DOWN`, so:

--bwlimit 10M:100k


would mean limit the upload bandwidth to 10 MiB/s and the download bandwidth to 100 KiB/s. Either limit can be `off`, meaning no limit, so to just limit the upload bandwidth you'd use:

--bwlimit 10M:off


this would limit the upload bandwidth to 10 MiB/s but the download bandwidth would be <rainbow>unlimited</rainbow>.

When specified as above, the bandwidth limits last for the duration of the run of the rclone binary.

It's also possible to specify a <purple>"timetable"</purple> of limits, which will cause certain limits to be applied at certain times. To specify a timetable, format your entries as `WEEKDAY-HH:MM,BANDWIDTH WEEKDAY-HH:MM,BANDWIDTH...` where: `WEEKDAY` is an optional element. 💅

- `BANDWIDTH` can be a single number, e.g. `100k` or a pair of numbers for upload:download, e.g. `10M:1M`.
- `WEEKDAY` can be written as the whole word or only using the first 3 characters. It is optional.
- `HH:MM` is an hour from `00:00` to `23:59`.

Entries can be separated by <mint>spaces</mint> or <mint>semicolons</mint>.

> Note: semicolons can be used as separators instead of spaces to avoid parsing issues in environments like Docker. 🐳

An example of a typical timetable to avoid link saturation during daytime working hours could be:

Using spaces as separators:

--bwlimit "08:00,512k 12:00,10M 13:00,512k 18:00,30M 23:00,off"


Using semicolons as separators:

--bwlimit "08:00,512k;12:00,10M;13:00,512k;18:00,30M;23:00,off"


In these examples, the transfer bandwidth will be set to 512 KiB/s at 8am every day. At noon, it'll rise to 10 MiB/s, and drop back to 512 KiB/sec at 1pm. At 6pm, the bandwidth limit will be set to 30 MiB/s, and at 11pm it'll be completely disabled (full speed). Anything between 11pm and 8am will remain unlimited. 🌙

An example of a timetable with `WEEKDAY` could be:

Using spaces as separators:

--bwlimit "Mon-00:00,512 Fri-23:59,10M Sat-10:00,1M Sun-20:00,off"


Using semicolons as separators:

--bwlimit "Mon-00:00,512;Fri-23:59,10M;Sat-10:00,1M;Sun-20:00,off"


It means that the transfer bandwidth will be set to 512 KiB/s on Monday. It'll rise to 10 MiB/s before the end of Friday. At 10:00 on Saturday it'll be set to 1 MiB/s. From 20:00 on Sunday it'll be unlimited. 🦋

Timeslots without `WEEKDAY` are extended to the whole week. So this example:

--bwlimit "Mon-00:00,512 12:00,1M Sun-20:00,off"


is equivalent to this:

--bwlimit "Mon-00:00,512Mon-12:00,1M Tue-12:00,1M Wed-12:00,1M Thu-12:00,1M Fri-12:00,1M Sat-12:00,1M Sun-12:00,1M Sun-20:00,off"


Bandwidth limits apply to the data transfer for <bold>all</bold> backends. For most backends the directory listing bandwidth is also included — exceptions being the non HTTP backends, `ftp`, `sftp` and `storj`.

Note that the units are <hotpink>Byte/s</hotpink>, not bit/s. Typically connections are measured in bit/s — to convert, divide by 8. For example, let's say you have a 10 Mbit/s connection and you want rclone to use half of it — 5 Mbit/s. This is 5/8 = 0.625 MiB/s so you would use a `--bwlimit 0.625M` parameter for rclone. math girlie moment 🧮✨

On Unix systems (Linux, macOS, ...) the bandwidth limiter can be toggled by sending a `SIGUSR2` signal to rclone. This lets you remove the limitations of a long running rclone transfer and restore it back to the value specified with `--bwlimit` quickly when needed. Assuming there's only one rclone instance running, you can toggle the limiter like this:

kill -SIGUSR2 $(pidof rclone)


If you configure rclone with a remote control then you can change the `bwlimit` dynamically:

rclone rc core/bwlimit rate=1M


---

### 🐌 `--bwlimit-file=BANDWIDTH_SPEC`

This option controls the <purple>per file</purple> bandwidth limit. For the options see the `--bwlimit` flag.

For example use this to allow no transfers to be faster than 1 MiB/s:

--bwlimit-file 1M


This can be used in conjunction with `--bwlimit`. 🫶

> Note that if a schedule is provided, the file will use the schedule in effect at the <bold>start</bold> of the transfer.

---

### 🧺 `--buffer-size=SIZE`

Use this sized buffer to speed up file transfers. Each `--transfer` will use this much memory for buffering. 💾

When using `mount` or `cmount`, each open file descriptor will use this much memory for buffering. See the mount documentation for more details.

Set to `0` to disable the buffering for the minimum memory usage.

> Note that the memory allocation of the buffers is influenced by the `--use-mmap` flag.

---

### 🏠 `--cache-dir=DIR`

Specify the directory rclone will use for caching, to override the default.

The default value depends on the operating system, bestie:

- Windows — `%LocalAppData%\rclone`, if `LocalAppData` is defined.
- macOS — `$HOME/Library/Caches/rclone` if `HOME` is defined.
- Unix — `$XDG_CACHE_HOME/rclone` if `XDG_CACHE_HOME` is defined, else `$HOME/.cache/rclone` if `HOME` is defined.
- Fallback (on all OS) to `$TMPDIR/rclone`, where `TMPDIR` is the value from `--temp-dir`.

You can use the `config paths` command to see the current value. 🔍

The cache directory is <hotpink>heavily</hotpink> used by the VFS File Caching mount feature, but also by `serve`, GUI and other parts of rclone. she's everywhere tbh 💅

---

### 🕵️ `--check-first`

If this flag is set then in a `sync`, `copy` or `move`, rclone will do <bold>all</bold> the checks to see whether files need to be transferred <italic>before</italic> doing any of the transfers. Normally rclone would start running transfers as soon as possible. so this is the "look before you leap" setting ✨

This flag can be useful on <yellow>IO limited</yellow> systems where transfers interfere with checking.

It can also be useful to ensure <purple>perfect ordering</purple> when using `--order-by`.

If both `--check-first` and `--order-by` are set when doing `rclone move` then rclone will use the transfer thread to delete source files which don't need transferring. This will enable perfect ordering of the transfers and deletes but will cause the transfer stats to have more items in than expected. 😭

> Using this flag can use more memory, as it effectively sets `--max-backlog` to infinite. This means that all the info on the objects to transfer is held in memory before the transfers start. 💀

---

### 🔎 `--checkers=N`

Originally controlling just the number of file checkers to run in parallel, e.g. by `rclone copy`. Now a fairly <purple>universal</purple> parallelism control used by rclone in several places. glow-up fr fr

Note: checkers do the equality checking of files during a sync. For some storage systems (e.g. S3, Swift, Dropbox) this can take a <italic>significant</italic> amount of time so they're run in parallel.

The default is to run <hotpink>8</hotpink> checkers in parallel. However, in case of slow-reacting backends you may need to <bold>lower</bold> (rather than increase) this default by setting `--checkers` to 4 or less threads. This is especially advised if you're experiencing <red>backend server crashes</red> during the file checking phase (e.g. on subsequent or top-up backups where little or no file copying is done and checking takes up most of the time). Increase this setting only with <bold>utmost care</bold>, while monitoring your server health and file checking throughput. no cap, be gentle with her 🫶

---

### 🧾 `-c`, `--checksum`

Normally rclone will look at <italic>modification time</italic> and <italic>size</italic> of files to see if they're equal. If you set this flag then rclone will check the <purple>file hash</purple> and size to determine if files are equal. 🌸

So basically the vibe here is: if the remote can't store modification times and you want a *more* accurate sync than just eyeballing the file size, this flag is your bestie. 💅

This one is <hotpink>lowkey iconic</hotpink> when you're moving stuff between remotes that store the same hash type on the object — like Drive and Swift, for example. Wanna know which remotes support which hash type? Go look at the table in the overview section, it's literally right there. 🫶

Example: `rclone --checksum sync s3:/bucket swift:/bucket` runs <green>much quicker</green> than the same thing without `--checksum`. no cap.

And heads up bestie: when you use this flag, rclone **won't** fix up the mtimes of remote files if they're wrong, even though it normally would. so, y'know. know that going in. 😭

- **`--color WHEN`** — tells rclone when it's allowed to sprinkle colors and other ANSI codes into the output. the options are:

  - `AUTO` (the default) — only allows ANSI codes when the output is a terminal
  - `NEVER` — never ever allows ANSI codes, periodt
  - `ALWAYS` — always adds ANSI codes, no matter what the output is (terminal or file)

- **`--compare-dest=DIR`** — when you're using sync, copy or move, this makes rclone check `DIR` *in addition to* the destination for files. If it finds a file identical to the source, that file is **NOT** copied from source. super handy when you just wanna copy the files that changed since your last backup. ✨

  You **must** use the same remote as the destination of the sync, and the compare directory **must not** overlap the destination directory.

  See `--copy-dest` and `--backup-dir`.

- **`--config=CONFIG_FILE`** — point rclone at your config file, overriding the default location. like `rclone config --config="rclone.conf"`.

  ngl, the exact default is a *whole* thing to describe, because rclone changed it across versions while still keeping backwards compatibility. but most of the time it's simple:

  - `%APPDATA%/rclone/rclone.conf` on Windows
  - `~/.config/rclone/rclone.conf` on other systems

  Okay so the complete logic is this: rclone looks for an **existing** config file in any of these spots, in priority order:

  1. `rclone.conf` (in the program directory, i.e. where the rclone executable lives)
  2. `%APPDATA%/rclone/rclone.conf` (only on Windows)
  3. `$XDG_CONFIG_HOME/rclone/rclone.conf` (on all systems, Windows included)
  4. `~/.config/rclone/rclone.conf` (the `~` symbol is explained below, bestie)
  5. `~/.rclone.conf`

  If no existing config file turns up, then a brand new one gets created here:

  - On Windows: location 2 from above — unless (in the unlikely event) `APPDATA` isn't defined, in which case location 4 is used instead.
  - On Unix: location 3 if `XDG_CONFIG_HOME` is defined, else location 4.
  - Fallback to location 5 (on all OS) when the rclone directory can't be created — but if a home directory wasn't found either, then the path `.rclone.conf` relative to the current working directory is used as the final resort.

  The `~` symbol up there means the home directory of the current user on any OS, and its value is defined like this:

  - On Windows: `%HOME%` if defined, else `%USERPROFILE%`, or else `%HOMEDRIVE%\%HOMEPATH%`.
  - On Unix: `$HOME` if defined, else look up the current user in the OS-specific user database (like a `passwd` file), or else use the result from the shell command `cd && pwd`.

  Run `rclone config file` and you'll literally see where the default location is for *you*. 🔍

  The way that an existing `rclone.conf` sitting in the same directory as the rclone executable is **always** preferred means it's easy to run in "portable" mode: just download the rclone executable into a writable directory and make an empty `rclone.conf` file next to it. slay.

  If you set the location to the empty string `""`, or a path to a file named `notfound`, or the OS null device (value `NUL` on Windows and `/dev/null` on Unix systems), then rclone keeps the config file **in memory only**.

  The file format is basic INI: sections of text, led by a `[section]` header, followed by `key=value` entries on separate lines. In rclone, each remote gets its own section, and the section name defines the name of the remote. Options are the `key=value` entries, where the key is the option name *without* the `--backend-` prefix, in lowercase, with `_` instead of `-`. Like, option `--mega-hard-delete` corresponds to key `hard_delete`. Only backend options can be specified. There's a special — and **required** — key called `type` that identifies the storage system, where the value is the internal lowercase name as returned by the command `rclone help backends`. Comments are marked with `;` or `#` at the beginning of a line.

  Example:

[megaremote] type = mega user = you@example.com pass = PDPcQVVjVtzFY-GTdDFozqBhTdsPg3qH


Note: passwords are in **obscured** form. Also, lots of storage systems use token-based authentication instead of passwords, and that needs extra steps. It is easier, and safer, to use the interactive command `rclone config` instead of hand-editing the config file. fr fr.

The config file will typically contain your login info, so it should have restricted permissions so that only the current user can read it. Rclone tries to make sure of that when it writes the file. You can also choose to encrypt the file. 🔐

When token-based authentication is used, the config file **must be writable**, because rclone needs to update the tokens inside it.

To reduce the risk of corrupting an existing config file, rclone won't write directly to it when saving changes. Instead it first writes to a new, temporary file. If a config file already existed, it'll (on Unix systems) try to mirror its permissions onto the new file. Then it renames the existing file to a temporary name as a backup. Next, rclone renames the new file to the correct name, and finally it cleans up by deleting the backup file. it's giving <lavender>very careful girlboss</lavender>.

If the config file path used by rclone is a symbolic link, then it gets evaluated and rclone writes to the **resolved** path, instead of overwriting the symlink. Temporary files used in that process (described above) get written to the same parent directory as the resolved config file — but if *that* directory is also a symbolic link, it won't be resolved, and the temporary files go to the location of the directory symbolic link.

- **`--contimeout=TIME`** — set the connection timeout. This should be in Go time format, which looks like `5s` for 5 seconds, `10m` for 10 minutes, or `3h30m`. ⏰

The connection timeout is how long rclone waits for a connection to go through to a remote object storage system. It's `1m` by default.

- **`--copy-dest=DIR`** — when using sync, copy or move, `DIR` is checked in addition to the destination for files. If a file identical to the source is found, that file is **server-side copied** from `DIR` to the destination. perfect for incremental backup. 💖

The remote in use **must** support server-side copy, and you must use the same remote as the destination of the sync. The compare directory must not overlap the destination directory.

See `--compare-dest` and `--backup-dir`.

- **`--dedupe-mode MODE`** — the mode to run the dedupe command in. One of `interactive`, `skip`, `first`, `newest`, `oldest`, `rename`. The default is `interactive`.

See the dedupe command for more info on what those options actually mean. 🌀

- **`--default-time TIME`** — if a file or directory doesn't have a modification time rclone can read, then rclone will display this fixed time instead.

The default is `2000-01-01 00:00:00 UTC`. You can configure it in any of the ways shown in the time or duration options.

For example `--default-time 2020-06-01` sets the default time to the 1st of June 2020, or `--default-time 0s` sets the default time to whenever rclone started up.

- **`--disable FEATURE,FEATURE,...`** — disables a comma separated list of optional features. Like, to disable server-side move and server-side copy, use:

--disable move,copy


The features can be in any case, bestie. 💅

To see the list of which features can be disabled, use:

--disable help


And the features a remote has can be seen in JSON format with:

rclone backend features remote:


See the overview features and optional features to get an idea of which feature does what.

Note that some features can be set to `true` if they're true/false feature flag features, by prefixing them with `!`. For example the `CaseInsensitive` feature can be forced to false with `--disable CaseInsensitive` and forced to true with `--disable '!CaseInsensitive'`. In general it isn't a good idea to do this, but it may be useful <italic>in extremis</italic>.

(Also note that `!` is a shell command, which you'll need to escape with single quotes or a backslash on unix-like platforms.)

This flag can be useful for debugging and in exceptional circumstances (e.g. Google Drive limiting the total volume of Server Side Copies to `100 GiB/day`). 💀

- **`--disable-http2`** — stops rclone from trying to use HTTP/2 if it's available. This can sometimes speed up transfers, due to a problem in the Go standard library.

- **`--dscp VALUE`** — specify a DSCP value or name to use in connections. This could help a QoS system identify the traffic class. `BE`, `EF`, `DF`, `LE`, `CSx` and `AFxx` are allowed.

See the description of differentiated services to get an idea of this field. Setting this to `1` (`LE`) to identify the flow to the SCAVENGER class can avoid occupying too much bandwidth in a network with DiffServ support (`RFC 8622`).

For example, if you configured QoS on your router to handle `LE` properly, running:

rclone copy --dscp LE from:/from to:/to


would make the priority lower than usual internet flows.

> This option has **no effect on Windows** (see `golang/go#42728`). 😭

- **`-n`, `--dry-run`** — do a trial run with no permanent changes. Use this to see what rclone *would* do without actually doing it. Super useful when you're setting up the sync command, since that one deletes files in the destination. 🙈

- **`--expect-continue-timeout=TIME`** — specifies how long to wait for a server's first response headers after fully writing the request headers, if the request has an "Expect: 100-continue" header. Not all backends support using this.

Zero means no timeout, and causes the body to be sent immediately, without waiting for the server to approve. This time does **not** include the time to send the request header.

The default is `1s`. Set to `0` to disable.

- **`--error-on-no-transfer`** — by default, rclone exits with return code `0` if there were no errors.

This option lets rclone return exit code `9` if **no files** were transferred between the source and the destination. Which is perfect for using rclone in scripts: trigger follow-on actions if data was copied, or skip stuff if it wasn't. 🎀

> NB: enabling this option turns a usually non-fatal error into a potentially **fatal** one — please check and adjust your scripts accordingly! ⚠️

- **`--fix-case`** — okay bestie, picture this: you're syncing to a <hotpink>case insensitive</hotpink> dest (macOS, Windows, that whole vibe) and your source and dest filenames differ only in casing but are otherwise identical. Normally, that sync will <italic>not</italic> end up with a matching filename. Example: sync `hello.txt` to `HELLO.txt` and normally the dest filename just stays `HELLO.txt`. 🫠 If `--fix-case` is set, then `HELLO.txt` will be <mint>renamed</mint> to `hello.txt` to match the source. iconic behaviour honestly.

NB, and you <bold>need</bold> to read this bit fr fr:

- directory names with incorrect casing will also be fixed 💅
- `--fix-case` will be ignored if `--immutable` is set
- using `--local-case-sensitive` instead is <red>not advisable</red>; it will cause `HELLO.txt` to get <red>deleted</red>! 😭
- the old dest filename must not be excluded by filters. Be <bold>especially careful</bold> with `--files-from`, which does not respect `--ignore-case`! 👀
- on remotes that do not support server-side move, `--fix-case` will require downloading the file and re-uploading it. To avoid this, do not use `--fix-case`. (not me creating extra work for myself 💀)

- **`--fs-cache-expire-duration=TIME`** — so when you drive rclone via the API, rclone <cyan>caches</cyan> the remotes it creates for <green>5 minutes</green> by default, and it keeps them in the <purple>“fs cache”</purple>. What that means for you: if you're doing repeated actions on the same remote, rclone doesn't have to build it all over again from scratch, which makes the whole thing way more efficient. ✨

This flag sets the time that the remotes are cached for. If you set it to `0` (or negative) then rclone won't cache the remotes at all. 🙈

Note that if you use some flags, eg `--backup-dir`, and if this is set to `0`, rclone may build <bold>two</bold> remotes (one for the source or destination and one for the `--backup-dir`) where it may have only built one before.

- **`--fs-cache-expire-interval=TIME`** — this one controls how often rclone checks for cached remotes to expire. See the `--fs-cache-expire-duration` documentation above for more info. The default is `60s`, and you set it to `0` to disable expiry. periodt. 🌸

- **`--header`** — adds an HTTP header for <bold>all</bold> transactions. You can repeat the flag to add multiple headers, slay. 🎀

If you want to add headers only for uploads, use `--header-upload`, and if you want to add headers only for downloads, use `--header-download`.

This flag is supported for all HTTP based backends, even those not supported by `--header-upload` and `--header-download`, so it may be used as a workaround for those — with care. 🫶

rclone ls remote:test --header "X-Rclone: Foo" --header "X-LetMeIn: Yes"


- **`--header-download`** — adds an HTTP header for all <bold>download</bold> transactions. Repeatable, so you can stack as many as you want. 💖

rclone sync --interactive s3:test/src ~/dst --header-download "X-Amz-Meta-Test: Foo" --header-download "X-Amz-Meta-Test2: Bar"


See the GitHub issue here for currently supported backends.

- **`--header-upload`** — adds an HTTP header for all <bold>upload</bold> transactions. Also repeatable, go off. 👑

rclone sync --interactive ~/src s3:test/dst --header-upload "Content-Disposition: attachment; filename='cool.html'" --header-upload "X-Amz-Meta-Test: FooBar"


See the GitHub issue here for currently supported backends.

- **`--human-readable`** — this is the one that decides whether rclone spits out values as raw numbers or in the cute <rainbow>human-readable</rainbow> format. Rclone commands output values for sizes (e.g. number of bytes) and counts (e.g. number of files) either as raw numbers, or in human-readable format. 💫

In human-readable format the values are <bold>scaled to larger units</bold>, indicated with a suffix shown after the value, and rounded to <cyan>three decimals</cyan>. Rclone consistently uses <bold>binary units</bold> (powers of 2) for sizes and <bold>decimal units</bold> (powers of 10) for counts. The unit prefix for size follows IEC standard notation, e.g. `Ki` for kibi. Used with the byte unit, `1 KiB` means `1024 Byte`. In list type of output, only the unit prefix gets appended to the value (e.g. `9.762Ki`), while in more textual output the full unit is shown (e.g. `9.762 KiB`). For counts the SI standard notation is used, e.g. prefix `k` for kilo. Used with file counts, `1k` means `1000 files`. 🧮

The various list commands output raw numbers by default. Option `--human-readable` will make them output values in human-readable format instead (with the short unit prefix).

The `about` command outputs human-readable by default, with a command-specific option `--full` to output the raw numbers instead.

Command `size` outputs <bold>both</bold> human-readable and raw numbers in the same output. 😌

The `tree` command also considers `--human-readable`, but it will <italic>not</italic> use the exact same notation as the other commands: it rounds to <bold>one decimal</bold>, and uses a single letter suffix, e.g. `K` instead of `Ki`. The reason for this is that it relies on an external library. 🤷‍♀️

The interactive command `ncdu` shows human-readable by default, and responds to key <kbd>u</kbd> for toggling human-readable format.

- **`--ignore-case-sync`** — using this option will cause rclone to ignore the case of the files when synchronizing, so files will not be copied/synced when the existing filenames are the same, even if the casing is different. lowkey chill of it. 🦋

- **`--ignore-checksum`** — normally rclone will check that the checksums of transferred files match, and give an error <red>“corrupted on transfer”</red> if they don't.

You can use this option to skip that check. You should <bold>only</bold> use it if you have had the `“corrupted on transfer”` error message and you are sure you might want to transfer potentially corrupted data. ⚠️

> girl. please read that twice. you're telling rclone to hand you possibly corrupted data on purpose. that's a choice!! 😭

- **`--ignore-existing`** — using this option will make rclone unconditionally skip <bold>all</bold> files that exist on the destination, no matter the content of these files. 🙈

While this isn't a generally recommended option, it can be useful in cases where your files change due to encryption. However, it <bold>cannot</bold> correct partial transfers in case a transfer was interrupted. 💀

When performing a `move`/`moveto` command, this flag will leave skipped files in the source location unchanged when a file with the same name exists on the destination.

- **`--ignore-size`** — normally rclone will look at modification time <italic>and</italic> size of files to see if they are equal. If you set this flag then rclone will check <bold>only the modification time</bold>. If `--checksum` is set then it only checks the checksum.

It will also cause rclone to skip verifying the sizes are the same after transfer.

This can be useful for transferring files to and from OneDrive, which occasionally misreports the size of image files (see `#399` for more info). 🍓

- **`-I`, `--ignore-times`** — using this option will cause rclone to unconditionally upload <bold>all</bold> files regardless of the state of files on the destination. full send. 🔥

Normally rclone would skip any files that have the same modification time and are the same size (or have the same checksum if using `--checksum`).

- **`--immutable`** — treats source and destination files as <bold>immutable</bold> and disallows modification. 🧊

With this option set, files will be created and deleted as requested, but existing files will <bold>never</bold> be updated. If an existing file does not match between the source and destination, rclone will give the error `Source and destination exist but do not match: immutable file modified`.

Note that only commands which transfer files (e.g. `sync`, `copy`, `move`) are affected by this behavior, and only <italic>modification</italic> is disallowed. Files may still be deleted explicitly (e.g. `delete`, `purge`) or implicitly (e.g. `sync`, `move`). Use `copy --immutable` if it is desired to avoid deletion as well as modification. 💅

This can be useful as an additional layer of protection for immutable or append-only data sets (notably backup archives), where modification implies corruption and should not be propagated. 🛡️

- **`--inplace`** — the `--inplace` flag changes the behaviour of rclone when uploading files to some backends (backends with the `PartialUploads` feature flag set), such as:

- `local`
- `ftp`
- `sftp`
- `pcloud`

Without `--inplace` (the default), rclone will first upload to a <italic>temporary file</italic> with an extension like this, where `XXXXXX` represents a hash of the source file's fingerprint and `.partial` is the `--partial-suffix` value (`.partial` by default).

original-file-name.XXXXXX.partial


(rclone will make sure the final name is no longer than <cyan>100 characters</cyan> by truncating the `original-file-name` part if necessary).

When the upload is complete, rclone will rename the `.partial` file to the correct name, overwriting any existing file at that point. If the upload fails then the `.partial` file will be deleted. 🧹

This prevents other users of the backend from seeing partially uploaded files in their new names and prevents overwriting the old file until the new one is completely uploaded. queen behaviour honestly. 👑

If the `--inplace` flag is supplied, rclone will upload <bold>directly to the final name</bold> without creating a `.partial` file.

This means that an incomplete file will be visible in the directory listings while the upload is in progress, and any existing files will be overwritten as soon as the upload starts. If the transfer fails then the file will be deleted. <red>This can cause data loss of the existing file if the transfer fails.</red> 😭

Note that on the local file system, if you don't use `--inplace`, hard links (Unix only) will be broken. And if you <italic>do</italic> use `--inplace`, you won't be able to update in-use executables.

Note also that versions of rclone prior to `v1.63.0` behave as if the `--inplace` flag is always supplied.

- **`-i`, `--interactive`** — this flag can be used to tell rclone that you wish a <bold>manual confirmation</bold> before destructive operations. 🙋‍♀️

It is <bold>recommended</bold> that you use this flag while learning rclone, especially with `rclone sync`. fr fr, use it.

For example:

$ rclone delete --interactive /tmp/dir rclone: delete "important-file.txt"? y) Yes, this is OK (default) n) No, skip this s) Skip all delete operations with no more questions !) Do all delete operations with no more questions q) Exit rclone now. y/n/s/!/q> n


The options mean:

- `y`: Yes, this operation should go ahead. You can also press <kbd>Return</kbd> for this to happen. You'll be asked every time unless you choose `s` or `!`.
- `n`: No, do not do this operation. You'll be asked every time unless you choose `s` or `!`.
- `s`: Skip all the following operations of this type with no more questions. This takes effect until rclone exits. If there are any different kind of operations you'll be prompted for them.
- `!`: Do all the following operations with no more questions. Useful if you've decided that you don't mind rclone doing that kind of operation. This takes effect until rclone exits. If there are any different kind of operations you'll be prompted for them.
- `q`: Quit rclone right now, just in case! 🏃‍♀️💨

- **`--leave-root`** — during `rmdirs` it will not remove the root directory, even if it's empty. 🌱

- **`--links`, `-l`** — normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows). 🙈

If you supply this flag then rclone will copy symbolic links from any supported backend backend, and store them as <bold>text files</bold>, with a `.rclonelink` suffix in the destination. 🎀

The text file will contain the target of the symbolic link.

...and that's the whole vibe of `--links` / `-l` right there — it turns this feature on for **every** backend that supports it, plus the VFS. ✨ But bestie, if you only want it in *one* place, there are solo flags: `--vfs-links` for just the VFS and `--local-links` for just the local backend. Pick your fighter. 💅

---

- **`--log-file=FILE`** — Writes *all* of rclone's output into `FILE`. Off by default, no cap. Super handy when you're sleuthing a sync problem and you've got `-v` going too — more on that in the Logging section. 📝

Heads up: if `FILE` already exists, rclone **appends** to it (never yeets your old logs, she's polite).

> If you're managing rclone's logs with the `logrotate` program, you gotta use the `copytruncate` option — because rclone has **no signal** to rotate logs. That's just the way it is. 😭

- **`--log-format LIST`** — A comma separated list of log format options. The accepted ones are `date`, `time`, `microseconds`, `pid`, `longfile`, `shortfile`, `UTC`. Any other keywords you sneak in there get **silently ignored** — no error, no nothing. 🙈 The `pid` option tags your log messages with the process identifier, which is genuinely useful with `rclone mount --daemon`. The other accepted options are explained in the go documentation. Default log format is `"date,time"`.

- **`--log-level LEVEL`** — Sets the log level for rclone. Default is `NOTICE`.

- `DEBUG` = same as `-vv`. Outputs a *lot* of debug info — chef's kiss for bug reports and for actually finding out what rclone is doing. 🔍
- `INFO` = same as `-v`. Outputs info about each transfer, and prints stats once a minute by default.
- `NOTICE` = the default when you supply no logging flags at all. Says very little when everything's working fine; spits out warnings and significant events.
- `ERROR` = same as `-q`. Only outputs error messages.

- **`--use-json-log`** — Switches the log format to JSON. The fields of the json log are `level`, `msg`, `source`, `time`. 💻

- **`--low-level-retries NUMBER`** — Controls how many low level retries rclone does.

A low level retry retries a *failing operation* — usually one HTTP request, like uploading a chunk of a big file. You'll see low level retries in the log when you use the `-v` flag.

Ngl, in normal operation you shouldn't need to touch this. But if you're drowning in low level retries, you might wanna *lower* the value so rclone moves on to a high level retry (see the `--retries` flag) faster. 🏃‍♀️

Disable low level retries entirely with `--low-level-retries 1`.

- **`--max-backlog=N`** — The maximum allowable backlog of files in a sync/copy/move that are queued up waiting to be checked or transferred.

You can set this arbitrarily large and it's fine — it only eats memory when the queue is actually in use. Note that it'll use in the order of N KiB of memory while the backlog is in use.

Set it big and rclone can calculate how many files are pending more accurately, give you a more accurate estimated finish time, and make `--order-by` work more accurately. ✨

Set it small and rclone becomes more synchronous with the listings of the remote — which may be exactly what you want.

Set it to a **negative number** and the backlog becomes as large as possible. 🤯

- **`--max-delete=N`** — Tells rclone not to delete more than `N` files. If that limit gets exceeded, a **fatal error** is generated and rclone stops the operation in progress. 🛑

- **`--max-delete-size=SIZE`** — Rclone will stop deleting files once the *total size* of deletions hits the size you specified. Defaults to off.

If that limit gets exceeded, a fatal error is generated and rclone stops the operation in progress.

- **`--max-depth=N`** — Modifies the recursion depth for all the commands **except `purge`**.

So `rclone --max-depth 1 ls remote:path` shows you only the files in the top level directory. `--max-depth 2` means everything in the first two directory levels, and so on. 🌳

For historical reasons, the `lsd` command defaults to using a `--max-depth` of `1` — you can override that with the command line flag.

You can use this to *disable* recursion entirely (with `--max-depth 1`).

> Lowkey important: if you use this with `sync` and `--delete-excluded`, the files that aren't recursed through get treated as **excluded** and will be **deleted** on the destination. Test first with `--dry-run` if you're not 100% sure what'll happen. 💀

- **`--max-duration=TIME`** — Rclone stops transferring once it's been running for the duration you specified. Defaults to off.

When the limit hits, all transfers stop **immediately**. Use `--cutoff-mode` to change up that behaviour.

Rclone exits with exit code `10` if the duration limit is reached.

- **`--max-transfer=SIZE`** — Rclone stops transferring once it's reached the size specified. Defaults to off.

When the limit hits, all transfers stop **immediately**. Use `--cutoff-mode` to change up that behaviour.

Rclone exits with exit code `8` if the transfer limit is reached.

- **`--cutoff-mode=hard|soft|cautious`** — Modifies the behavior of `--max-transfer` and `--max-duration`. Defaults to `--cutoff-mode=hard`.

- `--cutoff-mode=hard` stops transferring **immediately** when rclone reaches the limit.
- `--cutoff-mode=soft` stops *starting new* transfers when rclone reaches the limit (the ones already going get to finish 🫶).
- `--cutoff-mode=cautious` tries to *prevent* rclone from reaching the limit at all. Only applicable for `--max-transfer`.

- **`-M`, `--metadata`** — Setting this flag lets rclone copy the metadata from the source to the destination. For local backends that's ownership, permissions, xattr etc. See the metadata section for more info. 🏷️

- **`--metadata-mapper SpaceSepList`** — If you supply the parameter `--metadata-mapper /path/to/program` then rclone uses that program to map metadata from the source object to the destination object.

The argument to this flag should be a command with an optional space separated list of arguments. If one of the arguments has a space in it, enclose it in `"` — and if you want a literal `"` inside an argument, enclose the argument in `"` and double the `"`. See CSV encoding for more info.

--metadata-mapper "python bin/test_metadata_mapper.py" --metadata-mapper 'python bin/test_metadata_mapper.py "argument with a space"' --metadata-mapper 'python bin/test_metadata_mapper.py "argument with ""two"" quotes"'


This uses a simple JSON based protocol with input on STDIN and output on STDOUT. It gets called for every file and directory copied, and **may be called concurrently**. 👀

The program's job is to take a metadata blob on the input and turn it into a metadata blob on the output that's suitable for the destination backend.

Input to the program (via STDIN) might look like this. This provides some context for the Metadata which may be important.

- `SrcFs` is the config string for the remote that the object is currently on.
- `SrcFsType` is the name of the source backend.
- `DstFs` is the config string for the remote that the object is being copied to.
- `DstFsType` is the name of the destination backend.
- `Remote` is the path of the object relative to the root.
- `Size`, `MimeType`, `ModTime` are attributes of the object.
- `IsDir` is true if this is a directory (not yet implemented).
- `ID` is the source ID of the object if known.
- `Metadata` is the backend specific metadata as described in the backend docs.

{ "SrcFs": "gdrive:", "SrcFsType": "drive", "DstFs": "newdrive:user", "DstFsType": "onedrive", "Remote": "test.txt", "Size": 6, "MimeType": "text/plain; charset=utf-8", "ModTime": "2022-10-11T17:53:10.286745272+01:00", "IsDir": false, "ID": "xyz", "Metadata": { "btime": "2022-10-11T16:53:11Z", "content-type": "text/plain; charset=utf-8", "mtime": "2022-10-11T17:53:10.286745272+01:00", "owner": "user1@domain1.com", "permissions": "...", "description": "my nice file", "starred": "false" } }


The program should then modify the input as desired and send it to STDOUT. The returned `Metadata` field will be used **in its entirety** for the destination object. Any other fields will be ignored. Note in this example we translate user names and permissions and add something to the description:

{ "Metadata": { "btime": "2022-10-11T16:53:11Z", "content-type": "text/plain; charset=utf-8", "mtime": "2022-10-11T17:53:10.286745272+01:00", "owner": "user1@domain2.com", "permissions": "...", "description": "my nice file [migrated from domain1]", "starred": "false" } }


Metadata can be removed here too. 🗑️

An example python program might look something like this to implement the above transformations.

import sys, json

i = json.load(sys.stdin) metadata = i["Metadata"]

Add tag to description

if "description" in metadata: metadata["description"] += " [migrated from domain1]" else: metadata["description"] = "[migrated from domain1]"

Modify owner

if "owner" in metadata: metadata["owner"] = metadata["owner"].replace("domain1.com", "domain2.com") o = { "Metadata": metadata } json.dump(o, sys.stdout, indent="\t")


You can find this example (slightly expanded) in the rclone source code at `bin/test_metadata_mapper.py`.

If you want to see the input to the metadata mapper and the output returned from it in the log you can use `-vv --dump mapper`. 🔍

See the metadata section for more info.

- **`--metadata-set key=value`** — Add metadata `key` = `value` when uploading. This can be repeated as many times as required. See the metadata section for more info. 🎀

- **`--modify-window=TIME`** — When checking whether a file has been modified, this is the maximum allowed time difference a file can have and still be considered equivalent.

The default is `1ns` unless this is overridden by a remote. For example, OS X only stores modification times to the nearest second, so if you're reading and writing to an OS X filing system this'll be `1s` by default. 🍎

This command line flag lets you override that computed default.

- **`--multi-thread-write-buffer-size=SIZE`** — When transferring with multiple threads, rclone buffers `SIZE` bytes in memory before writing to disk, for each thread. ✍️

This can improve performance if the underlying filesystem doesn't deal well with a lot of small writes in different positions of the file — so if you see transfers getting limited by disk write speed, you might wanna experiment with different values. Especially for magnetic drives and remote file systems, a higher value can be useful. 💾

Nevertheless, the default of `128k` should be totally fine for like, almost every use case ever, so before you go changing it, make sure the network isn't actually your bottleneck, bestie. 🫶

And as a final hint: size is not the only factor. Block size (or whatever similar concept your storage has) can have an impact too. In one case, they observed that *exact* multiples of `16k` performed <pink>much</pink> better than other values. 💅

### **`--multi-thread-chunk-size=SizeSuffix`**

Normally the chunk size for multi thread transfers is set by the backend. But some backends — like `local` and `smb`, which implement `OpenWriterAt` but not `OpenChunkWriter` — don't have a natural chunk size. 😭

In this case the value of this option is used (default `64Mi`).

### **`--multi-thread-cutoff=SIZE`**

When you're transferring files above *SIZE* to capable backends, rclone will use multiple threads to transfer the file (default `256M`). 🔥

Capable backends are marked in the overview as <purple>MultithreadUpload</purple>. (They need to implement either the `OpenWriterAt` or `OpenChunkWriter` internal interfaces). At the time of writing these include `include`, `local`, `s3`, `azureblob`, `b2`, `oracleobjectstorage` and `smb`.

On the local disk, rclone preallocates the file (using `fallocate(FALLOC_FL_KEEP_SIZE)` on unix or `NTSetInformationFile` on Windows, both of which take no time) then each thread writes directly into the file at the correct place. This means rclone won't create fragmented or sparse files, and there won't be any assembly time at the end of the transfer. iconic behavior honestly ✨

The number of threads used to transfer is controlled by `--multi-thread-streams`.

Use `-vv` if you wish to see info about the threads. 👀

This will work with the `sync`/`copy`/`move` commands and friends `copyto`/`moveto`. Multi thread transfers will be used with `rclone mount` and `rclone serve` if `--vfs-cache-mode` is set to `writes` or above.

> NB that this only works with supported backends as the destination but will work with <green>any</green> backend as the source.

> NB that multi-thread copies are disabled for local to local copies as they are faster without — unless `--multi-thread-streams` is set explicitly.

> NB on Windows using multi-thread transfers to the local disk will cause the resulting files to be sparse. Use `--local-no-sparse` to disable sparse files (which may cause long delays at the start of transfers) or disable multi-thread transfers with `--multi-thread-streams 0` 💀

### **`--multi-thread-streams=N`**

When using multi thread transfers (see above, `--multi-thread-cutoff`) this sets the number of streams to use. Set to `0` to disable multi thread transfers (Default `4`).

If the backend has a `--backend-upload-concurrency` setting (eg `--s3-upload-concurrency`) then this setting will be used as the number of transfers instead if it is larger than the value of `--multi-thread-streams` or `--multi-thread-streams` isn't set. iykyk

### **`--no-check-dest`**

The `--no-check-dest` can be used with `move` or `copy` and it causes rclone <hotpink>not</hotpink> to check the destination at all when copying files.

This means that:

- the destination is not listed, minimising the API calls
- files are <rainbow>always</rainbow> transferred
- this can cause duplicates on remotes which allow it (e.g. Google Drive)
- `--retries 1` is recommended otherwise you'll transfer everything again on a retry 😭

This flag is useful to minimise the transactions if you know that none of the files are on the destination.

> This is a specialized flag which should be ignored by most users! Not your moment bestie, walk away 🚶‍♀️

### **`--no-gzip-encoding`**

Don't set `Accept-Encoding: gzip`. This means that rclone won't ask the server for compressed files automatically. Useful if you've set the server to return files with `Content-Encoding: gzip` but you uploaded compressed files.

There is no need to set this in normal operation, and doing so will decrease the network transfer efficiency of rclone. 🙈

### **`--no-traverse`**

The `--no-traverse` flag controls whether the destination file system is traversed when using the `copy` or `move` commands. `--no-traverse` is not compatible with `sync` and will be ignored if you supply it with `sync`.

If you are only copying a small number of files (or are filtering most of the files) and/or have a large number of files on the destination then `--no-traverse` will stop rclone listing the destination and save time. ⏱️

However, if you are copying a large number of files — especially if you are doing a copy where lots of the files under consideration haven't changed and won't need copying — then you shouldn't use `--no-traverse`.

See `rclone copy` for an example of how to use it.

### **`--no-unicode-normalization`**

Don't normalize unicode characters in filenames during the sync routine.

Sometimes, an operating system will store filenames containing unicode parts in their decomposed form (particularly macOS 🍎). Some cloud storage systems will then recompose the unicode, resulting in duplicate files if the data is ever copied back to a local filesystem.

Using this flag will disable that functionality, treating each unicode character as unique. For example, by default `é` and `é` will be normalized into the same character. With `--no-unicode-normalization` they will be treated as unique characters. (Yes those are the two different ones, no you can't tell by looking, that's the whole point 😭)

### **`--no-update-modtime`**

When using this flag, rclone won't update modification times of remote files if they are incorrect as it would normally.

This can be used if the remote is being synced with another tool also (e.g. the Google Drive client).

### **`--no-update-dir-modtime`**

When using this flag, rclone won't update modification times of remote directories if they are incorrect as it would normally.

### **`--order-by string`**

The `--order-by` flag controls the order in which files in the backlog are processed in `rclone sync`, `rclone copy` and `rclone move`.

The order by string is constructed like this. The first part describes what aspect is being measured:

- `size` - order by the size of the files
- `name` - order by the full path of the files
- `modtime` - order by the modification date of the files

This can have a modifier appended with a comma:

- `ascending` or `asc` - order so that the smallest (or oldest) is processed first
- `descending` or `desc` - order so that the largest (or newest) is processed first
- `mixed` - order so that the smallest is processed first for some threads and the largest for others

If the modifier is `mixed` then it can have an optional percentage (which defaults to `50`), e.g. `size,mixed,25` which means that 25% of the threads should be taking the smallest items and 75% the largest. The threads which take the smallest first will always take the smallest first and likewise the largest first threads. The `mixed` mode can be useful to minimise the transfer time when you are transferring a mixture of large and small files — the large files are guaranteed upload threads and bandwidth and the small files will be processed continuously. 💖

If no modifier is supplied then the order is `ascending`.

For example

- `--order-by size,desc` - send the largest files first
- `--order-by modtime,ascending` - send the oldest files first
- `--order-by name` - send the files with alphabetically by path first

If the `--order-by` flag is not supplied or it is supplied with an empty string then the default ordering will be used which is as scanned. With `--checkers 1` this is mostly alphabetical, however with the default `--checkers 8` it is somewhat random. 🎲

### Limitations

The `--order-by` flag does not do a separate pass over the data. This means that it may transfer some files out of the order specified if

- there are no files in the backlog or the source has not been fully scanned yet
- there are more than `--max-backlog` files in the backlog

Rclone will do its best to transfer the best file it has so in practice this should not cause a problem. Think of `--order-by` as being more of a best efforts flag rather than a perfect ordering.

If you want perfect ordering then you will need to specify `--check-first` which will find all the files which need transferring first before transferring any.

### **`--partial-suffix`**

When `--inplace` is not used, it causes rclone to use the `--partial-suffix` as suffix for temporary files.

Suffix length limit is 16 characters.

The default is `.partial`.

### **`--password-command SpaceSepList`**

This flag supplies a program which should supply the config password when run. This is an alternative to rclone prompting for the password or setting the `RCLONE_CONFIG_PASS` variable. It is also used when setting the config password for the first time. 🔐

The argument to this should be a command with a space separated list of arguments. If one of the arguments has a space in then enclose it in `"`, if you want a literal `"` in an argument then enclose the argument in `"` and double the `"`. See CSV encoding for more info.

Eg

--password-command "echo hello" --password-command 'echo "hello with space"' --password-command 'echo "hello with ""quotes"" and space"'


Note that when changing the configuration password the environment variable `RCLONE_PASSWORD_CHANGE=1` will be set. This can be used to distinguish initial decryption of the config file from the new password.

See the Configuration Encryption for more info.

See a Windows PowerShell example on the Wiki.

### **`-P`, `--progress`**

This flag makes rclone update the stats in a static block in the terminal providing a realtime overview of the transfer. 👑

Any log messages will scroll above the static block. Log messages will push the static block down to the bottom of the terminal where it will stay.

Normally this is updated every `500mS` but this period can be overridden with the `--stats` flag.

This can be used with the `--stats-one-line` flag for a simpler display.

To change the display length of filenames (for different terminal widths), see the `--stats-file-name-length` option. The default output is formatted for 80 character wide terminals.

> Note: On Windows until this bug is fixed all non-ASCII characters will be replaced with `.` when `--progress` is in use. ⭐

### **`--progress-terminal-title`**

This flag, when used with `-P`/`--progress`, will print the string `ETA: %s` to the terminal title.

### **`-q`, `--quiet`**

This flag will limit rclone's output to error messages only. 🤫

### **`--refresh-times`**

The `--refresh-times` flag can be used to update modification times of existing files when they are out of sync on backends which don't support hashes.

This is useful if you uploaded files with the incorrect timestamps and you now wish to correct them. 🕰️

This flag is only useful for destinations which don't support hashes (e.g. `crypt`).

This can be used any of the sync commands `sync`, `copy` or `move`.

To use this flag you will need to be doing a modification time sync (so not using `--size-only` or `--checksum`). The flag will have no effect when using `--size-only` or `--checksum`.

---

If this flag is on when rclone goes to upload a file, it's gonna peek at what's already sitting on the destination first. 👀 If that file matches the source on size (and checksum, when we have one) but its timestamp is different, rclone <purple>won't re-upload it</purple> — it just updates the timestamp on the destination file instead. If the checksum does <italic>not</italic> match, then yeah, rclone uploads the new file. And if there's no checksum at all (say, on a crypt backend, iykyk) then rclone just updates the timestamp. ✨

Heads up though: some remotes literally can't set the modification time without re-uploading the whole file, so this flag is a lot less useful on those. 🫠

Also, normally when you do a modification time sync, rclone updates modification times <italic>without</italic> `--refresh-times`, as long as the remote supports checksums and they match on the file. But if the checksums are absent, rclone will upload the file rather than setting the timestamp, because that's the safe behaviour. Periodt. 💅

- **`--retries int`** — retry the *entire* sync this many times if it keeps failing (default `3`). Some remotes are just flaky, okay, and a few retries genuinely help scoop up the files that didn't get transferred because of errors. 🌈 If you want no retries at all, disable them with `--retries 1`.

- **`--retries-sleep=TIME`** — sets the interval between each retry that `--retries` asks for. Default is `0`, and `0` means disabled. 😴

- **`--server-side-across-configs`** — lets server-side operations (like copy or move) work <hotpink>across different configurations</hotpink>. Super handy if you wanna do a server-side copy or move between two remotes that use the same backend but are configured differently. 🦋 Why isn't it on by default? Because it's genuinely not easy for rclone to tell whether it'll work between any two given configs. That's the whole tea. 🍵

- **`--size-only`** — normally rclone checks both modification time and size to decide if two files are equal. Turn this on and it only looks at the size. Useful when you're transferring files from Dropbox that got modified by the desktop sync client, which doesn't set checksums or modification times the same way rclone does. 🙃

- **`--stats=TIME`** — the commands that move data around (`sync`, `copy`, `copyto`, `move`, `moveto`) print data transfer stats at regular intervals so you can watch the progress. This sets the interval. Default is `1m`, and `0` disables it. 👑

  If you set the stats interval, then <italic>all</italic> commands can show stats — great when you're running other stuff like `check` or `mount`, for example.

  Stats get logged at `INFO` level by default, which means they <italic>won't</italic> show up at the default log level of `NOTICE`. Use `--stats-log-level NOTICE` or `-v` to make them appear. See the Logging section for more on log levels. 📜

  Oh and on macOS you can send a `SIGINFO` (which is normally <kbd>Ctrl</kbd>+<kbd>T</kbd> in the terminal) to make the stats print immediately. 💅

- **`--stats-file-name-length integer`** — by default the `--stats` output truncates file names and paths longer than `40` characters. This is equivalent to providing `--stats-file-name-length 40`. Use `--stats-file-name-length 0` to turn off all truncation of file names printed by stats. ✂️

- **`--stats-log-level string`** — the log level to show `--stats` output at. Can be `DEBUG`, `INFO`, `NOTICE`, or `ERROR`. Default is `INFO`, which means at the default level of logging (that's `NOTICE`) the stats won't show — if you want them to, use `--stats-log-level NOTICE`. See the Logging section for more on log levels. 📝

- **`--stats-one-line`** — with this, rclone squishes the stats down to a single line showing only the most important ones. ✨

- **`--stats-one-line-date`** — this turns on single-line stats <italic>and</italic> sticks a date string on the front of the display. The default is `2006/01/02 15:04:05 -`. 📅

- **`--stats-one-line-date-format`** — turns on single-line stats and prepends the display with a date string <italic>you</italic> supply. That date string MUST be enclosed in quotes. Follow the golang specs for date formatting syntax, bestie. 🎀

- **`--stats-unit=bits|bytes`** — by default, data transfer rates print in bytes per second. This option lets the data rate print in bits per second instead. Data transfer <italic>volume</italic> still gets reported in bytes though. And the rate is reported as a binary unit, not SI — so `1 Mbit/s` equals `1,048,576 bit/s`, not `1,000,000 bit/s`. The default is `bytes`. 🧮

- **`--suffix=SUFFIX`** — when you're using `sync`, `copy` or `move`, any files that would have been overwritten or deleted get this suffix added to them instead. And if there's already a file with the same path (after the suffix is added), it gets overwritten. 😬

  The remote you're using must support server-side move or copy, and you have to use the same remote as the destination of the sync.

  This is meant for use with files, to add the suffix in the current directory, or together with `--backup-dir`. See `--backup-dir` for more info. 🗂️

  For example

rclone copy --interactive /path/to/local/file remote:current --suffix .bak


will copy `/path/to/local` to `remote:current`, but any files that would have been updated or deleted get `.bak` added. 🌸

If you're using `rclone sync` with `--suffix` and <italic>without</italic> `--backup-dir`, then it's recommended you put a filter rule in excluding the suffix, otherwise the sync will go ahead and delete the backup files. 😭

rclone sync --interactive /path/to/local/file remote:current --suffix .bak --exclude "*.bak"


- **`--suffix-keep-extension`** — when using `--suffix`, setting this makes rclone put the SUFFIX <italic>before</italic> the extension of the files it backs up, rather than after. 🎯

So like, say we had `--suffix -2019-01-01`: without the flag, `file.txt` would be backed up to `file.txt-2019-01-01`, and with the flag it'd be backed up to `file-2019-01-01.txt`. This can help make sure the suffixed files can still be opened. 🫶

If a file has two (or more) extensions and the second (or subsequent) extension is recognised as a valid mime type, then the suffix goes before <italic>that</italic> extension. So `file.tar.gz` would be backed up to `file-2019-01-01.tar.gz` whereas `file.badextension.gz` would be backed up to `file.badextension-2019-01-01.gz`. 💀

- **`--syslog`** — on capable OSes (so, not Windows or Plan9) send all log output to syslog. Handy for running rclone in a script, or `rclone mount`. 💻

- **`--syslog-facility string`** — if you're using `--syslog`, this sets the syslog facility (e.g. `KERN`, `USER`). See `man syslog` for a list of possible facilities. The default facility is `DAEMON`. ⭐

- **`--temp-dir=DIR`** — specify the directory rclone will use for temporary files, to override the default. Make sure the directory exists and has accessible permissions, okay? 🙈

By default the operating system's temp directory is used:

- On Unix systems, `$TMPDIR` if non-empty, else `/tmp`.
- On Windows, the first non-empty value from `%TMP%`, `%TEMP%`, `%USERPROFILE%`, or the Windows directory.

When you override the default with this option, the specified path gets set as the value of environment variable `TMPDIR` on Unix systems, and `TMP` and `TEMP` on Windows. 🌀

You can use the `config paths` command to see the current value.

- **`--tpslimit float`** — limit transactions per second to this number. Default is `0`, which means unlimited transactions per second. 🚦

A "transaction" is roughly an API call; the exact meaning depends on the backend. For HTTP based backends it's an HTTP `PUT`/`GET`/`POST`/etc and its response. For FTP/SFTP it's a round trip transaction over TCP.

So for example, to limit rclone to 10 transactions per second use `--tpslimit 10`, or to 1 transaction every 2 seconds use `--tpslimit 0.5`. 🧠

Use this when rclone's transactions per second are causing problems with your cloud storage provider (like getting you banned or rate limited 😭). It can be <hotpink>very</hotpink> useful for `rclone mount` to control the behaviour of applications using it.

This limit applies to all HTTP based backends and to the FTP and SFTP backends. It does <italic>not</italic> apply to the local backend or the Storj backend. No cap on those, fr fr.

See also `--tpslimit-burst`. 👀

- **`--tpslimit-burst int`** — max burst of transactions for `--tpslimit` (default `1`). ✨

Normally `--tpslimit` does exactly the number of transactions per second you specified. But if you supply `--tps-burst` then rclone can save up some transactions from when it was idle, giving a burst of up to the parameter supplied. 🔥

For example, if you provide `--tpslimit-burst 10`, then if rclone has been idle for more than `10*--tpslimit` it can do 10 transactions very quickly before they get limited again. ⚡

This may be used to boost the performance of `--tpslimit` without changing the long term average number of transactions per second. 💅

- **`--track-renames`** — by default rclone doesn't keep track of renamed files, so if you rename a file locally and then sync it to a remote, rclone will delete the old file on the remote and upload a fresh copy. 🙃

A `rclone sync` with `--track-renames` runs like a normal sync, except it keeps track of objects that exist in the destination but not the source (which would normally be deleted), and objects that exist in the source but not the destination (which would normally be transferred). Those objects are then candidates for renaming. 👑

After the sync, rclone matches up the source-only and destination-only objects using the `--track-renames-strategy` you specified, and either renames the destination object or transfers the source and deletes the destination object. `--track-renames` is stateless, like all of rclone's syncs. 🦋

To use this flag the destination must support server-side copy or server-side move, and to use a hash based `--track-renames-strategy` (the default) the source <italic>and</italic> the destination must have a compatible hash. 🔐

If the destination doesn't support server-side copy or move, rclone falls back to the default behaviour and logs an error level message to the console.

Encrypted destinations are not currently supported by `--track-renames` if `--track-renames-strategy` includes `hash`. 🚫

Note that `--track-renames` is incompatible with `--no-traverse`, and that it uses extra memory to keep track of all the rename candidates. 🧠

Also note that `--track-renames` is incompatible with `--delete-before` and will select `--delete-after` instead of `--delete-during`. 😌

- **`--track-renames-strategy (hash,modtime,leaf,size)`** — this option changes the file matching criteria for `--track-renames`. 🎀

The matching is controlled by a comma separated selection of these tokens:

- `modtime` — the modification time of the file — not supported on all backends
- `hash` — the hash of the file contents — not supported on all backends
- `leaf` — the name of the file not including its directory name
- `size` — the size of the file (this is always enabled)

The default option is `hash`. ⭐

Using `--track-renames-strategy modtime,leaf` would match files based on modification time, the leaf of the file name and the size only. 💖

Okay so real talk — `--track-renames-strategy modtime` or `leaf`? Those are the ones that unlock `--track-renames` support for <pink>encrypted destinations</pink>. Slay. ✨

> But bestie, heads up: the `hash` strategy is **not** supported with encrypted destinations. Not a thing. Don't come for me, that's just how it is. 💀

---

### <hotpink>`--delete-before`, `--delete-during`, `--delete-after`</hotpink> 🗑️✨

This trio is how you pick *when* files on your destination get yeeted during a sync.

- **`--delete-before`** — nukes every file that's on the destination but not on the source, all *before* any new or updated files start transferring. This one does <purple>two whole passes</purple> through the file systems: one for the deletions, one for the copies. Two full laps, no shortcuts.
- **`--delete-during`** — deletes stuff as it goes, while it's checking and uploading files. This is the **fastest** option and it uses the **least memory**. Main character efficiency fr. 🔥
- **`--delete-after`** — (this is the **default** btw 👑) chills on the deletions until all the new/updated files have made it over successfully. The files-to-delete get collected during the copy pass, then deleted once that copy pass completes clean. Here's the catch though: those pending files are <yellow>held in memory</yellow>, so this mode might use more memory. But it's also the **safest** mode, because it only deletes if there have been *no* errors after that point. If errors happened before the deletions kicked off, you'll get the message `not deleting files as there were IO errors`. Safety first, always. 🫶

---

### <hotpink>`--fast-list`</hotpink> 📋💅

Anytime rclone does something that involves a directory listing — `sync`, `copy`, `ls`, honestly nearly every command — it's got different strategies to pick from. Vibe check on the two of them:

The **basic** strategy lists one directory and processes it before grabbing more directory lists to handle subdirectories. This is a *mandatory* backend feature called `List`, which means every single backend supports it. It uses a small amount of memory, and because it can be parallelised it's fast for operations that involve processing the list results. 🏃‍♀️

Some backends also support an **alternative** strategy where all the files beneath a directory can be listed in one (or a small number) of transactions. Rclone taps into this through an optional backend feature called `ListR`. You can peep the storage system overview documentation's optional features section to see which backends have it turned on — these tend to be the bucket-based girlies, like `S3`, `B2`, `GCS`, `Swift`. 💅 This strategy needs fewer transactions for highly recursive operations, which matters a lot on backends where that's charged or heavily rate limited. It might be <green>faster</green> (fewer transactions, periodt) or <red>slower</red> (because it can't be parallelized) depending on different parameters — and it may need more memory if rclone has to keep the entire listing in memory.

Which listing strategy rclone picks for a given operation is… complicated ngl, but in general it tries to choose the best possible one. It'll prefer `ListR` when it doesn't need to store the listed files in memory — like for unlimited recursive `ls` command variants. In other situations it'll prefer `List`, like for `sync` and `copy`, where it needs to keep the listed files in memory and is running operations on them where parallelization can be a *huge* advantage.

Rclone can't take all the relevant parameters into account when deciding the best strategy, so it lets you influence the choice two ways:

- You can stop rclone from using `ListR` by disabling the feature with the `--disable` option: `--disable ListR`
- Or you can let rclone use `ListR` even where it'd normally say no thanks because of higher memory usage, with `--fast-list`

Rclone should **always** produce identical results either way, no cap. And using `--disable ListR` or `--fast-list` on a remote that doesn't even support `ListR` does nothing — rclone just ignores it. 🤷‍♀️

A rule of thumb, bestie: if you're paying for transactions and can fit your entire sync listing into memory, then `--fast-list` is recommended. But if you've got a *very* big sync to do, then **don't** use `--fast-list`, or you will run out of memory. 😭 Run some tests and compare before you decide, and if you're in doubt, just leave the default — let rclone decide, i.e. don't use `--fast-list`.

---

### <hotpink>`--timeout=TIME`</hotpink> ⏳

Sets the IO idle timeout. If a transfer has started but then sits there idle for this long, it's considered <red>broken and disconnected</red>. 💀

The default is `5m`. Set it to `0` to disable.

---

### <hotpink>`--transfers=N`</hotpink> 🚀

How many file transfers run in parallel. Sometimes it's useful to set this smaller if the remote is throwing a lot of timeouts, or bigger if you've got lots of bandwidth and a fast remote.

The default is to run **4** file transfers in parallel.

Peep `--multi-thread-streams` if you want to control single file transfers. ✨

---

### <hotpink>`-u`, `--update`</hotpink> 🆕

This forces rclone to skip any files that exist on the destination and have a modified time that's **newer** than the source file.

Super useful for avoiding needless transfers when you're going to a remote that doesn't support modification times directly (or when you're using `--use-server-modtime` to dodge extra API calls) — because it's more accurate than a `--size-only` check and faster than using `--checksum`. On those remotes (or when you're using `--use-server-modtime`), the time it checks will be the <purple>uploaded time</purple>.

Here's the tea on how it decides:

- If an existing destination file has a modification time **older** than the source file's, it'll be updated if the sizes are different. If the sizes are the *same*, it'll be updated if the checksum is different or not available.
- If an existing destination file has a modification time **equal** (within the computed modify window) to the source file's, it'll be updated if the sizes are different. The checksum is **not** checked in this case unless you pass the `--checksum` flag.
- In all other cases the file will not be updated.

Consider using the `--modify-window` flag to compensate for time skews between the source and the backend, for backends that don't support mod times and instead use uploaded times. ⚠️ But if the backend doesn't support checksums, note that syncing or copying within the time skew window may still result in additional transfers, for safety.

---

### <hotpink>`--use-mmap`</hotpink> 🧠

If this flag is set, rclone will use anonymous memory allocated by `mmap` on Unix-based platforms and `VirtualAlloc` on Windows for its transfer buffers (size controlled by `--buffer-size`). Memory allocated like this does **not** go on the Go heap, and it can be returned to the OS immediately once it's done with. 💅

If this flag is *not* set, rclone allocates and frees the buffers using the Go memory allocator, which may use more memory as memory pages get returned less aggressively to the OS.

It's possible this doesn't work well on all platforms, so it's <yellow>disabled by default</yellow> — and in the future it may be enabled by default. 👀

---

### <hotpink>`--use-server-modtime`</hotpink> 🕐

Some object-store backends (e.g., `Swift`, `S3`) don't preserve file modification times (modtime). On those backends, rclone stores the original modtime as additional metadata on the object. By default it makes an API call to retrieve that metadata whenever the modtime is needed by an operation.

Use this flag to **disable** that extra API call and rely on the server's modified time instead. In cases like a local-to-remote sync using `--update`, knowing the local file is newer than the time it was last uploaded to the remote is enough. In those cases this flag can speed things up and cut down the number of API calls you need. 🔥

> ⚠️ Using this flag on a sync operation **without** also using `--update` would cause all files modified at any time other than the last upload time to be uploaded again — which is probably not what you want, bestie. Don't do that to yourself. 😭

---

### <hotpink>`-v`, `-vv`, `--verbose`</hotpink> 🗣️

With `-v`, rclone will tell you about each file that's transferred and a small number of significant events.

With `-vv`, rclone becomes *very* verbose — telling you about every single file it considers and transfers. Please send bug reports with a log set to this. 🙏

When setting verbosity as an environment variable, use `RCLONE_VERBOSE=1` or `RCLONE_VERBOSE=2` for `-v` and `-vv` respectively.

---

### <hotpink>`-V`, `--version`</hotpink> 🏷️

Prints the version number. That's it, that's the whole job. ✨

---

## <rainbow>SSL/TLS options</rainbow> 🔐🦋

The outgoing SSL/TLS connections rclone makes can be controlled with these options. For example this can be *very* useful with the HTTP or WebDAV backends. Rclone HTTP servers have their own separate set of configuration for SSL/TLS, which you can find in their documentation. 💖

### <hotpink>`--ca-cert stringArray`</hotpink>

Loads the PEM-encoded certificate authority certificates and uses them to verify the certificates of the servers rclone connects to.

If you've generated certificates signed with a local CA, then you'll need this flag to connect to servers using those certificates. 🎀

### <hotpink>`--client-cert string`</hotpink>

Loads the PEM-encoded client-side certificate.

This is used for mutual TLS authentication.

The `--client-key` flag is required too when using this. 👯‍♀️

### <hotpink>`--client-key string`</hotpink>

Loads the PEM-encoded client-side private key used for mutual TLS authentication. Used in conjunction with `--client-cert`.

### <hotpink>`--no-check-certificate=true/false`</hotpink>

`--no-check-certificate` controls whether a client verifies the server's certificate chain and host name. If `--no-check-certificate` is true, TLS accepts **any** certificate presented by the server and **any** host name in that certificate.

> ⚠️ In this mode, TLS is susceptible to **man-in-the-middle attacks**. This is serious, bestie.

This option defaults to `false`.

This should be used **only for testing**. Periodt. 🚨

---

## <rainbow>Configuration Encryption</rainbow> 🔒💜

Your configuration file contains information for logging in to your cloud services. This means you should keep your `rclone.conf` file in a secure location. 🏠

If you're in an environment where that isn't possible, you can add a password to your configuration. This means you'll have to supply the password every time you start rclone.

To add a password to your rclone configuration, execute `rclone config`.

rclone config

Current remotes:

e) Edit existing remote n) New remote d) Delete remote s) Set configuration password q) Quit config e/n/d/s/q>


Go into `s`, Set configuration password:

e/n/d/s/q> s Your configuration is not encrypted. If you add a password, you will protect your login information to cloud services. a) Add Password q) Quit to main menu a/q> a Enter NEW configuration password: password: Confirm NEW password: password: Password set Your configuration is encrypted. c) Change Password u) Unencrypt configuration q) Quit to main menu c/u/q>


okay so <rainbow>your config is encrypted now</rainbow> 💖 and every single time you start rclone, bestie, you're gonna have to supply the password. No skipping, no shortcuts — see below for the deets. 👀 And from that same menu you can change the password or completely remove encryption from your configuration, whichever vibe you're feeling.

> real talk, and I need you to hear me: there is **no way to recover the configuration if you lose your password.** None. Zero. That config is *gone* gone. 💀

You can also just do it from the command line:

- `rclone config encryption set` to set the config encryption directly ✨
- `rclone config encryption remove` to remove it 🗑️
- `rclone config encryption check` to check that it is encrypted properly ✅

rclone uses `nacl secretbox`, which in turn uses `XSalsa20` and `Poly1305` to encrypt and authenticate your configuration with secret-key cryptography. 🔐 Your password gets SHA-256 hashed, and that hash produces the key for secretbox. And nope — the hashed password is **not** stored anywhere.

While this provides very good security, we do not recommend storing your encrypted rclone configuration in public if it contains sensitive information — maybe except if you use a very strong password. 🤷

If it's safe in your environment, you can set the `RCLONE_CONFIG_PASS` environment variable to contain your password, and in that case it'll be used for decrypting the configuration. 🎀

You can set this for a session from a script. For unix like systems, save this to a file called `set-rclone-password`:

#!/bin/echo Source this file don't run it

read -s RCLONE_CONFIG_PASS export RCLONE_CONFIG_PASS


Then source the file when you want to use it. From the shell you'd do `source set-rclone-password`. It will then ask you for the password and set it in the environment variable. 🫶

An alternate means of supplying the password is to provide a script which will retrieve the password and print it on standard output. This script should have a fully specified path name and not rely on any environment variables — no vibes-based relative paths, bestie. The script is supplied either via `--password-command="..."` command line argument or via the `RCLONE_PASSWORD_COMMAND` environment variable.

One useful example of this is using the passwordstore application to retrieve the password:

export RCLONE_PASSWORD_COMMAND="pass rclone/config"


If the passwordstore password manager holds the password for the rclone configuration, using the script method means the password is primarily protected by the passwordstore system, and it's never embedded in the clear in scripts, nor available for examination using the standard commands available. 👑 And honestly it's quite possible with long running rclone sessions for copies of passwords to be innocently captured in log files or terminal scroll buffers, etc. Using the script method of supplying the password enhances the security of the config password considerably.

If you are running rclone inside a script, unless you're using the `--password-command` method, you might want to disable password prompts. To do that, pass the parameter `--ask-password=false` to rclone. This will make rclone fail instead of asking for a password if `RCLONE_CONFIG_PASS` doesn't contain a valid password, and `--password-command` has not been supplied. 🚫

Whenever running commands that may be affected by options in a configuration file, rclone will look for an existing file according to the rules described above, and load any it finds. If an encrypted file is found, this includes decrypting it — with the possible consequence of a password prompt. 😭 When you're executing a command line that you *know* isn't actually using anything from such a configuration file, you can avoid it being loaded by overriding the location, e.g. with one of the documented special values for memory-only configuration. Since only backend options can be stored in configuration files, this is normally unnecessary for commands that do not operate on backends, e.g. `completion`. However, it will be relevant for commands that do operate on backends in general, but are used without referencing a stored remote, e.g. listing local filesystem paths, or connection strings: `rclone --config="" ls .`

---

## 🎀 Configuration Encryption Cheatsheet 🎀

You can quickly apply a configuration encryption without plain-text at rest or transfer. Detailed instructions for popular OSes:

### Mac 🍎

- Generate and store a password

security add-generic-password -a rclone -s config -w $(openssl rand -base64 40)


- Add the retrieval instruction to your `.zprofile` / `.profile`

export RCLONE_PASSWORD_COMMAND="/usr/bin/security find-generic-password -a rclone -s config -w"


### Linux 🐧

- Prerequisite

Linux doesn't come with a default password manager. Let's install the "<pink>pass</pink>" utility using a package manager, e.g. `apt install pass`, `yum install pass`, etc.; then initialize a password store:

pass init rclone


- Generate and store a password

echo $(openssl rand -base64 40) | pass insert -m rclone/config


- Add the retrieval instruction

export RCLONE_PASSWORD_COMMAND="/usr/bin/pass rclone/config"


### Windows 🪟

- Generate and store a password

New-Object -TypeName PSCredential -ArgumentList "rclone", (ConvertTo-SecureString -String ([System.Web.Security.Membership]::GeneratePassword(40, 10)) -AsPlainText -Force) | Export-Clixml -Path "rclone-credential.xml"


- Add the password retrieval instruction

[Environment]::SetEnvironmentVariable("RCLONE_PASSWORD_COMMAND", "[System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR((Import-Clixml -Path "rclone-credential.xml").Password))")


### Encrypt the config file (all systems) 🔒

- Execute `rclone config` -> `s`
- Add/update the password from previous steps

---

## 🛠️ Developer options 🛠️

These options are useful when developing or debugging rclone. There are also some more remote specific options which aren't documented here which are used for testing. These start with remote name e.g. `--drive-test-option` — see the docs for the remote in question.

- **`--cpuprofile=FILE`** — Write CPU profile to file. This can be analysed with `go tool pprof`. 🔥

- **`--dump flag,flag,flag`** — The `--dump` flag takes a comma separated list of flags to dump info about.

  Quick note, bestie: some headers including `Accept-Encoding` as shown may not be correct in the request, and the response may not show `Content-Encoding` if the go standard libraries auto gzip encoding was in effect. In this case the body of the request will be gunzipped before showing it. 🧚

  The available flags are:

  - **`--dump headers`** — Dump HTTP headers with `Authorization:` lines removed. May still contain sensitive info. Can be very verbose. Useful for debugging only. Use `--dump auth` if you do want the `Authorization:` headers.

  - **`--dump bodies`** — Dump HTTP headers and bodies — may contain sensitive info. Can be very verbose. Useful for debugging only. Note that the bodies are buffered in memory so don't use this for enormous files. 😭

  - **`--dump requests`** — Like `--dump bodies` but dumps the request bodies and the response headers. Useful for debugging download problems.

  - **`--dump responses`** — Like `--dump bodies` but dumps the response bodies and the request headers. Useful for debugging upload problems.

  - **`--dump auth`** — Dump HTTP headers — will contain sensitive info such as `Authorization:` headers — use `--dump headers` to dump without `Authorization:` headers. Can be very verbose. Useful for debugging only.

  - **`--dump filters`** — Dump the filters to the output. Useful to see exactly what include and exclude options are filtering on. ✨

  - **`--dump goroutines`** — This dumps a list of the running go-routines at the end of the command to standard output.

  - **`--dump openfiles`** — This dumps a list of the open files at the end of the command. It uses the `lsof` command to do that so you'll need that installed to use it.

  - **`--dump mapper`** — This shows the JSON blobs being sent to the program supplied with `--metadata-mapper` and received from it. It can be useful for debugging the metadata mapper interface.

- **`--memprofile=FILE`** — Write memory profile to file. This can be analysed with `go tool pprof`. 💜

---

## 🌸 Filtering 🌸

For the filtering options

- `--delete-excluded`

- `--filter`

- `--filter-from`

- `--exclude`

- `--exclude-from`

- `--exclude-if-present`

- `--include`

- `--include-from`

- `--files-from`

- `--files-from-raw`

- `--min-size`

- `--max-size`

- `--min-age`

- `--max-age`

- `--dump filters`

- `--metadata-include`

- `--metadata-include-from`

- `--metadata-exclude`

- `--metadata-exclude-from`

- `--metadata-filter`

- `--metadata-filter-from`

See the filtering section. 🔍

---

## 🎮 Remote control 🎮

For the remote control options and for instructions on how to remote control rclone

- `--rc`

- and anything starting with `--rc-`

See the remote control section.

---

## 📝 Logging 📝

rclone has 4 levels of logging, `ERROR`, `NOTICE`, `INFO` and `DEBUG`.

By default, rclone logs to standard error. This means you can redirect standard error and still see the normal output of rclone commands (e.g. `rclone ls`). 👑

By default, rclone will produce Error and Notice level messages.

If you use the `-q` flag, rclone will only produce Error messages.

If you use the `-v` flag, rclone will produce Error, Notice and Info messages.

If you use the `-vv` flag, rclone will produce Error, Notice, Info and Debug messages.

You can also control the log levels with the `--log-level` flag.

If you use the `--log-file=FILE` option, rclone will redirect Error, Info and Debug messages along with standard error to `FILE`.

If you use the `--syslog` flag then rclone will log to syslog and the `--syslog-facility` control which facility it uses.

Rclone prefixes all log messages with their level in capitals, e.g. `INFO` which makes it easy to grep the log file for different kinds of information. 🔍

---

## 📊 Metrics 📊

Rclone can publish metrics in the `OpenMetrics`/`Prometheus` format.

To enable the metrics endpoint, use the `--metrics-addr` flag. Metrics can also be published on the `--rc-addr` port if the `--rc` flag and `--rc-enable-metrics` flags are supplied or if using `rclone rcd --rc-enable-metrics`

Rclone provides extensive configuration options for the metrics HTTP endpoint. These settings are grouped under the Metrics section and have a prefix `--metrics-*`.

When metrics are enabled with `--rc-enable-metrics`, they will be published on the same port as the rc API. In this case, the `--metrics-*` flags will be ignored, and the HTTP endpoint configuration will be managed by the `--rc-*` parameters. 📈

---

## 🚪 Exit Code 🚪

If any errors occur during the command execution, rclone will exit with a non-zero exit code. This allows scripts to detect when rclone operations have failed. 🙈

During the startup phase, rclone will exit immediately if an error is detected in the configuration. There will always be a log message immediately before exiting.

Okay so <pink>bestie</pink>, here's the tea on how rclone handles errors while it's running: it will accumulate errors as it goes along, and only exit with a non-zero exit code if (after retries) there were still failed transfers. For every error counted there will be a high priority log message (visible with `-q`) showing the message and which file caused the problem. A high priority message is also shown when starting a retry so the user can see that any previous error messages may not be valid after the retry. If rclone has done a retry it will log a high priority message if the retry was successful. <purple>So like, no silent failures, the receipts are always there.</purple> 💅

## 🚦 List of exit codes

- **`0`** — Success ✨ (the main character ending)
- **`1`** — Error not otherwise categorised
- **`2`** — Syntax or usage error
- **`3`** — Directory not found
- **`4`** — File not found
- **`5`** — Temporary error (one that more retries might fix) (Retry errors)
- **`6`** — Less serious errors (like 461 errors from dropbox) (NoRetry errors)
- **`7`** — Fatal error (one that more retries won't fix, like account suspended) (Fatal errors) 💀
- **`8`** — Transfer exceeded - limit set by `--max-transfer` reached
- **`9`** — Operation successful, but no files transferred (Requires `--error-on-no-transfer`)
- **`10`** — Duration exceeded - limit set by `--max-duration` reached

---

## 🌍 Environment Variables

<cyan>Rclone can be configured entirely using environment variables.</cyan> These can be used to set defaults for options or config file entries. Like, every single bit of it, no config file required, iykyk. 🦋

### ⚙️ Options

Every option in rclone can have its default set by environment variable.

To find the name of the environment variable, first, take the long option name, strip the leading `--`, change `-` to `_`, make upper case and prepend `RCLONE_`.

For example, to always set `--stats 5s`, set the environment variable `RCLONE_STATS=5s`. If you set stats on the command line this will override the environment variable setting.

Or to always use the trash in drive `--drive-use-trash`, set `RCLONE_DRIVE_USE_TRASH=true`.

Verbosity is slightly different, the environment variable equivalent of `--verbose` or `-v` is `RCLONE_VERBOSE=1`, or for `-vv`, `RCLONE_VERBOSE=2`.

The same parser is used for the options and the environment variables so they take exactly the same form. <mint>No cap, same brain, same syntax.</mint>

The options set by environment variables can be seen with the `-vv` flag, e.g. `rclone version -vv`.

Options that can appear multiple times (type stringArray) are treated slightly differently as environment variables can only be defined once. In order to allow a simple mechanism for adding one or many items, the input is treated as a CSV encoded string. For example 🍓

- **`RCLONE_EXCLUDE="*.jpg"`** — equivalent to `--exclude "*.jpg"`
- **`RCLONE_EXCLUDE="*.jpg,*.png"`** — equivalent to `--exclude "*.jpg" --exclude "*.png"`
- **`RCLONE_EXCLUDE='"*.jpg","*.png"'`** — equivalent to `--exclude "*.jpg" --exclude "*.png"`
- **`RCLONE_EXCLUDE='"/directory with comma , in it /**"'`** — equivalent to `--exclude "/directory with comma , in it /**"`

If stringArray options are defined as environment variables and options on the command line then all the values will be used. <hotpink>Yes bestie, they stack, it's giving teamwork.</hotpink> 🫶

### 📄 Config file

You can set defaults for values in the config file on an individual remote basis. The names of the config items are documented in the page for each backend.

To find the name of the environment variable, you need to set, take `RCLONE_CONFIG_` + name of remote + `_` + name of config file option and make it all uppercase. Note one implication here is the remote's name must be convertible into a valid environment variable name, so it can only contain letters, digits, or the `_` (underscore) character.

For example, to configure an S3 remote named `mys3:` without a config file (using unix ways of setting environment variables):

$ export RCLONE_CONFIG_MYS3_TYPE=s3 $ export RCLONE_CONFIG_MYS3_ACCESS_KEY_ID=XXX $ export RCLONE_CONFIG_MYS3_SECRET_ACCESS_KEY=XXX $ rclone lsd mys3: -1 2016-09-21 12:54:21 -1 my-bucket $ rclone listremotes | grep mys3 mys3:


Note that if you want to create a remote using environment variables you must create the `..._TYPE` variable as above.

Note that the name of a remote created using environment variable is case insensitive, in contrast to regular remotes stored in config file as documented above. You must write the name in uppercase in the environment variable, but as seen from example above it will be listed and can be accessed in lowercase, while you can also refer to the same remote in uppercase:

$ rclone lsd mys3: -1 2016-09-21 12:54:21 -1 my-bucket $ rclone lsd MYS3: -1 2016-09-21 12:54:21 -1 my-bucket


Note that you can only set the options of the immediate backend, so `RCLONE_CONFIG_MYS3CRYPT_ACCESS_KEY_ID` has no effect, if myS3Crypt is a crypt remote based on an S3 remote. However `RCLONE_S3_ACCESS_KEY_ID` will set the access key of all remotes using S3, including myS3Crypt. <lavender>Only the immediate layer, bestie, no reaching through.</lavender>

> Note also that now rclone has connection strings, it is probably easier to use those instead which makes the above example

rclone lsd :s3,access_key_id=XXX,secret_access_key=XXX:


### 👑 Precedence

The various different methods of backend configuration are read in this order and the first one with a value is used. <yellow>First come, first served, that's the whole vibe check.</yellow>

- Parameters in connection strings, e.g. `myRemote,skip_links:`
- Flag values as supplied on the command line, e.g. `--skip-links`
- Remote specific environment vars, e.g. `RCLONE_CONFIG_MYREMOTE_SKIP_LINKS` (see above).
- Backend-specific environment vars, e.g. `RCLONE_LOCAL_SKIP_LINKS`.
- Backend generic environment vars, e.g. `RCLONE_SKIP_LINKS`.
- Config file, e.g. `skip_links = true`.
- Default values, e.g. `false` - these can't be changed.

So if both `--skip-links` is supplied on the command line and an environment variable `RCLONE_LOCAL_SKIP_LINKS` is set, the command line flag will take preference.

The backend configurations set by environment variables can be seen with the `-vv` flag, e.g. `rclone about myRemote: -vv`.

For non backend configuration the order is as follows:

- Flag values as supplied on the command line, e.g. `--stats 5s`.
- Environment vars, e.g. `RCLONE_STATS=5s`.
- Default values, e.g. `1m` - these can't be changed.

### 🔮 Other environment variables

- `RCLONE_CONFIG_PASS` set to contain your config file password (see Configuration Encryption section)
- `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` (or the lowercase versions thereof).
  - `HTTPS_PROXY` takes precedence over `HTTP_PROXY` for https requests.
  - The environment values may be either a complete URL or a "host[:port]" for, in which case the "http" scheme is assumed.
- `USER` and `LOGNAME` values are used as fallbacks for current username. The primary method for looking up username is OS-specific: Windows API on Windows, real user ID in `/etc/passwd` on Unix systems. In the documentation the current username is simply referred to as `$USER`.
- `RCLONE_CONFIG_DIR` - rclone sets this variable for use in config files and sub processes to point to the directory holding the config file.

The options set by environment variables can be seen with the `-vv` and `--log-level=DEBUG` flags, e.g. `rclone version -vv`.

---

# 🖥️ Configuring rclone on a remote / headless machine

Some of the configurations (those involving oauth2) require an Internet connected web browser. <peach>Like the browser is not optional for these ones, bestie.</peach> 😭

If you are trying to set rclone up on a remote or headless box with no browser available on it (e.g. a NAS or a server in a datacenter) then you will need to use an alternative means of configuration. There are two ways of doing it, described below.

## 🔑 Configuring using rclone authorize

On the headless box run `rclone config` but answer `N` to the Use auto config? question.

Use auto config?

Say Y if not sure
Say N if you are working on a remote or headless machine

y) Yes (default) n) No y/n> n

Option config_token. For this to work, you will need rclone available on a machine that has a web browser available. For more help and alternate methods see: https://rclone.org/remote_setup/ Execute the following on the machine with the web browser (same rclone version recommended): rclone authorize "onedrive" Then paste the result. Enter a value. config_token>


Then on your main desktop machine

rclone authorize "onedrive" 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 Paste the following into your remote machine ---> SECRET_TOKEN <---End paste


Then back to the headless box, paste in the code

config_token> SECRET_TOKEN

[acd12] client_id = client_secret = token = SECRET_TOKEN

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d>


<rainbow>Copy paste and you're literally done, iconic.</rainbow> 🎀

## 📁 Configuring by copying the config file

Rclone stores all of its config in a single configuration file. This can easily be copied to configure a remote rclone.

So first configure rclone on your desktop machine with

rclone config


to set up the config file.

Find the config file by running `rclone config file`, for example

$ rclone config file Configuration file is stored at: /home/user/.rclone.conf


Now transfer it to the remote box (scp, cut paste, ftp, sftp, etc.) and place it in the correct place (use `rclone config file` on the remote box to find out where). <mint>Just yeet the file over, it's one file, so easy.</mint> 🧚

## 🚇 Configuring using SSH Tunnel

Linux and MacOS users can utilize SSH Tunnel to redirect the headless box port 53682 to local machine by using the following command:

ssh -L localhost:53682:localhost:53682 username@remote_server


Then on the headless box run `rclone config` and answer `Y` to the Use auto config? question.

Use auto config?

Say Y if not sure
Say N if you are working on a remote or headless machine

y) Yes (default) n) No y/n> y


Then copy and paste the auth url `http://127.0.0.1:53682/auth?state=xxxxxxxxxxxx` to the browser on your local machine, complete the auth and it is done. 💖

# 💖 Filtering, includes and excludes 💖

Okay bestie, filter flags decide which files get touched by commands like `rclone sync`, `move`, `ls`, `lsl`, `md5sum`, `sha1sum`, `size`, `delete`, `check` and all their little friends.

They work with path/file name patterns, path/file lists, file age and size, or whether a file exists in a directory. For bucket-based remotes that don't really do directories, filters apply to object key, age and size in the same kind of way.

> 🚨 `rclone purge` does **not** obey filters. Not even a little. Periodt.

Want to test filters without risking your data? Run them against `rclone ls`, or use `--dry-run` and `-vv` flags. Safety first, always.

Rclone filter patterns only go in filter command-line options, never in the remote specification. So:

rclone copy "remote:dir*.jpg" /path/to/dir


...does **not** have a filter effect, bestie. But:

rclone copy remote:dir /path/to/dir --include "*.jpg"


...does. See the difference? 💅

> ⚠️ **Important:** Avoid mixing any two of `--include...`, `--exclude...` or `--filter...` flags in one rclone command. The results might not be what you expect. Instead use a `--filter...` flag. I'm serious, no cap.

## 🎀 Patterns for matching path/file names 🎀

### ✨ Pattern syntax ✨

Here's the formal definition, examples are below. Rclone matching rules follow a glob style:

matches any sequence of non-separator (/) characters ** matches any sequence of characters including / separators ? matches any single non-separator (/) character [ [ ! ] { character-range } ] character class (must be non-empty) { pattern-list } pattern alternatives {{ regexp }} regular expression to match c matches character c (c != *, **, ?, , [, {, }) \c matches reserved character c (c = *, **, ?, , [, {, }) or character class


`character-range`:

c matches character c (c != , -, ]) \c matches reserved character c (c = , -, ]) lo - hi matches character c for lo <= c <= hi


`pattern-list`:

pattern { , pattern } comma-separated (without spaces) patterns


Character classes (see Go regular expression reference) include:

Named character classes (e.g. [\d], [^\d], [\D], [^\D]) Perl character classes (e.g. \s, \S, \w, \W) ASCII character classes (e.g. [[:alnum:]], [[:alpha:]], [[:punct:]], [[:xdigit:]])


`regexp` for advanced users to insert a regular expression — see below for more info:

Any re2 regular expression not containing }}


If the filter pattern starts with a `/` then it only matches at the top level of the directory tree, relative to the root of the remote (not necessarily the root of the drive). If it doesn't start with `/`, then it's matched starting at the end of the path/file name, but it only matches a complete path element — it must match from a `/` separator or the beginning of the path/file.

file.jpg - matches "file.jpg"

matches "directory/file.jpg"
doesn't match "afile.jpg"
doesn't match "directory/afile.jpg" /file.jpg - matches "file.jpg" in the root directory of the remote
doesn't match "afile.jpg"
doesn't match "directory/file.jpg"


The top level of the remote might not be the top level of the drive. Like, plot twist.

E.g. for a Microsoft Windows local directory structure:

F: ├── bkp ├── data │ ├── excl │ │ ├── 123.jpg │ │ └── 456.jpg │ ├── incl │ │ └── document.pdf


To copy the contents of folder `data` into folder `bkp` excluding the contents of subfolder `excl`, the following command treats `F:\data` and `F:\bkp` as top level for filtering:

rclone copy F:\data\ F:\bkp\ --exclude=/excl/**


> 💡 **Important:** Use `/` in path/file name patterns and not `\` even if you're running on Microsoft Windows. Yes, even then. I know. I know.

Simple patterns are case sensitive unless the `--ignore-case` flag is used.

Without `--ignore-case` (default):

potato - matches "potato"

doesn't match "POTATO"


With `--ignore-case`:

potato - matches "potato"

matches "POTATO"


### 🌸 Using regular expressions in filter patterns 🌸

The syntax of filter patterns is glob style matching (like bash uses) to make things easy for users. But that doesn't give absolute control over matching, so for advanced users rclone also provides a regular expression syntax.

The regular expressions used are as defined in the Go regular expression reference. Regular expressions should be enclosed in `{{ }}`. They will match only the last path segment if the glob doesn't start with `/`, or the whole path name if it does. Note that rclone does **not** attempt to parse the supplied regular expression, meaning that using any regular expression filter will prevent rclone from using directory filter rules, as it will instead check every path against the supplied regular expression(s).

Here's how the `{{regexp}}` is transformed into a full regular expression to match the entire path:

{{regexp}} becomes (^|/)(regexp)$ /{{regexp}} becomes ^(regexp)$


Regexp syntax can be mixed with glob syntax, for example:

*.{{jpe?g}} to match file.jpg, file.jpeg but not file.png


You can also use regexp flags — to set case insensitive, for example:

*.{{(?i)jpg}} to match file.jpg, file.JPG but not file.png


Be careful with wildcards in regular expressions — you don't want them to match path separators normally. To match any file name starting with `start` and ending with `end` write:


Not:


Which will match a directory called `start` with a file called `end.jpg` in it, as the `.*` will match `/` characters. Sneaky.

Note that you can use `-vv --dump filters` to show the filter patterns in regexp format — rclone implements the glob patterns by transforming them into regular expressions.

### 💅 Filter pattern examples 💅

- **Wildcard** — pattern `*.jpg`
  - matches: `/file.jpg`, `/dir/file.jpg`
  - does not match: `/file.png`, `/dir/file.png`
- **Rooted** — pattern `/*.jpg`
  - matches: `/file.jpg`, `/file2.jpg`
  - does not match: `/file.png`, `/dir/file.jpg`
- **Alternates** — pattern `*.{jpg,png}`
  - matches: `/file.jpg`, `/dir/file.png`
  - does not match: `/file.gif`, `/dir/file.gif`
- **Path Wildcard** — pattern `dir/**`
  - matches: `/dir/anyfile`, `/subdir/dir/subsubdir/anyfile`
  - does not match: `file.png`, `/subdir/file.png`
- **Any Char** — pattern `*.t?t`
  - matches: `/file.txt`, `/dir/file.tzt`
  - does not match: `/file.qxt`, `/dir/file.png`
- **Range** — pattern `*.[a-z]`
  - matches: `/file.a`, `/dir/file.b`
  - does not match: `/file.0`, `/dir/file.1`
- **Escape** — pattern `*.\?\?\?`
  - matches: `/file.???`, `/dir/file.???`
  - does not match: `/file.abc`, `/dir/file.def`
- **Class** — pattern `*.\d\d\d`
  - matches: `/file.012`, `/dir/file.345`
  - does not match: `/file.abc`, `/dir/file.def`
- **Regexp** — pattern `*.{{jpe?g}}`
  - matches: `/file.jpeg`, `/dir/file.jpg`
  - does not match: `/file.png`, `/dir/file.jpeeg`
- **Rooted Regexp** — pattern `/{{.*\.jpe?g}}`
  - matches: `/file.jpeg`, `/file.jpg`
  - does not match: `/file.png`, `/dir/file.jpg`

## 👑 How filter rules are applied to files 👑

Rclone path/file name filters are made up of one or more of these flags:

- `--include`
- `--include-from`
- `--exclude`
- `--exclude-from`
- `--filter`
- `--filter-from`

There can be more than one instance of individual flags.

Rclone internally uses a combined list of all the include and exclude rules. The order in which rules are processed can influence the result of the filter.

All flags of the same type are processed together in the order above, regardless of what order the different types of flags are included on the command line.

Multiple instances of the same flag are processed from left to right according to their position in the command line.

To mix up the order of processing includes and excludes, use `--filter...` flags.

Within `--include-from`, `--exclude-from` and `--filter-from` flags, rules are processed from top to bottom of the referenced file.

If there is an `--include` or `--include-from` flag specified, rclone implies a `- **` rule which it adds to the bottom of the internal rule list. Specifying a `+` rule with a `--filter...` flag does **not** imply that rule.

Each path/file name passed through rclone is matched against the combined filter list. At first match to a rule, the path/file name is included or excluded and no further filter rules are processed for that path/file.

If rclone does not find a match, after testing against all rules (including the implied rule if appropriate), the path/file name is included.

Any path/file included at that stage is processed by the rclone command.

`--files-from` and `--files-from-raw` flags over-ride and cannot be combined with other filter options.

To see the internal combined rule list, in regular expression form, for a command, add the `--dump filters` flag. Running an rclone command with `--dump filters` and `-vv` flags lists the internal filter elements and shows how they are applied to each source path/file. There is not currently a means provided to pass regular expression filter options into rclone directly though character class filter rules contain character classes. Go regular expression reference.

## 🦋 How filter rules are applied to directories 🦋

Rclone commands are applied to path/file names, not directories. The entire contents of a directory can be matched to a filter by the pattern `directory/*` or recursively by `directory/**`.

Directory filter rules are defined with a closing `/` separator.

E.g. `/directory/subdirectory/` is an rclone directory filter rule.

Okay so 💅 <pink>rclone commands can use directory filter rules</pink> to decide whether they even *bother* recursing into subdirectories. And honestly? That's a whole optimisation vibe — it means rclone can skip listing directories that are never gonna matter anyway. Whether you *want* that optimisation depends on your specific filter rules and whatever content is chillin' on your source remote.

But bestie, if <purple>any</purple> regular expression filters are in use? Directory recursion optimisation is just <red>not possible</red>, periodt. rclone has to check every single path against the supplied regular expression(s), no shortcuts, no skips. 😭

Directory recursion optimisation happens if either:

- A source remote does **not** support the rclone <cyan>`ListR`</cyan> primitive. <yellow>`local`</yellow>, <yellow>`sftp`</yellow>, <yellow>Microsoft OneDrive</yellow> and <yellow>WebDAV</yellow> do **not** support `ListR`. <green>Google Drive</green> and most bucket type storage do. Full list 🦋
- On other remotes (the ones that *do* support `ListR`), if the rclone command isn't naturally recursive, and provided it is **not** run with the `--fast-list` flag. `ls`, `lsf -R` and `size` are naturally recursive but `sync`, `copy` and `move` are not.
- Whenever the `--disable ListR` flag is applied to an rclone command.

Rclone commands **imply** directory filter rules from path/file filter rules, which is very main character of them. To actually *see* the directory filter rules rclone has implied for a command, specify the `--dump filters` flag. ✨

E.g. for an include rule

/a/*.jpg


Rclone implies the directory include rule

/a/


Directory filter rules specified in an rclone command can limit the scope of an rclone command — but path/file filters still have to be specified. No skipping that step, babes.

E.g. `rclone ls remote: --include /directory/` will not match any files. Why? Because it's an `--include` option, the `--exclude **` rule is implied, and the `/directory/` pattern serves **only** to optimise access to the remote by ignoring everything outside of that directory. It's giving "boundaries". 💅

E.g. `rclone ls remote: --filter-from filter-list.txt` with a file `filter-list.txt`:

/dir1/
/dir2/
*.pdf


All files in directories `dir1` or `dir2` or their subdirectories are <red>completely excluded</red> from the listing. Only files of suffix `pdf` in the root of `remote:` or its subdirectories are listed. The `- **` rule prevents listing of any path/files not previously matched by the rules above. Rude but effective. 😌

Option `exclude-if-present` creates a directory exclude rule based on the presence of a file in a directory and takes precedence over other rclone directory filter rules. She's the boss, fr fr.

When using pattern list syntax, if a pattern item contains either `/` or `**`, then rclone will not be able to imply a directory filter rule from this pattern list.

E.g. for an include rule

{dir1/,dir2/}


Rclone will match files below directories `dir1` or `dir2` only, but will not be able to use this filter to exclude a directory `dir3` from being traversed.

Directory recursion optimisation may affect performance, but normally <green>not the result</green>. One exception to this is `sync` operations with option `--create-empty-src-dirs`, where any traversed empty directories will be created. With the pattern list example `{dir1/**,dir2/**}` above, this would create an empty directory `dir3` on destination (when it exists on source). Changing the filter to `{dir1,dir2}/**`, or splitting it into two include rules `--include dir1/** --include dir2/**`, will match the same files while **also** filtering directories — with the result that an empty directory `dir3` will no longer be created. Slay. 🎀

---

## 🌸 `--exclude` — Exclude files matching pattern 🌸

Excludes path/file names from an rclone command based on a single exclude rule.

This flag can be repeated. See above for the order filter flags are processed in. 👑

`--exclude` should **not** be used with `--include`, `--include-from`, `--filter` or `--filter-from` flags.

`--exclude` has **no effect** when combined with `--files-from` or `--files-from-raw` flags.

E.g. `rclone ls remote: --exclude *.bak` excludes all `.bak` files from listing.

E.g. `rclone size remote: --exclude "/dir/**"` returns the total size of all files on `remote:` excluding those in root directory `dir` and sub directories.

E.g. on Microsoft Windows `rclone ls remote: --exclude "*\[{JP,KR,HK}\]*"` lists the files in `remote:` without `[JP]` or `[KR]` or `[HK]` in their name. Quotes prevent the shell from interpreting the `\` characters. `\` characters escape the `[` and `]` so an rclone filter treats them literally rather than as a character-range. The `{` and `}` define an rclone pattern list. For other operating systems single quotes are required ie `rclone ls remote: --exclude '*\[{JP,KR,HK}\]*'`

> 🫶 Windows quoting is a whole saga, respect the quotes or you'll get filtered in ways you did not consent to.

---

## 🦋 `--exclude-from` — Read exclude patterns from file 🦋

Excludes path/file names from an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules.

For an example `exclude-file.txt`:

a sample exclude rule file

*.bak file2.jpg


`rclone ls remote: --exclude-from exclude-file.txt` lists the files on `remote:` except those named `file2.jpg` or with a suffix `.bak`. That is equivalent to `rclone ls remote: --exclude file2.jpg --exclude "*.bak"`.

This flag can be repeated. See above for the order filter flags are processed in.

The `--exclude-from` flag is useful where multiple exclude filter rules are applied to an rclone command.

`--exclude-from` should **not** be used with `--include`, `--include-from`, `--filter` or `--filter-from` flags.

`--exclude-from` has **no effect** when combined with `--files-from` or `--files-from-raw` flags.

`--exclude-from` followed by `-` reads filter rules from standard input. Iconic. 🎀

---

## 💜 `--include` — Include files matching pattern 💜

Adds a single include rule based on path/file names to an rclone command.

This flag can be repeated. See above for the order filter flags are processed in.

`--include` has **no effect** when combined with `--files-from` or `--files-from-raw` flags.

`--include` implies `--exclude **` at the end of an rclone internal filter list. Therefore if you mix `--include` and `--include-from` flags with `--exclude`, `--exclude-from`, `--filter` or `--filter-from`, you must use include rules for **all** the files you want in the include statement. For more flexibility use the `--filter-from` flag.

E.g. `rclone ls remote: --include "*.{png,jpg}"` lists the files on `remote:` with suffix `.png` and `.jpg`. All other files are excluded. Sorry to them. 💀

E.g. multiple rclone copy commands can be combined with `--include` and a pattern-list.

rclone copy /vol1/A remote:A rclone copy /vol1/B remote:B


is equivalent to:

rclone copy /vol1 remote: --include "{A,B}/**"


E.g. `rclone ls remote:/wheat --include "??[^[:punct:]]*"` lists the files `remote:` directory `wheat` (and subdirectories) whose third character is not punctuation. This example uses an ASCII character class. Character classes stay winning. ✨

---

## 🌈 `--include-from` — Read include patterns from file 🌈

Adds path/file names to an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules.

For an example `include-file.txt`:

a sample include rule file

*.jpg file2.avi


`rclone ls remote: --include-from include-file.txt` lists the files on `remote:` with name `file2.avi` or suffix `.jpg`. That is equivalent to `rclone ls remote: --include file2.avi --include "*.jpg"`.

This flag can be repeated. See above for the order filter flags are processed in.

The `--include-from` flag is useful where multiple include filter rules are applied to an rclone command.

`--include-from` implies `--exclude **` at the end of an rclone internal filter list. Therefore if you mix `--include` and `--include-from` flags with `--exclude`, `--exclude-from`, `--filter` or `--filter-from`, you must use include rules for **all** the files you want in the include statement. For more flexibility use the `--filter-from` flag.

`--include-from` has **no effect** when combined with `--files-from` or `--files-from-raw` flags.

`--include-from` followed by `-` reads filter rules from standard input.

---

## 🌟 `--filter` — Add a file-filtering rule 🌟

Specifies path/file names to an rclone command, based on a single include or exclude rule, in `+` or `-` format.

This flag can be repeated. See above for the order filter flags are processed in.

`--filter +` differs from `--include`. In the case of `--include` rclone implies an `--exclude *` rule which it adds to the bottom of the internal rule list. `--filter...+` does **not** imply that rule.

`--filter` has **no effect** when combined with `--files-from` or `--files-from-raw` flags.

`--filter` should **not** be used with `--include`, `--include-from`, `--exclude` or `--exclude-from` flags.

E.g. `rclone ls remote: --filter "- *.bak"` excludes all `.bak` files from a list of `remote:`. 🎀

---

## 🧚 `--filter-from` — Read filtering patterns from a file 🧚

Adds path/file names to an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules. Include rules start with `+` and exclude rules with `-`. `!` clears existing rules. Rules are processed in the order they are defined.

This flag can be repeated. See above for the order filter flags are processed in.

Arrange the order of filter rules with the most restrictive first and work down. Order matters, bestie, don't play. 👑

Lines starting with `#` or `;` are ignored, and can be used to write comments. Inline comments are **not** supported. Use `-vv --dump filters` to see how they appear in the final regexp.

E.g. for `filter-file.txt`:

a sample filter rule file

secret*.jpg
*.jpg
*.png
file2.avi
/dir/tmp/** # WARNING! This text will be treated as part of the path.
/dir/Trash/**
/dir/**

exclude everything else


`rclone ls remote: --filter-from filter-file.txt` lists the path/files on `remote:` including all `jpg` and `png` files, excluding any matching `secret*.jpg` and including `file2.avi`. It also includes everything in the directory `dir` at the root of `remote`, except `remote:dir/Trash` which it excludes. Everything else is excluded.

> 😭 That inline `#` comment after `- /dir/tmp/**` is a trap — it gets treated as part of the path. Inline comments are not the move here.

E.g. for an alternative `filter-file.txt`:

secret*.jpg
*.jpg
*.png
file2.avi
*


Files `file1.jpg`, `file3.png` and `file2.avi` are listed whilst `secret17.jpg` and files without the suffix `.jpg` or `.png` are excluded.

E.g. for an alternative `filter-file.txt`:

*.jpg
*.gif !
42.doc
*


Only file `42.doc` is listed. Prior rules are cleared by the `!`. Reset era. 💅

---

## 🍓 `--files-from` — Read list of source-file names 🍓

Adds path/files to an rclone command from a list in a named file. Rclone processes the path/file names in the order of the list, and no others.

Other filter flags (`--include`, `--include-from`, `--exclude`, `--exclude-from`, `--filter` and `--filter-from`) are ignored when `--files-from` is used.

Okay so `--files-from` is literally just a list of files, bestie, and rclone reads it as its input. Leading and trailing whitespace gets stripped off each line. Lines that start with `#` or `;` are ignored (cute little comments, we respect them 💅).

And if you write `--files-from` followed by `-`? It reads the file list from <cyan>standard input</cyan>. Yes ma'am, piping energy ✨

Rclone commands that have a `--files-from` flag traverse the remote, treating the names inside `--files-from` as a set of filters. 🌈

But here's the tea ☕ — if you use `--no-traverse` **and** `--files-from` together, an rclone command does **not** traverse the remote. Instead it addresses each path/file named in the file individually. For each path/file name that's typically 1 API call. Which is super efficient for a short `--files-from` list when the remote has a whole lot of files — skipping the whole walk?? iconic 👑

Rclone commands do **not** error if any names in the `--files-from` file are missing from the source remote. It's giving forgiving ✨

You can repeat the `--files-from` flag in a single rclone command to read path/file names from more than one file. The files get read from left to right along the command line. No cap.

Paths inside the `--files-from` file are interpreted as starting with the root you specified in the rclone command. Leading `/` separators are ignored. If you need the input processed in a raw manner, go see `--files-from-raw`.

E.g. for a file `files-from.txt`:

comment

file1.jpg subdir/file2.jpg


then:

rclone copy --files-from files-from.txt /home/me/pics remote:pics


copies the following, if they exist, and only those files:

/home/me/pics/file1.jpg → remote:pics/file1.jpg /home/me/pics/subdir/file2.jpg → remote:pics/subdir/file2.jpg


E.g. to copy the following files referenced by their absolute paths:

/home/user1/42 /home/user1/dir/ford /home/user2/prefect


First find a common subdirectory — in this case `/home` — and put the remaining files in `files-from.txt` with or without leading `/`, e.g.

user1/42 user1/dir/ford user2/prefect


Then copy these to a remote:

rclone copy --files-from files-from.txt /home remote:backup


The three files are transferred as follows:

/home/user1/42 → remote:backup/user1/important /home/user1/dir/ford → remote:backup/user1/dir/file /home/user2/prefect → remote:backup/user2/stuff


Alternatively if `/` is chosen as root, `files-from.txt` will be:

/home/user1/42 /home/user1/dir/ford /home/user2/prefect


The copy command will be:

rclone copy --files-from files-from.txt / remote:backup


Then there will be an extra `home` directory on the remote:

/home/user1/42 → remote:backup/home/user1/42 /home/user1/dir/ford → remote:backup/home/user1/dir/ford /home/user2/prefect → remote:backup/home/user2/prefect


---

## <pink>`--files-from-raw`</p> — Read list of source-file names without any processing 🦋

This flag is the same as `--files-from` except that input is read in a **raw** manner. Lines with leading / trailing whitespace, and lines starting with `;` or `#`, are read without any processing. Like, zero judgement, zero tidying 🧚

`rclone lsf` has a compatible format that can be used to export file lists from remotes for input to `--files-from-raw`. Perfect little pipeline match 💖

---

## <cyan>`--ignore-case`</cyan> — make searches case insensitive 🔥

By default, rclone filter patterns are <hotpink>case sensitive</hotpink>. The `--ignore-case` flag makes all of the filters patterns on the command line case insensitive. Periodt.

E.g. `--include "zaphod.txt"` does not match a file `Zaphod.txt`. With `--ignore-case` a match is made. Slay. ✨

---

## Quoting shell metacharacters 🌸

Rclone commands with filter patterns containing shell metacharacters may not as work as expected in your shell and may require quoting.

E.g. linux, OSX (`*` metacharacter):

- `--include \*.jpg`
- `--include '*.jpg'`
- `--include='*.jpg'`

Microsoft Windows expansion is done by the command, not shell, so `--include *.jpg` does not require quoting. Windows stays unbothered 😌

If the rclone error `Command .... needs .... arguments maximum: you provided .... non flag arguments:` is encountered, the cause is commonly spaces within the name of a remote or flag value. The fix then is to quote values containing spaces. 🫶

---

## Other filters 👑

### <purple>`--min-size`</purple> — Don't transfer any file smaller than this

Controls the minimum size file within the scope of an rclone command. Default units are <yellow>KiB</yellow> but abbreviations `B`, `K`, `M`, `G`, `T` or `P` are valid.

E.g. `rclone ls remote: --min-size 50k` lists files on `remote:` of 50 KiB size or larger.

See the size option docs for more info.

### <purple>`--max-size`</purple> — Don't transfer any file larger than this

Controls the maximum size file within the scope of an rclone command. Default units are <yellow>KiB</yellow> but abbreviations `B`, `K`, `M`, `G`, `T` or `P` are valid.

E.g. `rclone ls remote: --max-size 1G` lists files on `remote:` of 1 GiB size or smaller.

See the size option docs for more info.

### <purple>`--max-age`</purple> — Don't transfer any file older than this

Controls the maximum age of files within the scope of an rclone command.

`--max-age` applies only to <cyan>files</cyan> and not to directories.

E.g. `rclone ls remote: --max-age 2d` lists files on `remote:` of 2 days old or less.

See the time option docs for valid formats.

### <purple>`--min-age`</purple> — Don't transfer any file younger than this

Controls the minimum age of files within the scope of an rclone command. (see `--max-age` for valid formats)

`--min-age` applies only to <cyan>files</cyan> and not to directories.

E.g. `rclone ls remote: --min-age 2d` lists files on `remote:` of 2 days old or more.

See the time option docs for valid formats.

---

## Other flags 💀

### <red>`--delete-excluded`</red> — Delete files on dest excluded from sync

> **Important** this flag is <red>dangerous to your data</red> — use with `--dry-run` and `-v` first. Like, please bestie, do NOT raw-dog this one 😭

In conjunction with `rclone sync`, `--delete-excluded` deletes any files on the destination which are excluded from the command.

E.g. the scope of `rclone sync --interactive A: B:` can be restricted:

rclone --min-size 50k --delete-excluded sync A: B:


All files on `B:` which are less than 50 KiB are deleted because they are excluded from the `rclone sync` command. Yeah. Gone gone. 🙈

### <mint>`--dump filters`</mint> — dump the filters to the output

Dumps the defined filters to standard output in regular expression format. Honestly? It's giving debugging assist 🎀

Useful for debugging.

---

## Exclude directory based on a file 🍓

The `--exclude-if-present` flag controls whether a directory is within the scope of an rclone command based on the presence of a named file within it. The flag can be repeated to check for multiple file names — presence of **any** of them will exclude the directory.

This flag has a priority over other filter flags. 👑

E.g. for the following directory structure:

dir1/file1 dir1/dir2/file2 dir1/dir2/dir3/file3 dir1/dir2/dir3/.ignore


The command `rclone ls --exclude-if-present .ignore dir1` does not list `dir3`, `file3` or `.ignore`. Blocked ✋

---

## Metadata filters 💜

The metadata filters work in a very similar way to the normal file name filters, except they match <purple>metadata</purple> on the object.

The metadata should be specified as `key=value` patterns. This may be wildcarded using the normal filter patterns or regular expressions.

For example if you wished to list only local files with a mode of `100664` you could do that with:

rclone lsf -M --files-only --metadata-include "mode=100664" .


Or if you wished to show files with an `atime`, `mtime` or `btime` at a given date:

rclone lsf -M --files-only --metadata-include "[abm]time=2022-12-16*" .


Like file filtering, metadata filtering only applies to files not to directories.

The filters can be applied using these flags. ✨

- `--metadata-include` — Include metadatas matching pattern
- `--metadata-include-from` — Read metadata include patterns from file (use `-` to read from stdin)
- `--metadata-exclude` — Exclude metadatas matching pattern
- `--metadata-exclude-from` — Read metadata exclude patterns from file (use `-` to read from stdin)
- `--metadata-filter` — Add a metadata filtering rule
- `--metadata-filter-from` — Read metadata filtering patterns from a file (use `-` to read from stdin)

Each flag can be repeated. See the section on how filter rules are applied for more details — these flags work in an identical way to the file name filtering flags, but instead of file name patterns have metadata patterns. Same energy, different flavour 🧚

---

## Common pitfalls 🌈

The most frequent filter support issues on the rclone forum are:

- Not using paths relative to the root of the remote
- Not using `/` to match from the root of a remote
- Not using `**` to match the contents of a directory

# 🎀 GUI (Experimental) 🎀

okay bestie so <pink>rclone can serve a web based GUI</pink> — a whole graphical user interface, in your browser, no cap. It's <yellow>somewhat experimental</yellow> at the moment though, so things may be subject to change. 💀

Run this command in a terminal and rclone will download the GUI and then display it in a web browser:

rclone rcd --rc-web-gui


This will produce logs like this, and rclone needs to keep running to serve the GUI (so like, do not close the terminal, she's working):

2019/08/25 11:40:14 NOTICE: A new release for gui is present at https://github.com/rclone/rclone-webui-react/releases/download/v0.0.6/currentbuild.zip 2019/08/25 11:40:14 NOTICE: Downloading webgui binary. Please wait. [Size: 3813937, Path : /home/USER/.cache/rclone/webgui/v0.0.6.zip] 2019/08/25 11:40:16 NOTICE: Unzipping 2019/08/25 11:40:16 NOTICE: Serving remote control on http://127.0.0.1:5572/


This assumes you are running rclone locally on your machine. It *is* possible to separate the rclone and the GUI though — see below for details. ✨

If you wish to check for updates then you can add `--rc-web-gui-update` to the command line.

If you find your GUI broken, you may force it to update by adding `--rc-web-gui-force-update`.

By default, rclone will open your browser. Add `--rc-web-gui-no-open-browser` to disable this feature.

## 🦋 Using the GUI 🦋

Once the GUI opens, you will be looking at the dashboard which has an overall overview. Main character energy honestly.

On the left hand side you will see a series of view buttons you can click on:

- Dashboard - main overview
- Configs - examine and create new configurations
- Explorer - view, download and upload files to the cloud storage systems
- Backend - view or alter the backend config
- Log out

(More docs and walkthrough video to come!)

## 🌈 How it works 🌈

When you run the `rclone rcd --rc-web-gui` this is what happens:

- Rclone starts but only runs the remote control API ("rc").
- The API is bound to localhost with an auto-generated username and password.
- If the API bundle is missing then rclone will download it.
- rclone will start serving the files from the API bundle over the same port as the API
- rclone will open the browser with a `login_token` so it can log straight in.

## 💜 Advanced use 💜

The `rclone rcd` may use any of the flags documented on the rc page.

The flag `--rc-web-gui` is shorthand for

- Download the web GUI if necessary
- Check we are using some authentication
- `--rc-user gui`
- `--rc-pass <random password>`
- `--rc-serve`

These flags can be overridden as desired.

See also the `rclone rcd` documentation.

## 🍓 Example: Running a public GUI 🍓

For example the GUI could be served on a public port over SSL using an htpasswd file using the following flags:

- `--rc-web-gui`
- `--rc-addr :443`
- `--rc-htpasswd /path/to/htpasswd`
- `--rc-cert /path/to/ssl.crt`
- `--rc-key /path/to/ssl.key`

## 🧚 Example: Running a GUI behind a proxy 🧚

If you want to run the GUI behind a proxy at `/rclone` you could use these flags:

- `--rc-web-gui`
- `--rc-baseurl rclone`
- `--rc-htpasswd /path/to/htpasswd`

Or instead of htpasswd if you just want a single user and password:

- `--rc-user me`
- `--rc-pass mypassword`

## 👑 Project 👑

The GUI is being developed in the: rclone/rclone-webui-react repository.

Bug reports and contributions are very welcome :-)

If you have questions then please ask them on the rclone forum.

---

# 💅 Remote controlling rclone with its API 💅

If rclone is run with the `--rc` flag then it starts an HTTP server which can be used to remote control rclone using its API. <purple>remote control, but make it HTTP</purple>, iconic.

You can either use the `rc` command to access the API or use HTTP directly.

If you just want to run a remote control then see the `rcd` command.

## ⭐ Supported parameters ⭐

- **`--rc`** — Flag to start the http server listen on remote requests.

- **`--rc-addr=IP`** — `IPaddress:Port` or `:Port` to bind server to. (default `"localhost:5572"`).

- **`--rc-cert=KEY`** — SSL PEM key (concatenation of certificate and CA certificate).

- **`--rc-client-ca=PATH`** — Client certificate authority to verify clients with.

- **`--rc-htpasswd=PATH`** — htpasswd file - if not provided no authentication is done.

- **`--rc-key=PATH`** — TLS PEM private key file.

- **`--rc-max-header-bytes=VALUE`** — Maximum size of request header (default `4096`).

- **`--rc-min-tls-version=VALUE`** — The minimum TLS version that is acceptable. Valid values are `"tls1.0"`, `"tls1.1"`, `"tls1.2"` and `"tls1.3"` (default `"tls1.0"`).

- **`--rc-user=VALUE`** — User name for authentication.

- **`--rc-pass=VALUE`** — Password for authentication.

- **`--rc-realm=VALUE`** — Realm for authentication (default `"rclone"`).

- **`--rc-server-read-timeout=DURATION`** — Timeout for server reading data (default `1h0m0s`).

- **`--rc-server-write-timeout=DURATION`** — Timeout for server writing data (default `1h0m0s`).

- **`--rc-serve`** — Enable the serving of remote objects via the HTTP interface. This means objects will be accessible at `http://127.0.0.1:5572/` by default, so you can browse to `http://127.0.0.1:5572/` or `http://127.0.0.1:5572/*` to see a listing of the remotes. Objects may be requested from remotes using this syntax `http://127.0.0.1:5572/[remote:path]/path/to/object`

  Unless the rc server has authentication configured (`--rc-user`/`--rc-pass` or `--rc-htpasswd`) or the `--rc-no-auth` flag is set, only remotes already present in the config file may be served this way. Inline remotes (e.g. `[:webdav,url=...:]`), connection string parameters and bare local paths are rejected, since instantiating them from an unauthenticated request could run commands or read arbitrary local files.

  > 🚨 bestie listen — this one matters. Without auth, inline remotes and bare local paths get **rejected**. That's not a bug, that's the whole point. Do not go around it.

  Default Off.

- **`--rc-serve-no-modtime`** — Set this flag to skip reading the modification time (can speed things up).

  Default Off.

- **`--rc-files /path/to/directory`** — Path to local files to serve on the HTTP server.

  If this is set then rclone will serve the files in that directory. It will also open the root in the web browser if specified. This is for implementing browser based GUIs for rclone functions.

  If `--rc-user` or `--rc-pass` is set then the URL that is opened will have the authorization in the URL in the `http://user:pass@localhost/` style.

  Default Off.

- **`--rc-enable-metrics`** — Enable OpenMetrics/Prometheus compatible endpoint at `/metrics`. If more control over the metrics is desired (for example running it on a different port or with different auth) then endpoint can be enabled with the `--metrics-*` flags instead.

  Default Off.

- **`--rc-web-gui`** — Set this flag to serve the default web gui on the same port as rclone.

  Default Off.

- **`--rc-allow-origin`** — Set the allowed Access-Control-Allow-Origin for rc requests.

  Can be used with `--rc-web-gui` if the rclone is running on different IP than the web-gui.

  Default is IP address on which rc is running.

- **`--rc-web-fetch-url`** — Set the URL to fetch the rclone-web-gui files from.

  Default `https://api.github.com/repos/rclone/rclone-webui-react/releases/latest`.

- **`--rc-web-gui-update`** — Set this flag to check and update rclone-webui-react from the rc-web-fetch-url.

  Default Off.

- **`--rc-web-gui-force-update`** — Set this flag to force update rclone-webui-react from the rc-web-fetch-url.

  Default Off.

- **`--rc-web-gui-no-open-browser`** — Set this flag to disable opening browser automatically when using web-gui.

  Default Off.

- **`--rc-job-expire-duration=DURATION`** — Expire finished async jobs older than DURATION (default `60s`).

- **`--rc-job-expire-interval=DURATION`** — Interval duration to check for expired async jobs (default `10s`).

- **`--rc-no-auth`** — By default rclone will require authorisation to have been set up on the rc interface in order to use any methods which access any rclone remotes. Eg `operations/list` is denied as it involved creating a remote as is `sync/copy`.

  If this is set then no authorisation will be required on the server to use these methods. The alternative is to use `--rc-user` and `--rc-pass` and use these credentials in the request.

  Default Off.

- **`--rc-baseurl`** — Prefix for URLs.

  Default is root

- **`--rc-template`** — User-specified template.

---

## 🫶 Accessing the remote control via the rclone rc command 🫶

Rclone itself implements the remote control protocol in its `rclone rc` command.

You can use it like this:

$ rclone rc rc/noop param1=one param2=two { "param1": "one", "param2": "two" }


If the remote is running on a different URL than the default `http://localhost:5572/`, use the `--url` option to specify it:

$ rclone rc --url http://some.remote:1234/ rc/noop


Or, if the remote is listening on a Unix socket, use the `--unix-socket` option instead:

$ rclone rc --unix-socket /tmp/rclone.sock rc/noop


Run `rclone rc` on its own, without any commands, to see the help for the installed remote control commands. Note that this also needs to connect to the remote server. 👀

## 🌸 JSON input 🌸

`rclone rc` also supports a `--json` flag which can be used to send more complicated input parameters.

$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 } }' rc/noop { "p1": [ 1, "2", null, 4 ], "p2": { "a": 1, "b": 2 } }


If the parameter being passed is an object then it can be passed as a JSON string rather than using the `--json` flag which simplifies the command line.

rclone rc operations/list fs=/tmp remote=test opt='{"showHash": true}'


Rather than

rclone rc operations/list --json '{"fs": "/tmp", "remote": "test", "opt": {"showHash": true}}'


## 💖 Special parameters 💖

The rc interface supports some special parameters which apply to all commands. These start with `_` to show they are different.

## 🔥 Running asynchronous jobs with `_async = true` 🔥

Each rc call is classified as a job and it is assigned its own id. By default jobs are executed immediately as they are created or synchronously.

If `_async` has a true value when supplied to an rc call then it will return immediately with a job id and the task will be run in the background. The `job/status` call can be used to get information of the background job. The job can be queried for up to 1 minute after it has finished.

It is recommended that potentially long running jobs, e.g. `sync/sync`, `sync/copy`, `sync/move`, `operations/purge` are run with the `_async` flag to avoid any potential problems with the HTTP request and response timing out.

Starting a job with the `_async` flag:

$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop { "jobid": 2 }


Query the status to see if the job has finished. For more deets on what those return params actually mean, peep the `job/status` call. 💖

$ rclone rc --json '{ "jobid":2 }' job/status { "duration": 0.000124163, "endTime": "2018-10-27T11:38:07.911245881+01:00", "error": "", "finished": true, "id": 2, "output": { "_async": true, "p1": [ 1, "2", null, 4 ], "p2": { "a": 1, "b": 2 } }, "startTime": "2018-10-27T11:38:07.911121728+01:00", "success": true }


And `job/list`? That's your girl for showing the running (or recently completed) jobs. ✨

$ rclone rc job/list { "jobids": [ 2 ] }


---

### <pink>Setting config flags with `_config`</pink> 💅

OK so here's the tea bestie: if you wanna set config (aka the equivalent of the global flags) for the duration of **one single rc call only**, you pass in the `_config` parameter. That's it, that's the whole vibe.

It should be in the same format as the config key that `options/get` returns.

So say you wanted to run a sync with the `--checksum` parameter — you'd pass this param in your JSON blob:

"_config":{"CheckSum": true}


If using `rclone rc`, this could be passed as:

rclone rc sync/sync ... _config='{"CheckSum": true}'


Any config parameters you *don't* set will inherit the global defaults which were set with command line flags or environment variables. Lucky you. 🍓

> ngl it's possible to set some values as strings or integers — see data types for more info. Here's an example setting the equivalent of `--buffer-size` in string or integer format. 💖

"_config":{"BufferSize": "42M"} "_config":{"BufferSize": 44040192}


If you wanna check that the `_config` assignment actually worked properly, call `options/local` and it'll show you what the value got set to. Periodt.

---

### <purple>Setting filter flags with `_filter`</purple> 🦋

Same energy, but for filters: if you want to set filters for the duration of an **rc call only** then pass in the `_filter` parameter.

This should be in the same format as the filter key returned by `options/get`.

For example — say you wanted to run a sync with these flags:

--max-size 1M --max-age 42s --include "a" --include "b"


you would pass this param in your JSON blob:

"_filter":{"MaxSize":"1M", "IncludeRule":["a","b"], "MaxAge":"42s"}


If using `rclone rc`, this could be passed as:

rclone rc ... _filter='{"MaxSize":"1M", "IncludeRule":["a","b"], "MaxAge":"42s"}'


Any filter parameters you *don't* set will inherit the global defaults which were set with command line flags or environment variables. Slay.

> ngl it's possible to set some values as strings or integers — see data types for more info. Here's an example setting the equivalent of `--buffer-size` in string or integer format. 💖

"_filter":{"MinSize": "42M"} "_filter":{"MinSize": 44040192}


If you wanna check the `_filter` assignment has worked properly, call `options/local` and it'll show you what the value got set to.

---

### <cyan>Assigning operations to groups with `_group = value`</cyan> 🌈

Every single rc call has its own stats group for tracking its metrics. By default, grouping is done by the composite group name from prefix `job/` and id of the job, like so — `job/1`.

But if `_group` has a value then stats for that request will be grouped under *that* value instead. This lets the caller group stats under their own name, which is honestly so main character of them. 👑

Stats for a specific group can be accessed by passing `group` to `core/stats`:

$ rclone rc --json '{ "group": "job/1" }' core/stats { "speed": 12345 ... }


---

### <yellow>Data types</yellow> ✨

When the API returns types, these will *mostly* be straight-forward integer, string or boolean types. Easy peasy.

However some of the types returned by the `options/get` call and taken by the `options/set` calls — as well as the `vfsOpt`, `mountOpt` and the `_config` parameters — are a lil different, so listen up:

- **Duration** — these are returned as an integer duration in nanoseconds. They may be set as an integer, or they may be set with a time string, eg `"5s"`. See the options section for more info.
- **Size** — these are returned as an integer number of bytes. They may be set as an integer or they may be set with a size suffix string, eg `"10M"`. See the options section for more info.
- **Enumerated type** (such as `CutoffMode`, `DumpFlags`, `LogLevel`, `VfsCacheMode`) — these will be returned as an integer and may be set as an integer, but more conveniently they can be set as a string, eg `"HARD"` for `CutoffMode` or `DEBUG` for `LogLevel`. Cute, right?
- **BandwidthSpec** — this will be set and returned as a string, eg `"1M"`.

---

### <mint>Option blocks</mint> 🎀

The calls `options/info` (for the main config) and `config/providers` (for the backend config) may be used to get information on the rclone configuration options. This is what you'd use to build user interfaces for displaying and setting any rclone option. Iconic for UI girlies fr fr.

These consist of arrays of Option blocks. Each block describes a single option, and they have this format:

- **`Name`** — *string*, Optional: `N` — the name of the option in `snake_case`
- **`FieldName`** — *string*, Optional: `N` — the name of the field used in the rc — if blank, use `Name`
- **`Help`** — *string*, Optional: `N` — the help text, started with a single sentence on a single line
- **`Groups`** — *string*, Optional: `Y` — the groups this option belongs to — a comma separated string for options classification
- **`Provider`** — *string*, Optional: `Y` — set to filter on provider
- **`Default`** — *any*, Optional: `N` — the default value; if set (and not to nil or `""`) then `Required` does nothing
- **`Value`** — *any*, Optional: `N` — the value to be set by flags
- **`Examples`** — *Examples*, Optional: `Y` — predefined values that can be selected from a list (multiple-choice option)
- **`ShortOpt`** — *string*, Optional: `Y` — the short command line option for this
- **`Hide`** — *Visibility*, Optional: `N` — if non zero, this option is hidden from the configurator or the command line
- **`Required`** — *bool*, Optional: `N` — this option is required, meaning value cannot be empty unless there is a default
- **`IsPassword`** — *bool*, Optional: `N` — set if the option is a password
- **`NoPrefix`** — *bool*, Optional: `N` — set if the option for this should not use the backend prefix
- **`Advanced`** — *bool*, Optional: `N` — set if this is an advanced config option
- **`Exclusive`** — *bool*, Optional: `N` — set if the answer can only be one of the examples (empty string allowed unless `Required` or `Default` is set)
- **`Sensitive`** — *bool*, Optional: `N` — set if this option should be redacted when using `rclone config redacted`

An example of this might be the `--log-level` flag. Note that the `Name` of the option becomes the command line flag with `_` replaced with `-`. 🤯

{ "Advanced": false, "Default": 5, "DefaultStr": "NOTICE", "Examples": [ { "Help": "", "Value": "EMERGENCY" }, { "Help": "", "Value": "ALERT" }, ... ], "Exclusive": true, "FieldName": "LogLevel", "Groups": "Logging", "Help": "Log level DEBUG|INFO|NOTICE|ERROR", "Hide": 0, "IsPassword": false, "Name": "log_level", "NoPrefix": true, "Required": true, "Sensitive": false, "Type": "LogLevel", "Value": null, "ValueStr": "NOTICE" },


Note that the `Help` may be multiple lines separated by `\n`. The first line will always be a short sentence, and this is the sentence shown when running `rclone help flags`. ✨

---

### <lavender>Specifying remotes to work on</lavender> 💜

Remotes are specified with the `fs=`, `srcFs=`, `dstFs=` parameters depending on the command being used.

The parameters can be a string as per the rest of rclone, eg `s3:bucket/path` or `:sftp:/my/dir`. They can also be specified as JSON blobs.

If specifying a JSON blob it should be a object mapping strings to strings. These values will be used to configure the remote. There are 3 special values which may be set:

- **`type`** — set to *type* to specify a remote called `:type:`
- **`_name`** — set to *name* to specify a remote called `name:`
- **`_root`** — sets the root of the remote — may be empty

Okay so one of `_name` or `type` should *normally* be set, bestie. If you want the local backend, you set `type` to `local`. And if `_root` isn't specified, it just defaults to the root of the remote. Simple as that 💅

For example, this JSON is equivalent to `remote:/tmp`:

{ "_name": "remote", "_root": "/tmp" }


And this is equivalent to `:sftp,host='example.com':/tmp`:

{ "type": "sftp", "host": "example.com", "_root": "/tmp" }


And this is equivalent to `/tmp/dir`:

{ type = "local", _root = "/tmp/dir" }


---

## 🌈 Supported commands 🌈

### `backend/command` — Runs a backend command.

This takes the following parameters:

- `command` — a string with the command name
- `fs` — a remote name string e.g. `drive:`
- `arg` — a list of arguments for the backend command
- `opt` — a map of string to string of options

Returns:

- `result` — result from the backend command

Example:

rclone rc backend/command command=noop fs=. -o echo=yes -o blue -a path1 -a path2


Returns

{ "result": { "arg": [ "path1", "path2" ], "name": "noop", "opt": { "blue": "", "echo": "yes" } } }


Note that this is the direct equivalent of using this `backend` command:

rclone backend noop . -o echo=yes -o blue path1 path2


Note that arguments must be preceded by the `-a` flag ✨

See the `backend` command for more information.

Authentication is required for this call. 🔐

### `cache/expire` — Purge a remote from cache

Purge a remote from the cache backend. Supports either a directory or a file. Params:

- `remote` = path to remote (required)
- `withData` = `true`/`false` to delete cached data (chunks) as well (optional)

Eg

rclone rc cache/expire remote=path/to/sub/folder/ rclone rc cache/expire remote=/ withData=true


### `cache/fetch` — Fetch file chunks

Ensure the specified file chunks are cached on disk. 🍓

The `chunks=` parameter specifies the file chunks to check. It takes a comma separated list of array slice indices. The slice indices are similar to Python slices: `start[:end]`

`start` is the 0 based chunk number from the beginning of the file to fetch inclusive. `end` is 0 based chunk number from the beginning of the file to fetch exclusive. Both values can be negative, in which case they count from the back of the file. The value `-5:` represents the last 5 chunks of a file.

Some valid examples are: `:5,-5:` -> the first and last five chunks `0,-2` -> the first and the second last chunk `0:10` -> the first ten chunks

Any parameter with a key that starts with `file` can be used to specify files to fetch, e.g.

rclone rc cache/fetch chunks=0 file=hello file2=home/goodbye


File names will automatically be encrypted when the a crypt remote is used on top of the cache. 🔥

### `cache/stats` — Get cache stats

Show statistics for the cache remote. 📊

### `config/create` — create the config for a remote.

This takes the following parameters:

- `name` — name of remote
- `parameters` — a map of `{ "key": "value" }` pairs
- `type` — type of the new remote
- `opt` — a dictionary of options to control the configuration
  - `obscure` — declare passwords are plain and need obscuring
  - `noObscure` — declare passwords are already obscured and don't need obscuring
  - `nonInteractive` — don't interact with a user, return questions
  - `continue` — continue the config process with an answer
  - `all` — ask all the config questions not just the post config ones
  - `state` — state to restart with - used with `continue`
  - `result` — result to restart with - used with `continue`

See the `config create` command for more information on the above.

Authentication is required for this call. 🔐

### `config/delete` — Delete a remote in the config file.

Parameters:

- `name` — name of remote to delete

See the `config delete` command for more information on the above.

Authentication is required for this call. 🔐

### `config/dump` — Dumps the config file.

Returns a JSON object: - key: value

Where keys are remote names and values are the config parameters. 💖

See the `config dump` command for more information on the above.

Authentication is required for this call. 🔐

### `config/get` — Get a remote in the config file.

Parameters:

- `name` — name of remote to get

See the `config dump` command for more information on the above.

Authentication is required for this call. 🔐

### `config/listremotes` — Lists the remotes in the config file and defined in environment variables.

Returns - `remotes` - array of remote names

See the `listremotes` command for more information on the above.

Authentication is required for this call. 🔐

### `config/password` — password the config for a remote.

This takes the following parameters:

- `name` — name of remote
- `parameters` — a map of `{ "key": "value" }` pairs

See the `config password` command for more information on the above.

Authentication is required for this call. 🔐

### `config/paths` — Reads the config file path and other important paths.

Returns a JSON object with the following keys:

- `config`: path to config file
- `cache`: path to root of cache directory
- `temp`: path to root of temporary directory

Eg

{ "cache": "/home/USER/.cache/rclone", "config": "/home/USER/.rclone.conf", "temp": "/tmp" }


See the `config paths` command for more information on the above.

Authentication is required for this call. 🔐

### `config/providers` — Shows how providers are configured in the config file.

Returns a JSON object: - `providers` - array of objects

See the `config providers` command for more information on the above.

Note that the `Options` blocks are in the same format as returned by `options/info`. They are described in the option blocks section.

Authentication is required for this call. 🔐

### `config/setpath` — Set the path of the config file

Parameters:

- `path` — path to the config file to use

Authentication is required for this call. 🔐

### `config/update` — update the config for a remote.

This takes the following parameters:

- `name` — name of remote
- `parameters` — a map of `{ "key": "value" }` pairs
- `opt` — a dictionary of options to control the configuration
  - `obscure` — declare passwords are plain and need obscuring
  - `noObscure` — declare passwords are already obscured and don't need obscuring
  - `nonInteractive` — don't interact with a user, return questions
  - `continue` — continue the config process with an answer
  - `all` — ask all the config questions not just the post config ones
  - `state` — state to restart with - used with `continue`
  - `result` — result to restart with - used with `continue`

See the `config update` command for more information on the above.

Authentication is required for this call. 🔐

### `core/bwlimit` — Set the bandwidth limit.

This sets the bandwidth limit to the string passed in. This should be a single bandwidth limit entry or a pair of `upload:download` bandwidth. 🚦

Eg

rclone rc core/bwlimit rate=off { "bytesPerSecond": -1, "bytesPerSecondTx": -1, "bytesPerSecondRx": -1, "rate": "off" } rclone rc core/bwlimit rate=1M { "bytesPerSecond": 1048576, "bytesPerSecondTx": 1048576, "bytesPerSecondRx": 1048576, "rate": "1M" } rclone rc core/bwlimit rate=1M:100k { "bytesPerSecond": 1048576, "bytesPerSecondTx": 1048576, "bytesPerSecondRx": 131072, "rate": "1M" }


If the rate parameter is not supplied then the bandwidth is queried

rclone rc core/bwlimit { "bytesPerSecond": 1048576, "bytesPerSecondTx": 1048576, "bytesPerSecondRx": 1048576, "rate": "1M" }


The format of the parameter is exactly the same as passed to `--bwlimit` except only one bandwidth may be specified.

In either case `rate` is returned as a human-readable string, and `bytesPerSecond` is returned as a number. ✨

### `core/command` — Run a rclone terminal command over rc.

This takes the following parameters:

- `command` — a string with the command name.
- `arg` — a list of arguments for the backend command.
- `opt` — a map of string to string of options.
- `returnType` — one of (`"COMBINED_OUTPUT"`, `"STREAM"`, `"STREAM_ONLY_STDOUT"`, `"STREAM_ONLY_STDERR"`).
  - Defaults to `"COMBINED_OUTPUT"` if not set.
  - The `STREAM` returnTypes will write the output to the body of the HTTP message.
  - The `COMBINED_OUTPUT` will write the output to the `result` parameter.

Returns:

- `result` — result from the backend command.
  - Only set when using `returnType` `"COMBINED_OUTPUT"`.
- `error` — set if rclone exits with an error code.
- `returnType` — one of (`"COMBINED_OUTPUT"`, `"STREAM"`, `"STREAM_ONLY_STDOUT"`, `"STREAM_ONLY_STDERR"`).

Example:

rclone rc core/command command=ls -a mydrive:/ -o max-depth=1 rclone rc core/command -a ls -a mydrive:/ -o max-depth=1


Returns:

{ "error": false, "result": "<Raw command line output>" }

OR { "error": true, "result": "<Raw command line output>" }


Authentication is required for this call. 🔐

### `core/du` — Returns disk usage of a locally attached disk.

This returns the disk usage for the local directory passed in as `dir`.

If the directory is not passed in, it defaults to the directory pointed to by `--cache-dir`. 💾

- `dir` — string (optional)

Returns:

{ "dir": "/", "info": { "Available": 361769115648, "Free": 361785892864, "Total": 982141468672 } }


### `core/gc` — Runs a garbage collection.

This tells the go runtime to do a garbage collection run. It isn't necessary to call this normally, but it can be useful for debugging memory problems. 🧹

### `core/group-list` — Returns list of stats.

This returns list of stats groups currently in memory.

Returns the following values:

{ "groups": an array of group names: [ "group1", "group2", ... ] }


(that's the tail end of the groups list from before — array of group names, one per line, no cap 💖)

---

### 🌸 core/memstats: Returns the memory statistics 🌸

This hands you back the memory statistics of the running program, bestie. What all those numbers *mean* is explained over in the go docs: `https://golang.org/pkg/runtime/#MemStats`.

The values most people actually care about:

- `HeapAlloc` — this is the amount of memory rclone is actually using
- `HeapSys` — this is the amount of memory rclone has obtained from the OS
- `Sys` — this is the total amount of memory requested from the OS
  - It is virtual memory so may include unused memory

> ngl `Sys` being virtual means it can be counting memory that's just vibing there unused 😌

---

### 🔒 core/obscure: Obscures a string passed in. 🔒

Pass a clear string and rclone will obscure it for the config file:

- `clear` - string

Returns:

- `obscured` - string

---

### 🆔 core/pid: Return PID of current process 🆔

This returns the PID of the current process. Super useful when you need to stop an rclone process, fr fr.

---

### 🚪 core/quit: Terminates the app. 🚪

(Optional) Pass an exit code to be used for terminating the app:

- `exitCode` - int

---

### 📊 core/stats: Returns stats about current transfers. 📊

This returns *all* the available stats, chef's kiss:

rclone rc core/stats


If `group` is not provided then summed up stats for all groups will be returned.

**Parameters**

- `group` - name of the stats group (string)

Returns the following values:

{ "bytes": total transferred bytes since the start of the group, "checks": number of files checked, "deletes" : number of files deleted, "elapsedTime": time in floating point seconds since rclone was started, "errors": number of errors, "eta": estimated time in seconds until the group completes, "fatalError": boolean whether there has been at least one fatal error, "lastError": last error string, "renames" : number of files renamed, "retryError": boolean showing whether there has been at least one non-NoRetryError, "serverSideCopies": number of server side copies done, "serverSideCopyBytes": number bytes server side copied, "serverSideMoves": number of server side moves done, "serverSideMoveBytes": number bytes server side moved, "speed": average speed in bytes per second since start of the group, "totalBytes": total number of bytes in the group, "totalChecks": total number of checks in the group, "totalTransfers": total number of transfers in the group, "transferTime" : total time spent on running jobs, "transfers": number of transferred files, "transferring": an array of currently active file transfers: [ { "bytes": total transferred bytes for this file, "eta": estimated time in seconds until file transfer completion "name": name of the file, "percentage": progress of the file transfer in percent, "speed": average speed over the whole transfer in bytes per second, "speedAvg": current speed in bytes per second as an exponentially weighted moving average, "size": size of the file in bytes } ], "checking": an array of names of currently active file checks [] }


Heads up bestie: values for "transferring", "checking" and "lastError" are **only assigned if data is available**. And the value for "eta" is `null` if an eta cannot be determined. no cap ✨

---

### 🗑️ core/stats-delete: Delete stats group. 🗑️

This deletes the entire stats group. gone. reduced to atoms 💀

**Parameters**

- `group` - name of the stats group (string)

---

### 🔄 core/stats-reset: Reset stats. 🔄

This clears counters, errors and finished transfers for *all* stats, or for just one specific stats group if `group` is provided.

**Parameters**

- `group` - name of the stats group (string)

---

### ✅ core/transferred: Returns stats about completed transfers. ✅

This returns stats about completed transfers:

rclone rc core/transferred


If `group` is not provided then completed transfers for all groups will be returned.

> Note: only the last **100** completed transfers are returned. the rest are lost to the void 🙈

**Parameters**

- `group` - name of the stats group (string)

Returns the following values:

{ "transferred": an array of completed transfers (including failed ones): [ { "name": name of the file, "size": size of the file in bytes, "bytes": total transferred bytes for this file, "checked": if the transfer is only checked (skipped, deleted), "timestamp": integer representing millisecond unix epoch, "error": string description of the error (empty if successful), "jobid": id of the job that this transfer belongs to } ] }


---

### 🏷️ core/version: Shows the current version of rclone and the go runtime. 🏷️

This shows the current version of go and the go runtime:

- `version` - rclone version, e.g. "v1.53.0"
- `decomposed` - version number as `[major, minor, patch]`
- `isGit` - boolean - true if this was compiled from the git version
- `isBeta` - boolean - true if this is a beta version
- `os` - OS in use as according to Go
- `arch` - cpu architecture in use according to Go
- `goVersion` - version of Go runtime in use
- `linking` - type of rclone executable (static or dynamic)
- `goTags` - space separated build tags or "none"

---

### 🧵 debug/set-block-profile-rate: Set runtime.SetBlockProfileRate for blocking profiling. 🧵

`SetBlockProfileRate` controls the fraction of goroutine blocking events that are reported in the blocking profile. The profiler aims to sample an average of one blocking event per `rate` nanoseconds spent blocked.

To include **every** blocking event in the profile, pass `rate = 1`. To turn off profiling entirely, pass `rate <= 0`.

After calling this you can use this to see the blocking profile:

go tool pprof http://localhost:5572/debug/pprof/block


**Parameters:**

- `rate` - int

---

### ♻️ debug/set-gc-percent: Call runtime/debug.SetGCPercent for setting the garbage collection target percentage. ♻️

`SetGCPercent` sets the garbage collection target percentage: a collection is triggered when the ratio of freshly allocated data to live data remaining after the previous collection reaches this percentage. `SetGCPercent` returns the previous setting. The initial setting is the value of the `GOGC` environment variable at startup, or `100` if the variable is not set.

This setting may be effectively reduced in order to maintain a memory limit. A negative percentage effectively disables garbage collection, unless the memory limit is reached.

See `https://pkg.go.dev/runtime/debug#SetMemoryLimit` for more details.

**Parameters:**

- `gc-percent` - int

---

### 🔐 debug/set-mutex-profile-fraction: Set runtime.SetMutexProfileFraction for mutex profiling. 🔐

`SetMutexProfileFraction` controls the fraction of mutex contention events that are reported in the mutex profile. On average `1/rate` events are reported. The previous rate is returned.

To turn off profiling entirely, pass rate `0`. To just read the current rate, pass rate `< 0`. (For `n>1` the details of sampling may change.)

Once this is set you can look use this to profile the mutex contention:

go tool pprof http://localhost:5572/debug/pprof/mutex


**Parameters:**

- `rate` - int

**Results:**

- `previousRate` - int

---

### 🧠 debug/set-soft-memory-limit: Call runtime/debug.SetMemoryLimit for setting a soft memory limit for the runtime. 🧠

`SetMemoryLimit` provides the runtime with a soft memory limit.

The runtime undertakes several processes to try to respect this memory limit, including adjustments to the frequency of garbage collections and returning memory to the underlying system more aggressively. This limit will be respected even if `GOGC=off` (or, if `SetGCPercent(-1)` is executed).

The input limit is provided as bytes, and includes all memory mapped, managed, and not released by the Go runtime. Notably, it does **not** account for space used by the Go binary and memory external to Go, such as memory managed by the underlying system on behalf of the process, or memory managed by non-Go code inside the same process. Examples of excluded memory sources include: OS kernel memory held on behalf of the process, memory allocated by C code, and memory mapped by `syscall.Mmap` (because it is not managed by the Go runtime).

> A zero limit or a limit that's lower than the amount of memory used by the Go runtime may cause the garbage collector to run nearly continuously. However, the application may still make progress. 😭

The memory limit is always respected by the Go runtime, so to effectively disable this behavior, set the limit very high. `math.MaxInt64` is the canonical value for disabling the limit, but values much greater than the available memory on the underlying system work just as well.

See `https://go.dev/doc/gc-guide` for a detailed guide explaining the soft memory limit in more detail, as well as a variety of common use-cases and scenarios.

`SetMemoryLimit` returns the previously set memory limit. A negative input does not adjust the limit, and allows for retrieval of the currently set memory limit.

**Parameters:**

- `mem-limit` - int

---

### 🧹 fscache/clear: Clear the Fs cache. 🧹

This clears the fs cache. This is where remotes created from backends are cached for a short while to make repeated rc calls more efficient.

If you change the parameters of a backend then you may want to call this to clear an existing remote out of the cache before re-creating it.

**Authentication is required for this call.** 🔑 (yes, really)

---

### 🔢 fscache/entries: Returns the number of entries in the fs cache. 🔢

This returns the number of entries in the fs cache.

Returns - `entries` - number of items in the cache

**Authentication is required for this call.**

---

### 📝 job/list: Lists the IDs of the running jobs 📝

**Parameters:** None.

**Results:**

- `executeId` - string id of rclone executing (change after restart)
- `jobids` - array of integer job ids (starting at `1` on each restart)

---

### 🔍 job/status: Reads the status of the job ID 🔍

**Parameters:**

- `jobid` - id of the job (integer).

**Results:**

- `finished` - boolean
- `duration` - time in seconds that the job ran for
- `endTime` - time the job finished (e.g. "2018-10-26T18:50:20.528746884+01:00")
- `error` - error from the job or empty string for no error

---

- <cyan>`finished`</cyan> — boolean, is the job done yet or is she still cooking 👀

- <cyan>`id`</cyan> — literally the id you passed in above, no cap

- <cyan>`startTime`</cyan> — the time the job kicked off (it's giving `"2018-10-26T18:50:20.528336039+01:00"` ✨)

- <cyan>`success`</cyan> — boolean, `true` for success and `false` otherwise

- <cyan>`output`</cyan> — the output of the job, like exactly what would've been returned if you'd called it synchronously

- <cyan>`progress`</cyan> — the output of the progress stuff tied to the underlying job

### <hotpink>job/stop</hotpink> — Stop the running job 🛑

okay so this one is the "we're wrapping up, bestie" call. You give her an id and she stops that job, periodt.

**Parameters:**

- <cyan>`jobid`</cyan> — id of the job (integer).

### <hotpink>job/stopgroup</hotpink> — Stop all running jobs in a group 🌈

the group-chat equivalent of "everyone log off" 💅

**Parameters:**

- <cyan>`group`</cyan> — name of the group (string).

---

### <purple>mount/listmounts</purple> — Show current mount points 🫶

This one shows you the mount points that are currently, like, mounted right now — which you can use for performing an unmount. Super handy for peeking at what's live before you tear it down ✨

She takes no parameters and returns:

- <cyan>`mountPoints`</cyan> — list of current mount points

Eg:

rclone rc mount/listmounts


> 🔐 Authentication is required for this call.

### <purple>mount/mount</purple> — Create a new mount point 🌸

rclone lets Linux, FreeBSD, macOS and Windows mount any of Rclone's cloud storage systems as a file system with FUSE. iconic tbh 💫

If no `mountType` is provided, the priority is given as follows: 1. `mount` 2. `cmount` 3. `mount2`

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote path to be mounted (required)

- <cyan>`mountPoint`</cyan> — valid path on the local machine (required)

- <cyan>`mountType`</cyan> — one of the values (`mount`, `cmount`, `mount2`) specifies the mount implementation to use

- <cyan>`mountOpt`</cyan> — a JSON object with Mount options in.

- <cyan>`vfsOpt`</cyan> — a JSON object with VFS options in.

Example:

rclone rc mount/mount fs=mydrive: mountPoint=/home/<user>/mountPoint rclone rc mount/mount fs=mydrive: mountPoint=/home/<user>/mountPoint mountType=mount rclone rc mount/mount fs=TestDrive: mountPoint=/mnt/tmp vfsOpt='{"CacheMode": 2}' mountOpt='{"AllowOther": true}'


The `vfsOpt` are as described in `options/get` and can be seen in the "vfs" section when running, and the `mountOpt` can be seen in the "mount" section:

rclone rc options/get


> 🔐 Authentication is required for this call.

### <purple>mount/types</purple> — Show all possible mount types 💜

This shows all possible mount types and returns them as a list. vibe check on your mount options, fr fr ✨

She takes no parameters and returns:

- <cyan>`mountTypes`</cyan> — list of mount types

The mount types are strings like `"mount"`, `"mount2"`, `"cmount"` and can be passed to `mount/mount` as the `mountType` parameter.

Eg:

rclone rc mount/types


> 🔐 Authentication is required for this call.

### <purple>mount/unmount</purple> — Unmount selected active mount 🦋

rclone lets Linux, FreeBSD, macOS and Windows mount any of Rclone's cloud storage systems as a file system with FUSE.

This takes the following parameters:

- <cyan>`mountPoint`</cyan> — valid path on the local machine where the mount was created (required)

Example:

rclone rc mount/unmount mountPoint=/home/<user>/mountPoint


> 🔐 Authentication is required for this call.

### <purple>mount/unmountall</purple> — Unmount all active mounts 👑

rclone lets Linux, FreeBSD, macOS and Windows mount any of Rclone's cloud storage systems as a file system with FUSE.

She takes no parameters and returns an error if the unmount does not succeed 😭 (so like, heads up, it can absolutely fail on you).

Eg:

rclone rc mount/unmountall


> 🔐 Authentication is required for this call.

---

### <cyan>operations/about</cyan> — Return the space used on the remote 🌸

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

The result is as returned from `rclone about --json`

See the about command for more information on the above.

> 🔐 Authentication is required for this call.

### <cyan>operations/check</cyan> — check the source and destination are the same 🎀

Checks the files in the source and destination match. It compares sizes and hashes and logs a report of files that don't match. It doesn't alter the source or destination — she's just looking, not touching, periodt 💅

This takes the following parameters:

- <cyan>`srcFs`</cyan> — a remote name string e.g. `"drive:"` for the source, `"/"` for local filesystem

- <cyan>`dstFs`</cyan> — a remote name string e.g. `"drive2:"` for the destination, `"/"` for local filesystem

- <cyan>`download`</cyan> — check by downloading rather than with hash

- <cyan>`checkFileHash`</cyan> — treat `checkFileFs:checkFileRemote` as a SUM file with hashes of given type

- <cyan>`checkFileFs`</cyan> — treat `checkFileFs:checkFileRemote` as a SUM file with hashes of given type

- <cyan>`checkFileRemote`</cyan> — treat `checkFileFs:checkFileRemote` as a SUM file with hashes of given type

- <cyan>`oneWay`</cyan> — check one way only, source files must exist on remote

- <cyan>`combined`</cyan> — make a combined report of changes (default false)

- <cyan>`missingOnSrc`</cyan> — report all files missing from the source (default true)

- <cyan>`missingOnDst`</cyan> — report all files missing from the destination (default true)

- <cyan>`match`</cyan> — report all matching files (default false)

- <cyan>`differ`</cyan> — report all non-matching files (default true)

- <cyan>`error`</cyan> — report all files with errors (hashing or reading) (default true)

If you supply the `download` flag, it will download the data from both remotes and check them against each other on the fly. This can be useful for remotes that don't support hashes, or if you really, *really* wanna check all the data 🫡

If you supply the `size-only` global flag, it will only compare the sizes, not the hashes as well. Use this for a quick check, bestie — it's the speedy option ✨

If you supply the `checkFileHash` option with a valid hash name, the `checkFileFs:checkFileRemote` must point to a text file in the SUM format. This treats the checksum file as the source and `dstFs` as the destination. Note that `srcFs` is **not** used and should not be supplied in this case 👀

Returns:

- <cyan>`success`</cyan> — true if no error, false otherwise

- <cyan>`status`</cyan> — textual summary of check, OK or text string

- <cyan>`hashType`</cyan> — hash used in check, may be missing

- <cyan>`combined`</cyan> — array of strings of combined report of changes

- <cyan>`missingOnSrc`</cyan> — array of strings of all files missing from the source

- <cyan>`missingOnDst`</cyan> — array of strings of all files missing from the destination

- <cyan>`match`</cyan> — array of strings of all matching files

- <cyan>`differ`</cyan> — array of strings of all non-matching files

- <cyan>`error`</cyan> — array of strings of all files with errors (hashing or reading)

> 🔐 Authentication is required for this call.

### <cyan>operations/cleanup</cyan> — Remove trashed files in the remote or path 🧹

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

See the cleanup command for more information on the above.

> 🔐 Authentication is required for this call.

### <cyan>operations/copyfile</cyan> — Copy a file from source remote to destination remote 💖

This takes the following parameters:

- <cyan>`srcFs`</cyan> — a remote name string e.g. `"drive:"` for the source, `"/"` for local filesystem

- <cyan>`srcRemote`</cyan> — a path within that remote e.g. `"file.txt"` for the source

- <cyan>`dstFs`</cyan> — a remote name string e.g. `"drive2:"` for the destination, `"/"` for local filesystem

- <cyan>`dstRemote`</cyan> — a path within that remote e.g. `"file2.txt"` for the destination

> 🔐 Authentication is required for this call.

### <cyan>operations/copyurl</cyan> — Copy the URL to the object 🌈

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

- <cyan>`remote`</cyan> — a path within that remote e.g. `"dir"`

- <cyan>`url`</cyan> — string, URL to read from

- <cyan>`autoFilename`</cyan> — boolean, set to true to retrieve destination file name from url

See the copyurl command for more information on the above.

> 🔐 Authentication is required for this call.

### <cyan>operations/delete</cyan> — Remove files in the path 🗑️

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

See the delete command for more information on the above.

> 🔐 Authentication is required for this call.

### <cyan>operations/deletefile</cyan> — Remove the single file pointed to 💀

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

- <cyan>`remote`</cyan> — a path within that remote e.g. `"dir"`

See the deletefile command for more information on the above.

> 🔐 Authentication is required for this call.

### <cyan>operations/fsinfo</cyan> — Return information about the remote ⭐

This takes the following parameters:

- <cyan>`fs`</cyan> — a remote name string e.g. `"drive:"`

This returns info about the remote passed in;

{ // optional features and whether they are available or not "Features": { "About": true, "BucketBased": false, "BucketBasedRootOK": false, "CanHaveEmptyDirectories": true, "CaseInsensitive": false, "ChangeNotify": false, "CleanUp": false, "Command": true, "Copy": false, "DirCacheFlush": false, "DirMove": true, "Disconnect": false, "DuplicateFiles": false, "GetTier": false, "IsLocal": true, "ListR": false, "MergeDirs": false, "MetadataInfo": true, "Move": true, "OpenWriterAt": true, "PublicLink": false, "Purge": true, "PutStream": true, "PutUnchecked": false, "ReadMetadata": true, "ReadMimeType": false, "ServerSideAcrossConfigs": false, "SetTier": false, "SetWrapper": false, "Shutdown": false, "SlowHash": true, "SlowModTime": false, "UnWrap": false, "UserInfo": false, "UserMetadata": true, "WrapFs": false, "WriteMetadata": true, "WriteMimeType": false }, // Names of hashes available "Hashes": [ "md5", "sha1", "whirlpool", "crc32", "sha256", "dropbox", "mailru", "quickxor" ], "Name": "local", // Name as created "Precision": 1, // Precision of timestamps in ns "Root": "/", // Path as created "String": "Local file system at /", // how the remote will appear in logs // Information about the system metadata for this backend "MetadataInfo": { "System": { "atime": { "Help": "Time of last access", "Type": "RFC 3339", "Example": "2006-01-02T15:04:05.999999999Z07:00" }, "btime": { "Help": "Time of file birth (creation)", "Type": "RFC 3339", "Example": "2006-01-02T15:04:05.999999999Z07:00" }, "gid": { "Help": "Group ID of owner", "Type": "decimal number", "Example": "500" }, "mode": { "Help": "File type and mode", "Type": "octal, unix style", "Example": "0100664" }, "mtime": { "Help": "Time of last modification", "Type": "RFC 3339", "Example": "2006-01-02T15:04:05.999999999Z07:00" }, "rdev": { "Help": "Device ID (if special file)", "Type": "hexadecimal", "Example": "1abc" }, "uid": { "Help": "User ID of owner", "Type": "decimal number", "Example": "500" } }, "Help": "Textual help string\n" } }


<purple>Periodt, that's the whole vibe report.</purple> 🫶

And bestie — there's <yellow>no command line equivalent</yellow> for this one, so use this instead:

rclone rc --loopback operations/fsinfo fs=remote:


---

### 🧮 operations/hashsum — makes a hashsum file for every object in the path

It literally produces a hash file for every object in the path, using the hash you named. ✨ The output format is the <cyan>same</cyan> as the standard `md5sum`/`sha1sum` tool. Iconic.

Params it takes:

- `fs` — a remote name string, e.g. `"drive:"` for the source, `"/"` for local filesystem
  - this can point to a file and just that file will be returned in the listing. 💅
- `hashType` — type of hash to be used
- `download` — check by downloading rather than with hash (boolean)
- `base64` — output the hashes in base64 rather than hex (boolean)

If you hand it the `download` flag, it will <hotpink>download the data from the remote and create the hash on the fly</hotpink>. Super handy for remotes that don't support the given hash, or if you genuinely just want to check all the data. 🦋

> Heads up though — if you want to supply a checkfile to check hashes against the current files, you should use `operations/check` instead of `operations/hashsum`. Not me confusing the two, never.

Returns:

- `hashsum` — array of strings of the hashes
- `hashType` — type of hash used

Example:

$ rclone rc --loopback operations/hashsum fs=bin hashType=MD5 download=true base64=true { "hashType": "md5", "hashsum": [ "WTSVLpuiXyJO_kGzJerRLg== backend-versions.sh", "v1b_OlWCJO9LtNq3EIKkNQ== bisect-go-rclone.sh", "VHbmHzHh4taXzgag8BAIKQ== bisect-rclone.sh", ] }


See the `hashsum` command for more info on the above. 👑

Authentication is required for this call. 🔐

---

### 📋 operations/list — lists the given remote and path in JSON format

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`
- `opt` — a dictionary of options to control the listing (optional)
  - `recurse` — If set recurse directories
  - `noModTime` — If set return modification time
  - `showEncrypted` — If set show decrypted names
  - `showOrigIDs` — If set show the IDs for each item if known
  - `showHash` — If set return a dictionary of hashes
  - `noMimeType` — If set don't show mime types
  - `dirsOnly` — If set only show directories
  - `filesOnly` — If set only show files
  - `metadata` — If set return metadata of objects also
  - `hashTypes` — array of strings of hash types to show if `showHash` set

Returns:

- `list`
  - This is an array of objects as described in the `lsjson` command

See the `lsjson` command for more info on the above and examples. 🌸

Authentication is required for this call. 🔐

---

### 📁 operations/mkdir — makes a destination directory or container

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`

See the `mkdir` command for more info on the above. 💖

Authentication is required for this call. 🔐

---

### 🚚 operations/movefile — moves a file from source remote to destination remote

Params it takes:

- `srcFs` — a remote name string e.g. `"drive:"` for the source, `"/"` for local filesystem
- `srcRemote` — a path within that remote e.g. `"file.txt"` for the source
- `dstFs` — a remote name string e.g. `"drive2:"` for the destination, `"/"` for local filesystem
- `dstRemote` — a path within that remote e.g. `"file2.txt"` for the destination

Authentication is required for this call. 🔐

---

### 🔗 operations/publiclink — creates or retrieves a public link to the given file or folder

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`
- `unlink` — boolean - if set removes the link rather than adding it (optional)
- `expire` — string - the expiry time of the link e.g. `"1d"` (optional)

Returns:

- `url` — URL of the resource

See the `link` command for more info on the above. ✨

Authentication is required for this call. 🔐

---

### 🗑️ operations/purge — removes a directory or container and all of its contents

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`

See the `purge` command for more info on the above. <red>It removes EVERYTHING in there, bestie.</red> 💀

Authentication is required for this call. 🔐

---

### 📂 operations/rmdir — removes an empty directory or container

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`

See the `rmdir` command for more info on the above. Note it's <hotpink>empty</hotpink> — it's not out here deleting your whole stash. 🙈

Authentication is required for this call. 🔐

---

### 🧹 operations/rmdirs — removes all the empty directories in the path

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`
- `leaveRoot` — boolean, set to true not to delete the root

See the `rmdirs` command for more info on the above. 🧚

Authentication is required for this call. 🔐

---

### 🏷️ operations/settier — changes storage tier or class on all files in the path

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`

See the `settier` command for more info on the above. 👑

Authentication is required for this call. 🔐

---

### 🏷️ operations/settierfile — changes storage tier or class on the single file pointed to

Params it takes:

- `fs` — a remote name string e.g. `"drive:"`
- `remote` — a path within that remote e.g. `"dir"`

See the `settierfile` command for more info on the above. ⭐

Authentication is required for this call. 🔐

---

### 📏 operations/size — counts the number of bytes and files in remote

Params it takes:

- `fs` — a remote name string e.g. `"drive:path/to/dir"`

Returns:

- `count` — number of files

- <green>**`bytes`**</green> — how many bytes are chillin' in those files

Peep the `size` command for the full tea on all of the above. 🔍

> Authentication is required for this call. 🔐

---

### 🫶 `operations/stat`: Give information about the supplied file or directory

Okay so this one takes these parameters:

- <pink>**`fs`**</pink> — a remote name string, eg `"drive:"`
- <pink>**`remote`**</pink> — a path within that remote, eg `"dir"`
- <pink>**`opt`**</pink> — a dictionary of options to control the listing (optional)
  - see `operations/list` for the options

And the result is:

- <mint>**`item`**</mint> — an object as described in the `lsjson` command. Will be `null` if not found.

Lowkey important: if you're only interested in files, then it is **much** more efficient to set the `filesOnly` flag in the options. Like, do that. 🦋

See the `lsjson` command for more info on the above and examples.

> Authentication is required for this call. 🔐

---

### 🌸 `operations/uploadfile`: Upload file using multiform/form-data

This takes the following parameters:

- <pink>**`fs`**</pink> — a remote name string e.g. `"drive:"`
- <pink>**`remote`**</pink> — a path within that remote e.g. `"dir"`
- each part in body represents a file to be uploaded

See the `uploadfile` command for more information on the above.

> Authentication is required for this call. 🔐

---

### ✨ `options/blocks`: List all the option blocks

Returns:

- <mint>**`options`**</mint> — a list of the options block names

---

### 💖 `options/get`: Get all the global options

Returns an object where keys are option block names and values are an object with the current option values in. Slay. 👑

Parameters:

- <pink>**`blocks`**</pink>: optional string of comma separated blocks to include
  - all are included if this is missing or `""`

Anyway bestie, note that these are the **global** options which are unaffected by use of the `_config` and `_filter` parameters. If you wish to read the parameters set in `_config` then use `options/config` and for `_filter` use `options/filter`. Don't mix 'em up fr fr. 🙈

This shows the internal names of the option within rclone which should map to the external options very easily with a few exceptions. iykyk.

---

### 🎀 `options/info`: Get info about all the global options

Returns an object where keys are option block names and values are an array of objects with info about each options. 📚

Parameters:

- <pink>**`blocks`**</pink>: optional string of comma separated blocks to include
  - all are included if this is missing or `""`

These objects are in the same format as returned by `"config/providers"`. They are described in the option blocks section.

---

### 🦋 `options/local`: Get the currently active config for this call

Returns an object with the keys `"config"` and `"filter"`. The `"config"` key contains the local config and the `"filter"` key contains the local filters. 💅

Note that these are the **local** options specific to this rc call. If `_config` was not supplied then they will be the global options. Likewise with `"_filter"`.

This call is mostly useful for seeing if `_config` and `_filter` passing is working. Vibe check for your rc call basically. ⭐

This shows the internal names of the option within rclone which should map to the external options very easily with a few exceptions.

---

### 🔥 `options/set`: Set an option

Parameters:

- option block name containing an object with
  - `key: value`

Repeated as often as required. 🔁

Only supply the options you wish to change. If an option is unknown it will be **silently ignored**. Not all options will have an effect when changed like this.

For example:

This sets `DEBUG` level logs (`-vv`) (these can be set by number or string):

rclone rc options/set --json '{"main": {"LogLevel": "DEBUG"}}' rclone rc options/set --json '{"main": {"LogLevel": 8}}'


And this sets `INFO` level logs (`-v`):

rclone rc options/set --json '{"main": {"LogLevel": "INFO"}}'


And this sets `NOTICE` level logs (normal without `-v`):

rclone rc options/set --json '{"main": {"LogLevel": "NOTICE"}}'


---

### 💜 `pluginsctl/addPlugin`: Add a plugin using url

Used for adding a plugin to the webgui. 🌐

This takes the following parameters:

- <pink>**`url`**</pink> — http url of the github repo where the plugin is hosted (`http://github.com/rclone/rclone-webui-react`).

Example:

rclone rc pluginsctl/addPlugin


> Authentication is required for this call. 🔐

---

### 🧚 `pluginsctl/getPluginsForType`: Get plugins with type criteria

This shows all possible plugins by a mime type.

This takes the following parameters:

- <pink>**`type`**</pink> — supported mime type by a loaded plugin e.g. (`video/mp4`, `audio/mp3`).
- <pink>**`pluginType`**</pink> — filter plugins based on their type e.g. (`DASHBOARD`, `FILE_HANDLER`, `TERMINAL`).

Returns:

- <mint>**`loadedPlugins`**</mint> — list of current production plugins.
- <mint>**`testPlugins`**</mint> — list of temporarily loaded development plugins, usually running on a different server.

Example:

rclone rc pluginsctl/getPluginsForType type=video/mp4


> Authentication is required for this call. 🔐

---

### 🌈 `pluginsctl/listPlugins`: Get the list of currently loaded plugins

This allows you to get the currently enabled plugins and their details. Obsessed. 🫶

This takes no parameters and returns:

- <mint>**`loadedPlugins`**</mint> — list of current production plugins.
- <mint>**`testPlugins`**</mint> — list of temporarily loaded development plugins, usually running on a different server.

E.g.

rclone rc pluginsctl/listPlugins


> Authentication is required for this call. 🔐

---

### 🌸 `pluginsctl/listTestPlugins`: Show currently loaded test plugins

Allows listing of test plugins with the `rclone.test` set to true in `package.json` of the plugin.

This takes no parameters and returns:

- <mint>**`loadedTestPlugins`**</mint> — list of currently available test plugins.

E.g.

rclone rc pluginsctl/listTestPlugins


> Authentication is required for this call. 🔐

---

### 💅 `pluginsctl/removePlugin`: Remove a loaded plugin

This allows you to remove a plugin using it's name.

This takes parameters:

- <pink>**`name`**</pink> — name of the plugin in the format `author/plugin_name`.

E.g.

rclone rc pluginsctl/removePlugin name=rclone/video-plugin


> Authentication is required for this call. 🔐

---

### ⭐ `pluginsctl/removeTestPlugin`: Remove a test plugin

This allows you to remove a plugin using it's name.

This takes the following parameters:

- <pink>**`name`**</pink> — name of the plugin in the format `author/plugin_name`.

Example:

rclone rc pluginsctl/removeTestPlugin name=rclone/rclone-webui-react


> Authentication is required for this call. 🔐

---

### 💀 `rc/error`: This returns an error

This returns an error with the input as part of its error string. Useful for testing error handling. Not me triggering an error on purpose 😭 it's for science bestie.

---

### 👑 `rc/list`: List all the registered remote control commands

This lists all the registered remote control commands as a JSON map in the `commands` response.

---

### 🍓 `rc/noop`: Echo the input to the output parameters

This echoes the input parameters to the output parameters for testing purposes. It can be used to check that rclone is still alive and to check that parameter passing is working properly. Little heartbeat check for your rc. 💓

---

### ✨ `rc/noopauth`: Echo the input to the output parameters requiring auth

This echoes the input parameters to the output parameters for testing purposes. It can be used to check that rclone is still alive and to check that parameter passing is working properly.

> Authentication is required for this call. 🔐

---

### 🔄 `sync/bisync`: Perform bidirectional synchronization between two paths.

This takes the following parameters:

- <pink>**`path1`**</pink> — a remote directory string e.g. `drive:path1`
- <pink>**`path2`**</pink> — a remote directory string e.g. `drive:path2`
- <pink>**`dryRun`**</pink> — dry-run mode
- <pink>**`resync`**</pink> — performs the resync run
- <pink>**`checkAccess`**</pink> — abort if `RCLONE_TEST` files are not found on both filesystems
- <pink>**`checkFilename`**</pink> — file name for `checkAccess` (default: `RCLONE_TEST`)
- <pink>**`maxDelete`**</pink> — abort sync if percentage of deleted files is above this threshold (default: `50`)
- <pink>**`force`**</pink> — Bypass `maxDelete` safety check and run the sync
- <pink>**`checkSync`**</pink> — `true` by default, `false` disables comparison of final listings, only will skip sync, only compare listings from the last run
- <pink>**`createEmptySrcDirs`**</pink> — Sync creation and deletion of empty directories. (Not compatible with `--remove-empty-dirs`)
- <pink>**`removeEmptyDirs`**</pink> — remove empty directories at the final cleanup step
- <pink>**`filtersFile`**</pink> — read filtering patterns from a file
- <pink>**`ignoreListingChecksum`**</pink> — Do not use checksums for listings
- <pink>**`resilient`**</pink> — Allow future runs to retry after certain less-serious errors, instead of requiring resync. **Use at your own risk!**
- <pink>**`workdir`**</pink> — server directory for history files (default: `~/.cache/rclone/bisync`)
- <pink>**`backupdir1`**</pink> — `--backup-dir` for Path1. Must be a non-overlapping path on the same remote.
- <pink>**`backupdir2`**</pink> — `--backup-dir` for Path2. Must be a non-overlapping path on the same remote.
- <pink>**`noCleanup`**</pink> — retain working files

See `bisync` command help and full `bisync` description for more information.

> Authentication is required for this call. 🔐

---

### 🦋 `sync/copy`: copy a directory from source remote to destination remote

This takes the following parameters:

- <pink>**`srcFs`**</pink> — a remote name string e.g. `"drive:src"` for the source
- <pink>**`dstFs`**</pink> — a remote name string e.g. `"drive:dst"` for the destination
- <pink>**`createEmptySrcDirs`**</pink> — create empty src directories on destination if set

See the `copy` command for more information on the above.

> Authentication is required for this call. 🔐

---

### 🎀 `sync/move`: move a directory from source remote to destination remote

This takes the following parameters:

- <pink>**`srcFs`**</pink> — a remote name string e.g. `"drive:src"` for the source
- <pink>**`dstFs`**</pink> — a remote name string e.g. `"drive:dst"` for the destination
- <pink>**`createEmptySrcDirs`**</pink> — create empty src directories on destination if set
- <pink>**`deleteEmptySrcDirs`**</pink> — delete empty src directories if set

See the `move` command for more information on the above.

> Authentication is required for this call. 🔐

---

### 🌈 `sync/sync`: sync a directory from source remote to destination remote

This takes the following parameters:

- <pink>**`srcFs`**</pink> — a remote name string e.g. `"drive:src"` for the source
- <pink>**`dstFs`**</pink> — a remote name string e.g. `"drive:dst"` for the destination
- <pink>**`createEmptySrcDirs`**</pink> — create empty src directories on destination if set

See the `sync` command for more information on the above.

> Authentication is required for this call. 🔐

---

### 💜 `vfs/forget`: Forget files or directories in the directory cache.

This forgets the paths in the directory cache causing them to be re-read from the remote when needed. Casual memory wipe, main character energy. 🧠✨

If no paths are passed in then it will forget **all** the paths in the directory cache.

rclone rc vfs/forget


Otherwise pass files or dirs in as `file=path` or `dir=path`. Any parameter key starting with `file` will forget that file and any starting with `dir` will forget that dir, e.g.

rclone rc vfs/forget file=hello file2=goodbye dir=home/junk


This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter **must** be supplied. No cap. 🫡

## <purple>vfs/list</purple>: List active VFSes 💅

okay so this one is genuinely the simplest thing ever — it lists the active VFSes. that's the whole job. slay.

It returns a list under the key `"vfses"`, and the values in that list are the VFS names you could pass to the other VFS commands in the `"fs"` parameter. that's it bestie. go off.

---

## <purple>vfs/poll-interval</purple>: Get the status or update the value of the poll-interval option ✨

Give it no parameters at all and it just tells you the current status of the `poll-interval` setting. casual.

But when you set the `interval=duration` parameter, the `poll-interval` value gets updated **and** the polling function gets notified. and if you set `interval=0`? that disables poll-interval entirely. no cap.

rclone rc vfs/poll-interval interval=5m


There's also the `timeout=duration` parameter, which lets you specify a time to wait for the current poll function to apply the new value. If `timeout` is less than or equal to `0`, which is the default, it waits indefinitely. forever. patient king behavior.

The new `poll-interval` value will only actually be active when the `timeout` is not reached. that part matters, don't skip it.

> 🫶 heads up: if `poll-interval` is updated or disabled *temporarily*, some changes might not get picked up by the polling function, depending on the used remote. so like. don't come for it.

This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter **must** be supplied. rules are rules.

---

## <purple>vfs/queue</purple>: Queue info for a VFS 🎀

This returns info about the upload queue for the selected VFS. it's giving backstage pass.

This is only useful if `--vfs-cache-mode > off`. If you call it when the `--vfs-cache-mode` is `off`, it will return an empty result. nothing. void. 💀

{ "queued": // an array of files queued for upload [ { "name": "file", // string: name (full path) of the file, "id": 123, // integer: id of this item in the queue, "size": 79, // integer: size of the file in bytes "expiry": 1.5 // float: time until file is eligible for transfer, lowest goes first "tries": 1, // integer: number of times we have tried to upload "delay": 5.0, // float: seconds between upload attempts "uploading": false, // boolean: true if item is being uploaded }, ], }


So about that expiry time: it's the time until the file is eligible for being uploaded, in floating point seconds. and yes, this may go **negative**. that's not a glitch, that's just life.

Since rclone only transfers `--transfers` files at once, only the lowest `--transfers` expiry times will have `uploading` as `true`. which means you might see files with negative expiry times where `uploading` is `false`. so if you're staring at that like 👀 — that's why.

This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter must be supplied.

---

## <purple>vfs/queue-set-expiry</purple>: Set the expiry time for an item queued for upload ⏰

Use this to adjust the expiry time for an item sitting in the upload queue. You will need to read the `id` of the item using `vfs/queue` before using this call — so go get that receipt first.

Then you can set `expiry` to a floating point number of seconds from now, when the item becomes eligible for upload.

- want it uploaded ASAP? set it to a large **negative** number (eg `-1000000000`). bestie is *hungry*.
- want the upload delayed for a long time? set it to a large **positive** number. nap era.

> ⚠️ Setting the expiry of an item which has already started uploading will have **no effect** — the item will carry on being uploaded. no takebacks.

This will return an error if called with `--vfs-cache-mode off` or if the `id` passed is not found.

This takes the following parameters

- **`fs`** — select the VFS in use (optional)
- **`id`** — a numeric ID as returned from `vfs/queue`
- **`expiry`** — a new expiry time as floating point seconds
- **`relative`** — if set, `expiry` is to be treated as relative to the current expiry (optional, boolean)

This returns an empty result on success, or an error. 🤷

This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter must be supplied.

---

## <purple>vfs/refresh</purple>: Refresh the directory cache 🌈

This reads the directories for the specified paths and freshens the directory cache. glow up for your cache.

If no paths are passed in then it will refresh the root directory.

rclone rc vfs/refresh


Otherwise, pass directories in as `dir=path`. Any parameter key starting with `dir` will refresh that directory, e.g.

rclone rc vfs/refresh dir=home/junk dir2=data/misc


If the parameter `recursive=true` is given the whole directory tree will get refreshed. and this refresh will use `--fast-list` if enabled. efficiency queeeen.

This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter must be supplied.

---

## <purple>vfs/stats</purple>: Stats for a VFS 📊

This returns stats for the selected VFS. numbers. we love numbers.

{ // Status of the disk cache - only present if --vfs-cache-mode > off "diskCache": { "bytesUsed": 0, "erroredFiles": 0, "files": 0, "hashType": 1, "outOfSpace": false, "path": "/home/user/.cache/rclone/vfs/local/mnt/a", "pathMeta": "/home/user/.cache/rclone/vfsMeta/local/mnt/a", "uploadsInProgress": 0, "uploadsQueued": 0 }, "fs": "/mnt/a", "inUse": 1, // Status of the in memory metadata cache "metadataCache": { "dirs": 1, "files": 0 }, // Options as returned by options/get "opt": { "CacheMaxAge": 3600000000000, // ... "WriteWait": 1000000000 } }


This command takes an `"fs"` parameter. If this parameter is not supplied and if there is only one VFS in use then that VFS will be used. If there is more than one VFS in use then the `"fs"` parameter must be supplied.

---

## <pink>Accessing the remote control via HTTP</pink> 🌐

Rclone implements a simple HTTP based protocol. cute and functional.

Each endpoint takes an JSON object and returns a JSON object or an error. The JSON objects are essentially a map of string names to values.

**All calls must made using POST.** okay? POST. not GET. don't test me.

The input objects can be supplied using URL parameters, POST parameters or by supplying `"Content-Type: application/json"` and a JSON blob in the body. There are examples of these below using `curl`.

The response will be a JSON blob in the body of the response. This is formatted to be reasonably human-readable. thank u for the accessibility king 👑

---

## <hotpink>Error returns</hotpink> 😭

If an error occurs then there will be an HTTP error status (e.g. `500`) and the body of the response will contain a JSON encoded error object, e.g.

{ "error": "Expecting string value for key "remote" (was float64)", "input": { "fs": "/tmp", "remote": 3 }, "status": 400 "path": "operations/rmdir", }


The keys in the error response are

- `error` — error string
- `input` — the input parameters to the call
- `status` — the HTTP status code
- `path` — the path of the call

---

## <lavender>CORS</lavender> 🦋

The sever implements basic CORS support and allows all origins for that. The response to a preflight `OPTIONS` request will echo the requested `"Access-Control-Request-Headers"` back. polite behavior fr.

---

## <mint>Using POST with URL parameters only</mint> 🍓

curl -X POST 'http://localhost:5572/rc/noop?potato=1&sausage=2'


Response

{ "potato": "1", "sausage": "2" }


Here is what an error response looks like:

curl -X POST 'http://localhost:5572/rc/error?potato=1&sausage=2'

{ "error": "arbitrary error on input map[potato:1 sausage:2]", "input": { "potato": "1", "sausage": "2" } }


Note that `curl` doesn't return errors to the shell unless you use the `-f` option

$ curl -f -X POST 'http://localhost:5572/rc/error?potato=1&sausage=2' curl: (22) The requested URL returned error: 400 Bad Request $ echo $? 22


---

## <yellow>Using POST with a form</yellow> 📝

curl --data "potato=1" --data "sausage=2" http://localhost:5572/rc/noop


Response

{ "potato": "1", "sausage": "2" }


Note that you can combine these with URL parameters too with the POST parameters taking precedence. POST wins the argument, sorry URL. 💅

curl --data "potato=1" --data "sausage=2" "http://localhost:5572/rc/noop?rutabaga=3&sausage=4"


Response

{ "potato": "1", "rutabaga": "3", "sausage": "4" }


---

## <peach>Using POST with a JSON blob</peach> 🌸

curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' http://localhost:5572/rc/noop


response

{ "password": "xyz", "username": "xyz" }


This can be combined with URL parameters too if required. The JSON blob takes precedence.

curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' 'http://localhost:5572/rc/noop?rutabaga=3&potato=4'

{ "potato": 2, "rutabaga": "3", "sausage": 1 }


---

## <cyan>Debugging rclone with pprof</cyan> 🔥

If you use the `--rc` flag this will also enable the use of the go profiling tools on the same port. two birds, one port, iconic.

To use these, first install `go`. yes you need go. go get go.

---

## <cyan>Debugging memory use</cyan> 🧚

To profile rclone's memory use you can run:

go tool pprof -web http://localhost:5572/debug/pprof/heap


This should open a page in your browser showing what is using what memory. detective mode activated 🔍.

You can also use the `-text` flag to produce a textual summary

$ go tool pprof -text http://localhost:5572/debug/pprof/heap Showing nodes accounting for 1537.03kB, 100% of 1537.03kB total flat flat% sum% cum cum% 1024.03kB 66.62% 66.62% 1024.03kB 66.62% github.com/rclone/rclone/vendor/golang.org/x/net/http2/hpack.addDecoderNode 513kB 33.38% 100% 513kB 33.38% net/http.newBufioWriterSize 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/cmd/all.init 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/cmd/serve.init 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/cmd/serve/restic.init 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/vendor/golang.org/x/net/http2.init 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/vendor/golang.org/x/net/http2/hpack.init 0 0% 100% 1024.03kB 66.62% github.com/rclone/rclone/vendor/golang.org/x/net/http2/hpack.init.0 0 0% 100% 1024.03kB 66.62% main.init 0 0% 100% 513kB 33.38% net/http.(*conn).readRequest 0 0% 100% 513kB 33.38% net/http.(*conn).serve 0 0% 100% 1024.03kB 66.62% runtime.main


### 💀 Debugging go routine leaks

Okay bestie, listen — memory leaks are like, <hotpink>almost always</hotpink> caused by go routine leaks, which keep memory alive that honestly should've been garbage collected ages ago. It's giving clingy ex energy honestly 😭

Peep every single active go routine with this:

curl http://localhost:5572/debug/pprof/goroutine?debug=1


Or like, just go to `http://localhost:5572/debug/pprof/goroutine?debug=1` in your browser 🌈

### ✨ Other profiles to look at

You can see a lil summary of all the profiles available at `http://localhost:5572/debug/pprof/` 👑

Here's how to use some of them:

- **Memory**: `go tool pprof http://localhost:5572/debug/pprof/heap`
- **Go routines**: `curl http://localhost:5572/debug/pprof/goroutine?debug=1`
- **30-second CPU profile**: `go tool pprof http://localhost:5572/debug/pprof/profile`
- **5-second execution trace**: `wget http://localhost:5572/debug/pprof/trace?seconds=5`
- **Goroutine blocking profile**
  - Enable first with: `rclone rc debug/set-block-profile-rate rate=1` (docs)
  - `go tool pprof http://localhost:5572/debug/pprof/block`
- **Contended mutexes:**
  - Enable first with: `rclone rc debug/set-mutex-profile-fraction rate=1` (docs)
  - `go tool pprof http://localhost:5572/debug/pprof/mutex`

See the `net/http/pprof` docs for more info on how to use the profiling, and for a general overview go check out the Go team's blog post on profiling go programs 📚

> The profiling hook is <green>zero overhead</green> unless it is used. Periodt. 🎀

---

# 🌈 Overview of cloud storage systems

So every single cloud storage system is a lil different, right? rclone tries its absolute best to give you one unified interface across all of them, but ngl, some of those underlying differences *do* show through 🙈

## 👑 Features

Here's the tea on all the major features of each cloud storage system, bestie. Columns are: **Name**, **Hash**, **ModTime**, **Case Insensitive**, **Duplicate Files**, **MIME Type**, **Metadata**.

- **`1Fichier`** — Hash: Whirlpool; ModTime: `-`; Case Insensitive: No; Duplicate Files: Yes; MIME Type: R; Metadata: `-`
- **`Akamai Netstorage`** — Hash: MD5, SHA256; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`Amazon S3 (or S3 compatible)`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: RWU
- **`Backblaze B2`** — Hash: SHA1; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Box`** — Hash: SHA1; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Citrix ShareFile`** — Hash: MD5; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Cloudinary`** — Hash: MD5; ModTime: R; Case Insensitive: No; Duplicate Files: Yes; MIME Type: `-`; Metadata: `-`
- **`Dropbox`** — Hash: DBHASH ¹; ModTime: R; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Enterprise File Fabric`** — Hash: `-`; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Files.com`** — Hash: MD5, CRC32; ModTime: DR/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`FTP`** — Hash: `-`; ModTime: R/W ¹⁰; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Gofile`** — Hash: MD5; ModTime: DR/W; Case Insensitive: No; Duplicate Files: Yes; MIME Type: R; Metadata: `-`
- **`Google Cloud Storage`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Google Drive`** — Hash: MD5, SHA1, SHA256; ModTime: DR/W; Case Insensitive: No; Duplicate Files: Yes; MIME Type: R/W; Metadata: DRWU
- **`Google Photos`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: Yes; MIME Type: R; Metadata: `-`
- **`HDFS`** — Hash: `-`; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`HiDrive`** — Hash: HiDrive ¹²; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`HTTP`** — Hash: `-`; ModTime: R; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`iCloud Drive`** — Hash: `-`; ModTime: R; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Internet Archive`** — Hash: MD5, SHA1, CRC32; ModTime: R/W ¹¹; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: RWU
- **`Jottacloud`** — Hash: MD5; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R; Metadata: RW
- **`Koofr`** — Hash: MD5; ModTime: `-`; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Linkbox`** — Hash: `-`; ModTime: R; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Mail.ru Cloud`** — Hash: Mailru ⁶; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Mega`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: Yes; MIME Type: `-`; Metadata: `-`
- **`Memory`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Microsoft Azure Blob Storage`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Microsoft Azure Files Storage`** — Hash: MD5; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Microsoft OneDrive`** — Hash: QuickXorHash ⁵; ModTime: DR/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R; Metadata: DRW
- **`OpenDrive`** — Hash: MD5; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: Partial ⁸; MIME Type: `-`; Metadata: `-`
- **`OpenStack Swift`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Oracle Object Storage`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`pCloud`** — Hash: MD5, SHA1 ⁷; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: W; Metadata: `-`
- **`PikPak`** — Hash: MD5; ModTime: R; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`Pixeldrain`** — Hash: SHA256; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: RW
- **`premiumize.me`** — Hash: `-`; ModTime: `-`; Case Insensitive: Yes; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`put.io`** — Hash: CRC-32; ModTime: R/W; Case Insensitive: No; Duplicate Files: Yes; MIME Type: R; Metadata: `-`
- **`Proton Drive`** — Hash: SHA1; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`QingStor`** — Hash: MD5; ModTime: `-` ⁹; Case Insensitive: No; Duplicate Files: No; MIME Type: R/W; Metadata: `-`
- **`Quatrix by Maytech`** — Hash: `-`; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Seafile`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`SFTP`** — Hash: MD5, SHA1 ²; ModTime: DR/W; Case Insensitive: Depends; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Sia`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`SMB`** — Hash: `-`; ModTime: R/W; Case Insensitive: Yes; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`SugarSync`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Storj`** — Hash: `-`; ModTime: R; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Uloz.to`** — Hash: MD5, SHA256 ¹³; ModTime: `-`; Case Insensitive: No; Duplicate Files: Yes; MIME Type: `-`; Metadata: `-`
- **`Uptobox`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: Yes; MIME Type: `-`; Metadata: `-`
- **`WebDAV`** — Hash: MD5, SHA1 ³; ModTime: R ⁴; Case Insensitive: Depends; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`Yandex Disk`** — Hash: MD5; ModTime: R/W; Case Insensitive: No; Duplicate Files: No; MIME Type: R; Metadata: `-`
- **`Zoho WorkDrive`** — Hash: `-`; ModTime: `-`; Case Insensitive: No; Duplicate Files: No; MIME Type: `-`; Metadata: `-`
- **`The local filesystem`** — Hash: All; ModTime: DR/W; Case Insensitive: Depends; Duplicate Files: No; MIME Type: `-`; Metadata: DRWU

¹ Dropbox supports its own custom hash. This is an SHA256 sum of all the 4 MiB block SHA256s. 💅

² SFTP supports checksums if the same login has shell access and `md5sum` or `sha1sum` as well as `echo` are in the remote's `PATH`.

³ WebDAV supports hashes when used with Fastmail Files, Owncloud and Nextcloud only.

⁴ WebDAV supports modtimes when used with Fastmail Files, Owncloud and Nextcloud only.

⁵ QuickXorHash is Microsoft's own hash.

⁶ Mail.ru uses its own modified SHA1 hash

⁷ pCloud only supports SHA1 (not MD5) in its EU region

⁸ Opendrive does not support creation of duplicate files using their web client interface or other stock clients, but the underlying storage platform has been determined to allow duplicate files, and it is possible to create them with rclone. It may be that this is a mistake or an unsupported feature. 🙈

⁹ QingStor does not support `SetModTime` for objects bigger than 5 GiB.

¹⁰ FTP supports modtimes for the major FTP servers, and also others if they advertised required protocol extensions. See this for more details.

¹¹ Internet Archive requires option `wait_archive` to be set to a non-zero value for full modtime support.

¹² HiDrive supports its own custom hash. It combines SHA1 sums for each 4 KiB block hierarchically to a single top-level sum.

¹³ Uloz.to provides server-calculated MD5 hash upon file upload. MD5 and SHA256 hashes are client-calculated and stored as metadata fields.

## 🦋 Hash

So the cloud storage system supports all these various hash types on the objects, right? These hashes get used when you're transferring data as an integrity check ✨ and you can specifically use them with the `--checksum` flag in syncs and in the `check` command.

And here's the thing — to actually verify checksums when you're transferring between cloud storage systems, those systems **must** support a common hash type. No shared hash, no check, bestie. 💀

## 🌸 ModTime

Almost every single cloud storage system stores *some* sort of timestamp on objects, but ngl several of them store something that is absolutely not appropriate to use for syncing 😭 Like, some backends will only write a timestamp that represents the time of the upload. Rude.

To be relevant for syncing, it should be able to store the **modification time of the source object**. If it can't do that, rclone will only check the file size by default, though you *can* configure it to check the file hash (with the `--checksum` flag). 🌈

And ideally? It should also be possible to change the timestamp of an existing file without having to re-upload the whole thing. Iconic behaviour, honestly 👑

- **`-`** — ModTimes not supported — times you see are probably the upload time
- **`R`** — ModTimes supported on files but can't be changed without re-upload
- **`R/W`** — Read and Write ModTimes fully supported on files
- **`DR`** — ModTimes supported on files and directories but can't be changed without re-upload
- **`DR/W`** — Read and Write ModTimes fully supported on files and directories

---

If a storage system has **`-`** in the ModTime column, bestie, that means the modification time you read off an object is *not* the modtime of the file when it was uploaded. It's most likely the time the file got uploaded, or possibly something else entirely (like the time the picture was taken in Google Photos). 🙈

<pink>Storage systems with **`R`** (read-only) in the ModTime column</pink> → it keeps modification times on objects and updates them when you upload objects, but it does **not** support changing *only* the modification time (the `SetModTime` operation) without re-uploading — possibly not even without deleting the existing file first. Some operations in rclone, like the `copy` and `sync` commands, will automatically check for `SetModTime` support and re-upload if necessary to keep the modification times in sync. Other commands just will not work without `SetModTime` support. For example, the `touch` command on an existing file will fail, and changes to modification time only on a file in a mount will be silently ignored. 💀

<purple>Storage systems with **`R/W`** (read/write) in the ModTime column</purple> → they *do* support modtime-only operations. Obsessed.

<purple>Storage systems with **`D`** in the ModTime column</purple> → means that all those symbols apply to **directories** as well as files.

## 🌈 Case Insensitive 🌈

So if a cloud storage system is case sensitive, it's possible to have two files that differ *only* in case, like `file.txt` and `FILE.txt`. And if a cloud storage system is case insensitive, that is just not a thing that can happen. 💅

This can cause problems when you're syncing between a case insensitive system and a case sensitive system. The symptom is giving: no matter how many times you run the sync, it never completes fully. 😭

The local filesystem and SFTP may or may not be case sensitive depending on the OS:

- Windows — usually case insensitive, though case is preserved
- OSX — usually case insensitive, though it is possible to format case sensitive
- Linux — usually case sensitive, but there are case insensitive file systems (e.g. FAT formatted USB keys)

Most of the time this doesn't cause any problems, because people tend to avoid files whose name differs only by case even on case sensitive systems. 🤷‍♀️

## 🫶 Duplicate files 🫶

If a cloud storage system allows duplicate files, then it can have two objects with the same name.

This confuses rclone **greatly** when syncing — use the `rclone dedupe` command to rename or remove duplicates. Iconic little fix, no cap.

## ✨ Restricted filenames ✨

Some cloud storage systems might have restrictions on the characters that are usable in file or directory names. When rclone detects such a name during a file upload, it will transparently replace the restricted characters with similar looking Unicode characters. To handle the different sets of restricted characters for different backends, rclone uses something it calls **encoding**. 🎀

This process is designed to avoid ambiguous file names as much as possible and allow you to move files between many cloud storage systems transparently. Slay.

The name shown by rclone to the user or during log output will only contain a minimal set of replaced characters to ensure correct formatting — and not necessarily the actual name used on the cloud storage.

This transformation is **reversed** when downloading a file or parsing rclone arguments. For example, when uploading a file named `my file?.txt` to Onedrive, it will be displayed as `my file?.txt` on the console, but stored as `my file？.txt` to Onedrive (the `?` gets replaced by the similar looking `？` character, the so-called "fullwidth question mark"). The reverse transformation allows you to read a file `unusual/name.txt` from Google Drive, by passing the name `unusual／name.txt` on the command line (the `/` needs to be replaced by the similar looking `／` character). 🤯

## 🌸 Caveats 🌸

The filename encoding system works well in most cases, at least where file names are written in English or similar languages. You might not even notice it: it just works. 💖 In some cases it may lead to issues, though. E.g. when file names are written in Chinese, or Japanese, where it is always the Unicode fullwidth variants of the punctuation marks that are used.

On Windows, the characters `:`, `*` and `?` are examples of restricted characters. If these are used in filenames on a remote that supports it, Rclone will transparently convert them to their fullwidth Unicode variants `＊`, `？` and `：` when downloading to Windows, and back again when uploading. This way files with names that are not allowed on Windows can still be stored. 👑

However, if you have files on your Windows system originally with these *same* Unicode characters in their names, they will be included in the same conversion process. E.g. if you create a file in your Windows filesystem with name `Test：1.jpg`, where `：` is the Unicode fullwidth colon symbol, and use rclone to upload it to Google Drive, which supports regular `:` (halfwidth question mark), rclone will replace the fullwidth `:` with the halfwidth `:` and store the file as `Test:1.jpg` in Google Drive. Since both Windows and Google Drive allows the name `Test：1.jpg`, it would probably be better if rclone just kept the name as is in this case. 😭

With the opposite situation: if you have a file named `Test:1.jpg`, in your Google Drive, e.g. uploaded from a Linux system where `:` is valid in file names. Then later use rclone to copy this file to your Windows computer — you will notice that on your local disk it gets renamed to `Test：1.jpg`. The original filename is not legal on Windows, due to the `:`, and rclone therefore renames it to make the copy possible. That is all good. However, this can also lead to an issue: if you already had a *different* file named `Test：1.jpg` on Windows, and then use rclone to copy either way. Rclone will then treat the file originally named `Test:1.jpg` on Google Drive and the file originally named `Test：1.jpg` on Windows as the same file, and replace the contents from one with the other. 💀

> Its virtually impossible to handle all cases like these correctly in all situations, but by customizing the `encoding` option — changing the set of characters that rclone should convert — you should be able to create a configuration that works well for your specific situation. See also the example below.

(Windows was used as an example of a file system with many restricted characters, and Google drive a storage system with few.)

## 🧚 Default restricted characters 🧚

The table below shows the characters that are replaced by default.

When a replacement character is found in a filename, this character will be escaped with the `‛` character to avoid ambiguous file names. (e.g. a file named `␀.txt` would shown as `‛␀.txt`)

Each cloud storage backend can use a different set of characters, which will be specified in the documentation for each backend.

- `NUL` — `0x00` → `␀`
- `SOH` — `0x01` → `␁`
- `STX` — `0x02` → `␂`
- `ETX` — `0x03` → `␃`
- `EOT` — `0x04` → `␄`
- `ENQ` — `0x05` → `␅`
- `ACK` — `0x06` → `␆`
- `BEL` — `0x07` → `␇`
- `BS` — `0x08` → `␈`
- `HT` — `0x09` → `␉`
- `LF` — `0x0A` → `␊`
- `VT` — `0x0B` → `␋`
- `FF` — `0x0C` → `␌`
- `CR` — `0x0D` → `␍`
- `SO` — `0x0E` → `␎`
- `SI` — `0x0F` → `␏`
- `DLE` — `0x10` → `␐`
- `DC1` — `0x11` → `␑`
- `DC2` — `0x12` → `␒`
- `DC3` — `0x13` → `␓`
- `DC4` — `0x14` → `␔`
- `NAK` — `0x15` → `␕`
- `SYN` — `0x16` → `␖`
- `ETB` — `0x17` → `␗`
- `CAN` — `0x18` → `␘`
- `EM` — `0x19` → `␙`
- `SUB` — `0x1A` → `␚`
- `ESC` — `0x1B` → `␛`
- `FS` — `0x1C` → `␜`
- `GS` — `0x1D` → `␝`
- `RS` — `0x1E` → `␞`
- `US` — `0x1F` → `␟`
- `/` — `0x2F` → `／`
- `DEL` — `0x7F` → `␡`

The default encoding will **also** encode these file names, as they are problematic with many cloud storage systems:

- `.` → `．`
- `..` → `．．`

## 💜 Invalid UTF-8 bytes 💜

Some backends only support a sequence of well formed UTF-8 bytes as file or directory names.

In this case all invalid UTF-8 bytes will be replaced with a quoted representation of the byte value to allow uploading a file to such a backend. For example, the invalid byte `0xFE` will be encoded as `‛FE`. ✨

A common source of invalid UTF-8 bytes are local filesystems, that store names in a different encoding than UTF-8 or UTF-16, like `latin1`. See the local filenames section for details.

## 🎀 Encoding option 🎀

Most backends have an `encoding` option, specified as a flag `--backend-encoding` where *backend* is the name of the backend, or as a config parameter `encoding` (you'll need to select the Advanced config in `rclone config` to see it).

This will have default value which encodes and decodes characters in such a way as to preserve the maximum number of characters (see above). 👑

However this can be incorrect in some scenarios — for example if you have a Windows file system with Unicode fullwidth characters `＊`, `？` or `：`, that you want to remain as those characters on the remote rather than being translated to regular (halfwidth) `*`, `?` and `:`.

The `--backend-encoding` flags allow you to change that. You can disable the encoding completely with `--backend-encoding Raw` or set `encoding = Raw` in the config file.

Encoding takes a comma separated list of encodings. You can see the list of all possible values by passing an invalid value to this flag, e.g. `--local-encoding "help"`. The command `rclone help flags encoding` will show you the defaults for the backends. 🦋

---

- <pink>Asterisk</pink> — `*` becomes `＊`
- <pink>BackQuote</pink> — `` ` `` becomes `｀`
- <pink>BackSlash</pink> — `\` becomes `＼`
- <pink>Colon</pink> — `:` becomes `：`
- <pink>CrLf</pink> — `CR 0x0D, LF 0x0A` becomes `␍, ␊`
- <pink>Ctl</pink> — all the control characters, `0x00-0x1F`, become `␀␁␂␃␄␅␆␇␈␉␊␋␌␍␎␏␐␑␒␓␔␕␖␗␘␙␚␛␜␝␞␟`
- <pink>Del</pink> — `DEL 0x7F` becomes `␡`
- <pink>Dollar</pink> — `$` becomes `＄`
- <pink>Dot</pink> — `.` or `..` as the entire string becomes `．, ．．`
- <pink>DoubleQuote</pink> — `"` becomes `＂`
- <pink>Exclamation</pink> — `!` becomes `！`
- <pink>Hash</pink> — `#` becomes `＃`
- <pink>InvalidUtf8</pink> — an invalid UTF-8 character (e.g. latin1) becomes `�`
- <pink>LeftCrLfHtVt</pink> — `CR 0x0D, LF 0x0A, HT 0x09, VT 0x0B` sitting on the left of a string become `␍, ␊, ␉, ␋`
- <pink>LeftPeriod</pink> — `.` on the left of a string becomes `.`
- <pink>LeftSpace</pink> — `SPACE` on the left of a string becomes `␠`
- <pink>LeftTilde</pink> — `~` on the left of a string becomes `～`
- <pink>LtGt</pink> — `<`, `>` become `＜, ＞`
- <pink>None</pink> ¹ — `NUL 0x00` becomes `␀`
- <pink>Percent</pink> — `%` becomes `％`
- <pink>Pipe</pink> — `|` becomes `｜`
- <pink>Question</pink> — `?` becomes `？`
- <pink>RightCrLfHtVt</pink> — `CR 0x0D, LF 0x0A, HT 0x09, VT 0x0B` sitting on the right of a string become `␍, ␊, ␉, ␋`
- <pink>RightPeriod</pink> — `.` on the right of a string becomes `.`
- <pink>RightSpace</pink> — `SPACE` on the right of a string becomes `␠`
- <pink>Semicolon</pink> — `;` becomes `；`
- <pink>SingleQuote</pink> — `'` becomes `＇`
- <pink>Slash</pink> — `/` becomes `／`
- <pink>SquareBracket</pink> — `[`, `]` become `［, ］`

> ¹ ngl the encoding from `NUL 0x00` to `␀` is <hotpink>always implicit</hotpink> unless you're using `Raw`. It used to be documented wrong — as if it *disabled* encoding — and to keep backwards compatibility that behaviour has **not** been changed. So don't be out here thinking it turns encoding off, bestie. 💀

### 💻 Encoding example: FTP

Okay so real talk, let's take one specific example, because abstract tables are giving ✨ nothing ✨. The FTP backend's default encoding is literally this:

--ftp-encoding "Slash,Del,Ctl,RightSpace,Dot"


But plot twist 🌪️ — say your FTP server is running on Windows and it absolutely *cannot* have any of the invalid Windows characters in file names. Meanwhile you're backing up Linux servers to this FTP server, and those Linux file names 100% do have those characters in them. So you'd add the Windows set, which is:

Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot


...onto the ones that were already there, and you get:

Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot,Del,RightSpace


You can set this with the `--ftp-encoding` flag, or you can drop an encoding parameter into the config file. Either one, your call 🫶

### 🪟 Encoding example: Windows

Another example for you — picture a Windows system with a file named `Test：1.jpg`, where that `：` is the Unicode **fullwidth** colon symbol. When you use rclone to copy this over to a remote that supports `:`, the regular (halfwidth) colon, like Google Drive does, you will notice the file gets renamed to `Test:1.jpg`. Not a vibe, honestly.

To dodge that, you can change the set of characters rclone should convert for the local filesystem, using the command-line argument `--local-encoding`. Rclone's default behaviour on Windows corresponds to:

--local-encoding "Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot"


So if you want to actually use fullwidth characters `：`, `＊` and `？` in your filenames *without* rclone messing with them when uploading to a remote, then set the same as the default value but without `Colon,Question,Asterisk`:

--local-encoding "Slash,LtGt,DoubleQuote,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot"


Or, alternativley, you can just disable the conversion of any characters at all with `--local-encoding Raw`. Periodt. 🎀

Instead of using the command-line argument `--local-encoding`, you may also set it as the environment variable `RCLONE_LOCAL_ENCODING`, or configure a remote of type local in your config, and set the encoding option there. Three routes, one destination, slay.

> ⚠️ But here's the risk of doing this, and no I'm not being dramatic: if you have a filename with the regular (halfwidth) `:`, `*` and `?` in your cloud storage, and you try to download it to your Windows filesystem, it will **fail**. Those characters are not valid in filenames on Windows, and you've just told rclone *not* to work around this by converting them to valid fullwidth variants. So like… choose your fighter wisely. 😭

### 🌈 MIME Type

MIME types, also known as media types, classify types of documents using a simple text classification — think `text/html` or `application/pdf`. Cute, simple, iconic.

Some cloud storage systems support reading (R) the MIME type of objects, and some support writing (W) the MIME type of objects.

The MIME type can be important if you are serving files directly to HTTP from the storage system. 👑

If you are copying from a remote which supports reading (R) to a remote which supports writing (W), then rclone will preserve the MIME types. Otherwise they will be guessed from the extension, or the remote itself may assign the MIME type. Either way, it gets handled. 💅

### 🧚 Metadata

Backends may or may not support reading or writing metadata. They may support reading and writing **system metadata** (metadata intrinsic to that backend) and/or **user metadata** (general purpose metadata).

The levels of metadata support are:

- **`R`** — Read only System Metadata on files only
- **`RW`** — Read and write System Metadata on files only
- **`RWU`** — Read and write System Metadata and read and write User Metadata on files only
- **`DR`** — Read only System Metadata on files and directories
- **`DRW`** — Read and write System Metadata on files and directories
- **`DRWU`** — Read and write System Metadata and read and write User Metadata on files and directories

See the metadata docs for more info.

### ⭐ Optional Features

All rclone remotes support a base command set. Other features depend upon backend-specific capabilities. That's just how it is, bestie. 🦋

okay so this is the big <pink>vibe-check chart</pink> — every backend and which special moves it can pull off. ✨ Read it like a group chat roll call: <green>Yes</green> means she ate, <muted>No</muted> means bestie simply cannot, and the little numbers are footnotes you're gonna want to read, fr fr.

Columns, in order: Name, Purge, Copy, Move, DirMove, CleanUp, ListR, StreamUpload, MultithreadUpload, LinkSharing, About, EmptyDir.

- **1Fichier** — Purge: No, Copy: Yes, Move: Yes, DirMove: No, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: No, EmptyDir: Yes
- **Akamai Netstorage** — Purge: Yes, Copy: No, Move: No, DirMove: No, CleanUp: No, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Amazon S3 (or S3 compatible)** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: Yes, ListR: Yes, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: Yes, About: No, EmptyDir: No
- **Backblaze B2** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: Yes, ListR: Yes, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: Yes, About: No, EmptyDir: No
- **Box** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Citrix ShareFile** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Dropbox** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Cloudinary** — Purge: No, Copy: No, Move: No, DirMove: No, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **Enterprise File Fabric** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Files.com** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: No, EmptyDir: Yes
- **FTP** — Purge: No, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Gofile** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Google Cloud Storage** — Purge: Yes, Copy: Yes, Move: No, DirMove: No, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **Google Drive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Google Photos** — Purge: No, Copy: No, Move: No, DirMove: No, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **HDFS** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **HiDrive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **HTTP** — Purge: No, Copy: No, Move: No, DirMove: No, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **iCloud Drive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **ImageKit** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: No, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Internet Archive** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: Yes, ListR: Yes, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: No
- **Jottacloud** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: Yes, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Koofr** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Mail.ru Cloud** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Mega** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Memory** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: No, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **Microsoft Azure Blob Storage** — Purge: Yes, Copy: Yes, Move: No, DirMove: No, CleanUp: No, ListR: Yes, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: No, About: No, EmptyDir: No
- **Microsoft Azure Files Storage** — Purge: No, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: No, About: Yes, EmptyDir: Yes
- **Microsoft OneDrive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: Yes ⁵, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **OpenDrive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **OpenStack Swift** — Purge: Yes ¹, Copy: Yes, Move: No, DirMove: No, CleanUp: No, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: No
- **Oracle Object Storage** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: Yes, ListR: Yes, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: No, About: No, EmptyDir: No
- **pCloud** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **PikPak** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Pixeldrain** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **premiumize.me** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **put.io** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **Proton Drive** — Purge: Yes, Copy: No, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **QingStor** — Purge: No, Copy: Yes, Move: No, DirMove: No, CleanUp: Yes, ListR: Yes, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **Quatrix by Maytech** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **Seafile** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **SFTP** — Purge: No, Copy: Yes, Move: Yes, DirMove: Yes ⁴, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **Sia** — Purge: No, Copy: No, Move: No, DirMove: No, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **SMB** — Purge: No, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: No, About: No, EmptyDir: Yes
- **SugarSync** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: No, EmptyDir: Yes
- **Storj** — Purge: Yes ², Copy: Yes, Move: Yes, DirMove: No, CleanUp: No, ListR: Yes, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: No, EmptyDir: No
- **Uloz.to** — Purge: No, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: Yes
- **Uptobox** — Purge: No, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: No, EmptyDir: No
- **WebDAV** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes ³, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **Yandex Disk** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: Yes, ListR: No, StreamUpload: Yes, MultithreadUpload: No, LinkSharing: Yes, About: Yes, EmptyDir: Yes
- **Zoho WorkDrive** — Purge: Yes, Copy: Yes, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: No, MultithreadUpload: No, LinkSharing: No, About: Yes, EmptyDir: Yes
- **The local filesystem** — Purge: No, Copy: No, Move: Yes, DirMove: Yes, CleanUp: No, ListR: No, StreamUpload: Yes, MultithreadUpload: Yes, LinkSharing: No, About: Yes, EmptyDir: Yes

And here are the little footnotes, no skipping, they matter 👇

¹ Note Swift implements this in order to delete directory markers but it doesn't actually have a quicker way of deleting files other than deleting them individually.

² Storj implements this efficiently only for entire buckets. If purging a directory inside a bucket, files are deleted individually.

³ StreamUpload is not supported with Nextcloud

⁴ Use the `--sftp-copy-is-hardlink` flag to enable.

⁵ Use the `--onedrive-delta` flag to enable.

---

## 🗑️ Purge

This deletes a directory quicker than just deleting all the files in the directory.

---

## 📋 Copy

Used when copying an object to and from the same remote. This known as a server-side copy so you can copy a file without downloading it and uploading it again. It is used if you use `rclone copy` or `rclone move` if the remote doesn't support Move directly.

If the server doesn't support Copy directly then for copy operations the file is downloaded then re-uploaded.

---

## 🚚 Move

Used when moving/renaming an object on the same remote. This is known as a server-side move of a file. This is used in `rclone move` if the server doesn't support DirMove.

If the server isn't capable of Move then rclone simulates it with Copy then delete. If the server doesn't support Copy then rclone will download the file and re-upload it.

---

## 📁 DirMove

This is used to implement `rclone move` to move a directory if possible. If it isn't then it will use Move on each file (which falls back to Copy then download and upload — see Move section).

---

## 🧹 CleanUp

This is used for emptying the trash for a remote by `rclone cleanup`.

If the server can't do CleanUp then `rclone cleanup` will return an error.

> ‡‡ Note that while Box implements this it has to delete every file individually so it will be slower than emptying the trash via the WebUI

---

## 🗂️ ListR

The remote supports a recursive list to list all the contents beneath a directory quickly. This enables the `--fast-list` flag to work. See the rclone docs for more details.

---

## 🌊 StreamUpload

Some remotes allow files to be uploaded without knowing the file size in advance. This allows certain operations to work without spooling the file to local disk first, e.g. `rclone rcat`.

---

## 🧵 MultithreadUpload

Some remotes allow transfers to the remote to be sent as chunks in parallel. If this is supported then rclone will use multi-thread copying to transfer files much faster.

---

## 🔗 LinkSharing

Sets the necessary permissions on a file or folder and prints a link that allows others to access them, even if they don't have an account on the particular cloud provider.

---

## 📊 About

`rclone about` prints quota information for a remote. Typical output includes bytes used, free, quota and in trash.

If a remote lacks about capability `rclone about remote:` returns an error.

Backends without about capability cannot determine free space for an `rclone mount`, or use policy mfs (most free space) as a member of an `rclone union` remote.

See `rclone about` command

---

## 📂 EmptyDir

The remote supports empty directories. See <cyan>Limitations</cyan> for details. Most Object/Bucket-based remotes do not support this.

---

# ✨ Global Flags ✨

This describes the global flags available to every rclone command split into groups.

## 📋 Copy

Flags for anything which can copy a file.

- **`--check-first`** — do literally ALL the checks before you start any transfers, bestie. zero chaos starts.
- **`-c`, `--checksum`** — check for changes using size AND checksum (if the remote even has one, otherwise it falls back to size only, rude but okay)
- **`--compare-dest stringArray`** — include extra server-side paths when comparing, so rclone has ✨more intel✨
- **`--copy-dest stringArray`** — this one implies `--compare-dest` but ALSO copies files over from those paths into the destination
- **`--cutoff-mode HARD|SOFT|CAUTIOUS`** — how it reacts when you hit the max transfer limit: `HARD|SOFT|CAUTIOUS` (default `HARD`)
- **`--ignore-case-sync`** — ignore case when syncing, lowercase girlies rise up
- **`--ignore-checksum`** — skip the post-copy checksum verification. living on the edge, no cap
- **`--ignore-existing`** — skip every file that already exists on the destination. if it's there, it stays there 💅
- **`--ignore-size`** — don't use size to skip stuff, use modtime or checksum instead
- **`-I`, `--ignore-times`** — do NOT skip items that match in size and time — transfer everything, no questions asked
- **`--immutable`** — do not modify files, and straight-up FAIL if existing files were modified. very protective, love that
- **`--inplace`** — download straight into the destination file instead of doing the atomic download-to-temp-then-rename thing
- **`-l`, `--links`** — translate symlinks to/from regular files using a `.rclonelink` extension
- **`--max-backlog int`** — max number of objects allowed in the sync or check backlog (default `10000`)
- **`--max-duration Duration`** — max duration rclone will transfer data for (default `0s`)
- **`--max-transfer SizeSuffix`** — max size of data to transfer (default `off`)
- **`-M`, `--metadata`** — if set, preserve metadata when copying objects 🎀
- **`--modify-window Duration`** — max time difference that still counts as "the same" (default `1ns`)
- **`--multi-thread-chunk-size SizeSuffix`** — chunk size for multi-thread downloads/uploads, unless the filesystem already set one (default `64Mi`)
- **`--multi-thread-cutoff SizeSuffix`** — files above this size get the multi-thread download treatment (default `256Mi`)
- **`--multi-thread-streams int`** — how many streams to use for multi-thread downloads (default `4`)
- **`--multi-thread-write-buffer-size SizeSuffix`** — the in-memory buffer size for writing when in multi-thread mode (default `128Ki`)
- **`--no-check-dest`** — don't check the destination at all, just copy regardless. feral behavior but ok
- **`--no-traverse`** — don't traverse the destination file system on copy
- **`--no-update-dir-modtime`** — don't update directory modification times
- **`--no-update-modtime`** — don't update destination modtime if the files are identical
- **`--order-by string`** — instructions on how to order the transfers, like `'size,descending'`
- **`--partial-suffix string`** — add this suffix to the temporary file name when `--inplace` isn't used (default `".partial"`)
- **`--refresh-times`** — refresh the modtime of remote files
- **`--server-side-across-configs`** — let server-side operations (like copy) work across different configs
- **`--size-only`** — skip based on size only, not modtime or checksum
- **`--streaming-upload-cutoff SizeSuffix`** — the cutoff for switching to a chunked upload when the file size is unknown; the upload starts after reaching the cutoff or when the file ends (default `100Ki`)
- **`-u`, `--update`** — skip files that are newer on the destination

---

## 🌈 Sync 🌈

<purple>These are the flags for the sync commands, bestie. the delete girlies.</purple>

- **`--backup-dir string`** — make backups into a hierarchy based in *DIR*
- **`--delete-after`** — when syncing, delete files on the destination AFTER transferring (this is the default)
- **`--delete-before`** — when syncing, delete files on the destination BEFORE transferring
- **`--delete-during`** — when syncing, delete files DURING the transfer
- **`--fix-case`** — force a rename of a case insensitive destination to match the source
- **`--ignore-errors`** — delete even if there are I/O errors (bold move 💀)
- **`--max-delete int`** — when syncing, limit the number of deletes (default `-1`)
- **`--max-delete-size SizeSuffix`** — when syncing, limit the total size of deletes (default `off`)
- **`--suffix string`** — suffix to add to changed files
- **`--suffix-keep-extension`** — preserve the extension when using `--suffix`
- **`--track-renames`** — when syncing, track file renames and do a server-side move if possible
- **`--track-renames-strategy string`** — strategies to use when syncing with track-renames `hash|modtime|leaf` (default `"hash"`)

---

## 💖 Important 💖

<pink>okay these are the ones you actually need for basically everything, iykyk.</pink>

- **`-n`, `--dry-run`** — do a trial run with NO permanent changes. practice mode, safe mode, the vibe
- **`-i`, `--interactive`** — enable interactive mode
- **`-v`, `--verbose count`** — print lots more stuff (repeat it for even more, stack it up)

---

## ✅ Check ✅

<purple>Flags used for check commands.</purple>

- **`--max-backlog int`** — maximum number of objects in sync or check backlog (default `10000`)

---

## 🌐 Networking 🌐

<pink>Flags for general networking and HTTP stuff, bestie.</pink>

- **`--bind string`** — local address to bind to for outgoing connections — IPv4, IPv6 or a name
- **`--bwlimit BwTimetable`** — bandwidth limit in KiB/s, or use a suffix `B|K|M|G|T|P`, or a full timetable
- **`--bwlimit-file BwTimetable`** — bandwidth limit *per file* in KiB/s, or use a suffix `B|K|M|G|T|P`, or a full timetable
- **`--ca-cert stringArray`** — CA certificate used to verify servers
- **`--client-cert string`** — client SSL certificate (PEM) for mutual TLS auth
- **`--client-key string`** — client SSL private key (PEM) for mutual TLS auth
- **`--contimeout Duration`** — connect timeout (default `1m0s`)
- **`--disable-http-keep-alives`** — disable HTTP keep-alives and use each connection exactly once
- **`--disable-http2`** — disable HTTP/2 in the global transport
- **`--dscp string`** — set the DSCP value for connections; a value or a name, e.g. `CS1`, `LE`, `DF`, `AF21`
- **`--expect-continue-timeout Duration`** — timeout when using expect / 100-continue in HTTP (default `1s`)
- **`--header stringArray`** — set an HTTP header for ALL transactions
- **`--header-download stringArray`** — set an HTTP header for download transactions
- **`--header-upload stringArray`** — set an HTTP header for upload transactions
- **`--no-check-certificate`** — do NOT verify the server SSL certificate (**insecure**, careful bestie 💀)
- **`--no-gzip-encoding`** — don't set `Accept-Encoding: gzip`
- **`--timeout Duration`** — IO idle timeout (default `5m0s`)
- **`--tpslimit float`** — limit HTTP transactions per second to this
- **`--tpslimit-burst int`** — max burst of transactions for `--tpslimit` (default `1`)
- **`--use-cookies`** — enable session cookiejar 🍪
- **`--user-agent string`** — set the user-agent to a specified string (default `"rclone/v1.69.3"`)

---

## 🔥 Performance 🔥

<purple>Flags that help you go faster, fr fr.</purple>

- **`--buffer-size SizeSuffix`** — in-memory buffer size when reading files for each `--transfer` (default `16Mi`)
- **`--checkers int`** — number of checkers to run in parallel (default `8`)
- **`--transfers int`** — number of file transfers to run in parallel (default `4`)

---

## 🎀 Config 🎀

<pink>Flags for general configuration of rclone.</pink>

- **`--ask-password`** — allow prompt for password for encrypted configuration (default `true`)
- **`--auto-confirm`** — if enabled, don't request console confirmation
- **`--cache-dir string`** — the directory rclone will use for caching (default `"$HOME/.cache/rclone"`)
- **`--color AUTO|NEVER|ALWAYS`** — when to show colors (and other ANSI codes) `AUTO|NEVER|ALWAYS` (default `AUTO`)
- **`--config string`** — config file (default `"$HOME/.config/rclone/rclone.conf"`)
- **`--default-time Time`** — the time to show if modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--disable string`** — disable a comma separated list of features (use `--disable help` to see a list)
- **`-n`, `--dry-run`** — do a trial run with no permanent changes
- **`--error-on-no-transfer`** — sets exit code `9` if no files are transferred, useful in scripts
- **`--fs-cache-expire-duration Duration`** — cache remotes for this long (0 to disable caching) (default `5m0s`)
- **`--fs-cache-expire-interval Duration`** — interval to check for expired remotes (default `1m0s`)
- **`--human-readable`** — print numbers in a human-readable format, sizes with suffix `Ki|Mi|Gi|Ti|Pi`
- **`-i`, `--interactive`** — enable interactive mode
- **`--kv-lock-time Duration`** — maximum time to keep the key-value database locked by a process (default `1s`)
- **`--low-level-retries int`** — number of low level retries to do (default `10`)
- **`--no-console`** — hide console window (supported on Windows only)
- **`--no-unicode-normalization`** — don't normalize unicode characters in filenames
- **`--password-command SpaceSepList`** — command for supplying the password for encrypted configuration
- **`--retries int`** — retry operations this many times if they fail (default `3`)
- **`--retries-sleep Duration`** — interval between retrying operations if they fail, e.g. `500ms`, `60s`, `5m` (0 to disable) (default `0s`)
- **`--temp-dir string`** — the directory rclone will use for temporary files (default `"/tmp"`)
- **`--use-mmap`** — use mmap allocator (see docs)
- **`--use-server-modtime`** — use server modified time instead of object metadata

---

## 💀 Debugging 💀

<purple>Flags for developers.</purple>

- **`--cpuprofile string`** — wanna write a CPU profile to a file? drop the path here and it's yours 💅
- **`--dump DumpFlags`** — the list of stuff you want dumped, and bestie it's a whole menu: `headers`, `bodies`, `requests`, `responses`, `auth`, `filters`, `goroutines`, `openfiles`, `mapper`
- **`--dump-bodies`** — dumps HTTP headers *and* bodies. ⚠️ heads up, this can contain sensitive info, so like, don't screenshot it and post it
- **`--dump-headers`** — dumps HTTP headers only. also can contain sensitive info, same warning, be careful bestie 🙈
- **`--memprofile string`** — write a memory profile to a file, just give it the path

## ✨ Filter ✨

Flags for filtering directory listings. this is where you get to be picky and honestly? iconic behavior 🎀

- **`--delete-excluded`** — deletes files on the destination that got excluded from the sync
- **`--exclude stringArray`** — exclude files that match a pattern
- **`--exclude-from stringArray`** — read your exclude patterns from a file (use `-` to read from stdin)
- **`--exclude-if-present stringArray`** — nope out of directories if a given filename is present in them
- **`--files-from stringArray`** — read the list of source-file names from a file (use `-` for stdin)
- **`--files-from-raw stringArray`** — same deal but with *no processing of the lines at all* (use `-` for stdin)
- **`-f`, `--filter stringArray`** — add a file filtering rule, the classic
- **`--filter-from stringArray`** — read your file filtering patterns from a file (use `-` for stdin)
- **`--ignore-case`** — ignore case in filters, fully case insensitive, lowercase rights 🌸
- **`--include stringArray`** — include files matching a pattern
- **`--include-from stringArray`** — read include patterns from a file (use `-` for stdin)
- **`--max-age Duration`** — only transfer files *younger* than this, in `s` or with a suffix of `ms|s|m|h|d|w|M|y` (default `off`)
- **`--max-depth int`** — if you set it, it limits the recursion depth to this (default `-1`)
- **`--max-size SizeSuffix`** — only transfer files *smaller* than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)
- **`--metadata-exclude stringArray`** — exclude metadatas matching a pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` for stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` for stdin)
- **`--metadata-include stringArray`** — include metadatas matching a pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` for stdin)
- **`--min-age Duration`** — only transfer files *older* than this, in `s` or with a suffix of `ms|s|m|h|d|w|M|y` (default `off`)
- **`--min-size SizeSuffix`** — only transfer files *bigger* than this, in KiB or with a suffix `B|K|M|G|T|P` (default `off`)

## 🌈 Listing 🌈

Flags for listing directories, aka window shopping but make it filesystem ✨

- **`--default-time Time`** — the time to show when modtime is unknown for files and directories (default `2000-01-01T00:00:00Z`)
- **`--fast-list`** — use a recursive list if it's available; it eats more memory but does fewer transactions, so pick your struggle 💀

## 🫶 Logging 🫶

Flags for logging and statistics. yes this is the "what is it even doing" section, we love her

- **`--log-file string`** — log *everything* to this file
- **`--log-format string`** — a comma separated list of log format options (default `"date,time"`)
- **`--log-level LogLevel`** — the log level: `DEBUG|INFO|NOTICE|ERROR` (default `NOTICE`)
- **`--log-systemd`** — activates systemd integration for the logger
- **`--max-stats-groups int`** — max number of stats groups to keep in memory; once you hit the max, the oldest one gets discarded (default `1000`)
- **`-P`, `--progress`** — show progress during a transfer, the little bar that keeps you going 😭
- **`--progress-terminal-title`** — puts the progress up in the terminal title (requires `-P`/`--progress`, no solo missions)
- **`-q`, `--quiet`** — print as little stuff as possible. minimalism era
- **`--stats Duration`** — how often to print stats, e.g. `500ms`, `60s`, `5m` (`0` to disable) (default `1m0s`)
- **`--stats-file-name-length int`** — max file name length in stats (`0` for no limit) (default `45`)
- **`--stats-log-level LogLevel`** — the log level used to show `--stats` output: `DEBUG|INFO|NOTICE|ERROR` (default `INFO`)
- **`--stats-one-line`** — squishes the stats down to fit on one single line 💅
- **`--stats-one-line-date`** — turns on `--stats-one-line` and slaps the current date/time prefix on it
- **`--stats-one-line-date-format string`** — turns on `--stats-one-line-date` and uses your custom formatted date: wrap the date string in double quotes (`"`), and peep `https://golang.org/pkg/time/#Time.Format` for the format rules
- **`--stats-unit string`** — show the data rate in stats as either `'bits'` or `'bytes'` per second (default `"bytes"`)
- **`--syslog`** — use Syslog for logging
- **`--syslog-facility string`** — the facility for syslog, e.g. `KERN`, `USER` (default `"DAEMON"`)
- **`--use-json-log`** — use the json log format
- **`-v`, `--verbose count`** — print lots more stuff (repeat it for even more, stack it up bestie)

## 💜 Metadata 💜

Flags to control metadata. the little details that make everything make sense, fr fr

- **`-M`, `--metadata`** — if you set it, metadata gets preserved when copying objects
- **`--metadata-exclude stringArray`** — exclude metadatas matching a pattern
- **`--metadata-exclude-from stringArray`** — read metadata exclude patterns from a file (use `-` to read from stdin)
- **`--metadata-filter stringArray`** — add a metadata filtering rule
- **`--metadata-filter-from stringArray`** — read metadata filtering patterns from a file (use `-` to read from stdin)
- **`--metadata-include stringArray`** — include metadatas matching a pattern
- **`--metadata-include-from stringArray`** — read metadata include patterns from a file (use `-` to read from stdin)
- **`--metadata-mapper SpaceSepList`** — a program to run that transforms metadata before the upload happens
- **`--metadata-set stringArray`** — add a metadata `key=value` when uploading

## 👑 RC 👑

Flags to control the Remote Control API. big main character energy, this is the remote in "remote control" 💅

- **`--rc`** — enable the remote control server
- **`--rc-addr stringArray`** — `IPaddress:Port` or `:Port` to bind the server to (default `localhost:5572`)
- **`--rc-allow-origin string`** — the origin that cross-domain requests (CORS) can be executed from
- **`--rc-baseurl string`** — prefix for URLs, leave it blank for root
- **`--rc-cert string`** — TLS PEM key (that's a concatenation of certificate and CA certificate, iykyk)
- **`--rc-client-ca string`** — client certificate authority to verify clients with
- **`--rc-enable-metrics`** — enable the Prometheus metrics path at the remote control server
- **`--rc-files string`** — path to local files to serve on the HTTP server
- **`--rc-htpasswd string`** — a htpasswd file; if you don't provide one, no authentication is done, so like… your call bestie 🫣
- **`--rc-job-expire-duration Duration`** — expire finished async jobs older than this value (default `1m0s`)
- **`--rc-job-expire-interval Duration`** — how often to check for expired async jobs (default `10s`)
- **`--rc-key string`** — TLS PEM Private key
- **`--rc-max-header-bytes int`** — maximum size of the request header (default `4096`)
- **`--rc-min-tls-version string`** — minimum TLS version that's acceptable (default `"tls1.0"`)
- **`--rc-no-auth`** — don't require auth for certain methods
- **`--rc-pass string`** — password for authentication
- **`--rc-realm string`** — realm for authentication
- **`--rc-salt string`** — password hashing salt (default `"dlPL2MqE"`)
- **`--rc-serve`** — enable the serving of remote objects
- **`--rc-serve-no-modtime`** — don't read the modification time (this can speed things up ⚡)
- **`--rc-server-read-timeout Duration`** — timeout for the server reading data (default `1h0m0s`)
- **`--rc-server-write-timeout Duration`** — timeout for the server writing data (default `1h0m0s`)
- **`--rc-template string`** — a user-specified template
- **`--rc-user string`** — user name for authentication
- **`--rc-web-fetch-url string`** — URL to fetch the releases for webgui (default `"https://api.github.com/repos/rclone/rclone-webui-react/releases/latest"`)
- **`--rc-web-gui`** — launch WebGUI on localhost
- **`--rc-web-gui-force-update`** — force update to the latest version of the web gui
- **`--rc-web-gui-no-open-browser`** — don't open the browser automatically
- **`--rc-web-gui-update`** — check and update to the latest version of the web gui

## 🦋 Metrics 🦋

Flags to control the Metrics HTTP endpoint.. (yes two dots, she did that, we respect it)

- **`--metrics-addr stringArray`** — `IPaddress:Port` or `:Port` to bind the metrics server to
- **`--metrics-allow-origin string`** — the origin that cross-domain requests (CORS) can be executed from
- **`--metrics-baseurl string`** — prefix for URLs, leave it blank for root
- **`--metrics-cert string`** — TLS PEM key (concatenation of certificate and CA certificate)
- **`--metrics-client-ca string`** — client certificate authority to verify clients with
- **`--metrics-htpasswd string`** — a htpasswd file; if you don't provide one, no authentication is done
- **`--metrics-key string`** — TLS PEM Private key
- **`--metrics-max-header-bytes int`** — maximum size of the request header (default `4096`)
- **`--metrics-min-tls-version string`** — minimum TLS version that's acceptable (default `"tls1.0"`)
- **`--metrics-pass string`** — password for authentication
- **`--metrics-realm string`** — realm for authentication
- **`--metrics-salt string`** — password hashing salt (default `"dlPL2MqE"`)
- **`--metrics-server-read-timeout Duration`** — timeout for the server reading data (default `1h0m0s`)
- **`--metrics-server-write-timeout Duration`** — timeout for the server writing data (default `1h0m0s`)
- **`--metrics-template string`** — a user-specified template
- **`--metrics-user string`** — user name for authentication
- **`--rc-enable-metrics`** — enable the Prometheus metrics path at the remote control server

## 🧚 Backend 🧚

Backend-only flags (these can be set in the config file also).

- **`--alias-description string`** — the lil description of the remote, for your own reference 🎀
- **`--alias-remote string`** — the remote or path you're pointing the alias at <cyan>periodt</cyan>
- **`--azureblob-access-tier string`** — access tier of the blob: `hot`, `cool`, `cold` or `archive` 💅
- **`--azureblob-account string`** — Azure Storage Account Name
- **`--azureblob-archive-tier-delete`** — delete archive tier blobs *before* overwriting them (yes because you literally cannot overwrite them otherwise, it's giving chaotic)
- **`--azureblob-chunk-size SizeSuffix`** — upload chunk size (default `4Mi`)
- **`--azureblob-client-certificate-password string`** — password for the certificate file, optional (obscured) 🔒
- **`--azureblob-client-certificate-path string`** — path to a PEM or PKCS12 certificate file including the private key
- **`--azureblob-client-id string`** — the ID of the client in use
- **`--azureblob-client-secret string`** — one of the service principal's client secrets, keep it secret bestie 🤫
- **`--azureblob-client-send-certificate-chain`** — send the certificate chain when using certificate auth
- **`--azureblob-delete-snapshots string`** — set this to specify how to deal with snapshots on blob deletion
- **`--azureblob-description string`** — description of the remote 💖
- **`--azureblob-directory-markers`** — upload an empty object with a trailing slash whenever a new directory gets created
- **`--azureblob-disable-checksum`** — don't store MD5 checksum with object metadata
- **`--azureblob-disable-instance-discovery`** — skip requesting Microsoft Entra instance metadata
- **`--azureblob-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,RightPeriod,InvalidUtf8`)
- **`--azureblob-endpoint string`** — endpoint for the service
- **`--azureblob-env-auth`** — read credentials from runtime (environment variables, CLI or MSI) ✨
- **`--azureblob-key string`** — Storage Account Shared Key
- **`--azureblob-list-chunk int`** — size of blob list (default `5000`)
- **`--azureblob-msi-client-id string`** — object ID of the user-assigned MSI to use, if any
- **`--azureblob-msi-mi-res-id string`** — Azure resource ID of the user-assigned MSI to use, if any
- **`--azureblob-msi-object-id string`** — object ID of the user-assigned MSI to use, if any
- **`--azureblob-no-check-container`** — if set, don't attempt to check the container exists or create it 👀
- **`--azureblob-no-head-object`** — if set, do not do `HEAD` before `GET` when getting objects
- **`--azureblob-password string`** — the user's password (obscured) 🔐
- **`--azureblob-public-access string`** — public access level of a container: `blob` or `container`
- **`--azureblob-sas-url string`** — SAS URL, container level access only
- **`--azureblob-service-principal-file string`** — path to file containing credentials for use with a service principal
- **`--azureblob-tenant string`** — ID of the service principal's tenant. Also called its directory ID
- **`--azureblob-upload-concurrency int`** — concurrency for multipart uploads (default `16`)
- **`--azureblob-upload-cutoff string`** — cutoff for switching to chunked upload (`<= 256 MiB`) **(deprecated)** ⚠️ like it's still here but it's old news, don't be building new stuff on it
- **`--azureblob-use-az`** — use the Azure CLI tool `az` for authentication
- **`--azureblob-use-emulator`** — uses the local storage emulator if provided as `'true'`
- **`--azureblob-use-msi`** — use a managed service identity to authenticate (only works in Azure, iykyk)
- **`--azureblob-username string`** — user name (usually an email address)

---

- **`--azurefiles-account string`** — Azure Storage Account Name
- **`--azurefiles-chunk-size SizeSuffix`** — upload chunk size (default `4Mi`)
- **`--azurefiles-client-certificate-password string`** — password for the certificate file, optional (obscured) 🔒
- **`--azurefiles-client-certificate-path string`** — path to a PEM or PKCS12 certificate file including the private key
- **`--azurefiles-client-id string`** — the ID of the client in use
- **`--azurefiles-client-secret string`** — one of the service principal's client secrets
- **`--azurefiles-client-send-certificate-chain`** — send the certificate chain when using certificate auth
- **`--azurefiles-connection-string string`** — Azure Files Connection String
- **`--azurefiles-description string`** — description of the remote 🎀
- **`--azurefiles-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,RightPeriod,InvalidUtf8,Dot`)
- **`--azurefiles-endpoint string`** — endpoint for the service
- **`--azurefiles-env-auth`** — read credentials from runtime (environment variables, CLI or MSI) ✨
- **`--azurefiles-key string`** — Storage Account Shared Key
- **`--azurefiles-max-stream-size SizeSuffix`** — max size for streamed files (default `10Gi`)
- **`--azurefiles-msi-client-id string`** — object ID of the user-assigned MSI to use, if any
- **`--azurefiles-msi-mi-res-id string`** — Azure resource ID of the user-assigned MSI to use, if any
- **`--azurefiles-msi-object-id string`** — object ID of the user-assigned MSI to use, if any
- **`--azurefiles-password string`** — the user's password (obscured) 🔐
- **`--azurefiles-sas-url string`** — SAS URL
- **`--azurefiles-service-principal-file string`** — path to file containing credentials for use with a service principal
- **`--azurefiles-share-name string`** — Azure Files Share Name
- **`--azurefiles-tenant string`** — ID of the service principal's tenant. Also called its directory ID
- **`--azurefiles-upload-concurrency int`** — concurrency for multipart uploads (default `16`)
- **`--azurefiles-use-msi`** — use a managed service identity to authenticate (only works in Azure)
- **`--azurefiles-username string`** — user name (usually an email address)

---

- **`--b2-account string`** — account ID or Application Key ID
- **`--b2-chunk-size SizeSuffix`** — upload chunk size (default `96Mi`)
- **`--b2-copy-cutoff SizeSuffix`** — cutoff for switching to multipart copy (default `4Gi`)
- **`--b2-description string`** — description of the remote 💜
- **`--b2-disable-checksum`** — disable checksums for large (`> upload cutoff`) files
- **`--b2-download-auth-duration Duration`** — how long before the public link authorization token expires, in `s` or with a suffix `ms|s|m|h|d` (default `1w`)
- **`--b2-download-url string`** — custom endpoint for downloads
- **`--b2-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--b2-endpoint string`** — endpoint for the service
- **`--b2-hard-delete`** — permanently delete files on remote removal, otherwise files just get hidden 🫣
- **`--b2-key string`** — Application Key
- **`--b2-lifecycle int`** — set the number of days deleted files should be kept when creating a bucket
- **`--b2-test-mode string`** — a flag string for the `X-Bz-Test-Mode` header, for debugging 🧪
- **`--b2-upload-concurrency int`** — concurrency for multipart uploads (default `4`)
- **`--b2-upload-cutoff SizeSuffix`** — cutoff for switching to chunked upload (default `200Mi`)
- **`--b2-version-at Time`** — show file versions as they were at the specified time (default `off`)
- **`--b2-versions`** — include old versions in directory listings

---

- **`--box-access-token string`** — Box App Primary Access Token
- **`--box-auth-url string`** — auth server URL
- **`--box-box-config-file string`** — Box App `config.json` location
- **`--box-box-sub-type string`** — (default `"user"`), that's literally all it says bestie, no description, just the default 😭
- **`--box-client-credentials`** — use client credentials OAuth flow
- **`--box-client-id string`** — OAuth Client Id
- **`--box-client-secret string`** — OAuth Client Secret 🤫
- **`--box-commit-retries int`** — max number of times to try committing a multipart file (default `100`)
- **`--box-description string`** — description of the remote 🌸
- **`--box-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,RightSpace,InvalidUtf8,Dot`)
- **`--box-impersonate string`** — impersonate this user ID when using a service account 👑
- **`--box-list-chunk int`** — size of listing chunk `1-1000` (default `1000`)
- **`--box-owned-by string`** — only show items owned by the login (email address) passed in
- **`--box-root-folder-id string`** — fill in for rclone to use a non root folder as its starting point
- **`--box-token string`** — OAuth Access Token as a JSON blob
- **`--box-token-url string`** — token server url
- **`--box-upload-cutoff SizeSuffix`** — cutoff for switching to multipart upload (`>= 50 MiB`) (default `50Mi`)

---

- **`--cache-chunk-clean-interval Duration`** — how often should the cache perform cleanups of the chunk storage (default `1m0s`) 🧹
- **`--cache-chunk-no-memory`** — disable the in-memory cache for storing chunks during streaming

- **`--cache-chunk-path`** *string* — where the chunk files get to live, bestie (default `"$HOME/.cache/rclone/cache-backend"`)
- **`--cache-chunk-size`** *SizeSuffix* — how big one chunk (aka a slice of file data) is (default `5Mi`)
- **`--cache-chunk-total-size`** *SizeSuffix* — the total amount of disk space all those chunks are allowed to eat up locally (default `10Gi`)
- **`--cache-db-path`** *string* — the directory where the file structure metadata DB is stored (default `"$HOME/.cache/rclone/cache-backend"`)
- **`--cache-db-purge`** — nukes all the cached data for this remote the moment it starts 💀
- **`--cache-db-wait-time`** *Duration* — how long to wait for the DB to show up — and `0` means unlimited patience (default `1s`)
- **`--cache-description`** *string* — a lil description of the remote
- **`--cache-info-age`** *Duration* — how long file structure info gets cached (directory listings, file size, times, all of it) (default `6h0m0s`)
- **`--cache-plex-insecure`** *string* — skip **all** certificate verification when connecting to the Plex server (yes, all of it, no cap)
- **`--cache-plex-password`** *string* — the Plex user's password (obscured)
- **`--cache-plex-url`** *string* — the URL of the Plex server
- **`--cache-plex-username`** *string* — the username of the Plex user
- **`--cache-read-retries`** *int* — how many times it's gonna retry a read from a cache storage (default `10`)
- **`--cache-remote`** *string* — the remote you're caching, periodt
- **`--cache-rps`** *int* — caps the number of requests per second to the source FS, use `-1` to turn it off entirely (default `-1`)
- **`--cache-tmp-upload-path`** *string* — the directory where temporary files hang out until they get uploaded
- **`--cache-tmp-wait-time`** *Duration* — how long files chill in the local cache before being uploaded (default `15s`)
- **`--cache-workers`** *int* — how many workers run in parallel to download chunks (default `4`)
- **`--cache-writes`** — cache file data on writes through the FS ✨

---

- **`--chunker-chunk-size`** *SizeSuffix* — files bigger than the chunk size get split into chunks (default `2Gi`)
- **`--chunker-description`** *string* — a lil description of the remote
- **`--chunker-fail-hard`** — choose how chunker should handle files with missing or invalid chunks
- **`--chunker-hash-type`** *string* — choose how chunker handles hash sums (default `"md5"`)
- **`--chunker-remote`** *string* — the remote to chunk/unchunk 🧩

---

- **`--cloudinary-api-key`** *string* — Cloudinary API Key
- **`--cloudinary-api-secret`** *string* — Cloudinary API Secret
- **`--cloudinary-cloud-name`** *string* — Cloudinary Environment Name
- **`--cloudinary-description`** *string* — a lil description of the remote
- **`--cloudinary-encoding`** *Encoding* — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Question,Asterisk,Pipe,Hash,Percent,BackSlash,Del,Ctl,RightSpace,InvalidUtf8,Dot`)
- **`--cloudinary-eventually-consistent-delay`** *Duration* — wait N seconds for eventual consistency of the databases that support the backend operation (default `0s`)
- **`--cloudinary-upload-prefix`** *string* — specify the API endpoint for environments that are out of the US
- **`--cloudinary-upload-preset`** *string* — Upload Preset to pick asset manipulation on upload

---

- **`--combine-description`** *string* — a lil description of the remote
- **`--combine-upstreams`** *SpaceSepList* — the upstreams you're combining 🌈

---

- **`--compress-description`** *string* — a lil description of the remote
- **`--compress-level`** *int* — GZIP compression level, and it's gotta be between `-2` and `9` (default `-1`)
- **`--compress-mode`** *string* — compression mode (default `"gzip"`)
- **`--compress-ram-cache-limit`** *SizeSuffix* — heads up: some remotes just don't allow uploading files with unknown size (default `20Mi`)
- **`--compress-remote`** *string* — the remote to compress 📦
- **`-L`, `--copy-links`** — follow symlinks and copy the item they point to 🫶

---

- **`--crypt-description`** *string* — a lil description of the remote
- **`--crypt-directory-name-encryption`** — the option to either encrypt directory names or leave them intact (default `true`)
- **`--crypt-filename-encoding`** *string* — how to encode the encrypted filename into a text string (default `"base32"`)
- **`--crypt-filename-encryption`** *string* — how to encrypt the filenames (default `"standard"`)
- **`--crypt-no-data-encryption`** — the option to either encrypt file data or leave it unencrypted 🙈
- **`--crypt-pass-bad-blocks`** — if this is set, bad blocks get passed through as all `0`
- **`--crypt-password`** *string* — password or pass phrase for encryption (obscured) 🔐
- **`--crypt-password2`** *string* — password or pass phrase for salt (obscured)
- **`--crypt-remote`** *string* — the remote to encrypt/decrypt
- **`--crypt-server-side-across-configs`** — **Deprecated: use `--server-side-across-configs` instead**
- **`--crypt-show-mapping`** — for all files listed, show how the names encrypt 👀
- **`--crypt-strict-names`** — if this is set, it raises an error when crypt comes across a filename it can't decrypt
- **`--crypt-suffix`** *string* — if this is set it overrides the default suffix of `".bin"` (default `".bin"`)

---

- **`--drive-acknowledge-abuse`** — set this to allow files which return `cannotDownloadAbusiveFile` to be downloaded
- **`--drive-allow-import-name-change`** — allow the filetype to change when uploading Google docs
- **`--drive-auth-owner-only`** — only consider files owned by the authenticated user
- **`--drive-auth-url`** *string* — auth server URL
- **`--drive-chunk-size`** *SizeSuffix* — upload chunk size (default `8Mi`)
- **`--drive-client-credentials`** — use client credentials OAuth flow
- **`--drive-client-id`** *string* — Google Application Client Id
- **`--drive-client-secret`** *string* — OAuth Client Secret
- **`--drive-copy-shortcut-content`** — server side copy the contents of shortcuts instead of the shortcut itself
- **`--drive-description`** *string* — a lil description of the remote
- **`--drive-disable-http2`** — disable drive using http2 (default `true`)
- **`--drive-encoding`** *Encoding* — the encoding for the backend (default `InvalidUtf8`)
- **`--drive-env-auth`** — get IAM credentials from runtime (environment variables, or instance metadata if there are no env vars)
- **`--drive-export-formats`** *string* — comma separated list of preferred formats for downloading Google docs (default `"docx,xlsx,pptx,svg"`)
- **`--drive-fast-list-bug-fix`** — work around a bug in Google Drive listing (default `true`)
- **`--drive-formats`** *string* — **Deprecated: see `export_formats`**
- **`--drive-impersonate`** *string* — impersonate this user when using a service account 🎭
- **`--drive-import-formats`** *string* — comma separated list of preferred formats for uploading Google docs
- **`--drive-keep-revision-forever`** — keep the new head revision of each file forever
- **`--drive-list-chunk`** *int* — size of listing chunk, `100`-`1000`, or `0` to disable (default `1000`)
- **`--drive-metadata-labels`** *Bits* — control whether labels should be read or written in metadata (default `off`)
- **`--drive-metadata-owner`** *Bits* — control whether owner should be read or written in metadata (default `read`)
- **`--drive-metadata-permissions`** *Bits* — control whether permissions should be read or written in metadata (default `off`)
- **`--drive-pacer-burst`** *int* — number of API calls to allow without sleeping (default `100`)
- **`--drive-pacer-min-sleep`** *Duration* — minimum time to sleep between API calls (default `100ms`)
- **`--drive-resource-key`** *string* — resource key for accessing a link-shared file 🔑
- **`--drive-root-folder-id`** *string* — ID of the root folder
- **`--drive-scope`** *string* — comma separated list of scopes that rclone should use when requesting access from drive
- **`--drive-server-side-across-configs`** — **Deprecated: use `--server-side-across-configs` instead**
- **`--drive-service-account-credentials`** *string* — Service Account Credentials JSON blob
- **`--drive-service-account-file`** *string* — Service Account Credentials JSON file path
- **`--drive-shared-with-me`** — only show files that are shared with me
- **`--drive-show-all-gdocs`** — show all Google Docs, including the non-exportable ones, in listings
- **`--drive-size-as-quota`** — show sizes as storage quota usage, not the actual size
- **`--drive-skip-checksum-gphotos`** — skip checksums on Google photos and videos only
- **`--drive-skip-dangling-shortcuts`** — if set, skip dangling shortcut files
- **`--drive-skip-gdocs`** — skip google documents in all listings
- **`--drive-skip-shortcuts`** — if set, skip shortcut files
- **`--drive-starred-only`** — only show files that are starred ⭐
- **`--drive-stop-on-download-limit`** — make download limit errors be **fatal**
- **`--drive-stop-on-upload-limit`** — make upload limit errors be **fatal**
- **`--drive-team-drive`** *string* — ID of the Shared Drive (Team Drive) 👑

- **`--drive-token`** (*string*) — the OAuth Access Token, handed over as a JSON blob 💅
- **`--drive-token-url`** (*string*) — where the token server lives, url-style
- **`--drive-trashed-only`** (*bool*) — only show files that are in the trash, yes we're going dumpster diving 🗑️
- **`--drive-upload-cutoff`** (*SizeSuffix*) — the size where uploads stop being one-shot and switch to chunked (default `8Mi`)
- **`--drive-use-created-date`** (*bool*) — use the file's created date instead of the modified date
- **`--drive-use-shared-date`** (*bool*) — use the date the file was shared instead of the modified date
- **`--drive-use-trash`** (*bool*) — send files to the trash instead of deleting them permanently (default `true`) ✨
- **`--drive-v2-download-min-size`** (*SizeSuffix*) — if objects are bigger than this, rclone downloads them with the drive v2 API instead (default `off`)

- **`--dropbox-auth-url`** (*string*) — auth server URL
- **`--dropbox-batch-commit-timeout`** (*Duration*) — the max time rclone will wait for a batch to finish committing (default `10m0s`)
- **`--dropbox-batch-mode`** (*string*) — upload file batching, and you pick `sync`|`async`|`off` (default `"sync"`)
- **`--dropbox-batch-size`** (*int*) — the max number of files that can live in one upload batch
- **`--dropbox-batch-timeout`** (*Duration*) — the max time rclone lets an upload batch sit idle before it just uploads it already (default `0s`)
- **`--dropbox-chunk-size`** (*SizeSuffix*) — upload chunk size, and it must be `< 150Mi` (default `48Mi`)
- **`--dropbox-client-credentials`** (*bool*) — use the client credentials OAuth flow
- **`--dropbox-client-id`** (*string*) — that OAuth Client Id
- **`--dropbox-client-secret`** (*string*) — that OAuth Client Secret
- **`--dropbox-description`** (*string*) — a lil description of the remote
- **`--dropbox-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,BackSlash,Del,RightSpace,InvalidUtf8,Dot`)
- **`--dropbox-impersonate`** (*string*) — impersonate this user when you're on a business account 🎭
- **`--dropbox-pacer-min-sleep`** (*Duration*) — the minimum time to sleep between API calls (default `10ms`)
- **`--dropbox-root-namespace`** (*string*) — pick a different Dropbox namespace ID to use as the root for all paths
- **`--dropbox-shared-files`** (*bool*) — tells rclone to work on individual shared files
- **`--dropbox-shared-folders`** (*bool*) — tells rclone to work on shared folders
- **`--dropbox-token`** (*string*) — the OAuth Access Token, as a JSON blob
- **`--dropbox-token-url`** (*string*) — token server url

- **`--fichier-api-key`** (*string*) — your API Key, grab it from `https://1fichier.com/console/params.pl` 🔑
- **`--fichier-cdn`** (*bool*) — set this if you wanna use CDN download links
- **`--fichier-description`** (*string*) — description of the remote
- **`--fichier-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,LtGt,DoubleQuote,SingleQuote,BackQuote,Dollar,BackSlash,Del,Ctl,LeftSpace,RightSpace,InvalidUtf8,Dot`)
- **`--fichier-file-password`** (*string*) — if you're downloading a password-protected shared file, drop this parameter in (obscured) 🤫
- **`--fichier-folder-password`** (*string*) — if you're listing files in a password-protected shared folder, add this parameter (obscured)
- **`--fichier-shared-folder`** (*string*) — if you wanna download a shared folder, add this parameter

- **`--filefabric-description`** (*string*) — description of the remote
- **`--filefabric-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,Del,Ctl,InvalidUtf8,Dot`)
- **`--filefabric-permanent-token`** (*string*) — Permanent Authentication Token
- **`--filefabric-root-folder-id`** (*string*) — ID of the root folder
- **`--filefabric-token`** (*string*) — Session Token
- **`--filefabric-token-expiry`** (*string*) — Token expiry time ⏰
- **`--filefabric-url`** (*string*) — URL of the Enterprise File Fabric you're connecting to
- **`--filefabric-version`** (*string*) — the version read from the file fabric

- **`--filescom-api-key`** (*string*) — the API key used to authenticate with Files.com
- **`--filescom-description`** (*string*) — description of the remote
- **`--filescom-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot`)
- **`--filescom-password`** (*string*) — the password used to authenticate with Files.com (obscured) 🙈
- **`--filescom-site`** (*string*) — your site subdomain (e.g. `mysite`) or your custom domain (e.g. `myfiles.customdomain.com`)
- **`--filescom-username`** (*string*) — the username used to authenticate with Files.com

- **`--ftp-ask-password`** (*bool*) — let rclone ask for the FTP password when it needs one
- **`--ftp-close-timeout`** (*Duration*) — the max time to wait for a response to close (default `1m0s`)
- **`--ftp-concurrency`** (*int*) — max number of simultaneous FTP connections, `0` means unlimited 🔥
- **`--ftp-description`** (*string*) — description of the remote
- **`--ftp-disable-epsv`** (*bool*) — don't use EPSV even if the server says it supports it
- **`--ftp-disable-mlsd`** (*bool*) — don't use MLSD even if the server says it supports it
- **`--ftp-disable-tls13`** (*bool*) — disable TLS 1.3 (the workaround for FTP servers with buggy TLS) 🐛
- **`--ftp-disable-utf8`** (*bool*) — don't use UTF-8 even if the server says it supports it
- **`--ftp-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,Del,Ctl,RightSpace,Dot`)
- **`--ftp-explicit-tls`** (*bool*) — use Explicit FTPS (AKA FTP over TLS) 🔒
- **`--ftp-force-list-hidden`** (*bool*) — use `LIST -a` to force listing of hidden files and folders. This disables the use of MLSD, just so you know
- **`--ftp-host`** (*string*) — the FTP host to connect to
- **`--ftp-idle-timeout`** (*Duration*) — max time before idle connections get closed (default `1m0s`)
- **`--ftp-no-check-certificate`** (*bool*) — do **not** verify the TLS certificate of the server
- **`--ftp-no-check-upload`** (*bool*) — don't check that the upload actually went OK
- **`--ftp-pass`** (*string*) — FTP password (obscured)
- **`--ftp-port`** (*int*) — FTP port number (default `21`)
- **`--ftp-shut-timeout`** (*Duration*) — max time to wait for the data connection's closing status (default `1m0s`)
- **`--ftp-socks-proxy`** (*string*) — Socks 5 proxy host
- **`--ftp-tls`** (*bool*) — use Implicit FTPS (FTP over TLS) 🔐
- **`--ftp-tls-cache-size`** (*int*) — size of the TLS session cache for all control and data connections (default `32`)
- **`--ftp-user`** (*string*) — FTP username (default `"$USER"`)
- **`--ftp-writing-mdtm`** (*bool*) — use MDTM to set modification time (the VsFtpd quirk)

- **`--gcs-access-token`** (*string*) — short-lived access token
- **`--gcs-anonymous`** (*bool*) — access public buckets and objects with zero credentials, no login needed 🕵️
- **`--gcs-auth-url`** (*string*) — auth server URL
- **`--gcs-bucket-acl`** (*string*) — Access Control List for new buckets
- **`--gcs-bucket-policy-only`** (*bool*) — access checks should use bucket-level IAM policies
- **`--gcs-client-credentials`** (*bool*) — use client credentials OAuth flow
- **`--gcs-client-id`** (*string*) — OAuth Client Id
- **`--gcs-client-secret`** (*string*) — OAuth Client Secret
- **`--gcs-decompress`** (*bool*) — set this and rclone will decompress gzip encoded objects
- **`--gcs-description`** (*string*) — description of the remote
- **`--gcs-directory-markers`** (*bool*) — upload an empty object with a trailing slash whenever a new directory gets created
- **`--gcs-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,CrLf,InvalidUtf8,Dot`)
- **`--gcs-endpoint`** (*string*) — endpoint for the service
- **`--gcs-env-auth`** (*bool*) — grab GCP IAM credentials from the runtime (env vars, or instance metadata if there are no env vars) 🌱
- **`--gcs-location`** (*string*) — location for the newly created buckets
- **`--gcs-no-check-bucket`** (*bool*) — if set, don't even attempt to check the bucket exists or create it
- **`--gcs-object-acl`** (*string*) — Access Control List for new objects
- **`--gcs-project-number`** (*string*) — project number
- **`--gcs-service-account-file`** (*string*) — Service Account Credentials JSON file path
- **`--gcs-storage-class`** (*string*) — the storage class to use when storing objects in Google Cloud Storage
- **`--gcs-token`** (*string*) — OAuth Access Token as a JSON blob
- **`--gcs-token-url`** (*string*) — token server url
- **`--gcs-user-project`** (*string*) — user project

- **`--gofile-access-token`** (*string*) — API Access token
- **`--gofile-account-id`** (*string*) — Account ID
- **`--gofile-description`** (*string*) — description of the remote
- **`--gofile-encoding`** (*Encoding*) — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftPeriod,RightPeriod,InvalidUtf8,Dot,Exclamation`)
- **`--gofile-list-chunk`** (*int*) — how many items to list in each call (default `1000`)
- **`--gofile-root-folder-id`** (*string*) — ID of the root folder

- **`--gphotos-auth-url`** *string* — <purple>the OAuth auth server URL</purple>, aka the bouncer checking IDs at the door 💅
- **`--gphotos-batch-commit-timeout`** *Duration* — how long you're willing to sit and wait for a batch to finish committing. default `10m0s` ⏳
- **`--gphotos-batch-mode`** *string* — upload file batching mode: `sync`, `async` or `off`. default `"sync"` 🧺
- **`--gphotos-batch-size`** *int* — max number of files that can be in one upload batch
- **`--gphotos-batch-timeout`** *Duration* — max time an idle upload batch is allowed to just sit there vibing before it gets pushed out. default `0s`
- **`--gphotos-client-credentials`** — use the client credentials OAuth flow
- **`--gphotos-client-id`** *string* — your OAuth Client Id
- **`--gphotos-client-secret`** *string* — your OAuth Client Secret 🤫 keep it secret, keep it safe
- **`--gphotos-description`** *string* — a lil description of the remote ✨
- **`--gphotos-encoding`** *Encoding* — the encoding for the backend. default `Slash,CrLf,InvalidUtf8,Dot`
- **`--gphotos-include-archived`** — also view and download archived media 🗄️
- **`--gphotos-proxy`** *string* — use the `gphotosdl` proxy for downloading the full resolution images 🖼️
- **`--gphotos-read-only`** — set this and the Google Photos backend becomes read only 🙅‍♀️
- **`--gphotos-read-size`** — set this to read the size of media items 📏
- **`--gphotos-start-year`** *int* — year limits the photos to be downloaded to those which are uploaded after the given year. default `2000`
- **`--gphotos-token`** *string* — OAuth Access Token as a JSON blob
- **`--gphotos-token-url`** *string* — token server url

---

- **`--hasher-auto-size`** *SizeSuffix* — auto-update checksum for files smaller than this size (disabled by default) 🧮
- **`--hasher-description`** *string* — description of the remote
- **`--hasher-hashes`** *CommaSepList* — comma separated list of supported checksum types. default `md5,sha1`
- **`--hasher-max-age`** *Duration* — maximum time to keep checksums in cache (`0` = no cache, `off` = cache forever). default `off` ♾️
- **`--hasher-remote`** *string* — remote to cache checksums for, like `myRemote:path`

---

- **`--hdfs-data-transfer-protection`** *string* — Kerberos data transfer protection: `authentication` | `integrity` | `privacy` 🔐
- **`--hdfs-description`** *string* — description of the remote
- **`--hdfs-encoding`** *Encoding* — the encoding for the backend. default `Slash,Colon,Del,Ctl,InvalidUtf8,Dot`
- **`--hdfs-namenode`** *CommaSepList* — Hadoop name nodes and ports
- **`--hdfs-service-principal-name`** *string* — Kerberos service principal name for the namenode
- **`--hdfs-username`** *string* — Hadoop user name

---

- **`--hidrive-auth-url`** *string* — auth server URL
- **`--hidrive-chunk-size`** *SizeSuffix* — chunksize for chunked uploads. default `48Mi` 🍰
- **`--hidrive-client-credentials`** — use client credentials OAuth flow
- **`--hidrive-client-id`** *string* — OAuth Client Id
- **`--hidrive-client-secret`** *string* — OAuth Client Secret
- **`--hidrive-description`** *string* — description of the remote
- **`--hidrive-disable-fetching-member-count`** — do not fetch number of objects in directories unless it is absolutely necessary 🚫
- **`--hidrive-encoding`** *Encoding* — the encoding for the backend. default `Slash,Dot`
- **`--hidrive-endpoint`** *string* — endpoint for the service. default `"https://api.hidrive.strato.com/2.1"`
- **`--hidrive-root-prefix`** *string* — the root/parent folder for all paths. default `"/"`
- **`--hidrive-scope-access`** *string* — access permissions that rclone should use when requesting access from HiDrive. default `"rw"`
- **`--hidrive-scope-role`** *string* — user-level that rclone should use when requesting access from HiDrive. default `"user"`
- **`--hidrive-token`** *string* — OAuth Access Token as a JSON blob
- **`--hidrive-token-url`** *string* — token server url
- **`--hidrive-upload-concurrency`** *int* — concurrency for chunked uploads. default `4`
- **`--hidrive-upload-cutoff`** *SizeSuffix* — cutoff/threshold for chunked uploads. default `96Mi`

---

- **`--http-description`** *string* — description of the remote
- **`--http-headers`** *CommaSepList* — set HTTP headers for all transactions 📨
- **`--http-no-escape`** — do not escape URL metacharacters in path names
- **`--http-no-head`** — don't use `HEAD` requests
- **`--http-no-slash`** — set this if the site doesn't end directories with `/`
- **`--http-url`** *string* — URL of HTTP host to connect to

---

- **`--iclouddrive-apple-id`** *string* — Apple ID 🍎
- **`--iclouddrive-client-id`** *string* — client id. default `"d39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d"`
- **`--iclouddrive-description`** *string* — description of the remote
- **`--iclouddrive-encoding`** *Encoding* — the encoding for the backend. default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`
- **`--iclouddrive-password`** *string* — password (obscured) 🔒
- **`--imagekit-description`** *string* — description of the remote
- **`--imagekit-encoding`** *Encoding* — the encoding for the backend. default `Slash,LtGt,DoubleQuote,Dollar,Question,Hash,Percent,BackSlash,Del,Ctl,InvalidUtf8,Dot,SquareBracket`
- **`--imagekit-endpoint`** *string* — you can find your ImageKit.io URL endpoint in your `[dashboard](https://imagekit.io/dashboard/developer/api-keys)`
- **`--imagekit-only-signed`** — Restrict unsigned image URLs. if you have configured *Restrict unsigned image URLs* in your dashboard settings, set this to `true`
- **`--imagekit-private-key`** *string* — you can find your ImageKit.io private key in your `[dashboard](https://imagekit.io/dashboard/developer/api-keys)`
- **`--imagekit-public-key`** *string* — you can find your ImageKit.io public key in your `[dashboard](https://imagekit.io/dashboard/developer/api-keys)`
- **`--imagekit-upload-tags`** *string* — tags to add to the uploaded files, e.g. `"tag1,tag2"` 🏷️
- **`--imagekit-versions`** — include old versions in directory listings 👵

---

- **`--internetarchive-access-key-id`** *string* — IAS3 Access Key
- **`--internetarchive-description`** *string* — description of the remote
- **`--internetarchive-disable-checksum`** — don't ask the server to test against MD5 checksum calculated by rclone. default `true`
- **`--internetarchive-encoding`** *Encoding* — the encoding for the backend. default `Slash,LtGt,CrLf,Del,Ctl,InvalidUtf8,Dot`
- **`--internetarchive-endpoint`** *string* — IAS3 Endpoint. default `"https://s3.us.archive.org"`
- **`--internetarchive-front-endpoint`** *string* — host of InternetArchive Frontend. default `"https://archive.org"`
- **`--internetarchive-secret-access-key`** *string* — IAS3 Secret Key (password) 🤐
- **`--internetarchive-wait-archive`** *Duration* — timeout for waiting the server's processing tasks (specifically `archive` and `book_op`) to finish. default `0s`

---

- **`--jottacloud-auth-url`** *string* — auth server URL
- **`--jottacloud-client-credentials`** — use client credentials OAuth flow
- **`--jottacloud-client-id`** *string* — OAuth Client Id
- **`--jottacloud-client-secret`** *string* — OAuth Client Secret
- **`--jottacloud-description`** *string* — description of the remote
- **`--jottacloud-encoding`** *Encoding* — the encoding for the backend. default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Del,Ctl,InvalidUtf8,Dot`
- **`--jottacloud-hard-delete`** — delete files permanently rather than putting them into the trash 💀 no undo, bestie
- **`--jottacloud-md5-memory-limit`** *SizeSuffix* — files bigger than this will be cached on disk to calculate the MD5 if required. default `10Mi`
- **`--jottacloud-no-versions`** — avoid server side versioning by deleting files and recreating files instead of overwriting them 🔁
- **`--jottacloud-token`** *string* — OAuth Access Token as a JSON blob
- **`--jottacloud-token-url`** *string* — token server url
- **`--jottacloud-trashed-only`** — only show files that are in the trash 🗑️
- **`--jottacloud-upload-resume-limit`** *SizeSuffix* — files bigger than this can be resumed if the upload fail's. default `10Mi`

---

- **`--koofr-description`** *string* — description of the remote
- **`--koofr-encoding`** *Encoding* — the encoding for the backend. default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`
- **`--koofr-endpoint`** *string* — the Koofr API endpoint to use
- **`--koofr-mountid`** *string* — Mount ID of the mount to use
- **`--koofr-password`** *string* — your password for rclone (generate one at `https://app.koofr.net/app/admin/preferences/password`) (obscured) 🔑
- **`--koofr-provider`** *string* — choose your storage provider
- **`--koofr-setmtime`** — does the backend support setting modification time. default `true`
- **`--koofr-user`** *string* — your user name
- **`--linkbox-description`** *string* — description of the remote
- **`--linkbox-token`** *string* — token from `https://www.linkbox.to/admin/account`

---

- **`--local-case-insensitive`** — force the filesystem to report itself as case insensitive
- **`--local-case-sensitive`** — force the filesystem to report itself as case sensitive 🔠

- **`--local-description string`** — a cute lil note describing this remote 💖
- **`--local-encoding Encoding`** — the encoding for this backend (default `Slash,Dot`)
- **`--local-links`** — turn symlinks into regular files (and back) using a `.rclonelink` extension, local backend edition 🦋
- **`--local-no-check-updated`** — don't peek at whether files changed mid-upload. no vibe checks here, we just send it
- **`--local-no-clone`** — kills reflink cloning for server-side copies
- **`--local-no-preallocate`** — stop preallocating disk space for files you're transferring
- **`--local-no-set-modtime`** — don't set modtime, we're leaving the timestamp alone bestie
- **`--local-no-sparse`** — disables sparse files on multi-thread downloads
- **`--local-nounc`** — turn off UNC (long path names) conversion on Windows
- **`--local-time-type mtime|atime|btime|ctime`** — pick which kind of time gets returned (default `mtime`)
- **`--local-unicode-normalization`** — apply unicode NFC normalization to paths and filenames ✨
- **`--local-zero-size-links`** — assume the Stat size of links is zero and read them instead. ⚠️ **deprecated**, so like, don't build your whole personality on it
- **`--mailru-auth-url string`** — auth server URL
- **`--mailru-check-hash`** — what copy should do when a file checksum is mismatched or invalid (default `true`)
- **`--mailru-client-credentials`** — use the client credentials OAuth flow
- **`--mailru-client-id string`** — OAuth Client Id
- **`--mailru-client-secret string`** — OAuth Client Secret
- **`--mailru-description string`** — description of the remote 💅
- **`--mailru-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--mailru-pass string`** — password (obscured) 🙈
- **`--mailru-speedup-enable`** — skip the whole upload if another file already has the same data hash (default `true`)
- **`--mailru-speedup-file-patterns string`** — comma separated list of filename patterns that qualify for speedup (put by hash) (default `"*.mkv,*.avi,*.mp4,*.mp3,*.zip,*.gz,*.rar,*.pdf"`)
- **`--mailru-speedup-max-disk SizeSuffix`** — lets you switch off speedup (put by hash) for big files (default `3Gi`)
- **`--mailru-speedup-max-memory SizeSuffix`** — any file bigger than this gets hashed on disk, every single time (default `32Mi`)
- **`--mailru-token string`** — OAuth Access Token as a JSON blob
- **`--mailru-token-url string`** — token server url
- **`--mailru-user string`** — user name (usually your email)
- **`--mega-debug`** — spill more debug out of Mega 🔥
- **`--mega-description string`** — description of the remote
- **`--mega-encoding Encoding`** — the encoding for the backend (default `Slash,InvalidUtf8,Dot`)
- **`--mega-hard-delete`** — yeet files permanently instead of dropping them in the trash 💀
- **`--mega-pass string`** — password (obscured)
- **`--mega-use-https`** — use HTTPS for transfers 🔒
- **`--mega-user string`** — user name
- **`--memory-description string`** — description of the remote
- **`--netstorage-account string`** — set the NetStorage account name
- **`--netstorage-description string`** — description of the remote
- **`--netstorage-host string`** — domain+path of the NetStorage host you're connecting to
- **`--netstorage-protocol string`** — choose between HTTP or HTTPS (default `"https"`)
- **`--netstorage-secret string`** — set the NetStorage account secret/G2O key for auth (obscured) 🫶
- **`-x`, `--one-file-system`** — don't cross filesystem boundaries (unix/macOS only)
- **`--onedrive-access-scopes SpaceSepList`** — set the scopes rclone should request (default `Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access`)
- **`--onedrive-auth-url string`** — auth server URL
- **`--onedrive-av-override`** — lets you download files the server swears have a virus 💀
- **`--onedrive-chunk-size SizeSuffix`** — chunk size for uploading files; **must be a multiple of 320k (327,680 bytes)** (default `10Mi`)
- **`--onedrive-client-credentials`** — use the client credentials OAuth flow
- **`--onedrive-client-id string`** — OAuth Client Id
- **`--onedrive-client-secret string`** — OAuth Client Secret
- **`--onedrive-delta`** — when set, rclone uses delta listing to do recursive listings
- **`--onedrive-description string`** — description of the remote
- **`--onedrive-drive-id string`** — the ID of the drive to use
- **`--onedrive-drive-type string`** — the type of the drive (`personal | business | documentLibrary`)
- **`--onedrive-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8,Dot`)
- **`--onedrive-expose-onenote-files`** — set this to make OneNote files actually show up in directory listings ✨
- **`--onedrive-hard-delete`** — permanently delete files when you remove them
- **`--onedrive-hash-type string`** — specify which hash the backend is using (default `"auto"`)
- **`--onedrive-link-password string`** — set the password for links made by the link command
- **`--onedrive-link-scope string`** — set the scope of links made by the link command (default `"anonymous"`)
- **`--onedrive-link-type string`** — set the type of links made by the link command (default `"view"`)
- **`--onedrive-list-chunk int`** — size of the listing chunk (default `1000`)
- **`--onedrive-metadata-permissions Bits`** — control whether permissions get read or written in metadata (default `off`)
- **`--onedrive-no-versions`** — remove all versions on modifying operations
- **`--onedrive-region string`** — pick the national cloud region for OneDrive (default `"global"`)
- **`--onedrive-root-folder-id string`** — ID of the root folder
- **`--onedrive-server-side-across-configs`** — ⚠️ **Deprecated**: use `--server-side-across-configs` instead
- **`--onedrive-tenant string`** — ID of the service principal's tenant. Also called its directory ID
- **`--onedrive-token string`** — OAuth Access Token as a JSON blob
- **`--onedrive-token-url string`** — token server url
- **`--oos-attempt-resume-upload`** — if true, try to resume a previously started multipart upload for the object
- **`--oos-chunk-size SizeSuffix`** — chunk size to use for uploading (default `5Mi`)
- **`--oos-compartment string`** — specify the compartment OCID, needed if you're listing buckets
- **`--oos-config-file string`** — path to the OCI config file (default `"~/.oci/config"`)
- **`--oos-config-profile string`** — profile name inside that oci config file (default `"Default"`)
- **`--oos-copy-cutoff SizeSuffix`** — cutoff for switching to multipart copy (default `4.656Gi`)
- **`--oos-copy-timeout Duration`** — timeout for copy (default `1m0s`)
- **`--oos-description string`** — description of the remote 🌸
- **`--oos-disable-checksum`** — don't store the MD5 checksum with object metadata
- **`--oos-encoding Encoding`** — the encoding for the backend (default `Slash,InvalidUtf8,Dot`)
- **`--oos-endpoint string`** — endpoint for the Object storage API
- **`--oos-leave-parts-on-error`** — if true, don't call abort upload on a failure; every successfully uploaded part is left behind for you to recover by hand 🫠
- **`--oos-max-upload-parts int`** — maximum number of parts in a multipart upload (default `10000`)
- **`--oos-namespace string`** — Object storage namespace
- **`--oos-no-check-bucket`** — if set, don't bother checking that the bucket exists or trying to create it
- **`--oos-provider string`** — choose your Auth Provider (default `"env_auth"`)
- **`--oos-region string`** — Object storage Region
- **`--oos-sse-customer-algorithm string`** — if you're using SSE-C, this optional header specifies `"AES256"` as the encryption algorithm
- **`--oos-sse-customer-key string`** — to use SSE-C, the optional header that specifies the base64-encoded 256-bit encryption key to use to
- **`--oos-sse-customer-key-file string`** — to use SSE-C, a file containing the base64-encoded string of the AES-256 encryption key associated
- **`--oos-sse-customer-key-sha256 string`** — if using SSE-C, the optional header that specifies the base64-encoded SHA256 hash of the encryption
- **`--oos-sse-kms-key-id string`** — if using your own master key in vault, this header specifies the
- **`--oos-storage-tier string`** — the storage class to use when storing new objects in storage. `https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/understandingstoragetiers.htm` (default `"Standard"`)
- **`--oos-upload-concurrency int`** — concurrency for multipart uploads (default `10`)
- **`--oos-upload-cutoff SizeSuffix`** — cutoff for switching to chunked upload (default `200Mi`)

> fr fr the last few `--oos-sse-*` lines just end mid-sentence in the source page — that's not me being chaotic (for once), that's genuinely how they're written 😭

- **`--opendrive-chunk-size SizeSuffix`** — files get uploaded in chunks of exactly this size (default `10Mi`) 🧩
- **`--opendrive-description string`** — a lil description of the remote, purely for your own reference
- **`--opendrive-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,LeftSpace,LeftCrLfHtVt,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot`)
- **`--opendrive-password string`** — your password, and yes bestie it's obscured 🔒
- **`--opendrive-username string`** — your username, iconic as always

- **`--pcloud-auth-url string`** — the Auth server URL 🌐
- **`--pcloud-client-credentials`** — flip this on to use the client credentials OAuth flow
- **`--pcloud-client-id string`** — your OAuth Client Id
- **`--pcloud-client-secret string`** — your OAuth Client Secret, keep it secret fr
- **`--pcloud-description string`** — description of the remote
- **`--pcloud-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--pcloud-hostname string`** — the hostname to connect to (default `"api.pcloud.com"`)
- **`--pcloud-password string`** — your pcloud password (obscured 🤫)
- **`--pcloud-root-folder-id string`** — fill this in if you want rclone to start somewhere that isn't the root folder (default `"d0"`)
- **`--pcloud-token string`** — OAuth Access Token, handed over as a JSON blob
- **`--pcloud-token-url string`** — the Token server url
- **`--pcloud-username string`** — your pcloud username

- **`--pikpak-chunk-size SizeSuffix`** — chunk size for multipart uploads (default `5Mi`)
- **`--pikpak-description string`** — description of the remote
- **`--pikpak-device-id string`** — the Device ID used for authorization 🪪
- **`--pikpak-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,LeftSpace,RightSpace,RightPeriod,InvalidUtf8,Dot`)
- **`--pikpak-hash-memory-limit SizeSuffix`** — any file bigger than this gets cached to disk when a hash needs calculating (default `10Mi`)
- **`--pikpak-no-media-link`** — use the original file links instead of media links, no cap
- **`--pikpak-pass string`** — Pikpak password (obscured)
- **`--pikpak-root-folder-id string`** — the ID of the root folder
- **`--pikpak-trashed-only`** — only show files that are chillin' in the trash 🗑️
- **`--pikpak-upload-concurrency int`** — concurrency for multipart uploads (default `5`)
- **`--pikpak-use-trash`** — send files to the trash instead of yeeting them permanently (default `true`)
- **`--pikpak-user string`** — Pikpak username
- **`--pikpak-user-agent string`** — HTTP user agent for pikpak (default `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:129.0) Gecko/20100101 Firefox/129.0"`)

- **`--pixeldrain-api-key string`** — API key for your pixeldrain account
- **`--pixeldrain-api-url string`** — the API endpoint to connect to; in the vast majority of cases it's fine to leave it alone (default `"https://pixeldrain.com/api"`)
- **`--pixeldrain-description string`** — description of the remote
- **`--pixeldrain-root-folder-id string`** — root of the filesystem to use (default `"me"`) ✨

- **`--premiumizeme-auth-url string`** — Auth server URL
- **`--premiumizeme-client-credentials`** — use the client credentials OAuth flow
- **`--premiumizeme-client-id string`** — OAuth Client Id
- **`--premiumizeme-client-secret string`** — OAuth Client Secret
- **`--premiumizeme-description string`** — description of the remote
- **`--premiumizeme-encoding Encoding`** — the encoding for the backend (default `Slash,DoubleQuote,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--premiumizeme-token string`** — OAuth Access Token as a JSON blob
- **`--premiumizeme-token-url string`** — token server url

- **`--protondrive-2fa string`** — the 2FA code 🔐
- **`--protondrive-app-version string`** — the app version string (default `"macos-drive@1.0.0-alpha.1+rclone"`)
- **`--protondrive-description string`** — description of the remote
- **`--protondrive-enable-caching`** — caches the files and folders metadata so we make fewer API calls (default `true`)
- **`--protondrive-encoding Encoding`** — the encoding for the backend (default `Slash,LeftSpace,RightSpace,InvalidUtf8,Dot`)
- **`--protondrive-mailbox-password string`** — the mailbox password of your two-password proton account (obscured)
- **`--protondrive-original-file-size`** — return the file size before encryption (default `true`)
- **`--protondrive-password string`** — the password of your proton account (obscured)
- **`--protondrive-replace-existing-draft`** — create a new revision whenever a filename conflict pops up
- **`--protondrive-username string`** — the username of your proton account

- **`--putio-auth-url string`** — Auth server URL
- **`--putio-client-credentials`** — use the client credentials OAuth flow
- **`--putio-client-id string`** — OAuth Client Id
- **`--putio-client-secret string`** — OAuth Client Secret
- **`--putio-description string`** — description of the remote
- **`--putio-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--putio-token string`** — OAuth Access Token as a JSON blob
- **`--putio-token-url string`** — token server url

- **`--qingstor-access-key-id string`** — QingStor Access Key ID
- **`--qingstor-chunk-size SizeSuffix`** — chunk size to use for uploading (default `4Mi`)
- **`--qingstor-connection-retries int`** — how many connection retries to do (default `3`)
- **`--qingstor-description string`** — description of the remote
- **`--qingstor-encoding Encoding`** — the encoding for the backend (default `Slash,Ctl,InvalidUtf8`)
- **`--qingstor-endpoint string`** — drop in an endpoint URL to connect to the QingStor API
- **`--qingstor-env-auth`** — grab QingStor credentials from the runtime
- **`--qingstor-secret-access-key string`** — QingStor Secret Access Key (it's the password)
- **`--qingstor-upload-concurrency int`** — concurrency for multipart uploads (default `1`)
- **`--qingstor-upload-cutoff SizeSuffix`** — the cutoff for switching over to chunked upload (default `200Mi`)
- **`--qingstor-zone string`** — the zone to connect to

- **`--quatrix-api-key string`** — API key for accessing your Quatrix account
- **`--quatrix-description string`** — description of the remote
- **`--quatrix-effective-upload-time string`** — the wanted upload time for one chunk (default `"4s"`) ⏱️
- **`--quatrix-encoding Encoding`** — the encoding for the backend (default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--quatrix-hard-delete`** — delete files permanently instead of dropping them into the trash
- **`--quatrix-host string`** — the host name of your Quatrix account
- **`--quatrix-maximal-summary-chunk-size SizeSuffix`** — the maximal summary for all the chunks; it should **not** be less than `'transfers'`*`'minimal_chunk_size'` (default `95.367Mi`)
- **`--quatrix-minimal-chunk-size SizeSuffix`** — the minimal size for one single chunk (default `9.537Mi`)
- **`--quatrix-skip-project-folders`** — skip project folders during operations, no thoughts just vibes

- **`--s3-access-key-id string`** — AWS Access Key ID
- **`--s3-acl string`** — the Canned ACL used when creating buckets and when storing or copying objects
- **`--s3-bucket-acl string`** — the Canned ACL used when creating buckets
- **`--s3-chunk-size SizeSuffix`** — chunk size to use for uploading (default `5Mi`)
- **`--s3-copy-cutoff SizeSuffix`** — the cutoff for switching over to multipart copy (default `4.656Gi`)
- **`--s3-decompress`** — set this and rclone will decompress gzip encoded objects 🫧
- **`--s3-description string`** — description of the remote
- **`--s3-directory-bucket`** — set this to use AWS Directory Buckets
- **`--s3-directory-markers`** — upload an empty object with a trailing slash whenever a new directory gets created
- **`--s3-disable-checksum`** — don't store the MD5 checksum with object metadata
- **`--s3-disable-http2`** — disable usage of http2 for S3 backends
- **`--s3-download-url string`** — a custom endpoint for downloads
- **`--s3-encoding Encoding`** — the encoding for the backend (default `Slash,InvalidUtf8,Dot`)
- **`--s3-endpoint string`** — endpoint for the S3 API
- **`--s3-env-auth`** — get AWS credentials from the runtime (environment variables, or EC2/ECS meta data if there are no env vars)
- **`--s3-force-path-style`** — if true use path style access, if false use virtual hosted style (default `true`)
- **`--s3-leave-parts-on-error`** — if true, avoid calling abort upload on a failure, leaving all the successfully uploaded parts just sitting on S3 for manual recovery 👀
- **`--s3-list-chunk int`** — size of the listing chunk (the response list for each ListObject S3 request) (default `1000`)
- **`--s3-list-url-encode Tristate`** — whether to url encode listings: `true`/`false`/`unset` (default `unset`)

- **`--s3-list-version int`** — which version of ListObjects we're using: `1`, `2`, or `0` to just let rclone figure it out ✨
- **`--s3-location-constraint string`** — the Location constraint, and bestie it has to match your Region, no cap
- **`--s3-max-upload-parts int`** — max number of parts allowed in one multipart upload (default `10000`)
- **`--s3-might-gzip Tristate`** — flip this on if the backend might be sneaking gzip on your objects (default `unset`)
- **`--s3-no-check-bucket`** — if set, rclone won't even try to check whether the bucket exists or create it 🙈
- **`--s3-no-head`** — if set, rclone skips the HEAD on uploaded objects, so no integrity check, just vibes
- **`--s3-no-head-object`** — if set, rclone won't do a HEAD before the GET when pulling objects down
- **`--s3-no-system-metadata`** — suppresses both setting <italic>and</italic> reading of system metadata
- **`--s3-profile string`** — which profile to use in the shared credentials file
- **`--s3-provider string`** — pick your S3 provider, your choice your power 💅
- **`--s3-region string`** — the Region to connect to
- **`--s3-requester-pays`** — turns on the requester pays option when you're interacting with an S3 bucket
- **`--s3-sdk-log-mode Bits`** — set this to debug the SDK (default `Off`)
- **`--s3-secret-access-key string`** — your AWS Secret Access Key (that's the password, keep it secret, fr fr 🔐)
- **`--s3-server-side-encryption string`** — the server-side encryption algorithm used when storing this object in S3
- **`--s3-session-token string`** — an AWS session token
- **`--s3-shared-credentials-file string`** — path to the shared credentials file
- **`--s3-sse-customer-algorithm string`** — if you're doing SSE-C, this is the server-side encryption algorithm used when storing this object in S3
- **`--s3-sse-customer-key string`** — for SSE-C you may hand over the secret encryption key used to encrypt/decrypt your data
- **`--s3-sse-customer-key-base64 string`** — if using SSE-C you <bold>must</bold> provide the secret encryption key in base64 format to encrypt/decrypt your data
- **`--s3-sse-customer-key-md5 string`** — for SSE-C you may also give the MD5 checksum of the secret encryption key (optional, no pressure)
- **`--s3-sse-kms-key-id string`** — if you're using a KMS ID you must provide the ARN of the Key
- **`--s3-storage-class string`** — the storage class to use when storing new objects in S3
- **`--s3-upload-concurrency int`** — concurrency for multipart uploads and copies (default `4`)
- **`--s3-upload-cutoff SizeSuffix`** — the cutoff for switching over to chunked upload (default `200Mi`)
- **`--s3-use-accelerate-endpoint`** — if true, use the AWS S3 accelerated endpoint 🚀
- **`--s3-use-accept-encoding-gzip Accept-Encoding: gzip`** — whether to send the `Accept-Encoding: gzip` header (default `unset`)
- **`--s3-use-already-exists Tristate`** — set this if rclone should be reporting `BucketAlreadyExists` errors on bucket creation (default `unset`)
- **`--s3-use-dual-stack`** — if true, use the AWS S3 dual-stack endpoint (that's IPv6 support, bestie 🌈)
- **`--s3-use-multipart-etag Tristate`** — whether to use the ETag in multipart uploads for verification (default `unset`)
- **`--s3-use-multipart-uploads Tristate`** — set this if rclone should use multipart uploads (default `unset`)
- **`--s3-use-presigned-request`** — whether to use a presigned request or `PutObject` for single part uploads
- **`--s3-use-unsigned-payload Tristate`** — whether to use an unsigned payload in `PutObject` (default `unset`)
- **`--s3-v2-auth`** — if true, use v2 authentication
- **`--s3-version-at Time`** — show file versions exactly as they were at the specified time (default `off`)
- **`--s3-version-deleted`** — show deleted file markers when you're using versions 👻
- **`--s3-versions`** — include old versions in directory listings
- **`--seafile-2fa`** — two-factor authentication (`'true'` if the account has 2FA enabled)
- **`--seafile-create-library`** — should rclone create a library if it doesn't already exist
- **`--seafile-description string`** — description of the remote
- **`--seafile-encoding Encoding`** — the encoding for the backend (default `Slash,DoubleQuote,BackSlash,Ctl,InvalidUtf8`)
- **`--seafile-library string`** — name of the library
- **`--seafile-library-key string`** — library password, for encrypted libraries only (obscured) 🔒
- **`--seafile-pass string`** — password (obscured)
- **`--seafile-url string`** — URL of the seafile host to connect to
- **`--seafile-user string`** — user name (usually your email address)
- **`--sftp-ask-password`** — allow rclone to ask for the SFTP password when it needs one
- **`--sftp-chunk-size SizeSuffix`** — upload and download chunk size (default `32Ki`)
- **`--sftp-ciphers SpaceSepList`** — space separated list of ciphers to be used for session encryption, ordered by preference
- **`--sftp-concurrency int`** — the maximum number of outstanding requests for one file (default `64`)
- **`--sftp-connections int`** — maximum number of SFTP simultaneous connections, `0` for unlimited
- **`--sftp-copy-is-hardlink`** — set this to enable server side copies using hardlinks
- **`--sftp-description string`** — description of the remote
- **`--sftp-disable-concurrent-reads`** — if set, no concurrent reads, we're keeping it chill
- **`--sftp-disable-concurrent-writes`** — if set, no concurrent writes either
- **`--sftp-disable-hashcheck`** — disables running SSH commands to figure out whether remote file hashing is available
- **`--sftp-host string`** — SSH host to connect to
- **`--sftp-host-key-algorithms SpaceSepList`** — space separated list of host key algorithms, ordered by preference
- **`--sftp-idle-timeout Duration`** — max time before idle connections get closed (default `1m0s`)
- **`--sftp-key-exchange SpaceSepList`** — space separated list of key exchange algorithms, ordered by preference
- **`--sftp-key-file string`** — path to the PEM-encoded private key file
- **`--sftp-key-file-pass string`** — the passphrase to decrypt that PEM-encoded private key file (obscured)
- **`--sftp-key-pem string`** — raw PEM-encoded private key
- **`--sftp-key-use-agent`** — when set, it forces the usage of the ssh-agent
- **`--sftp-known-hosts-file string`** — optional path to the `known_hosts` file
- **`--sftp-macs SpaceSepList`** — space separated list of MACs (message authentication code) algorithms, ordered by preference
- **`--sftp-md5sum-command string`** — the command used to read md5 hashes
- **`--sftp-pass string`** — SSH password, leave it blank to use ssh-agent (obscured)
- **`--sftp-path-override string`** — override the path used by SSH shell commands
- **`--sftp-port int`** — SSH port number (default `22`)
- **`--sftp-pubkey string`** — SSH public certificate, for public certificate based authentication
- **`--sftp-pubkey-file string`** — optional path to the public key file
- **`--sftp-server-command string`** — specifies the path or command to run a sftp server on the remote host
- **`--sftp-set-env SpaceSepList`** — environment variables to pass to sftp and commands
- **`--sftp-set-modtime`** — set the modified time on the remote if set (default `true`)
- **`--sftp-sha1sum-command string`** — the command used to read sha1 hashes
- **`--sftp-shell-type string`** — the type of SSH shell on the remote server, if there is one
- **`--sftp-skip-links`** — set this to skip any symlinks and any other non regular files, we don't have time 🫶
- **`--sftp-socks-proxy string`** — Socks 5 proxy host
- **`--sftp-ssh SpaceSepList`** — path and arguments to the external ssh binary
- **`--sftp-subsystem string`** — specifies the SSH2 subsystem on the remote host (default `"sftp"`)
- **`--sftp-use-fstat`** — if set, use `fstat` instead of `stat`
- **`--sftp-use-insecure-cipher`** — enables the use of insecure ciphers and key exchange methods ⚠️ (it literally says insecure, bestie, proceed with intention)
- **`--sftp-user string`** — SSH username (default `"$USER"`)
- **`--sharefile-auth-url string`** — Auth server URL
- **`--sharefile-chunk-size SizeSuffix`** — upload chunk size (default `64Mi`)
- **`--sharefile-client-credentials`** — use the client credentials OAuth flow
- **`--sharefile-client-id string`** — OAuth Client Id
- **`--sharefile-client-secret string`** — OAuth Client Secret
- **`--sharefile-description string`** — description of the remote
- **`--sharefile-encoding Encoding`** — the encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,LeftSpace,LeftPeriod,RightSpace,RightPeriod,InvalidUtf8,Dot`)
- **`--sharefile-endpoint string`** — endpoint for API calls
- **`--sharefile-root-folder-id string`** — ID of the root folder
- **`--sharefile-token string`** — OAuth Access Token as a JSON blob
- **`--sharefile-token-url string`** — token server url
- **`--sharefile-upload-cutoff SizeSuffix`** — cutoff for switching to multipart upload (default `128Mi`)

---

- **`--sia-api-password`** *string* — the Sia Daemon API Password, and yes bestie it's **obscured** 🔒 (so rclone hides it from nosy lil eyes)
- **`--sia-api-url`** *string* — Sia daemon API URL, like `http://sia.daemon.host:9980` (default `"http://127.0.0.1:9980"`)
- **`--sia-description`** *string* — Description of the remote 📝
- **`--sia-encoding`** *Encoding* — The encoding for the backend (default `Slash,Question,Hash,Percent,Del,Ctl,InvalidUtf8,Dot`)
- **`--sia-user-agent`** *string* — Siad User Agent (default `"Sia-Agent"`) 🕵️
- **`--skip-links`** — Don't warn about skipped symlinks. lowkey silencing the lil symlink drama 🦋
- **`--smb-case-insensitive`** — Whether the server is configured to be case-insensitive (default `true`)
- **`--smb-description`** *string* — Description of the remote
- **`--smb-domain`** *string* — Domain name for NTLM authentication (default `"WORKGROUP"`)
- **`--smb-encoding`** *Encoding* — The encoding for the backend (default `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot`)
- **`--smb-hide-special-share`** — Hide special shares (e.g. `print$`) which users aren't supposed to access (default `true`) 🙈
- **`--smb-host`** *string* — SMB server hostname to connect to
- **`--smb-idle-timeout`** *Duration* — Max time before closing idle connections (default `1m0s`)
- **`--smb-pass`** *string* — SMB password (**obscured**)
- **`--smb-port`** *int* — SMB port number (default `445`)
- **`--smb-spn`** *string* — Service principal name
- **`--smb-user`** *string* — SMB username (default `"$USER"`)
- **`--storj-access-grant`** *string* — Access grant
- **`--storj-api-key`** *string* — API key
- **`--storj-description`** *string* — Description of the remote
- **`--storj-passphrase`** *string* — Encryption passphrase 🔐
- **`--storj-provider`** *string* — Choose an authentication method (default `"existing"`)
- **`--storj-satellite-address`** *string* — Satellite address (default `"us1.storj.io"`) 🛰️
- **`--sugarsync-access-key-id`** *string* — Sugarsync Access Key ID
- **`--sugarsync-app-id`** *string* — Sugarsync App ID
- **`--sugarsync-authorization`** *string* — Sugarsync authorization
- **`--sugarsync-authorization-expiry`** *string* — Sugarsync authorization expiry
- **`--sugarsync-deleted-id`** *string* — Sugarsync deleted folder id
- **`--sugarsync-description`** *string* — Description of the remote
- **`--sugarsync-encoding`** *Encoding* — The encoding for the backend (default `Slash,Ctl,InvalidUtf8,Dot`)
- **`--sugarsync-hard-delete`** — Permanently delete files if true 💀 (no recycle bin, no take-backs)
- **`--sugarsync-private-access-key`** *string* — Sugarsync Private Access Key
- **`--sugarsync-refresh-token`** *string* — Sugarsync refresh token
- **`--sugarsync-root-id`** *string* — Sugarsync root id
- **`--sugarsync-user`** *string* — Sugarsync user
- **`--swift-application-credential-id`** *string* — Application Credential ID (`OS_APPLICATION_CREDENTIAL_ID`)
- **`--swift-application-credential-name`** *string* — Application Credential Name (`OS_APPLICATION_CREDENTIAL_NAME`)
- **`--swift-application-credential-secret`** *string* — Application Credential Secret (`OS_APPLICATION_CREDENTIAL_SECRET`)
- **`--swift-auth`** *string* — Authentication URL for server (`OS_AUTH_URL`)
- **`--swift-auth-token`** *string* — Auth Token from alternate authentication - optional (`OS_AUTH_TOKEN`)
- **`--swift-auth-version`** *int* — AuthVersion - optional - set to (1,2,3) if your auth URL has no version (`ST_AUTH_VERSION`)
- **`--swift-chunk-size`** *SizeSuffix* — Above this size files will be chunked (default `5Gi`)
- **`--swift-description`** *string* — Description of the remote
- **`--swift-domain`** *string* — User domain - optional (v3 auth) (`OS_USER_DOMAIN_NAME`)
- **`--swift-encoding`** *Encoding* — The encoding for the backend (default `Slash,InvalidUtf8`)
- **`--swift-endpoint-type`** *string* — Endpoint type to choose from the service catalogue (`OS_ENDPOINT_TYPE`) (default `"public"`)
- **`--swift-env-auth`** — Get swift credentials from environment variables in standard OpenStack form 🌱
- **`--swift-fetch-until-empty-page`** — When paginating, always fetch unless we received an empty page
- **`--swift-key`** *string* — API key or password (`OS_PASSWORD`)
- **`--swift-leave-parts-on-error`** — If true avoid calling abort upload on a failure
- **`--swift-no-chunk`** — Don't chunk files during streaming upload
- **`--swift-no-large-objects`** — Disable support for static and dynamic large objects
- **`--swift-partial-page-fetch-threshold`** *int* — When paginating, fetch if the current page is within this percentage of the limit
- **`--swift-region`** *string* — Region name - optional (`OS_REGION_NAME`)
- **`--swift-storage-policy`** *string* — The storage policy to use when creating a new container
- **`--swift-storage-url`** *string* — Storage URL - optional (`OS_STORAGE_URL`)
- **`--swift-tenant`** *string* — Tenant name - optional for v1 auth, this or tenant_id required otherwise (`OS_TENANT_NAME` or `OS_PROJECT_NAME`)
- **`--swift-tenant-domain`** *string* — Tenant domain - optional (v3 auth) (`OS_PROJECT_DOMAIN_NAME`)
- **`--swift-tenant-id`** *string* — Tenant ID - optional for v1 auth, this or tenant required otherwise (`OS_TENANT_ID`)
- **`--swift-use-segments-container`** *Tristate* — Choose destination for large object segments (default `unset`)
- **`--swift-user`** *string* — User name to log in (`OS_USERNAME`)
- **`--swift-user-id`** *string* — User ID to log in - optional - most swift systems use user and leave this blank (v3 auth) (`OS_USER_ID`)
- **`--ulozto-app-token`** *string* — The application token identifying the app. An app API key can be either found in the API
- **`--ulozto-description`** *string* — Description of the remote
- **`--ulozto-encoding`** *Encoding* — The encoding for the backend (default `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`)
- **`--ulozto-list-page-size`** *int* — The size of a single page for list commands. 1-500 (default `500`)
- **`--ulozto-password`** *string* — The password for the user (**obscured**)
- **`--ulozto-root-folder-slug`** *string* — If set, rclone will use this folder as the root folder for all operations. For example,
- **`--ulozto-username`** *string* — The username of the principal to operate as
- **`--union-action-policy`** *string* — Policy to choose upstream on ACTION category (default `"epall"`)
- **`--union-cache-time`** *int* — Cache time of usage and free space (in seconds) (default `120`)
- **`--union-create-policy`** *string* — Policy to choose upstream on CREATE category (default `"epmfs"`)
- **`--union-description`** *string* — Description of the remote
- **`--union-min-free-space`** *SizeSuffix* — Minimum viable free space for lfs/eplfs policies (default `1Gi`)
- **`--union-search-policy`** *string* — Policy to choose upstream on SEARCH category (default `"ff"`)
- **`--union-upstreams`** *string* — List of space separated upstreams
- **`--uptobox-access-token`** *string* — Your access token
- **`--uptobox-description`** *string* — Description of the remote
- **`--uptobox-encoding`** *Encoding* — The encoding for the backend (default `Slash,LtGt,DoubleQuote,BackQuote,Del,Ctl,LeftSpace,InvalidUtf8,Dot`)
- **`--uptobox-private`** — Set to make uploaded files private 🫣
- **`--webdav-auth-redirect`** — Preserve authentication on redirect
- **`--webdav-bearer-token`** *string* — Bearer token instead of user/pass (e.g. a Macaroon) 🍪
- **`--webdav-bearer-token-command`** *string* — Command to run to get a bearer token
- **`--webdav-description`** *string* — Description of the remote
- **`--webdav-encoding`** *string* — The encoding for the backend
- **`--webdav-headers`** *CommaSepList* — Set HTTP headers for all transactions
- **`--webdav-nextcloud-chunk-size`** *SizeSuffix* — Nextcloud upload chunk size (default `10Mi`)
- **`--webdav-owncloud-exclude-mounts`** — Exclude ownCloud mounted storages
- **`--webdav-owncloud-exclude-shares`** — Exclude ownCloud shares
- **`--webdav-pacer-min-sleep`** *Duration* — Minimum time to sleep between API calls (default `10ms`) 😴
- **`--webdav-pass`** *string* — Password (**obscured**)
- **`--webdav-unix-socket`** *string* — Path to a unix domain socket to dial to, instead of opening a TCP connection directly
- **`--webdav-url`** *string* — URL of http host to connect to
- **`--webdav-user`** *string* — User name
- **`--webdav-vendor`** *string* — Name of the WebDAV site/service/software you are using
- **`--yandex-auth-url`** *string* — Auth server URL
- **`--yandex-client-credentials`** — Use client credentials OAuth flow
- **`--yandex-client-id`** *string* — OAuth Client Id

- **`--yandex-client-secret string`** — your OAuth Client Secret 🙈 pls keep it secret
- **`--yandex-description string`** — a lil description of the remote, just for you
- **`--yandex-encoding Encoding`** — the encoding for the backend (default `Slash,Del,Ctl,InvalidUtf8,Dot`)
- **`--yandex-hard-delete`** — delete files permanently instead of yeeting them into the trash 🗑️
- **`--yandex-spoof-ua`** — sets the user agent to match an official version of the yandex disk client. may help with upload performance (default `true`)
- **`--yandex-token string`** — OAuth Access Token as a JSON blob
- **`--yandex-token-url string`** — the token server url
- **`--zoho-auth-url string`** — Auth server URL
- **`--zoho-client-credentials`** — use the client credentials OAuth flow
- **`--zoho-client-id string`** — OAuth Client Id
- **`--zoho-client-secret string`** — OAuth Client Secret 🙈
- **`--zoho-description string`** — description of the remote
- **`--zoho-encoding Encoding`** — the encoding for the backend (default `Del,Ctl,InvalidUtf8`)
- **`--zoho-region string`** — the Zoho region to connect to
- **`--zoho-token string`** — OAuth Access Token as a JSON blob
- **`--zoho-token-url string`** — the token server url
- **`--zoho-upload-cutoff SizeSuffix`** — the cutoff for switching to the large file upload api (>= 10 MiB) (default `10Mi`)

---

# 🐳 Docker Volume Plugin 🐳

## ✨ Introduction ✨

Docker 1.9 added support for making named volumes through the command-line interface and mounting them inside containers, as a whole way to share data between them. And ever since Docker 1.10 you can create named volumes with Docker Compose by describing them in `docker-compose.yml` files, so container groups on a single host can use them 🫶. Then as of Docker 1.12, volumes got supported by Docker Swarm — the one bundled with Docker Engine — created from descriptions in swarm compose v3 files, so you can use them with swarm stacks across multiple cluster nodes. iconic behaviour honestly.

Docker Volume Plugins are the glow-up on top of the default local volume driver that ships with Docker: they add stateful volumes shared across containers **and** hosts. And unlike local volumes, your data does **not** get deleted when that volume is removed 💅 (yes really, it stays). Plugins can run managed by the docker daemon, as a native system service (under systemd, sysv or upstart), or as a standalone executable. Rclone can run as a docker volume plugin in all of those modes. It talks to the local docker daemon via the plugin API and handles mounting remote file systems into docker containers, so it **must** run on the same host as the docker daemon, or on every Swarm node. no cap.

## 🌸 Getting started 🌸

First example: we're using the SFTP rclone volume with Docker engine on a standalone Ubuntu machine. let's go.

Start by installing Docker on the host.

The FUSE driver is a prerequisite for rclone mounting and should be installed on the host:

sudo apt-get -y install fuse3


Create the two directories the rclone docker plugin needs:

sudo mkdir -p /var/lib/docker-plugins/rclone/config sudo mkdir -p /var/lib/docker-plugins/rclone/cache


Install the managed rclone docker plugin for your architecture (here, `amd64`):

docker plugin install rclone/docker-volume-rclone:amd64 args="-v" --alias rclone --grant-all-permissions docker plugin list


Now make your SFTP volume:

docker volume create firstvolume -d rclone -o type=sftp -o sftp-host=_hostname_ -o sftp-user=_username_ -o sftp-pass=_password_ -o allow-other=true


Heads up bestie: since **all** the options are static, you don't even have to run `rclone config` or create the `rclone.conf` file (but the config directory should still be there, okay?). In the simplest case you can use `localhost` as the hostname and your SSH credentials as username and password. You can also change the remote path to your home directory on the host, for example `-o path=/home/username`.

Time to create a test container and mount the volume into it 🎀:

docker run --rm -it -v firstvolume:/mnt --workdir /mnt ubuntu:latest bash


If everything goes right, you'll drop into the new container and land right in the mounted SFTP remote. You can type `ls` to list the mounted directory or just play around with it. Type `exit` when you're done. The container will stop, but the volume stays — ready to be reused. When you don't need it anymore, remove it:

docker volume list docker volume remove firstvolume


Now let's try something more elaborate: a Google Drive volume on multi-node Docker Swarm. main character energy fr.

You should start from installing Docker and FUSE, creating the plugin directories and installing the rclone plugin on **every** swarm node. Then set up the Swarm.

Google Drive volumes need an access token, which can be set up via a web browser and will be periodically renewed by rclone. The managed plugin can't run a browser, so we'll use a technique similar to the rclone setup on a headless box.

Run `rclone config` on another machine that has a web browser and a graphical user interface. Create the Google Drive remote. When you're done, move the resulting `rclone.conf` over to the Swarm cluster and save it as `/var/lib/docker-plugins/rclone/config/rclone.conf` on every node. By default this location is only accessible to the `root` user, so you'll need the appropriate privileges. The resulting config will look like this:

[gdrive] type = drive scope = drive drive_id = 1234567... root_folder_id = 0Abcd... token = {"access_token":...}


Now create a file named `example.yml` with a swarm stack description like this:

version: '3' services: heimdall: image: linuxserver/heimdall:latest ports: [8080:80] volumes: [configdata:/config] volumes: configdata: driver: rclone driver_opts: remote: 'gdrive:heimdall' allow_other: 'true' vfs_cache_mode: full poll_interval: 0


and run the stack:

docker stack deploy example -c ./example.yml


After a few seconds docker will spread the parsed stack description across the cluster, create the `example_heimdall` service on port `8080`, run service containers on one or more cluster nodes and request the `example_configdata` volume from the rclone plugins on the node hosts. You can use these commands to confirm the results:

docker service ls docker service ps example_heimdall docker volume ls


Point your browser at `http://cluster.host.address:8080` and play with the service. Stop it with `docker stack remove example` when you're done. Note that the `example_configdata` volume(s) created on demand at the cluster nodes will **not** be automatically removed together with the stack — they stay for future reuse 🫶. You can remove them manually by running the `docker volume remove example_configdata` command on every node.

## 💅 Creating Volumes via CLI 💅

Volumes can be created with `docker volume create`. Here are a few examples:

docker volume create vol1 -d rclone -o remote=storj: -o vfs-cache-mode=full docker volume create vol2 -d rclone -o remote=:storj,access_grant=xxx:heimdall docker volume create vol3 -d rclone -o type=storj -o path=heimdall -o storj-access-grant=xxx -o poll-interval=0


Notice the `-d rclone` flag — that's what tells docker to request the volume from the rclone driver. This works even if you installed the managed driver by its full name `rclone/docker-volume-rclone`, because you passed the `--alias rclone` option. slay.

Volumes can be inspected like this:

docker volume list docker volume inspect vol1


## 🎀 Volume Configuration 🎀

Rclone flags and volume options are set via the `-o` flag to the `docker volume create` command. They include backend-specific parameters as well as mount and VFS options. There are also a few special `-o` options: `remote`, `fs`, `type`, `path`, `mount-type` and `persist`.

`remote` determines an existing remote name from the config file, with a trailing colon and optionally with a remote path. See the full syntax in the rclone documentation. This option can be aliased as `fs` to prevent confusion with the `remote` parameter of backends like `crypt` or `alias`.

The `remote=:backend:dir/subdir` syntax can be used to create on-the-fly (config-less) remotes, while the `type` and `path` options give you a simpler alternative for the same thing. Using two split options

-o type=backend -o path=dir/subdir


is equivalent to the combined syntax

-o remote=:backend:dir/subdir


but is arguably easier to parameterize in scripts. The `path` part is optional.

Mount and VFS options, as well as backend parameters, are named like their twin command-line flags but without the `--` CLI prefix. Optionally you can use underscores instead of dashes in option names. For example, `--vfs-cache-mode full` becomes `-o vfs-cache-mode=full` or `-o vfs_cache_mode=full`. Boolean CLI flags without a value will gain the `true` value, e.g. `--allow-other` becomes `-o allow-other=true` or `-o allow_other=true`.

> Bestie, important: you can only provide parameters for the backend **immediately** referenced by the backend type of the mounted remote. If this is a wrapping backend like `alias`, `chunker` or `crypt`, you **cannot** provide options for the remote or backend it refers to. This limitation is imposed by the rclone connection string parser 😭. The only workaround is to feed the plugin with `rclone.conf` or configure the plugin arguments (see below).

## ⭐ Special Volume Options ⭐

`mount-type` determines the mount method and in general can be one of: `mount`, `cmount`, or `mount2`. This can be aliased as `mount_type`. It should be noted that the managed rclone docker plugin currently does **not** support the `cmount` method, and `mount2` is rarely needed. This option defaults to the first found method, which is usually `mount`, so you generally won't need it.

`persist` is a reserved boolean (`true`/`false`) option. In future it will allow persisting on-the-fly remotes in the plugin `rclone.conf` file. 👑 (future vibes only, for now.)

## 🦋 Connection Strings 🦋

The `remote` value can be extended with connection strings as an alternative way to supply backend parameters. This is equivalent to the `-o` backend options with one syntactic difference: inside a connection string the backend prefix must be **dropped** from parameter names, but in the `-o param=value` array it must be present. For instance, compare the following option array

-o remote=:sftp:/home -o sftp-host=localhost


with the equivalent connection string:

-o remote=:sftp,host=localhost:/home


Okay bestie, so why does this difference even exist? Because the flag options `-o key=val` don't *just* carry backend parameters — they also pack mount/VFS flags and possibly other settings too 💅. And on top of that, it lets you tell the `remote` option apart from the crypt-remote (or any similarly named backend parameter), and honestly it arguably makes scripting way simpler because the value substitution is so much clearer. Slay.

## 🌈 Using with Swarm or Compose

Both Docker Swarm and Docker Compose use YAML-formatted text files to describe groups (stacks) of containers, their properties, networks and volumes. Compose uses the compose v2 format, Swarm uses the compose v3 format. They're mostly similar, and the differences are explained in the docker documentation.

Volumes are described by the children of the top-level `volumes:` node. Each of them should be named after its volume and have at least two elements — the self-explanatory `driver: rclone` value, and the `driver_opts:` structure that plays the exact same role as `-o key=val` CLI flags:

volumes: volume_name_1: driver: rclone driver_opts: remote: 'gdrive:' allow_other: 'true' vfs_cache_mode: full token: '{"type": "borrower", "expires": "2021-12-31"}' poll_interval: 0


Now let's clock a few important details, fr fr:

- YAML prefers `_` in option names instead of `-`.
- YAML treats single and double quotes interchangeably. Simple strings and integers can be left unquoted.
- Boolean values must be quoted like `'true'` or `"false"` because these two words are reserved by YAML.
- The filesystem string is keyed with `remote` (or with `fs`). Normally you can omit quotes here, but if the string ends with colon, you must quote it like `remote: "storage_box:"`.
- YAML is picky about surrounding braces in values, as this is in fact another syntax for key/value mappings. For example, JSON access tokens usually contain double quotes and surrounding braces, so you must put them in single quotes.

## 👑 Installing as Managed Plugin

Docker daemon can install plugins from an image registry and run them managed. We maintain the `docker-volume-rclone` plugin image on Docker Hub.

Rclone volume plugin requires Docker Engine >= 19.03.15

The plugin requires presence of two directories on the host before it can be installed. Note that plugin will **not** create them automatically. By default they must exist on host at the following locations (though you can tweak the paths):

- `/var/lib/docker-plugins/rclone/config` is reserved for the `rclone.conf` config file and must exist even if it's empty and the config file is not present.
- `/var/lib/docker-plugins/rclone/cache` holds the plugin state file as well as optional VFS caches.

You can install managed plugin with default settings as follows:

docker plugin install rclone/docker-volume-rclone:amd64 --grant-all-permissions --alias rclone


The `:amd64` part of the image specification after colon is called a **tag**. Usually you will want to install the latest plugin for your architecture. In this case the tag will just name it, like `amd64` above. The following plugin architectures are currently available:

- `amd64`
- `arm64`
- `arm-v7`

Sometimes you might want a concrete plugin version, not the latest one. Then you should use image tag in the form `:ARCHITECTURE-VERSION`. For example, to install plugin version `v1.56.2` on architecture `arm64` you will use tag `arm64-1.56.2` (note the removed `v`) so the full image specification becomes `rclone/docker-volume-rclone:arm64-1.56.2`.

We also provide the `latest` plugin tag, but since docker does not support multi-architecture plugins as of the time of this writing, this tag is currently an alias for `amd64`. By convention the `latest` tag is the default one and can be omitted, thus both `rclone/docker-volume-rclone:latest` and just `rclone/docker-volume-rclone` will refer to the latest plugin release for the `amd64` platform.

Also the `amd64` part can be omitted from the versioned rclone plugin tags. For example, rclone image reference `rclone/docker-volume-rclone:amd64-1.56.2` can be abbreviated as `rclone/docker-volume-rclone:1.56.2` for convenience. However, for non-intel architectures you still have to use the full tag as `amd64` or `latest` will fail to start.

Managed plugin is in fact a special container running in a namespace separate from normal docker containers. Inside it runs the `rclone serve docker` command. The config and cache directories are bind-mounted into the container at start. The docker daemon connects to a unix socket created by the command inside the container. The command creates on-demand remote mounts right inside, then docker machinery propagates them through kernel mount namespaces and bind-mounts into requesting user containers.

You can tweak a few plugin settings after installation when it's disabled (not in use), for instance:

docker plugin disable rclone docker plugin set rclone RCLONE_VERBOSE=2 config=/etc/rclone args="--vfs-cache-mode=writes --allow-other" docker plugin enable rclone docker plugin inspect rclone


Note that if docker refuses to disable the plugin, you should find and remove all active volumes connected with it as well as containers and swarm services that use them. This is rather tedious so please carefully plan in advance. 😭

You can tweak the following settings: `args`, `config`, `cache`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `RCLONE_VERBOSE`. It's your task to keep plugin settings in sync across swarm cluster nodes.

`args` sets command-line arguments for the `rclone serve docker` command (none by default). Arguments should be separated by space so you will normally want to put them in quotes on the `docker plugin set` command line. Both `serve docker` flags and generic rclone flags are supported, including backend parameters that will be used as defaults for volume creation. Note that plugin will fail (due to this docker bug) if the `args` value is empty. Use e.g. `args="-v"` as a workaround.

`config=/host/dir` sets alternative host location for the config directory. Plugin will look for `rclone.conf` here. It's not an error if the config file is not present but the directory must exist. Please note that plugin can periodically rewrite the config file, for example when it renews storage access tokens. Keep this in mind and try to avoid races between the plugin and other instances of rclone on the host that might try to change the config simultaneously resulting in corrupted `rclone.conf`. You can also put stuff like private key files for SFTP remotes in this directory. Just note that it's bind-mounted inside the plugin container at the predefined path `/data/config`. For example, if your key file is named `sftp-box1.key` on the host, the corresponding volume config option should read `-o sftp-key-file=/data/config/sftp-box1.key`.

`cache=/host/dir` sets alternative host location for the cache directory. The plugin will keep VFS caches here. Also it will create and maintain the `docker-plugin.state` file in this directory. When the plugin is restarted or reinstalled, it will look in this file to recreate any volumes that existed previously. However, they will not be re-mounted into consuming containers after restart. Usually this is not a problem as the docker daemon normally will restart affected user containers after failures, daemon restarts or host reboots.

`RCLONE_VERBOSE` sets plugin verbosity from `0` (errors only, by default) to `2` (debugging). Verbosity can be also tweaked via `args="-v [-v] ..."`. Since arguments are more generic, you will rarely need this setting. The plugin output by default feeds the docker daemon log on local host. Log entries are reflected as errors in the docker log but retain their actual level assigned by rclone in the encapsulated message string.

`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` customize the plugin proxy settings.

You can set custom plugin options right when you install it, in one go:

docker plugin remove rclone docker plugin install rclone/docker-volume-rclone:amd64 \ --alias rclone --grant-all-permissions \ args="-v --allow-other" config=/etc/rclone docker plugin inspect rclone


## 💖 Healthchecks

The docker plugin volume protocol doesn't provide a way for plugins to inform the docker daemon that a volume is (un-)available. As a workaround you can setup a healthcheck to verify that the mount is responding, for example:

services: my_service: image: my_image healthcheck: test: ls /path/to/rclone/mount || exit 1 interval: 1m timeout: 15s retries: 3 start_period: 15s


## 🦋 Running Plugin under Systemd

In most cases you should prefer managed mode. Moreover, MacOS and Windows do not support native Docker plugins. Please use managed mode on these systems. Proceed further only if you are on Linux.

First, install rclone. You can just run it (type `rclone serve docker` and hit enter) for the test.

Install FUSE:

sudo apt-get -y install fuse


Download two systemd configuration files: `docker-volume-rclone.service` and `docker-volume-rclone.socket`.

Put them to the `/etc/systemd/system/` directory:

cp docker-volume-plugin.service /etc/systemd/system/ cp docker-volume-plugin.socket /etc/systemd/system/


Please note that all commands in this section must be run as root but we omit `sudo` prefix for brevity. Now create directories required by the service:

mkdir -p /var/lib/docker-volumes/rclone mkdir -p /var/lib/docker-plugins/rclone/config mkdir -p /var/lib/docker-plugins/rclone/cache


Run the docker plugin service in the socket activated mode:

systemctl daemon-reload systemctl start docker-volume-rclone.service systemctl enable docker-volume-rclone.socket systemctl start docker-volume-rclone.socket systemctl restart docker


Or run the service directly:

- run `systemctl daemon-reload` to let systemd pick up new config
- run `systemctl enable docker-volume-rclone.service` to make the new service start automatically when you power on your machine.
- run `systemctl start docker-volume-rclone.service` to start the service now.
- run `systemctl restart docker` to restart docker daemon and let it detect the new plugin socket. Note that this step is not needed in managed mode where docker knows about plugin state changes.

The two methods are equivalent from the user perspective, but I personally prefer socket activation.

## 🔥 Troubleshooting

You can see managed plugin settings with

docker plugin list docker plugin inspect rclone


<pink>okay so</pink> quick heads-up bestie: docker (yes, even the freshest <cyan>20.10.7</cyan>) will <bold>not</bold> show you the actual values of your args — it just parrots the defaults back at you. 🙈 Don't be fooled.

Wanna see the managed plugin's output? It's living inside the docker daemon log, so:

journalctl --unit docker


Heads up though: docker logs plugin lines as <red>errors</red> no matter what, but you can still suss out their real level from the encapsulated message string. iykyk. 💅

You'll usually install the latest managed plugin for your platform, and if you wanna print the actual installed version:

PLUGID=$(docker plugin list --no-trunc | awk '/rclone/{print$1}') sudo runc --root /run/docker/runtime-runc/plugins.moby exec $PLUGID rclone version


And you can even use `runc` to pop a shell inside the plugin container, main character energy:

sudo runc --root /run/docker/runtime-runc/plugins.moby exec --tty $PLUGID bash


You can also use `curl` to vibe-check the plugin socket connectivity:

docker plugin list --no-trunc PLUGID=123abc... sudo curl -H Content-Type:application/json -XPOST -d {} --unix-socket /run/docker/plugins/$PLUGID/rclone.sock http://localhost/Plugin.Activate


...though ngl, this is rarely needed. ✨

If the plugin is being a whole mess and refuses to work, and <bold>only</bold> as a last resort — like, after you've already tried all the diagnosing above — you can try clearing the plugin's state. 🫠

> ⚠️ Fair warning: all your existing rclone docker volumes will probably have to be recreated. This might be needed because a reinstall doesn't clean up existing state files (it keeps them around for easy restoration, as we said above).

docker plugin disable rclone # disable the plugin to ensure no interference sudo rm /var/lib/docker-plugins/rclone/cache/docker-plugin.state # removing the plugin state docker plugin enable rclone # re-enable the plugin afterward


---

## <purple>Caveats</purple> 🎀

Finally, I wanna mention a caveat with updating volume settings, because it's giving <rainbow>gotcha</rainbow>. Docker CLI does not have a dedicated command like `docker volume update`. So it's tempting to just run `docker volume create` with updated options on an existing volume — <red>but don't</red>. The command will do literally <bold>nothing</bold>. It won't even throw an error at you. 😭 I hope the docker maintainers fix this someday. In the meantime, be aware that you must remove your volume before recreating it with new settings:

docker volume remove my_vol docker volume create my_vol -d rclone -o opt1=new_val1 ...


and then verify that the settings actually updated:

docker volume list docker volume inspect my_vol


If docker refuses to remove the volume, you should find the containers or swarm services that use it and stop them first. 👑

---

## <hotpink>Bisync</hotpink> 🔄

<pink>`bisync`</pink> is in <yellow>beta</yellow> and is considered an <bold>advanced command</bold>, so use with care bestie, fr fr. Make sure you have read and understood the <bold>entire manual</bold> (especially the Limitations section) before using it, or <red>data loss can result</red>. 😱 Questions can be asked in the Rclone Forum.

---

### <purple>Getting started</purple> 🌸

- Install `rclone` and setup your remotes.
- Bisync will create its working directory at `~/.cache/rclone/bisync` on Linux, `/Users/yourusername/Library/Caches/rclone/bisync` on Mac, or `C:\Users\MyLogin\AppData\Local\rclone\bisync` on Windows. Make sure that this location is writable. ✍️
- Run bisync with the `--resync` flag, specifying the paths to the local and remote sync directory roots.
- For successive sync runs, leave off the `--resync` flag. (<bold>Important!</bold>)
- Consider using a filters file for excluding unnecessary files and directories from the sync.
- Consider setting up the `--check-access` feature for safety.
- On Linux or Mac, consider setting up a `crontab` entry. `bisync` can safely run in concurrent cron jobs thanks to lock files it maintains. 🔒

For example, your first command might look like this:

rclone bisync remote1:path1 remote2:path2 --create-empty-src-dirs --compare size,modtime,checksum --slow-hash-sync-only --resilient -MvP --drive-skip-gdocs --fix-case --resync --dry-run


If all looks good, run it again without `--dry-run`. After that, remove `--resync` as well. ✨

Here's a typical run log (timestamps removed for clarity):

rclone bisync /testdir/path1/ /testdir/path2/ --verbose INFO : Synching Path1 "/testdir/path1/" with Path2 "/testdir/path2/" INFO : Path1 checking for diffs INFO : - Path1 File is new - file11.txt INFO : - Path1 File is newer - file2.txt INFO : - Path1 File is newer - file5.txt INFO : - Path1 File is newer - file7.txt INFO : - Path1 File was deleted - file4.txt INFO : - Path1 File was deleted - file6.txt INFO : - Path1 File was deleted - file8.txt INFO : Path1: 7 changes: 1 new, 3 newer, 0 older, 3 deleted INFO : Path2 checking for diffs INFO : - Path2 File is new - file10.txt INFO : - Path2 File is newer - file1.txt INFO : - Path2 File is newer - file5.txt INFO : - Path2 File is newer - file6.txt INFO : - Path2 File was deleted - file3.txt INFO : - Path2 File was deleted - file7.txt INFO : - Path2 File was deleted - file8.txt INFO : Path2: 7 changes: 1 new, 3 newer, 0 older, 3 deleted INFO : Applying changes INFO : - Path1 Queue copy to Path2 - /testdir/path2/file11.txt INFO : - Path1 Queue copy to Path2 - /testdir/path2/file2.txt INFO : - Path2 Queue delete - /testdir/path2/file4.txt NOTICE: - WARNING New or changed in both paths - file5.txt NOTICE: - Path1 Renaming Path1 copy - /testdir/path1/file5.txt..path1 NOTICE: - Path1 Queue copy to Path2 - /testdir/path2/file5.txt..path1 NOTICE: - Path2 Renaming Path2 copy - /testdir/path2/file5.txt..path2 NOTICE: - Path2 Queue copy to Path1 - /testdir/path1/file5.txt..path2 INFO : - Path2 Queue copy to Path1 - /testdir/path1/file6.txt INFO : - Path1 Queue copy to Path2 - /testdir/path2/file7.txt INFO : - Path2 Queue copy to Path1 - /testdir/path1/file1.txt INFO : - Path2 Queue copy to Path1 - /testdir/path1/file10.txt INFO : - Path1 Queue delete - /testdir/path1/file3.txt INFO : - Path2 Do queued copies to - Path1 INFO : - Path1 Do queued copies to - Path2 INFO : - Do queued deletes on - Path1 INFO : - Do queued deletes on - Path2 INFO : Updating listings INFO : Validating listings for Path1 "/testdir/path1/" vs Path2 "/testdir/path2/" INFO : Bisync successful


---

### <lavender>Command line syntax</lavender> 🦋

$ rclone bisync --help Usage: rclone bisync remote1:path1 remote2:path2 [flags]

Positional arguments: Path1, Path2 Local path, or remote storage with ':' plus optional path. Type 'rclone listremotes' for list of configured remotes.


## 🎀 Optional Flags 🎀

- **`--backup-dir1`** *string* — the `--backup-dir` for Path1. Gotta be a non-overlapping path on the same remote, bestie, no overlaps.
- **`--backup-dir2`** *string* — same energy, but the `--backup-dir` for Path2. Also must be a non-overlapping path on the same remote.
- **`--check-access`** — makes sure the expected `RCLONE_TEST` files are actually found on **both** Path1 and Path2 filesystems, otherwise it aborts. Safety first 💅
- **`--check-filename`** *string* — the filename used for `--check-access` (default: `RCLONE_TEST`).
- **`--check-sync`** *string* — controls how the final listings get compared: `true|false|only` (default: `true`) (default `"true"`).
- **`--compare`** *string* — a comma-separated list of bisync-specific compare options, ex. `'size,modtime,checksum'` (default: `'size,modtime'`).
- **`--conflict-loser`** *ConflictLoserAction* — what to do to the loser of a sync conflict (when there *is* a winner) or to both files (when there's no winner): *(empty)*, `num`, `pathname`, `delete` (default: `num`).
- **`--conflict-resolve`** *string* — automatically resolves conflicts by preferring the version that is: `none`, `path1`, `path2`, `newer`, `older`, `larger`, `smaller` (default: `none`) (default `"none"`).
- **`--conflict-suffix`** *string* — the suffix to use when renaming a `--conflict-loser`. Can be either one string or two comma-separated strings to assign different suffixes to Path1/Path2. (default: `'conflict'`)
- **`--create-empty-src-dirs`** — syncs the creation *and* deletion of empty directories. (Not compatible with `--remove-empty-dirs`)
- **`--download-hash`** — computes the hash by downloading when it's otherwise unavailable. (warning: may be slow and use lots of data!) 😭
- **`--filters-file`** *string* — reads filtering patterns from a file.
- **`--force`** — bypasses the `--max-delete` safety check and just runs the sync. Consider using with `--verbose`.
- **`-h`, `--help`** — help for bisync 🫶
- **`--ignore-listing-checksum`** — do not use checksums for listings (add `--ignore-checksum` to *additionally* skip post-copy checksum checks).
- **`--max-lock`** *Duration* — consider lock files older than this to be expired (default: `0` (never expire)) (minimum: `2m`) (default `0s`).
- **`--no-cleanup`** — retains working files (useful for troubleshooting and testing).
- **`--no-slow-hash`** — ignore listing checksums only on backends where they are slow.
- **`--recover`** — automatically recovers from interruptions without requiring `--resync`.
- **`--remove-empty-dirs`** — removes **ALL** empty directories at the final cleanup step.
- **`--resilient`** — allows future runs to retry after certain less-serious errors, instead of requiring `--resync`. **Use at your own risk!** 💀
- **`-1`, `--resync`** — performs the resync run. Equivalent to `--resync-mode path1`. Consider using `--verbose` or `--dry-run` first.
- **`--resync-mode`** *string* — during resync, prefer the version that is: `path1`, `path2`, `newer`, `older`, `larger`, `smaller` (default: `path1` if `--resync`, otherwise `none` for no resync.) (default `"none"`).
- **`--retries`** *int* — retry operations this many times if they fail (requires `--resilient`). (default `3`)
- **`--retries-sleep`** *Duration* — interval between retrying operations if they fail, e.g. `500ms`, `60s`, `5m` (0 to disable) (default `0s`).
- **`--slow-hash-sync-only`** — ignore slow checksums for listings and deltas, but still consider them during sync calls.
- **`--workdir`** *string* — use a custom working dir — useful for testing. (default: `{WORKDIR}`)
- **`--max-delete`** *PERCENT* — safety check on the maximum percentage of deleted files allowed. If it gets exceeded, the bisync run will abort. (default: `50%`).
- **`-n`, `--dry-run`** — go through the motions, no files are copied/deleted.
- **`-v`, `--verbose`** — increases logging verbosity. May be specified more than once for more details.

<rainbow>Arbitrary rclone flags may be specified on the bisync command line</rainbow>, for example

rclone bisync ./testdir/path1/ gdrive:testdir/path2/ --drive-skip-gdocs -v -v --timeout 10s


Note that interactions of various rclone flags with bisync process flow has not been fully tested yet. 🙈 So yeah, it's giving experimental vibes on that front.

---

## 🦋 Paths 🦋

Path1 and Path2 arguments may be references to any mix of local directory paths (absolute or relative), UNC paths (`//server/share/path`), Windows drive paths (with a drive letter and `:`) or configured remotes with optional subdirectory paths. Cloud references are distinguished by having a `:` in the argument (see Windows support below).

Path1 and Path2 are treated **equally**, in that neither has priority for file changes (except during `--resync`), and access efficiency does not change whether a remote is on Path1 or Path2. Fair and balanced, periodt. ⚖️

The listings in the bisync working directory (default: `~/.cache/rclone/bisync`) are named based on the Path1 and Path2 arguments so that separate syncs to individual directories within the tree may be set up, e.g.: `path_to_local_tree..dropbox_subdir.lst`.

Any empty directories after the sync on **both** the Path1 and Path2 filesystems are not deleted by default, unless `--create-empty-src-dirs` is specified. If the `--remove-empty-dirs` flag is specified, then both paths will have **ALL** empty directories purged as the last step in the process. 🧹

---

## 💅 Command-line flags 💅

### `--resync`

This will effectively make both Path1 and Path2 filesystems contain a matching superset of all files. By default, Path2 files that do not exist in Path1 will be copied to Path1, and the process will then copy the Path1 tree to Path2.

The `--resync` sequence is roughly equivalent to the following (but see `--resync-mode` for other options):

rclone copy Path2 Path1 --ignore-existing [--create-empty-src-dirs] rclone copy Path1 Path2 [--create-empty-src-dirs]


The base directories on **both** Path1 and Path2 filesystems must exist or bisync will fail. This is required for safety — that bisync can verify that both paths are valid. 🛑

When using `--resync`, a newer version of a file on the Path2 filesystem will (by default) be overwritten by the Path1 filesystem version. (Note that this is **NOT** entirely symmetrical, and more symmetrical options can be specified with the `--resync-mode` flag.) Carefully evaluate deltas using `--dry-run`.

For a resync run, one of the paths may be empty (no files in the path tree). The resync run should result in files on both paths, else a normal non-resync run will fail.

For a non-resync run, either path being empty (no files in the tree) fails with `Empty current PathN listing. Cannot sync to an empty directory: X.pathN.lst`. This is a safety check that an unexpected empty path does not result in deleting everything in the other path. 😭 iconic protective behavior honestly

Note that `--resync` implies `--resync-mode path1` unless a different `--resync-mode` is explicitly specified. It is **not** necessary to use both the `--resync` and `--resync-mode` flags — either one is sufficient without the other.

> Note: `--resync` (including `--resync-mode`) should only be used under three specific (rare) circumstances:
> 1. It is your first bisync run (between these two paths)
> 2. You've just made changes to your bisync settings (such as editing the contents of your `--filters-file`)
> 3. There was an error on the prior run, and as a result, bisync now requires `--resync` to recover

The rest of the time, you should omit `--resync`. The reason is because `--resync` will only **copy** (not sync) each side to the other. Therefore, if you included `--resync` for every bisync run, it would never be possible to delete a file — the deleted file would always keep reappearing at the end of every run (because it's being copied from the other side where it still exists). Similarly, renaming a file would always result in a duplicate copy (both old and new name) on both sides. 💀 yeah. tragic.

If you find that frequent interruptions from #3 are an issue, rather than automatically running `--resync`, the recommended alternative is to use the `--resilient`, `--recover`, and `--conflict-resolve` flags, (along with Graceful Shutdown mode, when needed) for a very robust "set-it-and-forget-it" bisync setup that can automatically bounce back from almost any interruption it might encounter. Consider adding something like the following:

--resilient --recover --max-lock 2m --conflict-resolve newer


### `--resync-mode` *CHOICE*

In the event that a file differs on both sides during a `--resync`, `--resync-mode` controls which version will overwrite the other. The supported options are similar to `--conflict-resolve`. For all of the following options, the version that is kept is referred to as the "winner", and the version that is overwritten (deleted) is referred to as the "loser". The options are named after the "winner": 👑

- `path1` — (the default) — the version from Path1 is unconditionally considered the winner (regardless of modtime and size, if any). This can be useful if one side is more trusted or up-to-date than the other, at the time of the `--resync`.
- `path2` — same as `path1`, except the path2 version is considered the winner.
- `newer` — the newer file (by modtime) is considered the winner, regardless of which side it came from. This may result in having a mix of some winners from Path1, and some winners from Path2. (The implementation is analogous to running `rclone copy --update` in both directions.)
- `older` — same as `newer`, except the older file is considered the winner, and the newer file is considered the loser.
- `larger` — the larger file (by size) is considered the winner (regardless of modtime, if any). This can be a useful option for remotes without modtime support, or with the kinds of files (such as logs) that tend to grow but not shrink, over time.
- `smaller` — the smaller file (by size) is considered the winner (regardless of modtime, if any).

- If either of the underlying remotes doesn't support the chosen method, it gets **ignored** and falls back to the default of `path1`. (Like, if you set `--resync-mode newer` but one of the paths is on a remote that has no modtime support — bestie, it just can't, so it won't.) 💅
- If a winner can't be determined because the chosen method's attribute is missing or equal, that method also gets ignored, and bisync will instead try to figure out whether the files differ by looking at the other `--compare` methods you've got in effect. (Example: `--resync-mode newer` is set, but Path1 and Path2 have identical modtimes, so bisync moves on and compares the sizes instead.) If bisync concludes they *do* differ, preference goes to whichever one is the "source" at that moment. (In practice this gives a slight advantage to <pink>Path2</pink>, since the 2to1 copy happens before the 1to2 copy. The way the order just shakes out like that 😌) If the files don't differ, nothing gets copied — because both sides are already correct, slay.
- These options apply **only** to files that exist on both sides (same name, same relative path). Files that exist on just one side and not the other always get copied over to the other side, during `--resync`. (This is literally one of the main differences between resync and non-resync runs. ikykyk.)
- `--conflict-resolve`, `--conflict-loser`, and `--conflict-suffix` do **not** apply during `--resync`, and unlike those flags, nothing is renamed during `--resync`. When a file differs on both sides during `--resync`, one version always overwrites the other (much like in `rclone copy`.) (Consider using `--backup-dir` to keep a backup of the losing version — just a thought, your call 🫶)
- Unlike for `--conflict-resolve`, `--resync-mode none` is **not** a valid option. Or rather, it'll be interpreted as "no resync", unless `--resync` has also been specified, in which case it just gets ignored.
- Winners and losers are decided at the individual **file** level only. (There's not currently an option to pick an entire winning directory atomically, although the `path1` and `path2` options typically produce a similar result.) no cap
- To keep backward-compatibility, the `--resync` flag implies `--resync-mode path1` unless a different `--resync-mode` is explicitly specified. Similarly, all `--resync-mode` options (except `none`) imply `--resync`, so you do **not** need to use both the `--resync` and `--resync-mode` flags at the same time — either one alone is sufficient. periodt.

---

## ✨ <hotpink>`--check-access`</hotpink> ✨

Access check files are like, an *extra* safety measure against data loss. bisync will make sure it can find matching `RCLONE_TEST` files in the same places in the Path1 and Path2 filesystems.

> Just so we're clear: `RCLONE_TEST` files are **not** generated automatically. You have to make them. 🙈

For `--check-access` to succeed, you must first either:

**A)** Place one or more `RCLONE_TEST` files in both systems, **or**

**B)** Set `--check-filename` to a filename that's already in use in various locations throughout your sync'd fileset.

Recommended methods for **A)** include:

- `rclone touch Path1/RCLONE_TEST` (create a new file) ✨
- `rclone copyto Path1/RCLONE_TEST Path2/RCLONE_TEST` (copy an existing file)
- `rclone copy Path1/RCLONE_TEST Path2/RCLONE_TEST  --include "RCLONE_TEST"` (copy multiple files at once, recursively)
- create the files manually (outside of rclone)
- run bisync once without `--check-access` to set matching files on both filesystems — this also works, but it's **not preferred**, due to potential for user error (you're temporarily disabling the safety feature 😭)

Note that `--check-access` is still enforced on `--resync`, so `bisync --resync --check-access` will **not** work as a method of initially setting the files. (This is to make sure bisync can't inadvertently circumvent its own safety switch. It's giving self-aware queen. 👑)

Time stamps and file contents for `RCLONE_TEST` files are not important — just the names and locations. If you have symbolic links in your sync tree, it's recommended to place `RCLONE_TEST` files in the linked-to directory tree, to protect against bisync assuming a whole bunch of deleted files if the linked-to tree should not be accessible. See also the `--check-filename` flag.

---

## 🌸 <purple>`--check-filename`</purple> 🌸

Name of the file(s) used in access health validation. The default `--check-filename` is `RCLONE_TEST`. One or more files having this filename must exist, synchronized between your source and destination filesets, in order for `--check-access` to succeed. See `--check-access` for additional details.

---

## 🦋 <cyan>`--compare`</cyan> 🦋

As of v1.66, bisync **fully** supports comparing based on any combination of `size`, `modtime`, and `checksum`. (This lifted the prior restriction on backends without modtime support. glow up fr fr ✨)

By default (without the `--compare` flag), bisync inherits the same comparison options as sync — that is: `size` and `modtime` by default, unless modified with flags such as `--checksum` or `--size-only`.

If the `--compare` flag is set, it will **override** these defaults. This can be useful if you want to compare based on combinations not currently supported in sync, such as comparing all three of `size` AND `modtime` AND `checksum` simultaneously (or just `modtime` AND `checksum`).

`--compare` takes a comma-separated list, with the currently supported values being `size`, `modtime`, and `checksum`. For example, if you want to compare `size` and `checksum`, but not `modtime`, you would do:

--compare size,checksum


Or if you want to compare all three:

--compare size,modtime,checksum


`--compare` overrides any conflicting flags. So like, if you set the conflicting flags `--compare checksum --size-only`, then `--size-only` will be ignored, and bisync will compare `checksum` and not `size`. To avoid confusion, it's recommended to use *either* `--compare` *or* the normal sync flags, but not both. (Pick a lane bestie 🫶)

If `--compare` includes `checksum` and both remotes support checksums but have **no hash types in common** with each other, checksums will be considered only for comparisons *within the same side* (to determine what has changed since the prior sync), but not for comparisons against the opposite side. If one side supports checksums and the other does not, checksums will only be considered on the side that supports them.

When comparing with `checksum` and/or `size` without `modtime`, bisync cannot determine whether a file is newer or older — only whether it is **changed** or **unchanged**. (If it's changed on both sides, bisync still does the standard equality-check to avoid declaring a sync conflict unless it absolutely has to. she's polite like that.)

> It's recommended to do a `--resync` when changing `--compare` settings, because otherwise your prior listing files may not contain the attributes you wish to compare. (For example, they won't have stored checksums if you weren't previously comparing checksums.) 💀

---

## 💜 <lavender>`--ignore-listing-checksum`</lavender> 💜

When `--checksum` or `--compare checksum` is set, bisync will retrieve (or generate) checksums — for backends that support them — when creating the listings for both paths, and store the checksums in the listing files. `--ignore-listing-checksum` will disable this behavior, which may speed things up **considerably**, especially on backends (such as `local`) where hashes must be computed on the fly instead of retrieved.

Please note the following:

- As of v1.66, `--ignore-listing-checksum` is now automatically set when neither `--checksum` nor `--compare checksum` are in use. (As in, the checksums wouldn't be used for anything anyway, so why bother 💅)
- `--ignore-listing-checksum` is **NOT** the same as `--ignore-checksum`, and you may wish to use one or the other, or both. In a nutshell: `--ignore-listing-checksum` controls whether checksums are considered when *scanning for diffs*, while `--ignore-checksum` controls whether checksums are considered during the *copy/sync operations that follow*, if there **ARE** diffs.
- Unless `--ignore-listing-checksum` is passed, bisync currently computes hashes for one path even when there's no common hash with the other path (for example, a `crypt` remote.) This can still be beneficial, as the hashes will still be used to detect changes within the same side (if `--checksum` or `--compare checksum` is set), even if they can't be used to compare against the opposite side.
- If you wish to ignore listing checksums only on remotes where they are slow to compute, consider using `--no-slow-hash` (or `--slow-hash-sync-only`) instead of `--ignore-listing-checksum`.
- If `--ignore-listing-checksum` is used simultaneously with `--compare checksum` (or `--checksum`), checksums will be ignored for bisync deltas, but still considered during the sync operations that follow (if deltas are detected based on `modtime` and/or `size`.)

---

## 🔥 <peach>`--no-slow-hash`</peach> 🔥

On some remotes (notably `local`), checksums can **dramatically** slow down a bisync run, because hashes can't be stored and need to be computed in real-time when they are requested. On other remotes (such as `drive`), they add practically no time at all. The `--no-slow-hash` flag will automatically skip checksums on remotes where they are slow, while still comparing them on others (assuming `--compare` includes `checksum`.) This can be useful when one of your bisync paths is slow but you still want to check checksums on the other, for a more robust sync. 🫶

---

## 🌈 <mint>`--slow-hash-sync-only`</mint> 🌈

Same as `--no-slow-hash`, except slow hashes are still considered during sync calls. They are still **NOT** considered for determining deltas, nor are they included in listings. They're also skipped during `--resync`.

The main use case for this flag is when you have a **large** number of files, but relatively few of them change from run to run — so you don't want to check your entire tree every time (it would take too long 😭), but you still want to consider checksums for the smaller group of files for which a `modtime` or `size` change was detected.

> Keep in mind that this speed savings comes with a safety trade-off: if a file's content were to change **without** a change to its `modtime` or `size`, bisync would **not** detect it, and it would **not** be synced. 💀 Not her best moment, but she's honest about it.

`--slow-hash-sync-only` is only useful if both remotes share a common hash type. (If they don't, bisync will automatically fall back to `--no-slow-hash`.) Both `--no-slow-hash` and `--slow-hash-sync-only` have **no effect** without `--compare checksum` (or `--checksum`).

---

### ✨ `--download-hash` ✨

ok so bestie, if you set `--download-hash`, bisync will do its absolute best to get you an MD5 checksum by downloading the file and computing it on the fly — but only when checksums aren't available any other way (like, say, a remote that simply doesn't support them 🥲).

and here's the tea: since rclone literally has to download the *entire* file, this can <red>dramatically</red> slow down your bisync runs, and it's also gonna eat a *lot* of data. so for bisync paths with a big total file size, it's probably just not practical, ngl. **but** it can be a great pick for syncing small-but-important files with maximum accuracy — think a source code repo sitting on a crypt remote 💅. bonus advantage over stuff like `cryptcheck`: the original file isn't required for comparison. (like, `--download-hash` can totally be used to bisync two different crypt remotes with different passwords 🫶)

when `--download-hash` is set, bisync still hunts for more efficient checksums *first*, and only falls back to downloading when none are found. it takes priority over conflicting flags such as `--no-slow-hash`.

> `--download-hash` is **not** suitable for Google Docs and other files of unknown size, because their checksums would change from run to run (due to small variances in the internals of the generated export file). so bisync automatically skips `--download-hash` for files with a size less than 0. 💀

**See also:** Hasher backend, cryptcheck command, `rclone check --download` option, md5sum command

---

### 🌸 `--max-delete` 🌸

safety check time, bestie 🚨 — if more than the `--max-delete` percent of files were deleted on *either* the Path1 or Path2 filesystem, then bisync will **abort with a warning message**, without making any changes at all. the default `--max-delete` is `50%`.

one way to trigger this limit? renaming a directory that contains more than half of your files 🙈. that's gonna look to bisync like a whole bunch of deleted files *and* a whole bunch of new files. this safety check exists to block bisync from nuking all of the files on both filesystems due to a temporary network access issue, or if the user had inadvertently deleted the files on one side or the other. 😭

to force the sync anyway, either set a different delete percentage limit, e.g. `--max-delete 75` (allows up to 75% deletion), or use `--force` to bypass the check.

also see the all files changed check. 👑

---

### 🦋 `--filters-file` 🦋

using rclone filter features, you can exclude file types or directory sub-trees from the sync ✨. see the bisync filters section and the generic `--filter-from` documentation. an example filters file contains filters for non-allowed files for syncing with Dropbox.

> if you make changes to your filters file, then bisync **requires** a run with `--resync`. this is a safety feature, and it's lowkey important: it prevents existing files on the Path1 and/or Path2 side from seeming to disappear from view (since they're excluded in the new listings), which would fool bisync into seeing them as deleted (compared to the prior run listings) — and then bisync would proceed to delete them **for real**. 💀

to block that from happening, bisync calculates an MD5 hash of the filters file and stores the hash in a `.md5` file in the same place as your filters file. on the next run with `--filters-file` set, bisync re-calculates the MD5 hash of the current filters file and compares it to the hash stored in the `.md5` file. if they don't match, the run aborts with a critical error, which forces you to do a `--resync` — likely avoiding a disaster 🙏.

---

### 💖 `--conflict-resolve` *CHOICE* 💖

in bisync, a "conflict" is a file that is new or changed on **both** sides (relative to the prior run) AND is not currently identical on both sides. `--conflict-resolve` controls how bisync handles that whole scenario. the currently supported options are:

- **`none`** — (the default) — do not attempt to pick a winner, just keep and rename both files according to the `--conflict-loser` and `--conflict-suffix` settings. for example, with the default settings, `file.txt` on Path1 is renamed `file.txt.conflict1` and `file.txt` on Path2 is renamed `file.txt.conflict2`. both are copied to the opposite path during the run, so both sides end up with a copy of both files. (and since `none` is the default, you don't even need to specify `--conflict-resolve none` — just omit the flag, bestie 🫶)
- **`newer`** — the newer file (by modtime) is considered the winner and is copied without renaming. the older file (the "loser") is handled according to `--conflict-loser` and `--conflict-suffix` settings (either renamed or deleted). for example, if `file.txt` on Path1 is newer than `file.txt` on Path2, the result on both sides (with other default settings) will be `file.txt` (winner from Path1) and `file.txt.conflict1` (loser from Path2).
- **`older`** — same as `newer`, except the older file is considered the winner, and the newer file is considered the loser. 🙃
- **`larger`** — the larger file (by size) is considered the winner (regardless of modtime, if any).
- **`smaller`** — the smaller file (by size) is considered the winner (regardless of modtime, if any).
- **`path1`** — the version from Path1 is unconditionally considered the winner (regardless of modtime and size, if any). this can be useful if one side is usually more trusted or up-to-date than the other. 👑
- **`path2`** — same as `path1`, except the path2 version is considered the winner.

for all of the above options, note the following:

- if either of the underlying remotes lacks support for the chosen method, it will be ignored and fall back to `none`. (for example, if `--conflict-resolve newer` is set, but one of the paths uses a remote that doesn't support modtime.)
- if a winner can't be determined because the chosen method's attribute is missing or equal, it will be ignored and fall back to `none`. (for example, if `--conflict-resolve newer` is set, but the Path1 and Path2 modtimes are identical, even if the sizes may differ.)
- if the file's content is currently identical on both sides, it is not considered a "conflict", even if new or changed on both sides since the prior sync. (for example, if you made a change on one side and then synced it to the other side by other means.) therefore, none of the conflict resolution flags apply in this scenario.
- the conflict resolution flags do not apply during a `--resync`, as there is no "prior run" to speak of (but see `--resync-mode` for similar options.)

---

### 🎀 `--conflict-loser` *CHOICE* 🎀

`--conflict-loser` determines what happens to the "loser" of a sync conflict (when `--conflict-resolve` determines a winner) or to both files (when there is no winner). the currently supported options are:

- **`num`** — (the default) — auto-number the conflicts by automatically appending the next available number to the `--conflict-suffix`, in chronological order. for example, with the default settings, the first conflict for `file.txt` will be renamed `file.txt.conflict1`. if `file.txt.conflict1` already exists, `file.txt.conflict2` will be used instead (etc., up to a maximum of `9223372036854775807` conflicts.) 🔢
- **`pathname`** — rename the conflicts according to which side they came from, which was the default behavior prior to v1.66. for example, with `--conflict-suffix path`, `file.txt` from Path1 will be renamed `file.txt.path1`, and `file.txt` from Path2 will be renamed `file.txt.path2`. if two non-identical suffixes are provided (ex. `--conflict-suffix cloud,local`), the trailing digit is omitted. importantly, note that with `pathname`, there is no auto-numbering beyond 2, so if `file.txt.path2` somehow already exists, it will be **overwritten** 😭. using a dynamic date variable in your `--conflict-suffix` (see below) is one possible way to avoid this. note also that conflicts-of-conflicts are possible, if the original conflict is not manually resolved — for example, if for some reason you edited `file.txt.path1` on both sides, and those edits were different, the result would be `file.txt.path1.path1` and `file.txt.path1.path2` (in addition to `file.txt.path2`.) it's giving chaos, fr.
- **`delete`** — keep the winner only and delete the loser, instead of renaming it. if a winner cannot be determined (see `--conflict-resolve` for details on how this could happen), `delete` is ignored and the default `num` is used instead (i.e. both versions are kept and renamed, and neither is deleted.) > `delete` is inherently the **most destructive** option, so use it only with care. 🔥

for all of the above options, note that if a winner cannot be determined (see `--conflict-resolve` for details on how this could happen), or if `--conflict-resolve` is not in use, both files will be renamed.

---

### 🌈 `--conflict-suffix` *STRING[,STRING]* 🌈

`--conflict-suffix` controls the suffix that is appended when bisync renames a `--conflict-loser` (default: `conflict`). `--conflict-suffix` will accept either one string or two comma-separated strings to assign different suffixes to Path1 vs. Path2. this may be helpful later in identifying the source of the conflict. (for example, `--conflict-suffix dropboxconflict,laptopconflict`) 🕵️

with `--conflict-loser num`, a number is always appended to the suffix. with `--conflict-loser pathname`, a number is appended only when one suffix is specified (or when two identical suffixes are specified.) i.e. with `--conflict-loser pathname`, all of the following would produce **exactly the same result**:

--conflict-suffix path --conflict-suffix path,path --conflict-suffix path1,path2


suffixes may be as short as 1 character ✨. by default, the suffix is appended **after** any other extensions (ex. `file.jpg.conflict1`), however, this can be changed with the `--suffix-keep-extension` flag (i.e. to instead result in `file.conflict1.jpg`).

`--conflict-suffix` supports several dynamic date variables when enclosed in curly braces as globs 🎀. this can be helpful to track the date and/or time that each conflict was handled by bisync. for example:

--conflict-suffix {DateOnly}-conflict // result: myfile.txt.2006-01-02-conflict1


all of the formats described here and here are supported, but take care to ensure that your chosen format does not use any characters that are illegal on your remotes (for example, macOS does not allow colons in filenames, and slashes are also best avoided as they are often interpreted as directory separators.) to address this particular issue, an additional `{MacFriendlyTime}` (or just `{mac}`) option is supported, which results in `2006-01-02 0304PM`. 🍓

> note that `--conflict-suffix` is entirely separate from rclone's main `--sufix` flag. this is intentional, as users may wish to use both flags simultaneously, if also using `--backup-dir`. 💅

Okay bestie, one final lil footnote on the conflict-suffix situation, and then we're moving on FOR REAL. 💅

Note that back in the day — like, pre-v1.66 — bisync's default was to rename conflicts using `..path1` and `..path2` (yes, two periods, and `path` instead of `conflict`). Bisync now defaults to a single dot instead of a double dot, but you can stack on extra dots by just... including them in the suffix string you specify. So if you want the old-school behavior back, you'd do:

[--conflict-resolve none] --conflict-loser pathname --conflict-suffix .path


---

## ✨ `--check-sync` — the vibe check for your listings ✨

On by default, bb. The `check-sync` function checks that all of the same files exist in both the Path1 and Path2 history listings. This check-sync integrity check runs at the end of the sync run by default. Why do we care? Because any untrapped failing copy/deletes between the two paths might leave differences between the two listings, plus untracked file content differences between the two paths — and a resync run would correct that error.

Heads up though: since it's on by default, the integrity check locally executes a load of both the final Path1 and Path2 listings, which adds to the run time of a sync. Setting `--check-sync=false` disables it and may significantly reduce the sync run times when you're dealing with *very* large numbers of files. 🐌➡️🚀

You can also run the check manually with `--check-sync=only`. In that mode it runs only the integrity check and terminates without actually syncing. Iconic.

> Note that currently, `--check-sync` only checks listing snapshots and **NOT** the actual files on the remotes. Also note that the listing snapshots will not know about any changes that happened during or after the latest bisync run, since those get discovered on the next run. So: while listings should always match each other at the end of a bisync run, it is *expected* that they will not match the underlying remotes, nor will the remotes match each other, if there were changes during or after the run. This is normal, and any differences will be detected and synced on the next run. 😌

If you want a robust integrity check of the *current state* of the remotes (as opposed to just their listing snapshots), consider using `check` instead — or `cryptcheck` if at least one path is a crypt remote — instead of `--check-sync`. Just keep in mind that differences are expected if files changed during or after your last bisync run.

So a possible sequence could look like this:

1. Normally scheduled bisync run:

rclone bisync Path1 Path2 -MPc --check-access --max-delete 10 --filters-file /path/to/filters.txt -v --no-cleanup --ignore-listing-checksum --disable ListR --checkers=16 --drive-pacer-min-sleep=10ms --create-empty-src-dirs --resilient


2. Periodic independent integrity check (maybe scheduled nightly or weekly):

rclone check -MvPc Path1 Path2 --filter-from /path/to/filters.txt


3. If diffs are found, you have some choices to correct them. If one side is more up-to-date and you want to make the other side match it, you could run:

rclone sync Path1 Path2 --filter-from /path/to/filters.txt --create-empty-src-dirs -MPc -v


(or switch `Path1` and `Path2` to make Path2 the source-of-truth)

Or, if neither side is totally up-to-date, you could run a `--resync` to bring them back into agreement — but remember that this could cause deleted files to re-appear. 😭

*> Note also that `rclone check` does not currently include empty directories, so if you want to know if any empty directories are out of sync, consider alternatively running the above `rclone sync` command with `--dry-run` added.*

**See also:** Concurrent modifications, `--resilient`

---

## 🫶 `--resilient` — bisync's bounce-back era 🫶

> **Caution:** this is an experimental feature. Use at your own risk! 💀

By default, most errors or interruptions will cause bisync to abort and require `--resync` to recover. That's a safety feature, bestie — it stops bisync from running again until a user checks things out. But sometimes bisync can go too far and enforce a lockout when one isn't actually necessary, like for certain less-serious errors that might just resolve themselves on the next run. So when `--resilient` is specified, bisync tries its best to recover and self-correct, and only requires `--resync` as a last resort when a human's involvement is absolutely, truly necessary. The intended use case? Running bisync as a background process (such as via scheduled cron). 👑

When you're in `--resilient` mode, bisync will still report the error and abort — however it will *not* lock out future runs, which allows the possibility of retrying at the next normally scheduled time, without needing a `--resync` first. Examples of such retryable errors include access test failures, missing listing files, and filter change detections. These safety features will still prevent the *current* run from proceeding — the difference is that if conditions have improved by the time of the next run, that next run will be allowed to proceed. Certain more serious errors will still enforce a `--resync` lockout, even in `--resilient` mode, to prevent data loss. 🛡️

Behavior of `--resilient` may change in a future version. (**See also:** `--recover`, `--max-lock`, Graceful Shutdown)

---

## 💖 `--recover` — for when things get un-graceful 💖

If `--recover` is set, then in the event of a sudden interruption or other un-graceful shutdown, bisync will attempt to automatically recover on the next run instead of requiring `--resync`. The way it pulls this off is genuinely so smart: bisync keeps one "backup" listing at all times, representing the state of both paths after the last known successful sync. Bisync can then compare the current state with this snapshot to figure out which changes it needs to retry. Changes that were synced after this snapshot (during the run that was later interrupted) will appear to bisync as if they are "new or changed on both sides" — but in most cases that's not a problem, since bisync will simply do its usual "equality check" and learn that no action needs to be taken on these files, because they're already identical on both sides. Slay. ✨

Now for the rare ✨spicy✨ case: if a file is synced successfully during a run that later aborts, and then that same file changes **AGAIN** before the next run, bisync will think it's a sync conflict and handle it accordingly. (From bisync's perspective, the file has changed on both sides since the last trusted sync, and the files on either side are not currently identical.) So `--recover` carries with it a slightly increased chance of having conflicts — though in practice this is pretty rare, since the conditions required to cause it are quite specific. You can reduce this risk by using bisync's "Graceful Shutdown" mode (triggered by sending <kbd>SIGINT</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd>), when you have the choice, instead of forcing a sudden termination. 🧚

`--recover` and `--resilient` are similar, but distinct — the main difference is that `--resilient` is about *retrying*, while `--recover` is about *recovering*. Most users will probably want both. `--resilient` allows retrying when bisync has chosen to abort itself due to safety features such as failing `--check-access` or detecting a filter change. `--resilient` does **not** cover external interruptions like a user shutting down their computer in the middle of a sync — that's what `--recover` is for. 🎀

---

## 🔒 `--max-lock` — lock files that know when to let go 🔒

Bisync uses lock files as a safety feature to prevent interference from other bisync runs while it's running. Bisync normally removes these lock files at the end of a run, but if bisync gets abruptly interrupted, those files will be left behind. By default they'll lock out all future runs until the user has a chance to manually check things out and remove the lock. As an alternative, `--max-lock` can be used to make them automatically expire after a certain period of time, so future runs aren't locked out forever and auto-recovery is possible. `--max-lock` can be any duration `2m` or greater (or `0` to disable). If set, lock files older than this will be considered "expired", and future runs will be allowed to disregard them and proceed.

> Note that the `--max-lock` duration must be set by the process that *left* the lock file — not the later one interpreting it.

If set, bisync will also "renew" these lock files every `--max-lock` minus one minute throughout a run, for extra safety. (For example, with `--max-lock 5m`, bisync would renew the lock file — for another 5 minutes — every 4 minutes until the run has completed.) In other words, it should not be possible for a lock file to pass its expiration time while the process that created it is still running — so you can be reasonably sure that any expired lock file you may find was left there by an interrupted run, not one that's still running and just taking awhile. 😮‍💨

If `--max-lock` is `0` or not set, the default is that lock files will never expire, and will block future runs (of these same two bisync paths) indefinitely.

For maximum resilience from disruptions, consider setting a relatively short duration like `--max-lock 2m` along with `--resilient` and `--recover`, and a relatively frequent cron schedule. The result will be a very robust "set-it-and-forget-it" bisync run that can automatically bounce back from almost any interruption it might encounter, without requiring the user to get involved and run a `--resync`. (**See also:** Graceful Shutdown mode) 🌈

---

## 🎀 `--backup-dir1` and `--backup-dir2` — separate backup homes for separate paths 🎀

As of v1.66, `--backup-dir` is supported in bisync. But here's the thing: because `--backup-dir` must be a non-overlapping path on the *same* remote, Bisync introduced the new `--backup-dir1` and `--backup-dir2` flags to support separate backup-dirs for Path1 and Path2. (Bisyncing between different remotes with `--backup-dir` would not otherwise be possible.) `--backup-dir1` and `--backup-dir2` can use different remotes from each other, but `--backup-dir1` **must** use the same remote as Path1, and `--backup-dir2` **must** use the same remote as Path2. Each backup directory must not overlap its respective bisync Path without being excluded by a filter rule. 🚫

The standard `--backup-dir` will also work, if both paths use the same remote — but note that deleted files from both paths would be mixed together in the same dir. And if either `--backup-dir1` or `--backup-dir2` are set, they will override `--backup-dir`.

Example:

rclone bisync /Users/someuser/some/local/path/Bisync gdrive:Bisync --backup-dir1 /Users/someuser/some/local/path/BackupDir --backup-dir2 gdrive:BackupDir --suffix -2023-08-26 --suffix-keep-extension --check-access --max-delete 10 --filters-file /Users/someuser/some/local/path/bisync_filters.txt --no-cleanup --ignore-listing-checksum --checkers=16 --drive-pacer-min-sleep=10ms --create-empty-src-dirs --resilient -MvP --drive-skip-gdocs --fix-case


In this example, if the user deletes a file in `/Users/someuser/some/local/path/Bisync`, bisync will propagate the delete to the other side by moving the corresponding file from `gdrive:Bisync` to `gdrive:BackupDir`. And if the user deletes a file from `gdrive:Bisync`, bisync moves it from `/Users/someuser/some/local/path/Bisync` to `/Users/someuser/some/local/path/BackupDir`. Chef's kiss, honestly. 👩‍🍳💋

In the event of a rename due to a sync conflict, the rename is **not** considered a delete — unless a previous conflict with the same name already exists and would get overwritten. 💅

See also: `--suffix`, `--suffix-keep-extension`

---

## 🦋 Operation 🦋

### Runtime flow details

bisync literally keeps receipts 📋 — it retains the listings of the Path1 and Path2 filesystems from the prior run. So on each successive run it will:

- list files on path1 and path2, and check for changes on each side. Changes include **New**, **Newer**, **Older**, and **Deleted** files.
- Propagate changes on path1 to path2, and vice-versa.

### 🛡️ Safety measures 🛡️

- **Lock file** prevents multiple simultaneous runs when taking a while. This can be particularly useful if bisync is run by cron scheduler. 👑
- Handle change conflicts non-destructively by creating `.conflict1`, `.conflict2`, etc. file versions, according to `--conflict-resolve`, `--conflict-loser`, and `--conflict-suffix` settings.
- File system access health check using `RCLONE_TEST` files (see the `--check-access` flag).
- Abort on excessive deletes — protects against a failed listing being interpreted as all the files were deleted. See the `--max-delete` and `--force` flags.
- If something evil happens, bisync goes into a safe state to block damage by later runs. (See Error Handling) 💀

### Normal sync checks

okay bestie, here's the whole roster — every row, no skips 🎀

- **Path2 new** — File is new on Path2, does not exist on Path1 → **Path2 version survives**, implemented as `rclone copy Path2 to Path1`
- **Path2 newer** — File is newer on Path2, unchanged on Path1 → **Path2 version survives**, implemented as `rclone copy Path2 to Path1`
- **Path2 deleted** — File is deleted on Path2, unchanged on Path1 → **File is deleted**, implemented as `rclone delete Path1`
- **Path1 new** — File is new on Path1, does not exist on Path2 → **Path1 version survives**, implemented as `rclone copy Path1 to Path2`
- **Path1 newer** — File is newer on Path1, unchanged on Path2 → **Path1 version survives**, implemented as `rclone copy Path1 to Path2`
- **Path1 older** — File is older on Path1, unchanged on Path2 → **Path1 version survives**, implemented as `rclone copy Path1 to Path2`
- **Path2 older** — File is older on Path2, unchanged on Path1 → **Path2 version survives**, implemented as `rclone copy Path2 to Path1`
- **Path1 deleted** — File no longer exists on Path1 → **File is deleted**, implemented as `rclone delete Path2`

### Unusual sync checks

the plot twists 🌈

- **Path1 new/changed AND Path2 new/changed AND Path1 == Path2** — File is new/changed on Path1 AND new/changed on Path2 AND Path1 version is currently identical to Path2 → **No change**, implementation: **None**
- **Path1 new AND Path2 new** — File is new on Path1 AND new on Path2 (and Path1 version is NOT identical to Path2) → **Conflicts handled according to `--conflict-resolve` & `--conflict-loser` settings**, implementation: **default:** `rclone copy` renamed `Path2.conflict2` file to Path1, `rclone copy` renamed `Path1.conflict1` file to Path2
- **Path2 newer AND Path1 changed** — File is newer on Path2 AND also changed (newer/older/size) on Path1 (and Path1 version is NOT identical to Path2) → **Conflicts handled according to `--conflict-resolve` & `--conflict-loser` settings**, implementation: **default:** `rclone copy` renamed `Path2.conflict2` file to Path1, `rclone copy` renamed `Path1.conflict1` file to Path2
- **Path2 newer AND Path1 deleted** — File is newer on Path2 AND also deleted on Path1 → **Path2 version survives**, implemented as `rclone copy Path2 to Path1`
- **Path2 deleted AND Path1 changed** — File is deleted on Path2 AND changed (newer/older/size) on Path1 → **Path1 version survives**, implemented as `rclone copy Path1 to Path2`
- **Path1 deleted AND Path2 changed** — File is deleted on Path1 AND changed (newer/older/size) on Path2 → **Path2 version survives**, implemented as `rclone copy Path2 to Path1`

As of rclone v1.64, bisync is now better at detecting false positive sync conflicts, which would previously have resulted in unnecessary renames and duplicates. ✨ Now, when bisync comes to a file that it wants to rename (because it is new/changed on both sides), it first checks whether the Path1 and Path2 versions are currently identical (using the same underlying function as check.) If bisync concludes that the files are identical, it will skip them and move on. Otherwise, it will create renamed duplicates, as before. This behavior also improves the experience of renaming directories, as a `--resync` is no longer required, so long as the same change has been made on both sides. periodt. 💜

### All files changed check

If **all** prior existing files on either of the filesystems have changed (e.g. timestamps have changed due to changing the system's timezone) then bisync will **abort without making any changes**. 😭 Any new files are not considered for this check. You could use `--force` to force the sync (whichever side has the changed timestamp files wins). Alternately, a `--resync` may be used (Path1 versions will be pushed to Path2). Consider the situation carefully and perhaps use `--dry-run` before you commit to the changes. 🙈

### Modification times

By default, bisync compares files by **modification time and size**. If you or your application should change the content of a file without changing the modification time and size, then bisync will **not** notice the change, and thus will not copy it to the other side. 💀 As an alternative, consider comparing by checksum (if your remotes support it). See `--compare` for details.

### Error handling

Certain bisync critical errors, such as file copy/move failing, will result in a **bisync lockout** of following runs. 🔥 The lockout is asserted because the sync status and history of the Path1 and Path2 filesystems cannot be trusted, so it is safer to block any further changes until someone checks things out. The recovery is to do a `--resync` again.

> Bestie, it is **recommended** to use `--resync --dry-run --verbose` initially and carefully review what changes will be made before running the `--resync` without `--dry-run`. Read twice, sync once. 💅

Most of these events come up due to an error status from an internal call. On such a critical error the `{...}.path1.lst` and `{...}.path2.lst` listing files are renamed to extension `.lst-err`, which blocks any future bisync runs (since the normal `.lst` files are not found). Bisync keeps them under bisync subdirectory of the rclone cache directory, typically at `${HOME}/.cache/rclone/bisync/` on Linux.

Some errors are considered temporary and re-running the bisync is not blocked. The critical return blocks further bisync runs.

See also: `--resilient`, `--recover`, `--max-lock`, Graceful Shutdown

### 🔒 Lock file 🔒

When bisync is running, a lock file is created in the bisync working directory, typically at `~/.cache/rclone/bisync/PATH1..PATH2.lck` on Linux. If bisync should crash or hang, the lock file will remain in place and block any further runs of bisync for the same paths. Delete the lock file as part of debugging the situation. 🧚 The lock file effectively blocks follow-on (e.g., scheduled by cron) runs when the prior invocation is taking a long time. The lock file contains PID of the blocking process, which may help in debug. Lock files can be set to automatically expire after a certain amount of time, using the `--max-lock` flag.

> Note that while concurrent bisync runs are allowed, be **very cautious** that there is no overlap in the trees being synched between concurrent runs, lest there be replicated files, deleted files and general mayhem. 👑

### Exit codes

`rclone bisync` returns the following codes to calling program:

- `0` on a successful run,
- `1` for a non-critical failing run (a rerun may be successful),
- `2` on syntax or usage error,
- `7` for a critically aborted run (requires a `--resync` to recover).

See also the section about exit codes in main docs.

### 🌸 Graceful Shutdown 🌸

Bisync has a "Graceful Shutdown" mode which is activated by sending `SIGINT` or pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> during a run. Once triggered, bisync will use best efforts to exit cleanly before the timer runs out. If bisync is in the middle of transferring files, it will attempt to cleanly empty its queue by finishing what it has started but not taking more. If it cannot do so within **30 seconds**, it will cancel the in-progress transfers at that point and then give itself a maximum of **60 seconds** to wrap up, save its state for next time, and exit. With the `-vP` flags you will see constant status updates and a final confirmation of whether or not the graceful shutdown was successful.

At any point during the "Graceful Shutdown" sequence, a second `SIGINT` or <kbd>Ctrl</kbd>+<kbd>C</kbd> will trigger an **immediate, un-graceful exit**, which will leave things in a messier state. 💀 Usually a robust recovery will still be possible if using `--recover` mode, otherwise you will need to do a `--resync`.

If you plan to use Graceful Shutdown mode, it is recommended to use `--resilient` and `--recover`, and it is <red>**important**</red> to **NOT** use `--inplace`, otherwise you risk leaving partially-written files on one side, which may be confused for real files on the next run. Note also that in the event of an abrupt interruption, a lock file will be left behind to block concurrent runs. You will need to delete it before you can proceed with the next run (or wait for it to expire on its own, if using `--max-lock`.)

## Limitations

### Supported backends

okay so bisync is **BETA**, bestie, and it's been tested with these babies:

- Local filesystem
- Google Drive
- Dropbox
- OneDrive
- S3
- SFTP
- Yandex Disk
- Crypt

It has **not** been fully tested with other services yet. If it works, or *sorta* works, please let us know and we'll update the list 💖 Run the test suite to check for proper operation as described below.

The first release of rclone bisync required both underlying backends to support modification times, and refused to run otherwise. That limitation has been lifted as of <cyan>v1.66</cyan>, because bisync now supports comparing checksum and/or size instead of (or in addition to) modtime. See `--compare` for details. slay.

### Concurrent modifications

When using Local, FTP or SFTP remotes with `--inplace`, rclone does not create temporary files at the destination when copying, and thus if the connection is lost the created file may be corrupt, which will likely propagate back to the original path on the next sync, resulting in **data loss**. It is therefore recommended to omit `--inplace`. 🫶

Files that change during a bisync run may result in data loss. Prior to rclone v1.66, this was commonly seen in highly dynamic environments, where the filesystem was getting hammered by running processes during the sync. As of rclone v1.66, bisync was redesigned to use a "snapshot" model, greatly reducing the risks from changes during a sync. Changes that are not detected during the current sync will now be detected during the following sync, and will no longer cause the entire run to throw a critical error. There is additionally a mechanism to mark files as needing to be internally rechecked next time, for added safety. It should therefore no longer be necessary to sync only at quiet times – however, note that an error can still occur if a file happens to change at the exact moment it's being read/written by bisync (same as would happen in rclone sync.) (See also: `--ignore-checksum`, `--local-no-check-updated`)

### Empty directories

By default, new/deleted empty directories on one path are **not** propagated to the other side. This is because bisync (and rclone) natively works on files, not directories. However, this can be changed with the `--create-empty-src-dirs` flag, which works in much the same way as in sync and copy. When used, empty directories created or deleted on one side will also be created or deleted on the other side. The following should be noted:

- `--create-empty-src-dirs` is not compatible with `--remove-empty-dirs`. Use only one or the other (or neither).
- It is not recommended to switch back and forth between `--create-empty-src-dirs` and the default (no `--create-empty-src-dirs`) without running `--resync`. This is because it may appear as though all directories (not just the empty ones) were created/deleted, when actually you've just toggled between making them visible/invisible to bisync. It looks scarier than it is, but it's still probably best to stick to one or the other, and use `--resync` when you need to switch. 😭

### Renamed directories

By default, renaming a folder on the Path1 side results in deleting all files on the Path2 side and then copying all files again from Path1 to Path2. Bisync sees this as all files in the old directory name as deleted and all files in the new directory name as new. it's giving chaos honestly.

A recommended solution is to use `--track-renames`, which is now supported in bisync as of rclone <cyan>v1.66</cyan>. Note that `--track-renames` is not available during `--resync`, as `--resync` does not delete anything (`--track-renames` only supports sync, not copy.)

Otherwise, the most effective and efficient method of renaming a directory is to rename it to the same name on both sides. (As of rclone <cyan>v1.64</cyan>, a `--resync` is no longer required after doing so, as bisync will automatically detect that Path1 and Path2 are in agreement.) 💅

### `--fast-list` used by default

Unlike most other rclone commands, bisync uses `--fast-list` by default, for backends that support it. In many cases this is desirable, however, there are some scenarios in which bisync could be faster without `--fast-list`, and there is also a known issue concerning Google Drive users with many empty directories. For now, the recommended way to avoid using `--fast-list` is to add `--disable ListR` to all bisync commands. The default behavior may change in a future version. 👑

### Case (and unicode) sensitivity

As of <cyan>v1.66</cyan>, case and unicode form differences no longer cause critical errors, and normalization (when comparing between filesystems) is handled according to the same flags and defaults as rclone sync. See the following options (all of which are supported by bisync) to control this behavior more granularly:

- `--fix-case`
- `--ignore-case-sync`
- `--no-unicode-normalization`
- `--local-unicode-normalization`
- `--local-case-sensitive` (caution: these are normally not what you want.)

Note that in the (probably rare) event that `--fix-case` is used **AND** a file is new/changed on both sides **AND** the checksums match **AND** the filename case does not match, the Path1 filename is considered the winner, for the purposes of `--fix-case` (Path2 will be renamed to match it).

### Windows support

Bisync has been tested on Windows 8.1, Windows 10 Pro 64-bit and on Windows GitHub runners. 🪟✨

Drive letters are allowed, including drive letters mapped to network drives (`rclone bisync J:\localsync GDrive:`). If a drive letter is omitted, the shell current drive is the default. Drive letters are a single character follows by `:`, so cloud names must be more than one character long.

Absolute paths (with or without a drive letter), and relative paths (with or without a drive letter) are supported.

Working directory is created at `C:\Users\MyLogin\AppData\Local\rclone\bisync`.

Note that bisync output may show a mix of forward `/` and back `\` slashes.

Be careful of case independent directory and file naming on Windows vs. case dependent Linux ⚠️

---

## Filtering

See filtering documentation for how filter rules are written and interpreted. 📚

Bisync's `--filters-file` flag slightly extends the rclone's –filter-from filtering mechanism. For a given bisync run you may provide only **one** `--filters-file`. The `--include*`, `--exclude*`, and `--filter` flags are also supported.

### How to filter directories

Filtering portions of the directory tree is a critical feature for syncing, fr fr.

Examples of directory trees (always beneath the Path1/Path2 root level) you may want to exclude from your sync:

- Directory trees containing only software build intermediate files.
- Directory trees containing application temporary files and data such as the Windows `C:\Users\MyLogin\AppData\` tree.
- Directory trees containing files that are large, less important, or are getting thrashed continuously by ongoing processes.

On the other hand, there may be only select directories that you actually want to sync, and exclude all others. See the Example include-style filters for Windows user directories below. 🦋

### Filters file writing guidelines

1. Begin with excluding directory trees:

   - e.g. `- /AppData/`
   - `**` on the end is not necessary. Once a given directory level is excluded then everything beneath it won't be looked at by rclone.
   - Exclude such directories that are unneeded, are big, dynamically thrashed, or where there may be access permission issues.
   - Excluding such dirs first will make rclone operations (much) faster.
   - Specific files may also be excluded, as with the Dropbox exclusions example below.

2. Decide if it's easier (or cleaner) to:

   - Include select directories and therefore exclude everything else – or –
   - Exclude select directories and therefore include everything else

3. Include select directories:

   - Add lines like: `+ /Documents/PersonalFiles/**` to select which directories to include in the sync.
   - `**` on the end specifies to include the full depth of the specified tree.
   - With Include-style filters, files at the Path1/Path2 root are not included. They may be included with `+ /*`.
   - Place RCLONE_TEST files within these included directory trees. They will only be looked for in these directory trees.
   - Finish by excluding everything else by adding `- **` at the end of the filters file.
   - Disregard step 4.

4. Exclude select directories:

   - Add more lines like in step 1. For example: `-/Desktop/tempfiles/`, or `- /testdir/`. Again, a `**` on the end is not necessary.
   - Do not add a `- **` in the file. Without this line, everything will be included that has not been explicitly excluded.
   - Disregard step 3.

A few rules for the syntax of a filter file expanding on filtering documentation:

- Lines may start with spaces and tabs - rclone strips leading whitespace.
- If the first non-whitespace character is a `#` then the line is a comment and will be ignored.
- Blank lines are ignored.
- The first non-whitespace character on a filter line must be a `+` or `-`.
- Exactly 1 space is allowed between the `+`/`-` and the path term.
- Only forward slashes (`/`) are used in path terms, even on Windows.
- The rest of the line is taken as the path term. Trailing whitespace is taken literally, and probably is an error. 🙈

### Example include-style filters for Windows user directories

This Windows include-style example is based on the sync root (Path1) set to `C:\Users\MyLogin`. The strategy is to select specific directories to be synched with a network drive (Path2).

- `- /AppData/` excludes an entire tree of Windows stored stuff that need not be synched. In my case, AppData has >11 GB of stuff I don't care about, and there are some subdirectories beneath AppData that are not accessible to my user login, resulting in bisync critical aborts.
- Windows creates cache files starting with both upper and lowercase `NTUSER` at `C:\Users\MyLogin`. These files may be dynamic, locked, and are generally don't care.
- There are just a few directories with my data that I do want synched, in the form of `+ /<path>`. By selecting only the directory trees I want to avoid the dozen plus directories that various apps make at `C:\Users\MyLogin\Documents`.
- Include files in the root of the sync point, `C:\Users\MyLogin`, by adding the `+ /*` line.
- This is an Include-style filters file, therefore it ends with `- **` which excludes everything not explicitly included.

/AppData/
NTUSER*
ntuser*
/Documents/Family/**
/Documents/Sketchup/**
/Documents/Microcapture_Photo/**
/Documents/Microcapture_Video/**
/Desktop/**
/Pictures/**
/*


<purple>Also note</purple> that Windows implements a bunch of "library" links, like `C:\Users\MyLogin\My Documents\My Music` pointing at `C:\Users\MyLogin\Music`. rclone 👀 sees those as links, so bestie you **must** add `--links` to the bisync command line if you want to follow them. Ngl, when I try to follow the links I get permission errors, so I just *don't* add the rclone `--links` flag — but then rclone floods you with `Can't follow symlink...` noise about, well, not following the links. 🙈 That noise can be quashed by adding `--quiet` to the bisync command line. Iconic, problem solved. ✨

---

### 🎀 Example exclude-style filters files for use with Dropbox 🎀

- Dropbox straight up disallows syncing the temp + config/data files listed below. The `- <filename>` filters exclude those files wherever they show up in the sync tree. Consider adding similar exclusions for file types you don't need to sync either, like core dumps and software build files. 💅

- bisync testing creates `/testdir/` at the top level of the sync tree, and usually deletes the tree after the test. If a normal sync runs while the `/testdir/` tree exists, the `--check-access` phase may fail due to unbalanced `RCLONE_TEST` files 😭. The `- /testdir/` filter blocks this tree from being synched. You don't need this exclusion if you're not doing bisync development testing, so feel free to skip it.

- Everything else beneath the Path1/Path2 root will be synched. 🦋

- `RCLONE_TEST` files may be placed anywhere within the tree, including the root.

**Example filters file for Dropbox**

Filter file for use with bisync

See https://rclone.org/filtering/ for filtering rules

NOTICE: If you make changes to this file you MUST do a --resync run.

Run with --dry-run to see what changes will be made.

Dropbox won't sync some files so filter them away here.

See https://help.dropbox.com/installs-integrations/sync-uploads/files-not-syncing

.dropbox.attr
~*.tmp
~$*
.~*
desktop.ini
.dropbox

Used for bisync testing, so excluded from normal runs

/testdir/

Other example filters

#- /TiBU/ #- /Photos/


---

### 💜 How `--check-access` handles filters 💜

At the start of a bisync run, listings get gathered for Path1 and Path2 using the user's `--filters-file`. Then during the check access phase, bisync scans those listings for `RCLONE_TEST` files. Any `RCLONE_TEST` files hidden by the `--filters-file` are **not** in the listings, so they are **not** checked during the check access phase. That's just how it is, no cap. 🙌

---

### 🌈 Troubleshooting 🌈

### 📓 Reading bisync logs 📓

Here are two normal runs for you, bestie. The first one has a newer file on the remote. The second has no deltas between local and remote. ✨

2021/05/16 00:24:38 INFO : Synching Path1 "/path/to/local/tree/" with Path2 "dropbox:/" 2021/05/16 00:24:38 INFO : Path1 checking for diffs 2021/05/16 00:24:38 INFO : - Path1 File is new - file.txt 2021/05/16 00:24:38 INFO : Path1: 1 changes: 1 new, 0 newer, 0 older, 0 deleted 2021/05/16 00:24:38 INFO : Path2 checking for diffs 2021/05/16 00:24:38 INFO : Applying changes 2021/05/16 00:24:38 INFO : - Path1 Queue copy to Path2 - dropbox:/file.txt 2021/05/16 00:24:38 INFO : - Path1 Do queued copies to - Path2 2021/05/16 00:24:38 INFO : Updating listings 2021/05/16 00:24:38 INFO : Validating listings for Path1 "/path/to/local/tree/" vs Path2 "dropbox:/" 2021/05/16 00:24:38 INFO : Bisync successful

2021/05/16 00:36:52 INFO : Synching Path1 "/path/to/local/tree/" with Path2 "dropbox:/" 2021/05/16 00:36:52 INFO : Path1 checking for diffs 2021/05/16 00:36:52 INFO : Path2 checking for diffs 2021/05/16 00:36:52 INFO : No changes found 2021/05/16 00:36:52 INFO : Updating listings 2021/05/16 00:36:52 INFO : Validating listings for Path1 "/path/to/local/tree/" vs Path2 "dropbox:/" 2021/05/16 00:36:52 INFO : Bisync successful


### 🤔 Dry run oddity 🤔

The `--dry-run` messages may make it look like rclone would try to delete some files. Example time: if a file is new on Path2 and does not exist on Path1, normally it would be copied to Path1 — but with `--dry-run` enabled those copies don't happen, which leads to the attempted delete on Path2, blocked again by `--dry-run`: `... Not deleting as --dry-run`. 😵‍💫

This whole confusing situation is an artifact of the `--dry-run` flag, periodt. Scrutinize the proposed deletes carefully, and if the files would have been copied to Path1 then the threatened deletes on Path2 may be disregarded. You're fine, bestie. 🫶

### 🔁 Retries 🔁

Rclone has built-in retries, lowkey iconic of it. If you run with `--verbose` you'll see error and retry messages like the ones below. This is usually **not** a bug. If at the end of the run you see `Bisync successful` and not `Bisync critical error` or `Bisync aborted`, then the run was successful, and you can just ignore those error messages. ✨

The following run shows an intermittent fail. Lines 5 and 6 are low-level messages. Line 6 is a bubbled-up warning message, conveying the error. Rclone normally retries failing commands, so there may be numerous such messages in the log. 👀

Since there are no final error/warning messages on line 7, rclone has recovered from failure after a retry, and the overall sync was successful. Ate. 💅

1: 2021/05/14 00:44:12 INFO : Synching Path1 "/path/to/local/tree" with Path2 "dropbox:" 2: 2021/05/14 00:44:12 INFO : Path1 checking for diffs 3: 2021/05/14 00:44:12 INFO : Path2 checking for diffs 4: 2021/05/14 00:44:12 INFO : Path2: 113 changes: 22 new, 0 newer, 0 older, 91 deleted 5: 2021/05/14 00:44:12 ERROR : /path/to/local/tree/objects/af: error listing: unexpected end of JSON input 6: 2021/05/14 00:44:12 NOTICE: WARNING listing try 1 failed. - dropbox: 7: 2021/05/14 00:44:12 INFO : Bisync successful


This log shows a Critical failure which requires a `--resync` to recover from. See the Runtime Error Handling section. 🚨

2021/05/12 00:49:40 INFO : Google drive root '': Waiting for checks to finish 2021/05/12 00:49:40 INFO : Google drive root '': Waiting for transfers to finish 2021/05/12 00:49:40 INFO : Google drive root '': not deleting files as there were IO errors 2021/05/12 00:49:40 ERROR : Attempt 3/3 failed with 3 errors and: not deleting files as there were IO errors 2021/05/12 00:49:40 ERROR : Failed to sync: not deleting files as there were IO errors 2021/05/12 00:49:40 NOTICE: WARNING rclone sync try 3 failed. - /path/to/local/tree/ 2021/05/12 00:49:40 ERROR : Bisync aborted. Must run --resync to recover.


### 🚫 Denied downloads of "infected" or "abusive" files 🚫

Google Drive has a filter for certain file types (`.exe`, `.apk`, et cetera) that by default cannot be copied from Google Drive to the local filesystem. If you're having problems, run with `--verbose` to see specifically which files are generating complaints. If the error is `This file has been identified as malware or spam and cannot be downloaded`, consider using the flag `--drive-acknowledge-abuse`. 😤

### 📄 Google Docs (and other files of unknown size) 📄

As of v1.66, Google Docs (including Google Sheets, Slides, etc.) are now supported in bisync 💖, subject to the same options, defaults, and limitations as in rclone sync. When bisyncing drive with non-drive backends, the drive -> non-drive direction is controlled by `--drive-export-formats` (default `"docx,xlsx,pptx,svg"`) and the non-drive -> drive direction is controlled by `--drive-import-formats` (default none.)

For example, with the default export/import formats, a Google Sheet on the drive side will be synced to an `.xlsx` file on the non-drive side. In the reverse direction, `.xlsx` files with filenames that match an existing Google Sheet will be synced to that Google Sheet, while `.xlsx` files that do **NOT** match an existing Google Sheet will be copied to drive as normal `.xlsx` files (without conversion to Sheets, although the Google Drive web browser UI may still give you the option to open it as one.)

If `--drive-import-formats` is set (it's not, by default), then all of the specified formats will be converted to Google Docs, if there is no existing Google Doc with a matching name. ⚠️ **Caution:** such conversion can be quite lossy, and in most cases it's probably not what you want!

To bisync Google Docs as URL shortcut links (in a manner similar to "Drive for Desktop"), use: `--drive-export-formats url` (or alternatives.)

Note that these link files **cannot** be edited on the non-drive side — you will get errors if you try to sync an edited link file back to drive. They **CAN** be deleted (it will result in deleting the corresponding Google Doc.) If you create a `.url` file on the non-drive side that does not match an existing Google Doc, bisyncing it will just result in copying the literal `.url` file over to drive (no Google Doc will be created.) So, as a general rule of thumb, think of them as read-only placeholders on the non-drive side, and make all your changes on the drive side. 👑

Likewise, even with other export-formats, it is best to only move/rename Google Docs on the drive side. This is because otherwise, bisync will interpret this as a file deleted and another created, and accordingly, it will delete the Google Doc and create a new file at the new path. (Whether or not that new file is a Google Doc depends on `--drive-import-formats`.) 😭

Lastly, take note that all Google Docs on the drive side have a size of `-1` and no checksum. Therefore, they cannot be reliably synced with the `--checksum` or `--size-only` flags. (To be exact: they will still get created/deleted, and bisync's delta engine will notice changes and queue them for syncing, but the underlying sync function will consider them identical and skip them.) To work around this, use the default (modtime and size) instead of `--checksum` or `--size-only`. 🧚

To ignore Google Docs entirely, use `--drive-skip-gdocs`. 🦋

---

### 🌸 Usage examples 🌸

### ⏰ Cron ⏰

Rclone does not yet have a built-in capability to monitor the local file system for changes, so it must be blindly run periodically 🙃. On Windows this can be done using a Task Scheduler, on Linux you can use Cron, which is described below.

The 1st example runs a sync every 5 minutes between a local directory and an OwnCloud server, with output logged to a runlog file:

Minute (0-59)

Hour (0-23)

Day of Month (1-31)

Month (1-12 or Jan-Dec)

Day of Week (0-6 or Sun-Sat)

Command

*/5 * * * * /path/to/rclone bisync /local/files MyCloud: --check-access --filters-file /path/to/bysync-filters.txt --log-file /path/to//bisync.log


See `crontab` syntax for the details of crontab time interval expressions.

If you run `rclone bisync` as a cron job, redirect stdout/stderr to a file. The 2nd example runs a sync to Dropbox every hour and logs all stdout (via the `>>`) and stderr (via `2>&1`) to a log file.

0 * * * * /path/to/rclone bisync /path/to/local/dropbox Dropbox: --check-access --filters-file /home/user/filters.txt >> /path/to/logs/dropbox-run.log 2>&1


---

### 🧚 Sharing an encrypted folder tree between hosts

`bisync` can keep a local folder in sync with a cloud service, but what if you have some <hotpink>highly sensitive files</hotpink> to be synched? 😳

Usage of a cloud service is for exchanging both routine and sensitive personal files between one's home network, one's personal notebook when on the road, and with one's work computer. The routine data is not sensitive. For the sensitive data, configure an rclone crypt remote to point to a subdirectory within the local disk tree that is bisync'd to Dropbox, and then set up an bisync for this local crypt directory to a directory outside of the main sync tree. 🫶

#### 🐧 Linux server setup

- `/path/to/DBoxroot` is the root of my local sync tree. There are numerous subdirectories.
- `/path/to/DBoxroot/crypt` is the root subdirectory for files that are encrypted. This local directory target is setup as an rclone crypt remote named `Dropcrypt:`. See `rclone.conf` snippet below.
- `/path/to/my/unencrypted/files` is the root of my sensitive files — not encrypted, not within the tree synched to Dropbox.
- To sync my local unencrypted files with the encrypted Dropbox versions I manually run `bisync /path/to/my/unencrypted/files DropCrypt:`. This step could be bundled into a script to run before and after the full Dropbox tree sync in the last step, thus actively keeping the sensitive files in sync.
- `bisync /path/to/DBoxroot Dropbox:` runs periodically via cron, keeping my full local sync tree in sync with Dropbox.

#### 🪟 Windows notebook setup

- The Dropbox client runs keeping the local tree `C:\Users\MyLogin\Dropbox` always in sync with Dropbox. I could have used `rclone bisync` instead.
- A separate directory tree at `C:\Users\MyLogin\Documents\DropLocal` hosts the tree of unencrypted files/folders.
- To sync my local unencrypted files with the encrypted Dropbox versions I manually run the following command: `rclone bisync C:\Users\MyLogin\Documents\DropLocal Dropcrypt:`.
- The Dropbox client then syncs the changes with Dropbox.

#### 📄 rclone.conf snippet

[Dropbox] type = dropbox ...

[Dropcrypt] type = crypt remote = /path/to/DBoxroot/crypt # on the Linux server remote = C:\Users\MyLogin\Dropbox\crypt # on the Windows notebook filename_encryption = standard directory_name_encryption = true password = ... ...


---

### 🧪 Testing

You should read this section only if you are developing for rclone. You need to have rclone source code locally to work with bisync tests. 👩‍💻

Bisync has a dedicated test framework implemented in the `bisync_test.go` file located in the rclone source tree. The test suite is based on the `go test` command. Series of tests are stored in subdirectories below the `cmd/bisync/testdata` directory. Individual tests can be invoked by their directory name, e.g. `go test . -case basic -remote local -remote2 gdrive: -v` ✨

Tests will make a temporary folder on remote and purge it afterwards. If during test run there are intermittent errors and rclone retries, these errors will be captured and flagged as invalid MISCOMPAREs. Rerunning the test will let it pass. Consider such failures as noise. 🫠

#### ⌨️ Test command syntax

usage: go test ./cmd/bisync [options...]

Options: -case NAME Name(s) of the test case(s) to run. Multiple names should be separated by commas. You can remove the test_ prefix and replace _ by - in test name for convenience. If not all, the name(s) should map to a directory under ./cmd/bisync/testdata. Use all to run all tests (default: all) -remote PATH1 local or name of cloud service with : (default: local) -remote2 PATH2 local or name of cloud service with : (default: local) -no-compare Disable comparing test results with the golden directory (default: compare) -no-cleanup Disable cleanup of Path1 and Path2 testdirs. Useful for troubleshooting. (default: cleanup) -golden Store results in the golden directory (default: false) This flag can be used with multiple tests. -debug Print debug messages -stop-at NUM Stop test after given step number. (default: run to the end) Implies -no-compare and -no-cleanup, if the test really ends prematurely. Only meaningful for a single test case. -refresh-times Force refreshing the target modtime, useful for Dropbox (default: false) -verbose Run tests verbosely


Note: unlike rclone flags which must be prefixed by double dash (`--`), the test command flags can be equally prefixed by a single `-` or double dash. 💅

#### 🏃 Running tests

- `go test . -case basic -remote local -remote2 local` runs the `test_basic` test case using only the local filesystem, syncing one local directory with another local directory. Test script output is to the console, while commands within `scenario.txt` have their output sent to the `.../workdir/test.log` file, which is finally compared to the golden copy.
- The first argument after `go test` should be a relative name of the directory containing `bisync` source code. If you run tests right from there, the argument will be `.` (current directory) as in most examples below. If you run bisync tests from the rclone source directory, the command should be `go test ./cmd/bisync ...`.
- The test engine will mangle rclone output to ensure comparability with golden listings and logs.
- Test scenarios are located in `./cmd/bisync/testdata`. The test `-case` argument should match the full name of a subdirectory under that directory. Every test subdirectory name on disk must start with `test_`, this prefix can be omitted on command line for brevity. Also, underscores in the name can be replaced by dashes for convenience.
- `go test . -remote local -remote2 local -case all` runs all tests.
- `Path1` and `Path2` may either be the keyword `local` or may be names of configured cloud services. `go test . -remote gdrive: -remote2 dropbox: -case basic` will run the test between these two services, without transferring any files to the local filesystem.
- Test run stdout and stderr console output may be directed to a file, e.g. `go test . -remote gdrive: -remote2 local -case all > runlog.txt 2>&1`

#### 🔄 Test execution flow

1. The base setup in the initial directory of the testcase is applied on the `Path1` and `Path2` filesystems (via `rclone copy` the initial directory to `Path1`, then `rclone sync Path1 to Path2`).
2. The commands in the `scenario.txt` file are applied, with output directed to the `test.log` file in the test working directory. Typically, the first actual command in the `scenario.txt` file is to do a `--resync`, which establishes the baseline `{...}.path1.lst` and `{...}.path2.lst` files in the test working directory (`.../workdir/` relative to the temporary test directory). Various commands and listing snapshots are done within the test.
3. Finally, the contents of the test working directory are compared to the contents of the testcase's golden directory.

#### 📝 Notes about testing

- Test cases are in individual directories beneath `./cmd/bisync/testdata`. A command line reference to a test is understood to reference a directory beneath `testdata`. For example, `go test ./cmd/bisync -case dry-run -remote gdrive: -remote2 local` refers to the test case in `./cmd/bisync/testdata/test_dry_run`.
- The test working directory is located at `.../workdir` relative to a temporary test directory, usually under `/tmp` on Linux.
- The local test sync tree is created at a temporary directory named like `bisync.XXX` under system temporary directory.
- The remote test sync tree is located at a temporary directory under `<remote:>/bisync.XXX/`.
- `path1` and/or `path2` subdirectories are created in a temporary directory under the respective local or cloud test remote.
- By default, the `Path1` and `Path2` test dirs and `workdir` will be deleted after each test run. The `-no-cleanup` flag disables purging these directories when validating and debugging a given test. These directories will be flushed before running another test, independent of the `-no-cleanup` usage.
- You will likely want to add `- /testdir/` to your normal `bisync --filters-file` so that normal syncs do not attempt to sync the test temporary directories, which may have `RCLONE_TEST` miscompares in some testcases which would otherwise trip the `--check-access` system. The `--check-access` mechanism is hard-coded to ignore `RCLONE_TEST` files beneath `bisync/testdata`, so the test cases may reside on the synched tree even if there are check file mismatches in the test tree.
- Some Dropbox tests can fail, notably printing the following message: `src and dst identical but can't set mod time without deleting and re-uploading` This is expected and happens due to the way Dropbox handles modification times. You should use the `-refresh-times` test flag to make up for this.
- If Dropbox tests hit request limit for you and print error message `too_many_requests/...: Too many requests or write operations.` then follow the Dropbox App ID instructions.

#### 🌟 Updating golden results

Sometimes even a slight change in the bisync source can cause little changes spread around many log files. Updating them manually would be a nightmare. 😭

The `-golden` flag will store the `test.log` and `*.lst` listings from each test case into respective golden directories. Golden results will automatically contain generic strings instead of local or cloud paths which means that they should match when run with a different cloud service. 👑

Your normal workflow might be as follows:

1. Git-clone the rclone sources locally 🫶
2. Modify bisync source and check that it builds
3. Run the whole test suite

go test ./cmd/bisync -remote local

4. If some tests show log difference, recheck them individually, e.g.:

go test ./cmd/bisync -remote local -case basic

5. If you are convinced with the difference, goldenize all tests at once:

go test ./cmd/bisync -remote local -golden

6. Use word diff:

git diff --word-diff ./cmd/bisync/testdata/

<hotpink>Please note</hotpink> that normal line-level diff is generally useless here. Like, it's giving noise 😭
7. Check the difference carefully! Fr fr, actually look at it 👀
8. Commit the change (`git commit`) <red>only if you are sure</red>. If unsure, save your code changes then wipe the log diffs from git:

git reset [--hard]


---

## 🌸 Structure of test scenarios 🌸

- `<testname>/initial/` contains a tree of files that will be set as the initial condition on both Path1 and Path2 testdirs.
- `<testname>/modfiles/` contains files that will be used to modify the Path1 and/or Path2 filesystems.
- `<testname>/golden/` contains the expected content of the test working directory (workdir) at the completion of the testcase.
- `<testname>/scenario.txt` contains the body of the test, in the form of various commands to modify files, run bisync, and snapshot listings. Output from these commands is captured to `.../workdir/test.log` for comparison to the golden files.

---

## 🎀 Supported test commands 🎀

- **`test <some message>`** — Print the line to the console and to the `test.log`:

test sync is working correctly with options x, y, z

- **`copy-listings <prefix>`** — Save a copy of all `.lst` listings in the test working directory with the specified prefix:

save-listings exclude-pass-run

- **`move-listings <prefix>`** — Similar to `copy-listings` but removes the source
- **`purge-children <dir>`** — This will delete all child files and purge all child subdirs under given directory but keep the parent intact. This behavior is important for tests with Google Drive because removing and re-creating the parent would change its ID. (iykyk 💅)
- **`delete-file <file>`** — Delete a single file.
- **`delete-glob <dir> <pattern>`** — Delete a group of files located one level deep in the given directory with names matching a given glob pattern.
- **`touch-glob YYYY-MM-DD <dir> <pattern>`** — Change modification time on a group of files.
- **`touch-copy YYYY-MM-DD <source-file> <dest-dir>`** — Change file modification time then copy it to destination.
- **`copy-file <source-file> <dest-dir>`** — Copy a single file to given directory.
- **`copy-as <source-file> <dest-file>`** — Similar to above but destination must include both directory and the new file name at destination.
- **`copy-dir <src> <dst>`** and **`sync-dir <src> <dst>`** — Copy/sync a directory. Equivalent of `rclone copy` and `rclone sync`.
- **`list-dirs <dir>`** — Equivalent to `rclone lsf -R --dirs-only <dir>`
- **`bisync [options]`** — Runs bisync against `-remote` and `-remote2`.

---

## 🦋 Supported substitution terms 🦋

- `{testdir/}` - the root dir of the testcase
- `{datadir/}` - the modfiles dir under the testcase root
- `{workdir/}` - the temporary test working directory
- `{path1/}` - the root of the Path1 test directory tree
- `{path2/}` - the root of the Path2 test directory tree
- `{session}` - base name of the test listings
- `{/}` - OS-specific path separator
- `{spc}`, `{tab}`, `{eol}` - whitespace
- `{chr:HH}` - raw byte with given hexadecimal code

Substitution results of the terms named like `{dir/}` will end with `/` (or backslash on Windows), so it is not necessary to include slash in the usage, for example `delete-file {path1/}file1.txt`.

---

## ✨ Benchmarks ✨

This section is <yellow>work in progress</yellow>.

Here are a few data points for scale, execution times, and memory usage. 📊

The first set of data was taken between a local disk to Dropbox. The speedtest.net download speed was ~170 Mbps, and upload speed was ~10 Mbps. 500 files (~9.5 MB each) had been already synched. 50 files were added in a new directory, each ~9.5 MB, ~475 MB total.

- **500 files synched (nothing to move)** — Operations and times: 1x listings for Path1 & Path2 — Overall run time: 1.5 sec
- **500 files synched with `--check-access`** — Operations and times: 1x listings for Path1 & Path2 — Overall run time: 1.5 sec
- **50 new files on remote** — Operations and times: Queued 50 copies down: 27 sec — Overall run time: 29 sec
- **Moved local dir** — Operations and times: Queued 50 copies up: 410 sec, 50 deletes up: 9 sec — Overall run time: 421 sec
- **Moved remote dir** — Operations and times: Queued 50 copies down: 31 sec, 50 deletes down: <1 sec — Overall run time: 33 sec
- **Delete local dir** — Operations and times: Queued 50 deletes up: 9 sec — Overall run time: 13 sec

This next data is from a user's application. They had ~400GB of data over 1.96 million files being sync'ed between a Windows local disk and some remote cloud. The file full path length was on average 35 characters (which factors into load time and RAM required). 😳

- Loading the prior listing into memory (1.96 million files, listing file size 140 MB) took ~30 sec and occupied about 1 GB of RAM.
- Getting a fresh listing of the local file system (producing the 140 MB output file) took about XXX sec.
- Getting a fresh listing of the remote file system (producing the 140 MB output file) took about XXX sec. The network download speed was measured at XXX Mb/s.
- Once the prior and current Path1 and Path2 listings were loaded (a total of four to be loaded, two at a time), determining the deltas was pretty quick (a few seconds for this test case), and the transfer time for any files to be copied was dominated by the network bandwidth.

---

## 💜 References 💜

rclone's bisync implementation was derived from the rclonesync-V2 project, including documentation and test mechanisms, with @cjnaz's full support and encouragement. 👑

rclone bisync is similar in nature to a range of other projects:

- unison
- syncthing
- cjnaz/rclonesync
- ConorWilliams/rsinc
- jwink3101/syncrclone
- DavideRossi/upback

Bisync adopts the differential synchronization technique, which is based on keeping history of changes performed by both synchronizing sides. See the Dual Shadow Method section in Neil Fraser's article.

Also note a number of academic publications by Benjamin Pierce about Unison and synchronization in general. 📚

---

## 🌈 Changelog 🌈

### v1.69.1

- Fixed an issue causing listings to not capture concurrent modifications under certain conditions

### v1.68

- Fixed an issue affecting backends that round modtimes to a lower precision.

### v1.67

- Added integration tests against all backends.

### v1.66

- Copies and deletes are now handled in one operation instead of two
- `--track-renames` and `--backup-dir` are now supported
- Partial uploads known issue on local/ftp/sftp has been resolved (unless using `--inplace`)
- Final listings are now generated from sync results, to avoid needing to re-list
- Bisync is now much more resilient to changes that happen during a bisync run, and far less prone to critical errors / undetected changes
- Bisync is now capable of rolling a file listing back in cases of uncertainty, essentially marking the file as needing to be rechecked next time.
- A few basic terminal colors are now supported, controllable with `--color` (AUTO|NEVER|ALWAYS)
- Initial listing snapshots of Path1 and Path2 are now generated concurrently, using the same "march" infrastructure as check and sync, for performance improvements and less risk of error.
- Fixed handling of unicode normalization and case insensitivity, support for `--fix-case`, `--ignore-case-sync`, `--no-unicode-normalization`
- `--resync` is now much more efficient (especially for users of `--create-empty-src-dirs`)
- Google Docs (and other files of unknown size) are now supported (with the same options as in sync)
- Equality checks before a sync conflict rename now fall back to cryptcheck (when possible) or `--download`, instead of of `--size-only`, when check is not available.
- Bisync no longer fails to find the correct listing file when configs are overridden with backend-specific flags.
- Bisync now fully supports comparing based on any combination of size, modtime, and checksum, lifting the prior restriction on backends without modtime support.
- Bisync now supports a "Graceful Shutdown" mode to cleanly cancel a run early without requiring `--resync`.
- New `--recover` flag allows robust recovery in the event of interruptions, without requiring `--resync`.
- A new `--max-lock` setting allows lock files to automatically renew and expire, for better automatic recovery when a run is interrupted.
- Bisync now supports auto-resolving sync conflicts and customizing rename behavior with new `--conflict-resolve`, `--conflict-loser`, and `--conflict-suffix` flags.
- A new `--resync-mode` flag allows more control over which version of a file gets kept during a `--resync`.
- Bisync now supports `--retries` and `--retries-sleep` (when `--resilient` is set.)

### v1.64

- Fixed an issue causing dry runs to inadvertently commit filter changes
- Fixed an issue causing `--resync` to erroneously delete empty folders and duplicate files unique to Path2
- `--check-access` is now enforced during `--resync`, preventing data loss in certain user error scenarios
- Fixed an issue causing bisync to consider more files than necessary due to overbroad filters during delete operations
- Improved detection of false positive change conflicts (identical files are now left alone instead of renamed)
- Added support for `--create-empty-src-dirs`
- Added experimental `--resilient` mode to allow recovery from self-correctable errors
- Added new `--ignore-listing-checksum` flag to distinguish from `--ignore-checksum`
- Performance improvements for large remotes
- Documentation and testing improvements

# 💖 Release signing 💖

okay bestie, this is the part where we make sure nobody's out here handing you a cursed bootleg rclone. The hashes of the binary artefacts of the rclone release are signed with a public PGP/GPG key 🔐, and you can verify that by hand, exactly like we're about to do below.

The same mechanism is also used by `rclone selfupdate` to verify that the release has not been tampered with before the new update is installed. It checks the **SHA256 hash** and the **signature** with a public key compiled right into the rclone binary 🫶. so like, rclone is checking its own homework, but with cryptography. slay.

---

## 🔑 Release signing key

You may obtain the release signing key from:

- From `KEYS` on this website — this file contains all past signing keys also.
- The git repository hosted on GitHub — `https://github.com/rclone/rclone/blob/master/docs/content/KEYS`
- `gpg --keyserver hkps://keys.openpgp.org --search nick@craig-wood.com`
- `gpg --keyserver hkps://keyserver.ubuntu.com --search nick@craig-wood.com`
- `https://www.craig-wood.com/nick/pub/pgp-key.txt`

After importing the key, verify that the fingerprint of one of the keys matches: `FBF737ECE9F8AB18604BD2AC93935E02FF3B54FA` as this key is used for signing. <hotpink>like, that fingerprint has to match match, no vibes-based trust here bestie</hotpink> 💅

We recommend that you cross-check the fingerprint shown above through the domains listed below. By cross-checking the integrity of the fingerprint across multiple domains you can be confident that you obtained the correct key. 🔍✨

- The source for this page on GitHub.
- Through DNS `dig key.rclone.org txt`

> 🚨 If you find anything that doesn't match, please contact the developers **at once**. not later, not after your snack. AT ONCE.

---

## 🧐 How to verify the release

In the release directory you will see the release files and some files called `MD5SUMS`, `SHA1SUMS` and `SHA256SUMS`. they're giving receipts 💅

$ rclone lsf --http-url https://downloads.rclone.org/v1.63.1 :http: MD5SUMS SHA1SUMS SHA256SUMS rclone-v1.63.1-freebsd-386.zip rclone-v1.63.1-freebsd-amd64.zip ... rclone-v1.63.1-windows-arm64.zip rclone-v1.63.1.tar.gz version.txt


The `MD5SUMS`, `SHA1SUMS` and `SHA256SUMS` contain hashes of the binary files in the release directory along with a signature. ✍️

For example:

$ rclone cat --http-url https://downloads.rclone.org/v1.63.1 :http:SHA256SUMS -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

f6d1b2d7477475ce681bdce8cb56f7870f174cb6b2a9ac5d7b3764296ea4a113 rclone-v1.63.1-freebsd-386.zip 7266febec1f01a25d6575de51c44ddf749071a4950a6384e4164954dff7ac37e rclone-v1.63.1-freebsd-amd64.zip ... 66ca083757fb22198309b73879831ed2b42309892394bf193ff95c75dff69c73 rclone-v1.63.1-windows-amd64.zip bbb47c16882b6c5f2e8c1b04229378e28f68734c613321ef0ea2263760f74cd0 rclone-v1.63.1-windows-arm64.zip -----BEGIN PGP SIGNATURE-----

iF0EARECAB0WIQT79zfs6firGGBL0qyTk14C/ztU+gUCZLVKJQAKCRCTk14C/ztU +pZuAJ0XJ+QWLP/3jCtkmgcgc4KAwd/rrwCcCRZQ7E+oye1FPY46HOVzCFU3L7g= =8qrL -----END PGP SIGNATURE-----


look at that gorgeous little signature block 💖 so demure, so cryptographic.

---

## 📥 Download the files

The first step is to download the binary and the `SUMs` file and verify that the `SUMs` you have downloaded match. Here we download `rclone-v1.63.1-windows-amd64.zip` — choose the binary (or binaries) appropriate to your architecture. We've also chosen the `SHA256SUMS` as these are the most secure. You could verify the other types of hash also for extra security 🔥. `rclone selfupdate` verifies just the `SHA256SUMS`.

$ mkdir /tmp/check $ cd /tmp/check $ rclone copy --http-url https://downloads.rclone.org/v1.63.1 :http:SHA256SUMS . $ rclone copy --http-url https://downloads.rclone.org/v1.63.1 :http:rclone-v1.63.1-windows-amd64.zip .


okay we love a `mkdir`, we love a `cd`, we love downloading exactly two things 🎀

---

## ✍️ Verify the signatures

First verify the signatures on the `SHA256` file.

Import the key. See above for ways to verify this key is correct. 😇

$ gpg --keyserver keyserver.ubuntu.com --receive-keys FBF737ECE9F8AB18604BD2AC93935E02FF3B54FA gpg: key 93935E02FF3B54FA: public key "Nick Craig-Wood <nick@craig-wood.com>" imported gpg: Total number processed: 1 gpg: imported: 1


Then check the signature:

$ gpg --verify SHA256SUMS gpg: Signature made Mon 17 Jul 2023 15:03:17 BST gpg: using DSA key FBF737ECE9F8AB18604BD2AC93935E02FF3B54FA gpg: Good signature from "Nick Craig-Wood <nick@craig-wood.com>" [ultimate]


Verify the signature was good and is using the fingerprint shown above. ✅ <mint>Good signature</mint> is the phrase you're looking for, bestie — anything else and we do NOT proceed.

Repeat for `MD5SUMS` and `SHA1SUMS` if desired.

---

## #️⃣ Verify the hashes

Now that we know the signatures on the hashes are `OK` we can verify the binaries match the hashes, completing the verification. 🦋

$ sha256sum -c SHA256SUMS 2>&1 | grep OK rclone-v1.63.1-windows-amd64.zip: OK


Or do the check with rclone:

$ rclone hashsum sha256 -C SHA256SUMS rclone-v1.63.1-windows-amd64.zip 2023/09/11 10:53:58 NOTICE: SHA256SUMS: improperly formatted checksum line 0 2023/09/11 10:53:58 NOTICE: SHA256SUMS: improperly formatted checksum line 1 2023/09/11 10:53:58 NOTICE: SHA256SUMS: improperly formatted checksum line 49 2023/09/11 10:53:58 NOTICE: SHA256SUMS: 4 warning(s) suppressed... = rclone-v1.63.1-windows-amd64.zip 2023/09/11 10:53:58 NOTICE: Local file system at /tmp/check: 0 differences found 2023/09/11 10:53:58 NOTICE: Local file system at /tmp/check: 1 matching files


those `NOTICE` lines are just the `SUMS` files being extra (they've got PGP boilerplate in them, so rclone complains about the formatting) — the part that matters is `0 differences found` and `1 matching files` 🫶💜

---

## 🏆 Verify signatures and hashes together

You can verify the signatures and hashes in one command line like this, because we are efficiency girlies:

$ h=$(gpg --decrypt SHA256SUMS) && echo "$h" | sha256sum - -c --ignore-missing gpg: Signature made Mon 17 Jul 2023 15:03:17 BST gpg: using DSA key FBF737ECE9F8AB18604BD2AC93935E02FF3B54FA gpg: Good signature from "Nick Craig-Wood <nick@craig-wood.com>" [ultimate] gpg: aka "Nick Craig-Wood <nick@memset.com>" [unknown] rclone-v1.63.1-windows-amd64.zip: OK


one `gpg --decrypt`, one `sha256sum - -c --ignore-missing`, and boom 💥 — signature verified **and** hash verified in a single line. that's the moment. that's the payoff. you just confirmed your download is the real deal and not some imposter with main character energy it didn't earn 👑

# 🌸 1Fichier

Okay bestie, so this one is a backend for the **1fichier** cloud storage service. <red>Heads up tho</red>: you literally *need* a **Premium subscription** to use the API. No premium, no party. 💅

Paths are specified as `remote:path`

And they can go as deep as you want, like `remote:directory/subdirectory`. Go off, nest those folders. 🦋

---

## ✨ Configuration

The initial setup for 1Fichier involves grabbing the **API key** from the website, and ngl you have to do that part in your browser. 🧚

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / 1Fichier \ "fichier" [snip] Storage> fichier ** See help for fichier backend at: https://rclone.org/fichier/ **

Your API Key, get it from https://1fichier.com/console/params.pl Enter a string value. Press Enter for the default (""). api_key> example_key

Edit advanced config? (y/n) y) Yes n) No y/n> Remote config Configuration complete. Options:

type: fichier
api_key: example_key Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can then use rclone like this,

List directories in top level of your 1Fichier account 💖

rclone lsd remote:


List all the files in your 1Fichier account

rclone ls remote:


To copy a local directory to a 1Fichier directory called backup

rclone copy /home/source remote:backup


---

## 🕐 Modification times and hashes

So <purple>1Fichier does not support modification times</purple>. What it *does* support is the **Whirlpool** hash algorithm. Slay cryptography. 🔥

---

## 👯 Duplicated files

1Fichier can have **two files with exactly the same name and path** (unlike a normal file system). The audacity honestly. 💀

> Duplicated files cause problems with the syncing and you will see messages in the log about duplicates.

---

## 🚫 Restricted filename characters

In addition to the default restricted characters set, these characters are also replaced:

Character Value Replacement ──────────────────────────────── \ 0x5C ＼ < 0x3C ＜

0x3E ＞

” 0x22 ＂ $ 0x24 ＄ ` 0x60 ｀ ’ 0x27 ＇


File names can also **not start or end** with the following characters. These only get replaced if they are the *first* or *last* character in the name:

Character Value Replacement ──────────────────────────────── SP 0x20 ␠


Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. Periodt. ✨

---

## ⭐ Standard options

Here are the Standard options specific to `fichier` (1Fichier).

### 💖 `--fichier-api-key`

Your API Key, get it from https://1fichier.com/console/params.pl.

Properties:

- **Config:** `api_key`
- **Env Var:** `RCLONE_FICHIER_API_KEY`
- **Type:** string
- **Required:** false

---

## 🔥 Advanced options

Here are the Advanced options specific to `fichier` (1Fichier).

### 🌸 `--fichier-shared-folder`

If you want to download a shared folder, add this parameter.

Properties:

- **Config:** `shared_folder`
- **Env Var:** `RCLONE_FICHIER_SHARED_FOLDER`
- **Type:** string
- **Required:** false

### 🔐 `--fichier-file-password`

If you want to download a shared file that is password protected, add this parameter.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- **Config:** `file_password`
- **Env Var:** `RCLONE_FICHIER_FILE_PASSWORD`
- **Type:** string
- **Required:** false

### 🔐 `--fichier-folder-password`

If you want to list the files in a shared folder that is password protected, add this parameter.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- **Config:** `folder_password`
- **Env Var:** `RCLONE_FICHIER_FOLDER_PASSWORD`
- **Type:** string
- **Required:** false

### 🌈 `--fichier-cdn`

Set if you wish to use CDN download links.

Properties:

- **Config:** `cdn`
- **Env Var:** `RCLONE_FICHIER_CDN`
- **Type:** bool
- **Default:** false

### 🎀 `--fichier-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_FICHIER_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,LtGt,DoubleQuote,SingleQuote,BackQuote,Dollar,BackSlash,Del,Ctl,LeftSpace,RightSpace,InvalidUtf8,Dot`

### 💜 `--fichier-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_FICHIER_DESCRIPTION`
- **Type:** string
- **Required:** false

---

## 😭 Limitations

`rclone about` is **not supported** by the 1Fichier backend. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote. Like, it just can't, bestie. 🙈

See <cyan>List of backends that do not support rclone about</cyan> and `rclone about`

---

# 🦋 Alias

The `alias` remote provides a **new name for another remote**. It's giving nickname energy, but for storage. 👑

Paths may be as deep as required or a local path, e.g. `remote:directory/subdirectory` or `/directory/subdirectory`.

During the initial setup with `rclone config` you will specify the **target remote**. The target remote can either be a local path or another remote.

Subfolders can be used in target remote. Assume an alias remote named `backup` with the target `mydrive:private/backup`. Invoking `rclone mkdir backup:desktop` is *exactly* the same as invoking `rclone mkdir mydrive:private/backup/desktop`.

There will be **no special handling of paths containing `..` segments**. Invoking `rclone mkdir backup:../desktop` is exactly the same as invoking `rclone mkdir mydrive:private/backup/../desktop`. The empty path is **not allowed** as a remote. To alias the current directory use `.` instead.

The target remote can also be a **connection string**. This can be used to modify the config of a remote for different uses, e.g. the alias `myDriveTrash` with the target remote `myDrive,trashed_only:` can be used to only show the trashed files in `myDrive`. Obsessed with this trick fr fr. 💅

---

## ✨ Configuration

Here is an example of how to make an alias called `remote` for local folder. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Alias for an existing remote \ "alias" [snip] Storage> alias Remote or path to alias. Can be "myremote:path/to/dir", "myremote:bucket", "myremote:" or "/local/path". remote> /mnt/storage/backup Remote config Configuration complete. Options:

type: alias
remote: /mnt/storage/backup Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== remote alias

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> q


Once configured you can then use rclone like this,

List directories in top level in `/mnt/storage/backup`

rclone lsd remote:


List all the files in `/mnt/storage/backup`

rclone ls remote:


Copy another local directory to the alias directory called source

rclone copy /home/source remote:source


---

## ⭐ Standard options

Here are the Standard options specific to `alias` (Alias for an existing remote).

### 🎀 `--alias-remote`

Remote or path to alias.

Can be `"myremote:path/to/dir"`, `"myremote:bucket"`, `"myremote:"` or `"/local/path"`.

Properties:

- **Config:** `remote`
- **Env Var:** `RCLONE_ALIAS_REMOTE`
- **Type:** string
- **Required:** true

---

## 💜 Advanced options

Here are the Advanced options specific to `alias` (Alias for an existing remote).

### ✨ `--alias-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_ALIAS_DESCRIPTION`
- **Type:** string
- **Required:** false

---

# 👑 Amazon S3 Storage Providers

The S3 backend can be used with a **number** of different providers, and like, the range is giving versatility:

- AWS S3
- Alibaba Cloud (Aliyun) Object Storage System (OSS)
- Ceph
- China Mobile Ecloud Elastic Object Storage (EOS)
- Cloudflare R2
- Arvan Cloud Object Storage (AOS)
- DigitalOcean Spaces
- Dreamhost
- GCS
- Huawei OBS
- IBM COS S3
- IDrive e2
- IONOS Cloud
- Leviia Object Storage
- Liara Object Storage
- Linode Object Storage
- Magalu Object Storage
- Minio
- Outscale
- Petabox
- Qiniu Cloud Object Storage (Kodo)
- RackCorp Object Storage
- Rclone Serve S3
- Scaleway
- Seagate Lyve Cloud
- SeaweedFS
- Selectel
- StackPath
- Storj
- Synology C2 Object Storage
- Tencent Cloud Object Storage (COS)
- Wasabi

Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`. 👑

Once you have made a remote (see the provider specific section above) you can use it like this:

See all buckets 🌈

rclone lsd remote:


Make a new bucket

rclone mkdir remote:bucket


List the contents of a bucket

rclone ls remote:bucket


Sync `/home/local/directory` to the remote bucket, deleting any excess files in the bucket. ⚠️ yes it deletes, that's the whole point of sync, don't come for me.

rclone sync --interactive /home/local/directory remote:bucket


---

## ✨ Configuration

Here is an example of making an `s3` configuration for the **AWS S3** provider. Most applies to the other providers as well, any differences are described below.

First run

rclone config


This will guide you through an interactive setup process.

okay bestie, here's the <rainbow>actual receipts</rainbow> — what it looks like when you run `rclone config`, say yes to a new remote, and pick S3 from the list. Every prompt, every menu, every vibe. Watch and learn 💅✨

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3" [snip] Storage> s3 Choose your S3 provider. Choose a number from below, or type in your own value 1 / Amazon Web Services (AWS) S3 \ "AWS" 2 / Ceph Object Storage \ "Ceph" 3 / DigitalOcean Spaces \ "DigitalOcean" 4 / Dreamhost DreamObjects \ "Dreamhost" 5 / IBM COS S3 \ "IBMCOS" 6 / Minio Object Storage \ "Minio" 7 / Wasabi Object Storage \ "Wasabi" 8 / Any other S3 compatible provider \ "Other" provider> 1 Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> XXX AWS Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> YYY Region to connect to. Choose a number from below, or type in your own value / The default endpoint - a good choice if you are unsure. 1 | US Region, Northern Virginia, or Pacific Northwest.

Leave location constraint empty.

\ "us-east-1" / US East (Ohio) Region 2 | Needs location constraint us-east-2. \ "us-east-2" / US West (Oregon) Region 3 | Needs location constraint us-west-2. \ "us-west-2" / US West (Northern California) Region 4 | Needs location constraint us-west-1. \ "us-west-1" / Canada (Central) Region 5 | Needs location constraint ca-central-1. \ "ca-central-1" / EU (Ireland) Region 6 | Needs location constraint EU or eu-west-1. \ "eu-west-1" / EU (London) Region 7 | Needs location constraint eu-west-2. \ "eu-west-2" / EU (Frankfurt) Region 8 | Needs location constraint eu-central-1. \ "eu-central-1" / Asia Pacific (Singapore) Region 9 | Needs location constraint ap-southeast-1. \ "ap-southeast-1" / Asia Pacific (Sydney) Region 10 | Needs location constraint ap-southeast-2. \ "ap-southeast-2" / Asia Pacific (Tokyo) Region 11 | Needs location constraint ap-northeast-1. \ "ap-northeast-1" / Asia Pacific (Seoul) 12 | Needs location constraint ap-northeast-2. \ "ap-northeast-2" / Asia Pacific (Mumbai) 13 | Needs location constraint ap-south-1. \ "ap-south-1" / Asia Pacific (Hong Kong) Region 14 | Needs location constraint ap-east-1. \ "ap-east-1" / South America (Sao Paulo) Region 15 | Needs location constraint sa-east-1. \ "sa-east-1" region> 1 Endpoint for S3 API. Leave blank if using AWS to use the default endpoint for the region. endpoint> Location constraint - must be set to match the Region. Used when creating buckets only. Choose a number from below, or type in your own value 1 / Empty for US Region, Northern Virginia, or Pacific Northwest. \ "" 2 / US East (Ohio) Region. \ "us-east-2" 3 / US West (Oregon) Region. \ "us-west-2" 4 / US West (Northern California) Region. \ "us-west-1" 5 / Canada (Central) Region. \ "ca-central-1" 6 / EU (Ireland) Region. \ "eu-west-1" 7 / EU (London) Region. \ "eu-west-2" 8 / EU Region. \ "EU" 9 / Asia Pacific (Singapore) Region. \ "ap-southeast-1" 10 / Asia Pacific (Sydney) Region. \ "ap-southeast-2" 11 / Asia Pacific (Tokyo) Region. \ "ap-northeast-1" 12 / Asia Pacific (Seoul) \ "ap-northeast-2" 13 / Asia Pacific (Mumbai) \ "ap-south-1" 14 / Asia Pacific (Hong Kong) \ "ap-east-1" 15 / South America (Sao Paulo) Region. \ "sa-east-1" location_constraint> 1 Canned ACL used when creating buckets and/or storing objects in S3. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). \ "private" 2 / Owner gets FULL_CONTROL. The AllUsers group gets READ access. \ "public-read" / Owner gets FULL_CONTROL. The AllUsers group gets READ and WRITE access. 3 | Granting this on a bucket is generally not recommended. \ "public-read-write" 4 / Owner gets FULL_CONTROL. The AuthenticatedUsers group gets READ access. \ "authenticated-read" / Object owner gets FULL_CONTROL. Bucket owner gets READ access. 5 | If you specify this canned ACL when creating a bucket, Amazon S3 ignores it. \ "bucket-owner-read" / Both the object owner and the bucket owner get FULL_CONTROL over the object. 6 | If you specify this canned ACL when creating a bucket, Amazon S3 ignores it. \ "bucket-owner-full-control" acl> 1 The server-side encryption algorithm used when storing this object in S3. Choose a number from below, or type in your own value 1 / None \ "" 2 / AES256 \ "AES256" server_side_encryption> 1 The storage class to use when storing objects in S3. Choose a number from below, or type in your own value 1 / Default \ "" 2 / Standard storage class \ "STANDARD" 3 / Reduced redundancy storage class \ "REDUCED_REDUNDANCY" 4 / Standard Infrequent Access storage class \ "STANDARD_IA" 5 / One Zone Infrequent Access storage class \ "ONEZONE_IA" 6 / Glacier Flexible Retrieval storage class \ "GLACIER" 7 / Glacier Deep Archive storage class \ "DEEP_ARCHIVE" 8 / Intelligent-Tiering storage class \ "INTELLIGENT_TIERING" 9 / Glacier Instant Retrieval storage class \ "GLACIER_IR" storage_class> 1 Remote config Configuration complete. Options:

type: s3
provider: AWS
env_auth: false
access_key_id: XXX
secret_access_key: YYY
region: us-east-1
endpoint:
location_constraint:
acl: private
server_side_encryption:
storage_class: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d>


and that's the whole thing, bestie 🫶 notice how at the very end it reads everything back to you under `Remote config` — all the `Options:` as a little bullet list — and then hits you with the `y/e/d>` prompt. <mint>y</mint> means yes this is OK, <mint>e</mint> means edit this remote, <mint>d</mint> means delete this remote. Main character decision-making moment fr fr. Answer right and you're done. 💅

---

## ✨ Modification times and hashes ✨

### ⏰ Modification times

The modified time is stored as metadata on the object as `X-Amz-Meta-Mtime` as floating point since the epoch, accurate to `1 ns`. Yes, <hotpink>nanosecond accurate</hotpink>, we love a precise queen. 👑

If the modification time needs to be updated rclone will attempt to perform a server side copy to update the modification if the object can be copied in a single part. In the case the object is larger than `5Gb` or is in Glacier or Glacier Deep Archive storage the object will be <yellow>uploaded</yellow> rather than copied. (Different move, same goal, but bestie the upload is real.)

Note that reading this from the object takes an additional `HEAD` request as the metadata isn't returned in object listings. So it's giving *extra* work, lowkey. 😭

### 🌸 Hashes

For small objects which weren't uploaded as multipart uploads (objects sized below `--s3-upload-cutoff` if uploaded with rclone) rclone uses the `ETag:` header as an MD5 checksum.

However for objects which were uploaded as multipart uploads or with server side encryption (SSE-AWS or SSE-C) the `ETag` header is no longer the MD5 sum of the data, so rclone adds an additional piece of metadata `X-Amz-Meta-Md5chksum` which is a base64 encoded MD5 hash (in the same format as is required for Content-MD5). You can use `base64 -d` and `hexdump` to check this value manually:

echo 'VWTGdNx3LyXQDfA0e2Edxw==' | base64 -d | hexdump


or you can use `rclone check` to verify the hashes are OK. ✔️

For large objects, calculating this hash can take some time so the addition of this hash can be disabled with `--s3-disable-checksum`. This will mean that these objects do <red>not</red> have an MD5 checksum. (Trade-off era, be aware bestie.)

Note that reading this from the object takes an additional `HEAD` request as the metadata isn't returned in object listings. Again. Every time. 🙈

---

## 💸 Reducing costs 💸

### 🧚 Avoiding HEAD requests to read the modification time

By default, rclone will use the modification time of objects stored in S3 for syncing. This is stored in object metadata which unfortunately takes an extra `HEAD` request to read which can be <red>expensive</red> (in time *and* money). Not the vibe we want on your wallet. 💀

The modification time is used by default for all operations that require checking the time a file was last updated. It allows rclone to treat the remote more like a true filesystem, but it is inefficient on S3 because it requires an extra API call to retrieve the metadata.

The extra API calls can be avoided when syncing (using `rclone sync` or `rclone copy`) in a few different ways, each with its own tradeoffs. Pick your fighter:

- **`--size-only`**
  - Only checks the size of files.
  - Uses no extra transactions.
  - If the file doesn't change size then rclone won't detect it has changed.
  - `rclone sync --size-only /path/to/source s3:bucket`

- **`--checksum`**
  - Checks the size and MD5 checksum of files.
  - Uses no extra transactions.
  - The most accurate detection of changes possible.

> fr fr, each of these is a *tradeoff* — you're trading accuracy of change-detection for the API calls you don't have to pay for. Not me picking whichever one my budget is in the mood for. 💅✨

- Will cause the source to read an MD5 checksum which, if it is a local disk, will cause <red>lots</red> of disk activity 😭
  - If the source and destination are both S3 this is the <green>recommended</green> flag to use for maximum efficiency 💯
  - `rclone sync --checksum /path/to/source s3:bucket`

- **`--update --use-server-modtime`** — the combo that costs you basically nothing extra ✨

  - Uses **no extra transactions** 🎉
  - Modification time becomes the time the object was uploaded
  - For many operations this is sufficient to determine if it needs uploading
  - Using `--update` along with `--use-server-modtime`, avoids the extra API call and uploads files whose local modification time is newer than the time it was last uploaded
  - Files created with timestamps in the past will be **missed** by the sync 💀
  - `rclone sync --update --use-server-modtime /path/to/source s3:bucket`

These flags can and <italic>should</italic> be used in combination with `--fast-list` — see below 👇

If using `rclone mount` or any command using the VFS (eg `rclone serve`) commands then you might want to consider using the VFS flag `--no-modtime` which will stop rclone reading the modification time for every object. You could also use `--use-server-modtime` if you are happy with the modification times of the objects being the time of upload 🫶

---

## 🌈 Avoiding GET requests to read directory listings

Rclone's default directory traversal is to process each directory individually. This takes <yellow>one API call per directory</yellow>. Using the `--fast-list` flag will read all info about the objects into memory first using a smaller number of API calls (one per 1000 objects). See the rclone docs for more details.

rclone sync --fast-list --checksum /path/to/source s3:bucket


`--fast-list` trades off API transactions for memory use. As a rough guide rclone uses `1k` of memory per object stored, so using `--fast-list` on a sync of a million objects will use roughly `1 GiB` of RAM 😳

If you are only copying a <italic>small</italic> number of files into a <italic>big</italic> repository then using `--no-traverse` is a good idea. This finds objects directly instead of through directory listings. You can do a "top-up" sync very cheaply by using `--max-age` and `--no-traverse` to copy only recent files, eg

rclone copy --max-age 24h --no-traverse /path/to/source s3:bucket


You'd then do a full `rclone sync` less often 🐢

Note that `--fast-list` <bold>isn't</bold> required in the top-up sync.

## 💅 Avoiding HEAD requests after PUT

By default, rclone will HEAD every object it uploads. It does this to check the object got uploaded correctly 👑

You can disable this with the `--s3-no-head` option — see there for more details.

> Setting this flag increases the chance for **undetected upload failures**. Careful bestie 🙈

## 🔥 Increasing performance

### Using server-side copy

If you are copying objects between S3 buckets in the <italic>same region</italic>, you should use server-side copy. This is <green>much faster</green> than downloading and re-uploading the objects, as no data is transferred 🦋

For rclone to use server-side copy, you must use the **same remote** for the source and destination.

rclone copy s3:source-bucket s3:destination-bucket


When using server-side copy, the performance is limited by the rate at which rclone issues API requests to S3. See below for how to increase the number of API requests rclone makes ⚡

### Increasing the rate of API requests

You can increase the rate of API requests to S3 by increasing the parallelism using `--transfers` and `--checkers` options.

Rclone uses a <italic>very</italic> conservative defaults for these settings, as not all providers support high rates of requests. Depending on your provider, you can increase significantly the number of transfers and checkers 📈

For example, with AWS S3, if you can increase the number of checkers to values like `200`. If you are doing a server-side copy, you can also increase the number of transfers to `200`.

rclone sync --transfers 200 --checkers 200 --checksum s3:source-bucket s3:destination-bucket


You will need to experiment with these values to find the optimal settings for your setup 🧪

## 🧚 Data integrity

Rclone does its best to verify every part of an upload or download to the s3 provider using various hashes. No cap 💯

Every HTTP transaction to/from the provider has a `X-Amz-Content-Sha256` or a `Content-Md5` header to guard against corruption of the HTTP body. The HTTP Header is protected by the signature passed in the `Authorization` header.

All communications with the provider is done over <green>https</green> for encryption and additional error protection 🔒

### Single part uploads

- Rclone uploads single part uploads with a `Content-Md5` using the MD5 hash read from the source. The provider checks this is correct on receipt of the data.
- Rclone then does a HEAD request (disable with `--s3-no-head`) to read the `ETag` back which is the MD5 of the file and checks that with what it sent.

Note that if the source does not have an MD5 then the single part uploads will <bold>not</bold> have hash protection. In this case it is recommended to use `--s3-upload-cutoff 0` so all files are uploaded as multipart uploads 🙌

### Multipart uploads

For files above `--s3-upload-cutoff` rclone splits the file into multiple parts for upload.

- Each part is protected with both an `X-Amz-Content-Sha256` and a `Content-Md5`

When rclone has finished the upload of all the parts it then completes the upload by sending:

- The MD5 hash of each part
- The number of parts
- This info is all protected with a `X-Amz-Content-Sha256`

The provider checks the MD5 for all the parts it has received against what rclone sends and if it is good it returns `OK`.

Rclone then does a HEAD request (disable with `--s3-no-head`) and checks the `ETag` is what it expects (in this case it should be the MD5 sum of all the MD5 sums of all the parts with the number of parts on the end).

If the source has an MD5 sum then rclone will attach the `X-Amz-Meta-Md5chksum` with it as the `ETag` for a multipart upload can't easily be checked against the file as the chunk size must be known in order to calculate it.

### Downloads

Rclone checks the MD5 hash of the data downloaded against either the `ETag` or the `X-Amz-Meta-Md5chksum` metadata (if present) which rclone uploads with multipart uploads 🫶

### Further checking

At each stage rclone and the provider are sending and checking hashes of everything. Rclone deliberately HEADs each object after upload to check it arrived safely for extra security. (You can disable this with `--s3-no-head`).

If you require further assurance that your data is intact you can use `rclone check` to check the hashes locally vs the remote 🔍

And if you are feeling <italic>ultimately paranoid</italic> use `rclone check --download` which will download the files and check them against the local copies. (Note that this doesn't use disk to do this — it streams them in memory) 🧠

## 👑 Versions

When bucket versioning is enabled (this can be done with rclone with the `rclone backend versioning` command) when rclone uploads a new version of a file it creates a new version of it. Likewise when you delete a file, the old version will be marked hidden and still be available 🕰️

Old versions of files, where available, are visible using the `--s3-versions` flag.

It is also possible to view a bucket as it was at a certain point in time, using the `--s3-version-at` flag. This will show the file versions as they were at that time, showing files that have been deleted afterwards, and hiding files that were created since ✨

If you wish to remove all the old versions then you can use the

rclone backend cleanup-hidden remote:bucket


command which will delete all the old hidden versions of files, leaving the current ones intact. You can also supply a path and only old versions under that path will be deleted, e.g.

rclone backend cleanup-hidden remote:bucket/path/to/stuff


When you purge a bucket, the current <italic>and</italic> the old versions will be deleted then the bucket will be deleted.

However delete will cause the current versions of the files to become hidden old versions 👻

Here is a session showing the listing and retrieval of an old version followed by a cleanup of the old versions.

Show current version and all the versions with `--s3-versions` flag.

$ rclone -q ls s3:cleanup-test 9 one.txt

$ rclone -q --s3-versions ls s3:cleanup-test 9 one.txt 8 one-v2016-07-04-141032-000.txt 16 one-v2016-07-04-141003-000.txt 15 one-v2016-07-02-155621-000.txt


Retrieve an old version

$ rclone -q --s3-versions copy s3:cleanup-test/one-v2016-07-04-141003-000.txt /tmp

$ ls -l /tmp/one-v2016-07-04-141003-000.txt -rw-rw-r-- 1 ncw ncw 16 Jul 2 17:46 /tmp/one-v2016-07-04-141003-000.txt


Clean up all the old versions and show that they've gone.

$ rclone -q backend cleanup-hidden s3:cleanup-test

$ rclone -q ls s3:cleanup-test 9 one.txt

$ rclone -q --s3-versions ls s3:cleanup-test 9 one.txt


## 🌸 Versions naming caveat

When using `--s3-versions` flag rclone is relying on the file name to work out whether the objects are versions or not. Versions' names are created by inserting `timestamp` between file name and its extension.

9 file.txt 8 file-v2023-07-17-161032-000.txt 16 file-v2023-06-15-141003-000.txt


If there are real files present with the same names as versions, then behaviour of `--s3-versions` can be <red>unpredictable</red> 🙈

## 🎀 Cleanup

If you run `rclone cleanup s3:bucket` then it will remove all pending multipart uploads older than 24 hours. You can use the `--interactive`/`-i` or `--dry-run` flag to see exactly what it will do. If you want more control over the expiry date then run `rclone backend cleanup s3:bucket -o max-age=1h` to expire all uploads older than one hour. You can use `rclone backend list-multipart-uploads s3:bucket` to see the pending multipart uploads 🧹

## 🦋 Restricted filename characters

S3 allows any valid UTF-8 string as a key.

Invalid UTF-8 bytes will be replaced, as they can't be used in XML.

The following characters are replaced since these are problematic when dealing with the REST API:

- `NUL` — `0x00` — replaced with `␀`

- `/` — `0x2F` — replaced with `／`

The encoding will also encode these file names as they don't seem to work with the SDK properly:

- `.` — replaced with `．`

- `..` — replaced with `．．`

## ⭐ Multipart uploads

rclone supports multipart uploads with S3 which means that it can upload files bigger than `5 GiB` 🎉

<pink>Note that files uploaded both with multipart upload and through crypt remotes do not have MD5 sums.</pink> Like, they just don't. No MD5 for you. 🙈

rclone switches from single part uploads to multipart uploads at the point specified by `--s3-upload-cutoff`. That can be a maximum of 5 GiB and a minimum of 0 (ie always upload multipart files).

The chunk sizes used in the multipart upload are specified by `--s3-chunk-size` and the number of chunks uploaded concurrently is specified by `--s3-upload-concurrency`.

Multipart uploads will use `--transfers` * `--s3-upload-concurrency` * `--s3-chunk-size` extra memory. Single part uploads do not use extra memory. (Not me stressing about your RAM bestie, but like… be aware. 💀)

Single part transfers can be faster than multipart transfers or slower depending on your latency from S3 — the more latency, the more likely single part transfers will be faster.

Increasing `--s3-upload-concurrency` will increase throughput (8 would be a sensible value) and increasing `--s3-chunk-size` also increases throughput (16M would be sensible). Increasing either of these will use more memory. The default values are high enough to gain most of the possible performance without using too much memory. Slay, defaults. 💅

## 🪣 Buckets and Regions

With Amazon S3 you can list buckets (`rclone lsd`) using any region, but you can **only** access the content of a bucket from the region it was created in. If you attempt to access a bucket from the wrong region, you will get an error, <red>incorrect region, the bucket is not in 'XXX' region</red>.

## 🔑 Authentication

There are a number of ways to supply rclone with a set of AWS credentials, with and without using the environment.

The different authentication methods are tried in this order:

- Directly in the rclone configuration file (`env_auth = false` in the config file):
  - `access_key_id` and `secret_access_key` are required.
  - `session_token` can be optionally set when using AWS STS.
- Runtime configuration (`env_auth = true` in the config file):
  - Export the following environment variables before running rclone:
    - Access Key ID: `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY`
    - Secret Access Key: `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY`
    - Session Token: `AWS_SESSION_TOKEN` (optional)
  - Or, use a named profile:
    - Profile files are standard files used by AWS CLI tools
    - By default it will use the profile in your home directory (e.g. `~/.aws/credentials` on unix based systems) file and the “default” profile, to change set these environment variables or config keys:
      - `AWS_SHARED_CREDENTIALS_FILE` to control which file or the `shared_credentials_file` config key.
      - `AWS_PROFILE` to control which profile to use or the `profile` config key.
  - Or, run rclone in an ECS task with an IAM role (AWS only).
  - Or, run rclone on an EC2 instance with an IAM role (AWS only).
  - Or, run rclone in an EKS pod with an IAM role that is associated with a service account (AWS only).
  - Or, use process credentials to read config from an external program.

With `env_auth = true` rclone (which uses the SDK for Go v2) should support all authentication methods that the aws CLI tool does and the other AWS SDKs. Periodt. 👑

If none of these option actually end up providing rclone with AWS credentials then S3 interaction will be non-authenticated (see the anonymous access section for more info).

## 🛡️ S3 Permissions

When using the `sync` subcommand of rclone the following minimum permissions are required to be available on the bucket being written to:

- `ListBucket`
- `DeleteObject`
- `GetObject`
- `PutObject`
- `PutObjectACL`
- `CreateBucket` (unless using `s3-no-check-bucket`)

When using the `lsd` subcommand, the `ListAllMyBuckets` permission is required.

Example policy:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::USER_SID:user/USER_NAME" }, "Action": [ "s3:ListBucket", "s3:DeleteObject", "s3:GetObject", "s3:PutObject", "s3:PutObjectAcl" ], "Resource": [ "arn:aws:s3:::BUCKET_NAME/", "arn:aws:s3:::BUCKET_NAME" ] }, { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "arn:aws:s3:::" } ] }


Notes on above:

1. This is a policy that can be used when creating bucket. It assumes that `USER_NAME` has been created.
2. The Resource entry must include both resource ARNs, as one implies the bucket and the other implies the bucket’s objects.
3. When using `s3-no-check-bucket` and the bucket already exists, the `"arn:aws:s3:::BUCKET_NAME"` doesn’t have to be included.

For reference, here’s an Ansible script that will generate one or more buckets that will work with `rclone sync`. ✨

## 🔐 Key Management System (KMS)

If you are using server-side encryption with KMS then you must make sure rclone is configured with `server_side_encryption = aws:kms` otherwise you will find you can’t transfer small objects — these will create checksum errors. Like, they will just break on you, no cap. 😭

## 🧊 Glacier and Glacier Deep Archive

You can upload objects using the `glacier` storage class or transition them to glacier using a lifecycle policy. The bucket can still be synced or copied into normally, but if rclone tries to access data from the glacier storage class you will see an error like below.

2017/09/11 19:07:43 Failed to sync: failed to open source object: Object in GLACIER, restore first: path/to/file


In this case you need to restore the object(s) in question before accessing object contents. The restore section below shows how to do this with rclone.

Note that rclone only speaks the S3 API it does not speak the Glacier Vault API, so rclone **cannot** directly access Glacier Vaults. Nope, not happening. 🚫

## 🔒 Object-lock enabled S3 bucket

According to AWS’s documentation on S3 Object Lock:

> If you configure a default retention period on a bucket, requests to upload objects in such a bucket must include the `Content-MD5` header.

As mentioned in the Modification times and hashes section, small files that are not uploaded as multipart, use a different tag, causing the upload to fail. A simple solution is to set the `--s3-upload-cutoff 0` and force all the files to be uploaded as multipart. 🫶

## ⭐ Standard options

Here are the Standard options specific to `s3` (Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, StackPath, Storj, Synology, TencentCOS, Wasabi, Qiniu and others).

### –s3-provider

Choose your S3 provider.

Properties:

- Config: `provider`
- Env Var: `RCLONE_S3_PROVIDER`
- Type: `string`
- Required: `false`
- Examples:
  - “AWS”
    - Amazon Web Services (AWS) S3
  - “Alibaba”
    - Alibaba Cloud Object Storage System (OSS) formerly Aliyun
  - “ArvanCloud”
    - Arvan Cloud Object Storage (AOS)
  - “Ceph”
    - Ceph Object Storage
  - “ChinaMobile”
    - China Mobile Ecloud Elastic Object Storage (EOS)
  - “Cloudflare”
    - Cloudflare R2 Storage
  - “DigitalOcean”
    - DigitalOcean Spaces
  - “Dreamhost”
    - Dreamhost DreamObjects
  - “GCS”
    - Google Cloud Storage
  - “HuaweiOBS”
    - Huawei Object Storage Service
  - “IBMCOS”
    - IBM COS S3
  - “IDrive”
    - IDrive e2
  - “IONOS”
    - IONOS Cloud
  - “LyveCloud”
    - Seagate Lyve Cloud
  - “Leviia”
    - Leviia Object Storage
  - “Liara”
    - Liara Object Storage
  - “Linode”
    - Linode Object Storage
  - “Magalu”
    - Magalu Object Storage
  - “Minio”
    - Minio Object Storage
  - “Netease”
    - Netease Object Storage (NOS)
  - “Outscale”
    - OUTSCALE Object Storage (OOS)
  - “Petabox”
    - Petabox Object Storage
  - “RackCorp”
    - RackCorp Object Storage
  - “Rclone”
    - Rclone S3 Server
  - “Scaleway”
    - Scaleway Object Storage
  - “SeaweedFS”
    - SeaweedFS S3
  - “Selectel”
    - Selectel Object Storage
  - “StackPath”
    - StackPath Object Storage
  - “Storj”
    - Storj (S3 Compatible Gateway)
  - “Synology”
    - Synology C2 Object Storage
  - “TencentCOS”
    - Tencent Cloud Object Storage (COS)
  - “Wasabi”
    - Wasabi Object Storage
  - “Qiniu”
    - Qiniu Object Storage (Kodo)
  - “Other”
    - Any other S3 compatible provider

### –s3-env-auth

Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars).

Only applies if `access_key_id` and `secret_access_key` is blank.

Properties:

- Config: `env_auth`
- Env Var: `RCLONE_S3_ENV_AUTH`
- Type: `bool`
- Default: `false`
- Examples:
  - “false”
    - Enter AWS credentials in the next step.
  - “true”
    - Get AWS credentials from the environment (env vars or IAM).

### –s3-access-key-id

AWS Access Key ID.

Leave blank for anonymous access or runtime credentials.

Properties:

- Config: `access_key_id`
- Env Var: `RCLONE_S3_ACCESS_KEY_ID`
- Type: `string`
- Required: `false`

### –s3-secret-access-key

AWS Secret Access Key (password).

Leave blank for anonymous access or runtime credentials.

Properties:

- Config: `secret_access_key`
- Env Var: `RCLONE_S3_SECRET_ACCESS_KEY`
- Type: `string`
- Required: `false`

### –s3-region

Region to connect to.

Properties:

- Config: `region`
- Env Var: `RCLONE_S3_REGION`
- Provider: AWS
- Type: `string`
- Required: `false`
- Examples:
  - “us-east-1”
    - The default endpoint - a good choice if you are unsure.
    - US Region, Northern Virginia, or Pacific Northwest.

- Leave location constraint empty.

- **`"us-east-2"`**
  - US East (Ohio) Region.
  - Needs location constraint `us-east-2`.

- **`"us-west-1"`**
  - US West (Northern California) Region.
  - Needs location constraint `us-west-1`.

- **`"us-west-2"`**
  - US West (Oregon) Region.
  - Needs location constraint `us-west-2`.

- **`"ca-central-1"`**
  - Canada (Central) Region.
  - Needs location constraint `ca-central-1`.

- **`"eu-west-1"`**
  - EU (Ireland) Region.
  - Needs location constraint `EU` or `eu-west-1`.

- **`"eu-west-2"`**
  - EU (London) Region.
  - Needs location constraint `eu-west-2`.

- **`"eu-west-3"`**
  - EU (Paris) Region.
  - Needs location constraint `eu-west-3`.

- **`"eu-north-1"`**
  - EU (Stockholm) Region.
  - Needs location constraint `eu-north-1`.

- **`"eu-south-1"`**
  - EU (Milan) Region.
  - Needs location constraint `eu-south-1`.

- **`"eu-central-1"`**
  - EU (Frankfurt) Region.
  - Needs location constraint `eu-central-1`.

- **`"ap-southeast-1"`**
  - Asia Pacific (Singapore) Region.
  - Needs location constraint `ap-southeast-1`.

- **`"ap-southeast-2"`**
  - Asia Pacific (Sydney) Region.
  - Needs location constraint `ap-southeast-2`.

- **`"ap-northeast-1"`**
  - Asia Pacific (Tokyo) Region.
  - Needs location constraint `ap-northeast-1`.

- **`"ap-northeast-2"`**
  - Asia Pacific (Seoul).
  - Needs location constraint `ap-northeast-2`.

- **`"ap-northeast-3"`**
  - Asia Pacific (Osaka-Local).
  - Needs location constraint `ap-northeast-3`.

- **`"ap-south-1"`**
  - Asia Pacific (Mumbai).
  - Needs location constraint `ap-south-1`.

- **`"ap-east-1"`**
  - Asia Pacific (Hong Kong) Region.
  - Needs location constraint `ap-east-1`.

- **`"sa-east-1"`**
  - South America (Sao Paulo) Region.
  - Needs location constraint `sa-east-1`.

- **`"il-central-1"`**
  - Israel (Tel Aviv) Region.
  - Needs location constraint `il-central-1`.

- **`"me-south-1"`**
  - Middle East (Bahrain) Region.
  - Needs location constraint `me-south-1`.

- **`"af-south-1"`**
  - Africa (Cape Town) Region.
  - Needs location constraint `af-south-1`.

- **`"cn-north-1"`**
  - China (Beijing) Region.
  - Needs location constraint `cn-north-1`.

- **`"cn-northwest-1"`**
  - China (Ningxia) Region.
  - Needs location constraint `cn-northwest-1`.

- **`"us-gov-east-1"`**
  - AWS GovCloud (US-East) Region.
  - Needs location constraint `us-gov-east-1`.

- **`"us-gov-west-1"`**
  - AWS GovCloud (US) Region.
  - Needs location constraint `us-gov-west-1`.

---

- **`--s3-endpoint`** — <purple>the endpoint for the S3 API, bestie 🔌</purple>

  Leave it blank if you're using AWS, so the default endpoint for the region gets used. The way that it's just… auto. Iconic.

  Properties:

  - Config: `endpoint`
  - Env Var: `RCLONE_S3_ENDPOINT`
  - Provider: `AWS`
  - Type: string
  - Required: false

- **`--s3-location-constraint`** — location constraint, and it has to match the Region fr fr 📍

  This one only matters when you're creating buckets, okay? Only then.

  Properties:

  - Config: `location_constraint`
  - Env Var: `RCLONE_S3_LOCATION_CONSTRAINT`
  - Provider: `AWS`
  - Type: string
  - Required: false
  - Examples:

    - **`""`**
      - Empty for US Region, Northern Virginia, or Pacific Northwest
    - **`"us-east-2"`**
      - US East (Ohio) Region
    - **`"us-west-1"`**
      - US West (Northern California) Region
    - **`"us-west-2"`**
      - US West (Oregon) Region
    - **`"ca-central-1"`**
      - Canada (Central) Region
    - **`"eu-west-1"`**
      - EU (Ireland) Region
    - **`"eu-west-2"`**
      - EU (London) Region
    - **`"eu-west-3"`**
      - EU (Paris) Region
    - **`"eu-north-1"`**
      - EU (Stockholm) Region
    - **`"eu-south-1"`**
      - EU (Milan) Region
    - **`"EU"`**
      - EU Region
    - **`"ap-southeast-1"`**
      - Asia Pacific (Singapore) Region
    - **`"ap-southeast-2"`**
      - Asia Pacific (Sydney) Region
    - **`"ap-northeast-1"`**
      - Asia Pacific (Tokyo) Region
    - **`"ap-northeast-2"`**
      - Asia Pacific (Seoul) Region
    - **`"ap-northeast-3"`**
      - Asia Pacific (Osaka-Local) Region
    - **`"ap-south-1"`**
      - Asia Pacific (Mumbai) Region
    - **`"ap-east-1"`**
      - Asia Pacific (Hong Kong) Region
    - **`"sa-east-1"`**
      - South America (Sao Paulo) Region
    - **`"il-central-1"`**
      - Israel (Tel Aviv) Region
    - **`"me-south-1"`**
      - Middle East (Bahrain) Region
    - **`"af-south-1"`**
      - Africa (Cape Town) Region
    - **`"cn-north-1"`**
      - China (Beijing) Region
    - **`"cn-northwest-1"`**
      - China (Ningxia) Region
    - **`"us-gov-east-1"`**
      - AWS GovCloud (US-East) Region
    - **`"us-gov-west-1"`**
      - AWS GovCloud (US) Region

- **`--s3-acl`** — the canned ACL used when creating buckets and when storing or copying objects 🎀

  So this ACL gets used for making objects, and — plot twist — if `bucket_acl` isn't set, it's used for creating buckets too. Multi-purpose queen.

  For more info, go peek at `https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl`.

  Heads up: this ACL is applied when server-side copying objects, because S3 does **not** copy the ACL from the source — no bestie, it writes a fresh one instead. It's giving "new identity, who dis".

  And if the acl is an empty string, then no `X-Amz-Acl:` header is added and the default (`private`) gets used.

  Properties:

  - Config: `acl`
  - Env Var: `RCLONE_S3_ACL`
  - Provider: `!Storj,Selectel,Synology,Cloudflare`
  - Type: string
  - Required: false
  - Examples:

    - **`"default"`**
      - Owner gets `Full_CONTROL`.
      - No one else has access rights (default).

    - **`"private"`**
      - Owner gets `FULL_CONTROL`.
      - No one else has access rights (default).

    - **`"public-read"`**
      - Owner gets `FULL_CONTROL`.
      - The `AllUsers` group gets `READ` access.

    - **`"public-read-write"`**
      - Owner gets `FULL_CONTROL`.
      - The `AllUsers` group gets `READ` and `WRITE` access.
      - Granting this on a bucket is generally not recommended.

    - **`"authenticated-read"`**
      - Owner gets `FULL_CONTROL`.
      - The `AuthenticatedUsers` group gets `READ` access.

    - **`"bucket-owner-read"`**
      - Object owner gets `FULL_CONTROL`.
      - Bucket owner gets `READ` access.
      - If you specify this canned ACL when creating a bucket, Amazon S3 ignores it. Rude of them tbh 💀

    - **`"bucket-owner-full-control"`**
      - Both the object owner and the bucket owner get `FULL_CONTROL` over the object.
      - If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.

    - **`"private"`**
      - Owner gets `FULL_CONTROL`.
      - No one else has access rights (default).
      - This acl is available on IBM Cloud (Infra), IBM Cloud (Storage), On-Premise COS.

    - **`"public-read"`**
      - Owner gets `FULL_CONTROL`.
      - The `AllUsers` group gets `READ` access.
      - This acl is available on IBM Cloud (Infra), IBM Cloud (Storage), On-Premise IBM COS.

    - **`"public-read-write"`**
      - Owner gets `FULL_CONTROL`.
      - The `AllUsers` group gets `READ` and `WRITE` access.
      - This acl is available on IBM Cloud (Infra), On-Premise IBM COS.

    - **`"authenticated-read"`**
      - Owner gets `FULL_CONTROL`.
      - The `AuthenticatedUsers` group gets `READ` access.
      - Not supported on Buckets.
      - This acl is available on IBM Cloud (Infra) and On-Premise IBM COS.

- **`--s3-server-side-encryption`** — the server-side encryption algorithm used when storing this object in S3 🔐

  Properties:

  - Config: `server_side_encryption`
  - Env Var: `RCLONE_S3_SERVER_SIDE_ENCRYPTION`
  - Provider: `AWS,Ceph,ChinaMobile,Minio`
  - Type: string
  - Required: false
  - Examples:

    - **`""`**
      - None
    - **`"AES256"`**
      - AES256
    - **`"aws:kms"`**
      - aws:kms

- **`--s3-sse-kms-key-id`** — if you're using a KMS ID, you **must** provide the ARN of the Key 🗝️

  Properties:

  - Config: `sse_kms_key_id`
  - Env Var: `RCLONE_S3_SSE_KMS_KEY_ID`
  - Provider: `AWS,Ceph,Minio`
  - Type: string
  - Required: false
  - Examples:

    - **`""`**
      - None
    - **`"arn:aws:kms:us-east-1:*"`**
      - `arn:aws:kms:*`

- **`--s3-storage-class`** — the storage class to use when storing new objects in S3 🗄️

  Properties:

  - Config: `storage_class`
  - Env Var: `RCLONE_S3_STORAGE_CLASS`
  - Provider: `AWS`
  - Type: string
  - Required: false
  - Examples:

    - **`""`**
      - Default
    - **`"STANDARD"`**
      - Standard storage class
    - **`"REDUCED_REDUNDANCY"`**
      - Reduced redundancy storage class
    - **`"STANDARD_IA"`**
      - Standard Infrequent Access storage class
    - **`"ONEZONE_IA"`**
      - One Zone Infrequent Access storage class
    - **`"GLACIER"`**
      - Glacier Flexible Retrieval storage class
    - **`"DEEP_ARCHIVE"`**
      - Glacier Deep Archive storage class
    - **`"INTELLIGENT_TIERING"`**
      - Intelligent-Tiering storage class
    - **`"GLACIER_IR"`**
      - Glacier Instant Retrieval storage class

---

## 💫 Advanced options 💫

Okay so here are the Advanced options that are specific to s3 — and s3 here means (deep breath bestie) Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, StackPath, Storj, Synology, TencentCOS, Wasabi, Qiniu and others. The whole squad fr fr 👑

---

- **`--s3-bucket-acl`** — the canned ACL used when creating buckets 🪣

  For more info visit `https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl`.

  Note that this ACL is applied only when creating buckets. And if it isn't set, then `acl` gets used instead. It's giving "backup bestie".

  If the `acl` and `bucket_acl` are both empty strings, then no `X-Amz-Acl:` header is added and the default (`private`) gets used.

  Properties:

  - Config: `bucket_acl`
  - Env Var: `RCLONE_S3_BUCKET_ACL`
  - Type: string
  - Required: false
  - Examples:

    - **`"private"`**
      - Owner gets `FULL_CONTROL`.

- <pink>**`"public-read"`**</pink>
  - Owner gets FULL_CONTROL.
  - The AllUsers group gets READ access.

- <purple>**`"public-read-write"`**</purple>
  - Owner gets FULL_CONTROL.
  - The AllUsers group gets READ and WRITE access.
  - Granting this on a **bucket** is generally <red>not recommended</red>. 🙅‍♀️

- <cyan>**`"authenticated-read"`**</cyan>
  - Owner gets FULL_CONTROL.
  - The AuthenticatedUsers group gets READ access.

---

- **`--s3-requester-pays`** — turns on the *requester pays* option when rclone is interacting with an S3 bucket. 💸

  Properties:

  - Config: `requester_pays`
  - Env Var: `RCLONE_S3_REQUESTER_PAYS`
  - Provider: `AWS`
  - Type: bool
  - Default: `false`

- **`--s3-sse-customer-algorithm`** — if you're doing the SSE-C thing, this is the server-side encryption algorithm used when storing this object in S3. 🔐

  Properties:

  - Config: `sse_customer_algorithm`
  - Env Var: `RCLONE_S3_SSE_CUSTOMER_ALGORITHM`
  - Provider: `AWS,Ceph,ChinaMobile,Minio`
  - Type: string
  - Required: `false`
  - Examples:
    - `""`
      - None
    - `"AES256"`
      - AES256

- **`--s3-sse-customer-key`** — bestie, if you wanna use SSE-C you can hand over the secret encryption key that encrypts/decrypts your data here. 🗝️

  Or instead you can pass `--sse-customer-key-base64`. Either one, your call.

  Properties:

  - Config: `sse_customer_key`
  - Env Var: `RCLONE_S3_SSE_CUSTOMER_KEY`
  - Provider: `AWS,Ceph,ChinaMobile,Minio`
  - Type: string
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--s3-sse-customer-key-base64`** — if you're on SSE-C you <hotpink>*must*</hotpink> give the secret encryption key encoded in base64 so it can encrypt/decrypt your data. ✨

  Or instead you can pass `--sse-customer-key`.

  Properties:

  - Config: `sse_customer_key_base64`
  - Env Var: `RCLONE_S3_SSE_CUSTOMER_KEY_BASE64`
  - Provider: `AWS,Ceph,ChinaMobile,Minio`
  - Type: string
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--s3-sse-customer-key-md5`** — if you're on SSE-C you can drop the MD5 checksum of that secret encryption key here (it's optional, no pressure bestie). 🧮

  And if you leave it blank, rclone just calculates it for you automatically from the `sse_customer_key` you provided. Iconic behaviour honestly.

  Properties:

  - Config: `sse_customer_key_md5`
  - Env Var: `RCLONE_S3_SSE_CUSTOMER_KEY_MD5`
  - Provider: `AWS,Ceph,ChinaMobile,Minio`
  - Type: string
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--s3-upload-cutoff`** — the cutoff point where rclone switches over to chunked upload. 🍰

  Any file bigger than this gets uploaded in chunks of `chunk_size`. The **minimum is `0`** and the **maximum is `5 GiB`**, periodt.

  Properties:

  - Config: `upload_cutoff`
  - Env Var: `RCLONE_S3_UPLOAD_CUTOFF`
  - Type: SizeSuffix
  - Default: `200Mi`

- **`--s3-chunk-size`** — the chunk size used for uploading. 🧩

  When you upload files bigger than `upload_cutoff`, or files whose size is unknown (like when they come from `rclone rcat`, or get uploaded with `rclone mount`, or from google photos or google docs), they'll go up as multipart uploads using *this* chunk size.

  Heads up: `--s3-upload-concurrency` chunks of this size get buffered in memory **per transfer**. So like, mind your RAM, bestie. 🧠

  If you're moving big files over high-speed links and you've got enough memory to spare, bumping this up will speed the transfers up. 🔥

  Rclone will automatically increase the chunk size when uploading a large file of known size, so it stays below the 10,000 chunks limit.

  Files of unknown size get uploaded with the configured `chunk_size`. Since the default chunk size is `5 MiB` and there can be at most 10,000 chunks, that means by default the biggest file you can stream upload is **`48 GiB`**. If you wanna stream upload bigger files than that, you're gonna need to increase `chunk_size`.

  Increasing the chunk size makes the progress stats shown with the `-P` flag **less accurate**. Rclone acts like a chunk is sent the moment it's buffered by the AWS SDK, when it might lowkey still be uploading. Bigger chunk size = bigger AWS SDK buffer = progress reporting drifting further from the truth. 😭

  Properties:

  - Config: `chunk_size`
  - Env Var: `RCLONE_S3_CHUNK_SIZE`
  - Type: SizeSuffix
  - Default: `5Mi`

- **`--s3-max-upload-parts`** — the maximum number of parts in a multipart upload. 🎀

  This option sets the max number of multipart chunks to use when doing a multipart upload.

  It's handy if some service doesn't support the AWS S3 spec of 10,000 chunks.

  Rclone will automatically increase the chunk size when uploading a large file of a known size, so it stays below this number-of-chunks limit.

  Properties:

  - Config: `max_upload_parts`
  - Env Var: `RCLONE_S3_MAX_UPLOAD_PARTS`
  - Type: int
  - Default: `10000`

- **`--s3-copy-cutoff`** — the cutoff where rclone switches to multipart copy. 📦

  Any files bigger than this that need a server-side copy will get copied in chunks of this size.

  The **minimum is `0`** and the **maximum is `5 GiB`**.

  Properties:

  - Config: `copy_cutoff`
  - Env Var: `RCLONE_S3_COPY_CUTOFF`
  - Type: SizeSuffix
  - Default: `4.656Gi`

- **`--s3-disable-checksum`** — don't store the MD5 checksum with the object metadata. 🚫

  Normally rclone calculates the MD5 checksum of the input before uploading so it can add it to the metadata on the object. That's amazing for data integrity checking, but it can cause long delays before big files actually start uploading.

  Properties:

  - Config: `disable_checksum`
  - Env Var: `RCLONE_S3_DISABLE_CHECKSUM`
  - Type: bool
  - Default: `false`

- **`--s3-shared-credentials-file`** — path to the shared credentials file. 📁

  If `env_auth = true` then rclone can use a shared credentials file.

  If this variable is empty, rclone will go looking for the `"AWS_SHARED_CREDENTIALS_FILE"` env variable. And if *that* env value is empty too, it'll default to the current user's home directory.

Linux/OSX: "$HOME/.aws/credentials" Windows: "%USERPROFILE%.aws\credentials"


Properties:

- Config: `shared_credentials_file`
- Env Var: `RCLONE_S3_SHARED_CREDENTIALS_FILE`
- Type: string
- Required: `false`

- **`--s3-profile`** — the profile to use inside the shared credentials file. 👤

If `env_auth = true` then rclone can use a shared credentials file. This variable controls *which* profile gets used in that file.

If it's empty it'll default to the environment variable `"AWS_PROFILE"`, or `"default"` if that environment variable isn't set either.

Properties:

- Config: `profile`
- Env Var: `RCLONE_S3_PROFILE`
- Type: string
- Required: `false`

- **`--s3-session-token`** — an AWS session token. 🎟️

Properties:

- Config: `session_token`
- Env Var: `RCLONE_S3_SESSION_TOKEN`
- Type: string
- Required: `false`

- **`--s3-upload-concurrency`** — concurrency for multipart uploads and copies. 🏃‍♀️🏃‍♀️

This is how many chunks of the *same* file get uploaded concurrently for multipart uploads and copies.

If you're uploading a small number of large files over high-speed links and those uploads aren't fully using your bandwidth, then bumping this up might help speed up the transfers.

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_S3_UPLOAD_CONCURRENCY`
- Type: int
- Default: `4`

- **`--s3-force-path-style`** — if `true`, use path style access; if `false`, use virtual hosted style. 🛣️

If this is `true` (which it is by default) then rclone uses path style access. If it's `false` then rclone uses virtual path style. Peep the AWS S3 docs for more info.

Some providers (like AWS, Aliyun OSS, Netease COS, or Tencent COS) need this set to `false` — rclone handles that automatically based on the provider setting. 🪄

Note that if your bucket isn't a valid DNS name, i.e. it's got a `.` or `_` in it, you'll need to set this to `true`.

Properties:

- Config: `force_path_style`
- Env Var: `RCLONE_S3_FORCE_PATH_STYLE`
- Type: bool
- Default: `true`

- **`--s3-v2-auth`** — if `true`, use v2 authentication. 🔑

If this is `false` (the default) then rclone uses v4 authentication. If it's set, then rclone uses v2 authentication.

Only reach for this if v4 signatures don't work, e.g. pre Jewel/v10 CEPH.

Properties:

- Config: `v2_auth`
- Env Var: `RCLONE_S3_V2_AUTH`
- Type: bool
- Default: `false`

- **`--s3-use-dual-stack`** — if `true`, use the AWS S3 dual-stack endpoint (IPv6 support). 🌐

See AWS Docs on Dualstack Endpoints.

Properties:

- Config: `use_dual_stack`
- Env Var: `RCLONE_S3_USE_DUAL_STACK`
- Type: bool
- Default: `false`

- **`--s3-use-accelerate-endpoint`** — if `true`, use the AWS S3 accelerated endpoint. ⚡

See: AWS S3 Transfer acceleration.

Properties:

- Config: `use_accelerate_endpoint`
- Env Var: `RCLONE_S3_USE_ACCELERATE_ENDPOINT`
- Provider: `AWS`
- Type: bool
- Default: `false`

- **`--s3-leave-parts-on-error`** — if `true`, rclone skips calling abort upload when something fails, leaving all the successfully uploaded parts sitting on S3 for manual recovery. 🩹

It should be set to `true` if you wanna resume uploads across different sessions.

> ⚠️ **WARNING:** storing parts of an incomplete multipart upload counts against your space usage on S3, and will add extra costs if you don't clean it up. Bestie, clean it up. 😭

Properties:

- Config: `leave_parts_on_error`
- Env Var: `RCLONE_S3_LEAVE_PARTS_ON_ERROR`
- Provider: `AWS`
- Type: bool
- Default: `false`

- **`--s3-list-chunk`** — the size of the listing chunk (the response list for each `ListObject` S3 request). 📜

This option is also known as `"MaxKeys"`, `"max-items"`, or `"page-size"` in the AWS S3 specification. Most services truncate the response list at 1000 objects even if you requested more than that. In AWS S3 this is a global maximum and can't be changed — see AWS S3. In Ceph, this can be increased with the `"rgw list buckets max chunk"` option.

Properties:

- Config: `list_chunk`
- Env Var: `RCLONE_S3_LIST_CHUNK`
- Type: int
- Default: `1000`

- **`--s3-list-version`** — which version of `ListObjects` to use: `1`, `2`, or `0` for auto. 🔍

Back when S3 first launched it only gave you the `ListObjects` call to enumerate objects in a bucket.

But in May 2016 the `ListObjectsV2` call showed up. It's much higher performance and you should be using it if at all possible.

If you leave it at the default, `0`, rclone guesses which list objects method to call based on the provider set. And if it guesses wrong, you can just set it manually here.

Properties:

- Config: `list_version`
- Env Var: `RCLONE_S3_LIST_VERSION`
- Type: int
- Default: `0`

- **`--s3-list-url-encode`** — whether to url encode listings: `true`/`false`/`unset` 🌈

Some providers are like *yes* to URL encoding listings, and when that's available it's way more reliable if ur filenames have control characters in them. If this is set to unset (the default) then rclone picks based on whatever the provider setting says, but bestie you can override rclone's choice right here 💅

Properties:

- **Config:** `list_url_encode`
- **Env Var:** `RCLONE_S3_LIST_URL_ENCODE`
- **Type:** Tristate
- **Default:** unset

---

## 🎀 `--s3-no-check-bucket`

If u set this, rclone just… won't check that the bucket exists, and won't try to create it either. Literally minding its own business.

Super useful when ur trying to keep the number of transactions rclone does as low as possible and u already *know* the bucket is there. Also a lifesaver if the user ur running as doesn't have bucket creation permissions at all 🙈

> Heads up: before <italic>v1.52.0</italic> this would have passed silently anyway, because of a <bold>bug</bold>. So if u were relying on that without knowing, that's why 👀

Properties:

- **Config:** `no_check_bucket`
- **Env Var:** `RCLONE_S3_NO_CHECK_BUCKET`
- **Type:** bool
- **Default:** false

## 🌸 `--s3-no-head`

Set this and rclone will NOT HEAD the objects it uploaded to check integrity. Skipping the vibe check entirely, risky behavior but go off.

Again, great for minimising how many transactions rclone does.

Setting it means: if rclone gets a `200 OK` back after uploading an object with PUT, it just ✨assumes✨ it uploaded properly.

Specifically it assumes:

- the metadata — modtime, storage class, content type, all of it — was exactly as uploaded
- the size was as uploaded

It does still read these things from the response for a single part PUT:

- the `MD5SUM`
- the uploaded date

For multipart uploads? Nope, none of those get read. 🙈

If the source object has an unknown length, rclone WILL do a HEAD request anyway.

> ⚠️ Setting this flag increases the chance of undetected upload failures — an incorrect size especially — so it's **not** recommended for normal operation. That said, in practice the chance of an undetected upload failure is very, very small even with this flag on.

Properties:

- **Config:** `no_head`
- **Env Var:** `RCLONE_S3_NO_HEAD`
- **Type:** bool
- **Default:** false

## 🦋 `--s3-no-head-object`

If set, do not do HEAD before GET when getting objects. Straight to the point, no small talk 💅

Properties:

- **Config:** `no_head_object`
- **Env Var:** `RCLONE_S3_NO_HEAD_OBJECT`
- **Type:** bool
- **Default:** false

## ⭐ `--s3-encoding`

The encoding for the backend.

Peep the <purple>encoding</purple> section in the overview for the whole rundown.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_S3_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,InvalidUtf8,Dot`

## 💜 `--s3-memory-pool-flush-time`

How often the internal memory buffer pools get flushed. <italic>(no longer used)</italic> — yeah bestie, it's a relic, it's giving legacy code energy 💀

Properties:

- **Config:** `memory_pool_flush_time`
- **Env Var:** `RCLONE_S3_MEMORY_POOL_FLUSH_TIME`
- **Type:** Duration
- **Default:** `1m0s`

## 🧚 `--s3-memory-pool-use-mmap`

Whether to use mmap buffers in the internal memory pool. <italic>(no longer used)</italic> — also a relic, ignore her, she's retired 🎀

Properties:

- **Config:** `memory_pool_use_mmap`
- **Env Var:** `RCLONE_S3_MEMORY_POOL_USE_MMAP`
- **Type:** bool
- **Default:** false

## 🔥 `--s3-disable-http2`

Disable usage of http2 for S3 backends.

So here's the tea: there's currently an unsolved issue with the s3 backend — specifically minio — and HTTP/2. HTTP/2 is enabled by default for the s3 backend but u can turn it off right here. When that issue finally gets solved, this flag is getting deleted, periodt.

See: `https://github.com/rclone/rclone/issues/4673`, `https://github.com/rclone/rclone/issues/3631`

Properties:

- **Config:** `disable_http2`
- **Env Var:** `RCLONE_S3_DISABLE_HTTP2`
- **Type:** bool
- **Default:** false

## 🌈 `--s3-download-url`

Custom endpoint for downloads. Usually u set this to a CloudFront CDN URL, bc AWS S3 gives u cheaper egress for data pulled through the CloudFront network. Saving coins, iconic behavior 💸

Properties:

- **Config:** `download_url`
- **Env Var:** `RCLONE_S3_DOWNLOAD_URL`
- **Type:** string
- **Required:** false

## 🍓 `--s3-directory-markers`

Upload an empty object with a trailing slash whenever a new directory is created.

See, empty folders are unsupported for bucket based remotes — sad but true 😭 — so this option creates an empty object ending with `/` to persist the folder. A little marker. A lil flag in the sand. 🚩

Properties:

- **Config:** `directory_markers`
- **Env Var:** `RCLONE_S3_DIRECTORY_MARKERS`
- **Type:** bool
- **Default:** false

## 💅 `--s3-use-multipart-etag`

Whether to use ETag in multipart uploads for verification.

This should be `true`, `false`, or just left unset to use whatever the default is for the provider.

Properties:

- **Config:** `use_multipart_etag`
- **Env Var:** `RCLONE_S3_USE_MULTIPART_ETAG`
- **Type:** Tristate
- **Default:** unset

## ✨ `--s3-use-unsigned-payload`

Whether to use an unsigned payload in PutObject.

The lore: rclone has to avoid the AWS SDK seeking the body when calling PutObject. The AWS provider can add checksums in the trailer to dodge the seeking, but other providers just… can't. Not their fault, not their problem 🫶

This should be `true`, `false`, or left unset to use the default for the provider.

Properties:

- **Config:** `use_unsigned_payload`
- **Env Var:** `RCLONE_S3_USE_UNSIGNED_PAYLOAD`
- **Type:** Tristate
- **Default:** unset

## 👑 `--s3-use-presigned-request`

Whether to use a presigned request or PutObject for single part uploads.

If this is false, rclone uses PutObject from the AWS SDK to upload an object.

Versions of rclone <italic>&lt; 1.59</italic> used presigned requests to upload a single part object, and setting this flag to `true` re-enables that old functionality. Nobody should actually need this except in *exceptional circumstances* or for testing. Nostalgia option fr fr 🙈

Properties:

- **Config:** `use_presigned_request`
- **Env Var:** `RCLONE_S3_USE_PRESIGNED_REQUEST`
- **Type:** bool
- **Default:** false

## 🎀 `--s3-versions`

Include old versions in directory listings. The ghosts of objects past 🫧

Properties:

- **Config:** `versions`
- **Env Var:** `RCLONE_S3_VERSIONS`
- **Type:** bool
- **Default:** false

## 🕰️ `--s3-version-at`

Show file versions as they were at the specified time.

The parameter should be a date — `2006-01-02` — a datetime like `2006-01-02 15:04:05`, or a duration for that long ago, eg `100d` or `1h`.

> ⚠️ Note that when ur using this, **no file write operations are permitted at all**. So u can't upload files or delete them. Read-only time travel only, bestie 🕰️✨

See the `time` option docs for valid formats.

Properties:

- **Config:** `version_at`
- **Env Var:** `RCLONE_S3_VERSION_AT`
- **Type:** Time
- **Default:** off

## 💀 `--s3-version-deleted`

Show deleted file markers when using versions.

This shows deleted file markers in the listing when using versions. They'll show up as 0 size files. The only operation u can perform on them is deletion. That's it. That's the whole moveset.

Deleting a delete marker will reveal the previous version 👀 (unburying the lore)

Deleted files will always show with a timestamp.

Properties:

- **Config:** `version_deleted`
- **Env Var:** `RCLONE_S3_VERSION_DELETED`
- **Type:** bool
- **Default:** false

## 🌸 `--s3-decompress`

If set, this will decompress gzip encoded objects.

So it's totally possible to upload objects to S3 with `Content-Encoding: gzip` set. Normally rclone downloads those files as compressed objects — just hands u the zip and says good luck.

If this flag is set, then rclone decompresses those `Content-Encoding: gzip` files as they're received. Which means rclone **can't check the size and hash**, but the file contents come out decompressed. Trade-off, bestie 💅

Properties:

- **Config:** `decompress`
- **Env Var:** `RCLONE_S3_DECOMPRESS`
- **Type:** bool
- **Default:** false

## 🫧 `--s3-might-gzip`

Set this if the backend might gzip objects.

Normally providers don't alter objects when they're downloaded. If an object wasn't uploaded with `Content-Encoding: gzip`, then it won't get that set on download. Simple, predictable, correct.

BUT — some providers may gzip objects even if they **weren't** uploaded with `Content-Encoding: gzip`. Cloudflare, I'm looking at u. 😭

A symptom of this would be receiving errors like:

ERROR corrupted on transfer: sizes differ NNN vs MMM


If u set this flag and rclone downloads an object with `Content-Encoding: gzip` set *and* chunked transfer encoding, then rclone will decompress the object on the fly. Crisis averted ✨

If this is set to unset (the default) then rclone chooses according to the provider setting what to apply, but u can override rclone's choice here.

Properties:

- **Config:** `might_gzip`
- **Env Var:** `RCLONE_S3_MIGHT_GZIP`
- **Type:** Tristate
- **Default:** unset

## 🧚 `--s3-use-accept-encoding-gzip`

Whether to send `Accept-Encoding: gzip` header.

By default, rclone appends `Accept-Encoding: gzip` to the request to download compressed objects whenever possible.

However, some providers — Google Cloud Storage for example — may alter the HTTP headers, which breaks the signature of the request 💀

A symptom of this would be receiving errors like:

SignatureDoesNotMatch: The request signature we calculated does not match the signature you provided.


If that's u, maybe try disabling this option. Turn it off and see what happens, no cap.

Properties:

- **Config:** `use_accept_encoding_gzip`
- **Env Var:** `RCLONE_S3_USE_ACCEPT_ENCODING_GZIP`
- **Type:** Tristate
- **Default:** unset

## 🎀 `--s3-no-system-metadata`

Suppress setting and reading of system metadata. Quiet mode for the metadata, she's not taking questions rn 🙊

Properties:

- **Config:** `no_system_metadata`
- **Env Var:** `RCLONE_S3_NO_SYSTEM_METADATA`
- **Type:** bool
- **Default:** false

## 📜 `--s3-sts-endpoint`

Endpoint for STS <italic>(deprecated)</italic>. Yeah she's deprecated, respect ur elders but also maybe move on.

Leave it blank if ur using AWS, and it'll use the default endpoint for the region.

Properties:

- **Config:** `sts_endpoint`
- **Env Var:** `RCLONE_S3_STS_ENDPOINT`
- **Provider:** AWS
- **Type:** string
- **Required:** false

## 💜 `--s3-use-already-exists`

Set this if rclone should report `BucketAlreadyExists` errors on bucket creation.

Okay so here's a whole saga 🍿 At some point during the evolution of the s3 protocol, AWS started returning an `AlreadyOwnedByYou` error when u tried to create a bucket the user already owned, instead of a `BucketAlreadyExists` error.

Unfortunately, exactly what's been implemented by s3 clones is… a little inconsistent. Some return `AlreadyOwnedByYou`, some return `BucketAlreadyExists`, and some just return no error at all. Chaos. Anarchy. Truly nobody is on the same page 💀

This matters to rclone bc it ensures the bucket exists by creating it on quite a lot of operations (unless `--s3-no-check-bucket` is used).

So if rclone knows the provider can return `AlreadyOwnedByYou` or returns no error, then it can properly report `BucketAlreadyExists` errors when the user tries to create a bucket that isn't theirs. Otherwise rclone just ignores the `BucketAlreadyExists` error — which can lead to confusion 👀

This should be automatically set correctly for all providers rclone knows about. If it's not, pls make a bug report bestie 🫶

Properties:

- **Config:** `use_already_exists`
- **Env Var:** `RCLONE_S3_USE_ALREADY_EXISTS`
- **Type:** Tristate
- **Default:** unset

## ✨ `--s3-use-multipart-uploads`

Set if rclone should use multipart uploads.

*(…and the page keeps going — more S3 goodness coming right up 💅)*

---

so about that multipart-upload toggle we were just on — <pink>you *can* flip it</pink> if you wanna <purple>disable multipart uploads</purple> entirely. You shouldn't need to though, like, not in normal operation, it's just not that deep. And rclone should already have this set correctly for <hotpink>every single provider it knows about</hotpink>, so if it doesn't, <red>please file a bug report</red> 🐛 — that's a real "not me getting ignored" moment.

**Properties:**

- Config: `use_multipart_uploads`
- Env Var: `RCLONE_S3_USE_MULTIPART_UPLOADS`
- Type: `Tristate`
- Default: `unset`

---

- **`--s3-directory-bucket`** — set this to use <cyan>AWS Directory Buckets</cyan> ✨ If you're on an AWS Directory Bucket, this flag is *the* flag. What it does: makes sure <green>no `Content-Md5` headers get sent</green> and makes sure <green>ETag headers are never interpreted as MD5 sums</green>. `X-Amz-Meta-Md5chksum` gets set on <purple>all</purple> objects, whether they were uploaded single or multipart. It also sets `no_check_bucket = true` for you, no extra charge 💅

  Heads up, Directory Buckets <red>do not support</red>:

  - Versioning
  - `Content-Encoding: gzip`

  And here are the rclone limitations with Directory Buckets, bestie, read these:

  - rclone does not support creating Directory Buckets with `rclone mkdir`
  - ... or removing them with `rclone rmdir` yet 😭
  - Directory Buckets do not appear when doing `rclone lsf` at the top level.
  - Rclone can't remove auto created directories yet. In theory this should work with `directory_markers = true` but it *doesn't* 💀
  - Directories don't seem to appear in recursive (ListR) listings.

  **Properties:**

  - Config: `directory_bucket`
  - Env Var: `RCLONE_S3_DIRECTORY_BUCKET`
  - Provider: `AWS`
  - Type: `bool`
  - Default: `false`

- **`--s3-sdk-log-mode`** — set this to <cyan>debug the SDK</cyan> 🔍 You can set it to a comma separated list of these functions:

  - `Signing`
  - `Retries`
  - `Request`
  - `RequestWithBody`
  - `Response`
  - `ResponseWithBody`
  - `DeprecatedUsage`
  - `RequestEventMessage`
  - `ResponseEventMessage`

  Use `Off` to disable it and `All` to set all log levels. And okay important: you'll need to use `-vv` to actually <hotpink>see</hotpink> the debug level logs, otherwise they're just sitting there being invisible 🌫️

  **Properties:**

  - Config: `sdk_log_mode`
  - Env Var: `RCLONE_S3_SDK_LOG_MODE`
  - Type: `Bits`
  - Default: `Off`

- **`--s3-description`** — a description of the remote. That's it, that's the whole flag 🎀

  **Properties:**

  - Config: `description`
  - Env Var: `RCLONE_S3_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

## 🌸 Metadata 🌸

User metadata gets stored as `x-amz-meta-` keys. And listen: S3 metadata keys are <purple>case insensitive</purple> and are <purple>always returned in lower case</purple>. Periodt.

Here are the possible system metadata items for the `s3` backend 👑

- **`btime`** — Time of file birth (creation) read from Last-Modified header
  - Type: `RFC 3339`
  - Example: `2006-01-02T15:04:05.999999999Z07:00`
  - Read Only: `Y`
- **`cache-control`** — Cache-Control header
  - Type: `string`
  - Example: `no-cache`
  - Read Only: `N`
- **`content-disposition`** — Content-Disposition header
  - Type: `string`
  - Example: `inline`
  - Read Only: `N`
- **`content-encoding`** — Content-Encoding header
  - Type: `string`
  - Example: `gzip`
  - Read Only: `N`
- **`content-language`** — Content-Language header
  - Type: `string`
  - Example: `en-US`
  - Read Only: `N`
- **`content-type`** — Content-Type header
  - Type: `string`
  - Example: `text/plain`
  - Read Only: `N`
- **`mtime`** — Time of last modification, read from rclone metadata
  - Type: `RFC 3339`
  - Example: `2006-01-02T15:04:05.999999999Z07:00`
  - Read Only: `N`
- **`tier`** — Tier of the object
  - Type: `string`
  - Example: `GLACIER`
  - Read Only: `Y`

See the metadata docs for more info 📚

---

## 🛠️ Backend commands 🛠️

Here are the commands that are <pink>specific to the `s3` backend</pink>.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes, no gatekeeping 💖

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

---

### 🧊 restore 🧊

Restore objects from GLACIER or INTELLIGENT-TIERING archive tier

rclone backend restore remote: [options] [<arguments>+]


This command can be used to restore one or more objects from GLACIER to normal storage, or from INTELLIGENT-TIERING Archive Access / Deep Archive Access tier up to the Frequent Access tier. <green>Un-archiving, iconic behavior</green> 🫶

Usage Examples:

rclone backend restore s3:bucket/path/to/ --include /object -o priority=PRIORITY -o lifetime=DAYS rclone backend restore s3:bucket/path/to/directory -o priority=PRIORITY -o lifetime=DAYS rclone backend restore s3:bucket -o priority=PRIORITY -o lifetime=DAYS rclone backend restore s3:bucket/path/to/directory -o priority=PRIORITY


This flag also obeys the filters. <hotpink>Test first</hotpink> with `--interactive`/`-i` or `--dry-run` flags, bestie, I'm begging 🙏

rclone --interactive backend restore --include "*.txt" s3:bucket/path -o priority=Standard -o lifetime=1


All the objects shown will be marked for restore, then

rclone backend restore --include "*.txt" s3:bucket/path -o priority=Standard -o lifetime=1


It returns a list of status dictionaries with `Remote` and `Status` keys. The `Status` will be `OK` if it was successful, or an error message if not.

[ { "Status": "OK", "Remote": "test.txt" }, { "Status": "OK", "Remote": "test/file4.txt" } ]


Options:

- "description": The optional description for the job.
- "lifetime": Lifetime of the active copy in days, ignored for INTELLIGENT-TIERING storage
- "priority": Priority of restore: Standard|Expedited|Bulk

---

### 🔎 restore-status 🔎

Show the restore status for objects being restored from GLACIER or INTELLIGENT-TIERING storage

rclone backend restore-status remote: [options] [<arguments>+]


This command can be used to show the status for objects being restored from GLACIER to normal storage, or from INTELLIGENT-TIERING Archive Access / Deep Archive Access tier to the Frequent Access tier. Like a little <cyan>vibe check</cyan> on your archive situation ✨

Usage Examples:

rclone backend restore-status s3:bucket/path/to/object rclone backend restore-status s3:bucket/path/to/directory rclone backend restore-status -o all s3:bucket/path/to/directory


> This command does <red>not</red> obey the filters. It does its own thing, main character energy 💅

It returns a list of status dictionaries.

[ { "Remote": "file.txt", "VersionID": null, "RestoreStatus": { "IsRestoreInProgress": true, "RestoreExpiryDate": "2023-09-06T12:29:19+01:00" }, "StorageClass": "GLACIER" }, { "Remote": "test.pdf", "VersionID": null, "RestoreStatus": { "IsRestoreInProgress": false, "RestoreExpiryDate": "2023-09-06T12:29:19+01:00" }, "StorageClass": "DEEP_ARCHIVE" }, { "Remote": "test.gz", "VersionID": null, "RestoreStatus": { "IsRestoreInProgress": true, "RestoreExpiryDate": "null" }, "StorageClass": "INTELLIGENT_TIERING" } ]


Options:

- "all": if set then show all objects, not just ones with restore status

---

### 📋 list-multipart-uploads 📋

List the unfinished multipart uploads

rclone backend list-multipart-uploads remote: [options] [<arguments>+]


This command lists the unfinished multipart uploads in JSON format.

rclone backend list-multipart s3:bucket/path/to/object


It returns a dictionary of buckets with values as lists of unfinished multipart uploads.

You can call it with no bucket, in which case it lists all buckets, or with a bucket, or with a bucket and a path. Flexible queen 🌈

{ "rclone": [ { "Initiated": "2020-06-26T14:20:36Z", "Initiator": { "DisplayName": "XXX", "ID": "arn:aws:iam::XXX:user/XXX" }, "Key": "KEY", "Owner": { "DisplayName": null, "ID": "XXX" }, "StorageClass": "STANDARD", "UploadId": "XXX" } ], "rclone-1000files": [], "rclone-dst": [] }


---

### 🧹 cleanup 🧹

Remove unfinished multipart uploads.

rclone backend cleanup remote: [options] [<arguments>+]


This command removes unfinished multipart uploads of age greater than `max-age`, which defaults to <purple>24 hours</purple>.

Note that you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do. <yellow>Look before you leap, bestie</yellow> 👀

rclone backend cleanup s3:bucket/path/to/object rclone backend cleanup -o max-age=7w s3:bucket/path/to/object


Durations are parsed as per the rest of rclone, `2h`, `7d`, `7w` etc.

Options:

- "max-age": Max age of upload to delete

---

### 🫥 cleanup-hidden 🫥

Remove old versions of files.

rclone backend cleanup-hidden remote: [options] [<arguments>+]


This command removes any old <purple>hidden</purple> versions of files on a versions enabled bucket.

Note that you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do.

rclone backend cleanup-hidden s3:bucket/path/to/dir


---

### 🔄 versioning 🔄

Set/get versioning support for a bucket.

rclone backend versioning remote: [options] [<arguments>+]


This command sets versioning support if a parameter is passed, and then returns the current versioning status for the bucket supplied.

rclone backend versioning s3:bucket # read status only rclone backend versioning s3:bucket Enabled rclone backend versioning s3:bucket Suspended


It may return `Enabled`, `Suspended` or `Unversioned`. And <red>important</red>: note that once versioning has been enabled, the status <bold>can't</bold> be set back to `Unversioned`. No take-backs 💀

---

### ⚙️ set ⚙️

Set command for updating the config parameters.

rclone backend set remote: [options] [<arguments>+]


This `set` command can be used to update the config parameters for a running `s3` backend.

Usage Examples:

<lavender>okay and the actual examples pull up in the next bit, hold on, don't go anywhere</lavender> 💅

rclone backend set s3: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=s3: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=s3: -o session_token=X -o access_key_id=X -o secret_access_key=X


<pink>Okay so the option keys? They're named exactly like they are in the config file. No glow-up, no rebranding. 💖</pink>

Calling this **rebuilds the connection to the s3 backend** with the new params you just handed over. And here's the cute part — you only have to pass the **new** parameters, because everything you *don't* mention just defaults to whatever's currently in use. Lazy girl friendly, we love that for us. 🫶

It doesn't return anything. Not a peep. Zero receipts. 💀

---

### 🌈 Anonymous access to public buckets 🌈

<purple>Wanna point rclone at a public bucket? Configure it with a **blank** `access_key_id` and `secret_access_key` and you're golden, bestie.</purple> Your config should end up looking like this:

[anons3] type = s3 provider = AWS


Then just use it as normal with the name of the public bucket, like:

rclone lsd anons3:1000genomes


You'll be able to **list and copy data but not upload it.** Read-only energy. 👑

You can also do this entirely on the command line, no config file required:

rclone lsd :s3,provider=AWS:1000genomes


---

### ✨ Providers ✨

<pink>**AWS S3**</pink>

This is the provider used as the main example and described in the configuration section above. It's the blueprint, the blueprint-est of blueprints. ⭐

---

### 🦋 AWS Directory Buckets 🦋

From <hotpink>rclone v1.69</hotpink> Directory Buckets are supported. slay.

You will need to set the `directory_buckets = true` config parameter, or just use `--s3-directory-buckets`. Either works, pick your fighter. 💅

> Heads up though: rclone cannot **yet** do these two things, so don't come for it:
>
> - Create directory buckets
> - List directory buckets

See the `--s3-directory-buckets` flag for more info. 🧚

---

### ❄️ AWS Snowball Edge ❄️

AWS Snowball is a hardware appliance used for transferring bulk data back to AWS. Its main software interface is S3 object storage. It's literally a box that shows up at your door, and inside the box is... S3. Iconic behaviour fr. 📦

To use rclone with AWS Snowball Edge devices, configure as standard for an 'S3 Compatible Service'.

If you're on rclone **pre v1.59**, be sure to set `upload_cutoff = 0` — otherwise you <red>will</red> run into authentication header issues, because the snowball device does not support query parameter based authentication. Not cute. 😭

With **rclone v1.59 or later**, setting `upload_cutoff` should not be necessary. You're free.

eg.

[snowball] type = s3 provider = Other access_key_id = YOUR_ACCESS_KEY secret_access_key = YOUR_SECRET_KEY endpoint = http://[IP of Snowball]:8080 upload_cutoff = 0


---

### 🌸 Ceph 🌸

Ceph is an open-source, unified, distributed storage system designed for excellent performance, reliability and scalability. It has an S3 compatible object storage interface. Very main character of it. 💜

To use rclone with Ceph, configure as above but **leave the region blank** and **set the endpoint**. You should end up with something like this in your config:

[ceph] type = s3 provider = Ceph env_auth = false access_key_id = XXX secret_access_key = YYY region = endpoint = https://ceph.endpoint.example.com location_constraint = acl = server_side_encryption = storage_class =


> If you are using an older version of CEPH (e.g. `10.2.x Jewel`) and a version of rclone **before v1.59**, then you may need to supply the parameter `--s3-upload-cutoff 0` or put this in the config file as `upload_cutoff 0` to work around a bug which causes uploading of small files to fail. Brace yourself. 🙈

<purple>Note also that Ceph sometimes puts `/` in the passwords it gives users.</purple> If you read the secret access key using the command line tools you will get a JSON blob with the `/` escaped as `\/`. Make sure you only write `/` in the secret access key. Okay? Only the slash. The pretty one. ✨

Eg the dump from Ceph looks something like this (irrelevant keys removed).

{ "user_id": "xxx", "display_name": "xxxx", "keys": [ { "user": "xxx", "access_key": "xxxxxx", "secret_key": "xxxxxx/xxxx" } ], }


Because this is a json dump, it is encoding the `/` as `\/`, so if you use the secret key as `xxxxxx/xxxx` it will work fine. <mint>Rip out the backslash, keep the slash, live your life.</mint> 🍓

---

### 🎀 Cloudflare R2 🎀

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services. No egress fees?? We're obsessed, actually. 💖

Here is an example of making a Cloudflare R2 configuration. First run:

rclone config


This will guide you through an interactive setup process.

> Note that all buckets are private, and all are stored in the same "auto" region. It is necessary to use Cloudflare workers to share the content of a bucket publicly.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> r2 Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. ... XX / Amazon S3 Compliant Storage Providers including AWS, Alibaba, Ceph, China Mobile, Cloudflare, ArvanCloud, DigitalOcean, Dreamhost, Huawei OBS, IBM COS, Lyve Cloud, Minio, Magalu, Netease, RackCorp, Scaleway, SeaweedFS, StackPath, Storj, Synology, Tencent COS and Wasabi \ (s3) ... Storage> s3 Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. ... XX / Cloudflare R2 Storage \ (Cloudflare) ... provider> Cloudflare Option env_auth. Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth> 1 Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> ACCESS_KEY Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> SECRET_ACCESS_KEY Option region. Region to connect to. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / R2 buckets are automatically distributed across Cloudflare's data centers for low latency. \ (auto) region> 1 Option endpoint. Endpoint for S3 API. Required when using an S3 clone. Enter a value. Press Enter to leave empty. endpoint> https://ACCOUNT_ID.r2.cloudflarestorage.com Edit advanced config? y) Yes n) No (default) y/n> n

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


This will leave your config looking something like:

[r2] type = s3 provider = Cloudflare access_key_id = ACCESS_KEY secret_access_key = SECRET_ACCESS_KEY region = auto endpoint = https://ACCOUNT_ID.r2.cloudflarestorage.com acl = private


Now run `rclone lsf r2:` to see your buckets and `rclone lsf r2:bucket` to look within a bucket. <rainbow>Go look at your little buckets, you earned this.</rainbow> 🪣

For R2 tokens with the "Object Read & Write" permission, you may also need to add `no_check_bucket = true` for object uploads to work correctly.

> Note that Cloudflare decompresses files uploaded with `Content-Encoding: gzip` by default which is a deviation from what AWS does. If this is causing a problem then upload the files with `--header-upload "Cache-Control: no-transform"`

A consequence of this is that `Content-Encoding: gzip` will **never** appear in the metadata on Cloudflare. Ever. Periodt. 💅

---

### 🌈 Dreamhost 🌈

Dreamhost DreamObjects is an object storage system based on CEPH.

To use rclone with Dreamhost, configure as above but **leave the region blank** and **set the endpoint**. You should end up with something like this in your config:

[dreamobjects] type = s3 provider = DreamHost env_auth = false access_key_id = your_access_key secret_access_key = your_secret_key region = endpoint = objects-us-west-1.dream.io location_constraint = acl = private server_side_encryption = storage_class =


---

### ⭐ Google Cloud Storage ⭐

GoogleCloudStorage is an S3-interoperable object storage service from Google Cloud Platform.

To connect to Google Cloud Storage you will need an **access key** and **secret key**. These can be retrieved by creating an HMAC key. 🔑

[gs] type = s3 provider = GCS access_key_id = your_access_key secret_access_key = your_secret_key endpoint = https://storage.googleapis.com


> Note that `--s3-versions` does **not** work with GCS when it needs to do directory paging. Rclone will return the error:

s3 protocol error: received versions listing with IsTruncated set with no NextKeyMarker


This is Google bug `#312292516`. <red>Not our fault, bestie, we're just the messenger.</red> 😭

---

### 🫶 DigitalOcean Spaces 🫶

Spaces is an S3-interoperable object storage service from cloud provider DigitalOcean.

To connect to DigitalOcean Spaces you will need an access key and secret key. These can be retrieved on the "Applications & API" page of the DigitalOcean control panel. They will be needed when prompted by `rclone config` for your `access_key_id` and `secret_access_key`.

When prompted for a region or location_constraint, press enter to use the default value. The region **must** be included in the endpoint setting (e.g. `nyc3.digitaloceanspaces.com`). The default values can be used for other settings.

Going through the whole process of creating a new remote by running `rclone config`, each prompt should be answered as shown below:

Storage> s3 env_auth> 1 access_key_id> YOUR_ACCESS_KEY secret_access_key> YOUR_SECRET_KEY region> endpoint> nyc3.digitaloceanspaces.com location_constraint> acl> storage_class>


The resulting configuration file should look like:

[spaces] type = s3 provider = DigitalOcean env_auth = false access_key_id = YOUR_ACCESS_KEY secret_access_key = YOUR_SECRET_KEY region = endpoint = nyc3.digitaloceanspaces.com location_constraint = acl = server_side_encryption = storage_class =


Okay so once that's locked in you can literally just make a brand-new Space and start copying files into it, no cap:

rclone mkdir spaces:my-new-space rclone copy /path/to/files spaces:my-new-space


Periodt. That's the whole vibe. 💅

---

### 🌸 Huawei OBS 🌸

Object Storage Service (OBS) is giving *stable, secure, efficient, easy-to-use* cloud storage energy — it lets you store basically any volume of unstructured data in any format and reach it from, like, anywhere. 🦋

OBS hands out an S3 interface, so you can copy + tweak this config and drop it straight into your rclone configuration file. Iconic:

[obs] type = s3 provider = HuaweiOBS access_key_id = your-access-key-id secret_access_key = your-secret-access-key region = af-south-1 endpoint = obs.af-south-1.myhuaweicloud.com acl = private


Orrr you can do it the interactive way via the command line, bestie — it looks like this:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> obs Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3 Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] 9 / Huawei Object Storage Service \ (HuaweiOBS) [snip] provider> 9 Option env_auth. Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth> 1 Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> your-access-key-id Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> your-secret-access-key Option region. Region to connect to. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / AF-Johannesburg \ (af-south-1) 2 / AP-Bangkok \ (ap-southeast-2) [snip] region> 1 Option endpoint. Endpoint for OBS API. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / AF-Johannesburg \ (obs.af-south-1.myhuaweicloud.com) 2 / AP-Bangkok \ (obs.ap-southeast-2.myhuaweicloud.com) [snip] endpoint> 1 Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) [snip] acl> 1 Edit advanced config? y) Yes n) No (default) y/n>

[obs] type = s3 provider = HuaweiOBS access_key_id = your-access-key-id secret_access_key = your-secret-access-key region = af-south-1 endpoint = obs.af-south-1.myhuaweicloud.com acl = private

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== obs s3

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> q


And that's it, you're in. Absolute slay. ✨

---

### 🧊 IBM COS (S3) 🧊

So, anything you stash with IBM Cloud Object Storage gets encrypted and scattered across multiple geographic locations, and you reach it through an implementation of the S3 API. This service is lowkey running on the distributed storage tech from IBM's Cloud Object Storage System (formerly known as Cleversafe, for the history girlies 🌈). Wanna read more? It's over here: (http://www.ibm.com/cloud/object-storage)

To set up access to IBM COS S3, here are the steps:

1. Run `rclone config` and pick `n` for a new remote.

2018/02/14 14:13:11 NOTICE: Config file "C:\Users\a\.config\rclone\rclone.conf" not found - using defaults No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n


2. Type in the name for your configuration.

name> <YOUR NAME>


3. Pick the "s3" storage. 💅

Choose a number from below, or type in your own value [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3" [snip] Storage> s3


4. Now choose IBM COS as the S3 Storage Provider.

Choose the S3 provider. Choose a number from below, or type in your own value 1 / Choose this option to configure Storage to AWS S3 \ "AWS" 2 / Choose this option to configure Storage to Ceph Systems \ "Ceph" 3 / Choose this option to configure Storage to Dreamhost \ "Dreamhost" 4 / Choose this option to the configure Storage to IBM COS S3 \ "IBMCOS" 5 / Choose this option to the configure Storage to Minio \ "Minio" Provider>4


5. Drop in your Access Key and Secret.

AWS Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> <> AWS Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> <>


6. Tell it which endpoint to use for IBM COS. For Public IBM COS, just pick from the options below. For On Premise IBM COS, you type in the endpoint address yourself.

Endpoint for IBM COS S3 API. Specify if using an IBM COS On Premise. Choose a number from below, or type in your own value 1 / US Cross Region Endpoint \ "s3-api.us-geo.objectstorage.softlayer.net" 2 / US Cross Region Dallas Endpoint \ "s3-api.dal.us-geo.objectstorage.softlayer.net" 3 / US Cross Region Washington DC Endpoint \ "s3-api.wdc-us-geo.objectstorage.softlayer.net" 4 / US Cross Region San Jose Endpoint \ "s3-api.sjc-us-geo.objectstorage.softlayer.net" 5 / US Cross Region Private Endpoint \ "s3-api.us-geo.objectstorage.service.networklayer.com" 6 / US Cross Region Dallas Private Endpoint \ "s3-api.dal-us-geo.objectstorage.service.networklayer.com" 7 / US Cross Region Washington DC Private Endpoint \ "s3-api.wdc-us-geo.objectstorage.service.networklayer.com" 8 / US Cross Region San Jose Private Endpoint \ "s3-api.sjc-us-geo.objectstorage.service.networklayer.com" 9 / US Region East Endpoint \ "s3.us-east.objectstorage.softlayer.net" 10 / US Region East Private Endpoint \ "s3.us-east.objectstorage.service.networklayer.com" 11 / US Region South Endpoint [snip] 34 / Toronto Single Site Private Endpoint \ "s3.tor01.objectstorage.service.networklayer.com" endpoint>1


7. Pick an IBM COS Location Constraint. Heads up bestie: if you're on IBM Cloud Public, the location constraint **has** to match the endpoint. And if you're on on-prem COS? Don't pick anything from this list, just hit enter.

1 / US Cross Region Standard \ "us-standard" 2 / US Cross Region Vault \ "us-vault" 3 / US Cross Region Cold \ "us-cold" 4 / US Cross Region Flex \ "us-flex" 5 / US East Region Standard \ "us-east-standard" 6 / US East Region Vault \ "us-east-vault" 7 / US East Region Cold \ "us-east-cold" 8 / US East Region Flex \ "us-east-flex" 9 / US South Region Standard \ "us-south-standard" 10 / US South Region Vault \ "us-south-vault" [snip] 32 / Toronto Flex \ "tor01-flex" location_constraint>1


9. Now pick a canned ACL. IBM Cloud (Storage) supports "public-read" and "private". IBM Cloud(Infra) supports all the canned ACLs. On-Premise COS supports all the canned ACLs.

...and the ACL menu isn't done with us yet, bestie 😭 — there's still a whole little menu of canned ACLs to scroll through before this thing lets you go. Then we wrap up the whole IBM COS walkthrough and the config file lands:

Canned ACL used when creating buckets and/or storing objects in S3. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). This acl is available on IBM Cloud (Infra), IBM Cloud (Storage), On-Premise COS \ "private" 2 / Owner gets FULL_CONTROL. The AllUsers group gets READ access. This acl is available on IBM Cloud (Infra), IBM Cloud (Storage), On-Premise IBM COS \ "public-read" 3 / Owner gets FULL_CONTROL. The AllUsers group gets READ and WRITE access. This acl is available on IBM Cloud (Infra), On-Premise IBM COS \ "public-read-write" 4 / Owner gets FULL_CONTROL. The AuthenticatedUsers group gets READ access. Not supported on Buckets. This acl is available on IBM Cloud (Infra) and On-Premise IBM COS \ "authenticated-read" acl> 1

Review the displayed configuration and accept to save the “remote” then quit. The config file should look like this

[xxx] type = s3 Provider = IBMCOS access_key_id = xxx secret_access_key = yyy endpoint = s3-api.us-geo.objectstorage.softlayer.net location_constraint = us-standard acl = private

Execute rclone commands
1. Create a bucket. rclone mkdir IBM-COS-XREGION:newbucket
2. List available buckets. rclone lsd IBM-COS-XREGION: -1 2017-11-08 21:16:22 -1 test -1 2018-02-14 20:16:39 -1 newbucket
3. List contents of a bucket. rclone ls IBM-COS-XREGION:newbucket 18685952 test.exe
4. Copy a file from local to remote. rclone copy /Users/file.txt IBM-COS-XREGION:newbucket
5. Copy a file from remote to local. rclone copy IBM-COS-XREGION:newbucket/file.txt .
6. Delete a file on remote. rclone delete IBM-COS-XREGION:newbucket/file.txt


<purple>That's the whole IBM COS journey babes</purple> 💅 you made a bucket, you listed buckets, you listed what's *in* the bucket, you copied both directions, you deleted one (rip `file.txt`, we hardly knew ye 💀). Certified rclone girlie behaviour right there.

---

### 🌈 IDrive e2

<cyan>IDrive e2 time!!</cyan> ✨ Here's an example of making an IDrive e2 configuration. First run:

rclone config


This will guide you through an interactive setup process. <lavender>(interactive = it asks you nice little questions and you just vibe along, no cap)</lavender>

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> e2

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / IDrive e2 \ (IDrive) [snip] provider> IDrive

Option env_auth. Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth>

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> YOUR_ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> YOUR_SECRET_KEY

Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) / Owner gets FULL_CONTROL. 2 | The AllUsers group gets READ access. \ (public-read) / Owner gets FULL_CONTROL. 3 | The AllUsers group gets READ and WRITE access.

Granting this on a bucket is generally not recommended.

\ (public-read-write) / Owner gets FULL_CONTROL. 4 | The AuthenticatedUsers group gets READ access. \ (authenticated-read) / Object owner gets FULL_CONTROL. 5 | Bucket owner gets READ access.

If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.

\ (bucket-owner-read) / Both the object owner and the bucket owner get FULL_CONTROL over the object. 6 | If you specify this canned ACL when creating a bucket, Amazon S3 ignores it. \ (bucket-owner-full-control) acl>

Edit advanced config? y) Yes n) No (default) y/n>

Configuration complete. Options:

type: s3
provider: IDrive
access_key_id: YOUR_ACCESS_KEY
secret_access_key: YOUR_SECRET_KEY
endpoint: q9d9.la12.idrivee2-5.com Keep this "e2" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


<pink>NOTICE</pink> 👀 — this ACL menu is a *different flavour* than the IBM COS one. Same idea, different wording, and it has the spicy notes: option 3 says granting `public-read-write` on a bucket is generally <red>not recommended</red> 🚩, and options 5 and 6 come with the warning that if you specify that canned ACL when creating a *bucket*, Amazon S3 straight up <italic>ignores it</italic> 💀. So like, keep that in mind, iykyk.

Also the default is just pressing Enter to leave the `acl` empty (no `1` typed in here, unlike IBM COS which picked `1`). And look at that default `endpoint` — `q9d9.la12.idrivee2-5.com`. It comes pre-filled for you. Iconic of them honestly 🫶

---

### 💜 IONOS Cloud

<hotpink>IONOS Cloud!!</hotpink> 🌸

IONOS S3 Object Storage is a service offered by IONOS for storing and accessing unstructured data. To connect to the service, you will need an access key and a secret key. These can be found in the Data Center Designer, by selecting Manager resources > Object Storage Key Manager. 🗝️

Here is an example of a configuration. First, run `rclone config`. This will walk you through an interactive setup process. Type `n` to add the new remote, and then enter a name:

Enter name for new remote. name> ionos-fra


Type `s3` to choose the connection type:

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3


Type `IONOS`:

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / IONOS Cloud \ (IONOS) [snip] provider> IONOS


Press Enter to choose the default option Enter AWS credentials in the next step:


Enter your Access Key and Secret key. These can be retrieved in the Data Center Designer, click on the menu “Manager resources” / “Object Storage Key Manager”. 🔑

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> YOUR_ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> YOUR_SECRET_KEY


Choose the region where your bucket is located 🌍:

Option region. Region where your bucket will be created and your data stored. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Frankfurt, Germany \ (de) 2 / Berlin, Germany \ (eu-central-2) 3 / Logrono, Spain \ (eu-south-2) region> 2


Choose the endpoint from the same region <yellow>(same region bestie, don't mix them up!!)</yellow>:

Option endpoint. Endpoint for IONOS S3 Object Storage. Specify the endpoint from the same region. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Frankfurt, Germany \ (s3-eu-central-1.ionoscloud.com) 2 / Berlin, Germany \ (s3-eu-central-2.ionoscloud.com) 3 / Logrono, Spain \ (s3-eu-south-2.ionoscloud.com) endpoint> 1


Press Enter to choose the default option or choose the desired ACL setting:


Press Enter to skip the advanced config:

Edit advanced config? y) Yes n) No (default) y/n>


Press Enter to save the configuration, and then `q` to quit the configuration process:

Configuration complete. Options:

type: s3
provider: IONOS
access_key_id: YOUR_ACCESS_KEY
secret_access_key: YOUR_SECRET_KEY
endpoint: s3-eu-central-1.ionoscloud.com Keep this "ionos-fra" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


<green>Done!</green> ✨ Now you can try some commands (for macOS, use `./rclone` instead of `rclone`).

---

**1)** Create a bucket (the name must be unique within the whole IONOS S3)

rclone mkdir ionos-fra:my-bucket


**2)** List available buckets

rclone lsd ionos-fra:


**4)** Copy a file from local to remote

rclone copy /Users/file.txt ionos-fra:my-bucket


**3)** List contents of a bucket

rclone ls ionos-fra:my-bucket


**5)** Copy a file from remote to local

rclone copy ionos-fra:my-bucket/file.txt


> bestie the numbering is out here living its own life (<pink>1, 2, 4, 3, 5</pink>, we don't ask questions, we just copy-paste 💅). The commands themselves? <hotpink>immaculate</hotpink>.

---

### 🌸 Minio 🌸

<purple>Minio</purple> is an object storage server built for cloud application developers and devops.

It is very easy to install and provides an S3 compatible server which can be used by rclone.

To use it, install Minio following the instructions here.

When it configures itself Minio will print something like this

Endpoint: http://192.168.1.106:9000 http://172.23.0.1:9000 AccessKey: USWUXHGYZQYFYFFIT3RE SecretKey: MOJRH0mkL1IPauahWITSVvyDrQbEEIwljvmxdq03 Region: us-east-1 SQS ARNs: arn:minio:sqs:us-east-1:1:redis arn:minio:sqs:us-east-1:2:redis

Browser Access: http://192.168.1.106:9000 http://172.23.0.1:9000

Command-line Access: https://docs.minio.io/docs/minio-client-quickstart-guide $ mc config host add myminio http://192.168.1.106:9000 USWUXHGYZQYFYFFIT3RE MOJRH0mkL1IPauahWITSVvyDrQbEEIwljvmxdq03

Object API (Amazon S3 compatible): Go: https://docs.minio.io/docs/golang-client-quickstart-guide Java: https://docs.minio.io/docs/java-client-quickstart-guide Python: https://docs.minio.io/docs/python-client-quickstart-guide JavaScript: https://docs.minio.io/docs/javascript-client-quickstart-guide .NET: https://docs.minio.io/docs/dotnet-client-quickstart-guide

Drive Capacity: 26 GiB Free, 165 GiB Total


These details need to go into rclone config like this. <red>Note that it is important to put the region in as stated above.</red> Don't skip it, don't improvise it, don't "eh close enough" it 😤

env_auth> 1 access_key_id> USWUXHGYZQYFYFFIT3RE secret_access_key> MOJRH0mkL1IPauahWITSVvyDrQbEEIwljvmxdq03 region> us-east-1 endpoint> http://192.168.1.106:9000 location_constraint> server_side_encryption>


Which makes the config file look like this

[minio] type = s3 provider = Minio env_auth = false access_key_id = USWUXHGYZQYFYFFIT3RE secret_access_key = MOJRH0mkL1IPauahWITSVvyDrQbEEIwljvmxdq03 region = us-east-1 endpoint = http://192.168.1.106:9000 location_constraint = server_side_encryption =


So once set up, for example, to copy files into a bucket

rclone copy /path/to/files minio:bucket


---

### 🦋 Outscale 🦋

<pink>OUTSCALE Object Storage (OOS)</pink> is an enterprise-grade, S3-compatible storage service provided by OUTSCALE, a brand of Dassault Systèmes. For more information about OOS, see the official documentation.

Here is an example of an OOS configuration that you can paste into your rclone configuration file:

[outscale] type = s3 provider = Outscale env_auth = false access_key_id = ABCDEFGHIJ0123456789 secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX region = eu-west-2 endpoint = oos.eu-west-2.outscale.com acl = private


You can also run `rclone config` to go through the interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> outscale

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] X / Amazon S3 Compliant Storage Providers including AWS, ...Outscale, ...and others \ (s3) [snip] Storage> outscale

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / OUTSCALE Object Storage (OOS) \ (Outscale) [snip] provider> Outscale

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> ABCDEFGHIJ0123456789

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Option region. Region where your bucket will be created and your data stored. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Paris, France \ (eu-west-2) 2 / New Jersey, USA \ (us-east-2) 3 / California, USA \ (us-west-1) 4 / SecNumCloud, Paris, France \ (cloudgouv-eu-west-1) 5 / Tokyo, Japan \ (ap-northeast-1) region> 1

Option endpoint. Endpoint for S3 API. Required when using an S3 clone. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Outscale EU West 2 (Paris) \ (oos.eu-west-2.outscale.com) 2 / Outscale US east 2 (New Jersey) \ (oos.us-east-2.outscale.com) 3 / Outscale EU West 1 (California) \ (oos.us-west-1.outscale.com) 4 / Outscale SecNumCloud (Paris) \ (oos.cloudgouv-eu-west-1.outscale.com) 5 / Outscale AP Northeast 1 (Japan) \ (oos.ap-northeast-1.outscale.com) endpoint> 1

Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. If the acl is an empty string then no X-Amz-Acl: header is added and the default (private) will be used. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) [snip] acl> 1

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: s3
provider: Outscale
access_key_id: ABCDEFGHIJ0123456789
secret_access_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
endpoint: oos.eu-west-2.outscale.com Keep this "outscale" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


---

### 👑 Qiniu Cloud Object Storage (Kodo) 👑

<purple>Qiniu Cloud Object Storage (Kodo)</purple>, a completely independent-researched core technology which is proven by repeated customer experience has occupied absolute leading market leader position. Kodo can be widely applied to mass data management.

To configure access to Qiniu Kodo, follow the steps below:

**1.** Run `rclone config` and select `n` for a new remote.

rclone config No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n


**2.** Give the name of the configuration. For example, name it `qiniu`.

name> qiniu


**3.** Select s3 storage.

Choose a number from below, or type in your own value [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3


**4.** Select Qiniu provider.

Choose a number from below, or type in your own value 1 / Amazon Web Services (AWS) S3 \ "AWS" [snip] 22 / Qiniu Object Storage (Kodo) \ (Qiniu) [snip] provider> Qiniu


**5.** Enter your SecretId and SecretKey of Qiniu Kodo.

Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Enter a boolean value (true or false). Press Enter for the default ("false"). Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). access_key_id> AKIDxxxxxxxxxx AWS Secret Access Key (password) Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). secret_access_key> xxxxxxxxxxx


**6.** Select endpoint for Qiniu Kodo. This is the standard endpoint for different region.

okay bestie, we're still deep in the S3 provider config arc and it's giving very much "choose your own adventure" but make it cloud storage. 💅 First up, you're at the endpoint picker and the options are:

/ The default endpoint - a good choice if you are unsure. 1 | East China Region 1.

Needs location constraint cn-east-1.

\ (cn-east-1) / East China Region 2. 2 | Needs location constraint cn-east-2. \ (cn-east-2) / North China Region 1. 3 | Needs location constraint cn-north-1. \ (cn-north-1) / South China Region 1. 4 | Needs location constraint cn-south-1. \ (cn-south-1) / North America Region. 5 | Needs location constraint us-north-1. \ (us-north-1) / Southeast Asia Region 1. 6 | Needs location constraint ap-southeast-1. \ (ap-southeast-1) / Northeast Asia Region 1. 7 | Needs location constraint ap-northeast-1. \ (ap-northeast-1) [snip] endpoint> 1


You smash that `1` for the default because you're a reliable queen. Then it immediately hits you with the Qiniu endpoint prompt:

Option endpoint. Endpoint for Qiniu Object Storage. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / East China Endpoint 1 \ (s3-cn-east-1.qiniucs.com) 2 / East China Endpoint 2 \ (s3-cn-east-2.qiniucs.com) 3 / North China Endpoint 1 \ (s3-cn-north-1.qiniucs.com) 4 / South China Endpoint 1 \ (s3-cn-south-1.qiniucs.com) 5 / North America Endpoint 1 \ (s3-us-north-1.qiniucs.com) 6 / Southeast Asia Endpoint 1 \ (s3-ap-southeast-1.qiniucs.com) 7 / Northeast Asia Endpoint 1 \ (s3-ap-northeast-1.qiniucs.com) endpoint> 1


You pick `1` again, no cap. Then location constraint:

Option location_constraint. Location constraint - must be set to match the Region. Used when creating buckets only. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / East China Region 1 \ (cn-east-1) 2 / East China Region 2 \ (cn-east-2) 3 / North China Region 1 \ (cn-north-1) 4 / South China Region 1 \ (cn-south-1) 5 / North America Region 1 \ (us-north-1) 6 / Southeast Asia Region 1 \ (ap-southeast-1) 7 / Northeast Asia Region 1 \ (ap-northeast-1) location_constraint> 1


Then step 7 is the acl and storage class moment. Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. So like, it's a fresh new ACL, not a hand-me-down. 🙈

Choose acl and storage class.

Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) / Owner gets FULL_CONTROL. 2 | The AllUsers group gets READ access. \ (public-read) [snip] acl> 2 The storage class to use when storing new objects in Tencent COS. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Standard storage class \ (STANDARD) 2 / Infrequent access storage mode \ (LINE) 3 / Archive storage mode \ (GLACIER) 4 / Deep archive storage mode \ (DEEP_ARCHIVE) [snip] storage_class> 1 Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config -------------------- [qiniu]

type: s3
provider: Qiniu
access_key_id: xxx
secret_access_key: xxx
region: cn-east-1
endpoint: s3-cn-east-1.qiniucs.com
location_constraint: cn-east-1
acl: public-read
storage_class: STANDARD -------------------- y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== qiniu s3


And boom, your remote config looks like this: a `[qiniu]` remote of type `s3`, provider `Qiniu`, with all those juicy details. You hit `y` and you're done. Current remotes show `qiniu` as `s3`. Slay. ✨

---

## 🌸 RackCorp 🌸

RackCorp Object Storage is an S3 compatible object storage platform from your friendly cloud provider RackCorp. The service is fast, reliable, well priced and located in many strategic locations unserviced by others, to ensure you can maintain data sovereignty.

Before you can use RackCorp Object Storage, you'll need to "sign up" for an account on our "portal". Next you can create an access key, a secret key and buckets, in your location of choice with ease. These details are required for the next steps of configuration, when rclone config asks for your `access_key_id` and `secret_access_key`.

Your config should end up looking a bit like this:

[RCS3-demo-config] type = s3 provider = RackCorp env_auth = true access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = au-nsw endpoint = s3.rackcorp.com location_constraint = au-nsw


---

## 🚀 Rclone Serve S3 🚀

Rclone can serve any remote over the S3 protocol. For details see the `rclone serve s3` documentation.

For example, to serve `remote:path` over s3, run the server like this:

rclone serve s3 --auth-key ACCESS_KEY_ID,SECRET_ACCESS_KEY remote:path


This will be compatible with an rclone remote which is defined like this:

[serves3] type = s3 provider = Rclone endpoint = http://127.0.0.1:8080/ access_key_id = ACCESS_KEY_ID secret_access_key = SECRET_ACCESS_KEY use_multipart_uploads = false


Note that setting `use_multipart_uploads = false` is to work around a bug which will be fixed in due course. 💀 (not me waiting for the fix, but okay)

---

## ☁️ Scaleway ☁️

Scaleway The Object Storage platform allows you to store anything from backups, logs and web assets to documents and photos. Files can be dropped from the Scaleway console or transferred through our API and CLI or using any S3-compatible tool.

Scaleway provides an S3 interface which can be configured for use with rclone like this:

[scaleway] type = s3 provider = Scaleway env_auth = false endpoint = s3.nl-ams.scw.cloud access_key_id = SCWXXXXXXXXXXXXXX secret_access_key = 1111111-2222-3333-44444-55555555555555 region = nl-ams location_constraint = nl-ams acl = private upload_cutoff = 5M chunk_size = 5M copy_cutoff = 5M


Scaleway Glacier is the low-cost S3 Glacier alternative from Scaleway and it works the same way as on S3 by accepting the "GLACIER" storage_class. So you can configure your remote with the `storage_class = GLACIER` option to upload directly to Scaleway Glacier. Don't forget that in this state you can't read files back after, you will need to restore them to "STANDARD" storage_class first before being able to read them (see "restore" section above). So like, it's giving deep freeze, not a snack. 🧊

---

## 🐦 Seagate Lyve Cloud 🐦

Seagate Lyve Cloud is an S3 compatible object storage platform from Seagate intended for enterprise use.

Here is a config run through for a remote called `remote` - you may choose a different name of course. Note that to create an access key and secret key you will need to create a service account first.

$ rclone config No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote


Choose s3 backend

Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3


Choose LyveCloud as S3 provider

Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / Seagate Lyve Cloud \ (LyveCloud) [snip] provider> LyveCloud


Take the default (just press enter) to enter access key and secret in the config file.

Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth>

AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> XXX

AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> YYY


Leave region blank

Region to connect to. Leave blank if you are using an S3 clone and you don't have a region. Choose a number from below, or type in your own value. Press Enter to leave empty. / Use this if unsure. 1 | Will use v4 signatures and an empty region. \ () / Use this only if v4 signatures don't work. 2 | E.g. pre Jewel/v10 CEPH. \ (other-v2-signature) region>


Choose an endpoint from the list

Endpoint for S3 API. Required when using an S3 clone. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Seagate Lyve Cloud US East 1 (Virginia) \ (s3.us-east-1.lyvecloud.seagate.com) 2 / Seagate Lyve Cloud US West 1 (California) \ (s3.us-west-1.lyvecloud.seagate.com) 3 / Seagate Lyve Cloud AP Southeast 1 (Singapore) \ (s3.ap-southeast-1.lyvecloud.seagate.com) endpoint> 1


Leave location constraint blank

Location constraint - must be set to match the Region. Leave blank if not sure. Used when creating buckets only. Enter a value. Press Enter to leave empty. location_constraint>


Choose default ACL (private).

Ooh and also bestie, quick word on that canned ACL situation 💅 — it's the thing that decides who gets to touch stuff when rclone makes buckets and stores/copies objects. It gets used when it's creating objects, and if `bucket_acl` isn't set, it's used for creating buckets too. Want the full lore? Go peek at https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl ✨

Also important, no cap: this ACL is applied when server-side copying objects, because S3 doesn't copy the ACL from the source — it just writes a brand new fresh one. Rude of it, honestly. 💀

Pick a number from the menu below, or type your own value. Hit Enter to leave it empty.

Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) [snip] acl>


And then your config file should look like this, bestie — very demure, very mindful:

[remote] type = s3 provider = LyveCloud access_key_id = XXX secret_access_key = YYY endpoint = s3.us-east-1.lyvecloud.seagate.com


---

### 🌿 SeaweedFS

SeaweedFS is a distributed storage system for blobs, objects, files, and data lake, with O(1) disk seek and a scalable file metadata store. It has an S3 compatible object storage interface. SeaweedFS can also act as a gateway to remote S3 compatible object store to cache data and metadata with asynchronous write back, for fast local speed and minimize access cost. It's giving *efficiency queen* 👑

So say your SeaweedFS is configured with `weed shell`, like this:

s3.bucket.create -name foo s3.configure -access_key=any -secret_key=any -buckets=foo -user=me -actions=Read,Write,List,Tagging,Admin -apply

{ "identities": [ { "name": "me", "credentials": [ { "accessKey": "any", "secretKey": "any" } ], "actions": [ "Read:foo", "Write:foo", "List:foo", "Tagging:foo", "Admin:foo" ] } ] }


To use rclone with SeaweedFS, that configuration above should end up looking something like this in your config:

[seaweedfs_s3] type = s3 provider = SeaweedFS access_key_id = any secret_access_key = any endpoint = localhost:8333


So once you're all set up, say you wanna copy files into a bucket, you literally just:

rclone copy /path/to/files seaweedfs_s3:foo


Main character behavior, honestly. 🦋

### 💜 Selectel

Selectel Cloud Storage is an S3 compatible storage system which features triple redundancy storage, automatic scaling, high availability and a comprehensive IAM system. So many green flags, we love to see it 🫶

Selectel have a section on their website for configuring rclone which shows how to make the right API keys.

From rclone v1.69 Selectel is a supported operator — please choose the Selectel provider type. Periodt.

> Heads up: you should use "vHosted" access for the buckets (which is the recommended default), **not** "path style".

You can use `rclone config` to make a new provider like this:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> selectel

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including ..., Selectel, ... \ (s3) [snip] Storage> s3

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / Selectel Object Storage \ (Selectel) [snip] provider> Selectel

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> SECRET_ACCESS_KEY

Option region. Region where your data stored. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / St. Petersburg \ (ru-1) region> 1

Option endpoint. Endpoint for Selectel Object Storage. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Saint Petersburg \ (s3.ru-1.storage.selcloud.ru) endpoint> 1

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: s3
provider: Selectel
access_key_id: ACCESS_KEY
secret_access_key: SECRET_ACCESS_KEY
region: ru-1
endpoint: s3.ru-1.storage.selcloud.ru Keep this "selectel" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


And your config should end up looking like this, bestie:

[selectel] type = s3 provider = Selectel access_key_id = ACCESS_KEY secret_access_key = SECRET_ACCESS_KEY region = ru-1 endpoint = s3.ru-1.storage.selcloud.ru


Slay. Moving on.

### 🧡 Wasabi

Wasabi is a cloud-based object storage service for a broad range of applications and use cases. Wasabi is designed for individuals and organizations that require a high-performance, reliable, and secure data storage infrastructure at minimal cost. Frugal *and* reliable? Iconic combo ngl 💖

Wasabi provides an S3 interface which can be configured for use with rclone like this:

No remotes found, make a new one? n) New remote s) Set configuration password n/s> n name> wasabi Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Amazon S3 (also Dreamhost, Ceph, ChinaMobile, ArvanCloud, Minio, Liara) \ "s3" [snip] Storage> s3 Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> YOURACCESSKEY AWS Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> YOURSECRETACCESSKEY Region to connect to. Choose a number from below, or type in your own value / The default endpoint - a good choice if you are unsure. 1 | US Region, Northern Virginia, or Pacific Northwest.

Leave location constraint empty.

\ "us-east-1" [snip] region> us-east-1 Endpoint for S3 API. Leave blank if using AWS to use the default endpoint for the region. Specify if using an S3 clone such as Ceph. endpoint> s3.wasabisys.com Location constraint - must be set to match the Region. Used when creating buckets only. Choose a number from below, or type in your own value 1 / Empty for US Region, Northern Virginia, or Pacific Northwest. \ "" [snip] location_constraint> Canned ACL used when creating buckets and/or storing objects in S3. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). \ "private" [snip] acl> The server-side encryption algorithm used when storing this object in S3. Choose a number from below, or type in your own value 1 / None \ "" 2 / AES256 \ "AES256" server_side_encryption> The storage class to use when storing objects in S3. Choose a number from below, or type in your own value 1 / Default \ "" 2 / Standard storage class \ "STANDARD" 3 / Reduced redundancy storage class \ "REDUCED_REDUNDANCY" 4 / Standard Infrequent Access storage class \ "STANDARD_IA" storage_class> Remote config

[wasabi] env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = us-east-1 endpoint = s3.wasabisys.com location_constraint = acl = server_side_encryption = storage_class =

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


This will leave the config file looking like this. ✨

[wasabi] type = s3 provider = Wasabi env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = endpoint = s3.wasabisys.com location_constraint = acl = server_side_encryption = storage_class =


### 🌈 Alibaba OSS

Here's an example of making an Alibaba Cloud (Aliyun) OSS configuration. First run:

rclone config


This will guide you through an interactive setup process. And bestie, we're *so* in for a treat, because it's got lore and seas of config coming up 😭💜

---

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> oss 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 / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3" [snip] Storage> s3 Choose your S3 provider. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Amazon Web Services (AWS) S3 \ "AWS" 2 / Alibaba Cloud Object Storage System (OSS) formerly Aliyun \ "Alibaba" 3 / Ceph Object Storage \ "Ceph" [snip] provider> Alibaba Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Enter a boolean value (true or false). Press Enter for the default ("false"). Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). access_key_id> accesskeyid AWS Secret Access Key (password) Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). secret_access_key> secretaccesskey Endpoint for OSS API. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / East China 1 (Hangzhou) \ "oss-cn-hangzhou.aliyuncs.com" 2 / East China 2 (Shanghai) \ "oss-cn-shanghai.aliyuncs.com" 3 / North China 1 (Qingdao) \ "oss-cn-qingdao.aliyuncs.com" [snip] endpoint> 1 Canned ACL used when creating buckets and storing or copying objects.

Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). \ "private" 2 / Owner gets FULL_CONTROL. The AllUsers group gets READ access. \ "public-read" / Owner gets FULL_CONTROL. The AllUsers group gets READ and WRITE access. [snip] acl> 1 The storage class to use when storing new objects in OSS. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Default \ "" 2 / Standard storage class \ "STANDARD" 3 / Archive storage mode. \ "GLACIER" 4 / Infrequent access storage mode. \ "STANDARD_IA" storage_class> 1 Edit advanced config? (y/n) y) Yes n) No y/n> n Remote config

[oss] type = s3 provider = Alibaba env_auth = false access_key_id = accesskeyid secret_access_key = secretaccesskey endpoint = oss-cn-hangzhou.aliyuncs.com acl = private storage_class = Standard

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


---

### 💜 China Mobile Ecloud Elastic Object Storage (EOS) 💜

okay bestie, next one up: here's an example of making an China Mobile Ecloud Elastic Object Storage (EOS) configuration ✨

First run this, like always:

rclone config


and it's gonna hold your hand through the whole interactive setup process, promise 🫶

...and the wizard just keeps talking, bestie, it's giving full interview 😭✨ Here's the whole exchange, verbatim, every prompt and every answer:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> ChinaMobile Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. ... XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) ... Storage> s3 Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. ... 4 / China Mobile Ecloud Elastic Object Storage (EOS) \ (ChinaMobile) ... provider> ChinaMobile Option env_auth. Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth> Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> accesskeyid Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> secretaccesskey Option endpoint. Endpoint for China Mobile Ecloud Elastic Object Storage (EOS) API. Choose a number from below, or type in your own value. Press Enter to leave empty. / The default endpoint - a good choice if you are unsure. 1 | East China (Suzhou) \ (eos-wuxi-1.cmecloud.cn) 2 / East China (Jinan) \ (eos-jinan-1.cmecloud.cn) 3 / East China (Hangzhou) \ (eos-ningbo-1.cmecloud.cn) 4 / East China (Shanghai-1) \ (eos-shanghai-1.cmecloud.cn) 5 / Central China (Zhengzhou) \ (eos-zhengzhou-1.cmecloud.cn) 6 / Central China (Changsha-1) \ (eos-hunan-1.cmecloud.cn) 7 / Central China (Changsha-2) \ (eos-zhuzhou-1.cmecloud.cn) 8 / South China (Guangzhou-2) \ (eos-guangzhou-1.cmecloud.cn) 9 / South China (Guangzhou-3) \ (eos-dongguan-1.cmecloud.cn) 10 / North China (Beijing-1) \ (eos-beijing-1.cmecloud.cn) 11 / North China (Beijing-2) \ (eos-beijing-2.cmecloud.cn) 12 / North China (Beijing-3) \ (eos-beijing-4.cmecloud.cn) 13 / North China (Huhehaote) \ (eos-huhehaote-1.cmecloud.cn) 14 / Southwest China (Chengdu) \ (eos-chengdu-1.cmecloud.cn) 15 / Southwest China (Chongqing) \ (eos-chongqing-1.cmecloud.cn) 16 / Southwest China (Guiyang) \ (eos-guiyang-1.cmecloud.cn) 17 / Nouthwest China (Xian) \ (eos-xian-1.cmecloud.cn) 18 / Yunnan China (Kunming) \ (eos-yunnan.cmecloud.cn) 19 / Yunnan China (Kunming-2) \ (eos-yunnan-2.cmecloud.cn) 20 / Tianjin China (Tianjin) \ (eos-tianjin-1.cmecloud.cn) 21 / Jilin China (Changchun) \ (eos-jilin-1.cmecloud.cn) 22 / Hubei China (Xiangyan) \ (eos-hubei-1.cmecloud.cn) 23 / Jiangxi China (Nanchang) \ (eos-jiangxi-1.cmecloud.cn) 24 / Gansu China (Lanzhou) \ (eos-gansu-1.cmecloud.cn) 25 / Shanxi China (Taiyuan) \ (eos-shanxi-1.cmecloud.cn) 26 / Liaoning China (Shenyang) \ (eos-liaoning-1.cmecloud.cn) 27 / Hebei China (Shijiazhuang) \ (eos-hebei-1.cmecloud.cn) 28 / Fujian China (Xiamen) \ (eos-fujian-1.cmecloud.cn) 29 / Guangxi China (Nanning) \ (eos-guangxi-1.cmecloud.cn) 30 / Anhui China (Huainan) \ (eos-anhui-1.cmecloud.cn) endpoint> 1 Option location_constraint. Location constraint - must match endpoint. Used when creating buckets only. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / East China (Suzhou) \ (wuxi1) 2 / East China (Jinan) \ (jinan1) 3 / East China (Hangzhou) \ (ningbo1) 4 / East China (Shanghai-1) \ (shanghai1) 5 / Central China (Zhengzhou) \ (zhengzhou1) 6 / Central China (Changsha-1) \ (hunan1) 7 / Central China (Changsha-2) \ (zhuzhou1) 8 / South China (Guangzhou-2) \ (guangzhou1) 9 / South China (Guangzhou-3) \ (dongguan1) 10 / North China (Beijing-1) \ (beijing1) 11 / North China (Beijing-2) \ (beijing2) 12 / North China (Beijing-3) \ (beijing4) 13 / North China (Huhehaote) \ (huhehaote1) 14 / Southwest China (Chengdu) \ (chengdu1) 15 / Southwest China (Chongqing) \ (chongqing1) 16 / Southwest China (Guiyang) \ (guiyang1) 17 / Nouthwest China (Xian) \ (xian1) 18 / Yunnan China (Kunming) \ (yunnan) 19 / Yunnan China (Kunming-2) \ (yunnan2) 20 / Tianjin China (Tianjin) \ (tianjin1) 21 / Jilin China (Changchun) \ (jilin1) 22 / Hubei China (Xiangyan) \ (hubei1) 23 / Jiangxi China (Nanchang) \ (jiangxi1) 24 / Gansu China (Lanzhou) \ (gansu1) 25 / Shanxi China (Taiyuan) \ (shanxi1) 26 / Liaoning China (Shenyang) \ (liaoning1) 27 / Hebei China (Shijiazhuang) \ (hebei1) 28 / Fujian China (Xiamen) \ (fujian1) 29 / Guangxi China (Nanning) \ (guangxi1) 30 / Anhui China (Huainan) \ (anhui1) location_constraint> 1 Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) / Owner gets FULL_CONTROL. 2 | The AllUsers group gets READ access. \ (public-read) / Owner gets FULL_CONTROL. 3 | The AllUsers group gets READ and WRITE access.

Granting this on a bucket is generally not recommended.

\ (public-read-write) / Owner gets FULL_CONTROL. 4 | The AuthenticatedUsers group gets READ access. \ (authenticated-read) / Object owner gets FULL_CONTROL. acl> private Option server_side_encryption. The server-side encryption algorithm used when storing this object in S3. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / None \ () 2 / AES256 \ (AES256) server_side_encryption> Option storage_class. The storage class to use when storing new objects in ChinaMobile. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Default \ () 2 / Standard storage class \ (STANDARD) 3 / Archive storage mode \ (GLACIER) 4 / Infrequent access storage mode \ (STANDARD_IA) storage_class> Edit advanced config? y) Yes n) No (default) y/n> n

[ChinaMobile] type = s3 provider = ChinaMobile access_key_id = accesskeyid secret_access_key = secretaccesskey endpoint = eos-wuxi-1.cmecloud.cn location_constraint = wuxi1 acl = private

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


---

<pink>okay but can we talk about that endpoint menu for a sec</pink> 😭 thirty whole regions, every province getting its own moment, main character energy from Suzhou all the way to Huainan. And yes, <yellow>`17 / Nouthwest China (Xian)`</yellow> — that is *literally* how the source page spells it, "Nouthwest", and we keep the typos because we respect the lore 💅 (the `location_constraint` menu says it too, so it's consistent, iconic behaviour honestly).

<purple>Also peep how your answers get echoed back</purple>: `endpoint = eos-wuxi-1.cmecloud.cn`, `location_constraint = wuxi1`, `acl = private` — that's the actual config block rclone is about to write to your config file, sandwiched in dashes like a lil' receipt 🧾, and then you say `y` to "Yes this is OK" and boom, remote secured. Periodt 🎀

---

### 🦋💖 Leviia Cloud Object Storage

<pink>Leviia Object Storage, backup and secure your data in a 100% French cloud, independent of GAFAM..</pink> ✨ (yes, two dots, we're not touching it, it's part of the vibe now 😭💀)

To configure access to Leviia, follow the steps below:

1. Run `rclone config` and select `n` for a new remote.

rclone config No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n


2. Give the name of the configuration. For example, name it `leviia'.

name> leviia


> <lavender>ngl that line is doing the absolute most with its punctuation — a backtick on one side and an apostrophe on the other 🙈 — but we're keeping it exactly as the source has it, no notes.</lavender>

3. Select `s3` storage.

Choose a number from below, or type in your own value [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ (s3) [snip] Storage> s3


4. Select Leviia provider.

Choose a number from below, or type in your own value 1 / Amazon Web Services (AWS) S3 \ "AWS" [snip] 15 / Leviia Object Storage \ (Leviia) [snip] provider> Leviia


5. Enter your SecretId and SecretKey of Leviia.

Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Enter a boolean value (true or false). Press Enter for the default ("false"). Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). access_key_id> ZnIx.xxxxxxxxxxxxxxx AWS Secret Access Key (password) Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default (""). secret_access_key> xxxxxxxxxxx

Select endpoint for Leviia.

/ The default endpoint 1 | Leviia. \ (s3.leviia.com) [snip] endpoint> 1

Choose acl.

type: s3
provider: Leviia
access_key_id: ZnIx.xxxxxxx
secret_access_key: xxxxxxxx
endpoint: s3.leviia.com
acl: private -------------------- y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== leviia s3


---

## 🦋 Liara

okay bestie, here's a whole example of making a <hotpink>Liara Object Storage</hotpink> config ✨ First you gotta run:

rclone config


and it walks you through the whole interactive setup, hand in hand, like a bestie 🫶

No remotes found, make a new one? n) New remote s) Set configuration password n/s> n name> Liara Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Amazon S3 (also Dreamhost, Ceph, ChinaMobile, ArvanCloud, Liara, Minio) \ "s3" [snip] Storage> s3 Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> YOURACCESSKEY AWS Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> YOURSECRETACCESSKEY Region to connect to. Choose a number from below, or type in your own value / The default endpoint 1 | US Region, Northern Virginia, or Pacific Northwest.

Leave location constraint empty.

\ "us-east-1" [snip] region> Endpoint for S3 API. Leave blank if using Liara to use the default endpoint for the region. Specify if using an S3 clone such as Ceph. endpoint> storage.iran.liara.space Canned ACL used when creating buckets and/or storing objects in S3. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). \ "private" [snip] acl> The server-side encryption algorithm used when storing this object in S3. Choose a number from below, or type in your own value 1 / None \ "" 2 / AES256 \ "AES256" server_side_encryption> The storage class to use when storing objects in S3. Choose a number from below, or type in your own value 1 / Default \ "" 2 / Standard storage class \ "STANDARD" storage_class> Remote config

[Liara] env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY endpoint = storage.iran.liara.space location_constraint = acl = server_side_encryption = storage_class =

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


and after all that, your config file is gonna be looking <purple>immaculate</purple> like this 💅

[Liara] type = s3 provider = Liara env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = endpoint = storage.iran.liara.space location_constraint = acl = server_side_encryption = storage_class =


---

## 🌸 Linode

and now the <cyan>Linode</cyan> one, same vibe, here's an example of making a Linode Object Storage configuration 💖 First, run:

rclone config


and let it guide you through the interactive setup process, no cap 🌈

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> linode

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ...Linode, ...and others \ (s3) [snip] Storage> s3

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / Linode Object Storage \ (Linode) [snip] provider> Linode

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> SECRET_ACCESS_KEY

Option endpoint. Endpoint for Linode Object Storage API. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Amsterdam (Netherlands), nl-ams-1 \ (nl-ams-1.linodeobjects.com) 2 / Atlanta, GA (USA), us-southeast-1 \ (us-southeast-1.linodeobjects.com) 3 / Chennai (India), in-maa-1 \ (in-maa-1.linodeobjects.com) 4 / Chicago, IL (USA), us-ord-1 \ (us-ord-1.linodeobjects.com) 5 / Frankfurt (Germany), eu-central-1 \ (eu-central-1.linodeobjects.com) 6 / Jakarta (Indonesia), id-cgk-1 \ (id-cgk-1.linodeobjects.com) 7 / London 2 (Great Britain), gb-lon-1 \ (gb-lon-1.linodeobjects.com) 8 / Los Angeles, CA (USA), us-lax-1 \ (us-lax-1.linodeobjects.com) 9 / Madrid (Spain), es-mad-1 \ (es-mad-1.linodeobjects.com) 10 / Melbourne (Australia), au-mel-1 \ (au-mel-1.linodeobjects.com) 11 / Miami, FL (USA), us-mia-1 \ (us-mia-1.linodeobjects.com) 12 / Milan (Italy), it-mil-1 \ (it-mil-1.linodeobjects.com) 13 / Newark, NJ (USA), us-east-1 \ (us-east-1.linodeobjects.com) 14 / Osaka (Japan), jp-osa-1 \ (jp-osa-1.linodeobjects.com) 15 / Paris (France), fr-par-1 \ (fr-par-1.linodeobjects.com) 16 / São Paulo (Brazil), br-gru-1 \ (br-gru-1.linodeobjects.com) 17 / Seattle, WA (USA), us-sea-1 \ (us-sea-1.linodeobjects.com) 18 / Singapore, ap-south-1 \ (ap-south-1.linodeobjects.com) 19 / Singapore 2, sg-sin-1 \ (sg-sin-1.linodeobjects.com) 20 / Stockholm (Sweden), se-sto-1 \ (se-sto-1.linodeobjects.com) 21 / Washington, DC, (USA), us-iad-1 \ (us-iad-1.linodeobjects.com) endpoint> 5

Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. If the acl is an empty string then no X-Amz-Acl: header is added and the default (private) will be used. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) [snip] acl>

Edit advanced config? y) Yes n) No (default) y/n> n


> fr fr bestie, that `acl` note is lowkey important — that ACL gets applied when you're server-side copying objects, bc S3 doesn't copy the ACL from the source, it writes a fresh one 💀 and if `acl` is an empty string then no `X-Amz-Acl:` header gets added and the default (`private`) is what gets used. 🎀

Configuration complete. Options:

type: s3
provider: Linode
access_key_id: ACCESS_KEY
secret_access_key: SECRET_ACCESS_KEY
endpoint: eu-central-1.linodeobjects.com Keep this "linode" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Aaaand boom, that's a whole remote, bestie. ✨ Your config file is now serving this:

[linode] type = s3 provider = Linode access_key_id = ACCESS_KEY secret_access_key = SECRET_ACCESS_KEY endpoint = eu-central-1.linodeobjects.com


---

### Magalu 💜

Okay so here's the rundown on setting up a Magalu Object Storage config, step by step.

First, you run:

rclone config


and it just walks you through the whole interactive setup like a little wizard. 🧚 Here's what that looks like:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> magalu

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ...Magalu, ...and others \ (s3) [snip] Storage> s3

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / Magalu Object Storage \ (Magalu) [snip] provider> Magalu

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> SECRET_ACCESS_KEY

Option endpoint. Endpoint for Magalu Object Storage API. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / São Paulo, SP (BR), br-se1 \ (br-se1.magaluobjects.com) 2 / Fortaleza, CE (BR), br-ne1 \ (br-ne1.magaluobjects.com) endpoint> 2

Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. If the acl is an empty string then no X-Amz-Acl: header is added and the default (private) will be used. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) [snip] acl>

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: s3
provider: magalu
access_key_id: ACCESS_KEY
secret_access_key: SECRET_ACCESS_KEY
endpoint: br-ne1.magaluobjects.com Keep this "magalu" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


And after all that, your config file is giving:

[magalu] type = s3 provider = Magalu access_key_id = ACCESS_KEY secret_access_key = SECRET_ACCESS_KEY endpoint = br-ne1.magaluobjects.com


Iconic. 🎀

---

### ArvanCloud 🌸

So ArvanCloud's ArvanCloud Object Storage is *not* your average limited traditional file storage, bestie — it goes way beyond that. It hands you access to backup and archived files and lets you share stuff too. Things like the profile image in an app, images that users send you, or scanned documents can all be stored securely and easily in their Object Storage service. 💅

ArvanCloud gives you an S3 interface, which you can set up for rclone like this:

No remotes found, make a new one? n) New remote s) Set configuration password n/s> n name> ArvanCloud Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Amazon S3 (also Dreamhost, Ceph, ChinaMobile, ArvanCloud, Liara, Minio) \ "s3" [snip] Storage> s3 Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter AWS credentials in the next step \ "false" 2 / Get AWS credentials from the environment (env vars or IAM) \ "true" env_auth> 1 AWS Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> YOURACCESSKEY AWS Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> YOURSECRETACCESSKEY Region to connect to. Choose a number from below, or type in your own value / The default endpoint - a good choice if you are unsure. 1 | US Region, Northern Virginia, or Pacific Northwest.

Leave location constraint empty.

\ "us-east-1" [snip] region> Endpoint for S3 API. Leave blank if using ArvanCloud to use the default endpoint for the region. Specify if using an S3 clone such as Ceph. endpoint> s3.arvanstorage.com Location constraint - must be set to match the Region. Used when creating buckets only. Choose a number from below, or type in your own value 1 / Empty for Iran-Tehran Region. \ "" [snip] location_constraint> Canned ACL used when creating buckets and/or storing objects in S3. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Choose a number from below, or type in your own value 1 / Owner gets FULL_CONTROL. No one else has access rights (default). \ "private" [snip] acl> The server-side encryption algorithm used when storing this object in S3. Choose a number from below, or type in your own value 1 / None \ "" 2 / AES256 \ "AES256" server_side_encryption> The storage class to use when storing objects in S3. Choose a number from below, or type in your own value 1 / Default \ "" 2 / Standard storage class \ "STANDARD" storage_class> Remote config

[ArvanCloud] env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = ir-thr-at1 endpoint = s3.arvanstorage.com location_constraint = acl = server_side_encryption = storage_class =

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


And then your config file is left looking exactly like this:

[ArvanCloud] type = s3 provider = ArvanCloud env_auth = false access_key_id = YOURACCESSKEY secret_access_key = YOURSECRETACCESSKEY region = endpoint = s3.arvanstorage.com location_constraint = acl = server_side_encryption = storage_class =


Slay. 🦋

---

### Tencent COS 🌈

Tencent Cloud Object Storage (COS) is a distributed storage service that Tencent Cloud offers for unstructured data. It's secure, stable, massive, convenient, low-delay and low-cost. It's giving everything, honestly.

To set up access to Tencent COS, follow these steps below:

1. Run `rclone config` and pick `n` for a new remote.

rclone config No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n


2. Give your configuration a name. For example, name it `` `cos' ``.

name> cos


3. Select `s3` storage.

Choose a number from below, or type in your own value [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3" [snip] Storage> s3


4. Select the `TencentCOS` provider.

Choose a number from below, or type in your own value 1 / Amazon Web Services (AWS) S3 \ "AWS" [snip] 11 / Tencent Cloud Object Storage (COS) \ "TencentCOS" [snip] provider> TencentCOS


5. Enter your SecretId and SecretKey of Tencent Cloud.


6. Select the endpoint for Tencent COS. This is the standard endpoint for different region.

1 / Beijing Region.
        \ "cos.ap-beijing.myqcloud.com"
      2 / Nanjing Region.
        \ "cos.ap-nanjing.myqcloud.com"
      3 / Shanghai Region.
        \ "cos.ap-shanghai.myqcloud.com"
      4 / Guangzhou Region.
        \ "cos.ap-guangzhou.myqcloud.com"
   [snip]
   endpoint> 4

7. Choose acl and storage class.

   Note that this ACL is applied when server-side copying objects as S3
   doesn't copy the ACL from the source but rather writes a fresh one.
   Enter a string value. Press Enter for the default ("").
   Choose a number from below, or type in your own value
    1 / Owner gets Full_CONTROL. No one else has access rights (default).
      \ "default"
   [snip]
   acl> 1
   The storage class to use when storing new objects in Tencent COS.
   Enter a string value. Press Enter for the default ("").
   Choose a number from below, or type in your own value
    1 / Default
      \ ""
   [snip]
   storage_class> 1
   Edit advanced config? (y/n)
   y) Yes
   n) No (default)
   y/n> n
   Remote config
   --------------------
   [cos]
   type = s3
   provider = TencentCOS
   env_auth = false
   access_key_id = xxx
   secret_access_key = xxx
   endpoint = cos.ap-guangzhou.myqcloud.com
   acl = default
   --------------------
   y) Yes this is OK (default)
   e) Edit this remote
   d) Delete this remote
   y/e/d> y
   Current remotes:

   Name                 Type
   ====                 ====
   cos                  s3

### 🍓 Netease NOS

Okay bestie, for Netease NOS you literally just configure it through the configurator, pick <pink>**Netease**</pink> as the provider, and you're done. That's it, that's the whole thing. The configurator is gonna set `force_path_style = false` for you automatically, which — no cap — is *required* for it to actually work right, so don't go messing with it. 💅

### 🎀 Petabox

Here's a full lil walkthrough for making a Petabox config. First, run:

rclone config


This will guide you through an interactive setup process. ✨

No remotes found, make a new one? n) New remote s) Set configuration password n/s> n

Enter name for new remote. name> My Petabox Storage

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3" [snip] Storage> s3

Option provider. Choose your S3 provider. Choose a number from below, or type in your own value. Press Enter to leave empty. [snip] XX / Petabox Object Storage \ (Petabox) [snip] provider> Petabox

Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> YOUR_ACCESS_KEY_ID

Option region. Region where your bucket will be created and your data stored. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / US East (N. Virginia) \ (us-east-1) 2 / Europe (Frankfurt) \ (eu-central-1) 3 / Asia Pacific (Singapore) \ (ap-southeast-1) 4 / Middle East (Bahrain) \ (me-south-1) 5 / South America (São Paulo) \ (sa-east-1) region> 1

Option endpoint. Endpoint for Petabox S3 Object Storage. Specify the endpoint from the same region. Choose a number from below, or type in your own value. 1 / US East (N. Virginia) \ (s3.petabox.io) 2 / US East (N. Virginia) \ (s3.us-east-1.petabox.io) 3 / Europe (Frankfurt) \ (s3.eu-central-1.petabox.io) 4 / Asia Pacific (Singapore) \ (s3.ap-southeast-1.petabox.io) 5 / Middle East (Bahrain) \ (s3.me-south-1.petabox.io) 6 / South America (São Paulo) \ (s3.sa-east-1.petabox.io) endpoint> 1

Option acl. Canned ACL used when creating buckets and storing or copying objects. This ACL is used for creating objects and if bucket_acl isn't set, for creating buckets too. For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl Note that this ACL is applied when server-side copying objects as S3 doesn't copy the ACL from the source but rather writes a fresh one. If the acl is an empty string then no X-Amz-Acl: header is added and the default (private) will be used. Choose a number from below, or type in your own value. Press Enter to leave empty. / Owner gets FULL_CONTROL. 1 | No one else has access rights (default). \ (private) / Owner gets FULL_CONTROL. 2 | The AllUsers group gets READ access. \ (public-read) / Owner gets FULL_CONTROL. 3 | The AllUsers group gets READ and WRITE access.

Granting this on a bucket is generally not recommended.

\ (public-read-write) / Owner gets FULL_CONTROL. 4 | The AuthenticatedUsers group gets READ access. \ (authenticated-read) / Object owner gets FULL_CONTROL. 5 | Bucket owner gets READ access.

If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.

Edit advanced config? y) Yes n) No (default) y/n> No

Configuration complete. Options:

type: s3
provider: Petabox
access_key_id: YOUR_ACCESS_KEY_ID
secret_access_key: YOUR_SECRET_ACCESS_KEY
region: us-east-1
endpoint: s3.petabox.io Keep this "My Petabox Storage" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


And when you're all done, this is what your config file is gonna look like. 🦋

[My Petabox Storage] type = s3 provider = Petabox access_key_id = YOUR_ACCESS_KEY_ID secret_access_key = YOUR_SECRET_ACCESS_KEY region = us-east-1 endpoint = s3.petabox.io


### 👑 Storj

Storj is a decentralized cloud storage sitch — you can hit it through its own native protocol, or through an S3 compatible gateway. Two doors, same vibe. 🚪✨

The S3 compatible gateway gets set up with `rclone config`, using a type of `s3` and a provider name of <pink>**Storj**</pink>. Here's a lil example run of the configurator, bestie:

Type of storage to configure. Storage> s3 Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own boolean value (true or false). Press Enter for the default (false). 1 / Enter AWS credentials in the next step. \ (false) 2 / Get AWS credentials from the environment (env vars or IAM). \ (true) env_auth> 1 Option access_key_id. AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. access_key_id> XXXX (as shown when creating the access grant) Option secret_access_key. AWS Secret Access Key (password). Leave blank for anonymous access or runtime credentials. Enter a value. Press Enter to leave empty. secret_access_key> XXXX (as shown when creating the access grant) Option endpoint. Endpoint of the Shared Gateway. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / EU1 Shared Gateway \ (gateway.eu1.storjshare.io) 2 / US1 Shared Gateway \ (gateway.us1.storjshare.io) 3 / Asia-Pacific Shared Gateway \ (gateway.ap1.storjshare.io) endpoint> 1 (as shown when creating the access grant) Edit advanced config? y) Yes n) No (default) y/n> n


> Heads up bestie 🙈 the s3 credentials get generated when you create an access grant. So like, make the grant first, then come back and paste the goods in.

#### 🫶 Backend quirks

- `--chunk-size` is forced to be `64 MiB` or greater. Just so you know, that means it'll eat more memory than the default of `5 MiB`. She's thicc. 💅

- Server side copy is **disabled**, because it isn't currently supported in the gateway. Not a choice, it's just the law. 😭

- `GetTier` and `SetTier` are not supported. Periodt.

#### 💀 Backend bugs

Okay so, due to issue <red>#39</red>, uploading multipart files via the S3 gateway makes them **lose their metadata**. For rclone's purposes this means the modification time isn't stored, and neither is any MD5SUM (if one is even available from the source). It's giving amnesia, honestly.

This has the following consequences:

- Using `rclone rcat` will **fail** as the medatada doesn't match after upload

- Uploading files with `rclone mount` will **fail** for the same reason

  - You can work around this by using `--vfs-cache-mode writes` or `--vfs-cache-mode full`, or by setting `--s3-upload-cutoff large`

- Files uploaded via a multipart upload **won't have their modtimes**

  - Which means `rclone sync` will likely keep trying to upload files bigger than `--s3-upload-cutoff`. She's stubborn like that. 😤

  - You can work around it with `--checksum` or `--size-only`, or by setting `--s3-upload-cutoff large`

  - But lowkey the maximum value for `--s3-upload-cutoff` is `5GiB` though, so that's your ceiling 🧚

<pink>okay so</pink> one general purpose workaround you can just ✨do✨ is set `--s3-upload-cutoff 5G`. That tells rclone to upload files smaller than 5GiB as single parts. Bestie, you can totally set this in the config file too, like `upload_cutoff = 5G`, or just go configure it in the advanced settings. And if you're regularly transferring files larger than 5G? Then using `--checksum` or `--size-only` in `rclone sync` is the recommended workaround. That's the move. 💅

### 🌈 Comparison with the native protocol 🌈

Use the native protocol when you want to take advantage of client-side encryption AND get the best possible download performance. Uploads get erasure-coded locally, which means a `1gb` upload will result in `2.68gb` of data being uploaded to storage nodes across the network. Yeah. That's a lot. 😭

Use this backend and the S3 compatible Hosted Gateway when you wanna increase upload performance and reduce the load on your systems and network. Uploads get encrypted and erasure-coded server-side, so a `1GB` upload results in only `1GB` of data being uploaded to storage nodes across the network. <mint>way better</mint> 🫶

For a more detailed comparison please check the documentation of the storj backend.

### Memory usage {memory} 🧠

The most common cause of rclone using lots of memory is a single directory with millions of files in it. Despite s3 not really having the concept of directories, rclone does the sync on a directory by directory basis to be compatible with normal filing systems. So like, it's doing the right thing, it's just <yellow>hungry</yellow>.

Rclone loads each directory into memory as rclone objects. Each rclone object takes `0.5k`-`1k` of memory, so approximately `1GB` per 1,000,000 files, and the sync for that directory does not begin until it is entirely loaded in memory. So the sync can take a <hotpink>long</hotpink> time to start for large directories. Not me waiting forever for the upload to even *begin*. 🙈

To sync a directory with 100,000,000 files in you would need approximately 100 GB of memory. At some point the amount of memory becomes difficult to provide so there is a workaround for this which involves a bit of scripting.

At some point rclone will gain a sync mode which is effectively this workaround but built in to rclone.

### Limitations 💀

`rclone about` is **not** supported by the S3 backend. Backends without this capability cannot determine free space for an `rclone mount` or use policy `mfs` (most free space) as a member of an `rclone union` remote.

See List of backends that do not support rclone about and rclone about.

---

## 🦋 Synology C2 Object Storage 🦋

Synology C2 Object Storage provides a secure, S3-compatible, and cost-effective cloud storage solution without API request, download fees, and deletion penalty. <green>no fees, no penalty, we love to see it</green> ✨

The S3 compatible gateway is configured using `rclone config` with a type of `s3` and with a provider name of `Synology`. Here is an example run of the configurator. 👑

First run:

rclone config


This will guide you through an interactive setup process.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config

n/s/q> n

Enter name for new remote.1 name> syno

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

XX / Amazon S3 Compliant Storage Providers including AWS, ... \ "s3"

Storage> s3

Choose your S3 provider. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 24 / Synology C2 Object Storage \ (Synology)

provider> Synology

env_auth> 1

AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default ("").

access_key_id> accesskeyid

AWS Secret Access Key (password) Leave blank for anonymous access or runtime credentials. Enter a string value. Press Enter for the default ("").

secret_access_key> secretaccesskey

Region where your data stored. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Europe Region 1 \ (eu-001) 2 / Europe Region 2 \ (eu-002) 3 / US Region 1 \ (us-001) 4 / US Region 2 \ (us-002) 5 / Asia (Taiwan) \ (tw-001)

region > 1

Option endpoint. Endpoint for Synology C2 Object Storage API. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / EU Endpoint 1 \ (eu-001.s3.synologyc2.net) 2 / US Endpoint 1 \ (us-001.s3.synologyc2.net) 3 / TW Endpoint 1 \ (tw-001.s3.synologyc2.net)

endpoint> 1

Option location_constraint. Location constraint - must be set to match the Region. Leave blank if not sure. Used when creating buckets only. Enter a value. Press Enter to leave empty. location_constraint>

Edit advanced config? (y/n) y) Yes n) No y/n> y

Option no_check_bucket. If set, don't attempt to check the bucket exists or create it. This can be useful when trying to minimise the number of transactions rclone does if you know the bucket exists already. It can also be needed if the user you are using does not have bucket creation permissions. Before v1.52.0 this would have passed silently due to a bug. Enter a boolean value (true or false). Press Enter for the default (true).

no_check_bucket> true

Configuration complete. Options:

type: s3
provider: Synology
region: eu-001
endpoint: eu-001.s3.synologyc2.net
no_check_bucket: true Keep this "syno" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote

y/e/d> y


---

# 🎀 Backblaze B2 🎀

B2 is Backblaze's cloud storage system.

Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`.

## Configuration 🛠️

Here is an example of making a b2 configuration. First run

rclone config


This will guide you through an interactive setup process. To authenticate you will either need your Account ID (a short hex number) and Master Application Key (a long hex number) OR an Application Key, which is the recommended method. See below for further details on generating and using an Application Key. 🔑

No remotes found, make a new one? n) New remote q) Quit config n/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Backblaze B2 \ "b2" [snip] Storage> b2 Account ID or Application Key ID account> 123456789abc Application Key key> 0123456789abcdef0123456789abcdef0123456789 Endpoint for the service - leave blank normally. endpoint> Remote config Configuration complete. Options:

type: b2
account: 123456789abc
key: 0123456789abcdef0123456789abcdef0123456789
endpoint: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


This remote is called `remote` and can now be used like this 👇

See all buckets:

rclone lsd remote:


Create a new bucket:

rclone mkdir remote:bucket


List the contents of a bucket:

rclone ls remote:bucket


Sync `/home/local/directory` to the remote bucket, deleting any excess files in the bucket.

rclone sync --interactive /home/local/directory remote:bucket


## Application Keys 🗝️

B2 supports multiple Application Keys for different access permission to B2 Buckets.

You can use these with rclone too; you will need to use rclone version `1.43` or later.

Follow Backblaze's docs to create an Application Key with the required permission and add the `applicationKeyId` as the `account` and the Application Key itself as the `key`.

> Note that you **must** put the `applicationKeyId` as the `account` – you can't use the master Account ID. If you try then B2 will return <red>401 errors</red>. 💀

## --fast-list ⚡

This remote supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs for more details.

## Modification times 🕰️

The modification time is stored as metadata on the object as `X-Bz-Info-src_last_modified_millis` as milliseconds since `1970-01-01` in the Backblaze standard. Other tools should be able to use this as a modified time.

Modified times are used in syncing and are fully supported. Note that if a modification time needs to be updated on an object then it will create a **new version** of the object.

## Restricted filename characters 🚫

In addition to the default restricted characters set the following characters are also replaced:

- Character `\` — value `0x5C` — replacement `＼`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings.

Note that in `2020-05` Backblaze started allowing `\` characters in file names. Rclone hasn't changed its encoding as this could cause syncs to re-transfer files. If you want rclone not to replace `\` then see the `--b2-encoding` flag below and remove the `BackSlash` from the string. This can be set in the config.

## SHA1 checksums 🔍

The SHA1 checksums of the files are checked on upload and download and will be used in the syncing process.

Large files (bigger than the limit in `--b2-upload-cutoff`) which are uploaded in chunks will store their SHA1 on the object as `X-Bz-Info-large_file_sha1` as recommended by Backblaze.

For a large file to be uploaded with an SHA1 checksum, the source needs to support SHA1 checksums. The local disk supports SHA1 checksums so large file transfers from local disk will have an SHA1. See the overview for exactly which remotes support SHA1.

Sources which don't support SHA1, in particular crypt will upload large files without SHA1 checksums. This may be fixed in the future (see #1767).

Files sizes below `--b2-upload-cutoff` will always have an SHA1 regardless of the source.

## ✨ Transfers ✨

Backblaze recommends that you do <hotpink>lots</hotpink> of transfers simultaneously for maximum speed. In tests from my SSD equipped laptop the optimum setting is about `--transfers 32` though higher numbers may be used for a slight speed improvement. The optimum number for you may vary depending on your hardware, how big the files are, how much you want to load your computer, etc. The default of `--transfers 4` is <red>definitely too low</red> for Backblaze B2 though.

> Heads up bestie — uploading big files (bigger than 200 MiB by default) will use a 96 MiB RAM buffer by default. There can be at most `--transfers` of these in use at any moment, so this sets the upper limit on the memory used. 💾

## 🌸 Versions 🌸

The default setting of B2 is to keep old versions of files. This means when rclone uploads a new version of a file it creates a new version of it. Likewise when you delete a file, the old version will be marked hidden and still be available.

Whether B2 keeps old versions of files or not can be adjusted on a per bucket basis using the "Lifecycle settings" on the B2 control panel or when creating the bucket using the `--b2-lifecycle` flag or after creation using the `rclone backend lifecycle` command.

You may opt in to a "hard delete" of files with the `--b2-hard-delete` flag which permanently removes files on deletion instead of hiding them.

Old versions of files, where available, are visible using the `--b2-versions` flag.

It is also possible to view a bucket as it was at a certain point in time, using the `--b2-version-at` flag. This will show the file versions as they were at that time, showing files that have been deleted afterwards, and hiding files that were created since. <purple>time travel but make it cloud storage ✨</purple>

If you wish to remove all the old versions, and unfinished large file uploads, then you can use the `rclone cleanup remote:bucket` command which will delete all the old versions of files, leaving the current ones intact. You can also supply a path and only old versions under that path will be deleted, e.g. `rclone cleanup remote:bucket/path/to/stuff`.

Note that `cleanup` will remove partially uploaded files from the bucket if they are more than a day old. If you want more control over the expiry date then run `rclone backend cleanup b2:bucket -o max-age=1h` to remove all unfinished large file uploads older than one hour, leaving old versions intact.

If you wish to remove all the old versions, leaving current files and unfinished large files intact, then you can use the `rclone backend cleanup-hidden remote:bucket` command. You can also supply a path and only old versions under that path will be deleted, e.g. `rclone backend cleanup-hidden remote:bucket/path/to/stuff`.

When you purge a bucket, the current and the old versions will be deleted then the bucket will be deleted.

However `delete` will cause the current versions of the files to become hidden old versions.

Here is a session showing the listing and retrieval of an old version followed by a cleanup of the old versions.

Show current version and all the versions with `--b2-versions` flag.

$ rclone -q ls b2:cleanup-test 9 one.txt

$ rclone -q --b2-versions ls b2:cleanup-test 9 one.txt 8 one-v2016-07-04-141032-000.txt 16 one-v2016-07-04-141003-000.txt 15 one-v2016-07-02-155621-000.txt


Retrieve an old version

$ rclone -q --b2-versions copy b2:cleanup-test/one-v2016-07-04-141003-000.txt /tmp

$ ls -l /tmp/one-v2016-07-04-141003-000.txt -rw-rw-r-- 1 ncw ncw 16 Jul 2 17:46 /tmp/one-v2016-07-04-141003-000.txt


Clean up all the old versions and show that they've gone.

$ rclone -q cleanup b2:cleanup-test

$ rclone -q ls b2:cleanup-test 9 one.txt

$ rclone -q --b2-versions ls b2:cleanup-test 9 one.txt


## 🦋 Versions naming caveat 🦋

When using `--b2-versions` flag rclone is relying on the file name to work out whether the objects are versions or not. Versions' names are created by inserting timestamp between file name and its extension.

9 file.txt 8 file-v2023-07-17-161032-000.txt 16 file-v2023-06-15-141003-000.txt


> Okay so lowkey important — if there are real files present with the same names as versions, then behaviour of `--b2-versions` can be **unpredictable**. 💀

## 💜 Data usage 💜

It is useful to know how many requests are sent to the server in different scenarios.

All copy commands send the following 4 requests:

/b2api/v1/b2_authorize_account /b2api/v1/b2_create_bucket /b2api/v1/b2_list_buckets /b2api/v1/b2_list_file_names


The `b2_list_file_names` request will be sent once for every 1k files in the remote path, providing the checksum and modification time of the listed files. As of version 1.33 issue #818 causes extra requests to be sent when using B2 with Crypt. When a copy operation does not require any files to be uploaded, no more requests will be sent.

Uploading files that do not require chunking, will send 2 requests per file upload:

/b2api/v1/b2_get_upload_url /b2api/v1/b2_upload_file/


Uploading files requiring chunking, will send 2 requests (one each to start and finish the upload) and another 2 requests for each chunk:

/b2api/v1/b2_start_large_file /b2api/v1/b2_get_upload_part_url /b2api/v1/b2_upload_part/ /b2api/v1/b2_finish_large_file


## 🌈 Versions 🌈

Versions can be viewed with the `--b2-versions` flag. When it is set rclone will show and act on older versions of files. For example

Listing without `--b2-versions`

$ rclone -q ls b2:cleanup-test 9 one.txt


And with

$ rclone -q --b2-versions ls b2:cleanup-test 9 one.txt 8 one-v2016-07-04-141032-000.txt 16 one-v2016-07-04-141003-000.txt 15 one-v2016-07-02-155621-000.txt


Showing that the current version is unchanged but older versions can be seen. These have the UTC date that they were uploaded to the server to the nearest millisecond appended to them.

> Note that when using `--b2-versions` **no file write operations are permitted**, so you can't upload files or delete them. 🚫

## 🎀 B2 and rclone link 🎀

Rclone supports generating file share links for private B2 buckets. They can either be for a file for example:

./rclone link B2:bucket/path/to/file.txt https://f002.backblazeb2.com/file/bucket/path/to/file.txt?Authorization=xxxxxxxx


or if run on a directory you will get:

./rclone link B2:bucket/path https://f002.backblazeb2.com/file/bucket/path?Authorization=xxxxxxxx


you can then use the authorization token (the part of the url from the `?Authorization=` on) on any file path under that directory. For example:

https://f002.backblazeb2.com/file/bucket/path/to/file1?Authorization=xxxxxxxx https://f002.backblazeb2.com/file/bucket/path/file2?Authorization=xxxxxxxx https://f002.backblazeb2.com/file/bucket/path/folder/file3?Authorization=xxxxxxxx


## ⭐ Standard options ⭐

Here are the Standard options specific to b2 (Backblaze B2).

### 💖 `--b2-account` 💖

Account ID or Application Key ID.

Properties:

- Config: account

- Env Var: `RCLONE_B2_ACCOUNT`

- Type: string

- Required: true

### 💖 `--b2-key` 💖

Application Key.

Properties:

- Config: key

- Env Var: `RCLONE_B2_KEY`

- Type: string

- Required: true

### 💖 `--b2-hard-delete` 💖

Permanently delete files on remote removal, otherwise hide files.

Properties:

- Config: hard_delete

- Env Var: `RCLONE_B2_HARD_DELETE`

- Type: bool

- Default: false

## 🔥 Advanced options 🔥

Here are the Advanced options specific to b2 (Backblaze B2).

### ✨ `--b2-endpoint` ✨

Endpoint for the service.

Leave blank normally.

Properties:

- Config: endpoint

- Env Var: `RCLONE_B2_ENDPOINT`

- Type: string

- Required: false

### ✨ `--b2-test-mode` ✨

A flag string for X-Bz-Test-Mode header for debugging.

This is for debugging purposes only. Setting it to one of the strings below will cause b2 to return specific errors:

- "fail_some_uploads"

- "expire_some_account_authorization_tokens"

- "force_cap_exceeded"

These will be set in the "X-Bz-Test-Mode" header which is documented in the b2 integrations checklist.

Properties:

- Config: test_mode

- Env Var: `RCLONE_B2_TEST_MODE`

- Type: string

- Required: false

### ✨ `--b2-versions` ✨

Include old versions in directory listings.

Note that when using this no file write operations are permitted, so you can't upload files or delete them.

Properties:

- Config: versions

- Env Var: `RCLONE_B2_VERSIONS`

- Type: bool

- Default: false

### ✨ `--b2-version-at` ✨

Show file versions as they were at the specified time.

Note that when using this no file write operations are permitted, so you can't upload files or delete them.

Properties:

- Config: version_at

- Env Var: `RCLONE_B2_VERSION_AT`

- Type: Time

- Default: off

### ✨ `--b2-upload-cutoff` ✨

Cutoff for switching to chunked upload.

Files above this size will be uploaded in chunks of `--b2-chunk-size`.

This value should be set no larger than 4.657 GiB (== 5 GB).

Properties:

- Config: upload_cutoff

- Env Var: `RCLONE_B2_UPLOAD_CUTOFF`

- Type: SizeSuffix

- Default: 200Mi

### ✨ `--b2-copy-cutoff` ✨

Cutoff for switching to multipart copy.

Any files larger than this that need to be server-side copied will be copied in chunks of this size.

The minimum is 0 and the maximum is 4.6 GiB.

Properties:

- Config: copy_cutoff

- Env Var: `RCLONE_B2_COPY_CUTOFF`

- Type: SizeSuffix

- Default: 4Gi

### ✨ `--b2-chunk-size` ✨

Upload chunk size.

When uploading large files, chunk the file into this size.

Must fit in memory. These chunks are buffered in memory and there might a maximum of `--transfers` chunks in progress at once.

5,000,000 Bytes is the minimum size.

Properties:

- Config: chunk_size

- Env Var: `RCLONE_B2_CHUNK_SIZE`

- Type: SizeSuffix

- Default: 96Mi

- **`--b2-upload-concurrency`** — the concurrency for multipart uploads, bestie 💅

  This is literally the number of chunks of the same file that get uploaded at the same time.

  Ngl heads up: those chunks live in memory, and there may be up to `--transfers` * `--b2-upload-concurrency` chunks sitting in memory all at once. So don't go feral with it.

  Properties:

  - Config: `upload_concurrency`
  - Env Var: `RCLONE_B2_UPLOAD_CONCURRENCY`
  - Type: `int`
  - Default: `4`

- **`--b2-disable-checksum`** — turns checksums off for big files (bigger than the upload cutoff) 🫶

  Normally rclone will calculate the SHA1 checksum of the input before uploading it so it can add it to metadata on the object. That's iconic for data integrity checking, but it can cause long delays for large files to start uploading. So if you're impatient, this is your girl.

  Properties:

  - Config: `disable_checksum`
  - Env Var: `RCLONE_B2_DISABLE_CHECKSUM`
  - Type: `bool`
  - Default: `false`

- **`--b2-download-url`** — custom endpoint for downloads ✨

  This is usually set to a Cloudflare CDN URL because Backblaze offers free egress for data downloaded through the Cloudflare network. Rclone works with private buckets by sending an `Authorization` header. If the custom endpoint rewrites the requests for authentication, e.g., in Cloudflare Workers, this header needs to be handled properly. Leave it blank if you want to use the endpoint provided by Backblaze.

  The URL provided here SHOULD have the protocol and SHOULD NOT have a trailing slash or specify the `/file/bucket` subpath, because rclone will request files with `{download_url}/file/{bucket_name}/{path}`.

  Example: `https://mysubdomain.mydomain.tld` (no trailing `/`, `file` or `bucket`)

  Properties:

  - Config: `download_url`
  - Env Var: `RCLONE_B2_DOWNLOAD_URL`
  - Type: `string`
  - Required: `false`

- **`--b2-download-auth-duration`** — how long till the public link authorization token expires, in s or with a suffix `ms|s|m|h|d` ⏳

  This gets used together with `rclone link` for making files accessible to the public, and it sets the duration before the download authorization token will expire.

  The minimum value is 1 second. The maximum value is one week. No infinite slay here, sorry.

  Properties:

  - Config: `download_auth_duration`
  - Env Var: `RCLONE_B2_DOWNLOAD_AUTH_DURATION`
  - Type: `Duration`
  - Default: `1w`

- **`--b2-memory-pool-flush-time`** — how often internal memory buffer pools will be flushed. (no longer used) 💀

  Properties:

  - Config: `memory_pool_flush_time`
  - Env Var: `RCLONE_B2_MEMORY_POOL_FLUSH_TIME`
  - Type: `Duration`
  - Default: `1m0s`

- **`--b2-memory-pool-use-mmap`** — whether to use mmap buffers in the internal memory pool. (no longer used) 💀

  Properties:

  - Config: `memory_pool_use_mmap`
  - Env Var: `RCLONE_B2_MEMORY_POOL_USE_MMAP`
  - Type: `bool`
  - Default: `false`

- **`--b2-lifecycle`** — set how many days deleted files should be kept when creating a bucket 🗓️

  On bucket creation, this parameter is used to create a lifecycle rule for the entire bucket.

  If lifecycle is `0` (the default) it does not create a lifecycle rule, so the default B2 behaviour applies. Which is to create versions of files on delete and overwrite, and to keep them indefinitely. Forever. Immortal. 👑

  If lifecycle is >0 then it creates a single rule setting the number of days before a file that is deleted or overwritten is deleted permanently. This is known as `daysFromHidingToDeleting` in the b2 docs.

  The minimum value for this parameter is 1 day.

  You can also enable `hard_delete` in the config also which will mean deletions won't cause versions but overwrites will still cause versions to be made.

  See: `rclone backend lifecycle` for setting lifecycles after bucket creation.

  Properties:

  - Config: `lifecycle`
  - Env Var: `RCLONE_B2_LIFECYCLE`
  - Type: `int`
  - Default: `0`

- **`--b2-encoding`** — the encoding for the backend 🎀

  See the encoding section in the overview for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_B2_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

- **`--b2-description`** — description of the remote 💖

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_B2_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

### 🌈 Backend commands 🌈

Here are the commands specific to the b2 backend, bestie.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

---

### ✨ lifecycle ✨

Read or set the lifecycle for a bucket 🦋

rclone backend lifecycle remote: [options] [<arguments>+]


This command can be used to read or set the lifecycle for a bucket. Yes, read AND set. Multitasking queen.

Usage Examples:

To show the current lifecycle rules:

rclone backend lifecycle b2:bucket


This will dump something like this showing the lifecycle rules.

[ { "daysFromHidingToDeleting": 1, "daysFromUploadingToHiding": null, "daysFromStartingToCancelingUnfinishedLargeFiles": null, "fileNamePrefix": "" } ]


If there are no lifecycle rules (the default) then it will just return `[]`. Empty. A void. 🕳️

To reset the current lifecycle rules:

rclone backend lifecycle b2:bucket -o daysFromHidingToDeleting=30 rclone backend lifecycle b2:bucket -o daysFromUploadingToHiding=5 -o daysFromHidingToDeleting=1


This will run and then print the new lifecycle rules as above.

Rclone only lets you set lifecycles for the whole bucket with the `fileNamePrefix = ""`.

You can't disable versioning with B2. The best you can do is to set the `daysFromHidingToDeleting` to 1 day. You can enable `hard_delete` in the config also which will mean deletions won't cause versions but overwrites will still cause versions to be made.

rclone backend lifecycle b2:bucket -o daysFromHidingToDeleting=1


See: https://www.backblaze.com/docs/cloud-storage-lifecycle-rules

Options:

- `daysFromHidingToDeleting`: After a file has been hidden for this many days it is deleted. `0` is off.
- `daysFromStartingToCancelingUnfinishedLargeFiles`: Cancels any unfinished large file versions after this many days
- `daysFromUploadingToHiding`: This many days after uploading a file is hidden

### 🧹 cleanup 🧹

Remove unfinished large file uploads ✂️

rclone backend cleanup remote: [options] [<arguments>+]


This command removes unfinished large file uploads of age greater than `max-age`, which defaults to 24 hours.

Note that you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do. Highly recommend, no cap.

rclone backend cleanup b2:bucket/path/to/object rclone backend cleanup -o max-age=7w b2:bucket/path/to/object


Durations are parsed as per the rest of rclone, `2h`, `7d`, `7w` etc.

Options:

- `max-age`: Max age of upload to delete

### 🙈 cleanup-hidden 🙈

Remove old versions of files 🌸

rclone backend cleanup-hidden remote: [options] [<arguments>+]


This command removes any old hidden versions of files.

Note that you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do.

rclone backend cleanup-hidden b2:bucket/path/to/dir


---

### 💀 Limitations 💀

`rclone about` is not supported by the B2 backend. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote.

See List of backends that do not support rclone about and rclone about

---

## 🎀 Box 🎀

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

The initial setup for Box involves getting a token from Box which you can do either in your browser, or with a `config.json` downloaded from Box to use JWT authentication. `rclone config` walks you through it. She's got you 🫶

---

### 🌸 Configuration 🌸

Here is an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Box \ "box" [snip] Storage> box Box App Client Id - leave blank normally. client_id> Box App Client Secret - leave blank normally. client_secret> Box App config.json location Leave blank normally. Enter a string value. Press Enter for the default (""). box_config_file> Box App Primary Access Token Leave blank normally. Enter a string value. Press Enter for the default (""). access_token>

Enter a string value. Press Enter for the default ("user"). Choose a number from below, or type in your own value 1 / Rclone should act on behalf of a user \ "user" 2 / Rclone should act on behalf of a service account \ "enterprise" box_sub_type> 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?state=XXXXXXXXXXXXXXXXXXXXXX Log in and authorize rclone for access Waiting for code... Got code Configuration complete. Options:

type: box
client_id:
client_secret:
token: {"access_token":"XXX","token_type":"bearer","refresh_token":"XXX","expiry":"XXX"} 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 for how to set it up on a machine with no Internet browser available.

Note that rclone runs a webserver on your local machine to collect the token as returned from Box. 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 may require you to unblock it temporarily if you are running a host firewall. 💅

Once configured you can then use rclone like this,

okay bestie, your Box remote is set up so let's actually *use it* 💅 here's the starter pack, copy-paste away:

List directories in top level of your Box

rclone lsd remote:


List all the files in your Box

rclone ls remote:


To copy a local directory to an Box directory called backup

rclone copy /home/source remote:backup


---

## 🏢 Using rclone with an Enterprise account with SSO 🔐

If you have an <pink>"Enterprise"</pink> account type with Box with single sign on (SSO), bestie, you **need** to create a password before rclone can talk to Box. No password, no access. 🚫

Where does that happen? On your Enterprise Box account: head to <pink>Settings</pink>, the <pink>"Account"</pink> Tab, and then set the password in the <pink>"Authentication"</pink> field. ✨

Once you have done this, you can setup your Enterprise Box account using the same procedure detailed above in the, using the password you have just set. 🫶

## 🚨 Invalid refresh token

According to the box docs:

Each refresh_token is valid for one use in 60 days.


Read that again bestie — **one** use, 60 days, that's it. So if you:

- Don't use the box remote for 60 days 😴

- Copy the config file with a box refresh token in and use it in two places 👯‍♀️

- Get an error on a token refresh 💀

then rclone will return an error which includes the text `Invalid refresh token`.

To fix it you'll need to use oauth2 again to update the refresh token. Use the methods in the remote setup docs, and keep this in mind: <red>if you use the copy the config file method, you should not use that remote on the computer you did the authentication on.</red> 🙅‍♀️

Here is how to do it.

$ rclone config Current remotes:

Name Type ==== ==== remote box

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> e Choose a number from below, or type in an existing value 1 > remote remote> remote Configuration complete. Options:

type: box
token: {"access_token":"XXX","token_type":"bearer","refresh_token":"XXX","expiry":"2017-07-08T23:40:08.059167677+01:00"} Keep this "remote" remote? Edit remote Value "client_id" = "" Edit? (y/n)> y) Yes n) No y/n> n Value "client_secret" = "" Edit? (y/n)> y) Yes n) No y/n> n Remote config Already have a token - refresh? y) Yes n) No y/n> y 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 Configuration complete. Options:
type: box
token: {"access_token":"YYY","token_type":"bearer","refresh_token":"YYY","expiry":"2017-07-23T12:22:29.259137901+01:00"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


## ⏰ Modification times and hashes

Box lets modification times be set on objects accurate to **1 second**. rclone uses those to detect whether objects need syncing or not. ✨

Box supports **SHA1** type hashes, so you can use the `--checksum` flag. 🎯

## ✂️ Restricted filename characters

In addition to the default restricted characters set the following characters are also replaced:

- Character `\` — Value `0x5C` — Replacement `＼`

File names can also not end with the following characters. These only get replaced if they are the last character in the name:

- Character SP — Value `0x20` — Replacement `␠`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 💀

## 🚚 Transfers

For files above 50 MiB rclone will use a chunked transfer. Rclone will upload up to `--transfers` chunks at the same time (shared among all the multipart uploads). Chunks are buffered in memory and are normally 8 MiB, so increasing `--transfers` will increase memory use. 👀

## 🗑️ Deleting files

Depending on the enterprise settings for your user, the item will either be actually deleted from Box or moved to the trash.

Emptying the trash is supported via the rclone however cleanup command however this deletes every trashed file and folder individually so it may take a very long time. Emptying the trash via the WebUI does not have this limitation so it is advised to empty the trash via the WebUI. 🙏

## 📁 Root folder ID

You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone considers to be the root of your Box drive.

Normally you will leave this blank and rclone will determine the correct root to use itself.

However you can set this to restrict rclone to a specific folder hierarchy. 🗂️

In order to do this you will have to find the Folder ID of the directory you wish rclone to display. This will be the last segment of the URL when you open the relevant folder in the Box web interface.

So if the folder you want rclone to use has a URL which looks like `https://app.box.com/folder/11xxxxxxxxx8` in the browser, then you use `11xxxxxxxxx8` as the `root_folder_id` in the config. iykyk 💅

## ✨ Standard options

Here are the Standard options specific to box (Box).

- **`--box-client-id`** — OAuth Client Id. Leave blank normally.
  - Config: `client_id`
  - Env Var: `RCLONE_BOX_CLIENT_ID`
  - Type: `string`
  - Required: `false`

- **`--box-client-secret`** — OAuth Client Secret. Leave blank normally.
  - Config: `client_secret`
  - Env Var: `RCLONE_BOX_CLIENT_SECRET`
  - Type: `string`
  - Required: `false`

- **`--box-box-config-file`** — Box App config.json location. Leave blank normally.
  - Leading `~` will be expanded in the file name as will environment variables such as `${RCLONE_CONFIG_DIR}`.
  - Config: `box_config_file`
  - Env Var: `RCLONE_BOX_BOX_CONFIG_FILE`
  - Type: `string`
  - Required: `false`

- **`--box-access-token`** — Box App Primary Access Token. Leave blank normally.
  - Config: `access_token`
  - Env Var: `RCLONE_BOX_ACCESS_TOKEN`
  - Type: `string`
  - Required: `false`

- **`--box-box-sub-type`**
  - Config: `box_sub_type`
  - Env Var: `RCLONE_BOX_BOX_SUB_TYPE`
  - Type: `string`
  - Default: `"user"`
  - Examples:
    - `"user"`
      - Rclone should act on behalf of a user.
    - `"enterprise"`
      - Rclone should act on behalf of a service account.

## 🔥 Advanced options

Here are the Advanced options specific to box (Box).

- **`--box-token`** — OAuth Access Token as a JSON blob.
  - Config: `token`
  - Env Var: `RCLONE_BOX_TOKEN`
  - Type: `string`
  - Required: `false`

- **`--box-auth-url`** — Auth server URL. Leave blank to use the provider defaults.
  - Config: `auth_url`
  - Env Var: `RCLONE_BOX_AUTH_URL`
  - Type: `string`
  - Required: `false`

- **`--box-token-url`** — Token server url. Leave blank to use the provider defaults.
  - Config: `token_url`
  - Env Var: `RCLONE_BOX_TOKEN_URL`
  - Type: `string`
  - Required: `false`

- **`--box-client-credentials`** — Use client credentials OAuth flow. This will use the OAUTH2 client Credentials Flow as described in RFC 6749.
  - Config: `client_credentials`
  - Env Var: `RCLONE_BOX_CLIENT_CREDENTIALS`
  - Type: `bool`
  - Default: `false`

- **`--box-root-folder-id`** — Fill in for rclone to use a non root folder as its starting point.
  - Config: `root_folder_id`
  - Env Var: `RCLONE_BOX_ROOT_FOLDER_ID`
  - Type: `string`
  - Default: `"0"`

- **`--box-upload-cutoff`** — Cutoff for switching to multipart upload (>= 50 MiB).
  - Config: `upload_cutoff`
  - Env Var: `RCLONE_BOX_UPLOAD_CUTOFF`
  - Type: `SizeSuffix`
  - Default: `50Mi`

- **`--box-commit-retries`** — Max number of times to try committing a multipart file.
  - Config: `commit_retries`
  - Env Var: `RCLONE_BOX_COMMIT_RETRIES`
  - Type: `int`
  - Default: `100`

- **`--box-list-chunk`** — Size of listing chunk 1-1000.
  - Config: `list_chunk`
  - Env Var: `RCLONE_BOX_LIST_CHUNK`
  - Type: `int`
  - Default: `1000`

- **`--box-owned-by`** — Only show items owned by the login (email address) passed in.
  - Config: `owned_by`
  - Env Var: `RCLONE_BOX_OWNED_BY`
  - Type: `string`
  - Required: `false`

- **`--box-impersonate`** — Impersonate this user ID when using a service account.
  - Setting this flag allows rclone, when using a JWT service account, to act on behalf of another user by setting the as-user header.
  - The user ID is the Box identifier for a user. User IDs can found for any user via the `GET /users` endpoint, which is only available to admins, or by calling the `GET /users/me` endpoint with an authenticated user session.
  - See: `https://developer.box.com/guides/authentication/jwt/as-user/`
  - Config: `impersonate`
  - Env Var: `RCLONE_BOX_IMPERSONATE`
  - Type: `string`
  - Required: `false`

- **`--box-encoding`** — The encoding for the backend. See the encoding section in the overview for more info.
  - Config: `encoding`
  - Env Var: `RCLONE_BOX_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,Del,Ctl,RightSpace,InvalidUtf8,Dot`

- **`--box-description`** — Description of the remote.
  - Config: `description`
  - Env Var: `RCLONE_BOX_DESCRIPTION`
  - Type: `string`
  - Required: `false`

## 🚧 Limitations

Okay so, the fine print bestie, read it before you get mad at rclone:

- Box is case insensitive so you can't have a file called <pink>"Hello.doc"</pink> and one called <pink>"hello.doc"</pink>. 😭

- Box file names can't have the `\` character in. rclone maps this to and from an identical looking unicode equivalent `＼` (U+FF3C Fullwidth Reverse Solidus).

- Box only supports filenames up to **255** characters in length.

- Box has API rate limits that sometimes reduce the speed of rclone. 🐌

---

...

<hotpink>okay so</hotpink> straight up, `rclone about` is **not supported by the Box backend**. Ngl this matters, bestie — backends without this capability literally cannot figure out free space for an `rclone mount`, and you also can't use policy `mfs` (most free space) as a member of an `rclone union` remote.

See *List of backends that do not support rclone about* and *rclone about*. 🫶

## 🎀 Get your own Box App ID 🎀

Here's exactly how you make your own Box App ID for rclone, step by step, no gatekeeping:

1. Go to the Box Developer Console and login, then click **My Apps** on the sidebar. Click **Create New App** and select **Custom App**.

2. In the first screen on the box that pops up, you can pretty much enter whatever you want. The **App Name** can be whatever. For **Purpose** choose `automation` to avoid having to fill out anything else. Click **Next**.

3. In the second screen of the creation screen, select **User Authentication (OAuth 2.0)**. Then click **Create App**.

4. You should now be on the **Configuration** tab of your new app. If not, click on it at the top of the webpage. Copy down **Client ID** and **Client Secret**, you'll need those for rclone.

5. Under "OAuth 2.0 Redirect URI", add `http://127.0.0.1:53682/`

6. For **Application Scopes**, select **Read all files and folders stored in Box** and **Write all files and folders stored in box** (assuming you want to do both, which, yeah). Leave others unchecked. Click **Save Changes** at the top right.

---

# 💜 CACHE 💜

The cache remote wraps another existing remote and stores file structure and its data for long running tasks like `rclone mount`. It's giving glow-up-for-your-remote energy. ✨

## 🦋 Status 🦋

The cache backend code is working but it currently doesn't have a maintainer so there are outstanding bugs which aren't getting fixed. <red>No cap, this is the real tea.</red> 💀

The cache backend is due to be phased out in favour of the VFS caching layer eventually, which is more tightly integrated into rclone.

Until this happens we recommend only using the cache backend if you find you can't work without it. There are many docs online describing the use of the cache backend to minimize API hits and by-and-large these are out of date and the cache backend isn't needed in those scenarios any more. 🙈

## 🌸 Configuration 🌸

To get started you just need to have an existing remote which can be configured with cache.

Here is an example of how to make a remote called `test-cache`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote r) Rename remote c) Copy remote s) Set configuration password q) Quit config n/r/c/s/q> n name> test-cache Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Cache a remote \ "cache" [snip] Storage> cache Remote to cache. Normally should contain a ':' and a path, e.g. "myremote:path/to/dir", "myremote:bucket" or maybe "myremote:" (not recommended). remote> local:/test Optional: The URL of the Plex server plex_url> http://127.0.0.1:32400 Optional: The username of the Plex user plex_username> dummyusername Optional: The password of the Plex user y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: The size of a chunk. Lower value good for slow connections but can affect seamless reading. Default: 5M Choose a number from below, or type in your own value 1 / 1 MiB \ "1M" 2 / 5 MiB \ "5M" 3 / 10 MiB \ "10M" chunk_size> 2 How much time should object info (file size, file hashes, etc.) be stored in cache. Use a very high value if you don't plan on changing the source FS from outside the cache. Accepted units are: "s", "m", "h". Default: 5m Choose a number from below, or type in your own value 1 / 1 hour \ "1h" 2 / 24 hours \ "24h" 3 / 24 hours \ "48h" info_age> 2 The maximum size of stored chunks. When the storage grows beyond this size, the oldest chunks will be deleted. Default: 10G Choose a number from below, or type in your own value 1 / 500 MiB \ "500M" 2 / 1 GiB \ "1G" 3 / 10 GiB \ "10G" chunk_total_size> 3 Remote config

[test-cache] remote = local:/test plex_url = http://127.0.0.1:32400 plex_username = dummyusername plex_password = * ENCRYPTED * chunk_size = 5M info_age = 48h chunk_total_size = 10G


You can then use it like this. <pink>List directories in top level of your drive:</pink>

rclone lsd test-cache:


<pink>List all the files in your drive:</pink>

rclone ls test-cache:


<pink>To start a cached mount:</pink>

rclone mount --allow-other test-cache: /var/tmp/test-cache


## ✨ Write Features ✨

### 💖 Offline uploading 💖

In an effort to make writing through cache more reliable, the backend now supports this feature which can be activated by specifying a `cache-tmp-upload-path`.

A files goes through these states when using this feature — <lavender>the character arc, honestly:</lavender>

1. An upload is started (usually by copying a file on the cache remote)

2. When the copy to the temporary location is complete the file is part of the cached remote and looks and behaves like any other file (reading included)

3. After `cache-tmp-wait-time` passes and the file is next in line, `rclone move` is used to move the file to the cloud provider

4. Reading the file still works during the upload but most modifications on it will be prohibited

5. Once the move is complete the file is unlocked for modifications as it becomes as any other regular file

6. If the file is being read through cache when it's actually deleted from the temporary path then cache will simply swap the source to the cloud provider without interrupting the reading (small blip can happen though)

Files are uploaded in sequence and only one file is uploaded at a time. Uploads will be stored in a queue and be processed based on the order they were added. The queue and the temporary storage is persistent across restarts but can be cleared on startup with the `--cache-db-purge` flag. 🧚

### 🌈 Write Support 🌈

Writes are supported through cache. One caveat is that a mounted cache remote does not add any retry or fallback mechanism to the upload operation. This will depend on the implementation of the wrapped remote. Consider using **Offline uploading** for reliable writes.

One special case is covered with `cache-writes` which will cache the file data at the same time as the upload when it is enabled, making it available from the cache store immediately once the upload is finished. 👑

## ⭐ Read Features ⭐

### 🍓 Multiple connections 🍓

To counter the high latency between a local PC where rclone is running and cloud providers, the cache remote can split multiple requests to the cloud provider for smaller file chunks and combines them together locally where they can be available almost immediately before the reader usually needs them.

This is similar to buffering when media files are played online. Rclone will stay around the current marker but always try its best to stay ahead and prepare the data before. <cyan>main character energy, honestly.</cyan>

### 💜 Plex Integration 💜

There is a direct integration with Plex which allows cache to detect during reading if the file is in playback or not. This helps cache to adapt how it queries the cloud provider depending on what is needed for.

Scans will have a minimum amount of workers (`1`) while in a confirmed playback cache will deploy the configured number of workers.

This integration opens the doorway to additional performance improvements which will be explored in the near future.

> Note: If Plex options are not configured, cache will function with its configured options without adapting any of its settings.

How to enable? Run `rclone config` and add all the Plex options (endpoint, username and password) in your remote and it will be automatically enabled. ✨

Affected settings:

- `cache-workers`: Configured value during confirmed playback or `1` all the other times

### 🎀 Certificate Validation 🎀

When the Plex server is configured to only accept secure connections, it is possible to use `.plex.direct` URLs to ensure certificate validation succeeds. These URLs are used by Plex internally to connect to the Plex server securely.

The format for these URLs is the following:

https://ip-with-dots-replaced.server-hash.plex.direct:32400/


The `ip-with-dots-replaced` part can be any IPv4 address, where the dots have been replaced with dashes, e.g. `127.0.0.1` becomes `127-0-0-1`.

To get the `server-hash` part, the easiest way is to visit

https://plex.tv/api/resources?includeHttps=1&X-Plex-Token=your-plex-token


This page will list all the available Plex servers for your account with at least one `.plex.direct` link for each. Copy one URL and replace the IP address with the desired address. This can be used as the `plex_url` value. 🦋

## 💀 Known issues 💀

### 🔥 Mount and --dir-cache-time 🔥

`--dir-cache-time` controls the first layer of directory caching which works at the mount layer. Being an independent caching mechanism from the cache backend, it will manage its own entries based on the configured time.

To avoid getting in a scenario where dir cache has obsolete data and cache would have the correct one, try to set `--dir-cache-time` to a lower time than `--cache-info-age`. Default values are already configured in this way. <yellow>iykyk.</yellow>

### 🫶 Windows support - Experimental 🫶

There are a couple of issues with Windows mount functionality that still require some investigations. It should be considered as experimental thus far as fixes come in for this OS.

Most of the issues seem to be related to the difference between filesystems on Linux flavors and Windows as cache is heavily dependent on them.

Any reports or feedback on how cache behaves on this OS is greatly appreciated. 🥺

- `https://github.com/rclone/rclone/issues/1935`

- `https://github.com/rclone/rclone/issues/1907`

- `https://github.com/rclone/rclone/issues/1834`

### 🌸 Risk of throttling 🌸

Future iterations of the cache backend will make use of the pooling functionality of the cloud provider to synchronize and at the same time make writing through it more tolerant to failures.

<pink>There are a couple of enhancements in track to add these</pink>, but rn there's a very valid concern that like… those expiring cache listings can get you <red>throttled or straight-up banned</red> by your cloud provider, because it just keeps querying over and over for huge mounts. 😭

Some recs, bestie:

- Don't use a super tiny interval for entry information (`--cache-info-age`) — small number, big problems.
- Writes aren't optimised yet, but you *can* still write through cache, and that gets you the little glow-up of the file landing in the cache at the same time, if you've configured it that way. ✨

Future enhancements (manifesting):

- https://github.com/rclone/rclone/issues/1937
- https://github.com/rclone/rclone/issues/1936

---

### 🔐 cache and crypt

Sooo one super common scenario: keeping your data encrypted in the cloud provider using the `crypt` remote. `crypt` uses a similar technique to wrap around an existing remote, and handles that translation seamlessly. Chef's kiss. 💅

But there's an issue with wrapping the remotes in *this* order:

cloud remote -> crypt -> cache


During testing, the author got a LOT of bans with the remotes in this order. 😭 They suspect it might be related to how `crypt` opens files on the cloud provider, which makes it think we're downloading the **full file** instead of small chunks. Organizing the remotes like this instead yields better results:

cloud remote -> cache -> crypt


### 🧭 absolute remote paths

`cache` cannot differentiate between relative and absolute paths for the wrapped remote. Any path you give in the remote config setting and on the command line gets passed to the wrapped remote *as is* — but for storing the chunks on disk, the path gets made relative by stripping any leading `/` character.

This behavior is irrelevant for most backend types, but there are backends where a leading `/` changes the effective directory. Like, in the `sftp` backend: paths starting with a `/` are relative to the root of the SSH server, and paths without it are relative to the user home directory. So as a result, `sftp:bin` and `sftp:/bin` will **share the same cache folder**, even if they represent a different directory on the SSH server. 💀 iykyk.

### 🎛️ Cache and Remote Control (–rc)

Cache supports the new `--rc` mode in rclone and can be remote controlled through the following end points. By default, the listener is disabled if you don't add the flag.

### 🧹 rc cache/expire

Purge a remote from the cache backend. Supports either a directory or a file. It supports both encrypted and unencrypted file names if cache is wrapped by `crypt`. 🫶

Params:

- `remote` = path to remote (required)
- `withData` = true/false to delete cached data (chunks) as well (optional, false by default)

---

### 🌟 Standard options

Here are the Standard options specific to cache (Cache a remote).

- **`--cache-remote`** — Remote to cache.

  Normally should contain a `:` and a path, e.g. `"myremote:path/to/dir"`, `"myremote:bucket"` or maybe `"myremote:"` (not recommended).

  Properties:

  - **Config:** `remote`
  - **Env Var:** `RCLONE_CACHE_REMOTE`
  - **Type:** string
  - **Required:** true

- **`--cache-plex-url`** — The URL of the Plex server.

  Properties:

  - **Config:** `plex_url`
  - **Env Var:** `RCLONE_CACHE_PLEX_URL`
  - **Type:** string
  - **Required:** false

- **`--cache-plex-username`** — The username of the Plex user.

  Properties:

  - **Config:** `plex_username`
  - **Env Var:** `RCLONE_CACHE_PLEX_USERNAME`
  - **Type:** string
  - **Required:** false

- **`--cache-plex-password`** — The password of the Plex user.

  > NB Input to this must be obscured - see `rclone obscure`.

  Properties:

  - **Config:** `plex_password`
  - **Env Var:** `RCLONE_CACHE_PLEX_PASSWORD`
  - **Type:** string
  - **Required:** false

- **`--cache-chunk-size`** — The size of a chunk (partial file data).

  Use lower numbers for slower connections. If the chunk size is changed, any downloaded chunks will be invalid and `cache-chunk-path` will need to be cleared or unexpected EOF errors will occur. 🙈

  Properties:

  - **Config:** `chunk_size`
  - **Env Var:** `RCLONE_CACHE_CHUNK_SIZE`
  - **Type:** SizeSuffix
  - **Default:** `5Mi`
  - **Examples:**
    - `"1M"`
      - 1 MiB
    - `"5M"`
      - 5 MiB
    - `"10M"`
      - 10 MiB

- **`--cache-info-age`** — How long to cache file structure information (directory listings, file size, times, etc.). If all write operations are done through the cache then you can safely make this value very large as the cache store will also be updated in real time. ⏰

  Properties:

  - **Config:** `info_age`
  - **Env Var:** `RCLONE_CACHE_INFO_AGE`
  - **Type:** Duration
  - **Default:** `6h0m0s`
  - **Examples:**
    - `"1h"`
      - 1 hour
    - `"24h"`
      - 24 hours
    - `"48h"`
      - 48 hours

- **`--cache-chunk-total-size`** — The total size that the chunks can take up on the local disk.

  If the cache exceeds this value then it will start to delete the oldest chunks until it goes under this value. Girl's gotta make room. 🧹

  Properties:

  - **Config:** `chunk_total_size`
  - **Env Var:** `RCLONE_CACHE_CHUNK_TOTAL_SIZE`
  - **Type:** SizeSuffix
  - **Default:** `10Gi`
  - **Examples:**
    - `"500M"`
      - 500 MiB
    - `"1G"`
      - 1 GiB
    - `"10G"`
      - 10 GiB

---

### 💎 Advanced options

Here are the Advanced options specific to cache (Cache a remote).

- **`--cache-plex-token`** — The plex token for authentication - auto set normally.

  Properties:

  - **Config:** `plex_token`
  - **Env Var:** `RCLONE_CACHE_PLEX_TOKEN`
  - **Type:** string
  - **Required:** false

- **`--cache-plex-insecure`** — Skip all certificate verification when connecting to the Plex server.

  Properties:

  - **Config:** `plex_insecure`
  - **Env Var:** `RCLONE_CACHE_PLEX_INSECURE`
  - **Type:** string
  - **Required:** false

- **`--cache-db-path`** — Directory to store file structure metadata DB.

  The remote name is used as the DB file name.

  Properties:

  - **Config:** `db_path`
  - **Env Var:** `RCLONE_CACHE_DB_PATH`
  - **Type:** string
  - **Default:** `"$HOME/.cache/rclone/cache-backend"`

- **`--cache-chunk-path`** — Directory to cache chunk files.

  Path to where partial file data (chunks) are stored locally. The remote name is appended to the final path.

  This config follows the `--cache-db-path`. If you specify a custom location for `--cache-db-path` and don't specify one for `--cache-chunk-path` then `--cache-chunk-path` will use the same path as `--cache-db-path`.

  Properties:

  - **Config:** `chunk_path`
  - **Env Var:** `RCLONE_CACHE_CHUNK_PATH`
  - **Type:** string
  - **Default:** `"$HOME/.cache/rclone/cache-backend"`

- **`--cache-db-purge`** — Clear all the cached data for this remote on start.

  Properties:

  - **Config:** `db_purge`
  - **Env Var:** `RCLONE_CACHE_DB_PURGE`
  - **Type:** bool
  - **Default:** `false`

- **`--cache-chunk-clean-interval`** — How often should the cache perform cleanups of the chunk storage.

  The default value should be ok for most people. If you find that the cache goes over `cache-chunk-total-size` too often then try to lower this value to force it to perform cleanups more often.

  Properties:

  - **Config:** `chunk_clean_interval`
  - **Env Var:** `RCLONE_CACHE_CHUNK_CLEAN_INTERVAL`
  - **Type:** Duration
  - **Default:** `1m0s`

- **`--cache-read-retries`** — How many times to retry a read from a cache storage.

  Since reading from a cache stream is independent from downloading file data, readers can get to a point where there's no more data in the cache. Most of the times this can indicate a connectivity issue if cache isn't able to provide file data anymore.

  For really slow connections, increase this to a point where the stream is able to provide data but your experience will be **very stuttering**. 😵‍💫

  Properties:

  - **Config:** `read_retries`
  - **Env Var:** `RCLONE_CACHE_READ_RETRIES`
  - **Type:** int
  - **Default:** `10`

- **`--cache-workers`** — How many workers should run in parallel to download chunks.

  Higher values will mean more parallel processing (better CPU needed) and more concurrent requests on the cloud provider. This impacts several aspects like the cloud provider API limits, more stress on the hardware that rclone runs on — but it also means that streams will be more fluid and data will be available much more faster to readers. 🔥

  Note: If the optional Plex integration is enabled then this setting will adapt to the type of reading performed and the value specified here will be used as a maximum number of workers to use.

  Properties:

  - **Config:** `workers`
  - **Env Var:** `RCLONE_CACHE_WORKERS`
  - **Type:** int
  - **Default:** `4`

- **`--cache-chunk-no-memory`** — Disable the in-memory cache for storing chunks during streaming.

  By default, cache will keep file data during streaming in RAM as well to provide it to readers as fast as possible.

  This transient data is evicted as soon as it is read and the number of chunks stored doesn't exceed the number of workers. However, depending on other settings like `cache-chunk-size` and `cache-workers` this footprint can increase if there are parallel streams too (multiple files being read at the same time).

  If the hardware permits it, use this feature to provide an overall better performance during streaming but it can also be disabled if RAM is not available on the local machine.

  Properties:

  - **Config:** `chunk_no_memory`
  - **Env Var:** `RCLONE_CACHE_CHUNK_NO_MEMORY`
  - **Type:** bool
  - **Default:** `false`

- **`--cache-rps`** — Limits the number of requests per second to the source FS (`-1` to disable).

  This setting places a **hard limit** on the number of requests per second that cache will be doing to the cloud provider remote and try to respect that value by setting waits between reads.

  If you find that you're getting banned or limited on the cloud provider through cache and know that a smaller number of requests per second will allow you to work with it then you can use this setting for that.

  A good balance of all the other settings should make this setting useless but it is available to set for more special cases.

  > NOTE: This will limit the number of requests during streams but other API calls to the cloud provider like directory listings will still pass.

  Properties:

  - **Config:** `rps`
  - **Env Var:** `RCLONE_CACHE_RPS`
  - **Type:** int
  - **Default:** `-1`

- **`--cache-writes`** — Cache file data on writes through the FS.

  If you need to read files immediately after you upload them through cache you can enable this flag to have their data stored in the cache store at the same time during upload. ✨

  Properties:

  - **Config:** `writes`
  - **Env Var:** `RCLONE_CACHE_WRITES`
  - **Type:** bool
  - **Default:** `false`

- **`--cache-tmp-upload-path`** — Directory to keep temporary files until they are uploaded.

<purple>okay so picking up right where we left off, bestie</purple> 💖 this is the path where cache will use as a temporary storage for new files that need to be uploaded to the cloud provider.

Specifying a value will enable this feature. Without it, it is completely disabled and files will be uploaded directly to the cloud provider.

- **Config:** `tmp_upload_path`
- **Env Var:** `RCLONE_CACHE_TMP_UPLOAD_PATH`
- **Type:** string
- **Required:** false

---

- **`--cache-tmp-wait-time`** — how long should files be stored in local cache before being uploaded? ⏳

  This is the duration that a file must wait in the temporary location `cache-tmp-upload-path` before it is selected for upload.

  Lowkey important: only **one** file is uploaded at a time, and it can take longer to start the upload if a queue formed for this purpose. <mint>(the queue is real and it does not care about your feelings)</mint>

  - **Config:** `tmp_wait_time`
  - **Env Var:** `RCLONE_CACHE_TMP_WAIT_TIME`
  - **Type:** Duration
  - **Default:** `15s`

- **`--cache-db-wait-time`** — how long to wait for the DB to be available — `0` is unlimited 🕰️

  Only one process can have the DB open at any one time, so rclone waits for this duration for the DB to become available before it gives an error.

  If you set it to `0` then it will wait forever. <peach>(forever-forever? yes bestie, forever)</peach>

  - **Config:** `db_wait_time`
  - **Env Var:** `RCLONE_CACHE_DB_WAIT_TIME`
  - **Type:** Duration
  - **Default:** `1s`

- **`--cache-description`** — description of the remote ✍️

  - **Config:** `description`
  - **Env Var:** `RCLONE_CACHE_DESCRIPTION`
  - **Type:** string
  - **Required:** false

---

### ✨ Backend commands ✨

Here are the commands specific to the cache backend 🎀

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`. <cyan>(iykyk)</cyan>

### 📊 stats

Print stats on the cache backend in JSON format.

rclone backend stats remote: [options] [<arguments>+]


---

# 🧩 Chunker

The chunker overlay transparently splits large files into smaller chunks during upload to wrapped remote and transparently assembles them back when the file is downloaded. This allows to effectively overcome size limits imposed by storage providers. <rainbow>iconic behaviour honestly</rainbow> 💅

## 🛠️ Configuration

To use it, first set up the underlying remote following the configuration instructions for that remote. You can also use a local pathname instead of a remote.

First check your chosen remote is working — we'll call it *`remote:path`* here. Note that anything inside *`remote:path`* will be chunked and anything outside won't. This means that if you are using a bucket-based remote (e.g. S3, B2, swift) then you should probably put the bucket in the remote *`s3:bucket`*. 🪣

Now configure chunker using `rclone config`. We will call this one *`overlay`* to separate it from the remote itself.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> overlay Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Transparently chunk/split large files \ "chunker" [snip] Storage> chunker Remote to chunk/unchunk. Normally should contain a ':' and a path, e.g. "myremote:path/to/dir", "myremote:bucket" or maybe "myremote:" (not recommended). Enter a string value. Press Enter for the default (""). remote> remote:path Files larger than chunk size will be split in chunks. Enter a size with suffix K,M,G,T. Press Enter for the default ("2G"). chunk_size> 100M Choose how chunker handles hash sums. All modes but "none" require metadata. Enter a string value. Press Enter for the default ("md5"). Choose a number from below, or type in your own value 1 / Pass any hash supported by wrapped remote for non-chunked files, return nothing otherwise \ "none" 2 / MD5 for composite files \ "md5" 3 / SHA1 for composite files \ "sha1" 4 / MD5 for all files \ "md5all" 5 / SHA1 for all files \ "sha1all" 6 / Copying a file to chunker will request MD5 from the source falling back to SHA1 if unsupported \ "md5quick" 7 / Similar to "md5quick" but prefers SHA1 over MD5 \ "sha1quick" hash_type> md5 Edit advanced config? (y/n) y) Yes n) No y/n> n Remote config

[overlay] type = chunker remote = remote:bucket chunk_size = 100M hash_type = md5

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


## 📍 Specifying the remote

In normal use, make sure the remote has a `:` in. If you specify the remote without a `:` then rclone will use a local directory of that name. So if you use a remote of `/path/to/secret/files` then rclone will chunk stuff in that directory. If you use a remote of `name` then rclone will put files in a directory called `name` in the current directory. 🗂️

## ✂️ Chunking

When rclone starts a file upload, chunker checks the file size. If it doesn't exceed the configured chunk size, chunker will just pass the file to the wrapped remote (however, see caveat below). If a file is large, chunker will transparently cut data in pieces with temporary names and stream them one by one, on the fly. Each data chunk will contain the specified number of bytes, except for the last one which may have less data. If file size is unknown in advance (this is called a streaming upload), chunker will internally create a temporary copy, record its size and repeat the above process.

When upload completes, temporary chunk files are finally renamed. This scheme guarantees that operations can be run in parallel and look from outside as atomic. A similar method with hidden temporary chunks is used for other operations (copy/move/rename, etc.). If an operation fails, hidden chunks are normally destroyed, and the target composite file stays intact. <mint>not it being atomic though — ate</mint> ✨

When a composite file download is requested, chunker transparently assembles it by concatenating data chunks in order. As the split is trivial one could even manually concatenate data chunks together to obtain the original content. 🧚

When the `list` rclone command scans a directory on wrapped remote, the potential chunk files are accounted for, grouped and assembled into composite directory entries. Any temporary chunks are hidden. 🙈

List and other commands can sometimes come across composite files with missing or invalid chunks, e.g. shadowed by like-named directory or another file. This usually means that wrapped file system has been directly tampered with or damaged. If chunker detects a missing chunk it will by default print warning, skip the whole incomplete group of chunks but proceed with current command. You can set the `--chunker-fail-hard` flag to have commands abort with error message in such cases.

> ⚠️ **Caveat:** As it is now, chunker will always create a temporary file in the backend and then rename it, even if the file is below the chunk threshold. This will result in unnecessary API calls and can severely restrict throughput when handling transfers primarily composed of small files on some backends (e.g. Box). A workaround to this issue is to use chunker only for files above the chunk threshold via `--min-size` and then perform a separate call without chunker on the remaining files. <red>(fr fr, this one bites)</red> 😭

## 🏷️ Chunk names

The default chunk name format is `*.rclone_chunk.###`, hence by default chunk names are `BIG_FILE_NAME.rclone_chunk.001`, `BIG_FILE_NAME.rclone_chunk.002` etc. You can configure another name format using the `name_format` configuration file option. The format uses asterisk `*` as a placeholder for the base file name and one or more consecutive hash characters `#` as a placeholder for sequential chunk number. There must be one and only one asterisk. The number of consecutive hash characters defines the minimum length of a string representing a chunk number. If decimal chunk number has less digits than the number of hashes, it is left-padded by zeros. If the decimal string is longer, it is left intact. By default numbering starts from `1` but there is another option that allows user to start from `0`, e.g. for compatibility with legacy software. 👑

For example, if name format is `big_*-##.part` and original file name is `data.txt` and numbering starts from `0`, then the first chunk will be named `big_data.txt-00.part`, the 99th chunk will be `big_data.txt-98.part` and the 302nd chunk will become `big_data.txt-301.part`.

Note that `list` assembles composite directory entries only when chunk names match the configured format and treats non-conforming file names as normal non-chunked files. <cyan>(the format is the vibe check)</cyan>

When using norename transactions, chunk names will additionally have a unique file version suffix. For example, `BIG_FILE_NAME.rclone_chunk.001_bp562k`.

## 🧾 Metadata

Besides data chunks chunker will by default create metadata object for a composite file. The object is named after the original file. Chunker allows user to disable metadata completely (the `none` format). Note that metadata is normally not created for files smaller than the configured chunk size. This may change in future rclone releases. 🔮

### Simple JSON metadata format

This is the default format. It supports hash sums and chunk validation for composite files. Meta objects carry the following fields:

- `ver` — version of format, currently `1`
- `size` — total size of composite file
- `nchunks` — number of data chunks in file
- `md5` — MD5 hashsum of composite file (if present)
- `sha1` — SHA1 hashsum (if present)
- `txn` — identifies current version of the file

There is no field for composite file name as it's simply equal to the name of meta object on the wrapped remote. Please refer to respective sections for details on hashsums and modified time handling.

### No metadata

You can disable meta objects by setting the meta format option to `none`. In this mode chunker will scan directory for all files that follow configured chunk name format, group them by detecting chunks with the same base name and show group names as virtual composite files. This method is more prone to missing chunk errors (especially missing last chunk) than format with metadata enabled. <peach>bestie, you've been warned</peach> 💀

## #️⃣ Hashsums

Chunker supports hashsums only when a compatible metadata is present. Hence, if you choose metadata format of `none`, chunker will report hashsum as `UNSUPPORTED`.

<purple>okay so the metadata tea ☕</purple> — by default metadata is stored **only for composite files**, bestie. And if a file is smaller than your configured `chunk_size`, chunker will <mint>transparently redirect hash requests to the wrapped remote</mint>, so whether that works at all depends on the wrapped remote behaving. Which means: for small files you'll literally see the **empty string** as the hashsum of the requested type if the wrapped remote doesn't support it. 🙈 Not a bug, just the deal.

Many storage backends support `MD5` and `SHA1` hash types, and so does chunker 💅. With chunker you can pick one or the other but <red>**not both**</red>. `MD5` is the default because it's the most widely supported type. And since chunker keeps hashes for composite files but falls back to the wrapped remote's hash for non-chunked ones, we *advise* you to choose the same hash type your wrapped remote supports — that way your file listings actually look coherent and not like a group chat where nobody's on the same page. 🦋

If your storage backend doesn't support `MD5` or `SHA1` but you *need* consistent file hashing, configure chunker with `md5all` or `sha1all`. These two modes <hotpink>guarantee the given hash for all files</hotpink>. If the wrapped remote doesn't support it, chunker will then add metadata to **all** files, even the small ones. ⚠️ Heads up though: this can **double** the amount of small files in storage and incur additional service charges. You can even use chunker to force md5/sha1 support in any other remote at the expense of sidecar meta objects — by setting e.g. `hash_type=sha1all` to force hashsums and `chunk_size=1P` to effectively disable chunking. iconic workaround honestly.

Normally, when a file is copied to a chunker controlled remote, chunker will ask the file source for a compatible file hash and revert to on-the-fly calculation if none is found. ✨ This involves some CPU overhead but it gives you a guarantee that the given hashsum is actually available. Also, chunker will **reject** a server-side copy or move operation if source and destination hashsum types are different — which results in extra network bandwidth too. In some rare cases this may be undesired, so chunker gives you two optional choices: `sha1quick` and `md5quick`. If the source doesn't support the primary hash type and quick mode is enabled, chunker will try to fall back to the secondary type. This saves CPU and bandwidth but can result in **empty hashsums at destination**. 😭 Beware of the consequences: the `sync` command will revert (sometimes *silently*) to time/size comparison if compatible hashsums between source and target are not found. iykyk.

## 🌸 Modification times 🌸

Chunker stores modification times using the wrapped remote, so whether it works depends on that. For a small non-chunked file the chunker overlay simply manipulates the modification time of the wrapped remote file. 🎀 For a composite file with metadata, chunker will get and set the modification time of the metadata object on the wrapped remote. And if the file is chunked but the metadata format is `none`, then chunker will use the modification time of the **first data chunk**. no cap.

## 🦋 Migrations 🦋

The idiomatic way to migrate to a different chunk size, hash type, transaction style, or chunk naming scheme is to:

1. Collect all your chunked files under a directory and have your chunker remote point to it.
2. Create another directory (most probably on the same cloud storage) and configure a new remote with the desired metadata format, hash type, chunk naming, etc.
3. Now run `rclone sync --interactive oldchunks: newchunks:` and all your data will be transparently converted in transfer. ⭐ This may take some time, yet chunker will try a server-side copy if possible.
4. After checking data integrity you may remove the configuration section of the old remote.

If rclone gets killed during a long operation on a big composite file, hidden temporary chunks may stay in the directory. 💀 They will **not** be shown by the `list` command but they *will* eat up your account quota. Please note that the `deletefile` command deletes only the active chunks of a file. As a workaround, you can use the remote of the wrapped file system to see them. An easy way to get rid of hidden garbage is to copy the littered directory somewhere using the chunker remote and purge the original directory. The `copy` command will copy only active chunks, while the `purge` will remove everything including garbage. 🧹✨

## 👑 Caveats and Limitations 👑

Chunker requires the wrapped remote to support **server-side move** (or `copy` + `delete`) operations, otherwise it will <red>explicitly refuse to start</red>. Why so strict, bestie? Because it internally renames temporary chunk files to their final names when an operation completes successfully. 💅

Chunker encodes the chunk number in the file name, so with the default `name_format` setting it adds **17 characters**. It also adds **7 characters** of temporary suffix during operations. Many file systems limit the base file name (no path) to **255 characters**. Using rclone's `crypt` remote as a base file system limits file name by **143 characters**. So the maximum name length is **231** for most files and **119** for chunker-over-crypt. 😭 A user in need can change the name format to e.g. `*.rcc##` and save 10 characters (provided at most **99 chunks per file**, okay?).

Note that a move implemented using the copy-and-delete method may incur **double charging** with some cloud storage providers. 💸

Chunker will **not** automatically rename existing chunks when you run `rclone config` on a live remote and change the chunk name format. 🚨 Beware that as a result of this, some files which have been treated as chunks before the change can pop up in directory listings as normal files — and vice versa. The same warning holds for the chunk size. So if you *desperately* need to change critical chunking settings, you should run a data migration as described above. periodt.

If the wrapped remote is case insensitive, the chunker overlay will inherit that property (so you can't have a file called "Hello.doc" *and* "hello.doc" in the same directory). 🙃

Chunker included in rclone releases up to **v1.54** can sometimes fail to detect metadata produced by recent versions of rclone. We recommend users keep rclone up-to-date to avoid data corruption. 🫶

> ⚠️ Changing transactions is **dangerous** and requires **explicit migration**.

---

## ✨ Standard options ✨

Here are the Standard options specific to chunker (Transparently chunk/split large files). 💖

### `--chunker-remote`

Remote to chunk/unchunk.

Normally should contain a `:` and a path, e.g. `"myremote:path/to/dir"`, `"myremote:bucket"` or maybe `"myremote:"` (not recommended).

Properties:

- Config: `remote`
- Env Var: `RCLONE_CHUNKER_REMOTE`
- Type: string
- Required: true

### `--chunker-chunk-size`

Files larger than chunk size will be split in chunks.

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_CHUNKER_CHUNK_SIZE`
- Type: SizeSuffix
- Default: `2Gi`

### `--chunker-hash-type`

Choose how chunker handles hash sums.

All modes but `"none"` require metadata.

Properties:

- Config: `hash_type`
- Env Var: `RCLONE_CHUNKER_HASH_TYPE`
- Type: string
- Default: `"md5"`
- Examples:
  - `"none"`
    - Pass any hash supported by wrapped remote for non-chunked files.
    - Return nothing otherwise.
  - `"md5"`
    - MD5 for composite files.
  - `"sha1"`
    - SHA1 for composite files.
  - `"md5all"`
    - MD5 for all files.
  - `"sha1all"`
    - SHA1 for all files.
  - `"md5quick"`
    - Copying a file to chunker will request MD5 from the source.
    - Falling back to SHA1 if unsupported.
  - `"sha1quick"`
    - Similar to `"md5quick"` but prefers SHA1 over MD5.

## 🌈 Advanced options 🌈

Here are the Advanced options specific to chunker (Transparently chunk/split large files). 💅

### `--chunker-name-format`

String format of chunk file names.

The two placeholders are: base file name (`*`) and chunk number (`#...`). There must be **one and only one** asterisk and **one or more** consecutive hash characters. If the chunk number has less digits than the number of hashes, it is left-padded by zeros. If there are more digits in the number, they are left as is. Possible chunk files are ignored if their name does not match the given format. 👀

Properties:

- Config: `name_format`
- Env Var: `RCLONE_CHUNKER_NAME_FORMAT`
- Type: string
- Default: `"*.rclone_chunk.###"`

### `--chunker-start-from`

Minimum valid chunk number. Usually `0` or `1`.

By default chunk numbers start from `1`.

Properties:

- Config: `start_from`
- Env Var: `RCLONE_CHUNKER_START_FROM`
- Type: int
- Default: `1`

### `--chunker-meta-format`

Format of the metadata object or `"none"`.

By default `"simplejson"`. Metadata is a small JSON file named after the composite file.

Properties:

- Config: `meta_format`
- Env Var: `RCLONE_CHUNKER_META_FORMAT`
- Type: string
- Default: `"simplejson"`
- Examples:
  - `"none"`
    - Do not use metadata files at all.
    - Requires hash type `"none"`.
  - `"simplejson"`
    - Simple JSON supports hash sums and chunk validation.
    - It has the following fields: `ver`, `size`, `nchunks`, `md5`, `sha1`.

### `--chunker-fail-hard`

Choose how chunker should handle files with missing or invalid chunks.

Properties:

- Config: `fail_hard`
- Env Var: `RCLONE_CHUNKER_FAIL_HARD`
- Type: bool
- Default: `false`
- Examples:
  - `"true"`
    - Report errors and abort current command.
  - `"false"`
    - Warn user, skip incomplete file and proceed.

### `--chunker-transactions`

Choose how chunker should handle temporary files during transactions.

Properties:

- Config: `transactions`
- Env Var: `RCLONE_CHUNKER_TRANSACTIONS`
- Type: string
- Default: `"rename"`
- Examples:
  - `"rename"`
    - Rename temporary files after a successful transaction.
  - `"norename"`
    - Leave temporary file names and write transaction ID to metadata file.
    - Metadata is required for no rename transactions (meta format cannot be `"none"`).
    - If you are using norename transactions you should be careful not to downgrade Rclone, as older versions of Rclone don't support this transaction style and will misinterpret files manipulated by norename transactions.
    - This method is **EXPERIMENTAL**, don't use on production systems. 💀
  - `"auto"`
    - Rename or norename will be used depending on capabilities of the backend.
    - If meta format is set to `"none"`, rename transactions will always be used.
    - This method is **EXPERIMENTAL**, don't use on production systems. 💀

### `--chunker-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_CHUNKER_DESCRIPTION`
- Type: string
- Required: false

# 🌤️ Cloudinary

This is a backend for the <pink>Cloudinary</pink> platform 💖

---

## ✨ About Cloudinary ✨

Cloudinary is an <hotpink>image and video API platform</hotpink>. Trusted by **1.5 million developers** and **10,000 enterprise and hyper-growth companies** as a critical part of their tech stack to deliver visually engaging experiences. Like, they are *not* playing around bestie, that's a whole lot of trust 💅

---

## 💸 Accounts & Pricing 💸

So to use this backend you literally need to create a free account on Cloudinary first, no cap. Start with a free plan with generous usage limits 🫶 Then, as your requirements grow, upgrade to a plan that best fits your needs. See the pricing details.

---

## 🔐 Securing Your Credentials 🔐

Please refer to the docs 👑

---

## 🛠️ Configuration 🛠️

Here's an example of making a Cloudinary configuration, bestie.

First, create a `cloudinary.com` account and choose a plan.

You will need to log in and get the **API Key** and **API Secret** for your account from the developer section.

Now run

rclone config


Follow the interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter the name for the new remote. name> cloudinary-media-library

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / cloudinary.com \ (cloudinary) [snip] Storage> cloudinary

Option cloud_name. You can find your cloudinary.com cloud_name in your [dashboard](https://console.cloudinary.com/pm/developer-dashboard) Enter a value. cloud_name>

Option api_key. You can find your cloudinary.com api key in your [dashboard](https://console.cloudinary.com/pm/developer-dashboard) Enter a value. api_key>

Option api_secret. You can find your cloudinary.com api secret in your [dashboard](https://console.cloudinary.com/pm/developer-dashboard) This value must be a single character, one of the following: y, g. y/g> y Enter a value. api_secret>

Option upload_prefix. [Upload prefix](https://cloudinary.com/documentation/cloudinary_sdks#configuration_parameters) to specify alternative data center Enter a value. upload_prefix>

Option upload_preset. [Upload presets](https://cloudinary.com/documentation/upload_presets) can be defined for different upload profiles Enter a value. upload_preset>

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: cloudinary
api_key:
api_secret:
cloud_name:
upload_prefix:
upload_preset:

Keep this "cloudinary-media-library" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


List directories in the top level of your Media Library 🦋

rclone lsd cloudinary-media-library:


Make a new directory.

rclone mkdir cloudinary-media-library:directory


List the contents of a directory.

rclone ls cloudinary-media-library:directory


---

## ⏰ Modified time and hashes ⏰

Cloudinary stores <mint>md5</mint> and <mint>timestamps</mint> for any successful Put automatically and read-only. It's giving "handled, don't worry about it" ✨

---

## 🌟 Standard options 🌟

Here are the Standard options specific to cloudinary (Cloudinary). Slay.

### 💫 `--cloudinary-cloud-name`

Cloudinary Environment Name

Properties:

- Config: `cloud_name`
- Env Var: `RCLONE_CLOUDINARY_CLOUD_NAME`
- Type: string
- Required: true

### 💫 `--cloudinary-api-key`

Cloudinary API Key

Properties:

- Config: `api_key`
- Env Var: `RCLONE_CLOUDINARY_API_KEY`
- Type: string
- Required: true

### 💫 `--cloudinary-api-secret`

Cloudinary API Secret

Properties:

- Config: `api_secret`
- Env Var: `RCLONE_CLOUDINARY_API_SECRET`
- Type: string
- Required: true

### 💫 `--cloudinary-upload-prefix`

Specify the API endpoint for environments out of the US

Properties:

- Config: `upload_prefix`
- Env Var: `RCLONE_CLOUDINARY_UPLOAD_PREFIX`
- Type: string
- Required: false

### 💫 `--cloudinary-upload-preset`

Upload Preset to select asset manipulation on upload

Properties:

- Config: `upload_preset`
- Env Var: `RCLONE_CLOUDINARY_UPLOAD_PRESET`
- Type: string
- Required: false

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to cloudinary (Cloudinary). Main character energy only 💅

### ✨ `--cloudinary-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_CLOUDINARY_ENCODING`
- Type: Encoding
- Default:
  `Slash,LtGt,DoubleQuote,Question,Asterisk,Pipe,Hash,Percent,BackSlash,Del,Ctl,RightSpace,InvalidUtf8,Dot`

### ✨ `--cloudinary-eventually-consistent-delay`

Wait N seconds for eventual consistency of the databases that support the backend operation

Properties:

- Config: `eventually_consistent_delay`
- Env Var: `RCLONE_CLOUDINARY_EVENTUALLY_CONSISTENT_DELAY`
- Type: Duration
- Default: `0s`

> <purple>Bestie note:</purple> that default is `0s`, so like, if your databases be lagging, this is your girl 💜

### ✨ `--cloudinary-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_CLOUDINARY_DESCRIPTION`
- Type: string
- Required: false

---

<pink>okay that's the whole Cloudinary vibe, obsessed 🎀 more coming, don't go anywhere ✨</pink>

# 💖 Citrix ShareFile 💖

Citrix ShareFile is a secure file sharing and transfer service that's lowkey aimed at business. Bestie, it's giving ✨enterprise✨.

---

## 🎀 Configuration 🎀

The initial setup for Citrix ShareFile means getting a token from Citrix ShareFile, which you can do right in your browser. The `rclone config` walkthrough holds your hand through the whole thing, no cap.

So here's an example of how to make a remote called `remote`. First, run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 XX / Citrix Sharefile \ "sharefile" Storage> sharefile ** See help for sharefile backend at: https://rclone.org/sharefile/ **

ID of the root folder

Leave blank to access "Personal Folders". You can use one of the standard values here or any folder ID (long hex number ID). Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Access the Personal Folders. (Default) \ "" 2 / Access the Favorites folder. \ "favorites" 3 / Access all the shared folders. \ "allshared" 4 / Access all the individual connectors. \ "connectors" 5 / Access the home, favorites, and shared folders as well as the connectors. \ "top" root_folder_id> 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?state=XXX Log in and authorize rclone for access Waiting for code... Got code Configuration complete. Options:
type: sharefile
endpoint: https://XXX.sharefile.com
token: {"access_token":"XXX","token_type":"bearer","refresh_token":"XXX","expiry":"2019-09-30T19:41:45.878561877+01:00"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


Peep the remote setup docs for how to set it up on a machine with no Internet browser available. 🦋

Just so you know — rclone runs a webserver on your local machine to collect the token as returned from Citrix ShareFile. This only runs from the moment it opens your browser to the moment you get back the verification code. It's on `http://127.0.0.1:53682/` and it may require you to unblock it temporarily if you're running a host firewall. 👑

Once it's configured you can then use rclone like this,

List directories in top level of your ShareFile

rclone lsd remote:


List all the files in your ShareFile

rclone ls remote:


To copy a local directory to an ShareFile directory called `backup`

rclone copy /home/source remote:backup


Paths may be as deep as required, e.g. `remote:directory/subdirectory`. Fr fr, go as deep as you want.

---

## 🕐 Modification times and hashes 🕐

ShareFile allows modification times to be set on objects accurate to 1 second. These get used to detect whether objects need syncing or not.

ShareFile supports MD5 type hashes, so you can use the `--checksum` flag. Slay. 💅

---

## 🚚 Transfers 🚚

For files above 128 MiB rclone will use a chunked transfer. Rclone will upload up to `--transfers` chunks at the same time (shared among all the multipart uploads). Chunks are buffered in memory and are normally 64 MiB so increasing `--transfers` will increase memory use. Watch your RAM bestie, seriously. 😭

---

## 🚫 Restricted filename characters 🚫

In addition to the default restricted characters set the following characters are also replaced:

- Character `\` — Value `0x5C` — Replacement `＼`
- Character `*` — Value `0x2A` — Replacement `＊`
- Character `<` — Value `0x3C` — Replacement `＜`
- Character `>` — Value `0x3E` — Replacement `＞`
- Character `?` — Value `0x3F` — Replacement `？`
- Character `:` — Value `0x3A` — Replacement `：`
- Character `|` — Value `0x7C` — Replacement `｜`
- Character `”` — Value `0x22` — Replacement `＂`

File names can also not start or end with the following characters. These only get replaced if they are the first or last character in the name:

- Character `SP` — Value `0x20` — Replacement `␠`
- Character `.` — Value `0x2E` — Replacement `．`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. It's giving "JSON said no" 🙈.

---

## ⚙️ Standard options ⚙️

Here are the Standard options specific to sharefile (Citrix Sharefile).

### 💜 `--sharefile-client-id`

OAuth Client Id.

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_SHAREFILE_CLIENT_ID`
- Type: string
- Required: false

### 💜 `--sharefile-client-secret`

OAuth Client Secret.

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_SHAREFILE_CLIENT_SECRET`
- Type: string
- Required: false

### 💜 `--sharefile-root-folder-id`

ID of the root folder.

Leave blank to access "Personal Folders". You can use one of the standard values here or any folder ID (long hex number ID).

Properties:

- Config: `root_folder_id`
- Env Var: `RCLONE_SHAREFILE_ROOT_FOLDER_ID`
- Type: string
- Required: false
- Examples:
  - `""`
    - Access the Personal Folders (default).
  - `"favorites"`
    - Access the Favorites folder.
  - `"allshared"`
    - Access all the shared folders.
  - `"connectors"`
    - Access all the individual connectors.
  - `"top"`
    - Access the home, favorites, and shared folders as well as the connectors.

---

## 🧪 Advanced options 🧪

Here are the Advanced options specific to sharefile (Citrix Sharefile).

### 💜 `--sharefile-token`

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_SHAREFILE_TOKEN`
- Type: string
- Required: false

### 💜 `--sharefile-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_SHAREFILE_AUTH_URL`
- Type: string
- Required: false

### 💜 `--sharefile-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_SHAREFILE_TOKEN_URL`
- Type: string
- Required: false

### 💜 `--sharefile-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_SHAREFILE_CLIENT_CREDENTIALS`
- Type: bool
- Default: false

### 💜 `--sharefile-upload-cutoff`

Cutoff for switching to multipart upload.

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_SHAREFILE_UPLOAD_CUTOFF`
- Type: SizeSuffix
- Default: 128Mi

### 💜 `--sharefile-chunk-size`

Upload chunk size.

Must a power of 2 >= 256k.

Making this larger will improve performance, but note that each chunk is buffered in memory one per transfer.

Reducing this will reduce memory usage but decrease performance.

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_SHAREFILE_CHUNK_SIZE`
- Type: SizeSuffix
- Default: 64Mi

### 💜 `--sharefile-endpoint`

Endpoint for API calls.

This is usually auto discovered as part of the oauth process, but can be set manually to something like: `https://XXX.sharefile.com`

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_SHAREFILE_ENDPOINT`
- Type: string
- Required: false

### 💜 `--sharefile-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_SHAREFILE_ENCODING`
- Type: Encoding
- Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,LeftSpace,LeftPeriod,RightSpace,RightPeriod,InvalidUtf8,Dot`

### 💜 `--sharefile-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_SHAREFILE_DESCRIPTION`
- Type: string
- Required: false

---

## 😬 Limitations 😬

Note that ShareFile is case insensitive so you can't have a file called "Hello.doc" and one called "hello.doc". Pick one, bestie, it can't tell them apart. 💀

ShareFile only supports filenames up to 256 characters in length.

`rclone about` is **not** supported by the Citrix ShareFile backend. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote.

See List of backends that do not support `rclone about` and `rclone about`

---

# 🔐 Crypt 🔐

Rclone crypt remotes encrypt and decrypt other remotes.

A remote of type `crypt` does not access a storage system directly, but instead wraps another remote, which in turn accesses the storage system. This is similar to how `alias`, `union`, `chunker` and a few others work. It makes the usage very flexible, as you can add a layer, in this case an encryption layer, on top of any other backend, even in multiple layers. Rclone's functionality can be used as with any other remote, for example you can mount a crypt remote. Layers on layers on layers, it's giving onion 🧅✨.

Accessing a storage system through a crypt remote realizes **client-side encryption**, which makes it safe to keep your data in a location you do not trust will not get compromised. When working against the crypt remote, rclone will automatically encrypt (before uploading) and decrypt (after downloading) on your local system as needed on the fly, leaving the data encrypted at rest in the wrapped remote. So your stuff is scrambled where it lives, and only you (well, your rclone) can read it. 🔥

> ⚠️ If you access the storage system using an application other than rclone, or access the wrapped remote directly using rclone, there will **not** be any encryption/decryption: Downloading existing content will just give you the encrypted (scrambled) format, and anything you upload will **not** become encrypted. No cap, that's the tea. 😭

Okay so the encryption here is a **secret-key encryption** (also called **symmetric key encryption**) algorithm, where a password (or pass phrase) is used to generate the *real* encryption key 🔐. That password can be supplied by you, the user, or you may chose to let rclone generate one. Either way it gets stored in the configuration file, in a lightly obscured form. If you are in an environment where you are not able to keep your configuration secured, you should add **configuration encryption** as protection. As long as you have this configuration file, you will be able to decrypt your data. Without the configuration file, as long as you remember the password (or keep it in a safe place), you can re-create the configuration and gain access to the existing data 👑. You may also configure a corresponding remote in a different installation to access the same data. See below for guidance to changing password.

Encryption uses a **cryptographic salt**, to permute the encryption key so that the same string may be encrypted in different ways 🧂✨. When configuring the crypt remote it is optional to enter a salt, or to let rclone generate a unique salt. If omitted, rclone uses a built-in unique string. Normally in cryptography, the salt is stored together with the encrypted content, and do not have to be memorized by the user. This is **not** the case in rclone, because rclone does not store any additional information on the remotes 😭. Use of custom salt is effectively a second password that must be memorized. Yeah. It's giving "two passwords, no notes".

File content encryption is performed using `NaCl SecretBox`, based on `XSalsa20` cipher and `Poly1305` for integrity 💅. Names (file- and directory names) are also encrypted by default, but this has some implications and is therefore possible to be turned off.

---

## 🎀 Configuration 🎀

Here is an example of how to make a remote called `secret`.

To use crypt, first set up the underlying remote. Follow the `rclone config` instructions for the specific backend.

Before configuring the crypt remote, check the underlying remote is working. In this example the underlying remote is called `remote`. We will configure a path `path` within this remote to contain the encrypted content. Anything inside `remote:path` will be encrypted and anything outside will not 🔥.

Configure crypt using `rclone config`. In this example the crypt remote is called `secret`, to differentiate it from the underlying remote.

When you are done you can use the crypt remote named `secret` just as you would with any other remote, e.g. `rclone copy D:\docs secret:\docs`, and rclone will encrypt and decrypt as needed on the fly ✨. If you access the wrapped remote `remote:path` directly you will **bypass the encryption**, and anything you read will be in encrypted form, and anything you write will be unencrypted 💀. To avoid issues it is best to configure a dedicated path for encrypted content, and access it exclusively through a crypt remote.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> secret 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 / Encrypt/Decrypt a remote \ "crypt" [snip] Storage> crypt ** See help for crypt backend at: https://rclone.org/crypt/ **

Remote to encrypt/decrypt. Normally should contain a ':' and a path, eg "myremote:path/to/dir", "myremote:bucket" or maybe "myremote:" (not recommended). Enter a string value. Press Enter for the default (""). remote> remote:path How to encrypt the filenames. Enter a string value. Press Enter for the default ("standard"). Choose a number from below, or type in your own value. / Encrypt the filenames. 1 | See the docs for the details. \ "standard" 2 / Very simple filename obfuscation. \ "obfuscate" / Don't encrypt the file names. 3 | Adds a ".bin" extension only. \ "off" filename_encryption> Option to either encrypt directory names or leave them intact.

NB If filename_encryption is "off" then this option will do nothing. Enter a boolean value (true or false). Press Enter for the default ("true"). Choose a number from below, or type in your own value 1 / Encrypt directory names. \ "true" 2 / Don't encrypt directory names, leave them intact. \ "false" directory_name_encryption> Password or pass phrase for encryption. y) Yes type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Password or pass phrase for salt. Optional but recommended. Should be different to the previous password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g/n> g Password strength in bits. 64 is just about memorable 128 is secure 1024 is the maximum Bits> 128 Your password is: JAsJvRcgR-_veXNfy_sGmQ Use this password? Please note that an obscured version of this password (and not the password itself) will be stored under your configuration file, so keep this generated password in a safe place. y) Yes (default) n) No y/n> Edit advanced config? (y/n) y) Yes n) No (default) y/n> Remote config

[secret] type = crypt remote = remote:path password = * ENCRYPTED * password2 = * ENCRYPTED *

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>


> **<hotpink>Important</hotpink>** 💀 The crypt password stored in `rclone.conf` is *lightly obscured*. That only protects it from cursory inspection. It is **not secure** unless configuration encryption of `rclone.conf` is specified. No cap, bestie.

A long passphrase is recommended, or `rclone config` can generate a random one 🌸.

The obscured password is created using `AES-CTR` with a static key. The IV (nonce) is stored verbatim at the beginning of the obscured password. This static key is shared between all versions of rclone 👑.

If you reconfigure rclone with the same passwords/passphrases elsewhere it will be compatible, but the obscured version will be **different** due to the different salt 🧂.

Rclone does **not** encrypt

- file length - this can be calculated within 16 bytes 📏
- modification time - used for syncing ⏰

---

## 🌈 Specifying the remote 🌈

When configuring the remote to encrypt/decrypt, you may specify any string that rclone accepts as a source/destination of other commands 💖.

The primary use case is to specify the path into an already configured remote (e.g. `remote:path/to/dir` or `remote:bucket`), such that data in a remote untrusted location can be stored encrypted 🔒.

You may also specify a local filesystem path, such as `/path/to/dir` on Linux, `C:\path\to\dir` on Windows. By creating a crypt remote pointing to such a local filesystem path, you can use rclone as a utility for pure local file encryption, for example to keep encrypted files on a removable USB drive 🫶.

Note: A string which do not contain a `:` will by rclone be treated as a relative path in the local filesystem. For example, if you enter the name `remote` without the trailing `:`, it will be treated as a subdirectory of the current directory with name “remote” 🙈.

If a path `remote:path/to/dir` is specified, rclone stores encrypted files in `path/to/dir` on the remote. With file name encryption, files saved to `secret:subdir/subfile` are stored in the unencrypted path `path/to/dir` but the `subdir/subpath` element is encrypted 👀.

The path you specify does not have to exist, rclone will create it when needed ✨.

If you intend to use the wrapped remote both directly for keeping unencrypted content, as well as through a crypt remote for encrypted content, it is recommended to point the crypt remote to a **separate directory** within the wrapped remote. If you use a bucket-based storage system (e.g. `Swift`, `S3`, `Google Compute Storage`, `B2`) it is generally advisable to wrap the crypt remote around a specific bucket (`s3:bucket`). If wrapping around the entire root of the storage (`s3:`), and use the optional file name encryption, rclone will encrypt the **bucket name** 💅.

---

## 🦋 Changing password 🦋

Should the password, or the configuration file containing a lightly obscured form of the password, be compromised, you need to re-encrypt your data with a new password. Since rclone uses secret-key encryption, where the encryption key is generated directly from the password kept on the client, it is **not possible** to change the password/key of already encrypted content 😭. Just changing the password configured for an existing crypt remote means you will no longer able to decrypt any of the previously encrypted content 💀. The only possibility is to re-upload everything via a crypt remote configured with your new password.

Depending on the size of your data, your bandwidth, storage quota etc, there are different approaches you can take:

- If you have everything in a different location, for example on your local system, you could remove all of the prior encrypted files, change the password for your configured crypt remote (or delete and re-create the crypt configuration), and then re-upload everything from the alternative location 🌸
- If you have enough space on the storage system you can create a new crypt remote pointing to a separate directory on the same backend, and then use rclone to copy everything from the original crypt remote to the new, effectively decrypting everything on the fly using the old password and re-encrypting using the new password. When done, delete the original crypt remote directory and finally the rclone crypt configuration with the old password. All data will be streamed from the storage system and back, so you will get **half the bandwidth** and be **charged twice** if you have upload and download quota on the storage system 🔥💸

> 🚨 **okay bestie we gotta talk about a glow-up that was actually a security patch.** There was a security problem related to the random password generator, and it got fixed in rclone version `1.53.3` (released 2020-11-19). Passwords generated by `rclone config` in version `1.49.0` (released 2019-08-26) to `1.53.2` (released 2020-10-26) are **not considered secure** and should be changed. 😭 If you made up your own password, or used rclone version older than `1.49.0` or newer than `1.53.2` to generate it, you are not affected by this issue, so you can unclench. See issue `#4783` for more details, and a tool you can use to check if you are affected.

---

## ✨ Example ✨

Create the following file structure using <pink>“standard”</pink> file name encryption.

plaintext/ ├── file0.txt ├── file1.txt └── subdir ├── file2.txt ├── file3.txt └── subsubdir └── file4.txt


Copy these to the remote, and list them

$ rclone -q copy plaintext secret: $ rclone -q ls secret: 7 file1.txt 6 file0.txt 8 subdir/file2.txt 10 subdir/subsubdir/file4.txt 9 subdir/file3.txt


The crypt remote looks like

$ rclone -q ls remote:path 55 hagjclgavj2mbiqm6u6cnjjqcg 54 v05749mltvv1tf4onltun46gls 57 86vhrsv86mpbtd3a0akjuqslj8/dlj7fkq4kdq72emafg7a7s41uo 58 86vhrsv86mpbtd3a0akjuqslj8/7uu829995du6o42n32otfhjqp4/b9pausrfansjth5ob3jkdqd4lc 56 86vhrsv86mpbtd3a0akjuqslj8/8njh1sk437gttmep3p70g81aps


The directory structure is preserved 🫶

$ rclone -q ls secret:subdir 8 file2.txt 9 file3.txt 10 subsubdir/file4.txt


Without file name encryption `.bin` extensions are added to underlying names. This prevents the cloud provider attempting to interpret file content.

$ rclone -q ls remote:path 54 file0.txt.bin 57 subdir/file3.txt.bin 56 subdir/file2.txt.bin 58 subdir/subsubdir/file4.txt.bin 55 file1.txt.bin


## 🎀 File name encryption modes 🎀

### <purple>Off</purple>

- doesn’t hide file names or directory structure
- allows for longer file names (~246 characters)
- can use sub paths and copy single files

### <purple>Standard</purple>

- file names encrypted
- file names can’t be as long (~143 characters)
- can use sub paths and copy single files
- directory structure visible
- identical files names will have identical uploaded names
- can use shortcuts to shorten the directory recursion

### <purple>Obfuscation</purple>

This is a simple <lavender>“rotate”</lavender> of the filename, with each file having a rot distance based on the filename. Rclone stores the distance at the beginning of the filename. A file called <cyan>“hello”</cyan> may become <cyan>“53.jgnnq”</cyan>. 🌀

Obfuscation is **not** a strong encryption of filenames, but it hinders automated scanning tools picking up on filename patterns. It is an intermediate between <pink>“off”</pink> and <pink>“standard”</pink> which allows for longer path segment names.

> There is a possibility with some unicode based filenames that the obfuscation is weak and may map lower case characters to upper case equivalents.

> <red>Obfuscation cannot be relied upon for strong protection.</red> 💀

- file names very lightly obfuscated
- file names can be longer than standard encryption
- can use sub paths and copy single files
- directory structure visible
- identical files names will have identical uploaded names

Cloud storage systems have limits on file name length and total path length which rclone is more likely to breach using <pink>“Standard”</pink> file name encryption. Where file names are `143` or fewer characters in length issues should not be encountered, irrespective of cloud storage provider.

An experimental advanced option `filename_encoding` is now provided to address this problem to a certain degree. For cloud storage systems with case sensitive file names (e.g. Google Drive), `base64` can be used to reduce file name length. For cloud storage systems using UTF-16 to store file names internally (e.g. OneDrive, Dropbox, Box), `base32768` can be used to drastically reduce file name length. 🔥

An alternative, future rclone file name encryption mode may tolerate backend provider path length limits.

## 🦋 Directory name encryption

Crypt offers the option of encrypting dir names or leaving them intact. There are two options:

### <mint>True</mint>

Encrypts the whole file path including directory names Example: `1/12/123.txt` is encrypted to `p0e52nreeaj0a5ea7s64m4j72s/l42g6771hnv3an9cgc8cr2n1ng/qgm4avr35m5loi1th53ato71v0`

### <mint>False</mint>

Only encrypts file names, skips directory names Example: `1/12/123.txt` is encrypted to `1/12/qgm4avr35m5loi1th53ato71v0`

## 🧚 Modification times and hashes

Crypt stores modification times using the underlying remote so support depends on that. 🕰️

Hashes are not stored for crypt. However the data integrity is protected by an <rainbow>extremely strong crypto authenticator</rainbow>. ✨

Use the `rclone cryptcheck` command to check the integrity of an encrypted remote instead of `rclone check` which can’t check the checksums properly.

---

## 👑 Standard options

Here are the Standard options specific to crypt (Encrypt/Decrypt a remote).

### `--crypt-remote`

Remote to encrypt/decrypt.

Normally should contain a `:` and a path, e.g. `"myremote:path/to/dir"`, `"myremote:bucket"` or maybe `"myremote:"` (not recommended).

Properties:

- Config: `remote`
- Env Var: `RCLONE_CRYPT_REMOTE`
- Type: `string`
- Required: `true`

### `--crypt-filename-encryption`

How to encrypt the filenames.

Properties:

- Config: `filename_encryption`
- Env Var: `RCLONE_CRYPT_FILENAME_ENCRYPTION`
- Type: `string`
- Default: `"standard"`
- Examples:
  - `"standard"`
    - Encrypt the filenames.
    - See the docs for the details.
  - `"obfuscate"`
    - Very simple filename obfuscation.
  - `"off"`
    - Don’t encrypt the file names.
    - Adds a `".bin"`, or `"suffix"` extension only.

### `--crypt-directory-name-encryption`

Option to either encrypt directory names or leave them intact.

> NB If `filename_encryption` is `"off"` then this option will do nothing.

Properties:

- Config: `directory_name_encryption`
- Env Var: `RCLONE_CRYPT_DIRECTORY_NAME_ENCRYPTION`
- Type: `bool`
- Default: `true`
- Examples:
  - `"true"`
    - Encrypt directory names.
  - `"false"`
    - Don’t encrypt directory names, leave them intact.

### `--crypt-password`

Password or pass phrase for encryption.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_CRYPT_PASSWORD`
- Type: `string`
- Required: `true`

### `--crypt-password2`

Password or pass phrase for salt.

Optional but recommended. Should be different to the previous password. 💅

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `password2`
- Env Var: `RCLONE_CRYPT_PASSWORD2`
- Type: `string`
- Required: `false`

---

## 💜 Advanced options

Here are the Advanced options specific to crypt (Encrypt/Decrypt a remote).

### `--crypt-server-side-across-configs`

Deprecated: use `--server-side-across-configs` instead.

Allow server-side operations (e.g. copy) to work across different crypt configs.

Normally this option is not what you want, but if you have two crypts pointing to the same backend you can use it.

This can be used, for example, to change file name encryption type without re-uploading all the data. Just make two crypt backends pointing to two different directories with the single changed parameter and use `rclone move` to move the files between the crypt remotes.

Properties:

- Config: `server_side_across_configs`
- Env Var: `RCLONE_CRYPT_SERVER_SIDE_ACROSS_CONFIGS`
- Type: `bool`
- Default: `false`

### `--crypt-show-mapping`

For all files listed show how the names encrypt.

If this flag is set then for each file that the remote is asked to list, it will log (at level `INFO`) a line stating the decrypted file name and the encrypted file name. 🔍

This is so you can work out which encrypted names are which decrypted names just in case you need to do something with the encrypted file names, or for debugging purposes.

Properties:

- Config: `show_mapping`
- Env Var: `RCLONE_CRYPT_SHOW_MAPPING`
- Type: `bool`
- Default: `false`

### `--crypt-no-data-encryption`

Option to either encrypt file data or leave it unencrypted.

Properties:

- Config: `no_data_encryption`
- Env Var: `RCLONE_CRYPT_NO_DATA_ENCRYPTION`
- Type: `bool`
- Default: `false`
- Examples:
  - `"true"`
    - Don’t encrypt file data, leave it unencrypted.
  - `"false"`
    - Encrypt file data.

### `--crypt-pass-bad-blocks`

If set this will pass bad blocks through as all `0`.

> This should **not** be set in normal operation, it should only be set if trying to recover an encrypted file with errors and it is desired to recover as much of the file as possible. 😭

Properties:

- Config: `pass_bad_blocks`
- Env Var: `RCLONE_CRYPT_PASS_BAD_BLOCKS`
- Type: `bool`
- Default: `false`

### `--crypt-strict-names`

If set, this will raise an error when crypt comes across a filename that can’t be decrypted.

(By default, rclone will just log a `NOTICE` and continue as normal.) This can happen if encrypted and unencrypted files are stored in the same directory (which is not recommended.) It may also indicate a more serious problem that should be investigated. 👀

Properties:

- Config: `strict_names`
- Env Var: `RCLONE_CRYPT_STRICT_NAMES`
- Type: `bool`
- Default: `false`

### `--crypt-filename-encoding`

How to encode the encrypted filename to text string.

This option could help with shortening the encrypted filename. The suitable option would depend on the way your remote count the filename length and if it’s case sensitive.

Properties:

- Config: `filename_encoding`
- Env Var: `RCLONE_CRYPT_FILENAME_ENCODING`
- Type: `string`
- Default: `"base32"`
- Examples:
  - `"base32"`
    - Encode using base32. Suitable for all remote.
  - `"base64"`
    - Encode using base64. Suitable for case sensitive remote.
  - `"base32768"`
    - Encode using base32768. Suitable if your remote counts UTF-16 or
    - Unicode codepoint instead of UTF-8 byte length. (Eg. Onedrive, Dropbox)

### `--crypt-suffix`

If this is set it will override the default suffix of `".bin"`.

---

Setting suffix to `none` gives you a <pink>completely empty suffix</pink>. Which is lowkey the move when your path length is on a diet and every byte counts. 🎀

Properties:

- **Config**: `suffix`
- **Env Var**: `RCLONE_CRYPT_SUFFIX`
- **Type**: string
- **Default**: `".bin"`

---

## 💖 OPTIONS 💖 (still going, bestie)

- **`--crypt-description`** — literally just a lil description of the remote, so future-you knows which vault this is. ✨

  Properties:

  - **Config**: `description`
  - **Env Var**: `RCLONE_CRYPT_DESCRIPTION`
  - **Type**: string
  - **Required**: false

---

## 📦 Metadata

Whatever metadata your underlying remote can handle? It gets read and written. No extra work needed. 🫶

Peep the metadata docs for the whole tea. ☕

---

## 🛠️ Backend commands

These are the commands that are special to the crypt backend, its lil signature moves. 💅

Run them like this:

rclone backend COMMAND remote:


The help below spills exactly which arguments each command takes.

Check out the backend command docs for the deets on passing options and arguments, iykyk. 👑

You can also run these on an already-running backend by using the rc command `backend/command`. 🌈

---

### 🔒 encode

Encode the filename(s) you hand over.

rclone backend encode remote: [options] [<arguments>+]


This encodes the filenames you gave as arguments and returns a list of strings of the encoded results. 🦋

Usage Example:

rclone backend encode crypt: file1 [file2...] rclone rc backend/command command=encode fs=crypt: file1 [file2...]


---

### 🔓 decode

Decode the filename(s) you hand over.

rclone backend decode remote: [options] [<arguments>+]


This decodes the filenames you gave as arguments and returns a list of strings of the decoded results. Heads up though — if any of the inputs are invalid, it's gonna return an error. 💀

Usage Example:

rclone backend decode crypt: encryptedfile1 [encryptedfile2...] rclone rc backend/command command=decode fs=crypt: encryptedfile1 [encryptedfile2...]


---

## 💾 Backing up an encrypted remote

Wanna back up an encrypted remote? Okay so the recommendation is: use `rclone sync` on the <hotpink>encrypted</hotpink> files, and make sure the passwords match in the new encrypted remote. That's the whole vibe. ✨

Here's why that's the serve:

- `rclone sync` will check the checksums while copying 👑
- you can use `rclone check` between the encrypted remotes
- you don't decrypt and encrypt unnecessarily — no wasted main character energy 🎀

Say your original remote lives at `remote:` and the encrypted version sits at `eremote:` with path `remote:crypt`. You'd set up the new remote `remote2:` and then the encrypted version `eremote2:` with path `remote2:crypt`, using the <rainbow>same passwords</rainbow> as `eremote:`.

To sync the two remotes you'd do:

rclone sync --interactive remote:crypt remote2:crypt


And to check the integrity you'd do:

rclone check remote:crypt remote2:crypt


---

## 🗂️ File formats

### 🔐 File encryption

Files are encrypted 1:1, source file straight to destination object. No merging, no games. The file has a header and is divided into chunks. 🧚

#### Header

- 8 bytes magic string `RCLONE\x00\x00`
- 24 bytes Nonce (IV)

The initial nonce comes from the operating system's crypto strong random number generator. Every chunk read bumps the nonce, making sure each nonce is unique per block written. The chance of a nonce being reused is <pink>minuscule</pink>. Like, if you wrote an exabyte of data (10¹⁸ bytes) you'd have a probability of roughly 2×10⁻³² of reusing a nonce. That's not a typo, it's just that tiny. 😭

#### Chunk

Each chunk carries 64 KiB of data, except the last one which may have less. The data chunk is in standard <lavender>NaCl SecretBox</lavender> format. SecretBox uses XSalsa20 and Poly1305 to encrypt and authenticate messages. 🔥

Each chunk contains:

- 16 Bytes of Poly1305 authenticator
- 1 - 65536 bytes XSalsa20 encrypted data

The 64k chunk size was picked as the best performing chunk size (the authenticator takes too much time below this, and performance drops off due to cache effects above this). Note that these chunks are buffered in memory, so they can't be too big. 🫶

This uses a 32 byte (256 bit key) key derived from the user password.

#### Examples

A 1 byte file will encrypt to:

- 32 bytes header
- 17 bytes data chunk

49 bytes total

A 1 MiB (1048576 bytes) file will encrypt to:

- 32 bytes header
- 16 chunks of 65568 bytes

1049120 bytes total (a 0.05% overhead). That's the overhead for the big files, bestie. ✨

---

### 🏷️ Name encryption

File names are encrypted segment by segment — the path is broken up into `/` separated strings, and these get encrypted individually. 🦋

File segments are padded using PKCS#7 to a multiple of 16 bytes before encryption.

Then they're encrypted with EME using AES with a 256 bit key. EME (ECB-Mix-ECB) is a wide-block encryption mode from the 2003 paper *"A Parallelizable Enciphering Mode"* by Halevi and Rogaway. 📚

This makes for deterministic encryption, which is exactly what we want — the same filename has to encrypt to the same thing, otherwise we can't find it on the cloud storage system. Periodt. 💅

This means that:

- filenames with the same name will encrypt the same
- filenames which start the same won't have a common prefix

This uses a 32 byte key (256 bits) and a 16 byte (128 bits) IV, both of which are derived from the user password.

After encryption they're written out using a modified version of standard base32 encoding as described in RFC4648. The standard encoding is modified in two ways:

- it becomes lower case (no-one likes upper case filenames!) 🙈
- we strip the padding character `=`

base32 is used rather than the more efficient base64 so rclone can be used on case insensitive remotes (e.g. Windows, Box, Dropbox, Onedrive etc). 👑

---

### 🔑 Key derivation

Rclone uses scrypt with parameters `N=16384`, `r=8`, `p=1`, with an optional user supplied salt (`password2`) to derive the 32+32+16 = 80 bytes of key material required. If the user doesn't supply a salt then rclone uses an internal one. 🧚

scrypt makes it impractical to mount a dictionary attack on rclone encrypted data. For full protection against this you should **always** use a salt. 💖

---

## 👀 SEE ALSO

- `rclone cryptdecode` — Show forward/reverse mapping of encrypted filenames

# 🦋 Compress 🦋

## ⚠️ Warning ⚠️

> This remote is currently experimental. Things may break and data may be lost. Anything you do with this remote is at your own risk. Please understand the risks associated with using experimental code and don't use this remote in critical applications.

okay so, real talk bestie — the <pink>Compress</pink> remote adds compression to another remote. It is best used with remotes containing many large compressible files. <rainbow>that's the whole vibe</rainbow> ✨

## 🎀 Configuration 🎀

To use this remote, all you need to do is specify another remote and a compression mode to use:

Current remotes:

Name Type ==== ==== remote_to_press sometype

e) Edit existing remote $ rclone config 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> compress ... 8 / Compress a remote \ "compress" ... Storage> compress ** See help for compress backend at: https://rclone.org/compress/ **

Remote to compress. Enter a string value. Press Enter for the default (""). remote> remote_to_press:subdir Compression mode. Enter a string value. Press Enter for the default ("gzip"). Choose a number from below, or type in your own value 1 / Gzip compression balanced for speed and compression strength. \ "gzip" compression_mode> gzip Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config

[compress] type = compress remote = remote_to_press:subdir compression_mode = gzip

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


## 🌸 Compression Modes 🌸

Currently only gzip compression is supported. It provides a decent balance between speed and size and is well supported by other applications. Compression strength can further be configured via an advanced setting where `0` is no compression and `9` is strongest compression. 💪

## 🍓 File types 🍓

If you open a remote wrapped by compress, you will see that there are <hotpink>many</hotpink> files with an extension corresponding to the compression algorithm you chose. These files are standard files that can be opened by various archive programs, but they have some hidden metadata that allows them to be used by rclone. While you may download and decompress these files at will, **do not manually delete or rename files**. Files without correct metadata files will not be recognized by rclone. 😭 no cap.

## 🧚 File names 🧚

The compressed files will be named `*.###########.gz` where `*` is the base file and the `#` part is base64 encoded size of the uncompressed file. The file names should not be changed by anything other than the rclone compression backend. <purple>hands off, bestie</purple> 🙈

## ✨ Standard options ✨

Here are the Standard options specific to compress (Compress a remote).

### 💅 `--compress-remote`

Remote to compress.

Properties:

- Config: `remote`
- Env Var: `RCLONE_COMPRESS_REMOTE`
- Type: string
- Required: true

### 💅 `--compress-mode`

Compression mode.

Properties:

- Config: `mode`
- Env Var: `RCLONE_COMPRESS_MODE`
- Type: string
- Default: `"gzip"`
- Examples:
  - `"gzip"`
    - Standard gzip compression with fastest parameters.

## 👑 Advanced options 👑

Here are the Advanced options specific to compress (Compress a remote).

### 🌈 `--compress-level`

GZIP compression level (`-2` to `9`).

Generally `-1` (default, equivalent to `5`) is recommended. Levels `1` to `9` increase compression at the cost of speed. Going past `6` generally offers very little return.

Level `-2` uses Huffman encoding only. Only use if you know what you are doing. Level `0` turns off compression.

Properties:

- Config: `level`
- Env Var: `RCLONE_COMPRESS_LEVEL`
- Type: int
- Default: `-1`

### 🌈 `--compress-ram-cache-limit`

Some remotes don't allow the upload of files with unknown size. In this case the compressed file will need to be cached to determine it's size.

Files smaller than this limit will be cached in RAM, files larger than this limit will be cached on disk.

Properties:

- Config: `ram_cache_limit`
- Env Var: `RCLONE_COMPRESS_RAM_CACHE_LIMIT`
- Type: SizeSuffix
- Default: `20Mi`

### 🌈 `--compress-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_COMPRESS_DESCRIPTION`
- Type: string
- Required: false

## 🫶 Metadata 🫶

Any metadata supported by the underlying remote is read and written.

See the metadata docs for more info.

---

# 💜 Combine 💜

The <pink>combine</pink> backend joins remotes together into a single directory tree. it's giving <rainbow>one directory to rule them all</rainbow> 👑

For example you might have a remote for images on one provider:

$ rclone tree s3:imagesbucket / ├── image1.jpg └── image2.jpg


And a remote for files on another:

$ rclone tree drive:important/files / ├── file1.txt └── file2.txt


The combine backend can join these together into a synthetic directory structure like this:

$ rclone tree combined: / ├── files │ ├── file1.txt │ └── file2.txt └── images ├── image1.jpg └── image2.jpg


You'd do this by specifying an `upstreams` parameter in the config like this

upstreams = images=s3:imagesbucket files=drive:important/files


During the initial setup with `rclone config` you will specify the upstreams remotes as a space separated list. The upstream remotes can either be a local paths or other remotes. 🦋

## 🎀 Configuration 🎀

Here is an example of how to make a combine called `remote` for the example above. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. ... XX / Combine several remotes into one \ (combine) ... Storage> combine Option upstreams. Upstreams for combining These should be in the form dir=remote:path dir2=remote2:path Where before the = is specified the root directory and after is the remote to put there. Embedded spaces can be added using quotes "dir=remote:path with space" "dir2=remote2:path with space" Enter a fs.SpaceSepList value. upstreams> images=s3:imagesbucket files=drive:important/files Configuration complete. Options:

type: combine
upstreams: images=s3:imagesbucket files=drive:important/files Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


## 🌈 Configuring for Google Drive Shared Drives 🌈

Rclone has a convenience feature for making a combine backend for all the shared drives you have access to. <hotpink>the way that it just does that</hotpink> 😭

Assuming your main (non shared drive) Google drive remote is called `drive:` you would run

rclone backend -o config drives drive:


This would produce something like this:

[My Drive] type = alias remote = drive,team_drive=0ABCDEF-01234567890,root_folder_id=:

[Test Drive] type = alias remote = drive,team_drive=0ABCDEFabcdefghijkl,root_folder_id=:

[AllDrives] type = combine upstreams = "My Drive=My Drive:" "Test Drive=Test Drive:"


If you then add that config to your config file (find it with `rclone config file`) then you can access all the shared drives in one place with the `AllDrives:` remote. obsessed 💖

See the Google Drive docs for full info.

## ✨ Standard options ✨

Here are the Standard options specific to combine (Combine several remotes into one).

### 💅 `--combine-upstreams`

Upstreams for combining

These should be in the form

dir=remote:path dir2=remote2:path


Where before the `=` is specified the root directory and after is the remote to put there.

Embedded spaces can be added using quotes

"dir=remote:path with space" "dir2=remote2:path with space"


Properties:

- Config: `upstreams`
- Env Var: `RCLONE_COMBINE_UPSTREAMS`
- Type: SpaceSepList
- Default:

## 👑 Advanced options 👑

Here are the Advanced options specific to combine (Combine several remotes into one).

### 🌟 `--combine-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_COMBINE_DESCRIPTION`
- Type: string
- Required: false

## 🫶 Metadata 🫶

Any metadata supported by the underlying remote is read and written.

See the metadata docs for more info.

---

# 🎀 Dropbox 🎀

Paths are specified as `remote:path`

Dropbox paths may be as deep as required, e.g. `remote:directory/subdirectory`. 📂

## 🦋 Configuration 🦋

The initial setup for dropbox involves getting a token from Dropbox 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:

rclone config


This will guide you through an interactive setup process:

n) New remote d) Delete remote q) Quit config e/n/d/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Dropbox \ "dropbox" [snip] Storage> dropbox Dropbox App Key - leave blank normally. app_key> Dropbox App Secret - leave blank normally. app_secret> Remote config Please visit: https://www.dropbox.com/1/oauth2/authorize?client_id=XXXXXXXXXXXXXXX&response_type=code Enter the code: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX Configuration complete. Options:

type: dropbox
app_key:
app_secret:
token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX_XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXX Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


okay bestie, lowkey important heads-up: if you're setting this up on a machine with **no Internet browser available**, go peep the remote setup docs, they got you covered 🫶

Also, a lil note: rclone spins up a <pink>webserver on your local machine</pink> to catch the token that Dropbox sends back. The way that it only runs from the moment it opens your browser to the moment you get back the verification code 💅 It lives at <cyan>`http://127.0.0.1:53682/`</cyan> and it might need you to unblock it temporarily if you're running a host firewall, or just use manual mode. no biggie.

Once that's done you can use it like this, fr fr:

List directories in top level of your dropbox

rclone lsd remote:


List all the files in your dropbox

rclone ls remote:


To copy a local directory to a dropbox directory called backup

rclone copy /home/source remote:backup


## 🌸 Dropbox for business 🌸

Rclone supports Dropbox for business and Team Folders. Yeah. We do it all 💅

When you're using Dropbox for business, <purple>`remote:`</purple> and <purple>`remote:path/to/file`</purple> will refer to your **personal folder**.

If you wish to see Team Folders you **must** use a leading `/` in the path, so `rclone lsd remote:/` will refer to the root and show you all Team Folders and your User Folder. iconic behaviour honestly.

You can then use team folders like this: `remote:/TeamFolder` and `remote:/TeamFolder/path/to/file`.

> ⚠️ Heads up: a leading `/` for a Dropbox **personal** account will do nothing, BUT it will take an extra HTTP transaction, so it should be avoided. kthanks bye 😌

## 🎀 Modification times and hashes 🎀

Dropbox supports modified times, but the *only* way to set a modification time is to re-upload the file. that's just how it is, ngl.

This means that if you uploaded your data with an older version of rclone which didn't support the v2 API and modified times, rclone will decide to upload **all your old data** to fix the modification times 😭 If you don't want this to happen, use `--size-only` or `--checksum` flag to stop it. periodt.

Dropbox supports its own hash type which is checked for all transfers. slay.

## 🦋 Restricted filename characters 🦋

- `NUL` — value `0x00` — gets replaced with `␀`
- `/` — value `0x2F` — gets replaced with `／`
- `DEL` — value `0x7F` — gets replaced with `␡`
- `\` — value `0x5C` — gets replaced with `＼`

File names can also **not end** with the following characters. These only get replaced if they are the *last* character in the name:

- `SP` — value `0x20` — gets replaced with `␠`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. facts are facts 💜

## ✨ Batch mode uploads ✨

Using batch mode uploads is **very important for performance** when using the Dropbox API. See the dropbox performance guide for more info. trust the process 🔥

There are <hotpink>3</hotpink> modes rclone can use for uploads.

### 💅 `--dropbox-batch-mode off`

In this mode rclone will **not** use upload batching. This was the default before rclone v1.55. Its downside? It's very likely to encounter `too_many_requests` errors like this:

NOTICE: too_many_requests/.: Too many requests or write operations. Trying again in 15 seconds.


When rclone receives these it has to wait for `15s` or sometimes `300s` before continuing, which *really* slows down transfers 💀

This will happen especially if `--transfers` is large, so this mode isn't recommended except for compatibility or investigating problems.

### 🫶 `--dropbox-batch-mode sync`

In this mode rclone will batch up uploads to the size specified by `--dropbox-batch-size` and commit them together.

Using this mode means you can use a much higher `--transfers` parameter (`32` or `64` works fine) without receiving `too_many_requests` errors. ate and left no crumbs 🍓

This mode ensures **full data integrity**. yesss.

Note that there may be a pause when quitting rclone while rclone finishes up the last batch using this mode. she just needs a sec to wrap up.

### 🌈 `--dropbox-batch-mode async`

In this mode rclone will batch up uploads to the size specified by `--dropbox-batch-size` and commit them together.

However it will **not** wait for the status of the batch to be returned to the caller. This means rclone can use a much bigger batch size (much bigger than `--transfers`), at the cost of not being able to check the status of the upload.

This provides the maximum possible upload speed especially with lots of small files, however rclone **can't check the file got uploaded properly** using this mode 😭 main character energy but make it risky.

If you are using this mode then using `rclone check` after the transfer completes is recommended. Or you could do an initial transfer with `--dropbox-batch-mode async` then do a final transfer with `--dropbox-batch-mode sync` (the default).

Note that there may be a pause when quitting rclone while rclone finishes up the last batch using this mode.

## ⭐ Standard options ⭐

Here are the Standard options specific to dropbox (Dropbox).

### 👑 `--dropbox-client-id`

OAuth Client Id.

Leave blank normally.

Properties:

- **Config:** `client_id`
- **Env Var:** `RCLONE_DROPBOX_CLIENT_ID`
- **Type:** string
- **Required:** false

### 👑 `--dropbox-client-secret`

OAuth Client Secret.

Leave blank normally.

Properties:

- **Config:** `client_secret`
- **Env Var:** `RCLONE_DROPBOX_CLIENT_SECRET`
- **Type:** string
- **Required:** false

## 💖 Advanced options 💖

Here are the Advanced options specific to dropbox (Dropbox).

### 🌟 `--dropbox-token`

OAuth Access Token as a JSON blob.

Properties:

- **Config:** `token`
- **Env Var:** `RCLONE_DROPBOX_TOKEN`
- **Type:** string
- **Required:** false

### 🌟 `--dropbox-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- **Config:** `auth_url`
- **Env Var:** `RCLONE_DROPBOX_AUTH_URL`
- **Type:** string
- **Required:** false

### 🌟 `--dropbox-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- **Config:** `token_url`
- **Env Var:** `RCLONE_DROPBOX_TOKEN_URL`
- **Type:** string
- **Required:** false

### 🌟 `--dropbox-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Properties:

- **Config:** `client_credentials`
- **Env Var:** `RCLONE_DROPBOX_CLIENT_CREDENTIALS`
- **Type:** bool
- **Default:** false

### 🌟 `--dropbox-chunk-size`

Upload chunk size (< 150Mi).

Any files larger than this will be uploaded in chunks of this size.

Note that chunks are buffered in memory (one at a time) so rclone can deal with retries. Setting this larger will increase the speed slightly (at most 10% for 128 MiB in tests) at the cost of using more memory. It can be set smaller if you are tight on memory.

Properties:

- **Config:** `chunk_size`
- **Env Var:** `RCLONE_DROPBOX_CHUNK_SIZE`
- **Type:** SizeSuffix
- **Default:** `48Mi`

### 🌟 `--dropbox-impersonate`

Impersonate this user when using a business account.

Note that if you want to use impersonate, you should make sure this flag is set when running `rclone config` as this will cause rclone to request the `members.read` scope which it won't normally. This is needed to lookup a members email address into the internal ID that dropbox uses in the API.

Using the `members.read` scope will require a Dropbox Team Admin to approve during the OAuth flow.

You will have to use your own App (setting your own `client_id` and `client_secret`) to use this option as currently rclone's default set of permissions doesn't include `members.read`. This can be added once v1.55 or later is in use everywhere.

Properties:

- **Config:** `impersonate`
- **Env Var:** `RCLONE_DROPBOX_IMPERSONATE`
- **Type:** string
- **Required:** false

### 🌟 `--dropbox-shared-files`

Instructs rclone to work on individual shared files.

In this mode rclone's features are **extremely limited** — only list (`ls`, `lsl`, etc.) operations and read operations (e.g. downloading) are supported in this mode. All other operations will be disabled. 💀 not the feature set we wanted but okay.

Properties:

- **Config:** `shared_files`
- **Env Var:** `RCLONE_DROPBOX_SHARED_FILES`
- **Type:** bool
- **Default:** false

### 🌟 `--dropbox-shared-folders`

Instructs rclone to work on shared folders.

When this flag is used with no path only the List operation is supported and all available shared folders will be listed. If you specify a path the first part will be interpreted as the name of shared folder. Rclone will then try to mount this shared to the root namespace. On success shared folder rclone proceeds normally. The shared folder is now pretty much a normal folder and all normal operations are supported. iconic, honestly.

Note that we don't unmount the shared folder afterwards so the `--dropbox-shared-folders` can be omitted after the first use of a particular shared folder.

See also `--dropbox-root-namespace` for an alternative way to work with shared folders.

Properties:

- **Config:** `shared_folders`
- **Env Var:** `RCLONE_DROPBOX_SHARED_FOLDERS`
- **Type:** bool
- **Default:** false

### 🌟 `--dropbox-pacer-min-sleep`

Minimum time to sleep between API calls.

Properties:

- **Config:** `pacer_min_sleep`
- **Env Var:** `RCLONE_DROPBOX_PACER_MIN_SLEEP`
- **Type:** Duration
- **Default:** `10ms`

### 🌟 `--dropbox-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_DROPBOX_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,BackSlash,Del,RightSpace,InvalidUtf8,Dot`

### 🌟 `--dropbox-root-namespace`

Specify a different Dropbox namespace ID to use as the root for all paths.

Properties:

- **Config:** `root_namespace`
- **Env Var:** `RCLONE_DROPBOX_ROOT_NAMESPACE`
- **Type:** string
- **Required:** false

### 🌟 `--dropbox-batch-mode`

Upload file batching `sync|async|off`.

This sets the batch mode used by rclone.

For full info see the main docs

Okay so `--dropbox-batch-mode` has <rainbow>3</rainbow> possible values and you genuinely have to pick one, no take-backs:

- **`off`** — no batching. One file at a time, like a Victorian child 👑
- **`sync`** — batch uploads *and* check completion. This is the default, bestie 💖
- **`async`** — batch uploads and *don't* check completion. Chaos mode, lowkey respect 😭

Also rclone will close any outstanding batches when it exits, which may make a delay on quit. So don't panic when it hangs for a sec 🫶

**Properties:**

- **Config:** `batch_mode`
- **Env Var:** `RCLONE_DROPBOX_BATCH_MODE`
- **Type:** `string`
- **Default:** `"sync"`

- **`--dropbox-batch-size`** — max number of files in an upload batch 💅

  This sets the batch size of files to upload, and bestie it **has** to be less than `1000`. That's the ceiling, do not test it.

  By default this is `0`, which means rclone will calculate the batch size depending on the setting of `batch_mode`:

  - `batch_mode: async` — default `batch_size` is `100`
  - `batch_mode: sync` — default `batch_size` is the same as `--transfers`
  - `batch_mode: off` — not in use

  Rclone will close any outstanding batches when it exits which may make a delay on quit.

  Setting this is a <hotpink>great idea</hotpink> if you are uploading lots of small files, because it will make them a lot quicker. You can use `--transfers 32` to maximise throughput. Slay ✨

  **Properties:**

  - **Config:** `batch_size`
  - **Env Var:** `RCLONE_DROPBOX_BATCH_SIZE`
  - **Type:** `int`
  - **Default:** `0`

- **`--dropbox-batch-timeout`** — max time to allow an idle upload batch before uploading it ⏰

  If an upload batch is idle for more than this long, then it will be uploaded. Simple as that.

  The default for this is `0`, which means rclone will choose a sensible default based on the `batch_mode` in use:

  - `batch_mode: async` — default `batch_timeout` is `10s`
  - `batch_mode: sync` — default `batch_timeout` is `500ms`
  - `batch_mode: off` — not in use

  **Properties:**

  - **Config:** `batch_timeout`
  - **Env Var:** `RCLONE_DROPBOX_BATCH_TIMEOUT`
  - **Type:** `Duration`
  - **Default:** `0s`

- **`--dropbox-batch-commit-timeout`** — max time to wait for a batch to finish committing, and then we move on 🦋

  **Properties:**

  - **Config:** `batch_commit_timeout`
  - **Env Var:** `RCLONE_DROPBOX_BATCH_COMMIT_TIMEOUT`
  - **Type:** `Duration`
  - **Default:** `10m0s`

- **`--dropbox-description`** — description of the remote 📝

  **Properties:**

  - **Config:** `description`
  - **Env Var:** `RCLONE_DROPBOX_DESCRIPTION`
  - **Type:** `string`
  - **Required:** `false`

## 🌸 Limitations 🌸

Note that Dropbox is case insensitive, so you literally can't have a file called `Hello.doc` and one called `hello.doc`. To Dropbox they're the same file, bestie, pick one 💀

There are some file names such as `thumbs.db` which Dropbox can't store. There's a full list of them in the "Ignored Files" section of this document. Rclone will issue an error message `File name disallowed - not uploading` if it attempts to upload one of those file names, but the sync won't fail. So it's giving minor inconvenience, not giving whole disaster 🫶

Some errors may occur if you try to sync copyright-protected files because Dropbox has its own copyright detector that prevents this sort of file being downloaded. This will return the error:

ERROR : /path/to/your/file: Failed to copy: failed to open source object: path/restricted_content/


If you have more than `10,000` files in a directory then `rclone purge dropbox:dir` will return the error `Failed to purge: There are too many files involved in this operation.` As a work-around, do an `rclone delete dropbox:dir` followed by an `rclone rmdir dropbox:dir`. Two steps instead of one, we move 🏃‍♀️

When using `rclone link` you'll need to set `--expire` if using a non-personal account, otherwise the visibility may not be correct. (Note that `--expire` isn't supported on personal accounts.) See the forum discussion and the dropbox SDK issue.

---

## ✨ Get your own Dropbox App ID ✨

When you use rclone with Dropbox in its default configuration you are using *rclone's* App ID. This is shared between all the rclone users. Very communal of us, but sometimes you want your own 👑

Here is how to create your own Dropbox App ID for rclone:

1. Log into the Dropbox App console with your Dropbox Account (it need not be the same account as the Dropbox you want to access)
2. Choose an API => usually this should be `Dropbox API`
3. Choose the type of access you want to use => `Full Dropbox` or `App Folder`. If you want to use Team Folders, `Full Dropbox` is required (see here).
4. Name your App. The app name is global, so you can't use `rclone` for example 💀
5. Click the button `Create App`
6. Switch to the `Permissions` tab. Enable at least the following permissions: `account_info.read`, `files.metadata.write`, `files.content.write`, `files.content.read`, `sharing.write`. The `files.metadata.read` and `sharing.read` checkboxes will be marked too. Click `Submit` ✅
7. Switch to the `Settings` tab. Fill `OAuth2 - Redirect URIs` as `http://localhost:53682/` and click on `Add`
8. Find the `App key` and `App secret` values on the `Settings` tab. Use these values in `rclone config` to add a new remote or edit an existing remote. The `App key` setting corresponds to `client_id` in rclone config, the `App secret` corresponds to `client_secret`

# 💖 Enterprise File Fabric 💖

This backend is lowkey obsessed with Storage Made Easy's Enterprise File Fabric™, which is a whole software situation that integrates and unifies File and Object Storage, all accessible through a global file system. Slay. 🌈

---

## ✨ Configuration ✨

Okay bestie, the initial setup means you gotta get a token from the Enterprise File Fabric, and yes, you do that in your browser like a normal person. `rclone config` literally walks you through the whole thing, hand in hand. 🫶

Here's how you make a remote called `remote`, step by step. First run:

rclone config


And it'll hold your hand through an interactive setup process that looks like this:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Enterprise File Fabric \ "filefabric" [snip] Storage> filefabric ** See help for filefabric backend at: https://rclone.org/filefabric/ **

URL of the Enterprise File Fabric to connect to Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Storage Made Easy US \ "https://storagemadeeasy.com" 2 / Storage Made Easy EU \ "https://eu.storagemadeeasy.com" 3 / Connect to your Enterprise File Fabric \ "https://yourfabric.smestorage.com" url> https://yourfabric.smestorage.com/ ID of the root folder Leave blank normally.

Fill in to make rclone start with directory of a given ID.

Enter a string value. Press Enter for the default (""). root_folder_id> Permanent Authentication Token

A Permanent Authentication Token can be created in the Enterprise File Fabric, on the users Dashboard under Security, there is an entry you'll see called "My Authentication Tokens". Click the Manage button to create one.

These tokens are normally valid for several years.

For more info see: https://docs.storagemadeeasy.com/organisationcloud/api-tokens

Enter a string value. Press Enter for the default (""). permanent_token> xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config Configuration complete. Options:

type: filefabric
url: https://yourfabric.smestorage.com/
permanent_token: xxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once you're configured, you can use `rclone` like this, and honestly it's giving main character energy 💅

Want the directories at the top level of your Enterprise File Fabric? Say less:

rclone lsd remote:


Want ALL the files in your Enterprise File Fabric? Periodt:

rclone ls remote:


And to copy a local directory into an Enterprise File Fabric directory called `backup`:

rclone copy /home/source remote:backup


---

## 🕐 Modification times and hashes 🕐

The Enterprise File Fabric lets modification times be set on files, and they're accurate to **1 second**. rclone uses those to figure out whether objects need syncing or not. Iconic. ✨

But heads up: the Enterprise File Fabric does **not** support any data hashes at this time. Not a single one. 💀

---

## 🚫 Restricted filename characters 🚫

The default restricted characters set gets replaced.

Invalid UTF-8 bytes will also get replaced, because they literally cannot be used in JSON strings. No cap.

---

## 🫙 Empty files 🫙

Empty files aren't supported by the Enterprise File Fabric, which is so rude of it 😭. So instead, rclone uploads an empty file as a **single space** with a mime type of `application/vnd.rclone.empty.file`, and any files with that mime type are treated as empty. Clever little workaround, ate. 💅

---

## 📂 Root folder ID 📂

You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone considers to be the root of your Enterprise File Fabric.

Normally you'll leave this blank and rclone will figure out the correct root to use all by itself. Independent queen. 👑

But you *can* set this to restrict rclone to a specific folder hierarchy.

To do that, you'll have to find the Folder ID of the directory you want rclone to display. These aren't shown in the web interface, but you can use `rclone lsf` to find them, like:

$ rclone lsf --dirs-only -Fip --csv filefabric: 120673758,Burnt PDFs/ 120673759,My Quick Uploads/ 120673755,My Syncs/ 120673756,My backups/ 120673757,My contacts/ 120673761,S3 Storage/


So the ID for "S3 Storage" would be `120673761`. Got it? Got it. 🎀

---

## 🌟 Standard options 🌟

Here are the Standard options specific to `filefabric` (Enterprise File Fabric). Bestie, these are the ones you actually set:

### –filefabric-url

URL of the Enterprise File Fabric to connect to.

Properties:

- Config: `url`
- Env Var: `RCLONE_FILEFABRIC_URL`
- Type: `string`
- Required: `true`
- Examples:
  - `"https://storagemadeeasy.com"`
    - Storage Made Easy US
  - `"https://eu.storagemadeeasy.com"`
    - Storage Made Easy EU
  - `"https://yourfabric.smestorage.com"`
    - Connect to your Enterprise File Fabric

### –filefabric-root-folder-id

ID of the root folder.

Leave blank normally.

Fill in to make rclone start with directory of a given ID.

Properties:

- Config: `root_folder_id`
- Env Var: `RCLONE_FILEFABRIC_ROOT_FOLDER_ID`
- Type: `string`
- Required: `false`

### –filefabric-permanent-token

Permanent Authentication Token.

A Permanent Authentication Token can be created in the Enterprise File Fabric, on the users Dashboard under Security, there is an entry you'll see called "My Authentication Tokens". Click the Manage button to create one.

These tokens are normally valid for several years. Long-lived king. 🔥

For more info see: https://docs.storagemadeeasy.com/organisationcloud/api-tokens

Properties:

- Config: `permanent_token`
- Env Var: `RCLONE_FILEFABRIC_PERMANENT_TOKEN`
- Type: `string`
- Required: `false`

---

## 🧚 Advanced options 🧚

Here are the Advanced options specific to `filefabric` (Enterprise File Fabric). Like, you probably shouldn't touch most of these unless you know what you're doing. Iykyk. 🙈

### –filefabric-token

Session Token.

This is a session token which rclone caches in the config file. It is usually valid for `1 hour`.

> Don't set this value - rclone will set it automatically. Seriously bestie, hands off. 🖐️

Properties:

- Config: `token`
- Env Var: `RCLONE_FILEFABRIC_TOKEN`
- Type: `string`
- Required: `false`

### –filefabric-token-expiry

Token expiry time.

> Don't set this value - rclone will set it automatically. It's not your job, it's rclone's. 💜

Properties:

- Config: `token_expiry`
- Env Var: `RCLONE_FILEFABRIC_TOKEN_EXPIRY`
- Type: `string`
- Required: `false`

### –filefabric-version

Version read from the file fabric.

> Don't set this value - rclone will set it automatically. Let it cook. 🍓

Properties:

- Config: `version`
- Env Var: `RCLONE_FILEFABRIC_VERSION`
- Type: `string`
- Required: `false`

### –filefabric-encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_FILEFABRIC_ENCODING`
- Type: `Encoding`
- Default: `Slash,Del,Ctl,InvalidUtf8,Dot`

### –filefabric-description

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_FILEFABRIC_DESCRIPTION`
- Type: `string`
- Required: `false`

---

There you go bestie, Enterprise File Fabric fully understood, no notes, 10/10. 🦋

# 💾 Files.com

<rainbow>okay bestie, Files.com is a cloud storage service that gives you a secure and easy way to store and share files</rainbow> ✨

Setting it up the first time is all about authenticating with your Files.com account. You can do that by handing over your site subdomain, username, and password. OR, if that's not your vibe, you can authenticate using an API Key from Files.com instead. Either way, `rclone config` walks you through it, hand in hand 🫶

---

## Configuration 🎀

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> remote

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Files.com \ "filescom" [snip] Storage> filescom

Option site. Your site subdomain (e.g. mysite) or custom domain (e.g. myfiles.customdomain.com) Enter a value. Press Enter to leave empty. site> mysite

Option username. The username used to authenticate with Files.com. Enter a value. Press Enter to leave empty. username> user

Option password. The password used to authenticate with Files.com. Choose an alternative below. Press Enter for the default (n). y) Yes, type in my own password g) Generate random password n) No, leave this optional password blank (default) y/g/n> y Enter the password: password: Confirm the password: password:

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: filescom
site: mysite
username: user
password: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can use rclone. 💅

See all files in the top level:

rclone lsf remote:


Make a new directory in the root:

rclone mkdir remote:dir


Recursively List the contents:

rclone ls remote:


Sync `/home/local/directory` to the remote directory, deleting any excess files in the directory.

rclone sync --interactive /home/local/directory remote:dir


---

## Standard options ⭐

Here are the Standard options specific to filescom (Files.com).

### `--filescom-site`

Your site subdomain (e.g. `mysite`) or custom domain (e.g. `myfiles.customdomain.com`).

Properties:

- Config: `site`
- Env Var: `RCLONE_FILESCOM_SITE`
- Type: string
- Required: false

### `--filescom-username`

The username used to authenticate with Files.com.

Properties:

- Config: `username`
- Env Var: `RCLONE_FILESCOM_USERNAME`
- Type: string
- Required: false

### `--filescom-password`

The password used to authenticate with Files.com.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_FILESCOM_PASSWORD`
- Type: string
- Required: false

---

## Advanced options 🔥

Here are the Advanced options specific to filescom (Files.com).

### `--filescom-api-key`

The API key used to authenticate with Files.com.

Properties:

- Config: `api_key`
- Env Var: `RCLONE_FILESCOM_API_KEY`
- Type: string
- Required: false

### `--filescom-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_FILESCOM_ENCODING`
- Type: Encoding
- Default: `Slash,BackSlash,Del,Ctl,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot`

### `--filescom-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_FILESCOM_DESCRIPTION`
- Type: string
- Required: false

---

# 🌐 FTP

<cyan>FTP</cyan> is the File Transfer Protocol. Rclone FTP support is provided using the `github.com/jlaffaye/ftp` package. No cap 🧚

<purple>Limitations of Rclone's FTP backend</purple>

Paths are specified as `remote:path`. If the path does not begin with a `/` it is relative to the home directory of the user. An empty path `remote:` refers to the user's home directory.

---

## Configuration 💖

To create an FTP configuration named `remote`, run

rclone config


Rclone config guides you through an interactive setup process. A minimal rclone FTP remote definition only requires `host`, `username` and `password`. For an anonymous FTP server, see below. 👇

No remotes found, make a new one? n) New remote r) Rename remote c) Copy remote s) Set configuration password q) Quit config n/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 / FTP \ "ftp" [snip] Storage> ftp ** See help for ftp backend at: https://rclone.org/ftp/ **

FTP host to connect to Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Connect to ftp.example.com \ "ftp.example.com" host> ftp.example.com FTP username Enter a string value. Press Enter for the default ("$USER"). user> FTP port number Enter a signed integer. Press Enter for the default (21). port> FTP password y) Yes type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Use FTP over TLS (Implicit) Enter a boolean value (true or false). Press Enter for the default ("false"). tls> Use FTP over TLS (Explicit) Enter a boolean value (true or false). Press Enter for the default ("false"). explicit_tls> Remote config Configuration complete. Options:

type: ftp
host: ftp.example.com
pass: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


To see all directories in the home directory of `remote`

rclone lsd remote:


Make a new directory

rclone mkdir remote:path/to/directory


List the contents of a directory

rclone ls remote:path/to/directory


Sync `/home/local/directory` to the remote directory, deleting any excess files in the directory.

rclone sync --interactive /home/local/directory remote:directory


---

## Anonymous FTP 🙈

When connecting to a FTP server that allows anonymous login, you can use the special "anonymous" username. Traditionally, this user account accepts *any* string as a password, although it is common to use either the password "anonymous" or "guest". Some servers require the use of a valid e-mail address as password. 📧

Using on-the-fly or connection string remotes makes it easy to access such servers, without requiring any configuration in advance. The following are examples of that:

rclone lsf :ftp: --ftp-host=speedtest.tele2.net --ftp-user=anonymous --ftp-pass=$(rclone obscure dummy) rclone lsf :ftp,host=speedtest.tele2.net,user=anonymous,pass=$(rclone obscure dummy):


The above examples work in Linux shells and in PowerShell, but **not** Windows Command Prompt. They execute the `rclone obscure` command to create a password string in the format required by the `pass` option. The following examples are exactly the same, except use an already obscured string representation of the same password "dummy", and therefore works even in Windows Command Prompt:

rclone lsf :ftp: --ftp-host=speedtest.tele2.net --ftp-user=anonymous --ftp-pass=IXs2wc8OJOz7SYLBk47Ji1rHTmxM rclone lsf :ftp,host=speedtest.tele2.net,user=anonymous,pass=IXs2wc8OJOz7SYLBk47Ji1rHTmxM:


---

## Implicit TLS 🔐

Rclone FTP supports implicit FTP over TLS servers (FTPS). This has to be enabled in the FTP backend config for the remote, or with `--ftp-tls`. The default FTPS port is `990`, not `21` and can be set with `--ftp-port`.

---

## Restricted filename characters 🚫

In addition to the default restricted characters set the following characters are also replaced:

File names cannot end with the following characters. Replacement is limited to the last character in a file name:

- `SP` — Value `0x20` — Replacement `␠`

Not all FTP servers can have all characters in file names, for example:

- `proftpd` — Forbidden characters: `*`
- `pureftpd` — Forbidden characters: `\ [ ]`

This backend's interactive configuration wizard provides a selection of sensible encoding settings for major FTP servers: ProFTPd, PureFTPd, VsFTPd. Just hit a selection number when prompted. 🎯

---

## Standard options 👑

Here are the Standard options specific to ftp (FTP).

### `--ftp-host`

FTP host to connect to.

E.g. "ftp.example.com".

Properties:

- Config: `host`
- Env Var: `RCLONE_FTP_HOST`
- Type: string
- Required: true

### `--ftp-user`

FTP username.

Properties:

- Config: `user`
- Env Var: `RCLONE_FTP_USER`
- Type: string
- Default: "$USER"

### `--ftp-port`

FTP port number.

Properties:

- Config: `port`
- Env Var: `RCLONE_FTP_PORT`
- Type: int
- Default: `21`

### `--ftp-pass`

FTP password.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `pass`
- Env Var: `RCLONE_FTP_PASS`
- Type: string
- Required: false

### `--ftp-tls`

Use Implicit FTPS (FTP over TLS).

When using implicit FTP over TLS the client connects using TLS right from the start which breaks compatibility with non-TLS-aware servers. This is usually served over port `990` rather than port `21`. Cannot be used in combination with explicit FTPS.

Properties:

- Config: `tls`
- Env Var: `RCLONE_FTP_TLS`
- Type: bool
- Default: `false`

- **`--ftp-explicit-tls`** — use Explicit FTPS, aka FTP over TLS, bestie 🔐

  When you go explicit FTP over TLS, the client literally *asks* the server for security so it can upgrade a plain-text connection into an encrypted one. So polite. So demure. But heads up: <red>you cannot use this together with implicit FTPS</red>. Pick one, periodt.

  Properties:

  - Config: `explicit_tls`
  - Env Var: `RCLONE_FTP_EXPLICIT_TLS`
  - Type: bool
  - Default: `false`

---

### ✨ Advanced options ✨

okay so these are the <purple>Advanced</purple> options that are specific to `ftp` (FTP). slay.

- **`--ftp-concurrency`** — max number of FTP simultaneous connections, or `0` for unlimited 🌈

  > <red>ngl, setting this is *very likely* to cause deadlocks</red>, so use it with care fr fr.

  If you're doing a sync or copy then make sure concurrency is one *more* than the sum of `--transfers` and `--checkers`.

  If you use `--check-first` then it just needs to be one more than the maximum of `--checkers` and `--transfers`.

  So for concurrency `3` you'd use `--checkers 2 --transfers 2 --check-first` or `--checkers 1 --transfers 1`.

  Properties:

  - Config: `concurrency`
  - Env Var: `RCLONE_FTP_CONCURRENCY`
  - Type: int
  - Default: `0`

- **`--ftp-no-check-certificate`** — do not verify the TLS certificate of the server 🙈

  Properties:

  - Config: `no_check_certificate`
  - Env Var: `RCLONE_FTP_NO_CHECK_CERTIFICATE`
  - Type: bool
  - Default: `false`

- **`--ftp-disable-epsv`** — disable using EPSV, even if the server is out here advertising support 💅

  Properties:

  - Config: `disable_epsv`
  - Env Var: `RCLONE_FTP_DISABLE_EPSV`
  - Type: bool
  - Default: `false`

- **`--ftp-disable-mlsd`** — disable using MLSD, even if the server advertises support 🦋

  Properties:

  - Config: `disable_mlsd`
  - Env Var: `RCLONE_FTP_DISABLE_MLSD`
  - Type: bool
  - Default: `false`

- **`--ftp-disable-utf8`** — disable using UTF-8, even if the server advertises support 🌸

  Properties:

  - Config: `disable_utf8`
  - Env Var: `RCLONE_FTP_DISABLE_UTF8`
  - Type: bool
  - Default: `false`

- **`--ftp-writing-mdtm`** — use MDTM to set modification time (this one is the VsFtpd quirk, iykyk) ⏰

  Properties:

  - Config: `writing_mdtm`
  - Env Var: `RCLONE_FTP_WRITING_MDTM`
  - Type: bool
  - Default: `false`

- **`--ftp-force-list-hidden`** — use `LIST -a` to force listing of hidden files and folders 👀

  > <yellow>This will disable the use of MLSD.</yellow>

  Properties:

  - Config: `force_list_hidden`
  - Env Var: `RCLONE_FTP_FORCE_LIST_HIDDEN`
  - Type: bool
  - Default: `false`

- **`--ftp-idle-timeout`** — max time before closing idle connections 😴

  If no connections have been returned to the connection pool in the time given, rclone will empty the connection pool.

  Set to `0` to keep connections indefinitely.

  Properties:

  - Config: `idle_timeout`
  - Env Var: `RCLONE_FTP_IDLE_TIMEOUT`
  - Type: Duration
  - Default: `1m0s`

- **`--ftp-close-timeout`** — maximum time to wait for a response to close ⏳

  Properties:

  - Config: `close_timeout`
  - Env Var: `RCLONE_FTP_CLOSE_TIMEOUT`
  - Type: Duration
  - Default: `1m0s`

- **`--ftp-tls-cache-size`** — size of the TLS session cache for all control and data connections 🎀

  The TLS cache lets you resume TLS sessions and reuse the PSK between connections. Increase it if the default size isn't enough and you're getting TLS resumption errors. It's enabled by default. Use `0` to disable.

  Properties:

  - Config: `tls_cache_size`
  - Env Var: `RCLONE_FTP_TLS_CACHE_SIZE`
  - Type: int
  - Default: `32`

- **`--ftp-disable-tls13`** — disable TLS 1.3 (this is the workaround for FTP servers with buggy TLS, no cap) 💀

  Properties:

  - Config: `disable_tls13`
  - Env Var: `RCLONE_FTP_DISABLE_TLS13`
  - Type: bool
  - Default: `false`

- **`--ftp-shut-timeout`** — maximum time to wait for data connection closing status 🫶

  Properties:

  - Config: `shut_timeout`
  - Env Var: `RCLONE_FTP_SHUT_TIMEOUT`
  - Type: Duration
  - Default: `1m0s`

- **`--ftp-ask-password`** — allow asking for the FTP password when it's needed 🔑

  If this is set and no password is supplied, then rclone will ask for a password.

  Properties:

  - Config: `ask_password`
  - Env Var: `RCLONE_FTP_ASK_PASSWORD`
  - Type: bool
  - Default: `false`

- **`--ftp-socks-proxy`** — Socks 5 proxy host 🧦

  Supports the format `user:pass@host:port`, `user@host:port`, `host:port`.

  Example:

myUser:myPass@localhost:9005


Properties:

- Config: `socks_proxy`
- Env Var: `RCLONE_FTP_SOCKS_PROXY`
- Type: string
- Required: false

- **`--ftp-no-check-upload`** — don't check that the upload is OK 🙅‍♀️

Normally rclone will try to check the upload exists after it has uploaded a file, just to make sure the size and modification time are as expected.

This flag stops rclone from doing those checks. This enables uploading to folders which are write only.

You will likely need to use the `--inplace` flag also if you're uploading to a write only folder.

Properties:

- Config: `no_check_upload`
- Env Var: `RCLONE_FTP_NO_CHECK_UPLOAD`
- Type: bool
- Default: `false`

- **`--ftp-encoding`** — the encoding for the backend ✨

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_FTP_ENCODING`
- Type: Encoding
- Default: `Slash,Del,Ctl,RightSpace,Dot`
- Examples:

  - `"Asterisk,Ctl,Dot,Slash"`

    - ProFTPd can't handle `'*'` in file names

  - `"BackSlash,Ctl,Del,Dot,RightSpace,Slash,SquareBracket"`

    - PureFTPd can't handle `` `[]' `` or `'*'` in file names

  - `"Ctl,LeftPeriod,Slash"`

    - VsFTPd can't handle file names starting with dot

- **`--ftp-description`** — description of the remote 📝

Properties:

- Config: `description`
- Env Var: `RCLONE_FTP_DESCRIPTION`
- Type: string
- Required: false

---

### 🚧 Limitations 🚧

FTP servers acting as rclone remotes **must** support passive mode. The mode cannot be configured, because passive is the only supported one. Rclone's FTP implementation is not compatible with active mode, since the library it uses doesn't support it. And honestly? This will likely never be supported, on account of security concerns. so that's that 💅

Rclone's FTP backend does not support any checksums, but it can compare file sizes.

`rclone about` is not supported by the FTP backend. Backends without this capability cannot determine free space for an rclone mount, or use policy `mfs` (most free space) as a member of an `rclone union` remote.

See <cyan>List of backends that do not support rclone about</cyan> and <cyan>rclone about</cyan>

The implementation of:
- `--dump headers`
- `--dump bodies`
- `--dump auth`

for debugging isn't the same as for rclone HTTP based backends — it has less fine grained control.

`--timeout` isn't supported (but `--contimeout` is).

`--bind` isn't supported.

Rclone's FTP backend could support server-side move but does not at present.

The `ftp_proxy` environment variable is not currently supported.

---

### 🕰️ Modification times 🕰️

File modification time (timestamps) is supported to 1 second resolution for the major FTP servers: ProFTPd, PureFTPd, VsFTPd, and FileZilla FTP server. The VsFTPd server has a non-standard implementation of time related protocol commands and needs a special configuration setting: `writing_mdtm = true`.

Support for precise file time with other FTP servers varies depending on what protocol extensions they advertise. If all the MLSD, MDTM and MFTM extensions are present, rclone will use them together to provide precise time. Otherwise the times you see on the FTP server through rclone are those of the last file upload.

You can use the following command to check whether rclone can use precise time with your FTP server: `rclone backend features your_ftp_remote:` (the trailing colon is important). Look for the number in the line tagged by `Precision` designating the remote time precision expressed as nanoseconds. A value of `1000000000` means that file time precision of 1 second is available. A value of `3153600000000000000` (or another large number) means "unsupported". iconic behaviour honestly 🌟

# 💖 Gofile 💖

<cyan>Gofile</cyan> is a content storage and distribution platform, bestie. Its whole vibe is giving you as much service as possible for free or at a *very* low price. 🫶

The initial setup for Gofile involves logging in to the web interface and going to the <hotpink>“My Profile”</hotpink> section. Copy the <hotpink>“Account API token”</hotpink> — that's what goes in the config file. 📋✨

> ⚠️ Heads up queen: if you wish to connect rclone to Gofile you will need a **premium account**. No cap. 💸

---

## ✨ Configuration ✨

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> remote

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. XX / Gofile \ (gofile) Storage> gofile

Option access_token. API Access token You can get this from the web control panel. Enter a value. Press Enter to leave empty. access_token> YOURACCESSTOKEN

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: gofile
access_token: YOURACCESSTOKEN Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can then use rclone like this — list directories and files in the top level of your Gofile:

rclone lsf remote:


To copy a local directory to an Gofile directory called `backup`:

rclone copy /home/source remote:backup


---

## 🕰️ Modification times and hashes 🕰️

Gofile supports modification times with a resolution of <purple>1 second</purple>. Periodt. ⏱️

Gofile supports <mint>MD5</mint> hashes, so you can use the `--checksum` flag. 🧬✨

---

## 🚫 Restricted filename characters 🚫

In addition to the default restricted characters set, the following characters are **also** replaced:

- `!` — value `0x21` — replaced with `！`
- `”` — value `0x22` — replaced with `＂`
- `*` — value `0x2A` — replaced with `＊`
- `:` — value `0x3A` — replaced with `：`
- `<` — value `0x3C` — replaced with `＜`
- `>` — value `0x3E` — replaced with `＞`
- `?` — value `0x3F` — replaced with `？`
- `\` — value `0x5C` — replaced with `＼`
- `|` — value `0x7C` — replaced with `｜`

File names can also **not** start or end with the following characters. These only get replaced if they are the first or last character in the name:

- `.` — value `0x2E` — replaced with `．`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 😭

---

## 🔗 Public Links 🔗

Gofile supports `rclone link` to make public links to files or directories. If you specify a directory it will download as a zip file. 🗜️ You can use the `--expire` flag to specify the time the link should be valid. And nota bene, bestie: `rclone link --unlink` removes **all** the public links for a file. 💅

---

## 🌳 Root folder ID 🌳

You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone considers to be the root of your Gofile drive.

Normally you will leave this blank and rclone will determine the correct root to use itself and fill in the value in the config file. ✨

However you can set this to restrict rclone to a specific folder hierarchy.

In order to do this you will have to find the Folder ID of the directory you wish rclone to display. You can do this with rclone:

$ rclone lsf -Fip --dirs-only remote: d6341f53-ee65-4f29-9f59-d11e8070b2a0;Files/ f4f5c9b8-6ece-478b-b03e-4538edfe5a1c;Photos/ d50e356c-29ca-4b27-a3a7-494d91026e04;Videos/


The ID to use is the part before the `;` so you could set

root_folder_id = d6341f53-ee65-4f29-9f59-d11e8070b2a0


to restrict rclone to the `Files` directory. 👑

---

## ⭐ Standard options ⭐

Here are the Standard options specific to gofile (Gofile).

### 🎀 --gofile-access-token

API Access token.

You can get this from the web control panel.

Properties:

- Config: `access_token`
- Env Var: `RCLONE_GOFILE_ACCESS_TOKEN`
- Type: `string`
- Required: `false`

---

## 💜 Advanced options 💜

Here are the Advanced options specific to gofile (Gofile).

### --gofile-root-folder-id

ID of the root folder.

Leave this blank normally, rclone will fill it in automatically.

If you want rclone to be restricted to a particular folder you can fill it in — see the docs for more info.

Properties:

- Config: `root_folder_id`
- Env Var: `RCLONE_GOFILE_ROOT_FOLDER_ID`
- Type: `string`
- Required: `false`

### --gofile-account-id

Account ID.

Leave this blank normally, rclone will fill it in automatically.

Properties:

- Config: `account_id`
- Env Var: `RCLONE_GOFILE_ACCOUNT_ID`
- Type: `string`
- Required: `false`

### --gofile-list-chunk

Number of items to list in each call.

Properties:

- Config: `list_chunk`
- Env Var: `RCLONE_GOFILE_LIST_CHUNK`
- Type: `int`
- Default: `1000`

### --gofile-encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_GOFILE_ENCODING`
- Type: `Encoding`
- Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftPeriod,RightPeriod,InvalidUtf8,Dot,Exclamation`

### --gofile-description

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_GOFILE_DESCRIPTION`
- Type: `string`
- Required: `false`

---

## 😩 Limitations 😩

Gofile only supports filenames up to <purple>255 characters</purple> in length, where a character is a unicode character. 📏

Directories should **not** be cached for more than <red>24h</red>, otherwise files in the directory may not be downloadable. In practice this means when using a VFS based rclone command such as `rclone mount` you should make sure `--dir-cache-time` is less than 24h. ⏳

> 🚨 Note that Gofile is currently limited to a total of <red>100,000 items</red>. If you attempt to upload more than that you will get `error-limit-100000`. This limit may be lifted in the future. 😭

---

## 👯 Duplicated files 👯

Gofile is capable of having files with duplicated file names. For instance two files called `hello.txt` in the same directory. 💀

Rclone cannot sync that to a normal file system but it can be fixed with the `rclone dedupe` command.

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates.

Use `rclone dedupe` to fix duplicated files. 🛠️✨

---

# 🌈 Google Cloud Storage 🌈

Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`. 📁

---

## ✨ Configuration ✨

The initial setup for google cloud storage involves getting a token from Google Cloud Storage 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:

rclone config


This will guide you through an interactive setup process:

See the remote setup docs for how to set it up on a machine with no Internet browser available.

Bestie, lowkey important: when you use the web browser to auto-authenticate, rclone spins up a **webserver on your local machine** to catch the token Google hands back. It only lives from the second it pops your browser open until you get the verification code back. It's on `http://127.0.0.1:53682/` and honestly it might need you to temporarily unblock it if you're running a host firewall — or you just use manual mode and skip the drama. 🫶

This remote is called `remote` and can now be used like this 👇

See all the buckets in your project:

rclone lsd remote:


Make a new bucket:

rclone mkdir remote:bucket


List the contents of a bucket:

rclone ls remote:bucket


Sync `/home/local/directory` to the remote bucket, deleting any excess files in the bucket:

rclone sync --interactive /home/local/directory remote:bucket


---

### 💖 Service Account support 💖

So you can set up rclone with Google Cloud Storage in an **unattended mode**, meaning it's not tied to a specific end-user Google account. This is giving main character energy for when you want to synchronise files onto machines that don't have actively logged-in users — build machines, we're looking at you. 👑

To get credentials for Google Cloud Platform IAM Service Accounts, head to the Service Account section of the Google Developer Console. Service Accounts behave just like normal User permissions in Google Cloud Storage ACLs, so you can limit their access (e.g. make them read only — queen of boundaries). After creating an account, a JSON file containing the Service Account's credentials will be downloaded onto your machines. These credentials are what rclone will use for authentication.

To use a Service Account instead of the OAuth2 token flow, enter the path to your Service Account credentials at the `service_account_file` prompt and rclone won't use the browser based authentication flow. If you'd rather stuff the contents of the credentials file into the rclone config file, you can set `service_account_credentials` with the actual contents of the file instead, or set the equivalent environment variable. ✨

---

### 🔑 Service Account Authentication with Access Tokens 🔑

Another option for service account authentication is to use access tokens via `gcloud impersonate-service-account`. Access tokens protect security by avoiding the use of the JSON key file, which can be breached (💀 not the vibe). They also bypass the oauth login flow, which is simpler on remote VMs that lack a web browser.

If you already have a working service account, skip to step 3. Slay, carry on. 💅

1. Create a service account using

gcloud iam service-accounts create gcs-read-only


You can re-use an existing service account as well (like the one created above)

2. Attach a Viewer (read-only) or User (read-write) role to the service account

$ PROJECT_ID=my-project $ gcloud --verbose iam service-accounts add-iam-policy-binding \ gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com \ --member=serviceAccount:gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com \ --role=roles/storage.objectViewer


Use the Google Cloud console to identify a limited role. Some relevant pre-defined roles:

- `roles/storage.objectUser` – read-write access but no admin privileges
- `roles/storage.objectViewer` – read-only access to objects
- `roles/storage.admin` – create buckets & administrative roles

3. Get a temporary access key for the service account

$ gcloud auth application-default print-access-token \ --impersonate-service-account \ gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com

ya29.c.c0ASRK0GbAFEewXD [truncated]


4. Update `access_token` setting

hit <kbd>Ctrl</kbd>+<kbd>C</kbd> when you see waiting for code. This will save the config without doing oauth flow 😌

rclone config update ${REMOTE_NAME} access_token ya29.c.c0Axxxx


5. Run rclone as usual

rclone ls dev-gcs:${MY_BUCKET}/


---

### 🌈 More Info on Service Accounts 🌈

- Official GCS Docs
- Guide on Service Accounts using Key Files (less secure, but similar concepts)

---

### 🙈 Anonymous Access 🙈

For downloads of objects that permit public access you can configure rclone to use anonymous access by setting `anonymous` to `true`. With unauthorized access you can't write or create files but only read or list those buckets and objects that have public read access. Look only, no touching. 👀

---

### ⭐ Application Default Credentials ⭐

If no other source of credentials is provided, rclone will fall back to Application Default Credentials — this is useful both when you already have configured authentication for your developer account, or in production when running on a google compute host. Note that if running in docker, you may need to run additional commands on your google compute machine — see this page.

Note that in the case application default credentials are used, there is no need to explicitly configure a project number. One less thing, we love that for us. 💜

---

### 🔥 `--fast-list` 🔥

This remote supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs for more details.

---

### 🎀 Custom upload headers 🎀

You can set custom upload headers with the `--header-upload` flag. Google Cloud Storage supports the headers as described in the working with metadata documentation:

- `Cache-Control`
- `Content-Disposition`
- `Content-Encoding`
- `Content-Language`
- `Content-Type`
- `X-Goog-Storage-Class`
- `X-Goog-Meta-`

Eg `--header-upload "Content-Type text/potato"` 🥔 (iconic, honestly)

Note that the last of these is for setting custom metadata in the form `--header-upload "x-goog-meta-key: value"`

### Modification times 🕰️

Google Cloud Storage stores md5sum natively. Google's `gsutil` tool stores modification time with **one-second precision** as `goog-reserved-file-mtime` in file metadata.

To ensure compatibility with `gsutil`, rclone stores modification time in **2 separate metadata entries**. `mtime` uses RFC3339 format with **one-nanosecond precision**. `goog-reserved-file-mtime` uses Unix timestamp format with **one-second precision**. To get modification time from object metadata, rclone reads the metadata in the following order: `mtime`, `goog-reserved-file-mtime`, object updated time.

> Heads up bestie 💖 note that rclone's default modify window is **1ns**. Files uploaded by `gsutil` only contain timestamps with one-second precision. If you use rclone to sync files previously uploaded by `gsutil`, rclone will attempt to update modification time for **all** these files. To avoid these possibly unnecessary updates, use `--modify-window 1s`. 🫶

---

### Restricted filename characters 🌸

These characters just can't come to the party, so rclone swaps them out:

- `NUL` — `0x00` — replaced with `␀`
- `LF` — `0x0A` — replaced with `␊`
- `CR` — `0x0D` — replaced with `␍`
- `/` — `0x2F` — replaced with `／`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 💅

---

### Standard options ✨

Here are the <hotpink>Standard</hotpink> options specific to google cloud storage (Google Cloud Storage (this is not Google Drive)).

- **`--gcs-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_GCS_CLIENT_ID`
  - Type: string
  - Required: false

- **`--gcs-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:

  - Config: `client_secret`
  - Env Var: `RCLONE_GCS_CLIENT_SECRET`
  - Type: string
  - Required: false

- **`--gcs-project-number`** — Project number.

  Optional - needed only for list/create/delete buckets - see your developer console.

  Properties:

  - Config: `project_number`
  - Env Var: `RCLONE_GCS_PROJECT_NUMBER`
  - Type: string
  - Required: false

- **`--gcs-user-project`** — User project.

  Optional - needed only for requester pays.

  Properties:

  - Config: `user_project`
  - Env Var: `RCLONE_GCS_USER_PROJECT`
  - Type: string
  - Required: false

- **`--gcs-service-account-file`** — Service Account Credentials JSON file path.

  Leave blank normally. Needed only if you want use SA instead of interactive login.

  Leading `~` will be expanded in the file name as will environment variables such as `${RCLONE_CONFIG_DIR}`.

  Properties:

  - Config: `service_account_file`
  - Env Var: `RCLONE_GCS_SERVICE_ACCOUNT_FILE`
  - Type: string
  - Required: false

- **`--gcs-service-account-credentials`** — Service Account Credentials JSON blob.

  Leave blank normally. Needed only if you want use SA instead of interactive login.

  Properties:

  - Config: `service_account_credentials`
  - Env Var: `RCLONE_GCS_SERVICE_ACCOUNT_CREDENTIALS`
  - Type: string
  - Required: false

- **`--gcs-anonymous`** — Access public buckets and objects without credentials.

  Set to `true` if you just want to download files and don't configure credentials.

  Properties:

  - Config: `anonymous`
  - Env Var: `RCLONE_GCS_ANONYMOUS`
  - Type: bool
  - Default: `false`

- **`--gcs-object-acl`** — Access Control List for new objects.

  Properties:

  - Config: `object_acl`
  - Env Var: `RCLONE_GCS_OBJECT_ACL`
  - Type: string
  - Required: false
  - Examples:
    - "authenticatedRead"
      - Object owner gets OWNER access.
      - All Authenticated Users get READER access.
    - "bucketOwnerFullControl"
      - Object owner gets OWNER access.
      - Project team owners get OWNER access.
    - "bucketOwnerRead"
      - Object owner gets OWNER access.
      - Project team owners get READER access.
    - "private"
      - Object owner gets OWNER access.
      - Default if left blank.
    - "projectPrivate"
      - Object owner gets OWNER access.
      - Project team members get access according to their roles.
    - "publicRead"
      - Object owner gets OWNER access.
      - All Users get READER access.

- **`--gcs-bucket-acl`** — Access Control List for new buckets.

  Properties:

  - Config: `bucket_acl`
  - Env Var: `RCLONE_GCS_BUCKET_ACL`
  - Type: string
  - Required: false
  - Examples:
    - "authenticatedRead"
      - Project team owners get OWNER access.
      - All Authenticated Users get READER access.
    - "private"
      - Project team owners get OWNER access.
      - Default if left blank.
    - "projectPrivate"
      - Project team members get access according to their roles.
    - "publicRead"
      - Project team owners get OWNER access.
      - All Users get READER access.
    - "publicReadWrite"
      - Project team owners get OWNER access.
      - All Users get WRITER access.

- **`--gcs-bucket-policy-only`** — Access checks should use bucket-level IAM policies.

  If you want to upload objects to a bucket with Bucket Policy Only set then you will need to set this.

  When it is set, rclone:

  - ignores ACLs set on buckets
  - ignores ACLs set on objects
  - creates buckets with Bucket Policy Only set

  Docs: `https://cloud.google.com/storage/docs/bucket-policy-only`

  Properties:

  - Config: `bucket_policy_only`
  - Env Var: `RCLONE_GCS_BUCKET_POLICY_ONLY`
  - Type: bool
  - Default: `false`

- **`--gcs-location`** — Location for the newly created buckets.

  Properties:

  - Config: `location`
  - Env Var: `RCLONE_GCS_LOCATION`
  - Type: string
  - Required: false
  - Examples:
    - ""
      - Empty for default location (US)
    - "asia"
      - Multi-regional location for Asia
    - "eu"
      - Multi-regional location for Europe
    - "us"
      - Multi-regional location for United States
    - "asia-east1"
      - Taiwan
    - "asia-east2"
      - Hong Kong
    - "asia-northeast1"
      - Tokyo
    - "asia-northeast2"
      - Osaka
    - "asia-northeast3"
      - Seoul
    - "asia-south1"
      - Mumbai
    - "asia-south2"
      - Delhi
    - "asia-southeast1"
      - Singapore
    - "asia-southeast2"
      - Jakarta
    - "australia-southeast1"
      - Sydney
    - "australia-southeast2"
      - Melbourne
    - "europe-north1"
      - Finland
    - "europe-west1"
      - Belgium
    - "europe-west2"
      - London
    - "europe-west3"
      - Frankfurt
    - "europe-west4"
      - Netherlands
    - "europe-west6"
      - Zürich
    - "europe-central2"
      - Warsaw
    - "us-central1"
      - Iowa
    - "us-east1"
      - South Carolina
    - "us-east4"
      - Northern Virginia
    - "us-west1"
      - Oregon
    - "us-west2"
      - California
    - "us-west3"
      - Salt Lake City
    - "us-west4"
      - Las Vegas
    - "northamerica-northeast1"
      - Montréal
    - "northamerica-northeast2"
      - Toronto
    - "southamerica-east1"
      - São Paulo
    - "southamerica-west1"
      - Santiago
    - "asia1"
      - Dual region: asia-northeast1 and asia-northeast2.
    - "eur4"
      - Dual region: europe-north1 and europe-west4.
    - "nam4"
      - Dual region: us-central1 and us-east1.

- **`--gcs-storage-class`** — The storage class to use when storing objects in Google Cloud Storage.

  Properties:

  - Config: `storage_class`
  - Env Var: `RCLONE_GCS_STORAGE_CLASS`
  - Type: string
  - Required: false
  - Examples:
    - ""
      - Default
    - "MULTI_REGIONAL"
      - Multi-regional storage class
    - "REGIONAL"
      - Regional storage class
    - "NEARLINE"
      - Nearline storage class
    - "COLDLINE"
      - Coldline storage class
    - "ARCHIVE"
      - Archive storage class
    - "DURABLE_REDUCED_AVAILABILITY"
      - Durable reduced availability storage class

- **`--gcs-env-auth`** — Get GCP IAM credentials from runtime (environment variables or instance meta data if no env vars).

  Only applies if `service_account_file` and `service_account_credentials` is blank.

  Properties:

  - Config: `env_auth`
  - Env Var: `RCLONE_GCS_ENV_AUTH`
  - Type: bool
  - Default: `false`
  - Examples:
    - "false"
      - Enter credentials in the next step.
    - "true"
      - Get GCP IAM credentials from the environment (env vars or IAM).

---

### Advanced options 🔥

Here are the <purple>Advanced</purple> options specific to google cloud storage (Google Cloud Storage (this is not Google Drive)).

- **`--gcs-token`** — OAuth Access Token as a JSON blob.

  Properties:

  - Config: `token`
  - Env Var: `RCLONE_GCS_TOKEN`
  - Type: string
  - Required: false

- **`--gcs-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `auth_url`
  - Env Var: `RCLONE_GCS_AUTH_URL`
  - Type: string
  - Required: false

- **`--gcs-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `token_url`
  - Env Var: `RCLONE_GCS_TOKEN_URL`
  - Type: string
  - Required: false

- **`--gcs-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Properties:

  - Config: `client_credentials`
  - Env Var: `RCLONE_GCS_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: `false`

- **`--gcs-access-token`** — Short-lived access token.

  Leave blank normally. Needed only if you want use short-lived access token instead of interactive login.

  Properties:

  - Config: `access_token`
  - Env Var: `RCLONE_GCS_ACCESS_TOKEN`
  - Type: string
  - Required: false

- **`--gcs-directory-markers`** — Upload an empty object with a trailing slash when a new directory is created

  Empty folders are unsupported for bucket based remotes, this option creates an empty object ending with "/", to persist the folder.

  Properties:

  - Config: `directory_markers`

- Env Var: `RCLONE_GCS_DIRECTORY_MARKERS`

  - Type: bool

  - Default: `false`

- **`--gcs-no-check-bucket`** — bestie, if you set this rclone will NOT try to check that the bucket exists, and it won't try to create it either. 👀

  This is lowkey iconic when you're trying to keep the number of transactions rclone does as smol as possible, because you already *know* the bucket is sitting there. No cap.

  Properties:

  - Config: `no_check_bucket`

  - Env Var: `RCLONE_GCS_NO_CHECK_BUCKET`

  - Type: bool

  - Default: `false`

- **`--gcs-decompress`** — set this and rclone will decompress gzip encoded objects. 🫧

  So here's the vibe: it IS possible to upload objects to GCS with `"Content-Encoding: gzip"` set on them. Normally rclone will download these files as compressed objects (i.e. as the compressed bytes, untouched).

  But if this flag is set, then rclone will decompress these `"Content-Encoding: gzip"` files as they are received. The tradeoff though — and this is the important part, bestie — is that rclone **can't check the size and hash** when you do this, but the file contents *will* be decompressed.

  Properties:

  - Config: `decompress`

  - Env Var: `RCLONE_GCS_DECOMPRESS`

  - Type: bool

  - Default: `false`

- **`--gcs-endpoint`** — the endpoint for the service. 🛰️

  Leave it blank normally, fr fr. It's the "only touch this if you know what you're doing" one.

  Properties:

  - Config: `endpoint`

  - Env Var: `RCLONE_GCS_ENDPOINT`

  - Type: string

  - Required: false

- **`--gcs-encoding`** — the encoding for the backend. ✨

  Go peek at the encoding section in the overview for more info, it's giving very thorough.

  Properties:

  - Config: `encoding`

  - Env Var: `RCLONE_GCS_ENCODING`

  - Type: Encoding

  - Default: `Slash,CrLf,InvalidUtf8,Dot`

- **`--gcs-description`** — a description of the remote. 🎀

  Properties:

  - Config: `description`

  - Env Var: `RCLONE_GCS_DESCRIPTION`

  - Type: string

  - Required: false

### Limitations 💀

`rclone about` is **not supported** by the Google Cloud Storage backend. And bestie, backends without this capability *cannot* determine free space for an `rclone mount`, and they *cannot* use policy `mfs` (most free space) as a member of an `rclone union` remote. So like… plan accordingly. 🙈

See List of backends that do not support `rclone about` and `rclone about`.

---

## 💙 Google Drive 💙

Paths are specified as `drive:path`. 🦋

Drive paths may be as deep as required, e.g. `drive:directory/subdirectory`. Go as deep as your heart desires, the drive does not care.

### Configuration 🎀

The initial setup for drive involves getting a token from Google drive, and you have to do that bit **in your browser**. `rclone config` walks you through it, hand in hand, like a good bestie. 💅

Here is an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote r) Rename remote c) Copy remote s) Set configuration password q) Quit config n/r/c/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Google Drive \ "drive" [snip] Storage> drive Google Application Client Id - leave blank normally. client_id> Google Application Client Secret - leave blank normally. client_secret> Scope that rclone should use when requesting access from drive. Choose a number from below, or type in your own value 1 / Full access all files, excluding Application Data Folder. \ "drive" 2 / Read-only access to file metadata and file contents. \ "drive.readonly" / Access to files created by rclone only. 3 | These are visible in the drive website.

File authorization is revoked when the user deauthorizes the app.

\ "drive.file" / Allows read and write access to the Application Data folder. 4 | This is not visible in the drive website. \ "drive.appfolder" / Allows read-only access to file metadata but 5 | does not allow any access to read or download file content. \ "drive.metadata.readonly" scope> 1 Service Account Credentials JSON file path - needed only if you want use SA instead of interactive login. service_account_file> 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 Configure this as a Shared Drive (Team Drive)? y) Yes n) No y/n> n Configuration complete. Options: type: drive
client_id:
client_secret:
scope: drive
root_folder_id:
service_account_file:
token: {"access_token":"XXX","token_type":"Bearer","refresh_token":"XXX","expiry":"2014-03-16T13:57:58.955387075Z"} 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 for how to set it up on a machine with no Internet browser available. 🧚 (yes, it's possible, we got you)

Now listen, this next bit matters: rclone runs a webserver on your local machine to collect the token as returned from Google, but ONLY if you're using web browser to automatically authenticate. And it only runs from the moment it opens your browser to the moment you get back the verification code. It lives on `http://127.0.0.1:53682/` and it may require you to unblock it temporarily if you are running a host firewall — or you can just use manual mode instead. 🫶

You can then use it like this,

List directories in top level of your drive:

rclone lsd remote:


List all the files in your drive:

rclone ls remote:


To copy a local directory to a drive directory called `backup`:

rclone copy /home/source remote:backup


### Scopes ✨

Rclone allows you to select which scope you would like for rclone to use. This changes what type of token is granted to rclone. The scopes are defined here. 👑

A comma-separated list is allowed e.g. `drive.readonly,drive.file`. Stack 'em, bestie.

The scope are

### `drive` 👑

This is the **default scope** and allows full access to all files, *except* for the Application Data Folder (see below).

Choose this one if you aren't sure. Honestly? Choose this one if you aren't sure. 🫡

### `drive.readonly` 🌸

This allows read only access to all files. Files may be listed and downloaded but **not** uploaded, renamed or deleted. Look with your eyes only. 👀

### `drive.file` 🦋

With this scope rclone can read/view/modify only those files and folders **it creates**.

So if you uploaded files to drive via the web interface (or any other means) they will **not** be visible to rclone. Not a single one.

This can be useful if you are using rclone to backup data and you want to be sure confidential data on your drive is not visible to rclone. Very "boundaries" of you, honestly. 💅

Files created with this scope are visible in the web interface.

### `drive.appfolder` 🎀

This gives rclone its own private area to store files. Rclone will not be able to see any other files on your drive, and you won't be able to see rclone's files from the web interface either. It's giving separate bedrooms. 🚪✨

### `drive.metadata.readonly` 🫧

This allows read only access to **file names only**. It does not allow rclone to download or upload data, or rename or delete files or directories. Names only, no content, sorry bestie. 😭

### Root folder ID 🗂️

This option has been moved to the advanced section. You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone considers to be the root of your drive.

Normally you will leave this blank and rclone will determine the correct root to use itself. Self-sufficient queen. 👑

However you can set this to restrict rclone to a specific folder hierarchy or to access data within the "Computers" tab on the drive web interface (where files from Google's Backup and Sync desktop program go).

In order to do this you will have to find the Folder ID of the directory you wish rclone to display. This will be the **last segment of the URL** when you open the relevant folder in the drive web interface.

So if the folder you want rclone to use has a URL which looks like `https://drive.google.com/drive/folders/1XyfxxxxxxxxxxxxxxxxxxxxxxxxxKHCh` in the browser, then you use `1XyfxxxxxxxxxxxxxxxxxxxxxxxxxKHCh` as the `root_folder_id` in the config. Copy that string exactly, do not freestyle it. 🚫

> NB folders under the "Computers" tab seem to be read only (drive gives a `500` error) when using rclone.

There doesn't appear to be an API to discover the folder IDs of the "Computers" tab — please contact us if you know otherwise! 🕵️‍♀️

Note also that rclone can't access any data under the "Backups" tab on the google drive web interface yet. Not yet, but we're manifesting. 🌈

### Service Account support 🤖

You can set up rclone with Google Drive in an **unattended mode**, i.e. not tied to a specific end-user Google account. This is useful when you want to synchronise files onto machines that don't have actively logged-in users, for example build machines. (Machines can't log in, bestie, they're machines. 💀)

To use a Service Account instead of OAuth2 token flow, enter the path to your Service Account credentials at the `service_account_file` prompt during `rclone config` and rclone won't use the browser based authentication flow. If you'd rather stuff the contents of the credentials file into the rclone config file, you can set `service_account_credentials` with the actual contents of the file instead, or set the equivalent environment variable. ✨

### Use case - Google Workspace account and individual Drive 💼

Let's say that you are the administrator of a Google Workspace. The goal is to read or write data on an individual's Drive account, who **IS** a member of the domain. We'll call the domain `example.com`, and the user `foo@example.com`. Very cute names, slay. 🎀

There's a few steps we need to go through to accomplish this:

#### 1. Create a service account for `example.com` 🔑

- To create a service account and obtain its credentials, go to the Google Developer Console.

- You must have a project - create one if you don't and make sure you are on the selected project. 👑

- Then go to "IAM & admin" -> "Service Accounts".

- Use the "Create Service Account" button. Fill in "Service account name" and "Service account ID" with something that identifies your client.

- Select "Create And Continue". Step 2 and 3 are optional. (optional bestie, we love an optional step 🫶)

- Click on the newly created service account

- Click "Keys" and then "Add Key" and then "Create new key" 🔐

- Choose type "JSON" and click create

- This will download a small JSON file that rclone will use for authentication.

If you ever need to remove access, press the "Delete service account key" button. Bye bye key, it was real. 👋

#### 2. Allowing API access to `example.com` Google Drive

- Go to `example.com`'s Workspace Admin Console

- Go into <pink>“Security”</pink> (or just yeet it into the search bar, same energy, less scrolling ✨)

- Select <pink>“Access and data control”</pink> and then <pink>“API controls”</pink>

- Click <pink>“Manage domain-wide delegation”</pink>

- Click <pink>“Add new”</pink>

- In the <pink>“Client ID”</pink> field enter the service account’s <pink>“Client ID”</pink> — you’ll find it in the Developer Console under <pink>“IAM & Admin”</pink> -> <pink>“Service Accounts”</pink>, then hit <pink>“View Client ID”</pink> for the service account you freshly created. It’s a ~21 character numerical string, lowkey just numbers 🫶

- In the next field, <pink>“OAuth Scopes”</pink>, enter <cyan>https://www.googleapis.com/auth/drive</cyan> to grant read/write access to Google Drive specifically. You can also use <cyan>https://www.googleapis.com/auth/drive.readonly</cyan> for read only access 🔐

- Click <pink>“Authorise”</pink> 👑

3. **Configure rclone**, assuming a new install 💅

rclone config

n/s/q> n # New name>gdrive # Gdrive is an example name Storage> # Type drive client_id> # Can be left blank client_secret> # Can be left blank scope> # Select the scope use used in step 2 root_folder_id> # Can be left blank service_account_file> /home/foo/myJSONfile.json # Path to the JSON file you downloaded in step 1. y/n> # Auto config, n


4. **Verify that it’s working** 🧚

- `rclone -v --drive-impersonate foo@example.com lsf gdrive:backup`

- The arguments do:

  - `-v` - verbose logging 📝
  - `--drive-impersonate foo@example.com` - this is what does the magic, pretending to be user `foo` ✨
  - `lsf` - list files in a parsing friendly way
  - `gdrive:backup` - use the remote called `gdrive`, work in the folder named `backup`.

> <yellow>Note:</yellow> in case you configured a specific root folder on gdrive and rclone is unable to access the contents of that folder when using `--drive-impersonate`, do this instead: — in the gdrive web interface, share your root folder with the user/email of the new Service Account you created/selected at step 1 — use rclone without specifying the `--drive-impersonate` option, like this: `rclone -v lsf gdrive:backup`

### 🌈 Shared drives (team drives)

If you want to configure the remote to point to a Google Shared Drive (previously known as Team Drives) then answer `y` to the question `Configure this as a Shared Drive (Team Drive)?` 😌

This will fetch the list of Shared Drives from google and allow you to configure which one you want to use. You can also type in a Shared Drive ID if you prefer — main character choice honestly 💅

For example:

Configure this as a Shared Drive (Team Drive)? y) Yes n) No y/n> y Fetching Shared Drive list... Choose a number from below, or type in your own value 1 / Rclone Test \ "xxxxxxxxxxxxxxxxxxxx" 2 / Rclone Test 2 \ "yyyyyyyyyyyyyyyyyyyy" 3 / Rclone Test 3 \ "zzzzzzzzzzzzzzzzzzzz" Enter a Shared Drive ID> 1 Configuration complete. Options:

type: drive
client_id:
client_secret:
token: {"AccessToken":"xxxx.x.xxxxx_xxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","RefreshToken":"1/xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxx","Expiry":"2014-03-16T13:57:58.955387075Z","Extra":null}
team_drive: xxxxxxxxxxxxxxxxxxxx Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


### 🚀 `--fast-list`

This remote supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs for more details 📚

It does this by combining multiple list calls into a single API request. So iconic of it, honestly.

This works by combining many `'%s' in parents` filters into one expression. To list the contents of directories `a`, `b` and `c`, the following requests will be send by the regular `List` function:

trashed=false and 'a' in parents trashed=false and 'b' in parents trashed=false and 'c' in parents


These can now be combined into a single request:

trashed=false and ('a' in parents or 'b' in parents or 'c' in parents)


The implementation of `ListR` will put up to 50 parents filters into one request. It will use the `--checkers` value to specify the number of requests to run in parallel ⚡

In tests, these batch requests were up to 20x faster than the regular method. Running the following command against different sized folders gives:

rclone lsjson -vv -R --checkers=6 gdrive:folder


small folder (220 directories, 700 files):

- without `--fast-list`: 38s 🐌

- with `--fast-list`: 10s 🏎️

large folder (10600 directories, 39000 files):

- without `--fast-list`: 22:05 min 💀

- with `--fast-list`: 58s 🔥

### 🕰️ Modification times and hashes

Google drive stores modification times accurate to 1 ms. Precise king behavior.

Hash algorithms MD5, SHA1 and SHA256 are supported. Note, however, that a small fraction of files uploaded may not have SHA1 or SHA256 hashes — especially if they were uploaded before 2018 👀

### 🙈 Restricted filename characters

Only **Invalid UTF-8 bytes** will be replaced, as they can’t be used in JSON strings.

In contrast to other backends, `/` can also be used in names and `.` or `..` are valid names. Chaotic but valid, we love that for them 💅

### 🔁 Revisions

Google drive stores revisions of files. When you upload a change to an existing file to google drive using rclone it will create a new revision of that file.

Revisions follow the standard google policy which at time of writing was

- They are deleted after 30 days or 100 revisions (whatever comes first) ⏳

- They do not count towards a user storage quota 🎀

### 🗑️ Deleting files

By default rclone will send all files to the trash when deleting files. If deleting them permanently is required then use the `--drive-use-trash=false` flag, or set the equivalent environment variable ⚠️

### 🪄 Shortcuts

In March 2020 Google introduced a new feature in Google Drive called drive shortcuts (API). These will (by September 2020) replace the ability for files or folders to be in multiple folders at once.

Shortcuts are files that link to other files on Google Drive — somewhat like a symlink in unix, except they point to the underlying file data (e.g. the inode in unix terms) so they don’t break if the source is renamed or moved about 🧠✨

By default rclone treats these as follows.

For shortcuts pointing to files:

- When listing, a file shortcut appears as the destination file.

- When downloading, the contents of the destination file is downloaded.

- When updating a shortcut file with a non shortcut file, the shortcut is removed then a new file is uploaded in place of the shortcut.

- When server-side moving (renaming), the shortcut is renamed, not the destination file.

- When server-side copying, the shortcut is copied, not the contents of the shortcut. (unless `--drive-copy-shortcut-content` is in use in which case the contents of the shortcut gets copied).

- When deleting, the shortcut is deleted not the linked file.

- When setting the modification time, the modification time of the linked file will be set.

For shortcuts pointing to folders:

- When listing, the shortcut appears as a folder and that folder will contain the contents of the linked folder appear (including any sub folders)

- When downloading, the contents of the linked folder and sub contents are downloaded

- When uploading to a shortcut folder the file will be placed in the linked folder

- When server-side moving (renaming), the shortcut is renamed, not the destination folder

- When server-side copying, the contents of the linked folder is copied, not the shortcut.

- When deleting with `rclone rmdir` or `rclone purge`, the shortcut is deleted not the linked folder.

- NB When deleting with `rclone remove` or `rclone mount` the contents of the linked folder will be deleted. 💀 not the vibe, be careful

The `rclone backend` command can be used to create shortcuts.

Shortcuts can be completely ignored with the `--drive-skip-shortcuts` flag or the corresponding `skip_shortcuts` configuration setting.

> <red>If you have shortcuts that lead to an infinite recursion in your drive (e.g. a shortcut pointing to a parent folder), `skip_shortcuts` might be mandatory to be able to copy the drive.</red> 🌀

### 🧹 Emptying trash

If you wish to empty your trash you can use the `rclone cleanup remote:` command which will permanently delete all your trashed files. This command does not take any path arguments.

Note that Google Drive takes some time (minutes to days) to empty the trash even though the command returns within a few seconds. No output is echoed, so there will be no confirmation even using `-v` or `-vv`. silent but deadly fr fr 🫥

### 📊 Quota information

To view your current quota you can use the `rclone about remote:` command which will display your usage limit (quota), the usage in Google Drive, the size of all files in the Trash and the space used by other Google services such as Gmail. This command does not take any path arguments.

### 📄 Import/Export of google documents

Google documents can be exported from and uploaded to Google Drive.

When rclone downloads a Google doc it chooses a format to download depending upon the `--drive-export-formats` setting. By default the export formats are `docx,xlsx,pptx,svg` which are a sensible default for an editable document ✨

When choosing a format, rclone runs down the list provided in order and chooses the first file format the doc can be exported as from the list. If the file can’t be exported to a format on the formats list, then rclone will choose a format from the default list.

If you prefer an archive copy then you might use `--drive-export-formats pdf`, or if you prefer openoffice/libreoffice formats you might use `--drive-export-formats ods,odt,odp` 🎀

Note that rclone adds the extension to the google doc, so if it is called `My Spreadsheet` on google docs, it will be exported as `My Spreadsheet.xlsx` or `My Spreadsheet.pdf` etc.

When importing files into Google Drive, rclone will convert all files with an extension in `--drive-import-formats` to their associated document type. rclone will not convert any files by default, since the conversion is lossy process ⚠️

The conversion must result in a file with the same extension when the `--drive-export-formats` rules are applied to the uploaded document.

Here are some examples for allowed and prohibited conversions.

<pink>okay so here's the compatibility chart everyone squints at</pink> 👀 — it's the whole "what you upload vs what the doc actually becomes vs will Google even let you" situation. Four columns, five vibes, no cap:

- `export-formats` `odt` · `import-formats` `odt` · `Upload Ext` `odt` · `Document Ext` `odt` → **Allowed: Yes**
- `export-formats` `odt` · `import-formats` `docx,odt` · `Upload Ext` `odt` · `Document Ext` `odt` → **Allowed: Yes**
- `export-formats` *(blank)* · `import-formats` `docx` · `Upload Ext` `docx` · `Document Ext` `docx` → **Allowed: Yes**
- `export-formats` *(blank)* · `import-formats` `odt` · `Upload Ext` `odt` · `Document Ext` `docx` → **Allowed: No**
- `export-formats` `odt,docx` · `import-formats` `docx,odt` · `Upload Ext` `docx` · `Document Ext` `odt` → **Allowed: No**
- `export-formats` `docx,odt` · `import-formats` `docx,odt` · `Upload Ext` `docx` · `Document Ext` `docx` → **Allowed: Yes**
- `export-formats` `docx,odt` · `import-formats` `docx,odt` · `Upload Ext` `odt` · `Document Ext` `docx` → **Allowed: No**

That whole "no" column? It's the limitation, bestie, and you *can* turn it off by specifying `--drive-allow-import-name-change`. 💅

> ⚠️ But listen — with that flag on, rclone can convert multiple files types resulting in the same document type at once, e.g. with `--drive-import-formats docx,odt,txt`, all files having these extension would result in a document represented as a docx file. This brings the additional risk of overwriting a document, if multiple files have the same stem. Many rclone operations will not handle this name change in any way. They assume an equal name when copying files and might copy the file again or delete them when the name changes. So like… know what you're doing 🫠

Here are the possible export extensions with their corresponding mime types. Most of these can also be used for importing, but there more that are not listed here. Some of these additional ones might only be available when the operating system provides the correct MIME type entries.

<purple>and this list can be changed by Google Drive at any time</purple> and might not represent the currently available conversions. so like, don't @ me if it drifts 🌸

- **`bmp`** — `image/bmp` — Windows Bitmap format
- **`csv`** — `text/csv` — Standard CSV format for Spreadsheets
- **`doc`** — `application/msword` — Classic Word file
- **`docx`** — `application/vnd.openxmlformats-officedocument.wordprocessingml.document` — Microsoft Office Document
- **`epub`** — `application/epub+zip` — E-book format
- **`html`** — `text/html` — An HTML Document
- **`jpg`** — `image/jpeg` — A JPEG Image File
- **`json`** — `application/vnd.google-apps.script+json` — JSON Text Format for Google Apps scripts
- **`md`** — `text/markdown` — Markdown Text Format
- **`odp`** — `application/vnd.oasis.opendocument.presentation` — Openoffice Presentation
- **`ods`** — `application/vnd.oasis.opendocument.spreadsheet` — Openoffice Spreadsheet
- **`ods`** — `application/x-vnd.oasis.opendocument.spreadsheet` — Openoffice Spreadsheet
- **`odt`** — `application/vnd.oasis.opendocument.text` — Openoffice Document
- **`pdf`** — `application/pdf` — Adobe PDF Format
- **`pjpeg`** — `image/pjpeg` — Progressive JPEG Image
- **`png`** — `image/png` — PNG Image Format
- **`pptx`** — `application/vnd.openxmlformats-officedocument.presentationml.presentation` — Microsoft Office Powerpoint
- **`rtf`** — `application/rtf` — Rich Text Format
- **`svg`** — `image/svg+xml` — Scalable Vector Graphics Format
- **`tsv`** — `text/tab-separated-values` — Standard TSV format for spreadsheets
- **`txt`** — `text/plain` — Plain Text
- **`wmf`** — `application/x-msmetafile` — Windows Meta File
- **`xls`** — `application/vnd.ms-excel` — Classic Excel file
- **`xlsx`** — `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — Microsoft Office Spreadsheet
- **`zip`** — `application/zip` — A ZIP file of HTML, Images CSS

✨ <hotpink>plot twist:</hotpink> Google documents can also be exported as *link files*. These files will open a browser window for the Google Docs website of that document when opened. The link file extension has to be specified as a `--drive-export-formats` parameter. They will match all available Google Documents. 🦋

- **`desktop`** — freedesktop.org specified desktop entry — OS Support: Linux
- **`link.html`** — An HTML Document with a redirect — OS Support: All
- **`url`** — INI style link file — OS Support: macOS, Windows
- **`webloc`** — macOS specific XML format — OS Support: macOS

---

## 💖 Standard options 💖

Here are the Standard options specific to drive (Google Drive). <mint>ur welcome.</mint>

### `--drive-client-id`

Google Application Client Id Setting your own is recommended. See `https://rclone.org/drive/#making-your-own-client-id` for how to create your own. If you leave this blank, it will use an internal key which is low performance. 😭 (yes, it literally says low performance, don't come for me)

Properties:

- Config: `client_id`
- Env Var: `RCLONE_DRIVE_CLIENT_ID`
- Type: string
- Required: false

### `--drive-client-secret`

OAuth Client Secret.

Leave blank normally. 🙈

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_DRIVE_CLIENT_SECRET`
- Type: string
- Required: false

### `--drive-scope`

Comma separated list of scopes that rclone should use when requesting access from drive. 🔐

Properties:

- Config: `scope`
- Env Var: `RCLONE_DRIVE_SCOPE`
- Type: string
- Required: false
- Examples:
  - `"drive"`
    - Full access all files, excluding Application Data Folder.
  - `"drive.readonly"`
    - Read-only access to file metadata and file contents.
  - `"drive.file"`
    - Access to files created by rclone only.
    - These are visible in the drive website.
    - File authorization is revoked when the user deauthorizes the app.
  - `"drive.appfolder"`
    - Allows read and write access to the Application Data folder.
    - This is not visible in the drive website.
  - `"drive.metadata.readonly"`
    - Allows read-only access to file metadata but
    - does not allow any access to read or download file content.

### `--drive-service-account-file`

Service Account Credentials JSON file path.

Leave blank normally. Needed only if you want use SA instead of interactive login.

Leading `~` will be expanded in the file name as will environment variables such as `${RCLONE_CONFIG_DIR}`. 🌈

Properties:

- Config: `service_account_file`
- Env Var: `RCLONE_DRIVE_SERVICE_ACCOUNT_FILE`
- Type: string
- Required: false

### `--drive-alternate-export`

Deprecated: No longer needed. 💀 (it said deprecated, not me, that's just the facts)

Properties:

- Config: `alternate_export`
- Env Var: `RCLONE_DRIVE_ALTERNATE_EXPORT`
- Type: bool
- Default: `false`

---

## 👑 Advanced options 👑

Here are the Advanced options specific to drive (Google Drive). buckle up, this is the main character section 🎀

### `--drive-token`

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_DRIVE_TOKEN`
- Type: string
- Required: false

### `--drive-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_DRIVE_AUTH_URL`
- Type: string
- Required: false

### `--drive-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_DRIVE_TOKEN_URL`
- Type: string
- Required: false

### `--drive-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749. 📜

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_DRIVE_CLIENT_CREDENTIALS`
- Type: bool
- Default: `false`

### `--drive-root-folder-id`

ID of the root folder. Leave blank normally.

Fill in to access "Computers" folders (see docs), or for rclone to use a non root folder as its starting point. 🧚

Properties:

- Config: `root_folder_id`
- Env Var: `RCLONE_DRIVE_ROOT_FOLDER_ID`
- Type: string
- Required: false

### `--drive-service-account-credentials`

Service Account Credentials JSON blob.

Leave blank normally. Needed only if you want use SA instead of interactive login.

Properties:

- Config: `service_account_credentials`
- Env Var: `RCLONE_DRIVE_SERVICE_ACCOUNT_CREDENTIALS`
- Type: string
- Required: false

### `--drive-team-drive`

ID of the Shared Drive (Team Drive). 🫶

Properties:

- Config: `team_drive`
- Env Var: `RCLONE_DRIVE_TEAM_DRIVE`
- Type: string
- Required: false

---

- **`--drive-auth-owner-only`** — bestie, this one only looks at files that the authenticated user actually owns. Nothing else gets a seat at the table. 👑

  Properties:

  - Config: `auth_owner_only`
  - Env Var: `RCLONE_DRIVE_AUTH_OWNER_ONLY`
  - Type: bool
  - Default: `false`

- **`--drive-use-trash`** — send files to the trash instead of deleting them permanently. ✨

  It defaults to `true`, so like, trash is the whole vibe by default. If you want files *actually gone* gone, hit it with `--drive-use-trash=false`.

  Properties:

  - Config: `use_trash`
  - Env Var: `RCLONE_DRIVE_USE_TRASH`
  - Type: bool
  - Default: `true`

- **`--drive-copy-shortcut-content`** — server side copy the *contents* of shortcuts instead of the shortcut itself.

  So here's the tea: when rclone does server side copies, normally it copies shortcuts as shortcuts. That's just the default.

  But if you use this flag, rclone will copy the contents of shortcuts rather than the shortcuts themselves when it's doing those server side copies. 💅

  Properties:

  - Config: `copy_shortcut_content`
  - Env Var: `RCLONE_DRIVE_COPY_SHORTCUT_CONTENT`
  - Type: bool
  - Default: `false`

- **`--drive-skip-gdocs`** — skip Google documents in *all* listings.

  If you give this flag, gdocs basically become invisible to rclone. Poof. 🙈

  Properties:

  - Config: `skip_gdocs`
  - Env Var: `RCLONE_DRIVE_SKIP_GDOCS`
  - Type: bool
  - Default: `false`

- **`--drive-show-all-gdocs`** — show ALL Google Docs in listings, even the ones that can't be exported.

  If you try a server side copy on a Google Form without this flag, you're gonna get this error, no cap:

No export formats found for "application/vnd.google-apps.form"


But adding this flag lets the form be server side copied. Slay.

Just know that in this mode rclone doesn't add extensions to the Google Docs file names.

> ⚠️ Do **not** use this flag when you're trying to download Google Docs — rclone will fail to download them. Not it. 😭

Properties:

- Config: `show_all_gdocs`
- Env Var: `RCLONE_DRIVE_SHOW_ALL_GDOCS`
- Type: bool
- Default: `false`

- **`--drive-skip-checksum-gphotos`** — skip checksums on Google photos and videos only. 📸

Use this if you keep getting checksum errors while transferring Google photos or videos.

Setting this flag makes Google photos and videos return a blank checksum.

Google photos are identified by being in the `"photos"` space.

The corrupted checksums happen because Google modifies the image/video but doesn't update the checksum. 💀

Properties:

- Config: `skip_checksum_gphotos`
- Env Var: `RCLONE_DRIVE_SKIP_CHECKSUM_GPHOTOS`
- Type: bool
- Default: `false`

- **`--drive-shared-with-me`** — only show files that are shared with me.

This tells rclone to operate on your "Shared with me" folder — the place where Google Drive lets you access the files and folders other people have shared with you. 🫶

It works with the "list" commands (`lsd`, `lsl`, etc.) *and* the "copy" commands (`copy`, `sync`, etc.), and honestly with all the other commands too.

Properties:

- Config: `shared_with_me`
- Env Var: `RCLONE_DRIVE_SHARED_WITH_ME`
- Type: bool
- Default: `false`

- **`--drive-trashed-only`** — only show files that are in the trash.

This shows trashed files in their original directory structure. So like, the ghost of your filesystem past. 👻

Properties:

- Config: `trashed_only`
- Env Var: `RCLONE_DRIVE_TRASHED_ONLY`
- Type: bool
- Default: `false`

- **`--drive-starred-only`** — only show files that are starred. ⭐

Properties:

- Config: `starred_only`
- Env Var: `RCLONE_DRIVE_STARRED_ONLY`
- Type: bool
- Default: `false`

- **`--drive-formats`** — Deprecated, bestie. See `export_formats`.

Properties:

- Config: `formats`
- Env Var: `RCLONE_DRIVE_FORMATS`
- Type: string
- Required: `false`

- **`--drive-export-formats`** — a comma separated list of your preferred formats for downloading Google docs.

Properties:

- Config: `export_formats`
- Env Var: `RCLONE_DRIVE_EXPORT_FORMATS`
- Type: string
- Default: `"docx,xlsx,pptx,svg"`

- **`--drive-import-formats`** — a comma separated list of your preferred formats for uploading Google docs.

Properties:

- Config: `import_formats`
- Env Var: `RCLONE_DRIVE_IMPORT_FORMATS`
- Type: string
- Required: `false`

- **`--drive-allow-import-name-change`** — allow the filetype to change when you're uploading Google docs.

Like, `file.doc` to `file.docx`. Fair warning though: this will confuse sync and reupload every single time. Every. Time. 😭

Properties:

- Config: `allow_import_name_change`
- Env Var: `RCLONE_DRIVE_ALLOW_IMPORT_NAME_CHANGE`
- Type: bool
- Default: `false`

- **`--drive-use-created-date`** — use the file's created date instead of the modified date.

This is handy when you're downloading data and you want the creation date used in place of the last modified date.

> ⚠️ **WARNING:** this flag may have some unexpected consequences.

When uploading to your drive, all files will be overwritten unless they haven't been modified since their creation. And the inverse will occur while downloading. You can dodge that side effect by using the `--checksum` flag.

This feature was implemented to retain the photos capture date as recorded by google photos. You'll first need to check the "Create a Google Photos folder" option in your google drive settings. Then you can copy or move the photos locally and use the date the image was taken (created) set as the modification date. 🌸

Properties:

- Config: `use_created_date`
- Env Var: `RCLONE_DRIVE_USE_CREATED_DATE`
- Type: bool
- Default: `false`

- **`--drive-use-shared-date`** — use the date the file was shared instead of the modified date.

Heads up: same deal as `--drive-use-created-date`, this flag may have unexpected consequences when uploading/downloading files.

And if both this flag *and* `--drive-use-created-date` are set, the created date wins. Periodt. 👑

Properties:

- Config: `use_shared_date`
- Env Var: `RCLONE_DRIVE_USE_SHARED_DATE`
- Type: bool
- Default: `false`

- **`--drive-list-chunk`** — size of the listing chunk, `100`-`1000`, or `0` to disable.

Properties:

- Config: `list_chunk`
- Env Var: `RCLONE_DRIVE_LIST_CHUNK`
- Type: int
- Default: `1000`

- **`--drive-impersonate`** — impersonate this user when you're using a service account.

Properties:

- Config: `impersonate`
- Env Var: `RCLONE_DRIVE_IMPERSONATE`
- Type: string
- Required: `false`

- **`--drive-upload-cutoff`** — the cutoff for switching to chunked upload.

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_DRIVE_UPLOAD_CUTOFF`
- Type: SizeSuffix
- Default: `8Mi`

- **`--drive-chunk-size`** — the upload chunk size.

It must be a power of 2 `>= 256k`. ✨

Making it larger improves performance, but keep in mind that each chunk is buffered in memory, one per transfer.

Making it smaller reduces memory usage but decreases performance. Pick your fighter. 💅

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_DRIVE_CHUNK_SIZE`
- Type: SizeSuffix
- Default: `8Mi`

- **`--drive-acknowledge-abuse`** — set this to allow files that return `cannotDownloadAbusiveFile` to be downloaded.

If downloading a file returns the error "This file has been identified as malware or spam and cannot be downloaded" with the error code `cannotDownloadAbusiveFile`, then you supply this flag to rclone to say you acknowledge the risks of downloading the file, and rclone will download it anyway. 🙈

Just know that if you're using a service account, it'll need Manager permission (not Content Manager) for this flag to work. If the SA doesn't have the right permission, Google will just ignore the flag. Rude, honestly.

Properties:

- Config: `acknowledge_abuse`
- Env Var: `RCLONE_DRIVE_ACKNOWLEDGE_ABUSE`
- Type: bool
- Default: `false`

- **`--drive-keep-revision-forever`** — keep the new head revision of each file forever. 🔥

Properties:

- Config: `keep_revision_forever`
- Env Var: `RCLONE_DRIVE_KEEP_REVISION_FOREVER`
- Type: bool
- Default: `false`

- **`--drive-size-as-quota`** — show sizes as storage quota usage, not actual size.

So it shows the size of a file as the storage quota it uses. That's the current version *plus* any older versions that have been set to keep forever.

> ⚠️ **WARNING:** this flag may have some unexpected consequences.

It is **not** recommended to set this flag in your config — the recommended usage is the flag form, `--drive-size-as-quota`, and only when you're doing `rclone ls`/`lsl`/`lsf`/`lsjson`/etc.

And if you do use this flag for syncing (not recommended, bestie), then you'll need to use `--ignore size` too.

Properties:

- Config: `size_as_quota`
- Env Var: `RCLONE_DRIVE_SIZE_AS_QUOTA`
- Type: bool
- Default: `false`

- **`--drive-v2-download-min-size`** — if objects are greater than this, use the drive v2 API to download.

Properties:

- Config: `v2_download_min_size`
- Env Var: `RCLONE_DRIVE_V2_DOWNLOAD_MIN_SIZE`
- Type: SizeSuffix
- Default: `off`

- **`--drive-pacer-min-sleep`** — the minimum time to sleep between API calls.

Properties:

- Config: `pacer_min_sleep`
- Env Var: `RCLONE_DRIVE_PACER_MIN_SLEEP`
- Type: Duration
- Default: `100ms`

- **`--drive-pacer-burst`** — how many API calls to allow without sleeping.

Properties:

- Config: `pacer_burst`
- Env Var: `RCLONE_DRIVE_PACER_BURST`
- Type: int
- Default: `100`

- **`--drive-server-side-across-configs`** — Deprecated: use `--server-side-across-configs` instead. 🫠

It lets server-side operations (e.g. `copy`) work across different drive configs.

This can be useful if you want to do a server-side copy between two different Google drives. Note that it isn't enabled by default because it isn't easy to tell if it will work between any two configurations.

Properties:

- Config: `server_side_across_configs`
- Env Var: `RCLONE_DRIVE_SERVER_SIDE_ACROSS_CONFIGS`
- Type: bool
- Default: `false`

- **`--drive-disable-http2`** — disable drive using http2.

There is currently an unsolved issue with the google drive backend and HTTP/2. HTTP/2 is therefore disabled by default for the drive backend, but you can re-enable it here. When the issue gets solved this flag will be removed. Fingers crossed bestie. 🎀

See: `https://github.com/rclone/rclone/issues/3631`

Properties:

- Config: `disable_http2`
- Env Var: `RCLONE_DRIVE_DISABLE_HTTP2`
- Type: bool
- Default: `true`

- **`--drive-stop-on-upload-limit`** — make upload limit errors fatal. 💀

At the time of writing it's only possible to upload `750 GiB` of data to Google Drive a day (this is an undocumented limit, iykyk). When this limit is reached, Google Drive produces a slightly different error message. When this flag is set, it causes these errors to be fatal. These will stop the in-progress sync.

Note that this detection is relying on error message strings which Google doesn't document, so it may break in the future. 🙃

See: `https://github.com/rclone/rclone/issues/3857`

Properties:

**Properties:**

- **Config:** `stop_on_upload_limit`
- **Env Var:** `RCLONE_DRIVE_STOP_ON_UPLOAD_LIMIT`
- **Type:** `bool`
- **Default:** `false`

---

### 💀 `--drive-stop-on-download-limit`

Okay bestie, this one makes <red>download limit errors FATAL</red> — like, no surviving them.

At the time of writing, you can only pull down <hotpink>10 TiB</hotpink> of data from Google Drive per day (and yes, that limit is <italic>undocumented</italic> — Google just does that 🙈). When you hit it, Google Drive throws a <yellow>slightly different error message</yellow> than usual. Flip this flag on and those errors become fatal — meaning they will <red>stop the in-progress sync</red> dead in its tracks. 🛑

> ⚠️ Heads up: this detection relies on matching <italic>error message strings</italic> that Google doesn't document, so it <bold>may break in the future</bold>. Not our fault, we're just working with what they give us. 😭

**Properties:**

- **Config:** `stop_on_download_limit`
- **Env Var:** `RCLONE_DRIVE_STOP_ON_DOWNLOAD_LIMIT`
- **Type:** `bool`
- **Default:** `false`

---

### 🩹 `--drive-skip-shortcuts`

If set, skip shortcut files. Periodt.

Normally rclone <green>dereferences</green> shortcut files, which makes them show up like they're literally the original file (go peek at the shortcuts section for the tea ☕). But if you set this flag, rclone will just <yellow>ignore shortcut files completely</yellow>. No dereferencing, no pretending, nothing. 💅

**Properties:**

- **Config:** `skip_shortcuts`
- **Env Var:** `RCLONE_DRIVE_SKIP_SHORTCUTS`
- **Type:** `bool`
- **Default:** `false`

---

### 🪦 `--drive-skip-dangling-shortcuts`

If set, skip the <italic>dangling</italic> shortcut files.

Dangling shortcuts are the ones pointing at nothing — the ghosting exes of the Drive world 👻. Set this and rclone <purple>will not show any dangling shortcuts in listings</purple>. They simply don't exist to us anymore, and honestly? Valid.

**Properties:**

- **Config:** `skip_dangling_shortcuts`
- **Env Var:** `RCLONE_DRIVE_SKIP_DANGLING_SHORTCUTS`
- **Type:** `bool`
- **Default:** `false`

---

### 🔑 `--drive-resource-key`

Resource key for accessing a link-shared file. It's giving "secret handshake" energy fr fr.

So if you need to access files shared with a link that looks like this:

https://drive.google.com/drive/folders/XXX?resourcekey=YYY&usp=sharing


…then you're gonna need to use the first part `XXX` as the `root_folder_id` and the second part `YYY` as the `resource_key`. Do that, or you'll be getting <red>404 not found errors</red> every time you try to touch that directory. 😭 Not cute.

See: `https://developers.google.com/drive/api/guides/resource-keys`

Also, this whole resource key requirement <yellow>only applies to a subset of old files</yellow>. And plot twist — opening the folder <italic>once</italic> in the web interface (with the same user you've authenticated rclone with) <green>seems to be enough</green> that the resource key isn't needed anymore. Iconic behavior honestly. 👑

**Properties:**

- **Config:** `resource_key`
- **Env Var:** `RCLONE_DRIVE_RESOURCE_KEY`
- **Type:** `string`
- **Required:** `false`

---

### 🐛 `--drive-fast-list-bug-fix`

Work around a bug in Google Drive listing. Yes bestie, sometimes we have to hack around the platform itself. 🙈

Normally rclone will work around a bug in Google Drive when you're using `--fast-list` (ListR), where the search `"(A in parents) or (B in parents)"` <yellow>returns nothing sometimes</yellow>. Like, hello?? See `#3114`, `#4289` and `https://issuetracker.google.com/issues/149522397` for the receipts.

Rclone detects this by finding no items in <bold>more than one directory</bold> while listing, and then it <green>retries them as lists of individual directories</green>.

The catch: this means if you have a <italic>lot</italic> of empty directories, rclone will end up listing them all one by one, individually, and that can take <red>many more API calls</red>. 💀

So this flag lets you <bold>disable the work-around</bold>. Which is <red>not recommended in normal use</red> — only do it if you've got a particular case you're having trouble with, like many empty directories.

**Properties:**

- **Config:** `fast_list_bug_fix`
- **Env Var:** `RCLONE_DRIVE_FAST_LIST_BUG_FIX`
- **Type:** `bool`
- **Default:** `true`

---

### 👤 `--drive-metadata-owner`

Control whether owner should be read or written in metadata. The way that ownership is just *sitting there* in the metadata… 🫶

Owner is a standard part of the file metadata so it's <green>easy to read</green>. But it isn't always desirable to <italic>set</italic> the owner from the metadata, y'know?

> ⚠️ Important tea: you <bold>can't set the owner on Shared Drives</bold>. Also, setting ownership will <yellow>generate an email to the new owner</yellow> and this <bold>can't be disabled</bold>. And you <bold>can't transfer ownership to someone outside your organization</bold>. So like… be careful. 😭

**Properties:**

- **Config:** `metadata_owner`
- **Env Var:** `RCLONE_DRIVE_METADATA_OWNER`
- **Type:** `Bits`
- **Default:** `read`
- **Examples:**
  - `"off"` — Do not read or write the value
  - `"read"` — Read the value only
  - `"write"` — Write the value only
  - `"failok"` — If writing fails log errors only, don't fail the transfer
  - `"read,write"` — Read and Write the value.

---

### 🔐 `--drive-metadata-permissions`

Control whether permissions should be read or written in metadata. Same vibe as above but for perms. ✨

Reading permissions metadata from files <green>can be done quickly</green>, but it isn't always desirable to set the permissions from the metadata.

> ⚠️ Note: rclone <purple>drops any inherited permissions on Shared Drives</purple> and <purple>any owner permission on My Drives</purple>, since those are duplicated in the owner metadata anyway. Cleaning house. 🧹

**Properties:**

- **Config:** `metadata_permissions`
- **Env Var:** `RCLONE_DRIVE_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
  - `"failok"` — If writing fails log errors only, don't fail the transfer
  - `"read,write"` — Read and Write the value.

---

### 🏷️ `--drive-metadata-labels`

Control whether labels should be read or written in metadata. Labels!! We love a good label moment. 🎀

Reading labels metadata from files <yellow>takes an extra API transaction</yellow> and <red>will slow down listings</red>. Fair warning. And again, it isn't always desirable to set the labels from the metadata.

The format of labels is documented in the drive API documentation at `https://developers.google.com/drive/api/reference/rest/v3/Label` — rclone just provides a <green>JSON dump of this format</green>. Simple as that.

> ⚠️ Big one: when setting labels, <bold>the label and fields must already exist</bold> — rclone will <red>not create them</red>. So if you're transferring labels from two different accounts, you'll have to create the labels in advance <italic>and</italic> use the metadata mapper to translate the IDs between the two accounts. No cap. 😤

**Properties:**

- **Config:** `metadata_labels`
- **Env Var:** `RCLONE_DRIVE_METADATA_LABELS`
- **Type:** `Bits`
- **Default:** `off`
- **Examples:**
  - `"off"` — Do not read or write the value
  - `"read"` — Read the value only
  - `"write"` — Write the value only
  - `"failok"` — If writing fails log errors only, don't fail the transfer
  - `"read,write"` — Read and Write the value.

---

### 🌈 `--drive-encoding`

The encoding for the backend. You know, the little translator between the filesystem world and whatever chaos Drive is on that day. 💅

Peep the encoding section in the overview for more info, bestie.

**Properties:**

- **Config:** `encoding`
- **Env Var:** `RCLONE_DRIVE_ENCODING`
- **Type:** `Encoding`
- **Default:** `InvalidUtf8`

---

### 🪪 `--drive-env-auth`

Get IAM credentials from runtime — that means <italic>environment variables</italic>, or <italic>instance meta data</italic> if there are no env vars. Very fetch. 🦋

> ⚠️ This <bold>only applies if</bold> `service_account_file` and `service_account_credentials` are blank. If you filled those in, this flag is like… sitting in the corner, uninvited. 🙈

**Properties:**

- **Config:** `env_auth`
- **Env Var:** `RCLONE_DRIVE_ENV_AUTH`
- **Type:** `bool`
- **Default:** `false`
- **Examples:**
  - `"false"` — Enter credentials in the next step.
  - `"true"` — Get GCP IAM credentials from the environment (env vars or IAM).

---

### 📝 `--drive-description`

Description of the remote. Just a lil space for your own notes, so future-you knows what this remote even *is*. You're welcome. 💖

**Properties:**

- **Config:** `description`
- **Env Var:** `RCLONE_DRIVE_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

---

### 🗂️ Metadata

User metadata is stored in the `properties` field of the drive object. That's the spot. 📍

Metadata is supported on <green>files</green> and <green>directories</green>. Both. Equality. 💅

Here are the possible system metadata items for the drive backend.

- **`btime`** — when the file was born (its creation time), with mS accuracy 💖. And bestie, hear me on this one: it's **only writable on fresh uploads** — it literally *can't* be written for updates. (<italic>Type</italic>: `RFC 3339` · <italic>Example</italic>: `2006-01-02T15:04:05.999Z07:00` · <italic>Read Only</italic>: `N`)

- **`content-type`** — the MIME type of the file. (<italic>Type</italic>: `string` · <italic>Example</italic>: `text/plain` · <italic>Read Only</italic>: `N`)

- **`copy-requires-writer-permission`** — whether the options to copy, print, or download this file should be disabled for readers and commenters. (<italic>Type</italic>: `boolean` · <italic>Example</italic>: `true` · <italic>Read Only</italic>: `N`)

- **`description`** — a short description of the file. (<italic>Type</italic>: `string` · <italic>Example</italic>: `Contract for signing` · <italic>Read Only</italic>: `N`)

- **`folder-color-rgb`** — the color for a folder or a shortcut to a folder, as an RGB hex string 🎀. (<italic>Type</italic>: `string` · <italic>Example</italic>: `881133` · <italic>Read Only</italic>: `N`)

- **`labels`** — Labels attached to this file in a JSON dump of Googled drive format. Enable with `--drive-metadata-labels`. (<italic>Type</italic>: `JSON` · <italic>Example</italic>: `[]` · <italic>Read Only</italic>: `N`)

- **`mtime`** — time of last modification, with mS accuracy. (<italic>Type</italic>: `RFC 3339` · <italic>Example</italic>: `2006-01-02T15:04:05.999Z07:00` · <italic>Read Only</italic>: `N`)

- **`owner`** — the owner of the file. Usually an email address. Enable with `--drive-metadata-owner`. (<italic>Type</italic>: `string` · <italic>Example</italic>: `user@example.com` · <italic>Read Only</italic>: `N`)

- **`permissions`** — Permissions in a JSON dump of Google drive format. On shared drives these will only be present if they aren't inherited. Enable with `--drive-metadata-permissions`. (<italic>Type</italic>: `JSON` · <italic>Example</italic>: `{}` · <italic>Read Only</italic>: `N`)

- **`starred`** — whether the user has starred the file ⭐. (<italic>Type</italic>: `boolean` · <italic>Example</italic>: `false` · <italic>Read Only</italic>: `N`)

- **`viewed-by-me`** — whether the file has been viewed by this user 👀. (<italic>Type</italic>: `boolean` · <italic>Example</italic>: `true` · <italic>Read Only</italic>: `Y`)

- **`writers-can-share`** — whether users with only writer permission can modify the file's permissions. Not populated and ignored when setting for items in shared drives. (<italic>Type</italic>: `boolean` · <italic>Example</italic>: `false` · <italic>Read Only</italic>: `N`)

See the metadata docs for more info.

---

### ✨ Backend commands ✨

Okay so here are the commands that are specific to the drive backend, bestie 🫶.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

### get

Get command for fetching the drive config parameters 🍓

rclone backend get remote: [options] [<arguments>+]


This is a get command which will be used to fetch the various drive config parameters.

Usage Examples:

rclone backend get drive: [-o service_account_file] [-o chunk_size] rclone rc backend/command command=get fs=drive: [-o service_account_file] [-o chunk_size]


Options:

- `chunk_size`: show the current upload chunk size
- `service_account_file`: show the current service account file

### set

Set command for updating the drive config parameters 🌸

rclone backend set remote: [options] [<arguments>+]


This is a set command which will be used to update the various drive config parameters.

Usage Examples:

rclone backend set drive: [-o service_account_file=sa.json] [-o chunk_size=67108864] rclone rc backend/command command=set fs=drive: [-o service_account_file=sa.json] [-o chunk_size=67108864]


Options:

- `chunk_size`: update the current upload chunk size
- `service_account_file`: update the current service account file

### shortcut

Create shortcuts from files or directories 🦋

rclone backend shortcut remote: [options] [<arguments>+]


This command creates shortcuts from files or directories.

Usage:

rclone backend shortcut drive: source_item destination_shortcut rclone backend shortcut drive: source_item -o target=drive2: destination_shortcut


In the first example this creates a shortcut from the "source_item" which can be a file or a directory to the "destination_shortcut". The "source_item" and the "destination_shortcut" should be relative paths from `drive:`.

In the second example this creates a shortcut from the "source_item" relative to `drive:` to the "destination_shortcut" relative to `drive2:`. This may fail with a permission error if the user authenticated with `drive2:` can't read files from `drive:`.

Options:

- `target`: optional target remote for the shortcut destination

### drives

List the Shared Drives available to this account 👑

rclone backend drives remote: [options] [<arguments>+]


This command lists the Shared Drives (Team Drives) available to this account.

Usage:

rclone backend [-o config] drives drive:


This will return a JSON list of objects like this

[ { "id": "0ABCDEF-01234567890", "kind": "drive#teamDrive", "name": "My Drive" }, { "id": "0ABCDEFabcdefghijkl", "kind": "drive#teamDrive", "name": "Test Drive" } ]


With the `-o config` parameter it will output the list in a format suitable for adding to a config file to make aliases for all the drives found and a combined drive.

[My Drive] type = alias remote = drive,team_drive=0ABCDEF-01234567890,root_folder_id=:

[Test Drive] type = alias remote = drive,team_drive=0ABCDEFabcdefghijkl,root_folder_id=:

[AllDrives] type = combine upstreams = "My Drive=My Drive:" "Test Drive=Test Drive:"


Adding this to the rclone config file will cause those team drives to be accessible with the aliases shown. Any illegal characters will be substituted with `_` and duplicate names will have numbers suffixed. It will also add a remote called AllDrives which shows all the shared drives combined into one directory tree. 🌈

### untrash

Untrash files and directories 😭

rclone backend untrash remote: [options] [<arguments>+]


This command untrashes all the files and directories in the directory passed in recursively.

Usage:

This takes an optional directory to trash which make this easier to use via the API.

rclone backend untrash drive:directory rclone backend --interactive untrash drive:directory subdir


Use the `--interactive`/`-i` or `--dry-run` flag to see what would be restored before restoring it.

Result:

{ "Untrashed": 17, "Errors": 0 }


### copyid

Copy files by ID 💅

rclone backend copyid remote: [options] [<arguments>+]


This command copies files by ID

Usage:

rclone backend copyid drive: ID path rclone backend copyid drive: ID1 path1 ID2 path2


It copies the drive file with ID given to the path (an rclone path which will be passed internally to rclone copyto). The ID and path pairs can be repeated.

The path should end with a `/` to indicate copy the file as named to this directory. If it doesn't end with a `/` then the last path component will be used as the file name.

If the destination is a drive backend then server-side copying will be attempted if possible.

Use the `--interactive`/`-i` or `--dry-run` flag to see what would be copied before copying.

### exportformats

Dump the export formats for debug purposes 🔥

rclone backend exportformats remote: [options] [<arguments>+]


### importformats

Dump the import formats for debug purposes 🔥

rclone backend importformats remote: [options] [<arguments>+]


### query

List files using Google Drive query language 🧚

rclone backend query remote: [options] [<arguments>+]


This command lists files based on a query

Usage:

rclone backend query drive: query


The query syntax is documented at Google Drive Search query terms and operators.

<pink>okay so</pink> here's what that query actually spits back at you — a JSON array of matches, looking like this:

[ { "createdTime": "2017-06-29T19:58:28.537Z", "id": "0AxBe_CDEF4zkGHI4d0FjYko2QkD", "md5Checksum": "68518d16be0c6fbfab918be61d658032", "mimeType": "text/plain", "modifiedTime": "2024-02-02T10:40:02.874Z", "name": "foo ' \.txt", "parents": [ "0BxAe_BCDE4zkFGZpcWJGek0xbzC" ], "resourceKey": "0-ABCDEFGHIXJQpIGqBJq3MC", "sha1Checksum": "8f284fa768bfb4e45d076a579ab3905ab6bfa893", "size": "311", "webViewLink": "https://drive.google.com/file/d/0AxBe_CDEF4zkGHI4d0FjYko2QkD/view?usp=drivesdk\u0026resourcekey=0-ABCDEFGHIXJQpIGqBJq3MC" } ]


## 💖 rescue 💖

<purple>bestie this one is literally the orphan-finder.</purple> It rescues or deletes any orphaned files.

rclone backend rescue remote: [options] [<arguments>+]


This command rescues or deletes any orphaned files or directories. <yellow>iykyk</yellow>

Sometimes files can get orphaned in Google Drive. This means that they are no longer in any folder in Google Drive. <cyan>like… how did you get there girl, who is your parent</cyan>

This command finds those files and either rescues them to a directory you specify or deletes them.

<pink>**Usage:**</pink>

This can be used in 3 ways.

**First**, list all orphaned files:

rclone backend rescue drive:


**Second**, rescue all orphaned files to the directory indicated:

rclone backend rescue drive: "relative/path/to/rescue/directory"


e.g. To rescue all orphans to a directory called "Orphans" in the top level:

rclone backend rescue drive: Orphans


**Third**, delete all orphaned files to the trash:

rclone backend rescue drive: -o delete


## 😭 Limitations 😭

Drive has quite a lot of rate limiting. This causes rclone to be limited to transferring about **2 files per second** only. <red>two. per. second.</red> Individual files may be transferred much faster at **100s of MiB/s** but lots of small files can take a long time.

Server side copies are also subject to a separate rate limit. If you see `User rate limit exceeded` errors, wait at least **24 hours** and retry. You can disable server-side copies with `--disable copy` to download and upload the files if you prefer. <purple>desperate times fr</purple>

## 📄 Limitations of Google Docs 📄

Google docs will appear as size **-1** in `rclone ls`, `rclone ncdu` etc, and as size **0** in anything which uses the VFS layer, e.g. `rclone mount` and `rclone serve`. When calculating directory totals, e.g. in `rclone size` and `rclone ncdu`, they will be counted in as empty files.

This is because rclone can't find out the size of the Google docs without downloading them. <lavender>it's giving mystery box energy 💅</lavender>

Google docs will transfer correctly with `rclone sync`, `rclone copy` etc as rclone knows to ignore the size when doing the transfer.

However an unfortunate consequence of this is that you may not be able to download Google docs using `rclone mount`. If it doesn't work you will get a **0 sized file**. If you try again the doc may gain its correct size and be downloadable. Whether it will work on not depends on the application accessing the mount and the OS you are running — <hotpink>experiment to find out if it does work for you!</hotpink> 🔬✨

## 👯 Duplicated files 👯

Sometimes, for no reason I've been able to track down, drive will duplicate a file that rclone uploads. Drive unlike all the other remotes can have duplicated files. <yellow>messy of it</yellow>

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates.

Use `rclone dedupe` to fix duplicated files. <green>slay, problem solved</green>

Note that this isn't just a problem with rclone, even Google Photos on Android duplicates files on drive sometimes. <purple>so it's not our fault bestie</purple>

## 😤 Rclone appears to be re-copying files it shouldn't 😤

The most likely cause of this is the duplicated file issue above — run `rclone dedupe` and check your logs for `duplicate object` or `duplicate directory` messages.

This can also be caused by a delay/caching on google drive's end when comparing directory listings. Specifically with team drives used in combination with `--fast-list`. Files that were uploaded recently may not appear on the directory list sent to rclone when using `--fast-list`.

Waiting a moderate period of time between attempts (estimated to be approximately **1 hour**) and/or not using `--fast-list` both seem to be effective in preventing the problem. <cyan>patience era ✨</cyan>

## 🔐 SHA1 or SHA256 hashes may be missing 🔐

All files have MD5 hashes, but a small fraction of files uploaded may not have SHA1 or SHA256 hashes especially if they were uploaded before **2018**. <rainbow>historical artefact vibes</rainbow>

## 👑 Making your own client_id 👑

When you use rclone with Google drive in its default configuration you are using rclone's `client_id`. This is shared between all the rclone users. There is a global rate limit on the number of queries per second that each `client_id` can do set by Google. rclone already has a high quota and I will continue to make sure it is high enough by contacting Google.

It is **strongly recommended** to use your own client ID as the default rclone ID is heavily used. If you have multiple services running, it is recommended to use an API key for each service. The default Google quota is **10 transactions per second** so it is recommended to stay under that number as if you use more than that, it will cause rclone to rate limit and make things slower. <red>stay under 10 or she will throttle you 💀</red>

Here is how to create your own Google Drive client ID for rclone:

1. Log into the Google API Console with your Google account. It doesn't matter what Google account you use. (It need not be the same account as the Google Drive you want to access)

2. Select a project or create a new project.

3. Under "ENABLE APIS AND SERVICES" search for "Drive", and enable the "Google Drive API".

4. Click "Credentials" in the left-side panel (not "Create credentials", which opens the wizard).

5. If you already configured an "Oauth Consent Screen", then skip to the next step; if not, click on "CONFIGURE CONSENT SCREEN" button (near the top right corner of the right panel), then select "External" and click on "CREATE"; on the next screen, enter an "Application name" (`rclone` is OK); enter "User Support Email" (your own email is OK); enter "Developer Contact Email" (your own email is OK); then click on "Save" (all other data is optional). You will also have to add some scopes, including:
   - `https://www.googleapis.com/auth/docs`
   - `https://www.googleapis.com/auth/drive` in order to be able to edit, create and delete files with RClone.
   - `https://www.googleapis.com/auth/drive.metadata.readonly` which you may also want to add.
   - If you want to add all at once, comma separated it would be `https://www.googleapis.com/auth/docs,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.metadata.readonly`.

6. After adding scopes, click "Save and continue" to add test users. Be sure to add your own account to the test users. Once you've added yourself as a test user and saved the changes, click again on "Credentials" on the left panel to go back to the "Credentials" screen.

   (PS: if you are a GSuite user, you could also select "Internal" instead of "External" above, but this will restrict API use to Google Workspace users in your organisation).

7. Click on the "+ CREATE CREDENTIALS" button at the top of the screen, then select "OAuth client ID".

8. Choose an application type of "Desktop app" and click "Create". (the default name is fine)

9. It will show you a client ID and client secret. Make a note of these. <pink>write them down bestie, do NOT lose them</pink>

   (If you selected "External" at Step 5 continue to Step 10. If you chose "Internal" you don't need to publish and can skip straight to Step 11 but your destination drive must be part of the same Google Workspace.)

10. Go to "Oauth consent screen" and then click "PUBLISH APP" button and confirm. You will also want to add yourself as a test user.

11. Provide the noted client ID and client secret to rclone.

Be aware that, due to the "enhanced security" recently introduced by Google, you are theoretically expected to "submit your app for verification" and then wait a few weeks(!) for their response; in practice, you can go right ahead and use the client ID and client secret with rclone, the only issue will be a **very scary confirmation screen** shown when you connect via your browser for rclone to be able to get its token-id (but as this only happens during the remote configuration, it's not such a big deal). Keeping the application in "Testing" will work as well, but the limitation is that any grants will **expire after a week**, which can be annoying to refresh constantly. If, for whatever reason, a short grant time is not a problem, then keeping the application in testing mode would also be sufficient. <yellow>a whole week?? iconic of google honestly</yellow>

(Thanks to @balazer on github for these instructions.) 🫶

Sometimes, creation of an OAuth consent in Google API Console fails due to an error message `The request failed because changes to one of the field of the resource is not supported`. As a convenient workaround, the necessary Google Drive API key can be created on the Python Quickstart page. Just push the **Enable the Drive API** button to receive the Client ID and Secret. Note that it will automatically create a new project in the API Console.

---

# 🌸 Google Photos 🌸

The rclone backend for Google Photos is a specialized backend for transferring photos and videos to and from Google Photos. <cyan>pics and vids, moving around, cute</cyan>

> **NB** The Google Photos API which rclone uses has quite a few limitations, so please read the limitations section carefully to make sure it is suitable for your use. <red>fr fr do not skip this one</red>

## 🔧 Configuration 🔧

The initial setup for google cloud storage involves getting a token from Google Photos which you need to do in your browser. `rclone config` walks you through it. <purple>she's holding your hand the entire time, you're safe</purple>

Here is an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Google Photos \ "google photos" [snip] Storage> google photos ** See help for google photos backend at: https://rclone.org/googlephotos/ **

Google Application Client Id Leave blank normally. Enter a string value. Press Enter for the default (""). client_id> Google Application Client Secret Leave blank normally. Enter a string value. Press Enter for the default (""). client_secret> Set to make the Google Photos backend read only.

If you choose read only then rclone will only request read only access to your photos, otherwise rclone will request full access. Enter a boolean value (true or false). Press Enter for the default ("false"). read_only> 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

* IMPORTANT: All media items uploaded to Google Photos with rclone * are stored in full resolution at original quality. These uploads *** will count towards storage in your Google Account.

Configuration complete. Options:

type: google photos
token: {"access_token":"XXX","token_type":"Bearer","refresh_token":"XXX","expiry":"2019-06-28T17:38:04.644930156+01:00"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


Ok so head over to the <pink>remote setup docs</pink> if you gotta do this on a machine with <italic>no</italic> browser at all, bestie. They got you. 💖

Also important bestie, rclone spins up a <hotpink>little webserver on your own local machine</hotpink> to catch that token when Google hands it back — but only if you're using the web browser auto-auth flow. It lives <italic>only</italic> from the moment it opens your browser until the moment the verification code lands back in its lap. The address is `http://127.0.0.1:53682/` and listen, if you're rocking a host firewall you might have to unblock it temporarily, or just go manual mode instead. 🫶

Now this remote is literally called `remote` and you can start using it like this 👑

See <rainbow>all the albums</rainbow> in your photos:

rclone lsd remote:album


Make a brand new album, main character move:

rclone mkdir remote:album/newAlbum


Peep what's inside an album:

rclone ls remote:album/newAlbum


Sync `/home/local/images` up to Google Photos and clear out any extra files in the album:

rclone sync --interactive /home/local/image remote:album/newAlbum


---

## 🦋 Layout 🦋

So Google Photos is <italic>not</italic> a general purpose cloud storage system (it's giving photo album, not file cabinet 😭), so the backend is laid out to help you actually navigate it.

The directories under `media` show different ways of categorizing the media. And here's the thing — <yellow>every single file will show up multiple times</yellow>. So if you wanna back up your google photos, maybe pick `remote:media/by-month`. (ngl `remote:media/by-day` is kinda slow right now so avoid it for syncing, fr.)

And lowkey note: all your photos and videos will appear <italic>somewhere</italic> under `media`, but they might not show up under `album` unless you've actually put them into albums. 🙈

upload
- file1.jpg
- file2.jpg
- ...
media
- all
  - file1.jpg
  - file2.jpg
  - ...
- by-year
  - 2000
    - file1.jpg
    - ...
  - 2001
    - file2.jpg
    - ...
  - ...
- by-month
  - 2000
    - 2000-01
    - file1.jpg
    - ...
    - 2000-02
    - file2.jpg
    - ...
  - ...
- by-day
  - 2000
    - 2000-01-01
    - file1.jpg
    - ...
    - 2000-01-02
    - file2.jpg
    - ...
  - ...
album
- album name
- album name/sub
shared-album
- album name
- album name/sub
feature
- favorites
  - file1.jpg
  - file2.jpg


There are <green>two writable parts</green> of the tree: the `upload` directory and the sub directories of the `album` directory. ✨

The `upload` directory is for uploading files you don't want to put into albums. It starts out empty and will only hold the files you've uploaded for <italic>one rclone session</italic> — it goes empty again the second you restart rclone. The use case here? You got a big pile of files and you just wanna one-off dump them into Google Photos. For repeated syncing though, uploading to `album` works better. 💅

Directories inside the `album` directory are also writeable, and you can create new directories (albums) under `album`. If you copy files in with a directory hierarchy, rclone will create albums with the `/` character in them. So like if you do

rclone copy /path/to/images remote:album/images


and the `images` directory contains

images

file1.jpg dir file2.jpg dir2 dir3 file3.jpg


Then rclone will create the following albums with the following files in:

- images

  - file1.jpg

- images/dir

  - file2.jpg

- images/dir2/dir3

  - file3.jpg

Which means you can use the `album` path pretty much like a normal filesystem, and it's a <green>great target for repeated syncing</green>. 👑

The `shared-album` directory shows albums shared with you or by you. It's basically the `Sharing` tab in the Google Photos web interface. 🌸

---

## 🌈 Standard options 🌈

Here are the Standard options specific to google photos (Google Photos).

- **`--gphotos-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_GPHOTOS_CLIENT_ID`
  - Type: string
  - Required: false

- **`--gphotos-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:

  - Config: `client_secret`
  - Env Var: `RCLONE_GPHOTOS_CLIENT_SECRET`
  - Type: string
  - Required: false

- **`--gphotos-read-only`** — Set to make the Google Photos backend read only.

  If you choose read only then rclone will only request read only access to your photos, otherwise rclone will request full access.

  Properties:

  - Config: `read_only`
  - Env Var: `RCLONE_GPHOTOS_READ_ONLY`
  - Type: bool
  - Default: false

---

## ✨ Advanced options ✨

Here are the Advanced options specific to google photos (Google Photos).

- **`--gphotos-token`** — OAuth Access Token as a JSON blob.

  Properties:

  - Config: `token`
  - Env Var: `RCLONE_GPHOTOS_TOKEN`
  - Type: string
  - Required: false

- **`--gphotos-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `auth_url`
  - Env Var: `RCLONE_GPHOTOS_AUTH_URL`
  - Type: string
  - Required: false

- **`--gphotos-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `token_url`
  - Env Var: `RCLONE_GPHOTOS_TOKEN_URL`
  - Type: string
  - Required: false

- **`--gphotos-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Properties:

  - Config: `client_credentials`
  - Env Var: `RCLONE_GPHOTOS_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: false

- **`--gphotos-read-size`** — Set to read the size of media items.

  Normally rclone does not read the size of media items since this takes another transaction. This isn't necessary for syncing. However rclone mount needs to know the size of files in advance of reading them, so setting this flag when using rclone mount is recommended if you want to read the media.

  Properties:

  - Config: `read_size`
  - Env Var: `RCLONE_GPHOTOS_READ_SIZE`
  - Type: bool
  - Default: false

- **`--gphotos-start-year`** — Year limits the photos to be downloaded to those which are uploaded after the given year.

  Properties:

  - Config: `start_year`
  - Env Var: `RCLONE_GPHOTOS_START_YEAR`
  - Type: int
  - Default: 2000

- **`--gphotos-include-archived`** — Also view and download archived media.

  By default, rclone does not request archived media. Thus, when syncing, archived media is not visible in directory listings or transferred.

  Note that media in albums is always visible and synced, no matter their archive status.

  With this flag, archived media are always visible in directory listings and transferred.

  Without this flag, archived media will not be visible in directory listings and won't be transferred.

  Properties:

  - Config: `include_archived`
  - Env Var: `RCLONE_GPHOTOS_INCLUDE_ARCHIVED`
  - Type: bool
  - Default: false

- **`--gphotos-proxy`** — Use the gphotosdl proxy for downloading the full resolution images

  The Google API will deliver images and video which aren't full resolution, and/or have EXIF data missing.

  However if you use the gphotosdl proxy then you can download original, unchanged images.

  This runs a headless browser in the background.

  Download the software from gphotosdl

  First run with

gphotosdl -login


Then once you have logged into google photos close the browser window and run

gphotosdl


Then supply the parameter `--gphotos-proxy "http://localhost:8282"` to make rclone use the proxy.

Properties:

- Config: `proxy`
- Env Var: `RCLONE_GPHOTOS_PROXY`
- Type: string
- Required: false

- <lavender>**`--gphotos-encoding`**</lavender> — the encoding for this backend, bestie. 💅

Wanna know more? Go peek at the encoding section in the overview, that's where all the lore lives.

Properties (the receipts ✨):

- Config: `encoding`
- Env Var: `RCLONE_GPHOTOS_ENCODING`
- Type: `Encoding`
- Default: `Slash,CrLf,InvalidUtf8,Dot`

- <lavender>**`--gphotos-batch-mode`**</lavender> — upload file batching: `sync|async|off`. 🎀

This is the batch mode rclone rolls with. Three options, no more no less:

- `off` — no batching at all, we're doing this one at a time like a peasant 😭
- `sync` — batch uploads **and** check completion (this is the default, she's the main character 👑)
- `async` — batch upload and don't check completion, we live dangerously 💀

Heads up: rclone will close any outstanding batches when it exits, which may make a delay on quit. Not a bug, just ✨the way she is✨.

Properties:

- Config: `batch_mode`
- Env Var: `RCLONE_GPHOTOS_BATCH_MODE`
- Type: `string`
- Default: `"sync"`

- <lavender>**`--gphotos-batch-size`**</lavender> — max number of files in an upload batch. 🍓

Sets how many files go in one batch. **It has to be less than 50**, okay? The limit is limit-ing. 🙈

By default this is `0`, which means rclone will calculate the batch size depending on the setting of `batch_mode`:

- `batch_mode: async` — default `batch_size` is `50`
- `batch_mode: sync` — default `batch_size` is the same as `--transfers`
- `batch_mode: off` — not in use

Also, again, rclone will close any outstanding batches when it exits which may make a delay on quit. Same girl, same warning. 💅

Setting this is a **great** idea if you are uploading lots of small files as it will make them a lot quicker. You can use `--transfers 32` to maximise throughput. Slay. 🔥

Properties:

- Config: `batch_size`
- Env Var: `RCLONE_GPHOTOS_BATCH_SIZE`
- Type: `int`
- Default: `0`

- <lavender>**`--gphotos-batch-timeout`**</lavender> — max time to allow an idle upload batch before uploading. ⏰

If an upload batch is idle for more than this long then it will be uploaded. She's not gonna wait around forever, periodt.

The default for this is `0` which means rclone will choose a sensible default based on the `batch_mode` in use:

- `batch_mode: async` — default `batch_timeout` is `10s`
- `batch_mode: sync` — default `batch_timeout` is `1s`
- `batch_mode: off` — not in use

Properties:

- Config: `batch_timeout`
- Env Var: `RCLONE_GPHOTOS_BATCH_TIMEOUT`
- Type: `Duration`
- Default: `0s`

- <lavender>**`--gphotos-batch-commit-timeout`**</lavender> — max time to wait for a batch to finish committing. 🫶

Properties:

- Config: `batch_commit_timeout`
- Env Var: `RCLONE_GPHOTOS_BATCH_COMMIT_TIMEOUT`
- Type: `Duration`
- Default: `10m0s`

- <lavender>**`--gphotos-description`**</lavender> — description of the remote, just a lil note-to-self about which remote this even is. 📝

Properties:

- Config: `description`
- Env Var: `RCLONE_GPHOTOS_DESCRIPTION`
- Type: `string`
- Required: `false`

---

## 🚧 Limitations 🚧

Okay bestie, sit down, this is the part where we talk about what she **cannot** do. Not her fault, it's the API's fault, but still — vibe check time. 😭

Only images and videos can be uploaded. If you attempt to upload non videos or images, or formats that Google Photos doesn't understand, rclone will upload the file, then Google Photos will give an error when it is put turned into a media item. Like, the upload succeeds and then it just... doesn't. 💀

Note that all media items uploaded to Google Photos through the API are stored in full resolution at "original quality" and will count towards your storage quota in your Google Account. The API does not offer a way to upload in "high quality" mode. There is no high quality mode. She does not know her. 🙈

`rclone about` is **not supported** by the Google Photos backend. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote.

See List of backends that do not support `rclone about`
See `rclone about`

### 🌸 Downloading Images 🌸

When Images are downloaded this strips EXIF location (according to the docs and my tests). This is a limitation of the Google Photos API and is covered by bug `#112096115`.

The current google API does not allow photos to be downloaded at original resolution. This is **very important** if you are, for example, relying on "Google Photos" as a backup of your photos. You will not be able to use rclone to redownload original images. You could use `google takeout` to recover the original photos as a last resort. 🫡

> NB you can use the `--gphotos-proxy` flag to use a headless browser to download images in full resolution. 👑

### 🦋 Downloading Videos 🦋

When videos are downloaded they are downloaded in a really compressed version of the video compared to downloading it via the Google Photos web interface. This is covered by bug `#113672044`. She's crunchy. Not in the cute way.

> NB you can use the `--gphotos-proxy` flag to use a headless browser to download images in full resolution. (Yes, same flag, same energy. ✨)

### 🎀 Duplicates 🎀

If a file name is duplicated in a directory then rclone will add the file ID into its name. So two files called `file.jpg` would then appear as `file {123456}.jpg` and `file {ABCDEF}.jpg` (the actual IDs are a lot longer alas!). Not me naming things like a chaos demon. 💅

If you upload the same image (with the same binary data) twice then Google Photos will deduplicate it. However it will retain the filename from the first upload which may confuse rclone. For example if you uploaded an image to `upload` then uploaded the same image to `album/my_album` the filename of the image in `album/my_album` will be what it was uploaded with initially, not what you uploaded it with to `album`. In practise this shouldn't cause too many problems. Lowkey fine. 🫶

### 🌈 Modification times 🌈

The date shown of media in Google Photos is the creation date as determined by the EXIF information, or the upload date if that is not known.

This is **not changeable** by rclone and is not the modification date of the media on local disk. This means that rclone cannot use the dates from Google Photos for syncing purposes. She is simply not that kind of girl. 😭

### ⭐ Size ⭐

The Google Photos API does not return the size of media. This means that when syncing to Google Photos, rclone can only do a file existence check.

It is possible to read the size of the media, but this needs an extra HTTP HEAD request per media item so is very slow and uses up a lot of transactions. This can be enabled with the `--gphotos-read-size` option or the `read_size = true` config parameter.

If you want to use the backend with `rclone mount` you may need to enable this flag (depending on your OS and application using the photos) otherwise you may not be able to read media off the mount. You'll need to experiment to see if it works for you without the flag. Science, bestie. 🧪

### 💜 Albums 💜

Rclone can **only** upload files to albums it created. This is a limitation of the Google Photos API.

Rclone can remove files it uploaded from albums it created only. That's the deal. 🤝

### 💖 Deleting files 💖

Rclone can remove files from albums it created, but note that the Google Photos API does not allow media to be deleted permanently so this media will still remain. See bug `#109759781`.

Rclone **cannot** delete files anywhere except under `album`. Nowhere else. Not even a little. 🚫

### 👑 Deleting albums 👑

The Google Photos API does not support deleting albums — see bug `#135714733`. They simply do not allow it and we must respect it. 💀

# ✨ Hasher ✨

okay so Hasher is <pink>not</pink> like a regular backend bestie, it's a special lil <hotpink>overlay backend</hotpink> that builds remotes whose whole job is handling <purple>checksums</purple> for *other* remotes 💅

Its main functions include:

- Emulate hash types unimplemented by backends
- Cache checksums to help with slow hashing of large local or (S)FTP files
- Warm up checksum cache from external SUM files

---

## 🌸 Getting started 🌸

To use Hasher, first set up the underlying remote following the configuration instructions for that remote. You can also use a local pathname instead of a remote. Check that your base remote is working. 🫶

Let's call the base remote `myRemote:path` here. Note that <yellow>anything inside `myRemote:path` will be handled by hasher and anything outside won't</yellow>. This means that if you are using a bucket based remote (S3, B2, Swift) then you should put the bucket in the remote `s3:bucket`.

Now proceed to interactive or manual configuration. ✨

---

## ✨ Interactive configuration ✨

Run `rclone config`:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> Hasher1 Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Handle checksums for other remotes \ "hasher" [snip] Storage> hasher Remote to cache checksums for, like myremote:mypath. Enter a string value. Press Enter for the default (""). remote> myRemote:path Comma separated list of supported checksum types. Enter a string value. Press Enter for the default ("md5,sha1"). hashsums> md5 Maximum time to keep checksums in cache. 0 = no cache, off = cache forever. max_age> off Edit advanced config? (y/n) y) Yes n) No y/n> n Remote config

[Hasher1] type = hasher remote = myRemote:path hashsums = md5 max_age = off

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


---

## 🌸 Manual configuration 🌸

Run `rclone config path` to see the path of current active config file, usually `YOURHOME/.config/rclone/rclone.conf`. Open it in your favorite text editor, find section for the base remote and create new section for hasher like in the following examples:

[Hasher1] type = hasher remote = myRemote:path hashes = md5 max_age = off

[Hasher2] type = hasher remote = /local/path hashes = dropbox,sha1 max_age = 24h


Hasher takes basically the following parameters:

- `remote` is required,
- `hashes` is a comma separated list of supported checksums (by default `md5,sha1`),
- `max_age` - maximum time to keep a checksum value in the cache, `0` will disable caching completely, `off` will cache "forever" (that is until the files get changed).

Make sure the remote has `:` (colon) in. If you specify the remote without a colon then rclone will use a local directory of that name. So if you use a remote of `/local/path` then rclone will handle hashes for that directory. If you use `remote = name` literally then rclone will put files in a directory called `name` located under current directory. <cyan>iykyk 👑</cyan>

---

## ✨ Usage ✨

## 🌸 Basic operations 🌸

Now you can use it as `Hasher2:subdir/file` instead of base remote. Hasher will transparently update cache with new checksums when a file is fully read or overwritten, like:

rclone copy External:path/file Hasher:dest/path

rclone cat Hasher:path/to/file > /dev/null


The way to refresh all cached checksums (even unsupported by the base backend) for a subtree is to re-download all files in the subtree. For example, use `hashsum --download` using any supported hashsum on the command line (we just care to re-read):

rclone hashsum MD5 --download Hasher:path/to/subtree > /dev/null

rclone backend dump Hasher:path/to/subtree


You can print or drop hashsum cache using custom backend commands:

rclone backend dump Hasher:dir/subdir

rclone backend drop Hasher:


---

## ✨ Pre-Seed from a SUM File ✨

Hasher supports two backend commands: generic SUM file import and faster but less consistent `stickyimport`. 🦋

rclone backend import Hasher:dir/subdir SHA1 /path/to/SHA1SUM [--checkers 4]


Instead of `SHA1` it can be any hash supported by the remote. The last argument can point to either a local or an `other-remote:path` text file in SUM format. The command will parse the SUM file, then walk down the path given by the first argument, snapshot current fingerprints and fill in the cache entries correspondingly.

- Paths in the SUM file are treated as relative to `hasher:dir/subdir`.
- The command will **not** check that supplied values are correct. You must know what you are doing.
- This is a one-time action. The SUM file will not get "attached" to the remote. Cache entries can still be overwritten later, should the object's fingerprint change.
- The tree walk can take long depending on the tree size. You can increase `--checkers` to make it faster. Or use `stickyimport` if you don't care about fingerprints and consistency.

rclone backend stickyimport hasher:path/to/data sha1 remote:/path/to/sum.sha1


`stickyimport` is similar to `import` but works much faster because it does not need to `stat` existing files and skips initial tree walk. Instead of binding cache entries to file fingerprints it creates <hotpink>sticky</hotpink> entries bound to the file name alone ignoring size, modification time etc. Such hash entries can be replaced only by `purge`, `delete`, `backend drop` or by full re-read/re-write of the files. 💀

---

## 🌸 Configuration reference 🌸

## ✨ Standard options ✨

Here are the Standard options specific to hasher (Better checksums for other remotes). ⭐

## 🌸 `--hasher-remote` 🌸

Remote to cache checksums for (e.g. `myRemote:path`).

Properties:

- Config: `remote`
- Env Var: `RCLONE_HASHER_REMOTE`
- Type: `string`
- Required: `true`

## ✨ `--hasher-hashes` ✨

Comma separated list of supported checksum types.

Properties:

- Config: `hashes`
- Env Var: `RCLONE_HASHER_HASHES`
- Type: `CommaSepList`
- Default: `md5,sha1`

## 🌸 `--hasher-max-age` 🌸

Maximum time to keep checksums in cache (`0` = no cache, `off` = cache forever).

Properties:

- Config: `max_age`
- Env Var: `RCLONE_HASHER_MAX_AGE`
- Type: `Duration`
- Default: `off`

## ✨ Advanced options ✨

Here are the Advanced options specific to hasher (Better checksums for other remotes). 🔥

## 🌸 `--hasher-auto-size` 🌸

Auto-update checksum for files smaller than this size (disabled by default).

Properties:

- Config: `auto_size`
- Env Var: `RCLONE_HASHER_AUTO_SIZE`
- Type: `SizeSuffix`
- Default: `0`

## ✨ `--hasher-description` ✨

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_HASHER_DESCRIPTION`
- Type: `string`
- Required: `false`

---

## 🌸 Metadata 🌸

Any metadata supported by the underlying remote is read and written. 🫶

See the metadata docs for more info.

---

## ✨ Backend commands ✨

Here are the commands specific to the hasher backend.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

## 🌸 drop 🌸

Drop cache

rclone backend drop remote: [options] [<arguments>+]


Completely drop checksum cache. Usage Example: `rclone backend drop hasher:`

## ✨ dump ✨

Dump the database

rclone backend dump remote: [options] [<arguments>+]


Dump cache records covered by the current remote

## 🌸 fulldump 🌸

Full dump of the database

rclone backend fulldump remote: [options] [<arguments>+]


Dump all cache records in the database

## ✨ import ✨

Import a SUM file

rclone backend import remote: [options] [<arguments>+]


Amend hash cache from a SUM file and bind checksums to files by size/time. Usage Example: `rclone backend import hasher:subdir md5 /path/to/sum.md5`

## 🌸 stickyimport 🌸

Perform fast import of a SUM file

rclone backend stickyimport remote: [options] [<arguments>+]


Fill hash cache from a SUM file without verifying file fingerprints. Usage Example: `rclone backend stickyimport hasher:subdir md5 remote:path/to/sum.md5`

---

## ✨ Implementation details (advanced) ✨

This section explains how various rclone operations work on a hasher remote.

> Disclaimer. This section describes current implementation which can change in future rclone versions! 😭

## 🌸 Hashsum command 🌸

The `rclone hashsum` (or `md5sum` or `sha1sum`) command will:

1. if requested hash is supported by lower level, just pass it.
2. if object size is below `auto_size` then download object and calculate requested hashes on the fly.
3. if unsupported and the size is big enough, build object fingerprint (including size, modtime if supported, first-found other hash if any).
4. if the strict match is found in cache for the requested remote, return the stored hash.
5. if remote found but fingerprint mismatched, then purge the entry and proceed to step 6.
6. if remote not found or had no requested hash type or after step 5: download object, calculate all supported hashes on the fly and store in cache; return requested hash.

## ✨ Other operations ✨

- any time a hash is requested, follow the logic from 1-4 from `hashsum` above
- whenever a file is uploaded or downloaded in full, capture the stream to calculate all supported hashes on the fly and update database
- server-side move will update keys of existing cache entries
- `deletefile` will remove a single cache entry
- `purge` will remove all cache entries under the purged path

Note that setting `max_age = 0` will disable checksum caching completely.

If you set `max_age = off`, checksums in cache will never age, unless you fully rewrite or delete the file. 💅

## 🌸 Cache storage 🌸

Cached checksums are stored as <purple>bolt database</purple> files under rclone cache directory, usually `~/.cache/rclone/kv/`. Databases are maintained one per base backend, named like `BaseRemote~hasher.bolt`. Checksums for multiple `alias`-es into a single base backend will be stored in the single database. All local paths are treated as aliases into the `local` backend (unless encrypted or chunked) and stored in `~/.cache/rclone/kv/local~hasher.bolt`. Databases can be shared between multiple rclone processes. 🌈

# 🌈 HDFS 🌈

ok so HDFS is a distributed file-system, and it's part of the Apache Hadoop framework 💛

Paths are written like `remote:` or `remote:path/to/dir`.

---

## 🛠️ Configuration 🛠️

here's how you make a remote called `remote`, bestie. first run:

rclone config


and it will hold your hand through the whole interactive setup, no cap:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 [skip] XX / Hadoop distributed file system \ "hdfs" [skip] Storage> hdfs ** See help for hdfs backend at: https://rclone.org/hdfs/ **

hadoop name node and port Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Connect to host namenode at port 8020 \ "namenode:8020" namenode> namenode.hadoop:8020 hadoop user name Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Connect to hdfs as root \ "root" username> root Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config Configuration complete. Options:

type: hdfs
namenode: namenode.hadoop:8020
username: root Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== hadoop hdfs

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> q


so this remote is called `remote` and now you can do stuff with it like 👇

**See all the top level directories**

rclone lsd remote:


**List the contents of a directory**

rclone ls remote:directory


**Sync the remote directory to `/home/local/directory`, deleting any excess files.**

rclone sync --interactive remote:directory /home/local/directory


---

## 🧪 Setting up your own HDFS instance for testing 🧪

you can go full manual setup, or just vibe with the docker image from the tests 🐳

if you wanna build the docker image yourself:

git clone https://github.com/rclone/rclone.git cd rclone/fstest/testserver/images/test-hdfs docker build --rm -t rclone/test-hdfs .


or honestly just grab the latest one already pushed:

docker run --rm --name "rclone-hdfs" -p 127.0.0.1:9866:9866 -p 127.0.0.1:8020:8020 --hostname "rclone-hdfs" rclone/test-hdfs


NB it need few seconds to startup. (literally give it a sec okay 😭)

for this docker image the remote has to be configured exactly like this:

[remote] type = hdfs namenode = 127.0.0.1:8020 username = root


you can stop this image with `docker kill rclone-hdfs` — NB it does not use volumes, so all data uploaded will be lost. gone. poof. 💀

---

## ⏰ Modification times ⏰

Time accurate to 1 second is stored. ✨

---

## 🔍 Checksum 🔍

No checksums are implemented. that's it, that's the whole section 🙈

---

## 📊 Usage information 📊

you can use the `rclone about remote:` command, and it will display filesystem size and current usage 👑

---

## 🚫 Restricted filename characters 🚫

on top of the default restricted characters set, these extra characters also get replaced:

- `:` — value `0x3A` — replaced with `：`

Invalid UTF-8 bytes will also be replaced.

---

## 💅 Standard options 💅

here are the Standard options specific to hdfs (Hadoop distributed file system).

---

### 🌟 --hdfs-namenode 🌟

Hadoop name nodes and ports.

E.g. `“namenode-1:8020,namenode-2:8020,...”` to connect to host namenodes at port 8020.

Properties:

- **Config:** `namenode`
- **Env Var:** `RCLONE_HDFS_NAMENODE`
- **Type:** `CommaSepList`
- **Default:**

### 🌟 --hdfs-username 🌟

Hadoop user name.

Properties:

- **Config:** `username`
- **Env Var:** `RCLONE_HDFS_USERNAME`
- **Type:** `string`
- **Required:** `false`
- **Examples:**
  - `“root”`
    - Connect to hdfs as root.

---

## 🚀 Advanced options 🚀

here are the Advanced options specific to hdfs (Hadoop distributed file system).

---

### 🔐 --hdfs-service-principal-name 🔐

Kerberos service principal name for the namenode.

Enables KERBEROS authentication. Specifies the Service Principal Name (SERVICE/FQDN) for the namenode. E.g. `"hdfs/namenode.hadoop.docker"` for namenode running as service `hdfs` with FQDN `namenode.hadoop.docker`.

Properties:

- **Config:** `service_principal_name`
- **Env Var:** `RCLONE_HDFS_SERVICE_PRINCIPAL_NAME`
- **Type:** `string`
- **Required:** `false`

### 🛡️ --hdfs-data-transfer-protection 🛡️

Kerberos data transfer protection: authentication|integrity|privacy.

Specifies whether or not authentication, data signature integrity checks, and wire encryption are required when communicating with the datanodes. Possible values are `authentication`, `integrity` and `privacy`. Used only with KERBEROS enabled.

Properties:

- **Config:** `data_transfer_protection`
- **Env Var:** `RCLONE_HDFS_DATA_TRANSFER_PROTECTION`
- **Type:** `string`
- **Required:** `false`
- **Examples:**
  - `“privacy”`
    - Ensure authentication, integrity and encryption enabled.

### 🔤 --hdfs-encoding 🔤

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_HDFS_ENCODING`
- **Type:** `Encoding`
- **Default:** `Slash,Colon,Del,Ctl,InvalidUtf8,Dot`

### 📝 --hdfs-description 📝

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_HDFS_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

---

## 😔 Limitations 😔

- No server-side Move or DirMove.
- Checksums not implemented.

---

# 🦋 HiDrive 🦋

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

The initial setup for hidrive involves getting a token from HiDrive which you need to do in your browser. `rclone config` walks you through it. 🫶

---

## 🛠️ Configuration 🛠️

here's an example of how to make a remote called `remote`. first run:

rclone config


it'll guide you through the interactive setup, like so:

No remotes found - make a new one n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / HiDrive \ "hidrive" [snip] Storage> hidrive OAuth Client Id - Leave blank normally. client_id> OAuth Client Secret - Leave blank normally. client_secret> Access permissions that rclone should use when requesting access from HiDrive. Leave blank normally. scope_access> Edit advanced config? y/n> n 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/n> y If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth?state=xxxxxxxxxxxxxxxxxxxxxx Log in and authorize rclone for access Waiting for code... Got code Configuration complete. Options:
type: hidrive
token: {"access_token":"xxxxxxxxxxxxxxxxxxxx","token_type":"Bearer","refresh_token":"xxxxxxxxxxxxxxxxxxxxxxx","expiry":"xxxxxxxxxxxxxxxxxxxxxxx"} Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


> bestie real talk: OAuth-tokens can be used to access your account and hence should not be shared with other persons. See the below section for more information. 👀

See the remote setup docs for how to set it up on a machine with no Internet browser available.

Note that rclone runs a webserver on your local machine to collect the token as returned from HiDrive. This only runs from the moment it opens your browser to the moment you get back the verification code. The webserver runs on `http://127.0.0.1:53682/`. If local port 53682 is protected by a firewall you may need to temporarily unblock the firewall to complete authorization. 🔥

Once configured you can then use rclone like this,

**List directories in top level of your HiDrive root folder**

rclone lsd remote:


**List all the files in your HiDrive filesystem**

rclone ls remote:


**To copy a local directory to a HiDrive directory called backup**

rclone copy /home/source remote:backup


---

## 🔒 Keeping your tokens safe 🔒

Any OAuth-tokens will be stored by rclone in the remote's configuration file as unencrypted text. Anyone can use a valid refresh-token to access your HiDrive filesystem without knowing your password. Therefore you should make sure no one else can access your configuration. 💀

It is possible to encrypt rclone's configuration file. You can find information on securing your configuration file by viewing the configuration encryption docs.

---

## ⏳ Invalid refresh token ⏳

As can be verified here, each `refresh_token` (for Native Applications) is valid for 60 days. If used to access HiDrivei, its validity will be automatically extended.

This means that if you

- Don't use the HiDrive remote for 60 days

then rclone will return an error which includes a text that implies the refresh token is invalid or expired. 😭

To fix this you will need to authorize rclone to access your HiDrive account again.

Using

rclone config reconnect remote:


the process is very similar to the process of initial setup exemplified before. ✨

---

## ⏰ Modification times and hashes ⏰

HiDrive allows modification times to be set on objects accurate to 1 second.

HiDrive supports its own hash type which is used to verify the integrity of file contents after successful transfers. 👑

## 🌈 Restricted filename characters

Okay so bestie, HiDrive is *picky* about names, and here's the tea 💅 — it literally cannot store files or folders that have `/` (`0x2F`) or null-bytes (`0x00`) in their name. Everything else? Totally fine, go off. *But* — and this is the plot twist — files or folders also can't be named either of these two things: `.` or `..`.

So obviously rclone handles that for you and automatically swaps out those characters whenever files or folders get stored or accessed with names like that. Iconic behavior, no notes.

You can read about how this filename encoding works in general here.

> Heads up bestie: HiDrive only supports file or folder names that are **255 characters or less**. That's the limit, periodt.

---

## 🚚 Transfers

HiDrive caps file sizes per single request at a maximum of **2 GiB**. So to let you store bigger files *and* get better upload performance, the hidrive backend does a chunked transfer for any file larger than **96 MiB**. rclone will upload multiple parts/chunks of the file at the same time 🎀.

The chunks that are mid-upload get buffered in memory, so if your system is running on limited resources, you might wanna rein in this behavior.

You can customize this using these options:

- `chunk_size`: size of file parts
- `upload_cutoff`: files larger or equal to this in size will use a chunked transfer
- `upload_concurrency`: number of file-parts to upload at the same time

See the below section about configuration options for more details.

---

## 📁 Root folder

You can set the root folder for rclone — this is the directory that rclone treats as the root of your HiDrive.

Usually you just leave this blank and rclone uses the root of the account. Simple as that ✨

But you *can* set it to restrict rclone to a specific folder hierarchy. How it works: it prepends the contents of the `root_prefix` option to any paths accessed by rclone. So for example, these two ways to access the home directory are equivalent:

rclone lsd --hidrive-root-prefix="/users/test/" remote:path

rclone lsd remote:/users/test/path


See the below section about configuration options for more details.

---

## 🔢 Directory member count

By default, rclone will know the number of directory members contained in a directory. For example, `rclone lsd` uses this information. Slay 💖

But getting this info means extra time costs from HiDrive's API. When you're dealing with big directory structures, it might be worth dodging that time cost — especially when you don't actually need this information. That's what the `disable_fetching_member_count` option is for.

See the below section about configuration options for more details.

---

## ⚙️ Standard options

Here are the Standard options specific to `hidrive` (HiDrive).

### `--hidrive-client-id`

OAuth Client Id.

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_HIDRIVE_CLIENT_ID`
- Type: string
- Required: false

### `--hidrive-client-secret`

OAuth Client Secret.

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_HIDRIVE_CLIENT_SECRET`
- Type: string
- Required: false

### `--hidrive-scope-access`

Access permissions that rclone should use when requesting access from HiDrive.

Properties:

- Config: `scope_access`
- Env Var: `RCLONE_HIDRIVE_SCOPE_ACCESS`
- Type: string
- Default: `"rw"`
- Examples:
  - `"rw"`
    - Read and write access to resources.
  - `"ro"`
    - Read-only access to resources.

---

## 🚀 Advanced options

Here are the Advanced options specific to `hidrive` (HiDrive).

### `--hidrive-token`

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_HIDRIVE_TOKEN`
- Type: string
- Required: false

### `--hidrive-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_HIDRIVE_AUTH_URL`
- Type: string
- Required: false

### `--hidrive-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_HIDRIVE_TOKEN_URL`
- Type: string
- Required: false

### `--hidrive-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_HIDRIVE_CLIENT_CREDENTIALS`
- Type: bool
- Default: false

### `--hidrive-scope-role`

User-level that rclone should use when requesting access from HiDrive.

Properties:

- Config: `scope_role`
- Env Var: `RCLONE_HIDRIVE_SCOPE_ROLE`
- Type: string
- Default: `"user"`
- Examples:
  - `"user"`
    - User-level access to management permissions.
    - This will be sufficient in most cases.
  - `"admin"`
    - Extensive access to management permissions.
  - `"owner"`
    - Full access to management permissions.

### `--hidrive-root-prefix`

The root/parent folder for all paths.

Fill in to use the specified folder as the parent for all paths given to the remote. This way rclone can use any folder as its starting point.

Properties:

- Config: `root_prefix`
- Env Var: `RCLONE_HIDRIVE_ROOT_PREFIX`
- Type: string
- Default: `"/"`
- Examples:
  - `"/"`
    - The topmost directory accessible by rclone.
    - This will be equivalent with `"root"` if rclone uses a regular HiDrive user account.
  - `"root"`
    - The topmost directory of the HiDrive user account
  - `""`
    - This specifies that there is no root-prefix for your paths.
    - When using this you will always need to specify paths to this remote with a valid parent e.g. `"remote:/path/to/dir"` or `"remote:root/path/to/dir"`.

### `--hidrive-endpoint`

Endpoint for the service.

This is the URL that API-calls will be made to.

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_HIDRIVE_ENDPOINT`
- Type: string
- Default: `"https://api.hidrive.strato.com/2.1"`

### `--hidrive-disable-fetching-member-count`

Do not fetch number of objects in directories unless it is absolutely necessary.

Requests may be faster if the number of objects in subdirectories is not fetched.

Properties:

- Config: `disable_fetching_member_count`
- Env Var: `RCLONE_HIDRIVE_DISABLE_FETCHING_MEMBER_COUNT`
- Type: bool
- Default: false

### `--hidrive-chunk-size`

Chunksize for chunked uploads.

Any files larger than the configured cutoff (or files of unknown size) will be uploaded in chunks of this size.

The upper limit for this is **2147483647 bytes** (about 2.000Gi). That is the maximum amount of bytes a single upload-operation will support. Setting this above the upper limit or to a negative value will cause uploads to fail 💀

Setting this to larger values may increase the upload speed at the cost of using more memory. It can be set to smaller values smaller to save on memory.

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_HIDRIVE_CHUNK_SIZE`
- Type: SizeSuffix
- Default: 48Mi

### `--hidrive-upload-cutoff`

Cutoff/Threshold for chunked uploads.

Any files larger than this will be uploaded in chunks of the configured chunksize.

The upper limit for this is **2147483647 bytes** (about 2.000Gi). That is the maximum amount of bytes a single upload-operation will support. Setting this above the upper limit will cause uploads to fail.

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_HIDRIVE_UPLOAD_CUTOFF`
- Type: SizeSuffix
- Default: 96Mi

### `--hidrive-upload-concurrency`

Concurrency for chunked uploads.

This is the upper limit for how many transfers for the same file are running concurrently. Setting this above to a value smaller than 1 will cause uploads to deadlock 😭

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_HIDRIVE_UPLOAD_CONCURRENCY`
- Type: int
- Default: 4

### `--hidrive-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_HIDRIVE_ENCODING`
- Type: Encoding
- Default: Slash,Dot

### `--hidrive-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_HIDRIVE_DESCRIPTION`
- Type: string
- Required: false

---

## 🚧 Limitations

### 🔗 Symbolic links

HiDrive is able to store symbolic links (symlinks) by design — for example, when unpacked from a zip archive. Cute, right?

But there's no direct mechanism to manage native symlinks in remotes. So this implementation has chosen to just… ignore any native symlinks present in the remote 🙈 rclone will not be able to access or show any symlinks stored in the hidrive-remote. That means symlinks can't be individually removed, copied, or moved — except when you're removing, copying, or moving the parent folder.

This does *not* affect the `.rclonelink` files that rclone uses to encode and store symbolic links.

### 🕳️ Sparse files

It is possible to store sparse files in HiDrive.

Note that copying a sparse file will expand the holes into null-byte (`0x00`) regions that will then consume disk space. Likewise, when downloading a sparse file, the resulting file will have null-byte regions in the place of file holes.

---

# <rainbow>HTTP</rainbow> 🌐✨

okay bestie, the HTTP remote is a <hotpink>read only</hotpink> remote for reading files off a webserver 💅 the webserver just needs to hand over file listings, and rclone will read them and turn them into a remote for you 🎀 this has been tested with the usual suspects like Apache/Nginx/Caddy and will *likely* work with file listings from most webservers. (and if it doesn't? please file an issue, or send a pull request! 🫶)

Paths get specified as `remote:` or `remote:path`.

The `remote:` bit is your configured url, and any path after it gets resolved relative to that url, according to the URL standard 📐 so with remote url `https://beta.rclone.org/branch` and path `fix`, the resolved URL is `https://beta.rclone.org/branch/fix`. But with path `/fix` the resolved URL is `https://beta.rclone.org/fix`, because that absolute path gets resolved from the root of the domain 🌈

If the path after `remote:` ends with `/` it's assumed to point to a directory 📁 if the path *doesn't* end with `/`, then a HEAD request gets sent and the response decides whether it's treated as a file or a directory (run with `-vv` to see the details 👀). When `--http-no-head` is specified, a path without the ending `/` is always assumed to be a file. So if rclone wrongly assumes the path is a file, the fix is to specify the path with a trailing `/` 🎀 and when you *know* the path is a directory, ending it with `/` is always better, because it skips that initial HEAD request entirely ✨

To just download a single file it's easier to use `copyurl`.

---

## 🌸 Configuration 🌸

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / HTTP \ "http" [snip] Storage> http URL of http host to connect to Choose a number from below, or type in your own value 1 / Connect to example.com \ "https://example.com" url> https://beta.rclone.org Remote config Configuration complete. Options:

type: http
url: https://beta.rclone.org Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== remote http

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> q


This remote is called `remote` and can now be used like this 👇

See all the top level directories:

rclone lsd remote:


List the contents of a directory:

rclone ls remote:directory


Sync the remote directory to `/home/local/directory`, deleting any excess files 🧹

rclone sync --interactive remote:directory /home/local/directory


---

## 🚫 Read only 🚫

This remote is <red>read only</red> — you can't upload files to an HTTP server. no cap bestie, that's just how it is 💀

## ⏰ Modification times ⏰

Most HTTP servers store time accurate to **1 second**.

## 🔍 Checksum 🔍

No checksums are stored. periodt.

## ✨ Usage without a config file ✨

Since the http remote only has one config parameter it's super easy to use without a config file 🎀

rclone lsd --http-url https://beta.rclone.org :http:

or:

rclone lsd :http,url='https://beta.rclone.org':


---

# 💖 Standard options 💖

Here are the Standard options specific to http (HTTP).

- **`--http-url`** — URL of HTTP host to connect to 🌐
  E.g. `"https://example.com"`, or `"https://user:pass@example.com"` to use a username and password 🔐
  Properties:
  - Config: `url`
  - Env Var: `RCLONE_HTTP_URL`
  - Type: `string`
  - Required: **true**

- **`--http-no-escape`** — Do not escape URL metacharacters in path names.
  Properties:
  - Config: `no_escape`
  - Env Var: `RCLONE_HTTP_NO_ESCAPE`
  - Type: `bool`
  - Default: `false`

---

# 🌈 Advanced options 🌈

Here are the Advanced options specific to http (HTTP).

- **`--http-headers`** — Set HTTP headers for all transactions.
  Use this to set additional HTTP headers for all transactions.
  The input format is a comma separated list of key,value pairs 📝 Standard CSV encoding may be used.
  For example, to set a Cookie use `` `Cookie,name=value' ``, or `` `"Cookie","name=value"' ``.
  You can set multiple headers, e.g. `` `"Cookie","name=value","Authorization","xxx"' ``.
  Properties:
  - Config: `headers`
  - Env Var: `RCLONE_HTTP_HEADERS`
  - Type: `CommaSepList`
  - Default:

- **`--http-no-slash`** — Set this if the site doesn't end directories with `/`.
  Use this if your target website does not use `/` on the end of directories.
  A `/` on the end of a path is how rclone normally tells the difference between files and directories 📁📄 If this flag is set, then rclone will treat all files with `Content-Type: text/html` as directories and read URLs from them rather than downloading them 👀
  > ⚠️ Note that this may cause rclone to confuse genuine HTML files with directories. be careful bestie 😭
  Properties:
  - Config: `no_slash`
  - Env Var: `RCLONE_HTTP_NO_SLASH`
  - Type: `bool`
  - Default: `false`

- **`--http-no-head`** — Don't use HEAD requests.
  HEAD requests are mainly used to find file sizes in dir listing 📏 If your site is being very slow to load then you can try this option 🐌
  Normally rclone does a HEAD request for each potential file in a directory listing to:
  - find its size
  - check it really exists
  - check to see if it is a directory
  If you set this option, rclone will not do the HEAD request 🚫 This will mean that directory listings are much quicker, but rclone won't have the times or sizes of any files, and some files that don't exist may be in the listing 💀
  Properties:
  - Config: `no_head`
  - Env Var: `RCLONE_HTTP_NO_HEAD`
  - Type: `bool`
  - Default: `false`

- **`--http-description`** — Description of the remote.
  Properties:
  - Config: `description`
  - Env Var: `RCLONE_HTTP_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

# 🛠️ Backend commands 🛠️

Here are the commands specific to the http backend 👑

Run them with:

rclone backend COMMAND remote:


The help below will explain what arguments each command takes 📖

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command` ✨

## set

Set command for updating the config parameters.

rclone backend set remote: [options] [<arguments>+]


This `set` command can be used to update the config parameters for a running http backend 💅

Usage Examples:

rclone backend set remote: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=remote: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=remote: -o url=https://example.com


The option keys are named as they are in the config file 📝

This rebuilds the connection to the http backend when it is called with the new parameters 🔄 Only new parameters need be passed as the values will default to those currently in use.

It doesn't return anything. iconic of it honestly 🙈

---

## ⚠️ Limitations ⚠️

`rclone about` is <red>not supported</red> by the HTTP backend 😭 Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote.

See List of backends that do not support rclone about and `rclone about`

# ✨ ImageKit ✨

okay so this is a backend for the <pink>ImageKit.io</pink> storage service 💖

## 🌸 About ImageKit

ImageKit.io provides <hotpink>real-time image and video optimizations, transformations, and CDN delivery</hotpink>. Over <purple>1,000 businesses</purple> and <purple>70,000 developers</purple> trust ImageKit with their images and videos on the web. no cap, that's a lot of people 🫶

## 💸 Accounts & Pricing

To use this backend, you need to create an account on ImageKit. Start with a <green>free plan</green> with generous usage limits. Then, as your requirements grow, upgrade to a plan that best fits your needs. See the pricing details. basically: start free, glow up later 💅

## 🎀 Configuration

Here's an example of making an `imagekit` configuration.

Firstly create a ImageKit.io account and choose a plan.

You will need to log in and get the `publicKey` and `privateKey` for your account from the developer section.

Now run

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter the name for the new remote. name> imagekit-media-library

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / ImageKit.io \ (imagekit) [snip] Storage> imagekit

Option endpoint. You can find your ImageKit.io URL endpoint in your [dashboard](https://imagekit.io/dashboard/developer/api-keys) Enter a value. endpoint> https://ik.imagekit.io/imagekit_id

Option public_key. You can find your ImageKit.io public key in your [dashboard](https://imagekit.io/dashboard/developer/api-keys) Enter a value. public_key> public_

Option private_key. You can find your ImageKit.io private key in your [dashboard](https://imagekit.io/dashboard/developer/api-keys) Enter a value. private_key> private_

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: imagekit
endpoint: https://ik.imagekit.io/imagekit_id
public_key: public_
private_key: private_

Keep this "imagekit-media-library" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


List directories in the top level of your Media Library 🦋

rclone lsd imagekit-media-library:


Make a new directory.

rclone mkdir imagekit-media-library:directory


List the contents of a directory.

rclone ls imagekit-media-library:directory


## ⏰ Modified time and hashes

ImageKit does <red>not</red> support modification times or hashes yet. 💀 yeah. it's giving "we'll get there".

## 🧾 Checksums

No checksums are supported. periodt. 🙈

## 👑 Standard options

Here are the Standard options specific to `imagekit` (ImageKit.io).

- **`--imagekit-endpoint`** — You can find your ImageKit.io URL endpoint in your dashboard

  Properties:

  - Config: `endpoint`
  - Env Var: `RCLONE_IMAGEKIT_ENDPOINT`
  - Type: string
  - Required: true

- **`--imagekit-public-key`** — You can find your ImageKit.io public key in your dashboard

  Properties:

  - Config: `public_key`
  - Env Var: `RCLONE_IMAGEKIT_PUBLIC_KEY`
  - Type: string
  - Required: true

- **`--imagekit-private-key`** — You can find your ImageKit.io private key in your dashboard

  Properties:

  - Config: `private_key`
  - Env Var: `RCLONE_IMAGEKIT_PRIVATE_KEY`
  - Type: string
  - Required: true

## 🌈 Advanced options

Here are the Advanced options specific to `imagekit` (ImageKit.io).

- **`--imagekit-only-signed`** — If you have configured <purple>Restrict unsigned image URLs</purple> in your dashboard settings, set this to true.

  Properties:

  - Config: `only_signed`
  - Env Var: `RCLONE_IMAGEKIT_ONLY_SIGNED`
  - Type: bool
  - Default: `false`

- **`--imagekit-versions`** — Include old versions in directory listings.

  Properties:

  - Config: `versions`
  - Env Var: `RCLONE_IMAGEKIT_VERSIONS`
  - Type: bool
  - Default: `false`

- **`--imagekit-upload-tags`** — Tags to add to the uploaded files, e.g. `"tag1,tag2"`.

  Properties:

  - Config: `upload_tags`
  - Env Var: `RCLONE_IMAGEKIT_UPLOAD_TAGS`
  - Type: string
  - Required: false

- **`--imagekit-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_IMAGEKIT_ENCODING`
  - Type: Encoding
  - Default: `Slash,LtGt,DoubleQuote,Dollar,Question,Hash,Percent,BackSlash,Del,Ctl,InvalidUtf8,Dot,SquareBracket`

- **`--imagekit-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_IMAGEKIT_DESCRIPTION`
  - Type: string
  - Required: false

## 🧚 Metadata

Any metadata supported by the underlying remote is read and written.

Here are the possible system metadata items for the `imagekit` backend.

- **`aws-tags`** — Help: AI generated tags by AWS Rekognition associated with the image — Type: string — Example: `tag1,tag2` — Read Only: `Y`
- **`btime`** — Help: Time of file birth (creation) read from Last-Modified header — Type: RFC 3339 — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: `Y`
- **`custom-coordinates`** — Help: Custom coordinates of the file — Type: string — Example: `0,0,100,100` — Read Only: `Y`
- **`file-type`** — Help: Type of the file — Type: string — Example: `image` — Read Only: `Y`
- **`google-tags`** — Help: AI generated tags by Google Cloud Vision associated with the image — Type: string — Example: `tag1,tag2` — Read Only: `Y`
- **`has-alpha`** — Help: Whether the image has alpha channel or not — Type: bool — Read Only: `Y`
- **`height`** — Help: Height of the image or video in pixels — Type: int — Read Only: `Y`
- **`is-private-file`** — Help: Whether the file is private or not — Type: bool — Read Only: `Y`
- **`size`** — Help: Size of the object in bytes — Type: int64 — Read Only: `Y`
- **`tags`** — Help: Tags associated with the file — Type: string — Example: `tag1,tag2` — Read Only: `Y`
- **`width`** — Help: Width of the image or video in pixels — Type: int — Read Only: `Y`

See the metadata docs for more info. 💜

# ☁️ iCloud Drive 💖

## 🎀 Configuration 🎀

okay so bestie, the very first time you set up an iCloud Drive backend you gotta get yourself a <pink>trust token/session</pink>. the way you do that is honestly so chill — just use your regular iCloud password, and then accept the code prompt that pops up on another iCloud-connected device. that's it. that's the whole vibe. 💅

> **IMPORTANT:** right now an <red>app specific password will NOT be accepted</red>. do not come in here with an app-specific password, it's giving rejected. only use your <bold>regular password and 2FA</bold>, fr fr. 😭

`rclone config` literally walks you through the token creation step by step, so you're not alone in this. the trust token stays valid for <yellow>30 days</yellow>. after that? you're gonna have to reauthenticate with `rclone reconnect` or `rclone config`. it's giving "expired milk in the fridge" energy but it is what it is. 🫶

here's an example of how to make a remote called `iclouddrive`. first run:

rclone config


and it will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> iclouddrive Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / iCloud Drive \ (iclouddrive) [snip] Storage> iclouddrive Option apple_id. Apple ID. Enter a value. apple_id> APPLEID Option password. Password. Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n> n Option config_2fa. Two-factor authentication: please enter your 2FA code Enter a value. config_2fa> 2FACODE Remote config

[iclouddrive]

type: iclouddrive
apple_id: APPLEID
password: * ENCRYPTED *
cookies:
trust_token:

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


## 🌈 Advanced Data Protection 🌈

ADP is <red>currently unsupported</red> and needs to be disabled. no cap, it just doesn't play nice yet. 🙈

on iPhone, go <purple>Settings > Apple Account > iCloud</purple>, then `Access iCloud Data on the Web' must be <green>ON</green>, and `Advanced Data Protection' <red>OFF</red>. periodt.

## 💅 Troubleshooting 💅

### 🦋 Missing PCS cookies from the request 🦋

if you're seeing this, bestie, it means you have <bold>Advanced Data Protection (ADP) turned on</bold>. this is **not supported at the moment**. if you wanna use rclone you're gonna have to turn it off — see above for how to do that (scroll up, it's right there 💜).

you'll need to <bold>clear the `cookies` and the `trust_token` fields in the config</bold>. or honestly you can just delete the remote config and start over, main character move. ✨

then you should run `rclone reconnect remote:`.

> **note:** changing the ADP setting may <italic>not</italic> take effect immediately — you may need to wait a few hours or even a day before rclone starts working. so keep clearing the config entry and running `rclone reconnect remote:` until rclone functions properly. it's giving "waiting for the wifi to come back" energy and we hate it here. 😭

---

## ⭐ Standard options ⭐

here are the Standard options specific to `iclouddrive` (iCloud Drive). 🌸

- **`--iclouddrive-apple-id`** — Apple ID.

  Properties:
  - Config: `apple_id`
  - Env Var: `RCLONE_ICLOUDDRIVE_APPLE_ID`
  - Type: string
  - Required: <bold>true</bold>

- **`--iclouddrive-password`** — Password.

  > NB Input to this must be obscured — see `rclone obscure`.

  Properties:
  - Config: `password`
  - Env Var: `RCLONE_ICLOUDDRIVE_PASSWORD`
  - Type: string
  - Required: <bold>true</bold>

- **`--iclouddrive-trust-token`** — Trust token (internal use)

  Properties:
  - Config: `trust_token`
  - Env Var: `RCLONE_ICLOUDDRIVE_TRUST_TOKEN`
  - Type: string
  - Required: false

- **`--iclouddrive-cookies`** — cookies (internal use only)

  Properties:
  - Config: `cookies`
  - Env Var: `RCLONE_ICLOUDDRIVE_COOKIES`
  - Type: string
  - Required: false

## 👑 Advanced options 👑

here are the Advanced options specific to `iclouddrive` (iCloud Drive). 🔥

- **`--iclouddrive-client-id`** — Client id

  Properties:
  - Config: `client_id`
  - Env Var: `RCLONE_ICLOUDDRIVE_CLIENT_ID`
  - Type: string
  - Default: `"d39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d"`

- **`--iclouddrive-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:
  - Config: `encoding`
  - Env Var: `RCLONE_ICLOUDDRIVE_ENCODING`
  - Type: Encoding
  - Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

- **`--iclouddrive-description`** — Description of the remote.

  Properties:
  - Config: `description`
  - Env Var: `RCLONE_ICLOUDDRIVE_DESCRIPTION`
  - Type: string
  - Required: false

---

# 🗄️ Internet Archive 🗄️

the Internet Archive backend utilizes <pink>Items</pink> on archive.org. historic. iconic. no cap. 📚

refer to the <bold>IAS3 API documentation</bold> for the API this backend uses.

paths are specified as `remote:bucket` (or just `remote:` for the `lsd` command). you can put subdirectories in there too bestie, like `remote:item/path/to/dir`. 🦋

unlike S3, listing up all the items uploaded by you <red>isn't supported</red>. yeah. we know. 💀

once you've made a remote, you can use it like this:

make a new item:

rclone mkdir remote:item


list the contents of an item:

rclone ls remote:item


sync `/home/local/directory` to the remote item, deleting any excess files in the item:

rclone sync --interactive /home/local/directory remote:item


## 🌸 Notes 🌸

because of Internet Archive's architecture, it enqueues write operations (and extra post-processings) in a <bold>per-item queue</bold>. you can check an item's queue at `https://catalogd.archive.org/history/item-name-here`. because of that, all uploads/deletes will <italic>not</italic> show up immediately and it takes some time to be available. the per-item queue gets enqueued to another queue, the <bold>Item Deriver Queue</bold>. you can check the status of the Item Deriver Queue there. this queue has a limit, and it may block you from uploading, or even deleting. 😭 you should avoid uploading a lot of small files for better behavior. fr fr, keep it chunky.

you can optionally wait for the server's processing to finish by setting a non-zero value to the `wait_archive` key. by making it wait, rclone can do normal file comparison. just make sure to set a large enough value (e.g. `30m0s` for smaller files) as it can take a long time depending on the server's queue. ⏳

## ✨ About metadata ✨

this backend supports setting, updating and reading metadata of each file. the metadata will appear as file metadata on Internet Archive. <italic>however</italic>, some fields are reserved by both Internet Archive and rclone, so watch out bestie. 🙈

the following are reserved by Internet Archive: `name`, `source`, `size`, `md5`, `crc32`, `sha1`, `format`, `old_version`, `viruscheck`, `summation`

trying to set values to these keys is ignored with a warning. the only exception is setting `mtime` — doing so makes it identical behavior to setting `ModTime`. 💅

rclone reserves all the keys starting with `rclone-`. setting a value for these keys will give you warnings, but values <italic>are</italic> set according to request.

if there are multiple values for a key, only the <bold>first one</bold> is returned. this is a limitation of rclone, which supports one value per one key. it can be triggered when you did a server-side copy. 😔

reading metadata will also provide custom (non-standard nor reserved) ones. cute. 🎀

## 🧚 Filtering auto generated files 🧚

the Internet Archive <bold>automatically creates metadata files</bold> after upload. these can cause problems when doing an rclone sync, as rclone will try — and fail — to delete them. these metadata files are not changeable, because they are created by the Internet Archive automatically. not yours to touch, bestie. 🙅

these auto-created files can be excluded from the sync using metadata filtering:

rclone sync ... --metadata-exclude "source=metadata" --metadata-exclude "format=Metadata"


which excludes from the sync any files which have the `source=metadata` or `format=Metadata` flags that get added to Internet Archive auto-created files. slay. ✅

## 💜 Configuration 💜

here's an example of making an `internetarchive` configuration. most of it applies to the other providers too, and any differences are described below. 🌈

first run:

rclone config


this will guide you through an interactive setup process.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. XX / InternetArchive Items \ (internetarchive) Storage> internetarchive Option access_key_id. IAS3 Access Key. Leave blank for anonymous access. You can find one here: https://archive.org/account/s3.php Enter a value. Press Enter to leave empty. access_key_id> XXXX Option secret_access_key. IAS3 Secret Key (password). Leave blank for anonymous access. Enter a value. Press Enter to leave empty. secret_access_key> XXXX Edit advanced config? y) Yes n) No (default) y/n> y Option endpoint. IAS3 Endpoint. Leave blank for default value. Enter a string value. Press Enter for the default (https://s3.us.archive.org). endpoint> Option front_endpoint. Host of InternetArchive Frontend. Leave blank for default value. Enter a string value. Press Enter for the default (https://archive.org). front_endpoint> Option disable_checksum. Don't store MD5 checksum with object metadata. Normally rclone will calculate the MD5 checksum of the input before uploading it so it can ask the server to check the object against checksum. This is great for data integrity checking but can cause long delays for large files to start uploading. Enter a boolean value (true or false). Press Enter for the default (true). disable_checksum> true Option encoding. The encoding for the backend. See the [encoding section in the overview](https://rclone.org/overview/#encoding) for more info. Enter a encoder.MultiEncoder value. Press Enter for the default (Slash,Question,Hash,Percent,Del,Ctl,InvalidUtf8,Dot). encoding> Edit advanced config? y) Yes n) No (default) y/n> n Configuration complete. Options:

type: internetarchive
access_key_id: XXXX
secret_access_key: XXXX Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


# ✨ Standard options ✨

okay bestie these are the <pink>Standard options</pink> that are specific to `internetarchive` (Internet Archive). basic but essential, yk? 💅

## 🎀 `--internetarchive-access-key-id`

IAS3 Access Key.

Leave blank for anonymous access. You can find one here: https://archive.org/account/s3.php

Properties:

- <cyan>Config</cyan>: `access_key_id`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_ACCESS_KEY_ID`
- <cyan>Type</cyan>: string
- <cyan>Required</cyan>: false

## 🎀 `--internetarchive-secret-access-key`

IAS3 Secret Key (password).

Leave blank for anonymous access.

Properties:

- <cyan>Config</cyan>: `secret_access_key`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_SECRET_ACCESS_KEY`
- <cyan>Type</cyan>: string
- <cyan>Required</cyan>: false

---

# 🌈 Advanced options 🌈

and now the <purple>Advanced options</purple> specific to `internetarchive` (Internet Archive). the spicy tier, the deluxe menu, the "yes I know what I'm doing" vibes 💅✨

## 🦋 `--internetarchive-endpoint`

IAS3 Endpoint.

Leave blank for default value.

Properties:

- <cyan>Config</cyan>: `endpoint`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_ENDPOINT`
- <cyan>Type</cyan>: string
- <cyan>Default</cyan>: "https://s3.us.archive.org"

## 🦋 `--internetarchive-front-endpoint`

Host of InternetArchive Frontend.

Leave blank for default value.

Properties:

- <cyan>Config</cyan>: `front_endpoint`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_FRONT_ENDPOINT`
- <cyan>Type</cyan>: string
- <cyan>Default</cyan>: "https://archive.org"

## 🦋 `--internetarchive-disable-checksum`

Don't ask the server to test against MD5 checksum calculated by rclone.

Normally rclone will calculate the MD5 checksum of the input before uploading it so it can ask the server to check the object against checksum. This is great for data integrity checking but can cause long delays for large files to start uploading.

Properties:

- <cyan>Config</cyan>: `disable_checksum`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_DISABLE_CHECKSUM`
- <cyan>Type</cyan>: bool
- <cyan>Default</cyan>: true

## 🦋 `--internetarchive-wait-archive`

Timeout for waiting the server's processing tasks (specifically `archive` and `book_op`) to finish. Only enable if you need to be guaranteed to be reflected after write operations. `0` to disable waiting. No errors to be thrown in case of timeout.

Properties:

- <cyan>Config</cyan>: `wait_archive`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_WAIT_ARCHIVE`
- <cyan>Type</cyan>: Duration
- <cyan>Default</cyan>: `0s`

## 🦋 `--internetarchive-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- <cyan>Config</cyan>: `encoding`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_ENCODING`
- <cyan>Type</cyan>: Encoding
- <cyan>Default</cyan>: `Slash,LtGt,CrLf,Del,Ctl,InvalidUtf8,Dot`

## 🦋 `--internetarchive-description`

Description of the remote.

Properties:

- <cyan>Config</cyan>: `description`
- <cyan>Env Var</cyan>: `RCLONE_INTERNETARCHIVE_DESCRIPTION`
- <cyan>Type</cyan>: string
- <cyan>Required</cyan>: false

---

# 💜 Metadata 💜

Metadata fields provided by Internet Archive. If there are multiple values for a key, only the **first one** is returned. This is a limitation of Rclone, that supports one value per one key. <red>(one key = one value bestie, that's just how it is 😭)</red>

Owner is able to add custom keys. Metadata feature grabs **all** the keys including them. so nothing sneaks past, no cap 🫶

Here are the possible system metadata items for the `internetarchive` backend. 🌸

- <pink>`crc32`</pink> — CRC32 calculated by Internet Archive · Type: string · Example: `01234567` · Read Only: **Y**
- <pink>`format`</pink> — Name of format identified by Internet Archive · Type: string · Example: `Comma-Separated Values` · Read Only: **Y**
- <pink>`md5`</pink> — MD5 hash calculated by Internet Archive · Type: string · Example: `01234567012345670123456701234567` · Read Only: **Y**
- <pink>`mtime`</pink> — Time of last modification, managed by Rclone · Type: RFC 3339 · Example: `2006-01-02T15:04:05.999999999Z` · Read Only: **Y**
- <pink>`name`</pink> — Full file path, without the bucket part · Type: filename · Example: `backend/internetarchive/internetarchive.go` · Read Only: **Y**
- <pink>`old_version`</pink> — Whether the file was replaced and moved by `keep-old-version` flag · Type: boolean · Example: `true` · Read Only: **Y**
- <pink>`rclone-ia-mtime`</pink> — Time of last modification, managed by Internet Archive · Type: RFC 3339 · Example: `2006-01-02T15:04:05.999999999Z` · Read Only: **N**
- <pink>`rclone-mtime`</pink> — Time of last modification, managed by Rclone · Type: RFC 3339 · Example: `2006-01-02T15:04:05.999999999Z` · Read Only: **N**
- <pink>`rclone-update-track`</pink> — Random value used by Rclone for tracking changes inside Internet Archive · Type: string · Example: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` · Read Only: **N**
- <pink>`sha1`</pink> — SHA1 hash calculated by Internet Archive · Type: string · Example: `0123456701234567012345670123456701234567` · Read Only: **Y**
- <pink>`size`</pink> — File size in bytes · Type: decimal number · Example: `123456` · Read Only: **Y**
- <pink>`source`</pink> — The source of the file · Type: string · Example: `original` · Read Only: **Y**
- <pink>`summation`</pink> — Check https://forum.rclone.org/t/31922 for how it is used · Type: string · Example: `md5` · Read Only: **Y**
- <pink>`viruscheck`</pink> — The last time viruscheck process was run for the file (?) · Type: unixtime · Example: `1654191352` · Read Only: **Y**

See the metadata docs for more info. 📚

---

# 👑 Jottacloud 👑

Jottacloud is a cloud storage service provider from a Norwegian company, using its own datacenters in Norway. <rainbow>it's giving Nordic excellence fr fr</rainbow> 🇳🇴✨ In addition to the official service at jottacloud.com, it also provides white-label solutions to different companies, such as:

- <blue>Telia</blue>
- <blue>Telia Cloud</blue> (`cloud.telia.se`)
- <blue>Telia Sky</blue> (`sky.telia.no`)
- <blue>Tele2</blue>
- <blue>Tele2 Cloud</blue> (`mittcloud.tele2.se`)
- <blue>Onlime</blue>
- <blue>Onlime Cloud Storage</blue> (`onlime.dk`)
- <blue>Elkjøp (with subsidiaries):</blue>
  - <blue>Elkjøp Cloud</blue> (`cloud.elkjop.no`)
  - <blue>Elgiganten Sweden</blue> (`cloud.elgiganten.se`)
  - <blue>Elgiganten Denmark</blue> (`cloud.elgiganten.dk`)
  - <blue>Giganti Cloud</blue> (`cloud.gigantti.fi`)
  - <blue>ELKO Cloud</blue> (`cloud.elko.is`)

Most of the white-label versions are supported by this backend, although may require different authentication setup - described below. 👀

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. 🦋

## 🔐 Authentication types 🔐

Some of the whitelabel versions uses a different authentication method than the official service, and you have to choose the correct one when setting up the remote. <red>pick the right one bestie, don't just vibe-check your way through this one 💀</red>

### 🎀 Standard authentication 🎀

Okay bestie, so the <pink>standard</pink> auth flow — the one the official service (`jottacloud.com`) uses, and also a bunch of the whitelabel services — needs you to generate a **single-use personal login token** from the account security settings in the service's web interface. Like, log in to your account, head to "Settings" and then "Security", or just use the direct link rclone literally hands you when you're configuring the remote: `https://www.jottacloud.com/web/secure`. Scroll all the way down to the section called "Personal login token" and click the "Generate" button. ✨

> Heads up though — if you're on a whitelabel service you probably **can't** use that direct link. You gotta find the same page in *their* dedicated web interface, and ngl it might be in a totally different spot than what's described above. 💀

So here's the thing. If you want to access your account from <hotpink>multiple instances of rclone</hotpink>, you have to configure each of them with a *separate* personal login token. Like, imagine you create a Jottacloud remote with rclone in one location, then copy the config file to a second location where you also wanna run rclone and hit the same remote. You then need to replace the token for one of them, using the `config reconnect` command, which requires you to generate a fresh personal login token and feed it as input. If you **don't** do this, the token can very easily end up being invalidated, and then both instances start failing with an error message something along the lines of:

oauth2: cannot fetch token: 400 Bad Request Response: {"error":"invalid_grant","error_description":"Stale token"}


When *that* happens, you just replace the token as described above and your remote is usable again. No stress. 🫶

Every personal login token you've taken into use gets listed in the web interface under "My logged in devices", and from the right side of that list you can click the "X" button to revoke individual tokens. Clean. Tidy. Iconic. 💅

---

### 🦋 Legacy authentication 🦋

So if you're running one of the whitelabel versions (like, say, from <purple>Elkjøp</purple>), you might not even have the option to generate a CLI token. In that case you'll have to use the **legacy authentication**. To do this, select <cyan>yes</cyan> when the setup asks for legacy authentication, then enter your username and password. The rest of the setup is literally identical to the default setup. ✨

### 🌸 Telia Cloud authentication 🌸

Similar vibe to the other whitelabel versions — Telia Cloud doesn't offer the option of creating a CLI token, and *additionally* uses a separate authentication flow where the username is generated internally. To set rclone up with Telia Cloud, choose <hotpink>Telia Cloud authentication</hotpink> in the setup. The rest of the setup is identical to the default setup. 💖

### 🌈 Tele2 Cloud authentication 🌈

Since the Tele2-Com Hem merger was completed, this authentication can be used for former Com Hem Cloud *and* Tele2 Cloud customers — because no support for creating a CLI token exists, and it additionally uses a separate authentication flow where the username is generated internally. To set rclone up with Tele2 Cloud, choose <hotpink>Tele2 Cloud authentication</hotpink> in the setup. The rest of the setup is identical to the default setup. ⭐

### 👑 Onlime Cloud Storage authentication 👑

The lore here: Onlime sold access to Jottacloud proper, while providing localized support to Danish customers, but they recently set up their **own** hosting, transferring their customers from Jottacloud servers over to their own ones. 📦

This, of course, necessitates using *their* servers for authentication — but otherwise the functionality and architecture seems equivalent to Jottacloud. No cap.

To set rclone up with Onlime Cloud Storage, choose <hotpink>Onlime Cloud authentication</hotpink> in the setup. The rest of the setup is identical to the default setup. 💜

---

### 🧚 Configuration 🧚

Here's an example of how to make a remote called `remote` with the default setup. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Jottacloud \ (jottacloud) [snip] Storage> jottacloud Edit advanced config? y) Yes n) No (default) y/n> n Option config_type. Select authentication type. Choose a number from below, or type in an existing string value. Press Enter for the default (standard). / Standard authentication. 1 | Use this if you're a normal Jottacloud user. \ (standard) / Legacy authentication. 2 | This is only required for certain whitelabel versions of Jottacloud and not recommended for normal users. \ (legacy) / Telia Cloud authentication. 3 | Use this if you are using Telia Cloud. \ (telia) / Tele2 Cloud authentication. 4 | Use this if you are using Tele2 Cloud. \ (tele2) / Onlime Cloud authentication. 5 | Use this if you are using Onlime Cloud. \ (onlime) config_type> 1 Personal login token. Generate here: https://www.jottacloud.com/web/secure Login Token> <your token here> Use a non-standard device/mountpoint? Choosing no, the default, will let you access the storage used for the archive section of the official Jottacloud client. If you instead want to access the sync or the backup section, for example, you must choose yes. y) Yes n) No (default) y/n> y Option config_device. The device to use. In standard setup the built-in Jotta device is used, which contains predefined mountpoints for archive, sync etc. All other devices are treated as backup devices by the official Jottacloud client. You may create a new by entering a unique name. Choose a number from below, or type in your own string value. Press Enter for the default (DESKTOP-3H31129). 1 > DESKTOP-3H31129 2 > Jotta config_device> 2 Option config_mountpoint. The mountpoint to use for the built-in device Jotta. The standard setup is to use the Archive mountpoint. Most other mountpoints have very limited support in rclone and should generally be avoided. Choose a number from below, or type in an existing string value. Press Enter for the default (Archive). 1 > Archive 2 > Shared 3 > Sync config_mountpoint> 1 Configuration complete. Options:

type: jottacloud
configVersion: 1
client_id: jottacli
client_secret:
tokenURL: https://id.jottacloud.com/auth/realms/jottacloud/protocol/openid-connect/token
token: {........}
username: 2940e57271a93d987d6f8a21
device: Jotta
mountpoint: Archive Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can then use rclone like this, 💫

List directories in top level of your Jottacloud

rclone lsd remote:


List all the files in your Jottacloud

rclone ls remote:


To copy a local directory to an Jottacloud directory called `backup`

rclone copy /home/source remote:backup


---

### 🍓 Devices and Mountpoints 🍓

The official Jottacloud client registers a **device** for each computer you install it on, and shows them in the backup section of the user interface. For each folder you select for backup it'll create a **mountpoint** within that device. And there's a built-in device called `Jotta` that's special — it contains mountpoints `Archive`, `Sync` and some others, used for the corresponding features in the official clients. 👑

With rclone you'll want to use the standard `Jotta`/`Archive` device/mountpoint in most cases. That said, you might for example wanna access files from the sync or backup functionality that the official clients provide — and so rclone gives you the option to select other devices and mountpoints during config. 🌈

You're allowed to create new devices and mountpoints. All devices **except** the built-in `Jotta` device are treated as backup devices by official Jottacloud clients, and the mountpoints on them are individual backup sets. lowkey important.

With the built-in `Jotta` device, only existing, built-in, mountpoints can be selected. In addition to the mentioned `Archive` and `Sync`, it may contain several other mountpoints such as: `Latest`, `Links`, `Shared` and `Trash`. All of these are special mountpoints with a different internal representation than the "regular" mountpoints. Rclone will only to a *very limited* degree support them.

> Generally you should avoid these, unless you know what you are doing. ⚠️ For real.

---

### 💀 `--fast-list` 💀

This backend supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs for more details.

Note that the implementation in Jottacloud always uses only a **single API request** to get the entire list, so for large folders this could lead to long wait time before the first results are shown. 😭

Note also that with rclone version `1.58` and newer, information about MIME types and metadata item `utime` are **not** available when using `--fast-list`. 🙈

---

### 💅 Modification times and hashes 💅

Jottacloud allows modification times to be set on objects accurate to **1 second**. These will be used to detect whether objects need syncing or not. ⏰

Jottacloud supports **MD5** type hashes, so you can use the `--checksum` flag.

Note that Jottacloud requires the MD5 hash **before** upload, so if the source does not have an MD5 checksum then the file will be cached temporarily on disk (in location given by `--temp-dir`) before it is uploaded. Small files will be cached in memory — see the `--jottacloud-md5-memory-limit` flag. When uploading from local disk the source checksum is always available, so this does not apply. Starting with rclone version `1.52` the same is true for encrypted remotes (in older versions the crypt backend would not calculate hashes for uploads from local disk, so the Jottacloud backend had to do it as described above). 🧠✨

---

### 🎀 Restricted filename characters 🎀

In addition to the default restricted characters set the following characters are also replaced:

<pink>Some characters just cannot be in Jottacloud names, bestie.</pink> So rclone swaps them for a lookalike. Here's the whole mapping, verbatim:

Character Value Replacement ──────────────────────────────── ” 0x22 ＂

0x2A ＊ : 0x3A ： < 0x3C ＜

0x3E ＞

? 0x3F ？

0x7C ｜


Invalid UTF-8 bytes will also be replaced, as they can’t be used in XML strings. <yellow>RIP to your cursed byte sequences, they simply could not sit with us.</yellow> 💀

---

## 🗑️ Deleting files

By default, rclone will send all files to the trash when deleting files. They will be permanently deleted automatically after 30 days. So like, a little grace period, a little "u up?" window before it's gone for real 👻

You may bypass the trash and permanently delete files immediately by using the `--jottacloud-hard-delete` flag, or set the equivalent environment variable. <red>That's it, no undo, no takebacks, gone.</red>

Emptying the trash is supported by the `cleanup` command. ✨

---

## 🕰️ Versions

Jottacloud supports file versioning. When rclone uploads a new version of a file it creates a new version of it. Currently rclone only supports retrieving the current version but older versions can be accessed via the Jottacloud Website. <purple>(iykyk, go dig through the web UI if you want the fossils 🦴)</purple>

Versioning can be disabled by `--jottacloud-no-versions` option. This is achieved by deleting the remote file prior to uploading a new version. If the upload the fails no version of the file will be available in the remote. <red>Yeah bestie, read that again — delete first, upload second, and if the upload flops there's nothing left. That's the deal.</red> 😭

---

## 📊 Quota information

To view your current quota you can use the `rclone about remote:` command which will display your usage limit (unless it is unlimited) and the current usage. <cyan>Know your numbers, queen.</cyan> 👑

---

# ✨ Standard options ✨

Here are the Standard options specific to jottacloud (Jottacloud).

- **`--jottacloud-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:
  - Config: `client_id`
  - Env Var: `RCLONE_JOTTACLOUD_CLIENT_ID`
  - Type: string
  - Required: false
- **`--jottacloud-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:
  - Config: `client_secret`
  - Env Var: `RCLONE_JOTTACLOUD_CLIENT_SECRET`
  - Type: string
  - Required: false

---

# 💅 Advanced options

Here are the Advanced options specific to jottacloud (Jottacloud).

- **`--jottacloud-token`** — OAuth Access Token as a JSON blob.

  Properties:
  - Config: `token`
  - Env Var: `RCLONE_JOTTACLOUD_TOKEN`
  - Type: string
  - Required: false
- **`--jottacloud-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:
  - Config: `auth_url`
  - Env Var: `RCLONE_JOTTACLOUD_AUTH_URL`
  - Type: string
  - Required: false
- **`--jottacloud-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:
  - Config: `token_url`
  - Env Var: `RCLONE_JOTTACLOUD_TOKEN_URL`
  - Type: string
  - Required: false
- **`--jottacloud-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Properties:
  - Config: `client_credentials`
  - Env Var: `RCLONE_JOTTACLOUD_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: false
- **`--jottacloud-md5-memory-limit`** — Files bigger than this will be cached on disk to calculate the MD5 if required.

  Properties:
  - Config: `md5_memory_limit`
  - Env Var: `RCLONE_JOTTACLOUD_MD5_MEMORY_LIMIT`
  - Type: SizeSuffix
  - Default: `10Mi`
- **`--jottacloud-trashed-only`** — Only show files that are in the trash.

  This will show trashed files in their original directory structure.

  Properties:
  - Config: `trashed_only`
  - Env Var: `RCLONE_JOTTACLOUD_TRASHED_ONLY`
  - Type: bool
  - Default: false
- **`--jottacloud-hard-delete`** — Delete files permanently rather than putting them into the trash.

  Properties:
  - Config: `hard_delete`
  - Env Var: `RCLONE_JOTTACLOUD_HARD_DELETE`
  - Type: bool
  - Default: false
- **`--jottacloud-upload-resume-limit`** — Files bigger than this can be resumed if the upload fail’s.

  Properties:
  - Config: `upload_resume_limit`
  - Env Var: `RCLONE_JOTTACLOUD_UPLOAD_RESUME_LIMIT`
  - Type: SizeSuffix
  - Default: `10Mi`
- **`--jottacloud-no-versions`** — Avoid server side versioning by deleting files and recreating files instead of overwriting them.

  Properties:
  - Config: `no_versions`
  - Env Var: `RCLONE_JOTTACLOUD_NO_VERSIONS`
  - Type: bool
  - Default: false
- **`--jottacloud-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:
  - Config: `encoding`
  - Env Var: `RCLONE_JOTTACLOUD_ENCODING`
  - Type: Encoding
  - Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Del,Ctl,InvalidUtf8,Dot`
- **`--jottacloud-description`** — Description of the remote.

  Properties:
  - Config: `description`
  - Env Var: `RCLONE_JOTTACLOUD_DESCRIPTION`
  - Type: string
  - Required: false

---

## 🏷️ Metadata

Jottacloud has limited support for metadata, currently an extended set of timestamps. <purple>It's giving "we have metadata at home" but honestly the timestamps are cute 🎀</purple>

Here are the possible system metadata items for the jottacloud backend.

- `btime` — Time of file birth (creation), read from rclone metadata — Type: RFC 3339 — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: N
- `content-type` — MIME type, also known as media type — Type: string — Example: `text/plain` — Read Only: Y
- `mtime` — Time of last modification, read from rclone metadata — Type: RFC 3339 — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: N
- `utime` — Time of last upload, when current revision was created, generated by backend — Type: RFC 3339 — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: Y

See the metadata docs for more info.

---

## 🚧 Limitations

Note that Jottacloud is case insensitive so you can’t have a file called “Hello.doc” and one called “hello.doc”. <red>They're the same file to Jottacloud, so pick one, you can't have both.</red> 😭

There are quite a few characters that can’t be in Jottacloud file names. 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. <mint>Same vibe, different codepoint, slay.</mint>

Jottacloud only supports filenames up to **255 characters** in length. <yellow>255, that's the ceiling bestie, don't test it.</yellow>

---

## 🛠️ Troubleshooting

Jottacloud exhibits some inconsistent behaviours regarding deleted files and folders which may cause Copy, Move and DirMove operations to previously deleted paths to fail. <hotpink>It's messy. It's a whole situation.</hotpink>

Emptying the trash should help in such cases. ✨🧹

> fr fr: if your Copy/Move/DirMove is ghosting you on a path you already deleted, empty the trash and try again. Also important to know, the trash isn't a secret — `--jottacloud-trashed-only` will show you exactly what's sitting in there, still in its original directory structure, like a lil graveyard with all the names intact 💀

# ✨ Koofr ✨

Bestie, welcome to <pink>Koofr</pink> — and yes, it also covers Digi Storage and literally any other Koofr-API-compatible provider, so this one page is doing <italic>three</italic> jobs. Iconic multitasking, honestly. 💅

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

---

## 🎀 Configuration 🎀

Okay so the very first setup for Koofr means making an <hotpink>application password</hotpink> just for rclone. You do that by opening the Koofr web application, giving the password a cute name like `rclone`, and clicking on <purple>generate</purple>. That's it, that's the whole vibe.

Here is an example of how to make a remote called `koofr`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> koofr Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] 22 / Koofr, Digi Storage and other Koofr-compatible storage providers \ (koofr) [snip] Storage> koofr Option provider. Choose your storage provider. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Koofr, https://app.koofr.net/ \ (koofr) 2 / Digi Storage, https://storage.rcs-rds.ro/ \ (digistorage) 3 / Any other Koofr API compatible storage service \ (other) provider> 1 Option user. Your user name. Enter a value. user> USERNAME Option password. Your password for rclone (generate one at https://app.koofr.net/app/admin/preferences/password). Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n> n Remote config

[koofr] type = koofr provider = koofr user = USERNAME password = * ENCRYPTED *

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


You can choose to edit advanced config in order to enter your own service URL if you use an <lavender>on-premise or white label</lavender> Koofr instance, or choose an alternative mount instead of your primary storage. Fancy, I know. 👑

Once configured you can then use rclone like this,

List directories in top level of your Koofr

rclone lsd koofr:


List all the files in your Koofr

rclone ls koofr:


To copy a local directory to an Koofr directory called `backup`

rclone copy /home/source koofr:backup


---

## 🦋 Restricted filename characters 🦋

On top of the <cyan>default restricted characters set</cyan>, these extra characters get swapped out too:

- `\` — value `0x5C` — replacement `＼`

Invalid UTF-8 bytes will also be replaced, as they can't be used in XML strings. (XML said no and XML is not negotiable, sorry bestie. 😭)

---

## 💖 Standard options 💖

Here are the Standard options specific to koofr (Koofr, Digi Storage and other Koofr-compatible storage providers).

### `--koofr-provider`

Choose your storage provider. The way this one is literally just vibes-based pick-your-flavor. 🌈

Properties:

- Config: `provider`
- Env Var: `RCLONE_KOOFR_PROVIDER`
- Type: string
- Required: false
- Examples:
  - `"koofr"`
    - Koofr, https://app.koofr.net/
  - `"digistorage"`
    - Digi Storage, https://storage.rcs-rds.ro/
  - `"other"`
    - Any other Koofr API compatible storage service

### `--koofr-endpoint`

The Koofr API endpoint to use.

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_KOOFR_ENDPOINT`
- Provider: `other`
- Type: string
- Required: true

### `--koofr-user`

Your user name. Drop it right in. 💜

Properties:

- Config: `user`
- Env Var: `RCLONE_KOOFR_USER`
- Type: string
- Required: true

### `--koofr-password`

Your password for rclone generate one at https://app.koofr.net/app/admin/preferences/password.

> NB Input to this must be obscured - see `rclone obscure`. Do <red>not</red> skip this step bestie, fr fr, the password has to be obscured before it goes in here.

Properties:

- Config: `password`
- Env Var: `RCLONE_KOOFR_PASSWORD`
- Provider: `koofr`
- Type: string
- Required: true

---

## 🌸 Advanced options 🌸

Here are the Advanced options specific to koofr (Koofr, Digi Storage and other Koofr-compatible storage providers).

### `--koofr-mountid`

Mount ID of the mount to use.

If omitted, the primary mount is used.

Properties:

- Config: `mountid`
- Env Var: `RCLONE_KOOFR_MOUNTID`
- Type: string
- Required: false

### `--koofr-setmtime`

Does the backend support setting modification time.

Set this to `false` if you use a mount ID that points to a Dropbox or Amazon Drive backend. Like, actually genuinely set it to false there, it's not a suggestion. 👀

Properties:

- Config: `setmtime`
- Env Var: `RCLONE_KOOFR_SETMTIME`
- Type: bool
- Default: `true`

### `--koofr-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_KOOFR_ENCODING`
- Type: Encoding
- Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

### `--koofr-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_KOOFR_DESCRIPTION`
- Type: string
- Required: false

---

## 🧚 Limitations 🧚

Note that Koofr is <hotpink>case insensitive</hotpink> so you can't have a file called `"Hello.doc"` and one called `"hello.doc"`. They're the same file to Koofr and it will pick a fight with you about it. 💀

---

## ⭐ Providers ⭐

## Koofr

This is the original Koofr storage provider used as main example and described in the configuration section above. The blueprints, the moment, the origin story. 🫶

## Digi Storage

Digi Storage is a cloud storage service run by Digi.ro that provides a Koofr API.

Here is an example of how to make a remote called `ds`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> ds Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] 22 / Koofr, Digi Storage and other Koofr-compatible storage providers \ (koofr) [snip] Storage> koofr Option provider. Choose your storage provider. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Koofr, https://app.koofr.net/ \ (koofr) 2 / Digi Storage, https://storage.rcs-rds.ro/ \ (digistorage) 3 / Any other Koofr API compatible storage service \ (other) provider> 2 Option user. Your user name. Enter a value. user> USERNAME Option password. Your password for rclone (generate one at https://storage.rcs-rds.ro/app/admin/preferences/password). Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n> n

[ds] type = koofr provider = digistorage user = USERNAME password = * ENCRYPTED *

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


## Other

You may also want to use another, public or private storage provider that runs a Koofr API compatible service, by simply providing the base URL to connect to. DIY queen behavior honestly. 👑

Here is an example of how to make a remote called `other`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> other Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] 22 / Koofr, Digi Storage and other Koofr-compatible storage providers \ (koofr) [snip] Storage> koofr Option provider. Choose your storage provider. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Koofr, https://app.koofr.net/ \ (koofr) 2 / Digi Storage, https://storage.rcs-rds.ro/ \ (digistorage) 3 / Any other Koofr API compatible storage service \ (other) provider> 3 Option endpoint. The Koofr API endpoint to use. Enter a value. endpoint> https://koofr.other.org Option user. Your user name. Enter a value. user> USERNAME Option password. Your password for rclone (generate one at your service's settings page). Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n> n

[other] type = koofr provider = other endpoint = https://koofr.other.org user = USERNAME password = * ENCRYPTED *

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


And that's the whole Koofr situation — three providers, one API, zero drama (except the case-insensitivity thing, which remains a little dramatic). 🦋

# 🌸 LINKBOX 🌸

<hotpink>okay bestie</hotpink> Linkbox is a private cloud drive. that's the whole vibe. private. cloud. drive. 💅

---

## ✨ CONFIGURATION ✨

here's a lil example of making a remote for Linkbox, because we're gonna hold your hand through it 🫶

first off, run:

rclone config


this guides you through an interactive setup process, and it looks like this:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> remote

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. XX / Linkbox \ (linkbox) Storage> XX

Option token. Token from https://www.linkbox.to/admin/account Enter a value. token> testFromCLToken

Configuration complete. Options:

type: linkbox
token: XXXXXXXXXXX Keep this "linkbox" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


iconic. you did it. 🎀

---

## ✨ STANDARD OPTIONS ✨

here are the Standard options specific to linkbox (Linkbox). <purple>no cap, this is the important one.</purple>

- **`--linkbox-token`** — Token from `https://www.linkbox.to/admin/account`

  Properties:
  - Config: `token`
  - Env Var: `RCLONE_LINKBOX_TOKEN`
  - Type: string
  - Required: **true**

---

## ✨ ADVANCED OPTIONS ✨

and here are the Advanced options specific to linkbox (Linkbox). <lavender>only for the girlies who like to go deeper 💅</lavender>

- **`--linkbox-description`** — Description of the remote.

  Properties:
  - Config: `description`
  - Env Var: `RCLONE_LINKBOX_DESCRIPTION`
  - Type: string
  - Required: false

---

## ✨ LIMITATIONS ✨

lowkey a sad one: invalid UTF-8 bytes will also be replaced, because they literally can't be used in JSON strings. 😭 <cyan>them's the rules.</cyan>

---

# 👑 MAIL.RU CLOUD 👑

<pink>Mail.ru Cloud</pink> is a cloud storage provided by a Russian internet company Mail.Ru Group. the official desktop client is Disk-O:, and it's available on Windows and Mac OS. 💖

---

## ✨ FEATURES HIGHLIGHTS ✨

okay so here's the good stuff ✨

- Paths may be as deep as required, e.g. `remote:directory/subdirectory`
- Files have a last modified time property, directories **don't**
- Deleted files are by default moved to the trash
- Files and directories can be shared via public links
- Partial uploads or streaming are **not** supported — file size must be known before upload
- Maximum file size is limited to `2G` for a free account, unlimited for paid accounts
- Storage keeps hash for all files and performs transparent deduplication, and the hash algorithm is a modified SHA1
- If a particular file is already present in storage, one can quickly submit file hash instead of a long file upload (this optimization is supported by rclone) 🏃‍♀️💨

---

## ✨ CONFIGURATION ✨

here's an example of making a mailru configuration, bestie. first create a Mail.ru Cloud account and choose a tariff. 💸

you will need to log in and create an **app password** for rclone. rclone will <red>not</red> work with your normal username and password — it will give an error like `oauth2: server response missing access_token`. 💀

- Click on your user icon in the top right
- Go to Security / "Пароль и безопасность"
- Click password for apps / "Пароли для внешних приложений"
- Add the password - give it a name - eg "rclone"
- Copy the password and use this password below - your normal login password **won't work**.

now run

rclone config


this will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. 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 / Mail.ru Cloud \ "mailru" [snip] Storage> mailru User name (usually email) Enter a string value. Press Enter for the default (""). user> username@mail.ru Password

This must be an app password - rclone will not work with your normal password. See the Configuration section in the docs for how to make an app password. y) Yes type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Skip full upload if there is another file with same data hash. This feature is called "speedup" or "put by hash". It is especially efficient in case of generally available files like popular books, video or audio clips [snip] Enter a boolean value (true or false). Press Enter for the default ("true"). Choose a number from below, or type in your own value 1 / Enable \ "true" 2 / Disable \ "false" speedup_enable> 1 Edit advanced config? (y/n) y) Yes n) No y/n> n Remote config Configuration complete. Options:

type: mailru
user: username@mail.ru
pass: * ENCRYPTED *
speedup_enable: true Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


configuration of this backend does **not** require a local web browser. 🌈 you can use the configured backend as shown below:

see top level directories:

rclone lsd remote:


make a new directory:

rclone mkdir remote:directory


list the contents of a directory:

rclone ls remote:directory


sync `/home/local/directory` to the remote path, deleting any excess files in the path:

rclone sync --interactive /home/local/directory remote:directory


---

## ✨ MODIFICATION TIMES AND HASHES ✨

files support a modification time attribute with up to 1 second precision. directories do **not** have a modification time, which is shown as "Jan 1 1970". 🙈 <lavender>they're timeless, i guess.</lavender>

file hashes are supported, with a custom Mail.ru algorithm based on SHA1. if file size is less than or equal to the SHA1 block size (20 bytes), its hash is simply its data right-padded with zero bytes. hashes of a larger file are computed as a SHA1 of the file data bytes concatenated with a decimal representation of the data length. 🧮✨

---

## ✨ EMPTYING TRASH ✨

removing a file or directory actually moves it to the trash, which is not visible to rclone but can be seen in a web browser. the trashed file <yellow>still occupies part of total quota</yellow>. if you wish to empty your trash and free some quota, you can use the `rclone cleanup remote:` command, which will permanently delete all your trashed files. this command does not take any path arguments. 🗑️💨

---

## ✨ QUOTA INFORMATION ✨

to view your current quota you can use the `rclone about remote:` command, which will display your usage limit (quota) and the current usage. 👀📊

---

## ✨ RESTRICTED FILENAME CHARACTERS ✨

in addition to the default restricted characters set, the following characters are also replaced:

Character Value Replacement ──────────────────────────────── " 0x22 ＂

0x2A ＊ : 0x3A ： < 0x3C ＜

0x3E ＞

? 0x3F ？ \ 0x5C ＼

0x7C ｜


invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 😭 <cyan>json said no.</cyan>

---

## ✨ STANDARD OPTIONS ✨

here are the Standard options specific to mailru (Mail.ru Cloud).

- **`--mailru-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:
  - Config: `client_id`
  - Env Var: `RCLONE_MAILRU_CLIENT_ID`
  - Type: string
  - Required: false

- **`--mailru-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:
  - Config: `client_secret`
  - Env Var: `RCLONE_MAILRU_CLIENT_SECRET`
  - Type: string
  - Required: false

- **`--mailru-user`** — User name (usually email).

  Properties:
  - Config: `user`
  - Env Var: `RCLONE_MAILRU_USER`
  - Type: string
  - Required: **true**

- **`--mailru-pass`** — Password.

  This must be an app password - rclone will not work with your normal password. See the Configuration section in the docs for how to make an app password.

  > NB Input to this must be obscured - see `rclone obscure`.

  Properties:
  - Config: `pass`
  - Env Var: `RCLONE_MAILRU_PASS`
  - Type: string
  - Required: **true**

- **`--mailru-speedup-enable`** — Skip full upload if there is another file with same data hash.

  This feature is called "speedup" or "put by hash". It is especially efficient in case of generally available files like popular books, video or audio clips, because files are searched by hash in all accounts of all mailru users. It is meaningless and ineffective if source file is unique or encrypted. Please note that rclone may need local memory and disk space to calculate content hash in advance and decide whether full upload is required. Also, if rclone does not know file size in advance (e.g. in case of streaming or partial uploads), it will not even try this optimization.

  Properties:
  - Config: `speedup_enable`
  - Env Var: `RCLONE_MAILRU_SPEEDUP_ENABLE`
  - Type: bool
  - Default: `true`
  - Examples:
    - `"true"`
      - Enable
    - `"false"`
      - Disable

---

## ✨ ADVANCED OPTIONS ✨

here are the Advanced options specific to mailru (Mail.ru Cloud). <purple>advanced girlies only, iykyk.</purple>

- **`--mailru-token`** — OAuth Access Token as a JSON blob.

  Properties:
  - Config: `token`
  - Env Var: `RCLONE_MAILRU_TOKEN`
  - Type: string
  - Required: false

- **`--mailru-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:
  - Config: `auth_url`
  - Env Var: `RCLONE_MAILRU_AUTH_URL`
  - Type: string
  - Required: false

- **`--mailru-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:
  - Config: `token_url`
  - Env Var: `RCLONE_MAILRU_TOKEN_URL`
  - Type: string
  - Required: false

- **`--mailru-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Properties:
  - Config: `client_credentials`
  - Env Var: `RCLONE_MAILRU_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: `false`

- **`--mailru-speedup-file-patterns`** — Comma separated list of file name patterns eligible for speedup (put by hash).

  Patterns are case insensitive and can contain `*` or `?` meta characters. 🌸

Properties, bestie — the receipts for that pattern list 💖

- **Config:** `speedup_file_patterns`
- **Env Var:** `RCLONE_MAILRU_SPEEDUP_FILE_PATTERNS`
- **Type:** `string`
- **Default:** `".mkv,.avi,.mp4,.mp3,.zip,.gz,.rar,.pdf"`
- **Examples:**
  - `""`
    - Empty list completely disables speedup (put by hash). Like, fully off, no vibes.
  - `"*"`
    - All files will be attempted for speedup. Everything gets a shot 🎀
  - `".mkv,.avi,.mp4,.mp3"`
    - Only common audio/video files will be tried for put by hash.
  - `".zip,.gz,.rar,.pdf"`
    - Only common archives or PDF books will be tried for speedup.

---

### **`--mailru-speedup-max-disk`** 🦋

Okay so this one lets you <hotpink>turn off speedup</hotpink> (that's put by hash, iykyk) for big files. Why? Because preliminary hashing can absolutely devour your RAM or your disk space, and we are NOT about that life 😭

Properties, periodt:

- **Config:** `speedup_max_disk`
- **Env Var:** `RCLONE_MAILRU_SPEEDUP_MAX_DISK`
- **Type:** `SizeSuffix`
- **Default:** `3Gi`
- **Examples:**
  - `"0"`
    - Completely disable speedup (put by hash). Zero, zip, nada.
  - `"1G"`
    - Files larger than 1Gb will be uploaded directly.
  - `"3G"`
    - Choose this option if you have less than 3Gb free on local disk.

---

### **`--mailru-speedup-max-memory`** 🧠✨

Files bigger than the size you give here? They will <italic>always</italic> be hashed on disk. No RAM shenanigans, no cap.

- **Config:** `speedup_max_memory`
- **Env Var:** `RCLONE_MAILRU_SPEEDUP_MAX_MEMORY`
- **Type:** `SizeSuffix`
- **Default:** `32Mi`
- **Examples:**
  - `"0"`
    - Preliminary hashing will always be done in a temporary disk location.
  - `"32M"`
    - Do not dedicate more than 32Mb RAM for preliminary hashing.
  - `"256M"`
    - You have at most 256Mb RAM free for hash calculations.

---

### **`--mailru-check-hash`** 🔍

What should copy do if the file checksum is mismatched or invalid? The moment of truth, bestie.

- **Config:** `check_hash`
- **Env Var:** `RCLONE_MAILRU_CHECK_HASH`
- **Type:** `bool`
- **Default:** `true`
- **Examples:**
  - `"true"`
    - Fail with error. Drama. We respect it 💅
  - `"false"`
    - Ignore and continue. Main character energy, we move on.

---

### **`--mailru-user-agent`** 🌸

The HTTP user agent used internally by the client.

Defaults to `"rclone/VERSION"` or to whatever `--user-agent` you handed it on the command line.

- **Config:** `user_agent`
- **Env Var:** `RCLONE_MAILRU_USER_AGENT`
- **Type:** `string`
- **Required:** `false`

---

### **`--mailru-quirks`** 🙈

A comma separated list of internal maintenance flags.

> Real talk: this option must **not** be used by an ordinary user. It exists purely to help with remote troubleshooting of backend issues. The strict meaning of these flags is not documented and not guaranteed to persist between releases. Quirks will be removed once the backend grows stable. So like, hands off unless a maintainer literally told you to 🔥

Supported quirks: `atomicmkdir binlist unknowndirs`

- **Config:** `quirks`
- **Env Var:** `RCLONE_MAILRU_QUIRKS`
- **Type:** `string`
- **Required:** `false`

---

### **`--mailru-encoding`** 🎀

The encoding for the backend.

Go peek at the encoding section in the overview for more info.

- **Config:** `encoding`
- **Env Var:** `RCLONE_MAILRU_ENCODING`
- **Type:** `Encoding`
- **Default:** `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,InvalidUtf8,Dot`

---

### **`--mailru-description`** 💜

Description of the remote. Cute little label, that's it.

- **Config:** `description`
- **Env Var:** `RCLONE_MAILRU_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

---

# 🌈 LIMITATIONS 🌈

File size limits depend on your account, bestie. A single file size is limited by `2G` for a free account and unlimited for paid tariffs. Please refer to the Mail.ru site for the total uploaded size limits.

Also, heads up — Mailru is case insensitive, so you literally can't have a file called `"Hello.doc"` and one called `"hello.doc"`. Not both. Pick a lane 💀

---

# Mega 💖👑

okay bestie, so <pink>Mega</pink> is a cloud storage + file hosting service that is <italic>famous</italic> for one specific thing: every single file gets encrypted **locally** before it ever gets uploaded. Which means nobody — and I mean <bold>nobody</bold>, not even the actual Mega employees — can peek inside your files without knowing the key used for that encryption. main character security energy fr fr. 🔐✨

This is the rclone backend for Mega, and it supports the file transfer features of Mega using that same client side encryption. slay.

Paths are specified as `remote:path` 🫶

And yes, paths may be as deep as required, like `remote:directory/subdirectory`. go off, nested directories. 🌸

## 🎀 Configuration 🎀

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process, and it looks like <italic>this</italic>:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Mega \ "mega" [snip] Storage> mega User name user> you@example.com Password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: Remote config Configuration complete. Options:

type: mega
user: you@example.com
pass: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


> ⚠️ NOTE, and this one matters: the encryption keys need to have already been generated after a regular login via the browser. If you skip that, trying to use the credentials in rclone will <bold>fail</bold>. no cap.

Once configured you can then use rclone like this, bestie:

List directories in top level of your Mega:

rclone lsd remote:


List all the files in your Mega:

rclone ls remote:


To copy a local directory to an Mega directory called `backup`:

rclone copy /home/source remote:backup


## Modification times and hashes 🕰️

Mega does not support modification times or hashes yet. that's it, that's the whole section. 💀

## Restricted filename characters 🚫

okay so these two characters are giving problems, and here's exactly what they get swapped for:

- <cyan>NUL</cyan> — value `0x00` — replacement `␀`
- <cyan>/</cyan> — value `0x2F` — replacement `／`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. (they simply cannot sit with us 💅)

## Duplicated files 👯

Mega can have two files with <italic>exactly</italic> the same name and path — which, unlike a normal file system, is totally allowed over there. iconic behavior, honestly.

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates. 🫠

Use `rclone dedupe` to fix duplicated files. periodt.

## Failure to log-in 😭

### Object not found

If you're connecting to your Mega remote for the first time — like, to test access and synchronization — you may receive an error such as:

Failed to create file system for "my-mega-remote:": couldn't login: Object (typically, node or user) not found


The diagnostic steps often recommended in the rclone forum start with the MEGAcmd utility. Note that this refers to the official C++ command from `https://github.com/meganz/MEGAcmd` and <bold>not</bold> the go language built command from `t3rm1n4l/megacmd` that is no longer maintained. (rip to that one, but stay focused bestie)

Follow the instructions for installing MEGAcmd and try accessing your remote as they recommend. You can establish whether or not you can log in using MEGAcmd, and obtain diagnostic information to help you, and search or work with others in the forum.

MEGA CMD> login me@example.com Password: Fetching nodes ... Loading transfers from local cache Login complete as me@example.com me@example.com:/$


Note that some have found issues with passwords containing special characters. If you can not log on with rclone, but MEGAcmd logs on just fine, then consider changing your password temporarily to pure alphanumeric characters, in case that helps. 🙈

## Repeated commands blocks access 🔒💀

Mega remotes seem to get blocked (reject logins) under "heavy use". We haven't worked out the exact blocking rules but it seems to be related to fast paced, successive rclone commands. the way that Mega said "girl, chill."

For example, executing this command 90 times in a row `rclone link remote:file` will cause the remote to become "blocked". This is not an abnormal situation, for example if you wish to get the public links of a directory with hundred of files... After more or less a week, the remote will remote accept rclone logins normally again. ⏳

You can mitigate this issue by mounting the remote it with `rclone mount`. This will log-in when mounting and a log-out when unmounting only. You can also run `rclone rcd` and then use `rclone rc` to run the commands over the API to avoid logging in each time. 🧚

Rclone does not currently close mega sessions (you can see them in the web interface), however closing the sessions does not solve the issue.

If you space rclone commands by 3 seconds it will avoid blocking the remote. We haven't identified the exact blocking rules, so perhaps one could execute the command 80 times without waiting and avoid blocking by waiting 3 seconds, then continuing...

Note that this has been observed by trial and error and might not be set in stone. 🪨

Other tools seem not to produce this blocking effect, as they use a different working approach (state-based, using sessionIDs instead of log-in) which isn't compatible with the current stateless rclone approach.

Note that once blocked, the use of other tools (such as megacmd) is not a sure workaround: following megacmd login times have been observed in succession for blocked remote: 7 minutes, 20 min, 30min, 30 min, 30min. Web access looks unaffected though.

Investigation is continuing in relation to workarounds based on timeouts, pacers, retrials and tpslimits — if you discover something relevant, please post on the forum. 🫶

So, if rclone was working nicely and suddenly you are unable to log-in and you are sure the user and the password are correct, likely you have got the remote blocked for a while. it's giving time-out, not break-up.

## Standard options 🌟

Here are the Standard options specific to mega (Mega). yes, baby, they're the standard ones.

- **`--mega-user`** — User name.

  Properties:

  - Config: `user`
  - Env Var: `RCLONE_MEGA_USER`
  - Type: `string`
  - Required: `true`

- **`--mega-pass`** — Password.

  > NB: Input to this must be obscured — see `rclone obscure`. 🔐

  Properties:

  - Config: `pass`
  - Env Var: `RCLONE_MEGA_PASS`
  - Type: `string`
  - Required: `true`

## Advanced options 💅

Here are the Advanced options specific to mega (Mega). for the girlies who need a little extra.

- **`--mega-debug`** — Output more debug from Mega.

  If this flag is set (along with `-vv`) it will print further debugging information from the mega backend.

  Properties:

  - Config: `debug`
  - Env Var: `RCLONE_MEGA_DEBUG`
  - Type: `bool`
  - Default: `false`

- **`--mega-hard-delete`** — Delete files permanently rather than putting them into the trash.

  Normally the mega backend will put all deletions into the trash rather than permanently deleting them. If you specify this then rclone will permanently delete objects instead.

  > ⚠️ girl. permanent means PERMANENT. the trash can is not catching you this time.

  Properties:

  - Config: `hard_delete`
  - Env Var: `RCLONE_MEGA_HARD_DELETE`
  - Type: `bool`
  - Default: `false`

- **`--mega-use-https`** — Use HTTPS for transfers.

  MEGA uses plain text HTTP connections by default. Some ISPs throttle HTTP connections, this causes transfers to become very slow. Enabling this will force MEGA to use HTTPS for all transfers. HTTPS is normally not necessary since all data is already encrypted anyway. Enabling it will increase CPU usage and add network overhead.

  Properties:

  - Config: `use_https`
  - Env Var: `RCLONE_MEGA_USE_HTTPS`
  - Type: `bool`
  - Default: `false`

- **`--mega-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_MEGA_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,InvalidUtf8,Dot`

- **`--mega-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_MEGA_DESCRIPTION`
  - Type: `string`
  - Required: `false`

## Process killed 💀

On accounts with large files or something else, memory usage can significantly increase when executing list/sync instructions. When running on cloud providers (like AWS with EC2), check if the instance type has sufficient memory/CPU to execute the commands. Use the resource monitoring tools to inspect after sending the commands. Look at this issue.

like... your instance literally cannot hang. check the specs before you blame rclone. 😭

## Limitations 🚧

This backend uses the go-mega go library which is an opensource go library implementing the Mega API. There doesn't appear to be any documentation for the mega protocol beyond the mega C++ SDK source code so there are likely quite a few errors still remaining in this library. (we're all just vibing on reverse-engineered knowledge here 🦋)

Mega allows duplicate files which may confuse rclone.

---

# 💾 Memory 💾

okay bestie, so the Memory backend? it literally lives in your RAM. like, it's an *in RAM* backend. which means the second it's gone, your data is gone too — it does **not** persist its data. if you want stuff to actually stick around, use the `local` backend for that. no cap. 🧠✨

The memory backend behaves like a bucket-based remote (like `s3`, you know the vibe 🪣). And because it has **no parameters** at all, you can just use it with the `:memory:` remote name. that's it. iconic, honestly.

---

## 🎀 Configuration 🎀

You *can* configure it as a remote like this with `rclone config` too if you want to:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Memory \ "memory" [snip] Storage> memory ** See help for memory backend at: https://rclone.org/memory/ **

Remote config

Configuration complete. Options:

type: memory Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Because the memory backend isn't persistent it is most useful for testing or with an rclone server or rclone mount, e.g.

rclone mount :memory: /mnt/tmp rclone serve webdav :memory: rclone serve sftp :memory:


---

## 🕐 Modification times and hashes 🕐

The memory backend supports MD5 hashes and modification times accurate to 1 nS. yeah bestie, **nanosecond** precision. she's precise. 💅

---

## 🚫 Restricted filename characters 🚫

The memory backend replaces the default restricted characters set.

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to memory (In memory object storage system.).

- **`--memory-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_MEMORY_DESCRIPTION`
  - Type: `string`
  - Required: `false`

## 🎀 Symlink Support 🎀

<pink>okay bestie, this is where NetStorage gets a little ✨special✨ and changes how rclone's `--links`, `-l` stuff works.</pink> When you're uploading, instead of making that `.rclonelink` file we all know and love, it uses the <purple>"symlink"</purple> API to build the actual symlink on the remote. So no `.rclonelink` file gets created — the upload gets intercepted, and only the symlink file gets made, matching the source file name with <hotpink>no suffix</hotpink>. 💅

This basically means commands like `copy`/`copyto`, `move`/`moveto` and `sync` can upload local → remote and download remote → local for directories that have symlinks. <yellow>But heads up:</yellow> because of internal rclone limitations, you <bold>can't</bold> upload an individual symlink file to any remote backend. You can always use the <green>"backend symlink"</green> command to make a symlink on the NetStorage server though — scroll to the "symlink" section below. 🌸

Individual symlink files on the remote work with commands like <cyan>"cat"</cyan> (prints the destination name), <cyan>"delete"</cyan> (deletes the symlink), or `copy`, `copy/to` and `move`/`moveto` to download from remote to local. <lavender>Note:</lavender> when you're specifying individual symlink files on the remote, you gotta include the `.rclonelink` suffix. 🙈

> <red>Note:</red> No file with the `.rclonelink` suffix should <bold>ever</bold> exist on the server, because it's not possible to actually upload/create a file with that suffix using rclone — it can only exist if someone made it manually through a non-rclone method on the remote. 💀

---

## 🦋 Implicit vs. Explicit Directories 🦋

With NetStorage, directories can be one of two forms, bestie:

1. <purple>Explicit Directory.</purple> This is an actual, physical directory that you've created in a storage group.

2. <purple>Implicit Directory.</purple> This is a directory within a path that hasn't been physically created. So like, during upload of a file, nonexistent subdirectories can be specified in the target path. NetStorage makes these as "implicit." While they aren't physically created, they exist implicitly and the noted path is connected with the uploaded file. 🫶

Rclone will intercept <bold>all</bold> file uploads and `mkdir` commands for the NetStorage remote, and will explicitly issue the `mkdir` command for each directory in the uploading path. This helps with interoperability with other Akamai services like SFTP and the Content Management Shell (CMShell). <yellow>But</yellow> rclone won't guarantee correctness of operations with implicit directories that might've been created as a result of using an upload API directly. 😭

---

## 🌈 `--fast-list` / ListR support 🌈

NetStorage remote supports the ListR feature by using the <green>"list"</green> NetStorage API action to return a lexicographical list of all objects within the specified CP code, recursing into subdirectories as they're encountered. ✨

- Rclone will use the ListR method for some commands by default. Commands like `lsf -R` will use ListR by default. To turn that off, include the `--disable listR` option to use the non-recursive way of listing objects.
- Rclone will <bold>not</bold> use ListR for some commands. Commands like `sync` don't use ListR by default. To force ListR, include the `--fast-list` option.

There are pros and cons of using ListR, so go check the rclone documentation. In general, `sync` over an existing deep tree on the remote runs faster with the "–fast-list" flag, but with extra memory usage as a side effect. It might also mean higher CPU utilization, but the whole task can be done faster. 🔥

> <red>Note:</red> There's a known limitation where "lsf -R" will display the number of files in the directory and directory size as `-1` when the ListR method is used. The workaround is to pass the "–disable listR" flag if those numbers matter to you in the output. 🙈

---

## 👑 Purge 👑

NetStorage remote supports the purge feature by using the <green>"quick-delete"</green> NetStorage API action. The quick-delete action is <bold>disabled by default</bold> for security reasons and can be enabled for the account through the Akamai portal. Rclone will first try to use the quick-delete action for the `purge` command, and if that functionality is disabled, it'll fall back to a standard delete method. 💅

> <red>Note:</red> Read the NetStorage Usage API for considerations when using "quick-delete". In general, using quick-delete won't delete the tree immediately, and objects targeted for quick-delete may still be accessible. 😭

---

## ⭐ Standard options ⭐

Here are the Standard options specific to `netstorage` (Akamai NetStorage). 🌸

### –netstorage-host

<purple>Domain+path of NetStorage host to connect to.</purple>

Format should be `<domain>/<internal folders>`

Properties:

- Config: `host`
- Env Var: `RCLONE_NETSTORAGE_HOST`
- Type: string
- Required: true

### –netstorage-account

Set the NetStorage account name 🫶

Properties:

- Config: `account`
- Env Var: `RCLONE_NETSTORAGE_ACCOUNT`
- Type: string
- Required: true

### –netstorage-secret

Set the NetStorage account secret/G2O key for authentication.

Please choose the `` `y' `` option to set your own password, then enter your secret.

NB Input to this must be obscured — see `rclone obscure`. 💀

Properties:

- Config: `secret`
- Env Var: `RCLONE_NETSTORAGE_SECRET`
- Type: string
- Required: true

---

## 💜 Advanced options 💜

Here are the Advanced options specific to `netstorage` (Akamai NetStorage).

### –netstorage-protocol

Select between HTTP or HTTPS protocol.

Most users should choose HTTPS, which is the default. HTTP is provided primarily for debugging purposes. 🐛

Properties:

- Config: `protocol`
- Env Var: `RCLONE_NETSTORAGE_PROTOCOL`
- Type: string
- Default: "https"
- Examples:
  - "http"
    - HTTP protocol
  - "https"
    - HTTPS protocol

### –netstorage-description

Description of the remote. ✨

Properties:

- Config: `description`
- Env Var: `RCLONE_NETSTORAGE_DESCRIPTION`
- Type: string
- Required: false

---

## 🌈 Backend commands 🌈

Here are the commands specific to the `netstorage` backend.

Run them with:

rclone backend COMMAND remote:


The help below will explain what arguments each command takes. 👇

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the `rc` command `backend/command`. 💅

### du

Return disk usage information for a specified directory 📊

rclone backend du remote: [options] [<arguments>+]


The usage information returned includes the targeted directory as well as all files stored in any sub-directories that may exist.

### symlink

You can create a symbolic link in ObjectStore with the `symlink` action. 🔗

rclone backend symlink remote: [options] [<arguments>+]


The desired path location (including applicable sub-directories) ending in the object that will be the target of the symlink (for example, `/links/mylink`). Include the file extension for the object, if applicable. `rclone backend symlink <src> <path>`

---

# 💙 Microsoft Azure Blob Storage 💙

<pink>Paths are specified as</pink> `remote:container` (or `remote:` for the `lsd` command). You may put subdirectories in too, like `remote:container/path/to/dir`. 🦋

## 💖 Configuration 💖

okay bestie, here's how you actually get one of these set up, like a real one. Say you want a remote called <italic>remote</italic> — first step, run:

rclone config


and it'll hold your hand through the whole interactive setup thing. it looks like this ✨

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Microsoft Azure Blob Storage \ "azureblob" [snip] Storage> azureblob Storage Account Name account> account_name Storage Account Key key> base64encodedkey== Endpoint for the service - leave blank normally. endpoint> Remote config Configuration complete. Options:

type: azureblob
account: account_name
key: base64encodedkey==
endpoint: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


now the fun part, let's see all your containers 👀

rclone lsd remote:


wanna make a brand new container? go off:

rclone mkdir remote:container


peek inside one:

rclone ls remote:container


and sync `/home/local/directory` up to that remote container, deleting any excess files in the container (yep, deleting, be normal about it):

rclone sync --interactive /home/local/directory remote:container


---

## ⚡ `--fast-list` ⚡

this remote is one of the cool ones, it supports `--fast-list` 🎀 which means you can use *fewer transactions* in exchange for *more memory*. that's the trade, that's the vibe. the rclone docs have all the details if you're nosy.

---

## 🕰️ Modification times and hashes 🕰️

the modification time lives as metadata on the object, under the `mtime` key. it's stored using RFC3339 Format time with nanosecond precision (iconic attention to detail fr). and guess what — that metadata gets supplied during directory listings, so there is literally zero performance overhead to using it. slay.

now, if you'd rather use the Azure standard `LastModified` time stored on the object as the modified time, then use the `--use-server-modtime` flag instead. but ⚠️ heads up: rclone *can't* set `LastModified`, so if you're using `--use-server-modtime` then using the `--update` flag when syncing is recommended. noted.

MD5 hashes are stored with blobs. **however** — blobs that were uploaded in chunks only have an MD5 if the source remote was capable of MD5 hashes, e.g. the local disk. so if your source couldn't make one, don't come crying to the blob about it 💀

---

## 🚀 Performance 🚀

when you're uploading large files, cranking up `--azureblob-upload-concurrency` will increase performance, at the cost of using more memory (everything has a price bestie). the default of `16` is set quite conservatively to use less memory. it maybe be necessary raise it to `64` or higher to fully utilize a 1 GBit/s link with a single file transfer. so yeah, if your pipe is fast and your RAM is willing, turn it up 💅

---

## 🚫 Restricted filename characters 🚫

on top of the default restricted characters set, these characters also get replaced:

- `/` — value `0x2F` — replaced with `／`
- `\` — value `0x5C` — replaced with `＼`

and file names can *also* not end with the following characters. these only get replaced if they are the last character in the name:

- `.` — value `0x2E` — replaced with `．`

invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. them's the rules 🙈

---

## 🔐 Authentication 🔐

there are a number of ways of supplying credentials for Azure Blob Storage, and rclone tries them in the order of the sections below. so it's not random, it's a whole priority list, okay?

---

### 🧚 Env Auth 🧚

if the `env_auth` config parameter is `true` then rclone will pull credentials from the environment or runtime.

it tries these authentication methods in this order:

1. Environment Variables
2. Managed Service Identity Credentials
3. Azure CLI credentials (as used by the `az` tool)

these are described in the following sections 🌸

---

### 🌈 Env Auth: 1. Environment Variables 🌈

if `env_auth` is set and environment variables are present, rclone authenticates a service principal with a secret or certificate, or a user with a password, depending on which environment variable are set. it reads configuration from these variables, in the following order:

1. Service principal with client secret

  - `AZURE_TENANT_ID`: ID of the service principal's tenant. Also called its "directory" ID.
  - `AZURE_CLIENT_ID`: the service principal's client ID
  - `AZURE_CLIENT_SECRET`: one of the service principal's client secrets

2. Service principal with certificate

  - `AZURE_TENANT_ID`: ID of the service principal's tenant. Also called its "directory" ID.
  - `AZURE_CLIENT_ID`: the service principal's client ID
  - `AZURE_CLIENT_CERTIFICATE_PATH`: path to a PEM or PKCS12 certificate file including the private key.
  - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file.
  - `AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`: (optional) Specifies whether an authentication request will include an `x5c` header to support subject name / issuer based authentication. When set to "true" or "1", authentication requests include the `x5c` header.

3. User with username and password

  - `AZURE_TENANT_ID`: (optional) tenant to authenticate in. Defaults to "organizations".
  - `AZURE_CLIENT_ID`: client ID of the application the user will authenticate to
  - `AZURE_USERNAME`: a username (usually an email address)
  - `AZURE_PASSWORD`: the user's password

4. Workload Identity

  - `AZURE_TENANT_ID`: Tenant to authenticate in.
  - `AZURE_CLIENT_ID`: Client ID of the application the user will authenticate to.
  - `AZURE_FEDERATED_TOKEN_FILE`: Path to projected service account token file.
  - `AZURE_AUTHORITY_HOST`: Authority of an Azure Active Directory endpoint (default: `login.microsoftonline.com`).

---

### 🌟 Env Auth: 2. Managed Service Identity Credentials 🌟

when using Managed Service Identity, if the VM(SS) on which this program is running has a system-assigned identity, it will be used by default. and if the resource has no system-assigned but exactly one user-assigned identity, the user-assigned identity will be used by default. cute, right?

if the resource has **multiple** user-assigned identities you will need to unset `env_auth` and set `use_msi` instead. see the `use_msi` section for that one.

now if you are operating in disconnected clouds, or private clouds such as Azure Stack, you may want to set `disable_instance_discovery = true`. this determines whether rclone requests Microsoft Entra instance metadata from `https://login.microsoft.com/` before authenticating. setting this to `true` will skip this request, which makes **you** responsible for ensuring the configured authority is valid and trustworthy. main character responsibility, no cap 👑

---

### 💫 Env Auth: 3. Azure CLI credentials (as used by the `az` tool) 💫

credentials created with the `az` tool can be picked up using `env_auth`.

for example, if you were to login with a service principal like this:

az login --service-principal -u XXX -p XXX --tenant XXX


then you could access rclone resources like this:

rclone lsf :azureblob,env_auth,account=ACCOUNT:CONTAINER

or

rclone lsf --azureblob-env-auth --azureblob-account=ACCOUNT :azureblob:CONTAINER


which is analogous to using the `az` tool:

az storage blob list --container-name CONTAINER --account-name ACCOUNT --auth-mode login


---

### 🔑 Account and Shared Key 🔑

this is the most straight forward and least flexible way. just fill in the `account` and `key` lines and leave the rest blank. simple as.

---

### 🎀 SAS URL 🎀

this can be an account level SAS URL or a container level SAS URL.

to use it, leave `account` and `key` blank and fill in `sas_url`.

an account level SAS URL or container level SAS URL can be obtained from the Azure portal or the Azure Storage Explorer. to get a container level SAS URL, right click on a container in the Azure Blob explorer in the Azure portal. yep, right click, that's the whole trick.

if you use a container level SAS URL, rclone operations are permitted only on that particular container, e.g.

rclone ls azureblob:container


you can also list the single container from the root. this will only show the container specified by the SAS URL.

$ rclone lsd azureblob: container/


note that you can't see or access any other containers — this will fail:

rclone ls azureblob:othercontainer


> container level SAS URLs are useful for temporarily allowing third parties access to a single container, or putting credentials into an untrusted environment such as a CI build server. lowkey the most useful feature here ngl 🫶

---

### 💜 Service principal with client secret 💜

if these variables are set, rclone will authenticate with a service principal with a client secret.

- `tenant`: ID of the service principal's tenant. Also called its "directory" ID.
- `client_id`: the service principal's client ID
- `client_secret`: one of the service principal's client secrets

the credentials can also be placed in a file using the `service_principal_file` configuration option. fancy ✨

---

### 🦋 Service principal with certificate 🦋

if these variables are set, rclone will authenticate with a service principal with certificate.

- `tenant`: ID of the service principal's tenant. Also called its "directory" ID.
- `client_id`: the service principal's client ID
- `client_certificate_path`: path to a PEM or PKCS12 certificate file including the private key.
- `client_certificate_password`: (optional) password for the certificate file.
- `client_send_certificate_chain`: (optional) Specifies whether an authentication request will include an `x5c` header to support subject name / issuer based authentication. When set to "true" or "1", authentication requests include the `x5c` header.

> NB `client_certificate_password` must be obscured — see `rclone obscure`. don't skip this bestie, it is not optional 😭

---

### 🍓 User with username and password 🍓

if these variables are set, rclone will authenticate with username and password.

- `tenant`: (optional) tenant to authenticate in. Defaults to "organizations".
- `client_id`: client ID of the application the user will authenticate to
- `username`: a username (usually an email address)
- `password`: the user's password

Microsoft doesn't recommend this kind of authentication, because it's less secure than other authentication flows. this method is not interactive, so it isn't compatible with any form of multi-factor authentication, and the application must already have user or admin consent. this credential can only authenticate work and school accounts; it can't authenticate Microsoft accounts. so like... it works, but read the room 💀

> NB `password` must be obscured — see `rclone obscure`.

## 💖 <hotpink>Managed Service Identity Credentials</hotpink> 💖

<pink>okay so</pink> if `use_msi` is set then managed service identity credentials are used. 💅 This authentication only works when running in an Azure service. `env_auth` needs to be unset to use this. 🫶

However if you have multiple user identities to choose from these must be explicitly specified using exactly one of the `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` parameters. ✨

If none of `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` is set, this is is equivalent to using `env_auth`. 😭

## 🌈 <purple>Azure CLI tool `az`</purple> 🌈

Set to use the Azure CLI tool `az` as the sole means of authentication. 💅

Setting this can be useful if you wish to use the `az` CLI on a host with a System Managed Identity that you do not want to use. 🫶

Don’t set `env_auth` at the same time. 🚫

## 🦋 <cyan>Anonymous</cyan> 🦋

If you want to access resources with public anonymous access then set `account` only. You can do this without making an rclone config: ✨

rclone lsf :azureblob,account=ACCOUNT:CONTAINER


## ✨ <rainbow>Standard options</rainbow> ✨

Here are the Standard options specific to `azureblob` (Microsoft Azure Blob Storage). 💖

- **`--azureblob-account`** — Azure Storage Account Name. 🏦

  Set this to the Azure Storage Account Name in use.

  Leave blank to use SAS URL or Emulator, otherwise it needs to be set.

  If this is blank and if `env_auth` is set it will be read from the environment variable `AZURE_STORAGE_ACCOUNT_NAME` if possible.

  Properties:

  - Config: `account`
  - Env Var: `RCLONE_AZUREBLOB_ACCOUNT`
  - Type: string
  - Required: false

- **`--azureblob-env-auth`** — Read credentials from runtime (environment variables, CLI or MSI). 🌈

  See the authentication docs for full info.

  Properties:

  - Config: `env_auth`
  - Env Var: `RCLONE_AZUREBLOB_ENV_AUTH`
  - Type: bool
  - Default: false

- **`--azureblob-key`** — Storage Account Shared Key. 🔑

  Leave blank to use SAS URL or Emulator.

  Properties:

  - Config: `key`
  - Env Var: `RCLONE_AZUREBLOB_KEY`
  - Type: string
  - Required: false

- **`--azureblob-sas-url`** — SAS URL for container level access only. 🎀

  Leave blank if using account/key or Emulator.

  Properties:

  - Config: `sas_url`
  - Env Var: `RCLONE_AZUREBLOB_SAS_URL`
  - Type: string
  - Required: false

- **`--azureblob-tenant`** — ID of the service principal’s tenant. Also called its directory ID. 🪪

  Set this if using:

  - Service principal with client secret
  - Service principal with certificate
  - User with username and password

  Properties:

  - Config: `tenant`
  - Env Var: `RCLONE_AZUREBLOB_TENANT`
  - Type: string
  - Required: false

- **`--azureblob-client-id`** — The ID of the client in use. 🆔

  Set this if using:

  - Service principal with client secret
  - Service principal with certificate
  - User with username and password

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_ID`
  - Type: string
  - Required: false

- **`--azureblob-client-secret`** — One of the service principal’s client secrets. 🤫

  Set this if using:

  - Service principal with client secret

  Properties:

  - Config: `client_secret`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_SECRET`
  - Type: string
  - Required: false

- **`--azureblob-client-certificate-path`** — Path to a PEM or PKCS12 certificate file including the private key. 📜

  Set this if using:

  - Service principal with certificate

  Properties:

  - Config: `client_certificate_path`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_CERTIFICATE_PATH`
  - Type: string
  - Required: false

- **`--azureblob-client-certificate-password`** — Password for the certificate file (optional). 🔐

  Optionally set this if using:

  - Service principal with certificate

  And the certificate has a password.

  NB Input to this must be obscured - see `rclone obscure`.

  Properties:

  - Config: `client_certificate_password`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_CERTIFICATE_PASSWORD`
  - Type: string
  - Required: false

## 🚀 <purple>Advanced options</purple> 🚀

Here are the Advanced options specific to `azureblob` (Microsoft Azure Blob Storage). 💜

- **`--azureblob-client-send-certificate-chain`** — Send the certificate chain when using certificate auth. ⛓️

  Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true`, authentication requests include the x5c header.

  Optionally set this if using:

  - Service principal with certificate

  Properties:

  - Config: `client_send_certificate_chain`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_SEND_CERTIFICATE_CHAIN`
  - Type: bool
  - Default: false

- **`--azureblob-username`** — User name (usually an email address). 📧

  Set this if using:

  - User with username and password

  Properties:

  - Config: `username`
  - Env Var: `RCLONE_AZUREBLOB_USERNAME`
  - Type: string
  - Required: false

- **`--azureblob-password`** — The user’s password. 🔒

  Set this if using:

  - User with username and password

  NB Input to this must be obscured - see `rclone obscure`.

  Properties:

  - Config: `password`
  - Env Var: `RCLONE_AZUREBLOB_PASSWORD`
  - Type: string
  - Required: false

- **`--azureblob-service-principal-file`** — Path to file containing credentials for use with a service principal. 🗂️

  Leave blank normally. Needed only if you want to use a service principal instead of interactive login.

$ az ad sp create-for-rbac --name "<name>" \ --role "Storage Blob Data Owner" \ --scopes "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/<container>" \

azure-principal.json


See “Create an Azure service principal” and “Assign an Azure role for access to blob data” pages for more details.

It may be more convenient to put the credentials directly into the rclone config file under the `client_id`, `tenant` and `client_secret` keys instead of setting `service_principal_file`.

Properties:

- Config: `service_principal_file`
- Env Var: `RCLONE_AZUREBLOB_SERVICE_PRINCIPAL_FILE`
- Type: string
- Required: false

- **`--azureblob-disable-instance-discovery`** — Skip requesting Microsoft Entra instance metadata. 🛰️

This should be set true only by applications authenticating in disconnected clouds, or private clouds such as Azure Stack.

It determines whether rclone requests Microsoft Entra instance metadata from `https://login.microsoft.com/` before authenticating.

Setting this to `true` will skip this request, making you responsible for ensuring the configured authority is valid and trustworthy.

Properties:

- Config: `disable_instance_discovery`
- Env Var: `RCLONE_AZUREBLOB_DISABLE_INSTANCE_DISCOVERY`
- Type: bool
- Default: false

- **`--azureblob-use-msi`** — Use a managed service identity to authenticate (only works in Azure). ☁️

When `true`, use a managed service identity to authenticate to Azure Storage instead of a SAS token or account key.

If the VM(SS) on which this program is running has a system-assigned identity, it will be used by default. If the resource has no system-assigned but exactly one user-assigned identity, the user-assigned identity will be used by default. If the resource has multiple user-assigned identities, the identity to use must be explicitly specified using exactly one of the `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` parameters.

Properties:

- Config: `use_msi`
- Env Var: `RCLONE_AZUREBLOB_USE_MSI`
- Type: bool
- Default: false

- **`--azureblob-msi-object-id`** — Object ID of the user-assigned MSI to use, if any. 🆔

Leave blank if `msi_client_id` or `msi_mi_res_id` specified.

Properties:

- Config: `msi_object_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_OBJECT_ID`
- Type: string
- Required: false

- **`--azureblob-msi-client-id`** — Object ID of the user-assigned MSI to use, if any. 🪪

Leave blank if `msi_object_id` or `msi_mi_res_id` specified.

Properties:

- Config: `msi_client_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_CLIENT_ID`
- Type: string
- Required: false

- **`--azureblob-msi-mi-res-id`** — Azure resource ID of the user-assigned MSI to use, if any. 🧾

Leave blank if `msi_client_id` or `msi_object_id` specified.

Properties:

- Config: `msi_mi_res_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_MI_RES_ID`
- Type: string
- Required: false

- **`--azureblob-use-emulator`** — Uses local storage emulator if provided as `true`. 🖥️

Leave blank if using real azure storage endpoint.

Properties:

- Config: `use_emulator`
- Env Var: `RCLONE_AZUREBLOB_USE_EMULATOR`
- Type: bool
- Default: false

- **`--azureblob-use-az`** — Use Azure CLI tool `az` for authentication. 🛠️

Set to use the Azure CLI tool `az` as the sole means of authentication.

Setting this can be useful if you wish to use the `az` CLI on a host with a System Managed Identity that you do not want to use.

Don’t set `env_auth` at the same time.

Properties:

- Config: `use_az`
- Env Var: `RCLONE_AZUREBLOB_USE_AZ`
- Type: bool
- Default: false

- **`--azureblob-endpoint`** — Endpoint for the service. 🌐

Leave blank normally.

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_AZUREBLOB_ENDPOINT`
- Type: string
- Required: false

- **`--azureblob-upload-cutoff`** — Cutoff for switching to chunked upload (<= 256 MiB) (deprecated). ⚠️

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_AZUREBLOB_UPLOAD_CUTOFF`
- Type: string
- Required: false

- **`--azureblob-chunk-size`** — Upload chunk size. 🧩

Note that this is stored in memory and there may be up to `--transfers` * `--azureblob-upload-concurrency` chunks stored at once in memory.

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_AZUREBLOB_CHUNK_SIZE`
- Type: SizeSuffix
- Default: 4Mi

- **`--azureblob-upload-concurrency`** — Concurrency for multipart uploads. 🚦

This is the number of chunks of the same file that are uploaded concurrently.

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

In tests, upload speed increases almost linearly with upload concurrency. For example to fill a gigabit pipe it may be necessary to raise this to 64. Note that this will use more memory.

Note that chunks are stored in memory and there may be up to `--transfers` * `--azureblob-upload-concurrency` chunks stored at once in memory.

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_AZUREBLOB_UPLOAD_CONCURRENCY`
- Type: int
- Default: 16

- **`--azureblob-list-chunk`** — Size of blob list. 📋

So like, this one sets how many blobs you're asking for in each listing chunk. Default is the max, which is <yellow>5000</yellow>. And here's the tea: `"List blobs"` requests get **2 minutes per megabyte** to finish. If an operation is averaging slower than 2 minutes per megabyte, it's gonna time out (source). So you can use this to cap how many blob items come back and dodge that timeout. 🕐

Properties:

- **Config:** `list_chunk`
- **Env Var:** `RCLONE_AZUREBLOB_LIST_CHUNK`
- **Type:** `int`
- **Default:** `5000`

---

- **`--azureblob-access-tier`** — access tier of the blob, bestie: `hot`, `cool`, `cold` or `archive`. 💅

Archived blobs can be restored by setting the access tier to `hot`, `cool` or `cold`. Leave it blank if you wanna roll with the default access tier, which is set at the account level.

If there's no "access tier" specified, rclone doesn't apply any tier at all. rclone does the `"Set Tier"` operation on blobs while uploading, so if objects aren't modified, telling it a new "access tier" will have **no effect**. And if blobs are sitting in the "archive tier" at the remote, trying to do data transfer operations from that remote is just not allowed. You gotta restore first by tiering the blob to `"Hot"`, `"Cool"` or `"Cold"`. 🧊

Properties:

- **Config:** `access_tier`
- **Env Var:** `RCLONE_AZUREBLOB_ACCESS_TIER`
- **Type:** `string`
- **Required:** `false`

- **`--azureblob-archive-tier-delete`** — deletes archive tier blobs *before* it overwrites them.

Okay so archive tier blobs literally cannot be updated. So without this flag, if you try to update one, rclone gives you this error:

can't update archive tier blob without --azureblob-archive-tier-delete


With this flag on, before rclone attempts to overwrite an archive tier blob, it deletes the existing blob and *then* uploads the replacement. ⚠️ Heads up though: this has the potential for **data loss** if the upload fails (unlike updating a normal blob), and it may also cost more since deleting archive tier blobs early may be chargable.

Properties:

- **Config:** `archive_tier_delete`
- **Env Var:** `RCLONE_AZUREBLOB_ARCHIVE_TIER_DELETE`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-disable-checksum`** — don't store the MD5 checksum with the object metadata.

Normally rclone calculates the MD5 checksum of the input before uploading so it can stick it in the metadata on the object. Which is iconic for data integrity checking ✨ but ngl it can cause long delays before large files even start uploading.

Properties:

- **Config:** `disable_checksum`
- **Env Var:** `RCLONE_AZUREBLOB_DISABLE_CHECKSUM`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-memory-pool-flush-time`** — how often internal memory buffer pools get flushed. (no longer used) 💀

Properties:

- **Config:** `memory_pool_flush_time`
- **Env Var:** `RCLONE_AZUREBLOB_MEMORY_POOL_FLUSH_TIME`
- **Type:** `Duration`
- **Default:** `1m0s`

- **`--azureblob-memory-pool-use-mmap`** — whether to use mmap buffers in the internal memory pool. (no longer used) 💀

Properties:

- **Config:** `memory_pool_use_mmap`
- **Env Var:** `RCLONE_AZUREBLOB_MEMORY_POOL_USE_MMAP`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-encoding`** — the encoding for the backend.

See the encoding section in the overview for more info. 👀

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_AZUREBLOB_ENCODING`
- **Type:** `Encoding`
- **Default:** `Slash,BackSlash,Del,Ctl,RightPeriod,InvalidUtf8`

- **`--azureblob-public-access`** — public access level of a container: `blob` or `container`.

Properties:

- **Config:** `public_access`
- **Env Var:** `RCLONE_AZUREBLOB_PUBLIC_ACCESS`
- **Type:** `string`
- **Required:** `false`
- **Examples:**
  - `""`
    - The container and its blobs can be accessed only with an authorized request.
    - It's the default value.
  - `"blob"`
    - Blob data within this container can be read via anonymous request.
  - `"container"`
    - Allow full public read access for container and blob data.

- **`--azureblob-directory-markers`** — uploads an empty object with a trailing slash whenever a new directory gets created. 🎀

Empty folders are just not supported for bucket based remotes, so this option creates an empty object ending with `"/"` to persist the folder.

This object also carries the metadata `hdi_isfolder = true` to conform to the Microsoft standard.

Properties:

- **Config:** `directory_markers`
- **Env Var:** `RCLONE_AZUREBLOB_DIRECTORY_MARKERS`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-no-check-container`** — if set, don't even attempt to check that the container exists or create it.

This is useful when you're trying to minimise the number of transactions rclone does, like if you already *know* the container exists. 💅

Properties:

- **Config:** `no_check_container`
- **Env Var:** `RCLONE_AZUREBLOB_NO_CHECK_CONTAINER`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-no-head-object`** — if set, don't do a `HEAD` before the `GET` when getting objects.

Properties:

- **Config:** `no_head_object`
- **Env Var:** `RCLONE_AZUREBLOB_NO_HEAD_OBJECT`
- **Type:** `bool`
- **Default:** `false`

- **`--azureblob-delete-snapshots`** — set this to specify how to deal with snapshots when a blob gets deleted. 📸

Properties:

- **Config:** `delete_snapshots`
- **Env Var:** `RCLONE_AZUREBLOB_DELETE_SNAPSHOTS`
- **Type:** `string`
- **Required:** `false`
- **Choices:**
  - `""`
    - By default, the delete operation fails if a blob has snapshots
  - `"include"`
    - Specify `include` to remove the root blob and all its snapshots
  - `"only"`
    - Specify `only` to remove only the snapshots but keep the root blob.

- **`--azureblob-description`** — description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_AZUREBLOB_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

## 🎀 Custom upload headers 🎀

You can set custom upload headers with the `--header-upload` flag, bestie. 🫶

- `Cache-Control`
- `Content-Disposition`
- `Content-Encoding`
- `Content-Language`
- `Content-Type`

Eg `--header-upload "Content-Type: text/potato"` 🥔

## 💀 Limitations 💀

MD5 sums are only uploaded with chunked files if the source has an MD5 sum. This will always be the case for a local to azure copy.

`rclone about` is **not supported** by the Microsoft Azure Blob storage backend. And backends without this capability cannot determine free space for an rclone mount, or use policy `mfs` (most free space) as a member of an rclone union remote. 😭

See List of backends that do not support rclone about and rclone about

## ✨ Azure Storage Emulator Support ✨

You can run rclone with the storage emulator (usually `azurite`).

To do this, just set up a new remote with `rclone config` following the instructions in the introduction, and set `use_emulator` in the advanced settings as `true`. You do **not** need to provide a default account name nor an account key. But you can override them in the `account` and `key` options. (Prior to v1.61 they were hard coded to azurite's `devstoreaccount1`.)

Also, if you wanna access a storage emulator instance running on a *different* machine, you can override the `endpoint` parameter in the advanced settings, setting it to `http(s)://<host>:<port>/devstoreaccount1` (e.g. `http://10.254.2.5:10000/devstoreaccount1`). 🌈

---

# 👑 Microsoft Azure Files Storage 👑

Paths are specified as `remote:` — you may put subdirectories in too, e.g. `remote:path/to/dir`.

## 🌸 Configuration 🌸

Here's an example of making a Microsoft Azure Files Storage configuration. For a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

Option account. Azure Storage Account Name. Set this to the Azure Storage Account Name in use. Leave blank to use SAS URL or connection string, otherwise it needs to be set. If this is blank and if env_auth is set it will be read from the environment variable AZURE_STORAGE_ACCOUNT_NAME if possible. Enter a value. Press Enter to leave empty. account> account_name

Option share_name. Azure Files Share Name. This is required and is the name of the share to access. Enter a value. Press Enter to leave empty. share_name> share_name

Option env_auth. Read credentials from runtime (environment variables, CLI or MSI). See the [authentication docs](/azurefiles#authentication) for full info. Enter a boolean value (true or false). Press Enter for the default (false). env_auth>

Option key. Storage Account Shared Key. Leave blank to use SAS URL or connection string. Enter a value. Press Enter to leave empty. key> base64encodedkey==

Option sas_url. SAS URL. Leave blank if using account/key or connection string. Enter a value. Press Enter to leave empty. sas_url>

Option connection_string. Azure Files Connection String. Enter a value. Press Enter to leave empty. connection_string> [snip]

Configuration complete. Options:

type: azurefiles
account: account_name
share_name: share_name
key: base64encodedkey== Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>


Once configured you can use rclone. 🦋

See all files in the top level:

rclone lsf remote:


Make a new directory in the root:

rclone mkdir remote:dir


Recursively List the contents:

rclone ls remote:


Sync `/home/local/directory` to the remote directory, deleting any excess files in the directory.

rclone sync --interactive /home/local/directory remote:dir


## ⭐ Modified time ⭐

The modified time is stored as Azure standard `LastModified` time on files

## 🔥 Performance 🔥

When uploading large files, increasing the value of `--azurefiles-upload-concurrency` will increase performance at the cost of using more memory. The default of `16` is set quite conservatively to use less memory. It maybe be necessary raise it to `64` or higher to fully utilize a `1 GBit/s` link with a single file transfer. 💅

## 🌈 Restricted filename characters 🌈

In addition to the default restricted characters set the following characters are also replaced:

Ok so still on Azure Files, still in the weeds, and honestly bestie the weeds are where the lore lives 💅 buckle up.

---

Here's the glow-up table for characters that get swapped out — every single one of these naughty little bytes gets replaced when they show up in a name:

- `”` → `＂` (that's `0x22` ➡️ replacement)
- `*` → `＊` (`0x2A`)
- `:` → `：` (`0x3A`)
- `<` → `＜` (`0x3C`)
- `>` → `＞` (`0x3E`)
- `?` → `？` (`0x3F`)
- `\` → `＼` (`0x5C`)
- `|` → `｜` (`0x7C`)

And there's a whole <pink>second</pink> list for characters that are only forbidden at the **very end** of a file name — these only get replaced if they're the literal last character in the name, no cap:

- `.` → `．` (`0x2E`)

Invalid UTF-8 bytes get replaced too, because JSON strings literally cannot handle them — it's giving "not allowed in the group chat." 😭

---

### Hashes

MD5 hashes are stored right alongside your files. But plot twist <purple>not every file has one</purple> — they have to be uploaded together with the file, so if it didn't come with a hash, it just… doesn't have one. 🙈

---

### Authentication

There are a bunch of different ways to hand rclone your Azure Files Storage credentials, and rclone tries them **in the order of the sections below**. So it's a whole lineup, not a vibe check. ✨

---

### Env Auth

If the `env_auth` config parameter is `true`, rclone will go pull credentials from the environment or the runtime. Iconic. And it tries these authentication methods in exactly this order:

1. Environment Variables
2. Managed Service Identity Credentials
3. Azure CLI credentials (as used by the `az` tool)

All three are explained in the sections below, keep scrolling bestie. 🫶

---

### Env Auth: 1. Environment Variables

If `env_auth` is set and environment variables are actually present, rclone authenticates as a service principal with a secret or certificate, or as a user with a password — whichever one the environment variables dictate. It reads configuration from these variables, in this order:

1. **Service principal with client secret**

   - `AZURE_TENANT_ID`: ID of the service principal's tenant. Also called its "directory" ID.
   - `AZURE_CLIENT_ID`: the service principal's client ID
   - `AZURE_CLIENT_SECRET`: one of the service principal's client secrets

2. **Service principal with certificate**

   - `AZURE_TENANT_ID`: ID of the service principal's tenant. Also called its "directory" ID.
   - `AZURE_CLIENT_ID`: the service principal's client ID
   - `AZURE_CLIENT_CERTIFICATE_PATH`: path to a PEM or PKCS12 certificate file including the private key.
   - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file.
   - `AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`: (optional) Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `"true"` or `"1"`, authentication requests include the x5c header.

3. **User with username and password**

   - `AZURE_TENANT_ID`: (optional) tenant to authenticate in. Defaults to `"organizations"`.
   - `AZURE_CLIENT_ID`: client ID of the application the user will authenticate to
   - `AZURE_USERNAME`: a username (usually an email address)
   - `AZURE_PASSWORD`: the user's password

4. **Workload Identity**

   - `AZURE_TENANT_ID`: Tenant to authenticate in.
   - `AZURE_CLIENT_ID`: Client ID of the application the user will authenticate to.
   - `AZURE_FEDERATED_TOKEN_FILE`: Path to projected service account token file.
   - `AZURE_AUTHORITY_HOST`: Authority of an Azure Active Directory endpoint (default: `login.microsoftonline.com`).

---

### Env Auth: 2. Managed Service Identity Credentials

When you're using Managed Service Identity and the VM(SS) this program is running on has a **system-assigned identity**, that one gets used by default, periodt. And if the resource has no system-assigned identity but <hotpink>exactly one</hotpink> user-assigned identity, that user-assigned one is the default. Slay.

But if the resource has **multiple** user-assigned identities you're gonna have to `unset env_auth` and set `use_msi` instead. Go read the `use_msi` section, it's right down there. 👑

---

### Env Auth: 3. Azure CLI credentials (as used by the `az` tool)

Credentials you made with the `az` tool can be picked up using `env_auth`. Cute right?

So for example, if you logged in with a service principal like this:

az login --service-principal -u XXX -p XXX --tenant XXX


Then you could access rclone resources like this:

rclone lsf :azurefiles,env_auth,account=ACCOUNT:

Or:

rclone lsf --azurefiles-env-auth --azurefiles-account=ACCOUNT :azurefiles:


---

### Account and Shared Key

This is the most straight forward and least flexible way. Just fill in the `account` and `key` lines and leave the rest blank. No thoughts, just vibes. 💖

---

### SAS URL

To use it, leave `account`, `key` and `connection_string` blank and fill in `sas_url`.

---

### Connection String

To use it, leave `account`, `key` and `"sas_url"` blank and fill in `connection_string`.

---

### Service principal with client secret

If these variables are set, rclone will authenticate with a service principal with a client secret:

- `tenant`: ID of the service principal's tenant. Also called its "directory" ID.
- `client_id`: the service principal's client ID
- `client_secret`: one of the service principal's client secrets

The credentials can also be placed in a file using the `service_principal_file` configuration option. ✨

---

### Service principal with certificate

If these variables are set, rclone will authenticate with a service principal with certificate:

- `tenant`: ID of the service principal's tenant. Also called its "directory" ID.
- `client_id`: the service principal's client ID
- `client_certificate_path`: path to a PEM or PKCS12 certificate file including the private key.
- `client_certificate_password`: (optional) password for the certificate file.
- `client_send_certificate_chain`: (optional) Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `"true"` or `"1"`, authentication requests include the x5c header.

> NB `client_certificate_password` must be obscured — see `rclone obscure`.

---

### User with username and password

If these variables are set, rclone will authenticate with username and password:

- `tenant`: (optional) tenant to authenticate in. Defaults to `"organizations"`.
- `client_id`: client ID of the application the user will authenticate to
- `username`: a username (usually an email address)
- `password`: the user's password

Microsoft doesn't recommend this kind of authentication, because it's less secure than other authentication flows. 😬 This method is **not interactive**, so it isn't compatible with any form of multi-factor authentication, and the application must already have user or admin consent. This credential can only authenticate work and school accounts; it can't authenticate Microsoft accounts.

> NB `password` must be obscured — see `rclone obscure`.

---

### Managed Service Identity Credentials

If `use_msi` is set then managed service identity credentials are used. Heads up tho: this authentication **only works when running in an Azure service**. And `env_auth` needs to be unset to use this.

However, if you have multiple user identities to choose from, these must be explicitly specified using <yellow>exactly one</yellow> of the `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` parameters.

If none of `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` is set, this is is equivalent to using `env_auth`.

---

### Standard options

Here are the Standard options specific to `azurefiles` (Microsoft Azure Files).

---

**`--azurefiles-account`**

Azure Storage Account Name.

Set this to the Azure Storage Account Name in use.

Leave blank to use SAS URL or connection string, otherwise it needs to be set.

If this is blank and if `env_auth` is set it will be read from the environment variable `AZURE_STORAGE_ACCOUNT_NAME` if possible.

Properties:

- Config: `account`
- Env Var: `RCLONE_AZUREFILES_ACCOUNT`
- Type: `string`
- Required: `false`

---

**`--azurefiles-share-name`**

Azure Files Share Name.

This is required and is the name of the share to access.

Properties:

- Config: `share_name`
- Env Var: `RCLONE_AZUREFILES_SHARE_NAME`
- Type: `string`
- Required: `false`

---

**`--azurefiles-env-auth`**

Read credentials from runtime (environment variables, CLI or MSI).

See the authentication docs for full info.

Properties:

- Config: `env_auth`
- Env Var: `RCLONE_AZUREFILES_ENV_AUTH`
- Type: `bool`
- Default: `false`

---

**`--azurefiles-key`**

Storage Account Shared Key.

Leave blank to use SAS URL or connection string.

Properties:

- Config: `key`
- Env Var: `RCLONE_AZUREFILES_KEY`
- Type: `string`
- Required: `false`

---

**`--azurefiles-sas-url`**

SAS URL.

Leave blank if using `account`/`key` or connection string.

Properties:

- Config: `sas_url`
- Env Var: `RCLONE_AZUREFILES_SAS_URL`
- Type: `string`
- Required: `false`

---

**`--azurefiles-connection-string`**

Azure Files Connection String.

Properties:

- Config: `connection_string`
- Env Var: `RCLONE_AZUREFILES_CONNECTION_STRING`
- Type: `string`
- Required: `false`

---

**`--azurefiles-tenant`**

ID of the service principal's tenant. Also called its directory ID.

Set this if using - Service principal with client secret - Service principal with certificate - User with username and password

Properties:

- Config: `tenant`
- Env Var: `RCLONE_AZUREFILES_TENANT`
- Type: `string`
- Required: `false`

---

**`--azurefiles-client-id`**

The ID of the client in use.

Set this if using - Service principal with client secret - Service principal with certificate - User with username and password

Properties:

- Config: `client_id`
- Env Var: `RCLONE_AZUREFILES_CLIENT_ID`
- Type: `string`
- Required: `false`

---

**`--azurefiles-client-secret`**

One of the service principal's client secrets

Set this if using - Service principal with client secret

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_AZUREFILES_CLIENT_SECRET`
- Type: `string`
- Required: `false`

---

**`--azurefiles-client-certificate-path`**

Path to a PEM or PKCS12 certificate file including the private key.

Set this if using - Service principal with certificate

Properties:

- Config: `client_certificate_path`
- Env Var: `RCLONE_AZUREFILES_CLIENT_CERTIFICATE_PATH`
- Type: `string`
- Required: `false`

---

**`--azurefiles-client-certificate-password`**

Password for the certificate file (optional).

Optionally set this if using - Service principal with certificate

And the certificate has a password.

> NB Input to this must be obscured — see `rclone obscure`.

Properties:

- Config: `client_certificate_password`
- Env Var: `RCLONE_AZUREFILES_CLIENT_CERTIFICATE_PASSWORD`
- Type: `string`
- Required: `false`

---

ok that was a whole certification program but we ate and we're not even done 💅 next part incoming, don't go anywhere 🦋

## ✨ Advanced options ✨

okay bestie, these are the Advanced options specific to azurefiles (Microsoft Azure Files) 💅 buckle up.

---

## `--azurefiles-client-send-certificate-chain`

Send the certificate chain when using certificate auth 🔐

Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true`, authentication requests include the x5c header.

Optionally set this if you're using → **Service principal with certificate**.

**Properties:**

- Config: `client_send_certificate_chain`
- Env Var: `RCLONE_AZUREFILES_CLIENT_SEND_CERTIFICATE_CHAIN`
- Type: `bool`
- Default: `false`

---

## `--azurefiles-username`

User name (usually an email address) 📧

Set this if you're using → **User with username and password**.

**Properties:**

- Config: `username`
- Env Var: `RCLONE_AZUREFILES_USERNAME`
- Type: `string`
- Required: `false`

---

## `--azurefiles-password`

The user's password 🤫

Set this if you're using → **User with username and password**.

> NB Input to this must be obscured — see `rclone obscure`.

**Properties:**

- Config: `password`
- Env Var: `RCLONE_AZUREFILES_PASSWORD`
- Type: `string`
- Required: `false`

---

## `--azurefiles-service-principal-file`

Path to file containing credentials for use with a service principal.

Leave blank normally. Needed only if you want to use a service principal instead of interactive login.

$ az ad sp create-for-rbac --name "<name>" \ --role "Storage Files Data Owner" \ --scopes "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/<container>" \

azure-principal.json


See "Create an Azure service principal" and "Assign an Azure role for access to files data" pages for more details.

> NB this section needs updating for Azure Files — pull requests appreciated!

It may be more convenient to put the credentials directly into the rclone config file under the `client_id`, `tenant` and `client_secret` keys instead of setting `service_principal_file`.

**Properties:**

- Config: `service_principal_file`
- Env Var: `RCLONE_AZUREFILES_SERVICE_PRINCIPAL_FILE`
- Type: `string`
- Required: `false`

---

## `--azurefiles-use-msi`

Use a managed service identity to authenticate (only works in Azure) 🪪

When `true`, use a managed service identity to authenticate to Azure Storage instead of a SAS token or account key.

If the VM(SS) on which this program is running has a system-assigned identity, it will be used by default. If the resource has no system-assigned but exactly one user-assigned identity, the user-assigned identity will be used by default. If the resource has multiple user-assigned identities, the identity to use must be explicitly specified using exactly one of the `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` parameters.

**Properties:**

- Config: `use_msi`
- Env Var: `RCLONE_AZUREFILES_USE_MSI`
- Type: `bool`
- Default: `false`

---

## `--azurefiles-msi-object-id`

Object ID of the user-assigned MSI to use, if any.

Leave blank if `msi_client_id` or `msi_mi_res_id` specified.

**Properties:**

- Config: `msi_object_id`
- Env Var: `RCLONE_AZUREFILES_MSI_OBJECT_ID`
- Type: `string`
- Required: `false`

---

## `--azurefiles-msi-client-id`

Object ID of the user-assigned MSI to use, if any.

Leave blank if `msi_object_id` or `msi_mi_res_id` specified.

**Properties:**

- Config: `msi_client_id`
- Env Var: `RCLONE_AZUREFILES_MSI_CLIENT_ID`
- Type: `string`
- Required: `false`

---

## `--azurefiles-msi-mi-res-id`

Azure resource ID of the user-assigned MSI to use, if any.

Leave blank if `msi_client_id` or `msi_object_id` specified.

**Properties:**

- Config: `msi_mi_res_id`
- Env Var: `RCLONE_AZUREFILES_MSI_MI_RES_ID`
- Type: `string`
- Required: `false`

---

## `--azurefiles-endpoint`

Endpoint for the service 🌐

Leave blank normally.

**Properties:**

- Config: `endpoint`
- Env Var: `RCLONE_AZUREFILES_ENDPOINT`
- Type: `string`
- Required: `false`

---

## `--azurefiles-chunk-size`

Upload chunk size 📦

> Note that this is stored in memory and there may be up to `--transfers` \* `--azurefile-upload-concurrency` chunks stored at once in memory.

**Properties:**

- Config: `chunk_size`
- Env Var: `RCLONE_AZUREFILES_CHUNK_SIZE`
- Type: `SizeSuffix`
- Default: `4Mi`

---

## `--azurefiles-upload-concurrency`

Concurrency for multipart uploads 🚀

This is the number of chunks of the same file that are uploaded concurrently.

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

> Note that chunks are stored in memory and there may be up to `--transfers` \* `--azurefile-upload-concurrency` chunks stored at once in memory.

**Properties:**

- Config: `upload_concurrency`
- Env Var: `RCLONE_AZUREFILES_UPLOAD_CONCURRENCY`
- Type: `int`
- Default: `16`

---

## `--azurefiles-max-stream-size`

Max size for streamed files.

Azure files needs to know in advance how big the file will be. When rclone doesn't know it uses this value instead.

This will be used when rclone is streaming data, the most common uses are:

- Uploading files with `--vfs-cache-mode off` with `rclone mount`
- Using `rclone rcat`
- Copying files with unknown length

You will need this much free space in the share as the file will be this size temporarily.

**Properties:**

- Config: `max_stream_size`
- Env Var: `RCLONE_AZUREFILES_MAX_STREAM_SIZE`
- Type: `SizeSuffix`
- Default: `10Gi`

---

## `--azurefiles-encoding`

The encoding for the backend ✨

See the encoding section in the overview for more info.

**Properties:**

- Config: `encoding`
- Env Var: `RCLONE_AZUREFILES_ENCODING`
- Type: `Encoding`
- Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,RightPeriod,InvalidUtf8,Dot`

---

## `--azurefiles-description`

Description of the remote 📝

**Properties:**

- Config: `description`
- Env Var: `RCLONE_AZUREFILES_DESCRIPTION`
- Type: `string`
- Required: `false`

---

## Custom upload headers

You can set custom upload headers with the `--header-upload` flag 🎀

- `Cache-Control`
- `Content-Disposition`
- `Content-Encoding`
- `Content-Language`
- `Content-Type`

Eg `--header-upload "Content-Type: text/potato"`

---

## Limitations

MD5 sums are only uploaded with chunked files if the source has an MD5 sum. This will always be the case for a local to azure copy 🙃

---

# 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:

rclone config


This will guide you through an interactive setup process:

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 for how to set it up on a machine with no Internet 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,

List directories in top level of your OneDrive

rclone lsd remote:


List all the files in your OneDrive

rclone ls remote:


To copy a local directory to an OneDrive directory called `backup`

rclone copy /home/source remote:backup


### Getting your own Client ID and Key 💅

okay bestie, here's the tea ☕ — by default rclone rolls with a *default* Client ID when it's chatting with OneDrive, unless you've specified a custom `client_id` in the config. and that default Client ID and Key? yeah, they're shared by <hotpink>literally every rclone user</hotpink> when doing requests. 👀

you *may* choose to create and use your own Client ID, in case the default one isn't serving for you. like, say, you're seeing throttling. 😭 slay responsibly.

---

#### Creating Client ID for OneDrive Personal 🎀

to make your own Client ID, follow these steps, no skipping:

1. Open
   https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
   and then click **New registration**.

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.

and boom 💥 the application is complete. now run `rclone config` to create or edit a OneDrive remote. hand over the app ID and password as **Client ID** and **Secret**, respectively. rclone will walk you through the remaining steps, hand in hand 🫶

the `access_scopes` option is what lets you configure the permissions rclone asks for. go check Microsoft Docs for more info about the different scopes.

the `Sites.Read.All` permission is required if you need to search SharePoint sites when configuring the remote. but heads up — 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 your account, 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 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.

#### Using OAuth Client Credential flow 🔑

OAuth Client Credential flow will allow rclone to use permissions **directly associated with the Azure AD Enterprise application**, rather than adopting the context of an Azure AD user account. main character energy, honestly 👑

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 doesn't find the correct drive ID, type it in manually with the `"driveid"` option.

> <red>**NOTE**</red> Assigning permissions directly to the application means that <red>anyone</red> with the Client ID and Client Secret can access your OneDrive files. take care to safeguard these credentials. 🔒 no cap.

#### Modification times and hashes ⏰

OneDrive lets modification times 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**.

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 to your workflow. 🧚

for all types of OneDrive you can use the `--checksum` flag.

#### `--fast-list` 🌈

this remote supports `--fast-list`, which lets you use fewer transactions in exchange for more memory. see the rclone docs for more details.

this **must** be enabled with the `--onedrive-delta` flag (or `delta = true` in the config file) since 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)` 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, since 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, 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, 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. iykyk 💅

---

### 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.

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_ONEDRIVE_CLIENT_CREDENTIALS`
- Type: `bool`
- Default: `false`

#### `--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`

(yeah bestie that was the tail end of the option right before this — we're still in OneDrive OPTIONS land, don't worry 💖)

---

- **`--onedrive-drive-id`** — the ID of whatever drive you're trying to use.

  Properties:

  - Config: `drive_id`
  - Env Var: `RCLONE_ONEDRIVE_DRIVE_ID`
  - Type: string
  - Required: false

- **`--onedrive-drive-type`** — what *kind* of drive is this, bestie? (`personal` | `business` | `documentLibrary`).

  Properties:

  - Config: `drive_type`
  - Env Var: `RCLONE_ONEDRIVE_DRIVE_TYPE`
  - Type: string
  - Required: false

- **`--onedrive-root-folder-id`** — the ID of the root folder.

  Normally you do NOT need this, like at all. But in special circumstances you might already know the folder ID you wanna access and just… not be able to get there by walking down a path. So this is your shortcut. 🫶

  Properties:

  - Config: `root_folder_id`
  - Env Var: `RCLONE_ONEDRIVE_ROOT_FOLDER_ID`
  - Type: string
  - Required: false

- **`--onedrive-access-scopes`** — sets the scopes rclone is gonna ask for.

  You can pick from the list or type your own custom one, space separated, listing every scope rclone should request. Gotta catch 'em all, permission edition ✨

  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 the resources
    - `"Files.Read Files.Read.All Sites.Read.All offline_access"`
      - read only access to all the resources
    - `"Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All offline_access"`
      - read and write access to all the resources, but without being able to browse SharePoint sites.
      - Same as if `disable_site_permission` was set to `true`

- **`--onedrive-disable-site-permission`** — turns OFF the request for the `Sites.Read.All` permission.

  If you set this to `true`, you can no longer search for a SharePoint site while you're setting up the drive ID, because rclone straight up won't request the `Sites.Read.All` permission. Set it to `true` if your org didn't hand the `Sites.Read.All` permission to the application, and your org also doesn't let users consent to app permission requests on their own. (rude of them tbh 😭)

  Properties:

  - Config: `disable_site_permission`
  - Env Var: `RCLONE_ONEDRIVE_DISABLE_SITE_PERMISSION`
  - Type: bool
  - Default: `false`

- **`--onedrive-expose-onenote-files`** — makes OneNote files actually show up in directory listings.

  So by default rclone hides OneNote files from directory listings, because operations like "Open" and "Update" just won't work on them. But plot twist: that same hiding behaviour might also stop you from **deleting** them. So if you wanna delete OneNote files, or just want them visible in listings for whatever reason, flip this on. 💅

  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.

  Lets server-side operations (like `copy`) work across *different* onedrive configs.

  This works if you're copying between two OneDrive Personal drives AND the files you're copying are already shared between them. It should also work 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 every other case, rclone just falls back to a normal copy — which, yeah, 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`** — the size of the listing chunk.

  Properties:

  - Config: `list_chunk`
  - Env Var: `RCLONE_ONEDRIVE_LIST_CHUNK`
  - Type: int
  - Default: `1000`

- **`--onedrive-no-versions`** — removes 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. And those versions? They eat up your quota, no cap. 💀

  This flag checks for versions after the file upload and after setting modification time, then removes everything except the last version.

  > NB: Onedrive personal can't currently delete versions, so do NOT use this flag there, bestie. Just don't. 🙈

  Properties:

  - Config: `no_versions`
  - Env Var: `RCLONE_ONEDRIVE_NO_VERSIONS`
  - Type: bool
  - Default: `false`

- **`--onedrive-hard-delete`** — permanently deletes files on removal.

  Normally files get sent to the recycle bin when deleted. Turning this flag on means they get **permanently deleted** instead. Use with care, this is not a vibe you can undo. 😭

  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`** — sets 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"`
      - anybody with the link can get in, no sign-in needed.
      - this may include people outside 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`** — sets 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`** — sets 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 picks the hash type in use. Set it to `"auto"` and it'll 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 you want an SHA1 hash then set this option accordingly, bestie.

  From July 2023, QuickXorHash will be the only available hash for both OneDrive for Business and OneDrive Personal.

  You can set this to `"none"` to not use any hashes at all.

  If the hash you requested doesn't exist on the object, it gets returned as an empty string, which rclone treats as a missing hash. Slay, technically. ✨

  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 you to download files the server thinks have 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 the download of the file.

  When that happens you'll 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 uses 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 these things up **greatly**:

rclone lsf -R onedrive: rclone size onedrive: rclone rc vfs/refresh recursive=true


BUT (and it's a big but) the delta listing API only works at the root of the drive. If you use it somewhere that isn't the root, then it recurses from the root and throws away all the data that isn't under the directory you asked for. So it'll still be *correct*, just maybe not very efficient. That's literally why this flag isn't the default.

Rule of thumb: if nearly all your data is under rclone's root directory (the `root/directory` in `onedrive:root/directory`), then this flag is a big performance win. If your data is mostly NOT under the root, then this flag is a big performance loss. 🎀

It's recommended if you're 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`** — controls whether permissions get 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 for more info, bestie.

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. Just a lil note to yourself, y'know? 💜

Properties:

- Config: `description`
- Env Var: `RCLONE_ONEDRIVE_DESCRIPTION`
- Type: string
- Required: false

## ✨ Metadata ✨

okay bestie, sit down, we're talking metadata 💅

OneDrive supports <pink>System Metadata</pink> (and **not** User Metadata, as of this writing, sorry babes 😭) for **both files and directories**. And listen — <yellow>a lot of that metadata is read-only</yellow>, and there are some differences between OneDrive Personal and OneDrive Business (the table below has the deets 👇).

Permissions are also supported, **if** `--onedrive-metadata-permissions` is set. The accepted values for `--onedrive-metadata-permissions` are `"read"`, `"write"`, `"read,write"`, and `"off"` — which, btw, is the default. So by default you get none of this, it's giving "opt in or go home" 🚪

`"write"` supports adding new permissions, updating the `"role"` of existing permissions, and removing permissions. <red>BUT</red> — updating and removing both require the Permission ID to be known, so if you wanna update/remove permissions it is **recommended** to use `"read,write"` instead of just `"write"`. iykyk 🔑

Permissions are read and written in JSON format using the same schema as the OneDrive API, which differs slightly between OneDrive Personal and Business. Two different flavors, two different vibes, same energy 🍓

Example for OneDrive Personal:

[ { "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:

[ { "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. And ngl, the `--metadata-mapper` tool can be <rainbow>very helpful</rainbow> 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`:

{ "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. not me finding out the hard way 💀

To update an existing permission, include **both** the Permission ID **and** the new roles to be assigned. And heads up: `roles` is the *only* property that can be changed. one job, and it's roles 🎯

To remove permissions, pass in a blob containing only the permissions you wish to keep (which can be empty, to remove all of them — scorched earth era 🔥). Note that the `owner` role will be **ignored**, because it cannot be removed. owner stays, end of story 👑

Also, note that both reading **and** writing permissions require extra API calls, so if you don't need to read or write permissions it is recommended to just omit `--onedrive-metadata-permissions`. save your API calls bestie, they're precious ✨

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**. just a lil Business tax 🧚

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 <pink>ignored</pink>. it's giving "if I don't know you, you're not coming in" 🙈

> **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.

---
<purple>main character metadata behaviour, no cap 💜</purple>

- **`btime`** — when the file was *born* (i.e. created) 🐣, measured with `S` accuracy (`mS` if you're on OneDrive Personal). Type: `RFC 3339`. Example: `2006-01-02T15:04:05Z`. Read only? `N`.
- **`content-type`** — the MIME type of the file 💅. Type: `string`. Example: `text/plain`. Read only? `Y`.
- **`created-by-display-name`** — the display name of whoever created this item 🫶. Type: `string`. Example: `John Doe`. Read only? `Y`.
- **`created-by-id`** — the ID of whoever created this item ✨. Type: `string`. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read only? `Y`.
- **`description`** — a short description of the file 📝, max `1024` characters. Heads up bestie: this one is **only supported for OneDrive Personal**. Type: `string`. Example: `Contract for signing`. Read only? `N`.
- **`id`** — the unique identifier of the item within OneDrive 🔑. Type: `string`. Example: `01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K`. Read only? `Y`.
- **`last-modified-by-display-name`** — the display name of whoever last touched this item 🙈. Type: `string`. Example: `John Doe`. Read only? `Y`.
- **`last-modified-by-id`** — the ID of whoever last modified this item 👀. Type: `string`. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read only? `Y`.
- **`malware-detected`** — whether OneDrive clocked that this item contains malware 💀. Type: `boolean`. Example: `true`. Read only? `Y`.
- **`mtime`** — time of last modification, with `S` accuracy (`mS` for OneDrive Personal). Type: `RFC 3339`. Example: `2006-01-02T15:04:05Z`. Read only? `N`.
- **`package-type`** — if it's present, it means this item is a *package* instead of a folder or a file 📦. Packages get treated like files in some contexts and like folders in others. Type: `string`. Example: `oneNote`. Read only? `Y`.
- **`permissions`** — permissions, dumped as a JSON blob of OneDrive format 🌈. Switch it on with `--onedrive-metadata-permissions`. Its properties are: `id`, `grantedTo`, `grantedToIdentities`, `invitation`, `inheritedFrom`, `link`, `roles`, `shareId`. Type: `JSON`. Example: `{}`. Read only? `N`.
- **`shared-by-id`** — the ID of the user who shared the item (if it's shared) 💌. Type: `string`. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read only? `Y`.
- **`shared-owner-id`** — the ID of the *owner* of the shared item (if shared) 👑. Type: `string`. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read only? `Y`.
- **`shared-scope`** — if it's shared, this tells you the scope of *how* it's shared: `anonymous`, `organization`, or `users` 🌍. Type: `string`. Example: `users`. Read only? `Y`.
- **`shared-time`** — the time when the item got shared, with `S` accuracy (`mS` for OneDrive Personal) 🕐. Type: `RFC 3339`. Example: `2006-01-02T15:04:05Z`. Read only? `Y`.
- **`utime`** — time of upload, with `S` accuracy (`mS` for OneDrive Personal) 📤. Type: `RFC 3339`. Example: `2006-01-02T15:04:05Z`. Read only? `Y`.

And if you want the whole lore, the metadata docs have it — go read those for more info 💖.

---

### ✨ Impersonate other users as Admin ✨

Okay so here's the tea ☕: unlike Google Drive where you can impersonate any domain user through service accounts, OneDrive makes you work for it. You have to authenticate as an admin account, and then set up a remote *manually* for every single user you wanna impersonate 😭.

1. In Microsoft 365 Admin Center, open each user you need to "impersonate" and go to the OneDrive section. There's a heading called "Get access to files" — you gotta click it to create the link. Doing that creates a link in the format

https://{tenant}-my.sharepoint.com/personal/{user_name_domain_tld}/


but it *also* changes the permissions so that you, the admin user, have access 👑

2. Then in powershell, run these commands:

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 drop the ID you got in the previous step into the `driveID` field 🚀. One remote per user, periodt. It'll confirm the drive ID, and hopefully hit you with a message like `Found drive "root" of type "business"` and then hand you the URL in 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 expires 😵. That means authorization problems, no cap. The fix is easy though — just run the `rclone config reconnect remote:` command to grab a new token and refresh token and you're back, slay ✨.

### 🔤 Naming 🔤

Not me having to tell you this, but OneDrive is case **insensitive**, so you literally cannot have one file called "Hello.doc" and another called "hello.doc" 🙅♀️.

There are quite a few characters that can't go in OneDrive file names. These can't occur on Windows platforms, but on non-Windows platforms they're, like, super common. So rclone maps these names to and from an identical-looking unicode equivalent 🪄. For example, if a file has a `?` in it, it gets 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) 🫠.

### 🛣️ Path length 🛣️

The entire path, file name included, has to contain fewer than `400` characters for OneDrive, OneDrive for Business and SharePoint Online. If you're encrypting file and folder names with rclone, pay attention here bestie 👀 — encrypted names are typically longer than the originals.

### 🔢 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` for more info.

There's an official document about the limitations for different types of OneDrive — it can be found here 📄.

### 🕰️ Versions 🕰️

Every change in a file makes OneDrive create a new *version* of that file 😭 — and that counts against a user's quota. For example, changing the modification time of a file creates a second version, so the file apparently uses twice the space. It's giving rent-free.

So the `copy` command is affected by this too, because 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. Careful though — this takes extra transactions, so only enable it if you actually 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 ✨

Okay bestie, listen. Starting <yellow>October 2018</yellow>, users <red>can't disable versioning by default</red> anymore 💀. That's not a rclone thing — <purple>Microsoft</purple> went and updated the mechanism. So to flip that new default, a <hotpink>SharePoint admin</hotpink> has to run a PowerShell command. If that's you (admin main character energy 👑), run these in PowerShell:

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` — swap *YOURSITE*, *YOU*, *YOURSITE.COM* for your actual values; this will prompt for your credentials

4. `Set-SPOTenant -EnableMinimumVersionRequirement $False`

5. `Disconnect-SPOService` — to disconnect from the server

And here's the glow-up for us normal users 💅. If you don't see the "No Versioning" option, double-check the requirements above are met, fr fr.

<pink>User Weropol</pink> 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 it will <green>not</green> 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 makes rclone look through <hotpink>every single file</hotpink> under the path you gave it and delete all versions but the current one. And because that means traversing all the files and then querying each file for versions, it can be kinda slow ngl 😭. Rclone does `--checkers` tests in parallel though. The command also supports `--interactive`/`-i` or `--dry-run` — which is a slay way to see what it *would* do first 👀.

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're getting excessive throttling or you're being blocked on SharePoint, 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 live in the Microsoft document: *Avoid getting throttled or blocked in SharePoint Online*.

#### Unexpected file size/hash differences on Sharepoint

It's a known issue that <yellow>Sharepoint</yellow> (not OneDrive or OneDrive for Business — read carefully bestie) <red>silently modifies uploaded files</red>, mainly Office files (`.docx`, `.xlsx`, etc.), which causes file size and hash checks to fail 💀. There are also other situations that make OneDrive report inconsistent file sizes. To use rclone with such affected files on Sharepoint, you may disable these checks with the following command line arguments:

--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 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's a known issue that <yellow>Sharepoint</yellow> (not OneDrive or OneDrive for Business) may return <red>"item not found" errors</red> 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:

--backup-dir mysharepoint:rclone-backup-dir


#### access_denied (AADSTS65005)

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 rclone <red>can't</red> use the OneDrive for Business API with your account 😭. You can't really 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)

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 <green>refreshing your OAuth refresh token</green>. 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 <red>"Invalid request"</red> 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`, `2`.

#### Can not access Shared with me files

`Shared with me files` is not supported by rclone currently, but there *is* a workaround 👀:

1. Visit `https://onedrive.live.com`

2. Right click a item in `Shared`, then click `Add shortcut to My files` in the context `[IMAGE: make_shortcut]`

3. The shortcut will appear in `My files`, you can access it with rclone, it behaves like a normal folder/file. `[IMAGE: in_my_files]` `[IMAGE: rclone_mount]`

#### Live Photos uploaded from iOS (small video clips in .heic files)

The iOS OneDrive app introduced upload and storage of Live Photos in <yellow>2020</yellow>. 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 the downloaded `.heic` file is <hotpink>smaller</hotpink> 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:

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:

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:

ERROR : 20230203_123826234_iOS.heic: ReadFileHandle.Read error: low level retry 1/10: unexpected EOF


or like this when using `--cache-mode=full`:

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:


# 🌸 OpenDrive 🌸

okay bestie so paths here go like `remote:path`

and they can be as deep as you need, like `remote:directory/subdirectory` — go feral, nest away 💅

## ✨ Configuration ✨

here's a lil example of how you'd make a remote called `remote`. First run:

rclone config


and it's gonna hold your hand through a whole interactive setup, like this:

n) New remote d) Delete remote q) Quit config e/n/d/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / OpenDrive \ "opendrive" [snip] Storage> opendrive Username username> Password y) Yes type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password: Configuration complete. Options:

type: opendrive
username:
password: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


wanna peep the top-level directories in your OpenDrive? say less:

rclone lsd remote:


wanna see, like, *every* file you've got in there? 👑

rclone ls remote:


and to yeet a local directory over to an OpenDrive directory called `backup`:

rclone copy /home/source remote:backup


## ⏰ Modification times and hashes ⏰

OpenDrive lets you set modification times on objects, and it's accurate down to 1 second. rclone uses those to clock whether objects actually need syncing or not. no cap.

MD5 hash algorithm? supported. ✅

## 🔒 Restricted filename characters 🔒

here's the whole vibe check on characters that are simply not invited to the party:

Character Value Replacement ──────────────────────────────── NUL 0x00 ␀ / 0x2F ／ ” 0x22 ＂

0x2A ＊ : 0x3A ： < 0x3C ＜

0x3E ＞

? 0x3F ？ \ 0x5C ＼

0x7C ｜


and heads up, file names also can't **begin or end** with these next ones. These only get replaced if they're the first or last character in the name:

Character Value Replacement ──────────────────────────────── SP 0x20 ␠ HT 0x09 ␉ LF 0x0A ␊ VT 0x0B ␋ CR 0x0D ␍


invalid UTF-8 bytes also get swapped out, because they literally can't be used in JSON strings. it's giving incompatible 💀

## 🎀 Standard options 🎀

these are the Standard options that are specific to `opendrive` (OpenDrive). ✨

### `--opendrive-username`

Username.

Properties:

- **Config:** `username`
- **Env Var:** `RCLONE_OPENDRIVE_USERNAME`
- **Type:** string
- **Required:** true

### `--opendrive-password`

Password.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- **Config:** `password`
- **Env Var:** `RCLONE_OPENDRIVE_PASSWORD`
- **Type:** string
- **Required:** true

## 🧚 Advanced options 🧚

and here are the Advanced options specific to `opendrive` (OpenDrive). yup, there's more 🫶

### `--opendrive-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_OPENDRIVE_ENCODING`
- **Type:** Encoding
- **Default:**

Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,LeftSpace,LeftCrLfHtVt,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot


### `--opendrive-chunk-size`

Files will be uploaded in chunks this size.

> Note that these chunks are buffered in memory so increasing them will increase memory use.

Properties:

- **Config:** `chunk_size`
- **Env Var:** `RCLONE_OPENDRIVE_CHUNK_SIZE`
- **Type:** SizeSuffix
- **Default:** 10Mi

### `--opendrive-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_OPENDRIVE_DESCRIPTION`
- **Type:** string
- **Required:** false

## 🚧 Limitations 🚧

so, real talk: OpenDrive is case insensitive, which means you cannot have one file called "Hello.doc" and another one called "hello.doc". pick a lane bestie 😭

also there are quite a few characters that can't be in OpenDrive 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. iconic behaviour honestly ✨

`rclone about` is not supported by the OpenDrive backend. Backends without this capability cannot determine free space for an rclone mount or use policy mfs (most free space) as a member of an rclone union remote.

See List of backends that do not support `rclone about` and `rclone about`

---

# 💜 Oracle Object Storage 💜

- Oracle Object Storage Overview
- Oracle Object Storage FAQ
- Oracle Object Storage Limits

Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`.

Sample command to transfer local artifacts to `remote:bucket` in oracle object storage:

rclone -vvv --progress --stats-one-line --max-stats-groups 10 --log-format date,time,UTC,longfile --fast-list --buffer-size 256Mi --oos-no-check-bucket --oos-upload-cutoff 10Mi --multi-thread-cutoff 16Mi --multi-thread-streams 3000 --transfers 3000 --checkers 64 --retries 2 --oos-chunk-size 10Mi --oos-upload-concurrency 10000 --oos-attempt-resume-upload --oos-leave-parts-on-error sync ./artifacts remote:bucket -vv


## 🦋 Configuration 🦋

Here is an example of making an oracle object storage configuration. `rclone config` walks you through it.

Here is an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

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

Enter name for new remote. name> remote

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Oracle Cloud Infrastructure Object Storage \ (oracleobjectstorage) Storage> oracleobjectstorage

Option provider. Choose your Auth Provider Choose a number from below, or type in your own string value. Press Enter for the default (env_auth). 1 / automatically pickup the credentials from runtime(env), first one to provide auth wins \ (env_auth) / use an OCI user and an API key for authentication. 2 | you’ll need to put in a config file your tenancy OCID, user OCID, region, the path, fingerprint to an API key.

https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm

\ (user_principal_auth) / use instance principals to authorize an instance to make API calls. 3 | each instance has its own identity, and authenticates using the certificates that are read from instance metadata.

https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm

\ (instance_principal_auth) / use workload identity to grant Kubernetes pods policy-driven access to Oracle Cloud 4 | Infrastructure (OCI) resources using OCI Identity and Access Management (IAM).

https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm

\ (workload_identity_auth) 5 / use resource principals to make API calls \ (resource_principal_auth) 6 / no credentials needed, this is typically for reading public buckets \ (no_auth) provider> 2

Option namespace. Object storage namespace Enter a value. namespace> idbamagbg734

Option compartment. Object storage compartment OCID Enter a value. compartment> ocid1.compartment.oc1..aaaaaaaapufkxc7ame3sthry5i7ujrwfc7ejnthhu6bhanm5oqfjpyasjkba

Option region. Object storage Region Enter a value. region> us-ashburn-1

Option endpoint. Endpoint for Object storage API. Leave blank to use the default endpoint for the region. Enter a value. Press Enter to leave empty. endpoint>

Option config_file. Full Path to OCI config file Choose a number from below, or type in your own string value. Press Enter for the default (~/.oci/config). 1 / oci configuration file location \ (~/.oci/config) config_file> /etc/oci/dev.conf

Option config_profile. Profile name inside OCI config file Choose a number from below, or type in your own string value. Press Enter for the default (Default). 1 / Use the default profile \ (Default) config_profile> Test

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: oracleobjectstorage
namespace: idbamagbg734
compartment: ocid1.compartment.oc1..aaaaaaaapufkxc7ame3sthry5i7ujrwfc7ejnthhu6bhanm5oqfjpyasjkba
region: us-ashburn-1
provider: user_principal_auth
config_file: /etc/oci/dev.conf
config_profile: Test Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


See all buckets 🌈

rclone lsd remote:


Create a new bucket ✨

rclone mkdir remote:bucket


List the contents of a bucket 👑

rclone ls remote:bucket rclone ls remote:bucket --max-depth 1


## 🔐 Authentication Providers 🔐

OCI has various authentication methods. To learn more about authentication methods please refer oci authentication methods. These choices can be specified in the rclone config file.

Rclone supports the following OCI authentication provider.

User Principal Instance Principal Resource Principal Workload Identity No authentication


## 💅 User Principal 💅

Sample rclone config file for Authentication Provider User Principal:

[oos] type = oracleobjectstorage namespace = id<redacted>34 compartment = ocid1.compartment.oc1..aa<redacted>ba region = us-ashburn-1 provider = user_principal_auth config_file = /home/opc/.oci/config config_profile = Default


**Advantages:** bestie, you can use this method from <pink>any server</pink> within OCI or on-premises or from other cloud provider. Literally anywhere. ✨

**Considerations:** okay so, real talk:

- you need to configure user’s privileges / policy to allow access to object storage
- Overhead of managing users and keys.
- If the user is deleted, the config file will no longer work and may cause automation regressions that use the user’s credentials. <red>not a vibe. dead the user, dead the automation.</red> 💀

---

### 🦋 Instance Principal

An OCI compute instance can be authorized to use rclone by using it’s identity and certificates as an instance principal. With this approach <green>no credentials have to be stored and managed</green> — which is the whole dream, honestly. no key files rotting in a repo somewhere. iconic.

Sample rclone configuration file for Authentication Provider Instance Principal:

[opc@rclone ~]$ cat ~/.config/rclone/rclone.conf [oos] type = oracleobjectstorage namespace = id<redacted>fn compartment = ocid1.compartment.oc1..aa<redacted>k7a region = us-ashburn-1 provider = instance_principal_auth


**Advantages:**

- With instance principals, you don’t need to configure user credentials and transfer/ save it to disk in your compute instances or rotate the credentials.
- You don’t need to deal with users and keys.
- Greatly helps in automation as you don’t have to manage access keys, user private keys, storing them in vault, using kms etc.

**Considerations:**

- You need to configure a dynamic group having this instance as member and add policy to read object storage to that dynamic group.
- Everyone who has access to this machine can execute the CLI commands. <yellow>👀 everybody on the box, bestie. the whole group chat.</yellow>
- It is applicable for oci compute instances only. It cannot be used on external instance or resources. <red>periodt, compute instances ONLY.</red>

---

### 🌸 Resource Principal

Resource principal auth is *very similar* to instance principal auth but used for resources that are <purple>not</purple> compute instances such as serverless functions. To use resource principal ensure Rclone process is started with these environment variables set in its process.

export OCI_RESOURCE_PRINCIPAL_VERSION=2.2 export OCI_RESOURCE_PRINCIPAL_REGION=us-ashburn-1 export OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/usr/share/model-server/key.pem export OCI_RESOURCE_PRINCIPAL_RPST=/usr/share/model-server/security_token


Sample rclone configuration file for Authentication Provider Resource Principal:

[oos] type = oracleobjectstorage namespace = id<redacted>34 compartment = ocid1.compartment.oc1..aa<redacted>ba region = us-ashburn-1 provider = resource_principal_auth


---

### 🧚 Workload Identity

Workload Identity auth may be used when running Rclone from Kubernetes pod on a Container Engine for Kubernetes (OKE) cluster. For more details on configuring Workload Identity, see Granting Workloads Access to OCI Resources. To use workload identity, ensure Rclone is started with these environment variables set in its process.

export OCI_RESOURCE_PRINCIPAL_VERSION=2.2 export OCI_RESOURCE_PRINCIPAL_REGION=us-ashburn-1


---

### 🌈 No authentication

Public buckets do not require any authentication mechanism to read objects. <green>the freest of the free. no keys, no config file nonsense, just vibes.</green> Sample rclone configuration file for No authentication:

[oos] type = oracleobjectstorage namespace = id<redacted>34 compartment = ocid1.compartment.oc1..aa<redacted>ba region = us-ashburn-1 provider = no_auth


---

### ⏰ Modification times and hashes

The modification time is stored as <pink>metadata</pink> on the object as `opc-meta-mtime` as floating point since the epoch, accurate to 1 ns. yeah, nanosecond precision, she's precise 💅

If the modification time needs to be updated rclone will attempt to perform a server side copy to update the modification if the object can be copied in a single part. In the case the object is larger than 5Gb, the object will be uploaded rather than copied.

> Note that reading this from the object takes an additional `HEAD` request as the metadata isn’t returned in object listings. so every read is a lil extra expensive, iykyk.

The `MD5` hash algorithm is supported.

---

### 🫶 Multipart uploads

rclone supports multipart uploads with OOS which means that it can upload files bigger than 5 GiB. big files? handled. no cap. 🔥

> Note that files uploaded both with multipart upload and through crypt remotes do not have MD5 sums.

rclone switches from single part uploads to multipart uploads at the point specified by `--oos-upload-cutoff`. This can be a maximum of 5 GiB and a minimum of 0 (ie always upload multipart files).

The chunk sizes used in the multipart upload are specified by `--oos-chunk-size` and the number of chunks uploaded concurrently is specified by `--oos-upload-concurrency`.

Multipart uploads will use `--transfers * --oos-upload-concurrency * --oos-chunk-size` extra memory. Single part uploads to not use extra memory. <yellow>so like, that's your RAM math right there, bestie. do the multiplication before you go feral with the flags.</yellow>

Single part transfers can be faster than multipart transfers or slower depending on your latency from oos - the more latency, the more likely single part transfers will be faster.

Increasing `--oos-upload-concurrency` will increase throughput (8 would be a sensible value) and increasing `--oos-chunk-size` also increases throughput (16M would be sensible). Increasing either of these will use more memory. The default values are high enough to gain most of the possible performance without using too much memory. <cyan>tl;dr: defaults already ate. only crank these if you know what you're doing.</cyan>

---

### ✨ Standard options ✨

Here are the Standard options specific to oracleobjectstorage (Oracle Cloud Infrastructure Object Storage).

#### 🎀 `--oos-provider`

Choose your Auth Provider — pick your fighter, bestie.

**Properties:**

- Config: `provider`
- Env Var: `RCLONE_OOS_PROVIDER`
- Type: string
- Default: “env_auth”
- Examples:
  - `env_auth`
    - automatically pickup the credentials from runtime(env), first one to provide auth wins
  - `user_principal_auth`
    - use an OCI user and an API key for authentication.
    - you’ll need to put in a config file your tenancy OCID, user OCID, region, the path, fingerprint to an API key.
    - `https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm`
  - `instance_principal_auth`
    - use instance principals to authorize an instance to make API calls.
    - each instance has its own identity, and authenticates using the certificates that are read from instance metadata.
    - `https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm`
  - `workload_identity_auth`
    - use workload identity to grant OCI Container Engine for Kubernetes workloads policy-driven access to OCI resources using OCI Identity and Access Management (IAM).
    - `https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm`
  - `resource_principal_auth`
    - use resource principals to make API calls
  - `no_auth`
    - no credentials needed, this is typically for reading public buckets

#### 🍓 `--oos-namespace`

Object storage namespace. you gotta have it, fr fr.

**Properties:**

- Config: `namespace`
- Env Var: `RCLONE_OOS_NAMESPACE`
- Type: string
- Required: true

#### 💜 `--oos-compartment`

Specify compartment OCID, if you need to list buckets.

List objects works without compartment OCID.

**Properties:**

- Config: `compartment`
- Env Var: `RCLONE_OOS_COMPARTMENT`
- Provider: `!no_auth`
- Type: string
- Required: false

#### 🌸 `--oos-region`

Object storage Region. where in the world is the bucket, basically.

**Properties:**

- Config: `region`
- Env Var: `RCLONE_OOS_REGION`
- Type: string
- Required: true

#### ⭐ `--oos-endpoint`

Endpoint for Object storage API.

Leave blank to use the default endpoint for the region.

**Properties:**

- Config: `endpoint`
- Env Var: `RCLONE_OOS_ENDPOINT`
- Type: string
- Required: false

#### 🎀 `--oos-config-file`

Path to OCI config file.

**Properties:**

- Config: `config_file`
- Env Var: `RCLONE_OOS_CONFIG_FILE`
- Provider: `user_principal_auth`
- Type: string
- Default: “~/.oci/config”
- Examples:
  - `~/.oci/config`
    - oci configuration file location

#### 💅 `--oos-config-profile`

Profile name inside the oci config file.

**Properties:**

- Config: `config_profile`
- Env Var: `RCLONE_OOS_CONFIG_PROFILE`
- Provider: `user_principal_auth`
- Type: string
- Default: “Default”
- Examples:
  - `Default`
    - Use the default profile

---

### 🔥 Advanced options 🔥

Here are the Advanced options specific to oracleobjectstorage (Oracle Cloud Infrastructure Object Storage).

#### 👑 `--oos-storage-tier`

The storage class to use when storing new objects in storage. `https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/understandingstoragetiers.htm`

**Properties:**

- Config: `storage_tier`
- Env Var: `RCLONE_OOS_STORAGE_TIER`
- Type: string
- Default: “Standard”
- Examples:
  - `Standard`
    - Standard storage tier, this is the default tier
  - `InfrequentAccess`
    - InfrequentAccess storage tier
  - `Archive`
    - Archive storage tier

#### 🦋 `--oos-upload-cutoff`

Cutoff for switching to chunked upload.

Any files larger than this will be uploaded in chunks of chunk_size. The minimum is 0 and the maximum is 5 GiB.

**Properties:**

- Config: `upload_cutoff`
- Env Var: `RCLONE_OOS_UPLOAD_CUTOFF`
- Type: SizeSuffix
- Default: `200Mi`

#### 🌈 `--oos-chunk-size`

Chunk size to use for uploading.

When uploading files larger than upload_cutoff or files with unknown size (e.g. from “rclone rcat” or uploaded with “rclone mount” they will be uploaded as multipart uploads using this chunk size.

Note that “upload_concurrency” chunks of this size are buffered in memory per transfer.

If you are transferring large files over high-speed links and you have enough memory, then increasing this will speed up the transfers.

Rclone will automatically increase the chunk size when uploading a large file of known size to stay below the 10,000 chunks limit.

Files of unknown size are uploaded with the configured chunk_size. Since the default chunk size is 5 MiB and there can be at most 10,000 chunks, this means that by default the maximum size of a file you can stream upload is 48 GiB. If you wish to stream upload larger files then you will need to increase chunk_size.

Increasing the chunk size decreases the accuracy of the progress statistics displayed with “-P” flag.

**Properties:**

- Config: `chunk_size`

- **Env Var**: `RCLONE_OOS_CHUNK_SIZE`

- **Type**: SizeSuffix

- **Default**: `5Mi`

---

### `--oos-max-upload-parts` 💅

Max number of parts you can smash into one multipart upload, bestie. This is the ceiling on how many multipart chunks rclone will use when it does a multipart upload.

OCI is like "no more than 10,000 chunks, I don't make the rules" — that's the hard limit. So when you're uploading a big file and rclone *knows* how big it is, it will automatically bump the chunk size up to keep you under that number of chunks. Iconic adaptive behaviour tbh.

**Properties:**

- **Config**: `max_upload_parts`

- **Env Var**: `RCLONE_OOS_MAX_UPLOAD_PARTS`

- **Type**: int

- **Default**: `10000`

---

### `--oos-upload-concurrency` 🔥

Concurrency for multipart uploads, aka how many chunks of the *same file* get uploaded at the same time.

So like, if you're uploading a small number of big files over a super fast link and your bandwidth is just sitting there, not being fully used?? Cranking this up might help speed up the transfers. Main character move.

**Properties:**

- **Config**: `upload_concurrency`

- **Env Var**: `RCLONE_OOS_UPLOAD_CONCURRENCY`

- **Type**: int

- **Default**: `10`

---

### `--oos-copy-cutoff` ✨

Cutoff for switching to multipart copy.

Any file bigger than this that needs to be server-side copied will get copied in chunks of this size instead.

The minimum is `0` and the maximum is `5 GiB`. Respect the range.

**Properties:**

- **Config**: `copy_cutoff`

- **Env Var**: `RCLONE_OOS_COPY_CUTOFF`

- **Type**: SizeSuffix

- **Default**: `4.656Gi`

---

### `--oos-copy-timeout` ⏳

Timeout for copy, bestie.

Copy is an *asynchronous* operation — it's giving "I'll get to it" — so you specify a timeout to wait for the copy to actually succeed.

**Properties:**

- **Config**: `copy_timeout`

- **Env Var**: `RCLONE_OOS_COPY_TIMEOUT`

- **Type**: Duration

- **Default**: `1m0s`

---

### `--oos-disable-checksum` 💀

"Don't store MD5 checksum with object metadata." Not me telling you to turn off integrity checks.

Normally rclone will calculate the MD5 checksum of the input *before* uploading it, so it can slap it into the metadata on the object. Which is amazing for data integrity checking, genuinely. But it can also cause long delays before large files even *start* uploading. So like, tradeoff.

**Properties:**

- **Config**: `disable_checksum`

- **Env Var**: `RCLONE_OOS_DISABLE_CHECKSUM`

- **Type**: bool

- **Default**: `false`

---

### `--oos-encoding` 🦋

The encoding for the backend.

See the encoding section in the overview for more info — that's where the tea is.

**Properties:**

- **Config**: `encoding`

- **Env Var**: `RCLONE_OOS_ENCODING`

- **Type**: Encoding

- **Default**: `Slash,InvalidUtf8,Dot`

---

### `--oos-leave-parts-on-error` 🫶

If true, avoid calling abort upload on a failure, leaving all the successfully uploaded parts around for manual recovery.

Set it to `true` if you wanna resume uploads across different sessions. That's the whole point.

> **WARNING**: Storing parts of an incomplete multipart upload counts towards space usage on object storage and will add additional costs if not cleaned up. So like... it's not free, bestie. Clean up after yourself. 🔥

**Properties:**

- **Config**: `leave_parts_on_error`

- **Env Var**: `RCLONE_OOS_LEAVE_PARTS_ON_ERROR`

- **Type**: bool

- **Default**: `false`

---

### `--oos-attempt-resume-upload` 😭

If true, attempt to resume a previously started multipart upload for the object. Super helpful for speeding up multipart transfers, because you're resuming uploads from a past session instead of starting from zero. The glow-up.

> **WARNING**: If the chunk size in the resumed session differs from the past incomplete session, then the resumed multipart upload is **aborted** and a brand new multipart upload is started with the new chunk size. No cap.

The flag `leave_parts_on_error` must be `true` to resume and to optimize/skip the parts that were already uploaded successfully.

**Properties:**

- **Config**: `attempt_resume_upload`

- **Env Var**: `RCLONE_OOS_ATTEMPT_RESUME_UPLOAD`

- **Type**: bool

- **Default**: `false`

---

### `--oos-no-check-bucket` 🌸

If set, don't even *attempt* to check the bucket exists or create it.

This is useful when you're trying to minimise the number of transactions rclone does, and you already know the bucket exists. Trust.

It can also be needed if the user you're using straight up does not have bucket creation permissions. Yeah.

**Properties:**

- **Config**: `no_check_bucket`

- **Env Var**: `RCLONE_OOS_NO_CHECK_BUCKET`

- **Type**: bool

- **Default**: `false`

---

### `--oos-sse-customer-key-file` 🔐

To use SSE-C, a file containing the base64-encoded string of the AES-256 encryption key associated with the object. Please note only one of `sse_customer_key_file|sse_customer_key|sse_kms_key_id` is needed.'

**Properties:**

- **Config**: `sse_customer_key_file`

- **Env Var**: `RCLONE_OOS_SSE_CUSTOMER_KEY_FILE`

- **Type**: string

- **Required**: false

- **Examples:**

  - `""`
    - None

---

### `--oos-sse-customer-key` 💜

To use SSE-C, the optional header that specifies the base64-encoded 256-bit encryption key to use to encrypt or decrypt the data. Please note only one of `sse_customer_key_file|sse_customer_key|sse_kms_key_id` is needed. For more info, see Using Your Own Keys for Server-Side Encryption (`https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm`)

**Properties:**

- **Config**: `sse_customer_key`

- **Env Var**: `RCLONE_OOS_SSE_CUSTOMER_KEY`

- **Type**: string

- **Required**: false

- **Examples:**

  - `""`
    - None

---

### `--oos-sse-customer-key-sha256` 🎀

If you're using SSE-C, the optional header that specifies the base64-encoded SHA256 hash of the encryption key. This value is used to check the integrity of the encryption key. See Using Your Own Keys for Server-Side Encryption (`https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm`).

**Properties:**

- **Config**: `sse_customer_key_sha256`

- **Env Var**: `RCLONE_OOS_SSE_CUSTOMER_KEY_SHA256`

- **Type**: string

- **Required**: false

- **Examples:**

  - `""`
    - None

---

### `--oos-sse-kms-key-id` 👑

If you're using your own master key in vault, this header specifies the OCID (`https://docs.cloud.oracle.com/Content/General/Concepts/identifiers.htm`) of a master encryption key, which gets used to call the Key Management service to generate a data encryption key, or to encrypt/decrypt a data encryption key. Please note only one of `sse_customer_key_file|sse_customer_key|sse_kms_key_id` is needed.

**Properties:**

- **Config**: `sse_kms_key_id`

- **Env Var**: `RCLONE_OOS_SSE_KMS_KEY_ID`

- **Type**: string

- **Required**: false

- **Examples:**

  - `""`
    - None

---

### `--oos-sse-customer-algorithm` 🌈

If you're using SSE-C, the optional header that specifies `"AES256"` as the encryption algorithm. Object Storage supports `"AES256"` as the encryption algorithm. For more info, see Using Your Own Keys for Server-Side Encryption (`https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm`).

**Properties:**

- **Config**: `sse_customer_algorithm`

- **Env Var**: `RCLONE_OOS_SSE_CUSTOMER_ALGORITHM`

- **Type**: string

- **Required**: false

- **Examples:**

  - `""`
    - None

  - `"AES256"`
    - AES256

---

### `--oos-description` ⭐

Description of the remote. Just a lil note-to-self about which remote this even is.

**Properties:**

- **Config**: `description`

- **Env Var**: `RCLONE_OOS_DESCRIPTION`

- **Type**: string

- **Required**: false

---

## 🧚 Backend commands 🧚

Here are the commands specific to the `oracleobjectstorage` backend. They're the special little extras this backend gets.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments. These can be run on a running backend using the rc command `backend/command`.

---

### rename 🔄

change the name of an object

rclone backend rename remote: [options] [<arguments>+]


This command can be used to rename a object.

Usage Examples:

rclone backend rename oos:bucket relative-object-path-under-bucket object-new-name


---

### list-multipart-uploads 📋

List the unfinished multipart uploads

rclone backend list-multipart-uploads remote: [options] [<arguments>+]


This command lists the unfinished multipart uploads in JSON format.

rclone backend list-multipart-uploads oos:bucket/path/to/object


It returns a dictionary of buckets with values as lists of unfinished multipart uploads.

You can call it with no bucket, in which case it lists all buckets; with a bucket; or with a bucket and a path.

{ "test-bucket": [ { "namespace": "test-namespace", "bucket": "test-bucket", "object": "600m.bin", "uploadId": "51dd8114-52a4-b2f2-c42f-5291f05eb3c8", "timeCreated": "2022-07-29T06:21:16.595Z", "storageTier": "Standard" } ]


---

### cleanup 🧹

Remove unfinished multipart uploads.

rclone backend cleanup remote: [options] [<arguments>+]


This command removes unfinished multipart uploads of age greater than `max-age`, which defaults to `24 hours`.

Note that you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do. Always vibe check before you delete, bestie.

rclone backend cleanup oos:bucket/path/to/object rclone backend cleanup -o max-age=7w oos:bucket/path/to/object


Durations are parsed as per the rest of rclone: `2h`, `7d`, `7w`, etc.

**Options:**

- `"max-age"`: Max age of upload to delete

---

### restore 🏛️

Restore objects from Archive to Standard storage

rclone backend restore remote: [options] [<arguments>+]


This command can be used to restore one or more objects from Archive to Standard storage.

Usage Examples:

rclone backend restore oos:bucket/path/to/directory -o hours=HOURS rclone backend restore oos:bucket -o hours=HOURS


This flag also obeys the filters. Test first with `--interactive`/`-i` or `--dry-run` flags

rclone --interactive backend restore --include "*.txt" oos:bucket/path -o hours=72


All the objects shown will be marked for restore, then

rclone backend restore --include "*.txt" oos:bucket/path -o hours=72

It returns a list of status dictionaries with Object Name and Status keys. The Status will be "RESTORED"" if it was successful or an error message if not.

[ { "Object": "test.txt" "Status": "RESTORED", }, { "Object": "test/file4.txt" "Status": "RESTORED", } ]


**Options:**

- `"hours"`: The number of hours for which this object will be restored. Default is `24` hrs.

---

## 📚 Tutorials 📚

### 🗂️ Mounting Buckets 🗂️

## 🌸 QingStor 🌸

oki bestie so paths here work like `remote:bucket` — and yes, just `remote:` on its own is valid too, but only for the `lsd` command 💅. You can also go full nesting-mode and drop subdirectories in there like `remote:bucket/path/to/dir`. Slay.

### ✨ Configuration ✨

Here's a lil example of setting up a QingStor remote, fr. First you run

rclone config


...and the interactive setup process walks you through the rest, like this:

No remotes found, make a new one? n) New remote r) Rename remote c) Copy remote s) Set configuration password q) Quit config n/r/c/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / QingStor Object Storage \ "qingstor" [snip] Storage> qingstor Get QingStor credentials from runtime. Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter QingStor credentials in the next step \ "false" 2 / Get QingStor credentials from the environment (env vars or IAM) \ "true" env_auth> 1 QingStor Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> access_key QingStor Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> secret_key Enter an endpoint URL to connection QingStor API. Leave blank will use the default value "https://qingstor.com:443" endpoint> Zone connect to. Default is "pek3a". Choose a number from below, or type in your own value / The Beijing (China) Three Zone 1 | Needs location constraint pek3a. \ "pek3a" / The Shanghai (China) First Zone 2 | Needs location constraint sh1a. \ "sh1a" zone> 1 Number of connection retry. Leave blank will use the default value "3". connection_retries> Remote config Configuration complete. Options:

type: qingstor
env_auth: false
access_key_id: access_key
secret_access_key: secret_key
endpoint:
zone: pek3a
connection_retries: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


So this remote is called `remote` and now you can use it like the main character she is 💖

See all your buckets:

rclone lsd remote:


Make a brand new bucket:

rclone mkdir remote:bucket


List what's inside a bucket:

rclone ls remote:bucket


Sync `/home/local/directory` up to the remote bucket, deleting any extra files in the bucket:

rclone sync --interactive /home/local/directory remote:bucket


---

### 🌈 --fast-list 🌈

Bestie this remote supports `--fast-list`, which means fewer transactions in exchange for more memory. Obsessed. The rclone docs have the whole deep-dive if you want it.

### 🎀 Multipart uploads 🎀

rclone does multipart uploads with QingStor, which means it can yeet files bigger than 5 GiB up there 🔥. Small heads-up though: files uploaded via multipart don't have an MD5SUM.

Also! Incomplete multipart uploads older than 24 hours can be removed with `rclone cleanup remote:bucket` for just one bucket, or `rclone cleanup remote:` for all the buckets. QingStor does **not** ever remove incomplete multipart uploads on its own, so you may need to run this from time to time. Not me letting my bucket collection get haunted 🙈

### 🦋 Buckets and Zone 🦋

With QingStor you can list buckets (`rclone lsd`) using **any** zone, but you can only access the content of a bucket from the zone it was created in. If you attempt to access a bucket from the wrong zone, you'll get an error:

`incorrect zone, the bucket is not in 'XXX' zone`.

Vibe check failed, respectfully 💀

### 🔐 Authentication 🔐

There are two ways to supply rclone with a set of QingStor credentials. In order of precedence:

- Directly in the rclone configuration file (as configured by `rclone config`)
  - set `access_key_id` and `secret_access_key`
- Runtime configuration:
  - set `env_auth` to `true` in the config file
  - Exporting the following environment variables before running rclone
    - Access Key ID: `QS_ACCESS_KEY_ID` or `QS_ACCESS_KEY`
    - Secret Access Key: `QS_SECRET_ACCESS_KEY` or `QS_SECRET_KEY`

### 💅 Restricted filename characters 💅

The control characters `0x00-0x1F` and `/` are replaced as in the default restricted characters set. Note that `0x7F` is **not** replaced, bestie, she stays as she is.

Invalid UTF-8 bytes will also be replaced, because they literally cannot be used in JSON strings.

---

## ⭐ Standard options ⭐

Here are the Standard options specific to `qingstor` (QingCloud Object Storage).

### `--qingstor-env-auth`

Get QingStor credentials from runtime.

Only applies if `access_key_id` and `secret_access_key` is blank.

Properties:

- Config: `env_auth`
- Env Var: `RCLONE_QINGSTOR_ENV_AUTH`
- Type: bool
- Default: false
- Examples:
  - "false"
    - Enter QingStor credentials in the next step.
  - "true"
    - Get QingStor credentials from the environment (env vars or IAM).

### `--qingstor-access-key-id`

QingStor Access Key ID.

Leave blank for anonymous access or runtime credentials.

Properties:

- Config: `access_key_id`
- Env Var: `RCLONE_QINGSTOR_ACCESS_KEY_ID`
- Type: string
- Required: false

### `--qingstor-secret-access-key`

QingStor Secret Access Key (password).

Leave blank for anonymous access or runtime credentials.

Properties:

- Config: `secret_access_key`
- Env Var: `RCLONE_QINGSTOR_SECRET_ACCESS_KEY`
- Type: string
- Required: false

### `--qingstor-endpoint`

Enter an endpoint URL to connection QingStor API.

Leave blank will use the default value `https://qingstor.com:443`.

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_QINGSTOR_ENDPOINT`
- Type: string
- Required: false

### `--qingstor-zone`

Zone to connect to.

Default is `pek3a`.

Properties:

- Config: `zone`
- Env Var: `RCLONE_QINGSTOR_ZONE`
- Type: string
- Required: false
- Examples:
  - "pek3a"
    - The Beijing (China) Three Zone.
    - Needs location constraint pek3a.
  - "sh1a"
    - The Shanghai (China) First Zone.
    - Needs location constraint sh1a.
  - "gd2a"
    - The Guangdong (China) Second Zone.
    - Needs location constraint gd2a.

---

## 👑 Advanced options 👑

Here are the Advanced options specific to `qingstor` (QingCloud Object Storage).

### `--qingstor-connection-retries`

Number of connection retries.

Properties:

- Config: `connection_retries`
- Env Var: `RCLONE_QINGSTOR_CONNECTION_RETRIES`
- Type: int
- Default: 3

### `--qingstor-upload-cutoff`

Cutoff for switching to chunked upload.

Any files larger than this will be uploaded in chunks of `chunk_size`. The minimum is 0 and the maximum is 5 GiB.

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_QINGSTOR_UPLOAD_CUTOFF`
- Type: SizeSuffix
- Default: 200Mi

### `--qingstor-chunk-size`

Chunk size to use for uploading.

When uploading files larger than `upload_cutoff` they will be uploaded as multipart uploads using this chunk size.

Note that `--qingstor-upload-concurrency` chunks of this size are buffered in memory per transfer.

If you are transferring large files over high-speed links and you have enough memory, then increasing this will speed up the transfers.

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_QINGSTOR_CHUNK_SIZE`
- Type: SizeSuffix
- Default: 4Mi

### `--qingstor-upload-concurrency`

Concurrency for multipart uploads.

This is the number of chunks of the same file that are uploaded concurrently.

> NB if you set this to > 1 then the checksums of multipart uploads become corrupted (the uploads themselves are not corrupted though). 🚨

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_QINGSTOR_UPLOAD_CONCURRENCY`
- Type: int
- Default: 1

### `--qingstor-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_QINGSTOR_ENCODING`
- Type: Encoding
- Default: Slash,Ctl,InvalidUtf8

### `--qingstor-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_QINGSTOR_DESCRIPTION`
- Type: string
- Required: false

---

### 💀 Limitations 💀

`rclone about` is **not** supported by the `qingstor` backend. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote. Sad but true, bestie 😭

See List of backends that do not support rclone about and rclone about.

## ✨ Quatrix ✨

<pink>Quatrix by Maytech</pink> is literally *Quatrix Secure Compliant File Sharing | Maytech*. That's the whole vibe 💖

Paths go like this: `remote:path`

And bestie, they can be as deep as you need, like `remote:directory/subdirectory` — go off, make a whole directory tree, it's giving organization 🌸

The initial setup for Quatrix involves getting an API Key from Quatrix. You can get the API key in the user's profile at `https://<account>/profile/api-keys` or with the help of the API — `https://docs.maytech.net/quatrix/quatrix-api/api-explorer#/API-Key/post_api_key_create` 🔑

See complete Swagger documentation for Quatrix — `https://docs.maytech.net/quatrix/quatrix-api/api-explorer` 📚

---

### 🎀 Configuration 🎀

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Quatrix by Maytech \ "quatrix" [snip] Storage> quatrix API key for accessing Quatrix account. api_key> your_api_key Host name of Quatrix account. host> example.quatrix.it

Configuration complete. Options:

type: quatrix
api_key: your_api_key
host: example.quatrix.it Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can then use rclone like this, no cap 💅

List directories in top level of your Quatrix:

rclone lsd remote:


List all the files in your Quatrix:

rclone ls remote:


To copy a local directory to an Quatrix directory called `backup`:

rclone copy /home/source remote:backup


---

### 🔑 API key validity 🔑

The API Key is created with <hotpink>no expiration date</hotpink>. It will be valid until you delete or deactivate it in your account. After disabling, the API Key can be enabled back. If the API Key was deleted and a new key was created, you can update it in rclone config. The same happens if the hostname was changed. So like, nothing is forever and that's okay bestie 🦋

$ rclone config Current remotes:

Name Type ==== ==== remote quatrix

type: quatrix
host: some_host.quatrix.it
api_key: your_api_key Keep this "remote" remote? Edit remote Option api_key. API key for accessing Quatrix account Enter a string value. Press Enter for the default (your_api_key) api_key> Option host. Host name of Quatrix account Enter a string value. Press Enter for the default (some_host.quatrix.it).

Configuration complete. Options:

type: quatrix
host: some_host.quatrix.it
api_key: your_api_key Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


---

### ⏰ Modification times and hashes ⏰

Quatrix allows modification times to be set on objects accurate to <cyan>1 microsecond</cyan>. These will be used to detect whether objects need syncing or not. Iconic precision honestly ✨

Quatrix <red>does not support hashes</red>, so you <red>cannot</red> use the `--checksum` flag. Yeah bestie, that flag is not invited to this party 💀

---

### 🚫 Restricted filename characters 🚫

File names in Quatrix are case sensitive and have limitations like the maximum length of a filename is `255`, and the minimum length is `1`. A file name <red>cannot</red> be equal to `.` or `..` nor contain `/`, `\` or non-printable ascii. Respect the boundaries, periodt 🙈

---

### 📦 Transfers 📦

For files above `50 MiB` rclone will use a chunked transfer. Rclone will upload up to `--transfers` chunks at the same time (shared among all multipart uploads). Chunks are buffered in memory, and the minimal chunk size is `10_000_000` bytes by default, and it can be changed in the advanced configuration, so increasing `--transfers` will increase the memory use. The chunk size has a maximum size limit, which is set to `100_000_000` bytes by default and can be changed in the advanced configuration. The size of the uploaded chunk will dynamically change depending on the upload speed. The total memory use equals the number of transfers multiplied by the minimal chunk size. In case there's free memory allocated for the upload (which equals the difference of `maximal_summary_chunk_size` and `minimal_chunk_size * transfers`), the chunk size may increase in case of high upload speed. As well as it can decrease in case of upload speed problems. If no free memory is available, all chunks will equal `minimal_chunk_size`. The way it's just doing maths on your RAM 😭 it's giving main character energy fr fr

---

### 🗑️ Deleting files 🗑️

Files you delete with rclone will end up in <purple>Trash</purple> and be stored there for `30 days`. Quatrix also provides an API to permanently delete files and an API to empty the Trash so that you can remove files permanently from your account. So like, your files get a lil 30 day situationship before it's really over 💔

---

### ⚙️ Standard options ⚙️

Here are the Standard options specific to `quatrix` (Quatrix by Maytech).

- **`--quatrix-api-key`** — API key for accessing Quatrix account

  - Config: `api_key`
  - Env Var: `RCLONE_QUATRIX_API_KEY`
  - Type: string
  - Required: true

- **`--quatrix-host`** — Host name of Quatrix account

  - Config: `host`
  - Env Var: `RCLONE_QUATRIX_HOST`
  - Type: string
  - Required: true

---

### 🛠️ Advanced options 🛠️

Here are the Advanced options specific to `quatrix` (Quatrix by Maytech).

- **`--quatrix-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  - Config: `encoding`
  - Env Var: `RCLONE_QUATRIX_ENCODING`
  - Type: Encoding
  - Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

- **`--quatrix-effective-upload-time`** — Wanted upload time for one chunk

  - Config: `effective_upload_time`
  - Env Var: `RCLONE_QUATRIX_EFFECTIVE_UPLOAD_TIME`
  - Type: string
  - Default: `"4s"`

- **`--quatrix-minimal-chunk-size`** — The minimal size for one chunk

  - Config: `minimal_chunk_size`
  - Env Var: `RCLONE_QUATRIX_MINIMAL_CHUNK_SIZE`
  - Type: SizeSuffix
  - Default: `9.537Mi`

- **`--quatrix-maximal-summary-chunk-size`** — The maximal summary for all chunks. It should <red>not</red> be less than `` `transfers'*`minimal_chunk_size' ``

  - Config: `maximal_summary_chunk_size`
  - Env Var: `RCLONE_QUATRIX_MAXIMAL_SUMMARY_CHUNK_SIZE`
  - Type: SizeSuffix
  - Default: `95.367Mi`

- **`--quatrix-hard-delete`** — Delete files permanently rather than putting them into the trash

  - Config: `hard_delete`
  - Env Var: `RCLONE_QUATRIX_HARD_DELETE`
  - Type: bool
  - Default: `false`

- **`--quatrix-skip-project-folders`** — Skip project folders in operations

  - Config: `skip_project_folders`
  - Env Var: `RCLONE_QUATRIX_SKIP_PROJECT_FOLDERS`
  - Type: bool
  - Default: `false`

- **`--quatrix-description`** — Description of the remote.

  - Config: `description`
  - Env Var: `RCLONE_QUATRIX_DESCRIPTION`
  - Type: string
  - Required: false

---

### 💾 Storage usage 💾

The storage usage in Quatrix is restricted to the account during the purchase. You can restrict any user with a smaller storage limit. The account limit is applied if the user has no custom storage limit. Once you've reached the limit, the upload of files <red>will fail</red>. This can be fixed by freeing up the space or increasing the quota. The quota ate and left no crumbs, respectfully 👑

---

### 🔄 Server-side operations 🔄

Quatrix supports server-side operations (copy and move). In case of conflict, files are overwritten during server-side operation. Sneaky but efficient, slay 💅

# 🦋 Sia 🦋

okay so <pink>Sia</pink> (sia.tech) is a decentralized cloud storage platform based on the blockchain technology 💅 yes bestie, *the blockchain*, we're doing this. With rclone you can use it like literally any other remote filesystem, or mount Sia folders locally. The technology behind it involves a number of new concepts such as <cyan>Siacoins</cyan> and <cyan>Wallet</cyan>, <cyan>Blockchain</cyan> and <cyan>Consensus</cyan>, <cyan>Renting</cyan> and <cyan>Hosting</cyan>, and so on. If you are new to it, you'd better first familiarize yourself using their excellent support documentation. Fr fr, do the reading, it saves you a whole confusion arc. 🫶

---

## 🌸 Introduction 🌸

Before you can use rclone with Sia, you will need to have a running copy of `Sia-UI` or `siad` (the Sia daemon) locally on your computer or on local network (e.g. a NAS). Please follow the **Get started** guide and install one. No daemon, no vibes. ✨

rclone interacts with Sia network by talking to the Sia daemon via HTTP API which is usually available on port `9980`. By default you will run the daemon locally on the same computer so it's safe to leave the API password blank (the API URL will be `http://127.0.0.1:9980` making external access impossible). Lowkey the perfect setup, nothing leaves your machine. 🔒

However, if you want to access Sia daemon running on another node, for example due to memory constraints or because you want to share single daemon between several rclone and Sia-UI instances, you'll need to make a few more provisions:

- Ensure you have Sia daemon installed directly or in a docker container because Sia-UI does not support this mode natively.
- Run it on externally accessible port, for example provide `--api-addr :9980` and `--disable-api-security` arguments on the daemon command line.
- Enforce API password for the `siad` daemon via environment variable `SIA_API_PASSWORD` or text file named `apipassword` in the daemon directory.
- Set rclone backend option `api_password` taking it from above locations.

Notes, bestie, pls actually read these:

1. If your wallet is locked, rclone cannot unlock it automatically. You should either unlock it in advance by using Sia-UI or via command line `siac wallet unlock`. Alternatively you can make `siad` unlock your wallet automatically upon startup by running it with environment variable `SIA_WALLET_PASSWORD`.
2. If `siad` cannot find the `SIA_API_PASSWORD` variable or the `apipassword` file in the `SIA_DIR` directory, it will generate a random password and store in the text file named `apipassword` under `YOUR_HOME/.sia/` directory on Unix or `C:\Users\YOUR_HOME\AppData\Local\Sia\apipassword` on Windows. Remember this when you configure password in rclone — future you will be so grateful you clocked this. 💖
3. The only way to use `siad` without API password is to run it on localhost with command line argument `--authorize-api=false`, but this is insecure and strongly discouraged. Like, genuinely do not. 🙈

---

## ✨ Configuration ✨

Here is an example of how to make a sia remote called `mySia`. First, run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> mySia 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 ... 29 / Sia Decentralized Cloud \ "sia" ... Storage> sia Sia daemon API URL, like http://sia.daemon.host:9980. Note that siad must run with --disable-api-security to open API port for other hosts (not recommended). Keep default if Sia daemon runs on localhost. Enter a string value. Press Enter for the default ("http://127.0.0.1:9980"). api_url> http://127.0.0.1:9980 Sia Daemon API Password. Can be found in the apipassword file located in HOME/.sia/ or in the daemon directory. y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g/n> y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n> n

[mySia] type = sia api_url = http://127.0.0.1:9980 api_password = * ENCRYPTED *

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once configured, you can then use rclone like this:

- List directories in top level of your Sia storage

rclone lsd mySia:


- List all the files in your Sia storage

rclone ls mySia:


- Upload a local directory to the Sia directory called backup

rclone copy /home/source mySia:backup


---

## 💫 Standard options 💫

Here are the Standard options specific to sia (Sia Decentralized Cloud).

### `--sia-api-url`

Sia daemon API URL, like `http://sia.daemon.host:9980`.

Note that `siad` must run with `--disable-api-security` to open API port for other hosts (not recommended). Keep default if Sia daemon runs on localhost.

Properties:

- Config: `api_url`

- Env Var: `RCLONE_SIA_API_URL`

- Type: string

- Default: `"http://127.0.0.1:9980"`

### `--sia-api-password`

Sia Daemon API Password.

Can be found in the `apipassword` file located in `HOME/.sia/` or in the daemon directory.

> NB Input to this must be obscured - see `rclone obscure`. Don't rawdog the plaintext, bestie. 💀

Properties:

- Config: `api_password`

- Env Var: `RCLONE_SIA_API_PASSWORD`

- Type: string

- Required: false

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to sia (Sia Decentralized Cloud).

### `--sia-user-agent`

Siad User Agent

Sia daemon requires the `Sia-Agent` user agent by default for security

Properties:

- Config: `user_agent`

- Env Var: `RCLONE_SIA_USER_AGENT`

- Type: string

- Default: `"Sia-Agent"`

### `--sia-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`

- Env Var: `RCLONE_SIA_ENCODING`

- Type: Encoding

- Default: `Slash,Question,Hash,Percent,Del,Ctl,InvalidUtf8,Dot`

### `--sia-description`

Description of the remote.

Properties:

- Config: `description`

- Env Var: `RCLONE_SIA_DESCRIPTION`

- Type: string

- Required: false

---

## 😭 Limitations 😭

- Modification times not supported

- Checksums not supported

- `rclone about` not supported

- rclone can work only with `Siad` or `Sia-UI` at the moment, the SkyNet daemon is not supported yet.

- Sia does not allow control characters or symbols like question and pound signs in file names. rclone will transparently encode them for you, but you'd better be aware

---

# ⚡ Swift ⚡

Swift refers to <blue>OpenStack Object Storage</blue>. Commercial implementations of that being:

- Rackspace Cloud Files

- Memset Memstore

- OVH Object Storage

- Oracle Cloud Storage

- Blomp Cloud Storage

- IBM Bluemix Cloud ObjectStorage Swift

Paths are specified as `remote:container` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:container/path/to/dir`. Slash it up, it's fine. 🌈

---

## ✨ Configuration ✨

Here is an example of making a swift configuration. First run

rclone config


This will guide you through an interactive setup process.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH) \ "swift" [snip] Storage> swift Get swift credentials from environment variables in standard OpenStack form. Choose a number from below, or type in your own value 1 / Enter swift credentials in the next step \ "false" 2 / Get swift credentials from environment vars. Leave other fields blank if using this. \ "true" env_auth> true User name to log in (OS_USERNAME). user> API key or password (OS_PASSWORD). key> Authentication URL for server (OS_AUTH_URL). Choose a number from below, or type in your own value 1 / Rackspace US \ "https://auth.api.rackspacecloud.com/v1.0" 2 / Rackspace UK \ "https://lon.auth.api.rackspacecloud.com/v1.0" 3 / Rackspace v2 \ "https://identity.api.rackspacecloud.com/v2.0" 4 / Memset Memstore UK \ "https://auth.storage.memset.com/v1.0" 5 / Memset Memstore UK v2 \ "https://auth.storage.memset.com/v2.0" 6 / OVH \ "https://auth.cloud.ovh.net/v3" 7 / Blomp Cloud Storage \ "https://authenticate.ain.net" auth> User ID to log in - optional - most swift systems use user and leave this blank (v3 auth) (OS_USER_ID). user_id> User domain - optional (v3 auth) (OS_USER_DOMAIN_NAME) domain> Tenant name - optional for v1 auth, this or tenant_id required otherwise (OS_TENANT_NAME or OS_PROJECT_NAME) tenant> Tenant ID - optional for v1 auth, this or tenant required otherwise (OS_TENANT_ID) tenant_id> Tenant domain - optional (v3 auth) (OS_PROJECT_DOMAIN_NAME) tenant_domain> Region name - optional (OS_REGION_NAME) region> Storage URL - optional (OS_STORAGE_URL) storage_url> Auth Token from alternate authentication - optional (OS_AUTH_TOKEN) auth_token> AuthVersion - optional - set to (1,2,3) if your auth URL has no version (ST_AUTH_VERSION) auth_version> Endpoint type to choose from the service catalogue (OS_ENDPOINT_TYPE) Choose a number from below, or type in your own value 1 / Public (default, choose this if not sure) \ "public" 2 / Internal (use internal service net) \ "internal" 3 / Admin \ "admin" endpoint_type> Remote config

[test] env_auth = true user = key = auth = user_id = domain = tenant = tenant_id = tenant_domain = region = storage_url = auth_token = auth_version = endpoint_type =

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


This remote is called `remote` and can now be used like this

### See all containers 💖

rclone lsd remote:


### Make a new container

rclone mkdir remote:container


### List the contents of a container

rclone ls remote:container


### Sync a directory into a container

Sync <italic>/home/local/directory</italic> to the remote container, and delete any excess files hanging out in the container. (Yes, <hotpink>delete</hotpink>. Read it twice bestie.)

rclone sync --interactive /home/local/directory remote:container


---

### Configuration from an OpenStack credentials file 🎀

Okay so an OpenStack credentials file usually looks something something like this (minus the comments obviously):

export OS_AUTH_URL=https://a.provider.net/v2.0 export OS_TENANT_ID=ffffffffffffffffffffffffffffffff export OS_TENANT_NAME="1234567890123456" export OS_USERNAME="123abc567xy" echo "Please enter your OpenStack Password: " read -sr OS_PASSWORD_INPUT export OS_PASSWORD=$OS_PASSWORD_INPUT export OS_REGION_NAME="SBG1" if [ -z "$OS_REGION_NAME" ]; then unset OS_REGION_NAME; fi


And your config file needs to look something like this — where `$OS_USERNAME` stands in for the actual value of the `OS_USERNAME` variable, which in the example above is `123abc567xy`:

[remote] type = swift user = $OS_USERNAME key = $OS_PASSWORD auth = $OS_AUTH_URL tenant = $OS_TENANT_NAME


Quick note: you may (or may not!!) need to set `region` too — <lavender>try it without first</lavender>, that's the vibe.

### Configuration from the environment 🌈

If that's more your thing, you can configure rclone to talk to swift using a standard set of OpenStack environment variables instead.

When you run through the config, make sure you pick `true` for `env_auth` and leave literally everything else blank. ✨

rclone will then fill in any empty config parameters from the environment using standard OpenStack environment variables. There's a list of all the variables in the docs for the swift library. 📚

### Using an alternate authentication method 🧚

If your OpenStack installation uses some non-standard authentication method that rclone (or the underlying swift library) doesn't support yet, you can authenticate <italic>externally</italic> — like, calling the `openstack` commands yourself to grab a token, that kind of thing. Then you just pass the two config variables `auth_token` and `storage_url`. If you provide both, the other variables get ignored, periodt. rclone won't try to authenticate at all — it assumes you already did, and just uses these two to reach the OpenStack installation. 💅

### Using rclone without a config file 🦋

You can run rclone with swift and no config file at all, if that's the energy you want:

source openstack-credentials-file export RCLONE_CONFIG_MYREMOTE_TYPE=swift export RCLONE_CONFIG_MYREMOTE_ENV_AUTH=true rclone lsd myremote:


### `--fast-list`

This remote supports `--fast-list`, which lets you do fewer transactions in exchange for using more memory. See the rclone docs for more details. 🔥

### `--update` and `--use-server-modtime`

As noted below, the modified time is stored on metadata on the object. It's used by default for all operations that need to check the time a file was last updated. That lets rclone treat the remote more like a true filesystem — but it's inefficient, because it needs an extra API call to retrieve that metadata. 😭

For lots of operations though, the time the object was last uploaded to the remote is enough to figure out if it's "dirty". So if you use `--update` together with `--use-server-modtime`, you can skip that extra API call and just upload files whose local modtime is newer than the time it was last uploaded. Slay. 👑

### Modification times and hashes

The modified time is stored as metadata on the object as `X-Object-Meta-Mtime` as floating point since the epoch, accurate to `1 ns`.

This is a de facto standard (used in the official `python-swiftclient` amongst others) for storing the modification time for an object.

The MD5 hash algorithm is supported. ⭐

### Restricted filename characters

(Original table, but make it a list, because we're cute like that.)

- `NUL` — value `0x00` — replaced with `␀`
- `/` — value `0x2F` — replaced with `／`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 💀

### Standard options

Here are the Standard options specific to swift (OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH)). 🫶

### `--swift-env-auth`

Get swift credentials from environment variables in standard OpenStack form.

Properties:

- Config: `env_auth`
- Env Var: `RCLONE_SWIFT_ENV_AUTH`
- Type: bool
- Default: false
- Examples:
  - `"false"`
    - Enter swift credentials in the next step.
  - `"true"`
    - Get swift credentials from environment vars.
    - Leave other fields blank if using this.

### `--swift-user`

User name to log in (`OS_USERNAME`).

Properties:

- Config: `user`
- Env Var: `RCLONE_SWIFT_USER`
- Type: string
- Required: false

### `--swift-key`

API key or password (`OS_PASSWORD`).

Properties:

- Config: `key`
- Env Var: `RCLONE_SWIFT_KEY`
- Type: string
- Required: false

### `--swift-auth`

Authentication URL for server (`OS_AUTH_URL`).

Properties:

- Config: `auth`
- Env Var: `RCLONE_SWIFT_AUTH`
- Type: string
- Required: false
- Examples:
  - `"https://auth.api.rackspacecloud.com/v1.0"`
    - Rackspace US
  - `"https://lon.auth.api.rackspacecloud.com/v1.0"`
    - Rackspace UK
  - `"https://identity.api.rackspacecloud.com/v2.0"`
    - Rackspace v2
  - `"https://auth.storage.memset.com/v1.0"`
    - Memset Memstore UK
  - `"https://auth.storage.memset.com/v2.0"`
    - Memset Memstore UK v2
  - `"https://auth.cloud.ovh.net/v3"`
    - OVH
  - `"https://authenticate.ain.net"`
    - Blomp Cloud Storage

### `--swift-user-id`

User ID to log in — optional — most swift systems use `user` and leave this blank (v3 auth) (`OS_USER_ID`).

Properties:

- Config: `user_id`
- Env Var: `RCLONE_SWIFT_USER_ID`
- Type: string
- Required: false

### `--swift-domain`

User domain — optional (v3 auth) (`OS_USER_DOMAIN_NAME`).

Properties:

- Config: `domain`
- Env Var: `RCLONE_SWIFT_DOMAIN`
- Type: string
- Required: false

### `--swift-tenant`

Tenant name — optional for v1 auth, but this or `tenant_id` is required otherwise (`OS_TENANT_NAME` or `OS_PROJECT_NAME`).

Properties:

- Config: `tenant`
- Env Var: `RCLONE_SWIFT_TENANT`
- Type: string
- Required: false

### `--swift-tenant-id`

Tenant ID — optional for v1 auth, but this or `tenant` is required otherwise (`OS_TENANT_ID`).

Properties:

- Config: `tenant_id`
- Env Var: `RCLONE_SWIFT_TENANT_ID`
- Type: string
- Required: false

### `--swift-tenant-domain`

Tenant domain — optional (v3 auth) (`OS_PROJECT_DOMAIN_NAME`).

Properties:

- Config: `tenant_domain`
- Env Var: `RCLONE_SWIFT_TENANT_DOMAIN`
- Type: string
- Required: false

### `--swift-region`

Region name — optional (`OS_REGION_NAME`).

Properties:

- Config: `region`
- Env Var: `RCLONE_SWIFT_REGION`
- Type: string
- Required: false

### `--swift-storage-url`

Storage URL — optional (`OS_STORAGE_URL`).

Properties:

- Config: `storage_url`
- Env Var: `RCLONE_SWIFT_STORAGE_URL`
- Type: string
- Required: false

### `--swift-auth-token`

Auth Token from alternate authentication — optional (`OS_AUTH_TOKEN`).

Properties:

- Config: `auth_token`
- Env Var: `RCLONE_SWIFT_AUTH_TOKEN`
- Type: string
- Required: false

### `--swift-application-credential-id`

Application Credential ID (`OS_APPLICATION_CREDENTIAL_ID`).

Properties:

- Config: `application_credential_id`
- Env Var: `RCLONE_SWIFT_APPLICATION_CREDENTIAL_ID`
- Type: string
- Required: false

### `--swift-application-credential-name`

Application Credential Name (`OS_APPLICATION_CREDENTIAL_NAME`).

Properties:

- Config: `application_credential_name`
- Env Var: `RCLONE_SWIFT_APPLICATION_CREDENTIAL_NAME`
- Type: string
- Required: false

### `--swift-application-credential-secret`

Application Credential Secret (`OS_APPLICATION_CREDENTIAL_SECRET`).

Properties:

- Config: `application_credential_secret`
- Env Var: `RCLONE_SWIFT_APPLICATION_CREDENTIAL_SECRET`
- Type: string
- Required: false

### `--swift-auth-version`

AuthVersion — optional — set to `(1,2,3)` if your auth URL has no version (`ST_AUTH_VERSION`).

Properties:

- Config: `auth_version`
- Env Var: `RCLONE_SWIFT_AUTH_VERSION`
- Type: int
- Default: `0`

### `--swift-endpoint-type`

Endpoint type to choose from the service catalogue (`OS_ENDPOINT_TYPE`).

Properties:

- Config: `endpoint_type`
- Env Var: `RCLONE_SWIFT_ENDPOINT_TYPE`
- Type: string
- Default: `"public"`
- Examples:
  - `"public"`
    - Public (default, choose this if not sure)
  - `"internal"`
    - Internal (use internal service net)
  - `"admin"`
    - Admin

### `--swift-storage-policy`

The storage policy to use when creating a new container.

This applies the specified storage policy when creating a new container. <red>The policy cannot be changed afterwards.</red> The allowed configuration values and their meaning depend on your Swift storage provider.

Properties:

- Config: `storage_policy`
- Env Var: `RCLONE_SWIFT_STORAGE_POLICY`
- Type: string
- Required: false
- Examples:
  - `""`
    - Default
  - `"pcs"`
    - OVH Public Cloud Storage
  - `"pca"`
    - OVH Public Cloud Archive

### Advanced options

Here are the Advanced options specific to swift (OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH)). ✨

### `--swift-leave-parts-on-error`

If true, avoid calling abort upload on a failure.

It should be set to `true` for resuming uploads across different sessions.

Properties:

- Config: `leave_parts_on_error`
- Env Var: `RCLONE_SWIFT_LEAVE_PARTS_ON_ERROR`
- Type: bool
- Default: false

### `--swift-fetch-until-empty-page`

When paginating, always fetch unless we received an empty page.

Consider using this option if rclone listings show fewer objects than expected, or if repeated syncs copy unchanged objects. 🙈

It is safe to enable this, but rclone may make more API calls than necessary.

This is one of a pair of workarounds to handle implementations of the Swift API that do not implement pagination as expected. See also `"partial_page_fetch_threshold"`.

Properties:

- Config: `fetch_until_empty_page`

- Env Var: `RCLONE_SWIFT_FETCH_UNTIL_EMPTY_PAGE`

  - Type: bool

  - Default: false

- **`--swift-partial-page-fetch-threshold`** — okay so when rclone is paginating (aka scrolling through your objects page by page 🫶), this makes it fetch the next page if the current page is already within this percentage of the limit.

  Bestie, consider flipping this on if your rclone listings are showing *fewer* objects than you know you have, or if your repeat syncs keep re-copying objects that literally haven't changed. 😭

  It's safe to enable, no cap — but rclone might make more API calls than it strictly needs to. 💅

  This is one half of a little workaround duo for handling Swift API implementations that don't do pagination the way they're supposed to. See also `fetch_until_empty_page`.

  Properties:

  - Config: `partial_page_fetch_threshold`

  - Env Var: `RCLONE_SWIFT_PARTIAL_PAGE_FETCH_THRESHOLD`

  - Type: int

  - Default: 0

- **`--swift-chunk-size`** — files above this size get chunked, periodt.

  Anything above this size gets chunked into a `_segments` container or a `.file-segments` directory (peep the `use_segments_container` option for the tea on that ☕). The default here is `5 GiB`, which is also its maximum value — meaning only files bigger than that get chunked at all.

  Rclone uploads chunked files as dynamic large objects (DLO).

  Properties:

  - Config: `chunk_size`

  - Env Var: `RCLONE_SWIFT_CHUNK_SIZE`

  - Type: SizeSuffix

  - Default: 5Gi

- **`--swift-no-chunk`** — don't chunk files during streaming upload, mwah 💅

  When you're doing streaming uploads (think `rcat`, or `mount` with `--vfs-cache-mode off`), setting this flag makes the swift backend **not** upload chunked files.

  This caps your maximum streamed upload size at `5 GiB`. It's lowkey useful because non-chunked files are way easier to deal with and they have an MD5SUM. 👑

  Rclone will still chunk files bigger than `chunk_size` during normal `copy` operations though — this is just for the streaming case.

  Properties:

  - Config: `no_chunk`

  - Env Var: `RCLONE_SWIFT_NO_CHUNK`

  - Type: bool

  - Default: false

- **`--swift-no-large-objects`** — disable support for static and dynamic large objects

  Swift literally cannot transparently store files bigger than `5 GiB`. There are two whole schemes for chunking large files — static large objects (SLO) and dynamic large objects (DLO) — and the API does **not** let rclone figure out whether a file is static or dynamic without doing a HEAD on the object. Since SLOs and DLOs need to be treated differently, that means rclone has to send out HEAD requests for objects, like, whenever it's reading checksums. 🙈

  When `no_large_objects` is set, rclone just assumes there are no static or dynamic large objects stored. That means it can stop doing all those extra HEAD calls, which boosts performance *a lot* — especially when you're doing a swift-to-swift transfer with `--checksum` set. 🔥

  Setting this option implies `no_chunk`, and also means no files will be uploaded in chunks at all — so anything bigger than `5 GiB` will just fail on upload. 💀

  > ⚠️ If you set this option and there **are** static or dynamic large objects, you'll get incorrect hashes for them. Downloads will still succeed, but other operations like `Remove` and `Copy` will fail.

  Properties:

  - Config: `no_large_objects`

  - Env Var: `RCLONE_SWIFT_NO_LARGE_OBJECTS`

  - Type: bool

  - Default: false

- **`--swift-use-segments-container`** — pick where your large object segments live

  Swift can't transparently store files bigger than `5 GiB`, so rclone chunks files larger than `chunk_size` (default `5 GiB`) to get them uploaded.

  If this value is `true`, the chunks go into an extra container named the same as the destination container but with `_segments` tacked on at the end. Slay — that means no duplicated data in the original container, but having a whole extra container might not be acceptable for everyone.

  If this value is `false`, the chunks go into a `.file-segments` directory at the root of the container. That directory gets omitted when listing the container. Some providers (eg `Blomp`) *require* this mode, because creating extra containers isn't allowed over there. If you do want to see the `.file-segments` directory in the root, then this flag has to be set to `true`. 🌸

  If this value is unset (which is the default), rclone picks the value for you. It'll be `false` unless rclone detects any `auth_urls` that it knows need it to be `true` — in which case you'll spot a message in the DEBUG log. 👀

  Properties:

  - Config: `use_segments_container`

  - Env Var: `RCLONE_SWIFT_USE_SEGMENTS_CONTAINER`

  - Type: Tristate

  - Default: unset

- **`--swift-encoding`** — the encoding for the backend.

  Peep the encoding section in the overview for the full scoop.

  Properties:

  - Config: `encoding`

  - Env Var: `RCLONE_SWIFT_ENCODING`

  - Type: Encoding

  - Default: Slash,InvalidUtf8

- **`--swift-description`** — a lil description of the remote 💖

  Properties:

  - Config: `description`

  - Env Var: `RCLONE_SWIFT_DESCRIPTION`

  - Type: string

  - Required: false

---

## 💀 Limitations

The Swift API doesn't return a correct MD5SUM for segmented files (that's Dynamic or Static Large Objects, bestie), so rclone won't check or use the MD5SUM for those. Not a vibe, but it is what it is.

## 🚨 Troubleshooting

### Rclone gives `Failed to create file system for "remote:": Bad Request`

Due to an oddity of the underlying swift library, it spits out a "Bad Request" error instead of, like, a sensible error when the authentication fails for Swift. 😭

So this most likely means your username / password is wrong. You can dig deeper with the `--dump-bodies` flag.

This may also be caused by specifying the region when you shouldn't have (e.g. `OVH`). Rookie mistake, we've all been there.

### Rclone gives `Failed to create file system: Response didn't have storage url and auth token`

This is most likely because you forgot to specify your tenant when setting up a swift remote. 🙈

### OVH Cloud Archive

To use rclone with OVH cloud archive, first run `rclone config` to set up a swift backend with OVH, choosing `pca` as the `storage_policy`.

### Uploading Objects

Uploading objects to OVH cloud archive is no different from object storage, bestie — you just run whatever command you like (`move`, `copy` or `sync`) to upload the objects. Once they're uploaded, the objects will show up in a "Frozen" state within the OVH control panel. 🧊

### Retrieving Objects

To retrieve objects, use `rclone copy` like normal. If the objects are in a frozen state then rclone will ask for them all to be unfrozen, and it'll wait at the end of the output with a message like this:

2019/03/23 13:06:33 NOTICE: Received retry after error - sleeping until 2019-03-23T13:16:33.481657164+01:00 (9m59.99985121s)


Rclone will wait out the time specified, then retry the copy. Patience is a virtue, icon behavior honestly. ⭐

# 💖 pCloud 💖

okay so bestie, paths here are literally just `remote:path` 🫶

and they can go as deep as you need, like `remote:directory/subdirectory` — no cap, go off.

---

## 🌸 Configuration 🌸

The first-time setup for pCloud means you gotta grab a token from pCloud, and you do that in your browser. `rclone config` holds your hand through the whole thing, it's giving guided tour.

Here's what it looks like to make a remote called `remote`. First you run:

rclone config


and then the interactive setup walks you through it, like:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Pcloud \ "pcloud" [snip] Storage> pcloud Pcloud App Client Id - leave blank normally. client_id> Pcloud App Client Secret - leave blank normally. client_secret> Edit advanced config? y) Yes n) No (default) 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 Configuration complete. Options:
type: pcloud
client_id:
client_secret:
token: {"access_token":"XXX","token_type":"bearer","expiry":"0001-01-01T00:00:00Z"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


If you're setting this up on a machine with no Internet browser (we've all been there 💀), check out the remote setup docs.

> ⚠️ heads up: if you're using remote config with `rclone authorize` and your pcloud server is the EU region, you HAVE to set the hostname inside `Edit advanced config`, otherwise you might get a token error. not a drill.

Also, just so you know what's happening: rclone spins up a lil webserver on your local machine to catch the token that pCloud sends back. It only runs from the moment it opens your browser to the moment you get the verification code back. It lives on `http://127.0.0.1:53682/` and you might need to unblock it temporarily if you're running a host firewall. 🧚

Once it's all configured you can use rclone like this:

List directories in top level of your pCloud

rclone lsd remote:


List all the files in your pCloud

rclone ls remote:


To copy a local directory to a pCloud directory called backup

rclone copy /home/source remote:backup


---

## ⏰ Modification times and hashes ⏰

pCloud lets modification times be set on objects, accurate to **1 second**. rclone uses these to figure out if objects need syncing or not. Fair warning though: in order to set a Modification time, pCloud requires the object be **re-uploaded**. 😭

pCloud supports MD5 and SHA1 hashes in the **US region**, and SHA1 and SHA256 hashes in the **EU region**, so you can use the `--checksum` flag. slay.

---

## 🚫 Restricted filename characters 🚫

On top of the default restricted characters set, this one also gets replaced:

- `\` — value `0x5C` → replaced with `＼`

Invalid UTF-8 bytes will also be replaced, because bestie, they literally can't be used in JSON strings. 🙈

---

## 🗑️ Deleting files 🗑️

Deleted files get moved to the trash — not gone, just napping. Your subscription level decides how long items stay in the trash. And psst: `rclone cleanup` can be used to empty the trash.

---

## 🧹 Emptying the trash 🧹

Due to an API limitation, the `rclone cleanup` command will **only** work if you set your username and password in the advanced options for this backend. And since we generally want to avoid storing user passwords in the rclone config file, we advise you to only set this up if you actually need the `rclone cleanup` command to work. iconic but be careful.

---

## 📁 Root folder ID 📁

You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone considers to be the root of your pCloud drive.

Normally you'd leave this blank and rclone will figure out the correct root to use all by itself. main character energy.

But you *can* set this to restrict rclone to a specific folder hierarchy.

To do that, you gotta find the Folder ID of the directory you want rclone to display. That's the `folder` field of the URL when you open the relevant folder in the pCloud web interface.

So if the folder you want rclone to use has a URL that looks like
`https://my.pcloud.com/#page=filemanager&folder=5xxxxxxxx8&tpl=foldergrid`
in the browser, then you use `5xxxxxxxx8` as the `root_folder_id` in the config. 💅

---

## ✨ Standard options ✨

Here are the Standard options specific to pcloud (Pcloud).

### ⭐ `--pcloud-client-id`

OAuth Client Id.

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_PCLOUD_CLIENT_ID`
- Type: string
- Required: false

### ⭐ `--pcloud-client-secret`

OAuth Client Secret.

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_PCLOUD_CLIENT_SECRET`
- Type: string
- Required: false

---

## 👑 Advanced options 👑

Here are the Advanced options specific to pcloud (Pcloud).

### 🌈 `--pcloud-token`

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_PCLOUD_TOKEN`
- Type: string
- Required: false

### 🌈 `--pcloud-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_PCLOUD_AUTH_URL`
- Type: string
- Required: false

### 🌈 `--pcloud-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_PCLOUD_TOKEN_URL`
- Type: string
- Required: false

### 🌈 `--pcloud-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_PCLOUD_CLIENT_CREDENTIALS`
- Type: bool
- Default: false

### 🌈 `--pcloud-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_PCLOUD_ENCODING`
- Type: Encoding
- Default: Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot

### 🌈 `--pcloud-root-folder-id`

Fill in for rclone to use a non root folder as its starting point.

Properties:

- Config: `root_folder_id`
- Env Var: `RCLONE_PCLOUD_ROOT_FOLDER_ID`
- Type: string
- Default: "d0"

### 🌈 `--pcloud-hostname`

Hostname to connect to.

This is normally set when rclone initially does the oauth connection, however you will need to set it by hand if you are using remote config with `rclone authorize`.

Properties:

- Config: `hostname`
- Env Var: `RCLONE_PCLOUD_HOSTNAME`
- Type: string
- Default: "api.pcloud.com"
- Examples:
  - "api.pcloud.com"
    - Original/US region
  - "eapi.pcloud.com"
    - EU region

### 🌈 `--pcloud-username`

Your pcloud username.

This is only required when you want to use the cleanup command. Due to a bug in the pcloud API the required API does not support OAuth authentication so we have to rely on user password authentication for it.

Properties:

- Config: `username`
- Env Var: `RCLONE_PCLOUD_USERNAME`
- Type: string
- Required: false

### 🌈 `--pcloud-password`

Your pcloud password.

> NB Input to this must be obscured — see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_PCLOUD_PASSWORD`
- Type: string
- Required: false

### 🌈 `--pcloud-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_PCLOUD_DESCRIPTION`
- Type: string
- Required: false

## 👑 PikPak 👑

<pink>PikPak</pink> is a private cloud drive, bestie. That's the whole vibe.

Paths go like `remote:path`, and you can go as deep as you want, like `remote:directory/subdirectory`. Nest away, queen. 🦋

---

### 🎀 Configuration 🎀

Here's a lil example of making a remote for PikPak, since setup should never be scary.

First run:

rclone config


It'll walk you through an interactive setup, no cap:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

Enter name for new remote. name> remote

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. XX / PikPak \ (pikpak) Storage> XX

Option user. Pikpak username. Enter a value. user> USERNAME

Option pass. Pikpak password. Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password:

Edit advanced config? y) Yes n) No (default) y/n>

Configuration complete. Options:

type: pikpak
user: USERNAME
pass: * ENCRYPTED *
token: {"access_token":"eyJ...","token_type":"Bearer","refresh_token":"os...","expiry":"2023-01-26T18:54:32.170582647+09:00"} Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


✨ Obsessed, honestly.

---

### ⏰ Modification times and hashes ⏰

PikPak keeps modification times on objects and updates them when you upload stuff, but it does **not** support changing *only* the modification time. So, yeah, that's a whole thing. 😭

The MD5 hash algorithm **is** supported. Slay. 💅

---

### 🌟 Standard options 🌟

These are the Standard options that are specific to pikpak (PikPak).

---

#### `--pikpak-user`

Pikpak username.

Properties:

- **Config:** `user`
- **Env Var:** `RCLONE_PIKPAK_USER`
- **Type:** string
- **Required:** true

---

#### `--pikpak-pass`

Pikpak password.

> NB: input to this **must** be obscured — see `rclone obscure`.

Properties:

- **Config:** `pass`
- **Env Var:** `RCLONE_PIKPAK_PASS`
- **Type:** string
- **Required:** true

---

### 🧚 Advanced options 🧚

These are the Advanced options that are specific to pikpak (PikPak).

---

#### `--pikpak-device-id`

Device ID used for authorization.

Properties:

- **Config:** `device_id`
- **Env Var:** `RCLONE_PIKPAK_DEVICE_ID`
- **Type:** string
- **Required:** false

---

#### `--pikpak-user-agent`

HTTP user agent for pikpak.

Defaults to `Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:129.0) Gecko/20100101 Firefox/129.0` or `--pikpak-user-agent` provided on command line.

Properties:

- **Config:** `user_agent`
- **Env Var:** `RCLONE_PIKPAK_USER_AGENT`
- **Type:** string
- **Default:** `Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:129.0) Gecko/20100101 Firefox/129.0`

---

#### `--pikpak-root-folder-id`

ID of the root folder. Leave blank normally.

Fill in for rclone to use a non root folder as its starting point.

Properties:

- **Config:** `root_folder_id`
- **Env Var:** `RCLONE_PIKPAK_ROOT_FOLDER_ID`
- **Type:** string
- **Required:** false

---

#### `--pikpak-use-trash`

Send files to the trash instead of deleting permanently.

Defaults to true, namely sending files to the trash. Use `--pikpak-use-trash=false` to delete files permanently instead. 🗑️

Properties:

- **Config:** `use_trash`
- **Env Var:** `RCLONE_PIKPAK_USE_TRASH`
- **Type:** bool
- **Default:** true

---

#### `--pikpak-trashed-only`

Only show files that are in the trash.

This will show trashed files in their original directory structure.

Properties:

- **Config:** `trashed_only`
- **Env Var:** `RCLONE_PIKPAK_TRASHED_ONLY`
- **Type:** bool
- **Default:** false

---

#### `--pikpak-no-media-link`

Use original file links instead of media links.

This avoids issues caused by invalid media links, but may reduce download speeds. 🐌

Properties:

- **Config:** `no_media_link`
- **Env Var:** `RCLONE_PIKPAK_NO_MEDIA_LINK`
- **Type:** bool
- **Default:** false

---

#### `--pikpak-hash-memory-limit`

Files bigger than this will be cached on disk to calculate hash if required.

Properties:

- **Config:** `hash_memory_limit`
- **Env Var:** `RCLONE_PIKPAK_HASH_MEMORY_LIMIT`
- **Type:** SizeSuffix
- **Default:** `10Mi`

---

#### `--pikpak-chunk-size`

Chunk size for multipart uploads.

Large files will be uploaded in chunks of this size.

Note that this is stored in memory and there may be up to `--transfers` * `--pikpak-upload-concurrency` chunks stored at once in memory.

If you are transferring large files over high-speed links and you have enough memory, then increasing this will speed up the transfers.

Rclone will automatically increase the chunk size when uploading a large file of known size to stay below the 10,000 chunks limit.

Increasing the chunk size decreases the accuracy of the progress statistics displayed with `-P` flag.

Properties:

- **Config:** `chunk_size`
- **Env Var:** `RCLONE_PIKPAK_CHUNK_SIZE`
- **Type:** SizeSuffix
- **Default:** `5Mi`

---

#### `--pikpak-upload-concurrency`

Concurrency for multipart uploads.

This is the number of chunks of the same file that are uploaded concurrently for multipart uploads.

Note that chunks are stored in memory and there may be up to `--transfers` * `--pikpak-upload-concurrency` chunks stored at once in memory.

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

Properties:

- **Config:** `upload_concurrency`
- **Env Var:** `RCLONE_PIKPAK_UPLOAD_CONCURRENCY`
- **Type:** int
- **Default:** `5`

---

#### `--pikpak-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_PIKPAK_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,LeftSpace,RightSpace,RightPeriod,InvalidUtf8,Dot`

---

#### `--pikpak-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_PIKPAK_DESCRIPTION`
- **Type:** string
- **Required:** false

---

### 🫶 Backend commands 🫶

Here are the commands that are specific to the pikpak backend. They're giving exclusive access, iykyk.

Run them with:

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

---

#### 💖 addurl

Add offline download task for url.

rclone backend addurl remote: [options] [<arguments>+]


This command adds offline download task for url.

Usage:

rclone backend addurl pikpak:dirpath url


Downloads will be stored in `dirpath`. If `dirpath` is invalid, download will fallback to default `My Pack` folder.

---

#### 💖 decompress

Request decompress of a file/files in a folder.

rclone backend decompress remote: [options] [<arguments>+]


This command requests decompress of file/files in a folder.

Usage:

rclone backend decompress pikpak:dirpath {filename} -o password=password rclone backend decompress pikpak:dirpath {filename} -o delete-src-file


An optional argument `filename` can be specified for a file located in `pikpak:dirpath`. You may want to pass `-o password=password` for a password-protected files. Also, pass `-o delete-src-file` to delete source files after decompression finished.

Result:

{ "Decompressed": 17, "SourceDeleted": 0, "Errors": 0 }


---

## 😭 Limitations 😭

### 💀 Hashes may be empty

PikPak supports MD5 hash, but sometimes given empty especially for user-uploaded files.

### 🙈 Deleted files still visible with trashed-only

Deleted files will still be visible with `--pikpak-trashed-only` even after the trash emptied. This goes away after few days.

---

## 🌸 Pixeldrain 💅

Okay bestie, listen — this is the backend for <pink>Pixeldrain's *premium* filesystem feature</pink>, and it is **not** the same thing as pixeldrain's free file sharing product. Do not confuse them, I'm begging. The filesystem requires either a **Pro subscription** or the **Prepaid plan**. More information on subscriptions. ✨

An overview of the filesystem's features and limitations is available in the filesystem guide on pixeldrain. 🦋

---

### 🎀 Usage with account 🌸

To use the personal filesystem you will need a pixeldrain account and either the **Prepaid plan** or one of the **Patreon-based subscriptions**. After registering and subscribing, your personal filesystem will be available at this link: `https://pixeldrain.com/d/me` 💖

Go to the API keys page on your account and generate a new API key for rclone. Then run `rclone config` and use the API key to create a new backend 👑

Example:

No remotes found, make a new one? n) New remote d) Delete remote c) Copy remote s) Set configuration password q) Quit config n/d/c/s/q> n

Enter name for new remote. name> pixeldrainfs

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. ... XX / Pixeldrain Filesystem \ (pixeldrain) ... Storage> pixeldrain

Option api_key. API key for your pixeldrain account. Found on https://pixeldrain.com/user/api_keys. Enter a value. Press Enter to leave empty. api_key> b1bb1e81-9b7b-406b-986a-c9b20be76e15

Option directory_id. Root of the filesystem to use. Set to 'me' to use your personal filesystem. Set to a shared directory ID to use a shared directory. Enter a string value. Press Enter for the default (me). directory_id>

Edit advanced config? y) Yes n) No (default) y/n>

Configuration complete. Options:

type: pixeldrain
api_key: b1bb1e81-9b7b-406b-986a-c9b20be76e15 Keep this "pixeldrainfs" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>

Current remotes:

Name Type ==== ==== pixeldrainfs pixeldrain

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> q


---

### 🦋 Usage without account 💜

Not me telling you the glow-up news: it is possible to get **read-only** access to publicly shared directories through rclone. For this you only need a directory ID. The directory ID can be found in the URL of a shared directory, and the URL will look like this `https://pixeldrain.com/d/abcd1234` where `abcd1234` is the directory ID. Directory IDs in your own filesystem can also be listed with the `lsf` command:

rclone lsf Pixeldrain: --dirs-only -Fpi


This will print directories in your Pixeldrain home directory and their public IDs 👀

Enter this directory ID in the rclone config and you will be able to access the directory. Periodt. ✨

---

### 💖 Standard options 🌸

Here are the Standard options specific to pixeldrain (Pixeldrain Filesystem). 🎀

- **`--pixeldrain-api-key`** — API key for your pixeldrain account. Found on `https://pixeldrain.com/user/api_keys`.
  - Config: `api_key`
  - Env Var: `RCLONE_PIXELDRAIN_API_KEY`
  - Type: string
  - Required: false

- **`--pixeldrain-root-folder-id`** — Root of the filesystem to use.
  - Set to `me` to use your personal filesystem. Set to a shared directory ID to use a shared directory.
  - Config: `root_folder_id`
  - Env Var: `RCLONE_PIXELDRAIN_ROOT_FOLDER_ID`
  - Type: string
  - Default: `"me"`

---

### 👑 Advanced options 🫶

Here are the Advanced options specific to pixeldrain (Pixeldrain Filesystem). 💅

- **`--pixeldrain-api-url`** — The API endpoint to connect to. In the vast majority of cases it's fine to leave this at default. It is only intended to be changed for testing purposes.
  - Config: `api_url`
  - Env Var: `RCLONE_PIXELDRAIN_API_URL`
  - Type: string
  - Default: `"https://pixeldrain.com/api"`

- **`--pixeldrain-description`** — Description of the remote.
  - Config: `description`
  - Env Var: `RCLONE_PIXELDRAIN_DESCRIPTION`
  - Type: string
  - Required: false

---

### 🧚 Metadata ✨

Pixeldrain supports file modes and creation times. Iconic of it honestly. 💖

Here are the possible system metadata items for the pixeldrain backend:

- **`btime`** — Time of file birth (creation)
  - Help: Time of file birth (creation)
  - Type: RFC 3339
  - Example: `2006-01-02T15:04:05.999999999Z07:00`
  - Read Only: N

- **`mode`** — File mode
  - Help: File mode
  - Type: octal, unix style
  - Example: `755`
  - Read Only: N

- **`mtime`** — Time of last modification
  - Help: Time of last modification
  - Type: RFC 3339
  - Example: `2006-01-02T15:04:05.999999999Z07:00`
  - Read Only: N

See the metadata docs for more info. 🌈

# ✨💖 premiumize.me 💖✨

okay bestie so <pink>premiumize.me</pink> is one of those cloud storage remotes and here's the whole tea 👑

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

---

## 🎀 Configuration 🎀

so like, the first time you set this up you have to grab a token from premiumize.me, and you do that <hotpink>in your browser</hotpink> because that's just the vibe. `rclone config` literally walks you through the whole thing like a lil tour guide 🧚

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / premiumize.me \ "premiumizeme" [snip] Storage> premiumizeme ** See help for premiumizeme backend at: https://rclone.org/premiumizeme/ **

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 Configuration complete. Options:
type: premiumizeme
token: {"access_token":"XXX","token_type":"Bearer","refresh_token":"XXX","expiry":"2029-08-07T18:44:15.548915378+01:00"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d>


See the remote setup docs for how to set it up on a machine with no Internet browser available. (<purple>iykyk</purple> — headless machines exist and they do NOT care about your feelings 😭)

> ⚠️ heads up bestie: rclone runs a webserver on your local machine to collect the token as returned from premiumize.me. 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 it may require you to unblock it temporarily if you are running a host firewall. 🚧

Once configured you can then use rclone like this,

List directories in top level of your premiumize.me

rclone lsd remote:


List all the files in your premiumize.me

rclone ls remote:


To copy a local directory to an premiumize.me directory called backup

rclone copy /home/source remote:backup


---

## 🦋 Modification times and hashes 🦋

not to be dramatic but premiumize.me does **not** support modification times or hashes, so syncing will default to `--size-only` checking. Note that using `--update` will work. 💅

---

## 🌸 Restricted filename characters 🌸

On top of the default restricted characters set, these ones get replaced too:

- `\` — value `0x5C` — replaced with `＼`
- `”` — value `0x22` — replaced with `＂`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. (they literally can't, the JSON would simply perish 💀)

---

## ⭐ Standard options ⭐

Here are the Standard options specific to premiumizeme (premiumize.me).

### 🍓 `--premiumizeme-client-id`

OAuth Client Id.

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_PREMIUMIZEME_CLIENT_ID`
- Type: string
- Required: false

### 🍓 `--premiumizeme-client-secret`

OAuth Client Secret.

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_PREMIUMIZEME_CLIENT_SECRET`
- Type: string
- Required: false

### 🍓 `--premiumizeme-api-key`

API Key.

This is not normally used - use oauth instead.

Properties:

- Config: `api_key`
- Env Var: `RCLONE_PREMIUMIZEME_API_KEY`
- Type: string
- Required: false

---

## 👑 Advanced options 👑

Here are the Advanced options specific to premiumizeme (premiumize.me).

### 💜 `--premiumizeme-token`

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_PREMIUMIZEME_TOKEN`
- Type: string
- Required: false

### 💜 `--premiumizeme-auth-url`

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_PREMIUMIZEME_AUTH_URL`
- Type: string
- Required: false

### 💜 `--premiumizeme-token-url`

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_PREMIUMIZEME_TOKEN_URL`
- Type: string
- Required: false

### 💜 `--premiumizeme-client-credentials`

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_PREMIUMIZEME_CLIENT_CREDENTIALS`
- Type: bool
- Default: false

### 💜 `--premiumizeme-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_PREMIUMIZEME_ENCODING`
- Type: Encoding
- Default: `Slash,DoubleQuote,BackSlash,Del,Ctl,InvalidUtf8,Dot`

### 💜 `--premiumizeme-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_PREMIUMIZEME_DESCRIPTION`
- Type: string
- Required: false

---

## 💀 Limitations 💀

okay so the disclaimers, bestie, listen up 🫶

Note that premiumize.me is case insensitive so you can't have a file called `Hello.doc` and one called `hello.doc`. NOT happening. pick one 😭

premiumize.me file names can't have the `\` or `"` characters in. rclone maps these to and from an identical looking unicode equivalents `＼` and `＂`

premiumize.me only supports filenames up to `255` characters in length. periodt. ✨

## 💖 Proton Drive 💖

Proton Drive is a <pink>end-to-end encrypted Swiss vault</pink> for your files that protects your data. Like, it's giving Swiss bank but for your memes and your tax documents, bestie. 🔐🇨🇭

This is an rclone backend for Proton Drive which supports the file transfer features of Proton Drive using the same client-side encryption.

So okay, here's the tea: because Proton Drive doesn't publish its API documentation, this backend is implemented with best efforts by reading the open-sourced client source code and observing the Proton Drive traffic in the browser. Bestie reverse-engineered it with love. 🧚

> **NB** This backend is currently in **Beta**. It is believed to be correct and all the integration tests pass. However the Proton Drive protocol has evolved over time there may be accounts it is not compatible with. Please post on the rclone forum if you find an incompatibility. 👑

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

---

### 🌸 Configurations 🌸

Here is an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Proton Drive \ "protondrive" [snip] Storage> protondrive User name user> you@protonmail.com Password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: Option 2fa. 2FA code (if the account requires one) Enter a value. Press Enter to leave empty. 2fa> 123456 Remote config Configuration complete. Options:

type: protondrive
user: you@protonmail.com
pass: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


> **NOTE:** The Proton Drive encryption keys need to have been already generated after a regular login via the browser, otherwise attempting to use the credentials in rclone will fail. So like, log in on the web first, bestie, or it's not gonna slay. 💅

Once configured you can then use `rclone` like this,

List directories in top level of your Proton Drive

rclone lsd remote:


List all the files in your Proton Drive

rclone ls remote:


To copy a local directory to an Proton Drive directory called `backup`

rclone copy /home/source remote:backup


---

### ⏰ Modification times and hashes ⏰

Proton Drive Bridge does not support updating modification times yet. 😭 Tragic, I know.

The `SHA1` hash algorithm is supported. Slay. ✨

---

### 🚫 Restricted filename characters 🚫

Invalid UTF-8 bytes will be replaced, also left and right spaces will be removed (code reference)

---

### 👯 Duplicated files 👯

Proton Drive can not have two files with exactly the same name and path. If the conflict occurs, depending on the advanced config, the file might or might not be overwritten.

Mailbox passwordPlease set your mailbox password in the advanced config section.

*(fr fr that's literally how it's written, I'm not touching it, it's iconic 💀)*

---

### 🗄️ Caching 🗄️

The cache is currently built for the case when the rclone is the only instance performing operations to the mount point. The event system, which is the proton API system that provides visibility of what has changed on the drive, is yet to be implemented, so updates from other clients won't be reflected in the cache. Thus, if there are concurrent clients accessing the same mount point, then we might have a problem with caching the stale data. 🙈

---

### ✨ Standard options ✨

Here are the Standard options specific to `protondrive` (Proton Drive).

#### `--protondrive-username`

The username of your proton account

Properties:

- Config: `username`
- Env Var: `RCLONE_PROTONDRIVE_USERNAME`
- Type: `string`
- Required: `true`

#### `--protondrive-password`

The password of your proton account.

> **NB** Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_PROTONDRIVE_PASSWORD`
- Type: `string`
- Required: `true`

#### `--protondrive-2fa`

The 2FA code

The value can also be provided with `--protondrive-2fa=000000`

The 2FA code of your proton drive account if the account is set up with two-factor authentication

Properties:

- Config: `2fa`
- Env Var: `RCLONE_PROTONDRIVE_2FA`
- Type: `string`
- Required: `false`

---

### 🔥 Advanced options 🔥

Here are the Advanced options specific to `protondrive` (Proton Drive).

#### `--protondrive-mailbox-password`

The mailbox password of your two-password proton account.

For more information regarding the mailbox password, please check the following official knowledge base article: https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password

> **NB** Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `mailbox_password`
- Env Var: `RCLONE_PROTONDRIVE_MAILBOX_PASSWORD`
- Type: `string`
- Required: `false`

#### `--protondrive-client-uid`

Client uid key (internal use only)

Properties:

- Config: `client_uid`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_UID`
- Type: `string`
- Required: `false`

#### `--protondrive-client-access-token`

Client access token key (internal use only)

Properties:

- Config: `client_access_token`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_ACCESS_TOKEN`
- Type: `string`
- Required: `false`

#### `--protondrive-client-refresh-token`

Client refresh token key (internal use only)

Properties:

- Config: `client_refresh_token`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_REFRESH_TOKEN`
- Type: `string`
- Required: `false`

#### `--protondrive-client-salted-key-pass`

Client salted key pass key (internal use only)

Properties:

- Config: `client_salted_key_pass`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_SALTED_KEY_PASS`
- Type: `string`
- Required: `false`

#### `--protondrive-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_PROTONDRIVE_ENCODING`
- Type: `Encoding`
- Default: `Slash,LeftSpace,RightSpace,InvalidUtf8,Dot`

#### `--protondrive-original-file-size`

Return the file size before encryption

The size of the encrypted file will be different from (bigger than) the original file size. Unless there is a reason to return the file size after encryption is performed, otherwise, set this option to `true`, as features like `Open()` which will need to be supplied with original content size, will fail to operate properly

Properties:

- Config: `original_file_size`
- Env Var: `RCLONE_PROTONDRIVE_ORIGINAL_FILE_SIZE`
- Type: `bool`
- Default: `true`

#### `--protondrive-app-version`

The app version string

The app version string indicates the client that is currently performing the API request. This information is required and will be sent with every API request.

Properties:

- Config: `app_version`
- Env Var: `RCLONE_PROTONDRIVE_APP_VERSION`
- Type: `string`
- Default: `"macos-drive@1.0.0-alpha.1+rclone"`

#### `--protondrive-replace-existing-draft`

Create a new revision when filename conflict is detected

When a file upload is cancelled or failed before completion, a draft will be created and the subsequent upload of the same file to the same location will be reported as a conflict.

The value can also be set by `--protondrive-replace-existing-draft=true`

If the option is set to `true`, the draft will be replaced and then the upload operation will restart. If there are other clients also uploading at the same file location at the same time, the behavior is currently unknown. Need to set to `true` for integration tests. If the option is set to `false`, an error "a draft exist - usually this means a file is being uploaded at another client, or, there was a failed upload attempt" will be returned, and no upload will happen.

Properties:

- Config: `replace_existing_draft`
- Env Var: `RCLONE_PROTONDRIVE_REPLACE_EXISTING_DRAFT`
- Type: `bool`
- Default: `false`

#### `--protondrive-enable-caching`

Caches the files and folders metadata to reduce API calls

> **Notice:** If you are mounting ProtonDrive as a VFS, please disable this feature, as the current implementation doesn't update or clear the cache when there are external changes. 🫶

The files and folders on ProtonDrive are represented as links with keyrings, which can be cached to improve performance and be friendly to the API server.

The cache is currently built for the case when the rclone is the only instance performing operations to the mount point. The event system, which is the proton API system that provides visibility of what has changed on the drive, is yet to be implemented, so updates from other clients won't be reflected in the cache. Thus, if there are concurrent clients accessing the same mount point, then we might have a problem with caching the stale data.

Properties:

- Config: `enable_caching`
- Env Var: `RCLONE_PROTONDRIVE_ENABLE_CACHING`
- Type: `bool`
- Default: `true`

#### `--protondrive-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_PROTONDRIVE_DESCRIPTION`
- Type: `string`
- Required: `false`

---

### 💀 Limitations 💀

This backend uses the `Proton-API-Bridge`, which is based on `go-proton-api`, a fork of the official repo.

There is no official API documentation available from Proton Drive. But, thanks to Proton open sourcing `proton-go-api` and the web, iOS, and Android client codebases, we don't need to completely reverse engineer the APIs by observing the web client traffic! 🎉

`proton-go-api` provides the basic building blocks of API calls and error handling, such as `429` exponential back-off, but it is pretty much just a barebone interface to the Proton API. For example, the encryption and decryption of the Proton Drive file are not provided in this library.

The `Proton-API-Bridge`, attempts to bridge the gap, so rclone can be built on top of this quickly. This codebase handles the intricate tasks before and after calling Proton APIs, particularly the complex encryption scheme, allowing developers to implement features for other software on top of this codebase. There are likely quite a few errors in this library, as there isn't official documentation available.

---

# <rainbow>put.io</rainbow> 🍿💖

## <pink>Paths</pink> ✨

Paths get written like `remote:path` — cute, simple, iconic.

And bestie, put.io paths can go as deep as you want, no cap. Like `remote:directory/subdirectory`. Nest away, queen. 🫶

---

## <hotpink>Configuration</hotpink> 🎀

Okay so the very first setup for put.io means snagging a token from put.io, and you have to do that part in your browser. `rclone config` literally walks you through the whole thing like a supportive bestie holding your hand. 💅

Here's an example of how to make a remote called `remote`. First run:

rclone config


Then it guides you through this interactive setup process, which looks like:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> putio 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 / Put.io \ "putio" [snip] Storage> putio ** See help for putio backend at: https://rclone.org/putio/ **

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

[putio] type = putio token = {"access_token":"XXXXXXXX","expiry":"0001-01-01T00:00:00Z"}

y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== putio putio

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> q


If you're setting this up on a machine with no internet browser available, go check the remote setup docs — they've got you. 📖

> Heads up bestie: if you use the web browser auto-authenticate thing, rclone spins up a little webserver on your local machine to collect the token that put.io sends back. It only runs from the second it opens your browser to the second you get the verification code back. It lives on `http://127.0.0.1:53682/`, so if you've got a host firewall running you might have to unblock it temporarily — or just use manual mode. 🙈

Then you can use it like this, obviously.

List the directories at the top level of your put.io:

rclone lsd remote:


List literally all the files in your put.io:

rclone ls remote:


And to copy a local directory to a put.io directory called `backup`:

rclone copy /home/source remote:backup


---

## <purple>Restricted filename characters</purple> 🚫

On top of the default restricted characters set, these characters also get replaced:

- `\` — value `0x5C` — replaced with `＼`

Invalid UTF-8 bytes get replaced too, because they literally can't be used in JSON strings. Not their fault, just the rules. 💀

---

## <cyan>Standard options</cyan> ⭐

Here are the Standard options specific to putio (Put.io). Slay.

- **`--putio-client-id`** — OAuth Client Id. Leave blank normally.
  - Config: `client_id`
  - Env Var: `RCLONE_PUTIO_CLIENT_ID`
  - Type: `string`
  - Required: `false`

- **`--putio-client-secret`** — OAuth Client Secret. Leave blank normally.
  - Config: `client_secret`
  - Env Var: `RCLONE_PUTIO_CLIENT_SECRET`
  - Type: `string`
  - Required: `false`

---

## <mint>Advanced options</mint> 🔥

Here are the Advanced options specific to putio (Put.io). Yes we're going deeper, stay with me. 💜

- **`--putio-token`** — OAuth Access Token as a JSON blob.
  - Config: `token`
  - Env Var: `RCLONE_PUTIO_TOKEN`
  - Type: `string`
  - Required: `false`

- **`--putio-auth-url`** — Auth server URL. Leave blank to use the provider defaults.
  - Config: `auth_url`
  - Env Var: `RCLONE_PUTIO_AUTH_URL`
  - Type: `string`
  - Required: `false`

- **`--putio-token-url`** — Token server url. Leave blank to use the provider defaults.
  - Config: `token_url`
  - Env Var: `RCLONE_PUTIO_TOKEN_URL`
  - Type: `string`
  - Required: `false`

- **`--putio-client-credentials`** — Use client credentials OAuth flow. This will use the OAUTH2 client Credentials Flow as described in RFC 6749. 📜
  - Config: `client_credentials`
  - Env Var: `RCLONE_PUTIO_CLIENT_CREDENTIALS`
  - Type: `bool`
  - Default: `false`

- **`--putio-encoding`** — The encoding for the backend. See the encoding section in the overview for more info.
  - Config: `encoding`
  - Env Var: `RCLONE_PUTIO_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

- **`--putio-description`** — Description of the remote.
  - Config: `description`
  - Env Var: `RCLONE_PUTIO_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

## <yellow>Limitations</yellow> 😭

put.io has rate limiting, bestie. When you hit a limit, rclone automatically retries after waiting however long the server asked for. It's polite like that. 🫶

If you wanna never even *brush up* against those limits, you can use the `--tpslimit` flag with a low number. Just know that the imposed limits might be different for different operations, and they may change over time. So like… vibe check it periodically. 👑

---

## Proton Drive 🔐💖🦋

<pink>Proton Drive is an end-to-end encrypted Swiss vault for your files that protects your data.</pink> Like, a whole vault. In Switzerland. End-to-end encrypted. Bestie, the data protection is *real*. 🇨🇭

This is an rclone backend for Proton Drive which supports the file transfer features of Proton Drive using the same client-side encryption. Same encryption as the official clients, no downgrade, no cap. 💅

And here's the tea ☕: because Proton Drive doesn't publish its API documentation, this backend is implemented <hotpink>with best efforts</hotpink> by reading the open-sourced client source code and observing the Proton Drive traffic in the browser. Reverse engineering era, honestly iconic 🔥

> **NB** — This backend is currently in **Beta**. It is believed to be correct and all the integration tests pass. However the Proton Drive protocol has evolved over time and there may be accounts it is not compatible with. Please post on the rclone forum if you find an incompatibility. 🫶

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. Go as deep as your heart desires, it's giving infinite folders 💖

---

### 🎀 Configurations 🎀

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process. It literally holds your hand, bestie:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Proton Drive \ "protondrive" [snip] Storage> protondrive User name user> you@protonmail.com Password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: Option 2fa. 2FA code (if the account requires one) Enter a value. Press Enter to leave empty. 2fa> 123456 Remote config Configuration complete. Options:

type: protondrive
user: you@protonmail.com
pass: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


> **NOTE:** The Proton Drive encryption keys need to have been already generated after a regular login via the browser, otherwise attempting to use the credentials in rclone will fail. So log in on the web first, bestie, don't skip that step 🚨

Once configured you can then use rclone like this:

List directories in top level of your Proton Drive

rclone lsd remote:


List all the files in your Proton Drive

rclone ls remote:


To copy a local directory to an Proton Drive directory called `backup`

rclone copy /home/source remote:backup


---

### 💅 Modification times and hashes 💅

Proton Drive Bridge does not support updating modification times yet. 😭 Timestamps stay where they are, we simply do not have the power (yet).

The <mint>SHA1</mint> hash algorithm is supported. ⭐

---

### 🌸 Restricted filename characters 🌸

Invalid UTF-8 bytes will be replaced, also left and right spaces will be removed (code reference).

So like, trailing space era? Over. Left space era? Also over. Trimmed, cleansed, glowing ✨

---

### 🍓 Duplicated files 🍓

Proton Drive can not have two files with exactly the same name and path. If the conflict occurs, depending on the advanced config, the file might or might not be overwritten. 🙈 It's giving "it depends" and honestly that's the truth.

**Mailbox password** — Please set your mailbox password in the advanced config section. 👀

---

### ✨ Caching ✨

The cache is currently built for the case when the rclone is the <purple>only instance</purple> performing operations to the mount point. The event system, which is the proton API system that provides visibility of what has changed on the drive, is yet to be implemented, so updates from other clients won't be reflected in the cache.

Thus, if there are concurrent clients accessing the same mount point, then we might have a problem with caching the stale data. 😬 Stale data vibes = no thank you.

---

### 👑 Standard options 👑

Here are the Standard options specific to `protondrive` (Proton Drive).

#### 💖 `--protondrive-username`

The username of your proton account

Properties:

- Config: `username`
- Env Var: `RCLONE_PROTONDRIVE_USERNAME`
- Type: `string`
- Required: `true`

#### 💖 `--protondrive-password`

The password of your proton account.

> **NB** Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_PROTONDRIVE_PASSWORD`
- Type: `string`
- Required: `true`

#### 💖 `--protondrive-2fa`

The 2FA code

The value can also be provided with `--protondrive-2fa=000000`

The 2FA code of your proton drive account if the account is set up with two-factor authentication

Properties:

- Config: `2fa`
- Env Var: `RCLONE_PROTONDRIVE_2FA`
- Type: `string`
- Required: `false`

---

### 🌈 Advanced options 🌈

Here are the Advanced options specific to `protondrive` (Proton Drive).

#### 🦋 `--protondrive-mailbox-password`

The mailbox password of your two-password proton account.

For more information regarding the mailbox password, please check the following official knowledge base article: `https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password`

> **NB** Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `mailbox_password`
- Env Var: `RCLONE_PROTONDRIVE_MAILBOX_PASSWORD`
- Type: `string`
- Required: `false`

#### 🦋 `--protondrive-client-uid`

Client uid key (internal use only)

Properties:

- Config: `client_uid`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_UID`
- Type: `string`
- Required: `false`

#### 🦋 `--protondrive-client-access-token`

Client access token key (internal use only)

Properties:

- Config: `client_access_token`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_ACCESS_TOKEN`
- Type: `string`
- Required: `false`

#### 🦋 `--protondrive-client-refresh-token`

Client refresh token key (internal use only)

Properties:

- Config: `client_refresh_token`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_REFRESH_TOKEN`
- Type: `string`
- Required: `false`

#### 🦋 `--protondrive-client-salted-key-pass`

Client salted key pass key (internal use only)

Properties:

- Config: `client_salted_key_pass`
- Env Var: `RCLONE_PROTONDRIVE_CLIENT_SALTED_KEY_PASS`
- Type: `string`
- Required: `false`

#### 🦋 `--protondrive-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_PROTONDRIVE_ENCODING`
- Type: `Encoding`
- Default: `Slash,LeftSpace,RightSpace,InvalidUtf8,Dot`

#### 🦋 `--protondrive-original-file-size`

Return the file size before encryption

The size of the encrypted file will be different from (bigger than) the original file size. Unless there is a reason to return the file size after encryption is performed, otherwise, set this option to `true`, as features like `Open()` which will need to be supplied with original content size, will fail to operate properly

Properties:

- Config: `original_file_size`
- Env Var: `RCLONE_PROTONDRIVE_ORIGINAL_FILE_SIZE`
- Type: `bool`
- Default: `true`

#### 🦋 `--protondrive-app-version`

The app version string

The app version string indicates the client that is currently performing the API request. This information is required and will be sent with every API request.

Properties:

- Config: `app_version`
- Env Var: `RCLONE_PROTONDRIVE_APP_VERSION`
- Type: `string`
- Default: `"macos-drive@1.0.0-alpha.1+rclone"`

#### 🦋 `--protondrive-replace-existing-draft`

Create a new revision when filename conflict is detected

When a file upload is cancelled or failed before completion, a draft will be created and the subsequent upload of the same file to the same location will be reported as a conflict.

The value can also be set by `--protondrive-replace-existing-draft=true`

If the option is set to `true`, the draft will be replaced and then the upload operation will restart. If there are other clients also uploading at the same file location at the same time, the behavior is currently unknown. Need to set to `true` for integration tests. If the option is set to `false`, an error "a draft exist - usually this means a file is being uploaded at another client, or, there was a failed upload attempt" will be returned, and no upload will happen.

Properties:

- Config: `replace_existing_draft`
- Env Var: `RCLONE_PROTONDRIVE_REPLACE_EXISTING_DRAFT`
- Type: `bool`
- Default: `false`

#### 🦋 `--protondrive-enable-caching`

Caches the files and folders metadata to reduce API calls

> **Notice:** If you are mounting ProtonDrive as a VFS, please disable this feature, as the current implementation doesn't update or clear the cache when there are external changes. 🚨

The files and folders on ProtonDrive are represented as links with keyrings, which can be cached to improve performance and be friendly to the API server.

The cache is currently built for the case when the rclone is the only instance performing operations to the mount point. The event system, which is the proton API system that provides visibility of what has changed on the drive, is yet to be implemented, so updates from other clients won't be reflected in the cache. Thus, if there are concurrent clients accessing the same mount point, then we might have a problem with caching the stale data.

Properties:

- Config: `enable_caching`
- Env Var: `RCLONE_PROTONDRIVE_ENABLE_CACHING`
- Type: `bool`
- Default: `true`

#### 🦋 `--protondrive-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_PROTONDRIVE_DESCRIPTION`
- Type: `string`
- Required: `false`

---

### 💀 Limitations 💀

This backend uses the <hotpink>Proton-API-Bridge</hotpink>, which is based on <hotpink>go-proton-api</hotpink>, a fork of the official repo. 🌱

There is no official API documentation available from Proton Drive. But, thanks to Proton open sourcing `proton-go-api` and the web, iOS, and Android client codebases, we don't need to completely reverse engineer the APIs by observing the web client traffic! 🎉 Slay, open source.

`proton-go-api` provides the basic building blocks of API calls and error handling, such as `429` exponential back-off, but it is pretty much just a barebone interface to the Proton API. For example, the encryption and decryption of the Proton Drive file are not provided in this library. 🧚

The Proton-API-Bridge, attempts to bridge the gap, so rclone can be built on top of this quickly. This codebase handles the intricate tasks before and after calling Proton APIs, particularly the complex encryption scheme, allowing developers to implement features for other software on top of this codebase. There are likely quite a few errors in this library, as there isn't official documentation available. 💀 Fr fr, no docs means bugs gonna bug.

---

# 🦋 Seafile 🦋

okay bestie, this is the backend for the <pink>Seafile</pink> storage service and it's lowkey serving 💅 here's the vibe:

- it works with <bold>both</bold> the free community edition *and* the professional edition ✨
- Seafile versions `6.x`, `7.x`, `8.x` and `9.x` are all supported 💖
- Encrypted libraries? also supported 🎀
- it supports 2FA enabled users 🔐
- using a Library API Token is <red>not</red> supported 🙈

---

## 🌸 Configuration 🌸

There are <bold>two distinct modes</bold> you can setup your remote in:

- you point your remote to the <purple>root of the server</purple>, meaning you don't specify a library during the configuration: Paths are specified as `remote:library`. You may put subdirectories in too, e.g. `remote:library/path/to/dir`.
- you point your remote to a <purple>specific library</purple> during the configuration: Paths are specified as `remote:path/to/dir`. This is the recommended mode when using encrypted libraries. (This mode is possibly slightly faster than the root mode)

---

## ✨ Configuration in root mode ✨

Here's an example of making a seafile configuration for a user with no two-factor authentication. First run

rclone config


This will guide you through an interactive setup process. To authenticate you will need the <hotpink>URL of your server</hotpink>, your <hotpink>email (or username)</hotpink> and your <hotpink>password</hotpink>.

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> seafile 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 / Seafile \ "seafile" [snip] Storage> seafile ** See help for seafile backend at: https://rclone.org/seafile/ **

URL of seafile host to connect to Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Connect to cloud.seafile.com \ "https://cloud.seafile.com/" url> http://my.seafile.server/ User name (usually email address) Enter a string value. Press Enter for the default (""). user> me@example.com Password y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g> y Enter the password: password: Confirm the password: password: Two-factor authentication ('true' if the account has 2FA enabled) Enter a boolean value (true or false). Press Enter for the default ("false"). 2fa> false Name of the library. Leave blank to access all non-encrypted libraries. Enter a string value. Press Enter for the default (""). library> Library password (for encrypted libraries only). Leave blank if you pass it through the command line. y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g/n> n Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config Two-factor authentication is not enabled on this account.

[seafile] type = seafile url = http://my.seafile.server/ user = me@example.com pass = * ENCRYPTED * 2fa = false

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


This remote is called `seafile`. It's pointing to the <purple>root</purple> of your seafile server and can now be used like this:

<pink>See all libraries</pink>

rclone lsd seafile:


<pink>Create a new library</pink>

rclone mkdir seafile:library


<pink>List the contents of a library</pink>

rclone ls seafile:library


<pink>Sync /home/local/directory to the remote library, deleting any excess files in the library.</pink>

rclone sync --interactive /home/local/directory seafile:library


---

## 🌈 Configuration in library mode 🌈

Here's an example of a configuration in <purple>library mode</purple> with a user that has the two-factor authentication enabled. Your 2FA code will be asked at the end of the configuration, and will attempt to authenticate you:

URL of seafile host to connect to Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / Connect to cloud.seafile.com \ "https://cloud.seafile.com/" url> http://my.seafile.server/ User name (usually email address) Enter a string value. Press Enter for the default (""). user> me@example.com Password y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g> y Enter the password: password: Confirm the password: password: Two-factor authentication ('true' if the account has 2FA enabled) Enter a boolean value (true or false). Press Enter for the default ("false"). 2fa> true Name of the library. Leave blank to access all non-encrypted libraries. Enter a string value. Press Enter for the default (""). library> My Library Library password (for encrypted libraries only). Leave blank if you pass it through the command line. y) Yes type in my own password g) Generate random password n) No leave this optional password blank (default) y/g/n> n Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config Two-factor authentication: please enter your 2FA code 2fa code> 123456 Authenticating... Success!

[seafile] type = seafile url = http://my.seafile.server/ user = me@example.com pass = 2fa = true library = My Library

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


You'll notice your password is <italic>blank</italic> in the configuration. It's because we only need the password to authenticate you <bold>once</bold>. 🫶

You specified `My Library` during the configuration. The root of the remote is pointing at the root of the library `My Library`:

<pink>See all files in the library:</pink>

rclone lsd seafile:


<pink>Create a new directory inside the library</pink>

rclone mkdir seafile:directory


<pink>List the contents of a directory</pink>

rclone ls seafile:directory


<pink>Sync /home/local/directory to the remote library, deleting any excess files in the library.</pink>

rclone sync --interactive /home/local/directory seafile:


---

## 🧚 --fast-list 🧚

Seafile version 7+ supports `--fast-list` which allows you to use <purple>fewer transactions</purple> in exchange for <purple>more memory</purple>. See the rclone docs for more details. Please note this is <red>not supported on seafile server version 6.x</red> 😭

---

## 💜 Restricted filename characters 💜

In addition to the default restricted characters set the following characters are also replaced:

- `/` — Value `0x2F` — replaced with `／`
- `"` — Value `0x22` — replaced with `＂`
- `\` — Value `0x5C` — replaced with `＼`

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. 💀

---

## 🔗 Seafile and rclone link 🔗

Rclone supports generating share links for <bold>non-encrypted libraries only</bold>. They can either be for a file or a directory:

rclone link seafile:seafile-tutorial.doc http://my.seafile.server/f/fdcd8a2f93f84b8b90f4/


or if run on a directory you will get:

rclone link seafile:dir http://my.seafile.server/d/9ea2455f6f55478bbb0d/


> Please note a share link is unique for each file or directory. If you run a `link` command on a file/dir that has already been shared, you will get the exact same link. 👑

---

## 🎀 Compatibility 🎀

It has been actively developed using the seafile docker image of these versions:

- `6.3.4` community edition
- `7.0.5` community edition
- `7.1.3` community edition
- `9.0.10` community edition

Versions below <red>6.0</red> are not supported. Versions between `6.0` and `6.3` haven't been tested and might not work properly. 🙈

Each new version of rclone is automatically tested against the latest docker image of the seafile community server. ✨

---

## 👑 Standard options 👑

Here are the Standard options specific to seafile (seafile).

### ⭐ --seafile-url

URL of seafile host to connect to.

Properties:

- Config: `url`
- Env Var: `RCLONE_SEAFILE_URL`
- Type: `string`
- Required: `true`
- Examples:
  - `"https://cloud.seafile.com/"`
    - Connect to cloud.seafile.com.

### ⭐ --seafile-user

User name (usually email address).

Properties:

- Config: `user`
- Env Var: `RCLONE_SEAFILE_USER`
- Type: `string`
- Required: `true`

### ⭐ --seafile-pass

Password.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `pass`
- Env Var: `RCLONE_SEAFILE_PASS`
- Type: `string`
- Required: `false`

### ⭐ --seafile-2fa

Two-factor authentication (`true' if the account has 2FA enabled).

Properties:

- Config: `2fa`
- Env Var: `RCLONE_SEAFILE_2FA`
- Type: `bool`
- Default: `false`

### ⭐ --seafile-library

Name of the library.

Leave blank to access all non-encrypted libraries.

Properties:

- Config: `library`
- Env Var: `RCLONE_SEAFILE_LIBRARY`
- Type: `string`
- Required: `false`

### ⭐ --seafile-library-key

Library password (for encrypted libraries only).

Leave blank if you pass it through the command line.

> NB Input to this must be obscured - see `rclone obscure`.

Properties:

- Config: `library_key`
- Env Var: `RCLONE_SEAFILE_LIBRARY_KEY`
- Type: `string`
- Required: `false`

### ⭐ --seafile-auth-token

Authentication token.

Properties:

- Config: `auth_token`
- Env Var: `RCLONE_SEAFILE_AUTH_TOKEN`

- **Type:** string

- **Required:** false

---

## ✨ Advanced options ✨

Okay bestie, this is where the fine-tuning lives 💅 These are the Advanced options specific to seafile (seafile).

### 🔧 `--seafile-create-library`

Should rclone create a library if it doesn't exist? Like, if it's not there, do we make it? 🤔

Properties:

- **Config:** `create_library`
- **Env Var:** `RCLONE_SEAFILE_CREATE_LIBRARY`
- **Type:** bool
- **Default:** `false`

### 🔧 `--seafile-encoding`

The encoding for the backend 🎀

See the encoding section in the overview for more info (iykyk, it's the whole character-set situation).

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_SEAFILE_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,DoubleQuote,BackSlash,Ctl,InvalidUtf8`

### 🔧 `--seafile-description`

Description of the remote — just your cute lil label for it 🏷️

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_SEAFILE_DESCRIPTION`
- **Type:** string
- **Required:** false

---

# 🦋 SFTP 🦋

SFTP is the <hotpink>Secure</hotpink> (or <hotpink>SSH</hotpink>) File Transfer Protocol. Not to be confused with the other one, fr fr. 💖

The SFTP backend can be used with a number of different providers:

- Hetzner Storage Box
- rsync.net

SFTP runs over SSH v2 and is installed as standard with most modern SSH installations. It's giving "already on your machine, no extra setup" ✨

Paths are specified as `remote:path`. If the path does not begin with a `/` it is relative to the home directory of the user. An empty path `remote:` refers to the user's home directory. For example, `rclone lsd remote:` would list the home directory of the user configured in the rclone remote config (i.e `/home/sftpuser`). However, `rclone lsd remote:/` would list the root directory for remote machine (i.e. `/`) 👑

Note that some SFTP servers will need the leading `/` — Synology is a good example of this. rsync.net and Hetzner, on the other hand, requires users to <red>OMIT</red> the leading `/`. So like, know your server bestie, okay? 🙈

Note that by default rclone will try to execute shell commands on the server, see shell access considerations (that whole section is down below, don't worry, we get there 🫶).

## ⚙️ Configuration ⚙️

Here is an example of making an SFTP configuration. First run:

rclone config


This will guide you through an interactive setup process ✨

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / SSH/SFTP \ "sftp" [snip] Storage> sftp SSH host to connect to Choose a number from below, or type in your own value 1 / Connect to example.com \ "example.com" host> example.com SSH username Enter a string value. Press Enter for the default ("$USER"). user> sftpuser SSH port number Enter a signed integer. Press Enter for the default (22). port> SSH password, leave blank to use ssh-agent. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> n Path to unencrypted PEM-encoded private key file, leave blank to use ssh-agent. key_file> Remote config Configuration complete. Options:

type: sftp
host: example.com
user: sftpuser
port:
pass:
key_file: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


This remote is called `remote` and can now be used like this 💅

See all directories in the home directory:

rclone lsd remote:


See all directories in the root directory:

rclone lsd remote:/


Make a new directory:

rclone mkdir remote:path/to/directory


List the contents of a directory:

rclone ls remote:path/to/directory


Sync `/home/local/directory` to the remote directory, deleting any excess files in the directory:

rclone sync --interactive /home/local/directory remote:directory


Mount the remote path `/srv/www-data/` to the local path `/mnt/www-data`:

rclone mount remote:/srv/www-data/ /mnt/www-data


## 🔐 SSH Authentication 🔐

The SFTP remote supports three authentication methods:

- Password
- Key file, including certificate signed keys
- ssh-agent

Key files should be PEM-encoded private key files. For instance `/home/$USER/.ssh/id_rsa`. Only unencrypted OpenSSH or PEM encrypted files are supported. (So like, lock it up or expose it, no in-between bestie 😭)

The key file can be specified in either an external file (`key_file`) or contained within the rclone config file (`key_pem`). If using `key_pem` in the config file, the entry should be on a single line with new line (`\n`) separating lines. i.e.

key_pem = -----BEGIN RSA PRIVATE KEY-----\nMaMbaIXtE\n0gAMbMbaSsd\nMbaass\n-----END RSA PRIVATE KEY-----


This will generate it correctly for `key_pem` for use in the config:

awk '{printf "%s\n", $0}' < ~/.ssh/id_rsa


If you don't specify `pass`, `key_file`, or `key_pem` or `ask_password` then rclone will attempt to contact an ssh-agent. You can also specify `key_use_agent` to force the usage of an ssh-agent. In this case `key_file` or `key_pem` can also be specified to force the usage of a specific key in the ssh-agent 🗝️

Using an ssh-agent is the only way to load encrypted OpenSSH keys at the moment. Periodt.

If you set the `ask_password` option, rclone will prompt for a password when needed and no password has been configured.

## 📜 Certificate-signed keys 📜

With traditional key-based authentication, you configure your private key only, and the public key built into it will be used during the authentication process.

If you have a certificate you may use it to sign your public key, creating a separate SSH user certificate that should be used instead of the plain public key extracted from the private key. Then you must provide the path to the user certificate public key file in `pubkey_file` or the content of the file in `pubkey` ✨

> <yellow>Note:</yellow> This is **not** the traditional public key paired with your private key, typically saved as `/home/$USER/.ssh/id_rsa.pub`. Setting this path in `pubkey_file` will <red>not</red> work. Don't do it bestie, it's a trap 🙈

Example:

[remote] type = sftp host = example.com user = sftpuser key_file = ~/id_rsa pubkey_file = ~/id_rsa-cert.pub


If you concatenate a cert with a private key then you can specify the merged file in both places.

> <yellow>Note:</yellow> the cert must come **first** in the file. e.g.

cat id_rsa-cert.pub id_rsa > merged_key


## 🛡️ Host key validation 🛡️

By default rclone will **not** check the server's host key for validation. This can allow an attacker to replace a server with their own and if you use password authentication then this can lead to that password being exposed. <red>This is the scary part, okay? Like, actually scary. 💀</red>

Host key matching, using standard `known_hosts` files can be turned on by enabling the `known_hosts_file` option. This can point to the file maintained by OpenSSH or can point to a unique file. 👑

e.g. using the OpenSSH `known_hosts` file:

[remote] type = sftp host = example.com user = sftpuser pass = known_hosts_file = ~/.ssh/known_hosts


Alternatively you can create your own known hosts file like this:

ssh-keyscan -t dsa,rsa,ecdsa,ed25519 example.com >> known_hosts


There are some limitations:

- rclone will not manage this file for you. If the key is missing or wrong then the connection will be refused.
- If the server is set up for a certificate host key then the entry in the `known_hosts` file must be the `@cert-authority` entry for the CA

If the host key provided by the server does not match the one in the file (or is missing) then the connection will be aborted and an error returned such as:

NewFs: couldn't connect SSH: ssh: handshake failed: knownhosts: key mismatch

or

NewFs: couldn't connect SSH: ssh: handshake failed: knownhosts: key is unknown


If you see an error such as:

NewFs: couldn't connect SSH: ssh: handshake failed: ssh: no authorities for hostname: example.com:22


then it is likely the server has presented a CA signed host certificate and you will need to add the appropriate `@cert-authority` entry. 🧚

The `known_hosts_file` setting can be set during `rclone config` as an advanced option.

## 🍎 ssh-agent on macOS 🍎

Note that there seem to be various problems with using an ssh-agent on macOS due to recent changes in the OS. The most effective work-around seems to be to start an ssh-agent in each session, e.g.

eval ssh-agent -s && ssh-add -A


And then at the end of the session:

eval ssh-agent -k


These commands can be used in scripts of course. 💅

## 🐚 Shell access 🐚

Some functionality of the SFTP backend relies on remote shell access, and the possibility to execute commands. This includes `checksum`, and in some cases also `about`. The shell commands that must be executed may be different on different type of shells, and also quoting/escaping of file path arguments containing special characters may be different. Rclone therefore needs to know what type of shell it is, and if shell access is available at all. 😤

Most servers run on some version of Unix, and then a basic Unix shell can be assumed, without further distinction. Windows 10, Server 2019, and later can also run a SSH server, which is a port of OpenSSH (see official installation guide). On a Windows server the shell handling is different: Although it can also be set up to use a Unix type shell, e.g. Cygwin bash, the default is to use Windows Command Prompt (`cmd.exe`), and PowerShell is a recommended alternative. All of these have behave differently, which rclone must handle. (Not me being obsessed with how many ways a shell can be a diva 💀)

Rclone tries to auto-detect what type of shell is used on the server, first time you access the SFTP remote. If a remote shell session is successfully created, it will look for indications that it is CMD or PowerShell, with fall-back to Unix if not something else is detected. If unable to even create a remote shell session, then shell command execution will be disabled entirely. The result is stored in the SFTP remote configuration, in option `shell_type`, so that the auto-detection only have to be performed once. If you manually set a value for this option before first run, the auto-detection will be skipped, and if you set a different value later this will override any existing. Value `none` can be set to avoid any attempts at executing shell commands, e.g. if this is not allowed on the server. If you have `shell_type = none` in the configuration then the `ssh` must not be set. 🔥

So when the server is `rclone serve sftp`, your rclone SFTP remote is gonna clock it as a **Unix type shell** — even if it's literally vibing on Windows. No cap. This server doesn't actually *have* a shell bestie, it just accepts input commands that match the specific ones the SFTP backend relies on for Unix shells, like `md5sum` and `df`. It also handles the string escape rules used for Unix shell. So treating it as a Unix type shell from a SFTP remote is **always correct**, and it supports all the features. Slay 💅

## Shell access considerations 🐚

The shell type auto-detection logic (the one we just talked about) means that, by default, rclone will try to run a shell command the very first time you access a new sftp remote. Okay but here's the tea: if you configure a sftp remote **without a config file** — like an on-the-fly remote — rclone has literally nowhere to store the result, so it will re-run that command on *every single access*. Not the vibe. To dodge this, you should explicitly set the `shell_type` option to the correct value, or set it to `none` if you want to stop rclone from executing any remote shell commands at all.

Also super important to note: since the shell type decides how quoting and escaping of file paths used as command-line arguments are performed, configuring the **wrong** shell type may leave you exposed to command injection exploits 😭. So please make sure to confirm the auto-detected shell type, or explicitly set the shell type you *know* is correct, or disable shell access until you know. Your girl is serious about this one.

## Checksum 🔐

SFTP does not natively support checksums (file hash), but rclone is able to use checksumming if the same login has shell access, and can execute remote commands. So if there's a command that can calculate compatible checksums on the remote system, rclone can then be configured to execute this whenever a checksum is needed, and read back the results. Currently <cyan>MD5</cyan> and <cyan>SHA-1</cyan> are supported.

Normally this requires an external utility being available on the server. By default rclone will try the commands `md5sum`, `md5` and `rclone md5sum` for MD5 checksums, and the first one found usable will be picked. Same energy with `sha1sum`, `sha1` and `rclone sha1sum` commands for SHA-1 checksums. These utilities normally need to be in the remote's `PATH` to be found.

In some cases the shell *itself* is capable of calculating checksums. PowerShell is an example of such a shell 👑. If rclone detects that the remote shell is PowerShell — which means it most probably is a Windows OpenSSH server — rclone will use a predefined script block to produce the checksums when no external checksum commands are found (see shell access). This assumes PowerShell version 4.0 or newer.

The options `md5sum_command` and `sha1_command` can be used to customize the command to be executed for calculation of checksums. You can, for example, set a specific path to where `md5sum` and `sha1sum` executables are located, or use them to specify some other tools that print checksums in compatible format. The value can include command-line arguments, or even shell script blocks as with PowerShell. Rclone has subcommands `md5sum` and `sha1sum` that use compatible format, which means if you have an rclone executable on the server it can be used. As mentioned above, they will be automatically picked up if found in `PATH`, but if not you can set something like `/path/to/rclone md5sum` as the value of option `md5sum_command` to make sure a specific executable is used.

Remote checksumming is **recommended and enabled by default** ✨. First time rclone is using a SFTP remote, if options `md5sum_command` or `sha1_command` are not set, it will check if any of the default commands for each of them, as described above, can be used. The result will be saved in the remote configuration, so next time it will use the same. Value `none` will be set if none of the default commands could be used for a specific algorithm, and this algorithm will not be supported by the remote.

Disabling the checksumming may be required if you are connecting to SFTP servers which are **not under your control**, and to which the execution of remote shell commands is prohibited 🙈. Set the configuration option `disable_hashcheck` to `true` to disable checksumming entirely, or set `shell_type` to `none` to disable all functionality based on remote shell command execution.

## Modification times and hashes 🕐

Modified times are stored on the server to **1 second precision**.

Modified times are used in syncing and are **fully supported**.

Some SFTP servers disable setting/modifying the file modification time after upload (for example, certain configurations of ProFTPd with `mod_sftp`). If you are using one of these servers, you can set the option `set_modtime = false` in your rclone backend configuration to disable this behaviour.

## About command 📊

The `about` command returns the total space, free space, and used space on the remote for the disk of the specified path on the remote or, if not set, the disk of the root on the remote.

SFTP usually supports the `about` command, but it depends on the server, ngl. If the server implements the vendor-specific VFS statistics extension — which is normally the case with OpenSSH instances — it will be used. If not, but the same login has access to a Unix shell, where the `df` command is available (e.g. in the remote's `PATH`), then this will be used instead. If the server shell is PowerShell, probably with a Windows OpenSSH server, rclone will use a built-in shell command (see shell access). And if none of the above is applicable, `about` will fail 💀.

## Standard options 🌟

Here are the Standard options specific to sftp (SSH/SFTP).

### `--sftp-host`

SSH host to connect to.

E.g. `"example.com"`.

Properties:

- Config: `host`
- Env Var: `RCLONE_SFTP_HOST`
- Type: `string`
- Required: `true`

### `--sftp-user`

SSH username.

Properties:

- Config: `user`
- Env Var: `RCLONE_SFTP_USER`
- Type: `string`
- Default: `"$USER"`

### `--sftp-port`

SSH port number.

Properties:

- Config: `port`
- Env Var: `RCLONE_SFTP_PORT`
- Type: `int`
- Default: `22`

### `--sftp-pass`

SSH password, leave blank to use ssh-agent.

> NB Input to this must be obscured — see `rclone obscure`.

Properties:

- Config: `pass`
- Env Var: `RCLONE_SFTP_PASS`
- Type: `string`
- Required: `false`

### `--sftp-key-pem`

Raw PEM-encoded private key.

Note that this should be on a single line with line endings replaced with `\n`, eg

key_pem = -----BEGIN RSA PRIVATE KEY-----\nMaMbaIXtE\n0gAMbMbaSsd\nMbaass\n-----END RSA PRIVATE KEY-----


This will generate the single line correctly:

awk '{printf "%s\n", $0}' < ~/.ssh/id_rsa


If specified, it will override the `key_file` parameter.

Properties:

- Config: `key_pem`
- Env Var: `RCLONE_SFTP_KEY_PEM`
- Type: `string`
- Required: `false`

### `--sftp-key-file`

Path to PEM-encoded private key file.

Leave blank or set `key-use-agent` to use ssh-agent.

Leading `~` will be expanded in the file name as will environment variables such as `${RCLONE_CONFIG_DIR}`.

Properties:

- Config: `key_file`
- Env Var: `RCLONE_SFTP_KEY_FILE`
- Type: `string`
- Required: `false`

### `--sftp-key-file-pass`

The passphrase to decrypt the PEM-encoded private key file.

Only PEM encrypted key files (old OpenSSH format) are supported. Encrypted keys in the new OpenSSH format **can't be used**.

> NB Input to this must be obscured — see `rclone obscure`.

Properties:

- Config: `key_file_pass`
- Env Var: `RCLONE_SFTP_KEY_FILE_PASS`
- Type: `string`
- Required: `false`

### `--sftp-pubkey`

SSH public certificate for public certificate based authentication. Set this if you have a signed certificate you want to use for authentication. If specified will override `pubkey_file`.

Properties:

- Config: `pubkey`
- Env Var: `RCLONE_SFTP_PUBKEY`
- Type: `string`
- Required: `false`

### `--sftp-pubkey-file`

Optional path to public key file.

Set this if you have a signed certificate you want to use for authentication.

Leading `~` will be expanded in the file name as will environment variables such as `${RCLONE_CONFIG_DIR}`.

Properties:

- Config: `pubkey_file`
- Env Var: `RCLONE_SFTP_PUBKEY_FILE`
- Type: `string`
- Required: `false`

### `--sftp-key-use-agent`

When set forces the usage of the ssh-agent.

When `key-file` is also set, the `.pub` file of the specified `key-file` is read and only the associated key is requested from the ssh-agent. This allows you to avoid `Too many authentication failures for *username*` errors when the ssh-agent contains many keys 🙏.

Properties:

- Config: `key_use_agent`
- Env Var: `RCLONE_SFTP_KEY_USE_AGENT`
- Type: `bool`
- Default: `false`

### `--sftp-use-insecure-cipher`

Enable the use of insecure ciphers and key exchange methods.

This enables the use of the following insecure ciphers and key exchange methods:

- `aes128-cbc`
- `aes192-cbc`
- `aes256-cbc`
- `3des-cbc`
- `diffie-hellman-group-exchange-sha256`
- `diffie-hellman-group-exchange-sha1`

> Those algorithms are **insecure** and may allow plaintext data to be recovered by an attacker 😱. Like, for real.

This must be `false` if you use either `ciphers` or `key_exchange` advanced options.

Properties:

- Config: `use_insecure_cipher`
- Env Var: `RCLONE_SFTP_USE_INSECURE_CIPHER`
- Type: `bool`
- Default: `false`
- Examples:
  - `"false"`
    - Use default Cipher list.
  - `"true"`
    - Enables the use of the `aes128-cbc` cipher and `diffie-hellman-group-exchange-sha256`, `diffie-hellman-group-exchange-sha1` key exchange.

### `--sftp-disable-hashcheck`

Disable the execution of SSH commands to determine if remote file hashing is available.

Leave blank or set to `false` to enable hashing (recommended), set to `true` to disable hashing.

Properties:

- Config: `disable_hashcheck`
- Env Var: `RCLONE_SFTP_DISABLE_HASHCHECK`
- Type: `bool`
- Default: `false`

### `--sftp-ssh`

Path and arguments to external ssh binary.

Normally rclone will use its internal ssh library to connect to the SFTP server. However it does not implement all possible ssh options so it may be desirable to use an external ssh binary 👀.

Rclone ignores **all** the internal config if you use this option and expects you to configure the ssh binary with the user/host/port and any other options you need.

> **Important** The `ssh` command must log in **without asking for a password**, so it needs to be configured with keys or certificates.

Rclone will run the command supplied either with the additional arguments `"-s sftp"` to access the SFTP subsystem, or with commands such as `"md5sum /path/to/file"` appended to read checksums.

Any arguments with spaces in should be surrounded by `"double quotes"`.

An example setting might be:

ssh -o ServerAliveInterval=20 user@example.com


<pink>Heads up bestie 💖</pink> when you're pointing at an **external** `ssh` binary, rclone spins up a *brand new* ssh connection every single time it needs to calculate a hash. Like, every time. Just so you know 🫶

**Properties:**

- Config: `ssh`
- Env Var: `RCLONE_SFTP_SSH`
- Type: `SpaceSepList`
- Default: *(empty — nothing set by default)*

---

## ✨ Advanced options ✨

Okay so these are the <hotpink>Advanced options</hotpink> that are specific to `sftp` (SSH/SFTP). Extra-special, use-with-intent vibes only 💅

### 🎀 `--sftp-known-hosts-file`

Optional path to a `known_hosts` file. 🌸

Set this value to turn on server host key validation. (Yes, that's the good security stuff ✨)

A leading `~` gets expanded in the file name, and so do environment variables like `${RCLONE_CONFIG_DIR}`.

**Properties:**

- Config: `known_hosts_file`
- Env Var: `RCLONE_SFTP_KNOWN_HOSTS_FILE`
- Type: `string`
- Required: `false`
- Examples:
  - `"~/.ssh/known_hosts"`
    - Use OpenSSH's `known_hosts` file.

### 🎀 `--sftp-ask-password`

Let rclone ask you for the SFTP password when it needs one. 🙈

If this is set and no password got supplied, then rclone will:

- ask for a password
- not contact the ssh agent

**Properties:**

- Config: `ask_password`
- Env Var: `RCLONE_SFTP_ASK_PASSWORD`
- Type: `bool`
- Default: `false`

### 🎀 `--sftp-path-override`

Override the path that SSH shell commands use. 🦋

This is what lets checksum calculation work when the SFTP path and the SSH path are *not* the same thing. This whole situation affects Synology NAS boxes, among others.

E.g. if shared folders live in directories that represent volumes:

rclone sync /home/local/directory remote:/directory --sftp-path-override /volume2/directory


E.g. if the home directory lives in a shared folder called `home`:

rclone sync /home/local/directory remote:/home/directory --sftp-path-override /volume1/homes/USER/directory


If you only wanna specify the path to the SFTP remote's **root**, and let rclone add any relative subpaths by itself (including unwrapping/decrypting remotes when it needs to), just slap the `@` character at the very front of the path 👑

E.g. that first example above could get rewritten as:

rclone sync /home/local/directory remote:/directory --sftp-path-override @/volume2


<purple>Little note:</purple> when you're using this trick with Synology "home" folders, you gotta specify the full `/homes/USER` path instead of `/home`.

E.g. that second example above should get rewritten as:

rclone sync /home/local/directory remote:/homes/USER/directory --sftp-path-override @/volume1


**Properties:**

- Config: `path_override`
- Env Var: `RCLONE_SFTP_PATH_OVERRIDE`
- Type: `string`
- Required: `false`

### 🎀 `--sftp-set-modtime`

Set the modified time on the remote, if it's set. ⏰

**Properties:**

- Config: `set_modtime`
- Env Var: `RCLONE_SFTP_SET_MODTIME`
- Type: `bool`
- Default: `true`

### 🎀 `--sftp-shell-type`

The type of SSH shell on the remote server, if there even is one. 🐚

Leave it blank and it'll autodetect for you.

**Properties:**

- Config: `shell_type`
- Env Var: `RCLONE_SFTP_SHELL_TYPE`
- Type: `string`
- Required: `false`
- Examples:
  - `"none"`
    - No shell access
  - `"unix"`
    - Unix shell
  - `"powershell"`
    - PowerShell
  - `"cmd"`
    - Windows Command Prompt

### 🎀 `--sftp-md5sum-command`

The command used to read md5 hashes. 🔍

Leave it blank to autodetect.

**Properties:**

- Config: `md5sum_command`
- Env Var: `RCLONE_SFTP_MD5SUM_COMMAND`
- Type: `string`
- Required: `false`

### 🎀 `--sftp-sha1sum-command`

The command used to read sha1 hashes. 🔍

Leave it blank to autodetect.

**Properties:**

- Config: `sha1sum_command`
- Env Var: `RCLONE_SFTP_SHA1SUM_COMMAND`
- Type: `string`
- Required: `false`

### 🎀 `--sftp-skip-links`

Set this to skip any symlinks and any other non-regular files. 🙅♀️

**Properties:**

- Config: `skip_links`
- Env Var: `RCLONE_SFTP_SKIP_LINKS`
- Type: `bool`
- Default: `false`

### 🎀 `--sftp-subsystem`

Specifies the SSH2 subsystem on the remote host. 🌈

**Properties:**

- Config: `subsystem`
- Env Var: `RCLONE_SFTP_SUBSYSTEM`
- Type: `string`
- Default: `"sftp"`

### 🎀 `--sftp-server-command`

Specifies the path or command to run an sftp server on the remote host. 🖥️

<purple>Fun fact:</purple> the `subsystem` option gets **ignored** whenever `server_command` is defined.

If you're adding `server_command` to the config file, pls pls pls note that it should **not** be wrapped in quotes, because that will make rclone fail. 💀

A working example is:

[remote_name] type = sftp server_command = sudo /usr/libexec/openssh/sftp-server


**Properties:**

- Config: `server_command`
- Env Var: `RCLONE_SFTP_SERVER_COMMAND`
- Type: `string`
- Required: `false`

### 🎀 `--sftp-use-fstat`

If set, use `fstat` instead of `stat`. 🌸

Some servers cap how many files can be open at once, and calling `Stat` *after* opening a file will make the server throw an error. Turning this flag on will call `Fstat` instead of `Stat`, which runs on a file handle that's **already open**. Iconic workaround, honestly.

Turns out this helps with IBM Sterling SFTP servers that have their "extractability" level set to `1`, which means only 1 file can be open at any given time. 😭

**Properties:**

- Config: `use_fstat`
- Env Var: `RCLONE_SFTP_USE_FSTAT`
- Type: `bool`
- Default: `false`

### 🎀 `--sftp-disable-concurrent-reads`

If set, **don't** use concurrent reads. 🛑

Normally concurrent reads are safe to use, and *not* using them will degrade performance — which is exactly why this option is disabled by default. ✨

Some servers limit how many times a file can be downloaded. Concurrent reads can trip that limit, so if you've got a server that returns:

Failed to copy: file does not exist


...then you may need to enable this flag.

<purple>Heads up:</purple> if concurrent reads are disabled, the `use_fstat` option gets ignored.

**Properties:**

- Config: `disable_concurrent_reads`
- Env Var: `RCLONE_SFTP_DISABLE_CONCURRENT_READS`
- Type: `bool`
- Default: `false`

### 🎀 `--sftp-disable-concurrent-writes`

If set, **don't** use concurrent writes. 🛑

Normally rclone uses concurrent writes to upload files, and honestly it improves the performance *greatly*, especially for distant servers. 📈

This option disables concurrent writes, should that ever be necessary.

**Properties:**

- Config: `disable_concurrent_writes`
- Env Var: `RCLONE_SFTP_DISABLE_CONCURRENT_WRITES`
- Type: `bool`
- Default: `false`

### 🎀 `--sftp-idle-timeout`

Max time before closing idle connections. 💤

If no connections have been returned to the connection pool within the time you gave, rclone will empty the connection pool.

Set it to `0` to keep connections indefinitely. 👑

**Properties:**

- Config: `idle_timeout`
- Env Var: `RCLONE_SFTP_IDLE_TIMEOUT`
- Type: `Duration`
- Default: `1m0s`

### 🎀 `--sftp-chunk-size`

Upload and download chunk size. 📦

This controls the maximum size of the payload in SFTP protocol packets. The RFC limits this to `32768` bytes (32k), which is the default. BUT — a lot of servers support bigger sizes, typically limited to a maximum *total* package size of `256k`, and setting it larger will increase transfer speed **dramatically** on high latency links 🔥. That includes OpenSSH, and, for example, using the value of `255k` works well — it leaves plenty of room for overhead while still staying within a total packet size of `256k`.

> ⚠️ Make sure to test thoroughly before using a value higher than `32k`, and only use it if you always connect to the same server or after sufficiently broad testing. If you get errors such as `"failed to send packet payload: EOF"`, lots of `"connection lost"`, or `"corrupted on transfer"` when copying a larger file, try lowering the value. <pink>The server run by `rclone serve sftp` sends packets with standard `32k` maximum payload so you must not set a different `chunk_size` when downloading files</pink>, but it accepts packets up to the `256k` total size, so for uploads the `chunk_size` can be set as for the OpenSSH example above.

**Properties:**

- Config: `chunk_size`
- Env Var: `RCLONE_SFTP_CHUNK_SIZE`
- Type: `SizeSuffix`
- Default: `32Ki`

### 🎀 `--sftp-concurrency`

The maximum number of outstanding requests for one file. 🚀

This controls the maximum number of outstanding requests for one file. Increasing it will increase throughput on high latency links, at the cost of using more memory.

**Properties:**

- Config: `concurrency`
- Env Var: `RCLONE_SFTP_CONCURRENCY`
- Type: `int`
- Default: `64`

### 🎀 `--sftp-connections`

Maximum number of SFTP simultaneous connections, `0` for unlimited. 🔗

> 💀 Note that setting this is **very likely to cause deadlocks** so it should be used with care.

If you're doing a sync or copy then make sure `connections` is one more than the sum of `--transfers` and `--checkers`.

If you use `--check-first` then it just needs to be one more than the maximum of `--checkers` and `--transfers`.

So for connections `3` you'd use `--checkers 2 --transfers 2 --check-first` or `--checkers 1 --transfers 1`.

**Properties:**

- Config: `connections`
- Env Var: `RCLONE_SFTP_CONNECTIONS`
- Type: `int`
- Default: `0`

### 🎀 `--sftp-set-env`

Environment variables to pass to sftp and commands. 🌍

Set environment variables in the form:

VAR=value


...to be passed to the sftp client and to any commands that get run (eg `md5sum`).

Pass multiple variables space separated, eg

VAR1=value VAR2=value


...and pass variables that have spaces in quotes, eg

"VAR3=value with space" "VAR4=value with space" VAR5=nospacehere


**Properties:**

- Config: `set_env`
- Env Var: `RCLONE_SFTP_SET_ENV`
- Type: `SpaceSepList`
- Default: *(empty — nothing set by default)*

### 🎀 `--sftp-ciphers`

Space separated list of ciphers to be used for session encryption, ordered by preference. 🔐

At least one has to match with the server configuration. You can check this for example using `ssh -Q cipher`.

<purple>Do not set this</purple> if `use_insecure_cipher` is true.

Example:

aes128-ctr aes192-ctr aes256-ctr aes128-gcm@openssh.com aes256-gcm@openssh.com


**Properties:**

- Config: `ciphers`
- Env Var: `RCLONE_SFTP_CIPHERS`
- Type: `SpaceSepList`
- Default: *(empty — nothing set by default)*

### 🎀 `--sftp-key-exchange`

Space separated list of key exchange algorithms, ordered by preference. 🔑✨

At least one has to match with the server configuration. You can check this for example using `ssh -Q kex`.

<purple>Do not set this</purple> if `use_insecure_cipher` is true.

Example:

sntrup761x25519-sha512@openssh.com curve25519-sha256 curve25519-sha256@libssh.org ecdh-sha2-nistp256


**Properties:**

- Config: `key_exchange`
- Env Var: `RCLONE_SFTP_KEY_EXCHANGE`
- Type: `SpaceSepList`
- Default: *(empty — nothing set by default)*

### 🎀 `--sftp-macs`

Space separated list of MACs (message authentication code) algorithms, ordered by preference. 🍓

At least one has to match with the server configuration. You can check this for example using `ssh -Q mac`.

Example:

umac-64-etm@openssh.com umac-128-etm@openssh.com hmac-sha2-256-etm@openssh.com


...and that's the rest of the list, bestie, no cap. ✨ The properties for that one? Slay, here they are:

- **Config:** `macs`
- **Env Var:** `RCLONE_SFTP_MACS`
- **Type:** SpaceSepList
- **Default:** *(empty, she's a blank slate)*

---

- **<hotpink>`--sftp-host-key-algorithms`</hotpink>** — a space separated list of host key algorithms, ordered by preference. 💅

> At least one of them **has to match** with the server configuration, or it's giving absolutely nothing. You can check this, for example, with `ssh -Q HostKeyAlgorithms`.

<lavender>Heads up:</lavender> this can affect the outcome of key negotiation with the server **even if server host key validation is not enabled**. Sneaky like that. 🙈

Example, iconic behaviour:

ssh-ed25519 ssh-rsa ssh-dss


Properties (the receipts 🧾):

- **Config:** `host_key_algorithms`
- **Env Var:** `RCLONE_SFTP_HOST_KEY_ALGORITHMS`
- **Type:** SpaceSepList
- **Default:** *(empty)*

- **<hotpink>`--sftp-socks-proxy`</hotpink>** — the Socks 5 proxy host. 🧦✨

Supports the format `user:pass@host:port`, `user@host:port`, `host:port`.

Example, so you get the vibe:

myUser:myPass@localhost:9005


Properties:

- **Config:** `socks_proxy`
- **Env Var:** `RCLONE_SFTP_SOCKS_PROXY`
- **Type:** string
- **Required:** false

- **<hotpink>`--sftp-copy-is-hardlink`</hotpink>** — set this to enable server side copies using **hardlinks**. 🔗

Okay so the SFTP protocol does **not** define a copy command, which means normally server side copies are just not allowed with the sftp backend. Tragic, I know. 😭

**BUT** — the SFTP protocol *does* support hardlinking, and if you enable this flag then the sftp backend **will** support server side copies. They get implemented by doing a hardlink from the source to the destination. Main character energy fr fr. 👑

Not all sftp servers support this. 💀

<peach>Note:</peach> hardlinking two files together uses **no additional space**, because the source and the destination will be the same file. The way that literally costs you nothing?? Obsessed.

This feature may be useful for backups made with `--copy-dest`.

Properties:

- **Config:** `copy_is_hardlink`
- **Env Var:** `RCLONE_SFTP_COPY_IS_HARDLINK`
- **Type:** bool
- **Default:** false

- **<hotpink>`--sftp-description`</hotpink>** — a description of the remote. Just a lil note-to-self, you know? 🎀

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_SFTP_DESCRIPTION`
- **Type:** string
- **Required:** false

## <rainbow>Limitations</rainbow> 🚧

Not everything can be perfect, bestie, and SFTP has ✨quirks✨:

- On some SFTP servers (e.g. Synology) the paths are different for SSH and SFTP, so the hashes can't be calculated properly. Your two options: use `--sftp-path-override` or `disable_hashcheck`.
- The only ssh agent supported under Windows is Putty's pageant. That's it. That's the list. 🫶
- The Go SSH library disables the use of the `aes128-cbc` cipher by default, due to **security concerns** (as it should 🚩). This can be re-enabled on a per-connection basis by setting the `use_insecure_cipher` setting in the configuration file to `true`. Further details on the insecurity of this cipher can be found in this paper.
- SFTP isn't supported under plan9 until this issue is fixed.
- <yellow>Note:</yellow> since SFTP isn't HTTP based, the following flags **don't work** with it: `--dump-headers`, `--dump-bodies`, `--dump-auth`.
- <mint>Note:</mint> `--timeout` and `--contimeout` are **both supported**. We love a flag that shows up. 💖

## <purple>rsync.net</purple> 🌈

`rsync.net` is supported through the SFTP backend. Simple as that, periodt.

See rsync.net's documentation of rclone examples.

## <purple>Hetzner Storage Box</purple> 📦

Hetzner Storage Boxes are supported through the SFTP backend on **port 23**.

See Hetzner's documentation for details.

---

# <hotpink>SMB</hotpink> 💅

SMB is a communication protocol to share files over network. Yes, the classic.

This relies on the `go-smb2` library for communication with the SMB protocol.

Paths are specified as `remote:sharename` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:item/path/to/dir`.

## <lavender>Notes</lavender> 📝

The **first path segment must be the name of the share** — the one you typed when you started to share on Windows. On `smbd`, it's the section title in `smb.conf` (usually in `/etc/samba/`) file. If you're unsure, you can find shares by querying the root, e.g. `rclone lsd remote:`. Go look, bestie. 🔍

You can't access the shared printers from rclone, obviously. 😭 (rip to the printer girlies)

You can't use Anonymous access for logging in. You have to use the **guest user with an empty password** instead. The rclone client tries to avoid 8.3 names when uploading files by encoding trailing spaces and periods. Alternatively, the local backend on Windows can access SMB servers using UNC paths, by `\\server\share`. This doesn't apply to non-Windows OSes, such as Linux and macOS.

## <lavender>Configuration</lavender> ⚙️✨

Here is an example of making a SMB configuration. It's a whole journey, stay with me.

First run

rclone config


This will guide you through an interactive setup process.

Option host. Samba hostname to connect to. E.g. "example.com". Enter a value. host> localhost

Option user. Samba username. Enter a string value. Press Enter for the default (lesmi). user> guest

Option port. Samba port number. Enter a signed integer. Press Enter for the default (445). port>

Option pass. Samba password. Choose an alternative below. Press Enter for the default (n). y) Yes, type in my own password g) Generate random password n) No, leave this optional password blank (default) y/g/n> g Password strength in bits. 64 is just about memorable 128 is secure 1024 is the maximum Bits> 64 Your password is: XXXX Use this password? Please note that an obscured version of this password (and not the password itself) will be stored under your configuration file, so keep this generated password in a safe place. y) Yes (default) n) No y/n> y

Option domain. Domain name for NTLM authentication. Enter a string value. Press Enter for the default (WORKGROUP). domain>

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

type: samba
host: localhost
user: guest
pass: * ENCRYPTED * Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> d


## <lavender>Standard options</lavender> 👑

Here are the Standard options specific to `smb` (SMB / CIFS).

- **<hotpink>`--smb-host`</hotpink>** — SMB server hostname to connect to.

  E.g. `"example.com"`. 🌐

  Properties:

  - **Config:** `host`
  - **Env Var:** `RCLONE_SMB_HOST`
  - **Type:** string
  - **Required:** true

- **<hotpink>`--smb-user`</hotpink>** — SMB username. 🫶

  Properties:

  - **Config:** `user`
  - **Env Var:** `RCLONE_SMB_USER`
  - **Type:** string
  - **Default:** `"$USER"`

- **<hotpink>`--smb-port`</hotpink>** — SMB port number.

  Properties:

  - **Config:** `port`
  - **Env Var:** `RCLONE_SMB_PORT`
  - **Type:** int
  - **Default:** `445`

- **<hotpink>`--smb-pass`</hotpink>** — SMB password.

  > **NB** Input to this must be obscured — see `rclone obscure`. No plaintext passwords in the group chat, bestie. 🚩

  Properties:

  - **Config:** `pass`
  - **Env Var:** `RCLONE_SMB_PASS`
  - **Type:** string
  - **Required:** false

- **<hotpink>`--smb-domain`</hotpink>** — domain name for NTLM authentication.

  Properties:

  - **Config:** `domain`
  - **Env Var:** `RCLONE_SMB_DOMAIN`
  - **Type:** string
  - **Default:** `"WORKGROUP"`

- **<hotpink>`--smb-spn`</hotpink>** — service principal name.

  Rclone presents this name to the server. Some servers use this as further authentication, and it often needs to be set for clusters. For example:

cifs/remotehost:1020


Leave blank if not sure. It's giving "optional but mysterious" honestly. 🙈

Properties:

- **Config:** `spn`
- **Env Var:** `RCLONE_SMB_SPN`
- **Type:** string
- **Required:** false

## <lavender>Advanced options</lavender> 🧚✨

Here are the Advanced options specific to `smb` (SMB / CIFS).

- **<hotpink>`--smb-idle-timeout`</hotpink>** — max time before closing idle connections. ⏰

If no connections have been returned to the connection pool in the time given, rclone will empty the connection pool.

Set to `0` to keep connections indefinitely.

Properties:

- **Config:** `idle_timeout`
- **Env Var:** `RCLONE_SMB_IDLE_TIMEOUT`
- **Type:** Duration
- **Default:** `1m0s`

- **<hotpink>`--smb-hide-special-share`</hotpink>** — hide special shares (e.g. `print$`) which users aren't supposed to access. 🚫

Properties:

- **Config:** `hide_special_share`
- **Env Var:** `RCLONE_SMB_HIDE_SPECIAL_SHARE`
- **Type:** bool
- **Default:** true

- **<hotpink>`--smb-case-insensitive`</hotpink>** — whether the server is configured to be case-insensitive.

Always `true` on Windows shares. (Windows being Windows, periodt.)

Properties:

- **Config:** `case_insensitive`
- **Env Var:** `RCLONE_SMB_CASE_INSENSITIVE`
- **Type:** bool
- **Default:** true

- **<hotpink>`--smb-encoding`</hotpink>** — the encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_SMB_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot`

- **<hotpink>`--smb-description`</hotpink>** — description of the remote. 🎀

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_SMB_DESCRIPTION`
- **Type:** string
- **Required:** false

---

# <cyan>Storj</cyan> 🦋

Storj is redefining the cloud to support the future of data — sustainably and economically. Storj leverages the vast global supply of underutilized resources to deliver better security, durability, and performance services. Experience up to **90% lower costs** and carbon reduction with Storj. 🌍💚

Storj is an encrypted, secure, and cost-effective object storage service that enables you to store, back up, and archive large amounts of data in a decentralized manner. Decentralized queen behaviour, honestly. 👑

## <mint>Backend options</mint> ⚙️

Storj can be used both with this native backend **and** with the `s3` backend using the Storj S3 compatible gateway (shared or private).

Use **this** backend to take advantage of client-side encryption as well as to achieve the best possible download performance. Uploads will be erasure-coded locally, thus a `1gb` upload will result in `2.68gb` of data being uploaded to storage nodes across the network. 😭 (the bandwidth, bestie)

Use the `s3` backend and one of the S3 compatible Hosted Gateways to increase upload performance and reduce the load on your systems and network. Uploads will be encrypted and erasure-coded server-side, thus a `1GB` upload will result in only in `1GB` of data being uploaded to storage nodes across the network. Way less chaotic. ✨

Side by side comparison with more details:

- **Characteristics:**

- **<green>Storj backend</green>**: uses native RPC protocol, connects directly to the storage nodes which hosts the data. Requires more CPU resource of encoding/decoding and has network amplification (especially during the upload), uses lots of TCP connections 🌈

- **<blue>S3 backend</blue>**: uses S3 compatible HTTP Rest API via the shared gateways. There is no network amplification, but performance depends on the shared gateways and the secret encryption key is shared with the gateway 🔑

- **<purple>Typical usage:</purple>**

- <green>Storj backend</green>: server environments and desktops with enough resources, internet speed and connectivity — and applications where storjs client-side encryption is required 💅
- <blue>S3 backend</blue>: desktops and similar with limited resources, internet speed or connectivity.

- **<purple>Security:</purple>**

- <green>Storj backend</green>: strong. Private encryption key doesn't need to leave the local computer 🔒
- <blue>S3 backend</blue>: weaker. Private encryption key is shared with the authentication service of the hosted gateway, where it's stored encrypted. It can be stronger when combining with the rclone crypt backend.

- **<purple>Bandwidth usage (upload):</purple>**

- <green>Storj backend</green>: higher. As data is erasure coded on the client side both the original data and the parities should be uploaded. About ~2.7 times more data is required to be uploaded. Client may start to upload with even higher number of nodes (~3.7 times more) and abandon/stop the slow uploads. 🚀
- <blue>S3 backend</blue>: normal. Only the raw data is uploaded, erasure coding happens on the gateway.

- **<purple>Bandwidth usage (download)</purple>**

- <green>Storj backend</green>: almost normal. Only the minimal number of data is required, but to avoid very slow data providers a few more sources are used and the slowest are ignored (max 1.2x overhead).
- <blue>S3 backend</blue>: normal. Only the raw data is downloaded, erasure coding happens on the shared gateway.

- **<purple>CPU usage:</purple>**

- <green>Storj backend</green>: higher, but more predictable. Erasure code and encryption/decryption happens locally which requires significant CPU usage. 🔥
- <blue>S3 backend</blue>: less. Erasure code and encryption/decryption happens on shared s3 gateways (and as is, it depends on the current load on the gateways)

- **<purple>TCP connection usage:</purple>**

- <green>Storj backend</green>: high. A direct connection is required to each of the Storj nodes resulting in 110 connections on upload and 35 on download per 64 MB segment. Not all the connections are actively used (slow ones are pruned), but they are all opened. Adjusting the max open file limit may be required. 😭
- <blue>S3 backend</blue>: normal. Only one connection per download/upload thread is required to the shared gateway.

- **<purple>Overall performance:</purple>**

- <green>Storj backend</green>: with enough resources (CPU and bandwidth) storj backend can provide even 2x better performance. Data is directly downloaded to / uploaded from to the client instead of the gateway. 👑
- <blue>S3 backend</blue>: Can be faster on edge devices where CPU and network bandwidth is limited as the shared S3 compatible gateways take care about the encrypting/decryption and erasure coding and no download/upload amplification.

- **<purple>Decentralization:</purple>**

- <green>Storj backend</green>: high. Data is downloaded directly from the distributed cloud of storage providers. 🌈
- <blue>S3 backend</blue>: low. Requires a running S3 gateway (either self-hosted or Storj-hosted).

- **<purple>Limitations:</purple>**

- <green>Storj backend</green>: rclone checksum is not possible without download, as checksum metadata is not calculated during upload
- <blue>S3 backend</blue>: secret encryption key is shared with the gateway

---

# ✨ Configuration ✨

okay bestie, to make a new Storj configuration you need **one of the following**: 🎀

- Access Grant that someone else shared with you.
- API Key of a Storj project you are a member of.

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process: 💅

## 🌸 Setup with access grant 🌸

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Storj Decentralized Cloud Storage \ "storj" [snip] Storage> storj ** See help for storj backend at: https://rclone.org/storj/ **

type: storj
access_grant: your-access-grant-received-by-someone-else Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


## 🦋 Setup with API key and passphrase 🦋

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Storj Decentralized Cloud Storage \ "storj" [snip] Storage> storj ** See help for storj backend at: https://rclone.org/storj/ **

Choose an authentication method. Enter a string value. Press Enter for the default ("existing"). Choose a number from below, or type in your own value 1 / Use an existing access grant. \ "existing" 2 / Create a new access grant from satellite address, API key, and passphrase. \ "new" provider> new Satellite Address. Custom satellite address should match the format: <nodeid>@<address>:<port>. Enter a string value. Press Enter for the default ("us1.storj.io"). Choose a number from below, or type in your own value 1 / US1 \ "us1.storj.io" 2 / EU1 \ "eu1.storj.io" 3 / AP1 \ "ap1.storj.io" satellite_address> 1 API Key. Enter a string value. Press Enter for the default (""). api_key> your-api-key-for-your-storj-project Encryption Passphrase. To access existing objects enter passphrase used for uploading. Enter a string value. Press Enter for the default (""). passphrase> your-human-readable-encryption-passphrase Remote config Configuration complete. Options:

type: storj
satellite_address: 12EayRS2V1kEsWESU9QMRseFhdxYxKicsiFmxrsLZHeLUtdps3S@us1.storj.io:7777
api_key: your-api-key-for-your-storj-project
passphrase: your-human-readable-encryption-passphrase
access_grant: the-access-grant-generated-from-the-api-key-and-passphrase Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


---

# ⭐ Standard options ⭐

Here are the Standard options specific to storj (Storj Decentralized Cloud Storage). ✨

## 💖 `--storj-provider`

Choose an authentication method.

Properties:

- **Config:** `provider`
- **Env Var:** `RCLONE_STORJ_PROVIDER`
- **Type:** string
- **Default:** `"existing"`
- **Examples:**
  - `"existing"`
    - Use an existing access grant.
  - `"new"`
    - Create a new access grant from satellite address, API key, and passphrase.

## 💖 `--storj-access-grant`

Access grant.

Properties:

- **Config:** `access_grant`
- **Env Var:** `RCLONE_STORJ_ACCESS_GRANT`
- **Provider:** `existing`
- **Type:** string
- **Required:** false

## 💖 `--storj-satellite-address`

Satellite address.

Custom satellite address should match the format: `<nodeid>@<address>:<port>`. 🌸

Properties:

- **Config:** `satellite_address`
- **Env Var:** `RCLONE_STORJ_SATELLITE_ADDRESS`
- **Provider:** `new`
- **Type:** string
- **Default:** `"us1.storj.io"`
- **Examples:**
  - `"us1.storj.io"`
    - US1
  - `"eu1.storj.io"`
    - EU1
  - `"ap1.storj.io"`
    - AP1

## 💖 `--storj-api-key`

API key.

Properties:

- **Config:** `api_key`
- **Env Var:** `RCLONE_STORJ_API_KEY`
- **Provider:** `new`
- **Type:** string
- **Required:** false

## 💖 `--storj-passphrase`

Encryption passphrase.

To access existing objects enter passphrase used for uploading. 🔐

Properties:

- **Config:** `passphrase`
- **Env Var:** `RCLONE_STORJ_PASSPHRASE`
- **Provider:** `new`
- **Type:** string
- **Required:** false

---

# 🔥 Advanced options 🔥

Here are the Advanced options specific to storj (Storj Decentralized Cloud Storage). 💅

## 🎀 `--storj-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_STORJ_DESCRIPTION`
- **Type:** string
- **Required:** false

---

# 🌈 Usage 🌈

Paths are specified as `remote:bucket` (or `remote:` for the `lsf` command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`. 🗂️

Once configured you can then use rclone like this. ✨

## 🧚 Create a new bucket 🧚

Use the `mkdir` command to create new bucket, e.g. `bucket`.

rclone mkdir remote:bucket


## 🧚 List all buckets 🧚

Use the `lsf` command to list all buckets.

rclone lsf remote:


> Note the colon (`:`) character at the end of the command line. 👀

## 🧚 Delete a bucket 🧚

Use the `rmdir` command to delete an empty bucket.

rclone rmdir remote:bucket


Use the `purge` command to delete a non-empty bucket with all its content. 💀

rclone purge remote:bucket


## 🧚 Upload objects 🧚

Use the `copy` command to upload an object.

rclone copy --progress /home/local/directory/file.ext remote:bucket/path/to/dir/


The `--progress` flag is for displaying progress information. Remove it if you don't need this information.

Use a folder in the local path to upload all its objects. 📂

rclone copy --progress /home/local/directory/ remote:bucket/path/to/dir/


Only the files that actually changed get copied, bestie — everything else just chills 💅

---

## ✨ List objects ✨

Wanna see everything in a bucket, recursively? The `ls` command is your girl:

rclone ls remote:bucket


Chuck a folder onto the remote path and it'll recurse through just that folder instead:

rclone ls remote:bucket/path/to/dir/


And when you want it *not* recursive, just the top layer? That's `lsf` energy:

rclone lsf remote:bucket/path/to/dir/


---

## 🌸 Download objects 🌸

`copy` isn't just for uploading, she's bidirectional and she's thriving. Grabbing a single object:

rclone copy --progress remote:bucket/path/to/dir/file.ext /home/local/directory/


The `--progress` flag is the one showing you that little live progress display 🫶 Remove it if you truly don't need the tea.

Point it at a folder in the remote path and it'll pull down every object inside:

rclone copy --progress remote:bucket/path/to/dir/ /home/local/directory/


---

## 🦋 Delete objects 🦋

One single object, one single command — `deletefile`:

rclone deletefile remote:bucket/path/to/dir/file.ext


Whole folder of objects? `delete` has you:

rclone delete remote:bucket/path/to/dir/


---

## 🎀 Print the total size of objects 🎀

Want the receipts on how much space a bucket or folder is eating? `size` will tell you:

rclone size remote:bucket/path/to/dir/


---

## ⭐ Sync two Locations ⭐

`sync` makes the source match the destination — it changes the **destination only**, and it deletes any excess files that are just vibing there with no source counterpart. Periodt.

rclone sync --interactive --progress /home/local/directory/ remote:bucket/path/to/dir/


`--progress` is doing the progress-display thing again. Not your vibe? Drop it 💅

> ⚠️ Okay bestie, listen, because this one is *serious*: this can cause **data loss**. Test first with the `--dry-run` flag so you can see exactly what would get copied and what would get deleted before any of it actually happens. No cap.

The sync can also run the other way, Storj → your local file system:

rclone sync --interactive --progress remote:bucket/path/to/dir/ /home/local/directory/


Or between two Storj buckets, which is honestly iconic:

rclone sync --interactive --progress remote-us:bucket/path/to/dir/ remote-europe:bucket/path/to/dir/


Or even between a totally different cloud storage and Storj:

rclone sync --interactive --progress s3:bucket/path/to/dir/ storj:bucket/path/to/dir/


---

## 💀 Limitations 💀

`rclone about` is **not supported** by the rclone Storj backend, sorry. And backends without that capability can't figure out free space for an `rclone mount`, nor can they use policy `mfs` (most free space) as a member of an rclone union remote 🥲

See List of backends that do not support `rclone about` and `rclone about`

---

## 😭 Known issues 😭

If you're catching errors like `too many open files`, that's usually what happens when the default `ulimit` for system max open files gets blown past. Native Storj protocol opens a *lot* of TCP connections — and every single one of them counts as an open file, which is giving chaos honestly.

For a single upload stream you can expect **110 TCP connections** to be opened. For a single download stream you can expect **35**. This whole batch of connections gets opened for every **64 MiB** segment, and you should also expect TCP connections to be reused. And if you do many transfers, eventually you open a connection to most storage nodes — we're talking thousands of nodes 🌈

To fix it, please raise your system limits. You can do it by issuing a `ulimit -n 65536` right before you run rclone. Want it more permanent? Add that to your shell startup script, e.g. `$HOME/.bashrc`, or change the system-wide configuration — usually `/etc/sysctl.conf` and/or `/etc/security/limits.conf` — but please refer to your operating system manual for that part 💜

---

# 👑 SugarSync 👑

SugarSync is a cloud service that enables active synchronization of files across computers and other devices for file backup, access, syncing, and sharing.

---

## 🎀 Configuration 🎀

The initial setup for SugarSync involves getting a token from SugarSync, and you can do that with rclone. `rclone config` literally walks you through it, hand in hand 🫶

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/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 / Sugarsync \ "sugarsync" [snip] Storage> sugarsync ** See help for sugarsync backend at: https://rclone.org/sugarsync/ **

Sugarsync App ID. Leave blank to use rclone's. Enter a string value. Press Enter for the default (""). app_id> Sugarsync Access Key ID. Leave blank to use rclone's. Enter a string value. Press Enter for the default (""). access_key_id> Sugarsync Private Access Key Leave blank to use rclone's. Enter a string value. Press Enter for the default (""). private_access_key> Permanently delete files if true otherwise put them in the deleted files. Enter a boolean value (true or false). Press Enter for the default ("false"). hard_delete> Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config Username (email address)> nick@craig-wood.com Your Sugarsync password is only required during setup and will not be stored. password: Configuration complete. Options:

type: sugarsync
refresh_token: https://api.sugarsync.com/app-authorization/XXXXXXXXXXXXXXXXXX Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Heads up: the config asks for your email and password, but it does **not** store them. It only uses them to get that initial token 🔐

Once it's configured you can run rclone like this:

List directories (sync folders) in top level of your SugarSync:

rclone lsd remote:


List all the files in your SugarSync folder "Test":

rclone ls remote:Test


To copy a local directory to an SugarSync folder called backup:

rclone copy /home/source remote:backup


Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

NB you can't create files in the top level folder — you have to create a folder, which rclone will create as a "Sync Folder" with SugarSync 🌸

---

## ✨ Modification times and hashes ✨

SugarSync does not support modification times or hashes, therefore syncing will default to `--size-only` checking. Note that using `--update` *will* work, since rclone can read the time files were uploaded 👑

---

## 💅 Restricted filename characters 💅

SugarSync replaces the default restricted characters set **except for DEL**.

Invalid UTF-8 bytes will also be replaced, as they can't be used in XML strings.

---

## 🦋 Deleting files 🦋

Deleted files will be moved to the "Deleted items" folder by default.

However you can supply the flag `--sugarsync-hard-delete` or set the config parameter `hard_delete = true` if you would like files to be deleted straight away 💀

---

## ⭐ Standard options ⭐

Here are the Standard options specific to sugarsync (Sugarsync).

### `--sugarsync-app-id`

Sugarsync App ID.

Leave blank to use rclone's.

Properties:

- <pink>Config:</pink> `app_id`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_APP_ID`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-access-key-id`

Sugarsync Access Key ID.

Leave blank to use rclone's.

Properties:

- <pink>Config:</pink> `access_key_id`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_ACCESS_KEY_ID`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-private-access-key`

Sugarsync Private Access Key.

Leave blank to use rclone's.

Properties:

- <pink>Config:</pink> `private_access_key`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_PRIVATE_ACCESS_KEY`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-hard-delete`

Permanently delete files if true otherwise put them in the deleted files.

Properties:

- <pink>Config:</pink> `hard_delete`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_HARD_DELETE`
- <pink>Type:</pink> bool
- <pink>Default:</pink> false

---

## 👑 Advanced options 👑

Here are the Advanced options specific to sugarsync (Sugarsync).

### `--sugarsync-refresh-token`

Sugarsync refresh token.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `refresh_token`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_REFRESH_TOKEN`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-authorization`

Sugarsync authorization.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `authorization`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_AUTHORIZATION`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-authorization-expiry`

Sugarsync authorization expiry.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `authorization_expiry`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_AUTHORIZATION_EXPIRY`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-user`

Sugarsync user.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `user`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_USER`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-root-id`

Sugarsync root id.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `root_id`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_ROOT_ID`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-deleted-id`

Sugarsync deleted folder id.

Leave blank normally, will be auto configured by rclone.

Properties:

- <pink>Config:</pink> `deleted_id`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_DELETED_ID`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

### `--sugarsync-encoding`

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- <pink>Config:</pink> `encoding`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_ENCODING`
- <pink>Type:</pink> Encoding
- <pink>Default:</pink> `Slash,Ctl,InvalidUtf8,Dot`

### `--sugarsync-description`

Description of the remote.

Properties:

- <pink>Config:</pink> `description`
- <pink>Env Var:</pink> `RCLONE_SUGARSYNC_DESCRIPTION`
- <pink>Type:</pink> string
- <pink>Required:</pink> false

---

## 💜 Limitations 💜

`rclone about` is **not supported** by the SugarSync backend 🥲 and backends without this capability cannot determine free space for an `rclone mount` or use policy `mfs` (most free space) as a member of an `rclone union remote`.

See List of backends that do not support `rclone about` and `rclone about`

## 💾 Uloz.to 💾

<pink>Paths are specified as</pink> `remote:path`

<pink>Paths may be as deep as required</pink>, e.g. `remote:directory/subdirectory`.

The initial setup for Uloz.to is <purple>lowkey just filling in your user credentials</purple> — and bestie, `rclone config` walks you through every single step of it.

### 🎀 Configuration 🎀

Here's a whole example of how to make a remote called `remote`. First run:

rclone config


This guides you through an interactive setup process:

Option app_token. The application token identifying the app. An app API key can be either found in the API doc https://uloz.to/upload-resumable-api-beta or obtained from customer service. Enter a value. Press Enter to leave empty. app_token> token_value

Option username. The username of the principal to operate as. Enter a value. Press Enter to leave empty. username> user

Option password. The password for the user. Choose an alternative below. Press Enter for the default (n). y) Yes, type in my own password g) Generate random password n) No, leave this optional password blank (default) y/g/n> y Enter the password: password: Confirm the password: password:

Edit advanced config? y) Yes n) No (default) y/n> n

Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y


Once it's configured you can just use rclone like this, <hotpink>no cap</hotpink>:

List folders in root level folder:

rclone lsd remote:


List all the files in your root folder:

rclone ls remote:


To copy a local folder to a Uloz.to folder called `backup`:

rclone copy /home/source remote:backup


### 🔐 User credentials 🔐

The <bold>only reliable method</bold> is to authenticate the user using username and password. Uloz.to offers an API key as well, but it's reserved for the use of Uloz.to's in-house application, and using it in different circumstances is <red>unreliable</red>. So like… don't, bestie. 💅

### 🕰️ Modification times and hashes 🕰️

Uloz.to doesn't let the user set a custom modification time, or retrieve the hashes after upload. <italic>So what does the integration do?</italic> It uses a free form field that the API provides to encode client-provided timestamps and hashes. Timestamps are stored with microsecond precision. ✨

A server calculated MD5 hash of the file is verified upon upload. Afterwards, the backend only serves the client-side calculated hashes. Hashes can also be retrieved upon creating a file download link, but it's impractical for list-like use cases.

### 🚫 Restricted filename characters 🚫

In addition to the default restricted characters set, the following characters are also replaced:

- `` \ `` — value `0x5C` — replaced with `＼`

Invalid UTF-8 bytes will also be replaced, since they can't be used in JSON strings.

### 📤 Transfers 📤

All files are currently uploaded using a single HTTP request, so for uploading large files a <yellow>stable connection is necessary</yellow>. Rclone will upload up to `--transfers` chunks at the same time (shared among all uploads).

### 🗑️ Deleting files 🗑️

By default, files are moved to the recycle bin, whereas folders are deleted <red>immediately</red>. Trashed files are permanently deleted after 30 days in the recycle bin.

Emptying the trash is currently <italic>not implemented</italic> in rclone.

### 📁 Root folder ID 📁

You can set the `root_folder_slug` for rclone. This is the folder (identified by its Folder slug) that rclone considers to be the root of your Uloz.to drive.

Normally you will leave this blank and rclone will determine the correct root to use itself. However you can set this to restrict rclone to a specific folder hierarchy.

In order to do this you will have to find the Folder slug of the folder you wish to use as root. This will be the last segment of the URL when you open the relevant folder in the Uloz.to web interface.

For example, for exploring a folder with URL `https://uloz.to/fm/my-files/foobar`, `foobar` should be used as the root slug.

`root_folder_slug` can be used alongside a specific path in the remote path. For example, if your remote's `root_folder_slug` corresponds to `/foo/bar`, `remote:baz/qux` will refer to `ABSOLUTE_ULOZTO_ROOT/foo/bar/baz/qux`.

---

### ⭐ Standard options ⭐

Here are the Standard options specific to ulozto (Uloz.to).

#### –ulozto-app-token

The application token identifying the app. An app API key can be either found in the API doc `https://uloz.to/upload-resumable-api-beta` or obtained from customer service.

Properties:

- Config: `app_token`
- Env Var: `RCLONE_ULOZTO_APP_TOKEN`
- Type: `string`
- Required: `false`

#### –ulozto-username

The username of the principal to operate as.

Properties:

- Config: `username`
- Env Var: `RCLONE_ULOZTO_USERNAME`
- Type: `string`
- Required: `false`

#### –ulozto-password

The password for the user.

> NB: Input to this must be obscured — see `rclone obscure`.

Properties:

- Config: `password`
- Env Var: `RCLONE_ULOZTO_PASSWORD`
- Type: `string`
- Required: `false`

### 💅 Advanced options 💅

Here are the Advanced options specific to ulozto (Uloz.to).

#### –ulozto-root-folder-slug

If set, rclone will use this folder as the root folder for all operations. For example, if the slug identifies `` `foo/bar/' ``, `` `ulozto:baz' `` is equivalent to `` `ulozto:foo/bar/baz' `` without any root slug set.

Properties:

- Config: `root_folder_slug`
- Env Var: `RCLONE_ULOZTO_ROOT_FOLDER_SLUG`
- Type: `string`
- Required: `false`

#### –ulozto-list-page-size

The size of a single page for list commands. `1-500`

Properties:

- Config: `list_page_size`
- Env Var: `RCLONE_ULOZTO_LIST_PAGE_SIZE`
- Type: `int`
- Default: `500`

#### –ulozto-encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_ULOZTO_ENCODING`
- Type: `Encoding`
- Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

#### –ulozto-description

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_ULOZTO_DESCRIPTION`
- Type: `string`
- Required: `false`

---

### ⚠️ Limitations ⚠️

Uloz.to file names can't have the `\` character in. rclone maps this to and from an identical looking unicode equivalent `＼` (`U+FF3C` Fullwidth Reverse Solidus).

Uloz.to only supports filenames up to <bold>255 characters</bold> in length.

Uloz.to rate limits access to the API, but exact details are <italic>undisclosed</italic>. Practical testing reveals that hitting the rate limit during normal use is very rare, although not impossible with higher number of concurrently uploaded files.

`rclone about` is <red>not supported</red> by the Uloz.to backend. Although there's an endpoint to retrieve the information for the UI, it's not exposed in the API. Backends without this capability cannot determine free space for an rclone mount or use policy `mfs` (most free space) as a member of an rclone union remote.

See List of backends that do not support rclone about and `rclone about` 🦋

## ✨ Uptobox ✨

Okay bestie, this one's a Backend for the Uptobox file storage service. Heads up tho — Uptobox is <hotpink>closer to a one-click hoster than a traditional cloud storage provider</hotpink>, which means it is **NOT** suitable for long term storage. Like, not even a little. 🫠

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

---

### 🎀 Configuration

To configure an Uptobox backend you'll need your personal api token. You'll find it in your account settings 💖

Here is an example of how to make a remote called `remote` with the default setup. First run:

rclone config


This will guide you through an interactive setup process:

Current remotes:

Name Type ==== ==== TestUptobox uptobox

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> uptobox 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 [...] 37 / Uptobox \ "uptobox" [...] Storage> uptobox ** See help for uptobox backend at: https://rclone.org/uptobox/ **

Your API Key, get it from https://uptobox.com/my_account Enter a string value. Press Enter for the default (""). api_key> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Edit advanced config? (y/n) y) Yes n) No (default) y/n> n Remote config

[uptobox] type = uptobox api_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>


Once configured you can then use rclone like this,

List directories in top level of your Uptobox ✨

rclone lsd remote:


List all the files in your Uptobox 🌸

rclone ls remote:


To copy a local directory to an Uptobox directory called `backup`

rclone copy /home/source remote:backup


---

### 🕐 Modification times and hashes

Uptobox supports **neither** modified times nor checksums, bestie. 😭 All timestamps will read as that set by `--default-time`.

---

### 🚫 Restricted filename characters

In addition to the default restricted characters set the following characters are also replaced:

- `”` — value `0x22` — replacement `＂`
- `` ` `` — value `0x41` — replacement `｀`

Invalid UTF-8 bytes will also be replaced, as they can't be used in XML strings. 💅

---

### 🌟 Standard options

Here are the Standard options specific to uptobox (Uptobox).

- **`--uptobox-access-token`** — Your access token.

  Get it from https://uptobox.com/my_account.

  Properties:

  - Config: `access_token`
  - Env Var: `RCLONE_UPTOBOX_ACCESS_TOKEN`
  - Type: string
  - Required: false

---

### 👑 Advanced options

Here are the Advanced options specific to uptobox (Uptobox).

- **`--uptobox-private`** — Set to make uploaded files private

  Properties:

  - Config: `private`
  - Env Var: `RCLONE_UPTOBOX_PRIVATE`
  - Type: bool
  - Default: `false`

- **`--uptobox-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_UPTOBOX_ENCODING`
  - Type: Encoding
  - Default: `Slash,LtGt,DoubleQuote,BackQuote,Del,Ctl,LeftSpace,InvalidUtf8,Dot`

- **`--uptobox-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_UPTOBOX_DESCRIPTION`
  - Type: string
  - Required: false

---

### ⚠️ Limitations

Uptobox will **delete inactive files that have not been accessed in 60 days**. Not a drill, bestie. 🫣

`rclone about` is not supported by this backend — an overview of used space can however been seen in the uptobox web interface.

---

## 💫 Union 💫

The union backend joins several remotes together to make a single unified view of them. Genuinely iconic behaviour ngl. 💜

During the initial setup with `rclone config` you will specify the upstream remotes as a space separated list. The upstream remotes can either be a local paths or other remotes.

The attributes `:ro`, `:nc` and `:writeback` can be attached to the end of the remote to tag the remote as read only, no create or writeback, e.g. `remote:directory/subdirectory:ro` or `remote:directory/subdirectory:nc`.

- `:ro` means files will only be read from here and never written
- `:nc` means new files or directories won't be created here
- `:writeback` means files found in different remotes will be written back here. See the writeback section for more info.

Subfolders can be used in upstream remotes. Assume a union remote named `backup` with the remotes `mydrive:private/backup`. Invoking `rclone mkdir backup:desktop` is exactly the same as invoking `rclone mkdir mydrive:private/backup/desktop`.

There is **no special handling** of paths containing `..` segments. Invoking `rclone mkdir backup:../desktop` is exactly the same as invoking `rclone mkdir mydrive:private/backup/../desktop`. 🫶

---

### 🎀 Configuration

Here is an example of how to make a union called `remote` for local folders. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Union merges the contents of several remotes \ "union" [snip] Storage> union List of space separated upstreams. Can be 'upstreama:test/dir upstreamb:', '"upstreama:test/space:ro dir" upstreamb:', etc. Enter a string value. Press Enter for the default (""). upstreams> remote1:dir1 remote2:dir2 remote3:dir3 Policy to choose upstream on ACTION class. Enter a string value. Press Enter for the default ("epall"). action_policy> Policy to choose upstream on CREATE class. Enter a string value. Press Enter for the default ("epmfs"). create_policy> Policy to choose upstream on SEARCH class. Enter a string value. Press Enter for the default ("ff"). search_policy> Cache time of usage and free space (in seconds). This option is only useful when a path preserving policy is used. Enter a signed integer. Press Enter for the default ("120"). cache_time> Remote config Configuration complete. Options:

type: union
upstreams: remote1:dir1 remote2:dir2 remote3:dir3 Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y Current remotes:

Name Type ==== ==== remote union

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> q


Once configured you can then use rclone like this,

List directories in top level in `remote1:dir1`, `remote2:dir2` and `remote3:dir3` ✨

rclone lsd remote:


List all the files in `remote1:dir1`, `remote2:dir2` and `remote3:dir3` 🌈

rclone ls remote:


Copy another local directory to the union directory called `source`, which will be placed into `remote3:dir3`

rclone copy C:\source remote:source


---

### 🧠 Behavior / Policies

The behavior of union backend is inspired by trapexit/mergerfs. All functions are grouped into 3 categories: **action**, **create** and **search**. These functions and categories can be assigned a policy which dictates what file or directory is chosen when performing that behavior. Any policy can be assigned to a function or category though some may not be very useful in practice. For instance: `rand` (random) may be useful for file creation (create) but could lead to **very odd behavior** if used for delete if there were more than one copy of the file. 😭

---

### 📊 Function / Category classifications

- **action** — Writing Existing file — Functions: `move`, `rmdir`, `rmdirs`, `delete`, `purge` and `copy`, `sync` (as destination when file exist)
- **create** — Create non-existing file — Functions: `copy`, `sync` (as destination when file not exist)
- **search** — Reading and listing file — Functions: `ls`, `lsd`, `lsl`, `cat`, `md5sum`, `sha1sum` and `copy`, `sync` (as source)
- **N/A** — Functions: `size`, `about`

---

### 🛤️ Path Preservation

Policies, as described below, are of two basic types: **path preserving** and **non-path preserving**.

All policies which start with `ep` (`epff`, `eplfs`, `eplus`, `epmfs`, `eprand`) are path preserving. `ep` stands for **existing path**.

A path preserving policy will only consider upstreams where the relative path being accessed already exists.

When using non-path preserving policies paths will be created in target upstreams as necessary.

---

### 📉 Quota Relevant Policies

Some policies rely on quota information. These policies should be used **only** if your upstreams support the respective quota fields.

- `lfs`, `eplfs` — Required Field: `Free`
- `mfs`, `epmfs` — Required Field: `Free`
- `lus`, `eplus` — Required Field: `Used`
- `lno`, `eplno` — Required Field: `Objects`

To check if your upstream supports the field, run `rclone about remote: [flags]` and see if the required field exists. 💅

---

### 🔍 Filters

Policies basically search upstream remotes and create a list of files / paths for functions to work on. The policy is responsible for filtering and sorting. The policy type defines the sorting but filtering is mostly uniform as described below.

- No search policies filter.
- All action policies will filter out remotes which are tagged as **read-only**.
- All create policies will filter out remotes which are tagged **read-only** or **no-create**.

If all remotes are filtered an error will be returned. 🫠

## ✨ Policy descriptions ✨

The policy definitions are inspired by <purple>trapexit/mergerfs</purple> but not exactly the same, okay bestie? Some policy definitions could be different because remote file systems have *way* bigger latency. Not a vibe, just physics. 💫

- **`all`** — Search category: same as `epall`. Action category: same as `epall`. Create category: act on all upstreams.
- **`epall`** (existing path, all) — Search category: given this order configured, act on the first one found where the relative path exists. Action category: apply to all found. Create category: act on all upstreams where the relative path exists.
- **`epff`** (existing path, first found) — Act on the first one found, by the time upstreams reply, where the relative path exists.
- **`eplfs`** (existing path, least free space) — Of all the upstreams on which the relative path exists choose the one with the least free space.
- **`eplus`** (existing path, least used space) — Of all the upstreams on which the relative path exists choose the one with the least used space.
- **`eplno`** (existing path, least number of objects) — Of all the upstreams on which the relative path exists choose the one with the least number of objects.
- **`epmfs`** (existing path, most free space) — Of all the upstreams on which the relative path exists choose the one with the most free space.
- **`eprand`** (existing path, random) — Calls `epall` and then randomizes. Returns only one upstream.
- **`ff`** (first found) — Search category: same as `epff`. Action category: same as `epff`. Create category: act on the first one found by the time upstreams reply.
- **`lfs`** (least free space) — Search category: same as `eplfs`. Action category: same as `eplfs`. Create category: pick the upstream with the least available free space.
- **`lus`** (least used space) — Search category: same as `eplus`. Action category: same as `eplus`. Create category: pick the upstream with the least used space.
- **`lno`** (least number of objects) — Search category: same as `eplno`. Action category: same as `eplno`. Create category: pick the upstream with the least number of objects.
- **`mfs`** (most free space) — Search category: same as `epmfs`. Action category: same as `epmfs`. Create category: pick the upstream with the most available free space.
- **`newest`** — Pick the file / directory with the largest mtime.
- **`rand`** (random) — Calls `all` and then randomizes. Returns only one upstream.

## 🎀 Writeback 🎀

The tag `:writeback` on an upstream remote can be used to make a simple cache system, like exactly this:

[union] type = union action_policy = all create_policy = all search_policy = ff upstreams = /local:writeback remote:dir


When files are opened for read, if the file is in `remote:dir` but **not** in `/local`, then rclone will copy the file *entirely* into `/local` before returning a reference to the file in `/local`. That copy is done with the equivalent of `rclone copy`, so it will use `--multi-thread-streams` if you configured it. Any copies get logged with an `INFO` log. 📝

When files are written, they get written to **both** `remote:dir` and `/local`.

You can add as many remotes as you want to `upstreams`, but there should only be **one** `:writeback` tag. One. Singular. 💅

> Rclone does not manage the `:writeback` remote in any way other than writing files back to it. So if you need to expire old files or manage the size, bestie, that's on you. You have to do this yourself. 😭

## ✨ Standard options ✨

Here are the Standard options specific to `union` (Union merges the contents of several upstream fs).

### `--union-upstreams`

List of space separated upstreams.

Can be `upstreama:test/dir upstreamb:`, `“upstreama:test/space:ro dir” upstreamb:`, etc.

Properties:

- **Config:** `upstreams`
- **Env Var:** `RCLONE_UNION_UPSTREAMS`
- **Type:** string
- **Required:** true

### `--union-action-policy`

Policy to choose upstream on ACTION category.

Properties:

- **Config:** `action_policy`
- **Env Var:** `RCLONE_UNION_ACTION_POLICY`
- **Type:** string
- **Default:** `“epall”`

### `--union-create-policy`

Policy to choose upstream on CREATE category.

Properties:

- **Config:** `create_policy`
- **Env Var:** `RCLONE_UNION_CREATE_POLICY`
- **Type:** string
- **Default:** `“epmfs”`

### `--union-search-policy`

Policy to choose upstream on SEARCH category.

Properties:

- **Config:** `search_policy`
- **Env Var:** `RCLONE_UNION_SEARCH_POLICY`
- **Type:** string
- **Default:** `“ff”`

### `--union-cache-time`

Cache time of usage and free space (in seconds).

This option is only useful when a path preserving policy is used.

Properties:

- **Config:** `cache_time`
- **Env Var:** `RCLONE_UNION_CACHE_TIME`
- **Type:** int
- **Default:** 120

## 👑 Advanced options 👑

Here are the Advanced options specific to `union` (Union merges the contents of several upstream fs).

### `--union-min-free-space`

Minimum viable free space for lfs/eplfs policies.

If a remote has less than this much free space then it won't be considered for use in `lfs` or `eplfs` policies. Like, it's out. Not invited. 🙅

Properties:

- **Config:** `min_free_space`
- **Env Var:** `RCLONE_UNION_MIN_FREE_SPACE`
- **Type:** SizeSuffix
- **Default:** 1Gi

### `--union-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_UNION_DESCRIPTION`
- **Type:** string
- **Required:** false

## 🌸 Metadata 🌸

Any metadata supported by the underlying remote is read and written.

See the metadata docs for more info.

---

# 🌈 WebDAV 🌈

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

## 💖 Configuration 💖

To configure the WebDAV remote you'll need to have a URL for it, plus a username and a password. And if you know what kind of system you're connecting to, then rclone can enable extra features for you. Iconic. ✨

Here's an example of how to make a remote called `remote`. First run:

rclone config


This will guide you through an interactive setup process:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / WebDAV \ "webdav" [snip] Storage> webdav URL of http host to connect to Choose a number from below, or type in your own value 1 / Connect to example.com \ "https://example.com" url> https://example.com/remote.php/webdav/ Name of the WebDAV site/service/software you are using Choose a number from below, or type in your own value 1 / Fastmail Files \ (fastmail) 2 / Nextcloud \ (nextcloud) 3 / Owncloud \ (owncloud) 4 / Sharepoint Online, authenticated by Microsoft account \ (sharepoint) 5 / Sharepoint with NTLM authentication, usually self-hosted or on-premises \ (sharepoint-ntlm) 6 / rclone WebDAV server to serve a remote over HTTP via the WebDAV protocol \ (rclone) 7 / Other site/service or software \ (other) vendor> 2 User name user> user Password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: Bearer token instead of user/pass (e.g. a Macaroon) bearer_token> Remote config Configuration complete. Options:

type: webdav
url: https://example.com/remote.php/webdav/
vendor: nextcloud
user: user
pass: * ENCRYPTED *
bearer_token: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


Once configured you can then use rclone like this,

List directories in top level of your WebDAV

rclone lsd remote:


List all the files in your WebDAV

rclone ls remote:


To copy a local directory to an WebDAV directory called `backup`

rclone copy /home/source remote:backup


## 🦋 Modification times and hashes 🦋

Plain WebDAV does **not** support modified times. However when used with Fastmail Files, Owncloud or Nextcloud, rclone will support modified times. 🕐

Likewise plain WebDAV does **not** support hashes, however when used with Fastmail Files, Owncloud or Nextcloud rclone will support SHA1 and MD5 hashes. Depending on the exact version of Owncloud or Nextcloud, hashes may appear on all objects, or only on objects which had a hash uploaded with them. iykyk 💅

## 🌟 Standard options 🌟

Here are the Standard options specific to `webdav` (WebDAV).

### `--webdav-url`

URL of http host to connect to.

E.g. `https://example.com`.

Properties:

- **Config:** `url`
- **Env Var:** `RCLONE_WEBDAV_URL`
- **Type:** string
- **Required:** true

### `--webdav-vendor`

Name of the WebDAV site/service/software you are using.

Properties:

- **Config:** `vendor`
- **Env Var:** `RCLONE_WEBDAV_VENDOR`
- **Type:** string
- **Required:** false
- **Examples:**
  - `“fastmail”`
    - Fastmail Files
  - `“nextcloud”`
    - Nextcloud
  - `“owncloud”`
    - Owncloud
  - `“sharepoint”`
    - Sharepoint Online, authenticated by Microsoft account
  - `“sharepoint-ntlm”`
    - Sharepoint with NTLM authentication, usually self-hosted or on-premises
  - `“rclone”`
    - rclone WebDAV server to serve a remote over HTTP via the WebDAV protocol
  - `“other”`
    - Other site/service or software

### `--webdav-user`

User name.

In case NTLM authentication is used, the username should be in the format `Domain`.

Properties:

- **Config:** `user`
- **Env Var:** `RCLONE_WEBDAV_USER`
- **Type:** string
- **Required:** false

### `--webdav-pass`

Password.

> NB Input to this must be obscured — see `rclone obscure`. 🔐

Properties:

- **Config:** `pass`

- **Env Var:** `RCLONE_WEBDAV_PASS`
  - **Type:** `string`
  - **Required:** `false`

---

- **`--webdav-bearer-token`** — bestie, this one lets you roll with a *bearer token* instead of the whole user/pass situation (think a Macaroon, yeah that's literally what it's called 🍪). <purple>So secure, so slay.</purple>
  - **Config:** `bearer_token`
  - **Env Var:** `RCLONE_WEBDAV_BEARER_TOKEN`
  - **Type:** `string`
  - **Required:** `false`

---

### ✨ Advanced options ✨

These are the extra-spicy knobs, and they're exclusive to webdav (WebDAV). <cyan>iykyk 💅</cyan>

---

- **`--webdav-bearer-token-command`** — a command you run to go fetch yourself a bearer token. <mint>yes, it goes and gets it for you, icon behavior</mint>
  - **Config:** `bearer_token_command`
  - **Env Var:** `RCLONE_WEBDAV_BEARER_TOKEN_COMMAND`
  - **Type:** `string`
  - **Required:** `false`

---

- **`--webdav-encoding`** — the encoding for the backend. ✨
  - Peep the encoding section in the overview if you want the full lore.
  - <yellow>Heads up on the default:</yellow> it's `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Hash,Percent,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8` for `sharepoint-ntlm`, or `identity` otherwise.
  - **Config:** `encoding`
  - **Env Var:** `RCLONE_WEBDAV_ENCODING`
  - **Type:** `string`
  - **Required:** `false`

---

- **`--webdav-headers`** — sets HTTP headers for <hotpink>all</hotpink> transactions. You're adding extra HTTP headers to literally everything that goes out.
  - The input format? A comma separated list of key,value pairs. Standard CSV encoding is allowed too, so go off.
  - For example, to set a Cookie use `Cookie,name=value`, or `“Cookie”,“name=value”`.
  - And you can stack multiple headers, e.g. `“Cookie”,“name=value”,“Authorization”,“xxx”`.
  - **Config:** `headers`
  - **Env Var:** `RCLONE_WEBDAV_HEADERS`
  - **Type:** `CommaSepList`
  - **Default:** *(empty, bestie — nothing pre-filled)*

---

- **`--webdav-pacer-min-sleep`** — minimum time to sleep between API calls. <lavender>little nap, little self-care 🦋</lavender>
  - **Config:** `pacer_min_sleep`
  - **Env Var:** `RCLONE_WEBDAV_PACER_MIN_SLEEP`
  - **Type:** `Duration`
  - **Default:** `10ms`

---

- **`--webdav-nextcloud-chunk-size`** — Nextcloud upload chunk size.
  - We <rainbow>highly recommend</rainbow> configuring your NextCloud instance to bump the max chunk size up to 1 GB for better upload performance. Full tea right here: https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/big_file_upload_configuration.html#adjust-chunk-size-on-nextcloud-side
  - Set it to `0` and chunked uploading is off, periodt.
  - **Config:** `nextcloud_chunk_size`
  - **Env Var:** `RCLONE_WEBDAV_NEXTCLOUD_CHUNK_SIZE`
  - **Type:** `SizeSuffix`
  - **Default:** `10Mi`

---

- **`--webdav-owncloud-exclude-shares`** — excludes ownCloud shares. bye bestie 👋
  - **Config:** `owncloud_exclude_shares`
  - **Env Var:** `RCLONE_WEBDAV_OWNCLOUD_EXCLUDE_SHARES`
  - **Type:** `bool`
  - **Default:** `false`

---

- **`--webdav-owncloud-exclude-mounts`** — excludes ownCloud mounted storages.
  - **Config:** `owncloud_exclude_mounts`
  - **Env Var:** `RCLONE_WEBDAV_OWNCLOUD_EXCLUDE_MOUNTS`
  - **Type:** `bool`
  - **Default:** `false`

---

- **`--webdav-unix-socket`** — path to a unix domain socket to dial to, instead of opening a TCP connection directly. <cyan>unix socket girls >>> everything else 💅</cyan>
  - **Config:** `unix_socket`
  - **Env Var:** `RCLONE_WEBDAV_UNIX_SOCKET`
  - **Type:** `string`
  - **Required:** `false`

---

- **`--webdav-auth-redirect`** — preserve authentication on redirect.
  - So here's the lore: if the server redirects rclone to a new domain while it's trying to read a file, rclone will *normally* drop the `Authorization:` header from the request.
  - That's standard security practice, fr fr — it stops your credentials from being sent to some random unknown webserver. <red>do not play with that.</red>
  - BUT sometimes you want it anyway. So if you're getting an error like `401 Unauthorized` while rclone is trying to read files off the webdav server, you can try this option.
  - **Config:** `auth_redirect`
  - **Env Var:** `RCLONE_WEBDAV_AUTH_REDIRECT`
  - **Type:** `bool`
  - **Default:** `false`

---

- **`--webdav-description`** — description of the remote. <lavender>name her, give her lore, main character energy ✨</lavender>
  - **Config:** `description`
  - **Env Var:** `RCLONE_WEBDAV_DESCRIPTION`
  - **Type:** `string`
  - **Required:** `false`

---

### 🫶 Provider notes 🫶

Okay so below are the notes for the specific providers. <pink>each one has its own little vibe check.</pink>

---

**Fastmail Files** 💌

Use `https://webdav.fastmail.com/` or a subdirectory as the URL, and your Fastmail email `username@domain.tld` as the username. Follow this documentation to create an app password with access to Files (WebDAV), and use that as the password.

Fastmail supports modified times using the `X-OC-Mtime` header. <mint>timestamp accuracy, we love to see it</mint>

---

**Owncloud** ☁️

Click the settings cog in the bottom right of the page, and it'll show you the WebDAV URL that rclone needs in the config step. It'll look something like `https://example.com/remote.php/webdav/`.

Owncloud supports modified times using the `X-OC-Mtime` header.

---

**Nextcloud** 🌈

This is configured in an identical way to Owncloud. Just so you know: Nextcloud initially did *not* support streaming of files (`rcat`) whereas Owncloud did — but this seems to be fixed as of 2020-11-27 (tested with rclone v1.53.1 and Nextcloud Server v19). <green>glow up, honestly</green>

---

**Sharepoint Online** 👑

Rclone can be used with Sharepoint provided by OneDrive for Business or Office365 Education Accounts. This feature is only needed for a few of these Accounts — mostly Office365 Education ones. <yellow>These accounts are sometimes not verified by the domain owner.</yellow> github#1975

That means these accounts *can't* be added using the official API (other Accounts should work with the "onedrive" option). But bestie, you *can* access them using webdav. rescued ✨

To use a sharepoint remote with rclone, add it like this. First, you need to get your remote's URL:

- Go here to open your OneDrive or to sign in.
- Now take a look at your address bar — the URL should look like this: `https://[YOUR-DOMAIN]-my.sharepoint.com/personal/[YOUR-EMAIL]/_layouts/15/onedrive.aspx`

You'll only need that URL up to the email address. After that, you'll most likely want to add `/Documents` — that subdirectory contains the actual data stored on your OneDrive.

Add the remote to rclone like this: configure the url as `https://[YOUR-DOMAIN]-my.sharepoint.com/personal/[YOUR-EMAIL]/Documents` and use your normal account email and password for user and pass. If you have 2FA enabled, you have to generate an app password. Set the vendor to `sharepoint`.

Your config file should look like this:

[sharepoint] type = webdav url = https://[YOUR-DOMAIN]-my.sharepoint.com/personal/[YOUR-EMAIL]/Documents vendor = sharepoint user = YourEmailAddress pass = encryptedpassword


---

**Sharepoint with NTLM Authentication** 🔐

Use this option in case your (hosted) Sharepoint isn't tied to OneDrive accounts and uses NTLM authentication.

To get the url configuration — similarly to the above — first navigate to the desired directory in your browser to get the URL, then strip everything after the name of the opened directory.

Example: if the URL is `https://example.sharepoint.com/sites/12345/Documents/Forms/AllItems.aspx`

then the configuration to use would be `https://example.sharepoint.com/sites/12345/Documents`

Set the vendor to `sharepoint-ntlm`.

NTLM uses a domain and user name combination for authentication, so set user to `DOMAIN\username`.

Your config file should look like this:

[sharepoint] type = webdav url = https://[YOUR-DOMAIN]/some-path-to/Documents vendor = sharepoint-ntlm user = DOMAIN\user pass = encryptedpassword


---

**Required Flags for SharePoint** 🚩

Since SharePoint does some special little things with uploaded documents, you *won't* be able to use the document's size or the document's hash to compare whether a file has been changed since the upload, or which file is newer. <red>this is the caveat, don't skip it.</red>

For rclone calls copying files (especially Office files such as `.docx`, `.xlsx`, etc.) from/to SharePoint (like `copy`, `sync`, etc.), you should append these flags to make sure rclone uses the "Last Modified" datetime property to compare your documents:

--ignore-size --ignore-checksum --update


---

**Rclone** 🧚

Use this option if you are hosting remotes over WebDAV provided by rclone. Read `rclone serve webdav` for more details.

rclone serve supports modified times using the `X-OC-Mtime` header. <purple>self-hosting era, we're obsessed</purple>

---

**dCache** 🗄️

dCache is a storage system that supports *so many* protocols and authentication/authorisation schemes. For WebDAV clients, it lets users authenticate with username and password (BASIC), X.509, Kerberos, and various bearer tokens — including Macaroons and OpenID-Connect access tokens.

Configure as normal using the `other` type. <hotpink>Don't</hotpink> enter a username or password — instead enter your Macaroon as the `bearer_token`.

The config will end up looking something like this:

[dcache] type = webdav url = https://dcache... vendor = other user = pass = bearer_token = your-macaroon


There's a script that obtains a Macaroon from a dCache WebDAV endpoint and creates an rclone config file.

Macaroons may also be obtained from the dCacheView web-browser/JavaScript client that comes with dCache.

---

**OpenID-Connect** 🔑

dCache also supports authenticating with OpenID-Connect access tokens. OpenID-Connect is a protocol (based on OAuth 2.0) that lets services identify users who have authenticated with some central service.

Support for OpenID-Connect in rclone is currently achieved using another software package called oidc-agent. It's a command-line tool that facilitates obtaining an access token. Once it's installed and configured, an access token is obtained by running the `oidc-token` command. The following example shows a (shortened) access token obtained from the XDC OIDC Provider. ✨

paul@celebrimbor:~$ oidc-token XDC eyJraWQ[...]QFXDt0 paul@celebrimbor:~$


> Note: before the `oidc-token` command will work, the refresh token must be loaded into the oidc agent. That's done with the `oidc-add` command (e.g., `oidc-add XDC`). This is typically done once per login session. Full details on this, and on how to register oidc-agent with your OIDC Provider, are provided in the oidc-agent documentation. <lavender>don't skip this step bestie, it will not work otherwise 😭</lavender>

The rclone `bearer_token_command` configuration option is used to fetch the access token from oidc-agent.

Configure as a normal WebDAV endpoint, using the `other` vendor, leaving the username and password empty. When prompted, choose to edit the advanced config and enter the command to get a bearer token (e.g., `oidc-agent XDC`).

The following example config shows a WebDAV endpoint that uses oidc-agent to supply an access token from the XDC OIDC Provider:

[dcache] type = webdav url = https://dcache.example.org/ vendor = other bearer_token_command = oidc-token XDC


# 🌸 Yandex Disk 🌸

Yandex Disk is a cloud storage solution created by Yandex. Yes bestie, *that* Yandex. It's giving cloud storage realness 💅

---

## 🎀 Configuration 🎀

okay so here's how you set up a yandex remote. First thing you do, you run:

rclone config


and it walks you through the whole interactive setup, hand-in-hand, like the icon that it is:

No remotes found, make a new one? n) New remote s) Set configuration password n/s> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Yandex Disk \ "yandex" [snip] Storage> yandex Yandex Client Id - leave blank normally. client_id> Yandex Client Secret - leave blank normally. client_secret> 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 Configuration complete. Options:
type: yandex
client_id:
client_secret:
token: {"access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","token_type":"OAuth","expiry":"2016-12-29T12:27:11.362788025Z"} Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y


If you're setting this up on a machine with **no** Internet browser available, go peek at the remote setup docs, they got you 🫶

> Heads up bestie: rclone spins up a lil webserver on your local machine to catch the token that Yandex Disk hands back. It only lives from the moment it opens your browser to the moment you get the verification code back. It's on `http://127.0.0.1:53682/` and it may need you to unblock it temporarily if you've got a host firewall running. Don't panic, it's temporary ✨

Once you're configured, you can use rclone like this:

See top level directories:

rclone lsd remote:


Make a new directory:

rclone mkdir remote:directory


List the contents of a directory:

rclone ls remote:directory


Sync `/home/local/directory` to the remote path, deleting any excess files in the path:

rclone sync --interactive /home/local/directory remote:directory


Yandex paths may be as deep as required, e.g. `remote:directory/subdirectory`. Go as deep as your heart desires 💖

---

## ⏰ Modification times and hashes ⏰

Modified times are supported, and they're stored accurate to **1 ns** in custom metadata called `rclone_modified` in RFC3339 with nanoseconds format. Nanosecond precision, we love to see it 👑

The MD5 hash algorithm is natively supported by Yandex Disk. No cap.

---

## 🗑️ Emptying Trash 🗑️

If you wish to empty your trash, you can use the

rclone cleanup remote:


command, which will ***permanently delete*** all your trashed files. Permanently. Gone. Poof 💀 This command does not take any path arguments — it's the whole trash or nothing.

---

## 📊 Quota information 📊

To view your current quota, use the

rclone about remote:


command, which will display your usage limit (quota) and the current usage. Vibe check your storage, bestie 🌈

---

## 🚫 Restricted filename characters 🚫

The default restricted characters set are replaced.

Invalid UTF-8 bytes will also be replaced, as they can't be used in JSON strings. The JSON said no 🙈

---

## ✨ Standard options ✨

Here are the Standard options specific to yandex (Yandex Disk).

- **`--yandex-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_YANDEX_CLIENT_ID`
  - Type: string
  - Required: false

- **`--yandex-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:

  - Config: `client_secret`
  - Env Var: `RCLONE_YANDEX_CLIENT_SECRET`
  - Type: string
  - Required: false

---

## 💎 Advanced options 💎

Here are the Advanced options specific to yandex (Yandex Disk).

- **`--yandex-token`** — OAuth Access Token as a JSON blob.

  Properties:

  - Config: `token`
  - Env Var: `RCLONE_YANDEX_TOKEN`
  - Type: string
  - Required: false

- **`--yandex-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `auth_url`
  - Env Var: `RCLONE_YANDEX_AUTH_URL`
  - Type: string
  - Required: false

- **`--yandex-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `token_url`
  - Env Var: `RCLONE_YANDEX_TOKEN_URL`
  - Type: string
  - Required: false

- **`--yandex-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Properties:

  - Config: `client_credentials`
  - Env Var: `RCLONE_YANDEX_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: false

- **`--yandex-hard-delete`** — Delete files permanently rather than putting them into the trash.

  Properties:

  - Config: `hard_delete`
  - Env Var: `RCLONE_YANDEX_HARD_DELETE`
  - Type: bool
  - Default: false

- **`--yandex-encoding`** — The encoding for the backend.

  See the encoding section in the overview for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_YANDEX_ENCODING`
  - Type: Encoding
  - Default: `Slash,Del,Ctl,InvalidUtf8,Dot`

- **`--yandex-spoof-ua`** — Set the user agent to match an official version of the yandex disk client. May help with upload performance.

  Properties:

  - Config: `spoof_ua`
  - Env Var: `RCLONE_YANDEX_SPOOF_UA`
  - Type: bool
  - Default: true

- **`--yandex-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_YANDEX_DESCRIPTION`
  - Type: string
  - Required: false

---

## 😭 Limitations 😭

When uploading **very large files** (bigger than about 5 GiB) you will need to increase the `--timeout` parameter. Why? Because Yandex *pauses* (perhaps to calculate the MD5SUM for the entire file, iconic behaviour honestly) before it returns confirmation that the file has been uploaded. And the default handling of timeouts in rclone is to assume a 5 minute pause is an error and close the connection — you'll see

net/http: timeout awaiting response headers


errors in the logs if this is happening. So yeah, you'll want to set the timeout to **twice the max size of file in GiB**, which should be enough. If you want to upload a 30 GiB file, set a timeout of `2 * 30 = 60m`, that is `--timeout 60m`. Do the math bestie, it's literally just doubling 🧮

> Also important: having a **Yandex Mail account is mandatory** to use the Yandex.Disk subscription. Token generation will work without a mail account, but Rclone won't be able to complete any actions. Sad but true 💀

[403 - DiskUnsupportedUserAccountTypeError] User account type is not supported.


---

# 🦋 Zoho Workdrive 🦋

Zoho WorkDrive is a <pink>cloud storage solution</pink> created by Zoho. bestie, it's giving "corporate Google Drive but make it Zoho" and honestly? we respect it. 💜

## ⚙️ Configuration ⚙️

Okay so here's a whole example of making a zoho configuration. First, run this, obviously:

rclone config


Not me holding your hand through the interactive setup, but here we go — this is literally what it looks like:

No remotes found, make a new one? n) New remote s) Set configuration password n/s> 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 / Zoho \ "zoho" [snip] Storage> zoho ** See help for zoho backend at: https://rclone.org/zoho/ **

OAuth Client Id Leave blank normally. Enter a string value. Press Enter for the default (""). client_id> OAuth 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 (default) 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 (default) n) No y/n> If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth?state=LVn0IHzxej1ZkmQw31d0wQ Log in and authorize rclone for access Waiting for code... Got code Choose a number from below, or type in your own value 1 / MyTeam \ "4u28602177065ff22426787a6745dba8954eb" Enter a Team ID> 1 Choose a number from below, or type in your own value 1 / General \ "4u2869d2aa6fca04f4f2f896b6539243b85b1" Enter a Workspace ID> 1 Configuration complete. Options:
type: zoho
token: {"access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","token_type":"Zoho-oauthtoken","refresh_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","expiry":"2020-10-12T00:54:52.370275223+02:00"}
root_folder_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Keep this "remote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>


Now if you're setting this up on a machine with **no Internet browser** available, go check the <purple>remote setup docs</purple> for how to do that. 💅

Here's the tea about the auth flow: rclone runs a <cyan>webserver on your local computer</cyan> to collect the authorization token from Zoho Workdrive. It only runs from the moment your browser opens until the token comes back — no lingering server, no vibe-killing background process. That webserver lives at `http://127.0.0.1:53682/`. And if local port `53682` is protected by a firewall, you may need to **temporarily unblock the firewall** to complete authorization. 🫶

Once you're configured, you can use rclone like this:

See top level directories 👑

rclone lsd remote:


Make a new directory ✨

rclone mkdir remote:directory


List the contents of a directory 🍓

rclone ls remote:directory


Sync `/home/local/directory` to the remote path, **deleting any excess files in the path**. (yes it deletes, that's the sync life, periodt)

rclone sync --interactive /home/local/directory remote:directory


Zoho paths may be as deep as required, eg `remote:directory/subdirectory`. Go off, queen. 🧚

## 🕐 Modification times and hashes 🕐

Modified times are **currently not supported** for Zoho Workdrive. 💀

No hash algorithms are supported. literally none. ngl that's just how it is.

## 📊 Usage information 📊

To view your current quota you can use the `rclone about remote:` command, which will display your current usage. flex your storage, bestie.

## 🚫 Restricted filename characters 🚫

Only control characters and invalid UTF-8 are replaced. In addition, most Unicode full-width characters are **not supported at all** and will be **removed from filenames during upload**. ok so, heads up on that one. 😭

## 🔧 Standard options 🔧

Here are the Standard options specific to zoho (Zoho).

### 💖 `--zoho-client-id` 💖

OAuth Client Id.

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_ZOHO_CLIENT_ID`
- Type: `string`
- Required: `false`

### 💖 `--zoho-client-secret` 💖

OAuth Client Secret.

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_ZOHO_CLIENT_SECRET`
- Type: `string`
- Required: `false`

### 💖 `--zoho-region` 💖

Zoho region to connect to.

You'll have to use the region your organization is registered in. If not sure, use the same top level domain as you connect to in your browser. 🔥

Properties:

- Config: `region`
- Env Var: `RCLONE_ZOHO_REGION`
- Type: `string`
- Required: `false`
- Examples:
  - `"com"`
    - United states / Global
  - `"eu"`
    - Europe
  - `"in"`
    - India
  - `"jp"`
    - Japan
  - `"com.cn"`
    - China
  - `"com.au"`
    - Australia

## 🚀 Advanced options 🚀

Here are the Advanced options specific to zoho (Zoho).

### 👑 `--zoho-token` 👑

OAuth Access Token as a JSON blob.

Properties:

- Config: `token`
- Env Var: `RCLONE_ZOHO_TOKEN`
- Type: `string`
- Required: `false`

### 👑 `--zoho-auth-url` 👑

Auth server URL.

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_ZOHO_AUTH_URL`
- Type: `string`
- Required: `false`

### 👑 `--zoho-token-url` 👑

Token server url.

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_ZOHO_TOKEN_URL`
- Type: `string`
- Required: `false`

### 👑 `--zoho-client-credentials` 👑

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749. fr fr, it's in the RFC and everything. 📜

Properties:

- Config: `client_credentials`
- Env Var: `RCLONE_ZOHO_CLIENT_CREDENTIALS`
- Type: `bool`
- Default: `false`

### 👑 `--zoho-upload-cutoff` 👑

Cutoff for switching to large file upload api (>= 10 MiB).

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_ZOHO_UPLOAD_CUTOFF`
- Type: `SizeSuffix`
- Default: `10Mi`

### 👑 `--zoho-encoding` 👑

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_ZOHO_ENCODING`
- Type: `Encoding`
- Default: `Del,Ctl,InvalidUtf8`

### 👑 `--zoho-description` 👑

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_ZOHO_DESCRIPTION`
- Type: `string`
- Required: `false`

## 🧚 Setting up your own client_id 🧚

For Zoho we advise you to set up your own `client_id`. To do so you have to complete the following steps. slay, it's only three.

1. Log in to the Zoho API Console 👩‍💻
2. Create a new client of type "Server-based Application". The name and website don't matter, but you **must** add the redirect URL `http://localhost:53682/`. (this is the important one bestie, do not skip it)
3. Once the client is created, you can go to the settings tab and enable it in other regions.

The client id and client secret can now be used with rclone. 💅

---

# 🏠 Local Filesystem 🏠

Local paths are specified as normal filesystem paths, e.g. `/path/to/wherever`, so:

rclone sync --interactive /home/source /tmp/destination


Will sync `/home/source` to `/tmp/destination`. iconic, no cloud required. 🌈

## ⚙️ Configuration ⚙️

For consistencies sake one can also configure a remote of type `local` in the config file, and access the local filesystem using rclone remote paths, e.g. `remote:path/to/wherever`, but it is probably easier not to. ngl, just don't. 😭

## 🕐 Modification times 🕐

Rclone reads and writes the modification times using an accuracy determined by the OS. Typically this is **1ns on Linux**, **10 ns on Windows** and **1 Second on OS X**.

## 📁 Filenames 📁

Filenames should be encoded in UTF-8 on disk. This is the normal case for Windows and OS X.

There is a bit more uncertainty in the Linux world, but new distributions will have UTF-8 encoded file names. If you are using an old Linux filesystem with non UTF-8 file names (e.g. `latin1`) then you can use the `convmv` tool to convert the filesystem to UTF-8. This tool is available in most distributions' package managers. 🫶

If an invalid (non-UTF8) filename is read, the invalid characters will be **replaced with a quoted representation of the invalid bytes**. The name `gro\xdf` will be transferred as `gro‛DF`. rclone will emit a debug message in this case (use `-v` to see), e.g.

Local file system at .: Replacing invalid UTF-8 characters in "gro\xdf"


## 🚫 Restricted characters 🚫

With the local backend, restrictions on the characters that are usable in file or directory names depend on the **operating system**. To check what rclone will replace by default on your system, run `rclone help flags local-encoding`.

On non Windows platforms the following characters are replaced when handling file names.

- `NUL` — value `0x00` — replaced with `␀`
- `/` — value `0x2F` — replaced with `／`

When running on Windows the following characters are replaced. This list is based on the **Windows file naming conventions**. buckle up, it's a long one. 💀

- `NUL` — value `0x00` — replaced with `␀`
- `SOH` — value `0x01` — replaced with `␁`
- `STX` — value `0x02` — replaced with `␂`
- `ETX` — value `0x03` — replaced with `␃`
- `EOT` — value `0x04` — replaced with `␄`
- `ENQ` — value `0x05` — replaced with `␅`
- `ACK` — value `0x06` — replaced with `␆`
- `BEL` — value `0x07` — replaced with `␇`
- `BS` — value `0x08` — replaced with `␈`
- `HT` — value `0x09` — replaced with `␉`
- `LF` — value `0x0A` — replaced with `␊`
- `VT` — value `0x0B` — replaced with `␋`
- `FF` — value `0x0C` — replaced with `␌`
- `CR` — value `0x0D` — replaced with `␍`
- `SO` — value `0x0E` — replaced with `␎`
- `SI` — value `0x0F` — replaced with `␏`
- `DLE` — value `0x10` — replaced with `␐`
- `DC1` — value `0x11` — replaced with `␑`
- `DC2` — value `0x12` — replaced with `␒`
- `DC3` — value `0x13` — replaced with `␓`
- `DC4` — value `0x14` — replaced with `␔`
- `NAK` — value `0x15` — replaced with `␕`
- `SYN` — value `0x16` — replaced with `␖`
- `ETB` — value `0x17` — replaced with `␗`
- `CAN` — value `0x18` — replaced with `␘`
- `EM` — value `0x19` — replaced with `␙`
- `SUB` — value `0x1A` — replaced with `␚`
- `ESC` — value `0x1B` — replaced with `␛`
- `FS` — value `0x1C` — replaced with `␜`
- `GS` — value `0x1D` — replaced with `␝`
- `RS` — value `0x1E` — replaced with `␞`
- `US` — value `0x1F` — replaced with `␟`
- `/` — value `0x2F` — replaced with `／`
- `"` — value `0x22` — replaced with `＂`
- `*` — value `0x2A` — replaced with `＊`
- `:` — value `0x3A` — replaced with `：`
- `<` — value `0x3C` — replaced with `＜`
- `>` — value `0x3E` — replaced with `＞`
- `?` — value `0x3F` — replaced with `？`
- `\` — value `0x5C` — replaced with `＼`
- `|` — value `0x7C` — replaced with `｜`

Okay so Windows is *picky* about how filenames end. File names can also not end with the following characters, and listen — these only get replaced if they're the last character in the name:

- **`SP`** (`0x20`) — gets swapped for `␠`
- **`.`** (`0x2E`) — gets swapped for `．`

Invalid UTF-8 bytes will also be replaced, because they literally can't be converted to UTF-16. it's giving "no thoughts, just conversion errors" 💀

---

## Paths on Windows 🪟

Bestie, Windows has like a *million* ways of specifying a path to a filesystem resource. Let's break it down:

- Local paths can be **absolute**, like `C:\path\to\wherever`
- ...or **relative**, like `..\wherever`
- Network paths in **UNC format**, `\\server\share`, are also supported
- Path separator can be either `\` (as in `C:\path\to\wherever`) or `/` (as in `C:/path/to/wherever`)

Length of these paths is limited to **259 characters** for files and **247 characters** for directories, which is honestly so restrictive of them. BUT there's an alternative **extended-length path format** that bumps the limit up to (approximately) **32,767 characters** ✨

This format requires absolute paths and the use of the prefix `\\?\`, e.g. `\\?\D:\some\very\long\path`.

For convenience, rclone will automatically convert regular paths into the corresponding extended-length paths, so in most cases you do **not** have to worry about this (read more below 👇).

Using that same prefix `\\?\` it is also possible to specify a path to volumes identified by their GUID, e.g. `\\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path`. iconic behavior ngl.

---

## Long paths 📏

Rclone handles long paths automatically, by converting all paths to extended-length path format, which allows paths up to **32,767 characters**. slay.

This conversion will ensure paths are absolute and prefix them with the `\\?\`. This is why you will see that your paths, for instance `.\files` is shown as path `\\?\C:\files` in the output, and `\\server\share` as `\\?\UNC\server\share`. no cap, that's just what it does 💅

However — and this is the messy part 🙈 — in rare cases this may cause problems with buggy file system drivers like **EncFS**.

To disable UNC conversion **globally**, add this to your `.rclone.conf` file:

[local] nounc = true


If you want to *selectively* disable UNC, you can add it to a separate entry like this:

[nounc] type = local nounc = true


And use rclone like this:

rclone copy c:\src nounc:z:\dst


This will use UNC paths on `c:\src` but **not** on `z:\dst`.

> Of course this will cause problems if the absolute path length of a file exceeds 259 characters on `z`, so only use this option if you have to. like, genuinely, only if you have to 🫶

---

## Symlinks / Junction points 🔗

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows). it's giving "not my problem, not my business".

If you supply `--copy-links` or `-L` then rclone will **follow** the symlink and copy the pointed-to file or directory. Note that this flag is **incompatible** with `--links` / `-l`.

This flag applies to **all commands**.

For example, supposing you have a directory structure like this:

$ tree /tmp/a /tmp/a ├── b -> ../b ├── expected -> ../expected ├── one └── two └── three


Then you can see the difference with and without the flag like this:

$ rclone ls /tmp/a 6 one 6 two/three

and

$ rclone -L ls /tmp/a 4174 expected 6 one 6 two/three 6 b/two 6 b/one


the way `-L` just went and followed everything... main character energy fr fr 👑

---

## `--local-links`, `--links`, `-l` 🔗✨

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

If you supply this flag then rclone will copy symbolic links from the local storage, and store them as **text files**, with a `.rclonelink` suffix in the remote storage.

The text file will contain the target of the symbolic link (see example).

This flag applies to **all commands**.

For example, supposing you have a directory structure like this:

$ tree /tmp/a /tmp/a ├── file1 -> ./file4 └── file2 -> /home/user/file3


Copying the entire directory with `-l`:

$ rclone copy -l /tmp/a/ remote:/tmp/a/


The remote files are created with a `.rclonelink` suffix:

$ rclone ls remote:/tmp/a 5 file1.rclonelink 14 file2.rclonelink


The remote files will contain the target of the symbolic links:

$ rclone cat remote:/tmp/a/file1.rclonelink ./file4

$ rclone cat remote:/tmp/a/file2.rclonelink /home/user/file3


Copying them back with `-l`:

$ rclone copy -l remote:/tmp/a/ /tmp/b/

$ tree /tmp/b /tmp/b ├── file1 -> ./file4 └── file2 -> /home/user/file3


However, if copied back **without** `-l`:

$ rclone copyto remote:/tmp/a/ /tmp/b/

$ tree /tmp/b /tmp/b ├── file1.rclonelink └── file2.rclonelink


If you want to copy a single file with `-l` then you **must** use the `.rclonelink` suffix:

$ rclone copy -l remote:/tmp/a/file1.rclonelink /tmp/c

$ tree /tmp/c /tmp/c └── file1 -> ./file4


Note that `--local-links` just enables this feature for the **local backend**. `--links` and `-l` enable the feature for **all supported backends and the VFS**.

> Note that this flag is incompatible with `--copy-links` / `-L`. they simply do not vibe together 😭

---

## Restricting filesystems with `--one-file-system` 🚧

Normally rclone will recurse through filesystems as mounted. it's nosy like that.

However if you set `--one-file-system` or `-x` this tells rclone to **stay in the filesystem** specified by the root and **not** to recurse into different file systems.

For example if you have a directory hierarchy like this:

root ├── disk1 - disk1 mounted on the root │ └── file3 - stored on disk1 ├── disk2 - disk2 mounted on the root │ └── file4 - stored on disk12 ├── file1 - stored on the root disk └── file2 - stored on the root disk


Using `rclone --one-file-system copy root remote:` will only copy `file1` and `file2`. Eg:

$ rclone -q --one-file-system ls root 0 file1 0 file2

$ rclone -q ls root 0 disk1/file3 0 disk2/file4 0 file1 0 file2


> NB Rclone (like most unix tools such as `du`, `rsync` and `tar`) treats a **bind mount to the same device** as being on the same filesystem.

> NB This flag is only available on **Unix based systems**. On systems where it isn't supported (e.g. Windows) it will be **ignored**. sorry windows girlies 💔

---

## Advanced options 🧠✨

Here are the Advanced options specific to local (Local Disk).

### `--local-nounc`

Disable UNC (long path names) conversion on Windows.

Properties:

- Config: `nounc`
- Env Var: `RCLONE_LOCAL_NOUNC`
- Type: `bool`
- Default: `false`
- Examples:
  - `"true"`
    - Disables long file names.

### `--copy-links` / `-L`

Follow symlinks and copy the pointed to item.

Properties:

- Config: `copy_links`
- Env Var: `RCLONE_LOCAL_COPY_LINKS`
- Type: `bool`
- Default: `false`

### `--local-links`

Translate symlinks to/from regular files with a `.rclonelink` extension for the local backend.

Properties:

- Config: `links`
- Env Var: `RCLONE_LOCAL_LINKS`
- Type: `bool`
- Default: `false`

### `--skip-links`

Don't warn about skipped symlinks.

This flag disables warning messages on skipped symlinks or junction points, as you explicitly acknowledge that they should be skipped. yep, you said it, not rclone 💅

Properties:

- Config: `skip_links`
- Env Var: `RCLONE_LOCAL_SKIP_LINKS`
- Type: `bool`
- Default: `false`

### `--local-zero-size-links`

Assume the `Stat` size of links is zero (and read them instead) **(deprecated)**.

Rclone used to use the `Stat` size of links as the link size, but this fails in quite a few places:

- Windows
- On some virtual filesystems (such as LucidLink)
- Android

So rclone now **always reads the link**.

Properties:

- Config: `zero_size_links`
- Env Var: `RCLONE_LOCAL_ZERO_SIZE_LINKS`
- Type: `bool`
- Default: `false`

### `--local-unicode-normalization`

Apply unicode NFC normalization to paths and filenames.

This flag can be used to normalize file names into unicode NFC form that are read from the local filesystem.

Rclone does **not** normally touch the encoding of file names it reads from the file system.

This can be useful when using macOS as it normally provides decomposed (NFD) unicode which in some language (eg Korean) doesn't display properly on some OSes. bless macOS for being Like That 🙈

Note that rclone compares filenames with unicode normalization in the sync routine so this flag shouldn't normally be used.

Properties:

- Config: `unicode_normalization`
- Env Var: `RCLONE_LOCAL_UNICODE_NORMALIZATION`
- Type: `bool`
- Default: `false`

### `--local-no-check-updated`

Don't check to see if the files change during upload.

Normally rclone checks the size and modification time of files as they are being uploaded and aborts with a message which starts `"can't copy - source file is being updated"` if the file changes during upload.

However on some file systems this modification time check may fail (e.g. Glusterfs `#2206`) so this check can be disabled with this flag.

If this flag is set, rclone will use its best efforts to transfer a file which is being updated. If the file is only having things appended to it (e.g. a log) then rclone will transfer the log file with the size it had the first time rclone saw it.

If the file is being modified throughout (not just appended to) then the transfer may fail with a hash check failure. 💀

In detail, once the file has had `stat()` called on it for the first time we:

- Only transfer the size that `stat` gave
- Only checksum the size that `stat` gave
- Don't update the stat info for the file

> NB do not use this flag on a Windows Volume Shadow (VSS). For some unknown reason, files in a VSS sometimes show different sizes from the directory listing (where the initial stat value comes from on Windows) and when stat is called on them directly. Other copy tools always use the direct stat value and setting this flag will disable that.

Properties:

- Config: `no_check_updated`
- Env Var: `RCLONE_LOCAL_NO_CHECK_UPDATED`
- Type: `bool`
- Default: `false`

### `--one-file-system` / `-x`

Don't cross filesystem boundaries (unix/macOS only).

Properties:

- Config: `one_file_system`
- Env Var: `RCLONE_LOCAL_ONE_FILE_SYSTEM`
- Type: `bool`
- Default: `false`

### `--local-case-sensitive`

Force the filesystem to report itself as case sensitive.

Plus, lowkey, the section that got cut off right before this one was talking about a case-sensitivity flag, and this first paragraph is literally just the rest of that vibe check, so here's the tail end of it, no heading needed:

Normally the local backend declares itself as case insensitive on Windows/macOS and case sensitive for everything else. Use this flag to override the default choice.

Properties:

- **Config:** `case_sensitive`
- **Env Var:** `RCLONE_LOCAL_CASE_SENSITIVE`
- **Type:** `bool`
- **Default:** `false`

---

## <pink>`--local-case-insensitive`</p>

Force the filesystem to report itself as case insensitive.

Normally the local backend declares itself as case insensitive on Windows/macOS and case sensitive for everything else. Use this flag to override the default choice.

Properties:

- **Config:** `case_insensitive`
- **Env Var:** `RCLONE_LOCAL_CASE_INSENSITIVE`
- **Type:** `bool`
- **Default:** `false`

---

## <purple>`--local-no-clone`</purple>

Disable reflink cloning for server-side copies.

Normally, for local-to-local transfers, rclone will "clone" the file when possible, and fall back to "copying" only when cloning is not supported.

Cloning creates a shallow copy (or "reflink") which initially shares blocks with the original file. Unlike a "hardlink", the two files are independent and neither will affect the other if subsequently modified.

Cloning is usually preferable to copying, as it is much faster and is deduplicated by default (i.e. having two identical files does not consume more storage than having just one.) However, for use cases where data redundancy is preferable, `--local-no-clone` can be used to disable cloning and force "deep" copies.

Currently, cloning is only supported when using APFS on macOS (support for other platforms may be added in the future.)

Properties:

- **Config:** `no_clone`
- **Env Var:** `RCLONE_LOCAL_NO_CLONE`
- **Type:** `bool`
- **Default:** `false`

---

## <mint>`--local-no-preallocate`</mint>

Disable preallocation of disk space for transferred files.

Preallocation of disk space helps prevent filesystem fragmentation. However, some virtual filesystem layers (such as Google Drive File Stream) may incorrectly set the actual file size equal to the preallocated space, causing checksum and file size checks to fail. Use this flag to disable preallocation.

Properties:

- **Config:** `no_preallocate`
- **Env Var:** `RCLONE_LOCAL_NO_PREALLOCATE`
- **Type:** `bool`
- **Default:** `false`

---

## <cyan>`--local-no-sparse`</cyan>

Disable sparse files for multi-thread downloads.

On Windows platforms rclone will make sparse files when doing multi-thread downloads. This avoids long pauses on large files where the OS zeros the file. However sparse files may be undesirable as they cause disk fragmentation and can be slow to work with.

Properties:

- **Config:** `no_sparse`
- **Env Var:** `RCLONE_LOCAL_NO_SPARSE`
- **Type:** `bool`
- **Default:** `false`

---

## <yellow>`--local-no-set-modtime`</yellow>

Disable setting modtime.

Normally rclone updates modification time of files after they are done uploading. This can cause permissions issues on Linux platforms when the user rclone is running as does not own the file uploaded, such as when copying to a CIFS mount owned by another user. If this option is enabled, rclone will no longer update the modtime after copying a file.

Properties:

- **Config:** `no_set_modtime`
- **Env Var:** `RCLONE_LOCAL_NO_SET_MODTIME`
- **Type:** `bool`
- **Default:** `false`

---

## <lavender>`--local-time-type`</lavender>

Set what kind of time is returned.

Normally rclone does all operations on the mtime or Modification time.

If you set this flag then rclone will return the Modified time as whatever you set here. So if you use `rclone lsl --local-time-type ctime` then you will see ctimes in the listing.

If the OS doesn't support returning the `time_type` specified then rclone will silently replace it with the modification time which all OSes support.

- `mtime` is supported by all OSes
- `atime` is supported on all OSes except: plan9, js
- `btime` is only supported on: Windows, macOS, freebsd, netbsd
- `ctime` is supported on all Oses except: Windows, plan9, js

> Bestie, note that setting the time will still set the modified time, so this is only useful for reading. Fr fr.

Properties:

- **Config:** `time_type`
- **Env Var:** `RCLONE_LOCAL_TIME_TYPE`
- **Type:** `mtime|atime|btime|ctime`
- **Default:** `mtime`
- **Examples:**
  - `"mtime"`
    - The last modification time.
  - `"atime"`
    - The last access time.
  - `"btime"`
    - The creation time.
  - `"ctime"`
    - The last status change time.

---

## <peach>`--local-encoding`</peach>

The encoding for the backend.

See the encoding section in the overview for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_LOCAL_ENCODING`
- **Type:** `Encoding`
- **Default:** `Slash,Dot`

---

## <mint>`--local-description`</mint>

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_LOCAL_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

---

# ✨ Metadata ✨

Depending on which OS is in use the local backend may return only some of the system metadata. Setting system metadata is supported on all OSes but setting user metadata is only supported on linux, freebsd, netbsd, macOS and Solaris. It is not supported on Windows yet (see `pkg/attrs#47`).

User metadata is stored as extended attributes (which may not be supported by all file systems) under the `user.*` prefix.

Metadata is supported on files and directories.

Here are the possible system metadata items for the local backend. <rainbow>(no tables allowed in this format so it's a list now, but not one single detail went missing, promise 💖)</rainbow>

- **`atime`** — Help: Time of last access — Type: `RFC 3339` — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: `N`
- **`btime`** — Help: Time of file birth (creation) — Type: `RFC 3339` — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: `N`
- **`gid`** — Help: Group ID of owner — Type: decimal number — Example: `500` — Read Only: `N`
- **`mode`** — Help: File type and mode — Type: octal, unix style — Example: `0100664` — Read Only: `N`
- **`mtime`** — Help: Time of last modification — Type: `RFC 3339` — Example: `2006-01-02T15:04:05.999999999Z07:00` — Read Only: `N`
- **`rdev`** — Help: Device ID (if special file) — Type: hexadecimal — Example: `1abc` — Read Only: `N`
- **`uid`** — Help: User ID of owner — Type: decimal number — Example: `500` — Read Only: `N`

See the metadata docs for more info.

---

# 🛠️ Backend commands 🛠️

Here are the commands specific to the local backend.

Run them with

rclone backend COMMAND remote:


The help below will explain what arguments each command takes.

See the backend command for more info on how to pass options and arguments.

These can be run on a running backend using the rc command `backend/command`.

## <hotpink>`noop`</hotpink>

A null operation for testing backend commands

rclone backend noop remote: [options] [<arguments>+]


This is a test command which has some options you can try to change the output.

Options:

- `"echo"`: echo the input arguments
- `"error"`: return an error based on option value

---

# <purple>Changelog</purple>

## `v1.69.3` - 2025-05-21

See commits

### Bug Fixes

- **build**
  - Reapply update `github.com/golang-jwt/jwt/v5` from `5.2.1` to `5.2.2` to fix `CVE-2025-30204` (dependabot[bot])
  - Update `github.com/ebitengine/purego` to work around bug in `go1.24.3` (Nick Craig-Wood)

## `v1.69.2` - 2025-05-01

See commits

### Bug fixes

- accounting: Fix percentDiff calculation – (Anagh Kumar Baranwal)
- **build**
  - Update `github.com/golang-jwt/jwt/v4` from `4.5.1` to `4.5.2` to fix `CVE-2025-30204` (dependabot[bot])
  - Update `github.com/golang-jwt/jwt/v5` from `5.2.1` to `5.2.2` to fix `CVE-2025-30204` (dependabot[bot])
  - Update `golang.org/x/crypto` to `v0.35.0` to fix `CVE-2025-22869` (Nick Craig-Wood)
  - Update `golang.org/x/net` from `0.36.0` to `0.38.0` to fix `CVE-2025-22870` (dependabot[bot])
  - Update `golang.org/x/net` to `0.36.0`. to fix `CVE-2025-22869` (dependabot[bot])
  - Stop building with go < `go1.23` as security updates forbade it (Nick Craig-Wood)
  - Fix docker plugin build (Anagh Kumar Baranwal)
- cmd: Fix crash if rclone is invoked without any arguments (Janne Hellsten)
- config: Read configuration passwords from stdin even when terminated with EOF (Samantha Bowen)
- doc fixes (Andrew Kreimer, Danny Garside, eccoisle, Ed Craig-Wood, emyarod, jack, Jugal Kishore, Markus Gerstel, Michael Kebe, Nick Craig-Wood, simonmcnair, simwai, Zachary Vorhies)
- fs: Fix corruption of `SizeSuffix` with `"B"` suffix in config (eg `--min-size`) (Nick Craig-Wood)
- `lib/http`: Fix race between `Serve()` and `Shutdown()` (Nick Craig-Wood)
- object: Fix memory object out of bounds `Seek` (Nick Craig-Wood)
- operations: Fix call `fmt.Errorf` with wrong err (alingse)
- **rc**
  - Disable the metrics server when running `rclone rc` (hiddenmarten)
  - Fix `debug/*` commands not being available over unix sockets (Nick Craig-Wood)
- serve nfs: Fix unlikely crash (Nick Craig-Wood)
- stats: Fix the speed not getting updated after a pause in the processing (Anagh Kumar Baranwal)
- **sync**
  - Fix cpu spinning when empty directory finding with leading slashes (Nick Craig-Wood)
  - Copy dir modtimes even when `copyEmptySrcDirs` is false (ll3006)
- **VFS**
  - Fix directory cache serving stale data (Lorenz Brun)
  - Fix inefficient directory caching when directory reads are slow (huanghaojun)
  - Fix integration test failures (Nick Craig-Wood)
- **Drive**
  - Metadata: fix error when setting `copy-requires-writer-permission` on a folder (Nick Craig-Wood)
- **Dropbox**
  - Retry link without expiry (Dave Vasilevsky)
- **HTTP**
  - Correct root if definitely pointing to a file (nielash)
- **Iclouddrive**
  - Fix so created files are writable (Ben Alex)
- **Onedrive**
  - Fix metadata ordering in permissions (Nick Craig-Wood)

## `v1.69.1` - 2025-02-14

See commits

### Bug Fixes

- `lib/oauthutil`: Fix redirect URL mismatch errors (Nick Craig-Wood)
- bisync: Fix listings missing concurrent modifications (nielash)
- serve s3: Fix list objects encoding-type (Nick Craig-Wood)

---

- <pink>**`fs`**</pink>: fixed that absolutely deranged “didn’t find section in config file” error, she was confusing everyone 😮‍💨 (Nick Craig-Wood)
- <pink>**doc fixes**</pink> 📚 (Christoph Berger, Dimitri Papadopoulos, Matt Ickstadt, Nick Craig-Wood, Tim White, Zachary Vorhies)
- <pink>**`build`**</pink>: added parallel docker builds and caching for `go build` in the container, we move ✨ (Anagh Kumar Baranwal)

- <purple>**VFS**</purple> 🦋
  - the cache was failing to upload symlinks whenever `--links` was specified — fixed, bestie (Nick Craig-Wood)
  - fixed a race that the race detector literally caught red-handed 👀 (Nick Craig-Wood)
  - the change notify channel now gets closed on `Shutdown` 🔒 (izouxv)

- <purple>**B2**</purple>
  - fixed `fatal error: concurrent map writes` — no more meltdown 💀 (Nick Craig-Wood)

- <purple>**Iclouddrive**</purple>
  - added notes on ADP and Missing PCS cookies 🍪 (Nick Craig-Wood)

- <purple>**Onedrive**</purple>
  - marked the German (`de`) region as **deprecated** ⚠️ (Nick Craig-Wood)

- <purple>**S3**</purple>
  - added a new storage class to the magalu provider 💅 (Bruno Fernandes)
  - added DigitalOcean regions `SFO2`, `LON1`, `TOR1`, `BLR1` 🌍 (jkpe)
  - added the latest Linode Object Storage endpoints ✨ (jbagwell-akamai)

---

## 🌈 v1.69.0 - 2025-01-12 🌈

See commits 📜

- <hotpink>**New backends**</hotpink> — okay NEW BABIES JUST DROPPED 👑
  - ICloud Drive (lostb1t)
  - Cloudinary (yuval-cloudinary)
  - new S3 providers:
    - Outscale (Matthias Gatto)
    - Selectel (Nick Craig-Wood)

- <red>**Security fixes**</red> 🔐
  - <pink>**`serve sftp`**</pink>: resolve `CVE-2024-45337` - Misuse of `ServerConfig.PublicKeyCallback` may cause authorization bypass (dependabot)
    - rclone was **not** vulnerable to this. phew 😅
    - see `https://github.com/advisories/GHSA-v778-237x-gjrc`
  - <pink>**`build`**</pink>: update `golang.org/x/net` to `v0.33.0` to fix `CVE-2024-45338` - Non-linear parsing of case-insensitive content (Nick Craig-Wood)
    - rclone was **not** vulnerable to this either. double phew 😮‍💨
    - see `https://github.com/advisories/GHSA-w32m-9786-jp63`

- <hotpink>**New Features**</hotpink> 💖
  - <pink>**`accounting`**</pink>: write the current bwlimit to the log on `SIGUSR2` (Nick Craig-Wood)
  - <pink>**`bisync`**</pink>: change exit code from `2` to `7` for critically aborted run (albertony)
  - <pink>**`build`**</pink>
    - update all dependencies (Nick Craig-Wood)
    - replace the Windows-specific `NewLazyDLL` with `NewLazySystemDLL` (albertony)
  - <pink>**`cmd`**</pink>: change exit code from `1` to `2` for syntax and usage errors (albertony)
  - <pink>**`docker serve`**</pink>: make sure all mount and VFS options are parsed (Nick Craig-Wood)
  - <pink>**doc fixes**</pink> (albertony, Alexandre Hamez, Anthony Metzidis, buengese, Dan McArdle, David Seifert, Francesco Frassinelli, Michael R. Davis, Nick Craig-Wood, Pawel Palucha, Randy Bush, remygrandin, Sam Harrison, shenpengfeng, tgfisher, Thomas ten Cate, ToM, Tony Metzidis, vintagefuture, Yxxx)
  - <pink>**`fs`**</pink>: make the `--links` flag global and add new `--local-links` and `--vfs-links` flags (Nick Craig-Wood)
  - <pink>**http servers**</pink>: disable automatic authentication skipping for unix sockets in http servers (Moises Lima)
    - this was making it impossible to use unix sockets with a proxy 🙈
    - this might now cause rclone to need authentication where it didn’t before ⚠️
  - <pink>**`oauthutil`**</pink>: add support for OAuth client credential flow (Martin Hassack, Nick Craig-Wood)
  - <pink>**`operations`**</pink>: make log messages consistent for `mkdir`/`rmdir` at `INFO` level (Nick Craig-Wood)
  - <pink>**`rc`**</pink>: add `relative` to `vfs/queue-set-expiry` (Nick Craig-Wood)
  - <pink>**`serve dlna`**</pink>: sort the directory entries by directories first then alphabetically by name (Nick Craig-Wood)
  - <pink>**`serve nfs`**</pink>
    - introduce symlink support (Nick Craig-Wood)
    - implement `--nfs-cache-type symlink` (Nick Craig-Wood)
  - <pink>**`size`**</pink>: make output compatible with `-P` (Nick Craig-Wood)
  - <pink>**`test makefiles`**</pink>: add `--flat` flag for making directories with many entries (Nick Craig-Wood)

- <hotpink>**Bug Fixes**</hotpink> 🐛
  - <pink>**`accounting`**</pink>
    - fix global error acounting (Benjamin Legrand)
    - fix debug printing when debug wasn’t set (Nick Craig-Wood)
    - fix race stopping/starting the stats counter (Nick Craig-Wood)
  - <pink>**`rc/job`**</pink>: use mutex for adding listeners thread safety (hayden.pan)
  - <pink>**`serve docker`**</pink>: fix incorrect GID assignment (TAKEI Yuya)
  - <pink>**`serve nfs`**</pink>: fix missing inode numbers which was messing up `ls -laR` (Nick Craig-Wood)
  - <pink>**`serve s3`**</pink>: fix `Last-Modified` timestamp (Nick Craig-Wood)
  - <pink>**`serve sftp`**</pink>: fix loading of authorized keys file with comment on last line (albertony)

- <purple>**Mount**</purple> 🧚
  - introduce symlink support (Filipe Azevedo, Nick Craig-Wood)
  - better snap mount error message (divinity76)
  - <pink>**`mount2`**</pink>: fix missing `.` and `..` entries (Filipe Azevedo)

- <purple>**VFS**</purple> 🦋
  - with `--vfs-used-is-size` value is calculated and then thrown away (Ilias Ozgur Can Leonard)
  - add symlink support to VFS (Filipe Azevedo, Nick Craig-Wood)
    - this can be enabled with the specific `--vfs-links` flag or the global `--links` flag
  - fix open files disappearing from directory listings (Nick Craig-Wood)
  - add remote name to vfs cache log messages (Nick Craig-Wood)

- <purple>**Cache**</purple>
  - fix parent not getting pinned when remote is a file (nielash)

- <purple>**Azure Blob**</purple>
  - add `--azureblob-disable-instance-discovery` (Nick Craig-Wood)
  - add `--azureblob-use-az` to force the use of the Azure CLI for auth (Nick Craig-Wood)
  - quit multipart uploads if the context is cancelled (Nick Craig-Wood)

- <purple>**Azurefiles**</purple>
  - fix missing `x-ms-file-request-intent` header (Nick Craig-Wood)

- <purple>**B2**</purple>
  - add `daysFromStartingToCancelingUnfinishedLargeFiles` to backend lifecycle command (Louis Laureys)

- <purple>**Box**</purple>
  - fix server-side copying a file over existing dst (nielash)
  - fix panic when decoding corrupted PEM from JWT file (Nick Craig-Wood)

- <purple>**Drive**</purple>
  - add support for markdown format (Noam Ross)
  - implement `rclone backend rescue` to rescue orphaned files (Nick Craig-Wood)

- <purple>**Dropbox**</purple>
  - fix server side copying over existing object (Nick Craig-Wood)
  - fix return status when full to be fatal error (Nick Craig-Wood)

- <purple>**FTP**</purple>
  - implement `--ftp-no-check-upload` to allow upload to write only dirs (Nick Craig-Wood)
  - fix `ls` commands returning empty on “Microsoft FTP Service” servers (Francesco Frassinelli)

- <purple>**Gofile**</purple>
  - fix server side copying over existing object (Nick Craig-Wood)

- <purple>**Google Cloud Storage**</purple>
  - add access token auth with `--gcs-access-token` (Leandro Piccilli)
  - update docs on service account access tokens (Anthony Metzidis)

- <purple>**Googlephotos**</purple>
  - implement `--gphotos-proxy` to allow download of full resolution media (Nick Craig-Wood)
  - fix nil pointer crash on upload (Nick Craig-Wood)

- <purple>**HTTP**</purple>
  - fix incorrect URLs with initial slash (Oleg Kunitsyn)

- <purple>**Onedrive**</purple>
  - add support for OAuth client credential flow (Martin Hassack, Nick Craig-Wood)
  - fix time precision for OneDrive personal (Nick Craig-Wood)
  - fix server side copying over existing object (Nick Craig-Wood)

- <purple>**Opendrive**</purple>
  - add `rclone about` support to backend (quiescens)

- <purple>**Oracle Object Storage**</purple>
  - make specifying `compartmentid` optional (Manoj Ghosh)
  - quit multipart uploads if the context is cancelled (Nick Craig-Wood)

- <purple>**Pikpak**</purple>
  - add option to use original file links (wiserain)

- <purple>**Protondrive**</purple>
  - improve performance of Proton Drive backend (Lawrence Murray)

- <purple>**Putio**</purple>
  - fix server side copying over existing object (Nick Craig-Wood)

- <purple>**S3**</purple>
  - add initial `--s3-directory-bucket` to support AWS Directory Buckets (Nick Craig-Wood)
  - add Wasabi `eu-south-1` region (Diego Monti)
  - fix download of compressed files from Cloudflare R2 (Nick Craig-Wood)
  - rename glacier storage class to flexible retrieval (Henry Lee)
  - quit multipart uploads if the context is cancelled (Nick Craig-Wood)

- <purple>**SFTP**</purple>
  - allow inline ssh public certificate for sftp (Dimitar Ivanov)
  - fix nil check when using auth proxy (Nick Craig-Wood)

- <purple>**Smb**</purple>
  - add initial support for Kerberos authentication (more work needed). (Francesco Frassinelli)
  - fix panic if stat fails (Nick Craig-Wood)

- <purple>**Sugarsync**</purple>
  - fix server side copying over existing object (Nick Craig-Wood)

- <purple>**WebDAV**</purple>
  - Nextcloud: implement backoff and retry for `423 LOCKED` errors (Nick Craig-Wood)
  - make `--webdav-auth-redirect` to fix `401` unauthorized on redirect (Nick Craig-Wood)

- <purple>**Yandex**</purple>
  - fix server side copying over existing object (Nick Craig-Wood)

- <purple>**Zoho**</purple>
  - use download server to accelerate downloads (buengese)
  - switch to large file upload API for larger files, fix missing URL encoding of filenames for the upload API (buengese)
  - print clear error message when missing oauth scope (buengese)
  - try to handle rate limits a bit better (buengese)
  - add support for private spaces (buengese)
  - make upload cutoff configurable (buengese)

---

## 🌈 v1.68.2 - 2024-11-15 🌈

See commits 📜

- <red>**Security fixes**</red> 🔐
  - <pink>**local backend**</pink>: `CVE-2024-52522`: fix permission and ownership on symlinks with `--links` and `--metadata` (Nick Craig-Wood)
    - **only affects users using `--metadata` and `--links` and copying files to the local backend** — so if that’s you, go update fr 😭
    - see `https://github.com/rclone/rclone/security/advisories/GHSA-hrxh-9w67-g4cv`
  - <pink>**`build`**</pink>: bump `github.com/golang-jwt/jwt/v4` from `4.5.0` to `4.5.1` (dependabot)
    - this is an issue in a dependency which is used for JWT certificates
    - see `https://github.com/golang-jwt/jwt/security/advisories/GHSA-29wx-vh33-7x7r`

- <hotpink>**Bug Fixes**</hotpink> 🐛
  - <pink>**`accounting`**</pink>: fix wrong message on `SIGUSR2` to enable/disable bwlimit (Nick Craig-Wood)
  - <pink>**`bisync`**</pink>: fix output capture restoring the wrong output for logrus (Dimitrios Slamaris)
  - <pink>**`dlna`**</pink>: fix `loggingResponseWriter` disregarding log level (Simon Bos)
  - <pink>**`serve s3`**</pink>: fix excess locking which was making serve s3 single threaded (Nick Craig-Wood)
  - <pink>**doc fixes**</pink> (Nick Craig-Wood, tgfisher, Alexandre Hamez, Randy Bush)

- <purple>**Local**</purple>
  - fix permission and ownership on symlinks with `--links` and `--metadata` (Nick Craig-Wood)
  - fix `--copy-links` on macOS when cloning (nielash)

- <purple>**Onedrive**</purple>
  - fix `Retry-After` handling to look at `503` errors also (Nick Craig-Wood)

- <purple>**Pikpak**</purple>
  - fix `cid`/`gcid` calculations for `fs.OverrideRemote` (wiserain)
  - fix fatal crash on startup with token that can’t be refreshed (Nick Craig-Wood)

- <purple>**S3**</purple>
  - fix crash when using `--s3-download-url` after migration to `SDKv2` (Nick Craig-Wood)

## v1.68.1 - 2024-09-24

See commits — the receipts are all right there if you wanna scroll them 💅

### Bug Fixes 🐛

- **build** — fixed the docker release build (ttionya)
- **doc fixes** — documentation got a lil glow-up (Nick Craig-Wood, Pawel Palucha)
- **fs**
  - fixed `--dump` filters not always appearing (Nick Craig-Wood)
  - fixed setting stringArray config values from environment variables (Nick Craig-Wood)
- **rc** — fixed the default value of `--metrics-addr` (Nick Craig-Wood)
- **serve docker** — added the missing `vfs-read-chunk-streams` option in the docker volume driver (Divyam)

### Onedrive

- fixed that spurious "Couldn't decode error response: EOF" DEBUG like bestie it was just lying for no reason (Nick Craig-Wood) 😭

### Pikpak

- fixed a login issue where token retrieval was just,,, failing (wiserain) 🫶

### S3

- fixed rclone ignoring static credentials when `env_auth=true` (Nick Craig-Wood)

---

## v1.68.0 - 2024-09-08

See commits

### New backends 🎉

- Files.com (Sam Harrison)
- Gofile (Nick Craig-Wood)
- Pixeldrain (Fornax)

### Changed backends

- the S3 backend got updated to use AWS SDKv2 because v1 is now unsupported 👑
  - heads up: the matrix of providers and auth methods is **huge** and there could be problems with obscure combinations
  - please report problems in a new issue on Github 🫶

### New commands

- `config encryption`: `set`, `remove` and `check` to manage config file encryption (Nick Craig-Wood)

### New Features ✨

- **build**
  - update to go1.23 and make go1.21 the minimum required version (Nick Craig-Wood)
  - update all dependencies (Nick Craig-Wood)
  - disable wasm/js build due to go bug #64856 (Nick Craig-Wood)
  - enable custom linting rules with ruleguard via gocritic (albertony)
  - update logging statements to make `--use-json-log` work always (albertony)
  - adding new code quality tests and fixing the fallout (albertony)
- **config**
  - internal config re-organised to be more consistent and make it available from the rc (Nick Craig-Wood)
  - avoid remotes with empty names from the environment (albertony)
  - make listing of remotes more consistent (albertony)
  - make getting config values more consistent (albertony)
  - use `--password-command` to set config file password if supplied (Nick Craig-Wood)
- **doc fixes** (albertony, crystalstall, David Seifert, Eng Zer Jun, Ernie Hershey, Florian Klink, John Oxley, kapitainsky, Mathieu Moreau, Nick Craig-Wood, nipil, Pétr Bozsó, Russ Bubley, Sam Harrison, Thearas, URenko, Will Miles, yuval-cloudinary)
- **fs**: allow semicolons as well as spaces in `--bwlimit` timetable parsing (Kyle Reynolds)
- **help**
  - global flags help command now takes glob filter (albertony)
  - make help command output less distracting (albertony)
- **lib/encoder**: add Raw encoding for use where no encoding at all is required, eg `--local-encoding Raw` (URenko)
- **listremotes**: added options for filtering, ordering and json output (albertony)
- **nfsmount**
  - make the `--sudo` flag work for umount as well as mount (Nick Craig-Wood)
  - add `-o tcp` option to NFS mount options to fix mounting under Linux (Nick Craig-Wood)
- **operations**: `copy`: generate stable partial suffix (Georg Welzel)
- **rc**
  - add `options/info` call to enumerate options (Nick Craig-Wood)
  - add option blocks parameter to `options/get` and `options/info` (Nick Craig-Wood)
  - add `vfs/queue` to show the status of the upload queue (Nick Craig-Wood)
  - add `vfs/queue-set-expiry` to adjust expiry of items in the VFS queue (Nick Craig-Wood)
  - add `--unix-socket` option to rc command (Florian Klink)
  - prevent unmount rc command from sending a `STOPPING=1` sd-notify message (AThePeanut4)
- **rcserver**: implement prometheus metrics on a dedicated port (Oleg Kunitsyn)
- **serve dlna**
  - also look at "Subs" subdirectory (Florian Klink)
  - don't swallow `video.{idx,sub}` (Florian Klink)
  - set more correct mime type (Florian Klink)
- **serve nfs**
  - implement on disk cache for file handles selected with `--nfs-cache-type` (Nick Craig-Wood)
  - add tracing to filesystem calls (Nick Craig-Wood)
  - mask unimplemented error from chmod (Nick Craig-Wood)
  - unify the nfs library logging with rclone's logging better (Nick Craig-Wood)
  - fix incorrect user id and group id exported to NFS (Nick Craig-Wood)
- **serve s3**
  - implement `--auth-proxy` (Sawjan Gurung)
  - update to AWS SDKv2 by updating `github.com/rclone/gofakes3` (Nick Craig-Wood)

### Bug Fixes 🐛

- **bisync**: fix sync time problems with backends that round time (eg Dropbox) (nielash)
- **serve dlna**: fix panic: invalid argument to Int63n (Nick Craig-Wood)

### VFS

- add `--vfs-read-chunk-streams` to parallel read chunks from files (Nick Craig-Wood)
  - this can increase mount performance on high bandwidth or large latency links 🔥
- fix cache encoding with special characters (URenko)

### Local

- fix encoding of root path fix (URenko)
- add server-side copy (using clone) with xattrs on macOS (nielash)
  - `--local-no-clone` flag to disable cloning for server-side copies (nielash)
- support setting custom `--metadata` during server-side Copy (nielash)

### Azure Blob

- allow anonymous access for public resources (Nick Craig-Wood)

### B2

- include custom upload headers in large file info (Pat Patterson)

### Drive

- fix copying Google Docs to a backend which only supports SHA1 (Nick Craig-Wood)

### Fichier

- fix detection of Flood Detected error (Nick Craig-Wood)
- fix server side move (Nick Craig-Wood)

### HTTP

- reload client certificates on expiry (Saleh Dindar)
- support listening on passed FDs (Florian Klink)

### Jottacloud

- fix setting of metadata on server side move (albertony)

### Onedrive

- fix nil pointer error when uploading small files (Nick Craig-Wood)

### Pcloud

- implement `SetModTime` (Georg Welzel)
- implement `OpenWriterAt` feature to enable multipart uploads (Georg Welzel)
- fix failing large file uploads (Georg Welzel)

### Pikpak

- improve data consistency by ensuring async tasks complete (wiserain)
- implement custom hash to replace wrong sha1 (wiserain)
- fix error with copyto command (wiserain)
- optimize file move by removing unnecessary `readMetaData()` call (wiserain)
- non-buffered hash calculation for local source files (wiserain)
- optimize upload by pre-fetching gcid from API (wiserain)
- correct file transfer progress for uploads by hash (wiserain)
- update to using AWS SDK v2 (wiserain)

### S3

- update to using AWS SDK v2 (Nick Craig-Wood)
  - add `--s3-sdk-log-mode` to control SDKv2 debugging (Nick Craig-Wood)
- fix incorrect region for Magalu provider (Filipe Herculano)
- allow restoring from intelligent-tiering storage class (Pawel Palucha)

### SFTP

- use `uint32` for mtime to save memory (Tomasz Melcer)
- ignore useless errors when closing the connection pool (Nick Craig-Wood)
- support listening on passed FDs (Florian Klink)

### Swift

- add workarounds for bad listings in Ceph RGW (Paul Collins)
- add total/free space info in about command. (fsantagostinobietti)

### Ulozto

- fix upload of > 2GB files on 32 bit platforms (Tobias Markus)

### WebDAV

- add `--webdav-unix-socket-path` to connect to a unix socket (Florian Klink)

### Yandex

- implement custom user agent to help with upload speeds (Sebastian Bünger)

### Zoho

- fix inefficiencies uploading with new API to avoid throttling (Nick Craig-Wood)

---

## v1.67.0 - 2024-06-14

See commits

### New backends 🎉

- uloz.to (iotmaestro)
- New S3 providers
  - Magalu Object Storage (Bruno Fernandes)

### New commands

- `gitannex`: enables git-annex to store and retrieve content from an rclone remote (Dan McArdle)

### New Features ✨

- **accounting**: add deleted files total size to status summary line (Kyle Reynolds)
- **build**
  - fix CVE-2023-45288 by upgrading `golang.org/x/net` (Nick Craig-Wood)
  - fix CVE-2024-35255 by upgrading `github.com/Azure/azure-sdk-for-go/sdk/azidentity` to 1.6.0 (dependabot)
  - convert source files with CRLF to LF (albertony)
  - update all dependencies (Nick Craig-Wood)
- **doc updates** (albertony, Alex Garel, Dave Nicolson, Dominik Joe Pantůček, Eric Wolf, Erisa A, Evan Harris, Evan McBeth, Gachoud Philippe, hidewrong, jakzoe, jumbi77, kapitainsky, Kyle Reynolds, Lewis Hook, Nick Craig-Wood, overallteach, pawsey-kbuckley, Pieter van Oostrum, psychopatt, racerole, static-moonlight, Warrentheo, yudrywet, yumeiyin )
- **ncdu**: do not quit on Esc to aid usability (Katia Esposito)
- **rcserver**: set ModTime for dirs and files served by `--rc-serve` (Nikita Shoshin)

### Bug Fixes 🐛

- **bisync**: add integration tests against all backends and fix many many problems (nielash)
- **config**: fix default value for description (Nick Craig-Wood)
- **copy**: fix nil pointer dereference when corrupted on transfer with nil dst (nielash)
- **fs**
  - improve JSON Unmarshalling for Duration types (Kyle Reynolds)
  - close the CPU profile on exit (guangwu)
  - replace `/bin/bash` with `/usr/bin/env bash` (Florian Klink)
- **oauthutil**: clear client secret if client ID is set (Michael Terry)
- **operations**
  - rework rcat so that it doesn't call the `--metadata-mapper` twice (Nick Craig-Wood)
  - ensure `SrcFsType` is set correctly when using `--metadata-mapper` (Nick Craig-Wood)
  - fix "optional feature not implemented" error with a crypted sftp bug (Nick Craig-Wood)
  - fix very long file names when using copy with `--partial` (Nick Craig-Wood)
  - fix retries downloading too much data with certain backends (Nick Craig-Wood)
  - fix move when dst is nil and fdst is case-insensitive (nielash)
  - fix `lsjson --encrypted` when using `--crypt-XXX` parameters (Nick Craig-Wood)

- Fix missing metadata for multipart transfers to local disk — ty Nick Craig-Wood 🫶
  - Fix incorrect modtime on some multipart transfers — Nick Craig-Wood, king 👑
  - Fix hashing problem in integration tests — Nick Craig-Wood again 💪

  - **`rc`** 💅
    - stats groups were being straight-up ignored in `operations/check` — fixed (Nick Craig-Wood)
    - the `Content-Type` in the HTTP API was wrong — fixed (Kyle Reynolds)

  - **`serve s3`**
    - `Last-Modified` header format fixed (Butanediol)
    - in-memory metadata was storing the wrong modtime — fixed (nielash)
    - XML of the error message fixed (Nick Craig-Wood)

  - **`serve webdav`**: webdav with `--baseurl` under Windows works again (Nick Craig-Wood)

  - **`serve dlna`**: `BrowseMetadata` is way more compliant now (albertony)

  - **`serve http`**: added `Content-Length` header when an HTML directory is served (Sunny)

  - **`sync`** 🧚
    - doesn't sync directories if they haven't been modified (Nick Craig-Wood)
    - doesn't test reading metadata if we can't write it (Nick Craig-Wood)
    - case normalisation fixed, which was a whole problem on s3 (Nick Craig-Wood)
    - empty directory management fixed so it's way more accurate (Nick Craig-Wood)
    - creation of empty directories when `--create-empty-src-dirs=false` fixed (Nick Craig-Wood)
    - directory modification times not being set — fixed (Nick Craig-Wood)
    - the whole `"failed to update directory timestamp or metadata: directory not found"` thing — fixed (Nick Craig-Wood)
    - no more expecting SFTP to have the `MkdirMetadata` method, aka "optional feature not implemented" (Nick Craig-Wood)

  - **`test info`**: temp file cleanup is better now (Kyle Reynolds)

  - **`touch`**: using `-R` on certain backends fixed (Nick Craig-Wood)

- **Mount** 🗻
  - added the `--direct-io` flag to force uncached access (Nick Craig-Wood)

- **VFS**
  - download loop when a file's size shrunk — fixed (Nick Craig-Wood)
  - renaming a directory fixed (nielash)

- **Local** 💻
  - added `--local-time-type` to use mtime/atime/btime/ctime as the time (Nick Craig-Wood)
  - `SeBackupPrivilege` and/or `SeRestorePrivilege` are allowed to work on Windows now (Charles Hamilton)

- **Azure Blob**
  - encoding issue with dir path comparison fixed (nielash)

- **B2**
  - added the new `cleanup` and `cleanup-hidden` backend commands  (Pat Patterson)
  - B2 URLs updated to their new home (Nick Craig-Wood)

- **Chunker**
  - startup fixed when the root points to a composite multi-chunk file without metadata (nielash)
  - case-insensitive comparison fixed on local without metadata (nielash)
  - the `"finalizer already set"` error — fixed (nielash)

- **Drive** 🚗
  - added a backend `query` command for general purpose querying of files (John-Paul Smith)
  - no more sending notification emails when setting permissions (Nick Craig-Wood)
  - server side copy with metadata from my drive to shared drive fixed (Nick Craig-Wood)
  - all metadata permissions are set now, and it returns an error summary instead of stopping on the first error (Nick Craig-Wood)
  - errors setting permissions are now no retry errors (Nick Craig-Wood)
  - description being overwritten on server side moves — fixed (Nick Craig-Wood)
  - setting metadata is allowed to fail if the `failok` flag is set (Nick Craig-Wood)
  - panic when using `--metadata-mapper` on large google doc files — fixed (Nick Craig-Wood)

- **Dropbox**
  - added `--dropbox-root-namespace` to override the root namespace (Bill Fraser)

- **Google Cloud Storage**
  - encoding issue with dir path comparison fixed (nielash)

- **Hdfs**
  - `f.String()` not including the subpath — fixed (nielash)

- **Http**
  - added `--http-no-escape` to not escape URL metacharacters in path names (Kyle Reynolds)

- **Jottacloud**
  - metadata is now set on server side copy and move (albertony)

- **Linkbox**
  - working with names longer than 8-25 Unicode chars fixed  (Vitaly)
  - list paging and optimized synchronization fixed  (gvitali)

- **Mailru**
  - attempt to fix throttling by increasing min sleep to 100ms (Nick Craig-Wood)

- **Memory**
  - `dst` mutating `src` after a server-side copy — fixed (nielash)
  - deadlock in `operations.Purge` — fixed (nielash)
  - incorrect list entries when rooted at a subdirectory — fixed (nielash)

- **Onedrive**
  - added `--onedrive-hard-delete` to permanently delete files (Nick Craig-Wood)
  - server-side copy now works in more scenarios (YukiUnHappy)
  - the `"unauthenticated: Unauthenticated"` errors when downloading — fixed (Nick Craig-Wood)
  - `--metadata-mapper` was being called twice if writing permissions — fixed (nielash)
  - all metadata permissions are set now, and it returns an error summary instead of stopping on the first error (nielash)
  - errors setting permissions are now no retry errors (Nick Craig-Wood)
  - skips writing permissions with the `owner` role (nielash)
  - references to deprecated permissions properties fixed (nielash)
  - added support for group permissions (nielash)
  - setting permissions is allowed to fail if the `failok` flag is set (Nick Craig-Wood)

- **Pikpak**
  - `getFile()` usage made more efficient so we avoid the download limit (wiserain)
  - upload reliability improved and potential file conflicts resolved (wiserain)
  - configurable chunk size implemented for multipart upload (wiserain)

- **Protondrive**
  - no more authing with an empty access token (Michał Dzienisiewicz)

- **Qingstor**
  - integration tests disabled because the test account got suspended (Nick Craig-Wood)

- **Quatrix**
  - `f.String()` not including the subpath — fixed (nielash)

- **S3**
  - added the new AWS region `il-central-1` Tel Aviv (yoelvini)
  - Scaleway's configuration options updated (Alexandre Lavigne)
  - Ceph: quirks fixed when creating buckets, which fixes trying to create an existing bucket (Thomas Schneider)
  - encoding issue with dir path comparison fixed (nielash)
  - 405 error on HEAD for delete marker with `versionId` fixed (nielash)
  - `--s3-copy-cutoff` size is validated before copy (hoyho)

- **SFTP**
  - added `--sftp-connections` to limit the maximum number of connections (Tomasz Melcer)

- **Storj**
  - `storj.io/uplink` updated to the latest release (JT Olio)
  - bio updated on request (Nick Craig-Wood)

- **Swift**
  - implemented `--swift-use-segments-container` to allow >5G files on Blomp (Nick Craig-Wood)

- **Union**
  - deleting dirs fixed for when all remotes can't have empty dirs (Nick Craig-Wood)

- **WebDAV**
  - setting modification times was erasing checksums on owncloud and nextcloud — fixed (nielash)
  - owncloud: added `--webdav-owncloud-exclude-mounts`, which lets you exclude mounted folders when listing remote resources (Thomas Müller)

- **Zoho**
  - throttling problem when uploading files fixed (Nick Craig-Wood)
  - cursor listing used for improved performance (Nick Craig-Wood)
  - reading info is retried after upload if the size wasn't returned (Nick Craig-Wood)
  - the simple file names complication is gone, it's not needed anymore (Nick Craig-Wood)
  - sleeps for 60 seconds if a rate limit error is received (Nick Craig-Wood)

---

## v1.66.0 - 2024-03-10

See commits 👀

- **Major features** ✨
  - rclone will now sync directory modification times if the backend supports it 💖
    - this can be disabled with `--no-update-dir-modtime`
    - peep the overview and look for the <yellow>D</yellow> flags in the <yellow>ModTime</yellow> column to see which backends support it
  - rclone will now sync directory metadata if the backend supports it when `-M`/`--metadata` is in use 💅
    - same deal — check the overview and look for the <yellow>D</yellow> flags in the <yellow>Metadata</yellow> column to see which backends support it
  - Bisync has received many updates, see below for more details or bisync's changelog 🌈

- **Removed backends** 💀
  - `amazonclouddrive`: the Amazon Drive backend code and docs got removed (Nick Craig-Wood)

- **New Features** 🌟
  - **backend**
    - description field added for all backends (Paul Stern)
  - **build**
    - updated to go1.22, and go1.20 is now the minimum required version (Nick Craig-Wood)
    - CVE-2024-24786 fixed by upgrading `google.golang.org/protobuf` (Nick Craig-Wood)
  - **check**: respects `--no-unicode-normalization` and `--ignore-case-sync` for `--checkfile` (nielash)
  - **cmd**: much improved shell auto completion, which reduces the size of the completion file and works faster (Nick Craig-Wood)
  - **doc updates** (albertony, ben-ba, Eli, emyarod, huajin tong, Jack Provance, kapitainsky, keongalvin, Nick Craig-Wood, nielash, rarspace01, rzitzer, Tera, Vincent Murphy)
  - **fs**: more detailed logging for file includes/excludes (Kyle Reynolds)
  - **lsf**
    - added the `--time-format` flag (nielash)
    - metadata now appears for directories (Nick Craig-Wood)
  - **lsjson**: metadata now appears for directories (Nick Craig-Wood)
  - **rc**
    - added `srcFs` and `dstFs` to `core/stats` and `core/transferred` stats (Nick Craig-Wood)
    - added `operations/hashsum` to the rc as the `rclone hashsum` equivalent (Nick Craig-Wood)
    - added `config/paths` to the rc as the `rclone config paths` equivalent (Nick Craig-Wood)
  - **sync**
    - optionally reports a list of synced paths to a file (nielash)
    - implemented directory sync for mod times and metadata (Nick Craig-Wood)
    - doesn't set directory modtimes if they're already set (nielash)
    - doesn't sync directory modtimes from backends which don't have directories (Nick Craig-Wood)

- **Bug Fixes** 🐛
  - **backend**
    - backends which use oauth now implement the Shutdown and shut the oauth down properly (rkonfj)
  - **bisync**
    - handles unicode and case normalization consistently (nielash)
    - the partial uploads known issue on local/ftp/sftp has been resolved (unless you're using `--inplace`) (nielash)
    - fixed handling of unicode normalization and case insensitivity, plus support for `--fix-case`, `--ignore-case-sync`, `--no-unicode-normalization` (nielash)
    - bisync no longer fails to find the correct listing file when configs are overridden with backend-specific flags  (nielash)
  - **nfsmount**
    - exit after external unmount fixed (nielash)
    - `--volname` being ignored — fixed (nielash)
  - **operations**
    - renaming a file on macOS fixed (nielash)
    - case-insensitive moves in `operations.Move` fixed (nielash)
    - `TestCaseInsensitiveMoveFileDryRun` fixed on chunker integration tests (nielash)

- Fix the `TestMkdirModTime` test (Nick Craig-Wood) — test suite self-care era ✨
  - Fix `TestSetDirModTime` for backends that have `SetDirModTime` but **not** `Metadata` (Nick Craig-Wood) 🫶
  - Fix a typo in the log messages (nielash) 💀

  - <cyan>`serve nfs`</cyan>: fix writing files via Finder on macOS (nielash) 🍎
  - <cyan>`serve restic`</cyan>: fix error handling (Michael Eischer)
  - <cyan>`serve webdav`</cyan>: fix `--baseurl` without a leading `/` (Nick Craig-Wood)
  - <cyan>`stats`</cyan>: fix the race between `ResetCounters` and `stopAverageLoop` called from `time.AfterFunc` (Nick Craig-Wood) 🏁
  - <cyan>`sync`</cyan>
    - `--fix-case` flag to rename a case insensitive dest (nielash)
    - use `operations.DirMove` instead of `sync.MoveDir` for `--fix-case` (nielash)
  - <cyan>`systemd`</cyan>: fix detection and switch to the coreos package everywhere rather than having 2 separate libraries (Anagh Kumar Baranwal)

- **Mount** 💾
  - Fix macOS not noticing errors with `--daemon` (Nick Craig-Wood)
  - Notice daemon dying much quicker (Nick Craig-Wood)

- **VFS** 🗂️
  - Fix unicode normalization on macOS (nielash)

- **Bisync** 🔁 — okay this one ATE, it's giving glow-up of the century
  - Copies and deletes are now handled in one operation instead of two (nielash)
  - `--track-renames` and `--backup-dir` are now supported (nielash)
  - Final listings are now generated from sync results, to avoid needing to re-list (nielash)
  - Bisync is now much more resilient to changes that happen during a bisync run, and far less prone to critical errors / undetected changes (nielash)
  - Bisync is now capable of rolling a file listing back in cases of uncertainty, essentially marking the file as needing to be rechecked next time. (nielash)
  - A few basic terminal colors are now supported, controllable with `--color` (`AUTO`|`NEVER`|`ALWAYS`) (nielash) 🌈
  - Initial listing snapshots of Path1 and Path2 are now generated concurrently, using the same "march" infrastructure as check and sync, for performance improvements and less risk of error. (nielash)
  - `--resync` is now much more efficient (especially for users of `--create-empty-src-dirs`) (nielash)
  - Google Docs (and other files of unknown size) are now supported (with the same options as in sync) (nielash)
  - Equality checks before a sync conflict rename now fall back to cryptcheck (when possible) or `--download`, (nielash) instead of `--size-only`, when check is not available.
  - Bisync now fully supports comparing based on any combination of size, modtime, and checksum, lifting the prior restriction on backends without modtime support. (nielash)
  - Bisync now supports a "Graceful Shutdown" mode to cleanly cancel a run early without requiring `--resync`. (nielash)
  - New `--recover` flag allows robust recovery in the event of interruptions, without requiring `--resync`. (nielash)
  - A new `--max-lock` setting allows lock files to automatically renew and expire, for better automatic recovery when a run is interrupted. (nielash)
  - Bisync now supports auto-resolving sync conflicts and customizing rename behavior with new `--conflict-resolve`, `--conflict-loser`, and `--conflict-suffix` flags. (nielash)
  - A new `--resync-mode` flag allows more control over which version of a file gets kept during a `--resync`. (nielash)
  - Bisync now supports `--retries` and `--retries-sleep` (when `--resilient` is set.) (nielash)
  - Clarify file operation directions in dry-run logs (Kyle Reynolds)

- **Local** 🖥️
  - Fix `cleanRootPath` on Windows after `go1.21.4` stdlib update (nielash)
  - Implement setting modification time on directories (nielash)
  - Implement modtime and metadata for directories (Nick Craig-Wood)
  - Fix setting of btime on directories on Windows (Nick Craig-Wood)
  - Delete backend implementation of Purge to speed up and make stats (Nick Craig-Wood)
  - Support metadata setting and mapping on server side Move (Nick Craig-Wood)

- **Cache**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)

- **Crypt** 🔐
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)
  - Improve handling of undecryptable file names (nielash)
  - Add missing error check spotted by linter (Nick Craig-Wood)

- **Azure Blob** ☁️
  - Implement `--azureblob-delete-snapshots` (Nick Craig-Wood)

- **B2**
  - Clarify exactly what `--b2-download-auth-duration` does in the docs (Nick Craig-Wood)

- **Chunker**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)

- **Combine**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)
  - Fix directory metadata error on upstream root (nielash)
  - Fix directory move across upstreams (nielash)

- **Compress**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)

- **Drive**
  - Implement setting modification time on directories (nielash)
  - Implement modtime and metadata setting for directories (Nick Craig-Wood)
  - Support metadata setting and mapping on server side Move,Copy (Nick Craig-Wood)

- **FTP**
  - Fix mkdir with `rsftp` which is returning the wrong code (Nick Craig-Wood)

- **Hasher**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)
  - Fix error from trying to stop an already-stopped db (nielash)
  - Look for cached hash if passed hash unexpectedly blank (nielash)

- **Imagekit**
  - Updated docs and web content (Harshit Budhraja)
  - Updated overview - supported operations (Harshit Budhraja)

- **Mega**
  - Fix panic with `go1.22` (Nick Craig-Wood) 😭

- **Netstorage**
  - Fix Root to return correct directory when pointing to a file (Nick Craig-Wood)

- **Onedrive**
  - Add metadata support (nielash)

- **Opendrive**
  - Fix moving file/folder within the same parent dir (nielash)

- **Oracle Object Storage**
  - Support backend restore command (Nikhil Ahuja)
  - Support workload identity authentication for OKE (Anders Swanson)

- **Protondrive**
  - Fix encoding of Root method (Nick Craig-Wood)

- **Quatrix**
  - Fix `Content-Range` header (Volodymyr)
  - Add option to skip project folders (Oksana Zhykina)
  - Fix Root to return correct directory when pointing to a file (Nick Craig-Wood)

- **S3**
  - Add `--s3-version-deleted` to show delete markers in listings when using versions. (Nick Craig-Wood)
  - Add IPv6 support with option `--s3-use-dual-stack` (Anthony Metzidis)
  - Copy parts in parallel when doing chunked server side copy (Nick Craig-Wood)
  - GCS provider: fix server side copy of files bigger than 5G (Nick Craig-Wood)
  - Support metadata setting and mapping on server side Copy (Nick Craig-Wood)

- **Seafile**
  - Fix download/upload error when `FILE_SERVER_ROOT` is relative (DanielEgbers)
  - Fix Root to return correct directory when pointing to a file (Nick Craig-Wood)

- **SFTP**
  - Implement setting modification time on directories (nielash)
  - Set directory modtimes update on write flag (Nick Craig-Wood)
  - Shorten wait delay for external ssh binaries now that we are using `go1.20` (Nick Craig-Wood)

- **Swift**
  - Avoid unnecessary container versioning check (Joe Cai)

- **Union**
  - Implement setting modification time on directories (if supported by wrapped remote) (nielash)
  - Implement setting metadata on directories (Nick Craig-Wood)

- **WebDAV**
  - Reduce priority of chunks upload log (Gabriel Ramos)
  - owncloud: Add config `owncloud_exclude_shares` which allows to exclude shared files and folders when listing remote resources (Thomas Müller)

**v1.65.2 - 2024-01-24** 🌸

See commits

- **Bug Fixes**
  - build: bump `github.com/cloudflare/circl` from `1.3.6` to `1.3.7` (dependabot)
  - docs updates (Nick Craig-Wood, kapitainsky, nielash, Tera, Harshit Budhraja)

- **VFS**
  - Fix stale data when using `--vfs-cache-mode full` (Nick Craig-Wood)

- **Azure Blob**
  - **IMPORTANT** Fix data corruption bug - see `#7590` (Nick Craig-Wood)

> okay bestie, real talk: that Azure Blob one is a **data corruption** fix, so if you're on an affected version please update, this is not the vibe 💀🚨

**v1.65.1 - 2024-01-08** 🎀

See commits

- **Bug Fixes**
  - build
    - Bump `golang.org/x/crypto` to fix ssh terrapin `CVE-2023-48795` (dependabot)
    - Update to `go1.21.5` to fix Windows path problems (Nick Craig-Wood)
    - Fix docker build on `arm/v6` (Nick Craig-Wood)
  - `install.sh`: fix harmless error message on install (Nick Craig-Wood)
  - accounting: fix stats to show server side transfers (Nick Craig-Wood)
  - doc fixes (albertony, ben-ba, Eli Orzitzer, emyarod, keongalvin, rarspace01)
  - `nfsmount`: Compile for all unix oses, add `--sudo` and fix error/option handling (Nick Craig-Wood)
  - operations: Fix files moved by `rclone move` not being counted as transfers (Nick Craig-Wood)
  - oauthutil: Avoid panic when `*token` and `*ts.token` are the same (rkonfj)
  - serve s3: Fix listing oddities (Nick Craig-Wood)

- **VFS**
  - Note that `--vfs-refresh` runs in the background (Nick Craig-Wood)

- **Azurefiles**
  - Fix storage base url (Oksana)

- **Crypt**
  - Fix `rclone move` a file over itself deleting the file (Nick Craig-Wood)

- **Chunker**
  - Fix `rclone move` a file over itself deleting the file (Nick Craig-Wood)

- **Compress**
  - Fix `rclone move` a file over itself deleting the file (Nick Craig-Wood)

- **Dropbox**
  - Fix used space on dropbox team accounts (Nick Craig-Wood)

- **FTP**
  - Fix multi-thread copy (WeidiDeng)

- **Googlephotos**
  - Fix nil pointer exception when batch failed (Nick Craig-Wood)

- **Hasher**
  - Fix `rclone move` a file over itself deleting the file (Nick Craig-Wood)
  - Fix invalid memory address error when `MaxAge == 0` (nielash)

- **Onedrive**
  - Fix error listing: unknown object type `<nil>` (Nick Craig-Wood)

- **Fix "unauthenticated: Unauthenticated" errors when uploading** (Nick Craig-Wood) 💅 like bestie that error message was giving NOTHING and now it's gone

- <pink>**Oracleobjectstorage**</pink>

  - Fix object storage endpoint for custom endpoints (Manoj Ghosh) 🔥
  - <hotpink>Multipart copy create bucket if it doesn't exist.</hotpink> (Manoj Ghosh) — yes it just... makes it. iconic behaviour tbh

- <pink>**Protondrive**</pink>

  - Fix CVE-2023-45286 / GHSA-xwh9-gc39-5298 (Nick Craig-Wood) 🛡️ security girlies stay winning

- <pink>**S3**</pink>

  - Fix crash if no `UploadId` in multipart upload (Nick Craig-Wood) 💀 no more yeeting itself into the void

- <pink>**Smb**</pink>

  - Fix shares not listed by updating `go-smb2` (halms) ✨

- <pink>**Union**</pink>

  - Fix `rclone move` a file over itself deleting the file (Nick Craig-Wood) 😭 the way that was lowkey a self-own. fixed fr fr

---

## 🎀 v1.65.0 - 2023-11-26 🎀

*See commits* 🌸

- <purple>**New backends**</purple>

  - Azure Files (karan, moongdal, Nick Craig-Wood) 💖
  - ImageKit (Abhinav Dhiman) 🎀
  - Linkbox (viktor, Nick Craig-Wood) 🦋

- <purple>**New commands**</purple>

  - `serve s3`: Let rclone act as an S3 compatible server (Mikubill, Artur Neumann, Saw-jan, Nick Craig-Wood) 👑 main character server energy
  - `nfsmount`: mount command to provide mount mechanism on macOS without FUSE (Saleh Dindar) ✨
  - `serve nfs`: to serve a remote for use by `nfsmount` (Saleh Dindar) 🧚

- <purple>**New Features**</purple>

  - `install.sh`: Clean up temp files in install script (Jacob Hands) 🧹
  - **build**
    - Update all dependencies (Nick Craig-Wood) ⭐
    - Refactor version info and icon resource handling on windows (albertony) 🪟
  - doc updates (albertony, alfish2000, asdffdsazqqq, Dimitri Papadopoulos, Herby Gillot, Joda Stößer, Manoj Ghosh, Nick Craig-Wood) 📚 the doc girlies ate
  - Implement `--metadata-mapper` to transform metadata with a user supplied program (Nick Craig-Wood) 🦋
  - Add `ChunkWriterDoesntSeek` feature flag and set it for b2 (Nick Craig-Wood) 💅
  - `lib/http`: Export basic go string functions for use in `--template` (Gabriel Espinoza) ✨
  - `makefile`: Use POSIX compatible install arguments (Mina Galić) 🎀
  - **operations**
    - Use less memory when doing multithread uploads (Nick Craig-Wood) 🌸 so considerate
    - Implement `--partial-suffix` to control extension of temporary file names (Volodymyr) 🫶
  - **rc**
    - Add `operations/check` to the rc API (Nick Craig-Wood) 🔥
    - Always report an error as JSON (Nick Craig-Wood) 💜
    - Set `Last-Modified` header for files served by `--rc-serve` (Nikita Shoshin) ⭐
  - `size`: Dont show duplicate object count when less than 1k (albertony) 🙈

- <purple>**Bug Fixes**</purple>

  - `fshttp`: Fix `--contimeout` being ignored (你知道未来吗) 😭 bestie it was literally being ghosted
  - `march`: Fix excessive parallelism when using `--no-traverse` (Nick Craig-Wood) 💀
  - `ncdu`: Fix crash when re-entering changed directory after rescan (Nick Craig-Wood) 🔥
  - **operations**
    - Fix overwrite of destination when multi-thread transfer fails (Nick Craig-Wood) 🎀
    - Fix invalid UTF-8 when truncating file names when not using `--inplace` (Nick Craig-Wood) 🦋
  - `serve dnla`: Fix crash on graceful exit (wuxingzhong) 🍓

- <purple>**Mount**</purple>

  - Disable mount for freebsd and alias `cmount` as `mount` on that platform (Nick Craig-Wood) 🌈

- <purple>**VFS**</purple>

  - Add `--vfs-refresh` flag to read all the directories on start (Beyond Meat) ✨
  - Implement `Name()` method in `WriteFileHandle` and `ReadFileHandle` (Saleh Dindar) 💅
  - Add `go-billy` dependency and make sure `vfs.Handle` implements `billy.File` (Saleh Dindar) 🧚
  - Error out early if can't upload 0 length file (Nick Craig-Wood) 💜

- <purple>**Local**</purple>

  - Fix copying from Windows Volume Shadows (Nick Craig-Wood) 🪟👑

- <purple>**Azure Blob**</purple>

  - Add support for cold tier (Ivan Yanitra) 🧊 it's giving sub-zero

- <purple>**B2**</purple>

  - Implement `rclone backend lifecycle` to read and set bucket lifecycles (Nick Craig-Wood) 🌸
  - Implement `--b2-lifecycle` to control lifecycle when creating buckets (Nick Craig-Wood) ⭐
  - Fix listing all buckets when not needed (Nick Craig-Wood) 🙈
  - Fix multi-thread upload with `copyto` going to wrong name (Nick Craig-Wood) 😭
  - Fix server side chunked copy when file size was exactly `--b2-copy-cutoff` (Nick Craig-Wood) 💀
  - Fix streaming chunked files an exact multiple of chunk size (Nick Craig-Wood) 🔥

- <purple>**Box**</purple>

  - Filter more EventIDs when polling (David Sze) 🎀
  - Add more logging for polling (David Sze) 📝
  - Fix performance problem reading metadata for single files (Nick Craig-Wood) 🚀

- <purple>**Drive**</purple>

  - Add read/write metadata support (Nick Craig-Wood) 💖
  - Add support for SHA-1 and SHA-256 checksums (rinsuki) 🔐
  - Add `--drive-show-all-gdocs` to allow unexportable gdocs to be server side copied (Nick Craig-Wood) 🦋
  - Add a note that `--drive-scope` accepts comma-separated list of scopes (Keigo Imai) ✨
  - Fix error updating created time metadata on existing object (Nick Craig-Wood) ⏰
  - Fix integration tests by enabling metadata support from the context (Nick Craig-Wood) 🧪

- <purple>**Dropbox**</purple>

  - Factor batcher into `lib/batcher` (Nick Craig-Wood) 🎀
  - Fix missing encoding for `rclone purge` (Nick Craig-Wood) 🧹

- <purple>**Google Cloud Storage**</purple>

  - Fix 400 Bad request errors when using multi-thread copy (Nick Craig-Wood) 💀 not the 400 bestie

- <purple>**Googlephotos**</purple>

  - Implement batcher for uploads (Nick Craig-Wood) 📸 slay

- <purple>**Hdfs**</purple>

  - Added support for list of namenodes in hdfs remote config (Tayo-pasedaRJ) 🌈

- <purple>**HTTP**</purple>

  - Implement set backend command to update running backend (Nick Craig-Wood) 🔥
  - Enable methods used with WebDAV (Alen Šiljak) 💅

- <purple>**Jottacloud**</purple>

  - Add support for reading and writing metadata (albertony) 💜

- <purple>**Onedrive**</purple>

  - Implement `ListR` method which gives `--fast-list` support (Nick Craig-Wood) ⚡
    - This must be enabled with the `--onedrive-delta` flag 🚩 important bestie, don't forget

- <purple>**Quatrix**</purple>

  - Add partial upload support (Oksana Zhykina) 🎀
  - Overwrite files on conflict during server-side move (Oksana Zhykina) 💥

- <purple>**S3**</purple>

  - Add Linode provider (Nick Craig-Wood) 👑
  - Add docs on how to add a new provider (Nick Craig-Wood) 📖
  - Fix no error being returned when creating a bucket we don't own (Nick Craig-Wood) 😭
  - Emit a debug message if anonymous credentials are in use (Nick Craig-Wood) 🕵️
  - Add `--s3-disable-multipart-uploads` flag (Nick Craig-Wood) 🚫
  - Detect looping when using gcs and versions (Nick Craig-Wood) 🔁💀

- <purple>**SFTP**</purple>

  - Implement `--sftp-copy-is-hardlink` to server side copy as hardlink (Nick Craig-Wood) 🔗

- <purple>**Smb**</purple>

  - Fix incorrect about size by switching to `github.com/cloudsoda/go-smb2` fork (Nick Craig-Wood) 🍴
  - Fix modtime of multithread uploads by setting `PartialUploads` (Nick Craig-Wood) ⏱️

- <purple>**WebDAV**</purple>

  - Added an rclone vendor to work with `rclone serve webdav` (Adithya Kumar) 🦋

---

## 🎀 v1.64.2 - 2023-10-19 🎀

*See commits* 🌸

- <purple>**Bug Fixes**</purple>

  - `selfupdate`: Fix "invalid hashsum signature" error (Nick Craig-Wood) 🔐
  - build: Fix docker build running out of space (Nick Craig-Wood) 🐳😭 no space left bestie we've ALL been there

---

## 🎀 v1.64.1 - 2023-10-17 🎀

*See commits* 🌸

- <purple>**Bug Fixes**</purple>

  - cmd: Make `--progress` output logs in the same format as without (Nick Craig-Wood) 📊
  - docs fixes (Dimitri Papadopoulos Orfanos, Herby Gillot, Manoj Ghosh, Nick Craig-Wood) 📚
  - `lsjson`: Make sure we set the global metadata flag too (Nick Craig-Wood) 🚩
  - **operations**
    - Ensure concurrency is no greater than the number of chunks (Pat Patterson) 🧵
    - Fix `OpenOptions` ignored in copy if operation was a `multiThreadCopy` (Vitor Gomes) 🦋
    - Fix error message on delete to have file name (Nick Craig-Wood) 📛
  - `serve sftp`: Return not supported error for not supported commands (Nick Craig-Wood) 🙅
  - build: Upgrade `golang.org/x/net` to `v0.17.0` to fix HTTP/2 rapid reset (Nick Craig-Wood) 🔥
  - `pacer`: Fix b2 deadlock by defaulting max connections to unlimited (Nick Craig-Wood) 🔓

- <purple>**Mount**</purple>

  - Fix automount not detecting drive is ready (Nick Craig-Wood) 🚗💨

- <purple>**VFS**</purple>

  - Fix update dir modification time (Saleh Dindar) ⏰

- <purple>**Azure Blob**</purple>

  - Fix "fatal error: concurrent map writes" (Nick Craig-Wood) 💀

- <purple>**B2**</purple>

  - Fix multipart upload: corrupted on transfer: sizes differ XXX vs 0 (Nick Craig-Wood) 😭 not the XXX
  - Fix locking window when getting multipart upload URL (Nick Craig-Wood) 🔒
  - Fix server side copies greater than 4GB (Nick Craig-Wood) 📦
  - Fix chunked streaming uploads (Nick Craig-Wood) 🌊
  - Reduce default `--b2-upload-concurrency` to 4 to reduce memory usage (Nick Craig-Wood) 🧠✨

- <purple>**Onedrive**</purple>

  - Fix the configurator to allow `/teams/ID` in the config (Nick Craig-Wood) 🛠️

- <purple>**Oracleobjectstorage**</purple>

  - Fix `OpenOptions` being ignored in `uploadMultipart` with `chunkWriter` (Nick Craig-Wood) 💅

- <purple>**S3**</purple>

  - Fix slice bounds out of range error when listing (Nick Craig-Wood) 📋
  - Fix `OpenOptions` being ignored in `uploadMultipart` with `chunkWriter` (Vitor Gomes) 🦋

- <purple>**Storj**</purple>

  - Update `storj.io/uplink` to `v1.12.0` (Kaloyan Raev) 🚀

---

## 🎀 v1.64.0 - 2023-09-11 🎀

*See commits* 🌸

- <purple>**New backends**</purple>

  - Proton Drive (Chun-Hung Tseng) 🦋
  - Quatrix (Oksana, Volodymyr Kit) 🎀
  - New S3 providers
    - Synology C2 (BakaWang) ⭐
    - Leviia (Benjamin) ✨
  - New Jottacloud providers
    - Onlime (Fjodor42) 💖
    - Telia Sky (NoLooseEnds) 🌈

- <purple>**Major changes**</purple>

  - Multi-thread transfers (Vitor Gomes, Nick Craig-Wood, Manoj Ghosh, Edwin Mackenzie-Owen) 🔥🔥🔥 this is THE moment bestie
    - Multi-thread transfers are now available when transferring to:
      - `local`, `s3`, `azureblob`, `b2`, `oracleobjectstorage` and `smb` 👑
    - This greatly improves transfer speed between two network sources. ⚡
    - In memory buffering has been unified between all backends and should share memory better. 🧠
    - See *–multi-thread* docs for more info 📖

- <purple>**New commands**</purple>

  - `rclone config redacted` support mechanism for showing redacted config (Nick Craig-Wood) 🙈✂️

- <purple>**New Features**</purple>

  - **accounting**
    - Show server side stats in own lines and not as bytes transferred (Nick Craig-Wood) 📊
  - **bisync**
    - Add new `--ignore-listing-checksum` flag to distinguish from `--ignore-checksum` (nielash) 🎀
    - Add experimental `--resilient` mode to allow recovery from self-correctable errors (nielash) 🧪
    - Add support for `--create-empty-src-dirs` (nielash) 📁
    - Dry runs no longer commit filter changes (nielash) 🏃♀️
    - Enforce `--check-access` during `--resync` (nielash) 🔒
    - Apply filters correctly during deletes (nielash) 🗑️
    - Equality check before renaming (leave identical files alone) (nielash) 👯♀️ if it's identical let it LIVE
    - Fix `dryRun` rc parameter being ignored (nielash) 💅
  - build

- Update to `go1.21` and make `go1.19` the minimum required version (Anagh Kumar Baranwal, Nick Craig-Wood) — glow up ✨ minimum bar raised, no cap
- Update dependencies (Nick Craig-Wood) 🧚
- Add snap installation (hideo aoyama) 🍓
- Change Winget Releaser job to `ubuntu-latest` (sitiom)
- cmd: Refactor and use sysdnotify in more commands (eNV25) — yes, that spelling, we're keeping it, it's ✨iconic✨
- config: Add `--multi-thread-chunk-size` flag (Vitor Gomes)
- doc updates (antoinetran, Benjamin, Bjørn Smith, Dean Attali, gabriel-suela, James Braza, Justin Hellings, kapitainsky, Mahad, Masamune3210, Nick Craig-Wood, Nihaal Sangha, Niklas Hambüchen, Raymond Berger, r-ricci, Sawada Tsunayoshi, Tiago Boeing, Vladislav Vorobev) — the whole group chat showed up 💖
- fs
  - Use atomic types everywhere (Roberto Ricci) 🔥
  - When `--max-transfer` limit is reached exit with code (10) (kapitainsky)
  - Add `rclone completion powershell` - basic implementation only (Nick Craig-Wood) — she's a baby but she's here 🎀
- http servers: Allow CORS to be set with `--allow-origin` flag (yuudi)
- lib/rest: Remove unnecessary `nil` check (Eng Zer Jun)
- ncdu: Add keybinding to rescan filesystem (eNV25)
- rc
  - Add `executeId` to job listings (yuudi)
  - Add `core/du` to measure local disk usage (Nick Craig-Wood)
  - Add `operations/settier` to API (Drew Stinnett)
- `rclone test info`: Add `--check-base32768` flag to check can store all `base32768` characters (Nick Craig-Wood)
- rmdirs: Remove directories concurrently controlled by `--checkers` (Nick Craig-Wood)

**Bug Fixes** 🐛💀

- accounting: Don’t stop calculating average transfer speed until the operation is complete (Jacob Hands) — no cutting the math short bestie, let her finish
- fs: Fix `transferTime` not being set in JSON logs (Jacob Hands)
- fshttp: Fix `--bind 0.0.0.0` allowing IPv6 and `--bind ::0` allowing IPv4 (Nick Craig-Wood)
- operations: Fix overlapping check on case insensitive file systems (Nick Craig-Wood)
- serve dlna: Fix MIME type if backend can’t identify it (Nick Craig-Wood)
- serve ftp: Fix race condition when using the auth proxy (Nick Craig-Wood)
- serve sftp: Fix hash calculations with `--vfs-cache-mode full` (Nick Craig-Wood)
- serve webdav: Fix error: Expecting fs.Object or fs.Directory, got nil (Nick Craig-Wood)
- sync: Fix lockup with `--cutoff-mode=soft` and `--max-duration` (Nick Craig-Wood)

**Mount** 🌈

- fix: Mount parsing for linux (Anagh Kumar Baranwal)

**VFS** 🦋

- Add `--vfs-cache-min-free-space` to control minimum free space on the disk containing the cache (Nick Craig-Wood)
- Added cache cleaner for directories to reduce memory usage (Anagh Kumar Baranwal)
- Update parent directory modtimes on vfs actions (David Pedersen)
- Keep virtual directory status accurate and reduce deadlock potential (Anagh Kumar Baranwal)
- Make sure struct field is aligned for atomic access (Roberto Ricci)

**Local** 💅

- Rmdir return an error if the path is not a dir (zjx20)

**Azure Blob** 👑

- Implement `OpenChunkWriter` and multi-thread uploads (Nick Craig-Wood)
- Fix creation of directory markers (Nick Craig-Wood)
- Fix purging with directory markers (Nick Craig-Wood)

**B2** ⭐

- Implement `OpenChunkWriter` and multi-thread uploads (Nick Craig-Wood)
- Fix `rclone link` when object path contains special characters (Alishan Ladhani)

**Box** 🎀

- Add polling support (David Sze)
- Add `--box-impersonate` to impersonate a user ID (Nick Craig-Wood)
- Fix unhelpful decoding of error messages into decimal numbers (Nick Craig-Wood)

**Chunker** 🧩

- Update documentation to mention issue with small files (Ricardo D’O. Albanus)

**Compress** 🗜️

- Fix ChangeNotify (Nick Craig-Wood)

**Drive** 🔥

- Add `--drive-fast-list-bug-fix` to control ListR bug workaround (Nick Craig-Wood)

**Fichier** 🫶

- Implement DirMove (Nick Craig-Wood)
- Fix error code parsing (alexia)

**FTP** 🌸

- Add `socks_proxy` support for SOCKS5 proxies (Zach)
- Fix 425 “TLS session of data connection not resumed” errors (Nick Craig-Wood)

**Hdfs** 💜

- Retry “replication in progress” errors when uploading (Nick Craig-Wood)
- Fix uploading to the wrong object on Update with overridden remote name (Nick Craig-Wood)

**HTTP** 🌈

- CORS should not be sent if not set (yuudi)
- Fix webdav OPTIONS response (yuudi)

**Opendrive** ✨

- Fix List on a just deleted and remade directory (Nick Craig-Wood)

**Oracleobjectstorage** 🍓

- Use rclone’s rate limiter in multipart transfers (Manoj Ghosh)
- Implement `OpenChunkWriter` and multi-thread uploads (Manoj Ghosh)

**S3** 💖

- Refactor multipart upload to use `OpenChunkWriter` and `ChunkWriter` (Vitor Gomes)
- Factor generic multipart upload into `lib/multipart` (Nick Craig-Wood)
- Fix purging of root directory with `--s3-directory-markers` (Nick Craig-Wood)
- Add `rclone backend set` command to update the running config (Nick Craig-Wood)
- Add `rclone backend restore-status` command (Nick Craig-Wood)

**SFTP** 🦋

- Stop uploads re-using the same ssh connection to improve performance (Nick Craig-Wood)
- Add `--sftp-ssh` to specify an external ssh binary to use (Nick Craig-Wood)
- Add `socks_proxy` support for SOCKS5 proxies (Zach)
- Support dynamic `--sftp-path-override` (nielash)
- Fix spurious warning when using `--sftp-ssh` (Nick Craig-Wood)

**Smb** 🎀

- Implement multi-threaded writes for copies to smb (Edwin Mackenzie-Owen)

**Storj** ⭐

- Performance improvement for large file uploads (Kaloyan Raev)

**Swift** 💅

- Fix HEADing 0-length objects when `--swift-no-large-objects` set (Julian Lepinski)

**Union** 🫶

- Add `:writback` to act as a simple cache (Nick Craig-Wood) — yes bestie, that's the flag, we don't edit history 💖

**WebDAV** 🌸

- Nextcloud: fix segment violation in low-level retry (Paul)

**Zoho** 🧚

- Remove Range requests workarounds to fix integration tests (Nick Craig-Wood)

---

## v1.63.1 - 2023-07-17 👑

See commits

**Bug Fixes** 🐛

- build: Fix macos builds for versions < 12 (Anagh Kumar Baranwal)
- dirtree: Fix performance with large directories of directories and `--fast-list` (Nick Craig-Wood)
- operations
  - Fix deadlock when using lsd/ls with `--progress` (Nick Craig-Wood)
  - Fix `.rclonelink` files not being converted back to symlinks (Nick Craig-Wood)
- doc fixes (Dean Attali, Mahad, Nick Craig-Wood, Sawada Tsunayoshi, Vladislav Vorobev)

**Local** 💅

- Fix partial directory read for corrupted filesystem (Nick Craig-Wood)

**Box** 🎀

- Fix reconnect failing with HTTP 400 Bad Request (albertony)

**Smb** 🦋

- Fix “Statfs failed: bucket or container name is needed” when mounting (Nick Craig-Wood)

**WebDAV** 🌈

- Nextcloud: fix must use /dav/files/USER endpoint not /webdav error (Paul)
- Nextcloud chunking: add more guidance for the user to check the config (darix)

---

## v1.63.0 - 2023-06-30 ✨

See commits

**New backends** 🌱

- Pikpak (wiserain)
- New S3 providers
  - petabox.io (Andrei Smirnov)
  - Google Cloud Storage (Anthony Pessy)
- New WebDAV providers
  - Fastmail (Arnavion)

**Major changes** 🚨 (okay these are big, sit down)

- Files will be copied to a temporary name ending in `.partial` when copying to `local`, `ftp`, `sftp` then renamed at the end of the transfer. (Janne Hellsten, Nick Craig-Wood)
  - This helps with data integrity as we don’t delete the existing file until the new one is complete.
  - It can be disabled with the `--inplace` flag.
  - This behaviour will also happen if the backend is wrapped, for example `sftp` wrapped with `crypt`.
- The `s3`, `azureblob` and `gcs` backends now support directory markers so empty directories are supported (Jānis Bebrītis, Nick Craig-Wood)
- The `--default-time` flag now controls the unknown modification time of files/dirs (Nick Craig-Wood)
  - If a file or directory does not have a modification time rclone can read then rclone will display this fixed time instead.
  - For the old behaviour use `--default-time 0s` which will set this time to the time rclone started up.

**New Features** 💖

- build
  - Modernise linters in use and fixup all affected code (albertony)
  - Push docker beta to GHCR (GitHub container registry) (Richard Tweed)
- cat: Add `--separator` option to cat command (Loren Gordon)
- config
  - Do not remove/overwrite other files during config file save (albertony)
  - Do not overwrite config file symbolic link (albertony)
  - Stop config create making invalid config files (Nick Craig-Wood)
- doc updates (Adam K, Aditya Basu, albertony, asdffdsazqqq, Damo, danielkrajnik, Dimitri Papadopoulos, dlitster, Drew Parsons, jumbi77, kapitainsky, mac-15, Mariusz Suchodolski, Nick Craig-Wood, NickIAm, Rintze Zelle, Stanislav Gromov, Tareq Sharafy, URenko, yuudi, Zach Kipp) — the credits list is literally a whole squad 🫶
- fs
  - Add size to JSON logs when moving or copying an object (Nick Craig-Wood)
  - Allow boolean features to be enabled with `--disable !Feature` (Nick Craig-Wood)
- genautocomplete: Rename to completion with alias to the old name (Nick Craig-Wood)
- librclone: Added example on using librclone with Go (alankrit)
- lsjson: Make `--stat` more efficient (Nick Craig-Wood)
- operations
  - Implement `--multi-thread-write-buffer-size` for speed improvements on downloads (Paulo Schreiner)
  - Reopen downloads on error when using `check --download` and `cat` (Nick Craig-Wood)
- rc: `config/listremotes` includes remotes defined with environment variables (kapitainsky)
- selfupdate: Obey `--no-check-certificate` flag (Nick Craig-Wood)
- serve restic: Trigger systemd notify (Shyim)
- serve webdav: Implement owncloud checksum and modtime extensions (WeidiDeng)
- sync: `--suffix-keep-extension` preserve 2 part extensions like `.tar.gz` (Nick Craig-Wood)

**Bug Fixes** 🐛💀

- accounting
  - Fix Prometheus metrics to be the same as `core/stats` (Nick Craig-Wood)
  - Bwlimit signal handler should always start (Sam Lai)
- bisync: Fix `maxDelete` parameter being ignored via the rc (Nick Craig-Wood)
- cmd/ncdu: Fix screen corruption when logging (eNV25)

- **`filter`** — Fix deadlock when errors pop up on `--files-from` (douchen) 🔒

- **`fs`**
  - Fix the interaction between `--progress` and `--interactive` (Nick Craig-Wood)
  - Fix an infinite recursive call in `pacer` `ModifyCalculator` (fixes an issue reported by the staticcheck linter) (albertony)

- **`lib/atexit`** — make sure `OnError` only calls the cancel function **once** (Nick Craig-Wood)

- **`lib/rest`** — fix problems re-using HTTP connections (Nick Craig-Wood)

- **`rc`**
  - Fix `operations/stat` with a trailing `/` (Nick Craig-Wood)
  - Fix missing `--rc` flags (Nick Craig-Wood)
  - Fix the output of Time values in `options/get` (Nick Craig-Wood)

- **`serve dlna`** — fix a potential data race (Nick Craig-Wood)

- **`version`** — fix the reported os/kernel version for windows (albertony)

- **Mount** 💅
  - Add `--mount-case-insensitive` to force the mount to be case insensitive (Nick Craig-Wood)
  - Removed unnecessary byte slice allocation for reads (Anagh Kumar Baranwal)
  - Clarify the `rclone mount` error you get when it's installed via homebrew (Nick Craig-Wood)
  - Added `_netdev` to the example mount so it gets treated as a remote-fs rather than local-fs (Anagh Kumar Baranwal)

- **Mount2**
  - Updated go-fuse version (Anagh Kumar Baranwal)
  - Fixed `statfs` (Anagh Kumar Baranwal)
  - Disable xattrs (Anagh Kumar Baranwal)

- **VFS**
  - Add `MkdirAll` function to make a directory and all beneath (Nick Craig-Wood)
  - Fix reload: `failed to add virtual dir entry: file does not exist` (Nick Craig-Wood)
  - Fix writing to a read only directory creating spurious directory entries (WeidiDeng)
  - Fix potential data race (Nick Craig-Wood)
  - Fix backends being Shutdown too early when startup takes a long time (Nick Craig-Wood)

- **Local**
  - Fix filtering of symlinks with the `-l`/`--links` flag (Nick Craig-Wood)
  - Fix `/path/to/file.rclonelink` when `-l`/`--links` is in use (Nick Craig-Wood)
  - Fix crash with `--metadata` on Android (Nick Craig-Wood)

- **Cache**
  - Fix backends shutting down when in use when used via the rc (Nick Craig-Wood)

- **Crypt**
  - Add `--crypt-suffix` option to set a custom suffix for encrypted files (jladbrook)
  - Add `--crypt-pass-bad-blocks` to allow corrupted file output (Nick Craig-Wood)
  - Fix reading 0 length files (Nick Craig-Wood)
  - Try not to return `unexpected EOF` error (Nick Craig-Wood)
  - Reduce allocations (albertony)
  - Recommend Dropbox for base32768 encoding (Nick Craig-Wood)

- **Azure Blob**
  - Empty directory markers (Nick Craig-Wood)
  - Support azure workload identities (Tareq Sharafy)
  - Fix azure blob uploads with multiple bits of metadata (Nick Craig-Wood)
  - Fix azurite compatibility by sending nil tier if set to empty string (Roel Arents)

- **Combine**
  - Implement missing methods (Nick Craig-Wood)
  - Fix goroutine stack overflow on bad object (Nick Craig-Wood)

- **Drive**
  - Add `--drive-env-auth` to get IAM credentials from runtime (Peter Brunner)
  - Update drive service account guide (Juang, Yi-Lin)
  - Fix change notify picking up files outside the root (Nick Craig-Wood)
  - Fix trailing slash mis-identificaton of folder as file (Nick Craig-Wood)
  - Fix incorrect remote after Update on object (Nick Craig-Wood)

- **Dropbox**
  - Implement `--dropbox-pacer-min-sleep` flag (Nick Craig-Wood)
  - Fix the dropbox batcher stalling (Misty)

- **Fichier**
  - Add `--ficicher-cdn` option to use the CDN for download (Nick Craig-Wood)

- **FTP**
  - Lower log message priority when `SetModTime` is not supported to debug (Tobias Gion)
  - Fix `unsupported LIST line` errors on startup (Nick Craig-Wood)
  - Fix `501 Not a valid pathname.` errors when creating directories (Nick Craig-Wood)

- **Google Cloud Storage**
  - Empty directory markers (Jānis Bebrītis, Nick Craig-Wood)
  - Added `--gcs-user-project` needed for requester pays (Christopher Merry)

- **HTTP**
  - Add client certificate user auth middleware. This can auth serve restic from the username in the client cert. (Peter Fern)

- **Jottacloud**
  - Fix vfs writeback stuck in a failed upload loop with file versioning disabled (albertony)

- **Onedrive**
  - Add `--onedrive-av-override` flag to download files flagged as virus (Nick Craig-Wood)
  - Fix quickxorhash on 32 bit architectures (Nick Craig-Wood)
  - Report any list errors during `rclone cleanup` (albertony)

- **Putio**
  - Fix uploading to the wrong object on Update with overridden remote name (Nick Craig-Wood)
  - Fix modification times not being preserved for server side copy and move (Nick Craig-Wood)
  - Fix server side copy failures (400 errors) (Nick Craig-Wood)

- **S3**
  - Empty directory markers (Jānis Bebrītis, Nick Craig-Wood)
  - Update Scaleway storage classes (Brian Starkey)
  - Fix `--s3-versions` on individual objects (Nick Craig-Wood)
  - Fix hang on aborting multipart upload with iDrive e2 (Nick Craig-Wood)
  - Fix missing `tier` metadata (Nick Craig-Wood)
  - Fix V3sign: add missing subresource delete (cc)
  - Fix Arvancloud Domain and region changes and alphabetise the provider (Ehsan Tadayon)
  - Fix Qiniu KODO quirks virtualHostStyle is false (zzq)

- **SFTP**
  - Add `--sftp-host-key-algorithms` to allow specifying SSH host key algorithms (Joel)
  - Fix using `--sftp-key-use-agent` and `--sftp-key-file` together needing private key file (Arnav Singh)
  - Fix move to allow overwriting existing files (Nick Craig-Wood)
  - Don't stat directories before listing them (Nick Craig-Wood)
  - Don't check remote points to a file if it ends with `/` (Nick Craig-Wood)

- **Sharefile**
  - Disable streamed transfers as they no longer work (Nick Craig-Wood)

- **Smb**
  - Code cleanup to avoid overwriting ctx before first use (fixes an issue reported by the staticcheck linter) (albertony)

- **Storj**
  - Fix `uplink: too many requests` errors when uploading to the same file (Nick Craig-Wood)
  - Fix uploading to the wrong object on Update with overridden remote name (Nick Craig-Wood)

- **Swift**
  - Ignore 404 error when deleting an object (Nick Craig-Wood)

- **Union**
  - Implement missing methods (Nick Craig-Wood)
  - Allow errors to be unwrapped for inspection (Nick Craig-Wood)

- **Uptobox**
  - Add `--uptobox-private` flag to make all uploaded files private (Nick Craig-Wood)
  - Fix improper regex (Aaron Gokaslan)
  - Fix Update returning the wrong object (Nick Craig-Wood)
  - Fix rmdir declaring that directories weren't empty (Nick Craig-Wood)

- **WebDAV**
  - nextcloud: Add support for chunked uploads (Paul)
  - Set modtime using propset for owncloud and nextcloud (WeidiDeng)
  - Make pacer minSleep configurable with `--webdav-pacer-min-sleep` (ed)
  - Fix server side copy/move not overwriting (WeidiDeng)
  - Fix modtime on server side copy for owncloud and nextcloud (Nick Craig-Wood)

- **Yandex**
  - Fix 400 Bad Request on transfer failure (Nick Craig-Wood)

- **Zoho**
  - Fix downloads with `Range:` header returning the wrong data (Nick Craig-Wood)

---

### v1.62.2 - 2023-03-16

See commits

- **Bug Fixes**
  - **docker volume plugin** — add the missing fuse3 dependency (Nick Craig-Wood) 🐳
  - **docs** — fix size documentation (asdffdsazqqq)
  - **FTP** — fix 426 errors on downloads with vsftpd (Lesmiscore)

### v1.62.1 - 2023-03-15

See commits

- **Bug Fixes**
  - **docker** — add missing fuse3 dependency (cycneuramus)
  - **build** — update release docs to be more careful with the tag (Nick Craig-Wood)
  - **build** — set the Github release to draft while uploading binaries (Nick Craig-Wood)

### v1.62.0 - 2023-03-14

See commits

- **New Features** ✨
  - **accounting** — make checkers show what they are doing (Nick Craig-Wood)
  - **authorize** — add support for custom templates (Hunter Wittenborn)
  - **build**
    - Update to go1.20 (Nick Craig-Wood, Anagh Kumar Baranwal)
    - Add winget releaser workflow (Ryan Caezar Itang)
    - Add dependabot (Ryan Caezar Itang)
  - **doc updates** — (albertony, Bryan Kaplan, Gerard Bosch, IMTheNachoMan, Justin Winokur, Manoj Ghosh, Nick Craig-Wood, Ole Frost, Peter Brunner, piyushgarg, Ryan Caezar Itang, Simmon Li, ToBeFree)
  - **filter** — emit an INFO message when it can't work out directory filters (Nick Craig-Wood)
  - **fs**
    - Added multiple ca certificate support. (alankrit)
    - Add `--max-delete-size` a delete size threshold (Leandro Sacchet)
  - **fspath** — allow the symbols `@` and `+` in remote names (albertony)
  - **lib/terminal** — enable windows console virtual terminal sequences processing (ANSI/VT100 colors) (albertony)
  - **move** — if `--check-first` and `--order-by` are set then delete with perfect ordering (Nick Craig-Wood)
  - **serve http** — support `--auth-proxy` (Matthias Baur)
- **Bug Fixes**
  - **accounting**
    - Avoid negative ETA values for very slow speeds (albertony)
    - Limit the length of the ETA string (albertony)
    - Show human readable elapsed time when longer than a day (albertony)
  - **all** — apply codeql fixes (Aaron Gokaslan)
  - **build**
    - Fix condition for manual workflow run (albertony)
    - Fix building for ARMv5 and ARMv6 (albertony)
      - `selfupdate`: Consider ARM version
      - `install.sh`: fix ARMv6 download
      - `version`: Report ARM version
  - **deletefile** — return error code 4 if file does not exist (Nick Craig-Wood)
  - **docker** — fix volume plugin does not remount volume on docker restart (logopk)
  - **fs** — fix race conditions in `--max-delete` and `--max-delete-size` (Nick Craig-Wood)
  - **lib/oauthutil** — handle fatal errors better (Alex Chen)
  - **mount2** — fix `--allow-non-empty` (Nick Craig-Wood)
  - **operations** — fix concurrency: use `--checkers` unless transferring files (Nick Craig-Wood)
  - **serve ftp** — fix timestamps older than 1 year in listings (Nick Craig-Wood)
  - **sync** — fix concurrency: use `--checkers` unless transferring files (Nick Craig-Wood)
  - **tree**
    - Fix nil pointer exception on stat failure (Nick Craig-Wood)
    - Fix colored output on windows (albertony)
    - Fix display of files with illegal Windows file system names (Nick Craig-Wood)
- **Mount**

- Fix creating and renaming files on case insensitive backends (Nick Craig-Wood) 💅

- Do not treat `\\?\` prefixed paths as network share paths on windows (albertony)

- Fix check for empty mount point on Linux (Nick Craig-Wood)

- Fix `--allow-non-empty` (Nick Craig-Wood) — the way that flag was just *not* behaving, bestie 😭

- Avoid incorrect or premature overlap check on windows (albertony)

- Update to fuse3 after bazil.org/fuse update (Nick Craig-Wood)

### 🦋 VFS

- Make uploaded files retain modtime with non-modtime backends (Nick Craig-Wood)

- Fix incorrect modtime on fs which don't support setting modtime (Nick Craig-Wood)

- Fix rename of directory containing files to be uploaded (Nick Craig-Wood)

### 🌸 Local

- Fix `%!w(<nil>)` in "failed to read directory" error (Marks Polakovs)

- Fix exclusion of dangling symlinks with `-L`/`--copy-links` (Nick Craig-Wood)

### 🎀 Crypt

- Obey `--ignore-checksum` (Nick Craig-Wood)

- Fix for unencrypted directory names on case insensitive remotes (Ole Frost)

### ✨ Azure Blob

- Remove workarounds for SDK bugs after v0.6.1 update (Nick Craig-Wood)

### 💜 B2

- Fix uploading files bigger than 1TiB (Nick Craig-Wood)

### 🔥 Drive

- Note that `--drive-acknowledge-abuse` needs SA Manager permission (Nick Craig-Wood)

- Make `--drive-stop-on-upload-limit` to respond to storageQuotaExceeded (Ninh Pham)

### 🌈 FTP

- Retry 426 errors (Nick Craig-Wood)

- Retry errors when initiating downloads (Nick Craig-Wood)

- Revert to upstream github.com/jlaffaye/ftp now fix is merged (Nick Craig-Wood)

### ⭐ Google Cloud Storage

- Add `--gcs-env-auth` to pick up IAM credentials from env/instance (Peter Brunner)

### 👑 Mega

- Add `--mega-use-https` flag (NodudeWasTaken)

### 💖 Onedrive

- Default onedrive personal to QuickXorHash as Microsoft is removing SHA1 (Nick Craig-Wood)

- Add `--onedrive-hash-type` to change the hash in use (Nick Craig-Wood)

- Improve speed of QuickXorHash (LXY)

### 🫶 Oracle Object Storage

- Speed up operations by using S3 pacer and setting minsleep to 10ms (Manoj Ghosh)

- Expose the storage_tier option in config (Manoj Ghosh)

- Bring your own encryption keys (Manoj Ghosh)

### 🌊 S3

- Check multipart upload ETag when `--s3-no-head` is in use (Nick Craig-Wood)

- Add `--s3-sts-endpoint` to specify STS endpoint (Nick Craig-Wood)

- Fix incorrect tier support for StorJ and IDrive when pointing at a file (Ole Frost)

- Fix AWS STS failing if `--s3-endpoint` is set (Nick Craig-Wood)

- Make purge remove directory markers too (Nick Craig-Wood)

### 🐚 Seafile

- Renew library password (Fred)

### 🦋 SFTP

- Fix uploads being 65% slower than they should be with crypt (Nick Craig-Wood)

### 🍓 Smb

- Allow SPN (service principal name) to be configured (Nick Craig-Wood)

- Check smb connection is closed (happyxhw)

### 🌌 Storj

- Implement rclone link (Kaloyan Raev)

- Implement rclone purge (Kaloyan Raev)

- Update satellite urls and labels (Kaloyan Raev)

### 🧚 WebDAV

- Fix interop with davrods server (Nick Craig-Wood)

---

## 🌈 v1.61.1 - 2022-12-23

See commits

### 💅 Bug Fixes

- docs:

  - Show only significant parts of version number in version introduced label (albertony)

  - Fix unescaped HTML (Nick Craig-Wood)

- lib/http: Shutdown all servers on exit to remove unix socket (Nick Craig-Wood)

- rc: Fix `--rc-addr` flag (which is an alternate for `--url`) (Anagh Kumar Baranwal)

- serve restic

  - Don't serve via http if serving via `--stdio` (Nick Craig-Wood)

  - Fix immediate exit when not using stdio (Nick Craig-Wood)

- serve webdav

  - Fix `--baseurl` handling after lib/http refactor (Nick Craig-Wood)

  - Fix running duplicate Serve call (Nick Craig-Wood)

### ✨ Azure Blob

- Fix "409 Public access is not permitted on this storage account" (Nick Craig-Wood)

### 🌊 S3

- storj: Update endpoints (Kaloyan Raev)

---

## 💜 v1.61.0 - 2022-12-20

See commits

### 🌟 New backends

- New S3 providers

  - Liara LOS (MohammadReza)

### 🎀 New Features

- build: Add vulnerability testing using govulncheck (albertony)

- cmd: Enable SIGINFO (<kbd>Ctrl</kbd>+<kbd>T</kbd>) handler on FreeBSD, NetBSD, OpenBSD and Dragonfly BSD (x3-apptech)

- config: Add config/setpath for setting config path via rc/librclone (Nick Craig-Wood)

- dedupe

  - Count Checks in the stats while scanning for duplicates (Nick Craig-Wood)

  - Make dedupe obey the filters (Nick Craig-Wood)

- dlna: Properly attribute code used from https://github.com/anacrolix/dms (Nick Craig-Wood)

- docs

  - Add minimum versions and status badges to backend and command docs (Nick Craig-Wood, albertony)

  - Remote names may not start or end with space (albertony)

- filter: Add metadata filters `--metadata-include/exclude/filter` and friends (Nick Craig-Wood)

- fs

  - Make all duration flags take y, M, w, d etc suffixes (Nick Craig-Wood)

  - Add global flag `--color` to control terminal colors (Kevin Verstaen)

- fspath: Allow unicode numbers and letters in remote names (albertony)

- lib/file: Improve error message for creating dir on non-existent network host on windows (albertony)

- lib/http: Finish port of rclone servers to lib/http (Tom Mombourquette, Nick Craig-Wood)

- lib/oauthutil: Improved usability of config flows needing web browser (Ole Frost)

- ncdu

  - Add support for modification time (albertony)

  - Fallback to sort by name also for sort by average size (albertony)

  - Rework to use tcell directly instead of the termbox wrapper (eNV25)

- rc: Add commands to set GC Percent & Memory Limit (go 1.19+) (Anagh Kumar Baranwal)

- rcat: Preserve metadata when Copy falls back to Rcat (Nick Craig-Wood)

- rcd: Refactor rclone rc server to use lib/http (Nick Craig-Wood)

- rcserver: Avoid generating default credentials with htpasswd (Kamui)

- restic: Refactor to use lib/http (Nolan Woods)

- serve http: Support unix sockets and multiple listeners (Tom Mombourquette)

- serve webdav: Refactor to use lib/http (Nick Craig-Wood)

- test: Replace defer cleanup with t.Cleanup (Eng Zer Jun)

- test memory: Read metadata if `-M` flag is specified (Nick Craig-Wood)

- wasm: Comply with wasm_exec.js licence terms (Matthew Vernon)

### 🔥 Bug Fixes

- build: Update golang.org/x/net/http2 to fix GO-2022-1144 (Nick Craig-Wood)

- restic: Fix typo in docs \`remove' should be \`remote' (asdffdsazqqq)

- serve dlna: Fix panic: Logger uninitialized.  (Nick Craig-Wood)

### 🦋 Mount

- Update cgofuse for FUSE-T support for mounting volumes on Mac (Nick Craig-Wood)

### 🌸 VFS

- Windows: fix slow opening of exe files by not truncating files when not necessary (Nick Craig-Wood)

- Fix IO Error opening a file with O_CREATE|O_RDONLY in `--vfs-cache-mode` not full (Nick Craig-Wood)

### 🎀 Crypt

- Fix compress wrapping crypt giving upload errors (Nick Craig-Wood)

### ✨ Azure Blob

- Port to new SDK (Nick Craig-Wood)

  - Revamp authentication to include all methods and docs (Nick Craig-Wood)

  - Port old authentication methods to new SDK (Nick Craig-Wood, Brad Ackerman)

  - Thanks to Stonebranch for sponsoring this work.

- Add `--azureblob-no-check-container` to assume container exists (Nick Craig-Wood)

- Add `--use-server-modtime` support (Abdullah Saglam)

- Add support for custom upload headers (rkettelerij)

- Allow emulator account/key override (Roel Arents)

- Support simple "environment credentials" (Nathaniel Wesley Filardo)

- Ignore AuthorizationFailure when trying to create a create a container (Nick Craig-Wood)

### 🧚 Box

- Added note on Box API rate limits (Ole Frost)

### 💜 Drive

- Handle shared drives with leading/trailing space in name (related to) (albertony)

### 🌈 FTP

- Update help text of implicit/explicit TLS options to refer to FTPS instead of FTP (ycdtosa)

- Improve performance to speed up `--files-from` and NewObject (Anthony Pessy)

### 🫶 HTTP

- Parse GET responses when no_head is set (Arnie97)

- Do not update object size based on Range requests (Arnie97)

- Support Content-Range response header (Arnie97)

### 👑 Onedrive

- Document workaround for shared with me files (vanplus)

### 🌊 S3

- Add Liara LOS to provider list (MohammadReza)

- Add DigitalOcean Spaces regions sfo3, fra1, syd1 (Jack)

- Avoid privileged GetBucketLocation to resolve s3 region (Anthony Pessy)

- Stop setting object and bucket ACL to private if it is an empty string (Philip Harvey)

- If bucket or object ACL is empty string then don't add X-Amz-Acl: header (Nick Craig-Wood)

- Reduce memory consumption for s3 objects (Erik Agterdenbos)

- Fix listing loop when using v2 listing on v1 server (Nick Craig-Wood)

- Fix nil pointer exception when using Versions (Nick Craig-Wood)

- Fix excess memory usage when using versions (Nick Craig-Wood)

- Ignore versionIDs from uploads unless using `--s3-versions` or `--s3-versions-at` (Nick Craig-Wood)

### 🦋 SFTP

- Add configuration options to set ssh Ciphers / MACs / KeyExchange (dgouju)

- Auto-detect shell type for fish (albertony)

- Fix NewObject with leading / (Nick Craig-Wood)

### 🍓 Smb

- Fix issue where spurious dot directory is created (albertony)

### 🌌 Storj

- Implement server side Copy (Kaloyan Raev)

---

## ⭐ v1.60.1 - 2022-11-17

See commits

### 💅 Bug Fixes

- lib/cache: Fix alias backend shutting down too soon (Nick Craig-Wood)

- wasm: Fix walltime link error by adding up-to-date wasm_exec.js (João Henrique Franco)

- docs

  - Update faq.md with bisync (Samuel Johnson)

  - Corrected download links in windows install docs (coultonluke)

  - Add direct download link for windows arm64 (albertony)

  - Remove link to rclone slack as it is no longer supported (Nick Craig-Wood)

  - Faq: how to use a proxy server that requires a username and password (asdffdsazqqq)

- Oracle-object-storage: doc fix (Manoj Ghosh)

  - Fix typo remove in `rclone_serve_restic` command (Joda Stößer)

  - Fix character that was incorrectly interpreted as markdown (Clément Notin)

- VFS

  - Fix deadlock caused by cache cleaner and upload finishing (Nick Craig-Wood)

- Local

  - Clean absolute paths (albertony)

  - Fix `-L`/`--copy-links` with filters missing directories (Nick Craig-Wood)

- Mailru

  - Note that an app password is now needed (Nick Craig-Wood)

  - Allow timestamps to be before the epoch 1970-01-01 (Nick Craig-Wood)

- S3

  - Add provider quirk `--s3-might-gzip` to fix corrupted on transfer: sizes differ (Nick Craig-Wood)

  - Allow Storj to server side copy since it seems to work now (Nick Craig-Wood)

  - Fix for unchecked err value in s3 listv2 (Aaron Gokaslan)

  - Add additional Wasabi locations (techknowlogick)

- Smb

  - Fix Failed to sync: context canceled at the end of syncs (Nick Craig-Wood)

- WebDAV

  - Fix Move/Copy/DirMove when using `-server-side-across-configs` (Nick Craig-Wood)

---

## 🌈 v1.60.0 - 2022-10-21

<pink>See commits</pink> ✨

- **New backends** 👑

  - Oracle object storage (Manoj Ghosh)

  - SMB / CIFS (Windows file sharing) (Lesmiscore)

  - New S3 providers

    - IONOS Cloud Storage (Dmitry Deniskin)

    - Qiniu KODO (Bachue Zhou)

- **New Features** 💖

  - build

    - Update to go1.19 and make go1.17 the minimum required version (Nick Craig-Wood)

    - Install.sh: fix arm-v7 download (Ole Frost)

  - fs: Warn the user when using an existing remote name without a colon (Nick Craig-Wood)

  - httplib: Add `--xxx-min-tls-version` option to select minimum TLS version for HTTP servers (Robert Newson)

  - librclone: Add PHP bindings and test program (Jordi Gonzalez Muñoz)

  - operations

    - Add `--server-side-across-configs` global flag for any backend (Nick Craig-Wood)

    - Optimise `--copy-dest` and `--compare-dest` (Nick Craig-Wood)

  - rc: add `job/stopgroup` to stop group (Evan Spensley)

  - serve dlna

    - Add `--announce-interval` to control SSDP Announce Interval (YanceyChiew)

    - Add `--interface` to Specify SSDP interface names line (Simon Bos)

    - Add support for more external subtitles (YanceyChiew)

    - Add verification of addresses (YanceyChiew)

  - sync: Optimise `--copy-dest` and `--compare-dest` (Nick Craig-Wood)

  - doc updates (albertony, Alexander Knorr, anonion, João Henrique Franco, Josh Soref, Lorenzo Milesi, Marco Molteni, Mark Trolley, Ole Frost, partev, Ryan Morey, Tom Mombourquette, YFdyh000)

- **Bug Fixes** 🐛

  - filter

    - Fix incorrect filtering with UseFilter context flag and wrapping backends (Nick Craig-Wood)

    - Make sure we check `--files-from` when looking for a single file (Nick Craig-Wood)

  - rc

    - Fix `mount/listmounts` not returning the full Fs entered in `mount/mount` (Tom Mombourquette)

    - Handle external unmount when mounting (Isaac Aymerich)

    - Validate Daemon option is not set when mounting a volume via RC (Isaac Aymerich)

  - sync: Update docs and error messages to reflect fixes to overlap checks (Nick Naumann)

- **VFS**

  - Reduce memory use by embedding `sync.Cond` (Nick Craig-Wood)

  - Reduce memory usage by re-ordering commonly used structures (Nick Craig-Wood)

  - Fix excess CPU used by VFS cache cleaner looping (Nick Craig-Wood)

- **Local**

  - Obey file filters in listing to fix errors on excluded files (Nick Craig-Wood)

  - Fix “Failed to read metadata: function not implemented” on old Linux kernels (Nick Craig-Wood)

- **Compress**

  - Fix crash due to nil metadata (Nick Craig-Wood)

  - Fix error handling to not use or return nil objects (Nick Craig-Wood)

- **Drive**

  - Make `--drive-stop-on-upload-limit` obey quota exceeded error (Steve Kowalik)

- **FTP**

  - Add `--ftp-force-list-hidden` option to show hidden items (Øyvind Heddeland Instefjord)

  - Fix hang when using ExplicitTLS to certain servers. (Nick Craig-Wood)

- **Google Cloud Storage**

  - Add `--gcs-endpoint` flag and config parameter (Nick Craig-Wood)

- **Hubic**

  - Remove backend as service has now shut down (Nick Craig-Wood)

- **Onedrive**

  - Rename Onedrive(cn) 21Vianet to Vnet Group (Yen Hu)

  - Disable change notify in China region since it is not supported (Nick Craig-Wood)

- **S3**

  - Implement `--s3-versions` flag to show old versions of objects if enabled (Nick Craig-Wood)

  - Implement `--s3-version-at` flag to show versions of objects at a particular time (Nick Craig-Wood)

  - Implement backend versioning command to get/set bucket versioning (Nick Craig-Wood)

  - Implement Purge to purge versions and backend `cleanup-hidden` (Nick Craig-Wood)

  - Add `--s3-decompress` flag to decompress gzip-encoded files (Nick Craig-Wood)

  - Add `--s3-sse-customer-key-base64` to supply keys with binary data (Richard Bateman)

  - Try to keep the maximum precision in ModTime with `--user-server-modtime` (Nick Craig-Wood)

  - Drop binary metadata with an ERROR message as it can’t be stored (Nick Craig-Wood)

  - Add `--s3-no-system-metadata` to suppress read and write of system metadata (Nick Craig-Wood)

- **SFTP**

  - Fix directory creation races (Lesmiscore)

- **Swift**

  - Add `--swift-no-large-objects` to reduce HEAD requests (Nick Craig-Wood)

- **Union**

  - Propagate SlowHash feature to fix hasher interaction (Lesmiscore)

---

## 🦋 v1.59.2 - 2022-09-15

<pink>See commits</pink> ✨

- **Bug Fixes** 💀

  - config: Move locking to fix fatal error: concurrent map read and map write (Nick Craig-Wood)

- **Local**

  - Disable xattr support if the filesystems indicates it is not supported (Nick Craig-Wood)

- **Azure Blob**

  - Fix chunksize calculations producing too many parts (Nick Craig-Wood)

- **B2**

  - Fix chunksize calculations producing too many parts (Nick Craig-Wood)

- **S3**

  - Fix chunksize calculations producing too many parts (Nick Craig-Wood)

---

## 🎀 v1.59.1 - 2022-08-08

<pink>See commits</pink> ✨

- **Bug Fixes** 🐛

  - accounting: Fix panic in `core/stats-reset` with unknown group (Nick Craig-Wood)

  - build: Fix android build after GitHub actions change (Nick Craig-Wood)

  - dlna: Fix SOAP action header parsing (Joram Schrijver)

  - docs: Fix links to mount command from install docs (albertony)

  - dropbox: Fix ChangeNotify was unable to decrypt errors (Nick Craig-Wood)

  - fs: Fix parsing of times and durations of the form “YYYY-MM-DD HH:MM:SS” (Nick Craig-Wood)

  - serve sftp: Fix checksum detection (Nick Craig-Wood)

  - sync: Add accidentally missed filter-sensitivity to `--backup-dir` option (Nick Naumann)

- **Combine**

  - Fix docs showing `remote=` instead of `upstreams=` (Nick Craig-Wood)

  - Throw error if duplicate directory name is specified (Nick Craig-Wood)

  - Fix errors with backends shutting down while in use (Nick Craig-Wood)

- **Dropbox**

  - Fix hang on quit with `--dropbox-batch-mode off` (Nick Craig-Wood)

  - Fix infinite loop on uploading a corrupted file (Nick Craig-Wood)

- **Internetarchive**

  - Ignore checksums for files using the different method (Lesmiscore)

  - Handle hash symbol in the middle of filename (Lesmiscore)

- **Jottacloud**

  - Fix working with whitelabel Elgiganten Cloud

  - Do not store username in config when using standard auth (albertony)

- **Mega**

  - Fix nil pointer exception when bad node received (Nick Craig-Wood)

- **S3**

  - Fix `--s3-no-head` panic: `reflect: Elem of invalid type s3.PutObjectInput` (Nick Craig-Wood)

- **SFTP**

  - Fix issue with WS_FTP by working around failing RealPath (albertony)

- **Union**

  - Fix duplicated files when using directories with leading `/` (Nick Craig-Wood)

  - Fix multiple files being uploaded when roots don’t exist (Nick Craig-Wood)

  - Fix panic due to misalignment of struct field in 32 bit architectures (r-ricci)

---

## 🌸 v1.59.0 - 2022-07-09

<pink>See commits</pink> ✨

- **New backends** 👑

  - Combine multiple remotes in one directory tree (Nick Craig-Wood)

  - Hidrive (Ovidiu Victor Tatar)

  - Internet Archive (Lesmiscore (Naoya Ozaki))

  - New S3 providers

    - ArvanCloud AOS (ehsantdy)

    - Cloudflare R2 (Nick Craig-Wood)

    - Huawei OBS (m00594701)

    - IDrive e2 (vyloy)

- **New commands** ⭐

  - test makefile: Create a single file for testing (Nick Craig-Wood)

- **New Features** 💖

  - Metadata framework to read and write system and user metadata on backends (Nick Craig-Wood)

    - Implemented initially for local, s3 and internetarchive backends

    - `--metadata`/`-M` flag to control whether metadata is copied

    - `--metadata-set` flag to specify metadata for uploads

    - Thanks to Manz Solutions for sponsoring this work.

  - build

    - Update to go1.18 and make go1.16 the minimum required version (Nick Craig-Wood)

    - Update android go build to 1.18.x and NDK to 23.1.7779620 (Nick Craig-Wood)

    - All windows binaries now no longer CGO (Nick Craig-Wood)

    - Add linux/arm/v6 to docker images (Nick Craig-Wood)

    - A huge number of fixes found with staticcheck (albertony)

    - Configurable version suffix independent of version number (albertony)

  - check: Implement `--no-traverse` and `--no-unicode-normalization` (Nick Craig-Wood)

  - config: Readability improvements (albertony)

  - copyurl: Add `--header-filename` to honor the HTTP header filename directive (J-P Treen)

  - filter: Allow multiple `--exclude-if-present` flags (albertony)

  - fshttp: Add `--disable-http-keep-alives` to disable HTTP Keep Alives (Nick Craig-Wood)

  - install.sh

    - Set the modes on the files and/or directories on macOS (Michael C Tiernan - MIT-Research Computing Project)

    - Pre verify sudo authorization `-v` before calling curl. (Michael C Tiernan - MIT-Research Computing Project)

  - lib/encoder: Add Semicolon encoding (Nick Craig-Wood)

  - lsf: Add metadata support with `M` flag (Nick Craig-Wood)

  - lsjson: Add `--metadata`/`-M` flag (Nick Craig-Wood)

  - ncdu

- Implement multi selection (<cyan>CrossR</cyan>) 💅
- Replace termbox with tcell's termbox wrapper (<cyan>eNV25</cyan>)
- Display correct path in delete confirmation dialog (<cyan>Roberto Ricci</cyan>) 🎀

- **`operations`**
  - <green>Speed up hash checking</green> by aborting the other hash if first returns nothing (<cyan>Nick Craig-Wood</cyan>)
  - Use correct src/dst in some log messages (<cyan>zzr93</cyan>)
- **`rcat`**: Check checksums by default like copy does (<cyan>Nick Craig-Wood</cyan>) ✨
- **`selfupdate`**: Replace deprecated x/crypto/openpgp package with ProtonMail/go-crypto (<cyan>albertony</cyan>)
- **`serve ftp`**: Check `--passive-port` arguments are correct (<cyan>Nick Craig-Wood</cyan>)
- **`size`**: Warn about inaccurate results when objects with unknown size (<cyan>albertony</cyan>)
- **`sync`**: Overlap check is now filter-sensitive so `--backup-dir` can be in the root provided it is filtered (<cyan>Nick</cyan>)
- **`test info`**: Check file name lengths using 1,2,3,4 byte unicode characters (<cyan>Nick Craig-Wood</cyan>)
- **`test makefile(s)`**: `--sparse`, `--zero`, `--pattern`, `--ascii`, `--chargen` flags to control file contents (<cyan>Nick Craig-Wood</cyan>) 🔥
- Make sure we call the Shutdown method on backends (<cyan>Martin Czygan</cyan>)

- **Bug Fixes** 😭
  - accounting: Fix unknown length file transfers counting 3 transfers each (<cyan>buda</cyan>)
  - ncdu: Fix issue where dir size is summed when file sizes are -1 (<cyan>albertony</cyan>)
  - sync/copy/move
    - Fix `--fast-list` `--create-empty-src-dirs` and `--exclude` (<cyan>Nick Craig-Wood</cyan>)
    - Fix `--max-duration` and `--cutoff-mode` soft (<cyan>Nick Craig-Wood</cyan>)
  - Fix fs cache unpin (<cyan>Martin Czygan</cyan>)
  - Set proper exit code for errors that are not low-level retried (e.g. size/timestamp changing) (<cyan>albertony</cyan>)

- **Mount** 🧚
  - Support windows/arm64 (may still be problems - see #5828) (<cyan>Nick Craig-Wood</cyan>)
  - Log IO errors at ERROR level (<cyan>Nick Craig-Wood</cyan>)
  - Ignore `_netdev` mount argument (<cyan>Hugal31</cyan>)
- **VFS**
  - Add `--vfs-fast-fingerprint` for less accurate but faster fingerprints (<cyan>Nick Craig-Wood</cyan>)
  - Add `--vfs-disk-space-total-size` option to manually set the total disk space (<cyan>Claudio Maradonna</cyan>)
  - vfscache: Fix fatal error: sync: unlock of unlocked mutex error (<cyan>Nick Craig-Wood</cyan>) 💀
- **Local**
  - Fix parsing of `--local-nounc` flag (<cyan>Nick Craig-Wood</cyan>)
  - Add Metadata support (<cyan>Nick Craig-Wood</cyan>)
- **Crypt**
  - Support metadata (<cyan>Nick Craig-Wood</cyan>)
- **Azure Blob**
  - Calculate Chunksize/blocksize to stay below maxUploadParts (<cyan>Leroy van Logchem</cyan>)
  - Use chunksize lib to determine chunksize dynamically (<cyan>Derek Battams</cyan>)
  - Case insensitive access tier (<cyan>Rob Pickerill</cyan>)
  - Allow remote emulator (azurite) (<cyan>Lorenzo Maiorfi</cyan>)
- **B2**
  - Add `--b2-version-at` flag to show file versions at time specified (<cyan>SwazRGB</cyan>)
  - Use chunksize lib to determine chunksize dynamically (<cyan>Derek Battams</cyan>)
- **Chunker**
  - Mark as not supporting metadata (<cyan>Nick Craig-Wood</cyan>)
- **Compress**
  - Support metadata (<cyan>Nick Craig-Wood</cyan>)
- **Drive** 🚗
  - Make backend config `-o config` add a combined `AllDrives:` remote (<cyan>Nick Craig-Wood</cyan>)
  - Make `--drive-shared-with-me` work with shared drives (<cyan>Nick Craig-Wood</cyan>)
  - Add `--drive-resource-key` for accessing link-shared files (<cyan>Nick Craig-Wood</cyan>)
  - Add backend commands `exportformats` and `importformats` for debugging (<cyan>Nick Craig-Wood</cyan>)
  - Fix 404 errors on copy/server side copy objects from public folder (<cyan>Nick Craig-Wood</cyan>)
  - Update Internal OAuth consent screen docs (<cyan>Phil Shackleton</cyan>)
  - Moved `root_folder_id` to advanced section (<cyan>Abhiraj</cyan>)
- **Dropbox**
  - Migrate from deprecated api (<cyan>m8rge</cyan>)
  - Add logs to show when poll interval limits are exceeded (<cyan>Nick Craig-Wood</cyan>)
  - Fix nil pointer exception on dropbox impersonate user not found (<cyan>Nick Craig-Wood</cyan>)
- **Fichier**
  - Parse api error codes and them accordingly (<cyan>buengese</cyan>)
- **FTP**
  - Add support for `disable_utf8` option (<cyan>Jason Zheng</cyan>)
  - Revert to upstream github.com/jlaffaye/ftp from our fork (<cyan>Nick Craig-Wood</cyan>)
- **Google Cloud Storage**
  - Add `--gcs-no-check-bucket` to minimise transactions and perms (<cyan>Nick Gooding</cyan>)
  - Add `--gcs-decompress` flag to decompress gzip-encoded files (<cyan>Nick Craig-Wood</cyan>)
    - by default these will be downloaded compressed (which previously failed)
- **Hasher**
  - Support metadata (<cyan>Nick Craig-Wood</cyan>)
- **HTTP**
  - Fix missing response when using custom auth handler (<cyan>albertony</cyan>)
- **Jottacloud**
  - Add support for upload to custom device and mountpoint (<cyan>albertony</cyan>)
  - Always store username in config and use it to avoid initial API request (<cyan>albertony</cyan>)
  - Fix issue with server-side copy when destination is in trash (<cyan>albertony</cyan>)
  - Fix listing output of remote with special characters (<cyan>albertony</cyan>)
- **Mailru**
  - Fix timeout by using int instead of time.Duration for keeping number of seconds (<cyan>albertony</cyan>)
- **Mega**
  - Document using MEGAcmd to help with login failures (<cyan>Art M. Gallagher</cyan>)
- **Onedrive**
  - Implement `--poll-interval` for onedrive (<cyan>Hugo Laloge</cyan>)
  - Add access scopes option (<cyan>Sven Gerber</cyan>)
- **Opendrive**
  - Resolve lag and truncate bugs (<cyan>Scott Grimes</cyan>)
- **Pcloud**
  - Fix about with no free space left (<cyan>buengese</cyan>)
  - Fix cleanup (<cyan>buengese</cyan>)
- **S3** 🪣
  - Use PUT Object instead of presigned URLs to upload single part objects (<cyan>Nick Craig-Wood</cyan>)
  - Backend restore command to skip non-GLACIER objects (<cyan>Vincent Murphy</cyan>)
  - Use chunksize lib to determine chunksize dynamically (<cyan>Derek Battams</cyan>)
  - Retry RequestTimeout errors (<cyan>Nick Craig-Wood</cyan>)
  - Implement reading and writing of metadata (<cyan>Nick Craig-Wood</cyan>)
- **SFTP**
  - Add support for about and hashsum on windows server (<cyan>albertony</cyan>)
  - Use vendor-specific VFS statistics extension for about if available (<cyan>albertony</cyan>)
  - Add `--sftp-chunk-size` to control packets sizes for high latency links (<cyan>Nick Craig-Wood</cyan>)
  - Add `--sftp-concurrency` to improve high latency transfers (<cyan>Nick Craig-Wood</cyan>)
  - Add `--sftp-set-env` option to set environment variables (<cyan>Nick Craig-Wood</cyan>)
  - Add Hetzner Storage Boxes to supported sftp backends (<cyan>Anthrazz</cyan>)
- **Storj**
  - Fix put which lead to the file being unreadable when using mount (<cyan>Erik van Velzen</cyan>)
- **Union**
  - Add `min_free_space` option for lfs/eplfs policies (<cyan>Nick Craig-Wood</cyan>)
  - Fix uploading files to union of all bucket based remotes (<cyan>Nick Craig-Wood</cyan>)
  - Fix get free space for remotes which don't support it (<cyan>Nick Craig-Wood</cyan>)
  - Fix eplus policy to select correct entry for existing files (<cyan>Nick Craig-Wood</cyan>)
  - Support metadata (<cyan>Nick Craig-Wood</cyan>)
- **Uptobox**
  - Fix root path handling (<cyan>buengese</cyan>)
- **WebDAV**
  - Add SharePoint in other specific regions support (<cyan>Noah Hsu</cyan>)
- **Yandex**
  - Handle api error on server-side move (<cyan>albertony</cyan>)
- **Zoho**
  - Add Japan and China regions (<cyan>buengese</cyan>)

---

### v1.58.1 - 2022-04-29 🌸

See commits

- **Bug Fixes**
  - build: Update github.com/billziss-gh to github.com/winfsp (<cyan>Nick Craig-Wood</cyan>)
  - filter: Fix timezone of `--min-age/-max-age` from UTC to local as documented (<cyan>Nick Craig-Wood</cyan>)
  - rc/js: Correct RC method names (<cyan>Sơn Trần-Nguyễn</cyan>)
  - docs
    - Fix some links to command pages (<cyan>albertony</cyan>)
    - Add `--multi-thread-streams` note to `--transfers`. (<cyan>Zsolt Ero</cyan>)

- **Mount**
  - Fix `--devname` and fusermount: unknown option `` `fsname' `` when mounting via rc (<cyan>Nick Craig-Wood</cyan>)
- **VFS**
  - Remove wording which suggests VFS is only for mounting (<cyan>Nick Craig-Wood</cyan>)
- **Dropbox**
  - Fix retries of multipart uploads with incorrect_offset error (<cyan>Nick Craig-Wood</cyan>)
- **Google Cloud Storage**
  - Use the s3 pacer to speed up transactions (<cyan>Nick Craig-Wood</cyan>)
  - pacer: Default the Google pacer to a burst of 100 to fix gcs pacing (<cyan>Nick Craig-Wood</cyan>)
- **Jottacloud**
  - Fix scope in token request (<cyan>albertony</cyan>)
- **Netstorage**
  - Fix unescaped HTML in documentation (<cyan>Nick Craig-Wood</cyan>)
  - Make levels of headings consistent (<cyan>Nick Craig-Wood</cyan>)
  - Add support contacts to netstorage doc (<cyan>Nil Alexandrov</cyan>)
- **Onedrive**
  - Note that sharepoint also changes web files (`.html`, `.aspx`) (<cyan>GH</cyan>)
- **Putio**
  - Handle rate limit errors (<cyan>Berkan Teber</cyan>)
  - Fix multithread download and other ranged requests (<cyan>rafma0</cyan>)
- **S3**
  - Add ChinaMobile EOS to provider list (<cyan>GuoXingbin</cyan>)
  - Sync providers in config description with providers (<cyan>Nick Craig-Wood</cyan>)
- **SFTP**
  - Fix OpenSSH 8.8+ RSA keys incompatibility (<cyan>KARBOWSKI Piotr</cyan>)
  - Note that Scaleway C14 is deprecating SFTP in favor of S3 (<cyan>Adrien Rey-Jarthon</cyan>)
- **Storj**
  - Fix bucket creation on Move (<cyan>Nick Craig-Wood</cyan>)
- **WebDAV**
  - Don't override Referer if user sets it (<cyan>Nick Craig-Wood</cyan>)

---

### v1.58.0 - 2022-03-18 👑

See commits

- **New backends** 🎉
  - Akamai Netstorage (<cyan>Nil Alexandrov</cyan>)
  - Seagate Lyve, SeaweedFS, Storj, RackCorp via s3 backend
  - Storj (renamed from Tardigrade - your old config files will continue working)
- **New commands**
  - bisync - experimental bidirectional cloud sync (<cyan>Ivan Andreev, Chris Nelson</cyan>)
- **New Features**
  - build
    - Add windows/arm64 build (rclone mount not supported yet) (<cyan>Nick Craig-Wood</cyan>)
    - Raise minimum go version to go1.15 (<cyan>Nick Craig-Wood</cyan>)
  - config: Allow dot in remote names and improve config editing (<cyan>albertony</cyan>)
  - dedupe: Add quit as a choice in interactive mode (<cyan>albertony</cyan>)
  - dlna: Change icons to the newest ones. (<cyan>Alain Nussbaumer</cyan>)
  - filter: Add `{{ regexp }}` syntax to pattern matches (<cyan>Nick Craig-Wood</cyan>)
  - fshttp: Add prometheus metrics for HTTP status code (<cyan>Michał Matczuk</cyan>)
  - hashsum: Support creating hash from data received on stdin (<cyan>albertony</cyan>)
  - librclone
    - Allow empty string or null input instead of empty json object (<cyan>albertony</cyan>)
    - Add support for mount commands (<cyan>albertony</cyan>)
  - operations: Add server-side moves to stats (<cyan>Ole Frost</cyan>)
  - rc: Allow user to disable authentication for web gui (<cyan>negative0</cyan>)
  - tree: Remove obsolete `--human` replaced by global `--human-readable` (<cyan>albertony</cyan>)
  - version: Report correct friendly-name for newer Windows 10/11 versions (<cyan>albertony</cyan>)
- **Bug Fixes**
  - build 🌸

<purple>okay bestie we are STILL in the changelog</purple> 💅 and it is <hotpink>long</hotpink>, but every single line matters, so let's goooo:

- Fix ARM architecture version in `.deb` packages after nfpm change (<cyan>Nick Craig-Wood</cyan>)
- Hard fork `github.com/jlaffaye/ftp` to fix `go get github.com/rclone/rclone` (<cyan>Nick Craig-Wood</cyan>)
- `oauthutil`: Fix crash when webbrowser requests `/robots.txt` (<cyan>Nick Craig-Wood</cyan>)
- `operations`: Fix goroutine leak in case of copy retry (<cyan>Ankur Gupta</cyan>)
- `rc`:
  - Fix `operations/publiclink` default for `expires` parameter (<cyan>Nick Craig-Wood</cyan>)
  - Fix missing computation of `transferQueueSize` when summing up statistics group (<cyan>Carlo Mion</cyan>)
  - Fix missing `StatsInfo` fields in the computation of the group sum (<cyan>Carlo Mion</cyan>)
- `sync`: Fix `--max-duration` so it doesn't retry when the duration is exceeded 🌸 (<cyan>Nick Craig-Wood</cyan>)
- `touch`: Fix issue where a directory is created instead of a file (<cyan>albertony</cyan>)

## 👑 Mount

- Add `--devname` to set the device name sent to FUSE for mount display (<cyan>Nick Craig-Wood</cyan>)

## 🦋 VFS

- Add `vfs/stats` remote control to show statistics (<cyan>Nick Craig-Wood</cyan>)
- Fix `failed to _ensure cache internal error: downloaders is nil` error (<cyan>Nick Craig-Wood</cyan>)
- Fix handling of special characters in file names (<cyan>Bumsu Hyeon</cyan>)

## 🍓 Local

- Fix hash invalidation which caused errors with local crypt mount (<cyan>Nick Craig-Wood</cyan>)

## 🔐 Crypt

- Add `base64` and `base32768` filename encoding options (<cyan>Max Sum</cyan>, <cyan>Sinan Tan</cyan>)

## 🌈 Azure Blob

- Implement `--azureblob-upload-concurrency` parameter to speed uploads (<cyan>Nick Craig-Wood</cyan>)
- Remove `100MB` upper limit on `chunk_size` as it is no longer needed (<cyan>Nick Craig-Wood</cyan>)
- Raise `--azureblob-upload-concurrency` to `16` by default (<cyan>Nick Craig-Wood</cyan>)
- Fix crash with SAS URL and no container (<cyan>Nick Craig-Wood</cyan>)

## 🎀 Compress

- Fix crash if metadata upload failed (<cyan>Nick Craig-Wood</cyan>)
- Fix memory leak (<cyan>Nick Craig-Wood</cyan>)

## 💜 Drive

- Added `--drive-copy-shortcut-content` (<cyan>Abhiraj</cyan>)
- Disable OAuth OOB flow (copy a token) due to Google deprecation (<cyan>Nick Craig-Wood</cyan>)
  - See the deprecation note.
- Add `--drive-skip-dangling-shortcuts` flag (<cyan>Nick Craig-Wood</cyan>)
- When using a link type `--drive-export-formats` shows all doc types (<cyan>Nick Craig-Wood</cyan>)

## 🧚 Dropbox

- Speed up directory listings by specifying `1000` items in a chunk (<cyan>Nick Craig-Wood</cyan>)
- Save an API request when at the root (<cyan>Nick Craig-Wood</cyan>)

## ✨ Fichier

- Implemented About functionality (<cyan>Gourav T</cyan>)

## 🌸 FTP

- Add `--ftp-ask-password` to prompt for password when needed (<cyan>Borna Butkovic</cyan>)

## ⭐ Google Cloud Storage

- Add missing regions (<cyan>Nick Craig-Wood</cyan>)
- Disable OAuth OOB flow (copy a token) due to Google deprecation (<cyan>Nick Craig-Wood</cyan>)
  - See the deprecation note.

## 💖 Googlephotos

- Disable OAuth OOB flow (copy a token) due to Google deprecation (<cyan>Nick Craig-Wood</cyan>)
  - See the deprecation note.

## 🫶 Hasher

- Fix crash on object not found (<cyan>Nick Craig-Wood</cyan>)

## 🔥 Hdfs

- Add file (Move) and directory move (`DirMove`) support (<cyan>Andy Jackson</cyan>)

## 🌈 HTTP

- Improved recognition of URL pointing to a single file (<cyan>albertony</cyan>)

## 💅 Jottacloud

- Change API used by recursive list (`ListR`) (<cyan>Kim</cyan>)
- Add support for Tele2 Cloud (<cyan>Fredric Arklid</cyan>)

## 🎀 Koofr

- Add Digistorage service as a Koofr provider.  (<cyan>jaKa</cyan>)

## 💜 Mailru

- Fix `int32` overflow on arm32 (<cyan>Ivan Andreev</cyan>)

## 🌸 Onedrive

- Add config option for oauth scope `Sites.Read.All` (<cyan>Charlie Jiang</cyan>)
- Minor optimization of `quickxorhash` (<cyan>Isaac Levy</cyan>)
- Add `--onedrive-root-folder-id` flag (<cyan>Nick Craig-Wood</cyan>)
- Do not retry on `400 pathIsTooLong` error (<cyan>ctrl-q</cyan>)

## 🦋 Pcloud

- Add support for recursive list (`ListR`) (<cyan>Niels van de Weem</cyan>)
- Fix pre-1970 time stamps (<cyan>Nick Craig-Wood</cyan>)

## 🔥 S3

- Use `ListObjectsV2` for faster listings (<cyan>Felix Bunemann</cyan>)
  - Fallback to `ListObject v1` on unsupported providers (<cyan>Nick Craig-Wood</cyan>)
- Use the `ETag` on multipart transfers to verify the transfer was OK (<cyan>Nick Craig-Wood</cyan>)
  - Add `--s3-use-multipart-etag` provider quirk to disable this on unsupported providers (<cyan>Nick Craig-Wood</cyan>)
- New Providers
  - RackCorp object storage (<cyan>bbabich</cyan>)
  - Seagate Lyve Cloud storage (<cyan>Nick Craig-Wood</cyan>)
  - SeaweedFS (<cyan>Chris Lu</cyan>)
  - Storj Shared gateways (<cyan>Márton Elek</cyan>, <cyan>Nick Craig-Wood</cyan>)
- Add Wasabi AP Northeast 2 endpoint info (<cyan>lindwurm</cyan>)
- Add `GLACIER_IR` storage class (<cyan>Yunhai Luo</cyan>)
- Document `Content-MD5` workaround for object-lock enabled buckets (<cyan>Paulo Martins</cyan>)
- Fix multipart upload with `--no-head` flag (<cyan>Nick Craig-Wood</cyan>)
- Simplify content length processing in s3 with download url (<cyan>Logeshwaran Murugesan</cyan>)

## 🧚 SFTP

- Add `rclone` to list of supported `md5sum`/`sha1sum` commands to look for (<cyan>albertony</cyan>)
- Refactor so we only have one way of running remote commands (<cyan>Nick Craig-Wood</cyan>)
- Fix timeout on hashing large files by sending keepalives (<cyan>Nick Craig-Wood</cyan>)
- Fix unnecessary seeking when uploading and downloading files (<cyan>Nick Craig-Wood</cyan>)
- Update docs on how to create `known_hosts` file (<cyan>Nick Craig-Wood</cyan>)

## ⭐ Storj

- Rename tardigrade backend to storj backend (<cyan>Nick Craig-Wood</cyan>)
- Implement server side Move for files (<cyan>Nick Craig-Wood</cyan>)
- Update docs to explain differences between s3 and this backend (<cyan>Elek, Márton</cyan>)

## 💖 Swift

- Fix About so it shows info about the current container only (<cyan>Nick Craig-Wood</cyan>)

## 🎀 Union

- Fix treatment of remotes with `//` in (<cyan>Nick Craig-Wood</cyan>)
- Fix deadlock when one part of a multi-upload fails (<cyan>Nick Craig-Wood</cyan>)
- Fix eplus policy returned nil (<cyan>Vitor Arruda</cyan>)

## 🌈 Yandex

- Add permanent deletion support (<cyan>deinferno</cyan>)

---

### 🌸 v1.57.0 - 2021-11-01

See commits

- New backends
  - Sia: for Sia decentralized cloud (<cyan>Ian Levesque</cyan>, <cyan>Matthew Sevey</cyan>, <cyan>Ivan Andreev</cyan>)
  - Hasher: caches hashes and enable hashes for backends that don't support them (<cyan>Ivan Andreev</cyan>)
- New commands
  - `lsjson` –stat: to get info about a single file/dir and `operations/stat` api (<cyan>Nick Craig-Wood</cyan>)
  - `config paths`: show configured paths (<cyan>albertony</cyan>)
- New Features
  - `about`: Make human-readable output more consistent with other commands (<cyan>albertony</cyan>)
  - `build`
    - Use `go1.17` for building and make `go1.14` the minimum supported (<cyan>Nick Craig-Wood</cyan>)
    - Update Go to `1.16` and NDK to `22b` for Android builds (<cyan>x0b</cyan>)
  - `config`
    - Support hyphen in remote name from environment variable (<cyan>albertony</cyan>)
    - Make temporary directory user-configurable (<cyan>albertony</cyan>)
    - Convert `--cache-dir` value to an absolute path (<cyan>albertony</cyan>)
    - Do not override MIME types from OS defaults (<cyan>albertony</cyan>)
  - `docs`
    - Toc styling and header levels cleanup (<cyan>albertony</cyan>)
    - Extend documentation on valid remote names (<cyan>albertony</cyan>)
    - Mention make for building and cmount tag for macos (<cyan>Alex Chen</cyan>)
    - ...and many more contributions to numerous to mention!
  - `fs`: Move with `--ignore-existing` will not delete skipped files (<cyan>Nathan Collins</cyan>)
  - `hashsum`
    - Treat hash values in sum file as case insensitive (<cyan>Ivan Andreev</cyan>)
    - Don't put `ERROR` or `UNSUPPORTED` in output (<cyan>Ivan Andreev</cyan>)
  - `lib/encoder`: Add encoding of square brackets (<cyan>Ivan Andreev</cyan>)
  - `lib/file`: Improve error message when attempting to create dir on nonexistent drive on windows (<cyan>albertony</cyan>)
  - `lib/http`: Factor password hash salt into options with default (<cyan>Nolan Woods</cyan>)
  - `lib/kv`: Add key-value database api (<cyan>Ivan Andreev</cyan>)
  - `librclone`
    - Add `RcloneFreeString` function (<cyan>albertony</cyan>)
    - Free strings in python example (<cyan>albertony</cyan>)
  - `log`: Optionally print pid in logs (<cyan>Ivan Andreev</cyan>)
  - `ls`: Introduce `--human-readable` global option to print human-readable sizes (<cyan>albertony</cyan>)
  - `ncdu`: Introduce key `u` to toggle human-readable (<cyan>albertony</cyan>)
  - `operations`: Add `rmdirs -v` output (<cyan>Justin Winokur</cyan>)
  - `serve sftp`
    - Generate an ECDSA server key as well as RSA (<cyan>Nick Craig-Wood</cyan>)
    - Generate an Ed25519 server key as well as ECDSA and RSA (<cyan>albertony</cyan>)
  - `serve docker`
    - Allow to customize proxy settings of docker plugin (<cyan>Ivan Andreev</cyan>)
    - Build docker plugin for multiple platforms (<cyan>Thomas Stachl</cyan>)
  - `size`: Include human-readable count (<cyan>albertony</cyan>)
  - `touch`: Add support for touching files in directory, with recursive option, filtering and `--dry-run`/`-i` (<cyan>albertony</cyan>)
  - `tree`: Option to print human-readable sizes removed in favor of global option (<cyan>albertony</cyan>)
- Bug Fixes
  - `lib/http`
    - Fix bad username check in single auth secret provider (<cyan>Nolan Woods</cyan>)
    - Fix handling of SSL credentials (<cyan>Nolan Woods</cyan>)
  - `serve ftp`: Ensure modtime is passed as UTC always to fix timezone oddities (<cyan>Nick Craig-Wood</cyan>)
  - `serve sftp`: Fix generation of server keys on windows (<cyan>albertony</cyan>)
  - `serve docker`: Fix octal umask (<cyan>Ivan Andreev</cyan>)
- Mount
  - Enable rclone to be run as mount helper direct from the fstab (<cyan>Ivan Andreev</cyan>)
  - Use procfs to validate mount on linux (<cyan>Ivan Andreev</cyan>)
  - Correctly daemonize for compatibility with automount (<cyan>Ivan Andreev</cyan>)
- VFS
  - Ensure names used in cache path are legal on current OS (<cyan>albertony</cyan>)
  - Ignore `ECLOSED` when truncating file handles to fix intermittent bad file descriptor error (<cyan>Nick Craig-Wood</cyan>)
- Local
  - Refactor default OS encoding out from local backend into shared encoder lib (<cyan>albertony</cyan>)
- Crypt
  - Return wrapped object even with `--crypt-no-data-encryption` (<cyan>Ivan Andreev</cyan>)
  - Fix uploads with `--crypt-no-data-encryption` (<cyan>Nick Craig-Wood</cyan>)
- Azure Blob
  - Add `--azureblob-no-head-object` (<cyan>Tatsuya Noyori</cyan>)
- Box
  - Make listings of heavily used directories more reliable (<cyan>Nick Craig-Wood</cyan>)
  - When doing cleanup delete as much as possible (<cyan>Nick Craig-Wood</cyan>)
  - Add `--box-list-chunk` to control listing chunk size (<cyan>Nick Craig-Wood</cyan>)
  - Delete items in parallel in cleanup using `--checkers` threads (<cyan>Nick Craig-Wood</cyan>)
  - Add `--box-owned-by` to only show items owned by the login passed (<cyan>Nick Craig-Wood</cyan>)
  - Retry `operation_blocked_temporary` errors (<cyan>Nick Craig-Wood</cyan>)
- Chunker
  - `Md5all` must create metadata if base hash is slow (<cyan>Ivan Andreev</cyan>)

<purple>and we're still not done bestie, the changelog keeps going</purple> 💀✨

- <pink>**Drive**</pink>

  - Speed up directory listings by constraining the API listing using the current filters (fotile96, Ivan Andreev)

  - Fix buffering for single request upload for files smaller than `--drive-upload-cutoff` (YenForYang)

  - Add `-o` config option to backend drives to make config for all shared drives (Nick Craig-Wood)

- <pink>**Dropbox**</pink>

  - Add `--dropbox-batch-commit-timeout` to control batch timeout (Nick Craig-Wood)

- <pink>**Filefabric**</pink>

  - Make backoff exponential for `error_background` to fix errors (Nick Craig-Wood)

  - Fix directory move after API change (Nick Craig-Wood)

- <pink>**FTP**</pink>

  - Enable tls session cache by default (Ivan Andreev)

  - Add option to disable tls13 (Ivan Andreev)

  - Fix timeout after long uploads (Ivan Andreev)

  - Add support for precise time (Ivan Andreev)

  - Enable CI for ProFtpd, PureFtpd, VsFtpd (Ivan Andreev)

- <pink>**Googlephotos**</pink>

  - Use encoder for album names to fix albums with control characters (Parth Shukla)

- <pink>**Jottacloud**</pink>

  - Implement `SetModTime` to support modtime-only changes (albertony)

  - Improved error handling with `SetModTime` and corrupt files in general (albertony)

  - Add support for `UserInfo` (`rclone config userinfo`) feature (albertony)

  - Return direct download link from `rclone link` command (albertony)

- <pink>**Koofr**</pink>

  - Create direct share link (Dmitry Bogatov)

- <pink>**Pcloud**</pink>

  - Add `sha256` support (Ken Enrique Morel)

- <pink>**Premiumizeme**</pink>

  - Fix directory listing after API changes (Nick Craig-Wood)

  - Fix server side move after API change (Nick Craig-Wood)

  - Fix server side directory move after API changes (Nick Craig-Wood)

- <pink>**S3**</pink>

  - Add support to use CDN URL to download the file (Logeshwaran)

  - Add AWS Snowball Edge to providers examples (r0kk3rz)

  - Use a combination of SDK retries and rclone retries (Nick Craig-Wood)

  - Fix IAM Role for Service Account not working and other auth problems (Nick Craig-Wood)

  - Fix `shared_credentials_file` auth after reverting incorrect fix (Nick Craig-Wood)

  - Fix <red>corrupted on transfer: sizes differ 0 vs xxxx</red> with Ceph (Nick Craig-Wood)

- <pink>**Seafile**</pink>

  - Fix error when not configured for 2fa (Fred)

- <pink>**SFTP**</pink>

  - Fix timeout when doing MD5SUM of large file (Nick Craig-Wood)

- <pink>**Swift**</pink>

  - Update OCI URL (David Liu)

  - Document OVH Cloud Archive (HNGamingUK)

- <pink>**Union**</pink>

  - Fix rename not working with union of local disk and bucket based remote (Nick Craig-Wood)

---

## 🌸 v1.56.2 - 2021-10-01 🌸

okay bestie, `See commits` if you wanna go full detective mode 🔍

- <purple>**Bug Fixes**</purple>

  - `serve http`: Re-add missing auth to http service (Nolan Woods)

  - `build`: Update `golang.org/x/sys` to fix crash on macOS when compiled with go1.17 (Herby Gillot)

- <pink>**FTP**</pink>

  - Fix deadlock after failed update when `concurrency=1` (Ivan Andreev)

---

## ✨ v1.56.1 - 2021-09-19 ✨

`See commits`, the receipts are right there 💅

- <purple>**Bug Fixes**</purple>

  - `accounting`: Fix maximum bwlimit by scaling scale max token bucket size (Nick Craig-Wood)

  - `rc`: Fix speed does not update in `core/stats` (negative0)

  - `selfupdate`: Fix `--quiet` option, not quite quiet (yedamo)

  - `serve http`: Fix `serve http` exiting directly after starting (Cnly)

  - `build`

    - Apply gofmt from golang 1.17 (Ivan Andreev)

    - Update Go to 1.16 and NDK to 22b for android/any (x0b)

- <pink>**Mount**</pink>

  - Fix `--daemon` mode (Ivan Andreev)

- <pink>**VFS**</pink>

  - Fix duplicates on rename (Nick Craig-Wood)

  - Fix crash when truncating a just uploaded object (Nick Craig-Wood)

  - Fix issue where empty dirs would build up in cache meta dir (albertony)

- <pink>**Drive**</pink>

  - Fix instructions for auto config (Greg Sadetsky)

  - Fix `lsf` example without drive-impersonate (Greg Sadetsky)

- <pink>**Onedrive**</pink>

  - Handle HTTP 400 better in `PublicLink` (Alex Chen)

  - Clarification of the process for creating custom `client_id` (Mariano Absatz)

- <pink>**Pcloud**</pink>

  - Return an early error when `Put` is called with an unknown size (Nick Craig-Wood)

  - Try harder to delete a failed upload (Nick Craig-Wood)

- <pink>**S3**</pink>

  - Add Wasabi’s AP-Northeast endpoint info (hota)

  - Fix typo in s3 documentation (Greg Sadetsky)

- <pink>**Seafile**</pink>

  - Fix 2fa config state machine (Fred)

- <pink>**SFTP**</pink>

  - Remove spurious error message on `--sftp-disable-concurrent-reads` (Nick Craig-Wood)

- <pink>**Sugarsync**</pink>

  - Fix initial connection after config re-arrangement (Nick Craig-Wood)

---

## 🦋 v1.56.0 - 2021-07-20 🦋

`See commits` my love, go read the lore 📜

- <purple>**New backends**</purple>

  - Uptobox (buengese)

- <purple>**New commands**</purple>

  - `serve docker` (Antoine GIRARD) (Ivan Andreev)

    - and accompanying docker volume plugin

  - `checksum` to check files against a file of checksums (Ivan Andreev)

    - this is also available as `rclone md5sum -C` etc

  - `config touch`: ensure config exists at configured location (albertony)

  - `test changenotify`: command to help debugging changenotify (Nick Craig-Wood)

- <purple>**Deprecations**</purple>

  - `dbhashsum`: Remove command deprecated a year ago (Ivan Andreev)

  - `cache`: Deprecate cache backend (Ivan Andreev)

- <purple>**New Features**</purple>

  - rework config system so it can be used non-interactively via cli and rc API.

    - See docs in `config create`

    - <red>This is a very big change to all the backends so may cause breakages - please file bugs!</red> 😭

  - `librclone` - export the rclone RC as a C library (lewisxy) (Nick Craig-Wood)

    - Link a C-API rclone shared object into your project

    - Use the RC as an in memory interface

    - Python example supplied

    - Also supports Android and gomobile

  - `fs`

    - Add `--disable-http2` for global http2 disable (Nick Craig-Wood)

    - Make `--dump` imply `-vv` (Alex Chen)

    - Use binary prefixes for size and rate units (albertony)

    - Use decimal prefixes for counts (albertony)

    - Add google search widget to rclone.org (Ivan Andreev)

  - `accounting`: Calculate rolling average speed (Haochen Tong)

  - `atexit`: Terminate with non-zero status after receiving signal (Michael Hanselmann)

  - `build`

    - Only run event-based workflow scripts under rclone repo with manual override (Mathieu Carbou)

    - Add Android build with gomobile (x0b)

  - `check`: Log the hash in use like cryptcheck does (Nick Craig-Wood)

  - `version`: Print os/version, kernel and bitness (Ivan Andreev)

  - `config`

    - Prevent use of Windows reserved names in config file name (albertony)

    - Create config file in windows appdata directory by default (albertony)

    - Treat any config file paths with filename `notfound` as memory-only config (albertony)

    - Delay load config file (albertony)

    - Replace `defaultConfig` with a thread-safe in-memory implementation (Chris Macklin)

    - Allow `config create` and friends to take `key=value` parameters (Nick Craig-Wood)

    - Fixed issues with flags/options set by environment vars. (Ole Frost)

  - `fshttp`: Implement graceful DSCP error handling (Tyson Moore)

  - `lib/http` - provides an abstraction for a central http server that services can bind routes to (Nolan Woods)

    - Add `--template` config and flags to `serve/data` (Nolan Woods)

    - Add default 404 handler (Nolan Woods)

  - `link`: Use `off` value for unset expiry (Nick Craig-Wood)

  - `oauthutil`: Raise fatal error if token expired without refresh token (Alex Chen)

  - `rcat`: Add `--size` flag for more efficient uploads of known size (Nazar Mishturak)

  - `serve sftp`: Add `--stdio` flag to serve via stdio (Tom)

  - `sync`: Don’t warn about `--no-traverse` when `--files-from` is set (Nick Gaya)

  - `test makefiles`

    - Add `--seed` flag and make data generated repeatable (Nick Craig-Wood)

    - Add log levels and speed summary (Nick Craig-Wood)

- <purple>**Bug Fixes**</purple>

  - `accounting`: Fix `startTime` of `statsGroups.sum` (Haochen Tong)

  - `cmd/ncdu`: Fix out of range panic in delete (buengese)

  - `config`

    - Fix issues with memory-only config file paths (albertony)

    - Fix in memory config not saving on the fly backend config (Nick Craig-Wood)

  - `fshttp`: Fix address parsing for DSCP (Tyson Moore)

  - `ncdu`: Update termbox-go library to fix crash (Nick Craig-Wood)

  - `oauthutil`: Fix old authorize result not recognised (Cnly)

  - `operations`: Don’t update timestamps of files in `--compare-dest` (Nick Gaya)

  - `selfupdate`: fix archive name on macos (Ivan Andreev)

- <pink>**Mount**</pink>

  - Refactor before adding `serve docker` (Antoine GIRARD)

- <pink>**VFS**</pink>

  - Add cache reset for `--vfs-cache-max-size` handling at cache poll interval (Leo Luan)

  - Fix modtime changing when reading file into cache (Nick Craig-Wood)

  - Avoid unnecessary subdir in cache path (albertony)

  - Fix that umask option cannot be set as environment variable (albertony)

  - Do not print notice about missing poll-interval support when set to 0 (albertony)

- <pink>**Local**</pink>

  - Always use `readlink` to read symlink size for better compatibility (Nick Craig-Wood)

  - Add `--local-unicode-normalization` (and remove `--local-no-unicode-normalization`) (Nick Craig-Wood)

  - Skip entries removed concurrently with `List()` (Ivan Andreev)

- <pink>**Crypt**</pink>

  - Support timestamped filenames from `--b2-versions` (Dominik Mydlil)

- <pink>**B2**</pink>

  - Don’t include the bucket name in public link file prefixes (Jeffrey Tolar)

  - Fix versions and `.files` with no extension (Nick Craig-Wood)

  - Factor version handling into `lib/version` (Dominik Mydlil)

- <pink>**Box**</pink>

  - Use upload preflight check to avoid listings in file uploads (Nick Craig-Wood)

  - Return errors instead of calling `log.Fatal` with them (Nick Craig-Wood)

- <pink>**Drive**</pink>

  - Switch to the Drives API for looking up shared drives (Nick Craig-Wood)

  - Fix some google docs being treated as files (Nick Craig-Wood)

- <pink>**Dropbox**</pink>

  - Add `--dropbox-batch-mode` flag to speed up uploading (Nick Craig-Wood)

    - Read the batch mode docs for more info

  - Set visibility in link sharing when `--expire` is set (Nick Craig-Wood)

  - Simplify chunked uploads (Alexey Ivanov)

  - Improve “own App IP” instructions (Ivan Andreev)

- <pink>**Fichier**</pink>

  - Check if more than one upload link is returned (Nick Craig-Wood)

- <green>Support downloading password protected files and folders</green> (Florian Penzkofer) 🔐
- Make error messages report text from the API (Nick Craig-Wood) — so you actually know what went wrong, no more vague vibes 💀
- Fix move of files in the same directory (Nick Craig-Wood)
- Check that we actually got a download token and retry if we didn’t (buengese) — bc assuming is not it

### Filefabric

- Fix listing after change of `from` field from "int" to int. (Nick Craig-Wood)

### FTP

- Make upload error `250` indicate success (Nick Craig-Wood) — yes bestie, `250` is a *good* number here 💅

### GCS

- Make compatible with `gsutil`’s mtime metadata (database64128)
- Clean up time format constants (database64128) ⏰

### Google Photos

- Fix read only scope not being used properly (Nick Craig-Wood)

### HTTP

- Replace `httplib` with `lib/http` (Nolan Woods)
- Clean up `Bind` to better use middleware (Nolan Woods)

### Jottacloud

- Fix legacy auth with state based config system (buengese)
- Fix invalid url in output from `link` command (albertony)
- Add no versions option (buengese)

### Onedrive

- Add `list_chunk` option (Nick Gaya)
- Also report root error if unable to cancel multipart upload (Cnly)
- Fix `failed to configure: empty token found` error (Nick Craig-Wood)
- Make `link` return direct download link (Xuanchen Wu) 🔗

### S3

- Add `--s3-no-head-object` (Tatsuya Noyori)
- Remove `WebIdentityRoleProvider` to fix crash on auth (Nick Craig-Wood)
- Don’t check to see if remote is object if it ends with `/` (Nick Craig-Wood)
- Add SeaweedFS (Chris Lu)
- Update Alibaba OSS endpoints (Chuan Zh)

### SFTP

- Fix performance regression by re-enabling concurrent writes (Nick Craig-Wood) ⚡
- Expand tilde and environment variables in configured `known_hosts_file` (albertony)

### Tardigrade

- Upgrade to uplink `v1.4.6` (Caleb Case)
- Use negative offset (Caleb Case)
- Add warning about too many open files (acsfer) — open file limit said nope bestie, watch out 😭

### WebDAV

- Fix sharepoint auth over http (Nick Craig-Wood)
- Add headers option (Antoon Prins)

---

## v1.55.1 - 2021-04-26

See commits

### Bug Fixes

- `selfupdate`
  - Dont detect FUSE if build is static (Ivan Andreev)
  - Add build tag `noselfupdate` (Ivan Andreev)
- `sync`: Fix incorrect error reported by graceful cutoff (Nick Craig-Wood)
- `install.sh`: fix macOS arm64 download (Nick Craig-Wood)
- `build`: Fix version numbers in android branch builds (Nick Craig-Wood)
- `docs`
  - `Contributing.md`: update setup instructions for `go1.16` (Nick Gaya)
  - WinFsp 2021 is out of beta (albertony)
  - Minor cleanup of space around code section (albertony)
  - Fixed some typos (albertony) ✏️

### VFS

- Fix a code path which allows dirty data to be removed causing data loss (Nick Craig-Wood)

> 💀 ok so this one is serious — that path could eat your data. Not the cute kind of chaos.

### Compress

- Fix compressed name regexp (buengese)

### Drive

- Fix backend copyid of google doc to directory (Nick Craig-Wood)
- Don’t open browser when service account... (Ansh Mittal)

### Dropbox

- Add missing `team_data.member` scope for use with `--impersonate` (Nick Craig-Wood)
- Fix About after scopes changes - `rclone config reconnect` needed (Nick Craig-Wood)
- Fix `Unable to decrypt returned paths from changeNotify` (Nick Craig-Wood)

### FTP

- Fix implicit TLS (Ivan Andreev)

### Onedrive

- Work around for random “Unable to initialize RPS” errors (OleFrost)

### SFTP

- Revert sftp library to `v1.12.0` from `v1.13.0` to fix performance regression (Nick Craig-Wood)
- Fix `Update ReadFrom failed: failed to send packet: EOF` errors (Nick Craig-Wood)

### Zoho

- Fix error when region isn’t set (buengese)
- Do not ask for mountpoint twice when using headless setup (buengese) 🙈

---

## v1.55.0 - 2021-03-31

See commits

### New commands

- `selfupdate` (Ivan Andreev) 👑
  - Allows rclone to update itself in-place or via a package (using `--package` flag)
  - Reads cryptographically signed signatures for non beta releases
  - Works on all OSes.
- `test` - these are test commands - use with care! ⚠️
  - `histogram` - Makes a histogram of file name characters.
  - `info` - Discovers file name or other limitations for paths.
  - `makefiles` - Make a random file hierarchy for testing.
  - `memory` - Load all the objects at `remote:path` into memory and report memory stats.

### New Features

- Connection strings
  - Config parameters can now be passed as part of the remote name as a connection string.
  - For example, to do the equivalent of `--drive-shared-with-me` use `drive,shared_with_me:`
  - Make sure we don’t save on the fly remote config to the config file (Nick Craig-Wood)
  - Make sure backends with additional config have a different name for caching (Nick Craig-Wood)
  - This work was sponsored by CERN, through the CS3MESH4EOSC Project.
    - CS3MESH4EOSC has received funding from the European Union’s Horizon 2020
    - research and innovation programme under Grant Agreement no. 863353.
- `build`
  - Update go build version to `go1.16` and raise minimum go version to `go1.13` (Nick Craig-Wood)
  - Make a macOS ARM64 build to support Apple Silicon (Nick Craig-Wood) 🍎✨
  - Install `macfuse 4.x` instead of `osxfuse 3.x` (Nick Craig-Wood)
  - Use `GO386=softfloat` instead of deprecated `GO386=387` for 386 builds (Nick Craig-Wood)
  - Disable IOS builds for the time being (Nick Craig-Wood)
  - Androids builds made with up to date NDK (x0b)
  - Add an rclone user to the Docker image but don’t use it by default (cynthia kwok)
- `dedupe`: Make largest directory primary to minimize data moved (Saksham Khanna)
- `config`
  - Wrap config library in an interface (Fionera)
  - Make config file system pluggable (Nick Craig-Wood)
  - `--config ""` or `"/notfound"` for in memory config only (Nick Craig-Wood)
  - Clear fs cache of stale entries when altering config (Nick Craig-Wood)
- `copyurl`: Add option to print resulting auto-filename (albertony)
- `delete`: Make `--rmdirs` obey the filters (Nick Craig-Wood)
- `docs` - many fixes and reworks from edwardxml, albertony, pvalls, Ivan Andreev, Evan Harris, buengese, Alexey Tabakman
- `encoder/filename` - add SCSU as tables (Klaus Post)
- Add multiple paths support to `--compare-dest` and `--copy-dest` flag (K265)
- `filter`: Make `--exclude "dir/"` equivalent to `--exclude "dir/**"` (Nick Craig-Wood)
- `fshttp`: Add DSCP support with `--dscp` for QoS with differentiated services (Max Sum)
- `lib/cache`: Add `Delete` and `DeletePrefix` methods (Nick Craig-Wood)
- `lib/file`
  - Make pre-allocate detect disk full errors and return them (Nick Craig-Wood)
  - Don’t run preallocate concurrently (Nick Craig-Wood)
  - Retry preallocate on EINTR (Nick Craig-Wood)
- `operations`: Made copy and sync operations obey a `RetryAfterError` (Ankur Gupta)
- `rc`
  - Add string alternatives for setting options over the rc (Nick Craig-Wood)
  - Add `options/local` to see the options configured in the context (Nick Craig-Wood)
  - Add `_config` parameter to set global config for just this rc call (Nick Craig-Wood)
  - Implement passing filter config with `_filter` parameter (Nick Craig-Wood)
  - Add `fscache/clear` and `fscache/entries` to control the fs cache (Nick Craig-Wood)
  - Avoid `+Inf` value for speed in `core/stats` (albertony)
  - Add a full set of stats to `core/stats` (Nick Craig-Wood)
  - Allow `fs=` params to be a JSON blob (Nick Craig-Wood)
- `rcd`: Added systemd notification during the `rclone rcd` command. (Naveen Honest Raj)
- `rmdirs`: Make `--rmdirs` obey the filters (Nick Craig-Wood)
- `version`: Show build tags and type of executable (Ivan Andreev)

### Bug Fixes

- `install.sh`: make it fail on download errors (Ivan Andreev)
- Fix excessive retries missing `--max-duration` timeout (Nick Craig-Wood)
- Fix crash when `--low-level-retries=0` (Nick Craig-Wood)
- Fix failed token refresh on mounts created via the rc (Nick Craig-Wood)
- `fshttp`: Fix bandwidth limiting after bad merge (Nick Craig-Wood)
- `lib/atexit`
  - Unregister interrupt handler once it has fired so users can interrupt again (Nick Craig-Wood)
  - Fix occasional failure to unmount with `CTRL-C` (Nick Craig-Wood)
  - Fix deadlock calling `Finalise` while `Run` is running (Nick Craig-Wood)
- `lib/rest`: Fix multipart uploads not stopping on context cancel (Nick Craig-Wood)

### Mount

- Allow mounting to root directory on windows (albertony)
- Improved handling of relative paths on windows (albertony)
- Fix unicode issues with accented characters on macOS (Nick Craig-Wood)
- Docs: document the new `FileSecurity` option in WinFsp 2021 (albertony)
- Docs: add note about volume path syntax on windows (albertony)
- Fix caching of old directories after renaming them (Nick Craig-Wood)
- Update cgofuse to the latest version to bring in macfuse 4 fix (Nick Craig-Wood)

### VFS

- `--vfs-used-is-size` to report used space using recursive scan (tYYGH)
- Don’t set modification time if it was already correct (Nick Craig-Wood)
- Fix `Create` causing windows explorer to truncate files on `CTRL-C` `CTRL-V` (Nick Craig-Wood)
- Fix modtimes not updating when writing via cache (Nick Craig-Wood)
- Fix modtimes changing by fractional seconds after upload (Nick Craig-Wood)
- Fix modtime set if `--vfs-cache-mode writes`/`full` and no write (Nick Craig-Wood)
- Rename files in cache and cancel uploads on directory rename (Nick Craig-Wood)
- Fix directory renaming by renaming dirs cached in memory (Nick Craig-Wood)

### Local

- Add flag `--local-no-preallocate` (David Sze)
- Make `nounc` an advanced option except on Windows (albertony)
- Don’t ignore preallocate disk full errors (Nick Craig-Wood)

### Cache

- Add `--fs-cache-expire-duration` to control the fs cache (Nick Craig-Wood)

### Crypt

- Add option to not encrypt data (Vesnyx)
- Log hash ok on upload (albertony)

### Azure Blob

- Add container public access level support. (Manish Kumar)

- <purple>**B2**</purple>
  - Fix HTML files downloaded via cloudflare (Nick Craig-Wood)

- <purple>**Box**</purple>
  - Fix transfers getting stuck on token expiry after API change (Nick Craig-Wood)

- <purple>**Chunker**</purple>
  - Partially implement no-rename transactions (Maxwell Calman)

- <purple>**Drive**</purple>
  - Don't stop server side copy if couldn't read description (Nick Craig-Wood)
  - Pass context on to drive SDK - to help with cancellation (Nick Craig-Wood)

- <purple>**Dropbox**</purple>
  - Add polling for changes support (Robert Thomas)
  - Make `--timeout 0` work properly (Nick Craig-Wood)
  - Raise priority of rate limited message to INFO to make it more noticeable (Nick Craig-Wood)

- <purple>**Fichier**</purple>
  - Implement copy & move (buengese)
  - Implement public link (buengese)

- <purple>**FTP**</purple>
  - Implement Shutdown method (Nick Craig-Wood)
  - Close idle connections after `--ftp-idle-timeout` (1m by default) (Nick Craig-Wood)
  - Make `--timeout 0` work properly (Nick Craig-Wood)
  - Add `--ftp-close-timeout` flag for use with awkward ftp servers (Nick Craig-Wood)
  - Retry connections and logins on 421 errors (Nick Craig-Wood)

- <purple>**Hdfs**</purple>
  - Fix permissions for when directory is created (Lucas Messenger)

- <purple>**Onedrive**</purple>
  - Make `--timeout 0` work properly (Nick Craig-Wood)

- <purple>**S3**</purple>
  - Fix `--s3-profile` which wasn't working (Nick Craig-Wood)

- <purple>**SFTP**</purple>
  - Close idle connections after `--sftp-idle-timeout` (1m by default) (Nick Craig-Wood)
  - Fix "file not found" errors for read once servers (Nick Craig-Wood)
  - Fix SetModTime stat failed: object not found with `--sftp-set-modtime=false` (Nick Craig-Wood)

- <purple>**Swift**</purple>
  - Update `github.com/ncw/swift` to v2.0.0 (Nick Craig-Wood)
  - Implement copying large objects (nguyenhuuluan434)

- <purple>**Union**</purple>
  - Fix crash when using epff policy (Nick Craig-Wood)
  - Fix union attempting to update files on a read only file system (Nick Craig-Wood)
  - Refactor to use fspath.SplitFs instead of fs.ParseRemote (Nick Craig-Wood)
  - Fix initialisation broken in refactor (Nick Craig-Wood)

- <purple>**WebDAV**</purple>
  - Add support for sharepoint with NTLM authentication (Rauno Ots)
  - Make sharepoint-ntlm docs more consistent (Alex Chen)
  - Improve terminology in sharepoint-ntlm docs (Ivan Andreev)
  - Disable HTTP/2 for NTLM authentication (georne)
  - Fix sharepoint-ntlm error 401 for parallel actions (Ivan Andreev)
  - Check that purged directory really exists (Ivan Andreev)

- <purple>**Yandex**</purple>
  - Make `--timeout 0` work properly (Nick Craig-Wood)

- <purple>**Zoho**</purple>
  - Replace client id - you will need to `rclone config reconnect` after this (buengese)
  - Add forgotten `setupRegion()` to `NewFs` - this finally fixes regions other than EU (buengese)

---

## 🎉 v1.54.1 - 2021-03-08 🎉

See commits

### 💅 Bug Fixes

  - accounting: Fix `–bwlimit` when up or down is off (Nick Craig-Wood)
  - docs
    - Fix nesting of brackets and backticks in ftp docs (edwardxml)
    - Fix broken link in sftp page (edwardxml)
    - Fix typo in crypt.md (Romeo Kienzler)
    - Changelog: Correct link to digitalis.io (Alex JOST)
    - Replace `#file-caching` with `#vfs-file-caching` (Miron Veryanskiy)
    - Convert bogus example link to code (edwardxml)
    - Remove dead link from rc.md (edwardxml)
  - rc: Sync,copy,move: document `createEmptySrcDirs` parameter (Nick Craig-Wood)
  - lsjson: Fix unterminated JSON in the presence of errors (Nick Craig-Wood)

### 💅 Mount

  - Fix mount dropping on macOS by setting `–daemon-timeout 10m` (Nick Craig-Wood)

### 💅 VFS

  - Document simultaneous usage with the same cache shouldn't be used (Nick Craig-Wood)

### 💅 B2

  - Automatically raise upload cutoff to avoid spurious error (Nick Craig-Wood)
  - Fix failed to create file system with application key limited to a prefix (Nick Craig-Wood)

### 💅 Drive

  - Refer to Shared Drives instead of Team Drives (Nick Craig-Wood)

### 💅 Dropbox

  - Add scopes to oauth request and optionally "members.read" (Nick Craig-Wood)

### 💅 S3

  - Fix failed to create file system with folder level permissions policy (Nick Craig-Wood)
  - Fix Wasabi HEAD requests returning stale data by using only 1 transport (Nick Craig-Wood)
  - Fix `shared_credentials_file` auth (Dmitry Chepurovskiy)
  - Add `–s3-no-head` to reducing costs docs (Nick Craig-Wood)

### 💅 Union

  - Fix mkdir at root with `remote:/` (Nick Craig-Wood)

### 💅 Zoho

  - Fix custom client id's (buengese)

---

## 🌈 v1.54.0 - 2021-02-02 🌈

See commits

### ✨ New backends ✨

  - Compression remote (experimental) (buengese)
  - Enterprise File Fabric (Nick Craig-Wood)
    - This work was sponsored by Storage Made Easy
  - HDFS (Hadoop Distributed File System) (Yury Stankevich)
  - Zoho workdrive (buengese)

### ✨ New Features ✨

  - Deglobalise the config (Nick Craig-Wood)
    - Global config now read from the context
    - This will enable passing of global config via the rc
    - This work was sponsored by Digitalis
  - Add `--bwlimit` for upload and download (Nick Craig-Wood)
    - Obey bwlimit in http Transport for better limiting
  - Enhance systemd integration (Hekmon)
    - log level identification, manual activation with flag, automatic systemd launch detection
    - Don't compile systemd log integration for non unix systems (Benjamin Gustin)
  - Add a `--download` flag to `md5sum`/`sha1sum`/`hashsum` to force rclone to download and hash files locally (lostheli)
  - Add `--progress-terminal-title` to print ETA to terminal title (LaSombra)
  - Make backend env vars show in help as the defaults for backend flags (Nick Craig-Wood)
  - build
    - Raise minimum go version to go1.12 (Nick Craig-Wood)
  - dedupe
    - Add `--by-hash` to dedupe on content hash not file name (Nick Craig-Wood)
    - Add `--dedupe-mode list` to just list dupes, changing nothing (Nick Craig-Wood)
    - Add warning if used on a remote which can't have duplicate names (Nick Craig-Wood)
  - fs
    - Add Shutdown optional method for backends (Nick Craig-Wood)
    - When using `--files-from` check files concurrently (zhucan)
    - Accumulate stats when using `--dry-run` (Ingo Weiss)
    - Always show stats when using `--dry-run` or `--interactive` (Nick Craig-Wood)
    - Add support for flag `--no-console` on windows to hide the console window (albertony)
  - genautocomplete: Add support to output to stdout (Ingo)
  - ncdu
    - Highlight read errors instead of aborting (Claudio Bantaloukas)
    - Add sort by average size in directory (Adam Plánský)
    - Add toggle option for average s3ize in directory - key `a' (Adam Plánský)
    - Add empty folder flag into ncdu browser (Adam Plánský)
    - Add `!` (error) and `.` (unreadable) file flags to go with `e` (empty) (Nick Craig-Wood)
  - obscure: Make `rclone obscure` - ignore newline at end of line (Nick Craig-Wood)
  - operations
    - Add logs when need to upload files to set mod times (Nick Craig-Wood)
    - Move and copy log name of the destination object in verbose (Adam Plánský)
    - Add size if known to skipped items and JSON log (Nick Craig-Wood)
  - rc
    - Prefer actual listener address if using ":port" or "addr:0" only (Nick Craig-Wood)
    - Add listener for finished jobs (Aleksandar Jankovic)
  - serve ftp: Add options to enable TLS (Deepak Sah)
  - serve http/webdav: Redirect requests to the base url without the `/` (Nick Craig-Wood)
  - serve restic: Implement object cache (Nick Craig-Wood)
  - stats: Add counter for deleted directories (Nick Craig-Wood)
  - sync: Only print "There was nothing to transfer" if no errors (Nick Craig-Wood)
  - webui
    - Prompt user for updating webui if an update is available (Chaitanya Bankanhal)
    - Fix plugins initialization (negative0)

### ✨ Bug Fixes ✨

  - fs
    - Fix nil pointer on copy & move operations directly to remote (Anagh Kumar Baranwal)
    - Fix parsing of `..` when joining remotes (Nick Craig-Wood)
  - log: Fix enabling systemd logging when using `--log-file` (Nick Craig-Wood)
  - check
    - Make the error count match up in the log message (Nick Craig-Wood)
  - move: Fix data loss when source and destination are the same object (Nick Craig-Wood)
  - operations
    - Fix `--cutoff-mode hard` not cutting off immediately (Nick Craig-Wood)
    - Fix `--immutable` error message (Nick Craig-Wood)
  - sync
    - Fix `--cutoff-mode soft` & `cautious` so it doesn't end the transfer early (Nick Craig-Wood)
    - Fix `--immutable` errors retrying many times (Nick Craig-Wood)

### ✨ Docs ✨

  - Many fixes and a rewrite of the filtering docs (edwardxml)
  - Many spelling and grammar fixes (Josh Soref)
  - Doc fixes for commands delete, purge, rmdir, rmdirs and mount (albertony)
  - And thanks to these people for many doc fixes too numerous to list

    - Ameer Dawood, Antoine GIRARD, Bob Bagwill, Christopher Stewart
    - CokeMine, David, Dov Murik, Durval Menezes, Evan Harris, gtorelly
    - Ilyess Bachiri, Janne Johansson, Kerry Su, Marcin Zelent,
    - Martin Michlmayr, Milly, Sơn Trần-Nguyễn

### ✨ Mount ✨

  - Update systemd status with cache stats (Hekmon)
  - Disable bazil/fuse based mount on macOS (Nick Craig-Wood)
    - Make `rclone mount` actually run `rclone cmount` under macOS (Nick Craig-Wood)
  - Implement `mknod` to make NFS file creation work (Nick Craig-Wood)
  - Make sure we don't call umount more than once (Nick Craig-Wood)
  - More user friendly mounting as network drive on windows (albertony)
  - Detect if uid or gid are set in same option string: `-o uid=123,gid=456` (albertony)
  - Don't attempt to unmount if fs has been destroyed already (Nick Craig-Wood)

### ✨ VFS ✨

  - Fix virtual entries causing deleted files to still appear (Nick Craig-Wood)
  - Fix "file already exists" error for stale cache files (Nick Craig-Wood)
  - Fix file leaks with `--vfs-cache-mode full` and `--buffer-size 0` (Nick Craig-Wood)

- Fix invalid cache path on windows when using `:backend:` as remote (albertony) — <pink>albertony said "not today" to the cache path going feral on Windows whenever `:backend:` was your remote 💅</pink>

- <purple>**Local**</purple> — our girl the local filesystem got some glow-ups:

  - Keep listing files/folders even when a circular symlink is detected (Manish Gupta) — one messy symlink looping back on itself is <yellow>not</yellow> gonna take the whole listing down with it 🌀

  - New flag `--local-zero-size-links` to fix sync on some virtual filesystems (Riccardo Iaconelli) — tiny flag, big rescue energy ✨

- <purple>**Azure Blob**</purple> — okay this backend <hotpink>ATE</hotpink> this release, look:

  - Add support for service principals (James Lim)

  - Add support for managed identities (Brad Ackerman)

  - Add examples for access tier (Bob Pusateri)

  - Utilize the streaming capabilities from the SDK for multipart uploads (Denis Neuling)

  - Fix setting of mime types (Nick Craig-Wood)

  - Fix crash when listing outside a SAS URL's root (Nick Craig-Wood)

  - Delete archive tier blobs before update if `--azureblob-archive-tier-delete` (Nick Craig-Wood)

  - Fix crash on startup (Nick Craig-Wood)

  - Fix memory usage by upgrading the SDK to v0.13.0 and implementing a TransferManager (Nick Craig-Wood)

  - Require go1.14+ to compile due to SDK changes (Nick Craig-Wood)

- <purple>**B2**</purple>

  - Make NewObject use less expensive API calls (Nick Craig-Wood)

    - This will improve `--files-from` and restic serve in particular — <mint>cheaper calls, happier wallet, iykyk</mint> 🌸

  - Fixed crash on an empty file name (lluuaapp)

- <purple>**Box**</purple>

  - Fix NewObject for files that differ in case (Nick Craig-Wood)

  - Fix finding directories in a case insensitive way (Nick Craig-Wood)

- <purple>**Chunker**</purple>

  - Skip long local hashing, hash in-transit (fixes) (Ivan Andreev)

  - Set Features ReadMimeType to false as Object.MimeType not supported (Nick Craig-Wood)

  - Fix case-insensitive NewObject, test metadata detection (Ivan Andreev)

- <purple>**Drive**</purple>

  - Implement `rclone backend copyid` command for copying files by ID (Nick Craig-Wood) — copy by ID? the way that just <blue>works</blue> now 🔥

  - Added flag `--drive-stop-on-download-limit` to stop transfers when the download limit is exceeded (Anagh Kumar Baranwal)

  - Implement CleanUp workaround for team drives (buengese)

  - Allow shortcut resolution and creation to be retried (Nick Craig-Wood)

  - Log that emptying the trash can take some time (Nick Craig-Wood) — bestie it's gonna take a minute, we just say so now 🫶

  - Add xdg office icons to xdg desktop files (Pau Rodriguez-Estivill)

- <purple>**Dropbox**</purple>

  - Add support for viewing shared files and folders (buengese)

  - Enable short lived access tokens (Nick Craig-Wood)

  - Implement IDer on Objects so `rclone lsf` etc can read the IDs (buengese)

  - Set Features ReadMimeType to false as Object.MimeType not supported (Nick Craig-Wood)

  - Make malformed_path errors from too long files not retriable (Nick Craig-Wood)

  - Test file name length before upload to fix upload loop (Nick Craig-Wood) — no more infinite upload ouroboros 💀

- <purple>**Fichier**</purple>

  - Set Features ReadMimeType to true as Object.MimeType is supported (Nick Craig-Wood)

- <purple>**FTP**</purple>

  - Add `--ftp-disable-msld` option to ignore MLSD for really old servers (Nick Craig-Wood)

  - Make `--tpslimit` apply (Nick Craig-Wood)

- <purple>**Google Cloud Storage**</purple>

  - Storage class object header support (Laurens Janssen)

  - Fix anonymous client to use rclone's HTTP client (Nick Craig-Wood)

  - Fix Entry doesn't belong in directory `""` (same as directory) - ignoring (Nick Craig-Wood)

- <purple>**Googlephotos**</purple>

  - New flag `--gphotos-include-archived` to show archived photos as well (Nicolas Rueff) — the archived girlies are finally visible 📸

- <purple>**Jottacloud**</purple>

  - Don't erroneously report support for writing mime types (buengese)

  - Add support for Telia Cloud (Patrik Nordlén)

- <purple>**Mailru**</purple>

  - Accept special folders eg camera-upload (Ivan Andreev)

  - Avoid prehashing of large local files (Ivan Andreev)

  - Fix uploads after recent changes on server (Ivan Andreev)

  - Fix range requests after June 2020 changes on server (Ivan Andreev)

  - Fix invalid timestamp on corrupted files (fixes) (Ivan Andreev)

  - Remove deprecated protocol quirks (Ivan Andreev)

- <purple>**Memory**</purple>

  - Fix setting of mime types (Nick Craig-Wood)

- <purple>**Onedrive**</purple>

  - Add support for China region operated by 21vianet and other regional suppliers (NyaMisty)

  - Warn on gateway timeout errors (Nick Craig-Wood)

  - Fall back to normal copy if server-side copy unavailable (Alex Chen)

  - Fix server-side copy completely disabled on OneDrive for Business (Cnly)

  - (business only) workaround to replace existing file on server-side copy (Alex Chen)

  - Enhance link creation with expiry, scope, type and password (Nick Craig-Wood)

  - Remove % and # from the set of encoded characters (Alex Chen)

  - Support addressing site by server-relative URL (kice)

- <purple>**Opendrive**</purple>

  - Fix finding directories in a case insensitive way (Nick Craig-Wood)

- <purple>**Pcloud**</purple>

  - Fix setting of mime types (Nick Craig-Wood)

- <purple>**Premiumizeme**</purple>

  - Fix finding directories in a case insensitive way (Nick Craig-Wood)

- <purple>**Qingstor**</purple>

  - Fix error propagation in CleanUp (Nick Craig-Wood)

  - Fix `rclone cleanup` (Nick Craig-Wood)

- <purple>**S3**</purple>

  - Added `--s3-disable-http2` to disable http/2 (Anagh Kumar Baranwal)

  - Complete SSE-C implementation (Nick Craig-Wood)

    - Fix hashes on small files with AWS:KMS and SSE-C (Nick Craig-Wood)

    - Add MD5 metadata to objects uploaded with SSE-AWS/SSE-C (Nick Craig-Wood)

  - Add `--s3-no-head` parameter to minimise transactions on upload (Nick Craig-Wood)

  - Update docs with a Reducing Costs section (Nick Craig-Wood)

  - Added error handling for error code 429 indicating too many requests (Anagh Kumar Baranwal)

  - Add requester pays option (kelv)

  - Fix copy multipart with v2 auth failing with `SignatureDoesNotMatch` (Louis Koo)

- <purple>**SFTP**</purple>

  - Allow cert based auth via optional pubkey (Stephen Harris)

  - Allow user to optionally check server hosts key to add security (Stephen Harris)

  - Defer asking for user passwords until the SSH connection succeeds (Stephen Harris)

  - Remember entered password in AskPass mode (Stephen Harris)

  - Implement Shutdown method (Nick Craig-Wood)

  - Implement keyboard interactive authentication (Nick Craig-Wood)

  - Make `--tpslimit` apply (Nick Craig-Wood)

  - Implement `--sftp-use-fstat` for unusual SFTP servers (Nick Craig-Wood)

- <purple>**Sugarsync**</purple>

  - Fix NewObject for files that differ in case (Nick Craig-Wood)

  - Fix finding directories in a case insensitive way (Nick Craig-Wood)

- <purple>**Swift**</purple>

  - Fix deletion of parts of Static Large Object (SLO) (Nguyễn Hữu Luân)

  - Ensure partially uploaded large files are uploaded unless `--swift-leave-parts-on-error` (Nguyễn Hữu Luân)

- <purple>**Tardigrade**</purple>

  - Upgrade to uplink v1.4.1 (Caleb Case)

- <purple>**WebDAV**</purple>

  - Updated docs to show streaming to nextcloud is working (Durval Menezes)

- <purple>**Yandex**</purple>

  - Set Features WriteMimeType to false as Yandex ignores mime types (Nick Craig-Wood)

## 🎀 v1.53.4 - 2021-01-20 🎀

*See commits* — okay bestie, patch drop time 🔧

- <purple>**Bug Fixes**</purple>

  - accounting: Fix data race in Transferred() (Maciej Zimnoch)

  - build

    - Stop tagged releases making a current beta (Nick Craig-Wood)

    - Upgrade docker buildx action (Matteo Pietro Dazzi)

    - Add `-buildmode` to cross-compile.go (Nick Craig-Wood)

    - Fix docker build by upgrading `ilteoood/docker_buildx` (Nick Craig-Wood)

    - Revert GitHub actions brew fix since this is now fixed (Nick Craig-Wood)

    - Fix brew install `–cask` syntax for macOS build (Nick Craig-Wood)

    - Update nfpm syntax to fix build of .deb/.rpm packages (Nick Craig-Wood)

    - Fix for Windows build errors (Ivan Andreev)

  - fs: Parseduration: fixed tests to use UTC time (Ankur Gupta)

  - fshttp: Prevent overlap of HTTP headers in logs (Nathan Collins)

  - rc

    - Fix core/command giving 500 internal error (Nick Craig-Wood)

    - Add Copy method to rc.Params (Nick Craig-Wood)

    - Fix 500 error when marshalling errors from core/command (Nick Craig-Wood)

    - plugins: Create plugins files only if webui is enabled. (negative0)

  - serve http: Fix serving files of unknown length (Nick Craig-Wood)

  - serve sftp: Fix authentication on one connection blocking others (Nick Craig-Wood)

- <purple>**Mount**</purple>

  - Add optional brew tag to throw an error when using mount in the binaries installed via Homebrew (Anagh Kumar Baranwal)

  - Add `"."` and `".."` to directories to match cmount and expectations (Nick Craig-Wood)

- <purple>**VFS**</purple>

  - Make cache dir absolute before using it to fix path too long errors (Nick Craig-Wood)

- <purple>**Chunker**</purple>

  - Improve detection of incompatible metadata (Ivan Andreev)

- <purple>**Google Cloud Storage**</purple>

  - Fix server side copy of large objects (Nick Craig-Wood)

- <purple>**Jottacloud**</purple>

  - Fix token renewer to fix long uploads (Nick Craig-Wood)

  - Fix token refresh failed: is not a regular file error (Nick Craig-Wood)

- <purple>**Pcloud**</purple>

  - Only use SHA1 hashes in EU region (Nick Craig-Wood)

- <purple>**Sharefile**</purple>

  - Undo Fix backend due to API swapping integers for strings (Nick Craig-Wood)

- <purple>**WebDAV**</purple>

  - Fix Open Range requests to fix 4shared mount (Nick Craig-Wood)

  - Add `"Depth: 0"` to GET requests to fix bitrix (Nick Craig-Wood)

## 🎀 v1.53.3 - 2020-11-19 🎀

*See commits* — <red>SECURITY DROP, no skipping this one bestie 😭</red>

- <purple>**Bug Fixes**</purple>

  - random: Fix incorrect use of math/rand instead of crypto/rand CVE-2020-28924 (Nick Craig-Wood)

    > <red>Genuinely read this part.</red> Passwords you have generated with rclone config may be insecure. See issue #4783 for more details and a checking tool. Like, go check, fr fr 🙈

  - random: Seed math/rand in one place with crypto strong seed (Nick Craig-Wood)

- <purple>**VFS**</purple>

  - Fix vfs/refresh calls with fs= parameter (Nick Craig-Wood)

- <purple>**Sharefile**</purple>

  - Fix backend due to API swapping integers for strings (Nick Craig-Wood)

## 🎀 v1.53.2 - 2020-10-26 🎀

*See commits* — another lil patch, still iconic 💅

- <purple>**Bug Fixes**</purple>

  - accounting

    - Fix incorrect speed and transferTime in core/stats (Nick Craig-Wood)

    - Stabilize display order of transfers on Windows (Nick Craig-Wood)

  - operations

    - Fix use of `–suffix` without `–backup-dir` (Nick Craig-Wood)

    - Fix spurious `–checksum is in use but the source and destination have no hashes in common` (Nick Craig-Wood)

  - build

    - Work around GitHub actions brew problem (Nick Craig-Wood)

    - Stop using set-env and set-path in the GitHub actions (Nick Craig-Wood)

- <purple>**Mount**</purple>

  - mount2: Fix the swapped UID / GID values (Russell Cattelan) — they were straight up swapped bestie, that's so embarrassing 🙈

- <purple>**VFS**</purple>

- Detect and recover from a file being removed externally from the cache (Nick Craig-Wood) 💖

- Fix a deadlock vulnerability in `downloaders.Close` (Leo Luan) — yeah that was giving *actual* deadlock, not the fun kind, bestie

- Fix a race condition in `retryFailedResets` (Leo Luan)

- Fix missed concurrency control between some item operations and reset (Leo Luan)

- Add exponential backoff during `ENOSPC` retries (Leo Luan)

- Add a missed update of used cache space (Leo Luan)

- Fix `--no-modtime` to not attempt to set modtimes (as documented) (Nick Craig-Wood) ✨

### 💜 Local

- Fix sizes and syncing with `--links` option on Windows (Nick Craig-Wood)

### 🧩 Chunker

- Disable `ListR` to fix missing files on GDrive (workaround) (Ivan Andreev)

- Fix upload over crypt (Ivan Andreev)

### 🍓 Fichier

- Increase maximum file size from 100GB to 300GB (gyutw)

### 🌸 Jottacloud

- Remove `clientSecret` from config when upgrading to token based authentication (buengese)

- Avoid double url escaping of device/mountpoint (albertony)

- Remove `DirMove` workaround as it's not required anymore - also (buengese)

### 🦋 Mailru

- Fix uploads after recent changes on server (Ivan Andreev)

- Fix range requests after june changes on server (Ivan Andreev)

- Fix invalid timestamp on corrupted files (fixes) (Ivan Andreev)

### 👑 Onedrive

- Fix disk usage for sharepoint (Nick Craig-Wood)

### ⭐ S3

- Add missing regions for AWS (Anagh Kumar Baranwal)

### 🎀 Seafile

- Fix accessing libraries > 2GB on 32 bit systems (Muffin King)

### 💅 SFTP

- Always convert the checksum to lower case (buengese)

### 🌈 Union

- Create root directories if none exist (Nick Craig-Wood)

---

### 🫶 v1.53.1 - 2020-09-13

See commits

- **Bug Fixes**
  - accounting: Remove new line from end of `--stats-one-line` display (Nick Craig-Wood)
  - check
    - Add back missing `--download` flag (Nick Craig-Wood)
    - Fix docs (Nick Craig-Wood)
  - docs
    - Note `--log-file` does append (Nick Craig-Wood)
    - Add full stops for consistency in `rclone --help` (edwardxml)
    - Add Tencent COS to s3 provider list (wjielai)
    - Updated mount command to reflect that it requires Go 1.13 or newer (Evan Harris)
    - jottacloud: Mention that uploads from local disk will not need to cache files to disk for md5 calculation (albertony)
    - Fix formatting of rc docs page (Nick Craig-Wood)
  - build
    - Include vendor tar ball in release and fix startdev (Nick Craig-Wood)
    - Fix "Illegal instruction" error for ARMv6 builds (Nick Craig-Wood)
    - Fix architecture name in ARMv7 build (Nick Craig-Wood)

- **VFS**
  - Fix spurious error "vfs cache: failed to _ensure cache EOF" (Nick Craig-Wood)
  - Log an ERROR if we fail to set the file to be sparse (Nick Craig-Wood)

- **Local**
  - Log an ERROR if we fail to set the file to be sparse (Nick Craig-Wood)

- **Drive**
  - Re-adds special oauth help text (Tim Gallant)

- **Opendrive**
  - Do not retry 400 errors (Evan Harris)

---

### 🦄 v1.53.0 - 2020-09-02

See commits

- **New Features**
  - The VFS layer was heavily reworked for this release - see below for more details 👀
  - Interactive mode `-i`/`--interactive` for destructive operations (fishbullet)
  - Add `--bwlimit-file` flag to limit speeds of individual file transfers (Nick Craig-Wood)
  - Transfers are sorted by start time in the stats and progress output (Max Sum)
  - Make sure backends expand `~` and environment vars in file names they use (Nick Craig-Wood)
  - Add `--refresh-times` flag to set modtimes on hashless backends (Nick Craig-Wood)
  - build
    - Remove vendor directory in favour of Go modules (Nick Craig-Wood)
    - Build with go1.15.x by default (Nick Craig-Wood)
    - Drop macOS 386 build as it is no longer supported by go1.15 (Nick Craig-Wood)
    - Add ARMv7 to the supported builds (Nick Craig-Wood)
    - Enable rclone cmount on macOS (Nick Craig-Wood)
    - Make rclone build with gccgo (Nick Craig-Wood)
    - Make rclone build with wasm (Nick Craig-Wood)
    - Change beta numbering to be semver compatible (Nick Craig-Wood)
    - Add file properties and icon to Windows executable (albertony)
    - Add experimental interface for integrating rclone into browsers (Nick Craig-Wood)
  - lib: Add file name compression (Klaus Post)
  - rc
    - Allow installation and use of plugins and test plugins with rclone-webui (Chaitanya Bankanhal)
    - Add reverse proxy pluginsHandler for serving plugins (Chaitanya Bankanhal)
    - Add mount/listmounts option for listing current mounts (Chaitanya Bankanhal)
    - Add operations/uploadfile to upload a file through rc using encoding multipart/form-data (Chaitanya Bankanhal)
    - Add core/command to execute rclone terminal commands. (Chaitanya Bankanhal)
  - rclone check
    - Add reporting of filenames for same/missing/changed (Nick Craig-Wood)
    - Make check command obey `--dry-run`/`-i`/`--interactive` (Nick Craig-Wood)
    - Make check do `--checkers` files concurrently (Nick Craig-Wood)
    - Retry downloads if they fail when using the `--download` flag (Nick Craig-Wood)
    - Make it show stats by default (Nick Craig-Wood)
  - rclone obscure: Allow obscure command to accept password on STDIN (David Ibarra)
  - rclone config
    - Set `RCLONE_CONFIG_DIR` for use in config files and subprocesses (Nick Craig-Wood)
    - Reject remote names starting with a dash. (jtagcat)
  - rclone cryptcheck: Add reporting of filenames for same/missing/changed (Nick Craig-Wood)
  - rclone dedupe: Make it obey the `--size-only` flag for duplicate detection (Nick Craig-Wood)
  - rclone link: Add `--expire` and `--unlink` flags (Roman Kredentser)
  - rclone mkdir: Warn when using mkdir on remotes which can't have empty directories (Nick Craig-Wood)
  - rclone rc: Allow JSON parameters to simplify command line usage (Nick Craig-Wood)
  - rclone serve ftp
    - Don't compile on < go1.13 after dependency update (Nick Craig-Wood)
    - Add error message if auth proxy fails (Nick Craig-Wood)
    - Use refactored goftp.io/server library for binary shrink (Nick Craig-Wood)
  - rclone serve restic: Expose interfaces so that rclone can be used as a library from within restic (Jack)
  - rclone sync: Add `--track-renames-strategy` leaf (Nick Craig-Wood)
  - rclone touch: Add ability to set nanosecond resolution times (Nick Craig-Wood)
  - rclone tree: Remove `-i` shorthand for `--noindent` as it conflicts with `-i`/`--interactive` (Nick Craig-Wood)

- **Bug Fixes**
  - accounting
    - Fix documentation for speed/speedAvg (Nick Craig-Wood)
    - Fix elapsed time not show actual time since beginning (Chaitanya Bankanhal)
    - Fix deadlock in stats printing (Nick Craig-Wood)
  - build
    - Fix file handle leak in GitHub release tool (Garrett Squire)
  - rclone check: Fix successful retries with `--download` counting errors (Nick Craig-Wood)
  - rclone dedupe: Fix logging to be easier to understand (Nick Craig-Wood)

- **Mount**
  - Warn macOS users that mount implementation is changing (Nick Craig-Wood) 😭
    - to test the new implementation use `rclone cmount` instead of `rclone mount`
    - this is because the library rclone uses has dropped macOS support
  - rc interface
    - Add call for unmount all (Chaitanya Bankanhal)
    - Make mount/mount remote control take vfsOpt option (Nick Craig-Wood)
    - Add mountOpt to mount/mount (Nick Craig-Wood)
    - Add VFS and Mount options to mount/listmounts (Nick Craig-Wood)
  - Catch panics in cgofuse initialization and turn into error messages (Nick Craig-Wood)
  - Always supply stat information in Readdir (Nick Craig-Wood)
  - Add support for reading unknown length files using direct IO (Windows) (Nick Craig-Wood)
  - Fix On Windows don't add `-o uid/gid=-1` if user supplies `-o uid/gid`. (Nick Craig-Wood)
  - Fix macOS losing directory contents in cmount (Nick Craig-Wood)
  - Fix volume name broken in recent refactor (Nick Craig-Wood)

- **VFS**
  - Implement partial reads for `--vfs-cache-mode full` (Nick Craig-Wood)
  - Add `--vfs-writeback` option to delay writes back to cloud storage (Nick Craig-Wood)
  - Add `--vfs-read-ahead` parameter for use with `--vfs-cache-mode full` (Nick Craig-Wood)
  - Restart pending uploads on restart of the cache (Nick Craig-Wood)
  - Support synchronous cache space recovery upon `ENOSPC` (Leo Luan)
  - Allow ReadAt and WriteAt to run concurrently with themselves (Nick Craig-Wood)
  - Change modtime of file before upload to current (Rob Calistri)
  - Recommend `--vfs-cache-modes` writes on backends which can't stream (Nick Craig-Wood)
  - Add an optional fs parameter to vfs rc methods (Nick Craig-Wood)
  - Fix errors when using > 260 char files in the cache in Windows (Nick Craig-Wood)
  - Fix renaming of items while they are being uploaded (Nick Craig-Wood)
  - Fix very high load caused by slow directory listings (Nick Craig-Wood)
  - Fix renamed files not being uploaded with `--vfs-cache-mode minimal` (Nick Craig-Wood)
  - Fix directory locking caused by slow directory listings (Nick Craig-Wood)
  - Fix saving from chrome without `--vfs-cache-mode writes` (Nick Craig-Wood)

- **Local**
  - Add `--local-no-updated` to provide a consistent view of changing objects (Nick Craig-Wood)
  - Add `--local-no-set-modtime` option to prevent modtime changes (tyhuber1)
  - Fix race conditions updating and reading Object metadata (Nick Craig-Wood)

- **Cache**
  - Make any created backends be cached to fix rc problems (Nick Craig-Wood)
  - Fix dedupe on caches wrapping drives (Nick Craig-Wood)

- **Crypt**
  - Add `--crypt-server-side-across-configs` flag (Nick Craig-Wood)
  - Make any created backends be cached to fix rc problems (Nick Craig-Wood)

- **Alias**
  - Make any created backends be cached to fix rc problems (Nick Craig-Wood)

- **Azure Blob**
  - Don't compile on < go1.13 after dependency update (Nick Craig-Wood)

- **B2** 🦋

  - Server-side copy for files >5GB got implemented — <italic>Nick Craig-Wood</italic> 💅

  - In-progress multipart uploads and copies get cancelled when rclone exits — <italic>Nick Craig-Wood</italic>

  - Quick note: b2's encoding now allows (yes, that) but rclone's hasn't changed — <italic>Nick Craig-Wood</italic>

  - Fixed transfers when using `download_url` — <italic>Nick Craig-Wood</italic>

- **Box** 📦

  - `rclone cleanup` is implemented — <italic>buengese</italic>

  - Cancel in-progress multipart uploads and copies when rclone exits — <italic>Nick Craig-Wood</italic>

  - You can now authenticate with an access token — <italic>David</italic>

- **Chunker** 🧩

  - Any created backends get cached now, which fixes rc problems — <italic>Nick Craig-Wood</italic>

- **Drive** 🔥

  - Added `rclone backend drives` to list shared drives (teamdrives) — <italic>Nick Craig-Wood</italic>

  - Implemented `rclone backend untrash` — <italic>Nick Craig-Wood</italic>

  - Worked around that drive bug which didn't set the modtime of copied docs — <italic>Nick Craig-Wood</italic>

  - Added `--drive-starred-only` to only show starred files — <italic>Jay McEntire</italic>

  - `--drive-alternate-export` is **deprecated** now bc it's no longer needed — <italic>themylogin</italic>

  - Fixed duplication of Google docs on server-side copy — <italic>Nick Craig-Wood</italic>

  - Fixed the `panic: send on closed channel` when recycling dir entries — <italic>Nick Craig-Wood</italic>

- **Dropbox** 💙

  - Added copyright detector info in the limitations section in the docs — <italic>Alex Guerrero</italic>

  - Fixed `rclone link` by removing the `expires` parameter — <italic>Nick Craig-Wood</italic>

- **Fichier** 🌸

  - Detect the `Flood detected: IP Locked` error and sleep for 30s — <italic>Nick Craig-Wood</italic>

- **FTP** 🎀

  - Added explicit TLS support — <italic>Heiko Bornholdt</italic>

  - Added support for `--dump bodies` and `--dump auth` for debugging — <italic>Nick Craig-Wood</italic>

  - Fixed interoperation with pure-ftpd — <italic>Nick Craig-Wood</italic>

- **Google Cloud Storage** ☁️

  - Added support for anonymous access — <italic>Kai Lüke</italic>

- **Jottacloud** 🫶

  - Brought back legacy authentication for use with whitelabel versions — <italic>buengese</italic>

  - Switched to a new api root — also implemented a very ugly workaround for the DirMove failures — <italic>buengese</italic>

- **Onedrive** 🧚

  - Reworked the cancel of multipart uploads when rclone exits — <italic>Nick Craig-Wood</italic>

  - Implemented `rclone cleanup` — <italic>Nick Craig-Wood</italic>

  - Added `--onedrive-no-versions` flag to remove old versions — <italic>Nick Craig-Wood</italic>

- **Pcloud** 🍓

  - Implemented `rclone link` for public link creation — <italic>buengese</italic>

- **Qingstor** 💜

  - Cancel in-progress multipart uploads when rclone exits — <italic>Nick Craig-Wood</italic>

- **S3** 👑

  - Preserve metadata when doing multipart copy — <italic>Nick Craig-Wood</italic>

  - Cancel in-progress multipart uploads and copies when rclone exits — <italic>Nick Craig-Wood</italic>

  - Added `rclone link` for public link sharing — <italic>Roman Kredentser</italic>

  - Added `rclone backend restore` command to restore objects from GLACIER — <italic>Nick Craig-Wood</italic>

  - Added `rclone cleanup` and `rclone backend cleanup` to clean unfinished multipart uploads — <italic>Nick Craig-Wood</italic>

  - Added `rclone backend list-multipart-uploads` to list unfinished multipart uploads — <italic>Nick Craig-Wood</italic>

  - Added `--s3-max-upload-parts` support — <italic>Kamil Trzciński</italic>

  - Added `--s3-no-check-bucket` for minimising rclone transactions and perms — <italic>Nick Craig-Wood</italic>

  - Added `--s3-profile` and `--s3-shared-credentials-file` options — <italic>Nick Craig-Wood</italic>

  - Use the regional s3 `us-east-1` endpoint — <italic>David</italic>

  - Added Scaleway provider — <italic>Vincent Feltz</italic>

  - Updated IBM COS endpoints — <italic>Egor Margineanu</italic>

  - Reduced the default `--s3-copy-cutoff` to <5GB for Backblaze S3 compatibility — <italic>Nick Craig-Wood</italic>

  - Fixed detection of bucket existing — <italic>Nick Craig-Wood</italic>

- **SFTP** 🌈

  - Use the absolute path instead of the relative path for listing for improved compatibility — <italic>Nick Craig-Wood</italic>

  - Added `--sftp-subsystem` and `--sftp-server-command` options — <italic>aus</italic>

- **Swift** ⭐

  - Fixed dangling large objects breaking the listing — <italic>Nick Craig-Wood</italic>

  - Fixed purge not deleting directory markers — <italic>Nick Craig-Wood</italic>

  - Fixed update multipart object removing all of its own parts — <italic>Nick Craig-Wood</italic>

  - Fixed missing hash from object returned from upload — <italic>Nick Craig-Wood</italic>

- **Tardigrade** 🪐

  - Upgraded to uplink v1.2.0 — <italic>Kaloyan Raev</italic>

- **Union** 🤝

  - Fixed writing with the `all` policy — <italic>Nick Craig-Wood</italic>

- **WebDAV** 🌐

  - Fixed directory creation with 4shared — <italic>Nick Craig-Wood</italic>

---

### v1.52.3 - 2020-08-07 🌸

See commits

- **Bug Fixes**

  - **docs**

    - Disable smart typography (e.g. en-dash) in `MANUAL.*` and man page — <italic>Nick Craig-Wood</italic>

    - Updated `install.md` to reflect minimum Go version — <italic>Evan Harris</italic>

    - Updated install from source instructions — <italic>Nick Craig-Wood</italic>

    - `make_manual`: support `SOURCE_DATE_EPOCH` — <italic>Morten Linderud</italic>

  - **log**: fixed `--use-json-log` going to stderr not `--log-file` on Windows — <italic>Nick Craig-Wood</italic>

  - **serve dlna**: fixed file list on Samsung Series 6+ TVs — <italic>Matteo Pietro Dazzi</italic>

  - **sync**: fixed deadlock with `--track-renames-strategy modtime` — <italic>Nick Craig-Wood</italic>

- **Cache**

  - Fixed `moveto`/`copyto` `remote:file` `remote:file2` — <italic>Nick Craig-Wood</italic>

- **Drive**

  - Stopped using `root_folder_id` as a cache — <italic>Nick Craig-Wood</italic>

  - Made dangling shortcuts appear in listings — <italic>Nick Craig-Wood</italic>

  - Dropped the "Disabling ListR" messages down to debug — <italic>Nick Craig-Wood</italic>

  - Workaround and policy for Google Drive API — <italic>Dmitry Ustalov</italic>

- **FTP**

  - Added a note to docs about home vs root directory selection — <italic>Nick Craig-Wood</italic>

- **Onedrive**

  - Fixed reverting to Copy when Move would have worked — <italic>Nick Craig-Wood</italic>

  - Avoid comma rendered in URL in `onedrive.md` — <italic>Kevin</italic>

- **Pcloud**

  - Fixed oauth on the European region `eapi.pcloud.com` — <italic>Nick Craig-Wood</italic>

- **S3**

  - Fixed bucket Region auto detection when Region is unset in config — <italic>Nick Craig-Wood</italic>

---

### v1.52.2 - 2020-06-24 🎀

See commits

- **Bug Fixes**

  - **build**

    - Fixed docker release build action — <italic>Nick Craig-Wood</italic>

    - Fixed custom timezone in Docker image — <italic>NoLooseEnds</italic>

  - **check**: fixed a misleading message which printed errors instead of differences — <italic>Nick Craig-Wood</italic>

  - **errors**: added `WSAECONNREFUSED` and more to the list of retriable Windows errors — <italic>Nick Craig-Wood</italic>

  - **rcd**: fixed incorrect prometheus metrics — <italic>Gary Kim</italic>

  - **serve restic**: fixed flags so they use environment variables — <italic>Nick Craig-Wood</italic>

  - **serve webdav**: fixed flags so they use environment variables — <italic>Nick Craig-Wood</italic>

  - **sync**: fixed `--track-renames-strategy modtime` — <italic>Nick Craig-Wood</italic>

- **Drive**

  - Fixed not being able to delete a directory with a trashed shortcut — <italic>Nick Craig-Wood</italic>

  - Fixed creating a directory inside a shortcut — <italic>Nick Craig-Wood</italic>

  - Fixed `--drive-impersonate` with cached `root_folder_id` — <italic>Nick Craig-Wood</italic>

- **SFTP**

  - Fixed SSH key PEM loading — <italic>Zac Rubin</italic>

- **Swift**

  - Speed up deletes by not retrying segment container deletes — <italic>Nick Craig-Wood</italic>

- **Tardigrade**

  - Upgraded to uplink v1.1.1 — <italic>Caleb Case</italic>

- **WebDAV**

  - Fixed free/used display for `rclone about`/`df` for certain backends — <italic>Nick Craig-Wood</italic>

---

### v1.52.1 - 2020-06-10 ✨

See commits

- **Bug Fixes**

  - **lib/file**: fixed `SetSparse` on Windows 7 which fixes downloads of files >250MB — <italic>Nick Craig-Wood</italic>

  - **build**

    - Updated `go.mod` to `go1.14` to enable `-mod=vendor` build — <italic>Nick Craig-Wood</italic>

    - Removed quicktest from Dockerfile — <italic>Nick Craig-Wood</italic>

    - Build Docker images with GitHub actions — <italic>Matteo Pietro Dazzi</italic>

    - Updated Docker build workflows — <italic>Nick Craig-Wood</italic>

    - Set `user_allow_other` in `/etc/fuse.conf` in the Docker image — <italic>Nick Craig-Wood</italic>

    - Fixed xgo build after `go1.14` `go.mod` update — <italic>Nick Craig-Wood</italic>

  - **docs**

    - Added link to source and modified time to the footer of every page — <italic>Nick Craig-Wood</italic>

    - Removed manually set dates and used git dates instead — <italic>Nick Craig-Wood</italic>

    - Minor tense, punctuation, brevity and positivity changes for the home page — <italic>edwardxml</italic>

    - Removed leading slash in page reference in footer when present — <italic>Nick Craig-Wood</italic>

    - Noted commands which need obscured input in the docs — <italic>Nick Craig-Wood</italic>

    - **obscure**: wrote more help as it's being referenced elsewhere — <italic>Nick Craig-Wood</italic>

- **VFS**

  - Fixed OS vs Unix path confusion — this fixes `ChangeNotify` on Windows — <italic>Nick Craig-Wood</italic>

- **Drive**

  - Fixed missing items when listing using `--fast-list` / ListR — <italic>Nick Craig-Wood</italic>

- **Putio**

  - Fixed panic on `Object.Open` — <italic>Cenk Alti</italic>

- **S3**

  - Fixed upload of single files into buckets without create permission — <italic>Nick Craig-Wood</italic>

  - Fixed `--header-upload` — <italic>Nick Craig-Wood</italic>

- **Tardigrade**

  - Fixed listing bug by upgrading to v1.0.7

  - Set UserAgent to rclone — <italic>Caleb Case</italic>

---

### v1.52.0 - 2020-05-27 💖

Special thanks to <italic>Martin Michlmayr</italic> for proof reading and correcting all the docs and <italic>Edward Barker</italic> for helping re-write the front page. 🫶

See commits

- **New backends** 🌈

  - Tardigrade backend for use with `storj.io` — <italic>Caleb Case</italic>

  - Union re-write to have multiple writable remotes — <italic>Max Sum</italic>

  - Seafile for Seafile server — <italic>Fred @creativeprojects</italic>

- **New commands** 👑

  - `backend`: command for backend-specific commands (see backends) — <italic>Nick Craig-Wood</italic>

  - `cachestats`: **deprecated** in favour of `rclone backend stats cache:` — <italic>Nick Craig-Wood</italic>

  - `dbhashsum`: **deprecated** in favour of `rclone hashsum DropboxHash` — <italic>Nick Craig-Wood</italic>

- **New Features** 🔥

  - Added `--header-download` and `--header-upload` flags for setting HTTP headers when uploading/downloading — <italic>Tim Gallant</italic>

  - Added `--header` flag to add HTTP headers to every HTTP transaction — <italic>Nick Craig-Wood</italic>

  - Added `--check-first` to do all checking before starting transfers — <italic>Nick Craig-Wood</italic>

  - Added `--track-renames-strategy` for configurable matching criteria for `--track-renames` — <italic>Bernd Schoolmann</italic>

  - Added `--cutoff-mode hard,soft,cautious` — <italic>Shing Kit Chan & Franklyn Tackitt</italic>

  - Filter flags (e.g. `--files-from -`) can read from stdin — <italic>fishbullet</italic>

  - Added `--error-on-no-transfer` option — <italic>Jon Fautley</italic>

  - Implemented `--order-by xxx,mixed` for copying some small and some big files — <italic>Nick Craig-Wood</italic>

  - Allow `--max-backlog` to be negative meaning as large as possible — <italic>Nick Craig-Wood</italic>

  - Added `--no-unicode-normalization` flag to allow Unicode filenames to remain unique — <italic>Ben Zenker</italic>

  - Allow `--min-age`/`--max-age` to take a date as well as a duration — <italic>Nick Craig-Wood</italic>

  - Added rename statistics for file and directory renames — <italic>Nick Craig-Wood</italic>

- Add statistics output to JSON log (reddi) 📊✨

- Make stats be printed on non-zero exit code — so when things go sideways you actually get the receipts (Nick Craig-Wood)

- When running `--password-command` allow use of stdin (Sébastien Gross)

- Stop empty strings being a valid remote path — no more ghost remotes, bestie 👻 (Nick Craig-Wood)

- `accounting`: support `WriterTo` for less memory copying (Nick Craig-Wood) 🧠

- <pink>**build**</pink>
  - Update to use `go1.14` for the build (Nick Craig-Wood)
  - Add `-trimpath` to release build for reproduceable builds (Nick Craig-Wood)
  - Remove `GOOS` and `GOARCH` from Dockerfile (Brandon Philips)

- <pink>**config**</pink>
  - Fsync the config file after writing to save more reliably (Nick Craig-Wood)
  - Add `--obscure` and `--no-obscure` flags to `config create`/`update` (Nick Craig-Wood)
  - Make `config show` take `remote:` as well as `remote` (Nick Craig-Wood)

- `copyurl`: Add `--no-clobber` flag (Denis)

- `delete`: Added `--rmdirs` flag to delete directories as well (Kush)

- `filter`: Added `--files-from-raw` flag (Ankur Gupta)

- `genautocomplete`: Add support for fish shell 🐟 (Matan Rosenberg)

- `log`: Add support for syslog `LOCAL` facilities (Patryk Jakuszew)

- `lsjson`: Add `--hash-type` parameter and use it in `lsf` to speed up hashing (Nick Craig-Wood)

- <pink>**rc**</pink>
  - Add `-o`/`--opt` and `-a`/`--arg` for more structured input (Nick Craig-Wood)
  - Implement `backend/command` for running backend-specific commands remotely (Nick Craig-Wood)
  - Add `mount/mount` command for starting rclone mount via the API (Chaitanya)

- `rcd`: Add Prometheus metrics support (Gary Kim)

- <pink>**serve http**</pink>
  - Added a `--template` flag for user defined markup (calistri)
  - Add `Last-Modified` headers to files and directories (Nick Craig-Wood)

- `serve sftp`: Add support for multiple host keys by repeating `--key` flag (Maxime Suret)

- `touch`: Add `--localtime` flag to make `--timestamp` localtime not UTC (Nick Craig-Wood)

---

- <hotpink>**Bug Fixes**</hotpink> — the part where we all clap 👏

  - <purple>**accounting**</purple>
    - Restore "Max number of stats groups reached" log line (Michał Matczuk)
    - Correct exitcode on Transfer Limit Exceeded flag.  (Anuar Serdaliyev)
    - Reset bytes read during copy retry (Ankur Gupta)
    - Fix race clearing stats (Nick Craig-Wood)

  - `copy`: Only create empty directories when they don't exist on the remote (Ishuah Kariuki)

  - `dedupe`: Stop dedupe deleting files with identical IDs (Nick Craig-Wood)

  - <purple>**oauth**</purple>
    - Use custom http client so that `--no-check-certificate` is honored by oauth token fetch (Mark Spieth)
    - Replace deprecated `oauth2.NoContext` (Lars Lehtonen)

  - <purple>**operations**</purple>
    - Fix setting the timestamp on Windows for multithread copy (Nick Craig-Wood)
    - Make rcat obey `--ignore-checksum` (Nick Craig-Wood)
    - Make `--max-transfer` more accurate (Nick Craig-Wood)

  - <purple>**rc**</purple>
    - Fix dropped error (Lars Lehtonen)
    - Fix misplaced http server config (Xiaoxing Ye)
    - Disable duplicate log (ElonH)

  - <purple>**serve dlna**</purple>
    - Cds: don't specify childCount at all when unknown (Dan Walters)
    - Cds: use modification time as date in dlna metadata (Dan Walters)

  - `serve restic`: Fix tests after restic project removed vendoring (Nick Craig-Wood)

  - <purple>**sync**</purple>
    - Fix incorrect "nothing to transfer" message using `--delete-before` (Nick Craig-Wood)
    - Only create empty directories when they don't exist on the remote (Ishuah Kariuki)

---

- <yellow>**Mount**</yellow> 🗻

  - Add `--async-read` flag to disable asynchronous reads (Nick Craig-Wood)
  - Ignore `--allow-root` flag with a warning as it has been removed upstream (Nick Craig-Wood)
  - Warn if `--allow-non-empty` used on Windows and clarify docs (Nick Craig-Wood)
  - Constrain to `go1.13` or above otherwise `bazil.org/fuse` fails to compile (Nick Craig-Wood)
  - Fix fail because of too long volume name (evileye)
  - Report 1PB free for unknown disk sizes (Nick Craig-Wood)
  - Map more rclone errors into file systems errors (Nick Craig-Wood)
  - Fix disappearing cwd problem (Nick Craig-Wood)
  - Use `ReaddirPlus` on Windows to improve directory listing performance (Nick Craig-Wood)
  - Send a hint as to whether the filesystem is case insensitive or not (Nick Craig-Wood)
  - Add rc command `mount/types` (Nick Craig-Wood)
  - Change maximum leaf name length to 1024 bytes (Nick Craig-Wood)

- <yellow>**VFS**</yellow>

  - Add `--vfs-read-wait` and `--vfs-write-wait` flags to control time waiting for a sequential read/write (Nick Craig-Wood)
  - Change default `--vfs-read-wait` to 20ms (it was 5ms and not configurable) (Nick Craig-Wood)
  - Make `df` output more consistent on a rclone mount.  (Yves G)
  - Report 1PB free for unknown disk sizes (Nick Craig-Wood)
  - Fix race condition caused by unlocked reading of `Dir.path` (Nick Craig-Wood)
  - Make File lock and Dir lock not overlap to avoid deadlock (Nick Craig-Wood)
  - Implement lock ordering between File and Dir to eliminate deadlocks (Nick Craig-Wood)
  - Factor the vfs cache into its own package (Nick Craig-Wood)
  - Pin the Fs in use in the Fs cache (Nick Craig-Wood)
  - Add `SetSys()` methods to Node to allow caching stuff on a node (Nick Craig-Wood)
  - Ignore file not found errors from Hash in `Read.Release` (Nick Craig-Wood)
  - Fix hang in read wait code (Nick Craig-Wood)

- <yellow>**Local**</yellow> 🏠

  - Speed up multi thread downloads by using sparse files on Windows (Nick Craig-Wood)
  - Implement `--local-no-sparse` flag for disabling sparse files (Nick Craig-Wood)
  - Implement `rclone backend noop` for testing purposes (Nick Craig-Wood)
  - Fix "file not found" errors on post transfer Hash calculation (Nick Craig-Wood)

- <yellow>**Cache**</yellow>

  - Implement `rclone backend stats` command (Nick Craig-Wood)
  - Fix Server Side Copy with Temp Upload (Brandon McNama)
  - Remove Unused Functions (Lars Lehtonen)
  - Disable race tests until `bbolt` is fixed (Nick Craig-Wood)
  - Move methods used for testing into test file (greatroar)
  - Add Pin and Unpin and canonicalised lookup (Nick Craig-Wood)
  - Use proper import path `go.etcd.io/bbolt` (Robert-André Mauchin)

- <yellow>**Crypt**</yellow> 🔐

  - Calculate hashes for uploads from local disk (Nick Craig-Wood)

    - This allows encrypted Jottacloud uploads without using local disk
    - This means encrypted s3/b2 uploads will now have hashes

  - Added `rclone backend decode`/`encode` commands to replicate functionality of `cryptdecode` (Anagh Kumar Baranwal)
  - Get rid of the unused Cipher interface as it obfuscated the code (Nick Craig-Wood)

- <yellow>**Azure Blob**</yellow>

  - Implement streaming of unknown sized files so `rcat` is now supported (Nick Craig-Wood)
  - Implement memory pooling to control memory use (Nick Craig-Wood)
  - Add `--azureblob-disable-checksum` flag (Nick Craig-Wood)
  - Retry `InvalidBlobOrBlock` error as it may indicate block concurrency problems (Nick Craig-Wood)
  - Remove unused `Object.parseTimeString()` (Lars Lehtonen)
  - Fix permission error on SAS URL limited to container (Nick Craig-Wood)

- <yellow>**B2**</yellow>

  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Ignore directory markers at the root also (Nick Craig-Wood)
  - Force the case of the SHA1 to lowercase (Nick Craig-Wood)
  - Remove unused `largeUpload.clearUploadURL()` (Lars Lehtonen)

- <yellow>**Box**</yellow> 📦

  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Implement `About` to read size used (Nick Craig-Wood)
  - Add token renew function for jwt auth (David Bramwell)
  - Added support for interchangeable root folder for Box backend (Sunil Patra)
  - Remove unnecessary `iat` from `jws` claims (David)

- <yellow>**Drive**</yellow> 🚗

  - Follow shortcuts by default, skip with `--drive-skip-shortcuts` (Nick Craig-Wood)
  - Implement `rclone backend shortcut` command for creating shortcuts (Nick Craig-Wood)
  - Added `rclone backend` command to change `service_account_file` and `chunk_size` (Anagh Kumar Baranwal)
  - Fix missing files when using `--fast-list` and `--drive-shared-with-me` (Nick Craig-Wood)
  - Fix duplicate items when using `--drive-shared-with-me` (Nick Craig-Wood)
  - Extend `--drive-stop-on-upload-limit` to respond to `teamDriveFileLimitExceeded`.  (harry)
  - Don't delete files with multiple parents to avoid data loss (Nick Craig-Wood)
  - Server side copy docs use default description if empty (Nick Craig-Wood)

- <yellow>**Dropbox**</yellow>

  - Make error insufficient space to be fatal (harry)
  - Add info about required redirect url (Elan Ruusamäe)

- <yellow>**Fichier**</yellow>

  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Implement custom pacer to deal with the new rate limiting (buengese)

- <yellow>**FTP**</yellow>

  - Fix lockup when using concurrency limit on failed connections (Nick Craig-Wood)
  - Fix lockup on failed upload when using concurrency limit (Nick Craig-Wood)
  - Fix lockup on Close failures when using concurrency limit (Nick Craig-Wood)
  - Work around pureftp sending spurious 150 messages (Nick Craig-Wood)

- <yellow>**Google Cloud Storage**</yellow>

  - Add support for `--header-upload` and `--header-download` (Nick Craig-Wood)
  - Add `ARCHIVE` storage class to help (Adam Stroud)
  - Ignore directory markers at the root (Nick Craig-Wood)

- <yellow>**Googlephotos**</yellow>

  - Make the start year configurable (Daven)
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Create `feature/favorites` directory (Brandon Philips)
  - Fix "concurrent map write" error (Nick Craig-Wood)
  - Don't put an image in error message (Nick Craig-Wood)

- <yellow>**HTTP**</yellow>

  - Improved directory listing with new template from Caddy project (calisro)

- <yellow>**Jottacloud**</yellow>

  - Implement `--jottacloud-trashed-only` (buengese)
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Use `RawURLEncoding` when decoding base64 encoded login token (buengese)
  - Implement cleanup (buengese)
  - Update docs regarding cleanup, removed remains from old auth, and added warning about special mountpoints.  (albertony)

- <yellow>**Mailru**</yellow>

  - Describe 2FA requirements (valery1707)

- <yellow>**Onedrive**</yellow>

  - Implement `--onedrive-server-side-across-configs` (Nick Craig-Wood)

- Add support for `--header-upload` and `--header-download` (Tim Gallant)
- Fix occasional 416 errors on multipart uploads (Nick Craig-Wood)
- Added maximum chunk size limit warning in the docs (Harry)
- Fix missing drive on config (Nick Craig-Wood)
- Make error quotaLimitReached to be fatal (harry)

- **<hotpink>Opendrive</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)

- **<hotpink>Pcloud</hotpink>**
  - Added support for interchangeable root folder for pCloud backend (Sunil Patra)
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Fix initial config “Auth state doesn’t match” message (Nick Craig-Wood)

- **<hotpink>Premiumizeme</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Prune unused functions (Lars Lehtonen)

- **<hotpink>Putio</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Nick Craig-Wood)
  - Make downloading files use the rclone http Client (Nick Craig-Wood)
  - Fix parsing of remotes with leading and trailing `/` (Nick Craig-Wood)

- **<hotpink>Qingstor</hotpink>**
  - Make `rclone cleanup` remove pending multipart uploads older than 24h (Nick Craig-Wood)
  - Try harder to cancel failed multipart uploads (Nick Craig-Wood)
  - Prune `multiUploader.list()` (Lars Lehtonen)
  - Lint fix (Lars Lehtonen)

- **<hotpink>S3</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Use memory pool for buffer allocations (Maciej Zimnoch)
  - Add SSE-C support for AWS, Ceph, and MinIO (Jack Anderson)
  - Fail fast multipart upload (Michał Matczuk)
  - Report errors on bucket creation (<code>mkdir</code>) correctly (Nick Craig-Wood)
  - Specify that Minio supports URL encoding in listings (Nick Craig-Wood)
  - Added 500 as retryErrorCode (Michał Matczuk)
  - Use `--low-level-retries` as the number of SDK retries (Aleksandar Janković)
  - Fix multipart abort context (Aleksandar Jankovic)
  - Replace deprecated `session.New()` with `session.NewSession()` (Lars Lehtonen)
  - Use the provided size parameter when allocating a new memory pool (Joachim Brandon LeBlanc)
  - Use rclone’s low level retries instead of AWS SDK to fix listing retries (Nick Craig-Wood)
  - Ignore directory markers at the root also (Nick Craig-Wood)
  - Use single memory pool (Michał Matczuk)
  - Do not resize buf on put to memBuf (Michał Matczuk)
  - Improve docs for `--s3-disable-checksum` (Nick Craig-Wood)
  - Don’t leak memory or tokens in edge cases for multipart upload (Nick Craig-Wood)

- **<hotpink>Seafile</hotpink>**
  - Implement 2FA (Fred)

- **<hotpink>SFTP</hotpink>**
  - Added `--sftp-pem-key` to support inline key files (calisro)
  - Fix post transfer copies failing with 0 size when using `set_modtime=false` (Nick Craig-Wood)

- **<hotpink>Sharefile</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)

- **<hotpink>Sugarsync</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)

- **<hotpink>Swift</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Nick Craig-Wood)
  - Fix cosmetic issue in error message (Martin Michlmayr)

- **<hotpink>Union</hotpink>**
  - Implement multiple writable remotes (Max Sum)
  - Fix server-side copy (Max Sum)
  - Implement ListR (Max Sum)
  - Enable ListR when upstreams contain local (Max Sum)

- **<hotpink>WebDAV</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)
  - Fix `X-OC-Mtime` header for Transip compatibility (Nick Craig-Wood)
  - Report full and consistent usage with `about` (Yves G)

- **<hotpink>Yandex</hotpink>**
  - Add support for `--header-upload` and `--header-download` (Tim Gallant)

---

## 🎀 v1.51.0 - 2020-02-01 🎀

okay bestie buckle up this one is <rainbow>STACKED</rainbow> 💖

- **<purple>New backends</purple>**
  - Memory (Nick Craig-Wood)
  - Sugarsync (Nick Craig-Wood)

- **<purple>New Features</purple>**
  - Adjust all backends to have `--backend-encoding` parameter (Nick Craig-Wood)
    - this enables the encoding for special characters to be adjusted or disabled
  - Add `--max-duration` flag to control the maximum duration of a transfer session (boosh)
  - Add `--expect-continue-timeout` flag, default `1s` (Nick Craig-Wood)
  - Add `--no-check-dest` flag for copying without testing the destination (Nick Craig-Wood)
  - Implement `--order-by` flag to order transfers (Nick Craig-Wood)
  - accounting
    - Don’t show entries in both transferring and checking (Nick Craig-Wood)
    - Add option to delete stats (Aleksandar Jankovic)
  - build
    - Compress the test builds with gzip (Nick Craig-Wood)
    - Implement a framework for starting test servers during tests (Nick Craig-Wood)
  - cmd: Always print elapsed time to tenth place seconds in progress (Gary Kim)
  - config
    - Add `--password-command` to allow dynamic config password (Damon Permezel)
    - Give config questions default values (Nick Craig-Wood)
    - Check a remote exists when creating a new one (Nick Craig-Wood)
  - copyurl: Add `--stdout` flag to write to stdout (Nick Craig-Wood)
  - dedupe: Implement keep smallest too (Nick Craig-Wood)
  - hashsum: Add flag `--base64` flag (landall)
  - lsf: Speed up on s3/swift/etc by not reading mimetype by default (Nick Craig-Wood)
  - lsjson: Add `--no-mimetype` flag (Nick Craig-Wood)
  - rc: Add methods to turn on blocking and mutex profiling (Nick Craig-Wood)
  - rcd
    - Adding group parameter to stats (Chaitanya)
    - Move webgui apart; option to disable browser (Xiaoxing Ye)
  - serve sftp: Add support for public key with auth proxy (Paul Tinsley)
  - stats: Show deletes in stats and hide zero stats (anuar45)

- **<purple>Bug Fixes</purple>**
  - accounting
    - Fix error counter counting multiple times (Ankur Gupta)
    - Fix error count shown as checks (Cnly)
    - Clear finished transfer in stats-reset (Maciej Zimnoch)
    - Added StatsInfo locking in statsGroups sum function (Michał Matczuk)
  - asyncreader: Fix EOF error (buengese)
  - check: Fix `--one-way` recursing more directories than it needs to (Nick Craig-Wood)
  - chunkedreader: Disable hash calculation for first segment (Nick Craig-Wood)
  - config
    - Do not open browser on headless on drive/gcs/google photos (Xiaoxing Ye)
    - SetValueAndSave ignore error if config section does not exist yet (buengese)
  - cmd: Fix completion with an encrypted config (Danil Semelenov)
  - dbhashsum: Stop it returning UNSUPPORTED on dropbox (Nick Craig-Wood)
  - dedupe: Add missing modes to help string (Nick Craig-Wood)
  - operations
    - Fix dedupe continuing on errors like insufficientFilePersimmon (SezalAgrawal)
    - Clear accounting before low level retry (Maciej Zimnoch)
    - Write debug message when hashes could not be checked (Ole Schütt)
    - Move interface assertion to tests to remove pflag dependency (Nick Craig-Wood)
    - Make NewOverrideObjectInfo public and factor uses (Nick Craig-Wood)
  - proxy: Replace use of bcrypt with sha256 (Nick Craig-Wood)
  - vendor
    - Update `bazil.org/fuse` to fix FreeBSD 12.1 (Nick Craig-Wood)
    - Update `github.com/t3rm1n4l/go-mega` to fix mega “illegal base64 data at input byte 22” (Nick Craig-Wood)
    - Update termbox-go to fix ncdu command on FreeBSD (Kuang-che Wu)
    - Update `t3rm1n4l/go-mega` - fixes mega: couldn’t login: crypto/aes: invalid key size 0 (Nick Craig-Wood)

- **<purple>Mount</purple>**
  - Enable async reads for a 20% speedup (Nick Craig-Wood)
  - Replace use of WriteAt with Write for cache mode >= writes and O_APPEND (Brett Dutro)
  - Make sure we call unmount when exiting (Nick Craig-Wood)
  - Don’t build on go1.10 as bazil/fuse no longer supports it (Nick Craig-Wood)
  - When setting dates discard out of range dates (Nick Craig-Wood)

- **<purple>VFS</purple>**
  - Add a newly created file straight into the directory (Nick Craig-Wood)
  - Only calculate one hash for reads for a speedup (Nick Craig-Wood)
  - Make ReadAt for non cached files work better with non-sequential reads (Nick Craig-Wood)
  - Fix edge cases when reading ModTime from file (Nick Craig-Wood)
  - Make sure existing files opened for write show correct size (Nick Craig-Wood)
  - Don’t cache the path in RW file objects to fix renaming (Nick Craig-Wood)
  - Fix rename of open files when using the VFS cache (Nick Craig-Wood)
  - When renaming files in the cache, rename the cache item in memory too (Nick Craig-Wood)
  - Fix open file renaming on drive when using `--vfs-cache-mode writes` (Nick Craig-Wood)
  - Fix incorrect modtime for mv into mount with `--vfs-cache-modes writes` (Nick Craig-Wood)
  - On rename, rename in cache too if the file exists (Anagh Kumar Baranwal)

- **<purple>Local</purple>**
  - Make source file being updated errors be NoLowLevelRetry errors (Nick Craig-Wood)
  - Fix update of hidden files on Windows (Nick Craig-Wood)

- **<purple>Cache</purple>**
  - Follow move of upstream library `github.com/coreos/bbolt` `github.com/etcd-io/bbolt` (Nick Craig-Wood)
  - Fix fatal error: concurrent map writes (Nick Craig-Wood)

- **<purple>Crypt</purple>**
  - Reorder the filename encryption options (Thomas Eales)
  - Correctly handle trailing dot (buengese)

- **<purple>Chunker</purple>**
  - Reduce length of temporary suffix (Ivan Andreev)

- **<purple>Drive</purple>**
  - Add `--drive-stop-on-upload-limit` flag to stop syncs when upload limit reached (Nick Craig-Wood)
  - Add `--drive-use-shared-date` to use date file was shared instead of modified date (Garry McNulty)
  - Make sure invalid auth for teamdrives always reports an error (Nick Craig-Wood)
  - Fix `--fast-list` when using appDataFolder (Nick Craig-Wood)
  - Use multipart resumable uploads for streaming and uploads in mount (Nick Craig-Wood)
  - Log an ERROR if an incomplete search is returned (Nick Craig-Wood)
  - Hide dangerous config from the configurator (Nick Craig-Wood)

- **<purple>Dropbox</purple>**
  - Treat `insufficient_space` errors as non retriable errors (Nick Craig-Wood)

- **<purple>Jottacloud</purple>**
  - Use new auth method used by official client (buengese)
  - Add URL to generate Login Token to config wizard (Nick Craig-Wood)
  - Add support whitelabel versions (buengese)

- **<purple>Koofr</purple>**
  - Use rclone HTTP client. (jaKa)

- **<purple>Onedrive</purple>**
  - Add `Sites.Read.All` permission (Benjamin Richter)

- ooh and it picks up the `Retry-After` header now, which is a whole vibe ✨ (Motonori IWAMURO)

- **Opendrive** 💜
  - `--opendrive-chunk-size` is implemented, finally (Nick Craig-Wood)

- **S3** 🫶
  - multipart upload got re-implemented to fix the memory issues, no cap (Nick Craig-Wood)
  - added `--s3-copy-cutoff` — that's the size threshold where it switches over to a multipart copy (Nick Craig-Wood)
  - new region dropped: Asia Pacific (Hong Kong) (Outvi V)
  - memory usage when streaming files is lower now since the max stream upload size got reduced (Nick Craig-Wood)
  - added the `--s3-list-chunk` option for bucket listing (Thomas Kriechbaumer)
  - path style bucket access is forced **off** now because AWS is deprecating it (Nick Craig-Wood)
  - it'll use the AWS web identity role provider if one's available (Tennix)
  - added StackPath Object Storage support 🎀 (Dave Koston)
  - fixed the ExpiryWindow value (Aleksandar Jankovic)
  - fixed the DisableChecksum condition (Aleksandar Janković)
  - fixed URL decoding of NextMarker (Nick Craig-Wood)

- **SFTP** 🌸
  - added `--sftp-skip-links` to skip symlinks and non-regular files (Nick Craig-Wood)
  - it retries the creation of the connection now (Sebastian Brandt)
  - fixed the `failed to parse private key file: ssh: not an encrypted key` error (Nick Craig-Wood)
  - files get opened for update as write-only so AWS SFTP interop works (Nick Craig-Wood)

- **Swift** 🦋
  - reserves segments of the dynamic large object when you delete objects in a container that had versioning enabled (Nguyễn Hữu Luân)
  - fixed parsing of X-Object-Manifest (Nick Craig-Wood)
  - updated the OVH API endpoint (unbelauscht)

- **WebDAV** 💖
  - nextcloud only uploads SHA1 checksums now (Nick Craig-Wood)
  - fixed the case of `Bearer` in the Authorization: header so it agrees with the RFC (Nick Craig-Wood)
  - added a Referer header to fix problems with WAFs (Nick Craig-Wood)

---

### v1.50.2 - 2019-11-19 👑

- **Bug Fixes**
  - accounting: fixed a memory leak on retries operations (Nick Craig-Wood)

- **Drive**
  - fixed listing of the root directory with the `drive.files` scope (Nick Craig-Wood)
  - fixed `--drive-root-folder-id` with team/shared drives (Nick Craig-Wood)

---

### v1.50.1 - 2019-11-02 💅

- **Bug Fixes**
  - hash: fixed the hash names for DropboxHash and CRC-32, which had been accidentally changed (Nick Craig-Wood)
  - fshttp: fixed error reporting on tpslimit token bucket errors (Nick Craig-Wood)
  - fshttp: doesn't print token bucket errors when the context is cancelled anymore (Nick Craig-Wood)

- **Local**
  - fixed listings of `.` on Windows (Nick Craig-Wood)

- **Onedrive**
  - fixed DirMove/Move after an Onedrive change (Xiaoxing Ye)

---

### v1.50.0 - 2019-10-26 🌈

- **New backends** 🆕
  - Citrix Sharefile (Nick Craig-Wood)
  - Chunker — an overlay backend that splits files into smaller parts (Ivan Andreev)
  - Mail.ru Cloud (Ivan Andreev)

- **New Features** ✨
  - encodings (Fabian Möller & Nick Craig-Wood)
    - all backends use file name encoding now, so any file name can be written to any backend 💯
    - see the restricted file name docs for more info, plus the local backend docs
    - some file names may look different in rclone if you're using any control characters in names, or unicode FULLWIDTH symbols
  - build
    - updated to use go1.13 for the build (Nick Craig-Wood)
    - support for go1.9 is dropped (Nick Craig-Wood)
    - rclone builds with GitHub actions now (Nick Craig-Wood)
    - python scripts converted to python3 (Nick Craig-Wood)
    - swapped Azure/go-ansiterm for mattn/go-colorable (Nick Craig-Wood)
    - Dockerfile fixes (Matei David)
    - added plugin support for backends and commands (Richard Patel)
  - config
    - uses alternating Red/Green in config so it's way more obvious (Nick Craig-Wood)
  - contrib
    - added a sample DLNA server Docker Compose manifest (pataquets)
    - added a sample WebDAV server Docker Compose manifest (pataquets)
  - copyurl
    - added the `--auto-filename` flag for using the file name from the URL in the destination path (Denis)
  - serve dlna:
    - so many compatibility improvements (Dan Walters)
    - support for external srt subtitles (Dan Walters)
  - rc
    - added the command `core/quit` (Saksham Khanna)

- **Bug Fixes** 🐛
  - sync
    - `--update`/`-u` no longer transfers files that haven't changed (Nick Craig-Wood)
    - frees objects after they come out of the transfer pipe, which saves memory (Nick Craig-Wood)
    - fixed `--files-from` without `--no-traverse` doing a recursive scan (Nick Craig-Wood)
  - operations
    - fixed accounting for server-side copies (Nick Craig-Wood)
    - only displays `All duplicates removed` if the dedupe was successful (Sezal Agrawal)
    - only displays `Deleted X extra copies` if the dedupe was successful (Sezal Agrawal)
  - accounting
    - only allows up to 100 completed transfers in the accounting list, to save memory (Nick Craig-Wood)
    - culls the old time ranges when possible, to save memory (Nick Craig-Wood)
    - fixed a panic due to server-side copy fallback (Ivan Andreev)
    - fixed a memory leak that was noticeable when transferring large numbers of objects (Nick Craig-Wood)
    - fixed the total duration calculation (Nick Craig-Wood)
  - cmd
    - fixed environment variables not setting command line flags (Nick Craig-Wood)
    - autocomplete is compatible with bash's posix mode for macOS now (Danil Semelenov)
    - made `--progress` work in git bash on Windows (Nick Craig-Wood)
    - fixed `compopt: command not found` on autocomplete on macOS (Danil Semelenov)
  - config
    - fixed the setting of non top level flags from environment variables (Nick Craig-Wood)
    - checks config names more carefully and reports errors (Nick Craig-Wood)
    - removed the error: can't use `--size-only` and `--ignore-size` together. (Nick Craig-Wood)
  - filter: prevents mixing options when `--files-from` is in use (Michele Caci)
  - serve sftp: fixed a crash on unsupported operations (e.g. Readlink) (Nick Craig-Wood)

- **Mount** 🏔️
  - allows files of unknown size to be read properly (Nick Craig-Wood)
  - skips tests on `<= 2` CPUs to avoid lockup (Nick Craig-Wood)
  - fixed a panic on File.Open (Nick Craig-Wood)
  - fixed `mount_fusefs: -o timeout=: option not supported` on FreeBSD (Nick Craig-Wood)
  - doesn't pass huge filenames (>4k) to FUSE because it can't cope (Nick Craig-Wood)

- **VFS**
  - added the flag `--vfs-case-insensitive` for windows/macOS mounts (Ivan Andreev)
  - makes objects of unknown size readable through the VFS (Nick Craig-Wood)
  - moved the writeback of dirty data out of the close() method into its own method (FlushWrites) and removed the close() call from Flush() (Brett Dutro)
  - stops empty dirs from disappearing when renamed on bucket-based remotes (Nick Craig-Wood)
  - stops change notify polling from clearing so much of the directory cache (Nick Craig-Wood)

- **Azure Blob**
  - disabled logging to the Windows event log (Nick Craig-Wood)

- **B2**
  - removed the `unverified:` prefix on sha1 to improve interop (e.g. with CyberDuck) (Nick Craig-Wood)

- **Box**
  - added options to get the access token via JWT auth (David)

- **Drive**
  - disables HTTP/2 by default to work around INTERNAL_ERROR problems (Nick Craig-Wood)
  - makes sure the drive root ID is always canonical (Nick Craig-Wood)
  - fixed `--drive-shared-with-me` from the root with `ls` and `--fast-list` (Nick Craig-Wood)
  - fixed ChangeNotify polling for shared drives (Nick Craig-Wood)
  - fixed change notify polling when using appDataFolder (Nick Craig-Wood)

- **Dropbox**
  - makes disallowed filenames errors not retry (Nick Craig-Wood)
  - fixed a nil pointer exception on restricted files (Nick Craig-Wood)

- **Fichier**
  - fixed accessing files > 2GB on 32 bit systems (Nick Craig-Wood)

- **FTP**
  - allows disabling EPSV mode (Jon Fautley)

- **HTTP**
  - HEADs directory entries in parallel to speed things up (Nick Craig-Wood)
  - added `--http-no-head` to stop rclone doing HEAD in listings (Nick Craig-Wood)

- **Putio**
  - added the ability to resume uploads (Cenk Alti)

- **S3**
  - fixed signature v2_auth headers (Anthony Rusdi)
  - fixed encoding for control characters (Nick Craig-Wood)
  - only asks for URL encoded directory listings if we actually need them on Ceph (Nick Craig-Wood)
  - added an option for multipart failure behaviour (Aleksandar Jankovic)
  - support for multipart copy (庄天翼)
  - fixed a nil pointer reference if no metadata was returned for an object (Nick Craig-Wood)

- **SFTP**
  - fixed `--sftp-ask-password` trying to contact the ssh agent (Nick Craig-Wood)
  - fixed hashes of files with backslashes (Nick Craig-Wood)
  - includes more ciphers with `--sftp-use-insecure-cipher` (Carlos Ferreyra)

- **WebDAV**
  - parses and returns the Sharepoint error response (Henning Surmeier)

---

### v1.49.5 - 2019-10-05 🌸

- **Bug Fixes**
  - reverted back to go1.12.x for the v1.49.x builds because go1.13.x was causing issues (Nick Craig-Wood)
  - fixed rpm packages by using master builds of nfpm (Nick Craig-Wood)
  - fixed the macOS build after brew changes (Nick Craig-Wood)

---

### v1.49.4 - 2019-09-29 💀

- **Bug Fixes**
  - cmd/rcd: addressed a ZipSlip vulnerability (Richard Patel)
  - accounting: fixed a file handle leak on errors (Nick Craig-Wood)
  - oauthutil: fixed a security problem when running with two users on the same machine (Nick Craig-Wood)

- **FTP**
  - fixed listing of an empty root returning: `error dir not found` (Nick Craig-Wood)

- **S3**
  - fixed SetModTime on GLACIER/ARCHIVE objects and implemented set/get tier (Nick Craig-Wood)

---

### v1.49.3 - 2019-09-15 ✨

- **Bug Fixes**
  - accounting
    - fixed the total duration calculation (Aleksandar Jankovic)
    - fixed `file already closed` on transfer retries (Nick Craig-Wood)

---

### v1.49.2 - 2019-09-08 🎀

- **New Features**
  - build: added Docker workflow support (Alfonso Montero)

- **Bug Fixes**
  - accounting: fixed locking in Transfer to avoid a deadlock with `--progress` (Nick Craig-Wood)
  - docs: fixed the template argument for `mktemp` in `install.sh` (Cnly)
  - operations: fixed `-u`/`--update` with google photos / files of unknown size (Nick Craig-Wood)
  - rc: fixed docs for `config/create` / `update` / `password` (Nick Craig-Wood)

- **Google Cloud Storage**
  - fixed the need for elevated permissions on SetModTime (Nick Craig-Wood)

---

### v1.49.1 - 2019-08-28 🫶

- **Bug Fixes**

- <mint>**`config`**</mint>: fix generated passwords being stored as empty password (Nick Craig-Wood)

- <mint>**`rcd`**</mint>: added missing parameter for web-gui info logs. (Chaitanya)

- <cyan>**Googlephotos**</cyan> 🦋
  - fix crash on error response (Nick Craig-Wood)

- <cyan>**Onedrive**</cyan> ☁️
  - fix crash on error response (Nick Craig-Wood)

---

## 🌈 v1.49.0 - 2019-08-26 🌈

okay bestie, this one is a *chunky* release, like it ate and left no crumbs 💅

- <hotpink>**New backends**</hotpink> ✨
  - <pink>`1fichier`</pink> (Laura Hausmann)
  - <pink>`Google Photos`</pink> (Nick Craig-Wood)
  - <pink>`Putio`</pink> (Cenk Alti)
  - <pink>`premiumize.me`</pink> (Nick Craig-Wood)

- <hotpink>**New Features**</hotpink> 💖
  - experimental web GUI (Chaitanya Bankanhal) — yes, the whole web ui era starts here
  - implemented `--compare-dest` & `--copy-dest` (yparitcher)
  - implemented `--suffix` *without* `--backup-dir`, for backing up to the current dir (yparitcher)
  - `config reconnect` to re-login (re-run the oauth login) for the backend. (Nick Craig-Wood)
  - `config userinfo` to discover which user you are logged in as. (Nick Craig-Wood)
  - `config disconnect` to disconnect you (log out) from the backend. (Nick Craig-Wood)
  - added `--use-json-log` for JSON logging (justinalin)
  - added context propagation to rclone (Aleksandar Jankovic)
  - reworking internal statistics interfaces so they work with rc jobs (Aleksandar Jankovic)
  - added Higher units for ETA (AbelThar)
  - updated rclone logos to the new design (Andreas Chlupka) 🎀
  - `hash`: added CRC-32 support (Cenk Alti)
  - `help showbackend`: fixed advanced option category when there are no standard options (buengese)
  - `ncdu`: display/copy to Clipboard Current Path (Gary Kim)
  - `operations`:
    - run hashing operations in parallel (Nick Craig-Wood)
    - don't calculate checksums when using `--ignore-checksum` (Nick Craig-Wood)
    - check transfer hashes when using `--size-only` mode (Nick Craig-Wood)
    - disable multi thread copy for local to local copies (Nick Craig-Wood)
    - debug successful hashes as well as failures (Nick Craig-Wood)
  - `rc`
    - add ability to stop async jobs (Aleksandar Jankovic)
    - return current settings if `core/bwlimit` called without parameters (Nick Craig-Wood)
    - Rclone-WebUI integration with rclone (Chaitanya Bankanhal)
    - added command line parameter to control the cross origin resource sharing (CORS) in the rcd. (Security Improvement) (Chaitanya Bankanhal) 🔒
    - add anchor tags to the docs so links are consistent (Nick Craig-Wood)
    - remove `_async` key from input parameters after parsing so later operations won't get confused (buengese)
    - add call to clear stats (Aleksandar Jankovic)
  - `rcd`
    - auto-login for web-gui (Chaitanya Bankanhal)
    - implement `--baseurl` for rcd and web-gui (Chaitanya Bankanhal)
  - `serve dlna`
    - only select interfaces which can multicast for SSDP (Nick Craig-Wood)
    - add more builtin mime types to cover standard audio/video (Nick Craig-Wood)
    - fix missing mime types on Android causing missing videos (Nick Craig-Wood)
  - `serve ftp`
    - refactor to bring into line with other serve commands (Nick Craig-Wood)
    - implement `--auth-proxy` (Nick Craig-Wood)
  - `serve http`: implement `--baseurl` (Nick Craig-Wood)
  - `serve restic`: implement `--baseurl` (Nick Craig-Wood)
  - `serve sftp`
    - implement auth proxy (Nick Craig-Wood)
    - fix detection of whether server is authorized (Nick Craig-Wood)
  - `serve webdav`
    - implement `--baseurl` (Nick Craig-Wood)
    - support `--auth-proxy` (Nick Craig-Wood)

- <hotpink>**Bug Fixes**</hotpink> 🐛
  - make "bad record MAC" a retriable error (Nick Craig-Wood)
  - `copyurl`: fix copying files that return HTTP errors (Nick Craig-Wood)
  - `march`: fix checking sub-directories when using `--no-traverse` (buengese)
  - `rc`
    - fix unmarshalable `http.AuthFn` in options and put in test for marshalability (Nick Craig-Wood)
    - move job expire flags to rc to fix initialization problem (Nick Craig-Wood)
    - fix `--loopback` with `rc/list` and others (Nick Craig-Wood)
  - `rcat`: fix slowdown on systems with multiple hashes (Nick Craig-Wood)
  - `rcd`: fix permissions problems on cache directory with web gui download (Nick Craig-Wood)

- <hotpink>**Mount**</hotpink> 🏔️
  - default `--daemon-timeout` to 15 minutes on macOS and FreeBSD (Nick Craig-Wood)
  - update docs to show mounting from root OK for bucket-based (Nick Craig-Wood)
  - remove nonseekable flag from write files (Nick Craig-Wood)

- <hotpink>**VFS**</hotpink> 🧚
  - make write without cache more efficient (Nick Craig-Wood)
  - fix `--vfs-cache-mode` minimal and writes ignoring cached files (Nick Craig-Wood)

- <hotpink>**Local**</hotpink> 🍓
  - add `--local-case-sensitive` and `--local-case-insensitive` (Nick Craig-Wood)
  - avoid polluting page cache when uploading local files to remote backends (Michał Matczuk)
  - don't calculate any hashes by default (Nick Craig-Wood)
  - `Fadvise` run syscall on a dedicated go routine (Michał Matczuk)

- <hotpink>**Azure Blob**</hotpink>
  - Azure Storage Emulator support (Sandeep)
  - updated config help details to remove connection string references (Sandeep)
  - make all operations work from the root (Nick Craig-Wood)

- <hotpink>**B2**</hotpink>
  - implement link sharing (yparitcher)
  - enable server-side copy to copy between buckets (Nick Craig-Wood)
  - make all operations work from the root (Nick Craig-Wood)

- <hotpink>**Drive**</hotpink>
  - fix server-side copy of big files (Nick Craig-Wood)
  - update API for teamdrive use (Nick Craig-Wood)
  - add error for purge with `--drive-trashed-only` (ginvine)

- <hotpink>**Fichier**</hotpink>
  - make `FolderID` int and adjust related code (buengese)

- <hotpink>**Google Cloud Storage**</hotpink>
  - reduce oauth scope requested as suggested by Google (Nick Craig-Wood)
  - make all operations work from the root (Nick Craig-Wood)

- <hotpink>**HTTP**</hotpink>
  - add `--http-headers` flag for setting arbitrary headers (Nick Craig-Wood)

- <hotpink>**Jottacloud**</hotpink>
  - use new api for retrieving internal username (buengese)
  - refactor configuration and minor cleanup (buengese)

- <hotpink>**Koofr**</hotpink>
  - support setting modification times on Koofr backend. (jaKa)

- <hotpink>**Opendrive**</hotpink>
  - refactor to use existing `lib/rest` facilities for uploads (Nick Craig-Wood)

- <hotpink>**Qingstor**</hotpink>
  - upgrade to v3 SDK and fix listing loop (Nick Craig-Wood)
  - make all operations work from the root (Nick Craig-Wood)

- <hotpink>**S3**</hotpink>
  - add `INTELLIGENT_TIERING` storage class (Matti Niemenmaa)
  - make all operations work from the root (Nick Craig-Wood)

- <hotpink>**SFTP**</hotpink>
  - add missing interface check and fix `About` (Nick Craig-Wood)
  - completely ignore all modtime checks if `SetModTime=false` (Jon Fautley)
  - support md5/sha1 with rsync.net (Nick Craig-Wood)
  - save the md5/sha1 command in use to the config file for efficiency (Nick Craig-Wood)
  - opt-in support for `diffie-hellman-group-exchange-sha256` `diffie-hellman-group-exchange-sha1` (Yi FU)

- <hotpink>**Swift**</hotpink>
  - use `FixRangeOption` to fix 0 length files via the VFS (Nick Craig-Wood)
  - fix upload when using `no_chunk` to return the correct size (Nick Craig-Wood)
  - make all operations work from the root (Nick Craig-Wood)
  - fix segments leak during failed large file uploads. (nguyenhuuluan434)

- <hotpink>**WebDAV**</hotpink>
  - add `--webdav-bearer-token-command` (Nick Craig-Wood)
  - refresh token when it expires with `--webdav-bearer-token-command` (Nick Craig-Wood)
  - add docs for using `bearer_token_command` with oidc-agent (Paul Millar)

---

## 🌸 v1.48.0 - 2019-06-15 🌸

- <hotpink>**New commands**</hotpink> ✨
  - `serve sftp`: serve an rclone remote over SFTP (Nick Craig-Wood)

- <hotpink>**New Features**</hotpink> 💖
  - multi threaded downloads to local storage (Nick Craig-Wood) 🔥
    - controlled with `--multi-thread-cutoff` and `--multi-thread-streams`
  - use `rclone.conf` from rclone executable directory to enable portable use (albertony)
  - allow sync of a file and a directory with the same name (forgems)
    - this is common on bucket-based remotes, e.g. `s3`, `gcs`
  - add `--ignore-case-sync` for forced case insensitivity (garry415)
  - implement `--stats-one-line-date` and `--stats-one-line-date-format` (Peter Berbec)
  - log an ERROR for all commands which exit with non-zero status (Nick Craig-Wood)
  - use go-homedir to read the home directory more reliably (Nick Craig-Wood)
  - enable creating encrypted config through external script invocation (Wojciech Smigielski)
  - `build`: drop support for go1.8 (Nick Craig-Wood)
  - `config`: make config create/update encrypt passwords where necessary (Nick Craig-Wood)
  - `copyurl`: honor `--no-check-certificate` (Stefan Breunig)
  - `install`: Linux skip man pages if no mandb (didil)
  - `lsf`: support showing the Tier of the object (Nick Craig-Wood)
  - `lsjson`
    - added `EncryptedPath` to output (calisro)
    - support showing the Tier of the object (Nick Craig-Wood)
    - add `IsBucket` field for bucket-based remote listing of the root (Nick Craig-Wood)
  - `rc`
    - add `--loopback` flag to run commands directly without a server (Nick Craig-Wood)
    - add `operations/fsinfo`: return information about the remote (Nick Craig-Wood)
    - skip auth for OPTIONS request (Nick Craig-Wood)
    - `cmd/providers`: add `DefaultStr`, `ValueStr` and `Type` fields (Nick Craig-Wood)
    - `jobs`: make job expiry timeouts configurable (Aleksandar Jankovic)
  - `serve dlna` reworked and improved (Dan Walters)
  - `serve ftp`: add `--ftp-public-ip` flag to specify public IP (calistri)
  - `serve restic`: add support for `--private-repos` in serve restic (Florian Apolloner)
  - `serve webdav`: combine `serve webdav` and `serve http` (Gary Kim)
  - `size`: ignore negative sizes when calculating total (Garry McNulty)

- <hotpink>**Bug Fixes**</hotpink> 🐛
  - make move and copy individual files obey `--backup-dir` (Nick Craig-Wood)
  - if `--ignore-checksum` is in effect, don't calculate checksum (Nick Craig-Wood)
  - `moveto`: fix case-insensitive same remote move (Gary Kim)
  - `rc`: fix serving bucket-based objects with `--rc-serve` (Nick Craig-Wood)
  - `serve webdav`: fix `serveDir` not being updated with changes from webdav (Gary Kim)

- <hotpink>**Mount**</hotpink> 🏔️
  - fix poll interval documentation (Animosity022)

- <hotpink>**VFS**</hotpink> 🧚
  - make `WriteAt` for non cached files work with non-sequential writes (Nick Craig-Wood)

- <hotpink>**Local**</hotpink> 🍓

- Only calculate the required hashes for big speedup (Nick Craig-Wood)

- Log errors when listing instead of returning an error (Nick Craig-Wood)

- Fix preallocate warning on Linux with ZFS (Nick Craig-Wood)

- **Crypt** 🎀
  - Make `rclone dedupe` work through crypt (Nick Craig-Wood)
  - Fix wrapping of `ChangeNotify` to decrypt directories properly (Nick Craig-Wood)
  - Support `PublicLink` (`rclone link`) of underlying backend (Nick Craig-Wood)
  - Implement Optional methods `SetTier`, `GetTier` (Nick Craig-Wood)

- **B2** 💅
  - Implement server-side copy (Nick Craig-Wood)
  - Implement `SetModTime` (Nick Craig-Wood)

- **Drive** 🦋
  - Fix move and copy from TeamDrive to GDrive (Fionera)
  - Add notes that cleanup works in the background on drive (Nick Craig-Wood)
  - Add `--drive-server-side-across-configs` to default back to old server-side copy semantics by default (Nick Craig-Wood)
  - Add `--drive-size-as-quota` to show storage quota usage for file size (Garry McNulty)

- **FTP** 🌸
  - Add FTP List timeout (Jeff Quinn)
  - Add FTP over TLS support (Gary Kim)
  - Add `--ftp-no-check-certificate` option for FTPS (Gary Kim)

- **Google Cloud Storage** ☁️
  - Fix upload errors when uploading pre 1970 files (Nick Craig-Wood)

- **Jottacloud** ✨
  - Add support for selecting device and mountpoint. (buengese)

- **Mega** 💖
  - Add cleanup support (Gary Kim)

- **Onedrive** 🫶
  - More accurately check if root is found (Cnly)

- **S3** 🔥
  - Support S3 Accelerated endpoints with `--s3-use-accelerate-endpoint` (Nick Craig-Wood)
  - Add config info for Wasabi's EU Central endpoint (Robert Marko)
  - Make `SetModTime` work for GLACIER while syncing (Philip Harvey)

- **SFTP** 🧚
  - Add About support (Gary Kim)
  - Fix about parsing of `df` results so it can cope with -ve results (Nick Craig-Wood)
  - Send custom client version and debug server version (Nick Craig-Wood)

- **WebDAV** 🌈
  - Retry on `423 Locked` errors (Nick Craig-Wood)

---

## 💜 v1.47.0 - 2019-04-13

- **New backends** 👑
  - Backend for Koofr cloud storage service. (jaKa)

- **New Features** ✨
  - Resume downloads if the reader fails in copy (Nick Craig-Wood)
    - this means rclone will restart transfers if the source has an error
    - this is most useful for downloads or cloud to cloud copies
  - Use `--fast-list` for listing operations where it won't use more memory (Nick Craig-Wood)
    - this should speed up the following operations on remotes which support `ListR`
    - `dedupe`, `serve restic lsf`, `ls`, `lsl`, `lsjson`, `lsd`, `md5sum`, `sha1sum`, `hashsum`, `size`, `delete`, `cat`, `settier`
    - use `--disable ListR` to get old behaviour if required
  - Make `--files-from` traverse the destination unless `--no-traverse` is set (Nick Craig-Wood)
    - this fixes `--files-from` with Google drive and excessive API use in general.
  - Make server-side copy account bytes and obey `--max-transfer` (Nick Craig-Wood)
  - Add `--create-empty-src-dirs` flag and default to not creating empty dirs (ishuah)
  - Add client side TLS/SSL flags `--ca-cert`/`--client-cert`/`--client-key` (Nick Craig-Wood)
  - Implement `--suffix-keep-extension` for use with `--suffix` (Nick Craig-Wood)
  - build:
    - Switch to semver compliant version tags to be go modules compliant (Nick Craig-Wood)
    - Update to use `go1.12.x` for the build (Nick Craig-Wood)
  - serve dlna: Add connection manager service description to improve compatibility (Dan Walters)
  - lsf: Add `e` format to show encrypted names and `o` for original IDs (Nick Craig-Wood)
  - lsjson: Added `--files-only` and `--dirs-only` flags (calistri)
  - rc: Implement `operations/publiclink` the equivalent of `rclone link` (Nick Craig-Wood)

- **Bug Fixes** 🐛
  - accounting: Fix total ETA when `--stats-unit bits` is in effect (Nick Craig-Wood)
  - Bash TAB completion
    - Use private custom func to fix clash between rclone and kubectl (Nick Craig-Wood)
    - Fix for remotes with underscores in their names (Six)
    - Fix completion of remotes (Florian Gamböck)
    - Fix autocompletion of remote paths with spaces (Danil Semelenov)
  - serve dlna: Fix root XML service descriptor (Dan Walters)
  - ncdu: Fix display corruption with Chinese characters (Nick Craig-Wood)
  - Add `SIGTERM` to signals which run the exit handlers on unix (Nick Craig-Wood)
  - rc: Reload filter when the options are set via the rc (Nick Craig-Wood)

- **VFS / Mount** 🌙
  - Fix FreeBSD: Ignore Truncate if called with no readers and already the correct size (Nick Craig-Wood)
  - Read directory and check for a file before mkdir (Nick Craig-Wood)
  - Shorten the locking window for `vfs/refresh` (Nick Craig-Wood)

- **Azure Blob** 💙
  - Enable MD5 checksums when uploading files bigger than the "Cutoff" (Dr.Rx)
  - Fix SAS URL support (Nick Craig-Wood)

- **B2** 💅
  - Allow manual configuration of backblaze downloadUrl (Vince)
  - Ignore `already_hidden` error on remove (Nick Craig-Wood)
  - Ignore malformed `src_last_modified_millis` (Nick Craig-Wood)

- **Drive** 🦋
  - Add `--skip-checksum-gphotos` to ignore incorrect checksums on Google Photos (Nick Craig-Wood)
  - Allow server-side move/copy between different remotes. (Fionera)
  - Add docs on team drives and `--fast-list` eventual consistency (Nestar47)
  - Fix imports of text files (Nick Craig-Wood)
  - Fix range requests on 0 length files (Nick Craig-Wood)
  - Fix creation of duplicates with server-side copy (Nick Craig-Wood)

- **Dropbox** 🍓
  - Retry blank errors to fix long listings (Nick Craig-Wood)

- **FTP** 🌸
  - Add `--ftp-concurrency` to limit maximum number of connections (Nick Craig-Wood)

- **Google Cloud Storage** ☁️
  - Fall back to default application credentials (marcintustin)
  - Allow bucket policy only buckets (Nick Craig-Wood)

- **HTTP** 🌐
  - Add `--http-no-slash` for websites with directories with no slashes (Nick Craig-Wood)
  - Remove duplicates from listings (Nick Craig-Wood)
  - Fix socket leak on 404 errors (Nick Craig-Wood)

- **Jottacloud** ✨
  - Fix token refresh (Sebastian Bünger)
  - Add device registration (Oliver Heyme)

- **Onedrive** 🫶
  - Implement graceful cancel of multipart uploads if rclone is interrupted (Cnly)
  - Always add trailing colon to path when addressing items, (Cnly)
  - Return errors instead of panic for invalid uploads (Fabian Möller)

- **S3** 🔥
  - Add support for "Glacier Deep Archive" storage class (Manu)
  - Update Dreamhost endpoint (Nick Craig-Wood)
  - Note incompatibility with CEPH Jewel (Nick Craig-Wood)

- **SFTP** 🧚
  - Allow custom ssh client config (Alexandru Bumbacea)

- **Swift** 🌊
  - Obey `Retry-After` to enable OVH restore from cold storage (Nick Craig-Wood)
  - Work around token expiry on CEPH (Nick Craig-Wood)

- **WebDAV** 🌈
  - Allow `IsCollection` property to be integer or boolean (Nick Craig-Wood)
  - Fix race when creating directories (Nick Craig-Wood)
  - Fix About/df when reading the available/total returns 0 (Nick Craig-Wood)

---

## 💫 v1.46 - 2019-02-09

- **New backends** 👑
  - Support Alibaba Cloud (Aliyun) OSS via the s3 backend (Nick Craig-Wood)

- **New commands** 🎀
  - serve dlna: serves a remove via DLNA for the local network (nicolov)

- **New Features** ✨
  - copy, move: Restore deprecated `--no-traverse` flag (Nick Craig-Wood)
    - This is useful for when transferring a small number of files into a large destination
  - genautocomplete: Add remote path completion for bash completion (Christopher Peterson & Danil Semelenov)
  - Buffer memory handling reworked to return memory to the OS better (Nick Craig-Wood)
    - Buffer recycling library to replace `sync.Pool`
    - Optionally use memory mapped memory for better memory shrinking
    - Enable with `--use-mmap` if having memory problems - not default yet
  - Parallelise reading of files specified by `--files-from` (Nick Craig-Wood)
  - check: Add stats showing total files matched. (Dario Guzik)
  - Allow rename/delete open files under Windows (Nick Craig-Wood)
  - lsjson: Use exactly the correct number of decimal places in the seconds (Nick Craig-Wood)
  - Add cookie support with cmdline switch `--use-cookies` for all HTTP based remotes (qip)
  - Warn if `--checksum` is set but there are no hashes available (Nick Craig-Wood)
  - Rework rate limiting (pacer) to be more accurate and allow bursting (Nick Craig-Wood)
  - Improve error reporting for too many/few arguments in commands (Nick Craig-Wood)
  - listremotes: Remove `-l` short flag as it conflicts with the new global flag (weetmuts)
  - Make http serving with auth generate INFO messages on auth fail (Nick Craig-Wood)

- **Bug Fixes** 🐛
  - Fix layout of stats (Nick Craig-Wood)
  - Fix `--progress` crash under Windows Jenkins (Nick Craig-Wood)
  - Fix transfer of google/onedrive docs by calling Rcat in Copy when size is -1 (Cnly)
  - copyurl: Fix checking of `--dry-run` (Denis Skovpen)

- **Mount** 🌙
  - Check that mountpoint and local directory to mount don't overlap (Nick Craig-Wood)
  - Fix mount size under 32 bit Windows (Nick Craig-Wood)

- **VFS** 💜
  - Implement renaming of directories for backends without `DirMove` (Nick Craig-Wood)
    - now all backends except b2 support renaming directories
  - Implement `--vfs-cache-max-size` to limit the total size of the cache (Nick Craig-Wood)
  - Add `--dir-perms` and `--file-perms` flags to set default permissions (Nick Craig-Wood)
  - Fix deadlock on concurrent operations on a directory (Nick Craig-Wood)
  - Fix deadlock between `RWFileHandle.close` and `File.Remove` (Nick Craig-Wood)
  - Fix renaming/deleting open files with cache mode "writes" under Windows (Nick Craig-Wood)
  - Fix panic on rename with `--dry-run` set (Nick Craig-Wood)
  - Fix `vfs/refresh` with `recurse=true` needing the `--fast-list` flag

- **Local** 💻
  - Add support for `-l`/`--links` (symbolic link translation) (yair@unicorn)
    - this works by showing links as `link.rclonelink` - see local backend docs for more info
    - this errors if used with `-L`/`--copy-links`

- Fix renaming/deleting files that are open on <cyan>Windows</cyan> <pink>(Nick Craig-Wood)</pink> 🪟

- **Crypt** 🔐
  - Check for maximum length <italic>before</italic> decrypting filename, so the panic stops panicking <pink>(Garry McNulty)</pink>

- **Azure Blob** 🟦
  - Allow building the azureblob backend on *BSD <pink>(themylogin)</pink>
  - Use the rclone HTTP client so `--dump headers`, `--tpslimit`, etc. all actually work <pink>(Nick Craig-Wood)</pink>
  - Use the s3 pacer for 0 delay in non error conditions <pink>(Nick Craig-Wood)</pink>
  - Ignore directory markers <pink>(Nick Craig-Wood)</pink>
  - Stop Mkdir from trying to create containers that already exist <pink>(Nick Craig-Wood)</pink>

- **B2** 💙
  - cleanup: will remove unfinished large files >24hrs old <pink>(Garry McNulty)</pink>
  - For a bucket limited application key, check the bucket name <pink>(Nick Craig-Wood)</pink>
    - before this, rclone would use the authorised bucket regardless of what you put on the command line 😭
  - Added `--b2-disable-checksum` flag <pink>(Wojciech Smigielski)</pink>
    - this enables large files to be uploaded without a SHA-1 hash for speed reasons ⚡

- **Drive** 🚗
  - Set default pacer to `100ms` for `10 tps` <pink>(Nick Craig-Wood)</pink>
    - This fits the Google defaults much better and reduces the 403 errors massively
    - Add `--drive-pacer-min-sleep` and `--drive-pacer-burst` to control the pacer
  - Improve ChangeNotify support for items with multiple parents <pink>(Fabian Möller)</pink>
  - Fix ListR for items with multiple parents — this fixes oddities with `vfs/refresh` <pink>(Fabian Möller)</pink>
  - Fix using `--drive-impersonate` and appfolders <pink>(Nick Craig-Wood)</pink>
  - Fix google docs in `rclone mount` for some (not all) applications <pink>(Nick Craig-Wood)</pink>

- **Dropbox** 📦
  - Retry-After support for the Dropbox backend <pink>(Mathieu Carbou)</pink>

- **FTP** 📡
  - Wait for 60 seconds for a connection to Close then declare it dead <pink>(Nick Craig-Wood)</pink>
    - helps with indefinite hangs on some FTP servers 💀

- **Google Cloud Storage** ☁️
  - Update google cloud storage endpoints <pink>(weetmuts)</pink>

- **HTTP** 🌐
  - Add an example with username and password which is supported but wasn't documented <pink>(Nick Craig-Wood)</pink>
  - Fix backend with `--files-from` and nonexistent files <pink>(Nick Craig-Wood)</pink>

- **Hubic** 🇫🇷
  - Make error message more informative if authentication fails <pink>(Nick Craig-Wood)</pink>

- **Jottacloud** 🎀
  - Resume and deduplication support <pink>(Oliver Heyme)</pink>
  - Use token auth for all API requests — don't store password anymore <pink>(Sebastian Bünger)</pink>
  - Add support for 2-factor authentication <pink>(Sebastian Bünger)</pink>

- **Mega** 🗄️
  - Implement v2 account login which fixes logins for newer Mega accounts <pink>(Nick Craig-Wood)</pink>
  - Return error if an unknown length file is attempted to be uploaded <pink>(Nick Craig-Wood)</pink>
  - Add new error codes for better error reporting <pink>(Nick Craig-Wood)</pink>

- **Onedrive** 🟪
  - Fix broken support for "shared with me" folders <pink>(Alex Chen)</pink>
  - Fix root ID not normalised <pink>(Cnly)</pink>
  - Return `err` instead of panic on unknown-sized uploads <pink>(Cnly)</pink>

- **Qingstor** 🧊
  - Fix go routine leak on multipart upload errors <pink>(Nick Craig-Wood)</pink>
  - Add upload chunk size/concurrency/cutoff control <pink>(Nick Craig-Wood)</pink>
  - Default `--qingstor-upload-concurrency` to `1` to work around bug <pink>(Nick Craig-Wood)</pink>

- **S3** 🪣
  - Implement `--s3-upload-cutoff` for single part uploads below this <pink>(Nick Craig-Wood)</pink>
  - Change `--s3-upload-concurrency` default to `4` to increase performance <pink>(Nick Craig-Wood)</pink>
  - Add `--s3-bucket-acl` to control bucket ACL <pink>(Nick Craig-Wood)</pink>
  - Auto detect region for buckets on operation failure <pink>(Nick Craig-Wood)</pink>
  - Add GLACIER storage class <pink>(William Cocker)</pink>
  - Add Scaleway to s3 documentation <pink>(Rémy Léone)</pink>
  - Add AWS endpoint eu-north-1 <pink>(weetmuts)</pink>

- **SFTP** 🛡️
  - Add support for PEM encrypted private keys <pink>(Fabian Möller)</pink>
  - Add option to force the usage of an ssh-agent <pink>(Fabian Möller)</pink>
  - Perform environment variable expansion on key-file <pink>(Fabian Möller)</pink>
  - Fix rmdir on Windows based servers (e.g. CrushFTP) <pink>(Nick Craig-Wood)</pink>
  - Fix rmdir deleting directory contents on some SFTP servers <pink>(Nick Craig-Wood)</pink>
  - Fix error on dangling symlinks <pink>(Nick Craig-Wood)</pink>

- **Swift** 🕊️
  - Add `--swift-no-chunk` to disable segmented uploads in rcat/mount <pink>(Nick Craig-Wood)</pink>
  - Introduce application credential auth support <pink>(kayrus)</pink>
  - Fix memory usage by slimming Object <pink>(Nick Craig-Wood)</pink>
  - Fix extra requests on upload <pink>(Nick Craig-Wood)</pink>
  - Fix reauth on big files <pink>(Nick Craig-Wood)</pink>

- **Union** 🧬
  - Fix poll-interval not working <pink>(Nick Craig-Wood)</pink>

- **WebDAV** 🕸️
  - Support About which means `rclone mount` will show the correct disk size <pink>(Nick Craig-Wood)</pink>
  - Support MD5 and SHA1 hashes with Owncloud and Nextcloud <pink>(Nick Craig-Wood)</pink>
  - Fail soft on time parsing errors <pink>(Nick Craig-Wood)</pink>
  - Fix infinite loop on failed directory creation <pink>(Nick Craig-Wood)</pink>
  - Fix identification of directories for Bitrix Site Manager <pink>(Nick Craig-Wood)</pink>
  - Fix upload of 0 length files on some servers <pink>(Nick Craig-Wood)</pink>
  - Fix: if MKCOL fails with 423 Locked assume the directory exists <pink>(Nick Craig-Wood)</pink>

---

## 🌟 v1.45 - 2018-11-24 🌟

- **New backends** 🎉
  - The Yandex backend was re-written — see below for details <pink>(Sebastian Bünger)</pink>

- **New commands** 💫
  - rcd: New command just to serve the remote control API <pink>(Nick Craig-Wood)</pink>

- **New Features** ✨
  - The remote control API (rc) was greatly expanded to allow full control over rclone <pink>(Nick Craig-Wood)</pink>
    - sensitive operations require authorization or the `--rc-no-auth` flag
    - `config/*` operations to configure rclone
    - `options/*` for reading/setting command line flags
    - `operations/*` for all low level operations, e.g. copy file, list directory
    - `sync/*` for sync, copy and move
    - `--rc-files` flag to serve files on the rc http server
      - this is for building web native GUIs for rclone
    - Optionally serving objects on the rc http server
    - Ensure rclone fails to start up if the `--rc` port is in use already
    - See the rc docs for more info
  - sync/copy/move
    - Make `--files-from` only read the objects specified and don't scan directories <pink>(Nick Craig-Wood)</pink>
      - This is a huge speed improvement for destinations with lots of files 🚀
  - filter: Add `--ignore-case` flag <pink>(Nick Craig-Wood)</pink>
  - ncdu: Add remove function (the <kbd>d</kbd> key) <pink>(Henning Surmeier)</pink>
  - rc command
    - Add `--json` flag for structured JSON input <pink>(Nick Craig-Wood)</pink>
    - Add `--user` and `--pass` flags and interpret `--rc-user`, `--rc-pass`, `--rc-addr` <pink>(Nick Craig-Wood)</pink>
  - build
    - Require go1.8 or later for compilation <pink>(Nick Craig-Wood)</pink>
    - Enable softfloat on MIPS arch <pink>(Scott Edlund)</pink>
    - Integration test framework revamped with a better report and better retries <pink>(Nick Craig-Wood)</pink>

- **Bug Fixes** 🐛
  - cmd: Make `--progress` update the stats correctly at the end <pink>(Nick Craig-Wood)</pink>
  - config: Create config directory on save if it is missing <pink>(Nick Craig-Wood)</pink>
  - dedupe: Check for existing filename before renaming a dupe file <pink>(ssaqua)</pink>
  - move: Don't create directories with `--dry-run` <pink>(Nick Craig-Wood)</pink>
  - operations: Fix Purge and Rmdirs when dir is not the root <pink>(Nick Craig-Wood)</pink>
  - serve http/webdav/restic: Ensure rclone exits if the port is in use <pink>(Nick Craig-Wood)</pink>

- **Mount** 🗻
  - Make `--volname` work for Windows and macOS <pink>(Nick Craig-Wood)</pink>

- **Azure Blob** 🟦
  - Avoid context deadline exceeded error by setting a large TryTimeout value <pink>(brused27)</pink>
  - Fix erroneous Rmdir error "directory not empty" <pink>(Nick Craig-Wood)</pink>
  - Wait for up to 60s to create a just deleted container <pink>(Nick Craig-Wood)</pink>

- **Dropbox** 📦
  - Add dropbox impersonate support <pink>(Jake Coggiano)</pink>

- **Jottacloud** 🎀
  - Fix bug in `--fast-list` handing of empty folders <pink>(albertony)</pink>

- **Opendrive** 🚙
  - Fix transfer of files with `+` and `&` in <pink>(Nick Craig-Wood)</pink>
  - Fix retries of upload chunks <pink>(Nick Craig-Wood)</pink>

- **S3** 🪣
  - Set ACL for server-side copies to that provided by the user <pink>(Nick Craig-Wood)</pink>
  - Fix `role_arn`, `credential_source`, ... <pink>(Erik Swanson)</pink>
  - Add config info for Wasabi's US-West endpoint <pink>(Henry Ptasinski)</pink>

- **SFTP** 🛡️
  - Ensure file hash checking is really disabled <pink>(Jon Fautley)</pink>

- **Swift** 🕊️
  - Add pacer for retries to make swift more reliable <pink>(Nick Craig-Wood)</pink>

- **WebDAV** 🕸️
  - Add Content-Type to PUT requests <pink>(Nick Craig-Wood)</pink>
  - Fix config parsing so `--webdav-user` and `--webdav-pass` flags work <pink>(Nick Craig-Wood)</pink>
  - Add RFC3339 date format <pink>(Ralf Hemberger)</pink>

- **Yandex** 🌈
  - The yandex backend was re-written <pink>(Sebastian Bünger)</pink>
    - This implements low level retries <pink>(Sebastian Bünger)</pink>
    - Copy, Move, DirMove, PublicLink and About optional interfaces <pink>(Sebastian Bünger)</pink>
    - Improved general error handling <pink>(Sebastian Bünger)</pink>
    - Removed ListR for now due to inconsistent behaviour <pink>(Sebastian Bünger)</pink>

---

## 🌸 v1.44 - 2018-10-15 🌸

- **New commands** 💫
  - serve ftp: Add ftp server <pink>(Antoine GIRARD)</pink>
  - settier: perform storage tier changes on supported remotes <pink>(sandeepkru)</pink>

- **New Features** ✨
  - Reworked command line help
    - Make default help less verbose <pink>(Nick Craig-Wood)</pink>
    - Split flags up into global and backend flags <pink>(Nick Craig-Wood)</pink>
    - Implement specialised help for flags and backends <pink>(Nick Craig-Wood)</pink>
    - Show URL of backend help page when starting config <pink>(Nick Craig-Wood)</pink>
  - stats: Long names now split in center <pink>(Joanna Marek)</pink>
  - Add `--log-format` flag for more control over log output <pink>(dcpu)</pink>
  - rc: Add support for OPTIONS and basic CORS <pink>(frenos)</pink>
  - stats: show FatalErrors and NoRetryErrors in stats <pink>(Cédric Connes)</pink>

- **Bug Fixes** 🐛
  - Fix `-P` not ending with a new line <pink>(Nick Craig-Wood)</pink>
  - config: don't create default config dir when user supplies `--config` <pink>(albertony)</pink>
  - Don't print non-ASCII characters with `--progress` on windows <pink>(Nick Craig-Wood)</pink>
  - Correct logs for excluded items <pink>(ssaqua)</pink>

- **Mount** 🗻
  - Remove EXPERIMENTAL tags <pink>(Nick Craig-Wood)</pink>

- **VFS** 🗂️
  - Fix race condition detected by serve ftp tests <pink>(Nick Craig-Wood)</pink>
  - Add `vfs/poll-interval` rc command <pink>(Fabian Möller)</pink>

- Enable rename for nearly all remotes using server-side Move or Copy (Nick Craig-Wood) 💅

- Reduce directory cache cleared by poll-interval (Fabian Möller)

- Remove EXPERIMENTAL tags (Nick Craig-Wood)

- **Local** 🏠

  - Skip bad symlinks in dir listing with `-L` enabled (Cédric Connes)

  - Preallocate files on Windows to reduce fragmentation (Nick Craig-Wood)

  - Preallocate files on linux with `fallocate(2)` (Nick Craig-Wood)

- **Cache**

  - Add `cache/fetch` rc function (Fabian Möller)

  - Fix worker scale down (Fabian Möller)

  - Improve performance by not sending info requests for cached chunks (dcpu)

  - Fix error return value of `cache/fetch` rc method (Fabian Möller)

  - Documentation fix for `cache-chunk-total-size` (Anagh Kumar Baranwal)

  - Preserve leading `/` in wrapped remote path (Fabian Möller)

  - Add `plex_insecure` option to skip certificate validation (Fabian Möller)

  - Remove entries that no longer exist in the source (dcpu)

- **Crypt** 🔐

  - Preserve leading `/` in wrapped remote path (Fabian Möller)

- **Alias**

  - Fix handling of Windows network paths (Nick Craig-Wood)

- **Azure Blob**

  - Add `--azureblob-list-chunk` parameter (Santiago Rodríguez)

  - Implemented `settier` command support on azureblob remote. (sandeepkru)

  - Work around SDK bug which causes errors for chunk-sized files (Nick Craig-Wood)

- **Box**

  - Implement link sharing. (Sebastian Bünger)

- **Drive**

  - Add `--drive-import-formats` - google docs can now be imported (Fabian Möller)

    - Rewrite mime type and extension handling (Fabian Möller)

    - Add document links (Fabian Möller)

    - Add support for multipart document extensions (Fabian Möller)

    - Add support for apps-script to json export (Fabian Möller)

    - Fix escaped chars in documents during list (Fabian Möller)

  - Add `--drive-v2-download-min-size` a workaround for slow downloads (Fabian Möller)

  - Improve directory notifications in ChangeNotify (Fabian Möller)

  - When listing team drives in config, continue on failure (Nick Craig-Wood)

- **FTP**

  - Add a small pause after failed upload before deleting file (Nick Craig-Wood)

- **Google Cloud Storage**

  - Fix `service_account_file` being ignored (Fabian Möller)

- **Jottacloud**

  - Minor improvement in quota info (omit if unlimited) (albertony)

  - Add `--fast-list` support (albertony)

  - Add permanent delete support: `--jottacloud-hard-delete` (albertony)

  - Add link sharing support (albertony)

  - Fix handling of reserved characters. (Sebastian Bünger)

  - Fix socket leak on `Object.Remove` (Nick Craig-Wood)

- **Onedrive**

  - Rework to support Microsoft Graph (Cnly)

    - NB this will require re-authenticating the remote ⚠️

  - Removed upload cutoff and always do session uploads (Oliver Heyme)

  - Use single-part upload for empty files (Cnly)

  - Fix new fields not saved when editing old config (Alex Chen)

  - Fix sometimes special chars in filenames not replaced (Alex Chen)

  - Ignore OneNote files by default (Alex Chen)

  - Add link sharing support (jackyzy823)

- **S3**

  - Use custom pacer, to retry operations when reasonable (Craig Miskell)

  - Use configured server-side-encryption and storage class options when calling `CopyObject()` (Paul Kohout)

  - Make `--s3-v2-auth` flag (Nick Craig-Wood)

  - Fix v2 auth on files with spaces (Nick Craig-Wood)

- **Union**

  - Implement union backend which reads from multiple backends (Felix Brucker)

  - Implement optional interfaces (Move, DirMove, Copy, etc.) (Nick Craig-Wood)

  - Fix ChangeNotify to support multiple remotes (Fabian Möller)

  - Fix `--backup-dir` on union backend (Nick Craig-Wood)

- **WebDAV**

  - Add another time format (Nick Craig-Wood)

  - Add a small pause after failed upload before deleting file (Nick Craig-Wood)

  - Add workaround for missing mtime (buergi)

  - Sharepoint: Renew cookies after 12hrs (Henning Surmeier)

- **Yandex**

  - Remove redundant nil checks (teresy)

---

# 🎀 v1.43.1 - 2018-09-07 🎀

Point release to fix hubic and azureblob backends. Just a lil glow-up patch bestie 💖

## ✨ Bug Fixes ✨

- `ncdu`: Return error instead of `log.Fatal` in Show (Fabian Möller)

- `cmd`: Fix crash with `--progress` and `--stats 0` (Nick Craig-Wood)

- `docs`: Tidy website display (Anagh Kumar Baranwal)

## Azure Blob:

- Fix multi-part uploads. (sandeepkru)

## Hubic

- Fix uploads (Nick Craig-Wood)

- Retry auth fetching if it fails to make hubic more reliable (Nick Craig-Wood)

---

# 🌈 v1.43 - 2018-09-01 🌈

## 🦋 New backends 🦋

- Jottacloud (Sebastian Bünger)

## 🦋 New commands 🦋

- `copyurl`: copies a URL to a remote (Denis)

## 🦋 New Features 🦋

- Reworked config for backends (Nick Craig-Wood)

  - All backend config can now be supplied by command line, env var or config file 👑

  - Advanced section in the config wizard for the optional items

  - A large step towards rclone backends being usable in other go software

  - Allow on the fly remotes with `:backend:` syntax

- Stats revamp

  - Add `--progress`/`-P` flag to show interactive progress (Nick Craig-Wood)

  - Show the total progress of the sync in the stats (Nick Craig-Wood)

  - Add `--stats-one-line` flag for single line stats (Nick Craig-Wood)

- Added weekday schedule into `--bwlimit` (Mateusz)

- `lsjson`: Add option to show the original object IDs (Fabian Möller)

- `serve webdav`: Make Content-Type without reading the file and add `--etag-hash` (Nick Craig-Wood)

- build

  - Build macOS with native compiler (Nick Craig-Wood)

  - Update to use go1.11 for the build (Nick Craig-Wood)

- rc

  - Added `core/stats` to return the stats (reddi1)

- `version --check`: Prints the current release and beta versions (Nick Craig-Wood)

## ✨ Bug Fixes ✨

- accounting

  - Fix time to completion estimates (Nick Craig-Wood)

  - Fix moving average speed for file stats (Nick Craig-Wood)

- `config`: Fix error reading password from piped input (Nick Craig-Wood)

- `move`: Fix `--delete-empty-src-dirs` flag to delete all empty dirs on move (ishuah)

## Mount

- Implement `--daemon-timeout` flag for OSXFUSE (Nick Craig-Wood)

- Fix `mount --daemon` not working with encrypted config (Alex Chen)

- Clip the number of blocks to `2^32-1` on macOS - fixes borg backup (Nick Craig-Wood)

## VFS

- Enable `vfs-read-chunk-size` by default (Fabian Möller)

- Add the `vfs/refresh` rc command (Fabian Möller)

- Add non recursive mode to `vfs/refresh` rc command (Fabian Möller)

- Try to seek buffer on read only files (Fabian Möller)

## Local

- Fix crash when deprecated `--local-no-unicode-normalization` is supplied (Nick Craig-Wood)

- Fix mkdir error when trying to copy files to the root of a drive on windows (Nick Craig-Wood)

## Cache

- Fix nil pointer deref when using `lsjson` on cached directory (Nick Craig-Wood)

- Fix nil pointer deref for occasional crash on playback (Nick Craig-Wood)

## Crypt

- Fix accounting when checking hashes on upload (Nick Craig-Wood)

## Amazon Cloud Drive

- Make very clear in the docs that rclone has no ACD keys (Nick Craig-Wood)

## Azure Blob

- Add connection string and SAS URL auth (Nick Craig-Wood)

- List the container to see if it exists (Nick Craig-Wood)

- Port new Azure Blob Storage SDK (sandeepkru)

- Added blob tier, tier between Hot, Cool and Archive. (sandeepkru)

- Remove leading `/` from paths (Nick Craig-Wood)

## B2

- Support Application Keys (Nick Craig-Wood)

- Remove leading `/` from paths (Nick Craig-Wood)

## Box

- Fix upload of > 2GB files on 32 bit platforms (Nick Craig-Wood)

- Make `--box-commit-retries` flag defaulting to `100` to fix large uploads (Nick Craig-Wood)

## Drive

- Add `--drive-keep-revision-forever` flag (lewapm)

- Handle gdocs when filtering file names in list (Fabian Möller)

- Support using `--fast-list` for large speedups (Fabian Möller)

## FTP

- Fix `Put mkParentDir failed: 521` for BunnyCDN (Nick Craig-Wood)

## Google Cloud Storage

- Fix index out of range error with `--fast-list` (Nick Craig-Wood)

## Jottacloud

- Fix MD5 error check (Oliver Heyme)

- Handle empty time values (Martin Polden)

- Calculate missing MD5s (Oliver Heyme)

- Docs, fixes and tests for MD5 calculation (Nick Craig-Wood)

- Add optional `MimeTyper` interface. (Sebastian Bünger)

- Implement optional `About` interface (for df support). (Sebastian Bünger)

## Mega

- Wait for events instead of arbitrary sleeping (Nick Craig-Wood)

- Add `--mega-hard-delete` flag (Nick Craig-Wood)

- Fix failed logins with upper case chars in email (Nick Craig-Wood)

## Onedrive

- Shared folder support (Yoni Jah)

- Implement DirMove (Cnly)

- Fix rmdir sometimes deleting directories with contents (Nick Craig-Wood)

## Pcloud

- Delete half uploaded files on upload error (Nick Craig-Wood)

## Qingstor

- Remove leading `/` from paths (Nick Craig-Wood)

## S3

- Fix index out of range error with `--fast-list` (Nick Craig-Wood)

- Add `--s3-force-path-style` (Nick Craig-Wood)

- Add support for KMS Key ID (bsteiss)

- Remove leading `/` from paths (Nick Craig-Wood)

## Swift

- Add `storage_policy` (Ruben Vandamme)

- Make it so just `storage_url` or `auth_token` can be overridden (Nick Craig-Wood)

- Fix server-side copy bug for unusual file names (Nick Craig-Wood)

- Remove leading `/` from paths (Nick Craig-Wood)

## WebDAV

- Ensure we call MKCOL with a URL with a trailing `/` for QNAP interop (Nick Craig-Wood)

- If root ends with `/` then don’t check if it is a file (Nick Craig-Wood)

- Don’t accept redirects when reading metadata (Nick Craig-Wood)

- Add bearer token (Macaroon) support for dCache (Nick Craig-Wood)

- Document dCache and Macaroons (Onno Zweers)

- Sharepoint recursion with different depth (Henning)

- Attempt to remove failed uploads (Nick Craig-Wood)

## Yandex

- Fix listing/deleting files in the root (Nick Craig-Wood)

---

# 💜 v1.42 - 2018-06-16 💜

## 🌸 New backends 🌸

- OpenDrive (Oliver Heyme, Jakub Karlicek, ncw)

- **New commands**

  - `deletefile` command (Filip Bartodziej) 🗑️

- **New Features**

  - `copy`, `move`: copy single files *directly*, no more `--files-from` workaround 🎉
    - which makes them **so** much more efficient, no cap
  - Implement the `--max-transfer` flag so transfers just *stop* at a limit 🛑
    - and exit code **8** is what you get when `--max-transfer` is exceeded
  - `copy`: empty source directories get copied to the destination too (Ishuah Kariuki)
  - `check`: added the `--one-way` flag (Kasper Byrdal Nielsen)
  - Added a `siginfo` handler for macOS so <kbd>Ctrl</kbd>+<kbd>T</kbd> stats actually work (kubatasiemski)
  - `rc`:
    - added `core/gc` to run a garbage collection *on demand* 🧹
    - go profiling is now enabled by default on the `--rc` port
    - errors from the remote now get returned on failure
  - `lsf`:
    - added `--absolute` to slap a leading `/` onto path names
    - added `--csv` for compliant CSV output
    - added the `m` format specifier to show the MimeType
    - implemented the `i` format for showing object ID
  - `lsjson`:
    - `MimeType` now shows up in the output
    - added an `ID` field to the output to show Object ID
  - Added the `--retries-sleep` flag (Benjamin Joseph Dag)
  - Oauth web page and error handling got a lil tidy up (Henning Surmeier)

- **Bug Fixes**

  - Password prompt output with `--log-file` fixed for unix (Filip Bartodziej)
  - `ModifyWindow` now gets calculated each time on the fly, fixing a whole pile of problems (Stefan Breunig)

- **Mount**

  - Only print `File.rename error` if there **actually** is an error (Stefan Breunig)
  - Delay rename when a file has open writers instead of just failing outright (Stefan Breunig)
  - Make sure `atexit` gets run on interrupt
  - macOS enhancements:
    - Made `--noappledouble` and `--noapplexattr`
    - Added the `--volname` flag and strip special chars out of it
    - Made `Get`/`List`/`Set`/`Remove` xattr return `ENOSYS` for efficiency
    - Made `--daemon` work on macOS without CGO

- **VFS**

  - Added `--vfs-read-chunk-size` and `--vfs-read-chunk-size-limit` (Fabian Möller)
  - Fixed `ChangeNotify` for new or changed folders (Fabian Möller)

- **Local**

  - Fixed symlink/junction point directory handling under Windows
    - NB bestie, you **will** need to add `-L` to your command line to copy files with reparse points

- **Cache**

  - Add non cached dirs on notifications (Remus Bunduc)
  - Allow root to be expired from rc (Remus Bunduc)
  - Clean remaining empty folders from the temp upload path (Remus Bunduc)
  - Cache lists using batch writes (Remus Bunduc)
  - Use secure websockets for HTTPS Plex addresses (John Clayton)
  - Reconnect the plex websocket on failures (Remus Bunduc)
  - Fix a panic when running without plex configs (Remus Bunduc)
  - Fix root folder caching (Remus Bunduc)

- **Crypt**

  - Check the encrypted hash of files when uploading, for extra data security 🔐

- **Dropbox**

  - Make Dropbox for business folders accessible using an initial `/` in the path

- **Google Cloud Storage**

  - Low level retry on **all** operations if necessary

- **Google Drive**

  - Added `--drive-acknowledge-abuse` to download flagged files
  - Added `--drive-alternate-export` to fix large doc export
  - Don't attempt to choose Team Drives when using `rclone config create`
  - Fix change list polling with team drives
  - Fix `ChangeNotify` for folders (Fabian Möller)
  - Fix `about` (and `df` on a mount) for team drives

- **Onedrive**

  - Errorhandler for onedrive for business requests (Henning Surmeier)

- **S3**

  - Adjust upload concurrency with `--s3-upload-concurrency` (themylogin)
  - Fix `--s3-chunk-size`, which was always using the minimum 🙈

- **SFTP**

  - Added the `--ssh-path-override` flag (Piotr Oleszczyk)
  - Fix slow downloads for long latency connections

- **Webdav**

  - Added workarounds for `biz.mail.ru`
  - Ignore `Reason-Phrase` in the status line to fix 4shared (Rodrigo)
  - Better error message generation

---

## 🌸 v1.41 - 2018-04-28 🌸

- **New backends**

  - Mega support added 🎀
  - Webdav now supports SharePoint cookie authentication (hensur)

- **New commands**

  - `link`: create a public link to files and folders (Stefan Breunig)
  - `about`: gets quota info from a remote (a-roussos, ncw)
  - `hashsum`: a generic tool for any hash to produce md5sum-like output

- **New Features**

  - `lsd`: added the `-R` flag and fixed and updated docs for all the ls commands
  - `ncdu`: added a "refresh" key — <kbd>Ctrl</kbd>+<kbd>L</kbd> (Keith Goldfarb)
  - `serve restic`: added append-only mode (Steve Kriss)
  - `serve restic`: disallow overwriting files in append-only mode (Alexander Neumann)
  - `serve restic`: print the actual listener address (Matt Holt)
  - `size`: added `--json` flag (Matthew Holt)
  - `sync`: implemented `--ignore-errors` (Mateusz Pabian)
  - `dedupe`: added dedupe largest functionality (Richard Yang)
  - `fs`: extended `SizeSuffix` to include TB and PB for `rclone about`
  - `fs`: added `--dump goroutines` and `--dump openfiles` for debugging
  - `rc`: implemented `core/memstats` to print internal memory usage info
  - `rc`: new call `rc/pid` (Michael P. Dubner)

- **Compile**

  - Dropped support for go1.6

- **Release**

  - Fix `make tarball` (Chih-Hsuan Yen)

- **Bug Fixes**

  - `filter`: fix the `--min-age` and `--max-age` together check
  - `fs`: limit `MaxIdleConns` and `MaxIdleConnsPerHost` in transport
  - `lsd`,`lsf`: make sure all times we output are in local time
  - `rc`: fix setting bwlimit to unlimited
  - `rc`: take note of the `--rc-addr` flag too, as per the docs

- **Mount**

  - Use `About` to return the correct disk total/used/free (e.g. in `df`)
  - Set `--attr-timeout` default to `1s` — fixes:
    - rclone using too much memory
    - rclone not serving files to samba
    - excessive time listing directories
  - Fix `df -i` (upstream fix)

- **VFS**

  - Filter the files `.` and `..` from directory listing
  - Only make the VFS cache if `--vfs-cache-mode` > `Off`

- **Local**

  - Add `--local-no-check-updated` to disable updated file checks
  - Retry remove on Windows sharing violation error

- **Cache**

  - Flush the memory cache after close
  - Purge file data on notification
  - Always forget the parent dir for notifications
  - Integrate with Plex websocket
  - Add `rc cache/stats` (seuffert)
  - Add info log on notification

- **Box**

  - Fix failure reading large directories — parse file/directory size as float

- **Dropbox**

  - Fix crypt+obfuscate on dropbox
  - Fix repeatedly uploading the same files

- **FTP**

  - Work around a strange response from the box FTP server
  - More workarounds for FTP servers to fix `mkParentDir` error
  - Fix no error on listing a nonexistent directory

- **Google Cloud Storage**

  - Add `service_account_credentials` (Matt Holt)
  - Detect bucket presence by listing it — minimises permissions needed
  - Ignore zero length directory markers

- **Google Drive**

  - Add `service_account_credentials` (Matt Holt)
  - Fix directory move leaving a hardlinked directory behind
  - Return proper google errors when Opening files
  - When initialized with a filepath, optional features used the incorrect root path (Stefan Breunig)

- **HTTP**

  - Fix sync for servers which don't return `Content-Length` in `HEAD`

- **Onedrive**

  - Add QuickXorHash support for OneDrive for business
  - Fix socket leak in multipart session upload

- **S3**

  - Look in S3 named profile files for credentials
  - Add `--s3-disable-checksum` to disable checksum uploading (Chris Redekop)
  - Hierarchical configuration support (Giri Badanahatti)
  - Add in config for all the supported S3 providers
  - Add One Zone Infrequent Access storage class (Craig Rachel)
  - Add `--use-server-modtime` support (Peter Baumgartner)
  - Add `--s3-chunk-size` option to control multipart uploads
  - Ignore zero length directory markers

- **SFTP**

  - Update docs to match code, fix typos and clarify the `disable_hashcheck` prompt (Michael G. Noll)
  - Update docs with Synology quirks
  - Fail soft with a debug on hash failure

- **Swift**

  - Add `--use-server-modtime` support (Peter Baumgartner)

- **Webdav**

  - Support SharePoint cookie authentication (hensur)
  - Strip leading and trailing `/` off root

---

## 💜 v1.40 - 2018-03-19 💜

- **New backends**

  - Alias backend, to create aliases for existing remote names (Fabian Möller)

- **New commands**

  - `lsf`: list for parsing purposes (Jakub Tasiemski)
    - by default this is a simple non recursive list of files and directories
    - it can be configured to add more info in an easy to parse way
  - `serve restic`: for serving a remote as a Restic REST endpoint
    - this enables restic to use any backends that rclone can access
    - thanks Alexander Neumann for help, patches and review 🫶
  - `rc`: enable the remote control of a running rclone
    - the running rclone must be started with `--rc` and related flags
    - currently there is support for bwlimit, and flushing for mount and cache

- **New Features**

  - `--max-delete` flag to add a delete threshold (Bjørn Erik Pedersen)
  - All backends now support `RangeOption` for ranged `Open`
    - `cat`: use `RangeOption` for limited fetches to make more efficient
    - `cryptcheck`: make reading of nonce more efficient with `RangeOption`
  - `serve http/webdav/restic`
    - support SSL/TLS
    - add `--user` `--pass` and `--htpasswd` for authentication
  - `copy`/`move`: detect file size change during copy/move and abort transfer (ishuah)
  - `cryptdecode`: added option to return encrypted file names (ishuah)
  - `lsjson`: add `--encrypted` to show encrypted name (Jakub Tasiemski)
  - Add `--stats-file-name-length` to specify the printed file name length for stats (Will Gunn)

- **Compile**

  - Code base was shuffled and factored
    - backends moved into a backend directory
    - large packages split up
    - See the `CONTRIBUTING.md` doc for info as to what lives where now
  - Update to using go1.10 as the default go version
  - Implement daily full integration tests

- **Release**

  - Include a source tarball and sign it and the binaries
  - Sign the git tags as part of the release process
  - Add `.deb` and `.rpm` packages as part of the build
  - Make a beta release for all branches on the main repo (but not pull requests)

- **Bug Fixes**

  - `config`: fixes errors on a nonexistent config by loading the config file only on first access

- **`config`** — retry saving the config after a failure (Mateusz) 💾

- **`sync`** — when you're rolling with `--backup-dir`, don't delete files if we can't set their modtime
  - this fixes the odd behaviour with Dropbox and `--backup-dir`
- **`fshttp`** — fix idle timeouts for HTTP connections
- **`serve http`** — fix serving files with `:` in - fixes
- **Fix `--exclude-if-present`** so it ignores directories it doesn't have permission for (Iakov Davydov) 🔐
- Make accounting work properly with `crypt` and `b2`
- remove `--no-traverse` flag because it is obsolete (bestie it had to go 💀)

### 🖥️ Mount

- Add `--attr-timeout` flag to control attribute caching in the kernel
  - this now defaults to `0` which is correct but less efficient
  - see the mount docs for more info
- Add `--daemon` flag to allow mount to run in the background (ishuah)
- Fix: Return `ENOSYS` rather than `EIO` on attempted link
  - This fixes FileZilla accessing an rclone mount served over sftp.
- Fix setting modtime twice
- Mount tests now run on CI for Linux (mount & cmount)/Mac/Windows
- Many bugs fixed in the VFS layer - see below 👀

### 🗂️ VFS

- Many fixes for `--vfs-cache-mode` writes and above
  - Update cached copy if we know it has changed (fixes stale data)
  - Clean path names before using them in the cache
  - Disable cache cleaner if `--vfs-cache-poll-interval=0`
  - Fill and clean the cache immediately on startup
- Fix Windows opening every file when it stats the file
- Fix applying modtime for an open Write Handle
- Fix creation of files when truncating
- Write 0 bytes when flushing unwritten handles to avoid race conditions in FUSE
- Downgrade "poll-interval is not supported" message to Info
- Make OpenFile and friends return `EINVAL` if `O_RDONLY` and `O_TRUNC`

### 📁 Local

- Downgrade "invalid cross-device link: trying copy" to debug
- Make DirMove return `fs.ErrorCantDirMove` to allow fallback to Copy for cross device
- Fix race conditions updating the hashes

### 🗄️ Cache

- Add support for polling - cache will update when remote changes on supported backends
- Reduce log level for Plex api
- Fix dir cache issue
- Implement `--cache-db-wait-time` flag
- Improve efficiency with RangeOption and RangeSeek
- Fix dirmove with temp fs enabled
- Notify vfs when using temp fs
- Offline uploading
- Remote control support for path flushing

### ☁️ Amazon cloud drive

- Rclone no longer has any working keys - disable integration tests 😭
- Implement DirChangeNotify to notify cache/vfs/mount of changes

### 🟦 Azureblob

- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation
- Improve accounting for chunked uploads

### 🔥 Backblaze B2

- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation

### 📦 Box

- Improve accounting for chunked uploads

### 💧 Dropbox

- Fix custom oauth client parameters

### 🌩️ Google Cloud Storage

- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation

### 🚗 Google Drive

- Migrate to api v3 (Fabian Möller)
- Add scope configuration and root folder selection
- Add `--drive-impersonate` for service accounts
  - thanks to everyone who tested, explored and contributed docs 🫶
- Add `--drive-use-created-date` to use created date as modified date (nbuchanan)
- Request the export formats only when required
  - This makes rclone quicker when there are no google docs
- Fix finding paths with latin1 chars (a workaround for a drive bug)
- Fix copying of a single Google doc file
- Fix `--drive-auth-owner-only` to look in all directories

### 🌐 HTTP

- Fix handling of directories with `&` in

### 🟣 Onedrive

- Removed upload cutoff and always do session uploads
  - this stops the creation of multiple versions on business onedrive
- Overwrite object size value with real size when reading file. (Victor)
  - this fixes oddities when onedrive misreports the size of images

### 🌥️ Pcloud

- Remove unused chunked upload flag and code

### 🧊 Qingstor

- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation

### 🪣 S3

- Support hashes for multipart files (Chris Redekop)
- Initial support for IBM COS (S3) (Giri Badanahatti)
- Update docs to discourage use of v2 auth with CEPH and others
- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation
- Fix server-side copy and set modtime on files with `+` in

### 🔑 SFTP

- Add option to disable remote hash check command execution (Jon Fautley)
- Add `--sftp-ask-password` flag to prompt for password when needed (Leo R. Lundgren)
- Add `set_modtime` configuration option
- Fix following of symlinks
- Fix reading config file outside of Fs setup
- Fix reading `$USER` in username fallback not `$HOME`
- Fix running under crontab - Use correct OS way of reading username

### 🦅 Swift

- Fix refresh of authentication token
  - in v1.39 a bug was introduced which ignored new tokens - this fixes it
- Fix extra HEAD transaction when uploading a new file
- Don't check for bucket/container presence if listing was OK
  - this makes rclone do one less request per invocation

### 🌍 Webdav

- Add new time formats to support mydrive.ch and others

---

## ✨ v1.39 - 2017-12-23 ✨

### 🎀 New backends

- WebDAV
  - tested with nextcloud, owncloud, put.io and others!
- Pcloud
- cache - wraps a cache around other backends (Remus Bunduc)
  - useful in combination with mount
  - **NB** this feature is in beta so use with care ⚠️

### 🛠️ New commands

- serve command with subcommands:
  - serve webdav: this implements a webdav server for any rclone remote.
  - serve http: command to serve a remote over HTTP
- config: add sub commands for full config file management
  - create/delete/dump/edit/file/password/providers/show/update
- touch: to create or update the timestamp of a file (Jakub Tasiemski)

### 💫 New Features

- curl install for rclone (Filip Bartodziej)
- `--stats` now shows percentage, size, rate and ETA in condensed form (Ishuah Kariuki)
- `--exclude-if-present` to exclude a directory if a file is present (Iakov Davydov)
- rmdirs: add `--leave-root` flag (lewapm)
- move: add `--delete-empty-src-dirs` flag to remove dirs after move (Ishuah Kariuki)
- Add `--dump` flag, introduce `--dump requests`, `responses` and remove `--dump-auth`, `--dump-filters`
  - Obscure `X-Auth-Token:` from headers when dumping too
- Document and implement exit codes for different failure modes (Ishuah Kariuki)

### 🧱 Compile

> okay bestie there is literally nothing listed under this one in the original 💀

### 🐛 Bug Fixes

- Retry lots more different types of errors to make multipart transfers more reliable
- Save the config before asking for a token, fixes disappearing oauth config
- Warn the user if `--include` and `--exclude` are used together (Ernest Borowski)
- Fix duplicate files (e.g. on Google drive) causing spurious copies
- Allow trailing and leading whitespace for passwords (Jason Rose)
- ncdu: fix crashes on empty directories
- rcat: fix goroutine leak
- moveto/copyto: Fix to allow copying to the same name

### 🖥️ Mount

- `--vfs-cache mode` to make writes into mounts more reliable.
  - this requires caching files on the disk (see `--cache-dir`)
  - As this is a new feature, use with care ⚠️
- Use sdnotify to signal systemd the mount is ready (Fabian Möller)
- Check if directory is not empty before mounting (Ernest Borowski)

### 📁 Local

- Add error message for cross file system moves
- Fix equality check for times

### 💧 Dropbox

- Rework multipart upload
  - buffer the chunks when uploading large files so they can be retried
  - change default chunk size to 48MB now we are buffering them in memory
  - retry every error after the first chunk is done successfully
- Fix error when renaming directories

### 🦅 Swift

- Fix crash on bad authentication

### 🚗 Google Drive

- Add service account support (Tim Cooijmans)

### 🪣 S3

- Make it work properly with Digital Ocean Spaces (Andrew Starr-Bochicchio)
- Fix crash if a bad listing is received
- Add support for ECS task IAM roles (David Minor)

### 🔥 Backblaze B2

- Fix multipart upload retries
- Fix `--hard-delete` to make it work 100% of the time

### 🦅 Swift

- Allow authentication with storage URL and auth key (Giovanni Pizzi)
- Add new fields for swift configuration to support IBM Bluemix Swift (Pierre Carlson)
- Add `OS_TENANT_ID` and `OS_USER_ID` to config
- Allow configs with user id instead of user name
- Check if swift segments container exists before creating (John Leach)
- Fix memory leak in swift transfers (upstream fix)

### 🔑 SFTP

- Add option to enable the use of aes128-cbc cipher (Jon Fautley)

### ☁️ Amazon cloud drive

- Fix download of large files failing with "Only one auth mechanism allowed"

### 🔒 crypt

- Option to encrypt directory names or leave them intact
- Implement DirChangeNotify (Fabian Möller)

### 🟣 onedrive

- Add option to choose resourceURL during setup of OneDrive Business account if more than one is available for user

---

## ✨ v1.38 - 2017-09-30 ✨

### 🎀 New backends

- Azure Blob Storage (thanks Andrei Dragomir)
- Box
- Onedrive for Business (thanks Oliver Heyme)
- QingStor from QingCloud (thanks wuyu)

### 🛠️ New commands

- rcat - read from standard input and stream upload
- tree - shows a nicely formatted recursive listing
- cryptdecode - decode encrypted file names (thanks ishuah)
- config show - print the config file
- config file - print the config file location

### 💫 New Features

- Empty directories are deleted on sync
- dedupe - implement merging of duplicate directories
- check and cryptcheck made more consistent and use less memory
- cleanup for remaining remotes (thanks ishuah)

- **`--immutable`** — makes sure your files *never* change, periodt (thanks Jacob McNamee 🫶)

- **`--user-agent`** — new option so you can set your own user agent string (thanks Alex McGrath Kraak)

- **`--disable`** — a flag that turns OFF optional features you don't vibe with

- **`--bind`** — picks which local addr to use for outgoing connections, iconic for multi-homed setups

- Support for zsh auto-completion dropped and it ATE (thanks bpicode) ✨

- Stopped normalizing file names, but does a normalized compare over in sync — the way that it still matches up is so real

---

### 🔨 Compile 🔨

- Updated to using <pink>`go1.9`</pink> as the default go version

- <red>Removed the snapd build</red> because maintenance was giving problems 😭

### 🐛 Bug Fixes 🐛

- Improved retriable error detection, which makes multipart uploads better

- Made `check` actually obey `--ignore-size` (yes bestie, it was ignoring it, embarrassing)

- Fixed the bwlimit toggle when it's used together with schedules (thanks cbruegg)

- `config` now ensures that a newly written config is on the same mount

### 📁 Local 📁

- Reverted to **copy** when moving a file across file system boundaries

- `--skip-links` to suppress symlink warnings (thanks Zhiming Wang)

### 🌿 Mount 🌿

- Reuses `rcat` internals so uploads work from *all* remotes 💅

### 💧 Dropbox 💧

- Fixed the `"entry doesn't belong in directory"` error

- Stopped using deprecated API methods (we don't do obsolete in this house)

### ☁️ Swift ☁️

- Fixed server-side copy to an empty container with `--fast-list`

### 🌈 Google Drive 🌈

- Changed the default for `--drive-use-trash` to `true`

### 🪣 S3 🪣

- Set session token when using STS (thanks Girish Ramakrishnan)

- Glacier docs and error messages (thanks Jan Varho)

- Now reads **1000** (not 1024) items in dir listings to fix Wasabi

### 🍓 Backblaze B2 🍓

- Fixed SHA1 mismatch when downloading files that have no SHA1

- Calculates missing hashes on the fly instead of spooling

- `--b2-hard-delete` to permanently delete (not hide) files (thanks John Papandriopoulos)

### 🧊 Hubic 🧊

- Fixed creating containers — you no longer *have* to use the default container 🎉

### ☁️ Swift ☁️

- Can optionally configure from a standard set of OpenStack environment vars

- Added `endpoint_type` config

### 👑 Google Cloud Storage 👑

- Fixed bucket creation so it works with limited permission users

### 🔐 SFTP 🔐

- Implemented connection pooling for multiple ssh connections

- Limits new connections per second

- Added support for MD5 and SHA1 hashes where available (thanks Christian Brüggemann)

### 🌐 HTTP 🌐

- Fixed URL encoding issues

- Fixed directories with `:` in them

- Fixed a panic with URL encoded content 💀

---

## 🌸 v1.37 - 2017-07-22 🌸

### 🎀 New backends 🎀

- <mint>FTP</mint> — thanks to Antonio Messina

- <mint>HTTP</mint> — thanks to Vasiliy Tolstov

### 🎀 New commands 🎀

- `rclone ncdu` — for exploring a remote with a text based user interface. Obsessed.

- `rclone lsjson` — for listing with a machine-readable output

- `rclone dbhashsum` — to show Dropbox style hashes of files (local or Dropbox)

### ✨ New Features ✨

- Implemented the `--fast-list` flag

  - This allows remotes to list recursively if they can

  - This uses less transactions (important if you pay for them 💸)

  - This may or may not be quicker

  - This will use more memory as it has to hold the listing in memory

  - `--old-sync-method` is deprecated — the remaining uses are covered by `--fast-list`

  - This involved a major re-write of all the listing code

- Added `--tpslimit` and `--tpslimit-burst` to limit transactions per second

  - this is useful together with `rclone mount` to limit external apps

- Added `--stats-log-level` so you can see `--stats` without `-v`

- Prints password prompts to stderr — Hraban Luyat

- Warns you about duplicate files when syncing 👀

- Oauth improvements

  - allows `auth_url` and `token_url` to be set in the config file

  - Prints the redirection URI if you're using your own credentials.

- Doesn't `Mkdir` at the start of sync anymore, to save transactions

### 🔨 Compile 🔨

- Updated the build to go1.8.3

- Requires go1.6 for building rclone

- Compiles 386 builds with `"GO386=387"` for maximum compatibility

### 🐛 Bug Fixes 🐛

- Fixed menu selection when there are no remotes

- Config saving reworked so it doesn't kill the file if the disk gets full

- Doesn't delete the remote if the name doesn't change while renaming

- `moveto`, `copyto`: report transfers and checks as per `move` and `copy`

### 📁 Local 📁

- Added the `--local-no-unicode-normalization` flag — Bob Potter

### 🌿 Mount 🌿

- Now supported on Windows using cgofuse and WinFsp — thanks to Bill Zissimopoulos for much help 🫶

- Compares checksums on upload/download via FUSE

- Unmounts when the program ends with SIGINT (<kbd>Ctrl</kbd>+<kbd>C</kbd>) or SIGTERM — Jérôme Vizcaino

- On a read only open of a file, makes the open pending until the first read

- Makes `--read-only` reject modify operations

- Implements ModTime via FUSE for remotes that support it

- Allows modTime to be changed even before all writers are closed

- Fixed a panic on renames

- Fixed a hang on errored upload

### 🔒 Crypt 🔒

- Reports the `name:root` as specified by the user

- Added an "obfuscate" option for filename encryption — Stephen Harris

### 📦 Amazon Drive 📦

- Fixed the initialization order for the token renewer

- Removed revoked credentials, allowed oauth proxy config and updated the docs

### 🍓 B2 🍓

- Reduced the minimum chunk size to 5MB

### 🌈 Drive 🌈

- Added team drive support

- Reduces bandwidth by adding fields for partial responses — Martin Kristensen

- Implemented the `--drive-shared-with-me` flag to view shared with me files — Danny Tsai

- Added `--drive-trashed-only` to read only the files in the trash

- Removed the obsolete `--drive-full-list`

- Added the missing seek to start on retries of chunked uploads

- Fixed stats accounting for upload

- Converts `/` in names to a unicode equivalent (／)

- Polls for Google Drive changes when mounted

### 🟦 OneDrive 🟦

- Fixed the uploading of files with spaces

- Fixed the initialization order for the token renewer

- Displays speeds accurately when uploading — Yoni Jah

- Swapped to using `http://localhost:53682/` as the redirect URL — Michael Ledin

- Retries on the token expired error, resets the upload body on retry — Yoni Jah

### 👑 Google Cloud Storage 👑

- Added the ability to specify location and storage class via config and command line — thanks gdm85

- Creates the container if necessary on server-side copy

- Increased the directory listing chunk to 1000 to increase performance

- Obtains a refresh token for GCS — Steven Lu

### 🟨 Yandex 🟨

- Fixed the name reported in log messages (it was empty 🙈)

- Corrected the error return for listing an empty directory

### 💧 Dropbox 💧

- Rewritten to use the v2 API

  - Now supports ModTime

    - Can only be set by uploading the file again

    - If you uploaded with an old rclone, rclone may upload everything again

    - Use `--size-only` or `--checksum` to avoid this

  - Now supports the Dropbox content hashing scheme

  - Now supports low level retries

### 🪣 S3 🪣

- Works around eventual consistency in bucket creation

- Creates the container if necessary on server-side copy

- Added `us-east-2` (Ohio) and `eu-west-2` (London) S3 regions — Zahiar Ahmed

### ☁️ Swift, Hubic ☁️

- Fixed zero length directory markers showing in the subdirectory listing

  - this caused lots of duplicate transfers

- Fixed paged directory listings

  - this caused duplicate directory errors

- Creates the container if necessary on server-side copy

- Increased the directory listing chunk to 1000 to increase performance

- Makes a sensible error if the user forgets the container

### 🔐 SFTP 🔐

- Added support for using ssh key files

- Fixed under Windows

- Fixed ssh agent on Windows

- Adapted to the latest version of the library — Igor Kharin

---

## 💜 v1.36 - 2017-03-18 💜

### ✨ New Features ✨

- SFTP remote (Jack Schmidt)

- Re-implemented the sync routine to work a directory at a time, reducing memory usage

- Logging revamped to be more in line with rsync — now much quieter ✨ <cyan>`-v`</cyan> only shows transfers ✨ <cyan>`-vv`</cyan> is for full debug ✨ `--syslog` to log to syslog on capable platforms

- Implemented `--backup-dir` and `--suffix`

- Implemented `--track-renames` (initial implementation by Bjørn Erik Pedersen)

- Added time-based bandwidth limits (Lukas Loesche)

- `rclone cryptcheck`: checks the integrity of crypt remotes

- Allow all config file variables and options to be set from environment variables

- Added the `--buffer-size` parameter to control the buffer size for copy

- Made `--delete-after` the default

- Added the `--ignore-checksum` flag (fixed by Hisham Zarka)

- `rclone check`: added the `--download` flag to check all the data, not just hashes

- `rclone cat`: added `--head`, `--tail`, `--offset`, `--count` and `--discard`

- `rclone config`: when choosing from a list, allows the value to be entered too

- `rclone config`: allows rename and copy of remotes

- `rclone obscure`: for generating encrypted passwords for rclone's config (T.C. Ferguson)

- Complies with the XDG Base Directory specification (Dario Giovannetti)

  - this moves the default location of the config file in a backwards compatible way

- Release changes

  - Ubuntu snap support (Dedsec1)

  - Compile with go 1.8

  - MIPS/Linux big and little endian support

### 🐛 Bug Fixes 🐛

- Fixed `copyto` copying things to the wrong place if the destination dir didn't exist

- Fixed parsing of remotes in `moveto` and `copyto`

- Fixed `--delete-before` deleting files on copy

- Fixed `--files-from` with an empty file copying everything 💀

- Fixed sync: doesn't update mod times if `--dry-run` is set

- Fixed MimeType propagation

- Fixed filters to add `**` rules to directory rules

### 📁 Local 📁

- Implemented the `-L`, `--copy-links` flag to allow rclone to follow symlinks

- Opens files in write only mode so rclone can write to an rclone mount

- Fixed unnormalised unicode causing problems reading directories

- Fixed the interaction between the `-x` flag and `--max-depth`

### 🌿 Mount 🌿

- Implemented proper directory handling (mkdir, rmdir, renaming) 👑

- Made include and exclude filters apply to mount

- Implemented read and write async buffers — control them with `--buffer-size`

- Fixed fsync on for directories

- Fixed retry on network failure when reading off crypt

### 🔒 Crypt 🔒

- Added `--crypt-show-mapping` to show the encrypted file mapping

- Fixed the crypt writer getting stuck in a loop

  - > <red>**IMPORTANT**</red> this bug had the potential to cause data corruption when

    - reading data from a network based remote and

- writing to a crypt on Google Drive 💖

- If you're worried about your data, use the `cryptcheck` command to validate it

- If you're syncing two crypt remotes, sync the **unencrypted** remote — trust

---

### 🗂️ Amazon Drive

- Fixed the panics on **Move** (rename) 💀
- Fixed the panic on token expiry

### 🗂️ B2

- Fixed inconsistent listings and `rclone check`
- Fixed uploading empty files with `go1.8`
- Constrained memory usage when doing multipart uploads
- Fixed the upload url not being refreshed properly

### 🗂️ Drive

- Fixed `Rmdir` on directories with trashed files
- Fixed "Ignoring unknown object" when downloading
- Added `--drive-list-chunk`
- Added `--drive-skip-gdocs` (Károly Oláh)

### 🗂️ OneDrive

- Implemented **Move**
- Fixed **Copy**
  - Fixed overwrite detection in **Copy**
  - Fixed `waitForJob` to parse errors correctly
- Used token renewer to stop auth errors on long uploads
- Fixed uploading empty files with `go1.8`

### 🗂️ Google Cloud Storage

- Fixed depth 1 directory listings

### 🗂️ Yandex

- Fixed single level directory listing

### 🗂️ Dropbox

- Normalised the case for single level directory listings
- Fixed depth 1 listing

### 🗂️ S3

- Added `ca-central-1` region (Jon Yergatian)

---

## 🌈 v1.35 - 2017-01-02

### ✨ New Features

- `moveto` and `copyto` commands, so you can pick a destination name on copy/move 👑
- `rmdirs` command — recursively deletes empty directories
- Allow repeated `--include`/`--exclude`/`--filter` options
- Only show transfer stats on commands which actually transfer stuff
  - show stats on any command using the `--stats` flag
- Allow overlapping directories in move when server-side dir move is supported
- Add `--stats-unit` option - thanks Scott McGillivray

### 🐛 Bug Fixes

- Fix the config file being overwritten when two rclone instances are running
- Make `rclone lsd` obey the filters properly
- Fix compilation on `mips`
- Fix not transferring files that don't differ in size
- Fix panic on nil retry/fatal error

### 🪄 Mount

- Retry reads on error - should help with reliability a lot
- Report the modification times for directories from the remote
- Add bandwidth accounting and limiting (fixes `--bwlimit`)
- If `--stats` provided will show stats and which files are transferring
- Support R/W files if truncate is set.
- Implement `statfs` interface so `df` works
- Note that write is now supported on Amazon Drive
- Report number of blocks in a file - thanks Stefan Breunig

### 🔐 Crypt

- Prevent the user pointing crypt at itself 🙈
- Fix failed to authenticate decrypted block errors
  - these will now return the underlying `unexpected EOF` instead

### 🗂️ Amazon Drive

- Add support for server-side move and directory move - thanks Stefan Breunig
- Fix nil pointer deref on size attribute

### 🗂️ B2

- Use new prefix and delimiter parameters in directory listings
  - This makes `--max-depth 1` dir listings as used in mount much faster
- Reauth the account while doing uploads too - should help with token expiry

### 🗂️ Drive

- Make `DirMove` more efficient and complain about moving the root
- Create destination directory on `Move()`

---

## 🌈 v1.34 - 2016-11-06

### ✨ New Features

- Stop single file and `--files-from` operations iterating through the source bucket.
- Stop removing failed upload to cloud storage remotes
- Make `ContentType` be preserved for cloud to cloud copies
- Add support to toggle bandwidth limits via `SIGUSR2` - thanks Marco Paganini
- `rclone check` shows count of hashes that couldn't be checked
- `rclone listremotes` command
- Support `linux/arm64` build - thanks Fredrik Fornwall
- Remove `Authorization:` lines from `--dump-headers` output

### 🐛 Bug Fixes

- Ignore files with control characters in the names
- Fix `rclone move` command
  - Delete src files which already existed in dst
  - Fix deletion of src file when dst file older
- Fix `rclone check` on encrypted file systems
- Make failed uploads not count as "Transferred"
- Make sure high level retries show with `-q`
- Use a vendor directory with `godep` for repeatable builds

### 🪄 rclone mount - FUSE

- Implement FUSE mount options
  - `--no-modtime`, `--debug-fuse`, `--read-only`, `--allow-non-empty`, `--allow-root`, `--allow-other`
  - `--default-permissions`, `--write-back-cache`, `--max-read-ahead`, `--umask`, `--uid`, `--gid`
- Add `--dir-cache-time` to control caching of directory entries
- Implement seek for files opened for read (useful for video players)
  - with `-no-seek` flag to disable
- Fix crash on 32 bit ARM (alignment of 64 bit counter)
- ...and many more internal fixes and improvements!

### 🔐 Crypt

- Don't show encrypted password in configurator to stop confusion

### 🗂️ Amazon Drive

- New wait for upload option `--acd-upload-wait-per-gb`
  - upload timeouts scale by file size and can be disabled
- Add 502 Bad Gateway to list of errors we retry
- Fix overwriting a file with a zero length file
- Fix ACD file size warning limit - thanks Felix Bünemann

### 💻 Local

- Unix: implement `-x`/`--one-file-system` to stay on a single file system
  - thanks Durval Menezes and Luiz Carlos Rumbelsperger Viana
- Windows: ignore the symlink bit on files
- Windows: Ignore directory-based junction points

### 🗂️ B2

- Make sure each upload has at least one upload slot - fixes strange upload stats
- Fix uploads when using crypt
- Fix download of large files (sha1 mismatch)
- Return error when we try to create a bucket which someone else owns
- Update B2 docs with Data usage, and Crypt section - thanks Tomasz Mazur

### 🗂️ S3

- Command line and config file support for
  - Setting/overriding ACL - thanks Radek Šenfeld
  - Setting storage class - thanks Asko Tamm

### 🗂️ Drive

- Make exponential backoff work exactly as per Google specification
- add `.epub`, `.odp` and `.tsv` as export formats.

### 🗂️ Swift

- Don't read metadata for directory marker objects

---

## 🌈 v1.33 - 2016-08-24

### ✨ New Features

- Implement encryption
  - data encrypted in NACL secretbox format
  - with optional file name encryption
- New commands
  - `rclone mount` - implements FUSE mounting of remotes (**EXPERIMENTAL**)
    - works on Linux, FreeBSD and OS X (need testers for the last 2!)
  - `rclone cat` - outputs remote file or files to the terminal
  - `rclone genautocomplete` - command to make a bash completion script for rclone
- Editing a remote using `rclone config` now goes through the wizard
- Compile with go 1.7 - this fixes rclone on macOS Sierra and on 386 processors
- Use cobra for sub commands and docs generation

### 🗂️ drive

- Document how to make your own client_id

### 🗂️ s3

- User-configurable Amazon S3 ACL (thanks Radek Šenfeld)

### 🗂️ b2

- Fix stats accounting for upload - no more jumping to 100% done
- On cleanup delete hide marker if it is the current file
- New B2 API endpoint (thanks Per Cederberg)
- Set maximum backoff to 5 Minutes

### 🗂️ onedrive

- Fix URL escaping in file names - e.g. uploading files with `+` in them.

### 🗂️ amazon cloud drive

- Fix token expiry during large uploads
- Work around 408 REQUEST_TIMEOUT and 504 GATEWAY_TIMEOUT errors

### 💻 local

- Fix filenames with invalid UTF-8 not being uploaded
- Fix problem with some UTF-8 characters on OS X

---

## 🌈 v1.32 - 2016-07-13

### 🗂️ Backblaze B2

- Fix upload of files large files not in root

---

## 🌈 v1.31 - 2016-07-13

### ✨ New Features

- Reduce memory on sync by about 50%
- Implement `--no-traverse` flag to stop copy traversing the destination remote.
  - This can be used to reduce memory usage down to the smallest possible.
  - Useful to copy a small number of files into a large destination folder.
- Implement `cleanup` command for emptying trash / removing old versions of files
  - Currently B2 only
- Single file handling improved
  - Now copied with `--files-from`
  - Automatically sets `--no-traverse` when copying a single file
- Info on using installing with ansible - thanks Stefan Weichinger
- Implement `--no-update-modtime` flag to stop rclone fixing the remote modified times.

### 🐛 Bug Fixes

- Fix `move` command - stop it running for overlapping Fses - this was causing data loss. 😭

### 💻 Local

- Fix incomplete hashes - this was causing problems for B2.

### 🗂️ Amazon Drive

- Rename Amazon Cloud Drive to Amazon Drive - no changes to config file needed.

### 🗂️ Swift

- Add support for non-default project domain - thanks Antonio Messina.

### 🗂️ S3

- Add instructions on how to use rclone with minio.
- Add `ap-northeast-2` (Seoul) and `ap-south-1` (Mumbai) regions.
- Skip setting the modified time for objects > 5GB as it isn't possible.

### 🗂️ Backblaze B2

- Add `--b2-versions` flag so old versions can be listed and retrieved.
- Treat 403 errors (e.g. cap exceeded) as fatal.
- Implement `cleanup` command for deleting old file versions.
- Make error handling compliant with B2 integrations notes.
- Fix handling of token expiry.
- Implement `--b2-test-mode` to set `X-Bz-Test-Mode` header.
- Set cutoff for chunked upload to 200MB as per B2 guidelines.
- Make upload multi-threaded.

### 🗂️ Dropbox

- Don't retry 461 errors.

---

## 🌈 v1.30 - 2016-06-18

### ✨ New Features

- Directory listing code reworked for more features and better error reporting (thanks to Klaus Post for help). This enables
  - Directory include filtering for efficiency
  - `--max-depth` parameter
  - Better error reporting
  - More to come
- Retry more errors
- Add `--ignore-size` flag - for uploading images to onedrive
- Log `-v` output to stdout by default
- Display the transfer stats in more human-readable form
- Make 0 size files specifiable with `--max-size 0b`
- Add `b` suffix so we can specify bytes in `--bwlimit`, `--min-size`, etc.
- Use "password:" instead of "password>" prompt - thanks Klaus Post and Leigh Klotz

### 🐛 Bug Fixes

- Fix retry doing one too many retries

### 💻 Local

- <pink>**Fix problems with OS X and UTF-8 characters**</pink> ✨

- **Amazon Drive** 💜
  - Check a file exists before uploading to help with 408 Conflict errors
  - Reauth on 401 errors - this has been causing a lot of problems
  - Work around spurious 403 errors
  - Restart directory listings on error

- **Google Drive** 🦋
  - Check a file exists before uploading to help with duplicates
  - Fix retry of multipart uploads

- **Backblaze B2** 🎀
  - Implement large file uploading

- **S3** 🌸
  - Add AES256 server-side encryption for - thanks Justin R. Wilson

- **Google Cloud Storage** ☁️
  - Make sure we don't use conflicting content types on upload
  - Add service account support - thanks Michal Witkowski

- **Swift** 🧚
  - Add auth version parameter
  - Add domain option for openstack (v3 auth) - thanks Fabian Ruff

---

### 🌈 v1.29 - 2016-04-18 🌈

- **New Features**
  - Implement `-I`, `--ignore-times` for unconditional upload
  - Improve `dedupe` command
    - Now removes identical copies without asking
    - Now obeys `--dry-run`
    - Implement `--dedupe-mode` for non interactive running
      - `--dedupe-mode interactive` - interactive the default.
      - `--dedupe-mode skip` - removes identical files then skips anything left.
      - `--dedupe-mode first` - removes identical files then keeps the first one.
      - `--dedupe-mode newest` - removes identical files then keeps the newest one.
      - `--dedupe-mode oldest` - removes identical files then keeps the oldest one.
      - `--dedupe-mode rename` - removes identical files then renames the rest to be different.

- **Bug fixes**
  - Make `rclone check` obey the `--size-only` flag.
  - Use `"application/octet-stream"` if discovered mime type is invalid.
  - Fix missing `"quit"` option when there are no remotes.

- **Google Drive** 👑
  - Increase default chunk size to 8 MB - increases upload speed of big files
  - Speed up directory listings and make more reliable
  - Add missing retries for `Move` and `DirMove` - increases reliability
  - Preserve mime type on file update

- **Backblaze B2** 💖
  - Enable mod time syncing
    - This means that B2 will now check modification times
    - It will upload new files to update the modification times
    - (there isn't an API to just set the mod time.)
    - If you want the old behaviour use `--size-only`.
  - Update API to new version
  - Fix parsing of mod time when not in metadata

- **Swift/Hubic**
  - Don't return an `MD5SUM` for static large objects

- **S3**
  - Fix uploading files bigger than 50GB

---

### ⭐ v1.28 - 2016-03-01 ⭐

- **New Features**
  - Configuration file encryption - thanks Klaus Post
  - Improve `rclone config` adding more help and making it easier to understand
  - Implement `-u`/`--update` so creation times can be used on all remotes
  - Implement `--low-level-retries` flag
  - Optionally disable gzip compression on downloads with `--no-gzip-encoding`

- **Bug fixes**
  - Don't make directories if `--dry-run` set
  - Fix and document the `move` command
  - Fix redirecting stderr on unix-like OSes when using `--log-file`
  - Fix `delete` command to wait until all finished - fixes missing deletes.

- **Backblaze B2** 🍓
  - Use one upload URL per go routine fixes more than one upload using auth token
  - Add pacing, retries and reauthentication - fixes token expiry problems
  - Upload without using a temporary file from local (and remotes which support SHA1)
  - Fix reading metadata for all files when it shouldn't have been

- **Drive**
  - Fix listing drive documents at root
  - Disable copy and move for Google docs

- **Swift**
  - Fix uploading of chunked files with non ASCII characters
  - Allow setting of `storage_url` in the config - thanks Xavier Lucas

- **S3**
  - Allow IAM role and credentials from environment variables - thanks Brian Stengaard
  - Allow low privilege users to use S3 (check if directory exists during `Mkdir`) - thanks Jakub Gedeon

- **Amazon Drive**
  - Retry on more things to make directory listings more reliable

---

### 💅 v1.27 - 2016-01-31 💅

- **New Features**
  - Easier headless configuration with `rclone authorize`
  - Add support for multiple hash types - we now check SHA1 as well as MD5 hashes.
  - `delete` command which does obey the filters (unlike `purge`)
  - `dedupe` command to deduplicate a remote. Useful with Google Drive.
  - Add `--ignore-existing` flag to skip all files that exist on destination.
  - Add `--delete-before`, `--delete-during`, `--delete-after` flags.
  - Add `--memprofile` flag to debug memory use.
  - Warn the user about files with same name but different case
  - Make `--include` rules add their implicit exclude `*` at the end of the filter list
  - Deprecate compiling with `go1.3`

- **Amazon Drive**
  - Fix download of files > 10 GB
  - Fix directory traversal ("Next token is expired") for large directory listings
  - Remove 409 conflict from error codes we will retry - stops very long pauses

- **Backblaze B2**
  - SHA1 hashes now checked by rclone core

- **Drive**
  - Add `--drive-auth-owner-only` to only consider files owned by the user - thanks Björn Harrtell
  - Export Google documents

- **Dropbox**
  - Make file exclusion error controllable with `-q`

- **Swift**
  - Fix upload from unprivileged user.

- **S3**
  - Fix updating of mod times of files with `+` in.

- **Local**
  - Add local file system option to disable UNC on Windows.

---

### 🫶 v1.26 - 2016-01-02 🫶

- **New Features**
  - Yandex storage backend - thank you Dmitry Burdeev ("dibu")
  - Implement Backblaze B2 storage backend
  - Add `--min-age` and `--max-age` flags - thank you Adriano Aurélio Meirelles
  - Make `ls`/`lsl`/`md5sum`/`size`/`check` obey includes and excludes

- **Fixes**
  - Fix crash in http logging
  - Upload releases to github too

- **Swift**
  - Fix sync for chunked files

- **OneDrive**
  - Re-enable server-side copy
  - Don't mask HTTP error codes with JSON decode error

- **S3**
  - Fix corrupting Content-Type on mod time update (thanks Joseph Spurrier)

---

### 💀 v1.25 - 2015-11-14 💀

- **New features**
  - Implement Hubic storage system

- **Fixes**
  - Fix deletion of some excluded files without `--delete-excluded`
    - This could have deleted files unexpectedly on sync
    - Always check first with `--dry-run`!

- **Swift**
  - Stop `SetModTime` losing metadata (e.g. `X-Object-Manifest`)
    - This could have caused data loss for files > 5GB in size
  - Use ContentType from Object to avoid lookups in listings

- **OneDrive**
  - disable server-side copy as it seems to be broken at Microsoft

---

### 🎀 v1.24 - 2015-11-07 🎀

- **New features**
  - Add support for Microsoft OneDrive
  - Add `--no-check-certificate` option to disable server certificate verification
  - Add async readahead buffer for faster transfer of big files

- **Fixes**
  - Allow spaces in remotes and check remote names for validity at creation time
  - Allow `` `&' `` and disallow `` `:' `` in Windows filenames.

- **Swift**
  - Ignore directory marker objects where appropriate - allows working with Hubic
  - Don't delete the container if fs wasn't at root

- **S3**
  - Don't delete the bucket if fs wasn't at root

- **Google Cloud Storage**
  - Don't delete the bucket if fs wasn't at root

---

### 🌸 v1.23 - 2015-10-03 🌸

- **New features**
  - Implement `rclone size` for measuring remotes

- **Fixes**
  - Fix headless config for drive and gcs
  - Tell the user they should try again if the webserver method failed
  - Improve output of `--dump-headers`

- **S3**
  - Allow anonymous access to public buckets

- **Swift**
  - Stop chunked operations logging `"Failed to read info: Object Not Found"`
  - Use Content-Length on uploads for extra reliability

---

### 🦋 v1.22 - 2015-09-28 🦋

- Implement rsync like include and exclude flags

- **swift**
  - Support files > 5GB - thanks Sergey Tolmachev

---

### ✨ v1.21 - 2015-09-22 ✨

- **New features**
  - Display individual transfer progress
  - Make `lsl` output times in localtime

- **Fixes**
  - Fix allowing user to override credentials again in Drive, GCS and ACD

- **Amazon Drive**
  - Implement compliant pacing scheme

- **Google Drive**
  - Make directory reads concurrent for increased speed.

---

### 👑 v1.20 - 2015-09-15 👑

- **New features**
  - Amazon Drive support
  - Oauth support redone - fix many bugs and improve usability
    - Use `"golang.org/x/oauth2"` as oauth library of choice
    - Improve oauth usability for smoother initial signup
    - drive, googlecloudstorage: optionally use auto config for the oauth token
  - Implement `--dump-headers` and `--dump-bodies` debug flags
  - Show multiple matched commands if abbreviation too short
  - Implement server-side move where possible

- **local**
  - Always use UNC paths internally on Windows - fixes a lot of bugs

- **dropbox**
  - force use of our custom transport which makes timeouts work

- Thanks to Klaus Post for lots of help with this release

---

### 🔥 v1.19 - 2015-08-28 🔥

- **New features**
  - Server side copies for s3/swift/drive/dropbox/gcs
  - `Move` command - uses server-side copies if it can
  - Implement `--retries` flag - tries 3 times by default
  - Build for plan9/amd64 and solaris/amd64 too

- **Fixes**
  - Make a current version download with a fixed URL for scripting
  - Ignore `rmdir` in limited fs rather than throwing error

- **dropbox**
  - Increase chunk size to improve upload speeds massively
  - Issue an error message when trying to upload bad file name

---

### 💜 v1.18 - 2015-08-17 💜

- **drive**
  - Add `--drive-use-trash` flag so rclone trashes instead of deletes
  - Add `"Forbidden to download"` message for files with no downloadURL

- **dropbox**
  - Remove datastore
    - This was deprecated and it caused a lot of problems
    - Modification times and MD5SUMs no longer stored
  - Fix uploading files > 2GB

- **s3**
  - use official AWS SDK from `github.com/aws/aws-sdk-go`
  - NB will most likely require you to delete and recreate remote
  - enable multipart upload which enables files > 5GB

- tested with Ceph / RadosGW / S3 emulation ✨
  - shoutout forever to Sam Liston and Brian Haymore at the Utah Center for High Performance Computing for sorting us a Ceph test account 🫶

- `misc`
  - errors when reading the config file actually get shown now
  - no more stats spam in quiet mode — thanks Leonid Shalupov 💖
  - added the FAQ
  - fixed freshly created directories not obeying umask
  - Linux installation instructions — thanks Shimon Doodkin

### v1.17 - 2015-06-14

- `dropbox`: case insensitivity issues fixed — thanks Leonid Shalupov 💅

### v1.16 - 2015-06-09

- fixed uploading big files, which had been out here causing timeouts or straight up panics 😭
- no md5sum check after download when you're using `--size-only`

### v1.15 - 2015-06-06

- new `--checksum` flag so transfers only get discarded by MD5SUM — thanks Alex Couper ✨
- `--size-only` implemented: sync on size, not checksum & modtime
- docs expanded and the duplicated info removed
- rclone's limitations with directories, documented 📝
- `dropbox`: docs updated about case insensitivity

### v1.14 - 2015-05-21

- `local`: encoding of non utf-8 file names fixed — this fixes a duplicate file problem
- `drive`: docs about rate limiting
- `google cloud storage`: compile fixed after the API change in `google.golang.org/api/storage/v1`

### v1.13 - 2015-05-10

- documentation revised (especially sync)
- `--timeout` and `--conntimeout` implemented
- `s3`: etags from multipart uploads which aren't md5sums get ignored

### v1.12 - 2015-03-15

- `drive`: chunked upload for files above a certain size
- `drive`: added the `--drive-chunk-size` and `--drive-upload-cutoff` parameters
- `drive`: switch to insert from update when a failed copy deletes the upload
- `core`: duplicate files get logged if they're detected

### v1.11 - 2015-03-04

- `swift`: `region` parameter added
- `drive`: crash on failed to update remote mtime, fixed
- in remote paths, native directory separators now become `/`
- synchronization added to `ls`/`lsl`/`lsd` output to stop corruptions
- all stats/log messages now go to stderr, guaranteed
- `--log-file` flag added to log everything (including panics) to a file
- stats printing can now be disabled with `--stats=0`
- `--bwlimit` implemented to limit data transfer bandwidth

### v1.10 - 2015-02-12

- `s3`: list an unlimited number of items
- no more getting stuck in the configurator 🎀

### v1.09 - 2015-02-07

- `windows`: stop drive letters (e.g. `C:`) getting mixed up with remotes (e.g. `drive:`)
- `local`: directory separators on Windows fixed
- `drive`: rate limit exceeded errors fixed

### v1.08 - 2015-02-04

- `drive`: subdirectory listing fixed so it doesn't list the entire drive 😅
- `drive`: `SetModTime` fixed
- `dropbox`: code adapted to recent library changes

### v1.07 - 2014-12-23

- `google cloud storage`: memory leak fixed

### v1.06 - 2014-12-12

- fixed `"Couldn't find home directory"` on OSX
- `swift`: `tenant` parameter added
- use the new location of the Google API packages

### v1.05 - 2014-08-09

- tests improved, and consequently lots of minor fixes
- `core`: race detected by the go race detector, fixed
- `core`: fixes after running errcheck
- `drive`: reset root directory on `Rmdir` and `Purge`
- `fs`: documented that `Purger` returns an error on an empty directory, tested and fixed
- `google cloud storage`: `ListDir` on subdirectory fixed
- `google cloud storage`: re-read metadata in `SetModTime`
- `s3`: reading metadata made more reliable to work around eventual consistency problems
- `s3`: strip trailing `/` from `ListDir()`
- `swift`: return directories without `/` in `ListDir`

### v1.04 - 2014-07-21

- `google cloud storage`: crash on `Update` fixed

### v1.03 - 2014-07-20

- `swift`, `s3`, `dropbox`: fixed updated files being marked as corrupted
- compiles with go 1.1 again

### v1.02 - 2014-07-19

- Dropbox remote implemented
- Google Cloud Storage remote implemented
- Md5sums and Sizes verified after copies
- times removed from the `ls` command — it lists sizes only now
- added `lsl` — lists times and sizes
- added the `md5sum` command

### v1.01 - 2014-07-04

- `drive`: transfer of big files using up lots of memory, fixed

### v1.00 - 2014-07-03

- `drive`: whole second dates fixed

### v0.99 - 2014-06-26

- `--dry-run` not working, fixed
- compatible with go 1.1

### v0.98 - 2014-05-30

- `s3`: treat missing `Content-Length` as 0 for some ceph installations
- `rclonetest`: added a file with a space in it

### v0.97 - 2014-05-05

- copying of single files implemented
- `s3` & `swift`: support paths inside containers/buckets

### v0.96 - 2014-04-24

- `drive`: fixed multiple files of the same name being created
- `drive`: use `o.Update` and `fs.Put` to optimise transfers
- added version number, `-V` and `--version`

### v0.95 - 2014-03-28

- `rclone.org`: website, docs and graphics
- `drive`: path parsing fixed

### v0.94 - 2014-03-27

- remote format changed one last time (for real this time)
- GNU style flags

### v0.93 - 2014-03-16

- `drive`: store token in config file
- cross compile other versions
- strict permissions set on config file

### v0.92 - 2014-03-15

- config fixes and the `--config` option

### v0.91 - 2014-03-15

- make config file

### v0.90 - 2013-06-27

- project named rclone 👑

### v0.00 - 2012-11-18

- project started 🌱

---

# <rainbow>Bugs and Limitations</rainbow> 💀

## Limitations

### Directory timestamps aren't preserved on some backends

Okay so as of v1.66, rclone supports syncing directory modtimes — *if* the backend supports it. Some backends just don't, bestie. See overview for a complete list. Also, heads up: empty directories are **not** synced by default (you can turn that on with `--create-empty-src-dirs`.)

### Rclone struggles with millions of files in a directory/bucket

Right now rclone loads each directory/bucket entirely into memory before using it. And since each rclone object takes 0.5k-1k of memory, this can take a *very* long time and eat a large amount of memory 😭

Millions of files in a directory tends to occur on bucket-based remotes (e.g. S3 buckets) since those remotes do not segregate subdirectories within the bucket.

### Bucket-based remotes and folders

Bucket-based remotes (e.g. S3/GCS/Swift/B2) do not have a concept of directories. Rclone therefore cannot create directories in them, which means that empty directories on a bucket-based remote will tend to disappear 🫠

Some software creates empty keys ending in `/` as directory markers. Rclone doesn't do this as it potentially creates more objects and costs more. This ability may be added in the future (probably via a flag/option).

## Bugs

Bugs are stored in rclone's GitHub project:

- Reported bugs
- Known issues

# 💖 Frequently Asked Questions 💖

okay bestie, this is the part where everybody slides into the same DMs asking the same stuff, so here's the whole group chat FAQ, all of it, no skips, periodt ✨

---

## 🌸 Do all cloud storage systems support all rclone commands

Yes they do. <green>All</green> the rclone commands (e.g. `sync`, `copy`, etc.) will work on all the remote storage systems. every single one, no gatekeeping 💅

---

## 🌸 Can I copy the config from one machine to another

Sure! Rclone stores all of its config in a <hotpink>single file</hotpink>. If you want to find this file, run `rclone config file` which will tell you where it is. iconic, honestly 🎀

See the remote setup docs for more info.

---

## 🌸 How do I configure rclone on a remote / headless box with no browser?

This has now been documented in its own remote setup page. no browser needed, we got you 🫶

---

## 🌸 Can rclone sync directly from drive to s3

Rclone can sync between two remote cloud storage systems just fine. slay ✨

Note that it effectively <yellow>downloads the file and uploads it again</yellow>, so the node running rclone would need to have <hotpink>lots of bandwidth</hotpink>.

The syncs would be incremental (on a file by file basis).

e.g.

rclone sync --interactive drive:Folder s3:bucket


---

## 🌸 Using rclone from multiple locations at the same time

You can use rclone from multiple places at the same time if you choose <purple>different subdirectory</purple> for the output, e.g.

Server A> rclone sync --interactive /tmp/whatever remote:ServerA Server B> rclone sync --interactive /tmp/whatever remote:ServerB


If you sync to the <red>same directory</red> then you should use `rclone copy` otherwise the two instances of rclone may delete each other's files, e.g.

Server A> rclone copy /tmp/whatever remote:Backup Server B> rclone copy /tmp/whatever remote:Backup


> ⚠️ The file names you upload from Server A and Server B should be <red>different</red> in this case, otherwise some file systems (e.g. Drive) may make duplicates. 🙈

---

## 🌸 Why doesn't rclone support partial transfers / binary diffs like rsync?

Rclone stores each file you transfer as a <hotpink>native object</hotpink> on the remote cloud storage system. This means that you can see the files you upload as expected using alternative access methods (e.g. using the Google Drive web interface). There is a <purple>1:1 mapping</purple> between files on your hard disk and objects created in the cloud storage system. bestie it's a whole vibe of exactness 💖

Cloud storage systems (at least none I've come across yet) <red>don't support partially uploading an object</red>. You can't take an existing object, and change some bytes in the middle of it. nope, not allowed, the vibe check fails 😭

It would be possible to make a sync system which stored binary diffs like rsync does, instead of whole objects, but that would <yellow>break the 1:1 mapping</yellow> of files on your hard disk to objects in the remote cloud storage system.

All the cloud storage systems <green>support partial downloads</green> of content, so it would be possible to make partial downloads work. However to make this work efficiently this would require storing a <purple>significant amount of metadata</purple>, which breaks the desired 1:1 mapping of files to objects.

---

## 🌸 Can rclone do bi-directional sync?

Yes, since rclone `v1.58.0`, bidirectional cloud sync is available. main character behavior fr fr 👑

---

## 🌸 Can I use rclone with an HTTP proxy?

Yes. Rclone will follow the standard environment variables for proxies, similar to cURL and other programs. 💅

In general the variables are called `http_proxy` (for services reached over http) and `https_proxy` (for services reached over https). Most public services will be using https, but you may wish to set both.

The content of the variable is `protocol://server:port`. The `protocol` value is the one used to talk to the proxy server, itself, and is commonly either `http` or `socks5`.

Slightly annoyingly, there is <red>no standard for the name</red>; some applications may use `http_proxy` but another one `HTTP_PROXY`. The Go libraries used by rclone will try <green>both</green> variations, but you may wish to set all possibilities. So, on Linux, you may end up with code similar to

export http_proxy=http://proxyserver:12345 export https_proxy=$http_proxy export HTTP_PROXY=$http_proxy export HTTPS_PROXY=$http_proxy


Note: If the proxy server requires a username and password, then use

export http_proxy=http://username:password@proxyserver:12345 export https_proxy=$http_proxy export HTTP_PROXY=$http_proxy export HTTPS_PROXY=$http_proxy


The `NO_PROXY` allows you to disable the proxy for specific hosts. Hosts must be <hotpink>comma separated</hotpink>, and can contain domains or parts. For instance `"foo.com"` also matches `"bar.foo.com"`.

e.g.

export no_proxy=localhost,127.0.0.0/8,my.host.name export NO_PROXY=$no_proxy


> ⚠️ Note that the FTP backend does <red>not</red> support `ftp_proxy` yet. not yet bestie, be patient 😭

---

## 🌸 Rclone gives x509: failed to load system roots and no roots provided error

This means that rclone can't find the <purple>SSL root certificates</purple>. Likely you are running rclone on a NAS with a cut-down Linux OS, or possibly on Solaris.

Rclone (via the Go runtime) tries to load the root certificates from these places on Linux.

"/etc/ssl/certs/ca-certificates.crt", // Debian/Ubuntu/Gentoo etc. "/etc/pki/tls/certs/ca-bundle.crt", // Fedora/RHEL "/etc/ssl/ca-bundle.pem", // OpenSUSE "/etc/pki/tls/cacert.pem", // OpenELEC


So doing something like this should fix the problem. It also sets the time which is <hotpink>important</hotpink> for SSL to work properly.

mkdir -p /etc/ssl/certs/ curl -o /etc/ssl/certs/ca-certificates.crt https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt ntpclient -s -h pool.ntp.org


The two environment variables `SSL_CERT_FILE` and `SSL_CERT_DIR`, mentioned in the x509 package, provide an <green>additional way</green> to provide the SSL root certificates.

Note that you may need to add the `--insecure` option to the curl command line if it doesn't work without.

curl --insecure -o /etc/ssl/certs/ca-certificates.crt https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt


---

## 🌸 Rclone gives Failed to load config file: function not implemented error

Likely this means that you are running rclone on Linux version <red>not supported</red> by the go runtime, ie earlier than version `2.6.23`. 💀

See the system requirements section in the go install docs for full details.

---

## 🌸 All my uploaded docx/xlsx/pptx files appear as archive/zip

This is caused by uploading these files from a Windows computer which hasn't got the Microsoft Office suite installed. The easiest way to fix is to install the <hotpink>Word viewer</hotpink> and the <hotpink>Microsoft Office Compatibility Pack for Word, Excel, and PowerPoint 2007 and later versions' file formats</hotpink>. yes the name is that long, that's just how it is 🎀

---

## 🌸 tcp lookup some.domain.com no such host

This happens when rclone cannot resolve a domain. Please check that your DNS setup is generally working, e.g.

both should print a long list of possible IP addresses

dig www.googleapis.com # resolve using your default DNS dig www.googleapis.com @8.8.8.8 # resolve with Google's DNS server


If you are using `systemd-resolved` (default on Arch Linux), ensure it is at version `233` or higher. Previous releases contain a <red>bug</red> which causes not all domains to be resolved properly.

The Go resolver decision can be influenced with the `GODEBUG=netdns=...` environment variable. This also allows to resolve certain issues with DNS resolution. On Windows or MacOS systems, try forcing use of the internal Go resolver by setting `GODEBUG=netdns=go` at runtime. On other systems (Linux, *BSD, etc) try forcing use of the system name resolver by setting `GODEBUG=netdns=cgo` (and recompile rclone from source with CGO enabled if necessary). See the name resolution section in the go docs.

---

## 🌸 Failed to start auth webserver on Windows

Error: config failed to refresh token: failed to start auth webserver: listen tcp 127.0.0.1:53682: bind: An attempt was made to access a socket in a way forbidden by its access permissions. ... yyyy/mm/dd hh:mm:ss Fatal error: config failed to refresh token: failed to start auth webserver: listen tcp 127.0.0.1:53682: bind: An attempt was made to access a socket in a way forbidden by its access permissions.


This is sometimes caused by the <purple>Host Network Service</purple> causing issues with opening the port on the host.

A simple solution may be restarting the Host Network Service with eg. Powershell

Restart-Service hns


---

## 🌸 The total size reported in the stats for a sync is wrong and keeps changing

It is likely you have <hotpink>more than 10,000 files</hotpink> that need to be synced. By default, rclone only gets <purple>10,000 files</purple> ahead in a sync so as not to use up too much memory. You can change this default with the `--max-backlog` flag. 🦋

---

## 🌸 Rclone is using too much memory or appears to have a memory leak

Rclone is written in Go which uses a <cyan>garbage collector</cyan>. The default settings for the garbage collector mean that it runs when the heap size has <hotpink>doubled</hotpink>.

However it is possible to tune the garbage collector to use less memory by setting `GOGC` to a lower value, say `export GOGC=20`. This will make the garbage collector work <yellow>harder</yellow>, reducing memory size at the expense of CPU usage.

The most common cause of rclone using lots of memory is a <red>single directory with millions of files</red> in. Rclone has to load this entirely into memory as rclone objects. Each rclone object takes `0.5k-1k` of memory. There is a workaround for this which involves a bit of scripting.

---

## 🌸 Rclone changes fullwidth Unicode punctuation marks in file names

For example: On a Windows system, you have a file with name `Test：1.jpg`, where `：` is the Unicode <purple>fullwidth colon</purple> symbol. When using rclone to copy this to your Google Drive, you will notice that the file gets renamed to `Test:1.jpg`, where `:` is the regular (<hotpink>halfwidth</hotpink>) colon. 😭 the betrayal

The reason for such renames is the way rclone handles different restricted filenames on different cloud storage systems. It tries to avoid ambiguous file names as much and allow moving files between many cloud storage systems transparently, by replacing invalid characters with similar looking Unicode characters when transferring to one storage system, and replacing back again when transferring to a different storage system where the original characters are supported. When the same Unicode characters are intentionally used in file names, this replacement strategy leads to unwanted renames. Read more here.

---

> <pink>okay bestie</pink> bestie, we're in the ✨paperwork era✨ of the manpage. yes it's the license and the credits, and yes we're still gonna do it with <rainbow>full main character energy</rainbow> because rules are rules 💅

# 💖 License 💖

So here's the tea 🍵 — this whole thing is <pink>free software</pink> under the terms of the **MIT license**. That's it, that's the vibe. Wanna read the real thing? Go check the `COPYING` file that's bundled up with the source code 🎀


and then, the whole license, verbatim, no edits, no cap 🫶

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


> 😭 not the ALL CAPS LEGAL SCREAMING stay with me — every single word of that matters, so every single word of it stays. <purple>THE SOFTWARE IS PROVIDED "AS IS"</purple>, no warranty, express or implied, fr fr. Don't come for the authors and copyright holders, they said what they said.

---

# 👑 Authors and contributors 👑

the <hotpink>roll call</hotpink> 🎀 the group chat that built this thing. every name, every address, exactly as written, i am not playing with the details 🔥

## 🌟 Authors

- **Nick Craig-Wood** `nick@craig-wood.com` — the founder, the blueprint, the moment 💅

## 🦋 Contributors

> a lil note that lives right here in the source, kept exactly as-is: <lavender>{{< rem email addresses removed from here need to be added to bin/.ignore-emails to make sure update-authors.py doesn't immediately put them back in again. >}}</lavender>

- **Alex Couper** — `amcouper@gmail.com`
- **Leonid Shalupov** — `leonid@shalupov.com` `shalupov@diverse.org.ru`
- **Shimon Doodkin** — `helpmepro1@gmail.com`
- **Colin Nicholson** — `colin@colinn.com`
- **Klaus Post** — `klauspost@gmail.com`
- **Sergey Tolmachev** — `tolsi.ru@gmail.com`
- **Adriano Aurélio Meirelles** — `adriano@atinge.com`
- **C. Bess** — `cbess@users.noreply.github.com`
- **Dmitry Burdeev** — `dibu28@gmail.com`
- **Joseph Spurrier** — `github@josephspurrier.com`
- **Björn Harrtell** — `bjorn@wololo.org`
- **Xavier Lucas** — `xavier.lucas@corp.ovh.com`
- **Werner Beroux** — `werner@beroux.com`
- **Brian Stengaard** — `brian@stengaard.eu`
- **Jakub Gedeon** — `jgedeon@sofi.com`
- **Jim Tittsler** — `jwt@onjapan.net`
- **Michal Witkowski** — `michal@improbable.io`
- **Fabian Ruff** — `fabian.ruff@sap.com`
- **Leigh Klotz** — `klotz@quixey.com`
- **Romain Lapray** — `lapray.romain@gmail.com`
- **Justin R. Wilson** — `jrw972@gmail.com`
- **Antonio Messina** — `antonio.s.messina@gmail.com`
- **Stefan G. Weichinger** — `office@oops.co.at`
- **Per Cederberg** — `cederberg@gmail.com`
- **Radek Šenfeld** — `rush@logic.cz`
- **Fredrik Fornwall** — `fredrik@fornwall.net`
- **Asko Tamm** — `asko@deekit.net`
- **xor-zz** — `xor@gstocco.com`
- **Tomasz Mazur** — `tmazur90@gmail.com`
- **Marco Paganini** — `paganini@paganini.net`
- **Felix Bünemann** — `buenemann@louis.info`
- **Durval Menezes** — `jmrclone@durval.com`
- **Luiz Carlos Rumbelsperger Viana** — `maxd13_luiz_carlos@hotmail.com`
- **Stefan Breunig** — `stefan-github@yrden.de`
- **Alishan Ladhani** — `ali-l@users.noreply.github.com`
- **0xJAKE** — `0xJAKE@users.noreply.github.com`
- **Thibault Molleman** — `thibaultmol@users.noreply.github.com`
- **Scott McGillivray** — `scott.mcgillivray@gmail.com`
- **Bjørn Erik Pedersen** — `bjorn.erik.pedersen@gmail.com`
- **Lukas Loesche** — `lukas@mesosphere.io`
- **emyarod** — `emyarod@users.noreply.github.com`
- **T.C. Ferguson** — `tcf909@gmail.com`
- **Brandur** — `brandur@mutelight.org`
- **Dario Giovannetti** — `dev@dariogiovannetti.net`
- **Károly Oláh** — `okaresz@aol.com`
- **Jon Yergatian** — `jon@macfanatic.ca`
- **Jack Schmidt** — `github@mowsey.org`
- **Dedsec1** — `Dedsec1@users.noreply.github.com`
- **Hisham Zarka** — `hzarka@gmail.com`
- **Jérôme Vizcaino** — `jerome.vizcaino@gmail.com`
- **Mike Tesch** — `mjt6129@rit.edu`
- **Marvin Watson** — `marvwatson@users.noreply.github.com`
- **Danny Tsai** — `danny8376@gmail.com`
- **Yoni Jah** — `yonjah+git@gmail.com` `yonjah+github@gmail.com`
- **Stephen Harris** — `github@spuddy.org` `sweharris@users.noreply.github.com`
- **Ihor Dvoretskyi** — `ihor.dvoretskyi@gmail.com`
- **Jon Craton** — `jncraton@gmail.com`
- **Hraban Luyat** — `hraban@0brg.net`
- **Michael Ledin** — `mledin89@gmail.com`
- **Martin Kristensen** — `me@azgul.com`
- **Too Much IO** — `toomuchio@users.noreply.github.com`
- **Anisse Astier** — `anisse@astier.eu`
- **Zahiar Ahmed** — `zahiar@live.com`
- **Igor Kharin** — `igorkharin@gmail.com`
- **Bill Zissimopoulos** — `billziss@navimatics.com`
- **Bob Potter** — `bobby.potter@gmail.com`
- **Steven Lu** — `tacticalazn@gmail.com`
- **Sjur Fredriksen** — `sjurtf@ifi.uio.no`
- **Ruwbin** — `hubus12345@gmail.com`
- **Fabian Möller** — `fabianm88@gmail.com` `f.moeller@nynex.de`
- **Edward Q. Bridges** — `github@eqbridges.com`
- **Vasiliy Tolstov** — `v.tolstov@selfip.ru`
- **Harshavardhana** — `harsha@minio.io`
- **sainaen** — `sainaen@gmail.com`
- **gdm85** — `gdm85@users.noreply.github.com`
- **Yaroslav Halchenko** — `debian@onerussian.com`
- **John Papandriopoulos** — `jpap@users.noreply.github.com`
- **Zhiming Wang** — `zmwangx@gmail.com`
- **Andy Pilate** — `cubox@cubox.me`
- **Oliver Heyme** — `olihey@googlemail.com` `olihey@users.noreply.github.com` `de8olihe@lego.com`
- **wuyu** — `wuyu@yunify.com`
- **Andrei Dragomir** — `adragomi@adobe.com`
- **Christian Brüggemann** — `mail@cbruegg.com`
- **Alex McGrath Kraak** — `amkdude@gmail.com`
- **bpicode** — `bjoern.pirnay@googlemail.com`
- **Daniel Jagszent** — `daniel@jagszent.de`
- **Josiah White** — `thegenius2009@gmail.com`
- **Ishuah Kariuki** — `kariuki@ishuah.com` `ishuah91@gmail.com`
- **Jan Varho** — `jan@varho.org`
- **Girish Ramakrishnan** — `girish@cloudron.io`
- **LingMan** — `LingMan@users.noreply.github.com`
- **Jacob McNamee** — `jacobmcnamee@gmail.com`
- **jersou** — `jertux@gmail.com`
- **thierry** — `thierry@substantiel.fr`
- **Simon Leinen** — `simon.leinen@gmail.com` `ubuntu@s3-test.novalocal`
- **Dan Dascalescu** — `ddascalescu+github@gmail.com`
- **Jason Rose** — `jason@jro.io`
- **Andrew Starr-Bochicchio** — `a.starr.b@gmail.com`
- **John Leach** — `john@johnleach.co.uk`
- **Corban Raun** — `craun@instructure.com`
- **Pierre Carlson** — `mpcarl@us.ibm.com`
- **Ernest Borowski** — `er.borowski@gmail.com`
- **Remus Bunduc** — `remus.bunduc@gmail.com`
- **Iakov Davydov** — `iakov.davydov@unil.ch` `dav05.gith@myths.ru`
- **Jakub Tasiemski** — `tasiemski@gmail.com`
- **David Minor** — `dminor@saymedia.com`
- **Tim Cooijmans** — `cooijmans.tim@gmail.com`
- **Laurence** — `liuxy6@gmail.com`
- **Giovanni Pizzi** — `gio.piz@gmail.com`
- **Filip Bartodziej** — `filipbartodziej@gmail.com`
- **Jon Fautley** — `jon@dead.li`
- **lewapm** — `32110057+lewapm@users.noreply.github.com`
- **Yassine Imounachen** — `yassine256@gmail.com`
- **Chris Redekop** — `chris-redekop@users.noreply.github.com` `chris.redekop@gmail.com`
- **Jon Fautley** — `jon@adenoid.appstal.co.uk`
- **Will Gunn** — `WillGunn@users.noreply.github.com`
- **Lucas Bremgartner** — `lucas@bremis.ch`
- **Jody Frankowski** — `jody.frankowski@gmail.com`
- **Andreas Roussos** — `arouss1980@gmail.com`
- **nbuchanan** — `nbuchanan@utah.gov`
- **Durval Menezes** — `rclone@durval.com`
- **Victor** — `vb-github@viblo.se`
- **Mateusz** — `pabian.mateusz@gmail.com`
- **Daniel Loader** — `spicypixel@gmail.com`
- **David0rk** — `davidork@gmail.com`
- **Alexander Neumann** — `alexander@bumpern.de`
- **Giri Badanahatti** — `gbadanahatti@us.ibm.com@Giris-MacBook-Pro.local`
- **Leo R. Lundgren** — `leo@finalresort.org`
- **wolfv** — `wolfv6@users.noreply.github.com`
- **Dave Pedu** — `dave@davepedu.com`
- **Stefan Lindblom** — `lindblom@spotify.com`
- **seuffert** — `oliver@seuffert.biz`
- **gbadanahatti** — `37121690+gbadanahatti@users.noreply.github.com`
- **Keith Goldfarb** — `barkofdelight@gmail.com`
- **Steve Kriss** — `steve@heptio.com`
- **Chih-Hsuan Yen** — `yan12125@gmail.com`
- **Alexander Neumann** — `fd0@users.noreply.github.com`
- **Matt Holt** — `mholt@users.noreply.github.com`
- **Eri Bastos** — `bastos.eri@gmail.com`
- **Michael P. Dubner** — `pywebmail@list.ru`
- **Antoine GIRARD** — `sapk@users.noreply.github.com`
- **Mateusz Piotrowski** — `mpp302@gmail.com`
- **Animosity022** — `animosity22@users.noreply.github.com` `earl.texter@gmail.com`
- **Peter Baumgartner** — `pete@lincolnloop.com`
- **Craig Rachel** — `craig@craigrachel.com`
- **Michael G. Noll** — `miguno@users.noreply.github.com`
- **hensur** — `me@hensur.de`
- **Oliver Heyme** — `de8olihe@lego.com`
- **Richard Yang** — `richard@yenforyang.com`
- **Piotr Oleszczyk** — `piotr.oleszczyk@gmail.com`
- **Rodrigo** — `rodarima@gmail.com`
- **NoLooseEnds** — `NoLooseEnds@users.noreply.github.com`
- **Jakub Karlicek** — `jakub@karlicek.me`
- **John Clayton** — `john@codemonkeylabs.com`
- **Kasper Byrdal Nielsen** — `byrdal76@gmail.com`
- **Benjamin Joseph Dag** — `bjdag1234@users.noreply.github.com`
- **themylogin** — `themylogin@gmail.com`
- **Onno Zweers** — `onno.zweers@surfsara.nl`
- **Jasper Lievisse Adriaanse** — `jasper@humppa.nl`
- **sandeepkru** — `sandeep.ummadi@gmail.com` `sandeepkru@users.noreply.github.com`
- **HerrH** — `atomtigerzoo@users.noreply.github.com`
- **Andrew** — `4030760+sparkyman215@users.noreply.github.com`
- **dan smith** — `XX1011@gmail.com`
- **Oleg Kovalov** — `iamolegkovalov@gmail.com`
- **Ruben Vandamme** — `github-com-00ff86@vandamme.email`
- **Cnly** — `minecnly@gmail.com`
- **Andres Alvarez** — `1671935+kir4h@users.noreply.github.com`
- **reddi1** — `xreddi@gmail.com`
- **Matt Tucker** — `matthewtckr@gmail.com`
- **Sebastian Bünger** — `buengese@gmail.com` `buengese@protonmail.com`
- **Martin Polden** — `mpolden@mpolden.no`
- **Alex Chen** — `Cnly@users.noreply.github.com`
- **Denis** — `deniskovpen@gmail.com`
- **bsteiss** — `35940619+bsteiss@users.noreply.github.com`
- **Cédric Connes** — `cedric.connes@gmail.com`
- **Dr. Tobias Quathamer** — `toddy15@users.noreply.github.com`
- **dcpu** — `42736967+dcpu@users.noreply.github.com`
- **Sheldon Rupp** — `me@shel.io`
- **albertony** — `12441419+albertony@users.noreply.github.com`
- **cron410** — `cron410@gmail.com`
- **Anagh Kumar Baranwal** — `6824881+darthShadow@users.noreply.github.com`
- **Felix Brucker** — `felix@felixbrucker.com`
- **Santiago Rodríguez** — `scollazo@users.noreply.github.com`
- **Craig Miskell** — `craig.miskell@fluxfederation.com`
- **Antoine GIRARD** — `sapk@sapk.fr`
- **Joanna Marek** — `joanna.marek@u2i.com`
- **frenos** — `frenos@users.noreply.github.com`
- **ssaqua** — `ssaqua@users.noreply.github.com`
- **xnaas** — `me@xnaas.info`
- **Frantisek Fuka** — `fuka@fuxoft.cz`
- **Paul Kohout** — `pauljkohout@yahoo.com`
- **dcpu** — `43330287+dcpu@users.noreply.github.com`
- **jackyzy823** — `jackyzy823@gmail.com`
- **David Haguenauer** — `ml@kurokatta.org`
- **teresy** — `hi.teresy@gmail.com`
- **buergi** — `patbuergi@gmx.de`
- **Florian Gamboeck** — `mail@floga.de`
- **Ralf Hemberger** — `10364191+rhemberger@users.noreply.github.com`
- **Scott Edlund** — `sedlund@users.noreply.github.com`
- **Erik Swanson** — `erik@retailnext.net`
- **Jake Coggiano** — `jake@stripe.com`
- **brused27** — `brused27@noemailaddress`
- **Peter Kaminski** — `kaminski@istori.com`

okay bestie we're still in the credits and honestly the list is LONG long 😭 but every single one of these people put in work and we are NOT skipping a soul, periodt. quick vibe check: these are the contributors, emails included, character for character 💖

- **Henry Ptasinski** — `henry@logout.com`
- **Alexander** — `kharkovalexander@gmail.com`
- **Garry McNulty** — `garrmcnu@gmail.com`
- **Mathieu Carbou** — `mathieu.carbou@gmail.com`
- **Mark Otway** — `mark@otway.com`
- **William Cocker** — `37018962+WilliamCocker@users.noreply.github.com`
- **François Leurent** — `131.js@cloudyks.org`
- **Arkadius Stefanski** — `arkste@gmail.com`
- **Jay** — `dev@jaygoel.com`
- **andrea rota** — `a@xelera.eu`
- **nicolov** — `nicolov@users.noreply.github.com`
- **Matt Joiner** — `anacrolix@gmail.com`
- **Dario Guzik** — `dario@guzik.com.ar`
- **qip** — `qip@users.noreply.github.com`
- **yair@unicorn** — `yair@unicorn`
- **Matt Robinson** — `brimstone@the.narro.ws`
- **kayrus** — `kay.diam@gmail.com`
- **Rémy Léone** — `remy.leone@gmail.com`
- **Wojciech Smigielski** — `wojciech.hieronim.smigielski@gmail.com`
- **weetmuts** — `oehrstroem@gmail.com`
- **Jonathan** — `vanillajonathan@users.noreply.github.com`
- **James Carpenter** — `orbsmiv@users.noreply.github.com`
- **Vince** — `vince0villamora@gmail.com`
- **Nestar47** — `47841759+Nestar47@users.noreply.github.com`
- **Six** — `brbsix@gmail.com`
- **Alexandru Bumbacea** — `alexandru.bumbacea@booking.com`
- **calisro** — `robert.calistri@gmail.com`
- **Dr.Rx** — `david.rey@nventive.com`
- **marcintustin** — `marcintustin@users.noreply.github.com`
- **jaKa Močnik** — `jaka@koofr.net` 💅
- **Fionera** — `fionera@fionera.de`
- **Dan Walters** — `dan@walters.io`
- **Danil Semelenov** — `sgtpep@users.noreply.github.com`
- **xopez** — `28950736+xopez@users.noreply.github.com`
- **Ben Boeckel** — `mathstuf@gmail.com`
- **Manu** — `manu@snapdragon.cc`
- **Kyle E. Mitchell** — `kyle@kemitchell.com`
- **Gary Kim** — `gary@garykim.dev`
- **Jon** — `jonathn@github.com`
- **Jeff Quinn** — `jeffrey.quinn@bluevoyant.com`
- **Peter Berbec** — `peter@berbec.com`
- **didil** — `1284255+didil@users.noreply.github.com`
- **id01** — `gaviniboom@gmail.com`
- **Robert Marko** — `robimarko@gmail.com`
- **Philip Harvey** — `32467456+pharveybattelle@users.noreply.github.com`
- **JorisE** — `JorisE@users.noreply.github.com`
- **garry415** — `garry.415@gmail.com`
- **forgems** — `forgems@gmail.com`
- **Florian Apolloner** — `florian@apolloner.eu`
- **Aleksandar Janković** — `office@ajankovic.com`, `ajankovic@users.noreply.github.com`
- **Maran** — `maran@protonmail.com`
- **nguyenhuuluan434** — `nguyenhuuluan434@gmail.com`
- **Laura Hausmann** — `zotan@zotan.pw`, `laura@hausmann.dev`
- **yparitcher** — `y@paritcher.com`
- **AbelThar** — `abela.tharen@gmail.com`
- **Matti Niemenmaa** — `matti.niemenmaa+git@iki.fi`
- **Russell Davis** — `russelldavis@users.noreply.github.com`
- **Yi FU** — `yi.fu@tink.se`
- **Paul Millar** — `paul.millar@desy.de`
- **justinalin** — `justinalin@qnap.com`
- **EliEron** — `subanimehd@gmail.com`
- **justina777** — `chiahuei.lin@gmail.com`
- **Chaitanya Bankanhal** — `bchaitanya15@gmail.com`
- **Michał Matczuk** — `michal@scylladb.com`
- **Macavirus** — `macavirus@zoho.com`
- **Abhinav Sharma** — `abhi18av@outlook.com`
- **ginvine** — `34869051+ginvine@users.noreply.github.com`
- **Patrick Wang** — `mail6543210@yahoo.com.tw`
- **Cenk Alti** — `cenkalti@gmail.com`
- **Andreas Chlupka** — `andy@chlupka.com`
- **Alfonso Montero** — `amontero@tinet.org`
- **Ivan Andreev** — `ivandeex@gmail.com`
- **David Baumgold** — `david@davidbaumgold.com`
- **Lars Lehtonen** — `lars.lehtonen@gmail.com`
- **Matei David** — `matei.david@gmail.com`
- **David** — `david.bramwell@endemolshine.com`
- **Anthony Rusdi** — `33247310+antrusd@users.noreply.github.com`
- **Richard Patel** — `me@terorie.dev`
- **庄天翼** — `zty0826@gmail.com`
- **SwitchJS** — `dev@switchjs.com`
- **Raphael** — `PowershellNinja@users.noreply.github.com`
- **Sezal Agrawal** — `sezalagrawal@gmail.com`
- **Tyler** — `TylerNakamura@users.noreply.github.com`
- **Brett Dutro** — `brett.dutro@gmail.com`
- **Vighnesh SK** — `booterror99@gmail.com`
- **Arijit Biswas** — `dibbyo456@gmail.com`
- **Michele Caci** — `michele.caci@gmail.com`
- **AlexandrBoltris** — `ua2fgb@gmail.com`
- **Bryce Larson** — `blarson@saltstack.com`
- **Carlos Ferreyra** — `crypticmind@gmail.com`
- **Saksham Khanna** — `sakshamkhanna@outlook.com`
- **dausruddin** — `5763466+dausruddin@users.noreply.github.com`
- **zero-24** — `zero-24@users.noreply.github.com`
- **Xiaoxing Ye** — `ye@xiaoxing.us`
- **Barry Muldrey** — `barry@muldrey.net`
- **Sebastian Brandt** — `sebastian.brandt@friday.de`
- **Marco Molteni** — `marco.molteni@mailbox.org`
- **Ankur Gupta** — `7876747+ankur0493@users.noreply.github.com`
- **Maciej Zimnoch** — `maciej@scylladb.com`
- **anuar45** — `serdaliyev.anuar@gmail.com`
- **Fernando** — `ferferga@users.noreply.github.com` 🦋
- **David Cole** — `david.cole@sohonet.com`
- **Wei He** — `git@weispot.com`
- **Outvi V** — `19144373+outloudvi@users.noreply.github.com`
- **Thomas Kriechbaumer** — `thomas@kriechbaumer.name`
- **Tennix** — `tennix@users.noreply.github.com`
- **Ole Schütt** — `ole@schuett.name`
- **Kuang-che Wu** — `kcwu@csie.org`
- **Thomas Eales** — `wingsuit@users.noreply.github.com`
- **Paul Tinsley** — `paul.tinsley@vitalsource.com`
- **Felix Hungenberg** — `git@shiftgeist.com`
- **Benjamin Richter** — `github@dev.telepath.de`
- **landall** — `cst_zf@qq.com`
- **thestigma** — `thestigma@gmail.com`
- **jtagcat** — `38327267+jtagcat@users.noreply.github.com`
- **Damon Permezel** — `permezel@me.com`
- **boosh** — `boosh@users.noreply.github.com`
- **unbelauscht** — `58393353+unbelauscht@users.noreply.github.com`
- **Motonori IWAMURO** — `vmi@nifty.com`
- **Benjapol Worakan** — `benwrk@live.com`
- **Dave Koston** — `dave.koston@stackpath.com`
- **Durval Menezes** — `DurvalMenezes@users.noreply.github.com`
- **Tim Gallant** — `me@timgallant.us`
- **Frederick Zhang** — `frederick888@tsundere.moe`
- **valery1707** — `valery1707@gmail.com`
- **Yves G** — `theYinYeti@yalis.fr`
- **Shing Kit Chan** — `chanshingkit@gmail.com`
- **Franklyn Tackitt** — `franklyn@tackitt.net`
- **Robert-André Mauchin** — `zebob.m@gmail.com`
- **evileye** — `48332831+ibiruai@users.noreply.github.com`
- **Joachim Brandon LeBlanc** — `brandon@leblanc.codes`
- **Patryk Jakuszew** — `patryk.jakuszew@gmail.com`
- **fishbullet** — `shindu666@gmail.com`
- **greatroar** — `<@>`
- **Bernd Schoolmann** — `mail@quexten.com`
- **Elan Ruusamäe** — `glen@pld-linux.org`
- **Max Sum** — `max@lolyculture.com`
- **Mark Spieth** — `mspieth@users.noreply.github.com`
- **harry** — `me@harry.plus`
- **Samantha McVey** — `samantham@posteo.net`
- **Jack Anderson** — `jack.anderson@metaswitch.com`
- **Michael G** — `draget@speciesm.net`
- **Brandon Philips** — `brandon@ifup.org`
- **Daven** — `dooven@users.noreply.github.com`
- **Martin Stone** — `martin@d7415.co.uk`
- **David Bramwell** — `13053834+dbramwell@users.noreply.github.com`
- **Sunil Patra** — `snl_su@live.com`
- **Adam Stroud** — `adam.stroud@gmail.com`
- **Kush** — `kushsharma@users.noreply.github.com`
- **Matan Rosenberg** — `matan129@gmail.com`
- **gitch1** — `63495046+gitch1@users.noreply.github.com`
- **ElonH** — `elonhhuang@gmail.com`
- **Fred** — `fred@creativeprojects.tech`
- **Sébastien Gross** — `renard@users.noreply.github.com`
- **Maxime Suret** — `11944422+msuret@users.noreply.github.com`
- **Caleb Case** — `caleb@storj.io`, `calebcase@gmail.com`
- **Ben Zenker** — `imbenzenker@gmail.com`
- **Martin Michlmayr** — `tbm@cyrius.com`
- **Brandon McNama** — `bmcnama@pagerduty.com`
- **Daniel Slyman** — `github@skylayer.eu`
- **Alex Guerrero** — `guerrero@users.noreply.github.com`
- **Matteo Pietro Dazzi** — `matteopietro.dazzi@gft.com`
- **edwardxml** — `56691903+edwardxml@users.noreply.github.com`
- **Roman Kredentser** — `shareed2k@gmail.com`
- **Kamil Trzciński** — `ayufan@ayufan.eu`
- **Zac Rubin** — `z-0@users.noreply.github.com`
- **Vincent Feltz** (no email, just vibes ✨)
- **Heiko Bornholdt** — `bornholdt@informatik.uni-hamburg.de`
- **Matteo Pietro Dazzi** — `matteopietro.dazzi@gmail.com`
- **jtagcat** — `gitlab@c7.ee`
- **Petri Salminen** — `petri@salminen.dev`
- **Tim Burke** — `tim.burke@gmail.com`
- **Kai Lüke** — `kai@kinvolk.io`
- **Garrett Squire** — `github@garrettsquire.com`
- **Evan Harris** — `eharris@puremagic.com`
- **Kevin** — `keyam@microsoft.com`
- **Morten Linderud** — `morten@linderud.pw`
- **Dmitry Ustalov** — `dmitry.ustalov@gmail.com`
- **Jack** — `196648+jdeng@users.noreply.github.com`
- **kcris** — `cristian.tarsoaga@gmail.com`
- **tyhuber1** — `68970760+tyhuber1@users.noreply.github.com`
- **David Ibarra** — `david.ibarra@realty.com`
- **Tim Gallant** — `tim@lilt.com`
- **Kaloyan Raev** — `kaloyan@storj.io`
- **Jay McEntire** — `jay.mcentire@gmail.com`
- **Leo Luan** — `leoluan@us.ibm.com`
- **aus** — `549081+aus@users.noreply.github.com`
- **Aaron Gokaslan** — `agokaslan@fb.com`
- **Egor Margineanu** — `egmar@users.noreply.github.com`
- **Lucas Kanashiro** — `lucas.kanashiro@canonical.com`
- **WarpedPixel** — `WarpedPixel@users.noreply.github.com`
- **Sam Edwards** — `sam@samedwards.ca`
- **wjielai** — `gouki0123@gmail.com`
- **Muffin King** — `jinxz_k@live.com` 🧁 (yes that's their name, iconic)
- **Christopher Stewart** — `6573710+1f47a@users.noreply.github.com`
- **Russell Cattelan** — `cattelan@digitalelves.com`
- **gyutw** — `30371241+gyutw@users.noreply.github.com`
- **Hekmon** — `edouardhur@gmail.com`
- **LaSombra** — `lasombra@users.noreply.github.com`
- **Dov Murik** — `dov.murik@gmail.com`
- **Ameer Dawood** — `ameer1234567890@gmail.com`
- **Dan Hipschman** — `dan.hipschman@opendoor.com`
- **Josh Soref** — `jsoref@users.noreply.github.com`
- **David** — `david@staron.nl`
- **Ingo** — `ingo@hoffmann.cx`
- **Adam Plánský** — `adamplansky@users.noreply.github.com`, `adamplansky@gmail.com`
- **Manish Gupta** — `manishgupta.ait@gmail.com`
- **Deepak Sah** — `sah.sslpu@gmail.com`
- **Marcin Zelent** — `marcin@zelent.net`
- **zhucan** — `zhucan.k8s@gmail.com`
- **James Lim** — `james.lim@samsara.com`
- **Laurens Janssen** — `BD69BM@insim.biz`
- **Bob Bagwill** — `bobbagwill@gmail.com`
- **Nathan Collins** — `colli372@msu.edu`
- **lostheli** (no email, mysterious queen 💅)
- **kelv** — `kelvin@acks.org`
- **Milly** — `milly.ca@gmail.com`
- **gtorelly** — `gtorelly@gmail.com`
- **Brad Ackerman** — `brad@facefault.org`
- **Mitsuo Heijo** — `mitsuo.heijo@gmail.com`
- **Claudio Bantaloukas** — `rockdreamer@gmail.com`
- **Benjamin Gustin** — `gustin.ben@gmail.com`
- **Ingo Weiss** — `ingo@redhat.com`
- **Kerry Su** — `me@sshockwave.net`
- **Ilyess Bachiri** — `ilyess.bachiri@sonder.com`
- **Yury Stankevich** — `urykhy@gmail.com`
- **kice** — `wslikerqs@gmail.com`
- **Denis Neuling** — `denisneuling@gmail.com`
- **Janne Johansson** — `icepic.dz@gmail.com`
- **Patrik Nordlén** — `patriki@gmail.com`
- **CokeMine** — `aptx4561@gmail.com`
- **Sơn Trần-Nguyễn** — `github@sntran.com`
- **lluuaapp** — `266615+lluuaapp@users.noreply.github.com`
- **Zach Kipp** — `kipp.zach@gmail.com`
- **Riccardo Iaconelli** — `riccardo@kde.org`
- **Sakuragawa Misty** — `gyc990326@gmail.com`
- **Nicolas Rueff** — `nicolas@rueff.fr`
- **Pau Rodriguez-Estivill** — `prodrigestivill@gmail.com`
- **Bob Pusateri** — `BobPusateri@users.noreply.github.com`
- **Alex JOST** — `25005220+dimejo@users.noreply.github.com`
- **Alexey Tabakman** — `samosad.ru@gmail.com`
- **David Sze** — `sze.david@gmail.com`
- **cynthia kwok** — `cynthia.m.kwok@gmail.com`
- **Miron Veryanskiy** — `MironVeryanskiy@gmail.com`
- **K265** — `k.265@qq.com`
- **Vesnyx** — `Vesnyx@users.noreply.github.com`

and that's the end of this chunk of names bestie, no cap, we're still going in the next part so don't you dare close the page 🫶✨

okay bestie the contributor roll call is *still* going and honestly? it's giving "this project has a whole city of people behind it" 🏙️✨ and every single one of them ate. some of these emails are truly unhinged in the most beautiful way and i am obsessed 😭💖 so like, roll call continues, no skipping, periodt.

- **`Dmitry Chepurovskiy`** — `me@dm3ch.net`
- **`Rauno Ots`** — `rauno.ots@cgi.com`
- **`Georg Neugschwandtner`** — `georg.neugschwandtner@gmx.net`
- **`pvalls`** — `polvallsrue@gmail.com`
- **`Robert Thomas`** — `31854736+wolveix@users.noreply.github.com`
- **`Romeo Kienzler`** — `romeo.kienzler@gmail.com`
- **`tYYGH`** — `tYYGH@users.noreply.github.com`
- **`georne`** — `77802995+georne@users.noreply.github.com`
- **`Maxwell Calman`** — `mcalman@MacBook-Pro.local` <hotpink>(bestie the `.local` address 😭 truly committing from the couch)</hotpink>
- **`Naveen Honest Raj`** — `naveendurai19@gmail.com`
- **`Lucas Messenger`** — `lmesseng@cisco.com`
- **`Manish Kumar`** — `krmanish260@gmail.com`
- **`x0b`** — `x0bdev@gmail.com`
- <purple>CERN</purple> through the `CS3MESH4EOSC` Project
- **`Nick Gaya`** — `nicholasgaya+github@gmail.com`
- **`Ashok Gelal`** — `401055+ashokgelal@users.noreply.github.com`
- **`Dominik Mydlil`** — `dominik.mydlil@outlook.com`
- **`Nazar Mishturak`** — `nazarmx@gmail.com`
- **`Ansh Mittal`** — `iamAnshMittal@gmail.com`
- **`noabody`** — `noabody@yahoo.com`
- **`OleFrost`** — `82263101+olefrost@users.noreply.github.com`
- **`Kenny Parsons`** — `kennyparsons93@gmail.com`
- **`Jeffrey Tolar`** — `tolar.jeffrey@gmail.com`
- **`jtagcat`** — `git-514635f7@jtag.cat`
- **`Tatsuya Noyori`** — `63089076+public-tatsuya-noyori@users.noreply.github.com`

ngl the `<rainbow>plus-addressed github emails</rainbow>` thing is so real, that's how github feeds us the whole crew and we love to see it 💅

- **`lewisxy`** — `lewisxy@users.noreply.github.com`
- **`Nolan Woods`** — `nolan_w@sfu.ca`
- **`Gautam Kumar`** — `25435568+gautamajay52@users.noreply.github.com`
- **`Chris Macklin`** — `chris.macklin@10xgenomics.com`
- **`Antoon Prins`** — `antoon.prins@surfsara.nl`
- **`Alexey Ivanov`** — `rbtz@dropbox.com`
- **`Serge Pouliquen`** — `sp31415@free.fr`
- **`acsfer`** — `carlos@reendex.com`
- **`Tom`** — `tom@tom-fitzhenry.me.uk`
- **`Tyson Moore`** — `tyson@tyson.me`
- **`database64128`** — `free122448@hotmail.com`
- **`Chris Lu`** — `chrislusf@users.noreply.github.com`
- **`Reid Buzby`** — `reid@rethink.software`
- **`darrenrhs`** — `darrenrhs@gmail.com`
- **`Florian Penzkofer`** — `fp@nullptr.de`
- **`Xuanchen Wu`** — `117010292@link.cuhk.edu.cn`
- **`partev`** — `petrosyan@gmail.com`
- **`Dmitry Sitnikov`** — `fo2@inbox.ru`
- **`Haochen Tong`** — `i@hexchain.org`
- **`Michael Hanselmann`** — `public@hansmi.ch`
- **`Chuan Zh`** — `zhchuan7@gmail.com`
- **`Antoine GIRARD`** — `antoine.girard@sapk.fr`
- **`Justin Winokur (Jwink3101)`** — `Jwink3101@users.noreply.github.com`
- **`Mariano Absatz (git)`** — `scm@baby.com.ar`
- **`Greg Sadetsky`** — `lepetitg@gmail.com`

lowkey every time i see a `.edu` or a `cern` in a contributor list i'm like "okay main character energy, the literal research labs are here" 🔥

- **`yedamo`** — `logindaveye@gmail.com`
- **`hota`** — `lindwurm.q@gmail.com`
- **`vinibali`** — `vinibali1@gmail.com`
- **`Ken Enrique Morel`** — `ken.morel.santana@gmail.com`
- **`Justin Hellings`** — `justin.hellings@gmail.com`
- **`Parth Shukla`** — `pparth@pparth.net`
- **`wzl`** — `wangzl31@outlook.com`
- **`HNGamingUK`** — `connor@earnshawhome.co.uk`
- **`Jonta`** — `359397+Jonta@users.noreply.github.com`
- **`YenForYang`** — `YenForYang@users.noreply.github.com`
- **`SimJoSt / Joda Stößer`** — `git@simjo.st`
- **`Logeshwaran`** — `waranlogesh@gmail.com`
- **`Rajat Goel`** — `rajat@dropbox.com`
- **`r0kk3rz`** — `r0kk3rz@gmail.com`
- **`Matthew Sevey`** — `mjsevey@gmail.com`
- **`Filip Rysavy`** — `fil@siasky.net`
- **`Ian Levesque`** — `ian@ianlevesque.org`
- **`Thomas Stachl`** — `thomas@stachl.me`
- **`Dmitry Bogatov`** — `git#v1@kaction.cc`
- **`thomae`** — `4493560+thomae@users.noreply.github.com`
- **`trevyn`** — `trevyn-git@protonmail.com`
- **`David Liu`** — `david.yx.liu@oracle.com`
- **`Chris Nelson`** — `stuff@cjnaz.com`
- **`Felix Bunemann`** — `felix.buenemann@gmail.com`
- **`Atílio Antônio`** — `atiliodadalto@hotmail.com`

the way some of y'all have custom domains and protonmail addresses... we see you, privacy girlies 🫶 <lavender>respectfully obsessed</lavender>

- **`Carlo Mion`** — `mion00@gmail.com`
- **`Chris Lu`** — `chris.lu@gmail.com`
- **`Vitor Arruda`** — `vitor.pimenta.arruda@gmail.com`
- **`bbabich`** — `bbabich@datamossa.com`
- **`David`** — `dp.davide.palma@gmail.com`
- **`Borna Butkovic`** — `borna@favicode.net`
- **`Fredric Arklid`** — `fredric.arklid@consid.se`
- **`Andy Jackson`** — `Andrew.Jackson@bl.uk`
- **`Sinan Tan`** — `i@tinytangent.com`
- **`deinferno`** — `14363193+deinferno@users.noreply.github.com`
- **`rsapkf`** — `rsapkfff@pm.me`
- **`Will Holtz`** — `wholtz@gmail.com`
- **`GGG KILLER`** — `gggkiller2@gmail.com`
- **`Logeshwaran Murugesan`** — `logeshwaran@testpress.in`
- **`Lu Wang`** — `coolwanglu@gmail.com`
- **`Bumsu Hyeon`** — `ksitht@gmail.com`
- **`Shmz Ozggrn`** — `98463324+ShmzOzggrn@users.noreply.github.com`
- **`Kim`** — `kim@jotta.no`
- **`Niels van de Weem`** — `n.van.de.weem@smile.nl`
- **`Koopa`** — `codingkoopa@gmail.com`
- **`Yunhai Luo`** — `yunhai-luo@hotmail.com`
- **`Charlie Jiang`** — `w@chariri.moe`
- **`Alain Nussbaumer`** — `alain.nussbaumer@alleluia.ch`
- **`Vanessasaurus`** — `814322+vsoch@users.noreply.github.com`
- **`Isaac Levy`** — `isaac.r.levy@gmail.com`

one thing about this list: it's *endless* and i mean that as the highest compliment. every handle here is a whole person who fixed a thing so your `rclone` commands just work ✨

- **`Gourav T`** — `workflowautomation@protonmail.com`
- **`Paulo Martins`** — `paulo.pontes.m@gmail.com`
- **`viveknathani`** — `viveknathani2402@gmail.com`
- **`Eng Zer Jun`** — `engzerjun@gmail.com`
- **`Abhiraj`** — `abhiraj.official15@gmail.com`
- **`Márton Elek`** — `elek@apache.org`, `elek@users.noreply.github.com`
- **`Vincent Murphy`** — `vdm@vdm.ie`
- **`ctrl-q`** — `34975747+ctrl-q@users.noreply.github.com`
- **`Nil Alexandrov`** — `nalexand@akamai.com`
- **`GuoXingbin`** — `101376330+guoxingbin@users.noreply.github.com`
- **`Berkan Teber`** — `berkan@berkanteber.com`
- **`Tobias Klauser`** — `tklauser@distanz.ch`
- **`KARBOWSKI Piotr`** — `piotr.karbowski@gmail.com`
- **`GH`** — `geeklihui@foxmail.com`
- **`rafma0`** — `int.main@gmail.com`
- **`Adrien Rey-Jarthon`** — `jobs@adrienjarthon.com`
- **`Nick Gooding`** — `73336146+nickgooding@users.noreply.github.com`
- **`Leroy van Logchem`** — `lr.vanlogchem@gmail.com`
- **`Zsolt Ero`** — `zsolt.ero@gmail.com`
- **`Lesmiscore`** — `nao20010128@gmail.com`
- **`ehsantdy`** — `ehsan.tadayon@arvancloud.com`, `ehsantadayon85@gmail.com`
- **`SwazRGB`** — `65694696+swazrgb@users.noreply.github.com`
- **`Mateusz Puczynski`** — `mati6095@gmail.com`
- **`Michael C Tiernan`** — MIT-Research Computing Project — `mtiernan@mit.edu`
- **`Kaspian`** — `34658474+KaspianDev@users.noreply.github.com`

<cyan>shoutout to everyone with two emails listed</cyan>, the way y'all switched addresses mid-project and still showed up? that's commitment fr fr 💖

- **`Werner`** — `EvilOlaf@users.noreply.github.com`
- **`Hugal31`** — `hugo.laloge@gmail.com`
- **`Christian Galo`** — `36752715+cgalo5758@users.noreply.github.com`
- **`Erik van Velzen`** — `erik@evanv.nl`
- **`Derek Battams`** — `derek@battams.ca`
- **`Paul`** — `devnoname120@gmail.com`
- **`SimonLiu`** — `simonliu009@users.noreply.github.com`
- **`Hugo Laloge`** — `hla@lescompanions.com`
- **`Mr-Kanister`** — `68117355+Mr-Kanister@users.noreply.github.com`
- **`Rob Pickerill`** — `r.pickerill@gmail.com`
- **`Andrey`** — `to.merge@gmail.com`
- **`Eric Wolf`** — `19wolf@gmail.com`
- **`Nick`** — `nick.naumann@mailbox.tu-dresden.de`
- **`Jason Zheng`** — `jszheng17@gmail.com`
- **`Matthew Vernon`** — `mvernon@wikimedia.org`
- **`Noah Hsu`** — `i@nn.ci`
- **`m00594701`** — `mengpengbo@huawei.com`
- **`Art M. Gallagher`** — `artmg50@gmail.com`
- **`Sven Gerber`** — `49589423+svengerber@users.noreply.github.com`
- **`CrossR`** — `r.cross@lancaster.ac.uk`
- **`Maciej Radzikowski`** — `maciej@radzikowski.com.pl`
- **`Scott Grimes`** — `scott.grimes@spaciq.com`
- **`Phil Shackleton`** — `71221528+philshacks@users.noreply.github.com`
- **`eNV25`** — `env252525@gmail.com`
- **`Caleb`** — `inventor96@users.noreply.github.com`

the uni emails, the corporate emails, the personal gmails — <mint>a whole mixed friend group</mint> 🎀 and they all collaborated on the same codebase, cute

- **`J-P Treen`** — `jp@wraptious.com`
- **`Martin Czygan`** — `53705+miku@users.noreply.github.com`
- **`buda`** — `sandrojijavadze@protonmail.com`
- **`mirekphd`** — `36706320+mirekphd@users.noreply.github.com`
- **`vyloy`** — `vyloy@qq.com`
- **`Anthrazz`** — `25553648+Anthrazz@users.noreply.github.com`
- **`zzr93`** — `34027824+zzr93@users.noreply.github.com`
- **`Paul Norman`** — `penorman@mac.com`
- **`Lorenzo Maiorfi`** — `maiorfi@gmail.com`
- **`Claudio Maradonna`** — `penguyman@stronzi.org`
- **`Ovidiu Victor Tatar`** — `ovi.tatar@googlemail.com`
- **`Evan Spensley`** — `epspensley@gmail.com`
- **`Yen Hu`** — `61753151+0x59656e@users.noreply.github.com`
- **`Steve Kowalik`** — `steven@wedontsleep.org`
- **`Jordi Gonzalez Muñoz`** — `jordigonzm@gmail.com`
- **`Joram Schrijver`** — `i@joram.io`
- **`Mark Trolley`** — `marktrolley@gmail.com`
- **`João Henrique Franco`** — `joaohenrique.franco@gmail.com`
- **`anonion`** — `aman207@users.noreply.github.com`
- **`Ryan Morey`** — `4590343+rmorey@users.noreply.github.com`
- **`Simon Bos`** — `simonbos9@gmail.com`
- **`YFdyh000`** — `yfdyh000@gmail.com`
- **`Josh Soref`** — `2119212+jsoref@users.noreply.github.com`
- **`Øyvind Heddeland Instefjord`** — `instefjord@outlook.com`
- **`Dmitry Deniskin`** — `110819396+ddeniskin@users.noreply.github.com`

okay the accented characters in these names are sending me in the best way 😭💜 it's an international slay, we love a global bestie situation

- **`Alexander Knorr`** — `106825+opexxx@users.noreply.github.com`
- **`Richard Bateman`** — `richard@batemansr.us`
- **`Dimitri Papadopoulos Orfanos`** — `3234522+DimitriPapadopoulos@users.noreply.github.com`
- **`Lorenzo Milesi`** — `lorenzo.milesi@yetopen.com`
- **`Isaac Aymerich`** — `isaac.aymerich@gmail.com`
- **`YanceyChiew`** — `35898533+YanceyChiew@users.noreply.github.com`
- **`Manoj Ghosh`** — `msays2000@gmail.com`
- **`Bachue Zhou`** — `bachue.shu@gmail.com`
- **`Manoj Ghosh`** — `manoj.ghosh@oracle.com`
- **`Tom Mombourquette`** — `tom@devnode.com`
- **`Robert Newson`** — `rnewson@apache.org`
- **`Samuel Johnson`** — `esamueljohnson@gmail.com`
- **`coultonluke`** — `luke@luke.org.uk`
- **`Anthony Pessy`** — `anthony@cogniteev.com`
- **`Philip Harvey`** — `pharvey@battelleecology.org`
- **`dgouju`** — `dgouju@users.noreply.github.com`
- **`Clément Notin`** — `clement.notin@gmail.com`
- **`x3-apptech`** — `66947598+x3-apptech@users.noreply.github.com`
- **`Arnie97`** — `arnie97@gmail.com`
- **`Roel Arents`** — `2691308+roelarents@users.noreply.github.com`
- **`Aaron Gokaslan`** — `aaronGokaslan@gmail.com`
- **`techknowlogick`** — `matti@mdranta.net`
- **`rkettelerij`** — `richard@mindloops.nl`
- **`Kamui`** — `fin-kamui@pm.me`
- **`asdffdsazqqq`** — `90116442+asdffdsazqqq@users.noreply.github.com`

not the same name showing up twice with two different emails — `Manoj Ghosh` said "i contain multitudes" 💀 and bestie we respect it

- **`Nathaniel Wesley Filardo`** — `nfilardo@microsoft.com`
- **`ycdtosa`** — `ycdtosa@users.noreply.github.com`
- **`Erik Agterdenbos`** — `agterdenbos@users.noreply.github.com`
- **`Kevin Verstaen`** — `48050031+kverstae@users.noreply.github.com`
- **`MohammadReza`** — `mrvashian@gmail.com`
- **`vanplus`** — `60313789+vanplus@users.noreply.github.com`
- **`Jack`** — `16779171+jkpe@users.noreply.github.com`
- **`Abdullah Saglam`** — `abdullah.saglam@stonebranch.com`
- **`Marks Polakovs`** — `github@markspolakovs.me`
- **`piyushgarg`** — `piyushgarg80@gmail.com`
- **`Kaloyan Raev`** — `kaloyan-raev@users.noreply.github.com`
- **`IMTheNachoMan`** — `imthenachoman@gmail.com`
- **`alankrit`** — `alankrit@google.com`
- **`Bryan Kaplan`** — `<#@bryankaplan.com>`
- **`LXY`** — `767763591@qq.com`
- **`Simmon Li (he/him)`** — `li.simmon@gmail.com`
- **`happyxhw`** — `44490504+happyxhw@users.noreply.github.com`
- **`Simmon Li (he/him)`** — `hello@crespire.dev`
- **`Matthias Baur`** — `baurmatt@users.noreply.github.com`
- **`Hunter Wittenborn`** — `hunter@hunterwittenborn.com`
- **`logopk`** — `peter@kreuser.name`
- **`Gerard Bosch`** — `30733556+gerardbosch@users.noreply.github.com`
- **`ToBeFree`** — `github@tfrei.de`
- **`NodudeWasTaken`** — `75137537+NodudeWasTaken@users.noreply.github.com`
- **`Peter Brunner`** — `peter@lugoues.net`

lowkey the `<blue>pronoun-in-the-name</blue>` thing is such a green flag, i love when folks make it known 🫶 and shoutout to whoever that `<#@bryankaplan.com>` situation belongs to, truly a formatting icon 😭

- **`Ninh Pham`** — `dongian.rapclubkhtn@gmail.com`
- **`Ryan Caezar Itang`** — `sitiom@proton.me`
- **`Peter Brunner`** — `peter@psykhe.com`
- **`Leandro Sacchet`** — `leandro.sacchet@animati.com.br`
- **`dependabot[bot]`** — `<49699333+dependabot[bot]@users.noreply.github.com>`
- **`cycneuramus`** — `56681631+cycneuramus@users.noreply.github.com`
- **`Arnavion`** — `me@arnavion.dev`
- **`Christopher Merry`** — `christopher.merry@mlb.com`
- **`Thibault Coupin`** — `thibault.coupin@gmail.com`
- **`Richard Tweed`** — `RichardoC@users.noreply.github.com`

and <rainbow>dependabot</rainbow> is on the list too 💀🤖 not a human but honestly? she's been carrying the dependency updates and that's a slay in its own right, give her the credit fr fr

aaaand the roll call keeps rolling because there are *more* parts coming and more names to hype — don't go anywhere bestie 💖

okay bestie we are STILL in the contributor roll-call and honestly? iconic. every single one of these people touched the code, filed the bug, or fixed the thing, and their names live here forever. no skips, no skimming, let's go 🌈

- **Zach Kipp** — `Zacho2@users.noreply.github.com`
- **yuudi** — `26199752+yuudi@users.noreply.github.com`
- **NickIAm** — `NickIAm@users.noreply.github.com`
- **Juang, Yi-Lin** — `frankyjuang@gmail.com`
- **jumbi77** — `jumbi77@users.noreply.github.com`
- **Aditya Basu** — `ab.aditya.basu@gmail.com`
- **ed** — `s@ocv.me`
- **Drew Parsons** — `dparsons@emerall.com`
- **Joel** — `joelnb@users.noreply.github.com`
- **wiserain** — `mail275@gmail.com`
- **Roel Arents** — `roel.arents@kadaster.nl`
- **Shyim** — `github@shyim.de`
- **Rintze Zelle** — `78232505+rzelle-lallemand@users.noreply.github.com`
- **Damo** — `damoclark@users.noreply.github.com`
- **WeidiDeng** — `weidi_deng@icloud.com`
- **Brian Starkey** — `stark3y@gmail.com`
- **jladbrook** — `jhladbrook@gmail.com`
- **Loren Gordon** — `lorengordon@users.noreply.github.com`
- **dlitster** — `davidlitster@gmail.com`
- **Tobias Gion** — `tobias@gion.io`
- **Jānis Bebrītis** — `janis.bebritis@wunder.io`
- **Adam K** — `github.com@ak.tidy.email`
- **Andrei Smirnov** — `smirnov.captain@gmail.com`
- **Janne Hellsten** — `jjhellst@gmail.com`
- **cc** — `12904584+shvc@users.noreply.github.com`
- **Tareq Sharafy** — `tareq.sha@gmail.com`
- **kapitainsky** — `dariuszb@me.com`
- **douchen** — `playgoobug@gmail.com`
- **Sam Lai** — `70988+slai@users.noreply.github.com`
- **URenko** — `18209292+URenko@users.noreply.github.com`
- **Stanislav Gromov** — `kullfar@gmail.com`
- **Paulo Schreiner** — `paulo.schreiner@delivion.de`
- **Mariusz Suchodolski** — `mariusz@suchodol.ski`
- **danielkrajnik** — `dan94kra@gmail.com`
- **Peter Fern** — `github@0xc0dedbad.com`
- **zzq** — `i@zhangzqs.cn`
- **mac-15** — `usman.ilamdin@phpstudios.com`
- **Sawada Tsunayoshi** — `34431649+TsunayoshiSawada@users.noreply.github.com`
- **Dean Attali** — `daattali@gmail.com`
- **Fjodor42** — `molgaard@gmail.com`
- **BakaWang** — `wa11579@hotmail.com`
- **Mahad** — `56235065+Mahad-lab@users.noreply.github.com`
- **Vladislav Vorobev** — `x.miere@gmail.com`
- **darix** — `darix@users.noreply.github.com`
- **Benjamin** — `36415086+bbenjamin-sys@users.noreply.github.com`
- **Chun-Hung Tseng** — `henrybear327@users.noreply.github.com`
- **Ricardo D’O.  Albanus** — `rdalbanus@users.noreply.github.com`
- **gabriel-suela** — `gscsuela@gmail.com`
- **Tiago Boeing** — `contato@tiagoboeing.com`
- **Edwin Mackenzie-Owen** — `edwin.mowen@gmail.com`
- **Niklas Hambüchen** — `mail@nh2.me`
- **yuudi** — `yuudi@users.noreply.github.com`
- **Zach** — `github@prozach.org`
- **nielash** — `31582349+nielash@users.noreply.github.com`
- **Julian Lepinski** — `lepinsk@users.noreply.github.com`
- **Raymond Berger** — `RayBB@users.noreply.github.com`
- **Nihaal Sangha** — `nihaal.git@gmail.com`
- **Masamune3210** — `1053504+Masamune3210@users.noreply.github.com`
- **James Braza** — `jamesbraza@gmail.com`
- **antoinetran** — `antoinetran@users.noreply.github.com`
- **alexia** — `me@alexia.lol`
- **nielash** — `nielronash@gmail.com`
- **Vitor Gomes** — `vitor.gomes@delivion.de mail@vitorgomes.com`
- **Jacob Hands** — `jacob@gogit.io`
- **hideo aoyama** — `100831251+boukendesho@users.noreply.github.com`
- **Roberto Ricci** — `io@r-ricci.it`
- **Bjørn Smith** — `bjornsmith@gmail.com`
- **Alishan Ladhani** — `8869764+aladh@users.noreply.github.com`
- **zjx20** — `zhoujianxiong2@gmail.com`
- **Oksana** — `142890647+oks-maytech@users.noreply.github.com`
- **Volodymyr Kit** — `v.kit@maytech.net`
- **David Pedersen** — `limero@me.com`
- **Drew Stinnett** — `drew@drewlink.com`
- **Pat Patterson** — `pat@backblaze.com`
- **Herby Gillot** — `herby.gillot@gmail.com`
- **Nikita Shoshin** — `shoshin_nikita@fastmail.com`
- **rinsuki** — `428rinsuki+git@gmail.com`
- **Beyond Meat** — `51850644+beyondmeat@users.noreply.github.com`
- **Saleh Dindar** — `salh@fb.com`
- **Volodymyr** — `142890760+vkit-maytech@users.noreply.github.com`
- **Gabriel Espinoza** — `31670639+gspinoza@users.noreply.github.com`
- **Keigo Imai** — `keigo.imai@gmail.com`
- **Ivan Yanitra** — `iyanitra@tesla-consulting.com`
- **alfish2000** — `alfish2000@gmail.com`
- **wuxingzhong** — `qq330332812@gmail.com`

> bestie the way this list just keeps GOING and every single name is someone who actually showed up and shipped something 💅 we love a community that pulls up.

- **Adithya Kumar** — `akumar42@protonmail.com`
- **Tayo-pasedaRJ** — `138471223+Tayo-pasedaRJ@users.noreply.github.com`
- **Peter Kreuser** — `logo@kreuser.name`
- **Piyush**
- **fotile96** — `fotile96@users.noreply.github.com`
- **Luc Ritchie** — `luc.ritchie@gmail.com`
- **cynful** — `cynful@users.noreply.github.com`
- **wjielai** — `wjielai@tencent.com`
- **Jack Deng** — `jackdeng@gmail.com`
- **Mikubill** — `31246794+Mikubill@users.noreply.github.com`
- **Artur Neumann** — `artur@jankaritech.com`
- **Saw-jan** — `saw.jan.grg3e@gmail.com`
- **Oksana Zhykina** — `o.zhykina@maytech.net`
- **karan** — `karan.gupta92@gmail.com`
- **viktor** — `viktor@yakovchuk.net`
- **moongdal** — `moongdal@tutanota.com`
- **Mina Galić** — `freebsd@igalic.co`
- **Alen Šiljak** — `dev@alensiljak.eu.org`
- **你知道未来吗** — `rkonfj@gmail.com`
- **Abhinav Dhiman** — `8640877+ahnv@users.noreply.github.com`
- **halms** — `7513146+halms@users.noreply.github.com`
- **ben-ba** — `benjamin.brauner@gmx.de`
- **Eli Orzitzer** — `e_orz@yahoo.com`
- **Anthony Metzidis** — `anthony.metzidis@gmail.com`
- **keongalvin** — `keongalvin@gmail.com`
- **rarspace01** — `rarspace01@users.noreply.github.com`
- **Paul Stern** — `paulstern45@gmail.com`
- **Nikhil Ahuja** — `nikhilahuja@live.com`
- **Harshit Budhraja** — `52413945+harshit-budhraja@users.noreply.github.com`
- **Tera** — `24725862+teraa@users.noreply.github.com`
- **Kyle Reynolds** — `kylereynoldsdev@gmail.com`
- **Michael Eischer** — `michael.eischer@gmx.de`
- **Thomas Müller** — `1005065+DeepDiver1975@users.noreply.github.com`
- **DanielEgbers** — `27849724+DanielEgbers@users.noreply.github.com`
- **Jack Provance** — `49460795+njprov@users.noreply.github.com`
- **Gabriel Ramos** — `109390599+gabrielramos02@users.noreply.github.com`
- **Dan McArdle** — `d@nmcardle.com`
- **Joe Cai** — `joe.cai@bigcommerce.com`
- **Anders Swanson** — `anders.swanson@oracle.com`
- **huajin tong** — `137764712+thirdkeyword@users.noreply.github.com`
- **John-Paul Smith** — `john-paulsmith@users.noreply.github.com`
- **racerole** — `148756161+racerole@users.noreply.github.com`
- **Gachoud Philippe** — `ph.gachoud@gmail.com`
- **YukiUnHappy** — `saberhana@yandex.com`
- **Kyle Reynolds** — `kyle.reynolds@bridgerphotonics.com`
- **Lewis Hook** — `lewis@hook.im`
- **hoyho** — `luohaihao@gmail.com`
- **Vitaly** — `9034218+gvitali@users.noreply.github.com`
- **iotmaestro** — `iotmaestro@proton.me`
- **psychopatt** — `66741203+psychopatt@users.noreply.github.com`
- **Alex Garel** — `alex@garel.org`
- **Warrentheo** — `warrentheo@hotmail.com`
- **Alexandre Lavigne** — `lavigne958@gmail.com`
- **yoelvini** — `134453420+yoelvini@users.noreply.github.com`
- **Erisa A** — `erisa@cloudflare.com`
- **Pieter van Oostrum** — `pieter@vanoostrum.org`
- **jakzoe** — `155812065+jakzoe@users.noreply.github.com`
- **guangwu** — `guoguangwu@magic-shield.com`
- **static-moonlight** — `107991124+static-moonlight@users.noreply.github.com`
- **yudrywet** — `yudeyao@yeah.net`
- **Butanediol** — `git@xnh.app`
- **Dave Nicolson** — `david.nicolson@gmail.com`
- **Katia Esposito** — `katia@linux.com`
- **pawsey-kbuckley** — `36438302+pawsey-kbuckley@users.noreply.github.com`
- **hidewrong** — `167099254+hidewrong@users.noreply.github.com`
- **Michael Terry** — `mike@mterry.name`
- **Sunny** — `25066078+LoSunny@users.noreply.github.com`
- **overallteach** — `cricis@foxmail.com`
- **JT Olio** — `jt@olio.lol`
- **Evan McBeth** — `64177332+AtomicRobotMan0101@users.noreply.github.com`
- **Dominik Joe Pantůček** — `dominik.pantucek@trustica.cz`
- **yumeiyin** — `155420652+yumeiyin@users.noreply.github.com`
- **Bruno Fernandes** — `54373093+folkzb@users.noreply.github.com`
- **Thomas Schneider** — `tspam.github@brainfuck.space`
- **Charles Hamilton** — `52973156+chamilton-ccn@users.noreply.github.com`
- **Tomasz Melcer** — `tomasz@melcer.pl`
- **Michał Dzienisiewicz** — `michal.piotr.dz@gmail.com`
- **Florian Klink** — `flokli@flokli.de`
- **Bill Fraser** — `bill@wfraser.dev`
- **Thearas** — `thearas850@gmail.com`
- **Filipe Herculano** — `fifo_@live.com`
- **Russ Bubley** — `russ.bubley@googlemail.com`
- **Paul Collins** — `paul.collins@canonical.com`
- **Tomasz Melcer** — `liori@exroot.org`
- **itsHenry** — `2671230065@qq.com`
- **Ke Wang** — `me@ke.wang`
- **AThePeanut4** — `49614525+AThePeanut4@users.noreply.github.com`
- **Tobias Markus** — `tobbi.bugs@googlemail.com`
- **Ernie Hershey** — `github@ernie.org`
- **Will Miles** — `wmiles@sgl.com`
- **David Seifert** — `16636962+SoapGentoo@users.noreply.github.com`
- **Fornax** — `wimbrand96@gmail.com`
- **Sam Harrison** — `sam.harrison@files.com`
- **Péter Bozsó** — `3806723+peterbozso@users.noreply.github.com`
- **Georg Welzel** — `gwelzel@mailbox.org`
- **John Oxley** — `john.oxley@gmail.com joxley@meta.com`
- **Pawel Palucha** — `pawel.palucha@aetion.com`
- **crystalstall** — `crystalruby@qq.com`
- **nipil** — `nipil@users.noreply.github.com`
- **yuval-cloudinary** — `46710068+yuval-cloudinary@users.noreply.github.com`
- **Mathieu Moreau** — `mrx23dot@users.noreply.github.com`
- **fsantagostinobietti** — `6057026+fsantagostinobietti@users.noreply.github.com`
- **Oleg Kunitsyn** — `114359669+hiddenmarten@users.noreply.github.com`
- **Divyam** — `47589864+divyam234@users.noreply.github.com`
- **ttionya** — `ttionya@users.noreply.github.com`
- **quiescens** — `quiescens@gmail.com`
- **rishi.sridhar** — `rishi.sridhar@zohocorp.com`
- **Lawrence Murray** — `lawrence@indii.org`
- **Leandro Piccilli** — `leandro.piccilli@thalesgroup.com`
- **Benjamin Legrand** — `benjamin.legrand@seagate.com`
- **Noam Ross** — `noam.ross@gmail.com`
- **lostb1t** — `coding-mosses0z@icloud.com`
- **Matthias Gatto** — `matthias.gatto@outscale.com`
- **André Tran** — `andre.tran@outscale.com`
- **Simon Bos** — `simon@simonbos.be`
- **Alexandre Hamez** — `199517+ahamez@users.noreply.github.com`
- **Randy Bush** — `randy@psg.com`
- **Diego Monti** — `diegmonti@users.noreply.github.com`
- **tgfisher** — `tgfisher@stanford.edu`
- **Moises Lima** — `mozlima@gmail.com`
- **Dimitar Ivanov** — `mimiteto@gmail.com`
- **shenpengfeng** — `xinhangzhou@icloud.com`
- **Dimitrios Slamaris** — `dim0x69@users.noreply.github.com`
- **vintagefuture** — `39503528+vintagefuture@users.noreply.github.com`
- **David Seifert** — `soap@gentoo.org`
- **Michael R. Davis** — `mrdvt92@users.noreply.github.com`
- **remygrandin** — `remy.gr@ndin.fr`
- **Ilias Ozgur Can Leonard** — `iscilyas@gmail.com`
- **divinity76** — `divinity76@gmail.com`
- **Martin Hassack** — `martin@redmaple.tech`
- **Filipe Azevedo** — `pasnox@gmail.com`
- **hayden.pan** — `hayden.pan@outlook.com`
- **Yxxx** — `45665172+marsjane@users.noreply.github.com`
- **Thomas ten Cate** — `ttencate@gmail.com`
- **Louis Laureys** — `louis@laureys.me`
- **Henry Lee** — `contact@nynxz.com`
- **ToM** — `thomas.faucher@bibliosansfrontieres.org`
- **TAKEI Yuya** — `853320+takei-yuya@users.noreply.github.com`
- **Francesco Frassinelli** — `fraph24@gmail.com francesco.frassinelli@nina.no`

> okay the scroll bar said *enough* but we kept going because that's the vibe 🫶 every email here is a real human who made rclone better, and that's the whole point.

## 🫶 Contact the rclone project 🫶

Bestie, if you ever need to reach actual humans behind this whole thing (yes, they're real, no cap ✨), here's every single door you can knock on. Pick your vibe 💅

### 📣 Forum

The forum is *the* place for questions and general discussion:

- `https://forum.rclone.org`

> Lowkey the fastest way to get help, fr fr. Start here before you dm anybody 🙈

### 💼 Business support

For business support or sponsorship enquiries please see:

- `https://rclone.com/`

- `sponsorship@rclone.com`

### 🐙 GitHub repository

The project's repository is located at:

- `https://github.com/rclone/rclone`

There you can file bug reports or contribute with pull requests. Like, actually go be the main character and open that PR, I believe in you 👑

### 🦋 Twitter

You can also follow Nick on twitter for rclone announcements:

- `@njcw`

### 💌 Email

Or if all else fails or you want to ask something private or confidential

- `info@rclone.com`

> Okay important one, listen up bestie 🚨 Please don't email requests for help to this address — those are better directed to the forum unless you'd like to sign up for business support. The inbox is for the confidential/private/business stuff only, mkay? 💖

---

# 👑 AUTHORS 👑

Nick Craig-Wood.

---

And that's a wrap on the whole entire man page, bestie 😭🎀 You made it all the way to the end of *two hundred and fifty-four* parts, which is genuinely iconic behavior and I'm so proud of you. This little beauty is from the **User Manual**, it's the **`rclone(1)`** page, and it's dated **Aug 11, 2026** ✨ Go `rclone` something, you've earned it. Mwah 💅💜

📦 where this page comes from

ubuntu stonking: rclone 1.69.3+dfsg-3ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms