rclone(1)

NAME

okay bestie, welcome to the rclone(1) manual page 😌 — this is the one that lets you manage files on cloud storage across like a million remotes, no cap. It's giving "I have 47 cloud accounts and I know how to use them" energy. Periodt. ✨

---

SYNOPSIS

Here's the usage shape, fr fr:

              Usage:
                rclone [flags]
                rclone [command]

✨ Available commands ✨

okay so these are all the commands rclone is giving. Don't skip, there's like 56 of them and they all matter:

• about — gets quota information from the remote. Like, "how much space do I have left?" energy. ✨
• archive — performs an action on an archive. It's giving archive management. 🎀
• authorize — remote authorization. The "let me in" moment. 🔑
• backend — runs a backend-specific command. iykyk. 🧚
• bisync — performs bidirectional synchronization between two paths. Both ways, no cap. 🔄
• cat — concatenates any files and sends them to stdout. Like cat, but make it cloud. 🐱
• check — checks the files in the source and destination match. Vibe check for your data. 👀
• checksum — checks the files in the destination against a SUM file. 🧾
• cleanup — cleans up the remote if possible. Tidy queen. 🧹
• completion — outputs completion script for a given shell. Your shell will thank you. 🐚
• config — enters an interactive configuration session. Set it up, bestie. ⚙️
• convmv — converts file and directory names in place. Rename glow-up. 💅
• copy — copies files from source to dest, skipping identical files. No duplicates, periodt. 📋
• copyto — copies files from source to dest, skipping identical files. Same energy, different target. 🎯
• copyurl — copies the contents of the URL supplied content to dest:path. URL to cloud, slay. 🔗
• cryptcheck — cryptcheck checks the integrity of an encrypted remote. 🔐
• cryptdecode — cryptdecode returns unencrypted file names. Decode the mystery. 🕵️
• dedupe — interactively finds duplicate filenames and deletes/renames them. Duplicate detective. 🔍
• delete — removes the files in path. Gone, but make it intentional. 🗑️
• deletefile — removes a single file from remote. Just one, bestie. ✂️
• gendocs — outputs markdown docs for rclone to the directory supplied. Docs on docs. 📝
• gitannex — speaks with git-annex over stdin/stdout. Niche but iconic. 🧬
• gui — opens the web based GUI. Clicky clicky. 🖱️
• hashsum — produces a hashsum file for all the objects in the path. Hashes for days. #️⃣
• help — shows help for rclone commands, flags and backends. When in doubt, ask. 🆘
• link — generates public link to file/folder. Share the love. 🔗
• listremotes — lists all the remotes in the config file and defined in environment variables. Remote roll call. 📋
• ls — lists the objects in the path with size and path. Basic but essential. 📂
• lsd — lists all directories/containers/buckets in the path. Directory vibes. 📁
• lsf — lists directories and objects in remote:path formatted for parsing. Machine-readable realness. 🤖
• lsjson — lists directories and objects in the path in JSON format. JSON girlies rise. 🧾
• lsl — lists the objects in path with modification time, size and path. The long view. 📅
• md5sum — produces an md5sum file for all the objects in the path. Classic hash energy. 🔢
• mkdir — makes the path if it doesn't already exist. Create the folder, bestie. 📁
• mount — mounts the remote as file system on a mountpoint. Cloud as local, iconic. 🗻
• move — moves files from source to dest. No copy left behind. 🚚
• moveto — moves file or directory from source to dest. Same, but specific. 🎯
• ncdu — explores a remote with a text based user interface. TUI adventure. 🗺️
• nfsmount — mounts the remote as file system on a mountpoint. NFS edition. 🗻
• obscure — obscures password for use in the rclone config file. Keep it secret, keep it safe. 🤫
• purge — removes the path and all of its contents. Nuclear option, be careful. 💥
• rc — runs a command against a running rclone. Remote control realness. 🎮
• rcat — copies standard input to file on remote. stdin to cloud. 🐈
• rcd — runs rclone listening to remote control commands only. Daemon mode, no cap. 🛰️
• rmdir — removes the empty directory at path. Only if it's empty, bestie. 📂
• rmdirs — removes empty directories under the path. Clean sweep. 🧹
• selfupdate — updates the rclone binary. Glow-up for your binary. ⬆️
• serve — serves a remote over a protocol. Host it. 🌐
• settier — changes storage class/tier of objects in remote. Tier list for your storage. 📊
• sha1sum — produces an sha1sum file for all the objects in the path. Another hash baddie. 🔢
• size — prints the total size and number of objects in remote:path. Math but make it cloud. 🧮
• sync — makes source and dest identical, modifying destination only. One-way realness. 🔄
• test — runs a test command. Just a test, bestie. 🧪
• touch — creates new file or changes file modification time. Touch grass? No, touch file. 🌱
• tree — lists the contents of the remote in a tree like fashion. Tree structure, slay. 🌳
• version — shows the version number. Know your era. 📌

And the little helper notes, exactly as rclone gives them:

              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.

💖 Rclone syncs your files to cloud storage ✨

• About rclone
• What can rclone do for you?
• What features does rclone have?
• What providers does rclone support?
• Download — https://rclone.org/downloads/
• Install — https://rclone.org/install/
• Donate — https://rclone.org/donate/

---

🌸 About rclone 🌸

okay so bestie, rclone is a command-line program that manages your files on cloud storage, and it is a seriously feature-rich alternative to whatever sad little web storage interface your cloud vendor gave you. Over 70 cloud storage products support rclone, including S3 object stores, business & consumer file storage services, and plain old standard transfer protocols. no cap.

It's got powerful cloud equivalents to the unix commands rsync, cp, mv, mount, ls, ncdu, tree, rm, and cat. The syntax is familiar, it includes shell pipeline support, and there's --dry-run protection so you don't accidentally nuke your whole drive 😭. You can use it at the command line, in scripts, or through its API.

Users literally call rclone "The Swiss army knife of cloud storage", and "Technology indistinguishable from magic". iconic behavior, honestly. 💅

Rclone really looks after your data. It preserves timestamps and verifies checksums at all times. Transfers over limited bandwidth, intermittent connections, or transfers subject to quota can be restarted — from the last good file that got transferred 🫶. You can check (https://rclone.org/commands/rclone_check/) the integrity of your files. And where possible, rclone employs server-side transfers to minimise your local bandwidth use, plus transfers from one provider to another without ever touching local disk. it's giving efficiency.

Virtual backends wrap local and cloud file systems so you can apply encryption (https://rclone.org/crypt/), compression (https://rclone.org/compress/), chunking (https://rclone.org/chunker/), hashing (https://rclone.org/hasher/) and joining (https://rclone.org/union/). 💫

Rclone mounts (https://rclone.org/commands/rclone_mount/) any local, cloud or virtual filesystem as a disk on Windows, macOS, linux and FreeBSD, and also serves these over SFTP (https://rclone.org/commands/rclone_serve_sftp/), HTTP (https://rclone.org/commands/rclone_serve_http/), WebDAV (https://rclone.org/commands/rclone_serve_webdav/), FTP (https://rclone.org/commands/rclone_serve_ftp/) and DLNA (https://rclone.org/commands/rclone_serve_dlna/).

Rclone is mature, open-source software originally inspired by rsync and written in Go (https://golang.org). The friendly support community is familiar with varied use cases. Official Ubuntu, Debian, Fedora, Brew and Chocolatey repos include rclone. But for the latest version, downloading from rclone.org (https://rclone.org/downloads/) 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 rclone does the heavy lifting of communicating with cloud storage. main character energy tbh. 👑

---

💅 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 (https://rclone.org/commands/rclone_lsf/), ljson (https://rclone.org/commands/rclone_lsjson/), size (https://rclone.org/commands/rclone_size/), ncdu (https://rclone.org/commands/rclone_ncdu/)
• Union (https://rclone.org/union/) file systems together to present multiple local and/or cloud file systems as one

---

✨ 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 (https://rclone.org/commands/rclone_copy/) new or changed files to cloud storage
• Sync (https://rclone.org/commands/rclone_sync/) (one way) to make a directory identical
• Bisync (https://rclone.org/bisync/) (two way) to keep two directories in sync bidirectionally
• Move (https://rclone.org/commands/rclone_move/) files to cloud storage deleting the local after verification
• Check (https://rclone.org/commands/rclone_check/) hashes and for missing/extra files
• Mount (https://rclone.org/commands/rclone_mount/) your cloud storage as a network disk
• Serve (https://rclone.org/commands/rclone_serve/) local or remote files over HTTP (https://rclone.org/commands/rclone_serve_http/)/WebDav (https://rclone.org/commands/rclone_serve_webdav/)/FTP (https://rclone.org/commands/rclone_serve_ftp/)/SFTP (https://rclone.org/commands/rclone_serve_sftp/)/DLNA (https://rclone.org/commands/rclone_serve_dlna/)
• Experimental Web based GUI (https://rclone.org/gui/)

---

🦋 Supported providers 🦋

(There are many others, built on standard protocols such as WebDAV or S3, that work out of the box. slay.)

• 1Fichier
• Akamai Netstorage
• Alibaba Cloud (Aliyun) Object Storage System (OSS)
• Amazon S3
• Bizfly Cloud Simple Storage
• Backblaze B2
• Box
• Ceph
• China Mobile Ecloud Elastic Object Storage (EOS)
• Arvan Cloud Object Storage (AOS)
• Citrix ShareFile
• Cloudflare R2
• Cloudinary
• Cubbit DS3
• DigitalOcean Spaces
• Digi Storage
• Dreamhost
• Drime
• Dropbox
• Enterprise File Fabric
• Exaba
• Fastly Object Storage
• Fastmail Files
• FileLu Cloud Storage
• FileLu S5 (S3-Compatible Object Storage)
• Filen
• Files.com
• FlashBlade
• FTP
• Gofile
• Google Cloud Storage
• Google Drive
• Google Photos
• HDFS
• Hetzner Object Storage
• Hetzner Storage Box
• HiDrive
• Hitachi Content Platform (HCP)
• HTTP
• Huawei Drive
• Huawei OBS
• iCloud Drive
• ImageKit
• Internet Archive
• Internxt
• Jottacloud
• IBM COS S3
• IDrive e2
• Impossible Cloud
• Intercolo Object Storage
• IONOS Cloud
• Koofr
• Leviia Object Storage
• Liara Object Storage
• Linkbox
• Linode Object Storage
• Magalu
• Mail.ru Cloud
• Memset Memstore
• MEGA
• MEGA S4
• Memory
• Microsoft Azure Blob Storage
• Microsoft Azure Files Storage
• Microsoft OneDrive
• Minio
• Nextcloud
• Blomp Cloud Storage
• OpenDrive
• OpenStack Swift
• Oracle Cloud Storage Swift
• Oracle Object Storage
• Outscale
• OVHcloud Object Storage (Swift)
• OVHcloud Object Storage (S3-compatible)
• ownCloud
• pCloud
• Petabox
• PikPak
• Pixeldrain
• premiumize.me
• put.io
• Proton Drive
• QingStor
• Qiniu Cloud Object Storage (Kodo)
• Quatrix by Maytech
• Rabata Cloud Storage
• RackCorp Object Storage
• Rackspace Cloud Files
• Rclone Serve S3
• rsync.net
• Scaleway
• Scality (RING / ARTESCA)
• Seafile
• Seagate Lyve Cloud
• SeaweedFS
• Selectel
• Servercore Object Storage
• SFTP
• Shade
• Sia
• SMB / CIFS
• Spectra Logic
• Storj
• Synology
• SugarSync
• Tencent Cloud Object Storage (COS)
• Uloz.to
• US3
• Wasabi
• WebDAV
• Yandex Disk
• Zadara Object Storage
• Zero Services (ZERO-Z3)
• Zoho WorkDrive
• Zata
• The local filesystem

🧚 Virtual providers 🧚

These backends adapt or modify other storage providers. little remix artists, honestly:

• Alias: Rename existing remotes
• Archive: Read archive files
• 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

🌈 Links 🌈

• Home page (https://rclone.org/)
• GitHub project page for source and bug tracker (https://github.com/rclone/rclone)
• Rclone Forum (https://forum.rclone.org)
• Downloads (https://rclone.org/downloads/)

---

🎀 Install 🎀

Rclone is a Go program and comes as a single binary file. that's it. one file. no cap. 🫶

💜 Quickstart 💜

• Download (https://rclone.org/downloads/) the relevant binary.
• Extract the rclone executable, rclone.exe on Windows, from the archive.
• Run rclone config to setup. See rclone config docs (https://rclone.org/docs/) for more details.
• Optionally configure automatic execution.

See below for some expanded Linux / macOS / Windows instructions.

See the usage (https://rclone.org/docs/) docs for how to use rclone, or run rclone -h.

Already installed rclone can be easily updated to the latest version using the rclone selfupdate (https://rclone.org/commands/rclone_selfupdate/) command. so convenient, obsessed. ✨

See the release signing docs (https://rclone.org/release_signing/) for how to verify signatures on the release.

🌸 Script installation 🌸

To install rclone on Linux/macOS/BSD systems, run:

sudo -v ; curl https://rclone.org/install.sh | sudo bash

For beta installation, run:

sudo -v ; curl https://rclone.org/install.sh | sudo bash -s beta

Note that this script checks the version of rclone installed first and won't re-download if not needed. polite of it.

🍓 Linux installation 🍓

⭐ Precompiled binary ⭐

Fetch and unpack:

curl -O https://downloads.rclone.org/rclone-current-linux-amd64.zip
unzip rclone-current-linux-amd64.zip
cd rclone-*-linux-amd64

Copy binary file:

sudo cp rclone /usr/bin/
sudo chown root:root /usr/bin/rclone
sudo chmod 755 /usr/bin/rclone

Install manpage:

sudo mkdir -p /usr/local/share/man/man1
sudo cp rclone.1 /usr/local/share/man/man1/
sudo mandb

Run rclone config to setup. See rclone config docs (https://rclone.org/docs/) for more details.

rclone config

🦋 macOS installation 🦋

💖 Installation with brew 💖

brew install rclone

NOTE: This version of rclone will not support mount any more (see #5373 (https://github.com/rclone/rclone/issues/5373)). If mounting is wanted on macOS, either install a precompiled binary or enable the relevant option when installing from source. tragic but true 😭

Note bestie, this one is a third party installer — not something the rclone devs control — so it might be lowkey outdated. Its current version is right here:

[IMAGE: Homebrew package (https://repology.org/badge/version-for-repo/homebrew/rclone.svg)] (https://repology.org/project/rclone/versions)

✨ Installation with MacPorts ✨

On macOS you can also pull rclone in through MacPorts (https://www.macports.org):

sudo port install rclone

Girl, heads up: this is also a third party installer not controlled by the rclone developers, so it might be out of date. Its current version is as below.

[IMAGE: MacPorts port (https://repology.org/badge/version-for-repo/macports/rclone.svg)] (https://repology.org/project/rclone/versions)

More info lives over at macports.org (https://ports.macports.org/port/rclone/).

💖 Precompiled binary, using curl 💖

So the whole macOS gatekeeper situation — where it insists binaries be signed and notarized — the trick is literally just to download with curl. That's it. That's the hack. slay.

Download the latest version of rclone:

cd && curl -O https://downloads.rclone.org/rclone-current-osx-amd64.zip

Unzip the download and cd into the extracted folder:

unzip -a rclone-current-osx-amd64.zip && cd rclone-*-osx-amd64

Move rclone to your $PATH. It's gonna ask for your password:

sudo mkdir -p /usr/local/bin
sudo mv rclone /usr/local/bin/

(the mkdir command is safe to run, even if the directory already exists 🫶)

Remove the leftover files:

cd .. && rm -rf rclone-*-osx-amd64 rclone-current-osx-amd64.zip

Run rclone config to set everything up. Peep the rclone config docs (https://rclone.org/docs/) for more details:

rclone config

🦋 Precompiled binary, using a web browser 🦋

Okay so the moment you download a binary with a web browser, the browser slaps the macOS gatekeeper quarantine attribute on it. And starting from Catalina, when you try to run rclone, a pop-up shows up being all:

"rclone" cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware.

The simplest fix is just to run:

xattr -d com.apple.quarantine rclone

🌈 Windows installation 🌈

⭐ Precompiled binary ⭐

Grab the correct binary for your processor type by clicking these links. Not sure? Use the first one, no stress.

• Intel/AMD - 64 Bit (https://downloads.rclone.org/rclone-current-windows-amd64.zip)
• Intel/AMD - 32 Bit (https://downloads.rclone.org/rclone-current-windows-386.zip)
• ARM - 64 Bit (https://downloads.rclone.org/rclone-current-windows-arm64.zip)

Open this file in the Explorer and extract rclone.exe. Rclone is a portable executable, so you can drop it wherever is convenient for you.

Open a CMD window (or powershell) and run the binary. FYI rclone does not launch a GUI by default — it runs in the CMD Window, periodt.

• Run rclone.exe config to setup. See rclone config docs (https://rclone.org/docs/) for more details.
• Optionally configure automatic execution.

If you're planning to use the rclone mount (https://rclone.org/commands/rclone_mount/) feature, then you're also gonna need the third party utility WinFsp (https://winfsp.dev/). No cap.

🎀 Windows package manager (Winget) 🎀

Winget (https://learn.microsoft.com/en-us/windows/package-manager/) comes pre-installed with the latest versions of Windows. If it's not there, update the App Installer (https://www.microsoft.com/p/app-installer/9nblggh4nns1) package from the Microsoft store.

To install rclone:

winget install Rclone.Rclone

To uninstall rclone:

winget uninstall Rclone.Rclone --force

🍓 Chocolatey package manager 🍓

First, make sure you have Choco (https://chocolatey.org/) installed:

choco search rclone
choco install rclone

This will install rclone on your Windows machine. And if you're planning to use rclone mount (https://rclone.org/commands/rclone_mount/), then:

choco install winfsp

will install that too 💅

Note that this is a third party installer not controlled by the rclone developers so it may be out of date. Its current version is as below.

[IMAGE: Chocolatey package (https://repology.org/badge/version-for-repo/chocolatey/rclone.svg)] (https://repology.org/project/rclone/versions)

🧚 Scoop package manager 🧚

Make sure you have Scoop (https://scoop.sh/) installed first:

scoop install rclone

Note that this is a third party installer not controlled by the rclone developers so it may be out of date. Its current version is as below.

[IMAGE: Scoop package (https://repology.org/badge/version-for-repo/scoop/rclone.svg)] (https://repology.org/project/rclone/versions)

👑 Package manager installation 👑

So many Linux, Windows, macOS and other OS distributions package and distribute rclone.

The distributed versions of rclone are often quite out of date and for this reason we recommend one of the other installation methods if possible. fr fr, they're stale 😭

You can get an idea of how up to date or not your OS distribution's package is right here:

[IMAGE: Packaging status (https://repology.org/badge/vertical-allrepos/rclone.svg?columns=3)] (https://repology.org/project/rclone/versions)

💜 Docker installation 💜

The rclone developers maintain a docker image for rclone (https://hub.docker.com/r/rclone/rclone).

These images are built as part of the release process based on a minimal Alpine Linux.

The :latest tag will always point to the latest stable release. You can use the :beta tag to get the latest build from master. You can also use version tags, e.g. :1.49.1, :1.49 or :1.

$ docker pull rclone/rclone:latest
latest: Pulling from rclone/rclone
Digest: sha256:0e0ced72671989bb837fea8e88578b3fc48371aa45d209663683e24cfdaa0e11
...
$ docker run --rm rclone/rclone:latest version
rclone v1.49.1
- os/arch: linux/amd64
- go version: go1.12.9

There are a few command line options to consider when starting an rclone Docker container from the rclone image:

• You need to mount the host rclone config dir at /config/rclone into the Docker container. Due to the fact that rclone updates tokens inside its config file, and that the update process involves a file rename, you need to mount the whole host rclone config dir, not just the single host rclone config file.
• You need to mount a host data dir at /data into the Docker container.
• By default, the rclone binary inside a Docker container runs with UID=0 (root). As a result, all files created in a run will have UID=0. If your config and data files reside on the host with a non-root UID:GID, you need to pass these on the container start command line.
• If you want to access the RC interface (either via the API or the Web UI), it is required to set the --rc-addr to :5572 in order to connect to it from outside the container. An explanation about why this is necessary can be found in an old pythonspeed.com (https://web.archive.org/web/20200808071950/https://pythonspeed.com/articles/docker-connection-refused/) article.
  • NOTE: Users running this container with the docker network set to host should probably set it to listen to localhost only, with 127.0.0.1:5572 as the value for --rc-addr
• It is possible to use rclone mount inside a userspace Docker container, and expose the resulting fuse mount to the host. The exact docker run options to do that might vary slightly between hosts. See, e.g. the discussion in this thread (https://github.com/moby/moby/issues/9448).
  • You also need to mount the host /etc/passwd and /etc/group for fuse to work inside the container.

Here are some commands tested on an Ubuntu 18.04.3 host:

# config on host at ~/.config/rclone/rclone.conf
# data on host at ~/data

# add a remote interactively
docker run --rm -it \
    --volume ~/.config/rclone:/config/rclone \
    --user $(id -u):$(id -g) \
    rclone/rclone \
    config

# make sure the config is ok by listing the remotes
docker run --rm \
    --volume ~/.config/rclone:/config/rclone \
    --user $(id -u):$(id -g) \
    rclone/rclone \
    listremotes

# perform mount inside Docker container, expose result to host
mkdir -p ~/data/mount
docker run --rm \
    --volume ~/.config/rclone:/config/rclone \
    --volume ~/data:/data:shared \
    --user $(id -u):$(id -g) \
    --volume /etc/passwd:/etc/passwd:ro --volume /etc/group:/etc/group:ro \
    --device /dev/fuse --cap-add SYS_ADMIN --security-opt apparmor:unconfined \
    rclone/rclone \
    mount dropbox:Photos /data/mount &
ls ~/data/mount
kill %1

🌸 Snap installation 🌸

[IMAGE: Get it from the Snap Store (https://snapcraft.io/static/images/badges/en/snap-store-black.svg)] (https://snapcraft.io/rclone)

Make sure you have Snapd installed (https://snapcraft.io/docs/installing-snapd):

sudo snap install rclone

Due to the strict confinement of Snap, rclone snap cannot access the real /home/$USER/.config/rclone directory — default config path is as below. 🙈

• Default config directory:
  • /home/$USER/snap/rclone/current/.config/rclone

Note: Due to the strict confinement of Snap, the rclone mount feature is not supported. 💀

If mounting is wanted, either install a precompiled binary or enable the relevant option when installing from source.

Note that this is controlled by community maintainer (https://github.com/boukendesho/rclone-snap) not the rclone developers so it may be out of date. Its current version is as below.

[IMAGE: rclone (https://snapcraft.io/rclone/badge.svg)] (https://snapcraft.io/rclone)

🔥 Source installation 🔥

Make sure you have git and Go (https://golang.org/) installed. Go version 1.26 or newer is required, the latest release is recommended. You can get it from your package manager, or download it from golang.org/dl (https://golang.org/dl/). Then you can run the following:

git clone https://github.com/rclone/rclone.git
cd rclone
go build

This will check out the rclone source in subfolder rclone, which you can later modify and send pull requests with. Then it will build the rclone executable in the same folder. As an initial check you can now run ./rclone version (.\rclone version on Windows). Iconic.

Note that on macOS and Windows the mount (https://rclone.org/commands/rclone_mount/) command will not be available unless you specify an additional build tag cmount. 😭

go build -tags cmount

okay so this whole thing assumes you have a GCC compatible C compiler (GCC or Clang) chilling in your PATH, because it uses cgo (https://pkg.go.dev/cmd/cgo). But on Windows there's a plot twist bestie: the cgofuse (https://github.com/winfsp/cgofuse) library that the cmount implementation is based on also supports building without cgo (https://github.com/golang/go/wiki/WindowsDLLs) — like, you just set the environment variable CGO_ENABLED to value 0 (that's static linking, periodt). That is literally how the official Windows release of rclone is being built, starting with version 1.59. And yes, it is still possible to build with cgo on Windows as well, by using the MinGW port of GCC, e.g. by installing it in an MSYS2 (https://www.msys2.org) distribution — just make sure you install it in the classic mingw64 subsystem, because the ucrt64 version is not compatible, no cap.

Additionally, to build with mount on Windows, you must install the third party utility WinFsp (https://winfsp.dev/), with the "Developer" feature selected. If you're building with cgo, you must also set the environment variable CPATH pointing to the fuse include directory within the WinFsp installation (normally C:\Program Files (x86)\WinFsp\inc\fuse).

You may add arguments -ldflags -s to omit symbol table and debug information, making the executable file smaller, and -trimpath to remove references to local file system paths. The official rclone releases are built with both of these. Iconic behaviour honestly 💅

go build -trimpath -ldflags -s -tags cmount

If you want to customize the version string, as reported by the rclone version command, you can set one of the variables fs.Version, fs.VersionTag (to keep default suffix but customize the number), or fs.VersionSuffix (to keep default number but customize the suffix). This can be done from the build command, by adding to the -ldflags argument value as shown below.

go build -trimpath -ldflags "-s -X github.com/rclone/rclone/fs.Version=v9.9.9-test" -tags cmount

On Windows, the official executables also have the version information, as well as a file icon, embedded as binary resources. To get that with your own build you need to run the following command before the build command. It generates a Windows resource system object file, with extension .syso, e.g. resource_windows_amd64.syso, that will be automatically picked up by future build commands. Magic fr fr ✨

go run bin/resource_windows.go

The above command will generate a resource file containing version information based on the fs.Version variable in source at the time you run the command, which means if the value of this variable changes you need to re-run the command for it to be reflected in the version information. Also, if you override this version variable in the build command as described above, you need to do that also when generating the resource file, or else it will still use the value from the source. So like, keep them in sync bestie 🙈

go run bin/resource_windows.go -version v9.9.9-test

Instead of executing the go build command directly, you can run it via the Makefile. The default target changes the version suffix from "-DEV" to "-beta" followed by additional commit details, embeds version information binary resources on Windows, and copies the resulting rclone executable into your GOPATH bin folder ($(go env GOPATH)/bin, which corresponds to ~/go/bin/rclone by default).

make

To include mount command on macOS and Windows with Makefile build:

make GOTAGS=cmount

There are other make targets that can be used for more advanced builds, such as cross-compiling for all supported os/architectures, and packaging results into release artifacts. See Makefile (https://github.com/rclone/rclone/blob/master/Makefile) and cross-compile.go (https://github.com/rclone/rclone/blob/master/bin/cross-compile.go) for details.

---

Another alternative method for source installation is to download the source, build and install rclone — all in one operation, as a regular Go package. The source will be stored it in the Go module cache, and the resulting executable will be in your GOPATH bin folder ($(go env GOPATH)/bin, which corresponds to ~/go/bin/rclone by default). One command, zero drama 🫶

go install github.com/rclone/rclone@latest

In some situations, rclone executable size might be too big for deployment in very restricted environments when all backends with large SDKs are included. To limit binary size unused backends can be commented out in backends/all/all.go and unused commands in cmd/all/all.go before building with go build or make. Declutter era 💀

Ansible installation 🧚

This can be done with Stefan Weichinger's ansible role (https://github.com/stefangweichinger/ansible-rclone).

Instructions

1. git clone https://github.com/stefangweichinger/ansible-rclone.git into your local roles-directory
2. add the role to the hosts you want rclone installed to:

- hosts: rclone-hosts
  roles:
    - rclone

Portable installation 🎒

As mentioned above (https://rclone.org/install/#quickstart), rclone is single executable (rclone, or rclone.exe on Windows) that you can download as a zip archive and extract into a location of your choosing. When executing different commands, it may create files in different locations, such as a configuration file and various temporary files. By default the locations for these are according to your operating system, e.g. configuration file in your user profile directory and temporary files in the standard temporary directory, but you can customize all of them, e.g. to make a completely self-contained, portable installation. Main character energy, honestly 🌈

Run the config paths command (https://rclone.org/commands/rclone_config_paths/) to see the locations that rclone will use.

To override them set the corresponding options (as command-line arguments, or as environment variables (https://rclone.org/docs/#environment-variables)):

• --config — (https://rclone.org/docs/#config-string)
• --cache-dir — (https://rclone.org/docs/#cache-dir-string)
• --temp-dir — (https://rclone.org/docs/#temp-dir-string)

Autostart ⏰

After installing and configuring rclone, as described above, you are ready to use rclone as an interactive command line utility. If your goal is to perform periodic operations, such as a regular sync (https://rclone.org/commands/rclone_sync/), you will probably want to configure your rclone command in your operating system's scheduler. If you need to expose service-like features, such as remote control (https://rclone.org/rc/), GUI (https://rclone.org/gui/), serve (https://rclone.org/commands/rclone_serve/) or mount (https://rclone.org/commands/rclone_mount/), you will often want an rclone command always running in the background, and configuring it to run in a service infrastructure may be a better option. Below are some alternatives on how to achieve this on different operating systems.

NOTE: Before setting up autorun it is highly recommended that you have tested your command manually from a Command Prompt first. Please bestie, test it by hand first, I am begging 🙏

Autostart on Windows 🪟

The most relevant alternatives for autostart on Windows are:

• Run at user log on using the Startup folder
• Run at user log on, at system startup or at schedule using Task Scheduler
• Run at system startup using Windows service

Running in background 🌙

Rclone is a console application, so if not starting from an existing Command Prompt, e.g. when starting rclone.exe from a shortcut, it will open a Command Prompt window. When configuring rclone to run from task scheduler and windows service you are able to set it to run hidden in background. From rclone version 1.54 you can also make it run hidden from anywhere by adding option --no-console (it may still flash briefly when the program starts). Since rclone normally writes information and any error messages to the console, you must redirect this to a file to be able to see it. Rclone has a built-in option --log-file for that. Sneaky invisible rclone, lowkey iconic 👑

Example command to run a sync in background:

c:\rclone\rclone.exe sync c:\files remote:/files --no-console --log-file c:\rclone\logs\sync_files.txt

User account 👤

As mentioned in the mount (https://rclone.org/commands/rclone_mount/) documentation, mounted drives created as Administrator are not visible to other accounts, not even the account that was elevated as Administrator. By running the mount command as the built-in SYSTEM user account, it will create drives accessible for everyone on the system. Both scheduled task and Windows service can be used to achieve this.

NOTE: Remember that when rclone runs as the SYSTEM user, the user profile that it sees will not be yours. This means that if you normally run rclone with configuration file in the default location, to be able to use the same configuration when running as the system user you must explicitly tell rclone where to find it with the --config (https://rclone.org/docs/#config-string) option, or else it will look in the system users profile path (C:\Windows\System32\config\systemprofile). To test your command manually from a Command Prompt, you can run it with the PsExec (https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) utility from Microsoft's Sysinternals suite, which takes option -s to execute commands as the SYSTEM user.

Start from Startup folder 📂

To quickly execute an rclone command you can simply create a standard Windows Explorer shortcut for the complete rclone command you want to run. If you store this shortcut in the special "Startup" start-menu folder, Windows will automatically run it at login. To open this folder in Windows Explorer, enter path %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup, or C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp if you want the command to start for every user that logs in.

This is the easiest approach to autostarting of rclone, but it offers no functionality to set it to run as different user, or to set conditions or actions on certain events. Setting up a scheduled task as described below will often give you better results. Easy mode now, upgrade later ✨

Start from Task Scheduler 🗓

Task Scheduler is an administrative tool built into Windows, and it can be used to configure rclone to be started automatically in a highly configurable way, e.g. periodically on a schedule, on user log on, or at system startup. It can run be configured to run as the current user, or for a mount command that needs to be available to all users it can run as the SYSTEM user. For technical information, see Task Scheduler for developers (https://docs.microsoft.com/windows/win32/taskschd/task-scheduler-start-page).

Run as service ⚙️

For running rclone at system startup, you can create a Windows service that executes your rclone command, as an alternative to scheduled task configured to run at startup.

🖥️ Mount command built-in service integration 🖥️

ok so for mount commands specifically, rclone has Windows service integration built right in, courtesy of the third-party WinFsp library it uses. Registering as a regular Windows service is easy peasy — you literally just run the built-in PowerShell command New-Service (heads up: this needs administrative privileges, bestie, no way around it).

Here's an example PowerShell command that creates a Windows service for mounting some remote:/files as drive letter X:, for all users (the service will be running as the local system account):

New-Service -Name Rclone -BinaryPathName 'c:\rclone\rclone.exe mount remote:/files X: --config c:\rclone\config\rclone.conf --log-file c:\rclone\logs\mount.txt'

The WinFsp service infrastructure (https://github.com/billziss-gh/winfsp/wiki/WinFsp-Service-Architecture) supports incorporating services for file system implementations, such as rclone, into its own launcher service, as kind of "child services". The glow-up here? It also implements a network provider that integrates into Windows standard methods for managing network drives. This is currently not officially supported by Rclone, but with WinFsp version 2019.3 B2 / v1.5B2 or later it should be possible through path rewriting as described in #3340 (https://github.com/rclone/rclone/issues/3340).

🧰 Third-party service integration 🧰

Wanna run any rclone command as a Windows service? There's the excellent third-party utility NSSM (http://nssm.cc), aka the "Non-Sucking Service Manager". It comes with some advanced features like adjusting process priority, defining process environment variables, redirecting anything written to stdout to a file, and customized response to different exit codes — plus a GUI to configure literally everything from (although it can also be used from command line).

There are also several other alternatives. To mention one more, WinSW (https://github.com/winsw/winsw), "Windows Service Wrapper", is worth checking out. It requires .NET Framework, but it's preinstalled on newer versions of Windows, and it also provides alternative standalone distributions which include the necessary runtime (.NET 5). WinSW is a command-line only utility, where you have to manually create an XML file with the service configuration. This may be a drawback for some, but it can also be an advantage since it's easy to back up and reuse the configuration settings, without having to go through manual steps in a GUI. One thing to note: by default it does not restart the service on error, you have to explicitly enable this in the configuration file (via the "onfailure" parameter). 🙈

🌸 Autostart on Linux 🌸

⭐ Start as a service ⭐

If you want rclone to always run in the background — super relevant for mount commands and stuff — you can use systemd to set up rclone as a system or user service. Running as a system service ensures that it gets run at startup even if the user it's running as has no active session. Running rclone as a user service ensures that it only starts after the configured user has logged into the system.

🕰️ Run periodically from cron 🕰️

Wanna run a periodic command, like a copy/sync? Set up a cron job, bestie. ez.

---

✨ Usage ✨

Rclone is a command line program to manage files on cloud storage. After downloading (https://rclone.org/downloads/) and installing, continue here to learn how to use it: initial configuration, what the basic syntax looks like, the various subcommands, the various options, and more. 🫶

🎀 Configure 🎀

First things first: you'll need to configure rclone. Since object storage systems have quite complicated authentication, all that stuff is kept 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

See the following for detailed instructions for 💖

• 1Fichier (https://rclone.org/fichier/)
• Akamai Netstorage (https://rclone.org/netstorage/)
• Alias (https://rclone.org/alias/)
• Archive (https://rclone.org/archive/)
• Amazon S3 (https://rclone.org/s3/)
• Backblaze B2 (https://rclone.org/b2/)
• Box (https://rclone.org/box/)
• Chunker (https://rclone.org/chunker/) - transparently splits large files for other remotes
• Citrix ShareFile (https://rclone.org/sharefile/)
• Compress (https://rclone.org/compress/)
• Cloudinary (https://rclone.org/cloudinary/)
• Combine (https://rclone.org/combine/)
• Crypt (https://rclone.org/crypt/) - to encrypt other remotes
• DigitalOcean Spaces (https://rclone.org/s3/#digitalocean-spaces)
• Digi Storage (https://rclone.org/koofr/#digi-storage)
• Drime (https://rclone.org/drime/)
• Dropbox (https://rclone.org/dropbox/)
• Enterprise File Fabric (https://rclone.org/filefabric/)
• FileLu Cloud Storage (https://rclone.org/filelu/)
• Filen (https://rclone.org/filen/)
• Files.com (https://rclone.org/filescom/)
• FTP (https://rclone.org/ftp/)
• Gofile (https://rclone.org/gofile/)
• Google Cloud Storage (https://rclone.org/googlecloudstorage/)
• Google Drive (https://rclone.org/drive/)
• Google Photos (https://rclone.org/googlephotos/)
• Hasher (https://rclone.org/hasher/) - to handle checksums for other remotes
• HDFS (https://rclone.org/hdfs/)
• Hetzner Storage Box (https://rclone.org/sftp/#hetzner-storage-box)
• HiDrive (https://rclone.org/hidrive/)
• HTTP (https://rclone.org/http/)
• Huawei Drive (https://rclone.org/huaweidrive/)
• iCloud Drive (https://rclone.org/iclouddrive/)
• Internet Archive (https://rclone.org/internetarchive/)
• Internxt (https://rclone.org/internxt/)
• Jottacloud (https://rclone.org/jottacloud/)
• Koofr (https://rclone.org/koofr/)
• Linkbox (https://rclone.org/linkbox/)
• Mail.ru Cloud (https://rclone.org/mailru/)
• Mega (https://rclone.org/mega/)
• Memory (https://rclone.org/memory/)
• Microsoft Azure Blob Storage (https://rclone.org/azureblob/)
• Microsoft Azure Files Storage (https://rclone.org/azurefiles/)
• Microsoft OneDrive (https://rclone.org/onedrive/)
• OpenStack Swift / Rackspace Cloudfiles / Blomp Cloud Storage / Memset Memstore (https://rclone.org/swift/)
• OpenDrive (https://rclone.org/opendrive/)
• Oracle Object Storage (https://rclone.org/oracleobjectstorage/)
• Pcloud (https://rclone.org/pcloud/)
• PikPak (https://rclone.org/pikpak/)
• Pixeldrain (https://rclone.org/pixeldrain/)
• premiumize.me (https://rclone.org/premiumizeme/)
• put.io (https://rclone.org/putio/)
• Proton Drive (https://rclone.org/protondrive/)
• QingStor (https://rclone.org/qingstor/)
• Quatrix by Maytech (https://rclone.org/quatrix/)
• rsync.net (https://rclone.org/sftp/#rsync-net)
• Seafile (https://rclone.org/seafile/)
• SFTP (https://rclone.org/sftp/)
• Shade (https://rclone.org/shade/)
• Sia (https://rclone.org/sia/)
• SMB (https://rclone.org/smb/)
• Storj (https://rclone.org/storj/)
• SugarSync (https://rclone.org/sugarsync/)
• Union (https://rclone.org/union/)
• Uloz.to (https://rclone.org/ulozto/)
• WebDAV (https://rclone.org/webdav/)
• Yandex Disk (https://rclone.org/yandex/)
• Zoho WorkDrive (https://rclone.org/zoho/)
• The local filesystem (https://rclone.org/local/)

🌈 Basic syntax 🌈

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

Its syntax is like this:

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

A subcommand is an rclone operation, and it's required (e.g. sync, copy, ls).

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, so breathe. 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. Anything after a -- option will not be interpreted as an option, so if you need to add a parameter which starts with a - then put a -- on its own first, eg

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

A parameter is usually a file path or rclone remote, eg /path/to/file or remote:path/to/file, but it can be other things — the subcommand help will tell you what. 👀

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.

You can define as many storage paths as you like in the config file. Go off. 🌟

Please use the --interactive/-i flag while learning rclone to avoid accidental data loss. bestie pls, protect ur files 😭

👑 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

okay bestie, this is THE command, the one you'll be living in. 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. 🦋

rclone config [flags]

💅 Options 💅

• -h, --help — help for config

See the global flags page (https://rclone.org/flags/) for global options not listed here. 🌸

🫶 See Also 🫶

• rclone — Show help for rclone commands, flags and backends. → https://rclone.org/commands/rclone/
• rclone config create — Create a new remote with name, type and options. → https://rclone.org/commands/rclone_config_create/
• rclone config delete — Delete an existing remote. → https://rclone.org/commands/rclone_config_delete/
• rclone config disconnect — Disconnects user from remote → https://rclone.org/commands/rclone_config_disconnect/
• rclone config dump — Dump the config file as JSON. → https://rclone.org/commands/rclone_config_dump/
• rclone config edit — Enter an interactive configuration session. → https://rclone.org/commands/rclone_config_edit/
• rclone config encryption — set, remove and check the encryption for the config file → https://rclone.org/commands/rclone_config_encryption/
• rclone config file — Show path of configuration file in use. → https://rclone.org/commands/rclone_config_file/
• rclone config password — Update password in an existing remote. → https://rclone.org/commands/rclone_config_password/
• rclone config paths — Show paths used for configuration, cache, temp etc. → https://rclone.org/commands/rclone_config_paths/
• rclone config providers — List in JSON format all the providers and options. → https://rclone.org/commands/rclone_config_providers/
• rclone config reconnect — Re-authenticates user with remote. → https://rclone.org/commands/rclone_config_reconnect/
• rclone config redacted — Print redacted (decrypted) config file, or the redacted config for a single remote. → https://rclone.org/commands/rclone_config_redacted/
• rclone config show — Print (decrypted) config file, or the config for a single remote. → https://rclone.org/commands/rclone_config_show/
• rclone config string — Print connection string for a single remote. → https://rclone.org/commands/rclone_config_string/
• rclone config touch — Ensure configuration file exists. → https://rclone.org/commands/rclone_config_touch/
• rclone config unset — Unset options in an existing remote. → https://rclone.org/commands/rclone_config_unset/
• rclone config update — Update options in an existing remote. → https://rclone.org/commands/rclone_config_update/
• rclone config userinfo — Prints info about logged in user of remote. → https://rclone.org/commands/rclone_config_userinfo/

---

🦋 rclone copy

Copy files from source to dest, skipping identical files. lowkey the daily driver fr fr 💖

✨ Synopsis ✨

Copy the source to the destination. Does not transfer files that are identical on source and destination, testing by size and modification time or MD5SUM. Doesn't delete files from the destination. If you want to also delete files from destination, to make it match source, use the sync (https://rclone.org/commands/rclone_sync/) command instead. 😤

Note that it is always the contents of the directory that is synced, not the directory itself. So when source:path is a directory, it's the contents of source:path that are copied, not the directory name and contents. read that twice bestie, it matters. 👀

To copy single files, use the copyto (https://rclone.org/commands/rclone_copyto/) command instead.

If dest:path doesn't exist, it is created and the source:path contents go there. ✨

For example

rclone copy source:sourcepath dest:destpath

Let's say there are two files in sourcepath

sourcepath/one.txt
sourcepath/two.txt

This copies them to

destpath/one.txt
destpath/two.txt

Not to

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

If you are familiar with rsync, rclone always works as if you had written a trailing / — meaning "copy the contents of this directory". This applies to all commands and whether you are talking about the source or destination. iconic behaviour, no notes. 💅

See the --no-traverse (https://rclone.org/docs/#no-traverse) option for controlling whether rclone lists the destination directory or not. Supplying this option when copying a small number of files into a large destination can speed transfers up greatly. 🚀

For example, if you have many files in /path/to/src but only a few of them change every day, you can copy all the files which have changed recently very efficiently like this:

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

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. 🕰️

Note that the modification time and metadata for the root directory will not be synced. See issue #7652 (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 --dry-run or the --interactive/-i flag to test without copying anything. 🙈

🪵 Logger Flags 🪵

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 --dest-after flag writes a list file using the same format flags as lsf (https://rclone.org/commands/rclone_lsf/#synopsis) (including customizable options for hash, modtime, etc. (https://rclone.org/commands/rclone_lsf/#synopsis)) 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 command is finished. 🔮

When the --no-traverse flag is set, all logs involving files that exist only on the destination will be incomplete or completely missing. 💀

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

Note also that each file is logged during execution, 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 copy 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 copy
• --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 copy
• --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 - see docs for details (default: 2006-01-02 15:04:05)

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) for global options not listed here. 🌈

🌸 Copy Options 🌸

Flags for anything which can copy a file

• --check-first — does literally all the checks before it even thinks about starting transfers ✨
• -c, --checksum — peeps for changes using size & checksum (or if checksums aren't a thing, it falls back to size only, ngl)
• --compare-dest stringArray — toss in extra server-side paths so they get compared too
• --copy-dest stringArray — it's giving --compare-dest but it also copies files from those paths into the destination 👑
• --cutoff-mode HARD|SOFT|CAUTIOUS — the mode for when transfers get stopped after hitting the max transfer limit, and your choices are HARD|SOFT|CAUTIOUS (default HARD)
• --ignore-case-sync — ignore case when synchronizing
• --ignore-checksum — skips the post-copy checksum check, no cap
• --ignore-existing — skips every file that already exists on the destination
• --ignore-size — pretend size doesn't matter when skipping, use modtime or checksum instead
• -I, --ignore-times — does NOT skip stuff that matches on size and time — it transfers everything unconditionally 🫶
• --immutable — do not modify files, and if existing files have been modified it just fails
• --inplace — downloads straight into the destination file instead of the whole atomic download-to-temp-then-rename thing
• -l, --links — translates symlinks to/from regular files, using a .rclonelink extension
• --max-backlog int — max number of objects chilling in the sync or check backlog (default 10000)
• --max-duration Duration — the maximum duration rclone will transfer data for (default 0s)
• --max-transfer SizeSuffix — maximum size of data to transfer (default off)
• -M, --metadata — if you set it, metadata gets preserved when copying objects 💖
• --modify-window Duration — max time diff that still counts as "same" (default 1ns)
• --multi-thread-chunk-size SizeSuffix — chunk size for multi-thread downloads/uploads, unless the filesystem says otherwise (default 64Mi)
• --multi-thread-cutoff SizeSuffix — files bigger than this get multi-thread downloads (default 256Mi)
• --multi-thread-streams int — how many streams multi-thread downloads get (default 4)
• --multi-thread-write-buffer-size SizeSuffix — the in-memory buffer size for writing while in multi-thread mode (default 128Ki)
• --name-transform stringArray — transform paths during the copy process
• --no-check-dest — don't check the destination at all, just copy regardless
• --no-traverse — don't traverse the destination file system on copy
• --no-update-dir-modtime — don't update directory modification times
• --no-update-modtime — if the files are identical, don't touch the destination modtime
• --order-by string — instructions on how to order the transfers, like 'size,descending'
• --partial-suffix string — adds partial-suffix to the temporary file name when --inplace is not used (default ".partial")
• --refresh-times — refreshes the modtime of remote files
• --server-side-across-configs — lets server-side operations (e.g. copy) work across different configs
• --size-only — skips based on size only, not modtime or checksum
• --streaming-upload-cutoff SizeSuffix — the cutoff for switching to chunked upload when the file size is unknown; the upload starts after it hits the cutoff or when the file ends (default 100Ki)
• -u, --update — skips files that are newer on the destination

✨ Important Options ✨

Important flags that are lowkey useful for most commands 💅

• -n, --dry-run — does a trial run with no permanent changes
• -i, --interactive — turns on interactive mode
• -v, --verbose count — prints lots more stuff (repeat it for even more)

🌸 Filter Options 🌸

Flags for filtering directory listings 🎀

• --delete-excluded — deletes files on the destination that were excluded from the sync
• --exclude stringArray — excludes files matching the pattern
• --exclude-from stringArray — reads file exclude patterns from a file (use - to read from stdin)
• --exclude-if-present stringArray — excludes directories if that filename is present
• --files-from stringArray — reads the list of source-file names from a file (use - to read from stdin)
• --files-from-raw stringArray — reads the list of source-file names from a file without any processing of the lines (use - to read from stdin)
• --files-from0 stringArray — reads the list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partitions filenames by hash as k/n or randomly as @/n
• --ignore-case — ignores case in filters (so it's case insensitive)
• --include stringArray — includes files matching the pattern
• --include-from stringArray — reads file include patterns from a file (use - to read from stdin)
• --max-age Duration — only transfers files younger than this, in s or with the suffix 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 transfers files smaller than this, in KiB or with the suffix B|K|M|G|T|P (default off)
• --metadata-exclude stringArray — excludes metadatas matching the 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 the 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 the suffix ms|s|m|h|d|w|M|y (default off)
• --min-size SizeSuffix — only transfers files bigger than this, in KiB or with the suffix B|K|M|G|T|P (default off)

🦋 Listing Options 🦋

Flags for listing directories, bestie 💜

• --default-time Time — the time to show if the modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
• --fast-list — uses a recursive list if it's available; eats more memory but does fewer transactions

⭐ See Also ⭐

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

👑 rclone sync 👑

Make source and dest identical, modifying destination only. Periodt. 💅

🌈 Synopsis 🌈

Syncs the source to the destination, and it only changes the destination. It does not transfer files that are identical on source and destination — it tests that with size and modification time, or MD5SUM. The destination gets updated to match the source, and yes, that includes deleting files if it has to (except duplicate objects, more on that below 👇). If you do not want files deleted from the destination, use the copy (https://rclone.org/commands/rclone_copy/) command instead.

Important: because this can cause data loss, test it first with the --dry-run or the --interactive/-i flag. Not me being dramatic, this is real 😭

rclone sync --interactive SOURCE remote:DESTINATION

Files in the destination won't get deleted if there were any errors at any point. Duplicate objects (files with the same name, on those providers that support it) are not yet handled. Files that are excluded won't be deleted unless --delete-excluded is used. Symlinks won't be transferred or deleted from local file systems unless --links is used.

It is always the contents of the directory that get synced, not the directory itself. So when source:path is a directory, it's the contents of source:path that get copied, not the directory name and contents. Peep the extended explanation in the copy (https://rclone.org/commands/rclone_copy/) command if you're unsure 🫶

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

It is not possible to sync overlapping remotes. But — plot twist — 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 syncing to a destination that's inside the source directory. Slay.

Rclone will sync the modification times of files and directories if the backend supports it. And if you need metadata syncing, 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 (https://forum.rclone.org/t/sync-not-clearing-duplicates/14372) 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 supply (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 the file paths with a symbol, then a space, then the path, to tell you what happened to it. These are giving total diff file energy 💅

• = path means path was found in source and destination and was identical
• - path means path was missing on the source, so it only exists in the destination
• + path means path was missing on the destination, so it only exists 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, and it uses the exact same format flags as lsf (including all the customizable options for hash, modtime, etc. — go peek at the lsf synopsis if you wanna know the vibes). Conceptually it's giving rsync's --itemize-changes, but bestie it is not identical — what it actually does is output an accurate list of what's gonna be sitting on the destination once the command finishes. 🎀

When you've got the --no-traverse flag set, literally all logs involving files that exist only on the destination will be incomplete or completely missing. So like… keep that in mind. 💀

Also, heads up — these logger flags come with a few limitations, and certain scenarios are just not supported right now:

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

And one more thing: each file is logged during execution, not after. So it's most useful as a predictor of what SHOULD happen to each file — which, fair warning, 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 - see docs for details (default: 2006-01-02 15:04:05)

Options shared with other commands are described next. And for global options that aren't listed here, go check the global flags page — they live over there. 🫶

🌈 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)
• --name-transform stringArray — Transform paths during the copy process
• --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
• --list-cutoff int — To save memory, sort directory listings on disk above this threshold (default 1000000)
• --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 — 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

okay bestie, back in the filter flags, and I'm giving every single one of them their moment 💅

• --delete-excluded — deletes files on dest that got excluded from the sync. yes it does exactly what it says, it means it 🔥
• --exclude stringArray — exclude files that match your pattern 🙈
• --exclude-from stringArray — read your file exclude patterns from a file (pass - to read from stdin) 📄
• --exclude-if-present stringArray — exclude a directory entirely if a file with this filename is present in it 🚫
• --files-from stringArray — read your list of source-file names from a file (use - to read from stdin) 📋
• --files-from-raw stringArray — read that same list of source-file names from a file, but with zero processing of the lines (use - to read from stdin) 🥩
• --files-from0 stringArray — read the list of source-file names from a file using NUL as the separator (use - to read from stdin) 🫧
• -f, --filter stringArray — drop in one single file filtering rule, that's it, that's the flag ✨
• --filter-from stringArray — read your file filtering patterns from a file (use - to read from stdin) 🗂️
• --hash-filter string — partition filenames by hash using k/n, or randomly with @/n 🎲
• --ignore-case — ignore case in filters, so everything is case insensitive now 💅
• --include stringArray — include the files matching your pattern 💖
• --include-from stringArray — read your file include patterns from a file (use - to read from stdin) 🌸
• --max-age Duration — only transfer files younger than this, in s or with the suffix ms|s|m|h|d|w|M|y (default off) ⏰
• --max-depth int — if you set it, it limits the recursion depth right there (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 your pattern 🏷️
• --metadata-exclude-from stringArray — read your 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 the metadatas matching your 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 the 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 B|K|M|G|T|P suffix (default off) 🐘

and that's the whole filter squad, not one skipped, no cap 🫶

---

🦋 Listing Options 🦋

Flags for listing directories, obviously 🗂️

• --default-time Time — the time to show if the modtime is unknown for files and directories (default 2000-01-01T00:00:00Z) 🕰️
• --fast-list — use the recursive list if it's available; it gobbles more memory but makes fewer transactions, a classic tradeoff queen 🚀

🌈 See Also 🌈

• rclone (https://rclone.org/commands/rclone/) — show help for rclone commands, flags and backends 💖

---

👑 rclone move 👑

Move files from source to dest. yes, the moving one, it's giving relocation era 🚚

✨ Synopsis ✨

Moves the contents of the source directory to the destination directory. And heads up bestie: rclone will error if the source and destination overlap and the remote does not support a server-side directory move operation. not a vibe, but that's the rule 😤

To move single files, use the moveto (https://rclone.org/commands/rclone_moveto/) command instead. that's its whole personality 🫶

If no filters are in use and if possible, this will server-side move source:path into dest:path. And after this, source:path will no longer exist. it's gone, ghosted, blocked 👻

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 and then delete the original (if there were no errors on copy) in source:path. copy first, delete only if the copy went clean, that's the safe girl behaviour 💅

If you want to delete the empty source directories after the move, use the --delete-empty-src-dirs flag 🧹

See the --no-traverse (https://rclone.org/docs/#no-traverse) option for controlling whether rclone lists the destination directory or not. Supplying this option when you're 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 🏷️

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. bestie please, dry run first, I'm begging 🙏

Note: use the -P/--progress flag to view real-time transfer statistics 📊

🎀 Logger Flags 🎀

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name you supply (or to stdout if it's -). What they write is described in the help below. So 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 the file paths with a symbol, then a space, then the path, telling you what happened to it. these are giving 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 --dest-after flag writes a list file using the same format flags as lsf (https://rclone.org/commands/rclone_lsf/#synopsis) (including customizable options for hash, modtime, etc. (https://rclone.org/commands/rclone_lsf/#synopsis)). 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 command is finished 🔮

When the --no-traverse flag is set, all logs involving files that exist only on the destination will be incomplete or completely missing. so like. good luck with that 💀

Note also 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

And note also that each file is logged during execution, 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). it's a fortune teller, not a receipt 🎭

rclone move 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 move 🗂️
• --csv — output in CSV format 📊
• --delete-empty-src-dirs — delete empty source dirs after move 🧹
• --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 move 🆘
• --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, see docs for details (default: 2006-01-02 15:04:05) 🕰️

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) for global options not listed here. 🌍

📦 Copy Options 📦

Flags for anything which can copy a file 🫶

• --check-first — do all the checks before you start any transfers, bestie. vibe check first, transfer later. 💅
• -c, --checksum — check for changes using size and checksum, if the backend has one; if not, it falls back to size only. size & checksum, or size only as the fallback. ✨
• --compare-dest stringArray — include additional server-side paths during comparison. extra server-side paths for the compare step. 🦋
• --copy-dest stringArray — this implies --compare-dest but also copies files from those paths into the destination. compare plus copy from extra paths. 💖
• --cutoff-mode HARD|SOFT|CAUTIOUS — mode to stop transfers when reaching the max transfer limit: HARD, SOFT, or CAUTIOUS (default HARD). pick your stopping vibe. 🎀
• --ignore-case-sync — ignore case when synchronizing. case? never heard of her. 💅
• --ignore-checksum — skip post copy check of checksums. no checksum check after the copy. 🙈
• --ignore-existing — skip all files that exist on destination. if it’s already there, leave it alone. ✨
• --ignore-size — ignore size when skipping; use modtime or checksum instead. size doesn’t count for the skip decision. 🦋
• -I, --ignore-times — don’t skip items that match size and time — transfer all unconditionally. transfer everything, no skips, periodt. 🔥
• --immutable — do not modify files, fail if existing files have been modified. do not touch, or it’s a whole fail. 💀
• --inplace — download directly to destination file instead of atomic download to temp/rename. straight to the destination, no temp-file-and-rename drama. 👑
• -l, --links — translate symlinks to/from regular files with a .rclonelink extension. symlink translation with that exact extension. 🧚
• --max-backlog int — maximum number of objects in sync or check backlog (default 10000). cap that backlog, bestie. 🌸
• --max-duration Duration — maximum duration rclone will transfer data for (default 0s). time limit on the transferring. ⏳
• --max-transfer SizeSuffix — maximum size of data to transfer (default off). size cap for the whole transfer. 💖
• -M, --metadata — if set, preserve metadata when copying objects. keep the metadata, no cap. ✨
• --modify-window Duration — max time diff to be considered the same (default 1ns). tiny time difference still counts as same. 🦋
• --multi-thread-chunk-size SizeSuffix — chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi). chunk size unless the filesystem says otherwise. 💅
• --multi-thread-cutoff SizeSuffix — use multi-thread downloads for files above this size (default 256Mi). bigger than this? multi-thread time. 🔥
• --multi-thread-streams int — number of streams to use for multi-thread downloads (default 4). four streams by default, slay. 🌈
• --multi-thread-write-buffer-size SizeSuffix — in memory buffer size for writing when in multi-thread mode (default 128Ki). in-memory write buffer for multi-thread mode. 🎀
• --name-transform stringArray — transform paths during the copy process. rename/reshape paths as they copy. ✨
• --no-check-dest — don’t check the destination, copy regardless. no destination check, just copy. 💀
• --no-traverse — don’t traverse destination file system on copy. skip walking the destination on copy. 🦋
• --no-update-dir-modtime — don’t update directory modification times. leave directory modtimes alone. 💅
• --no-update-modtime — don’t update destination modtime if files identical. identical files? don’t touch the modtime. ✨
• --order-by string — instructions on how to order the transfers, e.g. 'size,descending'. tell rclone what order to transfer in. 🔥
• --partial-suffix string — add partial-suffix to temporary file name when --inplace is not used (default ".partial"). the temp file gets this suffix. 🎀
• --refresh-times — refresh the modtime of remote files. update those remote modtimes. 🦋
• --server-side-across-configs — allow server-side operations (e.g. copy) to work across different configs. server-side copy across configs? iconic. 👑
• --size-only — skip based on size only, not modtime or checksum. size only, nothing else. 💅
• --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). unknown size? switch to chunked upload at this cutoff. ✨
• -u, --update — skip files that are newer on the destination. newer on dest? skip it. 🦋

---

✨ Important Options ✨

Important flags useful for most commands — bestie, these are the everyday icons. 💖

• -n, --dry-run — do a trial run with no permanent changes. pretend mode, no real changes. 🙈
• -i, --interactive — enable interactive mode. it asks you stuff as it goes. 💅
• -v, --verbose count — print lots more stuff (repeat for more). more -v, more tea. ☕

---

✨ Filter Options ✨

Flags for filtering directory listings — your little filter besties. 🎀

• --delete-excluded — delete files on dest excluded from sync. excluded on dest? delete them. 💀
• --exclude stringArray — exclude files matching pattern. bye, matching files. 👋
• --exclude-from stringArray — read file exclude patterns from file (use - to read from stdin). exclude patterns from a file, or stdin with -. 🦋
• --exclude-if-present stringArray — exclude directories if filename is present. if that filename is there, skip the whole directory. 🧚
• --files-from stringArray — read list of source-file names from file (use - to read from stdin). source file list, straight from a file. ✨
• --files-from-raw stringArray — read list of source-file names from file without any processing of lines (use - to read from stdin). raw lines, no processing. 💅
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (use - to read from stdin). NUL-separated source file list. 🌈
• -f, --filter stringArray — add a file filtering rule. one more filter rule. 🎀
• --filter-from stringArray — read file filtering patterns from a file (use - to read from stdin). filter patterns from a file, or stdin. 🦋
• --hash-filter string — partition filenames by hash k/n or randomly @/n. hash partition, k/n or random @/n. ✨
• --ignore-case — ignore case in filters (case insensitive). filters don’t care about case. 💅
• --include stringArray — include files matching pattern. only these matching files get in. 👑
• --include-from stringArray — read file include patterns from file (use - to read from stdin). include patterns from a file, or stdin. 🦋
• --max-age Duration — only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off). too old? not transferring. ⏳
• --max-depth int — if set limits the recursion depth to this (default -1). cap how deep recursion goes. 🎀
• --max-size SizeSuffix — only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off). too big? not transferring. 💖
• --metadata-exclude stringArray — exclude metadatas matching pattern. metadata matching this pattern gets excluded. 🦋
• --metadata-exclude-from stringArray — read metadata exclude patterns from file (use - to read from stdin). metadata exclude patterns from a file. ✨
• --metadata-filter stringArray — add a metadata filtering rule. one more metadata filter rule. 💅
• --metadata-filter-from stringArray — read metadata filtering patterns from a file (use - to read from stdin). metadata filter patterns from a file. 🎀
• --metadata-include stringArray — include metadatas matching pattern. include metadata matching this pattern. 👑
• --metadata-include-from stringArray — read metadata include patterns from file (use - to read from stdin). metadata include patterns from a file. 🌈
• --min-age Duration — only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off). too young? not transferring. ⏳
• --min-size SizeSuffix — only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off). too small? not transferring. ✨

---

✨ Listing Options ✨

Flags for listing directories — for when you just wanna see what’s there. 🦋

• --default-time Time — time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z). unknown modtime? show this timestamp. 🎀
• --fast-list — use recursive list if available; uses more memory but fewer transactions. more memory, fewer transactions — worth it. 👑

---

👀 See Also 👀

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends. 💖

🗑️ rclone delete

okay bestie, this one is the selective deleter. Remove the files in path.

✨ Synopsis

Remove the files in path. Unlike purge (https://rclone.org/commands/rclone_purge/) it obeys include/exclude filters so can be used to selectively delete files. that's the whole point of her, she's the picky one 💅

rclone delete only deletes files but leaves the directory structure alone. If you want to delete a directory and all of its contents use the purge (https://rclone.org/commands/rclone_purge/) command instead. purge is the one with zero chill.

If you supply the --rmdirs flag, it will remove all empty directories along with it. You can also use the separate command rmdir (https://rclone.org/commands/rclone_rmdir/) or rmdirs (https://rclone.org/commands/rclone_rmdirs/) to delete empty directories only. so many ways to clean up, we're spoiled fr fr 🧚

For example, to delete all files bigger than 100 MiB, you may first want to check what would be deleted (use either):

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. yes the logic is a little chaotic but she's right, trust. 🌈

Important: Since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. bestie please. do the trial run. I am begging. 😭

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 (https://rclone.org/flags/) for global options not listed here.

🌟 Important Options

Important flags useful for most commands — these girls show up everywhere, icons only ✨

• -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 — the "who gets to stay" committee 💖

• --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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

💀 rclone purge

Remove the path and all of its contents. yes she is that girl and yes she means ALL of it.

✨ Synopsis

Remove the path and all of its contents. Note that this does not obey include/exclude filters — everything will be removed. Use the delete (https://rclone.org/commands/rclone_delete/) command if you want to selectively delete files. To delete empty directories only, use command rmdir (https://rclone.org/commands/rclone_rmdir/) or rmdirs (https://rclone.org/commands/rclone_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. so if it's acting like the flag isn't real… it might not be, no cap 🙈

Important: Since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. this is the main character of "oops" moments, protect yourself 😭

rclone purge remote:path [flags]

✨ Options

• -h, --help — help for purge

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) 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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🌸 rclone mkdir

Make the path if it doesn't already exist. shortest icon behaviour ever, she just… shows up 💅

rclone mkdir remote:path [flags]

✨ Options

• -h, --help — help for mkdir

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) 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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🎀 rclone rmdir

Remove the empty directory at path. note the word empty, she's picky and that's valid.

✨ Synopsis

This removes empty directory given by path. Will not remove the path if it has any objects in it, not even empty subdirectories. like she will NOT budge if there's anything in there, not even a little empty subdirectory lurking 💀 Use command rmdirs (https://rclone.org/commands/rclone_rmdirs/) (or delete (https://rclone.org/commands/rclone_delete/) with option --rmdirs) to do that.

To delete a path and any objects in it, use purge (https://rclone.org/commands/rclone_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 (https://rclone.org/flags/) 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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

✨ rclone check ✨

okay bestie, this one is the vibe check command 💅 it just looks at your files and tells you if the source and destination actually match, no touching, no moving, no drama. purely observational. main character energy but make it polite.

🌸 Synopsis

rclone check checks that the files in the source and destination match. it compares sizes and hashes (MD5 or SHA1) and then logs a whole little report of the files that don't match. it does not alter the source or destination — promise, it's just looking 🫶

for the crypt remote (over at rclone.org/crypt/) there's a dedicated command, cryptcheck (at rclone.org/commands/rclone_cryptcheck/), and that one is able to check the checksums of the encrypted files. so if you're living that crypt life, that's your girl.

if you pass the --size-only flag, it will only compare the sizes and not the hashes as well. use this for a quick check, it's giving speedrun ⚡

if you pass 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 want to check all the data. like, all of it. no cap 😤

if you pass the --checkfile HASH flag with a valid hash name, then source:path must point to a text file in the SUM format. yes, that format. the SUM one 💖

if you pass 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. lowkey a blind spot, so know what you're asking for 🙈

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 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 🎀

• = 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 option (over at rclone.org/docs/#checkers-int) for more info. yes bestie, 8 at once, she multitasks ✨

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 (over at rclone.org/flags/) for global options not listed here, iykyk 👑

🦋 Check Options

flags used for check commands 🎯

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

🌈 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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 (over at rclone.org/commands/rclone/) — show help for rclone commands, flags and backends.

🌈 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🎀 rclone lsd 🎀

🌟 Synopsis 🌟

okay so rclone lsd lists the directories in the source path straight to standard output. ngl it does not recurse by default — you gotta hit it with the -R flag if you want it to recurse into everything. 💅

This command lists 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 the name of the directory. E.g. 🦋

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

Or

$ 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 you just want the directory names use rclone lsf --dirs-only. periodt. 😌

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

There are several related list commands — the whole friend group:

• 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 human and machine-readable. lsjson is designed to be machine-readable. range fr fr. 🌈

bestie, listen: ls and lsl recurse by default — use --max-depth 1 to stop the recursion. the other ones are chill.

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

On the bucket-based remotes (e.g. s3, gcs, b2) a directory is a key prefix rather than an object, so a listing without -R shows each prefix as one directory entry and not the objects stored under it. iykyk 🪣✨

List commands prefer a recursive method that uses more memory but fewer transactions by default. Use --disable ListR to suppress the behavior. See --fast-list (https://rclone.org/docs/#fast-list) for more details.

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). they literally can't do empty dirs so the rules don't apply to them 💀

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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

rclone lsl 💅

List the objects in path with modification time, size and path. ✨

Synopsis 🎀

Okay bestie, so lsl dumps all the objects in your source path straight to standard output in a human-readable format — and it gives you the modification time, the size, AND the path. Recurse? Oh it recurses by default, no cap. 🌈

Like, for example:

$ 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. (Yes, any. Filter girlies stay winning. 💖)

There are several related list commands and honestly they're a whole friend group:

• 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. (machine-readable girlies, this one's for you 🤖)

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. (Flip that switch, bestie. 🔁)

On the bucket-based remotes (e.g. s3, gcs, b2) a directory is a key prefix rather than an object, so a listing without -R shows each prefix as one directory entry and not the objects stored under it. sneaky!! 🙈

List commands prefer a recursive method that uses more memory but fewer transactions by default. Use --disable ListR to suppress the behavior. See --fast-list (https://rclone.org/docs/#fast-list) for more details. 🧠

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 lsl remote:path [flags]

Options 🌸

• -h, --help — help for lsl

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) - Show help for rclone commands, flags and backends.

---

rclone md5sum 🔥

Produces an md5sum file for all the objects in the path. ✨

Synopsis 🎀

So rclone md5sum produces an md5sum file for all the objects in the path. This is in the same format as the standard md5sum tool produces. same format besties, we're compatible 💖

By default, the hash is requested from the remote. If MD5 is not supported by the remote, no hash will be returned. not even a little bit, it just won't come back 😭 With the download flag, the file will be downloaded from the remote and hashed locally enabling MD5 for any remote. (Yes, any. Iconic behavior tbh. 👑)

For other algorithms, see the hashsum (https://rclone.org/commands/rclone_hashsum/) command. Running rclone md5sum remote:path is equivalent to running rclone hashsum MD5 remote:path.

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). careful babes, the hyphen has main character energy and it will do exactly what you told it to 🙈

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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) - Show help for rclone commands, flags and backends.

🍒 rclone sha1sum

Ok bestie, this one makes an sha1sum file for literally every object in the path. 💖

✨ 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](https://rclone.org/commands/rclone_hashsum/) command. Running rclone sha1sum remote:path is equivalent to running rclone hashsum SHA1 remote:path.

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).

This command can also hash data received on STDIN, if not passing a remote:path.

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 over at https://rclone.org/flags/ for global options not listed here.

🎀 Filter Options 🎀

Flags for filtering directory listings — yes they show up everywhere, she's consistent like that:

• --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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🍓 rclone size

Prints the total size and number of objects in remote:path. She's doing math for you, you're welcome. ✨

✨ Synopsis ✨

Counts objects in the path and calculates the total size. Prints the result to standard output.

By default the output is in human-readable format, but shows values in both human-readable format as well as the raw numbers (global option --human-readable is not considered). Use option --json to format output as JSON instead.

Recurses by default, use --max-depth 1 to stop the recursion.

Some backends do not always provide file sizes, see for example [Google Photos](https://rclone.org/googlephotos/#size) and [Google Docs](https://rclone.org/drive/#limitations-of-google-docs). Rclone will then show a notice in the log indicating how many such files were encountered, and count them in as empty files in the output of the size command.

rclone size remote:path [flags]

🌸 Options 🌸

• -h, --help — help for size
• --json — format output as JSON

Options shared with other commands are described next. See the global flags page over at https://rclone.org/flags/ 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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🦋 rclone version

Show the version number. Yes queen, receipts. 💅

✨ Synopsis ✨

Show the rclone version number, the go version, the build target OS and architecture, the runtime OS and kernel version and bitness, build tags and the type of executable (static or dynamic).

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". 💀

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.

$ 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

If you supply the --deps flag then rclone will print a list of all the packages it depends on and their versions along with some other information about the build.

rclone version [flags]

🌸 Options 🌸

• --check — check for new version
• --deps — show the Go dependencies
• -h, --help — help for version

See the global flags page over at https://rclone.org/flags/ for global options not listed here.

👑 See Also 👑

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

rclone cleanup</p> 🧼✨

okay so bestie, this one cleans up the remote if possible. Like, it empties the trash 🗑️ or deletes old file versions. Not every remote is gonna support this tho — vibe check your backend first 💅

---

Synopsis

Clean up the remote if possible. Empty the trash or delete old file versions. Not supported by all remotes.

rclone cleanup remote:path [flags]

---

Options

• -h, --help — help for cleanup 🫶

Options shared with other commands are described next. See the global flags page (<https://rclone.org/flags/>) for global options not listed here.

---

Important Options ✨

Important flags useful for most commands — lowkey these are your ride-or-dies:

• -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 (<https://rclone.org/commands/rclone/>) - Show help for rclone commands, flags and backends. 👑

---

rclone dedupe 👯‍♀️💖

Interactively find duplicate filenames and delete/rename them. This is the the way that you deal with a messy folder that has the same file three times like it's a group chat with the same screenshot posted by everyone 😭

Synopsis

By default dedupe interactively finds files with duplicate names and offers to delete all but one or rename them to be different. This is known as deduping by name.

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.

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. Fr fr, do not skip this step bestie, I'm begging 🙏

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 💅

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

Or:

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 (<https://rclone.org/flags/>) 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 (<https://rclone.org/commands/rclone/>) - Show help for rclone commands, flags and backends. 👑

---

rclone about 📊💜

Get quota information from the remote. It's giving receipts for your storage, bestie 🧾✨

Synopsis

Prints quota information about a remote to standard output. The output is typically used, free, quota and trash contents.

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. 🚫

Some backends does not support the rclone about command at all, see complete list in documentation (<https://rclone.org/overview/#optional-features>). 😭

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 (<https://rclone.org/flags/>) for global options not listed here.

---

See Also

• rclone (<https://rclone.org/commands/rclone/>) - Show help for rclone commands, flags and backends. 👑

---

rclone archive 📦✨

Perform an action on an archive. Zip-zip hooray 🎀

Synopsis

Perform an action on an archive. Requires the use of a subcommand to specify the protocol, e.g.

rclone archive list remote:file.zip

Each subcommand has its own options which you can see in their help.

See rclone archive create (<https://rclone.org/commands/rclone_archive_create/>) for the archive formats supported. 🗂️

rclone archive <action> [opts] <source> [<destination>] [flags]

---

Options

• -h, --help — help for archive 🫶

See the global flags page (<https://rclone.org/flags/>) for global options not listed here.

---

See Also

• rclone (<https://rclone.org/commands/rclone/>) - Show help for rclone commands, flags and backends. 👑
• rclone archive create (<https://rclone.org/commands/rclone_archive_create/>) - Archive source file(s) to destination. 📦
• rclone archive extract (<https://rclone.org/commands/rclone_archive_extract/>) - Extract archives from source to destination. 🎁
• rclone archive list (<https://rclone.org/commands/rclone_archive_list/>) - List archive contents from source. 📋

✨ rclone archive create ✨

Archive source file(s) to destination. 🗜️

🌸 Synopsis

So basically it creates an archive out of all the files in source:path and drops that archive into dest:path. 💖 And if <destination> isn't even there?? bestie it just writes straight to the console. no cap.

The valid formats for the --format flag are listed below, and if you don't set --format then rclone will guess it from the extension of dest:path (she's observant like that 💅):

• zip — .zip
• tar — .tar
• tar.gz — .tar.gz, .tgz, .taz
• tar.bz2 — .tar.bz2, .tb2, .tbz, .tbz2, .tz2
• tar.lz — .tar.lz
• tar.lz4 — .tar.lz4
• tar.xz — .tar.xz, .txz
• tar.zst — .tar.zst, .tzst
• tar.br — .tar.br
• tar.sz — .tar.sz
• tar.mz — .tar.mz

The --prefix and --full-path flags control the prefix for the files in the archive. 🎀

• If the flag --full-path is set then the files will have the full source path as the prefix.
• If the flag --prefix=<value> is set then the files will have <value> as prefix. It's possible to create invalid file names with --prefix=<value> so use with caution. ⚠️ Flag --prefix has priority over --full-path.

Given a directory /sourcedir with the following:

file1.txt
dir1/file2.txt

Running the command rclone archive create /sourcedir /dest.tar.gz will make an archive with the contents:

file1.txt
dir1/
dir1/file2.txt

Running the command rclone archive create --full-path /sourcedir /dest.tar.gz will make an archive with the contents:

sourcedir/file1.txt
sourcedir/dir1/
sourcedir/dir1/file2.txt

Running the command rclone archive create --prefix=my_new_path /sourcedir /dest.tar.gz will make an archive with the contents:

my_new_path/file1.txt
my_new_path/dir1/
my_new_path/dir1/file2.txt

rclone archive create [flags] <source> [<destination>]

🦋 Options

• --format string — Create the archive with format or guess from extension. 🔍
• --full-path — Set prefix for files in archive to source path.
• -h, --help — help for create 🫶
• --prefix string — Set prefix for files in archive to entered value or source path.

See the global flags page (https://rclone.org/flags/) for global options not listed here.

💜 See Also

• rclone archive (https://rclone.org/commands/rclone_archive/) - Perform an action on an archive.

---

✨ rclone archive extract ✨

Extract archives from source to destination. 📦

🌸 Synopsis

It extracts the archive contents to a destination directory, auto detecting the format because she's a genius. 😌 See rclone archive create (https://rclone.org/commands/rclone_archive_create/) for the archive formats supported.

For example on this archive:

$ rclone archive list --long remote:archive.zip
        6 2025-10-30 09:46:23.000000000 file.txt
        0 2025-10-30 09:46:57.000000000 dir/
        4 2025-10-30 09:46:57.000000000 dir/bye.txt

You can run extract like this

$ rclone archive extract remote:archive.zip remote:extracted

Which gives this result

$ rclone tree remote:extracted
/
├── dir
│   └── bye.txt
└── file.txt

The source or destination or both can be local or remote. 🌈

Filters can be used to only extract certain files:

$ rclone archive extract archive.zip partial --include "bye.*"
$ rclone tree partial
/
└── dir
    └── bye.txt

The archive backend (https://rclone.org/archive/) can also be used to extract files. It can be used to read only mount archives also but it supports a different set of archive formats to the archive commands. 💅

rclone archive extract [flags] <source> <destination>

🦋 Options

• -h, --help — help for extract 🫶

See the global flags page (https://rclone.org/flags/) for global options not listed here.

💜 See Also

• rclone archive (https://rclone.org/commands/rclone_archive/) - Perform an action on an archive.

---

✨ rclone archive list ✨

List archive contents from source. 📋

🌸 Synopsis

Lists the contents of an archive to the console, auto detecting the format (again, she just knows 🧚). See rclone archive create (https://rclone.org/commands/rclone_archive_create/) for the archive formats supported.

For example:

$ rclone archive list remote:archive.zip
        6 file.txt
        0 dir/
        4 dir/bye.txt

Or with --long flag for more info:

$ rclone archive list --long remote:archive.zip
        6 2025-10-30 09:46:23.000000000 file.txt
        0 2025-10-30 09:46:57.000000000 dir/
        4 2025-10-30 09:46:57.000000000 dir/bye.txt

Or with --plain flag which is useful for scripting:

$ rclone archive list --plain /path/to/archive.zip
file.txt
dir/
dir/bye.txt

Or with --dirs-only:

$ rclone archive list --plain --dirs-only /path/to/archive.zip
dir/

Or with --files-only:

$ rclone archive list --plain --files-only /path/to/archive.zip
file.txt
dir/bye.txt

Filters may also be used:

$ rclone archive list --long archive.zip --include "bye.*"
        4 2025-10-30 09:46:57.000000000 dir/bye.txt

The archive backend (https://rclone.org/archive/) can also be used to list files. It can be used to read only mount archives also but it supports a different set of archive formats to the archive commands. 💜

rclone archive list [flags] <source>

🦋 Options

• --dirs-only — Only list directories.
• --files-only — Only list files.
• -h, --help — help for list 🫶
• --long — List extra attributtes. (yep, that's how it's spelled bestie, we keep it exact 😭*)*
• --plain — Only list file names.

See the global flags page (https://rclone.org/flags/) for global options not listed here.

💜 See Also

• rclone archive (https://rclone.org/commands/rclone_archive/) - Perform an action on an archive.

---

✨ 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. See also the remote setup documentation. 🖥️

The command requires 1-3 arguments:

• Name of a backend (e.g. "drive", "s3")
• 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 <backendname> [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 (https://rclone.org/flags/) for global options not listed here.

💜 See Also

• rclone (https://rclone.org/commands/rclone/) - Show help for rclone commands, flags and backends.

---

✨ rclone backend ✨

Run a backend-specific command. ⚙️

🌸 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. iykyk 📚

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 (https://rclone.org/rc/#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 (https://rclone.org/rc/#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 (https://rclone.org/flags/) 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 (https://rclone.org/commands/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 (https://rclone.org/bisync/) provides a bidirectional cloud sync solution in rclone. 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 considered an advanced command, so use with care. 😳 Make sure you have read and understood the entire manual (https://rclone.org/bisync) (especially the Limitations (https://rclone.org/bisync/#limitations) section) before using, or data loss can result. Questions can be asked in the Rclone Forum (https://forum.rclone.org/).

See full bisync description (https://rclone.org/bisync/) for details. 🦋

rclone bisync remote1:path1 remote2:path2 [flags]

• --backup-dir1 string — the --backup-dir for Path1. Heads up bestie, it has to be a non-overlapping path living on the same remote.
• --backup-dir2 string — the --backup-dir for Path2. Same deal: non-overlapping, same remote.
• --check-access — makes sure the RCLONE_TEST files you expect are actually sitting on both the Path1 and Path2 filesystems. If they're not? It just aborts, no drama.
• --check-filename string — the filename it looks for when --check-access is doing its thing. (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, like size,modtime,checksum (default: 'size,modtime')
• --conflict-loser ConflictLoserAction — what to do with the loser of a sync conflict (when there is a winner) or with both files (when nobody won): , num, pathname, delete (default: num)
• --conflict-resolve string — auto-resolves conflicts by picking whichever version is: none, path1, path2, newer, older, larger, smaller (default: none) (default "none")
• --conflict-suffix string — the suffix used when you rename a --conflict-loser. It can be a single string, or two comma-separated strings so Path1 and Path2 get their own suffixes. (default: 'conflict')
• --create-empty-src-dirs — syncs the creating and deleting of empty directories. (Not compatible with --remove-empty-dirs)
• --download-hash — computes the hash by downloading when there's no other way to get it. (warning: may be slow and use lots of data!)
• --filters-file string — reads your filtering patterns from a file
• --force — bypasses the --max-delete safety check and just runs the sync. Consider pairing it with --verbose.
• -h, --help — help for bisync
• --ignore-listing-checksum — don't use checksums for listings (add --ignore-checksum too if you additionally want to skip the post-copy checksum checks)
• --max-lock Duration — treat lock files older than this as expired (default: 0 (never expire)) (minimum: 2m) (default 0s)
• --no-cleanup — keeps the working files around (so useful for troubleshooting and testing, fr)
• --no-slow-hash — ignores listing checksums only on the backends where they're slow
• --recover — automatically recovers from interruptions without needing --resync
• --remove-empty-dirs — removes ALL the empty directories at the final cleanup step
• --resilient — lets future runs retry after certain less-serious errors instead of forcing you into --resync
• -1, --resync — performs the resync run. Equivalent to --resync-mode path1. Pls pls pls consider --verbose or --dry-run first 💅
• --resync-mode string — during resync, prefer whichever version is: path1, path2, newer, older, larger, smaller (default: path1 if --resync, otherwise none for no resync.) (default "none")
• --slow-hash-sync-only — ignores slow checksums for listings and deltas, but still counts them during sync calls
• --workdir string — use a custom working dir, super handy for testing. (default: $HOME/.cache/rclone/bisync)

Options that are shared with other commands get described right below. For the global options that aren't listed here, go peek at the global flags page at https://rclone.org/flags/ 🫶

---

🎀 Copy Options 🎀

The flags for anything that can copy a file

• --check-first — does ALL the checks before it starts any transfers
• -c, --checksum — checks for changes using size & checksum (if it's available, or falls back to size only)
• --compare-dest stringArray — tosses in extra server-side paths during comparison
• --copy-dest stringArray — basically implies --compare-dest but also copies the files from those paths into the destination
• --cutoff-mode HARD|SOFT|CAUTIOUS — the mode for stopping transfers once you hit the max transfer limit: HARD|SOFT|CAUTIOUS (default HARD)
• --ignore-case-sync — ignores case while it's synchronizing
• --ignore-checksum — skips the post copy check of checksums
• --ignore-existing — skips every file that already exists on the destination
• --ignore-size — ignores size when skipping; uses modtime or checksum instead
• -I, --ignore-times — doesn't skip items that match in size and time, just transfers everything unconditionally
• --immutable — never modifies files; fails if existing files got modified
• --inplace — downloads straight into the destination file instead of the atomic download-to-temp-then-rename thing
• -l, --links — translates symlinks to/from regular files using a .rclonelink extension
• --max-backlog int — the max number of objects in the sync or check backlog (default 10000)
• --max-duration Duration — how long rclone will transfer data for, max (default 0s)
• --max-transfer SizeSuffix — the max amount of data it'll transfer (default off)
• -M, --metadata — if set, it preserves metadata when copying objects
• --modify-window Duration — the biggest time diff that still counts as "the same" (default 1ns)
• --multi-thread-chunk-size SizeSuffix — the chunk size for multi-thread downloads/uploads, when the filesystem doesn't set it (default 64Mi)
• --multi-thread-cutoff SizeSuffix — uses multi-thread downloads for files bigger than this (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 while in multi-thread mode (default 128Ki)
• --name-transform stringArray — transforms paths during the copy process
• --no-check-dest — doesn't check the destination, just copies regardless
• --no-traverse — doesn't traverse the destination file system on copy
• --no-update-dir-modtime — doesn't update directory modification times
• --no-update-modtime — doesn't update the destination modtime if the files are identical
• --order-by string — instructions for how to order the transfers, e.g. size,descending
• --partial-suffix string — adds this partial-suffix to the temporary file name when --inplace is not being used (default ".partial")
• --refresh-times — refreshes the modtime of remote files
• --server-side-across-configs — lets server-side operations (like copy) work across different configs
• --size-only — skips based on size only, no modtime or checksum
• --streaming-upload-cutoff SizeSuffix — the cutoff for switching to chunked upload when the file size is unknown; the upload starts after it reaches the cutoff or when the file ends (default 100Ki)
• -u, --update — skips files that are newer on the destination

---

✨ Sync Options ✨

The flags used for sync commands

• --backup-dir string — makes backups into a hierarchy based in DIR
• --delete-after — when synchronizing, deletes the files on the destination after transferring (this is the default)
• --delete-before — when synchronizing, deletes the files on the destination before transferring
• --delete-during — when synchronizing, deletes the files during transfer
• --fix-case — forces a rename of a case-insensitive dest so it matches the source
• --ignore-errors — deletes even if there are I/O errors
• --list-cutoff int — to save memory, sorts directory listings on disk above this threshold (default 1000000)
• --max-delete int — when synchronizing, limits the number of deletes (default -1)
• --max-delete-size SizeSuffix — when synchronizing, limits the total size of the deletes (default off)
• --suffix string — the suffix to add to changed files
• --suffix-keep-extension — preserves the extension when you're using --suffix
• --track-renames — when synchronizing, tracks file renames and does a server-side move if it possibly can
• --track-renames-strategy string — the strategies to use when synchronizing with track-renames: hash|modtime|leaf (default "hash")

---

👑 Important Options 👑

The important flags that are useful for most commands

• -n, --dry-run — does a trial run with zero permanent changes 🙈
• -i, --interactive — enables interactive mode
• -v, --verbose count — prints lots more stuff (repeat it for even more)

---

🌈 Filter Options 🌈

The flags for filtering directory listings

…and the rest of the filter fam, no skips, we list every single one 💅

• --delete-excluded — deletes files on dest that got excluded from sync (yes, it's giving "you're not invited AND we're taking your stuff" 💀)
• --exclude stringArray — excludes files matching pattern
• --exclude-from stringArray — reads exclude patterns from a file (use - to read from stdin)
• --exclude-if-present stringArray — nukes whole directories if that filename is in there
• --files-from stringArray — reads a 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)
• --files-from0 stringArray — reads source-file names using NUL as the separator (use - for stdin)
• -f, --filter stringArray — drop in a file filtering rule
• --filter-from stringArray — read your filtering patterns from a file (use - for stdin)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --ignore-case — ignore case in filters, so it's case insensitive bestie
• --include stringArray — includes files matching pattern
• --include-from stringArray — reads include patterns from a file (use - for stdin)
• --max-age Duration — only transfers files younger than this, in s or with the 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 transfers files smaller than this, in KiB or with the suffix B|K|M|G|T|P (default off)
• --metadata-exclude stringArray — excludes metadatas matching pattern
• --metadata-exclude-from stringArray — reads 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 — includes metadatas matching pattern
• --metadata-include-from stringArray — reads metadata include patterns from a file (use - for stdin)
• --min-age Duration — only transfers files older than this, in s or with suffix ms|s|m|h|d|w|M|y (default off)
• --min-size SizeSuffix — only transfers files bigger than this, in KiB or with suffix B|K|M|G|T|P (default off)

🫶 See Also 🫶

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🐱 rclone cat 🐱

The greatest hits of "just show me the file already" — it concatenates any files and yeets them straight to stdout. No cap.

✨ Synopsis ✨

Sends any files to standard output. That's it, that's the whole vibe. 💖

Use it like this to output a single file:

rclone cat remote:path/to/file

Or like this to output every file in dir or any of its subdirectories:

rclone cat remote:path/to/dir

Or like this to output any .txt files in dir or its subdirectories:

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

Now for the main character flags: --head prints only the characters at the start, --tail does the end, and --offset + --count let you print a section right out of the middle. 🎀 Heads up tho — if offset is negative it counts from the end, so --offset -1 --count 1 is equivalent to --tail 1. Iconic.

Use the --separator flag to print a separator value between files. Be sure to shell-escape special characters — don't be that girl who forgets and then wonders why her output is cursed. 🙈 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 it (produce and ghost, lmao 💀)
• --head int — only print the first N characters
• -h, --help — help for cat
• --offset int — start printing at offset N (or from the end if it's -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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

💅 rclone checksum 💅

Checks the files in the destination against a SUM file. No cap. 🫶

✨ Synopsis ✨

Okay bestie, so this one checks that the hashsums of your destination files actually match the SUM file you gave it. It compares hashes (MD5, SHA1, etc) and then logs you a whole lil report of the files that don't match. And the most important part: it doesn't alter the file system. It's just looking, never touching. Queen behavior honestly. 👑

The sumfile is treated as the source and the dst:path is treated as the destination, as far as the output is concerned. So like, keep that flipped-in-your-head framing, it matters.

If you pass the --download flag, it will literally download the data from the remote and calculate the content hash on the fly. Super useful for remotes that don't support hashes, or if you're just that girl who really wants to check ALL the data. 🔥

Heads up: hash values inside the SUM file are treated as case insensitive. So chill, casing doesn't matter here.

If you pass --one-way, it only checks that the files in the source match the files in the destination — not the other way around. Which means extra files sitting in the destination that aren't in the source? Yeah those will not be detected. 🙈

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags all write paths, one per line, to the file name you supply (or to stdout if it's -). What exactly they write is described in the help below. Like for example --differ writes all the paths that show up on both the source and destination but are different.

The --combined flag writes a file (or stdout) that has every file path with a symbol, then a space, then the path — telling you what happened to it. These are giving very much diff-file energy. 🦋

• = path means path was found in the source and destination and was identical
• - path means path was missing on the source, so it only exists in the destination
• + path means path was missing on the destination, so it only exists in the source
• * path means path was present in the 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 (https://rclone.org/docs/#checkers-int) option for more on that. ✨

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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🐚 rclone completion 🐚

Output completion script for a given shell.

✨ Synopsis ✨

Generates a shell completion script for rclone. Run it with --help to list the supported shells. Bestie, tab-completion is a lifestyle. ⭐

🌸 Options 🌸

• -h, --help — help for completion

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👑 See Also 👑

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.
• rclone completion bash (https://rclone.org/commands/rclone_completion_bash/) — Output bash completion script for rclone.
• rclone completion fish (https://rclone.org/commands/rclone_completion_fish/) — Output fish completion script for rclone.
• rclone completion powershell (https://rclone.org/commands/rclone_completion_powershell/) — Output powershell completion script for rclone.
• rclone completion zsh (https://rclone.org/commands/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.

So by default, when you run it with no arguments at all:

rclone completion bash

the generated script gets written to:

/etc/bash_completion.d/rclone

which means rclone will probably need to be run as root, or with sudo. 😭 (the classic "why do I need permission for everything" moment)

But if you supply a path to a file as the command line argument, then the generated script gets written to that file instead — and in that case you should not need root privileges. Slay. 💅

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

If you've installed the script into the default location, you can just log out and log in again to use the autocompletion script.

Or alternatively, you can source the script directly:

. /path/to/my_bash_completion_scripts/rclone

and the autocompletion functionality gets added to your current shell right then and there. Gorgeous. ✨

rclone completion bash [output_file] [flags]

🌸 Options 🌸

• -h, --help — help for bash

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👑 See Also 👑

• rclone completion (https://rclone.org/commands/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 it will probably need to be run with sudo or as root, like:

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 (https://rclone.org/flags/) for global options not listed here.

👑 See Also 👑

• rclone completion (https://rclone.org/commands/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.

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 (https://rclone.org/flags/) for global options not listed here.

👑 See Also 👑

• rclone completion (https://rclone.org/commands/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 it will probably need to be run with sudo or as root, like:

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 (https://rclone.org/flags/) for global options not listed here.

👑 See Also 👑

• rclone completion (https://rclone.org/commands/rclone_completion/) — Output completion script for a given shell.

🎀 rclone config create 🎀

Create a new remote with name, type and options. no cap, it's the glow-up command 💅

Synopsis

Create a new remote of name with type and options. Those options get passed in as pairs of key value, or as key=value. either way bestie, both work 💖

So like, if you wanna make a swift remote called myremote using auto config, you'd do:

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

And say you wanted to configure a Google Drive remote but using remote authorization, you'd do this:

rclone config create mydrive drive config_is_local=false

Big note: if the config process would normally ask you a question, the default is taken (unless --non-interactive is used). And every single time that happens, rclone will print or DEBUG a message telling you how to affect the value that got taken. so you're never just guessing 🫶

If any of the parameters you pass is a password field, rclone will automatically obscure them for you — if they aren't already obscured — before putting them into the config file. ✨

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, 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 --non-interactive flag is for apps that wanna configure rclone themselves instead of 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. it's giving very structured, very demure 📋

It'll 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). And any default config values should be passed in with each invocation of --continue. literally every time, don't skip it 🙈

At the end of the non interactive process, rclone will return a result with State as empty string. that's the finish line 🏁

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. iconic of it tbh 🧚

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
• --no-output — Don't provide any output
• --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 (https://rclone.org/flags/) for global options not listed here.

🌈 See Also 🌈

• rclone config (https://rclone.org/commands/rclone_config/) - Enter an interactive configuration session.

---

💜 rclone config delete 💜

Delete an existing remote. bye bestie, we hardly knew ye 😭

rclone config delete name [flags]

Options

• -h, --help — help for delete

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config (https://rclone.org/commands/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. yeah, the token is GONE, we said what we said 💅

To reconnect use rclone config reconnect.

rclone config disconnect remote: [flags]

Options

• -h, --help — help for disconnect

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config (https://rclone.org/commands/rclone_config/) - Enter an interactive configuration session.

---

⭐ rclone config dump ⭐

Dump the config file as JSON. raw. unfiltered. unhinged. 🔥

rclone config dump [flags]

Options

• -h, --help — help for dump

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config (https://rclone.org/commands/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. main character energy fr fr 👑

rclone config edit [flags]

Options

• -h, --help — help for edit

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config (https://rclone.org/commands/rclone_config/) - Enter an interactive configuration session.

---

🔐 rclone config encryption 🔐

set, remove and check the encryption for the config file — lock it down, bestie 💖

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 (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config (https://rclone.org/commands/rclone_config/) - Enter an interactive configuration session.
• rclone config encryption check (https://rclone.org/commands/rclone_config_encryption_check/) - Check that the config file is encrypted
• rclone config encryption remove (https://rclone.org/commands/rclone_config_encryption_remove/) - Remove the config file encryption password
• rclone config encryption set (https://rclone.org/commands/rclone_config_encryption_set/) - Set or change the config file encryption password

---

🌸 rclone config encryption check 🌸

Check that the config file is encrypted ✅

Synopsis

This checks the config file is encrypted and that you can decrypt it.

It will attempt to decrypt the config using the password you supply.

If decryption fails it will return a non-zero exit code if using --password-command, otherwise it will prompt again for the password.

If the config file is not encrypted it will return a non zero exit code.

rclone config encryption check [flags]

Options

• -h, --help — help for check

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config encryption (https://rclone.org/commands/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

This removes the config file encryption, returning it to un-encrypted. it's giving "we're so back" 💅

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

If the config was not encrypted then no error will be returned and this command will do nothing. so chill, it's fine 🫶

rclone config encryption remove [flags]

Options

• -h, --help — help for remove

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• rclone config encryption (https://rclone.org/commands/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. Like, glow-up time for your password bestie. 💅

✨ Synopsis ✨

This command sets or changes the config file encryption password.

If there was no config password set, then it sets a new one. If there was one already, it changes the existing config password. Either way, you're covered. 🫶

Heads up bestie: if you're changing an encryption password using --password-command, then that command gets called once to decrypt the config using the old password, and then again to read the new password so it can re-encrypt the config. Two calls, two jobs, no confusion. 😭

When --password-command is called to change the password, the environment variable RCLONE_PASSWORD_CHANGE=1 will be set. So if you're changing passwords programmatically, you can use that 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 (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config encryption (https://rclone.org/commands/rclone_config_encryption/) — set, remove and check the encryption for the config file

---

🎀 rclone config file 🎀

Show path of configuration file in use. Like, where IS the config at?? Let's find out. 🦋

rclone config file [flags]

✨ Options ✨

• -h, --help — help for file

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🍓 rclone config password 🍓

Update password in an existing remote.

✨ 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). 😳 No hiding, bestie.

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

Obsolete alert!! This command is obsolete now that config update and config create both support obscuring passwords directly. It's giving legacy. 💀

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

✨ Options ✨

• -h, --help — help for password

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🧚 rclone config paths 🧚

Show paths used for configuration, cache, temp etc. Like a lil tour of everywhere rclone keeps its stuff. 🏠✨

rclone config paths [flags]

✨ Options ✨

• -h, --help — help for paths

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

💜 rclone config providers 💜

List in JSON format all the providers and options. All of them. Every single one. JSON girlies rise. 🔥

rclone config providers [flags]

✨ Options ✨

• -h, --help — help for providers

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🦋 rclone config reconnect 🦋

Re-authenticates user with remote. The oauth flow is BACK and it wants your whole attention. 😭

✨ 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. Yes, again. Sit down, click the link, it's fine. 🫶

rclone config reconnect remote: [flags]

✨ Options ✨

• -h, --help — help for reconnect

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🌈 rclone config redacted 🌈

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

✨ 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. ✨ Censored, slay, privacy icon behavior.

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. 👀 Like, go through it yourself, bestie. Please.

rclone config redacted [<remote>] [flags]

✨ Options ✨

• -h, --help — help for redacted

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🎀 rclone config show 🎀

Print (decrypted) config file, or the config for a single remote. No XXXs here, this is the real deal, so maybe don't post it on the internet, okay bestie? 🙈

rclone config show [<remote>] [flags]

✨ Options ✨

• -h, --help — help for show

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

✨ rclone config string ✨

Print connection string for a single remote. One line, all the info, iconic. 👑

✨ Synopsis ✨

Print a connection string for a single remote.

The connection strings (https://rclone.org/docs/#connection-strings) can be used wherever a remote is needed, and can be more convenient than using the config file — especially if using the RC API. 🔥

Backend parameters may be provided to the command also.

Example:

$ rclone config string s3:rclone --s3-no-check-bucket
:s3,access_key_id=XXX,no_check_bucket,provider=AWS,region=eu-west-2,secret_access_key=YYY:rclone

NB the strings are not quoted for use in shells (eg bash, powershell, windows cmd). Most will work if enclosed in "double quotes", however connection strings that contain double quotes will require further quoting which is very shell dependent. 😭 Shells are like that.

rclone config string <remote> [flags]

✨ Options ✨

• -h, --help — help for string

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🌸 rclone config touch 🌸

Ensure configuration file exists. Just making sure the config file is there, existing, doing its lil thing. 💖

rclone config touch [flags]

✨ Options ✨

• -h, --help — help for touch

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🫶 rclone config unset 🫶

Unset options in an existing remote.

✨ Synopsis ✨

Remove one or more options from an existing remote. The options to remove should be passed in as a list of key names.

For example, to remove the client_id and client_secret options from a remote of name myremote you would do:

rclone config unset myremote client_id client_secret

This removes the keys from the config file entirely, which is different from setting them to an empty string with config update. Removing a key restores rclone's default behaviour for that option, whereas setting it to an empty string overrides the default with an empty value. 💅 Two very different vibes, fr fr.

You can't unset the type of a remote — use config delete to remove the whole remote instead. 🗑️

rclone config unset name [key]+ [flags]

✨ Options ✨

• -h, --help — help for unset

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

💖 rclone config update

Update options in an existing remote. Yes bestie, we're editing a remote that already exists. 🔧

✨ Synopsis

Update an existing remote's options. The options get passed in as pairs of key value, or as key=value. Either one, we don't gatekeep.

So like, if you wanted to update the env_auth field of a remote called myremote, you'd do:

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

And if the remote uses OAuth, the token is gonna get updated too — so if you do not want that, just toss in an extra parameter like this:

rclone config update myremote env_auth=true config_refresh_token=false

Major note: if the config process would normally ask you a question, the default is what gets taken (unless --non-interactive is passed). Every single time that happens, rclone will print — or DEBUG — a message telling you how to affect the value that got taken. So it's not ghosting you, it's just being quiet about it. 🌸

Now, if any of the parameters you pass is a password field, rclone will automatically obscure it if it isn't already obscured before it lands in the config file. Considerate king behavior. 👑

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

The --non-interactive flag is for applications that wanna configure rclone themselves instead of using rclone's text-based configuration questions. If this flag is set and rclone needs to ask the user a question, a JSON blob comes back with the question inside it. It's giving very "let the robots talk" and honestly? iconic. 🤖✨

That blob looks something like this (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 what rclone config providers returns. The question should be asked to the user and returned to rclone as the --result option, along with the --state parameter. Teamwork, fr fr.

The keys of Option are used like this:

• 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. Don't hide it, that's rude. 🙈

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

Heads up: when you're using --continue, all passwords should be passed in the clear (not obscured). And any default config values should be passed in with each invocation of --continue. Every time. No skipping. 💅

At the end of the non-interactive process, rclone will return a result with State as an empty string. That's the little "we're done here" signal. 🎀

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.

Oh and also — bin/config.py in the rclone source implements this protocol as a readable demonstration. Cute little reference implementation, lowkey a great place to snoop for how it all works. 🦋

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
• --no-output — Don't provide any output
• --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 (https://rclone.org/flags/) for global options not listed here.

🌈 See Also

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🫶 rclone config userinfo

Prints info about logged in user of remote. Yes, it's a little stalker-ish but for yourself. 🔍

✨ Synopsis

This prints the details of the person logged in to the cloud storage system. Very "who am I on this server" energy and honestly sometimes you just need to know. 😌

rclone config userinfo remote: [flags]

⭐ Options

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

See the global flags page (https://rclone.org/flags/) for global options not listed here.

🌈 See Also

• rclone config (https://rclone.org/commands/rclone_config/) — Enter an interactive configuration session.

---

🧚 rclone convmv

Convert file and directory names in place. Glow-up for your filenames, no cap. ✨

✨ Synopsis

convmv supports advanced path name transformations for converting and renaming files and directories by applying prefixes, suffixes, and other alterations. It's the makeover montage but for path strings. 💅

• --name-transform prefix=XXXX — Prepends XXXX to the file name.
• --name-transform suffix=XXXX — Appends XXXX to the file name after the extension.
• --name-transform suffix_keep_extension=XXXX — Appends XXXX to the file name while preserving the original file extension.
• --name-transform trimprefix=XXXX — Removes XXXX if it appears at the start of the file name.
• --name-transform trimsuffix=XXXX — Removes XXXX if it appears at the end of the file name.
• --name-transform regex=pattern/replacement — Applies a regex-based transformation.
• --name-transform replace=old:new — Replaces occurrences of old with new in the file name.
• --name-transform date={YYYYMMDD} — Appends or prefixes the specified date format.
• --name-transform truncate=N — Truncates the file name to a maximum of N characters.
• --name-transform truncate_keep_extension=N — Truncates the file name to a maximum of N characters while preserving the original file extension.
• --name-transform truncate_bytes=N — Truncates the file name to a maximum of N bytes (not characters).
• --name-transform truncate_bytes_keep_extension=N — Truncates the file name to a maximum of N bytes (not characters) while preserving the original file extension.
• --name-transform base64encode — Encodes the file name in Base64.
• --name-transform base64decode — Decodes a Base64-encoded file name.
• --name-transform encoder=ENCODING — Converts the file name to the specified encoding (e.g., ISO-8859-1, Windows-1252, Macintosh).
• --name-transform decoder=ENCODING — Decodes the file name from the specified encoding.
• --name-transform charmap=MAP — Applies a character mapping transformation.
• --name-transform lowercase — Converts the file name to lowercase.
• --name-transform uppercase — Converts the file name to UPPERCASE.
• --name-transform titlecase — Converts the file name to Title Case.
• --name-transform ascii — Strips non-ASCII characters.
• --name-transform url — URL-encodes the file name.
• --name-transform nfc — Converts the file name to NFC Unicode normalization form.
• --name-transform nfd — Converts the file name to NFD Unicode normalization form.
• --name-transform nfkc — Converts the file name to NFKC Unicode normalization form.
• --name-transform nfkd — Converts the file name to NFKD Unicode normalization form.
• --name-transform command=/path/to/my/program — Executes an external program to transform file names.

Conversion modes:

none
nfc
nfd
nfkc
nfkd
replace
prefix
suffix
suffix_keep_extension
trimprefix
trimsuffix
index
date
truncate
truncate_keep_extension
truncate_bytes
truncate_bytes_keep_extension
base64encode
base64decode
encoder
decoder
ISO-8859-1
Windows-1252
Macintosh
charmap
lowercase
uppercase
titlecase
ascii
url
regex
command

Char maps:

…and the rest of the charmap menu just keeps going, bestie, no skips:

• IBM-Code-Page-037
• IBM-Code-Page-437
• IBM-Code-Page-850
• IBM-Code-Page-852
• IBM-Code-Page-855
• Windows-Code-Page-858
• IBM-Code-Page-860
• IBM-Code-Page-862
• IBM-Code-Page-863
• IBM-Code-Page-865
• IBM-Code-Page-866
• IBM-Code-Page-1047
• IBM-Code-Page-1140
• ISO-8859-1
• ISO-8859-2
• ISO-8859-3
• ISO-8859-4
• ISO-8859-5
• ISO-8859-6
• ISO-8859-7
• ISO-8859-8
• ISO-8859-9
• ISO-8859-10
• ISO-8859-13
• ISO-8859-14
• ISO-8859-15
• ISO-8859-16
• KOI8-R
• KOI8-U
• Macintosh
• Macintosh-Cyrillic
• Windows-874
• Windows-1250
• Windows-1251
• Windows-1252
• Windows-1253
• Windows-1254
• Windows-1255
• Windows-1256
• Windows-1257
• Windows-1258
• X-User-Defined

---

Encoding masks — the other little squad of names you can hand to the encoder transform 💅:

• Asterisk
• BackQuote
• BackSlash
• Colon
• CrLf
• Ctl
• Del
• Dollar
• Dot
• DoubleQuote
• Exclamation
• Hash
• InvalidUtf8
• LeftCrLfHtVt
• LeftPeriod
• LeftSpace
• LeftTilde
• LtGt
• None
• Percent
• Pipe
• Question
• Raw
• RightCrLfHtVt
• RightPeriod
• RightSpace
• Semicolon
• SingleQuote
• Slash
• SquareBracket

---

✨ Examples ✨

okay no cap this is the fun part, watch the glow-ups happen in real time 🦋:

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,uppercase"
// Output: STORIES/THE QUICK BROWN FOX!.TXT

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,replace=Fox:Turtle" --name-transform "all,replace=Quick:Slow"
// Output: stories/The Slow Brown Turtle!.txt

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,base64encode"
// Output: c3Rvcmllcw==/VGhlIFF1aWNrIEJyb3duIEZveCEudHh0

rclone convmv "c3Rvcmllcw==/VGhlIFF1aWNrIEJyb3duIEZveCEudHh0" --name-transform "all,base64decode"
// Output: stories/The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,nfc"
// Output: stories/The Quick Brown 🦊 Fox Went to the Café!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,nfd"
// Output: stories/The Quick Brown 🦊 Fox Went to the Cafe!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox!.txt" --name-transform "all,ascii"
// Output: stories/The Quick Brown  Fox!.txt

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,trimsuffix=.txt"
// Output: stories/The Quick Brown Fox!

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,prefix=OLD_"
// Output: OLD_stories/OLD_The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,charmap=ISO-8859-7"
// Output: stories/The Quick Brown _ Fox Went to the Caf_!.txt

rclone convmv "stories/The Quick Brown Fox: A Memoir [draft].txt" --name-transform "all,encoder=Colon,SquareBracket"
// Output: stories/The Quick Brown Fox： A Memoir ［draft］.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,truncate=21"
// Output: stories/The Quick Brown 🦊 Fox

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,command=echo"
// Output: stories/The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown Fox!" --name-transform "date=-{YYYYMMDD}"
// Output: stories/The Quick Brown Fox!-20261009

rclone convmv "stories/The Quick Brown Fox!" --name-transform "date=-{macfriendlytime}"
// Output: stories/The Quick Brown Fox!-2026-10-09 1021AM

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,regex=[\\.\\w]/ab"
// Output: ababababababab/ababab ababababab ababababab ababab!abababab

---

okay so about that regex command 👑: it generally takes Perl-style regular expressions, and the exact syntax is the one defined in the Go regular expression reference (https://golang.org/pkg/regexp/syntax/). Your replacement string can hold capturing group variables — you reference capturing groups with the syntax $name or ${name}, where name can be a named capturing group, or honestly it can just be the index as a number, whatever's easier. Wanna insert a literal $? Use $$ 💅.

You can stack multiple transformations and they run in sequence, applied in the order you typed them on the command line. periodt.

Also, --name-transform is not a convmv-exclusive queen — it's also available in sync, copy, and move 👑.

---

🌸 Files vs Directories 🌸

By default --name-transform will only apply to file names. That means only the leaf file name gets transformed. But some of the transforms genuinely hit different when applied to the whole path, or just to directories. So to pick which part of the file path is affected, you can add some tags to your --name-transform.

• file — Only transform the leaf name of files (DEFAULT)
• dir — Only transform name of directories — these may appear anywhere in the path
• all — Transform the entire path for files and directories

You use it by dropping the tag into the transform name, like this: --name-transform file,prefix=ABC or --name-transform dir,prefix=DEF.

For some conversions using all is more likely to be useful, for example --name-transform all,nfc.

Heads up bestie: --name-transform may not add path separators / to the name. That will cause an error. 😭

---

🎀 Ordering and Conflicts 🎀

• Transformations will be applied in the order specified by the user.
  • If the file tag is in use (the default) then only the leaf name of files will be transformed.
  • If the dir tag is in use then directories anywhere in the path will be transformed
  • If the all tag is in use then directories and files anywhere in the path will be transformed
  • Each transformation will be run one path segment at a time.
  • If a transformation adds a / or ends up with an empty path segment then that will be an error.
• It is up to the user to put the transformations in a sensible order.
  • Conflicting transformations, such as prefix followed by trimprefix or nfc followed by nfd, are possible.
  • Instead of enforcing mutual exclusivity, transformations are applied in sequence as specified by the user, allowing for intentional use cases (e.g., trimming one prefix before adding another).
  • Users should be aware that certain combinations may lead to unexpected results and should verify transformations using --dry-run before execution.

---

💀 Race Conditions and Non-Deterministic Behavior 💀

Some transformations, like replace=old:new, may introduce conflicts where multiple source files map to the same destination name. And that can lead to race conditions when you're doing concurrent transfers. It's up to the user to anticipate these, fr fr.

• If two files from the source are transformed into the same name at the destination, the final state may be non-deterministic.
• Running rclone check after a sync using such transformations may erroneously report missing or differing files due to overwritten results.

To minimize risks, users should:

• Carefully review transformations that may introduce conflicts.
• Use --dry-run to inspect changes before executing a sync (but keep in mind that it won't show the effect of non-deterministic transformations).
• Avoid transformations that cause multiple distinct source files to map to the same destination name.
• Consider disabling concurrency with --transfers=1 if necessary.
• Certain transformations (e.g. prefix) will have a multiplying effect every time they are used. Avoid these when using bisync.

rclone convmv dest:path --name-transform XXX [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 convmv

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) for global options not listed here.

---

💖 Copy Options 💖

Flags for anything which can copy a file 🫶

• --check-first — do all the checks before starting any transfers 💅
• -c, --checksum — check for changes using size & checksum (if the backend has one, or fallback to size only) 🌸
• --compare-dest stringArray — include extra server-side paths during comparison 👀
• --copy-dest stringArray — implies --compare-dest, but also copies files from those paths into the destination, slay
• --cutoff-mode HARD|SOFT|CAUTIOUS — mode for stopping transfers when you hit the max transfer limit: HARD|SOFT|CAUTIOUS (default HARD)
• --ignore-case-sync — ignore case when synchronizing 🦋
• --ignore-checksum — skip the post-copy checksum check
• --ignore-existing — skip every file that already exists on the destination, periodt
• --ignore-size — ignore size when skipping, so use modtime or checksum instead
• -I, --ignore-times — don't skip items that match size and time — transfer literally everything, no vibe check 😭
• --immutable — do not modify files; fail if existing files have been modified 🔥
• --inplace — download straight to the destination file instead of the whole atomic download-to-temp-then-rename thing
• -l, --links — translate symlinks to/from regular files using a .rclonelink extension
• --max-backlog int — maximum number of objects in the 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 that still counts as "the same" (default 1ns)
• --multi-thread-chunk-size SizeSuffix — chunk size for multi-thread downloads / uploads, if the filesystem doesn't set its own (default 64Mi)
• --multi-thread-cutoff SizeSuffix — use multi-thread downloads for files above this size (default 256Mi)
• --multi-thread-streams int — number of streams for multi-thread downloads (default 4)
• --multi-thread-write-buffer-size SizeSuffix — in-memory buffer size for writing while in multi-thread mode (default 128Ki)
• --name-transform stringArray — transform paths during the copy process 🎀
• --no-check-dest — don't check the destination at all, just copy regardless
• --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, e.g. 'size,descending'
• --partial-suffix string — add this suffix to the 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 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

---

✨ Important Options ✨

Important flags that are useful for most commands, bestie — memorize these 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 it for even more) 🔥

---

🎀 Filter Options 🎀

Flags for filtering directory listings

• --delete-excluded — delete files on the dest that were 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 a 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)
• --files-from0 stringArray — read a list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --ignore-case — ignore case in filters (case insensitive) 🌸
• --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 the 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 the 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 - 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 the suffix ms|s|m|h|d|w|M|y (default off)
• --min-size SizeSuffix — only transfer files bigger than this, in KiB or with the 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 the backend supports it; uses more memory but fewer transactions ⭐

---

🫶 See Also 🫶

• rclone (https://rclone.org/commands/rclone/) — show help for rclone commands, flags and backends.

---

🌈 rclone copyto 🌈

Copy files from source to dest, skipping identical files. Iconic, no cap.

💅 Synopsis 💅

If source:path is a file or directory then it copies it to a file or directory named dest:path. Simple as that, bestie.

This can be used to copy a single file to a destination with a name different from its source — like, uploading and renaming in one step, obsessed 😍. If the source is a directory then it acts exactly like the copy (https://rclone.org/commands/rclone_copy/) command.

So

rclone copyto src dst

where src and dst are rclone paths — either remote:path or /path/to/local or C:\windows\path\if\on\windows.

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. (Not me deleting your stuff — I literally won't 🙈)

If you're 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 ✨

🎀 Logger Flags 🎀

The --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name supplied (or stdout if it is -). 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. Lowkey the receipts 📝

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 --dest-after flag writes a list file using the same format flags as lsf (https://rclone.org/commands/rclone_lsf/#synopsis) (including customizable options for hash, modtime, etc. (https://rclone.org/commands/rclone_lsf/#synopsis)). 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 command is finished.

When the --no-traverse flag is set, all logs involving files that exist only on the destination will be incomplete or completely missing. 🫠

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

Note also that each file is logged during execution, 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 copyto source:path dest:path [flags]

Options 💅

okay bestie, here's the whole little toolkit of flags that only apply to copyto — read 'em and weep (with joy):

• --absolute — slaps a leading / in front of every path name. no thoughts, just absolute paths. 🌸
• --combined string — makes a combined report of all the changes and dumps it into this file. 📝
• --csv — output in CSV format, because spreadsheets are lowkey eternal. ✨
• --dest-after string — reports every single file that exists on the destination after the sync has done its thing.
• --differ string — reports all the non-matching files to this file. the gossip file, basically.
• -d, --dir-slash — appends a slash to directory names (default true). yes queen, trailing slash energy.
• --dirs-only — only list directories. files? never heard of her. 🙈
• --error string — reports all files with errors (whether hashing or reading) to this file. keeping receipts on the flops.
• --files-only — only list files (default true). directories stay unbothered.
• -F, --format string — the output format. see lsf help for the deets (default "p").
• --hash h — use this hash when h shows up in the format. your options: MD5, SHA-1, DropboxHash (default "md5").
• -h, --help — help for copyto. the classic. 🫶
• --match string — reports all the matching files to this file. soulmates only. 💖
• --missing-on-dst string — reports all files missing from the destination to this file. where did they GO.
• --missing-on-src string — reports all files missing from the source to this file.
• -s, --separator string — the separator for items in the format (default ";").
• -t, --timeformat string — specify your very own custom time format — see the docs for details (default: 2006-01-02 15:04:05). 🎀

options shared with other commands are described right down below, no cap. and for global options that aren't listed here, go peek at the global flags page at https://rclone.org/flags/.

---

Copy Options 🫶

these are the flags for anything that can copy a file. which is a lot of things, tbh.

• --check-first — do all the checks before starting any transfers. patient queen behavior.
• -c, --checksum — check for changes using size & checksum (if it's available, or fall back to size only).
• --compare-dest stringArray — include additional server-side paths during the comparison.
• --copy-dest stringArray — implies --compare-dest but also copies files from those paths into the destination.
• --cutoff-mode HARD|SOFT|CAUTIOUS — the mode for stopping transfers once you hit the max transfer limit, either HARD, SOFT or CAUTIOUS (default HARD).
• --ignore-case-sync — ignore case when synchronizing.
• --ignore-checksum — skip the post-copy checksum check. living dangerously, love that for you.
• --ignore-existing — skip every file that already exists on the destination.
• --ignore-size — ignore size when skipping, so it uses modtime or checksum instead.
• -I, --ignore-times — don't skip items that match on size and time — transfer everything, unconditionally. no filter, no shame. 🔥
• --immutable — do not modify files, and fail if existing files have been modified.
• --inplace — download straight to 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 — maximum number of objects in the 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. the details matter!! 💜
• --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, if the filesystem doesn't set it itself (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 while in multi-thread mode (default 128Ki).
• --name-transform stringArray — transform paths during the copy process. glow-up for filenames. 🦋
• --no-check-dest — don't check the destination at all, just copy regardless.
• --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 the destination modtime if the files are identical.
• --order-by string — instructions on how to order the transfers, e.g. 'size,descending'.
• --partial-suffix string — add this partial-suffix to the 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 (like copy) to work across different configs. cross-config romance. 💞
• --size-only — skip based on size only, not modtime or checksum.
• --streaming-upload-cutoff SizeSuffix — the cutoff for switching to chunked upload if 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.

---

Important Options ⭐

the important flags that are useful for basically most commands. if you learn nothing else, learn these:

• -n, --dry-run — do a trial run with no permanent changes. rehearsal, bestie. 🎭
• -i, --interactive — enable interactive mode.
• -v, --verbose count — print lots more stuff (repeat it for even more). spammy and we love her.

---

Filter Options 🌈

flags for filtering directory listings. this is where you become the main character of your own file selection:

• --delete-excluded — delete files on the destination that were excluded from the 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 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 the lines (use - to read from stdin).
• --files-from0 stringArray — read a list of source-file names from a file using NUL as the separator (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).
• --hash-filter string — partition filenames by hash k/n or randomly with @/n.
• --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 the 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 the suffix B|K|M|G|T|P (default off).
• --metadata-exclude stringArray — exclude metadata 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 metadata 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 the suffix ms|s|m|h|d|w|M|y (default off).
• --min-size SizeSuffix — only transfer files bigger than this, in KiB or with the suffix B|K|M|G|T|P (default off).

---

Listing Options 🌸

flags for listing directories. short and sweet, like a good text back:

• --default-time Time — the time to show if the modtime is unknown for files and directories (default 2000-01-01T00:00:00Z).
• --fast-list — use a recursive list if it's available; uses more memory but fewer transactions. trade-off queen. 💅

---

See Also 👑

• rclone (https://rclone.org/commands/rclone/) — show help for rclone commands, flags and backends. the mothership fr fr. 🚀

🌸 rclone copyurl 🌸

Bestie, this one is SO handy — it grabs the content of a URL and yeets it straight to dest:path. No temp files, no middleman, no drama. 💅

✨ Synopsis ✨

So the vibe is: download a URL's content and copy it to the destination without saving it in temporary storage. Iconic behaviour, honestly.

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. Protective queen behaviour, we love to see it.

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

Setting --urls allows you to input a CSV file of URLs in format: URL, FILENAME. If --urls is in use then replace the URL in the arguments with the file containing the URLs, e.g.:

rclone copyurl --urls myurls.csv remote:dir

Missing filenames will be autogenerated equivalent to using --auto-filename. Note that --stdout and --print-filename are incompatible with --urls. This will do --transfers copies in parallel. Note that if --auto-filename is desired for all URLs then a file with only URLs and no filename can be used.

Each FILENAME in the CSV file can start with a relative path which will be appended to the destination path provided at the command line. For example, running the command shown above with the following CSV file will write two files to the destination: remote:dir/local/path/bar.json and remote:dir/another/local/directory/qux.json

https://example.org/foo/bar.json,local/path/bar.json
https://example.org/qux/baz.json,another/local/directory/qux.json

🛠️ Troubleshooting 🛠️

Okay so if you can't get rclone copyurl to work then here are some things you can try, bestie:

• --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
• --urls — Use a CSV file of links to process multiple URLs

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) 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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🔐 rclone cryptcheck 🔐

Cryptcheck checks the integrity of an encrypted remote. Integrity check era ✨

✨ Synopsis ✨

Checks a remote against an encrypted (https://rclone.org/crypt/) remote. This is the equivalent of running rclone check (https://rclone.org/commands/rclone_check/), but able to check the checksums of the encrypted remote.

For it to work the underlying remote of the cryptedremote must support some kind of checksum.

It works by reading the nonce from each file on the cryptedremote: and using that to encrypt each file on the remote:. It then checks the checksum of the underlying file on the cryptedremote: against the checksum of the file it has just encrypted.

Use it like this

rclone cryptcheck /path/to/files encryptedremote:path

You can use it like this also, but 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. 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.

• = 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 (https://rclone.org/docs/#checkers-int) 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 (https://rclone.org/flags/) 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)

🦋 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🔓 rclone cryptdecode 🔓

Cryptdecode returns unencrypted file names. Decoding the secret messages bestie 🔮

✨ Synopsis ✨

Returns unencrypted file names when provided with a list of encrypted file names. List limit is 10 items.

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 (https://rclone.org/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 (https://rclone.org/flags/) for global options not listed here.

🌈 See Also 🌈

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

🗑️ rclone deletefile

Bye bye one single file on a remote. That's it, that's the whole job bestie 💅

📖 Synopsis

Okay so: this removes a single file from a remote. And listen — unlike delete it can NOT be used to nuke a directory, and it does not obey include/exclude filters. Which means if the file you named actually exists, it is getting removed. Every time. No filter drama, no vibes-based negotiation. 🫶

rclone deletefile remote:path [flags]

🎀 Options

• -h, --help — help for deletefile

The options that are shared with the other commands are right below this. And for the global options that didn't make the list here, go peek at the global flags page (<https://rclone.org/flags/>). ✨

👑 Important Options

These are the important flags, and they're useful for basically every command, 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)

---

📝 rclone gendocs

Spits out markdown docs for rclone into whatever directory you hand it.

📖 Synopsis

So what this does: it produces markdown docs for all the rclone commands and drops them in the directory you supply. The formatting is set up so hugo can render them straight onto the rclone.org website. Fancy, honestly. 🌸

rclone gendocs output_directory [flags]

🎀 Options

• -h, --help — help for gendocs

For the global options that aren't listed here, check the global flags page (<https://rclone.org/flags/>). 💖

👀 See Also

• rclone (<https://rclone.org/commands/rclone/>) — Show help for rclone commands, flags and backends.

---

🧚 rclone gitannex

Talks to git-annex over stdin/stdout. It's giving middleman energy.

📖 Synopsis

rclone's gitannex subcommand is what lets git-annex (<https://git-annex.branchable.com/>) store stuff on and pull stuff back from an rclone remote. Key detail bestie: it's meant to be run by git-annex, not by you directly. So hands off, let git-annex drive. 🚗

🐧 Installation on Linux

1. Skip this step if your git-annex is version 10.20240430 (<https://git-annex.branchable.com/news/version_10.20240430/>) or newer. If it's older, you must create a symlink somewhere on your PATH with one particular name. That symlink is how git-annex tells rclone "hey I want 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

2. Add a new remote to your git-annex repo. This new remote is what wires git-annex up 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 (<https://github.com/git-annex-remote-rclone/git-annex-remote-rclone>) remote over 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 has to be one that's configured in your rclone.conf file, which you can locate with rclone config file.

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

3. 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

For the global options that aren't listed here, the global flags page has your back (<https://rclone.org/flags/>). ⭐

👀 See Also

• rclone (<https://rclone.org/commands/rclone/>) — Show help for rclone commands, flags and backends.

---

💻 rclone gui

Opens up the web based GUI. Main character interface moment.

📖 Synopsis

This command boots an embedded web GUI for rclone and opens it in your default browser.

Here's the tea: it starts an RC API server AND a GUI server on separate localhost ports, generates login credentials automatically (unless you pass --no-auth), and opens your browser already authenticated. So smooth. ✨

rclone gui

By default rclone gui serves the web GUI that got embedded into the rclone binary at build time, from <https://github.com/rclone/rclone-web/>. You can override that by passing a path to either an unpacked GUI directory or a dist.zip archive (like, say, one you downloaded from the rclone-web releases page):

rclone gui ./my-dist/
rclone gui ./dist.zip

This is useful for iterating on the GUI locally without rebuilding rclone, or for serving a different GUI release than the one that's embedded. Obsessed honestly. 💖

Use --no-open-browser to skip opening the browser automatically:

rclone gui --no-open-browser

Use --addr to bind the GUI to a specific address:

rclone gui --addr localhost:5580

Use --user and --pass to set specific credentials:

rclone gui --user admin --pass secret

Use --no-auth to disable authentication entirely:

rclone gui --no-auth

For more help see the GUI docs (<https://rclone.org/gui/>). 🦋

rclone gui [path] [flags]

🎀 Options

• --addr stringArray — IPaddress:Port for the GUI server (default auto-chosen localhost port)
• --api-addr stringArray — IPaddress:Port for the RC API server (default auto-chosen localhost port)
• --enable-metrics — Enable OpenMetrics/Prometheus compatible endpoint at /metrics
• -h, --help — help for gui
• --no-auth — Don't require auth for the RC API
• --no-open-browser — Skip opening the browser automatically
• --pass string — Password for RC authentication
• --user string — User name for RC authentication

The options shared with other commands are described next, and for the global options that aren't listed here, hit up the global flags page (<https://rclone.org/flags/>). 🌈

🎛️ 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-response-header stringArray — Set HTTP header for all responses, overriding existing values
• --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-user-from-header string — User name from a defined HTTP header
• --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 (<https://rclone.org/commands/rclone/>) — Show help for rclone commands, flags and backends.

🌸 rclone hashsum 🌸

okay bestie, this one produces a hashsum file for ALL the objects chilling in the path 💅

✨ Synopsis ✨

So basically: it makes a hash file for every object in the path, using the hash you named. The output format is exactly the same as the standard md5sum/sha1sum tool — no cap.

By default, the hash gets requested from the remote. If the remote doesn't support that hash, bestie, you get nothing back — no hash for you 🙈. But if you throw in the download flag, the file gets downloaded from the remote and hashed locally, which means literally any hash works for any remote. iconic.

For MD5 and SHA1 there are also dedicated commands — md5sum (https://rclone.org/commands/rclone_md5sum/) and sha1sum (https://rclone.org/commands/rclone_sha1sum/) — because they're extra like that.

Also!! This command can hash data it receives on standard input (stdin) 💖. Just don't pass a remote:path, or pass a hyphen as the remote:path when there's data to read. (btw if there's no data to read, the hyphen gets treated literally, as a relative path. sneaky.)

Run it with no hash at all to see the list of every supported hash, like:

$ rclone hashsum
Supported hashes are:
- md5
- sha1
- whirlpool
- crc32
- sha256
- sha512
- blake3
- xxh3
- xxh128

Then:

rclone hashsum MD5 remote:path

Quick note bestie: hash names are case insensitive, and the values come out in lower case. periodt.

rclone hashsum [<hash> 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 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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🔗 rclone link 🔗

Generate public link to file/folder. yes, we're being generous today ✨

✨ Synopsis ✨

Create, retrieve or remove a public link to the given file or folder. look at her go:

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 sets the expiration time — otherwise it uses the default (100 years, bestie, that link is outliving us all 💀). Note that not all backends support the --expire flag — and if the backend doesn't support it, then the link it hands back won't expire. so like, forever-forever.

Use the --unlink flag to remove existing public links to the file or folder. Note not all backends support the "--unlink" flag either — the ones that don't will just ignore it, no drama 🫶.

If it works, the last line of the output will contain the link. Exact capabilities depend on the remote, but by default the link will always be created with the least constraints — e.g. no expiry, no password protection, accessible without an account. public public.

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 (https://rclone.org/flags/) for global options not listed here.

💖 See Also 💖

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

📋 rclone listremotes 📋

List all the remotes in the config file AND the ones defined in environment variables. all of them, we're not leaving anyone out 💜

✨ 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, as a simple list of remote names. If you use the --long flag, you get a tabular format including the remote names, types and descriptions 👑. Using the --json flag gives you machine-readable output instead, which always includes all attributes — including the source (file or environment).

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

By default filtering uses non-anchored matching, so --type box also matches dropbox. Use --exact to match complete values only. iykyk.

rclone listremotes [<filter>] [flags]

🎀 Options 🎀

• --description string — Filter remotes by description
• --exact — Match filter strings exactly instead of using non-anchored glob matching
• -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 (https://rclone.org/flags/) for global options not listed here.

💖 See Also 💖

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

🦋 rclone lsf 🦋

List directories and objects in remote:path formatted for parsing.

✨ Synopsis ✨

okay so bestie, this is the list command that actually plays nice with your scripts 💅. lsf dumps the contents of the source path — both directories AND objects — to standard output in a form that's easy to parse. By default you just get the names of the objects and directories, one per line, and directories get a / glued onto the end.

Like, look:

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

Use the --format option to control what gets listed. By default it's literally just the path, but these little letters let you pick and choose what shows up:

• 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"}

Some backends use composite IDs. In particular, Google Drive shortcuts are normally dereferenced, and their i field contains the target object's ID followed by the shortcut's ID, separated by a tab. This tab is part of the ID field and is not changed by --separator. Use --drive-skip-shortcuts to omit shortcut entries.

So if you wanted the path, size and modification time, you'd use --format "pst", or maybe --format "tsp" to put the path last. Iconic either way.

E.g.

$ 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 specify h in the format you will get the MD5 hash by default, use the --hash flag to change which hash you want. Note that this can be returned as an empty string if it isn't available on the object (and for directories), "ERROR" if there was an error reading it from the object and "UNSUPPORTED" if that object does not support that hash type.

For example, to emulate the md5sum command you can use

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

E.g.

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

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

By default the separator is ; this can be changed with the --separator flag. Note that separators aren't escaped in the path so putting it last is a good strategy 🧠.

E.g.

$ 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 output in CSV standard format. This will escape things in " if they contain ,

E.g.

$ 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

Note that the --absolute parameter is 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 those only (without traversing the whole directory structure):

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 (https://pkg.go.dev/time#pkg-constants) 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
rclone lsf remote:path --format pt --time-format unix
rclone lsf remote:path --format pt --time-format unixnano

--time-format max will automatically truncate 2006-01-02 15:04:05.000000000 to the maximum precision supported by the remote. cute and efficient ✨

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.

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.

On the bucket-based remotes (e.g. s3, gcs, b2) a directory is a key prefix rather than an object, so a listing without -R shows each prefix as one directory entry and not the objects stored under it.

List commands prefer a recursive method that uses more memory but fewer transactions by default. Use --disable ListR to suppress the behavior. See --fast-list (https://rclone.org/docs/#fast-list) for more details.

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 - see docs for details (default: 2006-01-02 15:04:05)

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) - Show help for rclone commands, flags and backends.

fr fr that's the whole vibe, go parse something 💖

🌈 rclone lsjson 💖

List directories and objects in the path in JSON format. it's giving machine-readable, bestie 🤖✨

Synopsis ✨

List directories and objects in the path in JSON format.

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",
}

okay so which properties show up totally depends on the backend, lowkey:

• The property IsBucket will only be included for bucket-based remotes, and only for directories that are buckets. It will always be omitted when the 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 (https://rclone.org/docs/#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 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. 🫠

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). ⏰

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. 🧠

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.

On the bucket-based remotes (e.g. s3, gcs, b2) a directory is a key prefix rather than an object, so a listing without -R shows each prefix as one directory entry and not the objects stored under it. 🪣

List commands prefer a recursive method that uses more memory but fewer transactions by default. Use --disable ListR to suppress the behavior. See --fast-list (https://rclone.org/docs/#fast-list) for more details.

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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🌸 rclone mount 🌸

Mount the remote as file system on a mountpoint. yes bestie we're literally turning your cloud drive into a folder, iconic behavior 👑

Synopsis ✨

Rclone mount 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 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. ⌨️

Okay so the examples below mount to an automatically assigned drive, to a specific drive letter X:, to a path like C:\path\parent\mount (and heads up: the parent directory or drive has to already exist, the mount part must not exist, and this is not supported when you're mounting as a network drive), and the last one mounts as a network share \\cloud\remote and maps 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 it's in foreground mode — whether that's you hitting Ctrl+C, or it catching a SIGINT or SIGTERM signal — the mount should just automatically stop for you. 💅

When it's running in background mode though, bestie, you have to stop the mount yourself, 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. And when that happens? It's on you, the user, to stop the mount manually. No cap. 😭

The size of the mounted file system gets set according to information retrieved from the remote, same as what the rclone about command ((https://rclone.org/commands/rclone_about/)) returns. Remotes with unlimited storage may report only the used size, and then an extra 1 PiB of free space is assumed. And if the remote doesn't support ((https://rclone.org/overview/#optional-features)) the about feature at all, then 1 PiB gets set as both the total size and the free size. Iconic behaviour honestly. ✨

🪟 Installing on Windows

To run rclone mount on Windows you'll need to download and install WinFsp ((https://winfsp.dev)).

WinFsp ((https://github.com/winfsp/winfsp)) is an open-source Windows File System Proxy that makes writing user space file systems for Windows super easy. It hooks you up with a FUSE emulation layer that rclone uses in combination with cgofuse ((https://github.com/winfsp/cgofuse)). Both of these packages are by Bill Zissimopoulos, who was so helpful during the implementation of rclone mount for Windows. King behaviour, we love to see it. 👑

🖥️ 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 based on the assumption that fixed disk drives are fast and reliable, while network drives have relatively high latency and are less reliable. Some settings can also be differentiated between the two types — for example, Windows Explorer should just show 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 — which people often call a network share. And fr fr, if you mount an rclone remote using the default fixed drive mode and start seeing unexpected program errors, freezes or other issues, consider mounting as a network drive instead. 🙈

When you're 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:

The 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 just add the 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, like \\cloud\remote, optionally with a path \\cloud\remote\madeup\path, will be used as-is. Any other string gets used as the share part, after a default prefix of \\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 implicitly sets the --network-mode option, so these two examples give you the same result:

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

You can 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 you specified as the volume name, as if it were specified with --volname. This also implicitly sets --network-mode. Which means these two examples have the same result:

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

There's yet another way to enable network mode and set the share path, and that's passing the "native" libfuse/WinFsp option directly: --fuse-flag --VolumePrefix=\server\share. Note that in this case the path must have just a single backslash prefix.

Note: in previous versions of rclone this was the only supported method. (Ancient history vibes. 🦕)

Read more about drive mapping ((https://en.wikipedia.org/wiki/Drive_mapping)).

See also the Limitations section below. 👀

🔐 Windows filesystem permissions

The FUSE emulation layer on Windows has to 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 way that it has to translate between two whole permission systems... it's giving diplomat energy. 🫶

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 customised with the FUSE options "UserName" and "GroupName", e.g. -o UserName=user123 -o GroupName="Authenticated Users". 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 ((https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation)).

The default permissions correspond to --file-perms 0666 --dir-perms 0777, i.e. read and write permissions for everyone. Which means you will not be able to start any programs from the mount. To be able to do that you have to 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 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" permission, as explained next. 💀

The mapping of permissions is not always trivial, and the result 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, this 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 done for compatibility reasons — e.g. so that users without additional permissions can still read basic metadata about files, like they can in Unix.

WinFsp 2021 (version 1.9) introduced a new FUSE option, "FileSecurity", that allows the complete specification of file security descriptors using SDDL ((https://docs.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-string-format)). With this you get detailed control over the resulting permissions, compared to using the POSIX permissions described above, and no additional permissions will be added automatically for compatibility with Unix. Some example use cases will follow. ✨

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 might 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" permission, 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)". Slay. 💅

⚠️ 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. The result of this is that 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. It's giving ghost drive. 👻

---

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. Like, literally just... don't be admin. That's the whole tip. iconic 💅

To make mapped drives available to the user account that created them — regardless of whether it's running elevated or not — there's a special Windows setting called linked connections (https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/mapped-drives-not-available-from-elevated-command#detail-to-configure-the-enablelinkedconnections-registry-entry) that can be enabled. Go turn it on bestie. ✨

It's also possible to make a drive mount available to everyone on the system, by running the process creating it as the built-in SYSTEM account. There are several ways to do this: One is to use the command-line utility PsExec (https://docs.microsoft.com/en-us/sysinternals/downloads/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 (https://github.com/winfsp/winfsp/wiki/WinFsp-Service-Architecture). Read more in the install documentation (https://rclone.org/install/).

Heads up fr fr: when running rclone as another user, it will not use the configuration file from your profile unless you tell it to with the --config (https://rclone.org/docs/#config-string) option. Note also that it is 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 will then not get the "write extended attributes" permission, and this may prevent writing to files. You can work around this with the FileSecurity option, see example above.

And ooo, one more thing: mapping to a directory path instead of a drive letter does not suffer from the same limitations. 🎀

---

🍎 Mounting on macOS 🍎

Mounting on macOS can be done either via the built-in NFS server (https://rclone.org/commands/rclone_serve_nfs/), macFUSE (https://osxfuse.github.io/) (also known as osxfuse) or FUSE-T (https://www.fuse-t.org/). 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. so many options, we love choices 🦋

🔤 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 (https://rclone.org/commands/rclone_mount/#vfs-case-sensitivity). don't touch it, it's fine, leave it alone 🙈

📡 NFS mount 📡

For macOS (and other platforms where this path is supported), prefer the dedicated rclone nfsmount (https://rclone.org/commands/rclone_nfsmount/) command. It starts the NFS server and performs the mount for you. rclone mount itself still uses FUSE (macFUSE/FUSE-T) and does not switch to NFS via a flag. periodt. ✋

This method spins up an NFS server using serve nfs (https://rclone.org/commands/rclone_serve_nfs/) command and mounts it to the specified mountpoint. If you run this in background mode using --daemon, you will need to send SIGTERM signal to the rclone process using kill command to stop the mount. yes, you gotta actually kill it, it's not gonna let go on its own 💀

Note that --nfs-cache-handle-limit controls the maximum number of cached file handles stored by the nfsmount caching handler. This should not be set 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. (lowkey a whole balancing act, iykyk)

🧩 macFUSE Notes 🧩

If you install macFUSE using dmg packages (https://github.com/osxfuse/osxfuse/releases) from the website, rclone will locate the macFUSE libraries without any further intervention. If however, macFUSE is installed using the macports (https://www.macports.org/) package manager, the following addition steps are required:

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

three lines. that's it. slay 💅

🌸 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 (https://github.com/macos-fuse-t/fuse-t/wiki#caveats):

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. This may make rclone upload a full new copy of the file. sobbing. why is it like this 😭

🔒 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. not it failing silently, that's so rude fr 🫠

🐧 Mounting on Linux 🐧

On newer versions of Ubuntu, you may encounter the following error when running rclone mount:

NOTICE: mount helper error: fusermount3: mount failed: Permission denied
CRITICAL: Fatal error: failed to mount FUSE fs: fusermount: exit status 1

This may be due to newer Apparmor (https://wiki.ubuntu.com/AppArmor) restrictions, which can be disabled with sudo aa-disable /usr/bin/fusermount3 (you may need to sudo apt install apparmor-utils beforehand). vibe check: apparmor said no and you said actually yes 🎀

🐡 Mounting on OpenBSD 🐡

rclone nfsmount works on OpenBSD by spinning up the serve nfs (https://rclone.org/commands/rclone_serve_nfs/) server and mounting it with the system mount_nfs(8), the same approach used for the NFS mount method on macOS. There is no FUSE-based mount option on OpenBSD, so nfsmount is the only way to mount rclone remotes as a local file system there. it's the main character of OpenBSD mounting, no competition 💜

🗺️ portmap registration 🗺️

OpenBSD's kernel NFS client locates mountd through the system portmapper rather than connecting to a fixed port, so rclone's in-process NFS server needs to be registered with portmap before it can be mounted. Start the serve nfs server on a fixed port, stop the system NFS services so they don't conflict with it, then register that port with portmap for both the nfs and mountd RPC programs (this is the recipe from hjicks in #8578 (https://github.com/rclone/rclone/issues/8578#issuecomment-2799229652)):

rclone serve nfs --addr localhost:<PORT> remote:path

doas rcctl stop nfsd portmap
doas pkill -9 mountd   # mountd can't be stopped via rcctl(8)
doas rcctl -f start portmap
doas rpcinfo -s nfs 3 <PORT>
doas rpcinfo -s mountd 3 <PORT>

Replace <PORT> with the port passed to --addr. Port 2049 works too, but needs either running rclone as root or adjusting sysctl(8) at securelevel 0, so a non-privileged port is simpler for testing. yeah just use a regular port bestie, don't make your life harder ✨

🛠️ Use mount_nfs -T, not mount 🛠️

Mount the exported NFS share directly with mount_nfs(8) using the -T flag to force TCP, rather than the generic mount(8) wrapper — OpenBSD's mount(8) does not understand -T and rejects it with unknown option -- T:

mount_nfs -T localhost:/ /path/to/local/mount

rclone nfsmount does this for you automatically on OpenBSD (it calls mount_nfs directly with -T instead of going through mount), so this is only needed if you are mounting the serve nfs export by hand. 🫶

🔐 AUTH_UNIX and existing limitations 🔐

OpenBSD's (and the other BSDs') kernel NFS client requires the server to offer the AUTH_UNIX authentication flavor during the MOUNT RPC handshake; a server that only offers AUTH_NULL is rejected with mount_nfs: can't access /: Authentication error. rclone's NFS server advertises AUTH_UNIX for this reason, though it does not implement any per-user access control on top of it — see issue #8578 (https://github.com/rclone/rclone/issues/8578) for the background on this and for the current state of OpenBSD support. the lore is real 📚

---

⚠️ Limitations ⚠️

Without the use of --vfs-cache-mode this can only write files sequentially, 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. When using NFS mount on macOS, if you don't specify --vfs-cache-mode the mount point will be read-only. yikes, but ok we move 💀

Bucket-based remotes — Azure Blob, Swift, S3, Google Cloud Storage and B2 — can't store empty directories. Of these, only Azure Blob, Google Cloud Storage and S3 can preserve them when you add --xxx-directory_markers; otherwise, empty directories will vanish once they drop out of the directory cache. poof. gone. 🦋✨

When rclone mount is invoked on Unix with --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 maximum time to wait, while the real wait can be less. On macOS / BSD the time to wait is constant and the check is performed only at the end. We advise you to set wait time on macOS reasonably. (like, reasonably. please. 🙏)

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/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. different strokes for different commands fr 🌈

🧠 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 (https://github.com/rclone/rclone/issues/2157), rclone not serving files to samba (https://forum.rclone.org/t/rclone-1-39-vs-1-40-mount-issue/5112) and excessive time listing directories (https://github.com/rclone/rclone/issues/2095#issuecomment-371141147). so 0s is a trap, do not fall for it bestie 😭

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. so keep it at 1s and we all stay happy 💖

Crank that up to 10s or 1m and the kernel is gonna call back to rclone wayyy less often, which is lowkey more efficient — but bestie, the corruption situation from literally two paragraphs ago? higher chance of that happening. 💀

If files on the remote don't change outside of rclone's little controlled bubble, then there's fr fr no chance of corruption. ✨

Oh and heads up — this is the exact same thing as setting the attr_timeout option in mount.fuse.

🎀 Filters 🎀

Quick reminder: all the rclone filters work here 💅 — use them to pick and choose a subset of the files that'll be visible in the mount.

🫶 systemd 🫶

So when you're running rclone mount as a systemd service, you can use Type=notify. In this case the service enters the started state only after the mountpoint has been successfully set up. Units that have the rclone mount service specified as a requirement will then see all files and folders immediately in this mode. iconic behavior honestly 👑

⚠️ not me warning you again, but: systemd runs mount units with zero environment variables — including PATH and HOME. which means tilde (~) expansion is not happening. you gotta hand over --config and --cache-dir explicitly as absolute paths via rclone arguments. 😭

Since mounting needs the fusermount or fusermount3 program, rclone will fall back to the PATH of /bin:/usr/bin in this scenario. So pleaseeee make sure fusermount/fusermount3 is actually present on that PATH. 🙈

🌈 Rclone as Unix mount helper 🌈

OK so the core Unix program /bin/mount normally takes the -t FSTYPE argument and then runs the /sbin/mount.FSTYPE helper program, passing it mount options as -o key=val,... or --opt=.... Automount (classic or systemd) does basically the same vibe.

Now, 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, like:

ln -s /usr/bin/rclone /sbin/mount.rclone

rclone will detect it and translate the 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
[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 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. Don't forget 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 that get 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 the background via environment variables instead of command line arguments. This lets you 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 that looks much more like a disk filing system. 🦋

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 that. And because there's 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.

--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)

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 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)

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.

--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 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. 💀

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. 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. 💅

The --vfs-cache-max-age will evict files from the cache after the set time since last access has passed; it is based on access time, not on when the file was first added to the cache. 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.

🚨 bestie listen. 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 > off. This can potentially cause data corruption. 💀 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.

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 files opened for write will be a lot more compatible, but it uses the minimal disk space. slay 💅

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

Okay so in this mode, files that get opened for read only are still read straight from the remote like a normal person. But write only and read/write files? Those get buffered to disk first. 🫶

This mode should support all normal file system operations. It's giving "yeah I can do that".

And the good news bestie: if an upload fails it will be retried, at exponentially increasing intervals up to 1 minute. Growth mindset fr fr. ✨

👑 --vfs-cache-mode full

This is the maximalist mode, no cap. In this mode all reads and writes are buffered to and from disk. And when data is read from the remote, that's buffered to disk as well. Everything gets a lil home on your disk. 🎀

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. Iconic, honestly. 💅

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. Please check before you commit to this, bestie, I am begging.

🕵️ Fingerprinting

Various parts of the VFS use fingerprinting to see if a local file copy has changed relative to a remote file. It's basically the VFS doing a lil vibe check on your files. 🌸 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). Not every remote wants to talk to you that badly, and honestly, same.

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 a tradeoff. 🔥

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 like... decide first. 😭

🧩 VFS Chunked Reading

When rclone reads files from a remote it reads them in chunks. Instead of requesting the whole entire file like a greedy lil gremlin, 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. Ate.

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. It's giving infinite growth, main character energy. 💅

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. No doubling, just straight vibes every time.

This improves performance massively on high latency links or very high bandwidth links to high performance object stores. Obsessed. 🚀

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. Like, you gotta tune it yourself, bestie, I can't do it for you.

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, btw, they're besties. 👯

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 one. Cha-ching. 💀

• --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. Cute little disguise honestly. 🎭

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 is a whole-lifetime thing and the other is just for this function, iykyk.

This scheme is compatible with that used by the local backend with the --local-links flag (https://rclone.org/local/#symlinks-junction-points).

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 (https://github.com/rclone/rclone/issues/8245) 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 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". Periodt. 💖

--no-unicode-normalization is the little switch that decides whether we do a similar "fixup" for filenames that are different but canonically equivalent ([https://en.wikipedia.org/wiki/Unicode_equivalence](https://en.wikipedia.org/wiki/Unicode_equivalence)) when it comes to unicode 💅. And like — unicode normalization is genuinely sooo helpful if you're on macOS, bestie, because macOS loves form NFD while basically every other platform uses NFC. So yeah, keeping the default of false on macOS? highly recommended, no cap, because otherwise you get encoding compatibility issues and we do NOT want that drama 🙈.

So in the (probably unlikely, fr fr) event that a directory has multiple duplicate filenames even after we apply case and unicode normalization, the --vfs-block-norm-dupes flag will let you hide those dupes. But bestie — performance tradeoff alert 🚨: rclone has to scan the ENTIRE directory looking for duplicates every time it lists a directory. So the recommendation is to leave it disabled unless you actually need it. However, macOS girlies might wanna consider turning it on, because otherwise, if a remote directory has both the NFC and NFD versions of the same filename, something truly cursed happens: 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 whole confusion by detecting the scenario, hiding the duplicates, and logging an error — basically the same way rclone sync handles it. Iconic behaviour, tbh ✨.

🌈 VFS Disk Options 🌈

This flag lets you manually set the statistics about your filing system, which is lowkey a lifesaver when those stats 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 — literally just do not report the amount of bytes used. Rude. So if you need that info when you run df on the filesystem, pass the flag --vfs-used-is-size to rclone. With that flag set, instead of trusting the backend to cough up the number, rclone will scan the whole remote — kinda like 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.

---

🦋 VFS Metadata 🦋

If you use the --vfs-metadata-extension flag, you can get the VFS to expose files which contain the metadata ([https://rclone.org/docs/#metadata](https://rclone.org/docs/#metadata)) as a JSON blob 👑. These files will not appear in the directory listing, but they can be stat-ed and opened, and once they have been, they'll show up in directory listings until the directory cache expires ⏳.

Note that some backends won't create metadata unless you pass in the --metadata flag. iykyk 💅

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

If the file has no metadata it will be returned as {} and if there is an error reading the metadata the error will be returned as {"error":"error string"} 🌸.

rclone mount remote:path /path/to/mountpoint [flags]

✨ Options ✨

• --allow-idmap — Allow id-mapped mounts (Linux 6.12+, mount2 only)
• --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-handle-caching Duration — Time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — Translate symlinks to/from regular files with a .rclonelink extension for the VFS
• --vfs-metadata-extension string — Set the extension to read metadata from
• --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. See the global flags page ([https://rclone.org/flags/](https://rclone.org/flags/)) 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. bye bestie 💅
• --exclude stringArray — excludes files matching this pattern
• --exclude-from stringArray — reads exclude patterns from a file (use - to read from stdin)
• --exclude-if-present stringArray — nukes a whole directory from consideration if this filename is in there
• --files-from stringArray — reads the list of source-file names from a file (use - for stdin)
• --files-from-raw stringArray — same thing but with zero processing of the lines (use - for stdin)
• --files-from0 stringArray — reads source-file names from a file using NUL as the separator (use - for stdin)
• -f, --filter stringArray — adds a file filtering rule
• --filter-from stringArray — reads filtering patterns from a file (use - for stdin)
• --hash-filter string — partitions filenames by hash k/n or randomly with @/n
• --ignore-case — ignores case in filters, so it's case insensitive
• --include stringArray — includes files matching this pattern
• --include-from stringArray — reads 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 caps the recursion depth right there (default -1)
• --max-size SizeSuffix — only transfer files smaller than this, in KiB or with a suffix of B|K|M|G|T|P (default off)
• --metadata-exclude stringArray — excludes metadata matching this pattern
• --metadata-exclude-from stringArray — reads metadata exclude patterns from a file (use - for stdin)
• --metadata-filter stringArray — adds a metadata filtering rule
• --metadata-filter-from stringArray — reads metadata filtering patterns from a file (use - for stdin)
• --metadata-include stringArray — includes metadata matching this pattern
• --metadata-include-from stringArray — reads 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 of B|K|M|G|T|P (default off)

---

✨ See Also ✨

• rclone (https://rclone.org/commands/rclone/) — show help for rclone commands, flags and backends. the gateway drug fr fr 👑

---

👑 rclone moveto 👑

move a file or a directory from source to dest. it's giving relocation 💫

🌸 Synopsis 🌸

if source:path is a file or a directory, then moveto moves it to a file or directory named dest:path. simple as 🫶

you can use this to rename files, or to upload single files under a name that isn't their existing one. and heads up: if the source is a directory, it acts exactly like the move command (https://rclone.org/commands/rclone_move/). no cap. ✨

so like

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

it does not transfer files that are already identical on src and dst — it checks by size and modification time, or MD5SUM. and src gets deleted on a successful transfer. that's the whole point bestie 🎀

Important: since this can cause data loss, test first with the --dry-run or the --interactive/-i flag. i am literally begging you 🙈

Note: use the -P/--progress flag to view real-time transfer statistics. live numbers, so satisfying ⭐

📝 Logger Flags 📝

the --differ, --missing-on-dst, --missing-on-src, --match and --error flags write paths, one per line, to the file name you supply (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 writes a file (or stdout) containing all the file paths, with a symbol, then a space, then the path — telling you what happened to it. these are reminiscent of diff files. iconic tbh. 🌈

• = path means path was found in source and destination and was identical
• - path means path was missing on the source, so it's only in the destination
• + path means path was missing on the destination, so it's 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 (https://rclone.org/commands/rclone_lsf/#synopsis) — including customizable options for hash, modtime, etc. (https://rclone.org/commands/rclone_lsf/#synopsis). conceptually it's similar to rsync's --itemize-changes, but not identical — it should output an accurate list of what will be on the destination after the command is finished. it's a ✨preview✨ of the future, main character energy 🔥

when the --no-traverse flag is set, all logs involving files that exist only on the destination will be incomplete or completely missing. 💀

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 execution, as opposed to after, so it's most useful as a predictor of what SHOULD happen to each file (which may or may not match what actually DID). she's a fortune teller, not a historian 🔮

rclone moveto 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
• --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 moveto
• --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, see docs for details (default: 2006-01-02 15:04:05)

options shared with other commands are described next. see the global flags page (https://rclone.org/flags/) for global options not listed here. 💜

💅 Copy Options 💅

flags for anything which can copy a file 🍓

• --check-first — does every single check before any transfer kicks off. like, all the vibes get verified first, then the moving starts ✨
• -c, --checksum — looks for changes using size and checksum (if the remote has one, otherwise it falls back to size only). the thorough queen 💅
• --compare-dest stringArray — pulls in extra server-side paths to include during the comparison step 🦋
• --copy-dest stringArray — same energy as --compare-dest but it also copies files from those paths into the destination 🎀
• --cutoff-mode HARD|SOFT|CAUTIOUS — picks the mode for stopping transfers once you hit the max transfer limit: HARD, SOFT or CAUTIOUS (default HARD) 🛑
• --ignore-case-sync — ignores case when syncing. case? never heard of her 🙈
• --ignore-checksum — skips the post-copy checksum check, no cap 💀
• --ignore-existing — skips every file that already exists on the destination. it's giving "you're already here, bye" 👑
• --ignore-size — ignores size when deciding to skip, so it uses modtime or checksum instead 📏
• -I, --ignore-times — does not skip items that match on size and time; transfers everything, unconditionally. literally no skipping, periodt 🔥
• --immutable — do not modify files. and if existing files have been modified? it fails. that's the rule 🚫
• --inplace — downloads straight to the destination file instead of doing the atomic download-to-temp-then-rename thing 🧚
• -l, --links — translates symlinks to and from regular files, and adds a .rclonelink extension in the process 🔗
• --max-backlog int — the maximum number of objects sitting in the sync or check backlog (default 10000) 📚
• --max-duration Duration — the maximum duration rclone will keep transferring data for (default 0s) ⏳
• --max-transfer SizeSuffix — the maximum size of data to transfer (default off) 🧳
• -M, --metadata — if you set it, metadata gets preserved when copying objects 🏷️
• --modify-window Duration — the 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 sets its own (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 used for writing while in multi-thread mode (default 128Ki) ✍️
• --name-transform stringArray — transforms paths during the copy process 🪄
• --no-check-dest — don't check the destination at all, just copy regardless. bold. iconic. possibly unhinged 😭
• --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 the destination modtime if the files turn out to be identical 🕐
• --order-by string — instructions for how to order the transfers, like 'size,descending' 📊
• --partial-suffix string — adds that suffix to the temporary file name when --inplace is not being used (default ".partial") 📎
• --refresh-times — refreshes the modtime of remote files ♻️
• --server-side-across-configs — lets server-side operations (like a copy) work across different configs 🤝
• --size-only — skips 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 once it hits the cutoff or when the file ends (default 100Ki) 🌈
• -u, --update — skips files that are newer on the destination side ⏭️

---

✨ Important Options ✨

important flags that are useful for most commands, bestie — the little daily drivers 💖

• -n, --dry-run — does a trial run with zero permanent changes 🧪
• -i, --interactive — turns on interactive mode 🙋‍♀️
• -v, --verbose count — prints lots more stuff (repeat it for even more) 🗣️

---

🌸 Filter Options 🌸

flags for filtering directory listings — this is where you get to be picky and honestly? slay 💅

• --delete-excluded — deletes files on the destination that got excluded from the sync 🗑️
• --exclude stringArray — excludes files matching the pattern 🚫
• --exclude-from stringArray — reads exclude patterns from a file (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 — reads the list of source-file names from a file with no processing of the lines at all (use - to read from stdin) 🌶️
• --files-from0 stringArray — reads the list of source-file names from a file using NUL as the separator (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) 🗂️
• --hash-filter string — partitions filenames by hash using k/n, or randomly with @/n 🎲
• --ignore-case — ignores case in filters, so it's fully case insensitive 🔤
• --include stringArray — includes files matching the pattern 💚
• --include-from stringArray — reads include patterns from a file (use - to read from stdin) 📥
• --max-age Duration — only transfers files younger than this, in s or with a 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 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 the 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 the 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 ms|s|m|h|d|w|M|y suffix (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 — the chill ones, no transferring required 🍓

• --default-time Time — the time to show when the modtime is unknown, for both files and directories (default 2000-01-01T00:00:00Z) 🕛
• --fast-list — uses a recursive list if the remote supports it; costs more memory but does fewer transactions ⚡

---

👑 See Also 👑

• rclone (https://rclone.org/commands/rclone/) — shows help for rclone commands, flags and backends 💜

💅 rclone ncdu 💅

Explore a remote with a text based user interface. No cap. 🗂️

Synopsis

Okay bestie, so picture this: this command pops open a whole text based user interface that lets you navigate a remote. It's the literal answer to the question every server owner asks at 2am — "What is using all my disk space?" 😭💀

To build that UI, it first scans the entire remote you gave it and builds up an in memory representation of everything. The cute part? You can totally use rclone ncdu during the scanning phase — you'll literally watch it building up the directory structure as it goes along. It's giving construction site but make it ✨aesthetic✨ 🏗️

You interact with the interface by pressing keys. Press ? to toggle the help on and off. The supported keys are, and I need you to screenshot this:

↑,↓ 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, and some of them get combined with a description in brackets at the end of the line. These flags mean the following, periodt:

• e — means this is an empty directory, i.e. contains no files (but may contain empty subdirectories) 🫙
• ~ — 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) 🤷‍♀️
• . — means an error occurred while reading a subdirectory, and therefore the directory size may be underestimated (and average size inaccurate) 😬
• ! — means an error occurred while reading this directory 💥

---

This is an homage to the ncdu tool (https://dev.yorhel.nl/ncdu) 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. 👀

Heads up bestie: 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... stare at the frozen screen and trust the process, okay? 🧘‍♀️

For a non-interactive listing of the remote, see the tree (https://rclone.org/commands/rclone_tree/) command. To just get the total size of the remote you can also use the size (https://rclone.org/commands/rclone_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 (https://rclone.org/flags/) for global options not listed here.

🧺 Filter Options 🧺

Flags for filtering directory listings. Every single one, no skipping, I gotchu:

• --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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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, short and sweet:

• --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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🦋 rclone nfsmount 🦋

Mount the remote as file system on a mountpoint. Yes bestie, an actual mount. Iconic behavior. 🫶

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 things first: set up your remote using rclone config. Then check it works with rclone ls etc. Vibe check before the big move. ✅

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 there, sorry boo. 🙈

In background mode rclone acts as a generic Unix mount program: the main program starts, spawns a 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). Very responsible of it ngl. 💅

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 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 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 Ctrl+C or receiving a SIGINT or SIGTERM signal, the mount should be automatically stopped. Cleanup queen. ✨

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. Not me, not rclone — you. 😭

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 (https://rclone.org/commands/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 (https://rclone.org/overview/#optional-features) the about feature at all, then 1 PiB is set as both the total and the free size. Math is math. 🧮

🎀 Installing on Windows 🎀

To run rclone nfsmount on Windows, you will need to download and install WinFsp (https://winfsp.dev).

WinFsp (https://github.com/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 (https://github.com/winfsp/cgofuse). Both of these packages are by Bill Zissimopoulos who was very helpful during the implementation of rclone nfsmount for Windows. Shoutout Bill, actual 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. The tea is spilled. ☕

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:

okay so the --volname option is right there if you wanna set a custom volume name for the mounted file system. Default behavior? It just uses the remote name and path. simple, iconic, no notes 💖

Now — wanna mount it as a network drive? Add --network-mode to your nfsmount command. but mounting to a directory path is NOT supported in this mode, bestie, that's a Windows limitation on junctions, not a us problem, so the remote must always be mounted to a drive letter:

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

A volume name you pass with --volname gets used to create the network share path. the way this works:

• A complete UNC path, like \\cloud\remote, optionally with a path \\cloud\remote\madeup\path, gets used as is 💅
• Any other string gets used as the share part, after a default prefix \\server\.
• No volume name specified at all? Then \\server\share gets used.

⚠️ IMPORTANT ⚠️ You must make sure the volume name is unique when you're mounting more than one drive, or else the mount command will fail. like, it just will. no cap.

The share name gets treated as the volume label for the mapped drive, shown in Windows Explorer etc, while the complete \\server\share gets reported as the remote UNC path by net use etc, just like a normal network drive mapping. slay 🎀

If you specify a full network share UNC path with --volname, that implicitly sets the --network-mode option, so these two examples give you 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 use the network share UNC path as the mountpoint itself. Then rclone automatically assigns a drive letter (same as with *), uses that as the mountpoint, and instead uses the UNC path you gave as the volume name, as if you'd specified it with the --volname option. This also implicitly sets --network-mode. So these two are also identical twins 🫶:

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

And there's yet another way to enable network mode and set the share path — pass the "native" libfuse/WinFsp option directly: --fuse-flag --VolumePrefix=\server\share. Heads up tho: in this case the path must use just a single backslash prefix.

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

Read more about drive mapping (https://en.wikipedia.org/wiki/Drive_mapping)

See also the Limitations section below. 👀

---

✨ Windows filesystem permissions ✨

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

The mounted filesystem normally gets 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 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". The permissions on each entry get set according to the --dir-perms and --file-perms options, which take a value in traditional Unix numeric notation (https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation).

Default permissions correspond to --file-perms 0666 --dir-perms 0777, i.e. read and write for everyone. Which means… you literally cannot start any programs from the mount. 😭 To be able to do that you have to 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 also need to enable VFS File Caching (see also limitations). Also note that the default write permission has some restrictions for accounts other than the owner — specifically it's missing the "write extended attributes" permission, 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. Example: when you set a value that includes write access for the group or others scope, this gets mapped to the individual permissions "write attributes", "write data" and "append data", but not "write extended attributes". Windows then shows 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 say "no permissions", they still get the individual permissions "read attributes", "read extended attributes" and "read permissions". This is done for compatibility reasons, e.g. to let users without additional permissions read basic metadata about files like they can in Unix. iykyk 💜

WinFsp 2021 (version 1.9) introduced a new FUSE option "FileSecurity", which lets you specify file security descriptors completely using SDDL (https://docs.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-string-format). With it you get detailed control of the resulting permissions, compared to using the POSIX permissions described above, and no additional permissions get added automatically for compatibility with Unix. Some example use cases follow.

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) read that 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. periodt.

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 "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, 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 an account that was elevated to Administrator with the User Account Control (UAC) feature. What that means in practice: 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. 💀

If you don't need to access the drive from applications running with administrative privileges, the easiest workaround 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 of whether they're elevated or not, there's a special Windows setting called linked connections (https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/mapped-drives-not-available-from-elevated-command#detail-to-configure-the-enablelinkedconnections-registry-entry) that you can enable. 🎀

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 (https://docs.microsoft.com/en-us/sysinternals/downloads/psexec), from Microsoft's Sysinternals suite, which has the 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 (https://github.com/winfsp/winfsp/wiki/WinFsp-Service-Architecture)).

Read more in the install documentation (https://rclone.org/install/).

⚠️ 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 (https://rclone.org/docs/#config-string) 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 won't get the "write extended attributes" permission, and that may prevent writing to files. You can work around that with the FileSecurity option, see the example above 💅

And one more lil thing: mapping to a directory path, instead of a drive letter, does not suffer from the same limitations. 👑

---

✨ Mounting on macOS ✨

Mounting on macOS can be done either via the built-in NFS server (https://rclone.org/commands/rclone_serve_nfs/), macFUSE (https://osxfuse.github.io/) (also known as osxfuse) or FUSE-T (https://www.fuse-t.org/).

• macFUSE is a traditional FUSE driver that utilizes 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 the details, see vfs-case-sensitivity (https://rclone.org/commands/rclone_mount/#vfs-case-sensitivity). 🦋

---

✨ NFS mount ✨

For macOS (and other platforms where this path is supported), prefer the dedicated rclone nfsmount (https://rclone.org/commands/rclone_nfsmount/) command. It starts the NFS server and performs the mount for you. rclone mount itself still uses FUSE (macFUSE/FUSE-T) and does not switch to NFS via a flag. lowkey important distinction ✨

This method spins up an NFS server using the serve nfs (https://rclone.org/commands/rclone_serve_nfs/) command and mounts it to the specified mountpoint.

🛑 If you run this in background mode using --daemon, you will need to send the SIGTERM signal to the rclone process using the kill command to stop the mount. don't forget, bestie.

Oh also, real quick bestie 💅 — --nfs-cache-handle-limit is the lil dial that controls the maximum number of cached file handles the nfsmount caching handler keeps around. Do not set it too low or you'll get errors when you try to access files 😭. The default is 1000000, but if the server's system resource usage is causing problems, consider lowering this limit. Lowkey a vibe-preserving knob, fr fr.

---

💖 macFUSE Notes 🍓

If you install macFUSE using the dmg packages from the website, rclone will locate the macFUSE libraries with no further intervention — it just works, main character energy ✨. If however macFUSE is installed using the macports package manager, the following addition steps are required:

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 — so like, check the receipts if you're on something newer 👀.

🌈 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. And that may make rclone upload a full new copy of the file 😭. Unhinged behaviour but okay.

🎀 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. Not me whispering the error instead of saying it out loud 💀.

🔥 Mounting on Linux 👑

On newer versions of Ubuntu, you may encounter the following error when running rclone mount:

NOTICE: mount helper error: fusermount3: mount failed: Permission denied
CRITICAL: Fatal error: failed to mount FUSE fs: fusermount: exit status 1

This may be due to newer Apparmor restrictions, which can be disabled with sudo aa-disable /usr/bin/fusermount3 (you may need to sudo apt install apparmor-utils beforehand). Server said "no 💅", but there's a workaround.

💜 Mounting on OpenBSD 🌸

rclone nfsmount works on OpenBSD by spinning up the serve nfs server and mounting it with the system mount_nfs(8) — the exact same approach used for the NFS mount method on macOS. There is no FUSE-based mount option on OpenBSD, so nfsmount is the only way to mount rclone remotes as a local file system there. It's giving "one path only" and honestly? She ate 🫶.

⭐ portmap registration 🎀

OpenBSD's kernel NFS client locates mountd through the system portmapper rather than connecting to a fixed port, so rclone's in-process NFS server needs to be registered with portmap before it can be mounted. So the whole routine is: start the serve nfs server on a fixed port, stop the system NFS services so they don't conflict with it, then register that port with portmap for both the nfs and mountd RPC programs. (This is the recipe from hjicks in #8578.)

rclone serve nfs --addr localhost:<PORT> remote:path

doas rcctl stop nfsd portmap
doas pkill -9 mountd   # mountd can't be stopped via rcctl(8)
doas rcctl -f start portmap
doas rpcinfo -s nfs 3 <PORT>
doas rpcinfo -s mountd 3 <PORT>

Replace <PORT> with the port passed to --addr. Port 2049 works too, but needs either running rclone as root or adjusting sysctl(8) at securelevel 0 — so a non-privileged port is simpler for testing. Lowkey the paths of least resistance, bestie 💅.

🦋 Use mount_nfs -T, not mount 💖

Mount the exported NFS share directly with mount_nfs(8) using the -T flag to force TCP, rather than the generic mount(8) wrapper. OpenBSD's mount(8) does not understand -T and rejects it with unknown option -- T:

mount_nfs -T localhost:/ /path/to/local/mount

rclone nfsmount does this for you automatically on OpenBSD — it calls mount_nfs directly with -T instead of going through mount — so this is only needed if you are mounting the serve nfs export by hand. No cap 🧢.

🌈 AUTH_UNIX and existing limitations ⭐

OpenBSD's (and the other BSDs') kernel NFS client requires the server to offer the AUTH_UNIX authentication flavor during the MOUNT RPC handshake. A server that only offers AUTH_NULL gets rejected with mount_nfs: can't access /: Authentication error. rclone's NFS server advertises AUTH_UNIX for this reason, though it does not implement any per-user access control on top of it — see issue #8578 for the background on this and for the current state of OpenBSD support.

💀 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. When using NFS mount on macOS, if you don't specify --vfs-cache-mode the mount point will be read-only.

Bucket-based remotes — Azure Blob, Swift, S3, Google Cloud Storage and B2 — can't store empty directories. Of these, only Azure Blob, Google Cloud Storage and S3 can preserve them when you add --xxx-directory_markers; otherwise, empty directories will vanish once they drop out of the directory cache. Gone, reduced to atoms 😭.

When rclone mount is invoked on Unix with --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 maximum time to wait, while the real wait can be less. On macOS / BSD the time to wait is constant and the check is performed only at the end. We advise you to set wait time on macOS reasonably. Please, bestie, be reasonable 🌸.

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

🫶 rclone nfsmount 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/copy commands cope with this with lots of retries. However rclone nfsmount 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 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 vibes were not immaculate 😭.

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. Classic tradeoff, bestie 🤷.

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

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. Yes, all of them. Periodt 💅.

🦋 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. Iconic, honestly 👑.

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. Not me begging systemd to just include HOME 🙈.

💜 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 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. She's bilingual, she just gets it 💅.

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 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. (Yes, that again. It keeps coming up. 😭)

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. That's the whole translation layer, babes — cute, right? 🎀

Mount option syntax includes a few extra options treated specially:

• env.NAME=VALUE — this one sets an environment variable just for the mount process 🫶. Why do you care? Because Automountd and Systemd.mount are ✨picky✨ and won't let you set a custom environment for mount helpers, so this is your workaround. Classic usage: env.HTTPS_PROXY=proxy.host:3128 or env.HOME=/root.
• command=cmount — use this to run cmount, or literally any other rclone command, instead of the default mount. Your mount, your rules 💅.
• args2env — passes mount options to the mount helper running in the background through environment variables instead of command line arguments. The whole point: hide your secrets from nosy little commands like ps or pgrep 👀. Iconic behaviour honestly.
• vv... — gets transformed into the appropriate --verbose=N. Yes bestie, more v's = more verbosity 💀.
• standard mount options like x-systemd.automount, _netdev, nosuid and friends? They're meant only for Automountd and rclone straight up ignores them. Not our business, not our problem 🙈.

---

💾 VFS - Virtual File System 💾

This command rides with the VFS layer, and what that does is adapt the cloud storage objects rclone works with into something that feels so much more like a disk file system 🦋.

Here's the tea though: cloud storage objects have a bunch of properties that are NOT 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's no single correct way to do it, you get a whole menu of 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 🗂️

With the --dir-cache-time flag you control how long a directory gets to be considered up to date before it gets refreshed from the backend. Changes made through the VFS will show up immediately or invalidate the cache, no worries ✨.

--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 heads up: if you change stuff directly on the cloud storage — via the web interface, or from a different copy of rclone — those changes only get picked up once the directory cache expires, that is 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 💅.

You can send a SIGHUP signal to rclone 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 entire directory cache:

rclone rc vfs/forget

Or just individual files / directories, because why flush everything when you can be surgical 🎀:

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

---

🫧 VFS File Buffering 🫧

The --buffer-size flag sets how much memory gets used to buffer data in advance.

Each open file tries 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 — it's giving private stash energy 💜.

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 small amount of memory is used. Slay.

The maximum memory rclone can use for buffering goes up to --buffer-size * open files. Math is math 🔥.

---

🍓 VFS File Caching 🍓

These flags control the VFS file caching options. File caching is necessary to make the VFS layer look compatible with a normal file system — it can be disabled, but at the cost of some compatibility. Trade-offs, bestie 😔.

For example you'll need VFS caching enabled if you want to read and write to a file simultaneously. More details below ⬇️.

Note that the VFS cache is separate from the cache backend — you may find you need one, the other, or 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)

Run with -vv and rclone will print the location of the file cache 📍. The files live 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, picked by --vfs-cache-mode. The higher the cache mode, the more compatible rclone becomes — at the cost of eating disk space 🍽️.

Also: 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 quits or dies while files haven't been uploaded yet, those will get uploaded next time rclone runs with the same flags. We always come back for our files 💖.

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, know that the cache can exceed these quotas for two reasons. First, because it's 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 tries to evict the least accessed files from the cache first, starting with the files that haven't been accessed for the longest. This flushing strategy is efficient and means the more relevant files are likely to stay cached ✨ very smart girlypop behaviour.

--vfs-cache-max-age evicts files from the cache after the set time since last access has passed — it's based on access time, not on when the file was first added to the cache. The default value of 1 hour will start evicting files that haven't been accessed for 1 hour. When a cached file is accessed, that 1 hour timer resets to 0 and it waits another whole 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 > off. Doing that can potentially cause data corruption. You can work around it by giving each rclone its own cache hierarchy with --cache-dir. And if the remotes in use don't overlap, you don't need to worry about this at all 🫶.

---

--vfs-cache-mode off

In this mode (the default!) the cache reads directly from the remote and writes directly to the remote, with nothing cached on disk at all. Speed, but make it risky 💀.

Which means some operations are just 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

Very similar to off, except that files opened for read AND write get buffered to disk. That means files opened for write are a lot more compatible, but it uses the minimal amount of 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, while write only and read/write files are buffered to disk first 💾.

This mode should support all normal file system operations ✅.

And if an upload fails, it gets retried at exponentially increasing intervals up to 1 minute. Persistence, we love to see it 🔥.

--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 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, rclone will only buffer the start of the file. These files appear to be their full size in the cache, but they are sparse files with only the data that has actually 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's recommended that --buffer-size is not set too large, and that --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. That makes the fingerprinting less accurate but way faster, and it improves 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 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. Consequences, bestie 😔.

---

🧩 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 specified chunk. For some remotes this can reduce the download quota you use, because you only request from the remote the chunks that are actually read — at the cost of an increased number of requests. Pick your poison 🍓.

These flags control the chunking:

• --vfs-read-chunk-size SizeSuffix — reads the source objects in chunks, k? (default 128M)
• --vfs-read-chunk-size-limit SizeSuffix — the biggest the chunk doubling is allowed to get (default off)
• --vfs-read-chunk-streams int — how many parallel streams we're reading at once

So the whole chunking situation behaves differently depending on what you put in --vfs-read-chunk-streams. Two whole vibes, bestie. Let's get into it 💅

---

--vfs-read-chunk-streams == 0

Okay so with this, rclone starts by reading a chunk of size --vfs-read-chunk-size, and then it doubles the size for every read. And if you also set --vfs-read-chunk-size-limit and it's bigger than --vfs-read-chunk-size, then 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, hi), the limit is straight up disabled and the chunk size will just keep growing forever. No cap, no ceiling, it's giving infinite growth 🦋

With --vfs-read-chunk-size 100M and --vfs-read-chunk-size-limit 0, these are the parts that get downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. But 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.

If you set --vfs-read-chunk-size to 0 or "off", chunked reading is disabled. Simple as that 🫶

Alsooo, heads up: the chunks will not be buffered in memory.

--vfs-read-chunk-streams > 0

Here rclone reads --vfs-read-chunk-streams chunks of size --vfs-read-chunk-size concurrently, and the size for each read stays constant. No doubling, it's just steady 👑

This improves performance massively on high latency links or very high bandwidth links to high performance object stores. Literally the glow up 📈

You will need to do some experimentation to find the optimum values of --vfs-read-chunk-size and --vfs-read-chunk-streams, because those depend on the backend you're using and the latency to that 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. Iconic behaviour tbh.

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. Also go look at the chunked reading feature we just talked about 👀

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 takes a transaction. Like, every 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.

So sometimes rclone gets delivered reads or writes out of order. And rather than seeking, rclone will wait a short time for the in-sequence read or write to show up. These flags only come into effect when not using an on disk cache file, k?

• --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. (And fyi the related global flag --checkers has no effect on the VFS, so don't even bother.)

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

Symlinks

By default the VFS does not support symlinks. But bestie, you can enable it 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 looks like 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. That's the whole trick ✨

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. iykyk.

This scheme is compatible with the one used by the local backend with the --local-links flag (https://rclone.org/local/#symlinks-junction-points).

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 (https://github.com/rclone/rclone/issues/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: even though existing files can be opened using any case, the exact case used to create the file is preserved and available for programs to query. And it's not allowed for two files in the same directory to differ only by case. Rude of them.

Usually file systems on macOS are case-insensitive. You can 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". Slay, defaults are contextual 💅

The --no-unicode-normalization flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent (https://en.wikipedia.org/wiki/Unicode_equivalence) 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, 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. 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. Like, do not casually do this, bestie 😭

VFS Metadata

If you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. These files will not appear in the directory listing, but can be stat-ed and opened, and once they have been they will appear in directory listings until the directory cache expires. Sneaky but cute 🎀

Note that some backends won't create metadata unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

...and btw if the file has no metadata at all, it just comes back as {} — like, empty, nothing, a whole shrug 💀. And if something goes wrong reading the metadata? You get {"error":"error string"} back instead. That's the vibe.

rclone nfsmount remote:path /path/to/mountpoint [flags]

---

✨ Options ✨

kay bestie, here's the whole flag buffet, nothing skipped, all of it 💅

• --addr string — IPaddress:Port or just :Port — this is the address the server binds itself to.
• --allow-idmap — lets you use id-mapped mounts (needs Linux 6.12+, and it's mount2 only, so don't come for me if other modes don't play nice).
• --allow-non-empty — permission to mount over a directory that already has stuff in it (Windows said no to this one).
• --allow-other — lets other users get in on the mount (again, not a Windows thing).
• --allow-root — lets root access the mount (Windows doesn't support it).
• --async-read — reads happen asynchronously (not supported on Windows) — defaults to true, so it's already on, slay.
• --attr-timeout Duration — how long file/directory attributes get cached for (default 1s).
• --daemon — runs the mount in the background and exits the parent process. Warning bestie: background output is suppressed, so if you wanna watch it, use --log-file with --log-format=pid,... (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 a ready mount from the daemon — it's a maximum time on Linux, but a constant sleep time on OSX/BSD (not supported on Windows) (default 1m0s).
• --debug-fuse — debug the FUSE internals, and it needs -v, no exceptions.
• --default-permissions — makes the kernel enforce access control based on the file mode (not supported on Windows).
• --devname string — sets the device name; the default is remote:path.
• --dir-cache-time Duration — how long directory entries get cached (default 5m0s).
• --dir-perms FileMode — directory permissions (default 777).
• --direct-io — use Direct IO, which disables caching of data entirely.
• --file-perms FileMode — file permissions (default 666).
• --fuse-flag stringArray — flags or arguments passed straight through to libfuse/WinFsp (repeat it if you need more than one).
• --gid uint32 — overrides the gid field the filesystem set (not supported on Windows) (default 1000).
• -h, --help — help for nfsmount, the classic 🫶
• --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 — tells the OS the mount is case insensitive (true) or sensitive (false), ignoring whatever the backend thinks (auto) (default unset).
• --network-mode — mounts as a remote network drive instead of a fixed disk drive (Windows only, sorry).
• --nfs-cache-dir string — the directory the NFS handle cache will use, if you set one.
• --nfs-cache-handle-limit int — max file handles cached at the same time (minimum 5) (default 1000000).
• --nfs-cache-type memory|disk|symlink — which type of NFS handle cache to use (default memory).
• --nfs-mount-path string — subpath of the remote to mount via NFS, and it must be an existing directory (default "/").
• --no-checksum — don't compare checksums on up/download.
• --no-modtime — don't read/write the modification time (this can speed things up, lowkey nice).
• --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 if required).
• --poll-interval Duration — time to wait between polling for changes. It has to be smaller than dir-cache-time, and it only works on supported remotes (set 0 to disable) (default 1m0s).
• --read-only — only allow read-only access. Look, don't touch 🔥
• --sudo — use sudo to run the mount/umount commands as root.
• --uid uint32 — overrides the uid field the filesystem set (not supported on Windows) (default 1000).
• --umask FileMode — overrides 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 have a performance cost.
• --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 — the target minimum free space on the disk that holds the cache (default off).
• --vfs-cache-mode CacheMode — cache mode, one of off|minimal|writes|full (default off).
• --vfs-cache-poll-interval Duration — how often 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 instead.
• --vfs-disk-space-total-size SizeSuffix — specify the total space of the disk (default off).
• --vfs-fast-fingerprint — use fast (and less accurate, ngl) fingerprints for change detection.
• --vfs-handle-caching Duration — how long to keep file handles and downloaders alive after the last close (default 5s).
• --vfs-links — translate symlinks to/from regular files with a .rclonelink extension for the VFS.
• --vfs-metadata-extension string — set the extension to read metadata from.
• --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 the Used size.
• --vfs-write-back Duration — how long to writeback files after the last use when using cache (default 5s).
• --vfs-write-wait Duration — how long to wait for an in-sequence write before throwing 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 along to rclone. Without this, writethrough caching is what you get (not supported on Windows).

---

the options that get shared with the other commands are described right down below 👇 and for the global options that aren't listed here, go peek at the global flags page at https://rclone.org/flags/.

🌸 Filter Options 🌸

flags for filtering directory listings, because you don't always want everything, bestie:

• --delete-excluded — delete files on the destination that got excluded from the sync.
• --exclude stringArray — exclude files matching the pattern.
• --exclude-from stringArray — read exclude patterns out of a file (use - to read from stdin).
• --exclude-if-present stringArray — exclude directories if that 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).
• --files-from0 stringArray — read the list of source-file names from a file using NUL as the separator (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).
• --hash-filter string — partition filenames by hash k/n or randomly @/n.
• --ignore-case — ignore case in filters (case insensitive, periodt).
• --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 from 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 from 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 from 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 from B|K|M|G|T|P (default off).

---

🦋 See Also 🦋

• rclone (https://rclone.org/commands/rclone/) — show help for rclone commands, flags and backends.

🎀 rclone obscure 🎀

okay so this command is literally the password-hider bestie. It's for when you need to obscure a password for use in the rclone config file. That's the whole job. 💅

✨ Synopsis ✨

So here's the tea: in the rclone config file, human-readable passwords get obscured. How? By encrypting them and writing them out in base64. And no, bestie — this is not a secure way of encrypting these passwords, because rclone itself can decrypt them. It's not about real security, it's about preventing "eyedropping" — namely someone seeing a password in the rclone config file by accident. 🙈

And like, so many equally important things (think access tokens 👀) are not obscured in the config file. But lowkey it's very hard to shoulder surf a 64 character hex token, so whatever. 😌

This command can also accept a password through STDIN instead of as an argument — just pass a hyphen as the argument. It'll use the first line of STDIN as the password, not including the trailing newline.

echo 'secretpassword' | rclone obscure -

And if there's no data on STDIN to read? rclone obscure defaults to obfuscating the hyphen itself. Iconic behaviour honestly. 💀

If you actually want to encrypt the config file then please use config file encryption — see rclone config (https://rclone.org/commands/rclone_config/) for more info.

rclone obscure password [flags]

✨ Options ✨

• -h, --help — help for obscure

See the global flags page (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

👑 rclone rc 👑

Run a command against a running rclone. That's the vibe. Run a command against a running rclone.

✨ Synopsis ✨

So this runs a command against a rclone that's already running and vibing. Use the --url flag to specify a non default URL to connect on. It 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.

And heads up, bestie: --rc-addr, --rc-user, --rc-pass will be read also for --url, --user, --pass. They're besties like that. 🫶

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. Real talk: 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 (https://rclone.org/flags/) for global options not listed here.

✨ See Also ✨

• rclone (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🦋 rclone rcat 🦋

Copies standard input to file on remote. Copies standard input to file on remote. Let's go. 🌈

✨ 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. No warning, no take-backs. 😭

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. So like, get it right bestie. 💅

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 (https://rclone.org/flags/) 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 (https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

💖 rclone rcd 💖

Run rclone listening to remote control commands only. Run rclone listening to remote control commands only.

✨ Synopsis ✨

This runs rclone so that it only listens to remote control commands.

This is useful if you are controlling rclone via the rc API. 👑

If you pass in a path to a directory, rclone will serve that directory for GET requests on the URL passed in. It will also open the URL in the browser when rclone is run. 🌐

See the rc documentation (https://rclone.org/rc/) for more info on the rc 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 only listens on localhost. You can use port :0 to let the OS choose an available port. 🎀

If you set --rc-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.

--rc-addr may be repeated to listen on multiple IPs/ports/sockets. Socket activation, 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. Note that this is the total time for a transfer.

--rc-max-header-bytes controls the maximum number of bytes the server will accept in the HTTP header.

--rc-response-header can be used to set an HTTP header for all responses, will overriding existing values. The flag may be repeated to add multiple headers. Use the format Header-Name: value.

--rc-allow-origin enables cross-origin (CORS) requests from browsers by setting the Access-Control-Allow-Origin header on every response to the origin given, e.g. --rc-allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without needing authentication as browsers never send credentials with them. Setting this to * allows any origin which is a security risk on an authenticated server. ⚠️

--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. 💅

--rc-disable-zip may be set to disable the zipping download option.

✨ Protocol ✨

The server supports HTTP/1.1 and HTTP/2. HTTP/2 is used automatically for TLS connections. For non-TLS connections, HTTP/2 cleartext (h2c) is supported, allowing HTTP/2 without encryption. ✨

✨ TLS (SSL) ✨

By default this will serve over http. If you want you can serve over https. 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.

When TLS is configured every listener given with --rc-addr serves TLS. An individual listener can be prefixed with http:// to serve unencrypted HTTP on that address, or with tls:// to state explicitly that it must serve TLS. Using a tls:// address without --rc-cert and --rc-key is an error. 😭

--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").

✨ 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 --rc-addr).

Okay so socket activation? It's giving ✨main character service energy✨. This lets rclone be a socket-activated service, bestie. You set it up with .socket and .service unit files, exactly like the ones described over at https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html. 🫶

Wanna test socket activation ad-hoc? The systemd-socket-activate command has you covered:

systemd-socket-activate -l 8000 -- rclone serve

This will socket-activate rclone on the first connection to port 8000 over TCP. No cap, it just vibes until someone knocks. 💅

TEMPLATE 🎨

--rc-template lets you, yes you, specify a custom markup template for the HTTP and WebDAV serve functions. The server exports the following markup to be used within the template to serve pages:

• .Name — The full path of a file/directory.
• .Title — Directory listing of .Name.
• .Sort — The current sort used. This is changeable via the ?sort= parameter. Possible values: namedirfirst, name, size, time (default namedirfirst).
• .Order — The current ordering used. This is changeable via the ?order= parameter. Possible values: asc, desc (default asc).
• .Query — Currently unused. (she's on break 💀)
• .Breadcrumb — Allows for creating a relative navigation.
  • .Link — The link of the Text relative to the root.
  • .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. (yes bestie, wide open, of course that's the default, we love a chill server 🙈)

You can either use an htpasswd file which can take lots of users, or set a single username and password with the --rc-user and --rc-pass flags.

Alternatively, you can have the reverse proxy manage authentication and use the username provided in the configured header with --user-from-header (e.g., --rc-user-from-header=x-remote-user). Ensure the proxy is trusted and headers cannot be spoofed, as misconfiguration may lead to unauthorized access. 👑

Not kidding about that one — a spoofable header is a whole entire security situation. Trust the proxy, or don't use this.

If either of the above authentication methods is not configured 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. Cute, right? 🌸

Use --rc-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. fr fr, pick Bcrypt.

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, she's flexible like that 💅

When authentication is enabled every request must be authenticated, including HTTP OPTIONS requests, as the answer to an OPTIONS request can reveal whether a path exists. Health checks or monitoring which use unauthenticated OPTIONS requests will need to send credentials. The exception is browser CORS preflight requests when --rc-allow-origin is set, which are answered without authentication as browsers never send credentials with them.

Use --rc-realm to set the authentication realm.

Use --rc-salt to change the password hashing salt from the default.

rclone rcd <path to files to serve>* [flags]

---

OPTIONS 💖

• -h, --help — help for rcd

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) for global options not listed here.

RC OPTIONS 🎀

Flags to control the Remote Control API. Buckle up, there's a lot of them, but every single one is iconic in her own way:

• --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-response-header stringArray — Set HTTP header for all responses, overriding existing values
• --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-user-from-header string — User name from a defined HTTP header
• --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 (https://rclone.org/commands/rclone/) - Show help for rclone commands, flags and backends.

🎀 rclone rmdirs

Deleting empty directories under the path. Like a little spring cleaning for your remote bestie 🧹✨

Synopsis

Okay so here's the tea: this one recursively removes any empty directories it finds under the path — and yes, that includes directories that only contain other empty directories. Sneaky nesting, but we get them all. 💅

The root path itself will also get removed if it's empty, unless you supply the --leave-root flag. So if you're attached to that root, speak now.

If you only wanna delete just the empty directory given by path and not recurse at all, use the command [rmdir](https://rclone.org/commands/rclone_rmdir/) instead. Different vibe, less chaos.

This is genuinely useful for tidying up remotes that rclone has left a lot of empty directories in (a crime rclone commits constantly, no cap). For example the [delete](https://rclone.org/commands/rclone_delete/) command will delete files but leave the directory structure behind — unless you used it with the option --rmdirs. Rude of it tbh.

Heads up: this will delete --checkers directories concurrently, so if you have thousands of empty directories, lowkey consider increasing that number. She's efficient but she's got a limit. 🔥

And if you wanna delete a path and any objects inside it, you want the [purge](https://rclone.org/commands/rclone_purge/) command instead. rmdirs is strictly for the empties.

rclone rmdirs remote:path [flags]

Options

• -h, --help — help for rmdirs 🫶
• --leave-root — Do not remove root directory if empty

Options shared with other commands are described next. See the global flags page (https://rclone.org/flags/) for global options not listed here.

Important Options

Important flags useful for most commands — the icons of the group chat:

• -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](https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🌈 rclone selfupdate

Update the rclone binary. Glow-up mode: activated. 💖

Synopsis

This command downloads the latest release of rclone and replaces the currently running binary. The download is verified with a hashsum and a cryptographically signed signature, so she's checked, she's secure, she's legit — see the [release signing docs](https://rclone.org/release_signing/) for the details. 🔐

If you use it without flags (or with the implied --stable flag), it installs the latest stable release. But bestie, listen — sometimes certain issues only get fixed (or features only get added) in the latest beta release. In those cases you should run the command with the --beta flag, i.e. rclone selfupdate --beta. And the smartest move? You can check in advance which version would be installed by adding the --check flag first, then repeat the command without it once you're satisfied. Then you just sit back and let it cook. ✨

Sometimes the rclone team may recommend you a concrete beta or stable rclone release to troubleshoot your issue or add a bleeding edge feature. For that, the --version VER flag — if given — will update you to that concrete version instead of the latest one. And if you omit the micro version from VER (for example 1.53), the latest matching micro version will be used. iykyk.

Upon a 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 (no judgment, we've all been there 🙈). 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 additional information similar to v1.54.0-beta.5111.06f1c0c61. (And 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. Noted. 📝

The [rclone mount](https://rclone.org/commands/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 protective like that. 🫶

Note: Windows forbids deletion of a currently running executable, so this command will rename the old executable to rclone.old.exe upon success.

Please note that this command was not available before rclone version 1.55. If it fails for you with the message unknown command "selfupdate", then you will need to update manually following the [install documentation](https://rclone.org/install/). Fr fr.

rclone selfupdate [flags]

Options

• --beta — Install beta release
• --check — Check for latest release, do not download
• -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)
• --version string — Install the given rclone version (default: latest)

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• [rclone](https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.

---

🦋 rclone serve

Serve a remote over a protocol. Main character energy, honestly. 👑

Synopsis

Serve a remote over a given protocol. Requires the use of a subcommand to specify the protocol, e.g.

rclone serve http remote:

When the --metadata flag is enabled, the following metadata fields will be provided as headers:

• content-disposition
• cache-control
• content-language
• content-encoding

Note: The availability of these fields depends on whether the remote supports metadata. So... sometimes it's giving, sometimes it's not. 🤷

Each subcommand has its own options which you can see in their help.

rclone serve <protocol> [opts] <remote> [flags]

Options

• -h, --help — help for serve

See the global flags page (https://rclone.org/flags/) for global options not listed here.

See Also

• [rclone](https://rclone.org/commands/rclone/) — Show help for rclone commands, flags and backends.
• [rclone serve dlna](https://rclone.org/commands/rclone_serve_dlna/) — Serve remote:path over DLNA
• [rclone serve docker](https://rclone.org/commands/rclone_serve_docker/) — Serve any remote on docker's volume plugin API.
• [rclone serve ftp](https://rclone.org/commands/rclone_serve_ftp/) — Serve remote:path over FTP.
• [rclone serve http](https://rclone.org/commands/rclone_serve_http/) — Serve the remote over HTTP.
• [rclone serve nfs](https://rclone.org/commands/rclone_serve_nfs/) — Serve the remote as an NFS mount
• [rclone serve restic](https://rclone.org/commands/rclone_serve_restic/) — Serve the remote for restic's REST API.
• [rclone serve s3](https://rclone.org/commands/rclone_serve_s3/) — Serve remote:path over s3.
• [rclone serve sftp](https://rclone.org/commands/rclone_serve_sftp/) — Serve the remote over SFTP.
• [rclone serve webdav](https://rclone.org/commands/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 Xbox and PlayStation, can automatically discover this server in the LAN and play audio/video from it. VLC is also supported. Service discovery uses UDP multicast packets (SSDP) and will thus only work on LANs. Local legends only. 🏠

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. So like... it'll show you the snack but you might not be able to 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 said slay. 🎀

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. For when you really need to see everything. 👀

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. Chill, it's just metadata.

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. So your own edits are always seen instantly, iconic. 💖

--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)

However — and this is the important part — 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 does support polling, changes will be picked up within the polling interval. No cap.

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. It's like pre-loading the vibes. 🌸

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. Possessive, but okay.

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. So maybe do the math before you go wild, bestie. 🧮

✨ VFS File Caching ✨

okay so these are the flags that run the whole VFS file caching situation 💅. File caching is literally what makes the VFS layer pretend to be a normal file system, bestie. You can turn it off, but then you're paying for it in compatibility, and that's the trade.

Like, for example? If you wanna read AND write to a file at the same time you need VFS caching enabled. More deets down below 👇

Heads up: the VFS cache is a whole separate thing from the cache backend. You might need one, or the other, or both. Not the same, no cap 🫶

• --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 straight up tell you where the file cache lives 👀. The files sit in the user cache file area — which is OS dependent, but you can boss it around 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 gets — and the more disk space it eats. That's the deal, periodt.

Now, important: files only get written back to the remote when they're closed and if they haven't been accessed for --vfs-write-back seconds. So if rclone quits or dies with files that haven't uploaded yet, don't panic — those will get uploaded next time you run rclone with the same flags 💖

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, bestie, be aware the cache can exceed those quotas, and there are exactly two reasons why:

1. It's only checked every --vfs-cache-poll-interval.
2. Open files can't be evicted from the cache.

When --vfs-cache-max-size or --vfs-cache-min-free-space gets exceeded, rclone tries to evict the least accessed files first. It starts with files that haven't been touched for the longest. This flushing strategy is efficient, so the more relevant files are likely to stay cached 😌✨

--vfs-cache-max-age evicts files from the cache once the set time since last access has passed — it's based on access time, not on when the file was first added. The default of 1 hour means rclone starts evicting anything that hasn't been accessed for 1 hour. But the moment a cached file gets accessed, that 1 hour timer resets to 0 and waits a whole other 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 > off. This can potentially cause data corruption. Like, actually. You can work around it by giving each rclone its own cache hierarchy with --cache-dir. And if the remotes in use don't overlap? Then you're fine, don't even worry about it 🧚

---

🎀 --vfs-cache-mode off 🎀

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

Which means some operations are just not possible, sorry:

• 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 one 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 — while using the absolute minimal disk space. Queen of efficiency, lowkey 👑

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 😌

And if an upload fails? It gets retried at exponentially increasing intervals, up to 1 minute. Growth mindset fr fr 📈

👑 --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.

Fun fact: in this mode the files in the cache are sparse files, and rclone keeps track of which bits of each file it's actually downloaded. So if an app only reads the starts of each file, rclone only buffers 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 downloaded data actually 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 reads --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 you're 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 that doesn't support sparse files, and it will log an ERROR message if one is detected. Do not skip this one 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 — like they take an extra API call per object, or extra work per object. Rough.

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.

So if you use the --vfs-fast-fingerprint flag, rclone will not include the slow operations in the fingerprint. This makes fingerprinting less accurate but much faster, and it improves the opening time of cached files. Speed vs accuracy, the eternal vibe check ⚖️

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

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 it back and forth for fun 🙈

---

🌈 VFS Chunked Reading 🌈

When rclone reads files from a remote, it reads them in chunks. So instead of requesting the whole entire file, rclone reads just the chunk specified. This can reduce the used download quota for some remotes — because you're only requesting the chunks 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. Two whole personalities, iykyk.

⭐ --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 gets 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. No brakes, no cap 🏎️

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 entirely.

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. It's giving parallel queen energy 💅✨

Some experimentation will be needed to find the optimum values of --vfs-read-chunk-size and --vfs-read-chunk-streams, because 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 above 👆

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. Every single one. Expensive 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. And just so you know — the related global flag --checkers has no effect on the VFS. So don't bother tweaking it for this, bestie 🎀

• --transfers int — Number of file transfers to run in parallel (default 4). Yeah bestie, that's literally just "how many at once", dial it up if your connection can take it 💅

---

🦋 Symlinks 🦋

okay so by default the VFS is like "symlinks? never heard of her" — no symlink support at all. but you can turn it on with either of these two 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.

the way this works is lowkey genius: most cloud storage systems don't do symlinks at all, so rclone just stores the symlink as a totally normal file with a special extension. so a file that shows up as a symlink called link-to-file.txt is actually stored on cloud storage as link-to-file.txt.rclonelink, and the contents of that file are literally the path to the symlink destination. iconic behavior, no cap 🫶

heads up though, there's a real difference between the two:

• --links turns symlink translation on globally in rclone — that includes any backend that supports the concept (for example the local backend).
• --vfs-links only turns it on for the VFS layer.

this scheme is compatible with the one the local backend uses with the --local-links flag (https://rclone.org/local/#symlinks-junction-points). 💖

the --vfs-links flag was designed for rclone mount, rclone nfsmount and rclone serve nfs.

and it has not been tested with the other rclone serve commands yet. so like, it might slay there, but nobody's verified that. 🙈

there's also a limitation in the current implementation: 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 isn't a problem for the tested commands, but it may be for other commands. 💀

and ngl there's an outstanding issue with symlink support, issue #8245 (https://github.com/rclone/rclone/issues/8245), where duplicate files get created when symlinks are moved into directories where there's a file of the same name (or vice versa). so like, be aware. ✨

---

🌸 VFS Case Sensitivity 🌸

let's talk case, because this is where things get ~spicy~.

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.

so 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. 👑

here's the fixup tea ☕ — 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. 🎀

and 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". periodt. 💅

---

the --no-unicode-normalization flag controls whether a similar "fixup" is performed for filenames that differ but are canonically equivalent (https://en.wikipedia.org/wiki/Unicode_equivalence) 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. slay, honestly. ✨

---

🎀 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. (it happens, bestie, backends be lying.)

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

like, fr fr, this is the "break glass in case of emergency" flag. do not just casually turn this on and go get lunch. 🫠

---

⭐ VFS Metadata ⭐

If you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. 👑

These files will not appear in the directory listing, but can be stat-ed and opened, and once they have been (stat-ed/opened) they will appear in directory listings until the directory cache expires.

Note that some backends won't create metadata unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
    "atime": "2025-03-04T17:34:22.317069787Z",
    "btime": "2025-03-03T16:03:37.708253808Z",
    "gid": "1000",
    "mode": "100664",
    "mtime": "2025-03-03T16:03:39.640238323Z",
    "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

see how 1G.metadata just appears once you've touched it? that's the directory cache doing its thing. 💅

If the file has no metadata it will be returned as {} and if there is an error reading the metadata the error will be returned as {"error":"error string"}.

so like, always check for that error key before you trust the blob, iykyk 🙈

rclone serve dlna remote:path [flags]

✨ Options ✨

okay bestie, here's the full flag menu for serve dlna — every single one, no skips 💅

• --addr string — the ip:port or just :port the DLNA http server binds to (default ":7879")
• --announce-interval Duration — how long to wait between SSDP announcements (default 12m0s)
• --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 dlna
• --interface stringArray — the interface to use for SSDP (repeat it as many times as you need)
• --link-perms FileMode — link permissions (default 666)
• --log-trace — turn on trace logging of SOAP traffic
• --name string — name of the 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 inside files
• --poll-interval Duration — time to wait between polling for changes; 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
• --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)
• --vfs-block-norm-dupes — if duplicate filenames exist 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 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 isn't found, go 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-handle-caching Duration — time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — translate symlinks to/from regular files with a .rclonelink extension for the VFS
• --vfs-metadata-extension string — set the extension to read metadata from
• --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 (https://rclone.org/flags/) for global options not listed here.

🌈 Filter Options 🌈

Flags for filtering directory listings, bestie — this is the "what do I actually want" section 💖

• --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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone_serve/) — Serve a remote over a protocol.

---

🐳 rclone serve docker 🐳

bestie. we're serving ANY remote on docker's volume plugin API. it's giving "cloud storage but docker thinks it's a local volume" and honestly? iconic ✨

📜 Synopsis 📜

This command implements the Docker volume plugin API, which lets docker use rclone as a data storage mechanism for a whole buffet of cloud providers. rclone provides the docker volume plugin based on it. no cap.

So here's the tea on how you make a docker plugin: you create a Unix or TCP socket that Docker goes looking for when you use the plugin, and then it listens for commands from the docker daemon and runs the corresponding code when necessary. Docker plugins can run as a managed plugin under control of the docker daemon, or as an independent native service. For testing, you can literally just run it straight from the command line, like:

sudo rclone serve docker --base-dir /tmp/rclone-volumes --socket-addr localhost:8787 -vv

Running rclone serve docker will create the said socket, listening for commands from Docker to create the necessary Volumes. Normally you don't need to give the --socket-addr flag at all. The API will listen on the unix domain socket at /run/docker/plugins/rclone.sock. In the example above, rclone will create a TCP socket and a small file /etc/docker/plugins/rclone.spec containing the socket address. We use 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 commands will timeout trying to access the old socket. 😭 Running directly is supported on Linux only — not on Windows or MacOS. This is not a problem with managed plugin mode, described in detail in the full documentation (https://rclone.org/docker).

The command will create volume mounts under the path given by --base-dir (by default /var/lib/docker-volumes/rclone, available only to root) and maintain the JSON formatted file docker-plugin.state in the rclone cache directory, holding 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 provide defaults on the command line as well as set the path to the config file and cache directory, or adjust logging verbosity.

🔄 Restarting or upgrading the plugin 🔄

When the plugin is restarted (for example with docker plugin disable rclone && docker plugin enable rclone, when upgrading the plugin, or when the host reboots) rclone reads its docker-plugin.state file and restores the volumes and mounts that were active before. The plugin starts serving its socket straight away and re-establishes the mounts in the background, so a slow or unreachable remote no longer prevents the plugin from coming back up. periodt. 🫶

But — and this is the part you need to hear, bestie — restarting the plugin necessarily stops and restarts the process that serves the FUSE mounts. Any container that is already running and holding files open on an rclone volume keeps a handle to the old, now dead mount, so those handles start returning transport endpoint is not connected until the container is restarted. This is a limitation of replacing the process behind a live FUSE mount and cannot be avoided by rclone — the plugin itself recovers and newly started containers work normally, but:

• Restart any containers that were using rclone volumes after you restart or upgrade the plugin (e.g. docker restart <container>), or stop them before and start them after.
• Databases and other applications that keep files open continuously (Grafana, Prometheus, SQLite-backed apps, etc.) are the most affected and should always be restarted.

fr fr, if you've got a database squatting on an rclone volume, restart it. don't be that person 💀

🛡️ Security

so like, the plugin API takes a remote (aka fs) option when you create a volume, and bestie, it gets parsed exactly like an rclone connection string. Connection strings are trusted configuration — they can carry inline backend options, and some backends use those options to run local commands (the sftp backend's ssh option spawning an external binary is the classic example 👀). Which means anyone who can send requests to the plugin socket can make rclone run arbitrary commands as whoever's running rclone serve docker — and that's typically root. so. yeah. Treat access to that socket as literally equal to that level of access, and only ever expose it to callers you trust. periodt.

When rclone is listening on the default unix socket at /run/docker/plugins/rclone.sock, it makes that socket with mode 0660, owned by root and the group given by --socket-gid (which defaults to the process GID), so only root and members of that group — normally just the docker daemon — can reach it. Do not loosen these permissions, and do not hand that group over to untrusted users. nope nope nope 🙅

When you use --socket-addr to listen on a TCP socket, there is no authentication and the API is reachable by literally anyone who can open the port, so bind it to a loopback or otherwise trusted address and protect it with a firewall, okay? And note: holding Docker daemon access is already equivalent to root on the host, so a caller who can issue docker volume create doesn't actually gain anything new from this. the real concern is exposing the socket more widely than the daemon itself. 💅

---

🌈 VFS - Virtual File System

This command uses the VFS layer. It takes the cloud storage objects rclone works with and adapts them into something that looks wayyy more like a disk filing system ✨

Cloud storage objects have lots 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's no one single correct way of doing it, 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) in memory.

📁 VFS Directory Cache

Using the --dir-cache-time flag, you control how long a directory should be considered up to date and not refreshed from the backend. Changes made through the VFS will show up immediately or invalidate the cache. slay.

--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)

However 💀 changes made directly on the cloud storage — through the web interface, or by a different copy of rclone — will only get 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. iykyk.

You can send a SIGHUP signal to rclone and it'll 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)

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'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. The buffered data is bound to one open file and won't be shared. no sharing in this house 🙅♀️

This flag is an upper limit for the memory used per open file. The buffer will only use memory for data that's been downloaded but not yet read. If the buffer is empty, only a small amount of memory will be used. good news honestly.

The maximum memory rclone uses for buffering can be up to --buffer-size * open files. 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, but 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 you need one or the other, or 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 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.

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. it's giving tradeoffs, always.

Note that files are written back to the remote only when they're closed and if they haven't been accessed for --vfs-write-back seconds. If rclone is quit or dies while there are files that haven't been uploaded, those will be uploaded next time rclone is run with the same flags. no data left behind 💖

If you're 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's only checked every --vfs-cache-poll-interval. Secondly, because open files can't 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. rclone starts with the files that haven't been accessed for the longest. This cache flushing strategy is efficient, and the more relevant files are more likely to stay cached. iconic behaviour honestly 👑

The --vfs-cache-max-age will evict files from the cache after the set time since last access has passed; it's based on access time, not on when the file was first added to the cache. 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 will wait for 1 more hour before evicting. Specify the time with standard notation: s, m, h, d, w.

🚨 okay real talk: 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. yes really. 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 (which is the default), the cache will read directly from the remote and write directly to the remote, without caching anything on disk.

Which means some operations are just not possible, 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

This is very similar to off, except that files opened for read AND write will be buffered to disk. That means files opened for write will be a whole lot more compatible — but it uses the minimal amount of disk space. cute and efficient.

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, and write only and read/write files are buffered to disk first.

This mode should support all normal file system operations. finally.

If an upload fails, it will be retried at exponentially increasing intervals up to 1 minute. it's persistent, we love that 💅

👑 --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 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.

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's 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's recommended that --buffer-size is not set too large, and that --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 that doesn't support sparse files, and it will log an ERROR message if one is detected. you have been 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).

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. obsessed.

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

okay so real talk bestie 💖 heads up — if you go and 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. 😭 like, every single one of them. all over again. no cap.

VFS Chunked Reading

So when rclone reads files from a remote, it does not just inhale the whole file in one go — it reads them in chunks, like lil bite-size pieces. 🍓 That means instead of requesting the entire file, rclone reads the chunk specified. Why do we care? Because it can legitimately reduce the used download quota for some remotes (it only asks for chunks from the remote that are actually read), but it comes at the cost of an increased number of requests. The way that tradeoff works out is literally giving "more tiny knocks on the door vs one big knock." 🚪

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

And 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. 🙈 (yes, forever. it just keeps growing. main character energy.)

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. 🧚 (no doubling here, it stays exactly the same every time.)

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. (iykyk — there's no magic number, you gotta actually tune it.)

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 above. 👑

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. every read is a whole transaction. that's wild.

--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. 📤 (btw the related global flag --checkers has no effect on the VFS — not me finding that out the hard way 😭)

--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. 🦋 lowkey clever ngl.

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 (https://rclone.org/local/#symlinks-junction-points).

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 (https://github.com/rclone/rclone/issues/8245) with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). 💀 not me warning you twice.

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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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. slay.

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.

VFS Metadata

If you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. 🎀 These files will not appear in the directory listing, but can be stat-ed and opened and once they have been they will appear in directory listings until the directory cache expires.

Note that some backends won't create metadata unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

Okay so bestie, if your file has no metadata at all, rclone hits you with {} and keeps it moving. And if something goes sideways while reading the metadata? You get the error handed right back, shaped like {"error":"error string"}. No cap. 💅

Here's what that actually looks like in the wild:

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

Then the usage line, exactly as the manpage gods wrote it:

rclone serve docker [flags]

✨ Options ✨

Like, the whole menu. Every flag. Enjoy 💖

• --allow-idmap — let id-mapped mounts happen (Linux 6.12+, mount2 only)
• --allow-non-empty — let rclone mount right on top of a directory that already has stuff in it (not a Windows thing)
• --allow-other — other users get to come in too (not supported on Windows)
• --allow-root — the root user gets access (not supported on Windows)
• --async-read — do your reads async-style (not supported on Windows) (default true)
• --attr-timeout Duration — how long file/directory attributes get cached for (default 1s)
• --base-dir string — where the volumes live (default "/var/lib/docker-volumes/rclone")
• --daemon — run the mount in the background and yeet the parent process out (and because background output gets suppressed, use --log-file with --log-format=pid,... if you wanna monitor it) (not supported on Windows)
• --daemon-timeout Duration — how long rclone gets to respond to the kernel before time's up (not supported on Windows) (default 0s)
• --daemon-wait Duration — how long to wait for the daemon to be mount-ready (that's a maximum on Linux, but a flat constant sleep time on OSX/BSD) (not supported on Windows) (default 1m0s)
• --debug-fuse — debug the FUSE internals — heads up, it needs -v
• --default-permissions — makes the kernel enforce access control off the file mode (not supported on Windows)
• --devname string — set the device name, and the default is remote:path
• --dir-cache-time Duration — how long directory entries get cached (default 5m0s)
• --dir-perms FileMode — directory permissions (default 777)
• --direct-io — use Direct IO, which kills caching of data
• --file-perms FileMode — file permissions (default 666)
• --forget-state — skip restoring whatever state was there before
• --fuse-flag stringArray — flags or arguments passed straight 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 docker
• --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 the mount is case insensitive (true) or sensitive (false) no matter what the backend says (auto) (default unset)
• --network-mode — mount as a remote network drive instead of a fixed disk drive (Windows only, bestie)
• --no-checksum — don't bother comparing checksums on up/download
• --no-modtime — don't read/write the modification time (this can speed things up, ngl)
• --no-seek — don't allow seeking inside files
• --no-spec — don't write the spec file
• --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 if required)
• --poll-interval Duration — time to wait between polling for changes; it has to be smaller than dir-cache-time and only works on supported remotes (set it to 0 to disable) (default 1m0s)
• --read-only — read-only access only, that's the vibe
• --socket-addr string — address <host:port> or an absolute path (default: /run/docker/plugins/rclone.sock)
• --socket-gid int — GID for the unix socket (default: current process GID) (default 1000)
• --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 end up in the same directory (after normalization), log an error and hide the dupes (may cost you performance, fyi)
• --vfs-cache-max-age Duration — max time since last access for 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 hunt for a case-insensitive match
• --vfs-disk-space-total-size SizeSuffix — specify the total space of disk (default off)
• --vfs-fast-fingerprint — use fast (aka less accurate) fingerprints to detect changes
• --vfs-handle-caching Duration — how long to keep the file handle and downloaders alive after the last close (default 5s)
• --vfs-links — translate symlinks to/from regular files using a '.rclonelink' extension for the VFS
• --vfs-metadata-extension string — set the extension to read metadata from
• --vfs-read-ahead SizeSuffix — extra read ahead over --buffer-size when you're on 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 you're using cache (default 5s)
• --vfs-write-wait Duration — time to wait for an in-sequence write before throwing 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 the vibe) (not supported on Windows)

Options that are shared with other commands are described right below, bestie. And for the global options that aren't listed here, go peek at the global flags page (https://rclone.org/flags/). 🫶

🌸 Filter Options 🌸

Flags for filtering directory listings, okay?

• --delete-excluded — delete files on dest that got excluded from sync
• --exclude stringArray — exclude files matching pattern
• --exclude-from stringArray — read file exclude patterns from a file (use - to read from stdin)
• --exclude-if-present stringArray — exclude directories if 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 with no processing of the lines at all (use - to read from stdin)
• --files-from0 stringArray — read a list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --ignore-case — ignore case in filters (case insensitive)
• --include stringArray — include files matching 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 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 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 (https://rclone.org/commands/rclone_serve/) — Serve a remote over a protocol.

---

🦋 rclone serve ftp 🦋

Serve remote:path over FTP. ✨

✨ Synopsis ✨

Runs a lil baby FTP server that serves up a remote over the FTP protocol. You can peek at it with any FTP client, or lowkey just make your own remote of type FTP and read/write through it. Either way, it works. 💅

✨ Server options ✨

Use --addr to pick which IP address and port the server should sit and listen on, like --addr 1.2.3.4:8000, or --addr :8080 if you want it on literally every IP. By default it only listens on localhost, humble queen. And you can use port :0 to let the OS pick whatever available port it feels like. 🎀

If you set --addr to a public or LAN-accessible IP address, then using Authentication is advised — see the next section bestie, I'm not gonna let you get got.

✨ Authentication ✨

By default this will serve files without needing a login. It's giving open house. 🙈

You can set a single username and password with the --user and --pass flags. That's the whole vibe check.

## VFS - Virtual File System 🌸

Okay so this command uses the VFS layer. VFS stands for Virtual File System and what it does is adapt the cloud storage objects that rclone uses into something that looks a whole lot more like a disk filing system. Glow-up, honestly. ✨

Cloud storage objects have, like, so many 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 mess. And because there is no one right way of doing this, there are various options explained below. Pick your fighter.

The VFS layer also implements a directory cache — this caches info about files and directories (but not the data, bestie, just the metadata) 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 they'll invalidate the cache. Either way, slay.

--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)

However — and this is the part nobody tells you 💀 — changes made directly on the cloud storage by 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, then changes get picked up within the polling interval. Iconic behaviour, tbh.

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 you can do individual files or directories, main character energy:

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. Not sharing is self-care, actually.

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.

The maximum memory used by rclone for buffering can be up to --buffer-size * open files. Do with that information 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. No cap.

--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 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, always 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. 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. Obsessed with the efficiency, ngl. ✨

The --vfs-cache-max-age will evict files from the cache after the set time since last access has passed; it is based on access time, not on when the file was first added to the cache. 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 disk usage, zero chill.

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. It's giving low-effort-but-effective.

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, while write only and read/write files are buffered to disk first.

This mode should support all normal file system operations. Periodt. 👑

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 send.

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. The way that it only grabs what it needs?? Cheating, but legally.

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. 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. 😭

---

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. iykyk.

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.

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. A whole extra trip, for what. 💀

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. The speed, the slay. 🦋

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. Yeah. All of them. Start over bestie. 😭

---

VFS Chunked Reading 🍓

When rclone reads files from a remote it reads them in chunks — meaning 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 pieces, big brain. ✨

These flags control the chunking:

• --vfs-read-chunk-size SizeSuffix — reads the source objects in chunks (default 128M) ✨
• --vfs-read-chunk-size-limit SizeSuffix — the max size that chunk doubling is allowed to reach (default off) 👑
• --vfs-read-chunk-streams int — how many parallel streams read at once 🌈

The way chunking actually behaves literally depends on what you set --vfs-read-chunk-streams to, bestie. Two whole moods:

---

--vfs-read-chunk-streams == 0 💅

Rclone kicks off by reading a chunk of size --vfs-read-chunk-size, and then doubles that size on every read. If you've set --vfs-read-chunk-size-limit and it's bigger than --vfs-read-chunk-size, then each open file's chunk size only keeps doubling until it hits that value and then it chills there. If the value is "off" — which, btw, is the default — the limit is disabled and the chunk size will grow forever, no cap, no brakes, main character energy 🚀

With --vfs-read-chunk-size 100M and --vfs-read-chunk-size-limit 0, these are the parts that get downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. But 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 instead. Yes the math is mathing 💀

Setting --vfs-read-chunk-size to 0 or "off" disables chunked reading entirely. Periodt.

The chunks will not be buffered in memory. (so don't panic about your RAM, she's fine 🫶)

---

--vfs-read-chunk-streams > 0 🔥

Now rclone reads --vfs-read-chunk-streams chunks of size --vfs-read-chunk-size concurrently. The size for each read stays constant — no doubling happening here, we're stable, we're grounded, we're thriving 🧘

This improves performance massively on high latency links, or on very high bandwidth links to high performance object stores. It's giving glow-up.

Some experimentation will be needed to find the optimum values of --vfs-read-chunk-size and --vfs-read-chunk-streams, because these will depend on the backend in use and the latency to the backend. So like, go touch grass and tune your numbers, iykyk 🌸

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. Ate. 💖

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. Lowkey just keep adding streams until it stops being sad.

---

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 (up there 👆).

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. Like, every single time. Rent is due every time you peek at the mtime, bestie 😭

• --no-checksum — don't compare checksums on up/download. Skip the vibe check.
• --no-modtime — don't read/write the modification time (can speed things up).
• --no-seek — don't allow seeking in files. No jumping around.
• --read-only — only allow read-only access. Look but don't touch ✋

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 — like, only when there's no cache file on disk. Flag that. 🚩

• --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 — sorry babes, she just doesn't listen to that one 🙈

• --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. Clever girl. ✨

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, bestie. Scope matters.

This scheme is compatible with that used by the local backend with the --local-links flag (https://rclone.org/local/#symlinks-junction-points).

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. F in the chat. 💀

Note that there is an outstanding issue with symlink support, issue #8245 (https://github.com/rclone/rclone/issues/8245), with duplicate files being created when symlinks are moved into directories where there is a file of the same name (or vice versa). So like... heads up.

---

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. Strict queen. 👑

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. No duplicate-name drama allowed.

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. It's giving matchmaker, honestly. 🎀

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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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. Do not mess with this one, bestie, I'm so serious. 🙏

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. Iconic behaviour, honestly. 🌈

---

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. Like when the numbers come back lying. 🫠

• --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. She's doing the math herself, no help needed. 💅

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. Like bestie, this is the nuclear option. ⚠️

---

VFS Metadata 🎀

If you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. These files will not appear in the directory listing, but can be stat-ed and opened, and once they have been, they will appear in directory listings until the directory cache expires. Surprise appearance, iconic. ✨

Note that some backends won't create metadata unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

Look at that second ls — the .metadata file just spawned in like it always lived there. 🌸

If the file has no metadata it'll just hand you back {}, and if something goes sideways reading that metadata, you get {"error":"error string"} instead. Crystal clear, right? 💅

Auth Proxy ✨

Okay so if you pass in --auth-proxy /path/to/program, rclone will straight up use that program to generate backends on the fly, and those backends are what authenticate your incoming requests. The protocol is a lil JSON situation: input goes in on STDIN, output comes out on STDOUT. Simple. Iconic.

PLEASE NOTE: --auth-proxy and --authorized-keys cannot be used together — if --auth-proxy is set, the authorized keys option is just ignored. Periodt.

There's an example program bin/test_proxy.py over at https://github.com/rclone/rclone/blob/master/bin/test_proxy.py in the rclone source code if you wanna peek. 🧚

So the program's whole job is: take the user and pass it gets on input, and turn those into the config for a backend on STDOUT in JSON format. That config gets any default parameters for the backend added on, but it will not pull configuration from environment variables or command line options — nope, it's the proxy program's job to make a complete config. You want completeness, you bring completeness. ✋

This generated config must have this extra parameter:

• _root — root to use for the backend

And it may have these parameters too:

• _obscure — comma separated strings for parameters to obscure
• _secret_access_key — the secret for S3 access key auth (see below, bestie, don't skip it)

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",
  "client_ip": "192.168.1.1"
}

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",
  "client_ip": "192.168.1.1"
}

And if the client authenticated with an S3 access key (rclone serve s3), the client never sends its secret, only a signature made with it. So the input contains just the access key ID as the user, with no pass and no public_key:

{
  "user": "AKIAIOSFODNN7EXAMPLE",
  "client_ip": "192.168.1.1"
}

In this case the program has to look up the secret access key for that access key ID and return it in the _secret_access_key field of the output. Rclone then uses that secret to verify the signature on the request, and refuses the request if it doesn't match. Which means the proxy program is the source of truth for both the credentials and the backend they map to. And listen — if the program doesn't return _secret_access_key, or returns it empty? The request is refused. No secret, no entry. 💀

The program's answer for an access key ID is cached (see below), but it gets checked with the program again after 5 minutes even if that access key ID is in constant use. So revoking an access key ID in the program takes effect within 5 minutes. A rotated secret takes effect on the first request signed with it. Slay.

The client_ip key holds the IP address the client connected from, without a port number. You can use it to restrict logins to certain networks, or to log authentication attempts centrally. It's omitted if the client has no IP address — like when connecting over a unix socket. And heads up: if rclone is behind a reverse proxy, this will be the address of the reverse proxy, not the original client. 🙈

And as an example, it returns this on STDOUT:

{
  "type": "sftp",
  "_root": "",
  "_obscure": "pass",
  "user": "me",
  "pass": "mypassword",
  "host": "sftp.example.com"
}

Which would mean an SFTP backend gets 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, 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. Safety first, bestie. 🌸

There's an internal cache of backends keyed on the user, a hash of the pass or public_key, and the client_ip. Which means if a user's password or public-key changes, or the client connects from a new IP address, or the proxy returns different config parameters (eg a rotated api_key), a fresh backend will be created on the next request rather than the cached one being reused. Chef's kiss caching. ✨

This can be used to build general purpose proxies to any kind of backend that rclone supports. Main character proxy energy fr fr.

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-handle-caching Duration — Time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS
• --vfs-metadata-extension string — Set the extension to read metadata from
• --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. Peep the global flags page at https://rclone.org/flags/ for global options not listed here. 💖

---

Filter Options 🦋

Flags for filtering directory listings

• --delete-excluded — delete files on dest that got excluded from the sync (yes, actually delete them, bestie 💀)
• --exclude stringArray — exclude files matching a pattern
• --exclude-from stringArray — read your exclude patterns from a file (use - to read from stdin)
• --exclude-if-present stringArray — exclude directories if that filename is present in them
• --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 lines (use - to read from stdin)
• --files-from0 stringArray — read the list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partition filenames by hash k/n, or randomly with @/n
• --ignore-case — ignore case in filters (case insensitive era ✨)
• --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, given in s or with the suffix ms|s|m|h|d|w|M|y (default off)
• --max-depth int — if you set this, it limits the recursion depth to it (default -1)
• --max-size SizeSuffix — only transfer files smaller than this, in KiB or with the 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 - 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, given in s or with the suffix ms|s|m|h|d|w|M|y (default off)
• --min-size SizeSuffix — only transfer files bigger than this, in KiB or with the suffix B|K|M|G|T|P (default off)

---

🫶 See Also

• rclone serve (https://rclone.org/commands/rclone_serve/) — Serve a remote over a protocol. (the whole serve fam, iconic 👑)

---

🌈 rclone serve http 🌈

Serve the remote over HTTP. Straight up serving. No cap.

✨ Synopsis ✨

Run a basic web server to serve a remote over HTTP. You can peek at it in a web browser, or you can point a remote of type http at it and read from it that way.

You can use the filter flags (like --include, --exclude) to control exactly what gets served. Gatekeeping, but make it intentional 💅

The server will log errors. Use -v if you want to see access logs too.

--bwlimit will be respected for file transfers. And use --stats if you want to control the stats printing.

🌸 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. By default it only listens on localhost (introvert behaviour, honestly valid). You can use port :0 to let the OS pick an available port for you.

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. Seriously bestie, don't leave the door open 🙈

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, which we get into further below, can also be used to pull off the same thing.

--server-read-timeout and --server-write-timeout can be used to control the timeouts on the server. Heads up: 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.

--response-header can be used to set an HTTP header for all responses, and it will override existing values. The flag may be repeated to add multiple headers. Use the format Header-Name: value.

--allow-origin enables cross-origin (CORS) requests from browsers by setting the Access-Control-Allow-Origin header on every response to the origin you give it, e.g. --allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without needing authentication, because browsers never send credentials with them anyway. Setting this to * allows any origin — which is a security risk on an authenticated server. So like, know that before you do it 🚨

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

--disable-zip may be set to disable the zipping download option.

🦋 Protocol 🦋

The server supports HTTP/1.1 and HTTP/2. HTTP/2 is used automatically for TLS connections. For non-TLS connections, HTTP/2 cleartext (h2c) is supported, which means HTTP/2 without encryption. Slay, no encryption required.

🔐 TLS (SSL) 🔐

By default this will serve over http. If you want to, you can serve over https. You will need to supply the --cert and --key flags. And if you wish to do client side certificate validation then you will need to supply --client-ca as well.

When TLS is configured, every listener given with --addr serves TLS. An individual listener can be prefixed with http:// to serve unencrypted HTTP on that address, or with tls:// to state explicitly that it must serve TLS. Using a tls:// address without --cert and --key is an error.

--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 you're setting --client-ca, it should be set to the path of a file with PEM encoded client certificate authority certificates.

--min-tls-version is the minimum TLS version that's 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. First contact energy 👽✨

🎀 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 the '?sort=' parameter. Possible values: namedirfirst, name, size, time (default namedirfirst).
• .Order — the current ordering used. This is changeable via the '?order=' parameter. Possible values: asc, desc (default asc).
• .Query — currently unused.
• .Breadcrumb — allows for creating a relative navigation.
  • .Link — the link of the Text relative to the root.
  • .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.

…and that's the rest of the function lineup, bestie 👇

• afterEpoch — hands you exactly how much time has passed since the epoch, for whatever time you feed it. ⏰
• contains — vibe-checks whether a given substring is present or not inside a given string. yes/no energy. 🔍
• hasPrefix — checks whether the given string begins with the prefix you specified. literally just the beginning. ✨
• hasSuffix — checks whether the given string ends with the specified suffix. same deal, other end. 🎀

💖 Authentication 💖

okay so by default this whole thing serves files with no login needed at all. open house energy. 🏠

but babe, you have options:

• an htpasswd file — that one's the people-pleaser, it can hold lots of users
• or just one single username + password via the --user and --pass flags

OR you can let your reverse proxy do the auth and then trust the username it drops into a configured header, using --user-from-header (like, --user-from-header=x-remote-user for example). 🫶

⚠️ bestie pls be careful here: make sure the proxy is actually trusted and that headers cannot be spoofed, because a misconfiguration can legitimately lead to unauthorized access. not a drill. 💀

If neither of those auth methods is set up, and client certificates are required by the --client-ca flag passed to the server, then the client certificate's common name is what gets treated as the username. 👑

Use --htpasswd /path/to/htpasswd to point at your htpasswd file. It's in standard apache format and supports MD5, SHA1 and BCrypt for basic authentication. Bcrypt is the recommended one, no cap. 🧂

To create an htpasswd file:

touch htpasswd
htpasswd -B htpasswd user
htpasswd -B htpasswd anotherUser

and the cutest part? the password file can be updated while rclone is running. live updates, she doesn't even need a nap. 💅

When authentication is enabled, every single request must be authenticated — including HTTP OPTIONS requests, because the answer to an OPTIONS request can legit reveal whether a path exists. 🙈 So any health checks or monitoring that fire off unauthenticated OPTIONS requests will need to send credentials.

The one exception? Browser CORS preflight requests when --allow-origin is set — those get answered without authentication, because browsers never send credentials with them anyway. 🤷‍♀️

Use --realm to set the authentication realm.

Use --salt to change the password hashing salt away from the default.

---

🌈 VFS - Virtual File System 🌈

This command rides the VFS layer, and what that does is take the cloud storage objects rclone deals with and adapt them into something that looks way more like an actual disk filing system. 🗂️

Here's the tea though: cloud storage objects have a ton of properties that just aren't disk-file coded. You can't extend them, you can't write into the middle of them, and the VFS layer has to deal with all of that. And because there's genuinely no one right way to handle it, there are a bunch of options — all explained below. 👇

The VFS layer also implements a directory cache, which caches info about files and directories (but not 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 it's refreshed from the backend. Changes made through the VFS show up immediately, or they invalidate the cache. ⚡

--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 okay, plot twist: changes made directly on the cloud storage — like through the web interface or a different copy of rclone — only get picked up once the directory cache expires, if the backend you configured doesn't support polling for changes. If it does support polling, changes are picked up within the polling interval. 🔄

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

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 decides how much memory gets used to buffer data in advance.

Each open file will try 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. 🚫🤝

This flag is an upper limit for memory used per open file. The buffer only uses memory for data that's been downloaded but not yet read — so if the buffer is empty, only a small amount of memory is used. 🍃

The max memory rclone can use for buffering can be up to --buffer-size * open files. 📈

🎀 VFS File Caching 🎀

These flags control the VFS file caching options. File caching is what makes the VFS layer actually appear compatible with a normal file system — and it can be disabled, at the cost of some compatibility. 🙃

Like, for example, you'll need VFS caching enabled if you wanna read and write to a file simultaneously. More deets below. 👇

Note that the VFS cache is separate from the cache backend — and you may find you 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, selected by --vfs-cache-mode. The higher the cache mode, the more compatible rclone becomes — at the cost of eating up disk space. 💾

Note that files are only written back to the remote when they're closed, and only if they haven't been accessed for --vfs-write-back seconds. If rclone is quit or dies with files that haven't been uploaded yet, those will get uploaded next time rclone is run with the same flags. 🔁

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, heads up: the cache may exceed these quotas for two reasons. First, because it's 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 try to evict the least accessed files from the cache first — starting with the files that haven't been accessed for the longest. This flushing strategy is efficient, and it means the more relevant files are the ones likely to stay cached. 🏆

The --vfs-cache-max-age will evict files from the cache after the set time since last access has passed — it's based on access time, not on when the file was first added to the cache. The default of 1 hour means it starts evicting files that haven't been accessed for 1 hour. And 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 .

🚨 serious one: 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. Doing that can potentially cause data corruption. 😭 You can work around it by giving each rclone its own cache hierarchy with --cache-dir. And if the remotes in use don't overlap, you don't need to worry about this at all. 🫶

💅 --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 just... 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 become 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 for read only are still read directly from the remote, while write only and read/write files get buffered to disk first.

This mode should support all normal file system operations. 👑

And 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, that gets buffered to disk as well. 📥

In this mode the files in the cache are 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 only buffers 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. 🤯

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. 🌈

CW: this bit right here will bite you if you ignore it — not all file systems support sparse files. Specifically, <yellow>FAT/exFAT do not</yellow>. And rclone is gonna be so dramatic about it: if your cache directory lives on a filesystem that doesn't do sparse files, performance is going to be very bad, and rclone will log an ERROR message the second it sniffs one out. 💀

Fingerprinting ✨

Okay so various parts of the VFS do this thing called fingerprinting — think of it like checking a glow-up pic to see if a local file copy has changed compared to the remote file. Fingerprints get made from:

• size
• modification time
• hash

…where those exist on an object, bestie. 💅

And here's the tea: on some backends, some of these attributes are slow to read — like, they cost an extra API call per object, or extra work per object. Annoying fr fr.

For example, hash is slow with the local and sftp backends because they literally 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 that extra API call just to fetch it. 😭

So if you use the --vfs-fast-fingerprint flag, rclone will leave the slow operations out of the fingerprint entirely. The fingerprint gets less accurate but much faster, and it'll improve the opening time of your cached files. 👑

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

Careful though: if you change the value of this flag, the fingerprints of the files in the cache may get 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 entire file, rclone reads just the chunk specified. For some remotes this can reduce your used download quota, because you're only requesting the chunks from the remote that are actually being read — at the cost of an increased number of requests. tradeoff vibes.

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. so like, pay attention to that one. 👀

--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 gets doubled only until it hits that specified value. If the value is "off", which is the default, the limit is disabled and the chunk size just grows indefinitely. no cap. literally.

With --vfs-read-chunk-size 100M and --vfs-read-chunk-size-limit 0, the following parts will get downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. But 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. see how it doubles? iconic. ✨

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

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. no doubling here, just vibes.

This massively improves performance 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 these will depend on the backend in use and the latency to the backend. you gotta fiddle, 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.

Specifically: S3 and Swift benefit hugely from the --no-modtime flag (or you can use --use-server-modtime for a slightly different effect), because each read of the modification time takes a transaction. every single time. 😮‍💨

--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 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 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 that one trips people up.

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

Symlinks 🦋

By default the VFS does not support symlinks. But don't cry — 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 it works. 💅

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 (https://rclone.org/local/#symlinks-junction-points).

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.

Heads up: there's an outstanding issue with symlink support — issue #8245 (https://github.com/rclone/rclone/issues/8245) — where duplicate files get 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.

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. iykyk.

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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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. But bestie, this comes with a performance tradeoff, because 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 you don't need it. However, macOS users may wish to consider using it — 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 filing system. It can be useful when those statistics can't be read correctly automatically. sometimes the machine just lies, ok.

--vfs-disk-space-total-size    Manually set the total disk space size (example: 256G, default: -1)

### ✨ Alternate report of used bytes ✨

okay so bestie, picture this: some backends — looking at YOU, S3, main character of not telling us anything — just refuse to report how many bytes are actually being used. rude. so if you need that number to show up correctly when you run df on the filesystem, you go ahead and pass the flag --vfs-used-is-size to rclone. with that flag set, instead of trusting the backend to spill the tea, rclone will legitimately scan the whole remote — basically like rclone size does — and compute the total used space all by itself. 💪

⚠️ WARNING: contrary to rclone size, this flag ignores filters so that the result is accurate. but bestie, it is SO inefficient and may cost you lots and lots of API calls, which means extra charges 💀. use it as a last resort and only with caching, fr fr.

---

### 🎀 VFS Metadata 🎀

if you use the --vfs-metadata-extension flag, you can get the VFS to expose files that contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. these files will not appear in the directory listing, but they can be stat-ed and opened — and once they have been, they will show up in directory listings until the directory cache expires. it's giving ✨surprise appearance✨.

ngl, note that some backends won't even create metadata unless you pass in the --metadata flag. so like, don't forget it.

for example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

if the file has no metadata it will be returned as {} and if there is an error reading the metadata, the error will be returned as {"error":"error string"}. simple as that 💅

---

### 🔐 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 whole simple JSON based protocol with input on STDIN and output on STDOUT. slay.

PLEASE NOTE: --auth-proxy and --authorized-keys cannot be used together — if --auth-proxy is set, the authorized keys option will be ignored. pick a lane bestie 😌

there is an example program bin/test_proxy.py (https://github.com/rclone/rclone/blob/master/bin/test_proxy.py) in the rclone source code if you wanna peek.

so 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. no shortcuts.

this config generated must have this extra parameter:

• _root — root to use for the backend

and it may have these parameters:

• _obscure — comma separated strings for parameters to obscure
• _secret_access_key — the secret for S3 access key auth (see below)

if password authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{
  "user": "me",
  "pass": "mypassword",
  "client_ip": "192.168.1.1"
}

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",
  "client_ip": "192.168.1.1"
}

if the client authenticated with an S3 access key (rclone serve s3), the client never sends its secret, only a signature made with it — so the input contains just the access key ID as the user with no pass or public_key:

{
  "user": "AKIAIOSFODNN7EXAMPLE",
  "client_ip": "192.168.1.1"
}

in this case the program must look up the secret access key for that access key ID and return it in the _secret_access_key field of the output. rclone then uses that secret to verify the signature on the request, refusing the request if it does not match. this means the proxy program is the source of truth for both the credentials and the backend they map to. if the program does not return _secret_access_key or returns it empty, the request is refused. periodt.

the program's answer for an access key ID is cached (see below) but is checked with the program again after 5 minutes even if the access key ID is in constant use, so revoking an access key ID in the program takes effect within 5 minutes. a rotated secret takes effect on the first request signed with it.

the client_ip key holds the IP address the client connected from, without a port number. it can be used to restrict logins to certain networks, or to log authentication attempts centrally. it is omitted if the client has no IP address — for example when connecting over a unix socket. note that if rclone is behind a reverse proxy, this will be the address of the reverse proxy and not the original client. iykyk 🫶

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). yeah it's that deep.

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. be safe bestie 💜

an internal cache of backends is keyed on the user, a hash of the pass or public_key, and the client_ip. this means that if a user's password or public-key changes, the client connects from a new IP address, or the proxy returns different config parameters (eg a rotated api_key), a fresh backend will be created on the next request rather than the cached one being reused. fresh backend, fresh vibe ✨

this can be used to build general purpose proxies to any kind of backend that rclone supports. iconic.

rclone serve http remote:path [flags]

✨ Options ✨

okay bestie, deep breath, because rclone serve http has a LOT of flags and every single one of them is going in this list, no skips, no shortcuts 💅

• --addr stringArray — the IPaddress:Port (or just :Port) the server binds to (default 127.0.0.1:8080)
• --allow-origin string — which Origin gets to run cross-domain requests (CORS) from it
• --auth-proxy string — a program you use to build the backend out of the auth
• --baseurl string — prefix for your URLs; leave it blank if you want root
• --cert string — the TLS PEM key, which is your certificate and your CA certificate smushed together
• --client-ca string — the client certificate authority used to verify clients
• --dir-cache-time Duration — how long directory entries get cached (default 5m0s)
• --dir-perms FileMode — directory permissions (default 777)
• --disable-dir-list — kills the HTML directory listing on a GET request for a directory
• --disable-zip — kills zip download of directories
• --file-perms FileMode — file permissions (default 666)
• --gid uint32 — overrides the gid field the filesystem sets (not supported on Windows) (default 1000)
• -h, --help — help for http, the classic 🫶
• --htpasswd string — an htpasswd file; if you don't hand one over, literally no authentication happens
• --key string — TLS PEM Private key
• --link-perms FileMode — link permissions (default 666)
• --max-header-bytes int — the biggest request header you're allowed (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 or write the modification time (it can legit speed things up)
• --no-seek — seeking in files is off the table
• --pass string — password for authentication
• --poll-interval Duration — how long to wait between polls for changes; it has to be smaller than dir-cache-time and only works on supported remotes (set 0 to disable) (default 1m0s)
• --read-only — read-only access ONLY, nothing else gets through
• --realm string — realm for authentication
• --response-header stringArray — sets an HTTP header for all responses, overriding whatever values were already there
• --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 — user-specified template
• --uid uint32 — overrides the uid field the filesystem sets (not supported on Windows) (default 1000)
• --umask FileMode — overrides the permission bits the filesystem sets (not supported on Windows) (default 002)
• --user string — user name for authentication
• --user-from-header string — pulls the user name out of a defined HTTP header
• --vfs-block-norm-dupes — if duplicate filenames show up in the same directory after normalization, it logs an error and hides the dupes (heads up, this may cost you performance)
• --vfs-cache-max-age Duration — max time since an object in the cache was last accessed (default 1h0m0s)
• --vfs-cache-max-size SizeSuffix — max total size of the 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 — how often the cache gets polled for stale objects (default 1m0s)
• --vfs-case-insensitive — if a filename isn't found, it hunts for a case-insensitive match instead
• --vfs-disk-space-total-size SizeSuffix — specify the total space of the disk (default off)
• --vfs-fast-fingerprint — fast (and honestly less accurate) fingerprints for change detection
• --vfs-handle-caching Duration — how long a file handle and its downloaders stay alive after the last close (default 5s)
• --vfs-links — translates symlinks to and from regular files with a .rclonelink extension for the VFS
• --vfs-metadata-extension string — sets the extension metadata gets read from
• --vfs-read-ahead SizeSuffix — extra read ahead on top of --buffer-size when you're in cache-mode full
• --vfs-read-chunk-size SizeSuffix — reads the source objects in chunks (default 128Mi)
• --vfs-read-chunk-size-limit SizeSuffix — if it's greater than --vfs-read-chunk-size, the chunk size doubles after every chunk read until it hits the limit ('off' means unlimited) (default off)
• --vfs-read-chunk-streams int — how many parallel streams read at once
• --vfs-read-wait Duration — how long to wait for an in-sequence read before seeking (default 20ms)
• --vfs-read-wait Duration — nope, that's the same one 💀 (default 20ms)
• --vfs-refresh — refreshes the directory cache recursively, in the background, on start
• --vfs-used-is-size rclone size — uses the rclone size algorithm for the Used size
• --vfs-write-back Duration — how long to writeback files after last use when caching (default 5s)
• --vfs-write-wait Duration — how long to wait for an in-sequence write before it just gives you an error (default 1s)

---

Options that get shared with other commands are described right after this, bestie. And for global options that aren't listed here, go check the global flags page at https://rclone.org/flags/ 👑

✨ Filter Options ✨

These are the flags for filtering directory listings 🧚

• --delete-excluded — deletes files on the destination that got excluded from the sync
• --exclude stringArray — excludes files that match the pattern
• --exclude-from stringArray — reads file exclude patterns out of a file (use - to read from stdin)
• --exclude-if-present stringArray — excludes directories if that filename is present in them
• --files-from stringArray — reads a list of source-file names from a file (use - to read from stdin)
• --files-from-raw stringArray — reads a list of source-file names from a file with zero processing of the lines (use - to read from stdin)
• --files-from0 stringArray — reads a list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partitions filenames by hash k/n or randomly @/n
• --ignore-case — ignores case in filters, i.e. case insensitive
• --include stringArray — includes files that match the pattern
• --include-from stringArray — reads file include patterns from a file (use - to read from stdin)
• --max-age Duration — only transfers files younger than this, in s or with a ms|s|m|h|d|w|M|y suffix (default off)
• --max-depth int — if you set it, it caps the recursion depth at this (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 the 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 the 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 ms|s|m|h|d|w|M|y suffix (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)

✨ See Also ✨

• rclone serve (https://rclone.org/commands/rclone_serve/) — Serve a remote over a protocol.

---

rclone serve nfs 🌈

Serve the remote as an NFS mount

Synopsis

Creates an NFS server that serves the given remote over the network. Slay.

This is an NFSv3 server, and it'll serve any rclone remote over NFS. No cap.

So why does this exist? The main character reason: it lets the mount command (https://rclone.org/commands/rclone_mount/) work on recent macOS versions, where installing FUSE is an absolute ordeal 😭

Heads up bestie, this server does not implement any authentication, so any client can just waltz in and access the data. To lock things down you can run serve nfs on the loopback address, or lean on secure tunnels (like SSH), or do some firewalling. Your call, your vibes.

For exactly that reason, by default a random TCP port gets chosen, and the loopback interface is used as the listening address by default — meaning it's only reachable from the local machine. If you want other machines to reach the NFS mount over the local network, you need to specify the listening address and port with the --addr flag. 🫶

Modifying files through the NFS protocol requires VFS caching. Usually you'll need to specify --vfs-cache-mode so you can actually write to the mountpoint (full is the recommended one, periodt). If you don't specify a VFS cache mode, the mount is read-only. No writing, sorry not sorry.

--nfs-cache-type controls the type of the NFS handle cache. By default this is memory, where new handles get randomly allocated whenever they're needed, and they're stored in memory. If the server restarts, that handle cache is gone and connected NFS clients will get stale handle errors 💀

--nfs-cache-type disk uses an on-disk NFS handle cache instead. 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 specify the exact directory with --nfs-cache-dir. The whole point? With this, the NFS server can be restarted whenever you want without affecting the connected clients. Iconic, honestly 💅

--nfs-cache-type symlink is basically the sibling of --nfs-cache-type disk — it also keeps its cache on disk, but the cache entries are stored as symlinks. Rclone grabs the handle of the underlying file and uses that as the NFS handle, which is a whole performance glow-up. The catch: this kind of cache can't be backed up and restored, because the underlying handles will change on you. 😭 This one is Linux only, and it needs rclone running as root or with CAP_DAC_READ_SEARCH. Want to bless your rclone binary with that extra permission? Do this:

sudo setcap cap_dac_read_search+ep /path/to/rclone

--nfs-cache-handle-limit sets the max number of cached NFS handles the caching handler will hold onto. Do not set this too low or you'll start hitting errors when you try to access files, fr fr. The default is 1000000, but bestie, feel free to lower it if the server's system resource usage is giving problems. Heads up: this is only used by the memory type cache. 💅

To serve NFS over the network, run this:

rclone serve nfs remote: --addr 0.0.0.0:$PORT --vfs-cache-mode=full

That picks the port you'll use in the mount command. To mount the server on Linux/macOS, hit it with:

mount -t nfs -o port=$PORT,mountport=$PORT,tcp $HOSTNAME:/ path/to/mountpoint

Where $PORT is the exact same port number you used in the serve nfs command, and $HOSTNAME is the network address of the machine serve nfs was running on. 🫶

NFS clients can also mount a subdirectory of the served remote by sticking it into the mount path. Say you only want photos/2024:

mount -t nfs -o port=$PORT,mountport=$PORT,tcp $HOSTNAME:/photos/2024 path/to/mountpoint

The subpath gets resolved inside the served remote and must point at a directory that actually exists — not a file, not a symlink. Subpath mounts are a convenience thing: they're equivalent to mounting / and then changing directory. They share access to the same underlying VFS and the same file handles, so no, they do not isolate the client from the siblings or the parents of the mounted subdirectory. 👀

If --vfs-metadata-extension is in use, then for --nfs-cache-type disk and --nfs-cache-type cache the metadata files will have the file handle of their parent file suffixed with 0x00, 0x00, 0x00, 0x01. Which means they can be looked up directly from the parent file handle, if that's what you want. ✨

This command is only available on Unix platforms. 🐧

---

🦋 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. 🌸

Cloud storage objects come with a whole pile of properties that just aren't very disk-file-coded: 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's genuinely no single right way to do it, there are a bunch of options, explained below. 💜

The VFS layer also implements a directory cache — it caches info about files and directories (not the actual data, bestie) in memory.

VFS Directory Cache

Using the --dir-cache-time flag, you control how long a directory gets to be considered up to date before it's refreshed from the backend. Changes made through the VFS show up immediately, or they invalidate the cache. 👑

--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 here's the thing — changes made directly on the cloud storage, like via the web interface or a different copy of rclone, will only get 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. 🌈

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

kill -SIGHUP $(pidof rclone)

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 go one file / one directory at a time:

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

VFS File Buffering

The --buffer-size flag decides how much memory gets used to buffer data in advance. 🧚

Every open file will try to keep that specified amount of data in memory at all times. The buffered data is bound to one open file and is not shared. Nope, no sharing. 🙈

This flag is an upper limit for the memory used per open file. The buffer only uses memory for data that's been downloaded but not yet read — so if the buffer is empty, only a small amount of memory gets used. Slay, efficient. ✨

The maximum memory rclone uses for buffering can be up to --buffer-size * open files.

VFS File Caching

These flags control the VFS file caching options. File caching is genuinely necessary to make the VFS layer act compatible with a normal file system. You can disable it, but that costs you some compatibility. 💅

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

Note that the VFS cache is separate from the cache backend, and you may find you need one or the other, or 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)

Run it with -vv and 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 with --vfs-cache-mode. The higher the cache mode, the more compatible rclone becomes — at the cost of using disk space. That's the trade, bestie. 💀

Heads up: 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 dies while holding files that haven't been uploaded, those will get uploaded the next time rclone runs with the same flags. 🫶

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, note that the cache may exceed these quotas for two reasons. First: it's only checked every --vfs-cache-poll-interval. Second: open files can't be evicted from the cache, periodt. 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, and this cache flushing strategy is efficient — more relevant files are likely to stay cached. ✨

--vfs-cache-max-age will evict files from the cache once the set time since their last access has passed. It's based on access time, not on when the file was first added to the cache. The default value of 1 hour means it'll start evicting files 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. 🕐

🚨 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. That can potentially cause data corruption, and we do not play like that. You can work around it by giving each rclone its own cache hierarchy with --cache-dir. And you don't need to worry about any of this if the remotes in use don't overlap. 💖

--vfs-cache-mode off

In this mode (the default), the cache reads directly from the remote and writes directly to the remote — nothing gets cached on disk at all.

Which means some operations are just... 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 one is very similar to off, except files opened for read AND write get buffered to disk. That means files opened for write are a lot more compatible, while using the minimal amount of disk space. Iconic. 💅

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 get buffered to disk first. 🦋

This mode should support all normal file system operations. Ate. 💅

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, 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, 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 downloaded data actually present in them. Sneaky but correct. ✨

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 that doesn't support sparse files, and it will log an ERROR message if one is detected. So like, check your filesystem first, bestie. 🙈

🔍 Fingerprinting

ok so VFS is out here doing detective work 🕵️♀️ — different parts of it use fingerprinting to figure out whether some local file copy has actually changed compared to the remote one. And a fingerprint is built from:

• size
• modification time
• hash

…but only where available on an object, bestie. no making stuff up.

Now here's the tea: on some backends, some of these attributes are slow to read 😭 like they take an extra API call per object, or extra work per object. brutal.

For example, hash is slow with the local and sftp backends because they literally 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 just to fetch it. exhausting behavior tbh 💀

So if you pass the --vfs-fast-fingerprint flag, rclone will leave the slow operations out of the fingerprint. Is it less accurate? yes. Is it much faster and does it improve the opening time of cached files? also yes. slay. ✨

And if you're running a vfs cache over local, s3 or swift backends? using this flag is recommended. do it.

heads up: if you change the value of this flag, the fingerprints of the files in the cache may get invalidated and the files will need to be downloaded again. so like… know that going in 🙈

---

📦 VFS Chunked Reading

When rclone reads files from a remote, it reads them in chunks. so instead of requesting the whole entire file, it just reads the chunk specified. this can reduce the used download quota for some remotes — you're only asking for chunks from the remote that are actually read — at the cost of an increased number of requests. tradeoffs, babe 🎀

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

And the chunking behaves differently depending on the --vfs-read-chunk-streams parameter. so let's break it down 👑

--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. no cap, fr. 🙈

So 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. But 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. the glow up 📈

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

Also — the chunks will not be buffered in memory. noted. 💅

--vfs-read-chunk-streams > 0

Rclone reads --vfs-read-chunk-streams chunks of size --vfs-read-chunk-size concurrently. and the size for each read stays constant. no doubling, just parallel vibes 🦋

This improves performance massively on high latency links or very high bandwidth links to high performance object stores. it's giving speed ✨

You're gonna need some experimentation to find the optimum values of --vfs-read-chunk-size and --vfs-read-chunk-streams, because 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 above, bestie.

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. expensive!! 😭

--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, fyi).

--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 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. cute little disguise 🎀

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 (https://rclone.org/local/#symlinks-junction-points).

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. ngl, just so you know. 🙈

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.

alsooo there's an outstanding issue with symlink support — issue #8245 (https://github.com/rclone/rclone/issues/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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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. seriously bestie, don't touch 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. no more spooky twin files 🫶

---

💽 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

okay so here's the tea ☕: some backends — most notably S3, we see you — straight up do not report how many bytes are being used. Like, no number at all. So if you need that info to actually show up when you run df on the filesystem, pass the flag --vfs-used-is-size to rclone. With this flag set, instead of vibing and trusting the backend to give you that number, rclone will scan the whole remote kind of like rclone size does and compute the total used space itself. girlboss move honestly 💅

WARNING: Contrary to rclone size, this flag ignores filters so that the result is accurate. But bestie… it is very inefficient and may cost lots of API calls, which means extra charges. 😭 Use it as a last resort and only with caching. fr fr.

---

🌸 VFS Metadata

If you use the --vfs-metadata-extension flag you can make the VFS expose files that contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. ✨ These files will not show up in the directory listing, but they can be stat-ed and opened — and once they have been, they will appear in directory listings until the directory cache expires. sneaky little guys 🙈

ngl some backends won't even create metadata unless you pass the --metadata flag. heads up 🫶

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
    "atime": "2025-03-04T17:34:22.317069787Z",
    "btime": "2025-03-03T16:03:37.708253808Z",
    "gid": "1000",
    "mode": "100664",
    "mtime": "2025-03-03T16:03:39.640238323Z",
    "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

If the file has no metadata it will be returned as {} and if there's an error reading the metadata, the error will be returned as {"error":"error string"}. 💀

rclone serve nfs remote:path [flags]

---

👑 Options

• --addr string — IPaddress:Port or :Port to bind server to
• --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 nfs
• --link-perms FileMode — link permissions (default 666)
• --nfs-cache-dir string — the directory the NFS handle cache will use if set
• --nfs-cache-handle-limit int — max file handles cached simultaneously (min 5) (default 1000000)
• --nfs-cache-type memory|disk|symlink — 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 (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 isn't 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-handle-caching Duration — time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — translate symlinks to/from regular files with a .rclonelink extension for the VFS
• --vfs-metadata-extension string — set the extension to read metadata from
• --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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 (https://rclone.org/commands/rclone_serve/) — serve a remote over a protocol. 👑

🌸 rclone serve restic

okay bestie, this one is the restic server. Serve the remote for restic's REST API. 💖

✨ Synopsis

Run a basic web server to serve a remote over restic's REST backend API over HTTP. The way this works is it lets restic use rclone as a data storage mechanism for cloud providers that restic does not support directly. iconic behavior fr fr 🎀

Restic (<https://restic.net/>) is a command-line program for doing backups.

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 (<https://rclone.org/docs/#configure>).

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 biggie.

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. 👑

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. lowkey genius ngl 🧚

---

🦋 Setting up restic to use rclone

Now you can follow the restic instructions (<http://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#rest-server>) on setting up restic.

Note that you will need restic 0.8.2 or later to interoperate with rclone. bestie don't be on ancient versions, it's giving 2016 😭

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

---

🌈 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

---

🎀 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. 🙈

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.

--response-header can be used to set an HTTP header for all responses, will overriding existing values. The flag may be repeated to add multiple headers. Use the format Header-Name: value.

--allow-origin enables cross-origin (CORS) requests from browsers by setting the Access-Control-Allow-Origin header on every response to the origin given, e.g. --allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without needing authentication as browsers never send credentials with them. Setting this to * allows any origin which is a security risk on an authenticated server. 💀

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

--disable-zip may be set to disable the zipping download option.

---

🌸 Protocol

The server supports HTTP/1.1 and HTTP/2. HTTP/2 is used automatically for TLS connections. For non-TLS connections, HTTP/2 cleartext (h2c) is supported, allowing HTTP/2 without encryption. slay ✨

---

🔥 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.

When TLS is configured every listener given with --addr serves TLS. An individual listener can be prefixed with http:// to serve unencrypted HTTP on that address, or with tls:// to state explicitly that it must serve TLS. Using a tls:// address without --cert and --key is an error.

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

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.

Alternatively, you can have the reverse proxy manage authentication and use the username provided in the configured header with --user-from-header (e.g., --user-from-header=x-remote-user). Ensure the proxy is trusted and headers cannot be spoofed, as misconfiguration may lead to unauthorized access. ⚠️

If either of the above authentication methods is not configured 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.

When authentication is enabled every request must be authenticated, including HTTP OPTIONS requests, as the answer to an OPTIONS request can reveal whether a path exists. Health checks or monitoring which use unauthenticated OPTIONS requests will need to send credentials. The exception is browser CORS preflight requests when --allow-origin is set, which are answered without authentication as browsers never send credentials with them.

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 or :Port 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 — TLS PEM key (concatenation of certificate and CA certificate)
• --client-ca string — Client certificate authority to verify clients with
• -h, --help — help for restic
• --htpasswd string — A htpasswd file - if not provided no authentication is done
• --key string — TLS PEM Private key
• --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
• --response-header stringArray — Set HTTP header for all responses, overriding existing values
• --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
• --user-from-header string — User name from a defined HTTP header

See the global flags page (<https://rclone.org/flags/>) for global options not listed here.

---

🌈 See Also

• rclone serve (<https://rclone.org/commands/rclone_serve/>) - Serve a remote over a protocol.

🦋 rclone serve s3

Serve that remote:path over s3, bestie. Let's GO.

✨ Synopsis ✨

serve s3 ships a basic s3 server that serves a remote via s3. You can point an s3 client at it, or (iconic behaviour tbh) you can make an s3 type remote (https://rclone.org/s3/) and read + write to it with rclone itself.

🫶 Heads up: serve s3 is considered Experimental so use with care, okay?

The 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: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html.)

--auth-key can be repeated for multiple auth pairs. If --auth-key isn't provided, then serve s3 will let in anonymous access 😳.

Alternatively --auth-proxy can be used to look up the secret for each access key ID and choose the backend it maps to (see Auth Proxy below). When an auth proxy is in use --auth-key is ignored and every request must be signed with the secret the proxy returns for its access key ID. Each access key ID is a separate user, whose multipart uploads and object metadata are private to it, even if the proxy maps several access key IDs to the same backend. (very demure, very private 💅)

As on AWS, every x-amz-* header in an authenticated request must be in its signed headers list; a request with an unsigned x-amz-* header is refused with AccessDenied. S3 clients sign these headers as a matter of course, but a header added after signing (for example by a proxy in front of the server, or x-amz-meta-* headers sent with a presigned URL which only signs the host) is refused. not me getting rejected at the door 💀

Like all rclone flags --auth-key can be set via environment variables, in this case RCLONE_AUTH_KEY. Since this flag can be repeated, the input to RCLONE_AUTH_KEY is CSV encoded. Because the accessKey,secretKey has a comma in, this means it needs to be in quotes.

export RCLONE_AUTH_KEY='"user,pass"'
rclone serve s3 ...

Or to supply multiple identities:

export RCLONE_AUTH_KEY='"user1,pass1","user2,pass2"'
rclone serve s3 ...

Setting this variable without quotes will produce an error. 🙈

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. Use --etag-hash auto to use the best hash the backend supports — with --auth-proxy that of each user's backend.

---

🎀 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. slay.

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

---

🌸 Object uploads (PUT) 🌸

A PutObject upload only ever changes the object at its key atomically — on success, a failed or interrupted PUT neither removes nor overwrites the object already stored at the key, and never leaves a partial object visible at it. periodt. ✨

Remotes that upload atomically (e.g. object stores such as s3) are streamed straight to the destination. On remotes where a partial upload would otherwise be visible (e.g. local), and whenever --vfs-cache-mode is writes or above, the upload is written to a temporary object that is renamed into place on success; these remotes need to support a server-side move or copy for this (nearly all do — without move or copy the upload is written directly and a failed PUT may leave a partial object at the key 😭). If serve s3 is killed part-way through an upload the temporary object (named with a leading .rclone_temp_put_) may be left behind; it is hidden from S3 listings but must be removed manually.

---

💜 Multipart uploads 💜

Multipart uploads are written, in part-number order, to a temporary object which is renamed into place, server-side, on completion, so the upload is atomic. The object at the key only ever changes on a successful completion. A failed or aborted upload never affects any object already stored under that name and a partly-uploaded object never becomes visible under it. chef's kiss 👑

With the default --vfs-cache-mode off serve s3 streams each multipart upload, in part-number order, into a single streaming upload to the underlying remote, so the whole file is never buffered in memory — only parts which arrive out of order are buffered, within the limits described below. The remote then performs its own internal upload (for example its own multipart upload, still with bounded memory). Remotes that don't support streaming uploads (those that must know the file size before the upload starts, such as onedrive, pcloud, jottacloud, mailru, opendrive, putio, protondrive and zoho) have the parts spooled to a temporary file on local disk instead, and uploaded with the size then known on completion, so they need local disk space for the largest objects in flight rather than memory.

With --vfs-cache-mode writes (or full) the parts are written to a temporary file in the VFS cache and uploaded by the VFS write-back — see Multipart uploads and the VFS cache below.

The rename into place needs the remote to support a server-side move or copy, which nearly all do. It is a cheap rename on most remotes, but on object stores without a real rename (such as s3 itself) the move is performed as a server-side copy and delete of the whole object, which can take time and API calls for large objects. Concurrent multipart uploads of the same key (which S3 permits) are safe. Each writes its own temporary object and the last to complete wins. 🏁

On the few remotes that support neither server side move nor copy, the parts are written straight to the destination object instead and never buffered in memory. This is at some cost in atomicity — the incomplete object is visible under its final name while the upload is in flight, as it also is for a plain object PUT on such remotes, and concurrent multipart uploads of the same key write to the same object and can interleave. A failed or aborted upload still leaves any pre-existing object untouched provided the remote uploads atomically and the VFS cache is off; on a remote where partial uploads are visible it may leave partial data at the key (like a plain PUT there), and with --vfs-cache-mode writes (or full) a write to the cache cannot be abandoned, so an aborted upload's partial data is written back to the remote as if it had completed. 💀 not ideal bestie

⭐ Features ⭐

• The whole object is never buffered in memory; only parts arriving out of order are, within fixed limits, whatever the upload size.
• Parts can be any size. Clients that don't produce uniform-sized parts work fine — for example PostgreSQL backup tools such as pgBarman and pgBackRest, which flush an upload buffer once it grows past the chunk size, so each part is the chunk size plus a variable overshoot.
• Works through crypt for any part size, since the object is encrypted as one continuous stream. 🔐
• The destination object only ever changes atomically, on completion: an aborted or failed upload leaves any pre-existing object of the same name untouched, and a partly-uploaded object never becomes visible (except on the few remotes with no server-side move or copy, as above).
• Multipart uploads go through the VFS like any other upload, so they show in rclone's transfer stats and obey --bwlimit.
• Backend-agnostic — it only needs the remote to support a server-side move or copy for the rename into place, which nearly all do; a remote without streaming upload support spools to local disk as above.

🍓 Limitations 🍓

• Parts must arrive in ascending, contiguous part-number order (1, 2, 3, ...). The part the stream needs next is written straight through as it arrives, so it is never buffered, whatever its size. Parts the client uploads concurrently or out of order are buffered until their turn. The memory used for this buffering is capped, per upload, by --multipart-streaming-buffer-limit (default 256M, 0 for no limit), and across all the uploads of each user (each access key) by --multipart-streaming-buffer-total (default 1G, 0 for no limit), counting each buffered part in the whole 1 MiB memory pages it occupies: a part that would take the buffer over either limit is stalled until the stream drains (or, if it is bigger than the limits, until it is the next part), so a client that uploads faster than the remote can accept sees backpressure rather than unbounded server memory use. A stalled part holds its HTTP request open, and one stalled for more than a minute is failed with a SlowDown error, which S3 clients retry. Clients whose upload concurrency times part size exceeds the limits will see these stalls and retries when the remote is slower than the client. Non-contiguous part numbers are rejected on completion. Configure the client to upload in part order, ideally with low concurrency, for the lowest memory use. ✨
• A part uploaded again before completion — usually a client being a lil drama queen and retrying after a timeout — is accepted, bestie. If the earlier copy is still buffered, it just gets replaced. And if it's already been streamed, an identical re-upload is a no-op (and if that re-upload arrives while the part is being streamed, it waits for the stream to finish first, patient queen 💅). If a part fails part way through being streamed — say the client's connection just dipped 🙈 — the client's retry of it carries on where it stopped, as long as it has the same content. What is not possible: replacing a part that has already been streamed, in whole or in part, with different content — that gets rejected. And a part that arrives in full but then gets rejected (for example because it doesn't match the Content-MD5 the client declared) has already been streamed, so the whole upload is failed and the client has to start it again 😭. Same energy for a failure in the stream to the remote itself. (The remote's own upload still retries its internal chunks, don't worry 🫶)
• Parts are serialised into one stream, so ingest from the client is effectively single-threaded. When streaming, the remote's own upload runs at the same time as the parts arriving; but with the local disk spool or the VFS cache, the upload to the remote only starts on completion. No overlap, no shortcuts ✨
• If serve s3 gets killed part-way through an upload, the temporary object (named with a leading .rclone_temp_multipart_) may just... linger 🫠 It's hidden from S3 listings, but somebody's gotta remove it manually. That somebody is you.

---

🦋 Multipart uploads and the VFS cache 🦋

With --vfs-cache-mode writes (or full), multipart uploads do not stream to the remote at all. The parts get written, in part-number order, to a temporary file in the VFS cache. On completion the file is renamed into place and uploaded by the VFS write-back — exactly like a plain object PUT. This needs no streaming upload support from the remote, which is lowkey iconic of it 💖

The rename normally happens in the cache before the upload has started, but the VFS requires the remote to support a server-side move or copy to rename files at all (and it'll use one if the temporary file has already been written back, e.g. with --vfs-write-back 0). On remotes without either, the parts are written to the cache directly under the final key instead: the upload still never touches memory, but it loses its atomicity — the in-flight upload is visible at the key, and an aborted upload cannot be abandoned once it's in the cache, so its partial data gets written back to the remote as if it were a completed object. 😳 Yes, fr fr, that's the trade.

Remotes that benefit from --vfs-cache-mode writes:

• Remotes over slow or unreliable links. A failure in a streamed upload aborts the whole multipart upload and the client must start again from the first part; a failed write-back upload is retried by the VFS (see --vfs-cache-max-age and friends) without the client being involved. Ingest from the client also runs at local disk speed rather than being throttled to the remote's pace. Hello, speed 🌈
• Workloads that read back or overwrite what they just wrote. The completed object stays in the cache, so subsequent GET/HEAD requests are served locally, and plain PUTs and multipart uploads to the same key go through the same cache entry — so the last write wins regardless of upload style. Periodt.

The trade-offs of the VFS cache (matching, bestie, we don't gatekeep 💔):

• The whole object lands on local disk, so the cache (--cache-dir) needs space for the largest objects in flight; --vfs-cache-max-size cannot evict files which are still being uploaded. Nope, no evicting the in-flight ones.
• The 200 OK for CompleteMultipartUpload means the data is safely in the local cache, not yet on the remote — the same durability the cache gives plain PUTs. If an acknowledgement must mean the data has reached the remote (for example WAL archiving), use the default --vfs-cache-mode off. Don't play yourself 🙈
• The upload to the remote only starts on completion, rather than overlapping with the parts arriving, so the data reaches the remote later than with streaming. Patience babe 🎀
• If serve s3 is killed part-way through an upload, the temporary file survives in the cache and the VFS cache recovery uploads it to the remote on restart as a temporary object (named with a leading .rclone_temp_multipart_); as with the streaming path, it is hidden from S3 listings but must be removed manually. Same mess, different day 💅

🧹 Cleaning up temporary objects 🧹

If serve s3 is killed part-way through an upload it can leave a temporary object behind, named with a leading .rclone_temp_. This whole prefix is reserved: any object whose name (the last /-separated segment of its key) starts with .rclone_temp_ is hidden from S3 listings. So like, please don't give real objects such names 👑 — an existing object with such a name disappears from listings (though it stays accessible directly by its key: only listings hide reserved names, GET, HEAD and DELETE of the exact key still work).

A temporary object never holds acknowledged data — uploads whose temporary object survived were never confirmed to the client — so old ones are safe to delete:

rclone delete --min-age 24h --include ".rclone_temp_*" remote:path

The --min-age protects uploads which are still in progress: make sure it is longer than your longest upload, especially if several serve s3 instances share the same remote. 👀

rclone v1.75 named its temporary multipart objects .rclone_multipart_upload_*; leftovers from an older server are also hidden from listings and can be cleaned up the same way. Vintage mess, still mess ✨

💀 Abandoned uploads 💀

A client which starts a multipart upload and then vanishes 🌫️ without either completing or aborting it would otherwise hold on to its resources forever. Rude.

An incomplete multipart upload which has had no activity for --multipart-expiry (default 24h) is therefore aborted and cleaned up, exactly as if the client had called AbortMultipartUpload, and a NOTICE is logged. Bye bestie 🫶

An upload with a part still being received is never expired, however slowly the part is arriving, and each completed part restarts the clock — so the expiry only needs to outlast the client's pauses between parts, not the whole upload. Very generous of us, honestly.

Late operations on an expired upload fail with NoSuchUpload, as they do on real S3 when a lifecycle rule has aborted the upload. Set --multipart-expiry 0 to keep incomplete uploads forever — but note that abandoned uploads are then never cleaned up and go on counting towards --multipart-max-uploads below, so enough of them will stop the user starting any new multipart upload until the server is restarted. That's the villain arc, don't do it 💀

Each multipart upload in progress holds server resources — for example the buffers the remote's own upload uses once the first part has arrived — so each user (each access key) can have no more than --multipart-max-uploads (default 1000, 0 for no limit) in progress at once. Starting another fails with a SlowDown error, which S3 clients retry, and a one-off NOTICE is logged. Chill for a sec, bestie 😌

🌸 Disabling streaming 🌸

If you pass --disable-multipart-streaming, multipart uploads are instead buffered in memory by the underlying S3 library: every part is held in memory and the whole object is written out in one go when the upload completes. This removes the in-order/contiguous-part restriction above, so parts can be uploaded in any order — but memory use grows with the size of the upload, so it is only suitable for small objects 😬 A one-off NOTICE is logged the first time this happens.

This flag is the only thing that makes multipart uploads buffer in memory — it is never done because of missing remote capabilities. Copy that 📝

The limits on multipart uploads above (--multipart-streaming-buffer-limit, --multipart-streaming-buffer-total and --multipart-max-uploads) do not apply to uploads buffered in memory, so don't use this flag if the server is open to clients you don't trust. Consider --vfs-cache-mode writes instead, which buffers the upload in the VFS cache on disk and takes precedence over --disable-multipart-streaming. Safer, cuter, better 🎀

🧚 Memory use 🧚

serve s3 never buffers whole objects in memory (except with --disable-multipart-streaming, above), and limits the memory each kind of request can use — so that a client, even a hostile one 😾, can't make it use unbounded memory. Queen behaviour, honestly.

• Object data. PutObject bodies and multipart parts arriving in order are streamed straight through to the remote. Parts arriving out of order are buffered, up to --multipart-streaming-buffer-limit per upload and --multipart-streaming-buffer-total per user.
• Uploads in progress. Each user can have at most --multipart-max-uploads multipart uploads in progress. An upload holds little memory until its first part arrives. After that, with --vfs-cache-mode off, it holds a --streaming-upload-cutoff sized buffer plus whatever the remote's own upload buffers — which for many remotes is up to their chunk size times their upload concurrency (for example --s3-chunk-size times --s3-upload-concurrency). Plain PutObject uploads use the same while they are in progress.
• Metadata. The metadata of at most --metadata-max-objects objects of each user is kept, each limited to 2 KB.
• Request bodies. The XML bodies of requests such as CompleteMultipartUpload and DeleteObjects are limited to 10 MiB, and DeleteObjects to 1000 keys. A browser form (POST) upload holds at most 1 MiB in memory, spooling the rest to a temporary file, and is limited to 5 GB.
• Listings. Each page of a ListObjects listing reads only the directories needed to fill it, and returns at most 1000 keys. Directory listings are cached by the VFS directory cache.

The largest of these is usually the remote's upload buffers, which can be up to --multipart-max-uploads times the buffers of one upload for each user if clients start many uploads and send part of each 😳 The limits apply to each user separately, so that one user can't stop others uploading — which means the memory use grows with the number of users. To limit it, lower --multipart-max-uploads, the remote's chunk size or upload concurrency, or set --max-buffer-memory to limit the memory used by the buffers of all uploads to remotes which use rclone's buffer pool (including s3, azureblob and b2). Buffered multipart parts come from the same pool, so if you set --max-buffer-memory make it comfortably bigger than --multipart-streaming-buffer-total times the number of users uploading at once — otherwise buffered parts can use up all the memory the remote needs to upload the parts which would free them. Circular, bestie. Naur 😭

The number of connections is not limited, so if the server is open to clients you don't trust, use --auth-key or --auth-proxy and consider putting it behind a reverse proxy which limits connections. Protect the vibes 🛡️💖

💀 Bugs (yes bestie, we're starting with the messy part)

Multipart server side copies do not work — like, they just don't. See #7454 (https://github.com/rclone/rclone/issues/7454). These take a very long time and then eventually fail, which is giving "finishing a 10 page essay at 3am and the wifi dies". 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. 🫠

For a current list of serve s3 bugs, go check the serve s3 (https://github.com/rclone/rclone/labels/serve%20s3) bug category on GitHub. Live updates, as the girlies say.

---

🚧 Limitations

• serve s3 will treat all directories in the root as buckets and ignore all files in the root. It's giving "if you're not a folder, you're not real to me" 💅
• You can use CreateBucket to create folders under the root, but you can't create empty folders under other folders not in the root. So nested empty vibes? No. None. Never.
• When using PutObject or DeleteObject, rclone will automatically create or clean up empty folders. If you don't want to clean up empty folders automatically, use --no-cleanup. Tidy queen behaviour, but optional.
• When using ListObjects, rclone treats any delimiter as /. Without a delimiter the listing is recursive: rclone walks the directory tree below the prefix, reading only as many directories as it needs to fill each page. Efficient girlie ✨
• Versioning is not currently supported. That's it. No versioning era yet. 🙈
• Metadata will only be saved in memory other than the rclone mtime metadata which will be set as the modification time of the file. The metadata of at most --metadata-max-objects objects (default 100000, 0 for no limit) of each user (each access key) is kept; after that the metadata of the user's least recently used object is forgotten. The metadata of an object is ignored once the object has been changed some other way, for example by another --auth-proxy user or directly on the backend. LRU eviction, my beloved.

---

🏷️ Object names

serve s3 stores objects as files in the backend, so object keys are mapped to file paths rather than treated as the opaque strings AWS S3 allows. Real filesystem energy, not abstract string energy.

Keys must be in canonical path form: keys that contain .. or . path segments, repeated slashes (//), or a leading or trailing slash are rejected with a 400 Bad Request (InvalidArgument) instead of being normalised, since normalising them could alias two distinct keys to the same file or resolve a key outside its bucket. This matches the behaviour of other S3 servers such as MinIO. And honestly thank god, because that would be a whole security situation.

---

✅ Supported operations

serve s3 currently supports the following operations. Periodt.

• Bucket
  • ListBuckets
  • CreateBucket
  • DeleteBucket
• Object
  • HeadObject
  • ListObjects
  • GetObject
  • PutObject
  • DeleteObject
  • DeleteObjects
  • CreateMultipartUpload
  • CompleteMultipartUpload
  • AbortMultipartUpload
  • CopyObject
  • UploadPart

Other operations will return error Unimplemented. 😭 "Not now, babe" but in HTTP.

---

🔐 Authentication

By default this will serve files without needing a login. Open door policy, bestie. Bold choice!

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.

Alternatively, you can have the reverse proxy manage authentication and use the username provided in the configured header with --user-from-header (e.g., --user-from-header=x-remote-user). Ensure the proxy is trusted and headers cannot be spoofed, as misconfiguration may lead to unauthorized access. Like, do NOT skip this part.

If either of the above authentication methods is not configured 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 girlies, we stay winning.)

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. Hot-swap those users, no restart needed. 🔥

When authentication is enabled every request must be authenticated, including HTTP OPTIONS requests, as the answer to an OPTIONS request can reveal whether a path exists. Health checks or monitoring which use unauthenticated OPTIONS requests will need to send credentials. The exception is browser CORS preflight requests when --allow-origin is set, which are answered without authentication as browsers never send credentials with them. Snitching via OPTIONS? Not on our watch.

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 localhost. You can use port :0 to let the OS choose an available port. Let the OS pick, she has 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. ⚠️

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.

--response-header can be used to set an HTTP header for all responses, will overriding existing values. The flag may be repeated to add multiple headers. Use the format Header-Name: value.

--allow-origin enables cross-origin (CORS) requests from browsers by setting the Access-Control-Allow-Origin header on every response to the origin given, e.g. --allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without needing authentication as browsers never send credentials with them. Setting this to * allows any origin which is a security risk on an authenticated server.

--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. Slash-count agnostic, as she should be.

--disable-zip may be set to disable the zipping download option. 📦🚫

---

📡 Protocol

The server supports HTTP/1.1 and HTTP/2. HTTP/2 is used automatically for TLS connections. For non-TLS connections, HTTP/2 cleartext (h2c) is supported, allowing HTTP/2 without encryption. Modern protocol behaviour, no notes.

---

🔒 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.

When TLS is configured every listener given with --addr serves TLS. An individual listener can be prefixed with http:// to serve unencrypted HTTP on that address, or with tls:// to state explicitly that it must serve TLS. Using a tls:// address without --cert and --key is an error.

--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"). And yes bestie, tls1.0 is the default. Version check accordingly.

---

🔌 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. Lazy-loading but for a whole server. Iconic.

---

🗂️ 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. <sparkle>Glow-up: cloud object ➡️ actual file vibes.</sparkle>

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.

--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)

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

Selective memory loss, but make it a feature. 💅

---

🧺 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 buffer. Boundaries, bestie.

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 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. 🧮 Do the math before you crank that number, fr fr.

💾 VFS File Caching 💾

okay bestie, buckle up, because this is the part where rclone's virtual filesystem stops pretending and starts actually keeping stuff on your disk. File caching is what makes the VFS layer act like an actual normal filesystem, and yeah you can turn it off, but you pay for that in compatibility. 💅

Like, for example, you wanna read and write to the same file at the same time? Yeah, that needs VFS caching enabled. More on that below. 👇

Heads up bestie: the VFS cache is a whole separate creature from the cache backend. You might be out here needing one of them, or the other, or honestly both. No cap.

• --cache-dir string — the 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 literally print out where your file cache is chilling. Those 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 and you pick one with --vfs-cache-mode. The higher the cache mode, the more compatible rclone gets — and the more disk space it eats. That's the trade, bestie. 🍓

Also important: files only get written back to the remote when they're closed and they haven't been touched for --vfs-write-back seconds. And if rclone gets quit or just straight up dies while holding files that haven't been uploaded yet? Don't panic — those get uploaded next time you run rclone with the same flags. 🫶

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, note that the cache can absolutely exceed those quotas for two reasons. One: it's only checked every --vfs-cache-poll-interval. Two: open files cannot be evicted from the cache. When --vfs-cache-max-size or --vfs-cache-min-free-space is exceeded, rclone tries to evict the least accessed files first — starting with the ones that haven't been accessed for the longest. This flushing strategy is efficient and more relevant files are likely to stay cached. Iconic behavior honestly. 👑

The --vfs-cache-max-age will evict files from the cache once the set time since last access has passed — it's based on access time, not on when the file was first added to the cache. The default 1 hour means it starts evicting stuff that hasn't been accessed for 1 hour. But the moment a cached file gets accessed, that 1 hour timer resets to 0 and waits another whole 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 > 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. If the remotes in use don't overlap, you're totally fine, no worries.

---

🌙 --vfs-cache-mode off 🌙

This is the default mode, and in it the cache reads directly from the remote and writes directly to the remote — nothing gets cached on disk at all. Very demure. Very minimal. 🙈

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 one is very similar to off, except that files opened for read AND write will be buffered to disk. So files opened for write become a lot more compatible, while using the absolute minimum of 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 — but write only and read/write files get buffered to disk first. 🦋

This mode should support all normal file system operations. Slay.

And if an upload fails, it gets retried at exponentially increasing intervals up to 1 minute. It's giving persistence. 🔥

---

👑 --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 as well. Every single bit. 💅

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 ever reads the starts of each file, then rclone only buffers 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's been downloaded actually present in them. Sneaky! 🧚

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 that --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. You've been 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. Annoying, but that's the tea. ☕

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. This 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, 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. Which means that rather than requesting the whole entire file, rclone reads the chunk you specified. For some remotes this reduces the used download quota, because it only requests the chunks from the remote that are actually read — at the cost of an increased number of requests. Trade-offs, bestie. 💅

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. It's giving exponential. 📈

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 entirely.

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. No doubling here, we're just parallel now. 🏃‍♀️

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 above, bestie. 👆

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. Every. Single. Time. 💀

• --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. Sorry bestie, them's the rules. 💅

• --transfers int — how many file transfers are allowed to run in parallel at the same time (default 4). A lil squad of four, working the room. 💅

---

🦋 Symlinks 🦋

Okay so by default the VFS is like, not symlink-friendly at all. Zero symlink energy. But you can absolutely switch it on with either of these two flags:

• --links — translate symlinks to/from regular files using a .rclonelink extension.
• --vfs-links — same translation, same .rclonelink extension, but scoped to the VFS.

Here's the tea 🍓: most cloud storage systems do not support symlinks directly, like at all. So rclone just... stores the symlink as a totally normal file with a special extension. So a file that shows up as a symlink called link-to-file.txt is actually sitting on your cloud storage as link-to-file.txt.rclonelink, and the contents of that file are the path to wherever the symlink points. Iconic workaround, no notes.

Important distinction bestie: --links turns symlink translation on globally inside rclone — that includes every backend that even knows what the concept is (the local backend, for example 👀). --vfs-links is the chill one: it only does it for the VFS layer.

This scheme is compatible with the one the local backend uses with the --local-links flag (https://rclone.org/local/#symlinks-junction-points).

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. Like, look at 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 it may be for other commands.

Also, there's an outstanding issue with symlink support, issue #8245 (https://github.com/rclone/rclone/issues/8245), where duplicate files get created when symlinks are moved into directories where there's already a file of the same name (or the other way around). So like... be aware. 💀

---

💜 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. No shortcuts, no lowercase chaos.

File systems on modern Windows are case-insensitive but case-preserving: existing files can be opened using any case, but the exact case that was used to create the file is preserved and available for programs to query. What is not allowed is two files in the same directory differing 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 if it appears without a value on the command line), rclone may perform a "fixup" — and here's what that means, bestie:

You may specify a file name to open/delete/rename/etc with a case different from 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 disk is used. However, if a file name with exactly the same name is not found but 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 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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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 lets you hide those duplicates. Now, this comes with a performance tradeoff, because rclone will have to scan the entire directory for duplicates when listing a directory. For that reason, it's recommended to leave this disabled if you don't need it. But 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 — however, editing either version will actually result in only the NFD version getting edited under the hood. Sneaky. 😭 --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 just 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. So if you need that info available when you run df on the filesystem, pass the flag --vfs-used-is-size to rclone. With that 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. DIY, but make it storage. 🫶

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.

---

🌸 VFS Metadata 🌸

If you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. These files will not appear in the directory listing, but they can be stat-ed and opened — and once they have been, they will appear in directory listings until the directory cache expires.

Note that some backends won't create metadata unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
    "atime": "2025-03-04T17:34:22.317069787Z",
    "btime": "2025-03-03T16:03:37.708253808Z",
    "gid": "1000",
    "mode": "100664",
    "mtime": "2025-03-03T16:03:39.640238323Z",
    "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

If the file has no metadata it will be returned as {} and if there is an error reading the metadata the error will be returned as {"error":"error string"}.

---

👑 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 uses a simple JSON based protocol, with input on STDIN and output on STDOUT. Very demure, very standard-streams.

PLEASE NOTE: --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 (https://github.com/rclone/rclone/blob/master/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 generated config must have this extra parameter:

• _root — root to use for the backend

And it may have these parameters:

• _obscure — comma separated strings for parameters to obscure
• _secret_access_key — the secret for S3 access key auth (see below)

If password authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{
  "user": "me",
  "pass": "mypassword",
  "client_ip": "192.168.1.1"
}

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",
  "client_ip": "192.168.1.1"
}

If the client authenticated with an S3 access key (rclone serve s3), the client never sends its secret, only a signature made with it, so the input contains just the access key ID as the user, with no pass or public_key:

{
  "user": "AKIAIOSFODNN7EXAMPLE",
  "client_ip": "192.168.1.1"
}

In this case the program must look up the secret access key for that access key ID and return it in the _secret_access_key field of the output. Rclone then uses that secret to verify the signature on the request, refusing the request if it does not match. What this means is that the proxy program is the source of truth for both the credentials and the backend they map to. If the program does not return _secret_access_key, or returns it empty, the request is refused. Bye. 🚫

The program's answer for an access key ID is cached (see below), but is checked with the program again after 5 minutes even if the access key ID is in constant use, so revoking an access key ID in the program takes effect within 5 minutes. A rotated secret takes effect on the first request signed with it. ⭐

The client_ip key holds the IP address the client connected from, without a port number. It can be used to restrict logins to certain networks, or to log authentication attempts centrally. It is omitted if the client has no IP address — for example when connecting over a unix socket. Note that if rclone is behind a reverse proxy, this will be the address of the reverse proxy and not the original client. iykyk.

And as an example return this on STDOUT

{
  "type": "sftp",
  "_root": "",
  "_obscure": "pass",
  "user": "me",
  "pass": "mypassword",
  "host": "sftp.example.com"
}

okay bestie so this is the vibe: an SFTP backend gets created on the fly for whatever user and pass/public_key came back in the output, pointed at the host you handed over. 💖 and fr fr, notice _obscure is set to pass — that means rclone will obscure the pass parameter before it builds the backend, and that is required for sftp backends. not optional, not a suggestion, it's the rules. ✨

and the program can do literally anything it wants with the user it was given. want to proxy out to a whole swarm of different sftp backends? make the user be user@example.com, then in your output set host to example.com and user to user. slay. 🎀 though for security you'd probably want to restrict host to a limited list. lowkey important. 👀

there's an internal cache of backends and it's keyed on the user, a hash of the pass or public_key, and the client_ip. so if a user's password or public-key changes, or the client connects from a new IP address, or the proxy returns different config parameters (like a rotated api_key) — a fresh backend gets created on the next request instead of the cached one being reused. no stale vibes allowed. 💅

and the whole point of this: you can use it to build general purpose proxies to any kind of backend that rclone supports. main character energy, honestly. 👑

rclone serve s3 remote:path [flags]

---

✨ Options ✨

• --addr stringArray — IPaddress:Port or :Port 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 — TLS PEM key (concatenation of certificate and CA certificate)
• --client-ca string — Client certificate authority to verify clients with
• --dir-cache-time Duration — Time to cache directory entries for (default 5m0s)
• --dir-perms FileMode — Directory permissions (default 777)
• --disable-multipart-streaming — Buffer multipart uploads in memory instead of streaming them to the backend
• --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)
• --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 — TLS PEM Private key
• --link-perms FileMode — Link permissions (default 666)
• --max-header-bytes int — Maximum size of request header (default 4096)
• --metadata-max-objects int — Maximum number of objects of a user whose metadata is kept in memory, 0 for unlimited (default 100000)
• --min-tls-version string — Minimum TLS version that is acceptable (default "tls1.0")
• --multipart-expiry Duration — Abort incomplete multipart uploads idle for longer than this, 0 to keep forever (default 1d)
• --multipart-max-uploads int — Maximum number of streamed multipart uploads a user can have in progress at once, 0 for unlimited (default 1000)
• --multipart-streaming-buffer-limit SizeSuffix — Maximum memory buffered per streamed multipart upload for parts arriving out of order, 0 for unlimited (default 256Mi)
• --multipart-streaming-buffer-total SizeSuffix — Maximum memory buffered by all the streamed multipart uploads of a user for parts arriving out of order, 0 for unlimited (default 1Gi)
• --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
• --response-header stringArray — Set HTTP header for all responses, overriding existing values
• --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
• --user-from-header string — User name from a defined HTTP header
• --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-handle-caching Duration — Time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — Translate symlinks to/from regular files with a .rclonelink extension for the VFS
• --vfs-metadata-extension string — Set the extension to read metadata from
• --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 (https://rclone.org/flags/) for global options not listed here.

🔍 Filter Options 🔍

Flags for filtering directory listings

• --delete-excluded — delete files on dest that got excluded from the sync 💀 like, gone gone, no takebacks.
• --exclude stringArray — exclude files matching this pattern 🙅‍♀️
• --exclude-from stringArray — read your file exclude patterns from a file instead (use - to read from stdin) 📄
• --exclude-if-present stringArray — if a filename like this is present, exclude the whole directory 🚫
• --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 literally zero processing of the lines, raw as it gets (use - to read from stdin)
• --files-from0 stringArray — read the list of source-file names from a file using NUL as the separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --ignore-case — ignore case in filters, it's giving case insensitive 💅
• --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 suffix ms|s|m|h|d|w|M|y (default off)
• --max-depth int — if set, it 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 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 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 (https://rclone.org/commands/rclone_serve/) — Serve a remote over a protocol.

---

🦋 rclone serve sftp 💜

Serve the remote over SFTP.

🪄 Synopsis

Run an SFTP server to serve a remote over SFTP. Bestie, you can hook it up to an SFTP client, or you can just make a remote of type sftp and use it with that. Both are iconic, pick your fighter 🎀

You can use the filter flags (e.g. --include, --exclude) to control what is served.

The server will respond to a small number of shell commands, mainly md5sum, sha1sum and df, which enable it to provide support for checksums and the about feature when accessed from an sftp remote. Like, it's not a whole shell, it's just those lil guys 🐣

Note that 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 (https://rclone.org/sftp/#sftp-chunk-size) option on an sftp remote. Don't do it, it will not slay 🙈

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.

You must provide some means of authentication, either with --user/--pass, an authorized keys file (specify location with --authorized-keys — the default is the same as ssh), an --auth-proxy, or set the --no-auth flag for no authentication 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) in the "serve-sftp" directory. So cute, it remembers 🔑

By default the server binds to localhost:2022 — if you want it to be reachable externally then supply --addr :2022 for example.

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 <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 2222 -- rclone serve sftp :local:vfs/

This will socket-activate rclone on the first connection to port 2222 over TCP. Vibe check passed ✨

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.

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. It's chaos, honestly 💀

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. Choose wisely, bestie 🫶

🗂️ 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.

• --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)

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. Every file keeps its own lil stash 🍓

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 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 time ✨

💾 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. They're different girlies, don't mix them up 💅

• --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 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, bestie, always 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. It literally remembers for you 🫶

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 👑

---

The <code>--vfs-cache-max-age</code> evicts files from the cache once the set time has passed since last access — bestie, it's judging by access time, not by when the file first got added to the cache, ok? The default is 1 hour, so anything you haven't touched in an hour starts getting yeeted out of the cache. Touch a cached file and that 1 hour timer resets to 0 and waits another whole hour before it evicts again ✨. Write the duration in standard notation: s, m, h, d, w 💅.

🚨 GIRL. LISTEN. Do not run two copies of rclone using the same VFS cache with the same remotes — or even overlapping ones — if you're running --vfs-cache-mode > off. That can literally corrupt your data, and not in a cute way 😭. The workaround: give each rclone its own cache hierarchy with --cache-dir. If the remotes in play don't overlap, you don't have to worry about any of this 🫶.

---

--vfs-cache-mode off

This is the default, and honestly it's giving no thoughts, head empty. The cache reads straight from the remote and writes straight to the remote — nothing gets cached on disk at all. 🍓

Which means some operations are just... 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

Basically off's cousin, same vibe, tiny difference: files opened for read AND write get buffered to disk. So files opened for write are a lot more compatible, and it uses the absolute bare minimum of disk space ✨.

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

Now we're cooking 🎀. Files opened read-only 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 gets retried at exponentially increasing intervals, up to 1 minute. Growth mindset fr fr 🔥.

--vfs-cache-mode full

The main character of cache modes 👑. Here 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 are sparse files, and rclone keeps track of exactly which bits of each file it's downloaded 🧠.

So if an app only reads the starts of each file, rclone only buffers the start of the file. Those files will look full-size in the cache, but bestie they're sparse — only the data that's actually been downloaded is literally present in them ✨.

This mode should support all normal file system operations, and it's 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 gets buffered in memory, whereas the --vfs-read-ahead gets buffered on disk.

When you're using this mode, the move is: 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. In particular, FAT/exFAT do not. Rclone will perform very badly if the cache directory lives on a filesystem that doesn't support sparse files, and it will log an ERROR message if it detects one. So check before you commit, babe 😭.

---

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 those are 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. Like, the audacity.

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.

So if you use the --vfs-fast-fingerprint flag, rclone won't include those slow operations in the fingerprint. It makes the fingerprinting less accurate but much faster, and it improves the opening time of cached files 🔥.

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

💀 Heads up: 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. So like... pick a lane.

---

VFS Chunked Reading

When rclone reads files from a remote, it reads them in chunks 🎀. So instead of requesting the whole entire file, rclone reads the chunk it specified. This can reduce the used download quota on some remotes by only requesting the chunks that are actually read from the remote — at the cost of an increased number of requests. Trade-offs, bestie ✨.

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. Let's get into it 💅.

--vfs-read-chunk-streams == 0

Rclone starts by reading a chunk of size --vfs-read-chunk-size, and then doubles the size for each read 📈. When --vfs-read-chunk-size-limit is specified and is greater than --vfs-read-chunk-size, the chunk size for each open file gets doubled only until it reaches that specified value. If the value is "off" — which is the default — the limit is disabled and the chunk size will grow indefinitely. Iconic, honestly.

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 entirely.

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 stays 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, because these depend on the backend in use and the latency to that backend. Science, babe 🧪.

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 above.

In particular, S3 and Swift benefit hugely from the --no-modtime flag (or --use-server-modtime for a slightly different effect) — because every single read of the modification time takes a whole 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 gets 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 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 a value of 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, so don't bother, bestie.)

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

---

Symlinks

By default, the VFS does not support symlinks 🥲. But it can be enabled 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 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 — 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 the one used by the local backend with the --local-links flag: https://rclone.org/local/#symlinks-junction-points.

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 it may be for other commands.

💀 Also note there's an outstanding issue with symlink support — issue #8245 (https://github.com/rclone/rclone/issues/8245) — with 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. No 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 🔍. And it is not allowed for two files in the same directory to differ only by case. The vibes are strict but fair 🎀.

So like, usually file systems on macOS are case-insensitive. You can make them case-sensitive, but bestie, that is not the default, okay?

The --vfs-case-insensitive VFS flag is what controls how rclone handles these two situations. If its value is "false", rclone just passes file names to the remote as-is, like a good little messenger. If the flag is "true" (or shows up without a value on the command line), rclone may do a "fixup", which we're about to explain 💅

So picture this: you ask to open/delete/rename/etc. a file name whose case doesn't match what's actually stored on the remote. If some 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 — plot twist — if a name that's exactly the same isn't found, and instead there's a name differing only by case, rclone will transparently "fixup" the name for you. This fixup only happens when you request an existing file. And the case sensitivity of file names that rclone creates brand new? That's controlled by the underlying remote, not by this flag, periodt.

Heads up: the case sensitivity of the OS rclone is running on (the target) can totally differ from the case sensitivity of the file system rclone is presenting (the source). The flag is what decides whether that "fixup" gets performed so the target gets what it wants.

If the flag isn't on the command line at all, its default depends on the OS rclone runs on: "true" on Windows and macOS, "false" everywhere else. And if you provide the flag with no value? Then it's "true". Simple as 🎀

The --no-unicode-normalization flag controls whether a similar "fixup" happens for filenames that differ but are canonically equivalent (https://en.wikipedia.org/wiki/Unicode_equivalence) as far as unicode is concerned. Unicode normalization is lowkey a lifesaver for macOS users, since macOS prefers form NFD instead of the NFC that basically everyone else uses. So it is highly recommended to keep the default of false on macOS, to dodge encoding compatibility issues entirely 🙈

In the (probably unlikely, ngl) event that a directory ends up with multiple duplicate filenames after applying case and unicode normalization, the --vfs-block-norm-dupes flag lets you hide those duplicates. The tradeoff? Performance, bestie — rclone now has to scan the entire directory hunting for duplicates every single time it lists that directory. So yeah, it's recommended to leave this disabled unless you actually need it. However, macOS users might wanna consider it, because otherwise: if a remote directory contains both the NFC and the NFD version of the same filename, a genuinely odd situation occurs. Both versions of the file will be visible in the mount, and both will appear editable, but editing either version actually results in only the NFD version getting edited under the hood 😭 --vfs-block-norm-dupes prevents this whole confusing mess by detecting the scenario, hiding the duplicates, and logging an error, kinda like how rclone sync handles it. Iconic behavior, honestly.

🔧 VFS Disk Options 🔧

This flag lets you manually set the statistics all about the filing system. Super useful when those stats just can't be read correctly automatically — which happens, and it's not your fault.

--vfs-disk-space-total-size    Manually set the total disk space size (example: 256G, default: -1)

📊 Alternate report of used bytes 📊

Some backends — most famously S3 — straight up don't report the amount of bytes used. If you need that info available when running df on the filesystem, pass the flag --vfs-used-is-size to rclone. With that flag set, instead of relying on the backend to tell you, rclone scans the whole remote kinda like rclone size does and computes the total used space itself ✨

WARNING: unlike rclone size, this flag ignores filters so the result is accurate. But it is very inefficient and may cost you lots of API calls, which means extra charges 💀 Treat it as a last resort and only use it with caching.

🏷️ VFS Metadata 🏷️

If you use the --vfs-metadata-extension flag, you can get the VFS to expose files containing the metadata (https://rclone.org/docs/#metadata) as a JSON blob. These files will not show up in the directory listing, but they can be stat-ed and opened — and once they have been, they'll appear in directory listings until the directory cache expires. Sneaky little things 🦋

Note that some backends won't create metadata at all unless you pass in the --metadata flag.

For example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

If the file has no metadata it will be returned as {}, and if there's an error reading the metadata, the error gets returned as {"error":"error string"}. No cap.

🔐 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 are then used to authenticate incoming requests. It runs on 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. Choose one, bestie.

There's an example program bin/test_proxy.py (https://github.com/rclone/rclone/blob/master/bin/test_proxy.py) sitting in the rclone source code if you wanna peek 🌸

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 — making a complete config is the proxy program's job, not rclone's.

This config generated must have this extra parameter:

• _root - root to use for the backend

And it may have these parameters:

• _obscure - comma separated strings for parameters to obscure
• _secret_access_key - the secret for S3 access key auth (see below)

If password authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{
  "user": "me",
  "pass": "mypassword",
  "client_ip": "192.168.1.1"
}

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",
  "client_ip": "192.168.1.1"
}

If the client authenticated with an S3 access key (rclone serve s3), the client never sends its secret — only a signature made with it — so the input contains just the access key ID as the user with no pass or public_key:

{
  "user": "AKIAIOSFODNN7EXAMPLE",
  "client_ip": "192.168.1.1"
}

In this case the program must look up the secret access key for that access key ID and return it in the _secret_access_key field of the output. Rclone then uses that secret to verify the signature on the request, and refuses the request if it doesn't match. This means the proxy program is the source of truth for both the credentials and the backend they map to. If the program doesn't return _secret_access_key, or returns it empty, the request is refused. Period.

The program's answer for an access key ID is cached (see below) but gets checked with the program again after 5 minutes even if the access key ID is in constant use — so revoking an access key ID in the program takes effect within 5 minutes. A rotated secret takes effect on the first request signed with it 🔥

The client_ip key holds the IP address the client connected from, without a port number. It can be used to restrict logins to certain networks, or to log authentication attempts centrally. It's omitted if the client has no IP address — for example when connecting over a unix socket. Note that if rclone is behind a reverse proxy, this will be the address of the reverse proxy and not the original client. Just so you know 💅

And as an example, return this on STDOUT:

{
  "type": "sftp",
  "_root": "",
  "_obscure": "pass",
  "user": "me",
  "pass": "mypassword",
  "host": "sftp.example.com"
}

This would mean an SFTP backend gets 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, iykyk).

The program can manipulate the supplied user in any way it wants — 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 wanna restrict the host to a limited list. Do that. Please 🫶

An internal cache of backends is keyed on the user, a hash of the pass or public_key, and the client_ip. This means that if a user's password or public-key changes, the client connects from a new IP address, or the proxy returns different config parameters (eg a rotated api_key), a fresh backend gets created on the next request rather than the cached one being reused. Slay, cache invalidation. ✨

This can be used to build general purpose proxies to any kind of backend that rclone supports 👑

rclone serve sftp remote:path [flags]

• --addr string — the IPaddress:Port (or just :Port) the server binds to (default "localhost:2022").
• --auth-proxy string — a program you hand the auth to, and it builds the backend for you.
• --authorized-keys string — the authorized keys file (default "~/.ssh/authorized_keys").
• --dir-cache-time Duration — how long directory entries get cached (default 5m0s).
• --dir-perms FileMode — permissions for directories (default 777).
• --file-perms FileMode — permissions for files (default 666).
• --gid uint32 — overrides the gid field the filesystem sets (windows said no, not supported there) (default 1000).
• -h, --help — help for sftp, bestie, it's right there.
• --key stringArray — SSH private host key file, and yes it can be multi-valued; leave it blank and rclone just auto generates one for you ✨
• --link-perms FileMode — link permissions (default 666).
• --no-auth — if you set this, connections with literally no authentication are allowed 🫣
• --no-checksum — don't compare checksums on up/download.
• --no-modtime — don't read or write the modification time (can speed things up, lowkey).
• --no-seek — don't allow seeking in files.
• --pass string — the password for authentication.
• --poll-interval Duration — how long to wait between polling for changes; must be smaller than --dir-cache-time and only works on supported remotes (set 0 to disable) (default 1m0s).
• --read-only — read-only access only, no writing, periodt.
• --stdio — run an sftp server on stdin/stdout.
• --uid uint32 — overrides the uid field the filesystem sets (not supported on Windows) (default 1000).
• --umask FileMode — overrides the permission bits the filesystem sets (not supported on Windows) (default 002).
• --user string — the user name for authentication.
• --vfs-block-norm-dupes — if duplicate filenames end up in the same directory (after normalization), log an error and hide the duplicates (heads up: this may have a performance cost).
• --vfs-cache-max-age Duration — max time since last access for objects sitting 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 that holds the cache (default off).
• --vfs-cache-mode CacheMode — the cache mode, one of off|minimal|writes|full (default off).
• --vfs-cache-poll-interval Duration — how often to poll the cache for stale objects (default 1m0s).
• --vfs-case-insensitive — if a filename isn't found, go find a case-insensitive match instead.
• --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-handle-caching Duration — how long to keep the file handle and downloaders alive after the last close (default 5s).
• --vfs-links — translate symlinks to/from regular files with a .rclonelink extension, for the VFS.
• --vfs-metadata-extension string — set the extension to read metadata from.
• --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 this is greater than --vfs-read-chunk-size, the chunk size doubles after each chunk read until the limit is hit ('off' means unlimited) (default off).
• --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 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 — how long to write back files after last use when using cache (default 5s).
• --vfs-write-wait Duration — how long to wait for an in-sequence write before throwing an error (default 1s).

The options shared with other commands are described right up next. And if you want the global options that aren't listed here, go peek at the global flags page (<https://rclone.org/flags/>).

---

🌸 Filter Options 🌸

Flags for filtering your directory listings, aka the "no thank you, not that file" toolkit:

• --delete-excluded — delete files on dest that were excluded from sync.
• --exclude stringArray — exclude files matching a pattern.
• --exclude-from stringArray — read exclude patterns from a file (use - to read from stdin).
• --exclude-if-present stringArray — exclude directories if this 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 the lines (use - to read from stdin).
• --files-from0 stringArray — read a list of source-file names from a file using NUL as the separator (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).
• --hash-filter string — partition filenames by hash k/n or randomly @/n.
• --ignore-case — ignore case in filters (case insensitive, obviously 💅).
• --include stringArray — include files matching a pattern.
• --include-from stringArray — read 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 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 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 (<https://rclone.org/commands/rclone_serve/>) — Serve a remote over a protocol.

---

🌈 rclone serve webdav 🌈

Serve remote:path over WebDAV. Yes bestie, WebDAV, it's giving ancient-but-iconic and we love her for it.

✨ Synopsis ✨

Run a basic WebDAV server to serve a remote over HTTP via the WebDAV protocol. You can view it with a WebDAV client, through a web browser, or you can make a remote of type WebDAV to read and write it.

🎀 WebDAV options 🎀

--etag-hash

This controls 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 picks the first supported hash on the backend, or you can use a named hash like "MD5" or "SHA-1". Run the hashsum command (<https://rclone.org/commands/rclone_hashsum/>) to see the whole list. Go off.

Gzip compression

The server will compress certain response bodies (text and XML, including WebDAV PROPFIND responses) using gzip whenever the client advertises gzip support via the Accept-Encoding: gzip request header. Fewer bytes over the wire, everybody wins 💖

Access WebDAV on Windows

A WebDAV shared folder can be mapped as a drive on Windows, but the default settings are actively working against you, bestie. Windows will fail to connect to the server using insecure Basic authentication. It won't even show you a login dialog. Windows requires an SSL / HTTPS connection to be used with Basic. If you try to connect via the Add Network Location Wizard you'll get this error: "The folder you entered does not appear to be valid. Please choose another". That's not a vibe.

But plot twist — you can still connect if you set the following registry key on the client machine: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel 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 you need to, increase the FileSizeLimitInBytes to a higher value too. Then navigate to the Services interface, and restart the WebClient service. That's the whole ritual. 🕯️

Access Office applications on WebDAV

Navigate to the following registry: HKEY_CURRENT_USER\Software\Microsoft\Office\[14.0/15.0/16.0]\Common\Internet. 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>

Serving over a unix socket

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 — that's expected to be handled by the permissions on the socket. iykyk 🔐

Symlinks / Junction points

The webdav protocol does not support symlinks or junction points, and by default rclone will skip them completely.

You can use -L to get rclone to follow symlinks, or you can use --local-links to make rclone show .rclonelink files in place of the symlinks.

NB Do not use --links, because as of v1.69 it applies to the VFS layer too. Use --local-links, which only applies to the local backend. No cap, save yourself the confusion. 💀

Server options

Okay bestie, this is where you decide exactly how your server shows up to the world 💅

• --addr — tells rclone which IP address and port to listen on. Like --addr 1.2.3.4:8000, or --addr :8080 if you wanna listen on all the IPs. Default behaviour? It only listens on localhost, so it's ✨cozy✨ by default. You can use port :0 to let the OS pick whatever port is free — it's giving "you choose, I trust you".

If you set --addr to listen on a public or LAN accessible IP address then using Authentication is advised — peep the next section for the deets, okay? 🫶

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 (more on that below) can also be used to accomplish the same thing. Versatile queen 👑

• --server-read-timeout and --server-write-timeout — control the timeouts on the server. Heads up tho: this is the total time for a transfer, not per-chunk. Clock starts, clock ends, no takebacks ⏳
• --max-header-bytes — controls the maximum number of bytes the server will accept in the HTTP header.
• --response-header — sets an HTTP header for all responses, will overriding existing values. The flag may be repeated to add multiple headers. Use the format Header-Name: value.
• --allow-origin — enables cross-origin (CORS) requests from browsers by setting the Access-Control-Allow-Origin header on every response to the origin given, e.g. --allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without needing authentication as browsers never send credentials with them. Setting this to * allows any origin which is a security risk on an authenticated server. ⚠️

Real talk: * on an authenticated server is a security risk. Not me warning you twice, but also not me not warning you twice.

• --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 energy, three fits 🎀
• --disable-zip — may be set to disable the zipping download option.

---

Protocol

The server supports HTTP/1.1 and HTTP/2. HTTP/2 is used automatically for TLS connections. For non-TLS connections, HTTP/2 cleartext (h2c) is supported, allowing HTTP/2 without encryption. No TLS, still fancy. We love a flexible icon 🌈

---

TLS (SSL)

By default this will serve over http. If you want you can serve over https — you'll 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.

When TLS is configured every listener given with --addr serves TLS. An individual listener can be prefixed with http:// to serve unencrypted HTTP on that address, or with tls:// to state explicitly that it must serve TLS. Using a tls:// address without --cert and --key is an error. 🚨

• --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.
• --client-ca — if setting it, it should be set to the path of a file with PEM encoded client certificate authority certificates.
• --min-tls-version — is the 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, it just hands the whole address conversation to the service manager. Not me showing up to a party and letting someone else pick the playlist 🎧

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. Literally it just waits for someone to knock and then ✨materializes✨.

---

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. Possible values: namedirfirst, name, size, time (default namedirfirst).
• .Order — The current ordering used. This is changeable via '?order=' parameter. Possible values: asc, desc (default asc).
• .Query — Currently unused.
• .Breadcrumb — Allows for creating a relative navigation.
  • .Link — The link of the Text relative to the root.
  • .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. Chill! But maybe too chill depending on where you're serving 👀

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.

Alternatively, you can have the reverse proxy manage authentication and use the username provided in the configured header with --user-from-header (e.g., --user-from-header=x-remote-user). Ensure the proxy is trusted and headers cannot be spoofed, as misconfiguration may lead to unauthorized access. Do not skip the trusted-proxy part, bestie, I'm begging.

If either of the above authentication methods is not configured 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, no restart, so slay ✨

When authentication is enabled every request must be authenticated, including HTTP OPTIONS requests, as the answer to an OPTIONS request can reveal whether a path exists. Health checks or monitoring which use unauthenticated OPTIONS requests will need to send credentials. The exception is browser CORS preflight requests when --allow-origin is set, which are answered without authentication as browsers never send credentials with them.

• --realm — use it to set the authentication realm.
• --salt — use it 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. It's giving ✨illusion✨, but a useful one.

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. Metadata only, no data hoarding 🙈

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. So either it shows up instantly or it nukes the cache and starts over — either way you're not staring at stale listings, periodt 💅

--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)

okay so lowkey the sad part: if you go change stuff directly on the cloud (like through the web UI, or from a whole different rclone copy 💀), your rclone won't even notice until the directory cache expires — unless your backend does polling, in which case it catches the vibe within the polling interval. iykyk.

But bestie, here's the cheat code: send a SIGHUP signal to rclone and it flushes all the directory caches, no matter how stale they are. Assuming you've only got one rclone running (main character behavior, we love that), reset the cache like:

kill -SIGHUP $(pidof rclone)

And if you've got rclone set up with a remote control, you can use rclone rc to nuke the whole directory cache:

rclone rc vfs/forget

Or, if you're being surgical about it, individual files or directories:

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

---

✨ VFS File Buffering ✨

The --buffer-size flag is the amount of memory rclone uses to buffer data in advance. 🧠

Every open file will try to keep that amount of data in memory at all times. The buffered data is bound to one open file — it does not get shared, so no stealing from your bestie's buffer. 🙅‍♀️

This flag is an upper limit for how much memory each open file can use. The buffer only actually eats memory for data that's been downloaded but not read yet. If the buffer is empty, it barely uses anything. slay.

But watch out: the maximum memory rclone can burn on buffering can be up to --buffer-size * open files. yes, multiply it. do the math. 🔥

✨ VFS File Caching ✨

These flags control all the VFS file caching options. File caching is what makes the VFS layer act like a normal file system — it's giving real-filesystem energy. It can be disabled, but that costs you some compatibility.

Like, for example, you'll need VFS caching enabled if you want to read and write to a file at the same time. See below for the deets. 👇

small PSA: the VFS cache is totally separate from the cache backend. you might need one, the other, or literally both. no cap.

• --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 where the file cache lives. 📍 The files are stored 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 your disk space. tradeoffs, bestie. 💅

Also important: files are only written back to the remote when they're closed and if they haven't been accessed for --vfs-write-back seconds. If rclone quits or straight-up dies with files that haven't uploaded yet 😭, those will get uploaded the next time rclone runs with the same flags. it remembers. iconic.

If you're using --vfs-cache-max-size or --vfs-cache-min-free-space, heads up — the cache can actually exceed those quotas, for two reasons:

1. Because it's only checked every --vfs-cache-poll-interval.
2. Because open files cannot be evicted from the cache. (they're busy!!)

When --vfs-cache-max-size or --vfs-cache-min-free-space is exceeded, rclone tries to evict the least accessed files first. It starts with the files that haven't been accessed for the longest. This flushing strategy is efficient, and it means the more relevant files are likely to stay cached. ✨

The --vfs-cache-max-age will evict files from the cache after the set time since last access has passed. key detail: it's based on access time, not on when the file was first added to the cache. The default value of 1 hour starts evicting files that haven't been accessed for 1 hour. And when a cached file gets 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 > off. This can potentially cause data corruption. for real. You can work around it by giving each rclone its own cache hierarchy with --cache-dir. You don't gotta worry about any of this if your remotes don't overlap.

--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. 🫥

This means some operations are just… 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. That means files opened for write are way more compatible, but it uses the minimal amount of 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, 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 will be retried at exponentially increasing intervals up to 1 minute. we love a resilient queen.

--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 too. the full package. 💖

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 sparse files with only the downloaded data actually present in them. the illusion. ✨

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 that doesn't support sparse files, and it will log an ERROR message if one is detected. you've been 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). 🙈

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 those slow operations in the fingerprint. This makes fingerprinting less accurate but much faster, and it'll improve the opening time of cached files. speed. 🏎️

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. it's giving "start over". 😭

✨ VFS Chunked Reading ✨

When rclone reads files from a remote, it reads them in chunks. That means instead of requesting the whole file, rclone reads the specified chunk. This can reduce your used download quota for some remotes, because it only requests the chunks that are actually read — at the cost of an increased number of requests. worth it? depends. 🦋

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 is greater than --vfs-read-chunk-size, the chunk size for each open file gets 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. the math is mathing. 🔥

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

The chunks will not be buffered in memory. nope, not even a little.

--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. it's giving main character energy. 👑

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. tune it, bestie. 💅

okay so for high-performance object stores (think AWS S3, the girlies with real speed) a lowkey reasonable place to start is --vfs-read-chunk-streams 16 and --vfs-read-chunk-size 4M. and ngl, in testing with AWS S3 the performance scaled roughly as the --vfs-read-chunk-streams setting went. it's giving linear, bestie. 📈

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

---

✨ VFS Performance ✨

these flags are here to enable/disable features of the VFS for performance reasons or just... 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 every single read of the modification time takes a transaction. literally every one. that's so many transactions 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 gets delivered reads or writes out of order 🙈 and instead of seeking, rclone will wait a short time for the in-sequence read or write to come in. these flags only come into effect when you're not using an on disk cache file, so no cap:

• --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 (that's --vfs-cache-mode with the value writes or full), the global flag --transfers can be set to adjust the number of parallel uploads of modified files from the cache. and fyi the related global flag --checkers has no effect on the VFS, so don't even try it 🫶

• --transfers int — number of file transfers to run in parallel (default 4)

---

🦋 Symlinks 🦋

by default the VFS does not support symlinks. that's just the vibe. 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 do not support symlinks directly (rude of them honestly), rclone stores the symlink as a normal file with a special extension. so a file that 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 — 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 the one used by the local backend with the --local-links flag (https://rclone.org/local/#symlinks-junction-points).

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. so like... proceed with caution bestie 🙈

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 it may be for other commands. 👀

note that there is an outstanding issue with symlink support — issue #8245 (https://github.com/rclone/rclone/issues/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. strict. no notes.

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. but it is not allowed for two files in the same directory to differ only by case. okay so basically windows remembers your capitalization but doesn't care about it when you're searching 🔍

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 (https://en.wikipedia.org/wiki/Unicode_equivalence) 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 alone on mac 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 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. 💀 so yeah, mac girlies, maybe turn it on.

---

🎀 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. manual mode activated 💅

• --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. 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. it's doing the math, bestie 🧮

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.

---

💜 VFS Metadata 💜

if you use the --vfs-metadata-extension flag you can get the VFS to expose files which contain the metadata (https://rclone.org/docs/#metadata) as a JSON blob. these files will not appear in the directory listing, but can be stat-ed and opened and once they have been they will appear in directory listings until the directory cache expires. sneaky metadata files, living their little double life 🧚

note that some backends won't create metadata unless you pass in the --metadata flag.

for example, using rclone mount with --metadata --vfs-metadata-extension .metadata we get:

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

if the file has no metadata it will be returned as {} and if there is an error reading the metadata the error will be returned as {"error":"error string"}.

---

🔥 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. main character energy, honestly. this uses a simple JSON based protocol with input on STDIN and output on STDOUT.

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 (https://github.com/rclone/rclone/blob/master/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. no shortcuts, bestie 🫶

this config generated must have this extra parameter

• _root - root to use for the backend

and it may have these parameters

• _obscure - comma separated strings for parameters to obscure
• _secret_access_key - the secret for S3 access key auth (see below)

if password authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

{
  "user": "me",
  "pass": "mypassword",
  "client_ip": "192.168.1.1"
}

if public-key authentication was used by the client, input to the proxy process (on STDIN) would look similar to this:

...and it's giving very specific bestie. Let's get into what the auth-proxy actually spits back at rclone, because this part is all about the shape of that JSON. 👑

When the client authenticates with an SSH key, the JSON rclone feeds to your proxy program looks like this:

{
  "user": "me",
  "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf",
  "client_ip": "192.168.1.1"
}

Now listen, if the client authenticated with an S3 access key (that's the rclone serve s3 vibe), the client never sends its secret — it only sends a signature made with it. So the input you get is just the access key ID chilling in the user field, no pass or public_key in sight:

{
  "user": "AKIAIOSFODNN7EXAMPLE",
  "client_ip": "192.168.1.1"
}

When that happens, your program has to go look up the secret access key for that access key ID and hand it back in the _secret_access_key field of the output. Then rclone uses that secret to verify the signature on the request, and if it doesn't match, bestie, that request is refused. 💀

So basically your proxy program is the source of truth for both the credentials and the backend they map to. No cap. And if your program doesn't return _secret_access_key, or returns it empty? Request refused. Periodt.

Your program's answer for an access key ID gets cached (more on that lower down 👇), but rclone still checks back with the program after 5 minutes even if that access key ID is in constant use. So if you revoke an access key ID in your program, it takes effect within 5 minutes. A rotated secret takes effect on the first request signed with it. ✨

The client_ip key holds the IP address the client connected from, with no port number. You can use it to gate logins to certain networks, or to log authentication attempts all centrally. It gets omitted if the client has no IP address — like when connecting over a unix socket, for example. And heads up: if rclone is sitting behind a reverse proxy, this will be the address of the reverse proxy, not the original client. 🙈

---

And as an example, return this on STDOUT:

{
  "type": "sftp",
  "_root": "",
  "_obscure": "pass",
  "user": "me",
  "pass": "mypassword",
  "host": "sftp.example.com"
}

What this means: an SFTP backend gets created on the fly, for the user and pass/public_key returned in the output, pointing at the host you gave. And note — since _obscure is set to pass, rclone will obscure the pass parameter before creating the backend (which is required for sftp backends, don't @ me).

Your program can manipulate the supplied user in any way it wants. Like, to proxy to a bunch of 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 just user. For security you'd probably want to restrict the host to a limited list though. 🔒

There's an internal cache of backends that's keyed on the user, a hash of the pass or public_key, and the client_ip. So if a user's password or public-key changes, the client connects from a new IP address, or the proxy returns different config parameters (like a rotated api_key), a fresh backend gets created on the next request instead of the cached one being reused. Slay. 💅

This whole thing can be used to build general purpose proxies to any kind of backend that rclone supports. Iconic, honestly.

rclone serve webdav remote:path [flags]

👑 Options 👑

• --addr stringArray — IPaddress:Port or :Port 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 — TLS PEM key (concatenation of certificate and CA certificate)
• --client-ca string — Client certificate authority 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
• --disable-zip — Disable zip download of directories
• --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 — TLS PEM Private key
• --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
• --response-header stringArray — Set HTTP header for all responses, overriding existing values
• --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
• --user-from-header string — User name from a defined HTTP header
• --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-handle-caching Duration — Time to keep file handle and downloaders alive after last close (default 5s)
• --vfs-links — Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS
• --vfs-metadata-extension string — Set the extension to read metadata from
• --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 (<https://rclone.org/flags/>) for global options not listed here. 🫶

🌈 Filter Options 🌈

Flags for filtering directory listings

• --delete-excluded — deletes stuff on the destination that got excluded from the sync. yes it's as spicy as it sounds 💀
• --exclude stringArray — exclude files matching a pattern
• --exclude-from stringArray — read file exclude patterns from a file (pass - to read from stdin)
• --exclude-if-present stringArray — nuke whole directories if that filename is present in them
• --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 with zero processing of the lines (use - to read from stdin)
• --files-from0 stringArray — read list of source-file names from file using NUL as the separator (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)
• --hash-filter string — partition filenames by hash, k/n, or randomly with @/n
• --ignore-case — ignore case in filters (case insensitive bestie)
• --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 with a suffix of 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 of 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 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 of B|K|M|G|T|P (default off)

---

👀 See Also {#see-also}

• rclone serve — Serve a remote over a protocol. (https://rclone.org/commands/rclone_serve/)

---

🌈 rclone settier

Changes storage class/tier of objects in remote. it's giving glow up for your files fr fr 👑

📜 Synopsis

Changes the storage tier or class at the remote if the backend even supports that. A few cloud storage services offer different storage classes on objects — think AWS S3 and Glacier, Azure Blob storage with its Hot, Cool and Archive, Google Cloud Storage, Regional Storage, Nearline, Coldline, etc.

Lowkey important: certain tier changes make objects not available to access immediately. For example, tiering to archive in azure blob storage makes objects in frozen state, and the user can restore by setting tier to Hot/Cool. Similarly S3 to Glacier makes object inaccessible.true 😭

You can use it to tier a single object:

rclone settier Cool remote:path/file

Or use rclone filters to set the tier on only specific files:

rclone --include "*.txt" settier Hot remote:path/dir

Or just hand it a remote directory and every file in that directory gets tiered:

rclone settier tier remote:path/dir

rclone settier tier remote:path [flags]

⚙️ Options

• -h, --help — help for settier

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone — Show help for rclone commands, flags and backends. (https://rclone.org/commands/rclone/)

---

🧪 rclone test

Run a test command. we're in the lab now besties 🔬✨

📜 Synopsis

Rclone test is used to run test commands.

Pick which test command you want with the subcommand, e.g.

rclone test memory remote:

Each subcommand has its own options which you can see in their help.

NB: be careful running these commands, they may do strange things, so reading their documentation first is recommended. not a drill bestie 🙈

⚙️ Options

• -h, --help — help for test

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone — Show help for rclone commands, flags and backends. (https://rclone.org/commands/rclone/)
• rclone test changenotify — Log any change notify requests for the remote passed in. (https://rclone.org/commands/rclone_test_changenotify/)
• rclone test histogram — Makes a histogram of file name characters. (https://rclone.org/commands/rclone_test_histogram/)
• rclone test info — Discovers file name or other limitations for paths. (https://rclone.org/commands/rclone_test_info/)
• rclone test makefile — Make files with random contents of the size given (https://rclone.org/commands/rclone_test_makefile/)
• rclone test makefiles — Make a random file hierarchy in a directory (https://rclone.org/commands/rclone_test_makefiles/)
• rclone test memory — Load all the objects at remote:path into memory and report memory stats. (https://rclone.org/commands/rclone_test_memory/)
• rclone test speed — Run a speed test to the remote (https://rclone.org/commands/rclone_test_speed/)

---

📡 rclone test changenotify

Log any change notify requests for the remote passed in. it's literally just vibing and eavesdropping on your remote 👂💅

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 (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

📊 rclone test histogram

Makes a histogram of file name characters. charlie xcx would approve 🍓

📜 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 is useful for the rclone developers when developing filename compression. so you're basically doing charity work for the devs, iconic of you 🫶

rclone test histogram [remote:path] [flags]

⚙️ Options

• -h, --help — help for histogram

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

🔍 rclone test info

Discovers file name or other limitations for paths. detective mode activated 🕵️‍♀️

📜 Synopsis

Discovers what filenames and upload methods are possible to write to the paths passed in, and how long they can be. It can take some time. It will write test files into the remote:path passed in. It outputs a bit of go code for each one.

NB this can create undeletable files and other hazards — use with care! not me creating immortal files 😭💀

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 (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

📄 rclone test makefile

Make files with random contents of the size given. arts and crafts era 🎀✨

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 (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

🗂️ rclone test makefiles

Make a random file hierarchy in a directory. building a whole little world fr fr 🦋

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 (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

🧠 rclone test memory

Load all the objects at remote:path into memory and report memory stats. RAM girlies rise 🫶💜

rclone test memory remote:path [flags]

⚙️ Options

• -h, --help — help for memory

See the global flags page (https://rclone.org/flags/) for global options not listed here.

👀 See Also

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

rclone test speed 💨

Run a speed test to the remote.

✨ Synopsis ✨

Run a speed test to the remote.

This command runs a series of uploads and downloads to the remote, measuring and printing the speed of each test using varying file sizes and numbers of files.

Test time can be inaccurate with small file caps and large files. As it uses the results of an initial test to determine how many files to use in each subsequent test.

It is recommended to use the -q flag for a simpler output. e.g.:

rclone test speed remote: -q

NB This command will create and delete files on the remote in a randomly named directory which will be automatically removed on a clean exit. 🙈

You can use the --json flag to only print the results in JSON format.

rclone test speed <remote> [flags]

🌈 Options 🌈

• --ascii — Fill files with random ASCII printable bytes only
• --chargen — Fill files with a ASCII chargen pattern
• --file-cap int — Maximum number of files to use in each test (default 100)
• -h, --help — help for speed
• --json — Output only results in JSON format
• --large SizeSuffix — Size of large files (default 1Gi)
• --medium SizeSuffix — Size of medium files (default 10Mi)
• --pattern — Fill files with a periodic pattern
• --seed int — Seed for the random number generator (0 for random) (default 1)
• --small SizeSuffix — Size of small files (default 1Ki)
• --sparse — Make the files sparse (appear to be filled with ASCII 0x00)
• --test-time Duration — Length for each test to run (default 15s)
• --zero — Fill files with ASCII 0x00

See the global flags page (https://rclone.org/flags/) for global options not listed here.

🦋 See Also 🦋

• rclone test — Run a test command (https://rclone.org/commands/rclone_test/)

---

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 recursively sets the modification time on all existing files that is found under the path. Filters are supported, and you can test with the --dry-run or the --interactive/-i flag. This will touch --transfers files concurrently.

If --timestamp is used then 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 value of --timestamp is in UTC. If you want local time then add the --localtime flag. 🕰️

Metadata can be added when creating a new file with --metadata-set. For example: rclone touch remote:path -M --metadata-set key=value

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 (https://rclone.org/flags/) 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)
• --files-from0 stringArray — Read list of source-file names from file using NUL as separator (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)
• --hash-filter string — Partition filenames by hash k/n or randomly @/n
• --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. (https://rclone.org/commands/rclone/)

---

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 many options for controlling the listing which are compatible with the tree command, for example you can include file sizes with --size. Note that not all of them have short options as they conflict with rclone's short options. 👀

For a more interactive navigation of the remote see the ncdu command (https://rclone.org/commands/rclone_ncdu/).

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 (-U disables)
• --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 file/directory count at end of 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. See the global flags page (https://rclone.org/flags/) for global options not listed here.

🌸 Filter Options 🌸

Flags for filtering directory listings

• --delete-excluded — nukes files on the dest that got excluded from the sync 🗑️
• --exclude stringArray — excludes files that match the pattern
• --exclude-from stringArray — reads your exclude patterns out of a file (drop a - in there to read from stdin)
• --exclude-if-present stringArray — if this filename is present, the whole directory gets excluded, bye 👋
• --files-from stringArray — reads a list of source-file names from a file (again, - means stdin)
• --files-from-raw stringArray — reads a list of source-file names from a file with zero processing of the lines (and yes, - = stdin)
• --files-from0 stringArray — reads a list of source-file names from a file using NUL as the separator (you guessed it, - reads from stdin)
• -f, --filter stringArray — adds a file filtering rule, the fancy one ✨
• --filter-from stringArray — reads file filtering patterns from a file (use - to read from stdin)
• --hash-filter string — partitions filenames by hash k/n or randomly @/n
• --ignore-case — ignores case in filters (case insensitive, so chill)
• --include stringArray — includes files matching the pattern
• --include-from stringArray — reads file include patterns from a file (use - to read from stdin)
• --max-age Duration — only transfers 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 transfers files smaller than this, in KiB or with a suffix B|K|M|G|T|P (default off)
• --metadata-exclude stringArray — excludes metadatas matching the 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 the 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 ms|s|m|h|d|w|M|y (default off)
• --min-size SizeSuffix — only transfers files bigger than this, in KiB or with a suffix B|K|M|G|T|P (default off)

---

🌸 Listing Options 🌸

Flags for listing directories, bestie. Very demure, very mindful.

• --default-time Time — the time it shows 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 it; costs you more memory but way fewer transactions 💅

---

👑 See Also 👑

• rclone — Show help for rclone commands, flags and backends. (https://rclone.org/commands/rclone/)

---

🫶 Copying single files 🫶

okay so real talk: rclone normally syncs or copies whole directories. But if the source remote points at a file, rclone will just copy that one file, no drama. The destination remote has to point to a directory though — if it doesn't, rclone hits you with this bad boy:

Failed to create file system for "remote:file": is a file not a directory

So if you've got a remote with a file in it called test.jpg, you can copy literally just that one file like this:

rclone copy remote:test.jpg /tmp/download

And test.jpg lands inside /tmp/download. Cute.

That's exactly equivalent to specifying:

rclone copy --files-from /tmp/files remote: /tmp/download

where /tmp/files contains the single line:

test.jpg

💡 Pro tip from your girl: when you're copying individual files, use copy, not sync. They do pretty much the same thing, but copy uses a lot less memory. Periodt.

---

🧚 Syntax of remote paths 🧚

The syntax of the paths you hand to the rclone command goes like this, bestie. Buckle up.

🌈 /path/to/dir 🌈

This one refers to the local file system.

On Windows you can use \ instead of /, but only in local paths — non-local paths must use /. Peep the local filesystem docs for more on Windows-specific paths: https://rclone.org/local/#paths-on-windows.

Good news: these paths don't have to start with a leading /. If they don't, they're relative to your current directory. Slay.

🌟 remote:path/to/dir 🌟

This refers to a directory path/to/dir on remote:, as defined in the config file (the one you set up with rclone config).

💫 remote:/path/to/dir 💫

On most backends this means the exact same directory as remote:path/to/dir, and honestly that format should be your default. But on a very small number of remotes (FTP, SFTP, Dropbox for business) this points to a different directory. On those, paths without a leading / refer to your "home" directory, and paths with a leading / refer to the root root. Rooty root.

🦋 :backend:path/to/dir 🦋

This is the 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 config for that backend should be given 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 🎀

All those examples up there can also be written using a connection string syntax — so instead of passing the args as command line parameters like --http-url https://pub.rclone.org, you tuck them right into the remote specification as a kind of connection string. Obsessed.

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 modify existing remotes as well as create new ones with that on-the-fly syntax. This next 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 of the connection string style is that it only applies to that one remote, not to all the remotes of that type on the command line. A super common confusion is this attempt to copy a file shared on google drive over 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:

But using the connection string syntax? It works. Look at that:

rclone copy "gdrive,shared_with_me:shared-file.txt" gdrive:

Just know that the connection string only affects the options of the immediate backend. So if, say, gdriveCrypt is a crypt based on gdrive, this next command will not do what you want, because shared_with_me gets ignored by the crypt backend. 😭

rclone copy "gdriveCrypt,shared_with_me:shared-file.txt" gdriveCrypt:

Connection strings have this syntax:

remote,parameter=value,parameter2=value2:path/to/dir
:backend,parameter=value,parameter2=value2:path/to/dir

If the parameter contains a : or a ,, it has to go inside quotes — " or ' — so:

remote,parameter="colon:value",parameter2="comma,value":path/to/dir
:backend,parameter='colon:value',parameter2='comma,value':path/to/dir

And if a quoted value needs to include that quote, you double it up, like:

remote,parameter="with""quote",parameter2='with''quote':path/to/dir

That makes parameter be with"quote and parameter2 be with'quote. Very demure, very mindful quoting.

If you leave off the =parameter entirely, rclone will substitute =true, which plays so nicely with flags. For example, to use s3 configured in the environment you could do:

rclone lsd :s3,env_auth:

which is equivalent to:

rclone lsd :s3,env_auth=true:

Heads up though: on the command line you might need to wrap these connection strings in " or ' so your shell doesn't go interpreting special characters inside them. Rude of it, honestly.

If you're a shell master then you already know which strings are fine and which aren't. But if you're not sure, 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 still get interpreted inside " strings in the shell (notably \ and $ and "), so if your strings contain those, you can swap the roles of " and ' like this. (This syntax does not work on Windows. Sorry Windows girlies. 🙈)

rclone copy ':http,url="https://example.com":path/to/dir' /tmp/dir

You can use rclone config string (https://rclone.org/commands/rclone_config_string/) to convert a remote into a connection string. Handy.

💜 Connection strings, config and logging 💜

If you supply extra configuration to a backend via a command line flag, an environment variable, or a 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

DEBUG : s3: detected overridden config - adding "{Srj1p}" suffix to name

This is so rclone can tell the modified remote apart from the unmodified remote when it's caching backends. It's literally just a log thing, you probably won't notice it anywhere else.

Which means on-the-fly backends such as

rclone -vv lsf :s3,env_auth:

will get their own names:

DEBUG : :s3: detected overridden config - adding "{YTu53}" suffix to name

⭐ Valid remote names ⭐

Remote names are case sensitive, and they must follow these rules:

• 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 — before that it was limited to plain ASCII (0-9, A-Z, a-z). If you use the same rclone configuration from different shells, which may be configured with different character encoding, you must 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". 💀

---

okay so real talk bestie: do not use single-character names on Windows 💀 it creates ambiguity with Windows drives' names, like a remote called C is literally indistinguishable from the C drive. rclone will always assume that a single letter name refers to a drive. That's just how it is, no cap.

---

🎀 Adding global configuration to a remote 🎀

So you can add global configuration to the remote configuration, and it gets applied just before the remote is created. Two ways to do it:

• the first is to use override.var = value in the config file or the connection string for a temporary change
• the second is to use global.var = value in the config file or connection string for a permanent change

This is explained fully below 💅

override.var

This is used to override a global variable just for the duration of the remote creation. It won't affect other remotes even if they are created at the same time. Iconic behaviour honestly.

This is very useful for overriding networking config needed just for that remote. For example, say you have a remote which needs --no-check-certificate as it is running on test infrastructure without a proper certificate. You could supply the --no-check-certificate flag to rclone, but this will affect all the remotes. To make it just affect this remote you use an override. You could put this in the config file:

[remote]
type = XXX
...
override.no_check_certificate = true

or use it in the connection string remote,override.no_check_certificate=true: (or just remote,override.no_check_certificate:).

Note how the global flag name loses its initial -- and gets - replaced with _ and gets an override. prefix. Lowkey a glow-up for a flag name ✨

Not all global variables make sense to be overridden like this as the config is only applied during the remote creation. Here is a non exhaustive list of ones which might be useful:

• bind_addr
• ca_cert
• client_cert
• client_key
• connect_timeout
• disable_http2
• disable_http_keep_alives
• dump
• expect_continue_timeout
• headers
• http_proxy
• low_level_retries
• max_connections
• no_check_certificate
• no_gzip
• timeout
• traffic_class
• use_cookies
• use_server_modtime
• user_agent

An override.var will override all other config methods, but just for the duration of the creation of the remote. Ate and left no crumbs 🍓

global.var

This is used to set a global variable for everything. The global variable is set just before the remote is created.

This is useful for parameters (eg sync parameters) which can't be set as an override. For example, say you have a remote where you would always like to use the --checksum flag. You could supply the --checksum flag to rclone on every command line, but instead you could put this in the config file:

[remote]
type = XXX
...
global.checksum = true

or use it in the connection string remote,global.checksum=true: (or just remote,global.checksum:). This is equivalent to using the --checksum flag.

Note how the global flag name loses its initial -- and gets - replaced with _ and gets a global. prefix.

Any global variable can be set like this and it is exactly equivalent to using the equivalent flag on the command line. This means it will affect all uses of rclone. Yes, all of them. Main character energy, truly 👑

If two remotes set the same global variable then the first one instantiated will be overridden by the second one. A global.var will override all other config methods when the remote is created.

---

🌈 Quoting and the shell 🌈

When you are typing commands to your computer you are using something called the command line shell. This interprets various characters in an OS specific way. Cute of it, honestly.

Here are some gotchas which may help users unfamiliar with the shell rules 🫶

Linux / macOS

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. iykyk 📖

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 at https://github.com/rclone/rclone/issues/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. This is, however, a valid filename component in non-Windows OSes. The remote name parser will only search for a : up to the first / so if you need to act on a file or directory like this then 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 — see the overview at https://rclone.org/overview/#optional-features) 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. So efficient. So slay. 💅

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. 😭

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 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. Bestie that's the whole vibe 🦋

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 at https://rclone.org/overview/#features (Eg local at https://rclone.org/local/#metadata, 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 that 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.

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 server-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. The circle of metadata life 🧚

💜 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. Watch out for that one bestie 🚨

🎀 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. Lossless round trips?? Obsessed. 💖

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 as well. The metadata literally tags along for the ride. 💅

Standard system metadata 🏷️

Here's the tea: this is a table of standard system metadata which, if it's appropriate, a backend may implement.

• mode — File type and mode: octal, unix style — e.g. 0100664
• uid — User ID of owner: decimal number — e.g. 500
• gid — Group ID of owner: decimal number — e.g. 500
• rdev — Device ID (if special file) => hexadecimal — e.g. 0
• atime — Time of last access: RFC 3339 — e.g. 2006-01-02T15:04:05.999999999Z07:00
• mtime — Time of last modification: RFC 3339 — e.g. 2006-01-02T15:04:05.999999999Z07:00
• btime — Time of file creation (birth): RFC 3339 — e.g. 2006-01-02T15:04:05.999999999Z07:00
• utime — Time of file upload: RFC 3339 — e.g. 2006-01-02T15:04:05.999999999Z07:00
• cache-control — Cache-Control header — e.g. no-cache
• content-disposition — Content-Disposition header — e.g. inline
• content-encoding — Content-Encoding header — e.g. gzip
• content-language — Content-Language header — e.g. en-US
• content-type — Content-Type header — e.g. 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. Like, if you bring your own, yours wins. 👑

Hashes are not included in system metadata, because there's already a well defined way of reading those. No double-dipping. ✨

✨ Options ✨

Rclone has a number of options to control its behaviour. These are documented below, and in the flags page. 🎀

Options that take parameters can have the values passed in two ways: --option=value or --option value. BUT — and this is the part everyone gets wrong — boolean (true/false) options behave slightly differently from the other options, because --boolean sets the option to true and the absence of the flag sets it to false. You can also specify --boolean=false or --boolean=true. But heads up: --boolean false is not valid — that gets parsed as --boolean and the false gets parsed as an extra command line argument for rclone. 😭

String values that are recognized as special identifiers, e.g. the name of the log level to set with option --log-level, are case insensitive, e.g. --log-level ERROR and --log-level error are identical. Cute, right?

Options documented to take a stringArray parameter accept multiple values. To pass more than one value, repeat the option; for example: --include value1 --include value2. Other options may only accept a single value, and should only be specified once, but where the specified parameter may indicate a list of values separated by space or comma. Such options are documented to take a CommaSepList parameter if comma separated, and SpaceSepList if space separated, although some may also have different parameters such as DumpFlags or just string, and the help text explains that this will be interpreted as a list.

Floating-point values with a fractional part must use a period (.) as the decimal separator — the one that's common in English-speaking countries — no matter what your configured system locale is. Parameter type float accepts decimal and hexadecimal floating-point numbers as defined by the Go syntax for floating-point literals (https://go.dev/ref/spec#Floating-point_literals).

⏰ Time and duration options

Options that take a Time or Duration parameter must be specified as a formatted string describing an absolute or relative time. Note that both the Time and Duration parameter types can be expressed as either absolute or relative time, just with different interpretations, e.g. a relative time will be treated as an offset from the current time when passed as a Time value. It's giving "same string, different vibe". 🦋

An absolute time can be specified as a string in one of 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)

A relative time is a string with a, possibly signed, sequence of decimal numbers, each with optional fraction, and each with a unit suffix. If the string only contains a single number, then the unit suffix is optional and will default to seconds, i.e. a plain decimal value will be treated as a number of seconds. The following suffixes are valid:

• ms - Milliseconds
• s - Seconds
• m - Minutes
• h - Hours
• d - Days
• w - Weeks
• M - Months
• y - Years

Examples: "10", "300ms", "-1.5h" or "2h45m". 🌸

📏 Size options

Options that take a SizeSuffix parameter can be specified as an integer value, which will then be assumed to represent a KiB value (multiples of 1024 bytes) by default. The interpretation can be changed by appending a suffix: B for Byte, K for KiB, M for MiB, G for GiB, T for TiB and P for PiB. These are the binary units, e.g. 1, 210, 220, 2**30 respectively.

See also --human-readable. 💖

👑 Main options

--backup-dir string

When using sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/), any files which would have been overwritten or deleted are moved in their original hierarchy into this directory. Like a little retirement home for your old files. 🏡

If --suffix is set, then the moved files will have the suffix added to them. If there is a file with the same path (after the suffix has been added) in the directory, then it will be overwritten. Bestie, it does not ask. 💀

The remote in use must support server-side move or copy and you must use the same remote as the destination of the sync. The backup directory must not overlap the destination directory without it being 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 which would have been updated or deleted will be stored in remote:old.

If running rclone from a script you might want to use today's date as the directory name passed to --backup-dir to store the old files, or you might want to pass --suffix with today's date. This can be done with --suffix $(date +%F) in bash, and --suffix $(Get-Date -Format 'yyyy-MM-dd') in PowerShell.

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 host name. If the host name doesn't resolve or resolves to more than one IP address it will give an error. 🙈

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.

--bwlimit BwTimetable

This option controls the bandwidth limit. For example

--bwlimit 10M

would mean limit the upload and download bandwidth to 10 MiB/s. NB this is bytes 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 to not limit bandwidth. Full speed ahead, no cap. 🏎️

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 would use

--bwlimit 10M:off

this would limit the upload bandwidth to 10 MiB/s but the download bandwidth would be unlimited.

When specified as above the bandwidth limits last for the duration of run of the rclone binary.

It is also possible to specify a "timetable" 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 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 spaces or semicolons.

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 will 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 will be completely disabled (full speed). Anything between 11pm and 8am will remain unlimited. 🌙

An example of 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 will rise to 10 MiB/s before the end of Friday. At 10:00 on Saturday it will be set to 1 MiB/s. From 20:00 on Sunday it will 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,512 Mon-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 limit applies to the data transfer for all backends, bestie. And for most of them, the directory listing bandwidth counts too — the exceptions are the non-HTTP backends, ftp, sftp and storj. 💅

Ok so units check because this trips everybody up: it's Byte/s, not bit/s. Connections are usually measured in bit/s, so to convert you divide by 8. Say you've got a 10 Mbit/s connection and you want rclone to use half of it — 5 Mbit/s. That's 5/8 = 0.625 MiB/s, so you'd pass --bwlimit 0.625M. Maths ate, periodt. 🍓

On Unix systems (Linux, macOS, ...) you can toggle the bandwidth limiter by sending a SIGUSR2 signal to rclone. That means you can drop the limitations on a long-running transfer and then slam them right back to whatever you set with --bwlimit when you need it. Assuming there's only one rclone instance running, you toggle it like this:

kill -SIGUSR2 $(pidof rclone)

And if you've set rclone up with a remote control, you can change the bwlimit dynamically too:

rclone rc core/bwlimit rate=1M

---

--bwlimit-file BwTimetable ✨

This one controls the per file bandwidth limit. For all the actual options, go look at the --bwlimit flag. Same energy, smaller scope.

Wanna make sure no single transfer ever goes faster than 1 MiB/s? Do this:

--bwlimit-file 1M

You can run this right alongside --bwlimit, no conflict. 🫶

Heads up though: if you give it a schedule, the file uses the schedule that's in effect at the start of the transfer.

---

--buffer-size SizeSuffix 🎀

Use a buffer of this size to speed up your file transfers. Each --transfer will eat this much memory for buffering, so like… pick a number that isn't feral.

When you're using mount or cmount, every open file descriptor uses this much memory for buffering. The mount docs got you — https://rclone.org/commands/rclone_mount/#vfs-file-buffering — go read them for the deets.

Set it to 0 to disable buffering entirely, which is the minimum memory usage vibe.

Ngl, the memory allocation of the buffers is influenced by the --use-mmap flag. Just so you know. 💜

---

--cache-dir string 🌸

This is where you tell rclone which directory to use for caching, overriding the default. Queen behaviour.

The default value depends on your operating system:

• 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): $TMPDIR/rclone, where TMPDIR is the value from --temp-dir.

You can use the config paths command — https://rclone.org/commands/rclone_config_paths/ — to see what the current value is for you. Lowkey handy.

The cache directory is heavily used by the VFS File Caching mount feature (https://rclone.org/commands/rclone_mount/#vfs-file-caching), but also by serve (https://rclone.org/commands/rclone_serve/), GUI and other parts of rclone. It's a busy directory fr fr. 🔥

---

--check-first 👑

If this flag is set, then in a sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/), rclone will do all the checks to see whether files actually need to be transferred before doing any of the transfers. Normally rclone just starts running transfers as soon as possible, main character energy, no waiting.

This flag is useful on IO limited systems where transfers interfere with checking. Or when you want to ensure perfect ordering while 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. That gives you perfect ordering of the transfers and the deletes — but it'll cause the transfer stats to have more items in than expected. Not a bug, just a side effect, bestie.

Careful: using this flag can use more memory, because it effectively sets --max-backlog to infinite. That means all the info on the objects to transfer is held in memory before the transfers even start. 😭

---

--checkers int 🦋

Originally this only controlled the number of file checkers to run in parallel, e.g. by rclone copy. Now it's a fairly universal parallelism control used by rclone in several places. Glow up.

Note: checkers do the equality checking of files during a sync. For some storage systems (e.g. S3, Swift, Dropbox) this can take a significant amount of time, so they're run in parallel.

The default is to run 8 checkers in parallel. But if you've got slow-reacting backends, you may need to lower (rather than increase!) this default by setting --checkers to 4 or less threads. This is especially advised if you're experiencing backend server crashes 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 utmost care, while monitoring your server health and file checking throughput. Like, please.

---

-c, --checksum ⭐

Normally rclone looks at the modification time and the size of files to see if they're equal. If you set this flag, rclone checks the file hash and size instead to determine if files are equal. Whole different vibe check.

This is useful when the remote doesn't support setting modified time and you want a more accurate sync than just checking the file size.

It's especially useful when transferring between remotes which store the same hash type on the object, e.g. Drive and Swift. For the details of which remotes support which hash type, check the table in the overview section — https://rclone.org/overview/.

Eg rclone --checksum sync s3:/bucket swift:/bucket would run much quicker than without the --checksum flag. Ate. 🔥

When you use this flag, rclone won't update mtimes of remote files if they're incorrect, the way it normally would.

---

--color AUTO|NEVER|ALWAYS 🌈

Specify when colors (and other ANSI codes) should be added to the output. Cute, right?

• AUTO only allows ANSI codes when the output is a terminal. This is the default. ✨
• NEVER never allows ANSI codes.
• ALWAYS always adds ANSI codes, regardless of the output format (terminal or file).

---

--compare-dest stringArray 🧚

When using sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/), the specified paths are checked in addition to the destination for files. If a file identical to the source is found, that file is not copied from source. Super useful when you only 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 also --copy-dest and --backup-dir.

---

--config string 💖

Specify the location of the rclone configuration file, to override the default. E.g. rclone config --config="rclone.conf".

The exact default is a bit complex to describe, because different versions of rclone changed it while trying to preserve backwards compatibility — but in most cases it's as simple as:

• %APPDATA%/rclone/rclone.conf on Windows
• ~/.config/rclone/rclone.conf on other

The complete logic is as follows: rclone will look for an existing configuration file in any of these locations, in priority order:

1. rclone.conf (in the program directory, where the rclone executable is)
2. %APPDATA%/rclone/rclone.conf (only on Windows)
3. $XDG_CONFIG_HOME/rclone/rclone.conf (on all systems, including Windows)
4. ~/.config/rclone/rclone.conf (see below for the explanation of the ~ symbol)
5. ~/.rclone.conf

If no existing configuration file is found, then a new one will be created in the following location:

• On Windows: Location 2 listed above, except in the unlikely event that APPDATA is not defined, then 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 cannot be created — but if a home directory also wasn't found, then the path .rclone.conf relative to the current working directory is used as the final resort.

The ~ symbol in the paths above represents the home directory of the current user on any OS, and the value is defined like this:

• On Windows: %HOME% if defined, else %USERPROFILE%, or else %HOMEDRIVE%\%HOMEPATH%.
• On Unix: $HOME if defined, else by looking up the current user in the OS-specific user database (e.g. passwd file), or else use the result from the shell command cd && pwd.

If you run rclone config file you'll see where the default location is for you. Running rclone config touch will make sure a configuration file exists, creating an empty one in the default location if there isn't one already. 🫶

The fact that an existing rclone.conf 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 to a writable directory and then create an empty rclone.conf in the same directory. Iconic little trick.

If the location is set to the empty string "", or a path to a file with the name notfound, or the OS null device — represented by the value NUL on Windows and /dev/null on Unix systems — then rclone will keep the configuration file in memory only.

You may see a log message "Config file not found - using defaults" if there's no configuration file. This can be suppressed — e.g. if you're using rclone entirely with on the fly remotes (https://rclone.org/docs/#backend-path-to-dir) — by using a memory-only configuration file or by creating an empty configuration file, as described above.

The file format is basic INI (https://en.wikipedia.org/wiki/INI_file#Format): sections of text, led by a [section] header and followed by key=value entries on separate lines. In rclone each remote is represented by its own section, where the section name defines the name of the remote. Options are specified as key=value entries, where the key is the option name without the --backend- prefix, in lowercase and with _ instead of -. E.g. the option --mega-hard-delete corresponds to the key hard_delete. Only backend options can be specified. A special, and required, key type identifies the storage system (https://rclone.org/overview/), where the value is the internal lowercase name as returned by the command rclone help backends. Comments are indicated by ; or # at the beginning of a line.

Example:

[megaremote]
type = mega
user = you@example.com
pass = PDPcQVVjVtzFY-GTdDFozqBhTdsPg3qH

Note that passwords are in obscured (https://rclone.org/commands/rclone_obscure/) form. Also, many storage systems use token-based authentication instead of passwords, and this requires additional steps. It is easier, and safer, to use the interactive command rclone config instead of manually editing the configuration file. 💅

Okay bestie, real talk about that config file 💖 It's typically gonna hold your login info, so it should have restricted permissions — like, only the current user can read it. Rclone tries to make sure that happens when it writes the file, no cap. You can also choose to encrypt it if you're feeling spicy. 🔐

When token-based authentication is in play, the config file must be writable, because rclone needs to update the tokens inside it. It's giving non-negotiable. 🙅‍♀️

To reduce the risk of corrupting an existing config file, rclone will not write straight 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 cleans up by deleting the backup file. It's an atomic glow-up, periodt. ✨

And if the config file path rclone is using is a symbolic link? Then that gets evaluated and rclone writes to the resolved path instead of overwriting the symlink — iconic behaviour honestly. The temporary files used in that whole process (the one we just described, keep up 💅) get written to the same parent directory as the resolved config file. But heads up: if that directory is also a symbolic link, it will not be resolved, and the temporary files get written to the location of the directory symbolic link. 🌀

---

🌈 --contimeout Duration

Sets 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 stringArray

When you're using sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/), these specified paths get checked in addition to the destination for files. This part is exactly the same as --compare-dest, except — and here's the twist 🫢 — with --copy-dest, if a file identical to the source is found, that file is server-side copied from the specified paths to the destination. Super useful for incremental backup, fr fr.

The remote in use must support server-side copy, and you must use the same remote as the destination of the sync. Also the compare directory must not overlap the destination directory. 🚧

See --compare-dest and --backup-dir.

🦋 --dedupe-mode interactive|skip|first|newest|oldest|largest|smallest|rename|list

The mode to run the dedupe command in. One of interactive, skip, first, newest, oldest, largest, smallest, rename, list. The default is interactive. See the dedupe (https://rclone.org/commands/rclone_dedupe/) command for more info on what these options actually mean. 💫

💜 --default-time Time

If a file or directory doesn't have a modification time that rclone can read, then rclone will display this fixed time instead.

The default is 2000-01-01 00:00:00 UTC. This can be configured in any of the ways shown in time 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 string

This disables a comma separated list of optional features. For example, to disable server-side move and server-side copy, use:

--disable move,copy

The features can be put in any case — rclone is chill like that. 💅

To see a 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 (https://rclone.org/overview/#features) and optional features (https://rclone.org/overview/#optional-features) to get an idea of which feature does what.

Note that some features can be set to true if they are 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 doing this, but it may be useful in extremis. 😭

(Note that ! is a shell command which you will 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

This 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 (https://github.com/golang/go/issues/37373). 🐛

🌈 --dscp string

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 (https://en.wikipedia.org/wiki/Differentiated_services) to get an idea of this field. Setting this to 1 (LE) to identify the flow to SCAVENGER class can avoid occupying too much bandwidth in a network with DiffServ support (RFC 8622 (https://tools.ietf.org/html/rfc8622)).

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 (https://github.com/golang/go/issues/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 (https://rclone.org/commands/rclone_sync/) command, because that one deletes files in the destination. 😳 Please use it. I'm begging.

💖 --expect-continue-timeout Duration

This specifies the amount of time 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 allows rclone to return exit code 9 if no files were transferred between the source and destination. That lets you use rclone in scripts and trigger follow-on actions if data was copied, or skip them if not. Chef's kiss for automation. 👑

NB: Enabling this option turns a usually non-fatal error into a potentially fatal one — please check and adjust your scripts accordingly! 🚨

🦋 --fix-case

Normally, a sync to a case insensitive dest (such as macOS / Windows) will not result in a matching filename if the source and dest filenames have casing differences but are otherwise identical. For example, syncing hello.txt to HELLO.txt will normally result in the dest filename remaining HELLO.txt. If --fix-case is set, then HELLO.txt will be renamed to hello.txt to match the source. ✨

NB:

• directory names with incorrect casing will also be fixed 🗂️
• --fix-case will be ignored if --immutable is set
• using --local-case-sensitive instead is not advisable; it will cause HELLO.txt to get deleted! 💀
• the old dest filename must not be excluded by filters. Be especially careful with --files-from (https://rclone.org/filtering/#files-from-read-list-of-source-file-names), which does not respect --ignore-case (https://rclone.org/filtering/#ignore-case-make-searches-case-insensitive)! 🙈
• 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. 📉

💜 --fs-cache-expire-duration Duration

When you're using rclone via the API, rclone caches created remotes for 5 minutes by default in the "fs cache". Which means if you do repeated actions on the same remote, rclone won't have to build it again from scratch — efficient queen behaviour. 💅

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 two 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 Duration

This 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, set to 0 to disable expiry. ⏳

⭐ --header stringArray

Add an HTTP header for all transactions. The flag can be repeated to add multiple headers. 🔁

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. 🫶

The headers are only sent to the host of the original request. If the server redirects to another host (including a subdomain or a different port), or redirects an https request to http, the headers are not sent to it, or to any further hop in that redirect chain. Rclone logs this at debug level (-vv).

rclone ls remote:test --header "X-Rclone: Foo" --header "X-LetMeIn: Yes"

🎀 --header-download stringArray

Add an HTTP header for all download transactions. The flag can be repeated to add multiple headers.

rclone sync --interactive s3:test/src ~/dst --header-download "X-Amz-Meta-Test: Foo" --header-download "X-Amz-Meta-Test2: Bar"

See GitHub issue #59 (https://github.com/rclone/rclone/issues/59) for currently supported backends. 📥

🔥 --header-upload stringArray

Add an HTTP header for all upload transactions. The flag can be repeated to add multiple headers.

rclone sync --interactive ~/src s3:test/dst --header-upload "Content-Disposition: attachment; filename='cool.html'" --header-upload "X-Amz-Meta-Test: FooBar"

See GitHub issue #59 (https://github.com/rclone/rclone/issues/59) for currently supported backends. 📤

🌈 --http-proxy string

Use this option to set an HTTP proxy for all HTTP based services to use.

Rclone also supports the standard HTTP proxy environment variables, which it will pick up automatically. That's the way the HTTP proxy will normally be set, but this flag can be used to override it. 🧚

💖 --human-readable

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.

like, in human-readable mode the values get scaled up into bigger units, indicated with a suffix shown after the value, and rounded to three decimals. 💅

And rclone is so consistent about it: binary units (powers of 2) for sizes, decimal units (powers of 10) for counts. The unit prefix for size follows IEC standard notation, e.g. Ki for kibi — so 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. no cap 👑

The various list (https://rclone.org/commands/rclone_ls/) 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 (https://rclone.org/commands/rclone_about/) command outputs human-readable by default, with a command-specific option --full to output the raw numbers instead.

Command size (https://rclone.org/commands/rclone_size/) outputs both human-readable and raw numbers in the same output. she contains multitudes 🫶

The tree (https://rclone.org/commands/rclone_tree/) command also considers --human-readable, but it will not use the exact same notation as the other commands: it rounds to one decimal, and uses single letter suffix, e.g. K instead of Ki. The reason for this is that it relies on an external library. not her fault, she's just built different 😭

The interactive command ncdu (https://rclone.org/commands/rclone_ncdu/) shows human-readable by default, and responds to key u 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.

💔 --ignore-checksum

Normally rclone will check that the checksums of transferred files match, and give an error "corrupted on transfer" if they don't.

You can use this option to skip that check. You should only use it if you have had the "corrupted on transfer" error message and you are sure you might want to transfer potentially corrupted data. like... bestie, be so careful with this one. 🙈

🙈 --ignore-existing

Using this option will make rclone unconditionally skip all 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 cannot 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 and size of files to see if they are equal. If you set this flag then rclone will check only the modification time. 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 (https://github.com/rclone/rclone/issues/399) for more info).

🕐 -I, --ignore-times

Using this option will cause rclone to unconditionally upload all files regardless of the state of files on the destination.

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

Treat source and destination files as immutable and disallow modification.

With this option set, files will be created and deleted as requested, but existing files will never 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 (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/)) are affected by this behavior, and only modification is disallowed. Files may still be deleted explicitly (e.g. delete (https://rclone.org/commands/rclone_delete/), purge (https://rclone.org/commands/rclone_purge/)) or implicitly (e.g. sync (https://rclone.org/commands/rclone_sync/), move (https://rclone.org/commands/rclone_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 temporary file with an extension like this, where XXXXXX represents a hash of the source file's fingerprint and .partial is --partial-suffix value (.partial by default).

original-file-name.XXXXXX.partial

(rclone will make sure the final name is no longer than 100 characters 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.

If the --inplace flag is supplied, rclone will upload directly to the final name 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. This can cause data loss of the existing file if the transfer fails. 🚨

Note that on the local file system if you don't use --inplace hard links (Unix only) will be broken. And if you do 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 manual confirmation before destructive operations.

It is recommended that you use this flag while learning rclone especially with rclone sync. lowkey the training wheels are the whole point bestie 🎀

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 Return 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 now, just in case!

🌳 --leave-root

During rmdirs it will not remove root directory, even if it's empty.

🔗 -l, --links

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows). Ignored files won't be copied, moved or deleted in a sync.

If you supply this flag then rclone will copy symbolic links from any supported backend, and store them as text files, with a .rclonelink suffix in the destination.

The text file will contain the target of the symbolic link.

The --links / -l flag enables this feature for all supported backends and the VFS. There are individual flags for just enabling it for the VFS --vfs-links and the local backend --local-links if required. ✨

🗂️ --list-cutoff int

When syncing rclone needs to sort directory entries before comparing them. Below this threshold (1,000,000) by default, rclone will store the directory entries in memory. 1,000,000 entries will take approx 1GB of RAM to store. Above this threshold rclone will store directory entries on disk and sort them without using a lot of memory.

Doing this is slightly less efficient then sorting them in memory and will only work well for the bucket based backends (eg s3, b2, azureblob, swift) but these are the only backends likely to have millions of entries in a directory.

📝 --log-file string

Log all of rclone's output to a file. This is not active by default. This can be useful for tracking down problems with syncs in combination with the -v flag. See the logging section for more info.

If the file exists, then rclone will append to it.

Note that if you are using the logrotate program to manage rclone's logs, then you should use the copytruncate option as rclone doesn't have a signal to rotate logs.

Alternatively you can use the options below to manage rclone's built in log rotation.

📦 --log-file-max-size SizeSuffix

Maximum size of the log file before it's rotated (eg 10M). This SizeSuffix is rounded to the nearest MiB or 1 MiB if lower.

If --log-file is not set then this option will be ignored.

If this option is not set, then the other log rotation options will be ignored.

For example if the following flags are in use

rclone --log-file rclone.log --log-file-max-size 1M --log-file-max-backups 3

Then this will create log files which look like this

$ ls -l
-rw-------  1 user user  1048491 Apr 11 17:15 rclone-2025-04-11T17-15-29.998.log
-rw-------  1 user user  1048511 Apr 11 17:15 rclone-2025-04-11T17-15-30.467.log
-rw-------  1 user user  1048559 Apr 11 17:15 rclone-2025-04-11T17-15-30.543.log
-rw-------  1 user user   521602 Apr 11 17:15 rclone.log

The file rclone.log being the current one.

🗜️ --log-file-compress

If set, compress rotated log files using gzip. This changes the extension of the old log files to .log.gz.

Defaults to false - don't compress log files.

• --log-file-max-age Duration — bestie, this is how long old log files get to stick around before they're yeeted, like 7d. ✨ Heads up tho: it gets rounded to the dearest day (yes, the manpage says "dearest", we respect the typo in this house 💅), or 1 day if your value is lower than that.

The default? Nothing gets thrown out, ever. All your old log files stay. 🌸

• --log-file-max-backups int — the maximum number of old log files rclone will keep. 🎀

Default is still "keep literally all of them," no cap, no limits, main character energy. 👑

• --log-format string — a comma separated list of log format options. Here's the accepted lineup, queen: 💖
  • date — adds a date in the format YYYY/MM/YY to the log.
  • time — adds a time to the log in format HH:MM:SS.
  • microseconds — adds microseconds to the time in format HH:MM:SS.SSSSSS.
  • UTC — makes the logs in UTC, not localtime.
  • longfile — adds the source file and line number of the log statement.
  • shortfile — adds the source file and line number of the log statement.
  • pid — adds the process ID to the log — super useful with rclone mount --daemon.
  • nolevel — don't add the level to the log.
  • json — equivalent to adding --use-json-log.

They get added to the log line in the order above, so it's not a free-for-all. ⭐

The default log format is "date,time". 🦋

• --log-level LogLevel — this sets the log level for rclone. Default is NOTICE. 🌈

DEBUG is equivalent to -vv. It outputs lots of debug info — genuinely useful for bug reports and for really finding out what rclone is doing under the hood. 🔥

INFO is equivalent to -v. It outputs information about each transfer and prints stats once a minute by default.

NOTICE is the default log level if no logging flags are supplied. It outputs very little when things are working normally. It outputs warnings and significant events, so like, the important tea only. 🫖

ERROR is equivalent to -q. It only outputs error messages.

See also the logging section. ✨

• --windows-event-log-level LogLevel — if you configure this (default is OFF) then logs of this level and above will be logged to the Windows event log in addition to the normal logs. These get logged in JSON format as described below regardless of what format the main logs are configured for. Bestie it does not care about your main log format. 💅

The Windows event log only has 3 levels of severity: Info, Warning and Error. If enabled, we map rclone levels like this:

• Error ← ERROR (and above)
• Warning ← WARNING (note that this level is defined but not currently used — she exists but she's not doing anything rn 😭)
• Info ← NOTICE, INFO and DEBUG.

Rclone will declare its log source as "rclone" if it has enough permissions to create the registry key needed. If not, then logs will appear as "Application". You can run rclone version --windows-event-log-level DEBUG once as administrator to create the registry key in advance. 👑

Note that the --windows-event-log-level level must be greater (more severe) than or equal to the --log-level. For example to log DEBUG to a log file but ERRORs to the event log you would use

--log-file rclone.log --log-level DEBUG --windows-event-log-level ERROR

This option is only supported Windows platforms. 🪟

• --use-json-log — this switches the log format to JSON. The log messages are then streamed as individual JSON objects, with fields: level, msg, source, and time. The resulting format is what is sometimes referred to as newline-delimited JSON (https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON) (NDJSON), or JSON Lines (JSONL). This is well suited for processing by traditional line-oriented tools and shell pipelines, but a complete log file is not strictly valid JSON and needs a parser that can handle it. ⚠️

The JSON logs will be printed on a single line, but are shown expanded here for clarity:

{
  "time": "2025-05-13T17:30:51.036237518+01:00",
  "level": "debug",
  "msg": "4 go routines active\n",
  "source": "cmd/cmd.go:298"
}

Completed data transfer logs will have extra size information. Logs which are about a particular object will have object and objectType fields also. 🎀

{
  "time": "2025-05-13T17:38:05.540846352+01:00",
  "level": "info",
  "msg": "Copied (new) to: file2.txt",
  "size": 6,
  "object": "file.txt",
  "objectType": "*local.Object",
  "source": "operations/copy.go:368"
}

Stats logs will contain a stats field which is the same as returned from the rc call core/stats (https://rclone.org/rc/#core-stats).

{
  "time": "2025-05-13T17:38:05.540912847+01:00",
  "level": "info",
  "msg": "...text version of the stats...",
  "stats": {
    "bytes": 6,
    "checks": 0,
    "deletedDirs": 0,
    "deletes": 0,
    "elapsedTime": 0.000904825,
    ...truncated for clarity...
    "totalBytes": 6,
    "totalChecks": 0,
    "totalTransfers": 1,
    "transferTime": 0.000882794,
    "transfers": 1
  },
  "source": "accounting/stats.go:569"
}

• --low-level-retries int — this controls the number of low level retries rclone does. 🔁

A low level retry is used to retry a failing operation — typically one HTTP request. This might be uploading a chunk of a big file, for example. You will see low level retries in the log with the -v flag.

This shouldn't need to be changed from the default in normal operations. However, if you get a lot of low level retries you may wish to reduce the value so rclone moves on to a high level retry (see the --retries flag) quicker. ngl sometimes you just gotta let it go, bestie 💅

Disable low level retries with --low-level-retries 1.

• --max-backlog int — this is the maximum allowable backlog of files in a sync/copy/move queued for being checked or transferred. 📚

This can be set arbitrarily large. It will only use memory when the queue is in use. Note that it will use in the order of N KiB of memory when the backlog is in use.

Setting this large allows rclone to calculate how many files are pending more accurately, give a more accurate estimated finish time and make --order-by work more accurately. Iconic accuracy behavior. ✨

Setting this small will make rclone more synchronous to the listings of the remote which may be desirable.

Setting this to a negative number will make the backlog as large as possible. 🦋

• --max-buffer-memory SizeSuffix — if set, don't allocate more than the given amount of memory as buffers. If not set or set to 0 or off this will not limit the amount of memory in use. 🌸

This includes memory used by buffers created by the --buffer flag and buffers used by multi-thread transfers.

Most multi-thread transfers do not take additional memory, but some do depending on the backend (eg the s3 backend for uploads). This means there is a tension between setting --transfers as high as possible and memory use. 😤

Setting --max-buffer-memory allows the buffer memory to be controlled so that it doesn't overwhelm the machine and allows --transfers to be set large. Balance, bestie. ⚖️

• --max-connections int — this sets the maximum number of concurrent calls to the backend API. It may not map 1:1 to TCP or HTTP connections depending on the backend in use and the use of HTTP1 vs HTTP2. 🔌

When downloading files, backends only limit the initial opening of the stream. The bulk data download is not counted as a connection. This means that the --max--connections flag won't limit the total number of downloads. 💀 (yes that's the spelling in the manpage, we keep it verbatim, no cap)

Note that it is possible to cause deadlocks with this setting so it should be used with care. ⚠️

If you are doing a sync or copy then make sure --max-connections is one more than the sum of --transfers and --checkers.

If you use --check-first then --max-connections just needs to be one more than the maximum of --checkers and --transfers.

So for --max-connections 3 you'd use --checkers 2 --transfers 2 --check-first or --checkers 1 --transfers 1.

Setting this flag can be useful for backends which do multipart uploads to limit the number of simultaneous parts being transferred. 🎀

• --max-delete int — this tells rclone not to delete more than N files. If that limit is exceeded then a fatal error will be generated and rclone will stop the operation in progress. 🛑
• --max-delete-size SizeSuffix — rclone will stop deleting files when the total size of deletions has reached the size specified. It defaults to off.

If that limit is exceeded then a fatal error will be generated and rclone will stop the operation in progress. Same energy as above, just sized-based instead of count-based. 💅

• --max-depth int — this modifies the recursion depth for all the commands except purge.

So if you do rclone --max-depth 1 ls remote:path you will see only the files in the top level directory. Using --max-depth 2 means you will see all the files in first two directory levels and so on. It's giving very organized, very controlled. ✨

For historical reasons the lsd command defaults to using a --max-depth of 1 — you can override this with the command line flag.

You can use this command to disable recursion (with --max-depth 1).

Note that if you use this with sync and --delete-excluded the files not recursed through are considered excluded and will be deleted on the destination. Test first with --dry-run if you are not sure what will happen. 😭 Please test first bestie, I'm begging.

• --max-duration Duration — rclone will stop transferring when it has run for the duration specified. Defaults to off. ⏰

When the limit is reached all transfers will stop immediately. Use --cutoff-mode to modify this behaviour.

Rclone will exit with exit code 10 if the duration limit is reached.

• --max-transfer SizeSuffix — rclone will stop transferring when it has reached the size specified. Defaults to off.

When the limit is reached all transfers will stop immediately. Use --cutoff-mode to modify this behaviour.

Rclone will exit with exit code 8 if the transfer limit is reached.

• --cutoff-mode HARD|SOFT|CAUTIOUS — configure the behavior of --max-transfer and --max-duration. 🎚️

HARD will stop transferring immediately when rclone reaches the limit. This is the default.

SOFT will stop starting new transfers when rclone reaches the limit.

CAUTIOUS will try to prevent rclone from reaching the limit. Only applicable for --max-transfer.

• -M, --metadata — setting this flag enables rclone to copy the metadata from the source to the destination. For local backends this is 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 will use that program to map metadata from source object to 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 then enclose it in ", if you want a literal " in an argument then enclose the argument in " and double the ". See CSV encoding (https://godoc.org/encoding/csv) 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"'

Ok so quoting works like that, bestie, in case your script path has spaces or you're passing args with quotes in them 💅

Anyway bestie, it's giving simple JSON based protocol energy: input on STDIN, output on STDOUT. It gets called for every single file and directory that's copied, and heads up — it may be called concurrently, so don't go assuming you're the only one in the chat 😭

The program's whole job? Take a metadata blob on the input and turn it into a metadata blob on the output that's actually suitable for the destination backend. Glow-up, but for metadata ✨

Input to the program (via STDIN) might look like this. It's giving context, and the context matters, ok:

• 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"
  }
}

Then your program should modify the input however it wants and yeet it to STDOUT. The returned Metadata field gets used in its entirety for the destination object — and every other field? Ignored. Bye 👋

Not me translating user names and permissions and adding a lil something to the description in this example:

{
  "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"
  }
}

And yes, metadata can be removed here too. Deletion era 🗑️

An example python program to pull off the transformations above would look something like this:

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 — https://github.com/rclone/rclone/blob/master/bin/test_metadata_mapper.py 🫶

And if you wanna see what goes into the metadata mapper and what comes back out of it, hit it with -vv --dump mapper. Main character logging energy, genuinely 🔥

See the metadata section for more info.

---

🌸 --metadata-set stringArray

Specify value as string in format key=value to add metadata key with value value when uploading. Repeat it as many times as you need, girl, there's no limit here. See the metadata section for more info.

⏰ --modify-window Duration

When checking whether a file has been modified, this is the maximum allowed time difference that a file can have and still be considered equivalent.

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 will be 1s by default. Vibes-based timekeeping fr fr.

This command line flag lets you override that computed default, in case the auto-math isn't giving what you need 💅

🧵 --multi-thread-write-buffer-size SizeSuffix

When transferring with multiple threads, rclone will buffer the specified number of bytes in memory before writing to disk for each thread.

This can improve performance if the underlying filesystem does not deal well with a lot of small writes in different positions of the file — so if you see transfers being limited by disk write speed, you might wanna experiment with different values. Specially for magnetic drives and remote file systems a higher value can be useful 🌀

Nevertheless, the default of 128k should be fine for almost all use cases, so before changing it, ensure that network is not really your bottleneck. Read the room, bestie.

As a final hint, size is not the only factor: block size (or similar concept) can have an impact. In one case, they observed that exact multiples of 16k performed much better than other values. Iconic detective work honestly 🔍

🍰 --multi-thread-chunk-size SizeSuffix

Normally the chunk size for multi thread transfers is set by the backend. However some backends such as 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 SizeSuffix

When transferring files above the specified size to capable backends, rclone will use multiple threads to transfer the file (default 256M).

Capable backends are marked in the overview at https://rclone.org/overview/#optional-features as MultithreadUpload. (They need to implement either the OpenWriterAt or OpenChunkWriter internal interfaces). These include local, s3, azureblob, b2, oracleobjectstorage and smb at the time of writing. Ate, no crumbs 👑

On the local disk, rclone preallocates the file (using fallocate(FALLOC_FL_KEEP_SIZE) on unix or NTSetInformationFile on Windows, both of which takes no time) then each thread writes directly into the file at the correct place. This means that rclone won't create fragmented or sparse files and there won't be any assembly time at the end of the transfer. Clean, precise, organized ✨

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 (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) and move (https://rclone.org/commands/rclone_move/) commands, and friends copyto (https://rclone.org/commands/rclone_copyto/), moveto (https://rclone.org/commands/rclone_moveto/). Multi thread transfers will be used with rclone mount and rclone serve if --vfs-cache-mode is set to writes or above.

Most multi-thread transfers do not take additional memory, but some do (for example uploading to s3). In the worst case memory usage can be at maximum --transfers * --multi-thread-chunk-size * --multi-thread-streams or specifically for the s3 backend --transfers * --s3-chunk-size * --s3-concurrency. However you can use the --max-buffer-memory (https://rclone.org/docs/#max-buffer-memory) flag to control the maximum memory used here. Budget queen behaviour 😤

NB that this only works with supported backends as the destination but will work with any 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 (https://en.wikipedia.org/wiki/Sparse_file). 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. Not the Windows sparse file jump scare 😭

🌊 --multi-thread-streams int

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 if --multi-thread-streams isn't set.

🪄 --name-transform stringArray

--name-transform introduces path name transformations for rclone copy, rclone sync, and rclone move. These transformations enable modifications to source and destination file names by applying prefixes, suffixes, and other alterations during transfer operations. For detailed docs and examples, see convmv (https://rclone.org/commands/rclone_convmv/). Renaming slay 💅

🙈 --no-check-dest

The --no-check-dest can be used with move or copy and it causes rclone not to check the destination at all when copying files.

This means that:

• the destination is not listed, minimising the API calls
• files are always 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! Do not touch unless you know exactly why, bestie, I'm begging 🙏

🚫 --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. So like… don't? Unless you literally need it 🫠

🧭 --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're 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. Know your moment ✋

See rclone copy (https://rclone.org/commands/rclone_copy/) for an example of how to use it.

🦋 --no-unicode-normalization

Don't normalize unicode characters in filenames during the sync routine. As-is, no edits, untouched, raw 🌈

okay bestie, the unicode one (continued) 💅

Sometimes your operating system is gonna store filenames that contain unicode bits in their decomposed form (macOS, we are literally looking at you 🫵). Then some cloud storage systems go and recompose that unicode, and now you've got duplicate files the second the data gets copied back down to a local filesystem. a mess. 😭

Flip this flag on and that whole normalization situation is cancelled — every unicode character is treated as its own unique collectible. Like, by default é and é get normalized into the same character. With --no-unicode-normalization they're treated as unique characters. two icons, no overlap, periodt. ✨

---

• --no-update-modtime — with this flag on, rclone will not update modification times of remote files when they're incorrect, even though it normally would. super useful when the remote is also being synced by another tool (e.g. the Google Drive client) — nobody likes two apps fighting over the same timestamps 🙈
• --no-update-dir-modtime — same energy as above but for directories: rclone won't update modification times of remote directories if they're incorrect, even though it normally would. 🌸
• --order-by string — bestie this one controls the order in which files in the backlog get processed in rclone sync, rclone copy and rclone move. it's giving queue-manager energy 👑

The order by string is built like this. First part says what 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

Then you can slap a modifier on 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. it's giving ✨load balancing✨

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. (chaotic. unhinged. we love her. 💀)

Limitations

The --order-by flag does not do a separate pass over the data. Translation: 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. ngl it's trying its best 🥺

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. icon behaviour, no notes. 👑

---

• --partial-suffix string — 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 ". This includes the command itself: if the path to the executable contains a space, it must be quoted too. See CSV encoding (https://godoc.org/encoding/csv) for more info.

Eg:

--password-command "echo hello"
--password-command 'echo "hello with space"'
--password-command 'echo "hello with ""quotes"" and space"'
--password-command '"/path with a space/get-password.sh"'

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 (https://github.com/rclone/rclone/wiki/Windows-Powershell-use-rclone-password-command-for-Config-file-password).

• -P, --progress — this flag makes rclone update the stats in a static block in the terminal, providing a realtime overview of the transfer. main character energy fr fr 👑

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. it's so well behaved 🫶

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 (https://github.com/Azure/go-ansiterm/issues/26) is fixed all non-ASCII characters will be replaced with . when --progress is in use. rip to the emoji girlies on Windows 😭

• --progress-terminal-title — this flag, when used with -P/--progress, will print the string ETA: %s to the terminal title. cute little window title moment 🎀
• -q, --quiet — this flag will limit rclone's output to error messages only. silence, but make it ✨deliberate✨
• --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 (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_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. important bestie!! 🚨

If this flag is used when rclone comes to upload a file it will check to see if there is an existing file on the destination. If this file matches the source with size (and checksum if available) but has a differing timestamp then instead of re-uploading it, rclone will update the timestamp on the destination file. If the checksum does not match rclone will upload the new file. If the checksum is absent (e.g. on a crypt backend) then rclone will update the timestamp.

Note that some remotes can't set the modification time without re-uploading the file so this flag is less useful on them. 🙈

Normally if you are doing a modification time sync rclone will update modification times without --refresh-times provided that the remote supports checksums and the checksums match on the file. However if the checksums are absent then rclone will upload the file rather than setting the timestamp as this is the safe behaviour. safety first, always. 💜

• --retries int — retry the entire sync if it fails this many times it fails (default 3).

Some remotes can be unreliable and a few retries help pick up the files which didn't get transferred because of errors.

Disable retries with --retries 1. (one try, no mercy 💀)

• --retries-sleep Duration — this sets the interval between each retry specified by --retries. The default is 0. Use 0 to disable. 💤
• --server-side-across-configs — allow server-side operations (e.g. copy or move) to work across different configurations. 🌈

This can be useful if you wish to do a server-side copy or move between two remotes which use the same backend but are configured differently.

Note that this isn't enabled by default because it isn't easy for rclone to tell if it will work between any two configurations. (she's careful, she's ✨cautious✨)

• --size-only — normally rclone will look at modification time and size of files to see if they are equal. If you set this flag then rclone will check only the size.

This can be useful transferring files from Dropbox which have been modified by the desktop sync client which doesn't set checksums of modification times in the same way as rclone. Dropbox bestie we love you but 😭

• --stats Duration — commands which transfer data (sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/), copyto (https://rclone.org/commands/rclone_copyto/), move (https://rclone.org/commands/rclone_move/), moveto (https://rclone.org/commands/rclone_moveto/)) will print data transfer stats at regular intervals to show their progress. 📊

This sets the interval.

The default is 1m. Use 0 to disable.

If you set the stats interval then all commands can show stats. This can be useful when running other commands, check or mount for example.

Stats are logged at INFO level by default which means they won't show at default log level NOTICE. Use --stats-log-level NOTICE or -v to make them show. See the logging section for more info on log levels.

Note that on macOS you can send a SIGINFO (which is normally ctrl-T in the terminal) to make the stats print immediately. mac girlies stay winning 🍓

• --stats-file-name-length int — by default, the --stats output will truncate 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 disable any truncation of file names printed by stats. ✂️
• --stats-log-level LogLevel — log level to show --stats output at. This can be DEBUG, INFO, NOTICE, or ERROR. The default is INFO. This means at the default level of logging, which is NOTICE, the stats won't show — if you want them to then use --stats-log-level NOTICE. See the logging section for more details on log levels. 🎀
• --stats-one-line — when this is specified, rclone condenses the stats into a single line showing the most important stats only. minimalism era ✨
• --stats-one-line-date — when this is specified, rclone enables the single-line stats and prepends the display with a date string. The default is 2006/01/02 15:04:05 - 🗓️
• --stats-one-line-date-format string — bestie, if you set this, rclone flips on the single-line stats and slaps a custom date string right at the front of the display. That date string MUST be wrapped in quotes, no exceptions 💅, and the formatting syntax follows the golang specs (https://golang.org/pkg/time/#Time.Format), so go read those before you start freestyling.
• --stats-unit string — so by default, data transfer rates get printed in bytes per second, which is the same as saying --stats-unit bytes.

This option lets the data rate be printed in bits per second instead — you just say --stats-unit bits. Note that your data transfer volume is still reported in bytes tho, that part doesn't change ✨.

Also the rate is reported as a binary unit, not SI. So 1 Mbit/s equals 1,048,576 bit/s and not 1,000,000 bit/s. Math girlies stay winning 🎀

• --suffix string — when you're using sync (https://rclone.org/commands/rclone_sync/), copy (https://rclone.org/commands/rclone_copy/) or move (https://rclone.org/commands/rclone_move/), any files that would have been overwritten or deleted get the suffix added to them. And if a file already exists with that same path (like, after the suffix has been added), then it just gets overwritten. Sorry babe 💀

Heads up: the remote you're using must support server-side move or copy, and you must use the same remote as the destination of the sync.

This is for use with files to add the suffix in the current directory, or with --backup-dir. Peep --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 for any files which would have been updated or deleted have .bak added.

If you're using rclone sync with --suffix and without --backup-dir, then fr it's recommended to put a filter rule in excluding the suffix, otherwise the sync will delete the backup files 😭 Like:

rclone sync --interactive /path/to/local/file remote:current --suffix .bak --exclude "*.bak"

• --suffix-keep-extension — when you're using --suffix, setting this makes rclone put the SUFFIX before the extension of the files that it backs up, rather than after.

So let's 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 would be backed up to file-2019-01-01.txt. This can be super helpful to make sure the suffixed files can still be opened 👑

And if a file has two (or more) extensions and the second (or subsequent) extension is recognised as a valid mime type, then the suffix will go before that 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. iykyk 💅

• --syslog — on capable OSes (so like, not Windows or Plan9), send all log output to syslog.

This can be useful 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 string — specify the directory rclone will use for temporary files, to override the default. Make sure the directory exists and has accessible permissions, mmkay? 🙈

By default the operating system's temp directory will be 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 overriding the default with this option, the specified path will be set as value of environment variable TMPDIR on Unix systems and TMP and TEMP on Windows.

You can use the config paths (https://rclone.org/commands/rclone_config_paths/) command to see the current value 👀

• --tpslimit float — caps transactions per second at this number. Default is 0, which means unlimited transactions per second.

A transaction is roughly defined as an API call; its exact meaning will depend 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.

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 the number of transactions per second from rclone is causing a problem with the cloud storage provider (e.g. getting you banned or rate limited 😭 the horror).

This can be very 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 not apply to the local backend or the Storj backend.

See also --tpslimit-burst.

• --tpslimit-burst int — max burst of transactions for --tpslimit (default 1).

Normally --tpslimit will do exactly the number of transaction per second specified. However 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 then it can do 10 transactions very quickly before they are limited again.

This may be used to increase performance of --tpslimit without changing the long term average number of transactions per second. slay 💅

• --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 new copy. the way that wastes so much 😭

An rclone sync with --track-renames runs like a normal sync, but it keeps track of objects which exist in the destination but not in the source (which would normally be deleted), and which objects exist in the source but not the destination (which would normally be transferred). These objects are then candidates for renaming ✨

After the sync, rclone matches up the source only and destination only objects using the --track-renames-strategy 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 and the destination must have a compatible hash.

If the destination does not support server-side copy or move, rclone will fall back to the default behaviour and log 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 (memory girlies, pay attention).

Note also that --track-renames is incompatible with --delete-before and will select --delete-after instead of --delete-during.

• --track-renames-strategy string — 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.

Using --track-renames-strategy modtime or leaf can enable --track-renames support for encrypted destinations 👑

Note that the hash strategy is not supported with encrypted destinations.

• --delete-(before,during,after) — this option lets you specify when files on your destination get deleted when you sync folders.

Specifying the value --delete-before will delete all files present on the destination, but not on the source, before starting the transfer of any new or updated files. This uses two passes through the file systems, one for the deletions and one for the copies 👯

Specifying --delete-during will delete files while checking and uploading files. This is the fastest option and uses the least memory ⚡

Specifying --delete-after (the default value) will delay deletion of files until all new/updated files have been successfully transferred. The files to be deleted are collected in the copy pass, then deleted after the copy pass has completed successfully. The files to be deleted are held in memory so this mode may use more memory. This is the safest mode as it will only delete files if there have been no errors subsequent to that. If there have been errors before the deletions start then you will get the message not deleting files as there were IO errors. dramatic but for your own good 🫶

• --fast-list — when doing anything which involves a directory listing (e.g. sync, copy, ls - in fact nearly every command), rclone has different strategies to choose from.

The basic strategy is to list one directory and processes it before using more directory lists to process any subdirectories. This is a mandatory backend feature, called List, which means it is supported by all backends. This strategy uses small amount of memory, and because it can be parallelised it is fast for operations involving processing of the list results ✨

Some backends provide the support for an alternative strategy, where all files beneath a directory can be listed in one (or a small number) of transactions. Rclone supports this alternative strategy through an optional backend feature called ListR (https://rclone.org/overview/#listr). You can see in the storage system overview documentation's optional features (https://rclone.org/overview/#optional-features) section which backends it is enabled for (these tend to be the bucket-based ones, e.g. S3, B2, GCS, Swift). This strategy requires fewer transactions for highly recursive operations, which is important on backends where this is charged or heavily rate limited. It may be faster (due to fewer transactions) or slower (because it can't be parallelized) depending on different parameters, and may require more memory if rclone has to keep the whole listing in memory. it's giving trade-offs, bestie 💅

Which listing strategy rclone picks for a given operation is complicated, but in general it tries to choose the best possible. It will prefer ListR in situations where it doesn't need to store the listed files in memory, e.g. for unlimited recursive ls command variants. In other situations it will prefer List, e.g. for sync and copy, where it needs to keep the listed files in memory, and is performing operations on them where parallelization may be a huge advantage 🔥

Rclone can't read your mind about which strategy eats less, so it gives you two little dials instead. You can stop rclone from using ListR at all by killing the feature with the --disable option (--disable ListR), or you can let rclone use ListR even where it'd normally say "nah, too much memory" by flipping --fast-list. Either way, rclone should always produce identical results — like, genuinely identical. And if you slap --disable ListR or --fast-list on a remote that doesn't even support ListR? Nothing happens. rclone just shrugs and ignores it. 🫶

Rule of thumb bestie: if you're paying for transactions AND your whole sync listing fits in memory, then yeah, --fast-list is the move, recommended, slay. But if you've got a very big sync going down, do NOT use --fast-list, or you will run out of memory and it's giving tragedy. Run some tests, compare, and if you're in doubt just leave the default — let rclone decide, i.e. not use --fast-list. Periodt.

⏱️ --timeout Duration

This sets the IO idle timeout. If a transfer has started but then becomes idle for this long, it's considered broken and disconnected. Ghosted, basically. 💀

The default is 5m. Set to 0 to disable.

🔥 --transfers int

The number of file transfers to run in parallel. Sometimes it's useful to set this to a smaller number if your remote is being dramatic and giving a lot of timeouts, or bigger if you have lots of bandwidth and a fast remote. Main character energy.

The default is to run 4 file transfers in parallel.

Look at --multi-thread-streams if you would like to control single file transfers.

🌀 -u, --update

This forces rclone to skip any files which exist on the destination and have a modified time that is newer than the source file.

This can be useful in avoiding needless transfers when transferring to a remote which doesn't support modification times directly (or when using --use-server-modtime to avoid extra API calls) as it is more accurate than a --size-only check and faster than using --checksum. On such remotes (or when using --use-server-modtime) the time checked will be the uploaded time.

If an existing destination file has a modification time older than the source file's, it will be updated if the sizes are different. If the sizes are the same, it will 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 will be updated if the sizes are different. The checksum will not be checked in this case unless the --checksum flag is provided.

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 do not support mod times, and instead use uploaded times. However, if the backend does not support checksums, note that syncing or copying within the time skew window may still result in additional transfers for safety. 💅

🧠 --use-mmap

If this flag is set then 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 can be returned to the OS immediately when it is finished with.

If this flag is not set then rclone will allocate and free the buffers using the Go memory allocator which may use more memory as memory pages are returned less aggressively to the OS.

It is possible this does not work well on all platforms so it is disabled by default; in the future it may be enabled by default. 🙈

🕰️ --use-server-modtime

Some object-store backends (e.g, Swift, S3) do not preserve file modification times (modtime). On these backends, rclone stores the original modtime as additional metadata on the object. By default it will make an API call to retrieve the metadata when the modtime is needed by an operation.

Use this flag to disable the extra API call and rely instead on the server's modified time. In cases such as a local to remote sync using --update, knowing the local file is newer than the time it was last uploaded to the remote is sufficient. In those cases, this flag can speed up the process and reduce the number of API calls necessary. Efficiency queen 👑

This flag is only supported on certain backends and will be silently ignored on unsupported backends. Supported backends include azureblob, oracleobjectstorage, s3, swift.

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. Not the vibe fr fr.

🗣️ -v, -vv, --verbose

With -v rclone will tell you about each file that is transferred and a small number of significant events.

With -vv rclone will become very verbose telling you about every file it considers and transfers. Please send bug reports with a log with this setting.

When setting verbosity as an environment variable, use RCLONE_VERBOSE=1 or RCLONE_VERBOSE=2 for -v and -vv respectively.

✨ -V, --version

Prints the version number

🔐 SSL/TLS options

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 set of configuration for SSL/TLS which you can find in their documentation. Don't mix them up bestie, they're different girlies. 🎀

📜 --ca-cert stringArray

This loads the PEM encoded certificate authority certificates and uses it to verify the certificates of the servers rclone connects to.

If you have generated certificates signed with a local CA then you will need this flag to connect to servers using those certificates.

🪪 --client-cert string

This loads the PEM encoded client side certificate.

This is used for mutual TLS authentication (https://en.wikipedia.org/wiki/Mutual_authentication).

The --client-key flag is required too when using this.

🗝️ --client-key string

This loads the PEM encoded client side private key used for mutual TLS authentication. Used in conjunction with --client-cert.

Supported types are:

• Unencrypted PKCS#1 ("BEGIN RSA PRIVATE KEY")
• Unencrypted PKCS#8 ("BEGIN PRIVATE KEY")
• Encrypted PKCS#8 ("BEGIN ENCRYPTED PRIVATE KEY")
• Legacy PEM encryption (e.g., DEK-Info headers), which are automatically detected.

🤫 --client-pass string

This can be used to supply an optional password to decrypt the client key file.

NB the password should be obscured so it should be the output of rclone obscure YOURPASSWORD.

🚫 --no-check-certificate

--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. 😭 Scary.

This option defaults to false.

This should be used only for testing. Do not ship this, I'm begging.

🔒 Configuration encryption

Your configuration file contains information for logging in to your cloud services. This means that you should keep your rclone.conf file in a secure location. It's literally your diary but for cloud credentials.

If you are in an environment where that isn't possible, you can add a password to your configuration. This means that you will 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>

Your configuration is now encrypted, and every time you start rclone you will have to supply the password. See below for details. In the same menu, you can change the password or completely remove encryption from your configuration.

There is no way to recover the configuration if you lose your password. 🌸 Gone. Deleted. No take-backs. Write it down somewhere safe.

You can also use

• rclone config encryption set (https://rclone.org/commands/rclone_config_encryption_set/) to set the config encryption directly
• rclone config encryption remove (https://rclone.org/commands/rclone_config_encryption_remove/) to remove it
• rclone config encryption check (https://rclone.org/commands/rclone_config_encryption_check/) to check that it is encrypted properly.

rclone uses nacl secretbox (https://godoc.org/golang.org/x/crypto/nacl/secretbox) which in turn uses XSalsa20 and Poly1305 to encrypt and authenticate your configuration with secret-key cryptography. The password is SHA-256 hashed, which produces the key for secretbox. The hashed password is not stored. Obsessed with the security actually. 💜

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 is safe in your environment, you can set the RCLONE_CONFIG_PASS environment variable to contain your password, in which case it will 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 would 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 on standard output. This script should have a fully specified path name and not rely on any environment variables. 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"

...so like, if your passwordstore password manager is the one holding the password for your rclone config, the script method means that password is mainly protected by the passwordstore system itself 💖. It's never sitting there in the clear inside scripts, and it's not available for snooping with the standard commands either. And ngl bestie, this matters: with long-running rclone sessions it's quite possible for copies of passwords to get innocently captured in log files, terminal scroll buffers, etc. 🙈 So using the script method to hand over the password levels up your config password security considerably. ✨

If you're running rclone inside a script, and you're not using the --password-command method, you might wanna disable password prompts altogether. Do that by passing --ask-password=false to rclone. What that does: rclone will fail instead of asking for a password, if RCLONE_CONFIG_PASS doesn't contain a valid password and --password-command hasn't been supplied. No sneaky hanging prompt, just a clean fail. 💅

And whenever you run commands that might be affected by options in a configuration file, rclone goes looking for an existing file using the rules described above, and loads whatever it finds. If what it finds is an encrypted file, that includes decrypting it — with the possible consequence of a password prompt 😭. So if you're running a command line you know isn't actually pulling anything from such a config file, you can dodge the whole load 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 don't operate on backends — like completion. But it will be relevant for commands that do operate on backends in general, yet get used without referencing a stored remote — like listing local filesystem paths, or connection strings: rclone --config="" ls . 👑

---

🌸 Configuration encryption cheatsheet 🌸

Okay so you can quickly apply configuration encryption with no plain-text at rest or in transfer. Here's the detailed tea for the 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. So let's install the "pass" utility using a package manager, e.g. apt install pass, yum install pass, etc. (https://www.passwordstore.org/#download); 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, and select option s) Set configuration password
• Add/update the password from previous steps

---

🛠️ Developer options 🛠️

These options are literally your bestie when you're developing or debugging rclone. There are also some more remote-specific options that aren't documented here — those are used for testing, and they start with the remote name, e.g. --drive-test-option — see the docs for the remote in question. 💜

• --cpuprofile string — Write CPU profile to a file. This can be analysed with go tool pprof.
• --memprofile string — Write memory profile to a file. This can be analysed with go tool pprof.
• --dump DumpFlags — The --dump flag takes a comma separated list of flags to dump info about.

Note that some headers, such as Accept-Encoding, may not be correct as shown 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:

• headers — dumps HTTP headers. Any Authorization: headers will be excluded, but output may still contain sensitive information 😬. Can be very verbose. Useful for debugging only. Use auth if you do want the Authorization: headers.
• auth — dumps HTTP headers like headers, but also includes any Authorization: headers. This means the output will probably contain sensitive information. Use headers to dump without Authorization: headers. Can be very verbose. Useful for debugging only. This flag also makes the debug log of the config process (e.g. rclone config -vv) show answers to questions, passwords and tokens which are otherwise redacted. 💀
• bodies — dumps 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.
• requests — is similar to bodies, but dumps the request bodies and the response headers. Useful for debugging download problems.
• responses — is similar to bodies, but dumps the response bodies and the request headers. Useful for debugging upload problems.
• filters — dumps the filters. Useful to see exactly what include and exclude options are filtering on.
• goroutines — dumps a list of the running go-routines at the end of the command.
• openfiles — dumps a list of the open files at the end of the command. It uses the lsof Unix command to do that, so you'll need that installed to use it.
• mapper — dumps 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.
• curl — dumps the HTTP request as a curl command. Can be used with the other HTTP debugging flags (e.g. requests, bodies). By default the auth will be masked — use with auth to have the curl commands with authentication too.
• errors — only dumps the HTTP transactions which fail with a retryable error — that is a transport error, an HTTP 429 (too many requests) or an HTTP 5xx server error. The other dump flags control what is dumped, so for example use --dump errors,bodies to dump the headers and bodies of failed transactions only. On its own --dump errors dumps the headers. This lets you capture first-failure diagnostics without the noise of dumping every transaction. May contain sensitive info.
• trace — logs connection level events for each HTTP transaction using Go's net/http/httptrace — DNS resolution, TCP connect, TLS handshake (including the negotiated TLS version, cipher, ALPN protocol and server certificate), connection reuse, request write and time to first response byte. Each line is tagged with the time elapsed since the start of the transaction so you can see where the time goes ⏱️. This is complementary to the other dump flags: it shows how the connection behaved rather than what was sent, so it's useful for debugging connectivity, DNS, TLS, proxy and keep-alive problems. It does not dump headers or bodies — combine it with headers or bodies for that.

---

🦋 Filtering 🦋

For the filtering options:

• --delete-excluded
• --filter
• --filter-from
• --exclude
• --exclude-from
• --exclude-if-present
• --include
• --include-from
• --files-from
• --files-from-raw
• --files-from0
• --min-size
• --max-size
• --min-age
• --max-age
• --hash-filter
• --dump filters
• --metadata-include
• --metadata-include-from
• --metadata-exclude
• --metadata-exclude-from
• --metadata-filter
• --metadata-filter-from

See the filtering section (https://rclone.org/filtering/). ✨

---

🎀 Remote control 🎀

For the remote control options and for instructions on how to remote control rclone:

• --rc
• Anything starting with --rc-

See the remote control section (https://rclone.org/rc/). 👑

---

📋 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 option, rclone will redirect Error, Info and Debug messages along with standard error to a file.

If you use the --syslog flag then rclone will log to syslog, and the --syslog-facility controls 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 lets scripts 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. Periodt. 💅

okay bestie, real talk about how rclone handles errors while it's out there doing its thing ✨ — it just accumulates them as it goes along, like a little goblin collecting receipts 💀, and it only exits with a non-zero exit code if (after retries) there were still failed transfers. So a blip that fixed itself? not a problem, she moved on 💅

For every error that gets counted there's a high priority log message (visible with -q) showing the message AND which file caused the drama 👀. A high priority message also pops up when a retry is starting, so you know that any previous error messages might not be valid after the retry — like okay girl we're trying again, don't come for me. And if rclone has done a retry, it'll log a high priority message if the retry was successful 🎀. Good girl.

✨ List of exit codes ✨

• 0 — Success 🎉 ate, no crumbs
• 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 🌍

Bestie. You can configure rclone ENTIRELY using environment variables. Not joking. These can be used to set defaults for options or for config file entries. main character config energy, no config file required 👑

Options

Every option in rclone can have its default set by an environment variable. Every. Single. One. 💅

So how do you find the name of the environment variable? Recipe time, follow along:

1. Take the long option name
2. Strip the leading --
3. Change - to _
4. Make it upper case
5. Prepend RCLONE_

That's it, that's the whole spell 🧚

For example, if you want to always set --stats 5s, you set the environment variable RCLONE_STATS=5s. And if you set stats on the command line, that will override the environment variable setting — command line is the main character here, no cap.

Or, if you always want to use the trash in drive — that's --drive-use-trash — you set RCLONE_DRIVE_USE_TRASH=true.

Verbosity is slightly different, because of course she is 🙄 — the environment variable equivalent of --verbose or -v is RCLONE_VERBOSE=1, or for -vv it's RCLONE_VERBOSE=2.

The same parser is used for the options and the environment variables, so they take exactly the same form. Symmetry, we love to see it 🫶

The options that got 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, because 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 (https://godoc.org/encoding/csv) string. For example:

• RCLONE_EXCLUDE="*.jpg" is equivalent to --exclude "*.jpg"
• RCLONE_EXCLUDE="*.jpg,*.png" is equivalent to --exclude "*.jpg" --exclude "*.png"
• RCLONE_EXCLUDE='"*.jpg","*.png"' is equivalent to --exclude "*.jpg" --exclude "*.png"
• RCLONE_EXCLUDE='"/directory with comma , in it /**"' is equivalent to --exclude "/directory with comma , in it /**"

If stringArray options are defined as environment variables and as options on the command line, then all the values will be used. Both. Everything. Greedy and valid 💖

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 — go read those, bestie, they're right there.

To find the name of the environment variable you need to set, you take:

RCLONE_CONFIG_ + name of remote + _ + name of config file option

and make it all uppercase. One implication here that you need to know: the remote's name must be convertible into a valid environment variable name, so it can only contain letters, digits, or the _ (underscore) character. That's the vibe check the name has to pass ✅

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. No _TYPE, no remote. Periodt.

Note that the name of a remote created using environment variable is case insensitive, in contrast to regular remotes stored in a config file as documented above. You must write the name in uppercase in the environment variable, but as seen from the 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. It's giving "one set of keys to rule them all" 💀

Also, note that now rclone has connection strings, it's probably easier to use those instead, which makes the above example:

rclone lsd :s3,access_key_id=XXX,secret_access_key=XXX:

Look how much shorter. She ate and left no crumbs 🍓

Precedence

The various different methods of backend configuration are read in this order, and the first one with a value is the one that gets used. First come, first served, no takebacks 👇

1. Parameters in connection strings, e.g. myRemote,skip_links:
2. Flag values as supplied on the command line, e.g. --skip-links
3. Remote specific environment vars, e.g. RCLONE_CONFIG_MYREMOTE_SKIP_LINKS (see above)
4. Backend-specific environment vars, e.g. RCLONE_LOCAL_SKIP_LINKS
5. Backend generic environment vars, e.g. RCLONE_SKIP_LINKS
6. Config file, e.g. skip_links = true
7. 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. She said what she said 💅

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:

1. Flag values as supplied on the command line, e.g. --stats 5s
2. Environment vars, e.g. RCLONE_STATS=5s
3. 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. Queen behaviour 👑
  • 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. She's telling on herself, helpfully 🎀

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 💻

okay so bestie, listen — some of the configurations (specifically the ones involving oauth2) need an internet-connected web browser. like, non-negotiable ✨

So if you're trying to set rclone up on a remote or headless machine that has no browser at all (think: a NAS, or a server sitting in a datacenter somewhere), you're gonna need an alternative way to configure it. There are three ways to do it, and we're going through all of them below. 🫶

🔑 Configuring using rclone authorize

On the headless machine, run rclone config, but when it asks you "Use web browser to automatically authenticate rclone with remote?" — you answer N. no browser weirdness, we're doing this the manual way 💅

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> 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, over on your main desktop machine, you run rclone authorize (✨ https://rclone.org/commands/rclone_authorize/ — that's the link, keep it, it slays).

rclone authorize "onedrive"
NOTICE: Make sure your Redirect URL is set to "http://localhost:53682/" in your custom config.
NOTICE: If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth?state=xxxxxxxxxxxxxxxxxxxxxx
NOTICE: Log in and authorize rclone for access
NOTICE: Waiting for code...

Got code
Paste the following into your remote machine --->
SECRET_TOKEN
<---End paste

Then it's back to the headless machine, and you paste in the code girlie 🎀

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>

📁 Configuring by copying the config file

Rclone keeps all of its configuration in a single file. Which is honestly iconic of it, because that means you can just copy it over to configure a remote rclone — although some backends do not support reusing the same configuration, so definitely consult your backend documentation to be sure before you go copy-pasting things around 💀

Start by running rclone config to create the configuration file on your desktop machine.

rclone config

Then locate the file by running rclone config file.

$ rclone config file
Configuration file is stored at:
/home/user/.rclone.conf

Finally, transfer the file to the remote machine (scp, cut paste, ftp, sftp, whatever works for you, no judgement) and place it in the correct location — use rclone config file on the remote machine to find out where that is. 🦋

🌈 Configuring using SSH Tunnel

If you have an SSH client installed on your local machine, you can set up an SSH tunnel to redirect the port 53682 into the headless machine using this command:

ssh -L localhost:53682:localhost:53682 username@remote_server

Then on the headless machine run rclone config and answer Y to the question "Use web browser to automatically authenticate rclone with remote?". yes queen, we're doing the browser thing now, you've got a tunnel 🧚

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> y
NOTICE: Make sure your Redirect URL is set to "http://localhost:53682/" in your custom config.
NOTICE: If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth?state=xxxxxxxxxxxxxxxxxxxxxx
NOTICE: Log in and authorize rclone for access
NOTICE: Waiting for code...

Finally, copy and paste the presented URL http://127.0.0.1:53682/auth?state=xxxxxxxxxxxxxxxxxxxxxx into the browser on your local machine, complete the auth, and you are DONE. periodt. 💜

---

🌸 Filtering, includes and excludes 🌸

Filter flags decide which files the rclone sync, move, ls, lsl, md5sum, sha1sum, size, delete, check and similar commands actually apply to. iykyk.

They're specified in terms of path/file name patterns; path/file lists; file age and size; or the presence of a file in a directory. And for bucket based remotes that don't even have a concept of directories — those apply the filters to object key, age and size in an analogous way. 🫶

⚠️ rclone purge does not obey filters. like, at all. be careful bestie.

To test filters without any risk of damage to your data, apply them to rclone ls, or use the --dry-run and -vv flags. safety first 💖

Rclone filter patterns can only be used in filter command line options — not in the specification of a remote.

E.g. rclone copy "remote:dir*.jpg" /path/to/dir does not have a filter effect. rclone copy remote:dir /path/to/dir --include "*.jpg" does.

Important 🚨 Avoid mixing any two of --include..., --exclude... or --filter... flags in an rclone command. The results might not be what you expect. Instead use a --filter... flag. (fr fr, just don't do it.)

🎀 Patterns for matching path/file names

✨ Pattern syntax

Here is a formal definition of the pattern syntax, 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 at https://golang.org/pkg/regexp/syntax/) 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 is for advanced users who want 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 does not start with / then it is matched starting at the end of the path/file name — but it only matches a complete path element, so 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. lowkey important.

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 running on Microsoft Windows. yes even then. especially then.

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. However this does not provide absolute control over the matching, so for advanced users rclone also provides a regular expression syntax. 😌

Rclone generally accepts Perl-style regular expressions, the exact syntax is defined in the Go regular expression reference at https://golang.org/pkg/regexp/syntax/. 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 is 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

{{start[^/]*end\.jpg}}

Not

{{start.*end\.jpg}}

Which will match a directory called start with a file called end.jpg in it, as the .* will match / characters. that's the trap bestie, don't fall in it 😭

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 ✨

okay bestie, here's the whole vibe of how patterns hit, laid out so it actually makes sense 💖

• Wildcard — pattern *.jpg matches /file.jpg and /dir/file.jpg, but not /file.png or /dir/file.png
• Rooted — pattern /*.jpg matches /file.jpg and /file2.jpg, but not /file.png or /dir/file.jpg
• Alternates — pattern *.{jpg,png} matches /file.jpg and /dir/file.png, but not /file.gif or /dir/file.gif
• Path Wildcard — pattern dir/** matches /dir/anyfile and /subdir/dir/subsubdir/anyfile, but not file.png or /subdir/file.png
• Any Char — pattern *.t?t matches /file.txt and /dir/file.tzt, but not /file.qxt or /dir/file.png
• Range — pattern *.[a-z] matches /file.a and /dir/file.b, but not /file.0 or /dir/file.1
• Escape — pattern *.\?\?\? matches /file.??? and /dir/file.???, but not /file.abc or /dir/file.def
• Class — pattern *.\d\d\d matches /file.012 and /dir/file.345, but not /file.abc or /dir/file.def
• Regexp — pattern *.{{jpe?g}} matches /file.jpeg and /dir/file.jpg, but not /file.png or /dir/file.jpeeg
• Rooted Regexp — pattern /{{.*\.jpe?g}} matches /file.jpeg and /file.jpg, but not /file.png or /dir/file.jpg

---

🌸 How filter rules are applied to files 🌸

ngl this is the part everyone skips and then everyone gets confused, so let's NOT 💅

Rclone path/file name filters are made up of one or more of the following 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, --files-from-raw and --files-from0 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 (https://golang.org/pkg/regexp/syntax/)

---

🦋 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.

Rclone commands can use directory filter rules to determine whether they recurse into subdirectories. This potentially optimises access to a remote by avoiding listing unnecessary directories. Whether optimisation is desirable depends on the specific filter rules and source remote content.

If any regular expression filters are in use, then no directory recursion optimisation is possible, as rclone must check every path against the supplied regular expression(s).

Directory recursion optimisation occurs if either:

• A source remote does not support the rclone ListR primitive. local, sftp, Microsoft OneDrive and WebDAV do not support ListR. Google Drive and most bucket type storage do. Full list (https://rclone.org/overview/#optional-features)
• On other remotes (those that support ListR), if the rclone command is not 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. To view 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.

E.g. rclone ls remote: --include /directory/ will not match any files. Because it is 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.

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 completely excluded 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.

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.

When using pattern list syntax, if a pattern item contains either / or **, then rclone will not 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 not the result. 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.

---

🎀 --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, --files-from-raw or --files-from0 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}\]*'

---

💜 --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, --files-from-raw or --files-from0 flags.

--exclude-from followed by - reads filter rules from standard input.

---

🌈 --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, --files-from-raw or --files-from0 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.

E.g. multiple rclone copy commands can be smooshed into one with --include and a pattern-list, bestie:

rclone copy /vol1/A remote:A
rclone copy /vol1/B remote:B

is literally the same as:

rclone copy /vol1 remote: --include "{A,B}/**"

E.g. rclone ls remote:/wheat --include "??[^[:punct:]]*" lists the files in the remote: directory wheat (and all its subdirectories, slay) whose third character is not punctuation. This one uses an ASCII character class — the docs live at https://golang.org/pkg/regexp/syntax/. 💅

--include-from - Read include patterns from file

Adds path/file names to an rclone command based on rules in a named file. The file is a lil list of remarks and pattern rules, okay?

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's equivalent to rclone ls remote: --include file2.avi --include "*.jpg". ✨

This flag can be repeated (go off). 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. So 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, --files-from-raw or --files-from0 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, --files-from-raw or --files-from0 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, bestie.

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. 💖

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 !. 😭

--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, --files-from-raw or --files-from0 is used.

--files-from expects a list of files as its input. Leading or trailing whitespace is stripped from the input lines. Lines starting with # or ; are ignored.

--files-from followed by - reads the list of files from standard input.

Rclone commands with a --files-from flag traverse the remote, treating the names in --files-from as a set of filters.

If the --no-traverse and --files-from flags are used 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 requires typically 1 API call. This can be efficient for a short --files-from list and a remote containing many files. 🔥

Rclone commands do not error if any names in the --files-from file are missing from the source remote.

The --files-from flag can be repeated in a single rclone command to read path/file names from more than one file. The files are read from left to right along the command line.

Paths within the --files-from file are interpreted as starting with the root specified in the rclone command. Leading / separators are ignored. See --files-from-raw if you need the input to be processed in a raw manner.

E.g. for a file files-from.txt:

# comment
file1.jpg
subdir/file2.jpg

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

--files-from-raw - 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. rclone lsf (at https://rclone.org/commands/rclone_lsf/) has a compatible format that can be used to export file lists from remotes for input to --files-from-raw. 🦋

--files-from0 - Read NUL separated list of source-file names

This flag is the same as --files-from-raw except that input is split on NUL (\0) characters instead of newlines. This allows handling filenames that contain embedded newline characters.

It is similar to the -print0 option of find and the -0 option of xargs.

E.g. to copy files listed by find:

find /path -print0 | rclone copy --files-from0 - / remote:path

--ignore-case - make searches case insensitive

By default, rclone filter patterns are case sensitive. The --ignore-case flag makes all of the filters patterns on the command line case insensitive.

E.g. --include "zaphod.txt" does not match a file Zaphod.txt. With --ignore-case a match is made. ✨

Quoting shell metacharacters

Rclone commands with filter patterns containing shell metacharacters may not work as expected in your shell and may require quoting. (No cap.)

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.

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

--min-size - Don't transfer any file smaller than this

Controls the minimum size file within the scope of an rclone command. Default units are KiB 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 at https://rclone.org/docs/#size-options for more info.

--max-size - Don't transfer any file larger than this

Controls the maximum size file within the scope of an rclone command. Default units are KiB 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 at https://rclone.org/docs/#size-options for more info.

--max-age - 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 files 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 at https://rclone.org/docs/#time-options for valid formats.

--min-age - 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 files 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 at https://rclone.org/docs/#time-options for valid formats. 🌸

--hash-filter — deterministically pick a subset of files ✨

Okay so the --hash-filter flag lets you grab a deterministic subset of your files, and it's lowkey iconic for:

1. Running big sync operations spread across multiple machines.
2. Checking a subset of files for bitrot.
3. Any other operations where a sample of files is required.

Syntax 🎀

The flag takes two parameters expressed as a fraction:

--hash-filter K/N

• N: the total number of partitions (must be a positive integer).
• K: the specific partition to select (an integer from 0 to N).

For example:

• --hash-filter 1/3: selects the first third of the files.
• --hash-filter 2/3 and --hash-filter 3/3: select the second and third partitions, respectively.

Each partition is non-overlapping, ensuring all files are covered without duplication. No cap, the math is mathing. 💅

Random Partition Selection 🎲

Use @ as K to randomly select a partition:

--hash-filter @/M

For example, --hash-filter @/3 will randomly select a number between 0 and 2. This will stay constant across retries. (Very demure, very consistent.) 🫶

How It Works 🧠

• Rclone takes each file's full path, normalizes it to lowercase, and applies Unicode normalization.
• It then hashes the normalized path into a 64 bit number.
• The hash result is reduced modulo N to assign the file to a partition.
• If the calculated partition does not match K the file is excluded.
• Other filters may apply if the file is not excluded.

Important: Rclone will traverse all directories to apply the filter. 👀

Usage Notes 💖

• Safe to use with rclone sync; source and destination selections will match.
• Do not use with --delete-excluded, as this could delete unselected files.
• Ignored if --files-from, --files-from-raw or --files-from0 is used.

Examples 🌈

Dividing files into 4 partitions

Assuming the current directory contains file1.jpg through file9.jpg:

$ rclone lsf --hash-filter 0/4 .
file1.jpg
file5.jpg

$ rclone lsf --hash-filter 1/4 .
file3.jpg
file6.jpg
file9.jpg

$ rclone lsf --hash-filter 2/4 .
file2.jpg
file4.jpg

$ rclone lsf --hash-filter 3/4 .
file7.jpg
file8.jpg

$ rclone lsf --hash-filter 4/4 . # the same as --hash-filter 0/4
file1.jpg
file5.jpg

Syncing the first quarter of files

rclone sync --hash-filter 1/4 source:path destination:path

Checking a random 1% of files for integrity

rclone check --download --hash-filter @/100 source:path destination:path

---

Other flags ✨

--delete-excluded — delete files on dest excluded from sync

Important this flag is dangerous to your data — use with --dry-run and -v first. 😭 Like fr fr, do the dry run.

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.

--dump filters — dump the filters to the output

Dumps the defined filters to standard output in regular expression format.

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.

Metadata filters 🏷️

The metadata filters work in a very similar way to the normal file name filters, except they match metadata (https://rclone.org/docs/#metadata) 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.

Common pitfalls 💀

The most frequent filter support issues on the rclone forum (https://forum.rclone.org/) 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

---

🌸 rclone gui 🌸

The rclone gui command starts the official Web GUI that comes bundled with rclone. Bestie, it's built in. We're not even joking. ✨

With this command, rclone can serve a web-based GUI (graphical user interface) that is accessible from a normal web browser. 🦋

Run it in a terminal and rclone will initialize and then start the GUI.

rclone gui

This will produce logs like this. The terminal window needs to stay open to continue to run the GUI:

2026/04/14 11:36:04 NOTICE: Serving remote control on http://127.0.0.1:50803/
2026/04/14 11:36:04 NOTICE: Serving GUI on http://127.0.0.1:50802/
2026/04/14 11:36:04 NOTICE: GUI available at http://127.0.0.1:50802/login?pass=XXX&url=http%3A%2F%2F127.0.0.1%3A50803%2F&user=gui

You can also add debugging flags when running the GUI, such as -v, which will show more logging output from the rc server.

Using the GUI 🎀

Once the browser opens, you will be presented with the Dashboard, the main screen where you can see the status of your remotes and system.

At the top, starting from the left, you will see a series of tabs you can click on. On the right side you will have the logout button and potentially an "Update available" message if a new rclone version has been released.

Dashboard 📊

See live metrics, learn if your remotes are near capacity, and read the changelog for the current version.

Explorer 🔍

Explore and manage both local disks and remotes, download files and directories and start transfers.

Remotes ☁️

Scroll the list of remotes and tap on it to navigate to the explorer. There you can navigate the contents of your remotes, transfer, download, and even upload files.

Mounts 💾

Mount remotes as local drives on your computer and check on your existing mounts.

Serves 🌐

Get quick info about your active serve instances, and start new ones.

Settings ⚙️

Edit your rclone.conf file directly, set logging flags, and performance parameters.

How it works 🧠

When you run rclone gui this is what happens

• Rclone starts the remote control API ("rc").
• Rclone starts a second server to serve the Web GUI.
• If a port, username or password is not specified, then missing values will be auto-generated.
• Unless --no-open-browser is passed, a browser window will open.
• The URL already contains the username & password, in which case the GUI will use those values and log you in automatically.

Security 🔐

It's important to think first about what rclone has access to and what you might be sharing.

A few good measures:

• Don't use --no-auth (this is for testing only).
• Do not expose to the local network (eg with --api-addr :5572 --addr :8080) unless you trust all devices on your local network. Prefer 127.0.0.1 or localhost (the default).
• Use a strong password and non-obvious usernames like "admin" or "rclone" if you are using --user and --pass.
• If you want to host it on a server and access it remotely, make sure you're only exposing the GUI and not the RC API. They listen on different ports.

If you want to access it remotely but want to avoid running a proxy and exposing ports, you can use Cloudflare Tunnels or localhost.run or Tailscale (all free).

Options 💅

• --addr stringArray — IPaddress:Port for the GUI server (default auto-chosen localhost port)
• --api-addr stringArray — IPaddress:Port for the RC API server (default auto-chosen localhost port)
• --enable-metrics — Enable OpenMetrics/Prometheus compatible endpoint at /metrics
• -h, --help — help for gui
• --no-auth — Don't require auth for the RC API
• --no-open-browser — Skip opening the browser automatically
• --pass string — Password for RC authentication
• --user string — User name for RC authentication

History 📜

In v1.74 the GUI was redone and embedded within rclone for ease of use. The GUI bundle ships as a compressed zip embedded in the rclone binary and is served from the zip at runtime.

---

👑 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.

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 (https://rclone.org/commands/rclone_rcd/) command.

Security 🚨

Access to the rc API is equivalent to shell access as the user running rclone. Treat the rc port as you would an interactive login on the host.

Any caller who can reach the API (and pass authentication, if it is enabled) can, among other things:

• Run OS commands as the rclone user. core/command re-executes the rclone binary with arbitrary arguments, and several backend options shell out to programs, so even creating a remote with config/create can lead to command execution.
• Read and write literally any file the rclone process can reach, by pointing operations/* or sync/* at a local remote (or going through --rc-files / --rc-serve). Bestie, writing arbitrary files as the rclone user is itself a route to code execution. 💀
• Read back stored credentials. rclone configs are out here routinely holding cloud-provider secrets. config/dump and its little friends expose them, so the second your rc gets compromised, it's over for every configured backend. 😭
• Change rclone's runtime behaviour with options/set, manage remotes with config/*, and just straight up stop the process with core/quit.

There is currently no per-endpoint capability or scope system: authentication is all-or-nothing. Granting any access grants all of the above. No in-between, no crumbs. 🙈

Consequently:

• Do not bind the rc to a network address you do not control. The default bind is loopback (localhost:5572); keep it there unless you have a specific reason to change it.
• Do not use --rc-no-auth on a non-loopback bind. It disables authentication on the endpoints that access remotes — go read --rc-no-auth.
• Use authentication and TLS (--rc-user/--rc-pass or --rc-htpasswd, plus --rc-cert/--rc-key) whenever the port is reachable by anyone you do not fully trust, and raise --rc-min-tls-version.

---

✨ Supported parameters ✨

• --rc — the flag that starts the http server listening for remote requests. 🫶
• --rc-addr=IP — IPaddress:Port or :Port to bind server to. Default is "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. 😤

Default Off.

• global.* connection string options and the rc — Remotes instantiated by the rc do not let connection string (https://rclone.org/docs/#connection-strings) global.* options change rclone's process-wide configuration. Remotes created directly on the command line or defined in the config file are unaffected.

A global.* option still takes effect for the individual backend it is set on (exactly like an override.* option), it just does not leak into the global config for the rest of the process. 🦋

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

This enables cross-origin (CORS) requests from browsers on the origin given, for example --rc-allow-origin https://app.example.com. Browser CORS preflight OPTIONS requests are answered by rclone without authentication as browsers never send credentials with them. All other requests, including other OPTIONS requests, must be authenticated when authentication is enabled.

The rclone gui command sets this automatically to the origin the GUI is served from if it is not set explicitly.

Setting this to * allows any origin which is a security risk on an authenticated server. 🚨 be so for real about that one

Default is off (no CORS).

• --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. She's self-sufficient like that. 👑

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. So much less typing bestie, we love efficiency. 💅

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. It's giving main character energy, obviously. ✨

🔥 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 jobid and executeId, 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. Fr fr, just do it. 😭

As an alternative to _async, you can send the HTTP header Prefer: respond-async (RFC 7240). This has the same effect as _async = true but additionally returns HTTP status 202 (Accepted) instead of 200, and includes a Preference-Applied: respond-async response header. The 202 status code makes it easy for clients to distinguish an async response from a completed one without inspecting the body. Iconic behaviour honestly. 🫶

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,
    "executeId": "d794c33c-463e-4acf-b911-f4b23e4f40b7"
}

The jobid is a unique identifier for the job within this rclone instance. The executeId identifies the rclone process instance and changes after rclone restart. Together, the pair (executeId, jobid) uniquely identifies a job across rclone restarts. 🌟

Query the status to see if the job has finished. For more information on the meaning of these return parameters see the job/status call.

$ rclone rc --json '{ "jobid":2 }' job/status
{
    "duration": 0.000124163,
    "endTime": "2018-10-27T11:38:07.911245881+01:00",
    "error": "",
    "executeId": "d794c33c-463e-4acf-b911-f4b23e4f40b7",
    "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
}

okay so job/list is literally your little ✨ job tracker ✨ — it shows you the jobs that are running right now or recently finished, plus their status. bestie behavior fr 💅

$ rclone rc job/list
{
    "executeId": "d794c33c-463e-4acf-b911-f4b23e4f40b7",
    "finished_ids": [
        1
    ],
    "jobids": [
        1,
        2
    ],
    "running_ids": [
        2
    ]
}

And what are we actually looking at here 👀 let me break it down no cap:

• executeId — the current rclone instance ID (it's the same for every job, and it changes after a restart, so don't get attached 💀)
• jobids — array of all the job IDs, both running and finished
• running_ids — array of the job IDs that are running right now
• finished_ids — array of the job IDs that are done

---

Setting config flags with _config 🎀

So if you wanna set config — like the equivalent of the global flags — but only for the duration of one single rc call? Then you pass in the _config parameter. one call only, babe. what happens in the call stays in the call ✨

Alternative route: you can pass config options flat at the top level of the parameter map. The option names match their CLI flags, but without the -- and with - swapped for _ (so like transfers instead of Transfers inside _config). iykyk

This should be in the same format as the main key returned by options/get.

rclone rc --loopback options/get blocks=main

You can peep more help on these options with this command (check out the options blocks section for the full tea):

rclone rc --loopback options/info blocks=main

So real talk — say you wanna run a sync with the --checksum parameter. You'd pass this param in your JSON blob 👇

"_config":{"CheckSum": true}

Or pass it flat at the top level:

"checksum": true

If you're using rclone rc you could pass it as:

rclone rc sync/sync ... _config='{"CheckSum": true}'

Or just flat, easy peasy:

rclone rc sync/sync ... checksum=true

heads up bestie — if you supply both flat parameters and _config, the parameters in the legacy _config block take precedence. the old one wins, periodt.

Any config parameters you don't set will inherit the global defaults that were set with command line flags or environment variables. so it's giving... defaults that just vibe in the background 🦋

Quick note: 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}

Or flat:

"buffer_size": "42M"
"buffer_size": 44040192

And if you wanna confirm the _config assignment actually worked properly? Call options/local and it'll show you what the value got set to. we love receipts ✅

---

Setting filter flags with _filter 🌸

Same energy, different flag. If you wanna set filters for the duration of an rc call only, you pass in the _filter parameter.

Or — you guessed it — pass filter options flat at the top level of the parameter map. Option names = their CLI flags without -- and with - replaced by _ (so exclude instead of Exclude inside _filter). 🫶

This should be in the same format as the filter key returned by options/get.

rclone rc --loopback options/get blocks=filter

More help on these options? Yes bestie, this command got you (again, see the options blocks section for more):

rclone rc --loopback options/info blocks=filter

Say you wanted to run a sync with these flags:

--max-size 1M --max-age 42s --include "a" --include "b"

You'd pass this parameter in your JSON blob 👇

"_filter":{"MaxSize":"1M", "IncludeRule":["a","b"], "MaxAge":"42s"}

Or pass them flat at the top level:

"max_size":"1M", "include":["a","b"], "max_age":"42s"

If using rclone rc this could be passed as:

rclone rc ... _filter='{"MaxSize":"1M", "IncludeRule":["a","b"], "MaxAge":"42s"}'

Or simply flat:

rclone rc ... max_size=1M include="a,b" max_age=42s

same rule as before, bestie — if you supply both flat parameters and _filter, the parameters in the legacy _filter block take precedence. legacy stays winning 💀

Any filter parameters you don't set will inherit the global defaults set with command line flags or environment variables.

Note that it's possible to set some values as strings or integers — see data types for more info. Example setting the equivalent of --buffer-size in string or integer format:

"_filter":{"MinSize": "42M"}
"_filter":{"MinSize": 44040192}

Or flat:

"min_size": "42M"

And if you wanna check the _filter assignment worked properly, call options/local and it'll show you what the value got set to. ✨ iconic ✨

---

Assigning operations to groups with _group = value 👑

Every single rc call has its own stats group for tracking its metrics — main character energy, obviously 💅 By default, grouping is done by the composite group name from the prefix job/ and the id of the job, like so: job/1.

But if _group has a value, then the stats for that request get grouped under that value instead. This lets the caller group stats under their own name. custom labels? we love to see it 🎀

Stats for a specific group can be accessed by passing group to core/stats:

$ rclone rc --json '{ "group": "job/1" }' core/stats
{
    "speed": 12345
    ...
}

---

Data types 🦋

When the API returns types, these will mostly be straight-forward integer, string, or boolean types. nice and chill, no drama.

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 little spicier 🌶️

• Duration — these come back as an integer duration in nanoseconds. They may be set as an integer, or they may be set with a time string, e.g. "5s". See the options section (<https://rclone.org/docs/#options>) for more info.
• Size — these come back as an integer number of bytes. They may be set as an integer, or they may be set with a size suffix string, e.g. "10M". See the options section (<https://rclone.org/docs/#options>) for more info.
• Enumerated type (such as CutoffMode, DumpFlags, LogLevel, VfsCacheMode) — these come back as an integer and may be set as an integer, but more conveniently they can be set as a string, e.g. "HARD" for CutoffMode or DEBUG for LogLevel.
• BandwidthSpec — this will be set and returned as a string, e.g. "1M".

---

Option blocks 🧚

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 can be used to build user interfaces for displaying and setting any rclone option. UI girlies, this one's for you 💖

These consist of arrays of Option blocks. These have the following format. Each block describes a single option.

…and bestie, that's where we're picking up next — more blocks incoming, don't go anywhere 💜

• Name — type string, optional? N — name of the option in snake_case
• FieldName — type string, optional? N — name of the field used in the rc — if blank use Name. May contain "." for nested fields.
• Help — type string, optional? N — help, started with a single sentence on a single line
• Groups — type string, optional? Y — groups this option belongs to — comma separated string for options classification
• Provider — type string, optional? Y — set to filter on provider
• Default — type any, optional? N — default value, if set (and not to nil or "") then Required does nothing
• Value — type any, optional? N — value to be set by flags
• Examples — type Examples, optional? Y — predefined values that can be selected from list (multiple-choice option)
• ShortOpt — type string, optional? Y — the short command line option for this
• Hide — type Visibility, optional? N — if non zero, this option is hidden from the configurator or the command line
• Required — type bool, optional? N — this option is required, meaning value cannot be empty unless there is a default
• IsPassword — type bool, optional? N — set if the option is a password
• NoPrefix — type bool, optional? N — set if the option for this should not use the backend prefix
• Advanced — type bool, optional? N — set if this is an advanced config option
• Exclusive — type bool, optional? N — set if the answer can only be one of the examples (empty string allowed unless Required or Default is set)
• Sensitive — type 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. And bestie, note this: the Name of the option becomes the command line flag with _ replaced with -. That's the whole trick. ✨

{
    "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"
},

Also keep in your head: the Help may be multiple lines separated by \n. The first line will always be a short sentence, and that is the sentence shown when you run rclone help flags. 💅

🌸 Specifying remotes to work on 🌸

Remotes get specified with the fs=, srcFs=, dstFs= parameters, depending on which command you're using. Different command, different param name, that's just how it is bestie.

The parameters can be a string exactly like the rest of rclone, e.g. s3:bucket/path or :sftp:/my/dir. They can also be specified as JSON blobs. 🫶

If you specify a JSON blob, it should be an object mapping strings to strings. Those 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

One of _name or type should normally be set. If you want the local backend, then type should be set to local. If _root isn't specified then it defaults to the root of the remote.

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. Don't forget the -a, she's load-bearing. 😤

See the backend command (https://rclone.org/commands/rclone_backend/) for more information.

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. 📊

Authentication is not required for this call. No login needed, she's open.

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
  • noOutput — don't print anything to stdout
  • 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 (https://rclone.org/commands/rclone_config_create/) for more information on the above.

config/delete: Delete a remote in the config file.

Parameters:

• name — name of remote to delete

See the config delete command (https://rclone.org/commands/rclone_config_delete/) for more information on the above.

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 (https://rclone.org/commands/rclone_config_dump/) for more information on the above.

config/get: Get a remote in the config file.

Parameters:

• name — name of remote to get

See the config dump command (https://rclone.org/commands/rclone_config_dump/) for more information on the above.

config/listremotes: Lists the remotes in the config file and defined in environment variables.

Returns

• remotes — array of remote names

See the listremotes command (https://rclone.org/commands/rclone_listremotes/) for more information on the above. and that's the list bestie, keep going ✨

config/oauthstatus</p>: Get the status of the OAuth authentication server 🦋

Okay so this one just peeks at the OAuth authentication server and tells you what it's up to. It returns the current status, periodt.

It gives you back a JSON object:

• status — either "running" or "stopped", no in-between bestie
• authUrl — the URL for the authorization, and it's only there if status is "running"

Eg 💅

{
    "status": "running",
    "authUrl": "http://127.0.0.1:53682/auth?state=..."
}

---

config/oauthstop</p>: Stop any running OAuth authentication server 🛑

Stops the OAuth authentication server if one is running. That's it, that's the vibe.

This is your little escape hatch: you can use it to recover from an interrupted OAuth flow without restarting rclone. Iconic.

Heads up bestie: if no OAuth authentication is in progress, an error is returned. So don't come for it for no reason 😭

---

config/password</p>: 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 (https://rclone.org/commands/rclone_config_password/) command for more information on the above.

---

config/paths</p>: 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 (https://rclone.org/commands/rclone_config_paths/) command for more information on the above.

---

config/providers</p>: Shows how providers are configured in the config file 👑

Returns a JSON object:

• providers — array of objects

See the config providers (https://rclone.org/commands/rclone_config_providers/) command for more information on the above.

Lowkey important detail: the Options blocks are in the same format as returned by "options/info". They are described in the option blocks section. iykyk 🌸

---

config/setpath</p>: Set the path of the config file 📁

Parameters:

• path — path to the config file to use

---

config/unlock</p>: Unlock the config file 🔓

Unlocks the config file if it is locked. Fr fr, sometimes it just be locked.

Parameters:

• 'configPassword' — password to unlock the config file

Pro tip vibes: a good idea is to disable AskPassword before making this call ✨

---

config/unset</p>: Unset keys in a remote in the config file 🧹

Parameters:

• name — name of remote
• keys — a list of key names to remove

Returns:

• removed — a list of the keys that were actually removed

See the config unset (https://rclone.org/commands/rclone_config_unset/) command for more information on the above.

---

config/update</p>: 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
  • noOutput — don't print anything to stdout
  • 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 (https://rclone.org/commands/rclone_config_update/) command for more information on the above.

---

core/bwlimit</p>: Set the bandwidth limit 🚦

This sets the bandwidth limit to the string passed in. It should be a single bandwidth limit entry or a pair of upload:download bandwidth. The way it just… does that. Obsessed.

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. One. Singular. Don't try it.

In either case "rate" is returned as a human-readable string, and "bytesPerSecond" is returned as a number. Both, always, no cap 💖

---

core/command</p>: 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>"
}

---

core/disks</p>: List the local disks 💾

This does not take any parameters. Nothing. Nada. Zilch.

This call is for rclone GUI programs to enumerate local disks and important directories for doing transfers to and from. The list returned will include the root directory and the user's home directory and any mounted disks. The returned items should be usable directly as remotes. Slay, honestly 🌈

Returns:

• disks
  • This is an array of strings of local disk names

---

core/du</p>: 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
    }
}

Cute little detail: authentication is not required for this call. Walk right in bestie 🎀

---

core/gc</p>: 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. Like, you probably don't need it, but if memory is acting up it's giving ✨diagnostic✨

---

core/group-list</p>: 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",
            ...
        ]
}

Authentication is not required for this call either 💜

---

core/memstats</p>: Returns the memory statistics 🧠

This returns the memory statistics of the running program. What the values mean are explained in the go docs: https://golang.org/pkg/runtime/#MemStats

The most interesting values for most people are:

• 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

---

core/obscure</p>: 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</p>: Return PID of current process 🔢

This returns PID of current process. Useful for stopping rclone process. Like, know your enemy's number, y'know? 😌

---

core/quit</p>: Terminates the app 💀

(Optional) Pass an exit code to be used for terminating the app:

• exitCode — int

---

core/stats</p>: Returns stats about current transfers 📈

This returns all available stats:

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, optional)
• short — if true will not return the transferring and checking arrays (boolean, optional)

Returns the following values:

              {
                  "bytes": total transferred bytes since the start of the group,
                  "checks": number of files checked,
                  "deletedDirs": number of directories deleted,
                  "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,
                  "listed" : number of directory entries listed,
                  "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
                      []
              }

okay so tiny lil truth bomb: the values for "transferring", "checking" and "lastError" are only assigned if data is actually available. like, no vibes to report = no key, bestie. 🙈

And the value for "eta" is null if an eta genuinely cannot be determined. can't rush the mystery, yk?

✨ Authentication is not required for this call. ✨

---

🗑️ core/stats-delete: Delete stats group.

This deletes entire stats group. whole thing. gone. bye bestie 💅

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 one specific stats group if group is provided. fresh start energy ✨

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. after that it's giving amnesia, bestie 🫶

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),
                "what": the purpose of the transfer (transferring, deleting, checking, importing, hashing, merging, listing, moving, renaming),
                "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
            }
        ]
}

✨ Authentication is not required for this call. ✨

---

🏷️ core/version: Shows the current version of rclone, Go and the OS.

This shows the current versions of rclone, Go and the OS: 👑

• version — rclone version, e.g. "v1.71.2"
• 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 GOOS (e.g. "linux")
• osKernel — OS Kernel version (e.g. "6.8.0-86-generic (x86_64)")
• osVersion — OS Version (e.g. "ubuntu 24.04 (64 bit)")
• osArch — cpu architecture in use (e.g. "arm64 (ARMv8 compatible)")
• arch — cpu architecture in use according to Go GOARCH (e.g. "arm64")
• goVersion — version of Go runtime in use (e.g. "go1.25.0")
• linking — type of rclone executable (static or dynamic)
• goTags — space separated build tags or "none"

✨ Authentication is not required for this call. ✨

---

🧊 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.

---

🔢 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

---

📦 job/batch: Run a batch of rclone rc commands concurrently.

This takes the following parameters:

• concurrency — int — do this many commands concurrently. Defaults to --transfers if not set.
• inputs — an list of inputs to the commands with an extra _path parameter

{
    "_path": "rc/path",
    "param1": "parameter for the path as documented",
    "param2": "parameter for the path as documented, etc",
}

The inputs may use _async, _group, _config and _filter as normal when using the rc. 💅

Returns:

• results — a list of results from the commands with one entry for each in inputs.

For example:

rclone rc job/batch --json '{
  "inputs": [
    {
      "_path": "rc/noop",
      "parameter": "OK"
    },
    {
      "_path": "rc/error",
      "parameter": "BAD"
    }
  ]
}
'

Gives the result:

{
  "results": [
    {
      "parameter": "OK"
    },
    {
      "error": "arbitrary error on input map[parameter:BAD]",
      "input": {
        "parameter": "BAD"
      },
      "path": "rc/error",
      "status": 500
    }
  ]
}

🌈 job/list — the ID roll-call of everything currently running

Parameters: literally none, bestie. It takes nothing.

Results:

• executeId — string id of the rclone that's executing this (heads up: it changes after a restart 💀)
• jobids — array of integer job ids (and yes, they start back at 1 on every restart 🎀)
• runningIds — array of integer job ids that are running
• finishedIds — array of integer job ids that are finished

---

🔍 job/status — read the status of a 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
• finished — boolean whether the job has finished or not
• id — as passed in above
• executeId — rclone instance ID (changes after restart); combined with id uniquely identifies a job
• startTime — time the job started (e.g. "2018-10-26T18:50:20.528336039+01:00")
• success — boolean - true for success false otherwise
• output — output of the job as would have been returned if called synchronously
• progress — output of the progress related to the underlying job

ngl the finished key shows up twice in that list up there and I'm just telling you exactly what the manpage says 💅

🛑 job/stop — stop the running job

Parameters:

• jobid — id of the job (integer).

🛑🛑 job/stopgroup — stop all running jobs in a group

Parameters:

• group — name of the group (string).

---

🗺️ mount/listmounts — show me every current mount point

This shows currently mounted points, which can be used for performing an unmount. Iconic behaviour fr fr.

This takes no parameters and returns

• mountPoints: list of current mount points

Eg

rclone rc mount/listmounts

---

💖 mount/mount — create a new mount point

rclone allows Linux, FreeBSD, macOS and Windows to mount any of Rclone's cloud storage systems as a file system with FUSE. Obsessed, honestly.

If no mountType is provided, the priority is given as follows: 1. mount 2. cmount 3. mount2

This takes the following parameters:

• fs — a remote path to be mounted (required)
• mountPoint: valid path on the local machine (required)
• mountType: one of the values (mount, cmount, mount2) specifies the mount implementation to use
• mountOpt: a JSON object with Mount options in.
• vfsOpt: a JSON object with VFS options in.

Alternatively, you can pass VFS and Mount options flat at the top level of the parameter map. The option names are the same as their CLI flags without -- and with - replaced by _ (e.g. vfs_cache_mode instead of CacheMode inside vfsOpt, and volname instead of VolName inside mountOpt).

If both flat parameters and nested vfsOpt/mountOpt blocks are supplied, the parameters in the nested blocks will take precedence. Nested wins, always. Periodt. 👑

On Windows mountPoint may be set to * to assign the next available drive letter automatically, or a network share UNC path (e.g. "\\server") to mount as a network drive. In these cases the actual drive letter is chosen at mount time.

This returns the following values:

• mountPoint: the actual mount point that was used (this may differ from the input, e.g. on Windows when * is passed the allocated drive letter is returned)

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}'
rclone rc mount/mount fs=TestDrive: mountPoint=/mnt/tmp vfs_cache_mode=writes volname=MyTestVolume
rclone rc mount/mount fs=mydrive: mountPoint=* mountType=cmount

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

---

🧚 mount/types — show all possible mount types

This shows all possible mount types and returns them as a list.

This takes no parameters and returns

• mountTypes: 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

---

🦋 mount/unmount — unmount selected active mount

rclone allows Linux, FreeBSD, macOS and Windows to mount any of Rclone's cloud storage systems as a file system with FUSE.

This takes the following parameters:

• mountPoint: valid path on the local machine where the mount was created (required)

Example:

rclone rc mount/unmount mountPoint=/home/<user>/mountPoint

---

🌸 mount/unmountall — unmount all active mounts

rclone allows Linux, FreeBSD, macOS and Windows to mount any of Rclone's cloud storage systems as a file system with FUSE.

This takes no parameters and returns error if unmount does not succeed. 😭

Eg

rclone rc mount/unmountall

---

📊 operations/about — return the space used on the remote

This takes the following parameters:

• fs — a remote name string e.g. "drive:"

The result is as returned from rclone about --json

See the about (https://rclone.org/commands/rclone_about/) command for more information on the above.

---

✅ operations/check — 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. Pure vibes, zero side effects 🫶

This takes the following parameters:

• srcFs — a remote name string e.g. "drive:" for the source, "/" for local filesystem
• dstFs — a remote name string e.g. "drive2:" for the destination, "/" for local filesystem
• download — check by downloading rather than with hash
• checkFileHash — treat checkFileFs:checkFileRemote as a SUM file with hashes of given type
• checkFileFs — treat checkFileFs:checkFileRemote as a SUM file with hashes of given type
• checkFileRemote — treat checkFileFs:checkFileRemote as a SUM file with hashes of given type
• oneWay — check one way only, source files must exist on remote
• combined — make a combined report of changes (default false)
• missingOnSrc — report all files missing from the source (default true)
• missingOnDst — report all files missing from the destination (default true)
• match — report all matching files (default false)
• differ — report all non-matching files (default true)
• error — 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 want to check all the data. All of it. Every crumb. 🍓

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.

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. Don't do it bestie, it's not the move.

Returns:

• success — true if no error, false otherwise
• status — textual summary of check, OK or text string
• hashType — hash used in check, may be missing
• combined — array of strings of combined report of changes
• missingOnSrc — array of strings of all files missing from the source
• missingOnDst — array of strings of all files missing from the destination
• match — array of strings of all matching files
• differ — array of strings of all non-matching files
• error — array of strings of all files with errors (hashing or reading)

---

🧹 operations/cleanup — remove trashed files in the remote or path

This takes the following parameters:

• fs — a remote name string e.g. "drive:"

See the cleanup (https://rclone.org/commands/rclone_cleanup/) command for more information on the above.

---

📄 operations/copyfile — copy a file from source remote to destination remote

This takes the following parameters:

• 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

---

🔗 operations/copyurl — copy the URL to the object

This takes the following parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "dir"
• url — string, URL to read from
• autoFilename — boolean, set to true to retrieve destination file name from url

See the copyurl (https://rclone.org/commands/rclone_copyurl/) command for more information on the above.

---

🗑️ operations/delete — remove files in the path

This takes the following parameters:

• fs — a remote name string e.g. "drive:"

See the delete (https://rclone.org/commands/rclone_delete/) command for more information on the above.

---

💀 operations/deletefile — remove the single file pointed to

This takes the following parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "dir"

See the deletefile (https://rclone.org/commands/rclone_deletefile/) command for more information on the above.

---

🌈 operations/fsinfo — return information about the remote

This takes the following parameters:

• fs — 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"
               }
       }

okay so that whole glowing JSON blob above is just the tail of the operations/fsinfo response — the receipts, if you will. 💅 And here's the tea: this one has no command line equivalent, so bestie, if you want it you gotta go through the back door like this:

rclone rc --loopback operations/fsinfo fs=remote:

---

🌸 operations/hashsum: Produces a hashsum file for all the objects in the path 🔥

It makes a hash file for every single object sitting in that path, using whatever hash you named. The output format? Identical to the classic md5sum/sha1sum tool. Chef's kiss, familiar vibes. 🎀

It takes these parameters:

• fs — a remote name string, e.g. "drive:" for the source, / for the local filesystem
  • oh and fun fact: this can also point to a file, and then literally just that one file comes back in the listing. congrats, single-serve. 🍓
• hashType — the 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 toss in the download flag, it'll download the data from the remote and build the hash on the fly. Super useful for remotes that don't support the hash you asked for, or if you genuinely want to check all the data yourself. main character behaviour tbh. ✨

Heads up bestie: if what you actually want is to feed in a checkfile and compare hashes against the current files, then you want operations/check instead of operations/hashsum. different tool, different vibe. 🙈

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 (https://rclone.org/commands/rclone_hashsum/) command for more information on the above.

---

💜 operations/hashsumfile: Produces a hash for a single file 🧚

One file. One hash. Intimate. It produces a hash for a single file using the hash you named.

It takes these parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "file.txt"
• 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)

Supply the download flag and it'll pull the data from the remote and make the hash on the fly. Great for remotes that don't do your chosen hash, or if you really want to read all the data. go off, verify everything. 😭

Returns:

• hash — hash for the file
• hashType — type of hash used

Example:

$ rclone rc --loopback operations/hashsumfile fs=/ remote=/bin/bash hashType=MD5 download=true base64=true
{
    "hashType": "md5",
    "hash": "MDMw-fG2YXs7Uz5Nz-H68A=="
}

See the hashsum (https://rclone.org/commands/rclone_hashsum/) command for more information on the above.

---

⭐ operations/list: List the given remote and path in JSON format 👑

It takes these parameters:

• 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 (https://rclone.org/commands/rclone_lsjson/) command for more information on the above and examples.

---

🦋 operations/mkdir: Make a destination directory or container 🌈

It takes these parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "dir"

See the mkdir (https://rclone.org/commands/rclone_mkdir/) command for more information on the above.

---

💖 operations/movefile: Move a file from source remote to destination remote 🫶

It takes these parameters:

• 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

---

🎀 operations/publiclink: Create or retrieve a public link to the given file or folder. 💫

It takes these parameters:

• 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 (https://rclone.org/commands/rclone_link/) command for more information on the above.

---

🔥 operations/purge: Remove a directory or container and all of its contents 💀

okay so this one is not playing around. it takes these parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "dir"

See the purge (https://rclone.org/commands/rclone_purge/) command for more information on the above.

---

🌸 operations/rmdir: Remove an empty directory or container ✨

It takes these parameters:

• fs — a remote name string e.g. "drive:"
• remote — a path within that remote e.g. "dir"

See the rmdir (https://rclone.org/commands/rclone_rmdir/) command for more information on the above.

---

🧚 operations/rmdirs: Remove all the empty directories in the path 🍓

It takes these parameters:

• fs — a remote name string e.g. "drive:"

…and while we're still on that one, there's two more params riding along:

• remote — a path inside that remote, like "dir".
• leaveRoot — a boolean, and if you set it to true the root does not get deleted 🫶.

Peep the rmdirs command (https://rclone.org/commands/rclone_rmdirs/) for more on all of the above, bestie.

---

💅 operations/settier: Changes storage tier or class on all files in the path

This one takes the following parameters:

• fs — a remote name string, like "drive:".

And for more on it, go read the settier command (https://rclone.org/commands/rclone_settier/). Slay.

---

🎀 operations/settierfile: Changes storage tier or class on the single file pointed to

This takes these parameters:

• fs — a remote name string, like "drive:".
• remote — a path inside that remote, like "dir".

(Just the one file, babes. Very targeted of it.)

---

✨ operations/size: Count the number of bytes and files in remote

This takes the following parameters:

• fs — a remote name string, like "drive:path/to/dir".

Returns:

• count — how many files there are.
• bytes — how many bytes are in those files.

See the size command (https://rclone.org/commands/rclone_size/) for more info. 💖

---

🦋 operations/stat: Give information about the supplied file or directory

This takes the following parameters:

• fs — a remote name string, e.g. "drive:".
• remote — a path inside that remote, e.g. "dir".
• opt — a dictionary of options that controls the listing (optional).
  • see operations/list for what goes in there.

And the result is:

• item — an object exactly as described in the lsjson command. It'll be null if it's not found.

Real talk: if you only care about files, it is so much more efficient to set the filesOnly flag in the options. Do yourself a favor. 🙈

See the lsjson command (https://rclone.org/commands/rclone_lsjson/) for more on all of the above plus examples.

---

🌈 operations/uploadfile: Upload file using multiform/form-data

This takes the following parameters:

• fs — a remote name string, like "drive:".
• remote — a path inside that remote, like "dir".
• each part in body represents a file to be uploaded.

---

👑

options/blocks: List all the option blocks

Returns: options — a list of the option block names.

---

options/get: Get all the global options

Returns an object where the keys are option block names and the values are an object holding the current option values.

Parameters:

• blocks — optional string of comma separated blocks to include.
  • all of them get included if this is missing or "".

Heads up: these are the global options, which do not care about you using the _config and _filter parameters. If you wanna read the params set in _config or _filter, use options/local instead. iykyk.

This shows the internal names of the option inside rclone, which should map onto the external options super easily with a few exceptions.

---

options/info: Get info about all the global options

Returns an object where keys are option block names and the values are an array of objects with info about each option.

Parameters:

• blocks — optional string of comma separated blocks to include.
  • all of them get included if this is missing or "".

These objects are in the same format as what config/providers returns. They're 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 holds the local config and the "filter" key holds the local filters.

So like — these are the local options specific to this rc call. If _config wasn't supplied then they'll be the global options. Same vibe with _filter.

This call is mostly useful for seeing whether your _config and _filter passing is actually working. 😭

This shows the internal names of the option inside rclone, which should map onto the external options super easily with a few exceptions.

---

options/set: Set an option

Parameters:

• option block name containing an object with
  • key: value

Repeated as many times as you need.

Only supply the options you actually wanna change, bestie. If an option is unknown it gets silently ignored (💀). And not all options will have an effect when changed like this.

For example:

This sets DEBUG level logs (-vv) — and 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 (that's the normal one, 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:

• url — http url of the github repo where the plugin is hosted (http://github.com/rclone/rclone-webui-react).

Example:

rclone rc pluginsctl/addPlugin

---

🍓 pluginsctl/getPluginsForType: Get plugins with type criteria

This shows all the possible plugins for a mime type.

This takes the following parameters:

• type — supported mime type by a loaded plugin, e.g. (video/mp4, audio/mp3).
• pluginType — filter plugins based on their type, e.g. (DASHBOARD, FILE_HANDLER, TERMINAL).

Returns:

• loadedPlugins — list of current production plugins.
• testPlugins — list of temporarily loaded development plugins, usually running on a different server.

Example:

rclone rc pluginsctl/getPluginsForType type=video/mp4

---

⭐ pluginsctl/listPlugins: Get the list of currently loaded plugins

This lets you get the currently enabled plugins and all their details.

It takes no parameters and returns:

• loadedPlugins — list of current production plugins.
• testPlugins — list of temporarily loaded development plugins, usually running on a different server.

E.g.

rclone rc pluginsctl/listPlugins

---

💜 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.

It takes no parameters and returns:

• loadedTestPlugins — list of currently available test plugins.

E.g.

rclone rc pluginsctl/listTestPlugins

---

🎀 pluginsctl/removePlugin: Remove a loaded plugin

This lets you remove a plugin using its name.

It takes these parameters:

• name — name of the plugin in the format author/plugin_name.

E.g.

rclone rc pluginsctl/removePlugin name=rclone/video-plugin

---

🌸 pluginsctl/removeTestPlugin: Remove a test plugin

This lets you remove a plugin using its name.

This takes the following parameters:

• name — name of the plugin in the format author/plugin_name.

Example:

rclone rc pluginsctl/removeTestPlugin name=rclone/rclone-webui-react

---

💀 rc/error: This returns an error

This returns an error with the input as part of its error string. Useful for testing error handling.

Authentication is not required for this call.

---

🫶 rc/fatal: This returns an fatal error

This returns an error with the input as part of its error string. Useful for testing error handling.

---

👑 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.

Authentication is not required for this call.

---

🌈 rc/noop: Echo the input to the output parameters

This echoes the input parameters straight to the output parameters, for testing purposes. You can use it to check that rclone is still alive and to check that parameter passing is working properly.

Authentication is not required for this call.

---

✨ rc/noopauth: Echo the input to the output parameters requiring auth

This echoes the input parameters straight to the output parameters, for testing purposes. You can use it to check that rclone is still alive and to check that parameter passing is working properly.

---

😭 rc/panic: This returns an error by panicking

This returns an error with the input as part of its error string. Useful for testing error handling.

---

🦋 serve/list: Show running servers

Show running servers with their IDs.

It takes no parameters and returns

• list — list of running serve commands

Each list element will have:

• id — ID of the server
• addr — address the server is running on
• params — parameters used to start the server

Eg

rclone rc serve/list

Returns

{
    "list": [
        {
            "addr": "[::]:4321",
            "id": "nfs-ffc2a4e5",
            "params": {
                "fs": "remote:",
                "opt": {
                    "ListenAddr": ":4321"
                },
                "type": "nfs",
                "vfsOpt": {
                    "CacheMode": "full"
                }
            }
        }
    ]
}

---

🔥 serve/start: Create a new server

Creates a new server with the parameters you specify.

This takes the following parameters:

• type — type of server: http, webdav, ftp, sftp, nfs, etc.
• fs — remote storage path to serve
• addr — the ip:port to run the server on, e.g. ":1234" or "localhost:1234"

The other parameters are exactly as described in the documentation for the relevant rclone serve command line options (https://rclone.org/commands/rclone_serve/). To translate a command line option into an rc parameter, drop the leading -- and swap - for _, so --vfs-cache-mode becomes vfs_cache_mode. Periodt.

Option parameters (things like VFS, proxy, and protocol-specific options) can be passed flat at the top level of the parameter map, or inside nested JSON objects under the vfsOpt, proxyOpt, and opt keys (e.g. vfsOpt='{"CacheMode": 2}', proxyOpt='{"AuthProxy": "http://127.0.0.1:8080"}'). If you supply both flat parameters and nested blocks, the parameters in the nested blocks take precedence. And note that global parameters have to be set with _config and _filter as described above.

Examples:

rclone rc serve/start type=nfs fs=remote: addr=:4321 vfs_cache_mode=full
rclone rc serve/start --json '{"type":"nfs","fs":"remote:","addr":":1234","vfs_cache_mode":"full"}'
rclone rc serve/start type=webdav fs=remote: vfsOpt='{"CacheMode": 2}' proxyOpt='{"AuthProxy": "http://127.0.0.1:8080"}'

This will give the reply

{
    "addr": "[::]:4321", // Address the server was started on
    "id": "nfs-ecfc6852" // Unique identifier for the server instance
}

Or an error if it failed to start. 🙈

Stop the server with serve/stop and list the running servers with serve/list.

---

💅 serve/stop: Unserve selected active serve

Stops a running serve instance by ID.

This takes the following parameters:

• id: as returned by serve/start

Empty response = it worked 💖 an error = it did not. That's the whole vibe check.

Example:

rclone rc serve/stop id=12345

---

💀 serve/stopall: Stop all active servers

Stops all the active servers. Every single one. No survivors, bestie.

rclone rc serve/stopall

---

🌈 serve/types: Show all possible serve types

This one spills the tea on every serve type that exists and hands them back to you as a list.

Takes no parameters at all, and returns:

• types: a list of serve types, like "nfs", "sftp", etc.

Those serve types are strings like "serve", "serve2", "cserve" and you can pass them straight to serve/start as the serveType parameter. iykyk ✨

Example:

rclone rc serve/types

Returns:

{
    "types": [
        "http",
        "sftp",
        "nfs"
    ]
}

---

🔁 sync/bisync: Perform bidirectional synchronization between two paths.

Two-way sync, bestie. It takes these parameters:

• path1 (required) — (string) a remote directory string, e.g. drive:path1
• path2 (required) — (string) a remote directory string, e.g. drive:path2
• dryRun — (bool) dry-run mode
• backupDir1 — (string) --backup-dir for Path1. Has to be a non-overlapping path on the same remote.
• backupDir2 — (string) --backup-dir for Path2. Has to be a non-overlapping path on the same remote.
• checkAccess — (bool) Make sure the expected RCLONE_TEST files are found on both Path1 and Path2 filesystems, otherwise abort.
• checkFilename — (string) Filename for --check-access (default: RCLONE_TEST)
• checkSync — (string) Controls comparison of final listings: true|false|only (default: true)
• compare — (string) Comma-separated list of bisync-specific compare options, ex. 'size,modtime,checksum' (default: 'size,modtime')
• conflictLoser — (ConflictLoserAction) What to do to the loser of a sync conflict (when there is a winner) or to both files (when there isn't one): ``, num, pathname, delete (default: num)
• conflictResolve — (string) Automatically resolve conflicts by preferring the version that is: none, path1, path2, newer, older, larger, smaller (default: none)
• conflictSuffix — (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')
• createEmptySrcDirs — (bool) Sync creation and deletion of empty directories. (Not compatible with --remove-empty-dirs)
• downloadHash — (bool) Compute the hash by downloading when it's otherwise unavailable. (⚠️ warning: may be slow and use lots of data!)
• filtersFile — (string) Read filtering patterns from a file
• force — (bool) Bypass the --max-delete safety check and just run the sync. Consider using with --verbose
• ignoreListingChecksum — (bool) Do not use checksums for listings (add --ignore-checksum to additionally skip post-copy checksum checks)
• maxLock — (Duration) Consider lock files older than this to be expired (default: 0 (never expire)) (minimum: 2m)
• noCleanup — (bool) Retain working files (useful for troubleshooting and testing).
• noSlowHash — (bool) Ignore listing checksums only on backends where they are slow
• recover — (bool) Automatically recover from interruptions without requiring --resync.
• removeEmptyDirs — (bool) Remove ALL empty directories at the final cleanup step.
• resilient — (bool) Allow future runs to retry after certain less-serious errors, instead of requiring --resync.
• resync — (bool) Performs the resync run. Equivalent to --resync-mode path1. Consider using --verbose or --dry-run first.
• resyncMode — (string) During resync, prefer the version that is: path1, path2, newer, older, larger, smaller (default: path1 if --resync, otherwise none for no resync.)
• slowHashSyncOnly — (bool) 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: /home/ncw/.cache/rclone/bisync)

Check the bisync command help over at https://rclone.org/commands/rclone_bisync/ and the full bisync description at https://rclone.org/bisync/ for more info 🫶

---

📦 sync/copy: copy a directory from source remote to destination remote

Parameters, bestie:

• srcFs — a remote name string, e.g. "drive:src" for the source
• dstFs — a remote name string, e.g. "drive:dst" for the destination
• createEmptySrcDirs — create empty src directories on destination if set

See the copy command at https://rclone.org/commands/rclone_copy/ for more on all of the above.

---

🚚 sync/move: move a directory from source remote to destination remote

It takes:

• srcFs — a remote name string, e.g. "drive:src" for the source
• dstFs — a remote name string, e.g. "drive:dst" for the destination
• createEmptySrcDirs — create empty src directories on destination if set
• deleteEmptySrcDirs — delete empty src directories if set

See the move command at https://rclone.org/commands/rclone_move/ for more on the above.

---

🔄 sync/sync: sync a directory from source remote to destination remote

It takes:

• srcFs — a remote name string, e.g. "drive:src" for the source
• dstFs — a remote name string, e.g. "drive:dst" for the destination
• createEmptySrcDirs — create empty src directories on destination if set

See the sync command at https://rclone.org/commands/rclone_sync/ for more on the above.

---

🧹 vfs/forget: Forget files or directories in the directory cache.

This forgets the paths sitting in the directory cache, so they get re-read from the remote next time they're needed. Iconic little memory wipe ✨

If you don't pass in any paths, it forgets 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 you don't supply it and there's only one VFS in use, that VFS gets used. If there's more than one VFS in use, then you must supply the "fs" parameter. No shortcuts, bestie.

---

📋 vfs/list: List active VFSes.

Lists the active VFSes, periodt.

It returns a list under the key "vfses", where the values are the VFS names you can pass to the other VFS commands in the "fs" parameter.

🔓 Authentication is not required for this call.

---

⏱️ vfs/poll-interval: Get the status or update the value of the poll-interval option.

With no parameter given, this returns the current status of the poll-interval setting.

When you set the interval=duration parameter, the poll-interval value gets updated and the polling function gets notified. Setting interval=0 disables poll-interval entirely.

rclone rc vfs/poll-interval interval=5m

The timeout=duration parameter can be used to specify how long 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.

The new poll-interval value will only be active when the timeout is not reached. 💅

If poll-interval is updated or disabled temporarily, some changes might not get picked up by the polling function, depending on the remote you're using. Just so you know.

This command takes an "fs" parameter. If you don't supply it and there's only one VFS in use, that VFS gets used. If there's more than one VFS in use, then the "fs" parameter must be supplied.

---

📊 vfs/queue: Queue info for a VFS.

Returns info about the upload queue for the selected VFS.

This is only useful if --vfs-cache-mode > off. If you call it while --vfs-cache-mode is off, it'll return an empty result.

{
    "queue": // 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
        },
   ],
}

The expiry time is the time until the file is eligible for upload, in floating point seconds. It can go negative. Since rclone only transfers --transfers files at once, only the lowest --transfers expiry times will have uploading as true. So yeah — there may be files with negative expiry times where uploading is false. Not a bug, just math 🫶

This command takes an "fs" parameter. If you don't supply it and there's only one VFS in use, that VFS gets used. If there's more than one VFS in use, then the "fs" parameter must be supplied.

🔓 Authentication is not required for this call.

---

⏳ vfs/queue-set-expiry: Set the expiry time for an item queued for upload.

Use this to adjust the expiry time for an item in the upload queue. You'll need to read the id of the item using vfs/queue before you use this call. No skipping steps.

Then you can set expiry to a floating point number of seconds from now, for when the item is eligible for upload. Want it uploaded ASAP? Set it to a large negative number (eg -1000000000). Want it delayed for ages? Set it to a large positive number.

⚠️ Setting the expiry of an item that has already started uploading does nothing at all — the item will carry on being uploaded.

It'll return an error if you call it with --vfs-cache-mode off, or if the id you passed isn't found.

It takes these 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 treated as relative to the current expiry (optional, boolean)

Returns an empty result on success, or an error.

This command takes an "fs" parameter. If you don't supply it and there's only one VFS in use, that VFS gets used. If there's more than one VFS in use, then the "fs" parameter must be supplied.

---

🧚 vfs/refresh: Refresh the directory cache.

This reads the directories for the specified paths and freshens up the directory cache.

If no paths are passed in then it will refresh the root directory.

rclone rc vfs/refresh

Otherwise you pass directories in as dir=path. Any parameter key that starts with dir will refresh that directory, like:

rclone rc vfs/refresh dir=home/junk dir2=data/misc

If the parameter recursive=true is given the whole directory tree will get refreshed. This refresh will use --fast-list if it's enabled. ✨

This command takes an "fs" parameter. If you don't supply it and there's only one VFS in use then that VFS gets used. If there's more than one VFS in use then the "fs" parameter is mandatory, bestie — no guessing games.

---

🌸 vfs/stats: Stats for a VFS 🌸

This returns stats for the selected VFS.

{
    // 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 you don't supply it 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.

Authentication is not required for this call. 🙈

---

🌈 Accessing the remote control via HTTP 🌈

Rclone implements a simple HTTP based protocol. No cap.

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. 👑

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. (We love a readable blob. 💅)

---

💀 Error returns 💀

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

---

🦋 CORS 🦋

The server implements basic CORS support when --rc-allow-origin is set. Browser CORS preflight OPTIONS requests are then answered by rclone without authentication with the Access-Control-* headers. Without --rc-allow-origin no CORS headers are sent and a preflight request is authenticated like any other request. So like, it's giving strict parent energy until you flip that flag. 🎀

---

🍓 Using POST with URL parameters only 🍓

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. (Yes bestie, it will just sit there being quiet and wrong. 😭)

$ 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

---

🧚 Using POST with a form 🧚

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. So the form wins the vibe check. ✨

curl --data "potato=1" --data "sausage=2" "http://localhost:5572/rc/noop?rutabaga=3&sausage=4"

Response

{
    "potato": "1",
    "rutabaga": "3",
    "sausage": "4"
}

---

💜 Using POST with a JSON blob 💜

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
}

---

🔥 Debugging rclone with pprof 🔥

If you use the --rc flag this will also enable the use of the go profiling tools on the same port.

The profiling endpoints follow the same authentication rules as the rest of the rc: they are only served if authentication has been set up (--rc-user/--rc-pass or --rc-htpasswd) or the --rc-no-auth flag is in use. For debugging on the default localhost port the easiest thing is to use --rc --rc-no-auth (but see the warning about using --rc-no-auth on a non-loopback bind). ⚠️

To use these, first install go (https://golang.org/doc/install).

---

🎀 Debugging memory use 🎀

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.

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 🌸

Memory leaks are most often caused by go routine leaks keeping memory alive which should have been garbage collected.

See all active go routines using

curl http://localhost:5572/debug/pprof/goroutine?debug=1

Or go to <http://localhost:5572/debug/pprof/goroutine?debug=1> in your browser. 🦋

---

⭐ Other profiles to look at ⭐

You can see a summary of profiles available at <http://localhost:5572/debug/pprof/>

Here is 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 (https://golang.org/pkg/net/http/pprof/) for more info on how to use the profiling and for a general overview see the Go team's blog post on profiling go programs (https://blog.golang.org/profiling-go-programs).

The profiling hook is zero overhead unless it is used (https://stackoverflow.com/q/26545159/164234). 💅

---

👑 Overview of cloud storage systems 👑

Each cloud storage system is slightly different. Rclone attempts to provide a unified interface to them, but some underlying differences show through. It's giving "we're all unique besties" energy, fr fr. 🌈

---

✨ Features ✨

Here is an overview of the major features of each cloud storage system.

---

💾 Hash 💾

The cloud storage system supports various hash types of the objects. The hashes are used when transferring data as an integrity check and can be specifically used with the --checksum flag in syncs and in the check command.

To use the verify checksums when transferring between cloud storage systems they must support a common hash type.

---

🕐 ModTime 🕐

Almost all cloud storage systems store some sort of timestamp on objects, but several of them not something that is appropriate to use for syncing. E.g. some backends will only write a timestamp that represents the time of the upload. To be relevant for syncing it should be able to store the modification time of the source object. If this is not the case, rclone will only check the file size by default, though can be configured to check the file hash (with the --checksum flag). Ideally it should also be possible to change the timestamp of an existing file without having to re-upload it. 😭

okay bestie, the ModTime column has its own little alphabet and you're gonna wanna know it by heart 💅 here's the key:

• - — ModTimes are not supported — any time you see is most likely the upload time
• R — ModTimes are supported on files, but can't be changed without re-uploading
• R/W — Read and Write ModTimes, fully supported, on files
• DR — ModTimes are supported on files and directories, but can't be changed without re-uploading
• DR/W — Read and Write ModTimes, fully supported, on files and directories

So storage systems with a - in the ModTime column means the modification time you read off an object is not the modification time of the file when it was uploaded. It's most likely the time the file was uploaded, or possibly something else entirely (like the time the picture was taken in Google Photos 📸).

Storage systems with an R (for read-only) in the ModTime column means it does keep modification times on objects, and updates them when uploading 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 will not work without SetModTime support — e.g. 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 💀.

Storage systems with R/W (for read/write) in the ModTime column means they also support modtime-only operations. We love to see it ✨

Storage systems with a D in the ModTime column means that all those symbols apply to directories as well as files 👑

---

🌸 Case Insensitive 🌸

If a cloud storage system is case sensitive, then it's possible to have two files which differ only in case — e.g. file.txt and FILE.txt. If a cloud storage system is case insensitive, then that isn't possible.

This can cause problems when syncing between a case insensitive system and a case sensitive system. The symptom of this is that no matter how many times you run the sync, it never completes fully 😭 it's giving infinite sync, fr fr.

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. Not the vibe.

This confuses rclone greatly when syncing — so use the rclone dedupe command to rename or remove duplicates. 🧚

💖 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 to allow moving files between many cloud storage systems transparently. ✨

The name shown by rclone to you, or during log output, will only contain a minimal set of replaced characters — just enough 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 on 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 the 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. 💀

It's 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 (https://rclone.org/overview/#encoding-example-windows) 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 → ␡

And the default encoding will also encode these file names, because they're 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 (https://rclone.org/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 a 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. 🌈

• Asterisk — * becomes ＊ ✨
• BackQuote — ` becomes ｀
• BackSlash — \ becomes ＼
• Colon — : becomes ：
• CrLf — CR 0x0D, LF 0x0A become ␍, ␊
• Ctl — like, every control character 0x00-0x1F gets swapped for ␀␁␂␃␄␅␆␇␈␉␊␋␌␍␎␏␐␑␒␓␔␕␖␗␘␙␚␛␜␝␞␟
• Del — DEL 0x7F becomes ␡
• Dollar — $ becomes ＄
• Dot — . or .. when it's the entire string becomes ．, ．．
• DoubleQuote — " becomes ＂
• Exclamation — ! becomes ！
• Hash — # becomes ＃
• InvalidUtf8 — an invalid UTF-8 character (e.g. latin1) becomes �
• LeftCrLfHtVt — CR 0x0D, LF 0x0A, HT 0x09, VT 0x0B sitting on the left of a string become ␍, ␊, ␉, ␋
• LeftPeriod — a . on the left of a string becomes .
• LeftSpace — a SPACE on the left of a string becomes ␠
• LeftTilde — a ~ on the left of a string becomes ～
• LtGt — <, > become ＜, ＞
• None ¹ — NUL 0x00 becomes ␀
• Percent — % becomes ％
• Pipe — | becomes ｜
• Question — ? becomes ？
• RightCrLfHtVt — CR 0x0D, LF 0x0A, HT 0x09, VT 0x0B sitting on the right of a string become ␍, ␊, ␉, ␋
• RightPeriod — a . on the right of a string becomes .
• RightSpace — a SPACE on the right of a string becomes ␠
• Semicolon — ; becomes ；
• SingleQuote — ' becomes ＇
• Slash — / becomes ／
• SquareBracket — [, ] become ［, ］

¹ The encoding from NUL 0x00 to ␀ is always implicit except when you're using Raw. Bestie, this used to be documented wrongly as disabling encoding entirely, and to keep things backward compatible, its behavior has not been changed. So don't come for me, it's staying like that. 💅

🎀 Encoding example: FTP 🎀

okay so let's get concrete. 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 cannot have any of the invalid Windows characters in file names. And you're backing up Linux servers to this FTP server, and those Linux filenames do have those characters. 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 you already had, which gives you:

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 with an encoding parameter in your config file. Your call, main character. 👑

🦋 Encoding example: Windows 🦋

Another one for the girls: imagine a Windows system with a file named Test：1.jpg, where the ： is the Unicode fullwidth colon symbol. When you use rclone to copy this to a remote that supports the regular : (halfwidth) colon — like Google Drive — you will notice the file gets renamed to Test:1.jpg.

To avoid this you can change the set of characters rclone should convert for the local filesystem, using the command-line argument --local-encoding. Rclone's default behavior on Windows corresponds to:

--local-encoding "Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot"

If you want to use the fullwidth characters ：, ＊ and ？ in your filenames without rclone changing 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"

Alternatively you can disable the conversion of any characters with --local-encoding Raw.

And instead of using the command-line argument --local-encoding, you can also set it as the environment variable (<https://rclone.org/docs/#environment-variables>) RCLONE_LOCAL_ENCODING, or configure (<https://rclone.org/docs/#configure>) a remote of type local in your config and set the encoding option there. So many options, so little time. 💖

⚠️ The risk of doing this: if you have a filename with the regular (halfwidth) :, * and ? in your cloud storage, and you try to download it to your Windows filesystem, this will fail. Those characters are not valid in filenames on Windows, and you have literally told rclone not to work around this by converting them to valid fullwidth variants. So, like, you did this to yourself bestie 😭

🌸 MIME Type 🌸

MIME types (also known as media types) classify types of documents using a simple text classification, e.g. text/html or application/pdf.

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're serving files directly to HTTP from the storage system.

If you're copying from a remote which supports reading (R) to a remote which supports writing (W) then rclone will preserve the MIME types. Otherwise they'll be guessed from the extension, or the remote itself may assign the MIME type. iykyk ✨

💜 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 (<https://rclone.org/docs/#metadata>) for more info. 🫶

🌈 Optional Features 🌈

All rclone remotes support a base command set. Other features depend upon backend-specific capabilities. Let's go through the whole roster, no skips, periodt. 💅

🔥 Purge

This deletes a directory quicker than just deleting all the files in the directory. Faster is better, always. ⭐

🔥 Copy

Used when copying an object to and from the same remote. This is known as a server-side copy so you can copy a file without downloading it and uploading it again. It's 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. Annoying but it works, ngl. 🙈

🔥 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. The way that rclone just finds a way 😤

🔥 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 the Move section above, bestie, it's all connected 💫).

🔥 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. Not the vibe, but facts are facts. 💀

🔥 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 (<https://rclone.org/docs/#fast-list>) for more details. Slay, recursive listing. ✨

🔥 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. Iconic behavior honestly. 👑

🔥 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. The speed, the efficiency, it's giving ✨main character✨.

🔥 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. Sharing is caring fr fr. 🎀

🔥 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 (<https://rclone.org/commands/rclone_about/>)

🔥 EmptyDir

The remote supports empty directories. See Limitations (<https://rclone.org/bugs/#limitations>) for details. Most Object/Bucket-based remotes do not support this. RIP to your empty folders, bestie. 🌸

Tiers 💅

rclone backends get sorted into tiers so you, bestie, have a vibe check on how stable each one actually is. Here's the whole rundown, no gatekeeping:

• Core — production-grade, first-class ✨
• Stable — well-supported, only minor gaps
• Supported — works for many uses; known caveats (iykyk)
• Experimental — use with care; expect gaps/changes 😬
• Deprecated — no longer maintained or supported, it's giving legacy 💀

Overview

Here is a summary of all backends:

Scoring

Here is how the backends are scored. 📊

Features

These are the useful optional features a backend should have, roughly in order of importance. Each one of these scores a point for the Features column:

• F1: Hash(es)
• F2: Modtime
• F3: Stream upload
• F4: Copy/Move
• F5: DirMove
• F6: Metadata
• F7: MultipartUpload

Tier

The tier is decided after determining these attributes. Some discretion is allowed in tiering, because some of these attributes are more important than others. Periodt.

• Maintainers — T1: Core >=2 · T2: Stable >=1 · T3: Supported >=1 · T4: Experimental >=0 · T5: Incubator >=0
• API source — T1: Core Official · T2: Stable Official · T3: Supported Either · T4: Experimental Either · T5: Incubator Either
• Features (F1-F7) — T1: Core >=5/7 · T2: Stable >=4/7 · T3: Supported >=3/7 · T4: Experimental >=2/7 · T5: Incubator N/A
• Integration tests — T1: Core All Green · T2: Stable All green · T3: Supported Nearly all green · T4: Experimental Some Flaky · T5: Incubator N/A
• Error handling — T1: Core Pacer · T2: Stable Pacer · T3: Supported Retries · T4: Experimental Retries · T5: Incubator N/A
• Data integrity — T1: Core Hashes, alt, modtime · T2: Stable Hashes or alt · T3: Supported Hash OR modtime · T4: Experimental Best-effort · T5: Incubator N/A
• Perf baseline — T1: Core Bench within 2x S3 · T2: Stable Bench doc · T3: Supported Anecdotal OK · T4: Experimental Optional · T5: Incubator N/A
• Adoption — T1: Core widely used · T2: Stable often used · T3: Supported some use · T4: Experimental N/A · T5: Incubator N/A
• Docs completeness — T1: Core Full · T2: Stable Full · T3: Supported Basic · T4: Experimental Minimal · T5: Incubator Minimal
• Security — T1: Core Principle-of-least-privilege · T2: Stable Reasonable scopes · T3: Supported Basic auth · T4: Experimental Works · T5: Incubator Works

---

Global Flags 👑

This describes the global flags available to every rclone command, split into groups. Every. Single. One. 🫶

Copy

Flags for anything which can copy a file. Copy-paste girlies, this section is literally yours 💖

• --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)
• --name-transform stringArray — Transform paths during the copy process
• --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

Flags used for sync commands. The glamour of keeping two places identical ✨

• --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
• --list-cutoff int — To save memory, sort directory listings on disk above this threshold (default 1000000)
• --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

Important flags useful for most commands. Lowkey the ones you'll actually reach for every day 🎀

• -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)

Check

Flags used for check commands.

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

Networking

Flags for general networking and HTTP stuff. 🌐

• --bind string — the local address to bind to for outgoing connections, bestie. IPv4, IPv6 or a name, whichever vibe you're on 🌈
• --bwlimit BwTimetable — bandwidth limit in KiB/s, or use a suffix B|K|M|G|T|P, or serve a whole timetable if you're feeling fancy 🚦
• --bwlimit-file BwTimetable — same deal but per file, in KiB/s, with 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
• --client-pass string — password for client SSL private key (PEM) for mutual TLS auth (obscured) (obscured) — yes it says obscured twice, that's the original, we don't edit the source of truth 💅
• --contimeout Duration — connect timeout (default 1m0s) ⏱️
• --disable-http-keep-alives — turn OFF HTTP keep-alives and use each connection exactly once
• --disable-http2 — disable HTTP/2 in the global transport
• --dscp string — set the DSCP value on connections, as a value or a name, like 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 only
• --header-upload stringArray — set an HTTP header for upload transactions only
• --http-proxy string — HTTP proxy URL, go through the middleman bestie 🛣️
• --max-connections int — maximum number of simultaneous backend API connections, 0 for unlimited
• --no-check-certificate — do NOT verify the server SSL certificate (insecure) 😭
• --no-gzip-encoding — don't set Accept-Encoding: gzip
• --timeout Duration — IO idle timeout (default 5m0s)
• --tpslimit float — cap HTTP transactions per second to this number
• --tpslimit-burst int — max burst of transactions for --tpslimit (default 1)
• --use-cookies — enable the session cookiejar 🍪
• --user-agent string — set the user-agent to a specified string (default "rclone/v1.75.2")

---

⚡ Performance ⚡

Flags helpful for increasing performance. Speedrun energy, let's go 🏎️✨

• --buffer-size SizeSuffix — in-memory buffer size when reading files for each --transfer (default 16Mi)
• --checkers int — how many checkers run in parallel (default 8)
• --transfers int — how many file transfers run in parallel (default 4)

---

🎀 Config 🎀

Flags for general configuration of rclone. The whole settings vibe, iykyk.

• --ask-password — allow prompting for a password for encrypted configuration (default true)
• --auto-confirm — if enabled, don't ask for console confirmation
• --cache-dir string — directory rclone uses 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 — 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, the pretend-o-mode 🫧
• --error-on-no-transfer — sets exit code 9 if no files were transferred, super 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 the process (default 1s)
• --low-level-retries int — number of low level retries to do (default 10)
• --max-buffer-memory SizeSuffix — if set, don't allocate more than this amount of memory as buffers (default off)
• --no-console — hide the 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 — directory rclone uses for temporary files (default "/tmp")
• --use-mmap — use mmap allocator (see docs)
• --use-server-modtime — use server modified time instead of object metadata

---

🔍 Debugging 🔍

Flags for developers. Peak main character energy for the bug hunters 🐛🔦

• --cpuprofile string — write cpu profile to file
• --dump DumpFlags — list of items to dump from: headers, bodies, requests, responses, auth, filters, goroutines, openfiles, mapper, curl, errors, trace
• --dump-bodies — dump HTTP headers and bodies — may contain sensitive info 🙈
• --dump-headers — dump HTTP headers — may contain sensitive info 🙈
• --memprofile string — write memory profile to file

---

🧚 Filter 🧚

Flags for filtering directory listings. The "no thanks, not that one" toolkit 💅

• --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)
• --files-from0 stringArray — read list of source-file names from file using NUL as separator (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)
• --hash-filter string — partition filenames by hash k/n or randomly @/n
• --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 📋

Flags for listing directories. Just showing off what's there, no moving files required 💖

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

---

📊 Logging 📊

Flags for logging and statistics.

• --log-file string — tape every single log line to this file instead of your screen.
• --log-file-compress — if this is set, rotated log files get squished with gzip so they don't devour your disk 💅
• --log-file-max-age Duration — how long old log files get to stick around before they're gone, like "7d". Default is 0s.
• --log-file-max-backups int — the maximum number of old log files we're keeping. bye to the rest.
• --log-file-max-size SizeSuffix — how big the log file can get before it gets rotated, e.g. "10M". Default is off.
• --log-format Bits — comma separated list of log format options. Default is date,time.
• --log-level LogLevel — how much tea the logs spill: DEBUG|INFO|NOTICE|ERROR. Default is NOTICE.
• --log-systemd — activate systemd integration for the logger. very systemd of it.
• --max-stats-groups int — max number of stats groups to keep in memory, and once you hit the limit the oldest one gets discarded. Default is 1000.
• -P, --progress — show progress during the transfer, bestie.
• --progress-terminal-title — put the progress up in the terminal title (this one needs -P/--progress to actually do anything).
• -q, --quiet — print as little stuff as possible. minimal queen behavior.
• --stats Duration — interval between printing stats, e.g. 500ms, 60s, 5m (0 disables it entirely). Default is 1m0s.
• --stats-file-name-length int — max file name length in stats (0 = no limit). Default is 45.
• --stats-log-level LogLevel — log level that the --stats output shows up at: DEBUG|INFO|NOTICE|ERROR. Default is INFO.
• --stats-one-line — make the stats fit on one line. iconic.
• --stats-one-line-date — enables --stats-one-line and adds the current date/time as a prefix.
• --stats-one-line-date-format string — enables --stats-one-line-date and lets you use a custom formatted date: enclose the date string in double quotes ("), see https://golang.org/pkg/time/#Time.Format.
• --stats-unit string — show the data rate in stats as either 'bits' or 'bytes' per second. Default is "bytes".
• --syslog — use Syslog for logging instead.
• --syslog-facility string — facility for syslog, e.g. KERN, USER. Default is "DAEMON".
• --use-json-log — use json log format, for the structured-logging girlies.
• -v, --verbose count — print lots more stuff — repeat it for even more. the classic.

---

✨ Metadata ✨

Flags to control metadata. it's giving organized 🎀

• -M, --metadata — if set, preserve metadata when copying objects. no losing the lore.
• --metadata-exclude stringArray — exclude metadatas matching 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 pattern.
• --metadata-include-from stringArray — read metadata include patterns from a file (use - to read from stdin).
• --metadata-mapper SpaceSepList — program to run to transforming metadata before upload.
• --metadata-set stringArray — add metadata key=value when uploading.

---

🌈 RC 🌈

Flags to control the Remote Control API. this is the whole control room bestie 💜

• --rc — enable the remote control server.
• --rc-addr stringArray — IPaddress:Port or :Port to bind the server to. Default is 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 is 1m0s.
• --rc-job-expire-interval Duration — interval to check for expired async jobs. Default is 10s.
• --rc-key string — TLS PEM Private key.
• --rc-max-header-bytes int — maximum size of request header. Default is 4096.
• --rc-min-tls-version string — minimum TLS version that is acceptable. Default is "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-response-header stringArray — set HTTP header for all responses, overriding existing values.
• --rc-salt string — password hashing salt. Default is "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 is 1h0m0s.
• --rc-server-write-timeout Duration — timeout for server writing data. Default is 1h0m0s.
• --rc-template string — user-specified template.
• --rc-user string — user name for authentication.
• --rc-user-from-header string — user name from a defined HTTP header.
• --rc-web-fetch-url string — URL to fetch the releases for webgui. Default is "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.

---

💫 Metrics 💫

Flags to control the Metrics HTTP endpoint. numbers girlies rise 🌸

• --metrics-addr stringArray — IPaddress:Port or :Port to bind server to.
• --metrics-allow-origin string — origin which cross-domain request (CORS) can be executed from.
• --metrics-baseurl string — prefix for URLs — leave 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 not provided, no authentication is done 🚨
• --metrics-key string — TLS PEM Private key.
• --metrics-max-header-bytes int — maximum size of request header. Default is 4096.
• --metrics-min-tls-version string — minimum TLS version that is acceptable. Default is "tls1.0".
• --metrics-pass string — password for authentication.
• --metrics-realm string — realm for authentication.
• --metrics-response-header stringArray — set HTTP header for all responses, overriding existing values.
• --metrics-salt string — password hashing salt. Default is "dlPL2MqE".
• --metrics-server-read-timeout Duration — timeout for server reading data. Default is 1h0m0s.
• --metrics-server-write-timeout Duration — timeout for server writing data. Default is 1h0m0s.
• --metrics-template string — user-specified template.
• --metrics-user string — user name for authentication.
• --metrics-user-from-header string — user name from a defined HTTP header.
• --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). yes bestie, the config file counts too 💖

okay bestie back for more, and it's the backends section so you KNOW it's a long one 💅 hydrate, stretch, we're going in 🫶

---

first up, alias — literally the simplest remote type on earth 🎀

• --alias-description string — the lil description of the remote 💖
• --alias-remote string — the remote (or path) you're aliasing to ✨

---

next, archive — the wrapper that lets you read archives like a normal remote 🦋

• --archive-description string — description of the remote 💜
• --archive-remote string — the remote you're wrapping so rclone can read archives out of it 📦

---

and now, Azure Blob time, which is a LOT of flags, no cap 😭

• --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, before, because you can't just overwrite them) 💀
• --azureblob-chunk-size SizeSuffix — upload chunk size (default 4Mi) 🧱
• --azureblob-client-certificate-password string — password for the certificate file, optional, and it's obscured 🔒
• --azureblob-client-certificate-path string — path to a PEM or PKCS12 certificate file that includes 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 🤫
• --azureblob-client-send-certificate-chain — send the certificate chain when you're using certificate auth ⛓️
• --azureblob-connection-string string — storage Connection String 🔌
• --azureblob-copy-concurrency int — concurrency for multipart copy (default 512) 🚀
• --azureblob-copy-cutoff SizeSuffix — cutoff for switching to multipart copy (default 8Mi) ✂️
• --azureblob-copy-total-concurrency int — the global concurrency limit for multipart copy chunks 🎚️
• --azureblob-decompress — if you set this, gzip encoded objects get decompressed 🗜️
• --azureblob-delete-snapshots string — set this to pick how snapshots get handled when a blob is deleted 📸
• --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 the MD5 checksum alongside object metadata 🙈
• --azureblob-disable-instance-discovery — skip asking for 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, i.e. environment variables, CLI, or MSI 🔑
• --azureblob-key string — Storage Account Shared Key 🗝️
• --azureblob-list-chunk int — size of the blob list (default 5000) 📋
• --azureblob-list-parallelism int — how many parallel shards to list a directory with 🧵
• --azureblob-msi-client-id string — object ID of the user-assigned MSI to use, if there is one 🪪
• --azureblob-msi-mi-res-id string — Azure resource ID of the user-assigned MSI to use, if there is one 🆔
• --azureblob-msi-object-id string — object ID of the user-assigned MSI to use, if there is one 🔖
• --azureblob-no-check-container — if set, don't bother checking whether the container exists or trying to create it 🙅‍♀️
• --azureblob-no-head-object — if set, skip the HEAD before the 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, and it's for container level access only 🎟️
• --azureblob-service-principal-file string — path to a file holding 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) and heads up bestie, this one is deprecated ⚠️
• --azureblob-use-arrow-list — use the Apache Arrow listing format 🏹
• --azureblob-use-az — use the Azure CLI tool az for authentication 💻
• --azureblob-use-copy-blob — whether to use the Copy Blob API when copying to the same storage account (default true) 📄
• --azureblob-use-emulator — uses the local storage emulator if you pass it as 'true' 🎭
• --azureblob-use-msi — use a managed service identity to authenticate, and this only works in Azure btw ☁️
• --azureblob-username string — user name, usually an email address 📧

---

and Azure Files, its sibling, with a very similar list because of course 🫶

• --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 — storage Connection String 🔌
• --azurefiles-description string — description of the remote 💖
• --azurefiles-disable-instance-discovery — skip requesting Microsoft Entra instance metadata 🚫
• --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, i.e. 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, for container level access only 🎟️
• --azurefiles-service-principal-file string — path to a 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-az — use the Azure CLI tool az for authentication 💻
• --azurefiles-use-emulator — uses the local storage emulator if provided as 'true' 🎭
• --azurefiles-use-msi — use a managed service identity to authenticate, only works in Azure ☁️
• --azurefiles-username string — user name, usually an email address 📧

---

okay and last for this round: Backblaze B2, aka the icon 👑🌈

• --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 files, meaning anything bigger than the upload cutoff 🙈
• --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 when they're removed from the remote, otherwise files just get hidden 💀
• --b2-key string — Application Key 🔑
• --b2-lifecycle int — set how many days deleted files should be kept when creating a bucket 🗓️
• --b2-sse-customer-algorithm string — if you're using SSE-C, the server-side encryption algorithm used when storing this object in B2 🧊
• --b2-sse-customer-key string — to use SSE-C, you may hand over the secret encryption key encoded in a UTF-8 compatible string to encrypt/decrypt your data 🔐
• --b2-sse-customer-key-base64 string — to use SSE-C, you may hand over the secret encryption key encoded in Base64 format to encrypt/decrypt your data 🔐
• --b2-sse-customer-key-md5 string — if you're using SSE-C you may provide the secret encryption key MD5 checksum, and this one's optional ✅
• --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 👵

---

and that's not even all the backends, bestie, there's so much more coming 💖 stay with me 🫶

• --box-access-token string — the Primary Access Token for your Box App ✨
• --box-auth-url string — the URL of the auth server, bestie 🎀
• --box-box-config-file string — where your Box App's config.json lives 📁
• --box-box-sub-type string — (default "user") 🫶
• --box-client-credentials — flip this on to use the client credentials OAuth flow 💅
• --box-client-id string — your OAuth Client Id 👑
• --box-client-secret string — your OAuth Client Secret (keep it secret, fr fr) 🙈
• --box-commit-retries int — max number of times it'll try to commit a multipart file (default 100) 🔁
• --box-description string — a lil 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 you're rolling with a service account 🎭
• --box-list-chunk int — size of a listing chunk, 1-1000 (default 1000) 📜
• --box-owned-by string — only show items owned by the login (email address) you pass in here 📧
• --box-root-folder-id string — fill this in so rclone starts from a non-root folder instead of the usual root 🗂️
• --box-token string — your OAuth Access Token as a JSON blob 🔑
• --box-token-url string — the token server url 🌐
• --box-upload-cutoff SizeSuffix — the cutoff for switching over to multipart upload, and it has to be >= 50 MiB (default 50Mi) ✂️
• --cache-chunk-clean-interval Duration — how often the cache should do cleanups of the chunk storage (default 1m0s) 🧹
• --cache-chunk-no-memory — turn off the in-memory cache for storing chunks while streaming 🚫
• --cache-chunk-path string — the directory where chunk files get cached (default "$HOME/.cache/rclone/cache-backend") 🗄️
• --cache-chunk-size SizeSuffix — the size of a chunk (that's partial file data, iykyk) (default 5Mi) 🍰
• --cache-chunk-total-size SizeSuffix — the total size chunks can eat up on your local disk (default 10Gi) 💾
• --cache-db-path string — the directory where the file structure metadata DB lives (default "$HOME/.cache/rclone/cache-backend") 📚
• --cache-db-purge — wipe ALL the cached data for this remote on start 🧼
• --cache-db-wait-time Duration — how long to wait for the DB to be available — 0 means unlimited (default 1s) ⏳
• --cache-description string — a description of the remote 📝
• --cache-info-age Duration — how long to cache file structure info (directory listings, file size, times, etc.) (default 6h0m0s) 🕰️
• --cache-plex-insecure string — skip ALL certificate verification when connecting to the Plex server 😬
• --cache-plex-password string — the password of the Plex user (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 to retry a read from a cache storage (default 10) 🔁
• --cache-remote string — the remote you want to cache 🎯
• --cache-rps int — limits the number of requests per second to the source FS (-1 to disable) (default -1) 🚦
• --cache-tmp-upload-path string — the directory to keep temporary files in until they get uploaded 📤
• --cache-tmp-wait-time Duration — how long files should sit in the local cache before being uploaded (default 15s) ⏱️
• --cache-workers int — how many workers should run in parallel to download chunks (default 4) 👷
• --cache-writes — cache file data on writes through the FS ✍️
• --chunker-chunk-size SizeSuffix — any files bigger than the chunk size get split into chunks (default 2Gi) 🍬
• --chunker-description string — a 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-adjust-media-files-extensions — Cloudinary treats media formats as a file attribute and strips it from the name, which is NOT what most other file systems do (default true) 🎞️
• --cloudinary-api-key string — your Cloudinary API Key 🔑
• --cloudinary-api-secret string — your Cloudinary API Secret 🤫
• --cloudinary-cloud-name string — your Cloudinary Environment Name ☁️
• --cloudinary-description string — a 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-media-extensions stringArray — the media extensions Cloudinary supports (default 3ds,3g2,3gp,ai,arw,avi,avif,bmp,bw,cr2,cr3,djvu,dng,eps3,fbx,flif,flv,gif,glb,gltf,hdp,heic,heif,ico,indd,jp2,jpe,jpeg,jpg,jxl,jxr,m2ts,mov,mp4,mpeg,mts,mxf,obj,ogv,pdf,ply,png,psd,svg,tga,tif,tiff,ts,u3ma,usdz,wdp,webm,webp,wmv) 🖼️
• --cloudinary-upload-prefix string — specify the API endpoint for environments that are out of the US 🌍
• --cloudinary-upload-preset string — the Upload Preset to select asset manipulation on upload 🎨
• --combine-description string — a description of the remote 📝
• --combine-upstreams SpaceSepList — the upstreams you're combining 🔗
• --compress-description string — a description of the remote 📝
• --compress-level string — GZIP levels, from -2 to 9: 🗜️
• --compress-mode string — the compression mode (default "gzip") 🧃
• --compress-ram-cache-limit SizeSuffix — some remotes don't let you upload files with an 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 description of the remote 📝
• --crypt-directory-name-encryption — 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 — option to either encrypt file data or leave it unencrypted 🙅
• --crypt-pass-bad-blocks — if you set this, bad blocks get passed through as all 0 0️⃣
• --crypt-password string — the password or pass phrase for encryption (obscured) 🔑
• --crypt-password2 string — the password or pass phrase for the 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 every file listed, show how the names encrypt 👀
• --crypt-strict-names — if you set this, it'll raise an error whenever crypt comes across a filename it can't decrypt 😤
• --crypt-suffix string — if you set this it overrides the default suffix of ".bin" (default ".bin") 🏷️
• --doi-description string — a description of the remote 📝
• --doi-doi string — the DOI, or the doi.org URL 🔗
• --doi-doi-resolver-api-url string — the URL of the DOI resolver API to use 🌐
• --doi-provider string — the DOI provider 🏢
• --drime-access-token string — API Access token 🔑
• --drime-chunk-size SizeSuffix — chunk size to use for uploading (default 5Mi) 🍫
• --drime-description string — a description of the remote 📝
• --drime-encoding Encoding — the encoding for the backend (default Slash,BackSlash,Del,Ctl,LeftSpace,RightSpace,InvalidUtf8,Dot) 🌈
• --drime-hard-delete — delete files permanently instead of tossing them into the trash 🗑️
• --drime-list-chunk int — number of items to list in each call (default 1000) 📜
• --drime-root-folder-id string — the ID of the root folder 📂
• --drime-upload-concurrency int — concurrency for multipart uploads and copies (default 4) 👯
• --drime-upload-cutoff SizeSuffix — cutoff for switching to chunked upload (default 5Mi) ✂️
• --drime-workspace-id string — the Account ID 🆔
• --drive-acknowledge-abuse — set this to allow files that return cannotDownloadAbusiveFile to still be downloaded ⚠️
• --drive-allow-import-name-change — allow the filetype to change when you upload Google docs 🔄
• --drive-auth-owner-only — only consider files owned by the authenticated user 🙋
• --drive-auth-url string — the auth server URL 🌐
• --drive-chunk-size SizeSuffix — the upload chunk size (default 8Mi) 📦
• --drive-client-credentials — use the client credentials OAuth flow 💅
• --drive-client-id string — your Google Application Client Id 👑

…and we're still in flag city, bestie 💅 no thoughts, just options, and honestly? iconic behaviour.

• --drive-client-secret string — your Google Application 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) — yep, it's on by default, so this flag turns it off
• --drive-encoding Encoding — the encoding for the backend (default InvalidUtf8) 🔤
• --drive-env-auth — get IAM credentials from the runtime, meaning environment variables, or instance meta data 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, like a sentimental queen ♾️
• --drive-list-chunk int — size of listing chunk, 100-1000, or 0 to disable (default 1000)
• --drive-metadata-enforce-expansive-access — whether the request should enforce expansive access rules
• --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 in listings, and yes, even the non-exportable ones
• --drive-size-as-quota — show sizes as storage quota usage, not 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 — OAuth Access Token as a JSON blob
• --drive-token-url string — Token server url
• --drive-trashed-only — only show files that are in the trash 🗑️
• --drive-upload-cutoff SizeSuffix — cutoff for switching to chunked upload (default 8Mi)
• --drive-use-created-date — use file created date instead of modified date
• --drive-use-shared-date — use date file was shared instead of modified date
• --drive-use-trash — send files to the trash instead of deleting permanently (default true) 🗑️
• --drive-v2-download-min-size SizeSuffix — if Object's are greater, use drive v2 API to download (default off)

---

dropbox 🦋 — short king of cloud storage, lots of knobs though:

• --dropbox-auth-url string — Auth server URL
• --dropbox-batch-mode string — upload file batching, one of sync|async|off (default "sync")
• --dropbox-batch-size int — max number of files in upload batch
• --dropbox-batch-timeout Duration — max time to allow an idle upload batch before uploading (default 0s)
• --dropbox-chunk-size SizeSuffix — upload chunk size (< 150Mi) (default 48Mi)
• --dropbox-client-credentials — use client credentials OAuth flow
• --dropbox-client-id string — OAuth Client Id
• --dropbox-client-secret string — OAuth Client Secret
• --dropbox-description string — description of the remote
• --dropbox-encoding Encoding — the encoding for the backend (default Slash,BackSlash,Del,RightSpace,InvalidUtf8,Dot)
• --dropbox-export-formats CommaSepList — comma separated list of preferred formats for exporting files (default html,md)
• --dropbox-impersonate string — impersonate this user when using a business account
• --dropbox-impersonate-admin string — team admin ID to use when performing actions as a team administrator
• --dropbox-pacer-min-sleep Duration — minimum time to sleep between API calls (default 10ms)
• --dropbox-root-namespace string — specify a different Dropbox namespace ID to use as the root for all paths
• --dropbox-shared-files — instructs rclone to work on individual shared files
• --dropbox-shared-folders — instructs rclone to work on shared folders
• --dropbox-show-all-exports — show all exportable files in listings
• --dropbox-skip-exports — skip exportable files in all listings
• --dropbox-skip-shared-folders — instructs rclone to skip all shared folders
• --dropbox-skip-unowned-folders — instructs rclone to skip shared folders not owned by the current user
• --dropbox-token string — OAuth Access Token as a JSON blob
• --dropbox-token-url string — Token server url

---

fichier 🍓 — the French one, oui oui:

• --fichier-api-key string — your API Key, get it from https://1fichier.com/console/params.pl
• --fichier-cdn — set if you wish to 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 want to download a shared file that is password protected, add this parameter (obscured) 🔒
• --fichier-folder-password string — if you want to list the files in a shared folder that is password protected, add this parameter (obscured) 🔒
• --fichier-shared-folder string — if you want to download a shared folder, add this parameter

---

filefabric 🧵:

• --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 to connect to
• --filefabric-version string — version read from the file fabric

---

filelu ✨:

• --filelu-chunk-size SizeSuffix — chunk size to use for uploading, used for multipart uploads (default 64Mi)
• --filelu-description string — description of the remote
• --filelu-encoding Encoding — the encoding for the backend (default Slash,LtGt,DoubleQuote,SingleQuote,BackQuote,Dollar,Colon,Question,Asterisk,Pipe,Hash,Percent,BackSlash,CrLf,Del,Ctl,LeftSpace,LeftPeriod,LeftTilde,LeftCrLfHtVt,RightSpace,RightPeriod,RightCrLfHtVt,InvalidUtf8,Dot,SquareBracket,Semicolon,Exclamation) — look at that default, it ate and left no crumbs 😭
• --filelu-key string — your FileLu Rclone key from My Account 🔑
• --filelu-upload-cutoff SizeSuffix — cutoff for switching to chunked upload; any files larger than this will be uploaded in chunks of chunk_size (default 500Mi)

---

filen 🎀:

• --filen-api-key string — API Key for your Filen account (obscured) 🔐
• --filen-auth-version string — authentication Version (internal use only)
• --filen-base-folder-uuid string — UUID of Account Root Directory (internal use only)
• --filen-description string — description of the remote
• --filen-email string — email of your Filen account 📧
• --filen-encoding Encoding — the encoding for the backend (default Slash,Del,Ctl,InvalidUtf8,Dot)
• --filen-master-keys string — master Keys (internal use only)

---

still going, bestie — the flag list is lowkey endless but we're eating it one backend at a time 💅🌸

okay the flag parade is STILL going bestie, we're not even close to done 💅 and lowkey this stretch is a whole world tour of backends — Filen, Files.com, FTP, Google Cloud Storage, Gofile, Google Photos, Hasher, HDFS and HiDrive all pulling up at once. buckle in ✨

• --filen-password string — the password for your Filen account, all secret-squirrel and hidden from view (obscured) 🔒
• --filen-private-key string — your Private RSA Key — internal use only, don't go touching this unless you know exactly what you're doing 🙈
• --filen-public-key string — your Public RSA Key — also internal use only, same vibe, hands off bestie 🫶
• --filen-upload-concurrency int — how many chunked uploads can happen at once (default 16) 🚀
• --filescom-api-key string — the API key that gets you into Files.com 🔑
• --filescom-description string — a lil description of the remote, for your own notes 📝
• --filescom-encoding Encoding — the encoding for this backend (default Slash,BackSlash,Del,Ctl,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot) 🔤
• --filescom-password string — the password that gets you into Files.com, obscured ofc 🤫
• --filescom-site string — your site subdomain (like mysite) or your custom domain (like myfiles.customdomain.com) 🌐
• --filescom-username string — the username that gets you into Files.com 👤
• --ftp-allow-insecure-tls-ciphers — allow insecure TLS ciphers, yes it's giving risky 💀
• --ftp-ask-password — lets rclone ask you for the FTP password when it needs it 🙋
• --ftp-close-timeout Duration — max time to wait for a response to close (default 1m0s) ⏳
• --ftp-concurrency int — max number of simultaneous FTP connections, or 0 for unlimited (iykyk, unlimited is a mood) 🔥
• --ftp-description string — a cute description of the remote 🎀
• --ftp-disable-epsv — stop using EPSV even if the server says it supports it 🚫
• --ftp-disable-mlsd — stop using MLSD even if the server says it supports it 🚫
• --ftp-disable-tls13 — disable TLS 1.3, aka the workaround for FTP servers rockin' buggy TLS 🐛
• --ftp-disable-utf8 — stop using UTF-8 even if the server says it supports it 🚫
• --ftp-encoding Encoding — the encoding for this backend (default Slash,Del,Ctl,RightSpace,Dot) 🔤
• --ftp-explicit-tls — use Explicit FTPS, that's FTP over TLS periodt 🔐
• --ftp-force-list-hidden — use LIST -a to force listing of hidden files and folders. heads up: this will disable the use of MLSD ⚠️
• --ftp-host string — the FTP host to connect to 🖥️
• --ftp-http-proxy string — URL for an HTTP CONNECT proxy 🔀
• --ftp-idle-timeout Duration — max time before closing idle connections (default 1m0s) 😴
• --ftp-no-check-certificate — do NOT verify the TLS certificate of the server, lowkey risky bestie 💀
• --ftp-no-check-upload — don't check that the upload actually went OK 🙈
• --ftp-pass string — your FTP password, obscured ofc 🤫
• --ftp-port int — the 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 — use Implicit FTPS, that's FTP over TLS again, different flavor 🔐
• --ftp-tls-cache-size int — size of the TLS session cache for all control and data connections (default 32) 🗄️
• --ftp-user string — your FTP username (default "$USER") 👤
• --ftp-writing-mdtm — use MDTM to set the modification time, aka the VsFtpd quirk 🕰️
• --gcs-access-token string — a short-lived access token 🎟️
• --gcs-anonymous — access public buckets and objects with no credentials at all, just vibes 🕶️
• --gcs-auth-url string — the auth server URL 🔗
• --gcs-bucket-acl string — the Access Control List for any new buckets you make 📋
• --gcs-bucket-policy-only — access checks should use bucket-level IAM policies 👑
• --gcs-client-credentials — use the client credentials OAuth flow 🔑
• --gcs-client-id string — your OAuth Client Id 🪪
• --gcs-client-secret string — your OAuth Client Secret, keep it secret bestie 🤫
• --gcs-decompress — if you set this, it will decompress gzip encoded objects 📦
• --gcs-description string — a lil description of the remote ✍️
• --gcs-directory-markers — upload an empty object with a trailing slash whenever a new directory is created 📁
• --gcs-encoding Encoding — the encoding for this backend (default Slash,CrLf,InvalidUtf8,Dot) 🔤
• --gcs-endpoint string — a custom endpoint for the storage API. leave it blank to just use the provider default 🛰️
• --gcs-env-auth — grab your GCP IAM credentials from runtime — that's environment variables, or instance meta data if there are no env vars 🌱
• --gcs-location string — the location for the newly created buckets 📍
• --gcs-no-check-bucket — if set, don't even attempt to check that the bucket exists or create it 🚫
• --gcs-object-acl string — the Access Control List for new objects 📋
• --gcs-project-number string — your project number 🔢
• --gcs-service-account-file string — path to your Service Account Credentials JSON file 📄
• --gcs-storage-class string — the storage class to use when storing objects in Google Cloud Storage 🗂️
• --gcs-token string — your OAuth Access Token, dropped in as a JSON blob 🎟️
• --gcs-token-url string — the token server url 🔗
• --gcs-user-project string — your user project 👤
• --gofile-access-token string — the API Access token 🎟️
• --gofile-account-id string — your Account ID 🪪
• --gofile-description string — a description of the remote, cute cute ✍️
• --gofile-encoding Encoding — the encoding for this 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 — the ID of the root folder 📁
• --gphotos-auth-url string — the auth server URL 🔗
• --gphotos-batch-mode string — uploading file batching, one of sync|async|off (default "sync") 📦
• --gphotos-batch-size int — max number of files allowed in an upload batch 🔢
• --gphotos-batch-timeout Duration — max time to let an idle upload batch sit around before it uploads (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, shhh 🤫
• --gphotos-description string — a description of the remote ✍️
• --gphotos-encoding Encoding — the encoding for this backend (default Slash,CrLf,InvalidUtf8,Dot) 🔤
• --gphotos-include-archived — also view and download your archived media 🗄️
• --gphotos-proxy string — use the gphotosdl proxy for downloading the full resolution images 🖼️
• --gphotos-read-only — set this to make the Google Photos backend read only 👀
• --gphotos-read-size — set this to read the size of media items 📏
• --gphotos-start-year int — the year limits the photos to be downloaded to those uploaded after the given year (default 2000) 📅
• --gphotos-token string — your OAuth Access Token, as a JSON blob 🎟️
• --gphotos-token-url string — the token server url 🔗
• --hasher-auto-size SizeSuffix — auto-update the checksum for files smaller than this size, disabled by default ✨
• --hasher-description string — a description of the remote ✍️
• --hasher-hashes CommaSepList — a comma separated list of the supported checksum types (default md5,sha1) 🧮
• --hasher-max-age Duration — max time to keep checksums hanging out in the cache (0 = no cache, off = cache forever) (default off) ⏳
• --hasher-remote string — the remote to cache checksums for (e.g. myRemote:path) 🗃️
• --hdfs-data-transfer-protection string — Kerberos data transfer protection, pick your fighter: authentication|integrity|privacy 🔐
• --hdfs-description string — a description of the remote ✍️
• --hdfs-encoding Encoding — the encoding for this backend (default Slash,Colon,Del,Ctl,InvalidUtf8,Dot) 🔤
• --hdfs-namenode CommaSepList — your Hadoop name nodes and ports 🐘
• --hdfs-service-principal-name string — the Kerberos service principal name for the namenode 👑
• --hdfs-username string — your Hadoop user name 👤
• --hidrive-auth-url string — the auth server URL 🔗
• --hidrive-chunk-size SizeSuffix — the chunksize for chunked uploads (default 48Mi) 🧩
• --hidrive-client-credentials — use the client credentials OAuth flow 🔑
• --hidrive-client-id string — your OAuth Client Id 🪪
• --hidrive-client-secret string — your OAuth Client Secret, keep it tucked away 🤫
• --hidrive-description string — a description of the remote ✍️
• --hidrive-disable-fetching-member-count — do not fetch the number of objects in directories unless it's absolutely necessary 🙅
• --hidrive-encoding Encoding — the encoding for this backend (default Slash,Dot) 🔤
• --hidrive-endpoint string — the endpoint for the service (default "https://api.hidrive.strato.com/2.1") 🛰️

and that's the roundup for this batch bestie, but the flag list keeps unfolding like a lil accordion of power tools, so don't go anywhere 💖

• --hidrive-root-prefix string — the root/parent folder for all paths, aka where your HiDrive journey starts (default "/") 🏠
• --hidrive-scope-access string — the access permissions rclone should ask HiDrive for when requesting access (default "rw") 🔑
• --hidrive-scope-role string — the user-level rclone should request from HiDrive (default "user") 👤
• --hidrive-token string — OAuth Access Token, handed over 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 — a lil 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 the HTTP host to connect to 🌐
• --huaweidrive-auth-url string — Auth server URL
• --huaweidrive-chunk-size SizeSuffix — upload chunk size (default 8Mi)
• --huaweidrive-client-credentials — use the client credentials OAuth flow
• --huaweidrive-client-id string — OAuth Client Id
• --huaweidrive-client-secret string — OAuth Client Secret 🤫
• --huaweidrive-description string — a lil description of the remote 🏷️
• --huaweidrive-encoding Encoding — the encoding for the backend (default Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftSpace,LeftPeriod,LeftTilde,RightSpace,RightPeriod,InvalidUtf8,Dot)
• --huaweidrive-list-chunk int — size of listing chunk, 1-1000 (default 1000) 📜
• --huaweidrive-root-folder-id string — ID of the root folder
• --huaweidrive-token string — OAuth Access Token, as a JSON blob 🎟️
• --huaweidrive-token-url string — Token server url
• --huaweidrive-upload-cutoff SizeSuffix — cutoff for switching to resumable upload (default 20Mi)
• --iclouddrive-apple-id string — your Apple ID 🍎
• --iclouddrive-client-id string — Client ID for iCloud API access (default "d39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d")
• --iclouddrive-description string — a lil description of the remote 🏷️
• --iclouddrive-encoding Encoding — the encoding for the backend (default Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot)
• --iclouddrive-password string — Password (obscured) 🤫
• --iclouddrive-service string — which iCloud service to use (default "drive") ☁️
• --imagekit-description string — a lil 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've 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 — a lil description of the remote 🏷️
• --internetarchive-disable-checksum — don't ask the server to test against the 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 the InternetArchive Frontend (default "https://archive.org")
• --internetarchive-item-derive — whether to trigger derive on the IA item or not. if set to false, the item will not be derived by IA upon upload (default true)
• --internetarchive-item-metadata stringArray — metadata to be set on the IA item; heads up, this is different from file-level metadata that you can set using --metadata-set
• --internetarchive-secret-access-key string — IAS3 Secret Key (password) 🤫
• --internetarchive-wait-archive Duration — timeout for waiting for the server's processing tasks (specifically archive and book_op) to finish (default 0s) ⏳
• --internxt-chunk-size SizeSuffix — chunk size for multipart uploads (default 30Mi)
• --internxt-description string — a lil description of the remote 🏷️
• --internxt-email string — email of your Internxt account 📧
• --internxt-encoding Encoding — the encoding for the backend (default Slash,BackSlash,CrLf,RightPeriod,InvalidUtf8,Dot)
• --internxt-pass string — Password (obscured) 🤫
• --internxt-skip-hash-validation — skip hash validation when downloading files (default true)
• --internxt-upload-concurrency int — concurrency for multipart uploads (default 4) 🚀
• --internxt-upload-cutoff SizeSuffix — cutoff for switching to multipart upload (default 100Mi)
• --jottacloud-auth-url string — Auth server URL
• --jottacloud-client-credentials — use the client credentials OAuth flow
• --jottacloud-client-id string — OAuth Client Id
• --jottacloud-client-secret string — OAuth Client Secret 🤫
• --jottacloud-description string — a lil description of the remote 🏷️
• --jottacloud-encoding Encoding — the encoding for the backend (default Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Percent,Del,Ctl,InvalidUtf8,Dot)
• --jottacloud-hard-delete — delete files permanently instead of yeeting them into the trash 🗑️
• --jottacloud-md5-memory-limit SizeSuffix — files bigger than this get 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) (yes, that apostrophe is exactly as written, bestie)
• --koofr-description string — a lil 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 — a lil description of the remote 🏷️
• --linkbox-email string — email for login 📧
• --linkbox-password string — password for login (obscured) 🤫
• --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 lil description of the remote 🏷️
• --local-encoding Encoding — the encoding for the backend (default Slash,Dot)
• --local-fatal-if-no-space — make out-of-space errors fatal during transfers 💀
• --local-hashes CommaSepList — comma separated list of supported checksum types
• --local-links — translate symlinks to/from regular files with a .rclonelink extension for the local backend 🔗
• --local-metadata-restore-special-bits — restore the setuid, setgid and sticky bits from metadata
• --local-no-check-updated — don't check to see if the files change during upload 👀
• --local-no-clone — disable reflink cloning for server-side copies
• --local-no-preallocate — disable preallocation of disk space for transferred files
• --local-no-set-modtime — disable setting modtime ⏰
• --local-no-sparse — disable sparse files for multi-thread downloads
• --local-nounc — turns OFF the UNC long-path-name conversion thing on Windows. Windows girlies, this one's for u 💅
• --local-time-type mtime|atime|btime|ctime — picks which kinda time gets handed back (default mtime). btw btime = birth time, ctime = the change-y one, so choose wisely bestie 🕐
• --local-unicode-normalization — hits ur paths and filenames with unicode NFC normalization. ✨ Cleanup era. ✨
• --local-zero-size-links — assumes the Stat size of links is zero (and just reads them instead). Deprecated, so like… do not 🙈
• --mailru-auth-url string — the auth server URL.
• --mailru-check-hash — decides what copy does when a file checksum is mismatched or invalid (default true). No cap, it's policing ur hashes 🕵️♀️
• --mailru-client-credentials — use the client credentials OAuth flow.
• --mailru-client-id string — ur OAuth Client Id.
• --mailru-client-secret string — ur OAuth Client Secret. Keep it secret bestie 🤫
• --mailru-description string — a lil 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 — ur password (obscured) 🔒
• --mailru-speedup-enable — skips the full upload if there's already another file with the same data hash (default true). Main character energy: why re-upload when the vibes are already there 💅
• --mailru-speedup-file-patterns string — a comma separated list of file name patterns that are eligible for speedup (put by hash) (default "*.mkv,*.avi,*.mp4,*.mp3,*.zip,*.gz,*.rar,*.pdf").
• --mailru-speedup-max-disk SizeSuffix — here u can switch OFF speedup (put by hash) for the big files (default 3Gi).
• --mailru-speedup-max-memory SizeSuffix — anything bigger than this size always gets hashed on disk instead (default 32Mi).
• --mailru-token string — OAuth Access Token, as a JSON blob.
• --mailru-token-url string — the token server url.
• --mailru-user string — ur user name (usually the email) 👤

---

ok next up, MEGA my beloved 💖

• --mega-2fa string — the 2FA code for ur MEGA account, if u set one up. Two-factor bestie, protect urself 🔐
• --mega-debug — outputs more debug info from Mega. Spill the tea ☕
• --mega-description string — a description of the remote.
• --mega-encoding Encoding — the encoding for the backend (default Slash,InvalidUtf8,Dot).
• --mega-hard-delete — deletes files permanently instead of yeeting them into the trash. 💀 No undo, bestie. RIP to those files fr fr
• --mega-pass string — password (obscured).
• --mega-use-https — use HTTPS for transfers. As u should. Secure queen 👑
• --mega-user string — user name.
• --memory-description string — description of the remote.
• --memory-discard — if u set this, ALL writes get thrown away and reads will return an error. Like a lil void that eats ur data 😭 (fr, only if u know what ur doing)
• --netstorage-account string — sets the NetStorage account name.
• --netstorage-description string — description of the remote.
• --netstorage-host string — the domain + path of the NetStorage host to connect to.
• --netstorage-protocol string — pick between HTTP or HTTPS (default "https"). https girlies rise 🌈
• --netstorage-secret string — sets the NetStorage account secret / G2O key for authentication (obscured). 🤐
• -x, --one-file-system — don't cross filesystem boundaries (unix/macOS only). Staying in ur lane, lowkey iconic 🦋

---

ONEDRIVE TIME 🎀 (she has SO many flags, she's that girl)

• --onedrive-access-scopes SpaceSepList — sets the scopes rclone asks for (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 u download files the server thinks have a virus. Careful bestie, that's a yikes 💀
• --onedrive-chunk-size SizeSuffix — the chunk size for uploading files with — must be a multiple of 320k (327,680 bytes) (default 10Mi). Math is mathing 📐
• --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 — if set, rclone uses delta listing to do recursive listings. Sneaky efficient ✨
• --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. Not them hiding from u 🙈
• --onedrive-hard-delete — permanently deletes files when u remove them. Gone gone, no trash can 💀
• --onedrive-hash-type string — tells it which hash the backend is using (default "auto"). Let her choose, she's got it 💅
• --onedrive-link-password string — sets the password for links created by the link command.
• --onedrive-link-scope string — sets the scope of the links created by the link command (default "anonymous").
• --onedrive-link-type string — sets the type of the links created by the link command (default "view").
• --onedrive-list-chunk int — size of the listing chunk (default 1000).
• --onedrive-metadata-permissions Bits — controls whether permissions get read or written in metadata (default off).
• --onedrive-no-versions — removes all versions on modifying operations. History? Don't know her ✂️
• --onedrive-region string — choose 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. She's retired bestie, let her rest 🫶
• --onedrive-tenant string — ID of the service principal's tenant. Also called its directory ID.
• --onedrive-tenant-url string — the tenant URL for non-admin OneDrive access.
• --onedrive-token string — OAuth Access Token as a JSON blob.
• --onedrive-token-url string — token server url.
• --onedrive-upload-cutoff SizeSuffix — the cutoff for switching to chunked upload (default off).

---

and now… Oracle Object Storage, aka OOS 👑

• --oos-attempt-resume-upload — if true, it tries to resume a previously started multipart upload for the object. Picking up where she left off 💪
• --oos-chunk-size SizeSuffix — chunk size to use for uploading (default 5Mi).
• --oos-compartment string — specify the compartment OCID, in case u need to list buckets.
• --oos-config-file string — path to the OCI config file (default "~/.oci/config").
• --oos-config-profile string — profile name inside the 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-decompress — if u set this, it decompresses gzip encoded objects. Unzipping the vibe 🫧
• --oos-description string — description of the remote.
• --oos-disable-checksum — doesn't store the MD5 checksum with the object metadata. Trust issues, honestly 😌
• --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, it avoids calling abort upload on a failure, leaving all the successfully uploaded parts there for u to manually recover. Messy but recoverable 💅
• --oos-max-upload-parts int — max number of parts in a multipart upload (default 10000).
• --oos-namespace string — object storage namespace.
• --oos-no-check-bucket — if set, it won't bother checking if the bucket exists or creating it. Straight to business 🚀
• --oos-provider string — choose ur Auth Provider (default "env_auth").
• --oos-region string — object storage Region.
• --oos-sse-customer-algorithm string — if u use SSE-C, this is the optional header that 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 u use ur 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).

---

last lil group for this part, OpenDrive bestie 🍓

• --opendrive-access string — files and folders get uploaded with this access permission (default private) (default "private").
• --opendrive-chunk-size SizeSuffix — files get uploaded in chunks of this size (default 10Mi).
• --opendrive-description string — a lil free-text blurb for this remote, just so future you knows what it is 🎀
• --opendrive-encoding Encoding — the encoding for the backend, defaulting to Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,LeftSpace,LeftCrLfHtVt,RightSpace,RightCrLfHtVt,InvalidUtf8,Dot ✨
• --opendrive-password string — password, and yes it's obscured 🔒
• --opendrive-username string — username, bestie
• --pcloud-auth-url string — the auth server URL
• --pcloud-client-credentials — use the client credentials OAuth flow
• --pcloud-client-id string — OAuth Client Id
• --pcloud-client-secret string — OAuth Client Secret
• --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 other than the root folder (default "d0")
• --pcloud-token string — OAuth Access Token, handed over as a JSON blob
• --pcloud-token-url string — 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) — yes that's a whole mouthful, no cap
• --pikpak-hash-memory-limit SizeSuffix — files bigger than this get cached on disk so the hash can be calculated if it's needed (default 10Mi)
• --pikpak-no-media-link — use the original file links instead of media links 🔗
• --pikpak-pass string — Pikpak password, obscured
• --pikpak-root-folder-id string — the ID of the root folder
• --pikpak-trashed-only — only show the files chilling in the trash 🗑️
• --pikpak-upload-concurrency int — concurrency for multipart uploads (default 4)
• --pikpak-upload-cutoff SizeSuffix — the cutoff for switching over to chunked upload (default 200Mi)
• --pikpak-use-trash — send files to the trash instead of deleting them forever (default true) — much safer vibe honestly
• --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") — she's cosplaying Firefox, iconic
• --pixeldrain-api-key string — the API key for your pixeldrain account
• --pixeldrain-api-url string — the API endpoint to connect to; in the vast majority of cases it's totally fine to leave this alone (default "https://pixeldrain.com/api")
• --pixeldrain-description string — description of the remote 💅
• --pixeldrain-root-folder-id string — the 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
• --protondrive-description string — description of the remote
• --protondrive-enable-caching — caches the files and folders metadata so it makes 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 as it was before encryption (default true)
• --protondrive-otp-secret-key string — the OTP secret key, obscured 🤫
• --protondrive-password string — the password of your proton account, obscured
• --protondrive-replace-existing-draft — create a new revision when a filename conflict gets detected
• --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 — number of connection retries (default 3)
• --qingstor-description string — description of the remote
• --qingstor-encoding Encoding — the encoding for the backend (default Slash,Ctl,InvalidUtf8)
• --qingstor-endpoint string — enter an endpoint URL to connect to the QingStor API
• --qingstor-env-auth — get QingStor credentials from runtime
• --qingstor-secret-access-key string — QingStor Secret Access Key (password) 🔑
• --qingstor-upload-concurrency int — concurrency for multipart uploads (default 1)
• --qingstor-upload-cutoff SizeSuffix — cutoff for switching 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 — 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 putting them in the trash 💀 — no undo, bestie, be so serious
• --quatrix-host string — the host name of your Quatrix account
• --quatrix-maximal-summary-chunk-size SizeSuffix — the maximal summary for all chunks; it should not be less than 'transfers'*'minimal_chunk_size' (default 95.367Mi)
• --quatrix-minimal-chunk-size SizeSuffix — the minimal size for one chunk (default 9.537Mi)
• --quatrix-skip-project-folders — skip project folders in operations 🙈
• --s3-access-key-id string — AWS Access Key ID
• --s3-acl string — the canned ACL used when creating buckets and storing or copying objects
• --s3-bucket-acl string — the canned ACL used when creating buckets
• --s3-bucket-object-lock-enabled — enable Object Lock when creating new buckets 🔒
• --s3-bypass-governance-retention — allow deleting or modifying objects that are locked with GOVERNANCE mode ⚠️ — this one is a big deal, fr fr, governance locks exist for a reason
• --s3-chunk-size SizeSuffix — chunk size to use for uploading (default 5Mi)
• --s3-copy-cutoff SizeSuffix — cutoff for switching to multipart copy (default 4.656Gi)
• --s3-decompress — if set, this 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 when a new directory gets created
• --s3-disable-checksum — don't store the MD5 checksum with the object metadata
• --s3-disable-http2 — disable usage of http2 for S3 backends
• --s3-download-url string — 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 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-ibm-api-key string — IBM API Key to be used to obtain an IAM token 👑
• --s3-ibm-iam-endpoint string — the IBM IAM Endpoint ur supposed to auth against 💅
• --s3-ibm-resource-instance-id string — ur IBM service instance id, bestie
• --s3-leave-parts-on-error — if true, rclone will NOT call abort upload when something dies 😭 so every part that did make it up stays on S3 for u to recover by hand. it's giving "i'll deal with it later", but for real
• --s3-list-chunk int — how big each listing chunk is, aka the response list for every single ListObject S3 request (default 1000)
• --s3-list-url-encode Tristate — do we url encode listings or nah: true/false/unset (default unset)
• --s3-list-version int — which version of the ListObjects API to use: 1, 2, or 0 for auto ✨
• --s3-list-versions-oldest-first Tristate — flip this on if ur backend hands back object versions oldest first (default unset)
• --s3-location-constraint string — the location constraint, and lowkey it must be set to match the Region 🫶
• --s3-max-upload-parts int — max number of parts in a multipart upload (default 10000)
• --s3-might-gzip Tristate — set this if the backend might gzip objects (default unset)
• --s3-no-check-bucket — if set, pls do not attempt to check the bucket exists, and don't create it either 💀
• --s3-no-head — skips the HEAD on uploaded objects, so no integrity check. ur choice, queen
• --s3-no-head-object — if set, no HEAD before GET when getting objects
• --s3-no-system-metadata — suppress the setting and reading of system metadata entirely
• --s3-object-lock-legal-hold-status string — Object Lock legal hold status to apply when uploading or copying objects 🔒
• --s3-object-lock-mode string — Object Lock mode to apply when uploading or copying objects
• --s3-object-lock-retain-until-date string — Object Lock retention until date to apply when uploading or copying objects
• --s3-object-lock-set-after-upload — sets Object Lock with separate API calls after the upload, vv extra but ok
• --s3-object-lock-supported Tristate — does ur provider even support S3 Object Lock (default unset)
• --s3-profile string — the profile to use in the shared credentials file
• --s3-provider string — choose ur S3 provider, main character decision fr
• --s3-region string — region to connect to
• --s3-requester-pays — turns on the requester pays option when interacting with an S3 bucket 💸
• --s3-role-arn string — the ARN of the IAM role to assume
• --s3-role-external-id string — external ID for that assumed role
• --s3-role-session-duration string — session duration for the assumed role
• --s3-role-session-name string — session name for the assumed role
• --s3-sdk-log-mode Bits — set this to debug the SDK (default Off) 🐛
• --s3-secret-access-key string — ur AWS Secret Access Key, aka the password. guard it with ur life 🎀
• --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-sign-accept-encoding Tristate — set if rclone should include Accept-Encoding as part of the signature (default unset)
• --s3-sse-customer-algorithm string — if ur using SSE-C, this is the server-side encryption algorithm used when storing this object in S3
• --s3-sse-customer-key string — to use SSE-C u may hand over the secret encryption key used to encrypt/decrypt ur data 🔐
• --s3-sse-customer-key-base64 string — if ur using SSE-C u must provide the secret encryption key encoded in base64 format to encrypt/decrypt ur data
• --s3-sse-customer-key-md5 string — if ur using SSE-C u may optionally provide the secret encryption key MD5 checksum (optional)
• --s3-sse-kms-key-id string — if ur using KMS ID u 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 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 if rclone should report BucketAlreadyExists errors when it creates a bucket (default unset)
• --s3-use-arn-region — if true, enables arn region support for the service
• --s3-use-data-integrity-protections Tristate — if true, use AWS S3 data integrity protections (default unset)
• --s3-use-dual-stack — if true, use the AWS S3 dual-stack endpoint (IPv6 support, slay) 🌈
• --s3-use-multipart-etag Tristate — whether to use ETag in multipart uploads for verification (default unset)
• --s3-use-multipart-uploads Tristate — set 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-use-x-id Tristate — set if rclone should add x-id URL parameters (default unset)
• --s3-v2-auth — if true, use v2 authentication
• --s3-version-at Time — show file versions as they were at the specified time (default off) ⏰
• --s3-version-deleted — show deleted file markers when using versions 🪦
• --s3-versions — include old versions in directory listings

okay and that's the S3 saga wrapped, ur officially an S3 girlie 💅✨

---

now moving onto the seafile girlies 🍓

• --seafile-2fa — two-factor authentication, set it to 'true' if the account has 2FA enabled 🔐
• --seafile-create-library — should rclone create a library if it doesn't exist
• --seafile-description string — description of the remote
• --seafile-encoding Encoding — the encoding for the backend (default Slash,DoubleQuote,BackSlash,Ctl,InvalidUtf8,Dot)
• --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 ur email address 📧

---

and finally, SFTP, the classic. sit down bestie, this one's long 🦋

• --sftp-ask-password — allow asking for the SFTP password when it's needed
• --sftp-blake3sum-command string — the command used to read BLAKE3 hashes
• --sftp-chunk-size SizeSuffix — upload and download chunk size (default 32Ki)
• --sftp-ciphers SpaceSepList — a space separated list of ciphers used for session encryption, ordered by preference
• --sftp-concurrency int — the maximum number of outstanding requests for one file (default 64)
• --sftp-connections int — max number of SFTP simultaneous connections, 0 for unlimited
• --sftp-copy-is-hardlink — set this to enable server side copies using hardlinks 🔗
• --sftp-crc32sum-command string — the command used to read CRC-32 hashes
• --sftp-description string — description of the remote
• --sftp-disable-concurrent-reads — if set, don't use concurrent reads
• --sftp-disable-concurrent-writes — if set, don't use concurrent writes
• --sftp-disable-hashcheck — disables running SSH commands to figure out whether remote file hashing is even available
• --sftp-encoding Encoding — the encoding for the backend (default Slash,Del,Ctl,Dot)
• --sftp-hashes CommaSepList — a comma separated list of supported checksum types
• --sftp-host string — SSH host to connect to
• --sftp-host-key-algorithms SpaceSepList — space separated list of host key algorithms, ordered by preference
• --sftp-host-keys CommaSepList — pinned host keys for this remote, used to verify the server 📌
• --sftp-http-proxy string — URL for the HTTP CONNECT proxy
• --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, straight up
• --sftp-key-use-agent — when set, it forces the usage of the SSH agent
• --sftp-known-hosts-file string — optional path to a 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 the SSH agent instead (obscured)

Okay bestie, buckle up, this is the backend flag era and we're going ✨methodically✨ 💅

---

🦋 SFTP says hi 🦋

• --sftp-path-override string — overrides the path that gets used by SSH shell commands 🛠️
• --sftp-pin-host-key — pins the server's host key on first connection, aka Trust On First Use 🔐
• --sftp-port int — SSH port number (default 22)
• --sftp-pubkey string — SSH public certificate, for public-certificate-based auth 🎀
• --sftp-pubkey-file string — optional path to your public key file
• --sftp-server-command string — tells rclone 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 it's set (default true)
• --sftp-sha1sum-command string — the command used to read SHA-1 hashes
• --sftp-sha256sum-command string — the command used to read SHA-256 hashes
• --sftp-shell-type string — the type of SSH shell on the remote server, if any
• --sftp-skip-links — set it to skip any symlinks and any other non-regular files 🙈
• --sftp-socks-proxy string — Socks 5 proxy host
• --sftp-ssh SpaceSepList — path and arguments to an 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

bestie, that flag has "insecure" right in the name for a reason, so don't be casual with it 💀

• --sftp-user string — SSH username (default "$USER")
• --sftp-xxh128sum-command string — the command used to read XXH128 hashes
• --sftp-xxh3sum-command string — the command used to read XXH3 hashes

---

🌈 Shade era 🌈

• --shade-api-key string — an API key for your account
• --shade-chunk-size SizeSuffix — chunk size to use for uploading (default 64Mi)
• --shade-description string — description of the remote 📝
• --shade-drive-id string — the ID of your drive, you can see it in the drive settings. Individual rclone configs must be made per drive 🚗
• --shade-encoding Encoding — the encoding for the backend (default Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot)
• --shade-endpoint string — endpoint for the service
• --shade-max-upload-parts int — maximum amount of parts in a multipart upload (default 10000)
• --shade-token string — JWT Token for performing Shade FS operations. Don't set this value — rclone will set it automatically, fr fr
• --shade-token-expiry string — JWT Token Expiration time. Don't set this value — rclone will set it automatically, same deal 💫
• --shade-upload-concurrency int — concurrency for multipart uploads and copies. This is the number of chunks of the same file that are uploaded concurrently for multipart uploads and copies (default 4)

---

🎀 Sharefile, iconic 🎀

• --sharefile-auth-url string — auth server URL
• --sharefile-chunk-size SizeSuffix — upload chunk size (default 64Mi)
• --sharefile-client-credentials — use 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, the decentralized one 🍓

• --sia-api-password string — Sia Daemon API Password (obscured) 🔒
• --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")

---

🧚 Global-ish skipping ✨

• --skip-links — don't warn about skipped symlinks 🤐
• --skip-specials — don't warn about skipped pipes, sockets and device objects

---

👑 SMB, corporate but make it cute 👑

• --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-kerberos-ccache string — path to the Kerberos credential cache (krb5cc)
• --smb-pass string — SMB password (obscured) 🔒
• --smb-port int — SMB port number (default 445)
• --smb-spn string — service principal name
• --smb-use-kerberos — use Kerberos authentication 🎫
• --smb-user string — SMB username

---

💜 Storj, decentralized again but different 💜

• --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, sweet name 🌸

• --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 ⚠️

"permanently" is doing a lot of heavy lifting in that sentence, bestie. No undo button, no recycle bin, just vibes and regret 💀

• --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, the OpenStack main character 🌈

• --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 — the region name, optional bestie (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, otherwise you need this or tenant_id (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, and ngl most swift systems just use user and leave this blank (v3 auth) (OS_USER_ID).
• <coral>--ulozto-app-token</coral> string — the application token identifying the app. An app API key can be either found in the API
• <coral>--ulozto-description</coral> string — description of the remote.
• <coral>--ulozto-encoding</coral> Encoding — the encoding for the backend (default Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot).
• <coral>--ulozto-list-page-size</coral> int — the size of a single page for list commands. 1-500 (default 500).
• <coral>--ulozto-password</coral> string — the password for the user (obscured).
• <coral>--ulozto-root-folder-slug</coral> string — if set, rclone will use this folder as the root folder for all operations. For example,
• <coral>--ulozto-username</coral> 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.
• --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. iykyk which one you've got.
• --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 — OAuth Client Secret.
• --yandex-description string — description of the remote.
• --yandex-encoding Encoding — the encoding for the backend (default Slash,Del,Ctl,InvalidUtf8,Dot).
• --yandex-hard-delete — delete files permanently rather than putting them into the trash. no undo bestie, be so serious.
• --yandex-spoof-ua — set 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 — token server url.
• --yandex-upload-wait Duration — wait this long after an upload before setting the modification time (default 0s).
• --zoho-auth-url string — auth server URL.
• --zoho-client-credentials — use 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-list-folder-burst int — same-folder listings allowed back-to-back before --zoho-list-folder-limit paces them (default 6).
• --zoho-list-folder-limit int — max listings of the SAME folder allowed per --zoho-list-folder-window (default 19).
• --zoho-list-folder-window Duration — the window for --zoho-list-folder-limit (default 1m0s).
• --zoho-region string — Zoho region to connect to.
• --zoho-root-folder-id string — ID of the root folder.
• --zoho-token string — OAuth Access Token as a JSON blob.
• --zoho-token-url string — token server url.
• --zoho-tpslimit float — max number of API transactions per second (default 6).
• --zoho-tpslimit-burst int — number of API calls to allow back-to-back without sleeping, for --zoho-tpslimit (default 1).
• --zoho-upload-cutoff SizeSuffix — cutoff for switching to large file upload api (>= 10 MiB) (default 10Mi).

---

🐳 Docker Volume Plugin 🐳

✨ Introduction ✨

okay so history lesson but make it cute. Docker 1.9 added support for creating named volumes (https://docs.docker.com/storage/volumes/) through the command-line interface (https://docs.docker.com/engine/reference/commandline/volume_create/), and mounting them in containers, as a way to share data between them. Then since Docker 1.10 you can create named volumes with Docker Compose (https://docs.docker.com/compose/) — you just describe them in docker-compose.yml files (https://docs.docker.com/compose/compose-file/compose-file-v2/#volume-configuration-reference) for use by container groups on a single host. And as of Docker 1.12, volumes are supported by Docker Swarm (https://docs.docker.com/engine/swarm/key-concepts/) included with Docker Engine, created from descriptions in swarm compose v3 files (https://docs.docker.com/compose/compose-file/compose-file-v3/#volume-configuration-reference) for use with swarm stacks across multiple cluster nodes. the way docker kept levelling up 😭

Docker Volume Plugins (https://docs.docker.com/engine/extend/plugins_volume/) augment the default local volume driver baked into Docker with stateful volumes shared across containers and hosts. And here's the part that eats: unlike local volumes, your data will not be deleted when such a volume is removed. periodt, the data 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 docker volume plugin in all these modes. It interacts with the local docker daemon via plugin API (https://docs.docker.com/engine/extend/plugin_api/) and handles mounting of remote file systems into docker containers, so it must run on the same host as the docker daemon or on every Swarm node. no shortcuts bestie, that's the vibe check.

---

🌸 Getting started 🌸

In the first example we will use the SFTP (https://rclone.org/sftp/) rclone volume with Docker engine on a standalone Ubuntu machine. iconic starting point tbh.

Start from installing Docker (https://docs.docker.com/engine/install/) on the host.

The FUSE driver is a prerequisite for rclone mounting and should be installed on host:

sudo apt-get -y install fuse3

Create two directories required by rclone docker plugin:

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

Create your SFTP volume (https://rclone.org/sftp/#standard-options):

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

Note that since all 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 present). 💅

In the simplest case you can use localhost as 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. like, that's it, that's the whole flex.

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 all goes well, you will enter the new container and change right to the mounted SFTP remote. You can type ls to list the mounted directory or otherwise play with it. Type exit when you are done. The container will stop but the volume will stay, ready to be reused. When it's not needed anymore, remove it:

docker volume list
docker volume remove firstvolume

Okay so now we're doing something ✨spicy✨ — a Google Drive volume on a multi-node Docker Swarm. 👑

You should start from installing Docker and FUSE, creating plugin directories and installing rclone plugin on every single swarm node. Then setup the Swarm — the deets are at https://docs.docker.com/engine/swarm/swarm-mode/.

Google Drive volumes need an access token, which can be setup via web browser and will be periodically renewed by rclone. The managed plugin cannot run a browser (it's giving no-GUI energy 😭) so we will use a technique similar to the rclone setup on a headless box — link in bio: https://rclone.org/remote_setup/.

Run rclone config (that's https://rclone.org/commands/rclone_config_create/) on another machine equipped with web browser and graphical user interface. Create the Google Drive remote (standard options guide: https://rclone.org/drive/#standard-options). When done, transfer the resulting rclone.conf to the Swarm cluster and save as /var/lib/docker-plugins/rclone/config/rclone.conf on every node. By default this location is accessible only to the root user so you will need appropriate privileges, bestie, no shortcuts. 💅

The resulting config will look like this:

[gdrive]
type = drive
scope = drive
drive_id = 1234567...
root_folder_id = 0Abcd...
token = {"access_token":...}

Now create the 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 over 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 rclone plugins on the node hosts. You can use the following commands to confirm results:

docker service ls
docker service ps example_heimdall
docker volume ls

Point your browser to http://cluster.host.address:8080 and play with the service. Stop it with docker stack remove example when you are done. 🫶

Heads up bestie: 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 invoking the docker volume remove example_configdata command on every node.

---

🎀 Creating Volumes via CLI 🎀

Volumes can be created with docker volume create (docs over at https://docs.docker.com/engine/reference/commandline/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

Note the -d rclone flag that tells docker to request volume from the rclone driver. This works even if you installed managed driver by its full name rclone/docker-volume-rclone because you provided the --alias rclone option. iykyk 😌

Volumes can be inspected as follows:

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. Also there are a few special -o options: remote, fs, type, path, mount-type and persist.

remote determines an existing remote name from the config file, with trailing colon and optionally with a remote path. See the full syntax in the rclone documentation (https://rclone.org/docs/#syntax-of-remote-paths). This option can be aliased as fs to prevent confusion with the remote parameter of such backends as crypt or alias.

The remote=:backend:dir/subdir syntax can be used to create on-the-fly (config-less) remotes (https://rclone.org/docs/#backend-path-to-dir), while the type and path options provide a simpler alternative for this. 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 (https://rclone.org/commands/rclone_serve_docker/#options) as well as backend parameters (https://rclone.org/flags/#backend) are named like their twin command-line flags 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 value will gain the true value, e.g. --allow-other becomes -o allow-other=true or -o allow_other=true. slay, consistent. ✨

⚠️ Please note that you can provide parameters only for the backend immediately referenced by the backend type of mounted remote. If this is a wrapping backend like alias, chunker or crypt, you cannot provide options for the referred to remote or backend. This limitation is imposed by the rclone connection string parser. The only workaround is to feed plugin with rclone.conf or configure plugin arguments (see below). Don't fight it, it's just how the parser woke up today. 💀

---

✨ 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 to persist on-the-fly remotes in the plugin rclone.conf file. (Future, bestie, not now. 👀)

---

🔗 Connection Strings 🔗

The remote value can be extended with connection strings (https://rclone.org/docs/#connection-strings) as an alternative way to supply backend parameters. This is equivalent to the -o backend options with one syntactic difference. Inside 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 equivalent connection string:

-o remote=:sftp,host=localhost:/home

This difference exists because flag options -o key=val include not only backend parameters but also mount/VFS flags and possibly other settings. Also it allows to discriminate the remote option from the crypt-remote (or similarly named backend parameters) and arguably simplifies scripting due to clearer value substitution. It's giving thoughtful design, honestly. 💜

---

🐝 Using with Swarm or Compose 🐝

Both Docker Swarm and Docker Compose use YAML (http://yaml.org/spec/1.2/spec.html)-formatted text files to describe groups (stacks) of containers, their properties, networks and volumes. Compose uses the compose v2 (https://docs.docker.com/compose/compose-file/compose-file-v2/#volume-configuration-reference) format, Swarm uses the compose v3 (https://docs.docker.com/compose/compose-file/compose-file-v3/#volume-configuration-reference) format. They are mostly similar, differences are explained in the docker documentation (https://docs.docker.com/compose/compose-file/compose-versioning/#upgrading).

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 playing the 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

Notice a few important details:

• 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 (http://yaml.org/spec/1.2/spec.html#id2790832). 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 (https://hub.docker.com/p/rclone/docker-volume-rclone/) plugin image on Docker Hub (https://hub.docker.com).

🌟 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 (https://docs.docker.com/engine/reference/commandline/plugin_install/) 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.

latest also ships as a tag, bestie, but heads up — docker doesn't do multi-architecture plugins (as of the time this was written), so latest is currently just an alias for amd64. By convention latest is the default tag so you can straight up omit it, which means rclone/docker-volume-rclone:latest and plain old rclone/docker-volume-rclone both point at the latest plugin release for the amd64 platform. ✨

Oh and also — the amd64 part can be dropped from versioned rclone plugin tags. Like, rclone/docker-volume-rclone:amd64-1.56.2 can be abbreviated to rclone/docker-volume-rclone:1.56.2 for convenience. BUT. For non-intel architectures you still have to use the full tag, because amd64 or latest will fail to start. 🫠

Managed plugin is actually 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 go 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. fr fr.

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 — no one else is gonna do it for you, bestie. 😭

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 (https://docs.docker.com/engine/reference/commandline/plugin_set/) command line. Both serve docker flags (https://rclone.org/commands/rclone_serve_docker/#options) and generic rclone flags (https://rclone.org/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 (https://github.com/moby/moby/blob/v20.10.7/plugin/v2/plugin.go#L195)) 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 (https://rclone.org/install/). 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 (https://raw.githubusercontent.com/rclone/rclone/master/contrib/docker-plugin/systemd/docker-volume-rclone.service) and docker-volume-rclone.socket (https://raw.githubusercontent.com/rclone/rclone/master/contrib/docker-plugin/systemd/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 the 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 (https://docs.docker.com/engine/extend/#debugging-plugins) with

docker plugin list
docker plugin inspect rclone

Note that docker (including latest 20.10.7) will not show actual values of args, just the defaults. 🙈

Use journalctl --unit docker to see managed plugin output as part of the docker daemon log. Note that docker reflects plugin lines as errors but their actual level can be seen from encapsulated message string.

You will usually install the latest version of managed plugin for your platform. Use the following commands to 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

You can even use runc to run shell inside the plugin container:

sudo runc --root /run/docker/runtime-runc/plugins.moby exec --tty $PLUGID bash

Also you can use curl to 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 this is rarely needed.

If the plugin fails to work properly, and only as a last resort after you tried diagnosing with the above methods, you can try clearing the state of the plugin. Note that all existing rclone docker volumes will probably have to be recreated. This might be needed because a reinstall don't cleanup existing state files to allow for easy restoration, as stated 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

🚨 Caveats

Finally I'd like to mention a caveat with updating volume settings. Docker CLI does not have a dedicated command like docker volume update. It may be tempting to invoke docker volume create with updated options on existing volume, but there is a gotcha. The command will do nothing, it won't even return an error. I hope that docker maintainers will fix this some day. 🙏 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 verify that settings did update:

docker volume list
docker volume inspect my_vol

If docker refuses to remove the volume, you should find containers or swarm services that use it and stop them first.

---

🔄 Bisync

bisync is considered an advanced command, so use with care. Make sure you have read and understood the entire manual (https://rclone.org/bisync) (especially the Limitations section) before using, or data loss can result. 💀 Questions can be asked in the Rclone Forum (https://forum.rclone.org/).

🚀 Getting started

• Install rclone (https://rclone.org/install/) and setup your remotes.
• Bisync is gonna make its little home 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 location is writable, bestie, or it's giving sad girl hours 💀
• Run bisync with the --resync flag, and tell it where your paths are — the local dir and the remote sync dir roots. Specify both, okay? It needs both.
• For successive sync runs, leave OFF the --resync flag. (Important!) Like fr fr, this one matters — don't @ me 🙈
• Consider using a filters file for excluding unnecessary files and directories from the sync. Lowkey a game changer for keeping things tidy.
• Consider setting up the --check-access feature for safety. Safety first, always 💅
• On Linux or Mac, consider setting up a crontab entry. Bisync can safely run in concurrent cron jobs thanks to lock files it maintains — no drama, no race conditions, she's organized like that ✨

So like, 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. Periodt. 💖

---

Here's a typical run log to show you what a vibe looks like (timestamps removed for clarity, you're welcome):

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

Bisync successful, we love to see it 👑

---

💫 Command line syntax 💫

$ 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                   --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.
  -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 custom working dir - useful for testing. (default: {WORKDIR})
      --max-delete PERCENT                   Safety check on maximum percentage of deleted files allowed. If 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.

Arbitrary rclone flags may be specified on the bisync command line (https://rclone.org/commands/rclone_bisync/), for example rclone bisync ./testdir/path1/ gdrive:testdir/path2/ --drive-skip-gdocs -v -v --timeout 10s

Heads up bestie: note that interactions of various rclone flags with bisync process flow has not been fully tested yet. 🧚

---

🦋 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 (https://rclone.org/docs/#syntax-of-remote-paths) 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. Equal partnership, no main character syndrome here, periodt.

The listings in 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. Like, ALL of them. Be sure that's what you want 💀

---

🌸 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. No base dir, no vibes, no sync. Simple as. 🫶

Okay so when you're using --resync, a newer version of a file on the Path2 filesystem will (by default) be overwritten by the Path1 filesystem version. Ngl bestie, clock this: that is NOT entirely symmetrical (there's a whole saga about it at https://github.com/rclone/rclone/issues/5681#issuecomment-938761815), and if you want the more symmetrical options you can specify them with the --resync-mode flag. So carefully evaluate deltas using --dry-run first (https://rclone.org/flags/#non-backend-flags) before you commit to anything, fr fr. 💅

For a resync run, one of the paths may be empty (like, literally no files in the path tree). And the resync run should result in files on both paths, else a normal non-resync run will fail. 🙈

For a non-resync run, if either path is empty (no files in the tree) it fails with Empty current PathN listing. Cannot sync to an empty directory: X.pathN.lst — and that is literally a safety check so that an unexpected empty path doesn't result in deleting everything in the other path. Protective queen behavior, we love to see it. 👑

Note that --resync implies --resync-mode path1 unless a different --resync-mode is explicitly specified. And 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. And the reason is kind of iconic actually: because --resync will only copy (not sync) each side to the other. So 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. Not the vibe.

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:

--resilient --recover --max-lock 2m --conflict-resolve newer

---

🎀 --resync-mode CHOICE

So if 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).

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 will fall back to the default of path1. (For example, if --resync-mode 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 bisync will instead try to determine whether the files differ by looking at the other --compare methods in effect. (For example, if --resync-mode newer is set, but the Path1 and Path2 modtimes are identical, bisync will compare the sizes.) If bisync concludes that they differ, preference is given to whichever is the "source" at that moment. (In practice, this gives a slight advantage to Path2, as the 2to1 copy comes before the 1to2 copy.) If the files do not differ, nothing is copied (as both sides are already correct). ✨
• These options apply only to files that exist on both sides (with the same name and relative path). Files that exist only on one side and not the other are always copied to the other, during --resync (this is one of the main differences between resync and non-resync runs.). 🔥
• --conflict-resolve, --conflict-loser, and --conflict-suffix do not apply during --resync, and unlike these 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 retain a backup of the losing version.) 💀
• Unlike for --conflict-resolve, --resync-mode none is not a valid option (or rather, it will be interpreted as "no resync", unless --resync has also been specified, in which case it will be ignored.)
• Winners and losers are decided at the individual file-level only (there is not currently an option to pick an entire winning directory atomically, although the path1 and path2 options typically produce a similar result.) 💜
• To maintain 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 it is not necessary to use both the --resync and --resync-mode flags simultaneously — either one is sufficient without the other. 🫶

---

🦋 --check-access

Access check files are an additional safety measure against data loss. bisync will ensure it can find matching RCLONE_TEST files in the same places in the Path1 and Path2 filesystems. And no, RCLONE_TEST files are not generated automatically, bestie — you gotta do it yourself. 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 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 will also work, but is not preferred, due to potential for user error (you are 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 ensure that bisync can't inadvertently circumvent its own safety switch — see https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=3.%20%2D%2Dcheck%2Daccess%20doesn%27t%20always%20fail%20when%20it%20should.) She guards herself. Iconic honestly. 👑

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 is recommended to place RCLONE_TEST files in the linked-to directory tree to protect against bisync assuming a bunch of deleted files if the linked-to tree should not be accessible. See also the --check-filename flag. 🌸

---

🌈 --check-filename

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. 💖

---

⭐ --compare

As of v1.66, bisync fully supports comparing based on any combination of size, modtime, and checksum (lifting the prior restriction on backends without modtime support.) 🎉

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 (https://rclone.org/docs/#c-checksum) or --size-only.)

If the --compare flag is set, it will override these defaults. This can be useful if you wish 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. For example, if you set the conflicting flags --compare checksum --size-only, --size-only will be ignored, and bisync will compare checksum and not size. To avoid confusion, it is recommended to use either --compare or the normal sync flags, but not both. 💅

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 is changed on both sides, bisync still does the standard equality-check to avoid declaring a sync conflict unless it absolutely has to.) 😌

It is recommended to do a --resync when changing --compare settings, as otherwise your prior listing files may not contain the attributes you wish to compare (for example, they will not have stored checksums if you were not previously comparing checksums.) 💖

---

✨ --ignore-listing-checksum ✨

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 — https://rclone.org/local/ ) where hashes must be computed on the fly instead of retrieved. 🏃‍♀️💨 Please note the following, bestie:

• As of v1.66, --ignore-listing-checksum is now automatically set when neither --checksum nor --compare checksum are in use (as the checksums would not be used for anything.) 💅
• --ignore-listing-checksum is NOT the same as --ignore-checksum (https://rclone.org/docs/#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 (https://rclone.org/crypt/#modification-times-and-hashes) 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.) 👑

---

🐢 --no-slow-hash 🐢

On some remotes (notably local), checksums can dramatically slow down a bisync run, because hashes cannot 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. 💪

---

🌸 --slow-hash-sync-only 🌸

Same as --no-slow-hash, except slow hashes are still considered during sync calls. They are still NOT considered for determining deltas, nor or they included in listings. They are 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. 💀

--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 🎀

If --download-hash is set, bisync will use best efforts to obtain an MD5 checksum by downloading and computing on-the-fly, when checksums are not otherwise available (for example, a remote that doesn't support them.) Note that since rclone has to download the entire file, this may dramatically slow down your bisync runs, and is also likely to use a lot of data, so it is probably not practical for bisync paths with a large total file size. 💸

However, it can be a good option for syncing small-but-important files with maximum accuracy (for example, a source code repo on a crypt remote.) An additional advantage over methods like cryptcheck (https://rclone.org/commands/rclone_cryptcheck/) is that the original file is not required for comparison (for example, --download-hash can be used to bisync two different crypt remotes with different passwords.) 🔐✨

When --download-hash is set, bisync still looks for more efficient checksums first, and falls back to downloading only 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, as their checksums would change from run to run (due to small variances in the internals of the generated export file.) Therefore, bisync automatically skips --download-hash for files with a size less than 0. 🍓

See also: Hasher (https://rclone.org/hasher/) backend, cryptcheck (https://rclone.org/commands/rclone_cryptcheck/) command, rclone check --download (https://rclone.org/commands/rclone_check/) option, md5sum (https://rclone.org/commands/rclone_md5sum/) command 👑

---

🛡️ --max-delete 🛡️

As a safety check, if greater 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. The default --max-delete is 50%. 😱

One way to trigger this limit is to rename a directory that contains more than half of your files. This will appear to bisync as a bunch of deleted files and a bunch of new files. This safety check is intended to block bisync from deleting 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, 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 📄

By using rclone filter features you can exclude file types or directory sub-trees from the sync. See the bisync filters section and generic --filter-from (https://rclone.org/filtering/#filter-from-read-filtering-patterns-from-a-file) 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, which prevents existing files on the Path1 and/or Path2 side from seeming to disappear from view (since they are excluded in the new listings), which would fool bisync into seeing them as deleted (as compared to the prior run listings), and then bisync would proceed to delete them for real. 💀

To block this 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 and thus 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 such a scenario. The currently supported options are:

• none — (the default) — do not attempt to pick a winner, keep and rename both files according to --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. (As none is the default, it is not necessary to specify --conflict-resolve none — you can just omit the flag.) 🙈
• 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, bestie ✨ it auto-numbers your conflicts by automatically appending the next available number to the --conflict-suffix, in chronological order. So with the default settings, the first conflict for file.txt gets renamed to file.txt.conflict1. And if file.txt.conflict1 already exists? Then file.txt.conflict2 is used instead (etc., etc., all the way up to a maximum of 9223372036854775807 conflicts 💅).
• pathname — renames conflicts based on which side they came from, which was literally the default behavior before v1.66. So with --conflict-suffix path, file.txt from Path1 becomes file.txt.path1, and file.txt from Path2 becomes file.txt.path2. If two non-identical suffixes are provided (ex. --conflict-suffix cloud,local), the trailing digit is omitted. Impor­tantly, 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) 🫠.
• delete — keeps the winner only and deletes 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, fr fr.

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 gets appended when bisync renames a --conflict-loser (default: conflict) 🎀. --conflict-suffix accepts either one string or two comma-separated strings to assign different suffixes to Path1 vs. Path2. This can be super helpful later for identifying the source of the conflict, iykyk. (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 (https://rclone.org/docs/#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 (go Time.Layout constants) (https://pkg.go.dev/time#pkg-constants) and here (go Time.Format examples) (https://pkg.go.dev/time#example-Time.Format) 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 (https://rclone.org/docs/#suffix-string) flag. This is intentional, as users may wish to use both flags simultaneously, if also using --backup-dir.

Finally, note that the default in bisync prior to v1.66 was to rename conflicts with ..path1 and ..path2 (with two periods, and path instead of conflict 🌈). Bisync now defaults to a single dot instead of a double dot, but additional dots can be added by including them in the specified suffix string. For example, for behavior equivalent to the previous default, use:

[--conflict-resolve none] --conflict-loser pathname --conflict-suffix .path

---

✨ --check-sync ✨

Enabled by default 💖, 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 is performed at the end of the sync run by default. Any untrapped failing copy/deletes between the two paths might result in differences between the two listings and in the untracked file content differences between the two paths. A resync run would correct the error.

Note that the default-enabled integrity check locally executes a load of both the final Path1 and Path2 listings, and thus adds to the run time of a sync. Using --check-sync=false will disable it and may significantly reduce the sync run times for very large numbers of files ⚡.

The check may be run manually with --check-sync=only. It runs only the integrity check and terminates without actually syncing.

Note that currently, --check-sync only checks listing snapshots and NOT the actual files on the remotes 👀. Note also that the listing snapshots will not know about any changes that happened during or after the latest bisync run, as those will be discovered on the next run. Therefore, 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 🦋.

For a robust integrity check of the current state of the remotes (as opposed to just their listing snapshots), consider using check (or cryptcheck (https://rclone.org/commands/rclone_cryptcheck/), if at least one path is a crypt remote) instead of --check-sync, keeping in mind that differences are expected if files changed during or after your last bisync run.

For example, 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 (perhaps 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 ✨

By default, most errors or interruptions will cause bisync to abort and require --resync to recover 😤. This is a safety feature, to prevent bisync from running again until a user checks things out. However, in some cases, bisync can go too far and enforce a lockout when one isn't actually necessary, like for certain less-serious errors that might resolve themselves on the next run. 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 necessary. The intended use case is for running bisync as a background process (such as via scheduled cron) 💅.

When using --resilient mode, bisync will still report the error and abort, however it will not lock out future runs — allowing the possibility of retrying at the next normally scheduled time, without requiring 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 ✨

If --recover is set, in the event of a sudden interruption or other ungraceful shutdown, bisync will attempt to automatically recover on the next run, instead of requiring --resync 🫶. Bisync is able to recover robustly by keeping 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 determine 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 this is not a problem, as bisync will simply do its usual "equality check" and learn that no action needs to be taken on these files, since they are already identical on both sides 💖.

because bestie, the ✨rare✨ event: a file syncs successfully during a run, and then that run aborts, and then the SAME file changes AGAIN before the next run starts? bisync is gonna think that'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 two sides aren't currently identical, so... yeah.) Which means --recover ships with a slightly increased chance of conflicts — though ngl in practice this is pretty rare, because the conditions required to even cause it are super specific 🦋 This risk can be reduced by using bisync's "Graceful Shutdown" mode (triggered by sending SIGINT or Ctrl+C) when you have the choice, instead of forcing a sudden termination 💅

So --recover and --resilient are similar but distinct — the main difference is that --resilient is about retrying, while --recover is about re-covering. Most users will probably want both, fr fr. --resilient lets bisync retry when it has chosen to abort itself due to safety features like failing --check-access or detecting a filter change. But --resilient does NOT cover external interruptions — like a user shutting down their computer in the middle of a sync — that is literally what --recover is for 🫶

🌸 --max-lock 🌸

Bisync uses lock files as a safety feature to prevent interference from other bisync runs while it is running 🔒 Bisync normally removes these lock files at the end of a run, but if bisync is abruptly interrupted, those files get left behind 😭 By default, they will 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 that future runs are not 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 — and you can therefore be reasonably sure that any expired lock file you may find was left there by an interrupted run, not one that is still running and just taking awhile 🐌

If a lock file exists but its contents are unreadable (for example, due to an incomplete write or disk error), it is treated as expired when --max-lock is set to a value greater than 0. If --max-lock is 0 or not set, an unreadable lock file will produce an error and block future runs until removed manually 💀

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 🎀

As of v1.66, --backup-dir (https://rclone.org/docs/#backup-dir-string) is supported in bisync ✨ Because --backup-dir must be a non-overlapping path on the same remote, Bisync has introduced 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 😬). If either --backup-dir1 and --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 🌈 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 💖

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 (https://rclone.org/docs/#suffix-string), --suffix-keep-extension (https://rclone.org/docs/#suffix-keep-extension) ✨

---

👑 Operation 👑

🦋 Runtime flow details 🦋

bisync retains the listings of the Path1 and Path2 filesystems 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 🔁

💅 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, this is the master list — every combo bisync checks for, what it means, who survives, and which rclone command it runs 👇

• Path2 new — File is new on Path2, does not exist on Path1 → Path2 version survives → rclone copy Path2 to Path1
• Path2 newer — File is newer on Path2, unchanged on Path1 → Path2 version survives → rclone copy Path2 to Path1
• Path2 deleted — File is deleted on Path2, unchanged on Path1 → File is deleted → rclone delete Path1
• Path1 new — File is new on Path1, does not exist on Path2 → Path1 version survives → rclone copy Path1 to Path2
• Path1 newer — File is newer on Path1, unchanged on Path2 → Path1 version survives → rclone copy Path1 to Path2
• Path1 older — File is older on Path1, unchanged on Path2 → Path1 version survives → rclone copy Path1 to Path2
• Path2 older — File is older on Path2, unchanged on Path1 → Path2 version survives → rclone copy Path2 to Path1
• Path1 deleted — File no longer exists on Path1 → File is deleted → rclone delete Path2

(and yes, Path1 older and Path2 older are not typos — the older one on the source side still wins and survives, which is giving exactly the energy it needs to be giving 😌)

💫 Unusual sync checks 💫

okay so bestie, this is the messy-exception corner of bisync and you're gonna wanna pay attention because it's everything 🌸. Here's the whole vibe check, one row at a time, because tables are for cowards and bullet points are for girlies who actually read:

• Path1 new/changed AND Path2 new/changed AND Path1 == Path2 — the file is new/changed on Path1 AND new/changed on Path2 AND the Path1 version is currently identical to Path2 → no change ✨ → implementation: none. literally nothing happens. iconic behaviour honestly.
• Path1 new AND Path2 new — the file is new on Path1 AND new on Path2 (and the Path1 version is NOT identical to Path2) → conflicts handled according to --conflict-resolve & --conflict-loser settings → default implementation: rclone copy renamed Path2.conflict2 file to Path1, rclone copy renamed Path1.conflict1 file to Path2. 💅
• Path2 newer AND Path1 changed — the file is newer on Path2 AND also changed (newer/older/size) on Path1 (and the Path1 version is NOT identical to Path2) → conflicts handled according to --conflict-resolve & --conflict-loser settings → default implementation: rclone copy renamed Path2.conflict2 file to Path1, rclone copy renamed Path1.conflict1 file to Path2.
• Path2 newer AND Path1 deleted — the file is newer on Path2 AND also deleted on Path1 → the Path2 version survives 🔥 → implementation: rclone copy Path2 to Path1.
• Path2 deleted AND Path1 changed — the file is deleted on Path2 AND changed (newer/older/size) on Path1 → the Path1 version survives 👑 → implementation: rclone copy Path1 to Path2.
• Path1 deleted AND Path2 changed — the file is deleted on Path1 AND changed (newer/older/size) on Path2 → the Path2 version survives 🦋 → implementation: 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 (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=Renamed%20directories), as a --resync is no longer required, so long as the same change has been made on both sides. slay 🌈

🚨 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. fr fr, be careful with this one.

⏰ 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.

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. no cap, do the dry run first.

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. literally mayhem bestie. 😭

🚪 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 (https://rclone.org/docs/#exit-code) in main docs.

🌸 Graceful Shutdown 🌸

Bisync has a "Graceful Shutdown" mode which is activated by sending SIGINT or pressing Ctrl+C 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 Ctrl+C 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 important to NOT use --inplace (https://rclone.org/docs/#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

Bisync is integration-tested against all rclone backends to verify compatibility. Most backends (including all backends not listed below) are deemed fully supported with no known issues ✨. Occasionally, however, these tests reveal issues with particular backends, usually related to a provider-specific limitation beyond rclone's control (for example, disallowed special characters and filename encodings.)

The following backends have known issues that need more investigation 🔍:

• TestHuaweiDrive (huaweidrive)
  • TestBisyncRemoteLocal/ext_paths (https://pub.rclone.org/integration-tests/current/huaweidrive-cmd.bisync-TestHuaweiDrive-1.txt)
  • TestBisyncRemoteLocal/extended_filenames (https://pub.rclone.org/integration-tests/current/huaweidrive-cmd.bisync-TestHuaweiDrive-1.txt)
  • TestBisyncLocalRemote/ext_paths (https://pub.rclone.org/integration-tests/current/huaweidrive-cmd.bisync-TestHuaweiDrive-1.txt)
  • TestBisyncLocalRemote/extended_filenames (https://pub.rclone.org/integration-tests/current/huaweidrive-cmd.bisync-TestHuaweiDrive-1.txt)
  • TestBisyncRemoteRemote/ext_paths (https://pub.rclone.org/integration-tests/current/huaweidrive-cmd.bisync-TestHuaweiDrive-1.txt)
  • 2 more (https://pub.rclone.org/integration-tests/current/)
• TestPcloud (pcloud)
  • TestBisyncLocalRemote/check_access_filters (https://pub.rclone.org/integration-tests/current/pcloud-cmd.bisync-TestPcloud-1.txt)
  • TestBisyncLocalRemote/createemptysrcdirs (https://pub.rclone.org/integration-tests/current/pcloud-cmd.bisync-TestPcloud-1.txt)
  • TestBisyncLocalRemote/resolve (https://pub.rclone.org/integration-tests/current/pcloud-cmd.bisync-TestPcloud-1.txt)
  • TestBisyncRemoteRemote/createemptysrcdirs (https://pub.rclone.org/integration-tests/current/pcloud-cmd.bisync-TestPcloud-1.txt)
• Updated: 2026-10-08-010019 🕐

The following backends are either ones nobody has tested recently, or ones with known issues that are deemed unfixable for the time being (iykyk 💀):

• TestArchive (archive)
• TestCache (cache)
• TestDrime (drime)
• TestDropbox (dropbox)
  • TestBisyncRemoteLocal/normalization
  • TestBisyncLocalRemote/normalization
  • TestBisyncRemoteRemote/normalization
• TestFileLu (filelu)
• TestFilesCom (filescom)
• TestImageKit (imagekit)
• TestJottacloud (jottacloud)
• TestLinkbox (linkbox)
• TestMailru (mailru)
• TestMega (mega)
• TestOpenDrive (opendrive)
• TestOracleObjectStorage (oracleobjectstorage)
• TestPikPak (pikpak)
• TestPixeldrain (pixeldrain)
• TestProtonDrive (protondrive)
• TestPutio (putio)
• TestQuatrix (quatrix)
• TestS3GCS (s3)
  • TestBisyncRemoteRemote/extended_filenames
• TestS3Rclone (s3)
• TestSFTPRsyncNet (sftp)
• TestStorj (storj)
• TestWebdavNextcloud (webdav)
• TestWebdavOwncloud (webdav)
• TestnStorage (netstorage) (more info (https://github.com/rclone/rclone/blob/master/fstest/test_all/config.yaml))

Those lists get refreshed for each stable release of rclone ✨. And if you want the test results that get re-run nightly off the latest beta, go peek at rclone's integration test status page (https://pub.rclone.org/integration-tests/current/) — that's where the tea is 🫖.

Ok so, history lesson, bestie: the early beta versions of rclone bisync required both underlying backends to support modification times, and flat-out refused to run otherwise 🙅‍♀️. That limitation got lifted as of v1.66, because bisync now supports comparing checksum and/or size instead of (or in addition to) modtime. See --compare for details 👀.

Concurrent modifications

When you're using Local, FTP or SFTP remotes with --inplace (https://rclone.org/docs/#inplace), rclone does not create temporary files at the destination while copying. Which means if the connection dies, the file it was making may be corrupt 💀 — and that corruption will likely propagate back to the original path on the next sync, resulting in data loss. So it is therefore recommended to omit --inplace. Just don't. 🙈

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 absolutely hammered by running processes during the sync 😭. As of rclone v1.66, bisync was redesigned to use a "snapshot" model, which greatly reduces the risks from changes during a sync 🌸. Changes that aren't 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. So it should 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 (https://rclone.org/docs/#ignore-checksum), --local-no-check-updated (https://rclone.org/local/#local-no-check-updated))

Empty directories

By default, new/deleted empty directories on one path are not propagated to the other side 🫠. That's because bisync (and rclone) natively works on files, not directories. But you can change it with the --create-empty-src-dirs flag, which works in much the same way as in sync (https://rclone.org/commands/rclone_sync/) and copy (https://rclone.org/commands/rclone_copy/). When it's used, empty directories created or deleted on one side will also be created or deleted on the other side 💅. A few things to clock though:

• --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. Why? 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

So 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 being deleted and all files in the new directory name being new. Not the vibe.

A recommended solution is to use --track-renames (https://rclone.org/docs/#track-renames), which is now supported in bisync as of rclone v1.66 👑. Note that --track-renames is not available during --resync, because --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 v1.64, a --resync is no longer required after doing so, as bisync will automatically detect that Path1 and Path2 are in agreement.) Slay.

Note that although the flag --track-renames ensures that renamed/moved files won't be deleted and uploaded again, they are still counted as deleted files for purposes of the --max-delete flag (as this check happens before the rename detection operation). See this issue (https://github.com/rclone/rclone/issues/8685).

--fast-list used by default

Unlike most other rclone commands, bisync uses --fast-list (https://rclone.org/docs/#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 (https://github.com/rclone/rclone/commit/cbf3d4356135814921382dd3285d859d15d0aa77) 🙃. 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 v1.66, 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 (https://rclone.org/docs/#fix-case)
• --ignore-case-sync (https://rclone.org/docs/#ignore-case-sync)
• --no-unicode-normalization (https://rclone.org/docs/#no-unicode-normalization)
• --local-unicode-normalization (https://rclone.org/local/#local-unicode-normalization) and --local-case-sensitive (https://rclone.org/local/#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 (https://rclone.org/filtering/) for how filter rules are written and interpreted 📝.

Bisync's --filters-file flag slightly extends the rclone's --filter-from (https://rclone.org/filtering/#filter-from-read-filtering-patterns-from-a-file) 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 🔥.

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.

• Please do not add a - ** line in this file. Because without that line, everything gets included that hasn't been explicitly excluded. 💅
• Literally disregard step 3. 🙈

---

A few rules for the syntax of a filter file, expanding on the filtering docs over at https://rclone.org/filtering/ — bestie, take notes 📝:

• Lines may start with spaces and tabs — rclone strips that leading whitespace for you. ✨
• If the first non-whitespace character is a # then the line is a comment and gets ignored. 💤
• Blank lines are ignored too. 🫶
• The first non-whitespace character on a filter line must be a + or a -. No cap. 🚨
• Exactly 1 space is allowed between the +/- and the path term. One. Uno. Don't push it. 💀
• Only forward slashes (/) are used in path terms, even on Windows. Yes, even on Windows. 🪟
• The rest of the line is taken as the path term. Trailing whitespace is taken literally, and it probably is an error. So watch those sneaky spaces at the end 👀

### ✨ 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? Select specific directories to be synched with a network drive (Path2). Iconic planning honestly 👑

• - /AppData/ excludes an entire tree of Windows stored stuff that need not be synched. In this case, AppData has >11 GB of stuff nobody cares 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 actual data that you do want synched, in the form of + /<path>. By selecting only the directory trees you want, you 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. Periodt. 💖

- /AppData/
- NTUSER*
- ntuser*
+ /Documents/Family/**
+ /Documents/Sketchup/**
+ /Documents/Microcapture_Photo/**
+ /Documents/Microcapture_Video/**
+ /Desktop/**
+ /Pictures/**
+ /*
- **

Note also that Windows implements several "library" links such as C:\Users\MyLogin\My Documents\My Music pointing to C:\Users\MyLogin\Music. rclone sees these as links, so you must add --links to the bisync command line if you want to follow these links. That said, following the links gives permission errors, so this example does not include the rclone --links flag — but then you get lots of Can't follow symlink... noise from rclone about not following the links. 😤 This noise can be quashed by adding --quiet to the bisync command line. 🤫

### 🌸 Example exclude-style filters files for use with Dropbox 🌸

• Dropbox disallows syncing the listed temporary and configuration/data files. The - <filename> filters exclude these files wherever they may occur in the sync tree. Consider adding similar exclusions for file types you don't need to sync, such as core dump 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 should run 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 are not doing bisync development testing. 🧪
• 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 are gathered for Path1 and Path2 while using the user's --filters-file. During the check access phase, bisync scans these listings for RCLONE_TEST files. Any RCLONE_TEST files hidden by the --filters-file are not in the listings and thus are not checked during the check access phase. 🕵️‍♀️

---

🩹 Troubleshooting 🩹

Reading bisync logs

Here are two normal runs. The first one has a newer file on the remote. The second has no deltas between local and remote. So chill, these are the good ones 😌

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 indicate that it would try to delete some files. For example, if a file is new on Path2 and does not exist on Path1 then it would normally 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. Scrutinize the proposed deletes carefully, and if the files would have been copied to Path1 then the threatened deletes on Path2 may be disregarded. 👀✅

Retries

Rclone has built-in retries. If you run with --verbose you'll see error and retry messages such as shown 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 ignore the error messages. It's giving "all good actually" 💅

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. slay 🎉

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 are 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 (https://rclone.org/drive/#drive-acknowledge-abuse). 🙈

📄 Google Docs (and other files of unknown size) 📄

As of v1.66, Google Docs (https://rclone.org/drive/#import-export-of-google-documents) (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 (https://rclone.org/drive/#drive-export-formats) (default "docx,xlsx,pptx,svg") and the non-drive -> drive direction is controlled by --drive-import-formats (https://rclone.org/drive/#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.) ✨

okay so bestie, listen — if --drive-import-formats is set (and spoiler: it is not, by default 🙈), then literally all of those formats you specified get converted into Google Docs, but only if there's no Google Doc already sitting there with a matching name. Caution though! that conversion can be mad lossy, and in most cases it's probably not what you want, fr fr. 💀

If you wanna bisync Google Docs as URL shortcut links (basically the same vibe as "Drive for Desktop"), you use --drive-export-formats url, or you can peep the alternatives here: https://rclone.org/drive/#exportformats:~:text=available%20Google%20Documents.-,Extension,macOS,-Standard%20options.

Heads up: these little link files can't be edited on the non-drive side — the absolute moment you try to sync an edited link file back to drive you're getting errors, no cap. They CAN be deleted though (and yes, deleting one deletes the corresponding Google Doc 😭). And if you make a .url file on the non-drive side that doesn't match any existing Google Doc, bisyncing it just copies the literal .url file over to drive — no Google Doc gets created, periodt. So the general rule of thumb? Think of them as read-only placeholders on the non-drive side, and do all your changing on the drive side. 🫶

Same energy with other export-formats, btw: it's genuinely best to only move/rename Google Docs on the drive side. Why? Because otherwise bisync reads it as one file deleted + another file created, so it goes ahead and deletes the Google Doc and makes a brand new file at the new path. (And whether that new file is a Google Doc or not? That depends entirely on --drive-import-formats, iykyk ✨)

Lastly — and this one's important — every single Google Doc on the drive side has a size of -1 and no checksum. Which means they cannot be reliably synced with --checksum or --size-only. To be exact about it: they'll still get created/deleted, and bisync's delta engine will notice the changes and queue them up for syncing, but the underlying sync function looks at them and goes "yeah these are identical" and skips them. 💀 To work around that whole situation, use the default (modtime and size) instead of --checksum or --size-only.

And if you just want Google Docs to not exist in your life at all? Use --drive-skip-gdocs: https://rclone.org/drive/#drive-skip-gdocs ✨

---

Usage examples 🌸

Cron ⏰

So rclone does not yet have a built-in way to monitor your local filesystem for changes — it just has to be blindly run periodically, bestie. 😭 On Windows you can do this with a Task Scheduler; on Linux you've got Cron, and that's what we're describing below.

The 1st example runs a sync every 5 minutes between a local directory and an OwnCloud server, with the 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

For all the deets on crontab time interval expressions, go look at the crontab syntax: https://www.man7.org/linux/man-pages/man1/crontab.1p.html#INPUT_FILES

If you're running 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 of 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, sure — but what if you've got some highly sensitive files that need synching too? 👀

So the whole point of using a cloud service here is exchanging both routine and sensitive personal files between your home network, your personal notebook when you're on the road, and your work computer. The routine data isn't sensitive, obviously. For the sensitive data, you configure an rclone crypt remote (https://rclone.org/crypt/) pointing at a subdirectory inside the local disk tree that's bisync'd to Dropbox, and then you set up a bisync for this local crypt directory to a directory outside of the main sync tree. Slay. 💅

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 the 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 the rclone source code locally to work with bisync tests. Periodt.

Bisync has a dedicated test framework, implemented in the bisync_test.go file, which lives right there 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. You can invoke individual tests by their directory name, like:

go test . -case basic -remote local -remote2 gdrive: -v

Tests will make a temporary folder on remote and purge it afterwards. And if during a test run there are intermittent errors and rclone retries, those errors get captured and flagged as invalid MISCOMPAREs. Re-running the test lets it pass. Just consider such failures as noise, bestie. 🙈

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 goes 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_, and this prefix can be omitted on the 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. iykyk — the dir name is literally a pun, iconic 💖
• 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. okay this one is lowkey important, bestie, do not skip it 🫶
• 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 (https://rclone.org/dropbox/#get-your-own-dropbox-app-id).

---

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. fr fr, nobody is hand-editing 400 log files 😭

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. generic ✨ portable ✨ slay

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/. Please note that normal line-level diff is generally useless here.
7. Check the difference carefully!
8. Commit the change (git commit) only if you are sure. If unsure, save your code changes then wipe the log diffs from git: git reset [--hard].

Step 8 is not a joke, bestie. git reset [--hard] will absolutely wipe your uncommitted work. Save first, then reset. No cap. 💀

---

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. the ID matters, bestie, don't touch the parent
• 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. she's self-sufficient, she brings her own slash 💅

---

Benchmarks 🔥📊

This section is work in progress.

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 (https://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.

yes the XXXs are literally in the original, bestie — those numbers were never filled in 🙈

---

References 🌈📚

rclone's bisync implementation was derived from the rclonesync-V2 (https://github.com/cjnaz/rclonesync-V2) project, including documentation and test mechanisms, with @cjnaz (https://github.com/cjnaz)'s full support and encouragement. shoutout to @cjnaz, absolute legend 🫶

rclone bisync is similar in nature to a range of other projects:

• unison (https://github.com/bcpierce00/unison)
• syncthing (https://github.com/syncthing/syncthing)
• cjnaz/rclonesync (https://github.com/cjnaz/rclonesync-V2)
• ConorWilliams/rsinc (https://github.com/ConorWilliams/rsinc)
• jwink3101/syncrclone (https://github.com/Jwink3101/syncrclone)
• DavideRossi/upback (https://github.com/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 (https://neil.fraser.name/writing/sync/). the Dual Shadow Method sounds like a spell and honestly? it kind of is 🦋

Also note a number of academic publications by Benjamin Pierce (http://www.cis.upenn.edu/%7Ebcpierce/papers/index.shtml#File%20Synchronization) about Unison and synchronization in general.

---

Changelog 📝✨

v1.74.2

• Fixed an issue causing --conflict-loser pathname to produce unexpected behavior if using a non-default --conflict-resolve value.

v1.74

• Added several missing rc parameters.
• Optional rc parameters are now truly optional.
• rc output now provides more structured information.

v1.71

• bisync is now officially released from beta. WE'RE OUT OF BETA BABY 🎉👑
• Fixed an issue causing hash type to be set incorrectly if path2 had slow hashes and --no-slow-hash or --slow-hash-sync-only was in use.
• Fixed an issue causing errors when running concurrent bisync runs through the rc.

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 single operation instead of two — yeah, glow-up 💅
• --track-renames and --backup-dir are supported now ✨
• The known issue with partial uploads on local/ftp/sftp? Resolved 🎉 (unless you're using --inplace, bestie — then nah)
• Final listings are now generated straight from the sync results, so no more having to re-list 🔥
• Bisync is so much more resilient to stuff changing while a bisync run is happening, and way less likely to throw critical errors or just straight-up miss changes 👑
• Bisync can now roll a file listing back when it's not sure about something, which basically marks the file as "needs a recheck next time" 🫶
• A few basic terminal colors are supported now, and you control them with --color (https://rclone.org/docs/#color-autoneveralways) — options are AUTO, NEVER, ALWAYS 🌈
• The initial listing snapshots of Path1 and Path2 are now generated concurrently, using the same "march" infrastructure as check and sync, which means better performance and less chance of something going wrong (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=4.%20Listings%20should%20alternate%20between%20paths%20to%20minimize%20errors) 💖
• Unicode normalization handling and case insensitivity are fixed, plus there's support for --fix-case (https://rclone.org/docs/#fix-case), --ignore-case-sync, and --no-unicode-normalization (https://rclone.org/docs/#no-unicode-normalization) 🎀
• --resync is so much more efficient now (especially if you're out here using --create-empty-src-dirs) ⭐
• Google Docs — and any other files with unknown size — are 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 --size-only, whenever check isn't available 💜
• Bisync no longer fails to find the correct listing file when configs get overridden with backend-specific flags 🙈
• Bisync now fully supports comparing based on any combination of size, modtime, and checksum — the old restriction on backends without modtime support? Gone, periodt 💀
• Bisync now supports a "Graceful Shutdown" mode, so you can cleanly cancel a run early without needing --resync 🌸
• New --recover flag lets you do robust recovery after interruptions, no --resync required 🙌
• New --max-lock setting lets lock files automatically renew and expire, which means better automatic recovery when a run gets interrupted 🔐
• Bisync now supports auto-resolving sync conflicts and customizing rename behavior with the new --conflict-resolve, --conflict-loser, and --conflict-suffix flags ✨
• New --resync-mode flag gives you more control over which version of a file gets kept during a --resync 👑
• Bisync now supports --retries (https://rclone.org/docs/#retries-int) and --retries-sleep (when --resilient is set) 💖

v1.64

• Fixed an issue (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=1.%20Dry%20runs%20are%20not%20completely%20dry) where dry runs would inadvertently commit filter changes — not very dry of them ngl 😭
• Fixed an issue (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=2.%20%2D%2Dresync%20deletes%20data%2C%20contrary%20to%20docs) where --resync would erroneously delete empty folders and duplicate files that were unique to Path2 💀
• --check-access is now enforced during --resync, which prevents data loss in certain user error scenarios (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=%2D%2Dcheck%2Daccess%20doesn%27t%20always%20fail%20when%20it%20should) 🛡️
• Fixed an issue (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=5.%20Bisync%20reads%20files%20in%20excluded%20directories%20during%20delete%20operations) where bisync was considering way more files than it needed to, because the filters were overbroad during delete operations 🙈
• Improved detection of false positive change conflicts (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=1.%20Identical%20files%20should%20be%20left%20alone%2C%20even%20if%20new/newer/changed%20on%20both%20sides) — identical files now get left alone instead of renamed 🫶
• Added support for --create-empty-src-dirs (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=3.%20Bisync%20should%20create/delete%20empty%20directories%20as%20sync%20does%2C%20when%20%2D%2Dcreate%2Dempty%2Dsrc%2Ddirs%20is%20passed) ✨
• Added experimental --resilient mode so you can recover from self-correctable errors (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=2.%20Bisync%20should%20be%20more%20resilient%20to%20self%2Dcorrectable%20errors) 💪
• Added new --ignore-listing-checksum flag (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=6.%20%2D%2Dignore%2Dchecksum%20should%20be%20split%20into%20two%20flags%20for%20separate%20purposes) so it stays clearly distinct from --ignore-checksum 🎀
• Performance improvements (https://forum.rclone.org/t/bisync-bugs-and-feature-requests/37636#:~:text=6.%20Deletes%20take%20several%20times%20longer%20than%20copies) for large remotes 🚀
• Documentation and testing improvements 📚

✨ Release signing 💅

okay so bestie, the hashes of the binary artefacts of the rclone release are signed with a public PGP/GPG key 🎀 — and yeah, you can verify this manually, and that is exactly the little journey we're going on below, no skipping anything.

The same mechanism is also used by rclone selfupdate (https://rclone.org/commands/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 into the rclone binary. 🫶

🔑 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 ads this key is used for signing.

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. trust but verify, it's giving responsible queen behaviour 💖

• The source for this page on GitHub (https://github.com/rclone/rclone/blob/master/docs/content/release_signing.md).
• Through DNS dig key.rclone.org txt

If you find anything that doesn't not match, please contact the developers at once. 🚨 like, immediately.

🕵️♀️ How to verify the release

In the release directory you will see the release files and some files called MD5SUMS, SHA1SUMS and SHA256SUMS.

$ 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-----

⬇️ Download the files

The first step is to download the binary and 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 .

✅ 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. 👑

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. full circle moment ✨

Extract the signed data with:

$ gpg --output SHA256SUMS.signed --decrypt SHA256SUMS

Then check the binaries:

$ sha256sum -c --ignore-missing SHA256SUMS.signed
rclone-v1.63.1-windows-amd64.zip: OK

Or do the check with rclone

$ rclone hashsum sha256 -C SHA256SUMS.signed rclone-v1.63.1-windows-amd64.zip
= 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

🎀 Verify signatures and hashes together

You can verify the signatures and hashes in one command line like this:

$ 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 command, all the checks, main character energy honestly 💜

💾 1Fichier

Okay bestie, so this one? It's a backend for the 1fichier cloud storage service (that's https://1fichier.com for the girlies who need the link). Heads up though: you NEED a Premium subscription to use the API. No premium, no vibes. Periodt.

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, queen. 💅

⚙️ Configuration

The initial setup for 1Fichier involves getting the API key from the website which you need to do in your browser. Yes, browser. Yes, you have to actually go do it. Sorry babe. 🫶

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 / 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 (replace remote with the name you gave your remote):

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

1Fichier does not support modification times. It supports the Whirlpool hash algorithm. So yeah, timestamps are not the moment here, but Whirlpool is serving. ✨

👯 Duplicated files

1Fichier can have two files with exactly the same name and path (unlike a normal file system). It's giving chaos, honestly.

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates. Not a vibe. Watch your logs bestie.

🚫 Restricted filename characters

In addition to the default restricted characters set (https://rclone.org/overview/#restricted-characters) the following characters are also replaced:

• \ — 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:

• SP — 0x20 → ␠

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings. JSON said no. 💀

✨ 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 (https://rclone.org/commands/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 (https://rclone.org/commands/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 (https://rclone.org/overview/#encoding) 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.

See List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

---

🪞 Alias

The alias remote provides a new name for another remote. It's literally giving "same girl, different name." 👑

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 (https://rclone.org/docs/#connection-strings). 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. Iconic flexibility tbh.

⚙️ 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 (replace remote with the name you gave your remote):

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. It's giving universal compatibility, and honestly? Slay. 🫶

• AWS S3
• Alibaba Cloud (Aliyun) Object Storage System (OSS)
• Ceph
• China Mobile Ecloud Elastic Object Storage (EOS)
• Cloudflare R2
• Arvan Cloud Object Storage (AOS)
• Bizfly Cloud Simple Storage
• Cubbit DS3
• DigitalOcean Spaces
• Dreamhost
• Exaba
• Fastly Object Storage
• FileLu S5 (S3-Compatible Object Storage)
• GCS
• Hetzner
• Hitachi Content Platform (HCP)
• Huawei OBS
• IBM COS S3
• IDrive e2
• Impossible Cloud
• Intercolo Object Storage
• IONOS Cloud
• Leviia Object Storage
• Liara Object Storage
• Linode Object Storage
• Magalu Object Storage
• MEGA S4 Object Storage
• Minio
• Outscale
• OVHcloud
• Petabox
• Pure Storage FlashBlade
• Qiniu Cloud Object Storage (Kodo)
• Rabata Cloud Storage
• RackCorp Object Storage
• Rclone Serve S3
• Scaleway
• Scality (RING / ARTESCA)
• Seagate Lyve Cloud
• SeaweedFS
• Selectel
• Servercore Object Storage
• Spectra Logic
• Storj

And bestie we are so not done — there's more coming, keep scrolling. 💖

• Synology C2 Object Storage 💜
• Tencent Cloud Object Storage (COS) 🧡
• US3 💙
• Wasabi 💚
• Zadara Object Storage 🤍
• Zata 💛
• Zero Services (ZERO-Z3) 🖤

okay so now the fun part — actually using the thing bestie ✨

Paths go like remote:bucket (or just remote: if you're running the lsd command, that one's special). And yes you can absolutely nest subdirectories in there too, like remote:bucket/path/to/dir 🌸

Once you've made yourself a remote (scroll up to the provider-specific section if you need it 👀) 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.

rclone sync --interactive /home/local/directory remote:bucket

heads up bestie 👀 that sync one deletes the excess files in the bucket. That's the whole point of sync, but like… know that going in 💀

---

⚙️ Configuration

okay so here's a whole walkthrough of making an s3 configuration for the AWS S3 provider 🫶 Most of it applies to the other providers too — any differences are described below (which is giving "read the fine print but honestly it's fine" energy).

First run

rclone config

and it'll hold your hand through an interactive setup process, 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 / 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>

like… that whole thing. Every option, every prompt, right there 👑 And honestly the defaults are doing a lot of the heavy lifting, you just keep pressing numbers 💅

---

⏱️ Modification times and hashes

💫 Modification times

The modified time gets stored as metadata on the object as X-Amz-Meta-Mtime, as floating point since the epoch, accurate to 1 ns ⭐ (yes, nanosecond accuracy, we're bougie like that).

If the modification time needs to be updated, rclone will attempt to perform a server side copy to update the modification — but only if the object can be copied in a single part. And if the object is larger than 5Gb, or it's chilling in Glacier or Glacier Deep Archive storage, then rip, the object gets uploaded rather than copied 😭

Also note: reading this from the object costs you an additional HEAD request, because the metadata isn't returned in object listings. It's giving "extra ticket, extra line" energy 🎟️

🔗 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 ✨ easy, clean, no notes.

But — and this is the plot twist — 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 called 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 🫶 (honestly bestie, just use rclone check, it's the vibe)

For large objects, calculating this hash can take some time, so the addition of this hash can be disabled with --s3-disable-checksum. That will mean that these objects do not have an MD5 checksum 😶 no checksum, no cap.

And same disclaimer as above: reading this from the object takes an additional HEAD request, as the metadata isn't returned in object listings.

---

💸 Reducing costs

Bestie, S3 is amazing but it will absolutely drain your coins if you let it, so here's how to be cheap AND fast. 💅

🙅 Avoiding HEAD requests to read the modification time

So by default, rclone uses the modification time of objects stored in S3 for syncing. Sounds innocent right? WRONG. That time is stored in object metadata which unfortunately takes an extra HEAD request to read, and that can be expensive — in time AND in money. 💀

The modification time is used by default for all operations that require checking the time a file was last updated. It lets rclone treat the remote more like a true filesystem, which is the vibe, but it's inefficient on S3 because it requires an extra API call to retrieve the metadata.

Good news: the extra API calls can be avoided when syncing (using rclone sync or rclone copy) in a few different ways, and each one has 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.
  • Will cause the source to read an MD5 checksum which, if it is a local disk, will cause lots of disk activity.
  • If the source and destination are both S3 this is the recommended flag to use for maximum efficiency.
  • rclone sync --checksum /path/to/source s3:bucket
• --update --use-server-modtime
  • 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 should 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. That's one API call per directory, and honestly? It adds up. 📈

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). Check the rclone docs at https://rclone.org/docs/#fast-list 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 small number of files into a big 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 isn't 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. Very protective of you, honestly. 🫶

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. So like… your call bestie. 😭

🔥 Increasing performance

👯 Using server-side copy

If you are copying objects between S3 buckets in the same region, you should use server-side copy. This is much faster than downloading and re-uploading the objects, as no data is transferred. It's giving free real estate. 👑

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 very conservative default 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. Science, but make it storage. 🧚

🛡️ 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 https 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 not 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 ultimately paranoid 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 at https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html 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. Time travel but for buckets, iconic. 🦋

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 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 --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 unpredictable. 😭 Be careful out there bestie.

🧼 Cleanup

ok so bestie, if you run rclone cleanup s3:bucket it will yeet all pending multipart uploads older than 24 hours 💅 you can totally use the --interactive/i or --dry-run flag to see exactly what it's about to do before it does it (protect your peace fr fr). if you want more control over the expiry date, run rclone backend cleanup s3:bucket -o max-age=1h to expire all uploads older than one hour ✨ and you can run rclone backend list-multipart-uploads s3:bucket to peek at the pending multipart uploads, like a little gossip session for your bucket 👀

---

🚫 Restricted filename characters

S3 allows any valid UTF-8 string as a key, no cap 🫶

Invalid UTF-8 bytes will be replaced (see the invalid UTF-8 overview at https://rclone.org/overview/#invalid-utf8), because they literally can't be used in XML 😭

The following characters are replaced since these are problematic when dealing with the REST API:

• Character NUL — value 0x00 — replacement ␀
• Character / — value 0x2F — replacement ／

The encoding will also encode these file names as they don't seem to work with the SDK properly:

• File name . — replacement ．
• File name .. — replacement ．．

---

⚠️ Important note about double slashes (//)

Object keys containing consecutive forward slashes (//) are not supported by rclone. periodt.

When rclone encounters an object key with // (e.g. a//b), it will normalize the path to use a single slash (e.g. a/b). This normalization can cause "object not found" errors when trying to access the original object, as rclone will look for the normalized path instead of the actual object key 💀

Example:

• Original S3 object key: folder//file.txt
• rclone interprets it as: folder/file.txt
• Result: "object not found" error when trying to access folder//file.txt

Workaround: Avoid using consecutive forward slashes (//) in S3 object keys when using rclone. If you have existing objects with // in their keys, you will need to rename them to use single slashes or access them through other means 🙈

---

📦 Multipart uploads

rclone supports multipart uploads with S3 which means that it can upload files bigger than 5 GiB 🔥

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 --s3-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 --s3-chunk-size and the number of chunks uploaded concurrently is specified by --s3-upload-concurrency.

Multipart uploads will use extra memory equal to: --transfers × --s3-upload-concurrency × --s3-chunk-size. Single part uploads do not use extra memory ✨

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 👑

---

🪣 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:

incorrect region, the bucket is not in 'XXX' region

---

🔐 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 (see the AWS CLI configure files docs at https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html):
    • 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 (see https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html) to read config from an external program.

With env_auth = true rclone (which uses the SDK for Go v2) should support all authentication methods (https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) that the aws CLI tool does and the other AWS SDKs 💖

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).

---

🎭 Assume Role (Cross-Account Access)

If you need to access S3 resources in a different AWS account, you can use IAM role assumption 🧚 this is useful for cross-account access scenarios where you have credentials in one account but need to access resources in another account.

To use assume role, configure the following parameters:

• role_arn — The ARN (Amazon Resource Name) of the IAM role to assume in the target account. Format: arn:aws:iam::ACCOUNT-ID:role/ROLE-NAME
• role_session_name (optional) — A name for the assumed role session. If not specified, rclone will generate one automatically.
• role_session_duration (optional) — Duration for which the assumed role credentials are valid. If not specified, AWS default duration will be used (typically 1 hour).
• role_external_id (optional) — An external ID required by the role's trust policy for additional security. This is typically used when the role is accessed by a third party.

The assume role feature works with both direct credentials (env_auth = false) and environment-based authentication (env_auth = true). Rclone will first authenticate using the base credentials, then use those credentials to assume the specified role ✨

Example configuration for cross-account access:

[s3-cross-account]
type = s3
provider = AWS
env_auth = true
region = us-east-1
role_arn = arn:aws:iam::123456789012:role/CrossAccountS3Role
role_session_name = rclone-session
role_external_id = unique-role-external-id-12345

In this example:

• Base credentials are obtained from the environment (IAM role, credentials file, or environment variables)
• These credentials are then used to assume the role CrossAccountS3Role in account 123456789012
• An external ID is provided for additional security as required by the role's trust policy

The target role's trust policy in the destination account must allow the source account or user to assume it. Example trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::SOURCE-ACCOUNT-ID:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalID": "unique-role-external-id-12345"
        }
      }
    }
  ]
}

---

🔑 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 (https://gist.github.com/ebridges/ebfc9042dd7c756cd101cfa807b7ae2b) 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 💀

🧊 Glacier and Glacier Deep Archive 🧊

Okay so listen — you can upload stuff using the glacier storage class, or yeet objects over to glacier later with a lifecycle policy (http://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html). The bucket itself still syncs and copies like normal, no drama. BUT. The second rclone tries to touch data chillin' in the glacier storage class, you get hit with an error that looks a lil like this:

2017/09/11 19:07:43 Failed to sync: failed to open source object: Object in GLACIER, restore first: path/to/file

When that happens, bestie, you gotta restore (http://docs.aws.amazon.com/AmazonS3/latest/user-guide/restore-archived-objects.html) the object(s) in question before you can get at the contents. The restore section down below shows how to do that with rclone. 💅

Heads up: rclone only speaks the S3 API — it does not speak the Glacier Vault API, so rclone cannot directly access Glacier Vaults. No cap.

---

🔒 Object-lock enabled S3 bucket 🔒

Per AWS's documentation on S3 Object Lock (https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-permission):

If you configure a default retention period on a bucket, requests to upload objects in such a bucket must include the Content-MD5 header.

And the way rclone ate that? It automatically computes and includes the Content-MD5 header whenever you upload objects with Object Lock parameters set. Zero special configuration required. Iconic behaviour honestly. ✨

---

🗓️ Setting Object Lock retention 🗓️

Rclone supports setting Object Lock retention on uploaded objects with these options:

• --s3-object-lock-mode - Set the Object Lock mode (GOVERNANCE or COMPLIANCE)
• --s3-object-lock-retain-until-date - Set the retention date (RFC3339 format or duration like 365d, 24h)
• --s3-object-lock-legal-hold-status - Set legal hold (ON or OFF)

Example — upload files with 1 year GOVERNANCE retention:

rclone copy local:/data remote:bucket \
    --s3-object-lock-mode GOVERNANCE \
    --s3-object-lock-retain-until-date 365d

---

📋 Copying Object Lock settings from source 📋

When you're using --metadata, you can use the special value copy to preserve the source object's Object Lock settings:

rclone copy source:bucket dest:bucket \
    --metadata \
    --s3-object-lock-mode copy \
    --s3-object-lock-retain-until-date copy

You can also mix copied and explicit values, like the multitasking queen you are. For example, to change the mode from COMPLIANCE to GOVERNANCE while preserving the original retention date:

rclone copy source:bucket dest:bucket \
    --metadata \
    --s3-object-lock-mode GOVERNANCE \
    --s3-object-lock-retain-until-date copy

---

➕ Additional Object Lock options ➕

• --s3-bypass-governance-retention - Required to delete or overwrite objects with GOVERNANCE mode retention before the retention date expires
• --s3-bucket-object-lock-enabled - Enable Object Lock when creating a new bucket with rclone mkdir
• --s3-object-lock-set-after-upload - Set Object Lock via separate API calls after upload (for providers that don't support Object Lock headers during PUT)

---

⭐ Standard options ⭐

Here are the Standard options specific to s3 (Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, BizflyCloud, Ceph, ChinaMobile, Cloudflare, Cubbit, DigitalOcean, Dreamhost, Exaba, Fastly, FileLu, FlashBlade, GCS, HCP, Hetzner, HuaweiOBS, IBMCOS, IDrive, ImpossibleCloud, Intercolo, IONOS, Leviia, Liara, Linode, LyveCloud, Magalu, Mega, Minio, Netease, Outscale, OVHcloud, Petabox, Qiniu, Rabata, RackCorp, Rclone, Scaleway, Scality, SeaweedFS, Selectel, Servercore, SpectraLogic, Storj, Synology, TencentCOS, US3, Wasabi, Zadara, Zata, ZeroServices, Other). That's a lot of providers and yes, they're all valid. 🫶

---

🌈 --s3-provider 🌈

Choose your S3 provider. Character selection screen but make it cloud storage.

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)
  • "BizflyCloud"
    • Bizfly Cloud Simple Storage
  • "Ceph"
    • Ceph Object Storage
  • "ChinaMobile"
    • China Mobile Ecloud Elastic Object Storage (EOS)
  • "Cloudflare"
    • Cloudflare R2 Storage
  • "Cubbit"
    • Cubbit DS3 Object Storage
  • "DigitalOcean"
    • DigitalOcean Spaces
  • "Dreamhost"
    • Dreamhost DreamObjects
  • "Exaba"
    • Exaba Object Storage
  • "Fastly"
    • Fastly Object Storage
  • "FileLu"
    • FileLu S5 (S3-Compatible Object Storage)
  • "FlashBlade"
    • Pure Storage FlashBlade Object Storage
  • "GCS"
    • Google Cloud Storage
  • "HCP"
    • Hitachi Content Platform (HCP)
  • "Hetzner"
    • Hetzner Object Storage
  • "HuaweiOBS"
    • Huawei Object Storage Service
  • "IBMCOS"
    • IBM COS S3
  • "IDrive"
    • IDrive e2
  • "ImpossibleCloud"
    • Impossible Cloud Object Storage
  • "Intercolo"
    • Intercolo Object Storage
  • "IONOS"
    • IONOS Cloud
  • "Leviia"
    • Leviia Object Storage
  • "Liara"
    • Liara Object Storage
  • "Linode"
    • Linode Object Storage
  • "LyveCloud"
    • Seagate Lyve Cloud
  • "Magalu"
    • Magalu Object Storage
  • "Mega"
    • MEGA S4 Object Storage
  • "Minio"
    • Minio Object Storage
  • "Netease"
    • Netease Object Storage (NOS)
  • "Outscale"
    • OUTSCALE Object Storage (OOS)
  • "OVHcloud"
    • OVHcloud Object Storage
  • "Petabox"
    • Petabox Object Storage
  • "Qiniu"
    • Qiniu Object Storage (Kodo)
  • "Rabata"
    • Rabata Cloud Storage
  • "RackCorp"
    • RackCorp Object Storage
  • "Rclone"
    • Rclone S3 Server
  • "Scaleway"
    • Scaleway Object Storage
  • "Scality"
    • Scality (RING / ARTESCA)
  • "SeaweedFS"
    • SeaweedFS S3
  • "Selectel"
    • Selectel Object Storage
  • "Servercore"
    • Servercore Object Storage
  • "SpectraLogic"
    • Spectra Logic Black Pearl
  • "Storj"
    • Storj (S3 Compatible Gateway)
  • "Synology"
    • Synology C2 Object Storage
  • "TencentCOS"
    • Tencent Cloud Object Storage (COS)
  • "US3"
    • US3 Object Storage
  • "Wasabi"
    • Wasabi Object Storage
  • "Zadara"
    • Zadara Object Storage
  • "Zata"
    • Zata (S3 compatible Gateway)
  • "ZeroServices"
    • Zero Services GmbH (ZERO-Z3)
  • "Other"
    • Any other S3 compatible provider

---

🔑 --s3-env-auth 🔑

Get AWS credentials from runtime (environment variables or EC2/ECS metadata 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.

Leave blank if you are using an S3 clone and you don't have a region.

Properties:

• Config: region
• Env Var: RCLONE_S3_REGION
• Provider: AWS,BizflyCloud,Ceph,Cloudflare,Cubbit,DigitalOcean,Dreamhost,Exaba,Fastly,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IBMCOS,ImpossibleCloud,Intercolo,IONOS,Leviia,LyveCloud,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,Rabata,RackCorp,Scaleway,Scality,SeaweedFS,Selectel,Servercore,Synology,Wasabi,Zadara,Zata,ZeroServices,Other
• 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.
    • Provider: AWS
  • "us-east-2"
    • US East (Ohio) Region.
    • Needs location constraint us-east-2.
    • Provider: AWS
  • "us-west-1"
    • US West (Northern California) Region.
    • Needs location constraint us-west-1.
    • Provider: AWS
  • "us-west-2"
    • US West (Oregon) Region.
    • Needs location constraint us-west-2.
    • Provider: AWS
  • "ca-central-1"
    • Canada (Central) Region.
    • Needs location constraint ca-central-1.
    • Provider: AWS
  • "eu-west-1"
    • EU (Ireland) Region.
    • Needs location constraint EU or eu-west-1.
    • Provider: AWS
  • "eu-west-2"
    • EU (London) Region.
    • Needs location constraint eu-west-2.
    • Provider: AWS
  • "eu-west-3"
    • EU (Paris) Region.
    • Needs location constraint eu-west-3.
    • Provider: AWS
  • "eu-north-1"
    • EU (Stockholm) Region.
    • Needs location constraint eu-north-1.
    • Provider: AWS
  • "eu-south-1"
    • EU (Milan) Region.
    • Needs location constraint eu-south-1.
    • Provider: AWS
  • "eu-central-1"
    • EU (Frankfurt) Region.
    • Needs location constraint eu-central-1.
    • Provider: AWS
  • "ap-southeast-1"
    • Asia Pacific (Singapore) Region.
    • Needs location constraint ap-southeast-1.
    • Provider: AWS
  • "ap-southeast-2"
    • Asia Pacific (Sydney) Region.
    • Needs location constraint ap-southeast-2.
    • Provider: AWS
  • "ap-northeast-1"
    • Asia Pacific (Tokyo) Region.
    • Needs location constraint ap-northeast-1.
    • Provider: AWS
  • "ap-northeast-2"
    • Asia Pacific (Seoul).
• Needs location constraint ap-northeast-2. 💖 bestie don't sleep on this one
  • Provider: AWS. ✨
• "ap-northeast-3"
  • Asia Pacific (Osaka-Local). 🎀 it's giving Kansai vibes
  • Needs location constraint ap-northeast-3.
  • Provider: AWS. 💅
• "ap-south-1"
  • Asia Pacific (Mumbai). 🌸
  • Needs location constraint ap-south-1.
  • Provider: AWS. 🫶
• "ap-east-1"
  • Asia Pacific (Hong Kong) Region. 🌈
  • Needs location constraint ap-east-1.
  • Provider: AWS. ⭐
• "sa-east-1"
  • South America (Sao Paulo) Region. 💜
  • Needs location constraint sa-east-1.
  • Provider: AWS. 🔥
• "il-central-1"
  • Israel (Tel Aviv) Region. ✨
  • Needs location constraint il-central-1.
  • Provider: AWS. 👑
• "me-south-1"
  • Middle East (Bahrain) Region. 🦋
  • Needs location constraint me-south-1.
  • Provider: AWS. 💫
• "af-south-1"
  • Africa (Cape Town) Region. 🌍
  • Needs location constraint af-south-1.
  • Provider: AWS. 🧚
• "cn-north-1"
  • China (Beijing) Region. 🏮
  • Needs location constraint cn-north-1.
  • Provider: AWS. 💖
• "cn-northwest-1"
  • China (Ningxia) Region. 🐉
  • Needs location constraint cn-northwest-1.
  • Provider: AWS. ✨
• "us-gov-east-1"
  • AWS GovCloud (US-East) Region. 🦅
  • Needs location constraint us-gov-east-1.
  • Provider: AWS. 💅
• "us-gov-west-1"
  • AWS GovCloud (US) Region. 🗽
  • Needs location constraint us-gov-west-1.
  • Provider: AWS. 🫶
• "hn"
  • Ha Noi. 🌸
  • Provider: BizflyCloud. 💖
• "hcm"
  • Ho Chi Minh. 🌺
  • Provider: BizflyCloud. ✨
• ""
  • Use this if unsure. 🤷♀️ lowkey the safe pick
  • Will use v4 signatures and an empty region. 🔥
  • Provider: Ceph,DigitalOcean,Dreamhost,Exaba,GCS,HCP,IBMCOS,Leviia,LyveCloud,Minio,Netease,Scality,SeaweedFS,Wasabi,Other. 💅
• "other-v2-signature"
  • Use this only if v4 signatures don't work. ⚠️
  • E.g. pre Jewel/v10 CEPH. 💀
  • Provider: Ceph,DigitalOcean,Dreamhost,Exaba,GCS,HCP,IBMCOS,Leviia,LyveCloud,Minio,Netease,Scality,SeaweedFS,Wasabi,Other. 😭
• "auto"
  • R2 buckets are automatically distributed across Cloudflare's data centers for low latency. ⚡
  • Provider: Cloudflare. 🌥️
• "eu-west-1"
  • Europe West. 🇪🇺
  • Provider: Cubbit. 🧊
• "au-east-1"
  • AU East 1. 🇦🇺
  • Provider: Fastly. 🚀
• "eu-central"
  • EU Central. 🇪🇺
  • Provider: Fastly. 💨
• "eu-south-1"
  • EU South 1. 🇪🇺
  • Provider: Fastly. 🌞
• "eu-west-1"
  • EU West 1. 🇪🇺
  • Provider: Fastly. 🌊
• "jp-central-1"
  • JP Central 1. 🇯🇵
  • Provider: Fastly. 🗾
• "uk-east-1"
  • UK East 1. 🇬🇧
  • Provider: Fastly. ☕
• "us-central-1"
  • US Central 1. 🇺🇸
  • Provider: Fastly. 🌽
• "us-east"
  • US East. 🇺🇸
  • Provider: Fastly. 🗽
• "us-east-1"
  • US East 1. 🇺🇸
  • Provider: Fastly. 🦅
• "us-west"
  • US West. 🇺🇸
  • Provider: Fastly. 🌄
• "us-west-1"
  • US West 1. 🇺🇸
  • Provider: Fastly. 🌉
• "global"
  • Global. 🌐
  • Provider: FileLu. 💖
• "us-east"
  • North America (US-East). 🌎
  • Provider: FileLu. ✨
• "eu-central"
  • Europe (EU-Central). 🇪🇺
  • Provider: FileLu. 💅
• "ap-southeast"
  • Asia Pacific (AP-Southeast). 🌏
  • Provider: FileLu. 🫶
• "me-central"
  • Middle East (ME-Central). 🕌
  • Provider: FileLu. 💫
• "hel1"
  • Helsinki. 🇫🇮
  • Provider: Hetzner. ❄️
• "fsn1"
  • Falkenstein. 🇩🇪
  • Provider: Hetzner. 🏰
• "nbg1"
  • Nuremberg. 🇩🇪
  • Provider: Hetzner. 🥨
• "af-south-1"
  • AF-Johannesburg. 🇿🇦
  • Provider: HuaweiOBS. 💖
• "ap-southeast-2"
  • AP-Bangkok. 🇹🇭
  • Provider: HuaweiOBS. ✨
• "ap-southeast-3"
  • AP-Singapore. 🇸🇬
  • Provider: HuaweiOBS. 💅
• "cn-east-3"
  • CN East-Shanghai1. 🇨🇳
  • Provider: HuaweiOBS. 🌸
• "cn-east-2"
  • CN East-Shanghai2. 🇨🇳
  • Provider: HuaweiOBS. 🫶
• "cn-north-1"
  • CN North-Beijing1. 🇨🇳
  • Provider: HuaweiOBS. 🐉
• "cn-north-4"
  • CN North-Beijing4. 🇨🇳
  • Provider: HuaweiOBS. 🏮
• "cn-south-1"
  • CN South-Guangzhou. 🇨🇳
  • Provider: HuaweiOBS. 🍵
• "ap-southeast-1"
  • CN-Hong Kong. 🇭🇰
  • Provider: HuaweiOBS. 🌃
• "sa-argentina-1"
  • LA-Buenos Aires1. 🇦🇷
  • Provider: HuaweiOBS. 💃
• "sa-peru-1"
  • LA-Lima1. 🇵🇪
  • Provider: HuaweiOBS. 🦙
• "na-mexico-1"
  • LA-Mexico City1. 🇲🇽
  • Provider: HuaweiOBS. 🌮
• "sa-chile-1"
  • LA-Santiago2. 🇨🇱
  • Provider: HuaweiOBS. 🍷
• "sa-brazil-1"
  • LA-Sao Paulo1. 🇧🇷
  • Provider: HuaweiOBS. ⚽
• "ru-northwest-2"
  • RU-Moscow2. 🇷🇺
  • Provider: HuaweiOBS. 🐻
• "eu-central-2"
  • Frankfurt, Germany. 🇩🇪
  • Provider: ImpossibleCloud. 🌩️
• "eu-west-1"
  • Amsterdam, Netherlands. 🇳🇱
  • Provider: ImpossibleCloud. 🌷
• "eu-west-2"
  • London, UK. 🇬🇧
  • Provider: ImpossibleCloud. ☕
• "eu-west-3"
  • Paris, France. 🇫🇷
  • Provider: ImpossibleCloud. 🥐
• "eu-east-1"
  • Poznań, Poland. 🇵🇱
  • Provider: ImpossibleCloud. 🥟
• "eu-north-1"
  • Copenhagen, Denmark. 🇩🇰
  • Provider: ImpossibleCloud. 🧜‍♀️
• "us-east-1"
  • New York, USA. 🇺🇸
  • Provider: ImpossibleCloud. 🗽
• "de-fra"
  • Frankfurt, Germany. 🇩🇪
  • Provider: Intercolo. 💖
• "de"
  • Frankfurt, Germany. 🇩🇪
  • Provider: IONOS,OVHcloud. ✨
• "eu-central-2"
  • Berlin, Germany. 🇩🇪
  • Provider: IONOS. 💅
• "eu-central-3"
  • Berlin, Germany. 🇩🇪
  • Provider: IONOS. 🫶
• "eu-central-4"
  • Frankfurt, Germany. 🇩🇪
  • Provider: IONOS. 🌸
• "eu-south-2"
  • Logrono, Spain. 🇪🇸
  • Provider: IONOS. 🍷
• "us-central-1"
  • Lenexa, USA. 🇺🇸
  • Provider: IONOS. 🌽
• "eu-west-2"
  • Paris, France. 🇫🇷
  • Provider: Outscale. 🥖
• "us-east-2"
  • New Jersey, USA. 🇺🇸
  • Provider: Outscale. 🏙️
• "us-west-1"
  • California, USA. 🇺🇸
  • Provider: Outscale. 🌴
• "cloudgouv-eu-west-1"
  • SecNumCloud, Paris, France. 🇫🇷
  • Provider: Outscale. 🔒
• "ap-northeast-1"
  • Tokyo, Japan. 🇯🇵
  • Provider: Outscale. 🗼
• "gra"
  • Gravelines, France. 🇫🇷
  • Provider: OVHcloud. 💖
• "rbx"
  • Roubaix, France. 🇫🇷
  • Provider: OVHcloud. ✨
• "sbg"
  • Strasbourg, France. 🇫🇷
  • Provider: OVHcloud. 💅
• "eu-west-par"
  • Paris, France (3AZ). 🇫🇷
  • Provider: OVHcloud. 🫶
• "uk"
  • London, United Kingdom. 🇬🇧
  • Provider: OVHcloud. ☕
• "waw"
  • Warsaw, Poland. 🇵🇱
  • Provider: OVHcloud. 🥟
• "bhs"
  • Beauharnois, Canada. 🇨🇦
  • Provider: OVHcloud. 🍁
• "ca-east-tor"
  • Toronto, Canada. 🇨🇦
  • Provider: OVHcloud. 🏒
• "sgp"
  • Singapore. 🇸🇬
  • Provider: OVHcloud. 🦁
• "ap-southeast-syd"
  • Sydney, Australia. 🇦🇺
  • Provider: OVHcloud. 🦘
• "ap-south-mum"
  • Mumbai, India. 🇮🇳
  • Provider: OVHcloud. 🐘
• "us-east-va"
  • Vint Hill, Virginia, USA. 🇺🇸
  • Provider: OVHcloud. 🏛️
• "us-west-or"
  • Hillsboro, Oregon, USA. 🇺🇸
  • Provider: OVHcloud. 🌲
• "rbx-archive"
  • Roubaix, France (Cold Archive). 🇫🇷
  • Provider: OVHcloud. 🧊
• "us-east-1"
  • US East (N. Virginia). 🇺🇸
  • Provider: Petabox,Rabata. 💖
• "eu-central-1"
  • Europe (Frankfurt). 🇪🇺
  • Provider: Petabox. ✨
• "ap-southeast-1"
  • Asia Pacific (Singapore). 🇸🇬
  • Provider: Petabox. 💅
• "me-south-1"
  • Middle East (Bahrain). 🇧🇭
  • Provider: Petabox. 🫶
• "sa-east-1"
  • South America (São Paulo). 🇧🇷
  • Provider: Petabox. 🌸
• "cn-east-1"
  • The default endpoint - a good choice if you are unsure. 🤔
  • East China Region 1. 🇨🇳
  • Needs location constraint cn-east-1.
  • Provider: Qiniu. 💖
• "cn-east-2"
  • East China Region 2. 🇨🇳
  • Needs location constraint cn-east-2.
  • Provider: Qiniu. ✨
• "cn-north-1"
  • North China Region 1. 🇨🇳
  • Needs location constraint cn-north-1.
  • Provider: Qiniu. 💅
• "cn-south-1"
  • South China Region 1. 🇨🇳
  • Needs location constraint cn-south-1.
  • Provider: Qiniu. 🫶
• "us-north-1"
  • North America Region. 🌎
  • Needs location constraint us-north-1.
  • Provider: Qiniu. 🌸
• "ap-southeast-1"
  • Southeast Asia Region 1. 🌏
  • Needs location constraint ap-southeast-1.
  • Provider: Qiniu. 💖
• "ap-northeast-1"
  • Northeast Asia Region 1. 🌏
  • Needs location constraint ap-northeast-1.
  • Provider: Qiniu. ✨
• "eu-west-1"
  • EU (Ireland). 🇮🇪
  • Provider: Rabata. 💅
• "eu-west-2"
  • EU (London). 🇬🇧
  • Provider: Rabata. 🫶
• "global"
  • Global CDN (All locations) Region. 🌐
  • Provider: RackCorp. 🌸
• "au"
  • Australia (All states). 🇦🇺
  • Provider: RackCorp. 💖
• "au-nsw"
  • NSW (Australia) Region. 🇦🇺
  • Provider: RackCorp. ✨
• "au-qld"
  • QLD (Australia) Region. 🇦🇺
  • Provider: RackCorp. 💅
• "au-vic"
  • VIC (Australia) Region. 🇦🇺
  • Provider: RackCorp. 🫶
• "au-wa"
  • Perth (Australia) Region. 🇦🇺
  • Provider: RackCorp. 🌸
• "ph"
  • Manila (Philippines) Region. 🇵🇭
  • Provider: RackCorp. 💖
• "th"
  • Bangkok (Thailand) Region. 🇹🇭
  • Provider: RackCorp. ✨
• "hk"
  • HK (Hong Kong) Region. 🇭🇰
  • Provider: RackCorp. 💅
• "mn"
  • Ulaanbaatar (Mongolia) Region. 🇲🇳
  • Provider: RackCorp. 🫶
• "kg"
  • Bishkek (Kyrgyzstan) Region. 🇰🇬
  • Provider: RackCorp. 🌸
• "id"
• Jakarta (Indonesia) Region
  • Provider: RackCorp
• "jp" — Tokyo (Japan) Region 🇯🇵 · Provider: RackCorp
• "sg" — SG (Singapore) Region · Provider: RackCorp
• "de" — Frankfurt (Germany) Region 🇩🇪 · Provider: RackCorp
• "us" — USA (AnyCast) Region 🇺🇸 · Provider: RackCorp
• "us-east-1" — New York (USA) Region 🗽 · Provider: RackCorp
• "us-west-1" — Freemont (USA) Region · Provider: RackCorp
• "nz" — Auckland (New Zealand) Region 🥝 · Provider: RackCorp
• "nl-ams" — Amsterdam, The Netherlands 🌷 · Provider: Scaleway
• "fr-par" — Paris, France 🥐 · Provider: Scaleway
• "pl-waw" — Warsaw, Poland · Provider: Scaleway
• "ru-1" — St. Petersburg · Provider: Selectel,Servercore
• "ru-3" — St. Petersburg · Provider: Selectel
• "ru-7" — Moscow · Provider: Selectel,Servercore
• "gis-1" — Moscow · Provider: Selectel,Servercore
• "kz-1" — Kazakhstan · Provider: Selectel
• "uz-2" — Uzbekistan · Provider: Selectel
• "uz-2" — Tashkent, Uzbekistan · Provider: Servercore
• "kz-1" — Almaty, Kazakhstan · Provider: Servercore
• "eu-001" — Europe Region 1 · Provider: Synology
• "eu-002" — Europe Region 2 · Provider: Synology
• "us-001" — US Region 1 · Provider: Synology
• "us-002" — US Region 2 · Provider: Synology
• "tw-001" — Asia (Taiwan) · Provider: Synology
• "us-east-1" — The default region. Leave location constraint empty. · Provider: Zadara
• "us-east-1" — Indore, Madhya Pradesh, India 🇮🇳 · Provider: Zata
• "zero-fra1" — Frankfurt 1 · Provider: ZeroServices
• "zero-fra2" — Frankfurt 2 · Provider: ZeroServices
• "zero-eyl1" — Eyl 1 · Provider: ZeroServices

---

✨ --s3-endpoint ✨

okay bestie, this is the big one 👑 Endpoint for the S3 API.

Required when you're using an S3 clone — like, mandatory mandatory, no skipping 🫶

Properties:

• Config: endpoint
• Env Var: RCLONE_S3_ENDPOINT
• Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cloudflare,Cubbit,DigitalOcean,Dreamhost,Exaba,Fastly,FileLu,FlashBlade,GCS,HCP,Hetzner,HuaweiOBS,IBMCOS,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Mega,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,Rabata,RackCorp,Rclone,Scaleway,Scality,SeaweedFS,Selectel,Servercore,SpectraLogic,Storj,Synology,TencentCOS,US3,Wasabi,Zadara,Zata,ZeroServices,Other
• Type: string
• Required: false

Examples — and babes, there are so many 💀:

• "oss-accelerate.aliyuncs.com" — Global Accelerate · Provider: Alibaba
• "oss-accelerate-overseas.aliyuncs.com" — Global Accelerate (outside mainland China) · Provider: Alibaba
• "oss-cn-hangzhou.aliyuncs.com" — East China 1 (Hangzhou) · Provider: Alibaba
• "oss-cn-shanghai.aliyuncs.com" — East China 2 (Shanghai) · Provider: Alibaba
• "oss-cn-qingdao.aliyuncs.com" — North China 1 (Qingdao) · Provider: Alibaba
• "oss-cn-beijing.aliyuncs.com" — North China 2 (Beijing) · Provider: Alibaba
• "oss-cn-zhangjiakou.aliyuncs.com" — North China 3 (Zhangjiakou) · Provider: Alibaba
• "oss-cn-huhehaote.aliyuncs.com" — North China 5 (Hohhot) · Provider: Alibaba
• "oss-cn-wulanchabu.aliyuncs.com" — North China 6 (Ulanqab) · Provider: Alibaba
• "oss-cn-shenzhen.aliyuncs.com" — South China 1 (Shenzhen) · Provider: Alibaba
• "oss-cn-heyuan.aliyuncs.com" — South China 2 (Heyuan) · Provider: Alibaba
• "oss-cn-guangzhou.aliyuncs.com" — South China 3 (Guangzhou) · Provider: Alibaba
• "oss-cn-chengdu.aliyuncs.com" — West China 1 (Chengdu) · Provider: Alibaba
• "oss-cn-hongkong.aliyuncs.com" — Hong Kong (Hong Kong) 🇭🇰 · Provider: Alibaba
• "oss-us-west-1.aliyuncs.com" — US West 1 (Silicon Valley) · Provider: Alibaba
• "oss-us-east-1.aliyuncs.com" — US East 1 (Virginia) · Provider: Alibaba
• "oss-ap-southeast-1.aliyuncs.com" — Southeast Asia Southeast 1 (Singapore) · Provider: Alibaba
• "oss-ap-southeast-2.aliyuncs.com" — Asia Pacific Southeast 2 (Sydney) · Provider: Alibaba
• "oss-ap-southeast-3.aliyuncs.com" — Southeast Asia Southeast 3 (Kuala Lumpur) · Provider: Alibaba
• "oss-ap-southeast-5.aliyuncs.com" — Asia Pacific Southeast 5 (Jakarta) · Provider: Alibaba
• "oss-ap-northeast-1.aliyuncs.com" — Asia Pacific Northeast 1 (Japan) · Provider: Alibaba
• "oss-ap-south-1.aliyuncs.com" — Asia Pacific South 1 (Mumbai) · Provider: Alibaba
• "oss-eu-central-1.aliyuncs.com" — Central Europe 1 (Frankfurt) · Provider: Alibaba
• "oss-eu-west-1.aliyuncs.com" — West Europe (London) · Provider: Alibaba
• "oss-me-east-1.aliyuncs.com" — Middle East 1 (Dubai) 🐪 · Provider: Alibaba
• "s3.ir-thr-at1.arvanstorage.ir" — The default endpoint - a good choice if you are unsure. Tehran Iran (Simin) · Provider: ArvanCloud
• "s3.ir-tbz-sh1.arvanstorage.ir" — Tabriz Iran (Shahriar) · Provider: ArvanCloud
• "hn.ss.bfcplatform.vn" — Hanoi endpoint · Provider: BizflyCloud
• "hcm.ss.bfcplatform.vn" — Ho Chi Minh endpoint · Provider: BizflyCloud

and now, hold on, we're entering the ChinaMobile cinematic universe 💀 thirty of these, bestie, thirty:

• "eos-wuxi-1.cmecloud.cn" — The default endpoint - a good choice if you are unsure. East China (Suzhou) · Provider: ChinaMobile
• "eos-jinan-1.cmecloud.cn" — East China (Jinan) · Provider: ChinaMobile
• "eos-ningbo-1.cmecloud.cn" — East China (Hangzhou) · Provider: ChinaMobile
• "eos-shanghai-1.cmecloud.cn" — East China (Shanghai-1) · Provider: ChinaMobile
• "eos-zhengzhou-1.cmecloud.cn" — Central China (Zhengzhou) · Provider: ChinaMobile
• "eos-hunan-1.cmecloud.cn" — Central China (Changsha-1) · Provider: ChinaMobile
• "eos-zhuzhou-1.cmecloud.cn" — Central China (Changsha-2) · Provider: ChinaMobile
• "eos-guangzhou-1.cmecloud.cn" — South China (Guangzhou-2) · Provider: ChinaMobile
• "eos-dongguan-1.cmecloud.cn" — South China (Guangzhou-3) · Provider: ChinaMobile
• "eos-beijing-1.cmecloud.cn" — North China (Beijing-1) · Provider: ChinaMobile
• "eos-beijing-2.cmecloud.cn" — North China (Beijing-2) · Provider: ChinaMobile
• "eos-beijing-4.cmecloud.cn" — North China (Beijing-3) · Provider: ChinaMobile
• "eos-huhehaote-1.cmecloud.cn" — North China (Huhehaote) · Provider: ChinaMobile
• "eos-chengdu-1.cmecloud.cn" — Southwest China (Chengdu) · Provider: ChinaMobile
• "eos-chongqing-1.cmecloud.cn" — Southwest China (Chongqing) · Provider: ChinaMobile
• "eos-guiyang-1.cmecloud.cn" — Southwest China (Guiyang) · Provider: ChinaMobile
• "eos-xian-1.cmecloud.cn" — Nouthwest China (Xian) · Provider: ChinaMobile
• "eos-yunnan.cmecloud.cn" — Yunnan China (Kunming) · Provider: ChinaMobile
• "eos-yunnan-2.cmecloud.cn" — Yunnan China (Kunming-2) · Provider: ChinaMobile
• "eos-tianjin-1.cmecloud.cn" — Tianjin China (Tianjin) · Provider: ChinaMobile
• "eos-jilin-1.cmecloud.cn" — Jilin China (Changchun) · Provider: ChinaMobile
• "eos-hubei-1.cmecloud.cn" — Hubei China (Xiangyan) · Provider: ChinaMobile
• "eos-jiangxi-1.cmecloud.cn" — Jiangxi China (Nanchang) · Provider: ChinaMobile
• "eos-gansu-1.cmecloud.cn" — Gansu China (Lanzhou) · Provider: ChinaMobile
• "eos-shanxi-1.cmecloud.cn" — Shanxi China (Taiyuan) · Provider: ChinaMobile
• "eos-liaoning-1.cmecloud.cn" — Liaoning China (Shenyang) · Provider: ChinaMobile
• "eos-hebei-1.cmecloud.cn" — Hebei China (Shijiazhuang) · Provider: ChinaMobile
• "eos-fujian-1.cmecloud.cn" — Fujian China (Xiamen) · Provider: ChinaMobile
• "eos-guangxi-1.cmecloud.cn" — Guangxi China (Nanning) · Provider: ChinaMobile
• "eos-anhui-1.cmecloud.cn" — Anhui China (Huainan) · Provider: ChinaMobile

we made it through, icon behavior honestly 🫶 now Cubbit:

• "s3.cubbit.eu" — Cubbit DS3 Object Storage endpoint · Provider: Cubbit
• "s3.{tenant_name}.cubbit.eu" — Multi-tenant endpoint - replace {tenant_name} with your actual tenant name. Do not select this directly ⚠️ · Provider: Cubbit

bestie listen — that second one says do not select this directly. it's literally a fill-in-the-blank, not a vibe, okay? 🙈

and finally, DigitalOcean Spaces, the moment we've all been waiting for 🌊:

• "syd1.digitaloceanspaces.com" — DigitalOcean Spaces Sydney 1 · Provider: DigitalOcean
• "sfo3.digitaloceanspaces.com" — DigitalOcean Spaces San Francisco 3 · Provider: DigitalOcean
• "sfo2.digitaloceanspaces.com" — DigitalOcean Spaces San Francisco 2 · Provider: DigitalOcean
• "fra1.digitaloceanspaces.com" — DigitalOcean Spaces Frankfurt 1 · Provider: DigitalOcean
• "nyc3.digitaloceanspaces.com" — DigitalOcean Spaces New York 3 · Provider: DigitalOcean
• "ams3.digitaloceanspaces.com" — DigitalOcean Spaces Amsterdam 3 · Provider: DigitalOcean
• "sgp1.digitaloceanspaces.com" — DigitalOcean Spaces Singapore 1 · Provider: DigitalOcean
• "lon1.digitaloceanspaces.com" 🦋
  • DigitalOcean Spaces London 1 — she's cute, she's London, she slays
  • Provider: DigitalOcean
• "tor1.digitaloceanspaces.com" 🍁
  • DigitalOcean Spaces Toronto 1
  • Provider: DigitalOcean
• "blr1.digitaloceanspaces.com" ✨
  • DigitalOcean Spaces Bangalore 1
  • Provider: DigitalOcean
• "objects-us-east-1.dream.io" 💭
  • Dream Objects endpoint — lowkey a whole vibe
  • Provider: Dreamhost
• "au-east-1.object.fastlystorage.app" 🦋
  • AU East 1
  • Provider: Fastly
• "eu-central.object.fastlystorage.app" 🧚
  • EU Central
  • Provider: Fastly
• "eu-south-1.object.fastlystorage.app" 💖
  • EU South 1
  • Provider: Fastly
• "eu-west-1.object.fastlystorage.app" 🌸
  • EU West 1
  • Provider: Fastly
• "jp-central-1.object.fastlystorage.app" 🎀
  • JP Central 1
  • Provider: Fastly
• "uk-east-1.object.fastlystorage.app" 👑
  • UK East 1
  • Provider: Fastly
• "us-central-1.object.fastlystorage.app" ⭐
  • US Central 1
  • Provider: Fastly
• "us-east.object.fastlystorage.app" 🌈
  • US East
  • Provider: Fastly
• "us-east-1.object.fastlystorage.app" 💅
  • US East 1
  • Provider: Fastly
• "us-west.object.fastlystorage.app" 🦋
  • US West
  • Provider: Fastly
• "us-west-1.object.fastlystorage.app" ✨
  • US West 1
  • Provider: Fastly
• "s5lu.com" 🍓
  • Global FileLu S5 endpoint — the main character endpoint, no cap
  • Provider: FileLu
• "us.s5lu.com" 💜
  • North America (US-East) region endpoint
  • Provider: FileLu
• "eu.s5lu.com" 🌸
  • Europe (EU-Central) region endpoint
  • Provider: FileLu
• "ap.s5lu.com" 🎀
  • Asia Pacific (AP-Southeast) region endpoint
  • Provider: FileLu
• "me.s5lu.com" 🧚
  • Middle East (ME-Central) region endpoint
  • Provider: FileLu
• "https://storage.googleapis.com" 🔥
  • Google Cloud Storage endpoint — periodt, that's the GCS one
  • Provider: GCS
• "hel1.your-objectstorage.com" 🦋
  • Helsinki
  • Provider: Hetzner
• "fsn1.your-objectstorage.com" 🌈
  • Falkenstein
  • Provider: Hetzner
• "nbg1.your-objectstorage.com" ⭐
  • Nuremberg
  • Provider: Hetzner
• "obs.af-south-1.myhuaweicloud.com" 💅
  • AF-Johannesburg
  • Provider: HuaweiOBS
• "obs.ap-southeast-2.myhuaweicloud.com" 🎀
  • AP-Bangkok
  • Provider: HuaweiOBS
• "obs.ap-southeast-3.myhuaweicloud.com" ✨
  • AP-Singapore
  • Provider: HuaweiOBS
• "obs.cn-east-3.myhuaweicloud.com" 🍓
  • CN East-Shanghai1
  • Provider: HuaweiOBS
• "obs.cn-east-2.myhuaweicloud.com" 💜
  • CN East-Shanghai2
  • Provider: HuaweiOBS
• "obs.cn-north-1.myhuaweicloud.com" 🌸
  • CN North-Beijing1
  • Provider: HuaweiOBS
• "obs.cn-north-4.myhuaweicloud.com" 🦋
  • CN North-Beijing4
  • Provider: HuaweiOBS
• "obs.cn-south-1.myhuaweicloud.com" 🌈
  • CN South-Guangzhou
  • Provider: HuaweiOBS
• "obs.ap-southeast-1.myhuaweicloud.com" 👑
  • CN-Hong Kong
  • Provider: HuaweiOBS
• "obs.sa-argentina-1.myhuaweicloud.com" ⭐
  • LA-Buenos Aires1
  • Provider: HuaweiOBS
• "obs.sa-peru-1.myhuaweicloud.com" 🧚
  • LA-Lima1
  • Provider: HuaweiOBS
• "obs.na-mexico-1.myhuaweicloud.com" 🎀
  • LA-Mexico City1
  • Provider: HuaweiOBS
• "obs.sa-chile-1.myhuaweicloud.com" 💖
  • LA-Santiago2
  • Provider: HuaweiOBS
• "obs.sa-brazil-1.myhuaweicloud.com" ✨
  • LA-Sao Paulo1
  • Provider: HuaweiOBS
• "obs.ru-northwest-2.myhuaweicloud.com" 🔥
  • RU-Moscow2
  • Provider: HuaweiOBS
• "s3.us.cloud-object-storage.appdomain.cloud" 💅
  • US Cross Region Endpoint — okay IBM COS besties, we're going deep, buckle up
  • Provider: IBMCOS
• "s3.dal.us.cloud-object-storage.appdomain.cloud" 🦋
  • US Cross Region Dallas Endpoint
  • Provider: IBMCOS
• "s3.wdc.us.cloud-object-storage.appdomain.cloud" ✨
  • US Cross Region Washington DC Endpoint
  • Provider: IBMCOS
• "s3.sjc.us.cloud-object-storage.appdomain.cloud" 🌸
  • US Cross Region San Jose Endpoint
  • Provider: IBMCOS
• "s3.private.us.cloud-object-storage.appdomain.cloud" 🎀
  • US Cross Region Private Endpoint
  • Provider: IBMCOS
• "s3.private.dal.us.cloud-object-storage.appdomain.cloud" 🧚
  • US Cross Region Dallas Private Endpoint
  • Provider: IBMCOS
• "s3.private.wdc.us.cloud-object-storage.appdomain.cloud" 💜
  • US Cross Region Washington DC Private Endpoint
  • Provider: IBMCOS
• "s3.private.sjc.us.cloud-object-storage.appdomain.cloud" ⭐
  • US Cross Region San Jose Private Endpoint
  • Provider: IBMCOS
• "s3.us-east.cloud-object-storage.appdomain.cloud" 👑
  • US Region East Endpoint
  • Provider: IBMCOS
• "s3.private.us-east.cloud-object-storage.appdomain.cloud" 🌈
  • US Region East Private Endpoint
  • Provider: IBMCOS
• "s3.us-south.cloud-object-storage.appdomain.cloud" 🍓
  • US Region South Endpoint
  • Provider: IBMCOS
• "s3.private.us-south.cloud-object-storage.appdomain.cloud" 🔥
  • US Region South Private Endpoint
  • Provider: IBMCOS
• "s3.eu.cloud-object-storage.appdomain.cloud" 💖
  • EU Cross Region Endpoint
  • Provider: IBMCOS
• "s3.fra.eu.cloud-object-storage.appdomain.cloud" ✨
  • EU Cross Region Frankfurt Endpoint
  • Provider: IBMCOS
• "s3.mil.eu.cloud-object-storage.appdomain.cloud" 🦋
  • EU Cross Region Milan Endpoint
  • Provider: IBMCOS
• "s3.ams.eu.cloud-object-storage.appdomain.cloud" 🌸
  • EU Cross Region Amsterdam Endpoint
  • Provider: IBMCOS
• "s3.private.eu.cloud-object-storage.appdomain.cloud" 🎀
  • EU Cross Region Private Endpoint
  • Provider: IBMCOS
• "s3.private.fra.eu.cloud-object-storage.appdomain.cloud" 🧚
  • EU Cross Region Frankfurt Private Endpoint
  • Provider: IBMCOS
• "s3.private.mil.eu.cloud-object-storage.appdomain.cloud" 💜
  • EU Cross Region Milan Private Endpoint
  • Provider: IBMCOS
• "s3.private.ams.eu.cloud-object-storage.appdomain.cloud" ⭐
  • EU Cross Region Amsterdam Private Endpoint
  • Provider: IBMCOS
• "s3.eu-gb.cloud-object-storage.appdomain.cloud" 👑
  • Great Britain Endpoint
  • Provider: IBMCOS
• "s3.private.eu-gb.cloud-object-storage.appdomain.cloud" 🌈
  • Great Britain Private Endpoint
  • Provider: IBMCOS
• "s3.eu-de.cloud-object-storage.appdomain.cloud" 🍓
  • EU Region DE Endpoint
  • Provider: IBMCOS
• "s3.private.eu-de.cloud-object-storage.appdomain.cloud" 🔥
  • EU Region DE Private Endpoint
  • Provider: IBMCOS
• "s3.ap.cloud-object-storage.appdomain.cloud" 💖
  • APAC Cross Regional Endpoint
  • Provider: IBMCOS
• "s3.tok.ap.cloud-object-storage.appdomain.cloud" ✨
  • APAC Cross Regional Tokyo Endpoint
  • Provider: IBMCOS
• "s3.hkg.ap.cloud-object-storage.appdomain.cloud" 🦋
  • APAC Cross Regional Hong Kong Endpoint
  • Provider: IBMCOS
• "s3.seo.ap.cloud-object-storage.appdomain.cloud" 🌸
  • APAC Cross Regional Seoul Endpoint
  • Provider: IBMCOS
• "s3.private.ap.cloud-object-storage.appdomain.cloud" 🎀
  • APAC Cross Regional Private Endpoint
  • Provider: IBMCOS
• "s3.private.tok.ap.cloud-object-storage.appdomain.cloud" 🧚
  • APAC Cross Regional Tokyo Private Endpoint
  • Provider: IBMCOS
• "s3.private.hkg.ap.cloud-object-storage.appdomain.cloud" 💜
  • APAC Cross Regional Hong Kong Private Endpoint
  • Provider: IBMCOS
• "s3.private.seo.ap.cloud-object-storage.appdomain.cloud" ⭐
  • APAC Cross Regional Seoul Private Endpoint
  • Provider: IBMCOS
• "s3.jp-tok.cloud-object-storage.appdomain.cloud" 👑
  • APAC Region Japan Endpoint
  • Provider: IBMCOS
• "s3.private.jp-tok.cloud-object-storage.appdomain.cloud" 🌈
  • APAC Region Japan Private Endpoint
  • Provider: IBMCOS
• "s3.au-syd.cloud-object-storage.appdomain.cloud" 🍓
  • APAC Region Australia Endpoint
  • Provider: IBMCOS
• "s3.private.au-syd.cloud-object-storage.appdomain.cloud" 🔥
  • APAC Region Australia Private Endpoint
  • Provider: IBMCOS
• "s3.ams03.cloud-object-storage.appdomain.cloud" 💖
  • Amsterdam Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.ams03.cloud-object-storage.appdomain.cloud" ✨
  • Amsterdam Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.che01.cloud-object-storage.appdomain.cloud" 🦋
  • Chennai Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.che01.cloud-object-storage.appdomain.cloud" 🌸
  • Chennai Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.mel01.cloud-object-storage.appdomain.cloud" 🎀
  • Melbourne Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.mel01.cloud-object-storage.appdomain.cloud" 🧚
  • Melbourne Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.osl01.cloud-object-storage.appdomain.cloud" 💜
  • Oslo Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.osl01.cloud-object-storage.appdomain.cloud" ⭐
  • Oslo Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.tor01.cloud-object-storage.appdomain.cloud" 👑
  • Toronto Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.tor01.cloud-object-storage.appdomain.cloud" 🌈
  • Toronto Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.seo01.cloud-object-storage.appdomain.cloud" 🍓
  • Seoul Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.seo01.cloud-object-storage.appdomain.cloud" 🔥
  • Seoul Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.mon01.cloud-object-storage.appdomain.cloud" 💖
  • Montreal Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.mon01.cloud-object-storage.appdomain.cloud" ✨
  • Montreal Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.mex01.cloud-object-storage.appdomain.cloud" 💖
  • Mexico Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.mex01.cloud-object-storage.appdomain.cloud" 💖
  • Mexico Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.sjc04.cloud-object-storage.appdomain.cloud" 💖
  • San Jose Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.sjc04.cloud-object-storage.appdomain.cloud" 💖
  • San Jose Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.mil01.cloud-object-storage.appdomain.cloud" 💖
  • Milan Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.mil01.cloud-object-storage.appdomain.cloud" 💖
  • Milan Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.hkg02.cloud-object-storage.appdomain.cloud" 💖
  • Hong Kong Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.hkg02.cloud-object-storage.appdomain.cloud" 💖
  • Hong Kong Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.par01.cloud-object-storage.appdomain.cloud" 💖
  • Paris Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.par01.cloud-object-storage.appdomain.cloud" 💖
  • Paris Single Site Private Endpoint
  • Provider: IBMCOS
• "s3.sng01.cloud-object-storage.appdomain.cloud" 💖
  • Singapore Single Site Endpoint
  • Provider: IBMCOS
• "s3.private.sng01.cloud-object-storage.appdomain.cloud" 💖
  • Singapore Single Site Private Endpoint
  • Provider: IBMCOS
• "eu-central-2.storage.impossibleapi.net" 🔥
  • Frankfurt, Germany
  • Provider: ImpossibleCloud
• "eu-west-1.storage.impossibleapi.net" 🔥
  • Amsterdam, Netherlands
  • Provider: ImpossibleCloud
• "eu-west-2.storage.impossibleapi.net" 🔥
  • London, UK
  • Provider: ImpossibleCloud
• "eu-west-3.storage.impossibleapi.net" 🔥
  • Paris, France
  • Provider: ImpossibleCloud
• "eu-east-1.storage.impossibleapi.net" 🔥
  • Poznań, Poland
  • Provider: ImpossibleCloud
• "eu-north-1.storage.impossibleapi.net" 🔥
  • Copenhagen, Denmark
  • Provider: ImpossibleCloud
• "us-east-1.storage.impossibleapi.net" 🔥
  • New York, USA
  • Provider: ImpossibleCloud
• "de-fra.i3storage.com" 🍓
  • Frankfurt, Germany
  • Provider: Intercolo
• "s3.eu-central-1.ionoscloud.com" 👑
  • Frankfurt, Germany
  • Provider: IONOS
• "s3.eu-central-2.ionoscloud.com" 👑
  • Berlin, Germany
  • Provider: IONOS
• "s3.eu-central-3.ionoscloud.com" 👑
  • Berlin, Germany
  • Provider: IONOS
• "s3.eu-central-4.ionoscloud.com" 👑
  • Frankfurt, Germany
  • Provider: IONOS
• "s3.eu-south-2.ionoscloud.com" 👑
  • Logrono, Spain
  • Provider: IONOS
• "s3.us-central-1.ionoscloud.com" 👑
  • Lenexa, USA
  • Provider: IONOS
• "s3.leviia.com" 🎀
  • The default endpoint
  • Leviia
  • Provider: Leviia
• "storage.iran.liara.space" 🦋
  • The default endpoint
  • Iran
  • Provider: Liara
• "nl-ams-1.linodeobjects.com" ✨
  • Amsterdam, NL (nl-ams-1)
  • Provider: Linode
• "us-southeast-1.linodeobjects.com" ✨
  • Atlanta, GA, US (us-southeast-1)
  • Provider: Linode
• "in-maa-1.linodeobjects.com" ✨
  • Chennai, IN (in-maa-1)
  • Provider: Linode
• "us-ord-1.linodeobjects.com" ✨
  • Chicago, IL, US (us-ord-1)
  • Provider: Linode
• "eu-central-1.linodeobjects.com" ✨
  • Frankfurt, DE (eu-central-1)
  • Provider: Linode
• "id-cgk-1.linodeobjects.com" ✨
  • Jakarta, ID (id-cgk-1)
  • Provider: Linode
• "gb-lon-1.linodeobjects.com" ✨
  • London 2, UK (gb-lon-1)
  • Provider: Linode
• "us-lax-1.linodeobjects.com" ✨
  • Los Angeles, CA, US (us-lax-1)
  • Provider: Linode
• "es-mad-1.linodeobjects.com" ✨
  • Madrid, ES (es-mad-1)
  • Provider: Linode
• "us-mia-1.linodeobjects.com" ✨
  • Miami, FL, US (us-mia-1)
  • Provider: Linode
• "it-mil-1.linodeobjects.com" ✨
  • Milan, IT (it-mil-1)
  • Provider: Linode
• "us-east-1.linodeobjects.com" ✨
  • Newark, NJ, US (us-east-1)
  • Provider: Linode
• "jp-osa-1.linodeobjects.com" ✨
  • Osaka, JP (jp-osa-1)
  • Provider: Linode
• "fr-par-1.linodeobjects.com" ✨
  • Paris, FR (fr-par-1)
  • Provider: Linode
• "br-gru-1.linodeobjects.com" ✨
  • Sao Paulo, BR (br-gru-1)
  • Provider: Linode
• "us-sea-1.linodeobjects.com" ✨
  • Seattle, WA, US (us-sea-1)
  • Provider: Linode
• "ap-south-1.linodeobjects.com" ✨
  • Singapore, SG (ap-south-1)
  • Provider: Linode
• "sg-sin-1.linodeobjects.com" ✨
  • Singapore 2, SG (sg-sin-1)
  • Provider: Linode
• "se-sto-1.linodeobjects.com" ✨
  • Stockholm, SE (se-sto-1)
  • Provider: Linode
• "jp-tyo-1.linodeobjects.com" ✨
  • Tokyo 3, JP (jp-tyo-1)
  • Provider: Linode
• "us-iad-10.linodeobjects.com" ✨
  • Washington, DC, US (us-iad-10)
  • Provider: Linode
• "s3.us-west-1.{account_name}.lyve.seagate.com" 🌊
  • US West 1 - California
  • Provider: LyveCloud
• "s3.eu-west-1.{account_name}.lyve.seagate.com" 🌊
  • EU West 1 - Ireland
  • Provider: LyveCloud
• "br-se1.magaluobjects.com" 💛
  • São Paulo, SP (BR), br-se1
  • Provider: Magalu
• "br-ne1.magaluobjects.com" 💛
  • Fortaleza, CE (BR), br-ne1
  • Provider: Magalu
• "s3.eu-luxembourg-1.megas4.com" 🌈
  • Mega S4 Luxembourg 1
  • Provider: Mega
• "s3.eu-luxembourg-2.megas4.com" 🌈
  • Mega S4 Luxembourg 2
  • Provider: Mega
• "s3.eu-amsterdam-1.megas4.com" 🌈
  • Mega S4 Amsterdam 1
  • Provider: Mega
• "s3.eu-amsterdam-2.megas4.com" 🌈
  • Mega S4 Amsterdam 2
  • Provider: Mega
• "s3.eu-paris-1.megas4.com" 🌈
  • Mega S4 Paris 1
  • Provider: Mega
• "s3.eu-paris-2.megas4.com" 🌈
  • Mega S4 Paris 2
  • Provider: Mega
• "s3.eu-barcelona-1.megas4.com" 🌈
  • Mega S4 Barcelona 1
  • Provider: Mega
• "s3.eu-barcelona-2.megas4.com" 🌈
  • Mega S4 Barcelona 2
  • Provider: Mega
• "s3.ca-montreal-1.megas4.com" 🌈
  • Mega S4 Montreal 1
  • Provider: Mega
• "s3.ca-montreal-2.megas4.com" 🌈
  • Mega S4 Montreal 2
  • Provider: Mega
• "s3.ca-vancouver-1.megas4.com" 🌈
  • Mega S4 Vancouver 1
  • Provider: Mega
• "s3.ca-vancouver-2.megas4.com" 🌈
  • Mega S4 Vancouver 2
  • Provider: Mega
• "s3.ap-tokyo-1.megas4.com" 🌈
  • Mega S4 Tokyo 1
  • Provider: Mega
• "s3.ap-tokyo-2.megas4.com" 🌈
  • Mega S4 Tokyo 2
  • Provider: Mega
• "oos.eu-west-2.outscale.com" 🍀
  • Outscale EU West 2 (Paris)
  • Provider: Outscale
• "oos.us-east-2.outscale.com" 🍀
  • Outscale US east 2 (New Jersey)
  • Provider: Outscale
• "oos.us-west-1.outscale.com" 🍀
  • Outscale EU West 1 (California)
  • Provider: Outscale
• "oos.cloudgouv-eu-west-1.outscale.com" 🍀
  • Outscale SecNumCloud (Paris)
  • Provider: Outscale
• "oos.ap-northeast-1.outscale.com" 🍀
  • Outscale AP Northeast 1 (Japan)
  • Provider: Outscale
• "s3.gra.io.cloud.ovh.net" 💙
  • OVHcloud Gravelines, France
  • Provider: OVHcloud
• "s3.rbx.io.cloud.ovh.net" 💙
  • OVHcloud Roubaix, France
  • Provider: OVHcloud
• "s3.sbg.io.cloud.ovh.net" 💙
  • OVHcloud Strasbourg, France
  • Provider: OVHcloud
• "s3.eu-west-par.io.cloud.ovh.net" 💙
  • OVHcloud Paris, France (3AZ)
  • Provider: OVHcloud
• "s3.de.io.cloud.ovh.net" 💙
  • OVHcloud Frankfurt, Germany
  • Provider: OVHcloud
• "s3.uk.io.cloud.ovh.net" 💙
  • OVHcloud London, United Kingdom
  • Provider: OVHcloud
• "s3.waw.io.cloud.ovh.net" 💙
  • OVHcloud Warsaw, Poland
  • Provider: OVHcloud
• "s3.bhs.io.cloud.ovh.net" 💙
  • OVHcloud Beauharnois, Canada
  • Provider: OVHcloud
• "s3.ca-east-tor.io.cloud.ovh.net" 💙
  • OVHcloud Toronto, Canada
  • Provider: OVHcloud
• "s3.sgp.io.cloud.ovh.net" 💙
  • OVHcloud Singapore
  • Provider: OVHcloud
• "s3.ap-southeast-syd.io.cloud.ovh.net" 💙
  • OVHcloud Sydney, Australia
  • Provider: OVHcloud
• "s3.ap-south-mum.io.cloud.ovh.net" 💙
  • OVHcloud Mumbai, India
  • Provider: OVHcloud
• "s3.us-east-va.io.cloud.ovh.us" 💙
  • OVHcloud Vint Hill, Virginia, USA
  • Provider: OVHcloud
• "s3.us-west-or.io.cloud.ovh.us" 💙
  • OVHcloud Hillsboro, Oregon, USA
  • Provider: OVHcloud
• "s3.rbx-archive.io.cloud.ovh.net" 💙
  • OVHcloud Roubaix, France (Cold Archive)
  • Provider: OVHcloud
• "s3.petabox.io" 🫶
  • US East (N. Virginia)
  • Provider: Petabox
• "s3.us-east-1.petabox.io" 🫶
  • US East (N. Virginia)
  • Provider: Petabox
• "s3.eu-central-1.petabox.io" 🫶
  • Europe (Frankfurt)
  • Provider: Petabox
• "s3.ap-southeast-1.petabox.io" 🫶
  • Asia Pacific (Singapore)
  • Provider: Petabox
• "s3.me-south-1.petabox.io" 🫶
  • Middle East (Bahrain)
  • Provider: Petabox
• "s3.sa-east-1.petabox.io" 🫶
  • South America (São Paulo)
  • Provider: Petabox
• "s3-cn-east-1.qiniucs.com" ⭐
  • East China Endpoint 1
  • Provider: Qiniu
• "s3-cn-east-2.qiniucs.com" ⭐
  • East China Endpoint 2
  • Provider: Qiniu
• "s3-cn-north-1.qiniucs.com" ⭐
  • North China Endpoint 1
  • Provider: Qiniu
• "s3-cn-south-1.qiniucs.com" ⭐
  • South China Endpoint 1
  • Provider: Qiniu
• "s3-us-north-1.qiniucs.com" ⭐
  • North America Endpoint 1
  • Provider: Qiniu
• "s3-ap-southeast-1.qiniucs.com" ✨
• "s3-ap-southeast-1.qiniucs.com"
  • Southeast Asia Endpoint 1 🌏
  • Provider: Qiniu
• "s3.us-east-1.rabata.io"
  • US East (N. Virginia) 🗽
  • Provider: Rabata
• "s3.eu-west-1.rabata.io"
  • EU West (Ireland) 🍀
  • Provider: Rabata
• "s3.eu-west-2.rabata.io"
  • EU West (London) 🎡
  • Provider: Rabata
• "s3.rackcorp.com"
  • Global (AnyCast) Endpoint
  • Provider: RackCorp
• "au.s3.rackcorp.com"
  • Australia (Anycast) Endpoint 🦘
  • Provider: RackCorp
• "au-nsw.s3.rackcorp.com"
  • Sydney (Australia) Endpoint
  • Provider: RackCorp
• "au-qld.s3.rackcorp.com"
  • Brisbane (Australia) Endpoint
  • Provider: RackCorp
• "au-vic.s3.rackcorp.com"
  • Melbourne (Australia) Endpoint
  • Provider: RackCorp
• "au-wa.s3.rackcorp.com"
  • Perth (Australia) Endpoint
  • Provider: RackCorp
• "ph.s3.rackcorp.com"
  • Manila (Philippines) Endpoint
  • Provider: RackCorp
• "th.s3.rackcorp.com"
  • Bangkok (Thailand) Endpoint 🇹🇭
  • Provider: RackCorp
• "hk.s3.rackcorp.com"
  • HK (Hong Kong) Endpoint
  • Provider: RackCorp
• "mn.s3.rackcorp.com"
  • Ulaanbaatar (Mongolia) Endpoint
  • Provider: RackCorp
• "kg.s3.rackcorp.com"
  • Bishkek (Kyrgyzstan) Endpoint
  • Provider: RackCorp
• "id.s3.rackcorp.com"
  • Jakarta (Indonesia) Endpoint
  • Provider: RackCorp
• "jp.s3.rackcorp.com"
  • Tokyo (Japan) Endpoint 🗼
  • Provider: RackCorp
• "sg.s3.rackcorp.com"
  • SG (Singapore) Endpoint
  • Provider: RackCorp
• "de.s3.rackcorp.com"
  • Frankfurt (Germany) Endpoint 🥨
  • Provider: RackCorp
• "us.s3.rackcorp.com"
  • USA (AnyCast) Endpoint
  • Provider: RackCorp
• "us-east-1.s3.rackcorp.com"
  • New York (USA) Endpoint 🗽
  • Provider: RackCorp
• "us-west-1.s3.rackcorp.com"
  • Freemont (USA) Endpoint
  • Provider: RackCorp
• "nz.s3.rackcorp.com"
  • Auckland (New Zealand) Endpoint 🥝
  • Provider: RackCorp
• "s3.nl-ams.scw.cloud"
  • Amsterdam Endpoint 🚲
  • Provider: Scaleway
• "s3.fr-par.scw.cloud"
  • Paris Endpoint 🥐
  • Provider: Scaleway
• "s3.pl-waw.scw.cloud"
  • Warsaw Endpoint
  • Provider: Scaleway
• "localhost:8333"
  • SeaweedFS S3 localhost 🌿
  • Provider: SeaweedFS
• "s3.ru-1.storage.selcloud.ru"
  • St. Petersburg
  • Provider: Selectel
• "s3.ru-3.storage.selcloud.ru"
  • St. Petersburg
  • Provider: Selectel
• "s3.ru-7.storage.selcloud.ru"
  • Moscow
  • Provider: Selectel,Servercore
• "s3.gis-1.storage.selcloud.ru"
  • Moscow
  • Provider: Selectel,Servercore
• "s3.kz-1.storage.selcloud.ru"
  • Kazakhstan
  • Provider: Selectel
• "s3.uz-2.storage.selcloud.ru"
  • Uzbekistan
  • Provider: Selectel
• "s3.ru-1.storage.selcloud.ru"
  • Saint Petersburg
  • Provider: Servercore
• "s3.uz-2.srvstorage.uz"
  • Tashkent, Uzbekistan
  • Provider: Servercore
• "s3.kz-1.srvstorage.kz"
  • Almaty, Kazakhstan
  • Provider: Servercore
• "gateway.storjshare.io"
  • Global Hosted Gateway 🛰️
  • Provider: Storj
• "eu-001.s3.synologyc2.net"
  • EU Endpoint 1
  • Provider: Synology
• "eu-002.s3.synologyc2.net"
  • EU Endpoint 2
  • Provider: Synology
• "us-001.s3.synologyc2.net"
  • US Endpoint 1
  • Provider: Synology
• "us-002.s3.synologyc2.net"
  • US Endpoint 2
  • Provider: Synology
• "tw-001.s3.synologyc2.net"
  • TW Endpoint 1
  • Provider: Synology
• "cos.ap-beijing.myqcloud.com"
  • Beijing Region
  • Provider: TencentCOS
• "cos.ap-nanjing.myqcloud.com"
  • Nanjing Region
  • Provider: TencentCOS
• "cos.ap-shanghai.myqcloud.com"
  • Shanghai Region
  • Provider: TencentCOS
• "cos.ap-guangzhou.myqcloud.com"
  • Guangzhou Region
  • Provider: TencentCOS
• "cos.ap-chengdu.myqcloud.com"
  • Chengdu Region
  • Provider: TencentCOS
• "cos.ap-chongqing.myqcloud.com"
  • Chongqing Region
  • Provider: TencentCOS
• "cos.ap-hongkong.myqcloud.com"
  • Hong Kong (China) Region
  • Provider: TencentCOS
• "cos.ap-singapore.myqcloud.com"
  • Singapore Region
  • Provider: TencentCOS
• "cos.ap-mumbai.myqcloud.com"
  • Mumbai Region
  • Provider: TencentCOS
• "cos.ap-seoul.myqcloud.com"
  • Seoul Region
  • Provider: TencentCOS
• "cos.ap-bangkok.myqcloud.com"
  • Bangkok Region
  • Provider: TencentCOS
• "cos.ap-tokyo.myqcloud.com"
  • Tokyo Region
  • Provider: TencentCOS
• "cos.na-siliconvalley.myqcloud.com"
  • Silicon Valley Region
  • Provider: TencentCOS
• "cos.na-ashburn.myqcloud.com"
  • Virginia Region
  • Provider: TencentCOS
• "cos.na-toronto.myqcloud.com"
  • Toronto Region
  • Provider: TencentCOS
• "cos.eu-frankfurt.myqcloud.com"
  • Frankfurt Region
  • Provider: TencentCOS
• "cos.eu-moscow.myqcloud.com"
  • Moscow Region
  • Provider: TencentCOS
• "cos.accelerate.myqcloud.com"
  • Use Tencent COS Accelerate Endpoint ⚡
  • Provider: TencentCOS
• "s3-cn-bj.ufileos.com"
  • North China (Beijing 2)
  • Provider: US3
• "s3-cn-wlcb.ufileos.com"
  • North China (Ulanqab)
  • Provider: US3
• "s3-cn-sh2.ufileos.com"
  • Shanghai
  • Provider: US3
• "s3-cn-gd.ufileos.com"
  • South China (Guangzhou)
  • Provider: US3
• "s3-hk.ufileos.com"
  • Hongkong
  • Provider: US3
• "s3-us-ca.ufileos.com"
  • United States (Los Angeles)
  • Provider: US3
• "s3-sg.ufileos.com"
  • Singapore
  • Provider: US3
• "s3-idn-jakarta.ufileos.com"
  • Indonesia (Jakarta)
  • Provider: US3
• "s3-tw-tp.ufileos.com"
  • Taiwan (Taipei)
  • Provider: US3
• "s3-afr-nigeria.ufileos.com"
  • Nigeria (Lagos)
  • Provider: US3
• "s3-bra-saopaulo.ufileos.com"
  • Brazil (São Paulo)
  • Provider: US3
• "s3-uae-dubai.ufileos.com"
  • United Arab Emirates (Dubai)
  • Provider: US3
• "s3-ge-fra.ufileos.com"
  • Germany (Frankfurt)
  • Provider: US3
• "s3-vn-sng.ufileos.com"
  • Vietnam (Ho Chi Minh City)
  • Provider: US3
• "s3-us-ws.ufileos.com"
  • United States (Washington)
  • Provider: US3
• "s3-ind-mumbai.ufileos.com"
  • India (Mumbai)
  • Provider: US3
• "s3-kr-seoul.ufileos.com"
  • Seoul (South Korea)
  • Provider: US3
• "s3-jpn-tky.ufileos.com"
  • Japan (Tokyo)
  • Provider: US3
• "s3-th-bkk.ufileos.com"
  • Bangkok (Thailand)
  • Provider: US3
• "s3-uk-london.ufileos.com"
  • United Kingdom (London)
  • Provider: US3
• "s3-rus-mosc.ufileos.com"
  • Russia (Moscow)
  • Provider: US3
• "s3-cn-guiyang1.ufileos.com"
  • Guiyang 1
  • Provider: US3
• "s3-pk-khi.ufileos.com"
  • Pakistan
  • Provider: US3
• "s3.wasabisys.com"
  • Wasabi US East 1 (N. Virginia)
  • Provider: Wasabi
• "s3.us-east-2.wasabisys.com"
  • Wasabi US East 2 (N. Virginia)
  • Provider: Wasabi
• "s3.us-central-1.wasabisys.com"
  • Wasabi US Central 1 (Texas)
  • Provider: Wasabi
• "s3.us-west-1.wasabisys.com"
  • Wasabi US West 1 (Oregon)
  • Provider: Wasabi
• "s3.ca-central-1.wasabisys.com"
  • Wasabi CA Central 1 (Toronto)
  • Provider: Wasabi
• "s3.eu-central-1.wasabisys.com"
  • Wasabi EU Central 1 (Amsterdam)
  • Provider: Wasabi
• "s3.eu-central-2.wasabisys.com"
  • Wasabi EU Central 2 (Frankfurt)
  • Provider: Wasabi
• "s3.eu-west-1.wasabisys.com"
  • Wasabi EU West 1 (London)
  • Provider: Wasabi
• "s3.eu-west-2.wasabisys.com"
  • Wasabi EU West 2 (Paris)
  • Provider: Wasabi
• "s3.eu-south-1.wasabisys.com"
  • Wasabi EU South 1 (Milan)
  • Provider: Wasabi
• "s3.ap-northeast-1.wasabisys.com"
  • Wasabi AP Northeast 1 (Tokyo) endpoint
  • Provider: Wasabi
• "s3.ap-northeast-2.wasabisys.com"
  • Wasabi AP Northeast 2 (Osaka) endpoint
  • Provider: Wasabi
• "s3.ap-southeast-1.wasabisys.com"
  • Wasabi AP Southeast 1 (Singapore)
  • Provider: Wasabi
• "s3.ap-southeast-2.wasabisys.com"
  • Wasabi AP Southeast 2 (Sydney)
  • Provider: Wasabi
• "idr01.zata.ai"
  • South Asia Endpoint
  • Provider: Zata
• "fra1.s3.zeroservices.eu"
  • Frankfurt 1
  • Provider: ZeroServices
• "fra.s3.zeroservices.eu"
  • Frankfurt 2
  • Provider: ZeroServices
• "eyl1.s3.zeroservices.eu"
  • Eyl 1
  • Provider: ZeroServices

---

💅 --s3-location-constraint

okay bestie, this one is literally the location constraint — and it must be set to match the Region. That's not a suggestion, that's the whole vibe.

Leave it blank if you're not sure 🫶. Heads up tho: it's only used when creating buckets — so if you're just vibing with existing buckets, this one's not your problem.

Properties, because we stay informed:

• Config: location_constraint
• Env Var: RCLONE_S3_LOCATION_CONSTRAINT
• Provider: AWS,ArvanCloud,Ceph,ChinaMobile,DigitalOcean,Dreamhost,Exaba,GCS,HCP,Hetzner,IBMCOS,ImpossibleCloud,LyveCloud,Minio,Netease,Qiniu,Rabata,RackCorp,Scality,SeaweedFS,Synology,Wasabi,Zata,ZeroServices,Other
• Type: string
• Required: false
• Examples:
  • ""

fr fr, if the location constraint doesn't match your Region, that's not a slay, that's a bucket-creation situation you do not want. Match it or leave it empty. 💀

okay bestie, buckle up — the region list is long and we are finishing it right here, every single one, no skips 💅

• "us-east-2" ✨
  • US East (Ohio) Region
  • provider: AWS
• "us-west-1" 🌸
  • US West (Northern California) Region
  • provider: AWS
• "us-west-2" 🦋
  • US West (Oregon) Region
  • provider: AWS
• "ca-central-1" 🍓
  • Canada (Central) Region
  • provider: AWS
• "eu-west-1" 💜
  • EU (Ireland) Region
  • provider: AWS
• "eu-west-2" ✨
  • EU (London) Region
  • provider: AWS
• "eu-west-3" 🌈
  • EU (Paris) Region
  • provider: AWS
• "eu-north-1" 🌸
  • EU (Stockholm) Region
  • provider: AWS
• "eu-south-1" 🎀
  • EU (Milan) Region
  • provider: AWS
• "EU" 💖
  • EU Region
  • provider: AWS
• "ap-southeast-1" 🦋
  • Asia Pacific (Singapore) Region
  • provider: AWS
• "ap-southeast-2" ⭐
  • Asia Pacific (Sydney) Region
  • provider: AWS
• "ap-northeast-1" 👑
  • Asia Pacific (Tokyo) Region
  • provider: AWS
• "ap-northeast-2" 🌸
  • Asia Pacific (Seoul) Region
  • provider: AWS
• "ap-northeast-3" 🧚
  • Asia Pacific (Osaka-Local) Region
  • provider: AWS
• "ap-south-1" 💜
  • Asia Pacific (Mumbai) Region
  • provider: AWS
• "ap-east-1" ✨
  • Asia Pacific (Hong Kong) Region
  • provider: AWS
• "sa-east-1" 🍓
  • South America (Sao Paulo) Region
  • provider: AWS
• "il-central-1" 🌈
  • Israel (Tel Aviv) Region
  • provider: AWS
• "me-south-1" 🦋
  • Middle East (Bahrain) Region
  • provider: AWS
• "af-south-1" 🌸
  • Africa (Cape Town) Region
  • provider: AWS
• "cn-north-1" 🎀
  • China (Beijing) Region
  • provider: AWS
• "cn-northwest-1" 💖
  • China (Ningxia) Region
  • provider: AWS
• "us-gov-east-1" ⭐
  • AWS GovCloud (US-East) Region
  • provider: AWS
• "us-gov-west-1" 👑
  • AWS GovCloud (US) Region
  • provider: AWS

---

• "ir-thr-at1" 🌺
  • Tehran Iran (Simin)
  • provider: ArvanCloud
• "ir-tbz-sh1" 💙
  • Tabriz Iran (Shahriar)
  • provider: ArvanCloud

---

• "wuxi1" 🌸
  • East China (Suzhou)
  • provider: ChinaMobile
• "jinan1" ✨
  • East China (Jinan)
  • provider: ChinaMobile
• "ningbo1" 🦋
  • East China (Hangzhou)
  • provider: ChinaMobile
• "shanghai1" 🎀
  • East China (Shanghai-1)
  • provider: ChinaMobile
• "zhengzhou1" 💜
  • Central China (Zhengzhou)
  • provider: ChinaMobile
• "hunan1" 🍓
  • Central China (Changsha-1)
  • provider: ChinaMobile
• "zhuzhou1" 🌈
  • Central China (Changsha-2)
  • provider: ChinaMobile
• "guangzhou1" 💖
  • South China (Guangzhou-2)
  • provider: ChinaMobile
• "dongguan1" ⭐
  • South China (Guangzhou-3)
  • provider: ChinaMobile
• "beijing1" 👑
  • North China (Beijing-1)
  • provider: ChinaMobile
• "beijing2" 🌸
  • North China (Beijing-2)
  • provider: ChinaMobile
• "beijing4" 🧚
  • North China (Beijing-3)
  • provider: ChinaMobile
• "huhehaote1" 🦋
  • North China (Huhehaote)
  • provider: ChinaMobile
• "chengdu1" ✨
  • Southwest China (Chengdu)
  • provider: ChinaMobile
• "chongqing1" 💜
  • Southwest China (Chongqing)
  • provider: ChinaMobile
• "guiyang1" 🎀
  • Southwest China (Guiyang)
  • provider: ChinaMobile
• "xian1" 🌈
  • Northwest China (Xian)
  • provider: ChinaMobile
• "yunnan" 🌸
  • Yunnan China (Kunming)
  • provider: ChinaMobile
• "yunnan2" 🍓
  • Yunnan China (Kunming-2)
  • provider: ChinaMobile
• "tianjin1" ⭐
  • Tianjin China (Tianjin)
  • provider: ChinaMobile
• "jilin1" 💖
  • Jilin China (Changchun)
  • provider: ChinaMobile
• "hubei1" 🦋
  • Hubei China (Xiangyan)
  • provider: ChinaMobile
• "jiangxi1" 👑
  • Jiangxi China (Nanchang)
  • provider: ChinaMobile
• "gansu1" ✨
  • Gansu China (Lanzhou)
  • provider: ChinaMobile
• "shanxi1" 🎀
  • Shanxi China (Taiyuan)
  • provider: ChinaMobile
• "liaoning1" 🌸
  • Liaoning China (Shenyang)
  • provider: ChinaMobile
• "hebei1" 🧚
  • Hebei China (Shijiazhuang)
  • provider: ChinaMobile
• "fujian1" 💜
  • Fujian China (Xiamen)
  • provider: ChinaMobile
• "guangxi1" 🌈
  • Guangxi China (Nanning)
  • provider: ChinaMobile
• "anhui1" 🍓
  • Anhui China (Huainan)
  • provider: ChinaMobile

---

• "us-standard" ✨
  • US Cross Region Standard
  • provider: IBMCOS
• "us-vault" 🔒
  • US Cross Region Vault
  • provider: IBMCOS
• "us-cold" 🧊
  • US Cross Region Cold
  • provider: IBMCOS
• "us-flex" 🦋
  • US Cross Region Flex
  • provider: IBMCOS
• "us-east-standard" 💖
  • US East Region Standard
  • provider: IBMCOS
• "us-east-vault" 🔒
  • US East Region Vault
  • provider: IBMCOS
• "us-east-cold" 🧊
  • US East Region Cold
  • provider: IBMCOS
• "us-east-flex" 🌸
  • US East Region Flex
  • provider: IBMCOS
• "us-south-standard" ⭐
  • US South Region Standard
  • provider: IBMCOS
• "us-south-vault" 🔒
  • US South Region Vault
  • provider: IBMCOS
• "us-south-cold" 🧊
  • US South Region Cold
  • provider: IBMCOS
• "us-south-flex" 🎀
  • US South Region Flex
  • provider: IBMCOS
• "eu-standard" 💜
  • EU Cross Region Standard
  • provider: IBMCOS
• "eu-vault" 🔒
  • EU Cross Region Vault
  • provider: IBMCOS
• "eu-cold" 🧊
  • EU Cross Region Cold
  • provider: IBMCOS
• "eu-flex" 🌈
  • EU Cross Region Flex
  • provider: IBMCOS
• "eu-gb-standard" 👑
  • Great Britain Standard
  • provider: IBMCOS
• "eu-gb-vault" 🔒
  • Great Britain Vault
  • provider: IBMCOS
• "eu-gb-cold" 🧊
  • Great Britain Cold
  • provider: IBMCOS
• "eu-gb-flex" 🦋
  • Great Britain Flex
  • provider: IBMCOS
• "ap-standard" ✨
  • APAC Standard
  • provider: IBMCOS
• "ap-vault" 🔒
  • APAC Vault
  • provider: IBMCOS
• "ap-cold" 🧊
  • APAC Cold
  • provider: IBMCOS
• "ap-flex" 🌸
  • APAC Flex
  • provider: IBMCOS
• "mel01-standard" 🍓
  • Melbourne Standard
  • provider: IBMCOS
• "mel01-vault" 🔒
  • Melbourne Vault
  • provider: IBMCOS
• "mel01-cold" 🧊
  • Melbourne Cold
  • provider: IBMCOS
• "mel01-flex" 🎀
  • Melbourne Flex
  • provider: IBMCOS
• "tor01-standard" 💖
  • Toronto Standard
  • provider: IBMCOS
• "tor01-vault" 🔒
  • Toronto Vault
  • provider: IBMCOS
• "tor01-cold" 🧊
  • Toronto Cold
  • provider: IBMCOS
• "tor01-flex" 🌈
  • Toronto Flex
  • provider: IBMCOS

---

• "cn-east-1" ✨
  • East China Region 1
  • provider: Qiniu
• "cn-east-2" 🦋
  • East China Region 2
  • provider: Qiniu
• "cn-north-1" 🌸
  • North China Region 1
  • provider: Qiniu
• "cn-south-1" 💜
  • South China Region 1
  • provider: Qiniu
• "us-north-1" ⭐
  • North America Region 1
  • provider: Qiniu
• "ap-southeast-1" 🎀
  • Southeast Asia Region 1
  • provider: Qiniu
• "ap-northeast-1" 👑
  • Northeast Asia Region 1
  • provider: Qiniu

---

• "us-east-1" 💖
  • US East (N. Virginia)
  • provider: Rabata
• "eu-west-1" 🌈
  • EU (Ireland)
  • provider: Rabata
• "eu-west-2" 🍓
  • EU (London)
  • provider: Rabata

---

• "global" 🌍
  • Global CDN Region
  • provider: RackCorp
• "au" 🦘
  • Australia (All locations)
  • provider: RackCorp
• "au-nsw" ✨
  • NSW (Australia) Region
  • provider: RackCorp
• "au-qld" 🌸
  • QLD (Australia) Region
  • provider: RackCorp
• "au-vic" 🎀
  • VIC (Australia) Region
  • provider: RackCorp
• "au-wa" 💜
  • Perth (Australia) Region
  • provider: RackCorp
• "ph" 🦋
  • Manila (Philippines) Region
  • provider: RackCorp
• "th" ⭐
  • Bangkok (Thailand) Region
  • provider: RackCorp
• "hk" 💖
  • HK (Hong Kong) Region
  • provider: RackCorp
• "mn" 🌈
  • Ulaanbaatar (Mongolia) Region
  • provider: RackCorp
• "kg" 🍓
  • Bishkek (Kyrgyzstan) Region
  • provider: RackCorp
• "id" 🌸
  • Jakarta (Indonesia) Region
  • provider: RackCorp
• "jp" 👑
  • Tokyo (Japan) Region
  • provider: RackCorp
• "sg" ✨
  • SG (Singapore) Region
  • provider: RackCorp
• "de" 🎀
  • Frankfurt (Germany) Region
  • provider: RackCorp
• "us" 💜
  • USA (AnyCast) Region
  • provider: RackCorp
• "us-east-1" 🦋
  • New York (USA) Region
  • provider: RackCorp
• "us-west-1" 🌸
  • Fremont (USA) Region
  • provider: RackCorp

---

--s3-acl 🎀

The canned ACL we use when we're making buckets and when we're storing or copying objects. It's the little permission preset bestie, not a whole custom policy 💅

This ACL gets used for creating objects, and if bucket_acl isn't set, it gets used for creating buckets too. iykyk ✨

For all the tea, the details, the whole lore — visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl 🌸

Also, lowkey important: this ACL gets applied when server-side copying objects, because S3 doesn't copy the ACL from the source — it just writes a fresh one instead. So it's giving "new me, who dis" energy, every single time 💅

And if the acl is an empty string then no X-Amz-Acl: header is added and the default (private) will be used. Empty string = it simply minding its business, iconic.

Properties:

• Config: acl
• Env Var: RCLONE_S3_ACL
• Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IBMCOS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,US3,Wasabi,Zata,ZeroServices,Other
• Type: string
• Required: false
• Examples:
  • "private"
    • Owner gets FULL_CONTROL.
    • No one else has access rights (default).
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,US3,Wasabi,Zata,ZeroServices,Other
  • "public-read"
    • Owner gets FULL_CONTROL.
    • The AllUsers group gets READ access.
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,US3,Wasabi,Zata,ZeroServices,Other
  • "public-read-write"
    • Owner gets FULL_CONTROL.
    • The AllUsers group gets READ and WRITE access.
    • Granting this on a bucket is generally not recommended.
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,Wasabi,Zata,ZeroServices,Other
  • "authenticated-read"
    • Owner gets FULL_CONTROL.
    • The AuthenticatedUsers group gets READ access.
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,Wasabi,Zata,ZeroServices,Other
  • "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.
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,Wasabi,Zata,ZeroServices,Other
  • "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.
    • Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,Scality,SeaweedFS,TencentCOS,Wasabi,Zata,ZeroServices,Other
  • "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.
    • Provider: IBMCOS
  • "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.
    • Provider: IBMCOS
  • "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.
    • Provider: IBMCOS
  • "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.
    • Provider: IBMCOS
  • "default"
    • Owner gets Full_CONTROL.
    • No one else has access rights (default).
    • Provider: TencentCOS

---

• --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
    • Provider: AWS,Ceph,ChinaMobile,Minio
  • "AES256"
    • AES256
    • Provider: AWS,Ceph,ChinaMobile,Minio
  • "aws:kms"
    • aws:kms
    • Provider: AWS,Ceph,Minio

• --s3-sse-kms-key-id — if you're using a KMS ID you must provide the ARN of the Key, no shortcuts bestie 🫶

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,Alibaba,ArvanCloud,ChinaMobile,Liara,Magalu,OVHcloud,Qiniu,Scaleway,TencentCOS,US3
• Type: string
• Required: false
• Examples:
  • ""
    • Default
    • Provider: AWS,Alibaba,ChinaMobile,OVHcloud,TencentCOS,US3
  • "STANDARD"
    • Standard storage class
    • Provider: AWS,Alibaba,ArvanCloud,ChinaMobile,Liara,Magalu,OVHcloud,Qiniu,TencentCOS,US3
  • "REDUCED_REDUNDANCY"
    • Reduced redundancy storage class
    • Provider: AWS
  • "STANDARD_IA"
    • Standard Infrequent Access storage class
    • Provider: AWS,OVHcloud
  • "ONEZONE_IA"
    • One Zone Infrequent Access storage class
    • Provider: AWS
  • "GLACIER"
    • Glacier Flexible Retrieval storage class
    • Provider: AWS
  • "DEEP_ARCHIVE"
    • Glacier Deep Archive storage class
    • Provider: AWS
  • "INTELLIGENT_TIERING"
    • Intelligent-Tiering storage class
    • Provider: AWS
  • "GLACIER_IR"
    • Glacier Instant Retrieval storage class
    • Provider: AWS,Magalu
  • "GLACIER"
    • Archive storage mode
    • Provider: Alibaba,ChinaMobile,Qiniu
  • "STANDARD_IA"
    • Infrequent access storage mode
    • Provider: Alibaba,ChinaMobile,TencentCOS,US3
  • "EXPRESS_ONEZONE"
    • High Performance storage class
    • Provider: OVHcloud
  • "ONEZONE_IA"
    • Standard Infrequent Access storage class
    • Provider: OVHcloud
  • "GLACIER"
    • Active Archive storage class
    • Provider: OVHcloud
  • "GLACIER_IR"
    • Active Archive storage class
    • Provider: OVHcloud
  • "DEEP_ARCHIVE"
    • Cold Archive storage class
    • Provider: OVHcloud
  • "INTELLIGENT_TIERING"
    • Standard storage class
    • Provider: OVHcloud
  • "LINE"
    • Infrequent access storage mode
    • Provider: Qiniu
  • "DEEP_ARCHIVE"
    • Deep archive storage mode
    • Provider: Qiniu
  • ""
    • Default.
    • Provider: Scaleway
  • "STANDARD"
    • The Standard class for any upload.
    • Suitable for on-demand content like streaming or CDN.
    • Available in all regions.
    • Provider: Scaleway
  • "GLACIER"
    • Archived storage.
    • Prices are lower, but it needs to be restored first to be accessed.
    • Available in the FR-PAR region only.
    • Provider: Scaleway
  • "ONEZONE_IA"
    • One Zone - Infrequent Access.
    • A good choice for storing secondary backup copies or easily re-creatable data.
    • Available in all regions.
    • Provider: Scaleway
  • "ARCHIVE"
    • Archive storage mode
    • Provider: TencentCOS,US3

• --s3-ibm-api-key — IBM API Key to be used to obtain IAM token 🔑

Properties:

• Config: ibm_api_key
• Env Var: RCLONE_S3_IBM_API_KEY
• Provider: IBMCOS
• Type: string
• Required: false

• --s3-ibm-resource-instance-id — IBM service instance id 🆔

Properties:

• Config: ibm_resource_instance_id
• Env Var: RCLONE_S3_IBM_RESOURCE_INSTANCE_ID
• Provider: IBMCOS
• Type: string
• Required: false

• --s3-bucket-object-lock-enabled — enable Object Lock when creating new buckets 🔒 (no take-backsies, that's kinda the whole point of a lock)

Properties:

• Config: bucket_object_lock_enabled
• Env Var: RCLONE_S3_BUCKET_OBJECT_LOCK_ENABLED
• Type: bool
• Default: false

---

🌈 Advanced options 🌈

Okay bestie, here are the Advanced options specific to s3 (Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, BizflyCloud, Ceph, ChinaMobile, Cloudflare, Cubbit, DigitalOcean, Dreamhost, Exaba, Fastly, FileLu, FlashBlade, GCS, HCP, Hetzner, HuaweiOBS, IBMCOS, IDrive, ImpossibleCloud, Intercolo, IONOS, Leviia, Liara, Linode, LyveCloud, Magalu, Mega, Minio, Netease, Outscale, OVHcloud, Petabox, Qiniu, Rabata, RackCorp, Rclone, Scaleway, Scality, SeaweedFS, Selectel, Servercore, SpectraLogic, Storj, Synology, TencentCOS, US3, Wasabi, Zadara, Zata, ZeroServices, Other). That's a lot of providers and they all ate 💅

• --s3-bucket-acl — Canned ACL used when creating buckets.

For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl

Okay so real talk: this ACL only does anything when you're creating buckets, bestie. If it's not set, then acl gets used instead. And if both acl and bucket_acl are empty strings? Then no X-Amz-Acl: header goes out at all and the default (private) is what you get. 💅

Properties:

• Config: bucket_acl
• Env Var: RCLONE_S3_BUCKET_ACL
• Provider: AWS,Alibaba,ArvanCloud,BizflyCloud,Ceph,ChinaMobile,Cubbit,DigitalOcean,Dreamhost,Exaba,FileLu,GCS,HCP,Hetzner,HuaweiOBS,IBMCOS,IDrive,ImpossibleCloud,Intercolo,IONOS,Leviia,Liara,Linode,LyveCloud,Magalu,Mega,Minio,Netease,Outscale,OVHcloud,Petabox,Qiniu,RackCorp,Scaleway,SeaweedFS,Servercore,TencentCOS,US3,Wasabi,Zata,ZeroServices,Other
• Type: string
• Required: false
• Examples:
  • "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.

---

🌸 --s3-requester-pays

Turns on the requester pays option when you're interacting with an S3 bucket. Yes, you pay for the requests instead of the bucket owner. Iconic but also 💸.

Properties:

• Config: requester_pays
• Env Var: RCLONE_S3_REQUESTER_PAYS
• Provider: AWS
• Type: bool
• Default: false

🔐 --s3-sse-customer-algorithm

If you're using SSE-C, this is the server-side encryption algorithm used when storing this object in S3. iykyk.

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

To use SSE-C you may provide the secret encryption key used to encrypt/decrypt your data.

Alternatively you can provide --sse-customer-key-base64.

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 using SSE-C you must provide the secret encryption key encoded in base64 format to encrypt/decrypt your data. no cap, it's required for this route.

Alternatively you can provide --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 using SSE-C you may provide the secret encryption key MD5 checksum (optional, bestie, breathe).

If you leave it blank, this gets calculated automatically from the sse_customer_key you provided. rclone's got you 🫶

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

Cutoff for switching to chunked upload.

Any files larger than this get uploaded in chunks of chunk_size. The minimum is 0 and the maximum is 5 GiB.

Properties:

• Config: upload_cutoff
• Env Var: RCLONE_S3_UPLOAD_CUTOFF
• Type: SizeSuffix
• Default: 200Mi

🧩 --s3-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 or google photos or google docs), they get uploaded as multipart uploads using this chunk size.

Note that --s3-upload-concurrency chunks of this size are buffered in memory per transfer. So like, memory check bestie 🧠

If you're transferring large files over high-speed links and you have enough memory, then increasing this will speed up the transfers. slay.

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 the -P flag. Rclone treats a chunk as sent when it's buffered by the AWS SDK, when in fact it may still be uploading. A bigger chunk size means a bigger AWS SDK buffer and progress reporting more deviating from the truth. 😭 the lies.

Properties:

• Config: chunk_size
• Env Var: RCLONE_S3_CHUNK_SIZE
• Type: SizeSuffix
• Default: 5Mi

🔢 --s3-max-upload-parts

Maximum number of parts in a multipart upload.

This option defines the maximum number of multipart chunks to use when doing a multipart upload.

This can be useful if a service does not support the AWS S3 specification of 10,000 chunks. rude of them honestly.

Rclone will automatically increase the chunk size when uploading a large file of a known size to stay 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

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 1 byte 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 MD5 checksum with object metadata.

Normally rclone will calculate the MD5 checksum of the input before uploading it so it can add it to metadata on the object. This is great for data integrity checking but can cause long delays for large files to start uploading. it's giving "waiting forever for a progress bar". 🙈

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 look for the AWS_SHARED_CREDENTIALS_FILE env variable. If the env value is empty it will 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

Profile to use in the shared credentials file.

If env_auth = true then rclone can use a shared credentials file. This variable controls which profile is used in that file.

If empty it will default to the environment variable AWS_PROFILE or default if that environment variable is also not set.

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-role-arn

ARN of the IAM role to assume.

Leave blank if not using assume role. main character energy only if you actually need it 💅

Properties:

• Config: role_arn
• Env Var: RCLONE_S3_ROLE_ARN
• Type: string
• Required: false

🏷️ --s3-role-session-name

Session name for assumed role.

If empty, a session name will be generated automatically. rclone's on it ✨

Properties:

• Config: role_session_name
• Env Var: RCLONE_S3_ROLE_SESSION_NAME
• Type: string
• Required: false

⏳ --s3-role-session-duration

Session duration for assumed role.

If empty, the default session duration will be used.

Properties:

• Config: role_session_duration
• Env Var: RCLONE_S3_ROLE_SESSION_DURATION
• Type: string
• Required: false

🔑 --s3-role-external-id

External ID for assumed role.

Leave blank if not using an external ID.

Properties:

• Config: role_external_id
• Env Var: RCLONE_S3_ROLE_EXTERNAL_ID
• Type: string
• Required: false

🔀 --s3-upload-concurrency

Concurrency for multipart uploads and copies.

This is the number of chunks of the same file that are uploaded concurrently for multipart uploads and copies.

If you're 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. ate. 🔥

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 (the default) then rclone will use path style access, if false then rclone will use virtual path style. See the AWS S3 docs (https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html) for more info.

Some providers (e.g. AWS, Aliyun OSS, Netease COS, or Tencent COS) require this set to false - rclone will do this automatically based on the provider setting.

Note that if your bucket isn't a valid DNS name, i.e. has . or _ in, you'll need to set this to true. 👀 don't skip this one.

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 will use v4 authentication. If it is set then rclone will use v2 authentication.

Use this only if v4 signatures don't work, e.g. pre Jewel/v10 CEPH. like, only if you're desperate bestie 😭

Properties:

• Config: v2_auth
• Env Var: RCLONE_S3_V2_AUTH
• Type: bool
• Default: false

🌐 --s3-use-dual-stack

If true use AWS S3 dual-stack endpoint (IPv6 support).

See AWS Docs on Dualstack Endpoints (https://docs.aws.amazon.com/AmazonS3/latest/userguide/dual-stack-endpoints.html)

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 — https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration-examples.html ✨

And the receipt (aka its properties, bestie):

• Config: use_accelerate_endpoint
• Env Var: RCLONE_S3_USE_ACCELERATE_ENDPOINT
• Provider: AWS
• Type: bool
• Default: false

---

--s3-use-arn-region

Set this to true and boom 💥 — you get arn region support for the service. That's the whole plot.

• Config: use_arn_region
• Env Var: RCLONE_S3_USE_ARN_REGION
• Type: bool
• Default: false

---

--s3-leave-parts-on-error

Okay so when an upload fails, if this is true rclone will not call abort upload — it literally leaves all the successfully uploaded parts chillin' on S3 so you can rescue them by hand. 🫶

Set it to true if you wanna resume uploads across different sessions. That's the whole point of it, no cap.

⚠️ WARNING: keeping parts of an incomplete multipart upload around still counts toward your space usage on S3, and if you don't clean it up, it'll cost you extra money. So like, don't forget about them. 😭

• Config: leave_parts_on_error
• Env Var: RCLONE_S3_LEAVE_PARTS_ON_ERROR
• Provider: AWS
• Type: bool
• Default: false

---

--s3-list-chunk

How big the listing chunk is — i.e. the response list for every single ListObject S3 request. 📦

You might know this option by its other names: "MaxKeys", "max-items", or "page-size" in the AWS S3 spec. Most services will truncate the response list to 1000 objects even if you ask for more than that. And for AWS S3 specifically, 1000 is a global maximum and cannot be changed — see AWS S3: https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html. Over in Ceph land though, you can bump it up with the "rgw list buckets max chunk" option. 🧚

• Config: list_chunk
• Env Var: RCLONE_S3_LIST_CHUNK
• Type: int
• Default: 1000

---

--s3-list-version

Which version of ListObjects we're using: 1, 2, or 0 for auto. 🎀

Back when S3 first launched it only had the ListObjects call for enumerating objects in a bucket. Then in May 2016, ListObjectsV2 showed up and it's so much higher performance, so you should use it if it's even remotely possible.

If you leave it at the default, 0, rclone will guess based on the provider setting which list objects method to call. And if it guesses wrong? Just set it manually here, bestie. 💅

• 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 support URL encoding listings, and where it's available it's genuinely more reliable when you've got control characters in your file names. If this is set to unset (which is the default), rclone picks based on the provider setting what to apply — but you can override rclone's choice right here. 👑

• Config: list_url_encode
• Env Var: RCLONE_S3_LIST_URL_ENCODE
• Type: Tristate
• Default: unset

---

--s3-no-check-bucket

If set, rclone won't try to check whether the bucket exists or create it. 🙈

Lowkey useful when you're trying to minimise the number of transactions rclone does, and you already know the bucket exists.

It can also be necessary when the user you're running as doesn't have bucket creation permissions. And fun fact: before v1.52.0 this would have passed silently anyway because of a bug. 💀

• Config: no_check_bucket
• Env Var: RCLONE_S3_NO_CHECK_BUCKET
• Type: bool
• Default: false

---

--s3-no-head

If set, rclone won't HEAD uploaded objects to check integrity. ✨

Again: great for minimising how many transactions rclone does.

Setting it means that if rclone gets a 200 OK message back after uploading an object with PUT, it just... assumes it uploaded properly. Main character energy, honestly.

Specifically it will assume:

• the metadata was as uploaded — and that includes modtime, storage class and content type
• the size was as uploaded

It does read these items from the response for a single part PUT:

• the MD5SUM
• the uploaded date

For multipart uploads, these items aren't read at all.

Oh and if a source object of unknown length gets uploaded, rclone will do a HEAD request anyway.

⚠️ Setting this flag raises the chance of undetected upload failures — incorrect size especially — so it is 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. 🤏

• Config: no_head
• Env Var: RCLONE_S3_NO_HEAD
• Type: bool
• Default: false

---

--s3-no-head-object

If set, no HEAD before GET when you're getting objects. Simple as that. 🦋

• Config: no_head_object
• Env Var: RCLONE_S3_NO_HEAD_OBJECT
• Type: bool
• Default: false

---

--s3-encoding

The encoding for the backend. 🔤

Peep the encoding section in the overview for more: https://rclone.org/overview/#encoding

• Config: encoding
• Env Var: RCLONE_S3_ENCODING
• Type: Encoding
• Default: Slash,InvalidUtf8,Dot

---

--s3-disable-http2

Disables usage of http2 for S3 backends. 🚫

Right now there's an unsolved issue with the s3 backend (specifically minio) and HTTP/2. HTTP/2 is enabled by default for the s3 backend, but you can turn it off here. When the issue finally gets solved, this flag will be removed, so don't get too attached. 😭

See: https://github.com/rclone/rclone/issues/4673, https://github.com/rclone/rclone/issues/3631

• Config: disable_http2
• Env Var: RCLONE_S3_DISABLE_HTTP2
• Type: bool
• Default: false

---

--s3-download-url

Custom endpoint for downloads. 🌐

Usually you'd set this to a CloudFront CDN URL, because AWS S3 offers cheaper egress for data downloaded through the CloudFront network. Save that coin, bestie 💸

• Config: download_url
• Env Var: RCLONE_S3_DOWNLOAD_URL
• Type: string
• Required: false

---

--s3-directory-markers

Uploads an empty object with a trailing slash whenever a new directory is created. 📁

Empty folders are unsupported for bucket based remotes, so this option creates an empty object ending with "/" to make the folder persist. It's giving "fake it till you make it" but for directories.

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

• 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. ✍️

Here's the tea: rclone has to stop the AWS SDK from seeking the body when it calls PutObject. The AWS provider can add checksums in the trailer to dodge the seeking, but other providers simply can't.

This should be true, false, or left unset to use the provider's default.

• 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 < 1.59 used presigned requests to upload a single part object, and setting this flag to true re-enables that functionality. You shouldn't need it except in exceptional circumstances or for testing. Like, genuinely exceptional. 🫣

• Config: use_presigned_request
• Env Var: RCLONE_S3_USE_PRESIGNED_REQUEST
• Type: bool
• Default: false

---

--s3-use-data-integrity-protections

If true, use AWS S3 data integrity protections. 🛡️✨

See the AWS Docs on Data Integrity Protections: https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html

• Config: use_data_integrity_protections
• Env Var: RCLONE_S3_USE_DATA_INTEGRITY_PROTECTIONS
• Type: Tristate
• Default: unset

---

--s3-versions

Include old versions in directory listings. 👻

• Config: versions
• Env Var: RCLONE_S3_VERSIONS
• Type: bool
• Default: false

---

--s3-version-at

Shows file versions exactly as they were at a specified time. ⏰

The parameter should be a date, "2006-01-02", a datetime "2006-01-02 15:04:05", or a duration meaning "that long ago", like "100d" or "1h".

Heads up: when you're using this, no file write operations are permitted — so you can't upload files or delete them. Read-only era. 📖

See the time option docs for valid formats: https://rclone.org/docs/#time-options

• Config: version_at
• Env Var: RCLONE_S3_VERSION_AT
• Type: Time
• Default: off

---

--s3-version-deleted

Shows deleted file markers when you're using versions. 🪦

This makes deleted file markers show up in the listing when using versions. They'll appear as 0 size files, and the only operation you can perform on them is deletion.

Deleting a delete marker reveals the previous version — iconic behaviour, honestly. 💅

Deleted files will always show with a timestamp.

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

But if this flag is set, rclone will decompress those "Content-Encoding: gzip" files as they're received. Which means rclone can't check the size and hash — but the file contents will be decompressed. Trade-offs, bestie. ⚖️

• Config: decompress
• Env Var: RCLONE_S3_DECOMPRESS
• Type: bool
• Default: false

---

--s3-might-gzip

Set this if the backend might gzip objects. 🤔

Normally providers won't alter objects when they're downloaded. If an object wasn't uploaded with Content-Encoding: gzip, then that won't be set on download either.

However, some providers may gzip objects even if they weren't uploaded with Content-Encoding: gzip — Cloudflare, for example. 🙃

A symptom of this would be receiving errors like:

ERROR corrupted on transfer: sizes differ NNN vs MMM

If you 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. ✨

If this is set to unset (the default), rclone chooses according to the provider setting what to apply — but you can override rclone's choice here.

• Config: might_gzip
• Env Var: RCLONE_S3_MIGHT_GZIP
• Type: Tristate
• Default: unset

---

--s3-use-accept-encoding-gzip

Whether to send the Accept-Encoding: gzip header. 🫶

By default, rclone will append Accept-Encoding: gzip to the request to download compressed objects whenever possible.

However some providers, like Google Cloud Storage, will go and mess with the HTTP headers, which completely breaks the signature on the request 😭

If that's happening to you, you'll see errors like this:

SignatureDoesNotMatch: The request signature we calculated does not match the signature you provided.

And in that case, bestie, you might wanna try disabling this option ✨

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

Properties:

• Config: no_system_metadata
• Env Var: RCLONE_S3_NO_SYSTEM_METADATA
• Type: bool
• Default: false

• --s3-use-already-exists — Set if rclone should report BucketAlreadyExists errors on bucket creation.

Okay so storytime 📖 at some point while the s3 protocol was evolving, AWS started returning an AlreadyOwnedByYou error when you attempt to create a bucket you already own — instead of a BucketAlreadyExists error. Classic glow-up, honestly.

And unfortunately, the way the s3 clones implemented this is kinda all over the place 🙈 some return AlreadyOwnedByYou, some return BucketAlreadyExists, and some just return no error at all. Not them being inconsistent 💀

This matters to rclone because it makes sure 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 report BucketAlreadyExists errors when you try to create a bucket that isn't yours. Otherwise rclone just ignores the BucketAlreadyExists error, which can lead to confusion 👀

This should be automatically set correctly for all providers rclone knows about — but if it isn't, please make a bug report 🫶

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.

You can change this if you wanna disable the use of multipart uploads. Lowkey this shouldn't be necessary in normal operation though ✨

This should be automatically set correctly for all providers rclone knows about — if it's not, please make a bug report 🫶

Properties:

• Config: use_multipart_uploads
• Env Var: RCLONE_S3_USE_MULTIPART_UPLOADS
• Type: Tristate
• Default: unset

• --s3-list-versions-oldest-first — Set if the backend returns object versions oldest first.

So the S3 standard returns object versions newest first. But some backends (e.g. Hitachi HCP) return them oldest first instead. Not them being quirky 💅

Set this quirk if --s3-version-at or --s3-versions are producing incorrect results with your backend.

This should be automatically set correctly for all providers rclone knows about — if it's not, please make a bug report 🫶

Properties:

• Config: list_versions_oldest_first
• Env Var: RCLONE_S3_LIST_VERSIONS_OLDEST_FIRST
• Type: Tristate
• Default: unset

• --s3-use-x-id — Set if rclone should add x-id URL parameters.

You can change this if you want to stop the AWS SDK from adding x-id URL parameters. Again, this shouldn't be necessary in normal operation, bestie ✨

This should be automatically set correctly for all providers rclone knows about — if it's not, please make a bug report 🫶

Properties:

• Config: use_x_id
• Env Var: RCLONE_S3_USE_X_ID
• Type: Tristate
• Default: unset

• --s3-sign-accept-encoding — Set if rclone should include Accept-Encoding as part of the signature.

You can change this if you want to stop rclone including Accept-Encoding as part of the signature. And yep — this shouldn't be necessary in normal operation either 😌

This should be automatically set correctly for all providers rclone knows about — if it's not, please make a bug report 🫶

Properties:

• Config: sign_accept_encoding
• Env Var: RCLONE_S3_SIGN_ACCEPT_ENCODING
• Type: Tristate
• Default: unset

• --s3-directory-bucket — Set to use AWS Directory Buckets

If you're using an AWS Directory Bucket then set this flag, bestie 👑

This will make sure no Content-Md5 headers are sent and make sure ETag headers are not interpreted as MD5 sums. And X-Amz-Meta-Md5chksum will be set on all objects, whether single or multipart uploaded.

This also sets no_check_bucket = true.

Just so you know, Directory Buckets do not support:

• Versioning
• Content-Encoding: gzip

And here are the rclone limitations with Directory Buckets (not ideal, we know 😭):

• 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 to debug the SDK

This can be set to a comma separated list of the following functions:

• Signing
• Retries
• Request
• RequestWithBody
• Response
• ResponseWithBody
• DeprecatedUsage
• RequestEventMessage
• ResponseEventMessage

Use Off to disable and All to set all log levels. And heads up 🫶 you'll need to use -vv to actually see the debug level logs.

Properties:

• Config: sdk_log_mode
• Env Var: RCLONE_S3_SDK_LOG_MODE
• Type: Bits
• Default: Off

• --s3-ibm-iam-endpoint — IBM IAM Endpoint to use for authentication.

Leave blank to use the default public endpoint.

Properties:

• Config: ibm_iam_endpoint
• Env Var: RCLONE_S3_IBM_IAM_ENDPOINT
• Provider: IBMCOS
• Type: string
• Required: false

• --s3-object-lock-mode — Object Lock mode to apply when uploading or copying objects.

Set this to apply Object Lock retention mode to objects. If you don't set it, no Object Lock mode is applied (even with --metadata).

⚠️ Note bestie: to enable Object Lock retention, you must set BOTH object_lock_mode AND object_lock_retain_until_date. Setting only one has no effect.

• GOVERNANCE: Set Object Lock mode to GOVERNANCE
• COMPLIANCE: Set Object Lock mode to COMPLIANCE
• copy: Copy the mode from the source object (requires --metadata)

See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html

Properties:

• Config: object_lock_mode
• Env Var: RCLONE_S3_OBJECT_LOCK_MODE
• Type: string
• Required: false
• Examples:
  • "GOVERNANCE"
    • Set Object Lock mode to GOVERNANCE
  • "COMPLIANCE"
    • Set Object Lock mode to COMPLIANCE
  • "copy"
    • Copy from source object (requires --metadata)

• --s3-object-lock-retain-until-date — Object Lock retention until date to apply when uploading or copying objects.

Set this to apply an Object Lock retention date to objects. If you don't set it, no retention date is applied (even with --metadata).

⚠️ Note bestie: to enable Object Lock retention, you must set BOTH object_lock_mode AND object_lock_retain_until_date. Setting only one has no effect.

Accepts:

• RFC 3339 format: 2030-01-02T15:04:05Z
• Duration from now: 365d, 1y, 6M (days, years, months)
• copy: Copy the date from the source object (requires --metadata)

See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html

Properties:

• Config: object_lock_retain_until_date
• Env Var: RCLONE_S3_OBJECT_LOCK_RETAIN_UNTIL_DATE
• Type: string
• Required: false
• Examples:
  • "copy"
    • Copy from source object (requires --metadata)
  • "2030-01-01T00:00:00Z"
    • Set specific date (RFC 3339 format)
  • "365d"
    • Set retention for 365 days from now
  • "1y"
    • Set retention for 1 year from now

• --s3-object-lock-legal-hold-status — Object Lock legal hold status to apply when uploading or copying objects.

Set this to apply Object Lock legal hold to objects. If you don't set it, no legal hold is applied (even with --metadata).

⚠️ Note: legal hold is independent of retention and can be set separately ✨

• ON: Enable legal hold
• OFF: Disable legal hold
• copy: Copy the legal hold status from the source object (requires --metadata)

See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html

Properties:

• Config: object_lock_legal_hold_status
• Env Var: RCLONE_S3_OBJECT_LOCK_LEGAL_HOLD_STATUS
• Type: string
• Required: false
• Examples:
  • "ON"
    • Enable legal hold
  • "OFF"
    • Disable legal hold
  • "copy"
    • Copy from source object (requires --metadata)

• --s3-bypass-governance-retention — Allow deleting or modifying objects locked with GOVERNANCE mode.

Properties:

• Config: bypass_governance_retention
• Env Var: RCLONE_S3_BYPASS_GOVERNANCE_RETENTION
• Type: bool
• Default: false

• --s3-object-lock-set-after-upload — Set Object Lock via separate API calls after upload.

Use this for S3-compatible providers that don't support setting Object Lock headers during PUT operations. When it's enabled, Object Lock gets set via separate PutObjectRetention and PutObjectLegalHold API calls after the upload finishes.

Heads up though 🫶 this adds extra API calls per object, so only enable it if your provider actually requires it.

Properties:

• Config: object_lock_set_after_upload
• Env Var: RCLONE_S3_OBJECT_LOCK_SET_AFTER_UPLOAD
• Type: bool
• Default: false

• --s3-object-lock-supported — Whether the provider supports S3 Object Lock.

This should be true, false or left unset to use the default for the provider.

Set it to false for providers that don't fully support the S3 Object Lock API (e.g. GCS, which uses non-standard headers for bypass governance retention and doesn't implement Legal Hold via the S3 API).

Properties:

• Config: object_lock_supported
• Env Var: RCLONE_S3_OBJECT_LOCK_SUPPORTED
• Type: Tristate
• Default: unset

• --s3-description — Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_S3_DESCRIPTION
• Type: string
• Required: false

---

🌸 Metadata 🌸

User metadata is stored as x-amz-meta- keys. And fun fact 💅 S3 metadata keys are case insensitive and are always returned in lowercase.

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
• object-lock-legal-hold-status — Object Lock legal hold status: ON or OFF 🫶 · Type: string · Example: OFF · Read Only: N
• object-lock-mode — Object Lock mode: GOVERNANCE or COMPLIANCE 😭 · Type: string · Example: GOVERNANCE · Read Only: N
• object-lock-retain-until-date — Object Lock retention until date 🔥 · Type: RFC 3339 · Example: 2030-01-02T15:04:05Z · Read Only: N
• tier — Tier of the object 👑 · Type: string · Example: GLACIER · Read Only: Y

See the metadata docs (https://rclone.org/docs/#metadata) for more info, bestie — it's giving ✨ essential reading ✨.

---

🛠️ Backend commands 🛠️

Okay so these are the commands that are specific to the s3 backend — like, only s3 ones, not your everyday rclone moves 💜.

Run them like this:

rclone backend COMMAND remote:

The help below spills all the tea on what arguments each command takes 🌈.

See the backend command (https://rclone.org/commands/rclone_backend/) for more info on how to pass options and arguments, iykyk.

These can be run on a running backend using the rc command backend/command (https://rclone.org/rc/#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 to the Frequent Access tier 💖.

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. Test first with --interactive/-i or --dry-run flags — no cap, always vibe-check before you commit 🙈.

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 status for objects being restored from GLACIER or INTELLIGENT-TIERING 👀.

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 💫.

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

Heads up bestie: this command does not obey the filters 🚫✨.

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 🦋.

Usage examples:

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 bucket, with a bucket or with a bucket and path 👑.

{
    "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 24 hours ⏰.

Note that you can use --interactive/-i or --dry-run with this command to see what it would do — peep before you yeet, fr fr 🙈.

Usage examples:

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 hidden 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 💖.

Usage example:

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 ✨.

Usage examples:

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 👀. Note that once versioning has been enabled the status can't be set back to Unversioned 😭 — like, that door is locked bestie.

---

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:

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

The option keys are named as they are in the config file 📝.

This rebuilds the connection to the s3 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 🤐.

---

🔓 Anonymous access to public buckets 🔓

If you want to use rclone to access a public bucket, configure with a blank access_key_id and secret_access_key 🌈. Your config should end up looking like this:

[anons3]
type = s3
provider = AWS

Then use it as normal with the name of the public bucket, e.g.

rclone lsd anons3:1000genomes

You will be able to list and copy data but not upload it 🚫⬆️.

You can also do this entirely on the command line ✨:

rclone lsd :s3,provider=AWS:1000genomes

---

🌩️ Providers 🌩️

AWS S3

This is the provider used as main example and described in the configuration section above 💖 — the blueprint, the blueprint-iest, the main character of s3 providers 👑.

AWS Directory Buckets

From rclone v1.69 Directory Buckets (https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html) are supported 🎉.

You will need to set the directory_bucket = true config parameter or use --s3-directory-bucket 🦋.

Note that rclone cannot yet:

• Create directory buckets 🚫
• List directory buckets 🚫

See the --s3-directory-bucket flag for more info 💅.

❄️ AWS Snowball Edge

okay so AWS Snowball (https://aws.amazon.com/snowball/) is a literal physical hardware appliance 📦 that you use to haul bulk data back to AWS. Its main software interface is S3 object storage.

To use rclone with AWS Snowball Edge devices, just configure it as a standard 'S3 Compatible Service'.

If you're on rclone pre v1.59, bestie, be sure to set upload_cutoff = 0, otherwise you will run into authentication header issues, because the snowball device does not support query parameter based authentication. 😭

With rclone v1.59 or later, setting upload_cutoff should not be necessary. ✨

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

---

🌸 Alibaba OSS

Here is an example of making an Alibaba Cloud (Aliyun) OSS (https://www.alibabacloud.com/product/oss/) 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> 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

---

🦋 ArvanCloud

ArvanCloud (https://www.arvancloud.com/en/products/cloud-storage) — ArvanCloud Object Storage goes beyond the limited traditional file storage. It gives you access to backup and archived files and allows sharing. Files like profile image in the app, images sent by users or scanned documents can be stored securely and easily in our Object Storage service. 💜

ArvanCloud 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> 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

This will leave the config file looking 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 =

---

🍓 BizflyCloud

Bizfly Cloud Simple Storage (https://bizflycloud.vn/simple-storage) is an S3-compatible service with regions in Hanoi (HN) and Ho Chi Minh City (HCM).

Use the endpoint for your region:

• HN: hn.ss.bfcplatform.vn
• HCM: hcm.ss.bfcplatform.vn

A minimal configuration looks like this.

[bizfly]
type = s3
provider = BizflyCloud
env_auth = false
access_key_id = YOUR_ACCESS_KEY
secret_access_key = YOUR_SECRET_KEY
region = HN
endpoint = hn.ss.bfcplatform.vn
location_constraint =
acl =
server_side_encryption =
storage_class =

Switch region and endpoint to HCM and hcm.ss.bfcplatform.vn for Ho Chi Minh City. 🛫

---

🐙 Ceph

Ceph (https://ceph.com/) is an open-source, unified, distributed storage system designed for excellent performance, reliability and scalability. It has an S3 compatible object storage interface.

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 =

⚠️ bestie listen up, if you're on an ancient Ceph (like 10.2.x Jewel energy) and an rclone from before v1.59, you might have to pass --s3-upload-cutoff 0 — or drop upload_cutoff 0 into your config file — to dodge a bug that makes uploading small files just… fail. 💀

Rclone defaults sign_accept_encoding to false for the Ceph provider. Why? Because it avoids SignatureDoesNotMatch errors when a reverse proxy (hi Cloudflare 👋) rewrites the Accept-Encoding request header. You can override that whenever you need with --s3-sign-accept-encoding / sign_accept_encoding. No cap. 🫶

Also PSA: Ceph sometimes sneaks a / into the passwords it hands out. If you read the secret access key using the command line tools you'll get a JSON blob where the / is escaped as \/. So make sure you only write / in the secret access key. Like, just the slash, nothing else. 💅

For example, the dump from Ceph looks something like this (irrelevant keys removed, because who has time):

{
    "user_id": "xxx",
    "display_name": "xxxx",
    "keys": [
        {
            "user": "xxx",
            "access_key": "xxxxxx",
            "secret_key": "xxxxxx\/xxxx"
        }
    ],
}

Because this is a json dump, it's encoding the / as \/, so if you use the secret key as xxxxxx/xxxx it will work fine. ✨ Easy. Iconic. Moving on.

---

🌸 China Mobile Ecloud Elastic Object Storage (EOS) 🌸

Here's an example of making a China Mobile Ecloud Elastic Object Storage (EOS) (https:///ecloud.10086.cn/home/product-introduction/eos/) configuration. First run:

rclone config

This will guide you through an interactive setup process. 🎀 Step by step, hand held, main character energy — we love to see it.

okay so like, watch the terminal do its little dance 🩰 — every line is a real prompt, and the replies are what you type:

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

obsessed</p> with how clean that came out 💖 quick recap of what you just watched happen: no remotes existed yet, so you made a new remote called ChinaMobile, picked storage type s3, then told the provider prompt it's ChinaMobile (that's option 4, China Mobile Ecloud Elastic Object Storage (EOS)). You skipped env_auth entirely, so it stayed at the default false and you hand-typed the access_key_id and secret_access_key. Then you chose endpoint option 1, which is East China (Suzhou) → eos-wuxi-1.cmecloud.cn, and location_constraint option 1, which is wuxi1 (and yeah, they must match — that's not a suggestion, bestie, it's literally in the prompt text 🫠). acl = private, server_side_encryption left empty, storage_class left empty, advanced config? <purple>n</purple>. Then the config preview, then y because yes, this is OK, and boom — remote secured. ✨

lowkey important thing to clock: that acl thing is applied when server-side copying objects too, because S3 doesn't carry the ACL over from the source — it just writes a fresh one. No cap. So your copy gets the ACL you configured, not the one the original file was chilling with. 💅

---

🦋 Cloudflare R2

Cloudflare R2 (https://blog.cloudflare.com/r2-open-beta/) Storage lets devs store, like, huge amounts of unstructured data without the costly egress bandwidth fees that come with your typical cloud storage services. The way that's such a glow-up 😭 the egress fees were giving scam fr fr.

Here's an example of making a Cloudflare R2 configuration. First run:

rclone config

This will guide you through an interactive setup process. 🧚

⚠️ okay so heads up bestie, all buckets are private, and they're all stored in the same "auto" region. If you wanna share the content of a bucket publicly you have to use Cloudflare workers. That's the whole vibe — no sneaky public bucket setting here, iykyk. 🙈

---

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

and boom, your config file is gonna look a lil something like this 💖

[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 go be nosy 👀 run rclone lsf r2: to peek at your buckets, and rclone lsf r2:bucket to snoop inside a bucket. it's giving detective energy.

heads up bestie: if your R2 token has the "Object Read & Write" permission, you might also need to add no_check_bucket = true or your object uploads will simply not work. tragic, but fixable.

also, ngl, Cloudflare decompresses files that get uploaded with Content-Encoding: gzip by default, which is a deviation from what AWS does. so if that's causing you pain, upload your files with --header-upload "Cache-Control: no-transform" and you're golden ✨

one lil consequence of all this (iykyk): Content-Encoding: gzip is literally never gonna show up in the metadata on Cloudflare. periodt.

---

🦋 Cubbit DS3

Cubbit Object Storage (https://www.cubbit.io/ds3-cloud) is a geo-distributed cloud object storage platform. very ✨global✨ of it.

to connect to Cubbit DS3 you need an access key + secret key pair. you can follow this guide (https://docs.cubbit.io/getting-started/quickstart#api-keys) to grab those keys. rclone config is gonna ask you for them, so have 'em ready 🫶

the default region corresponds to eu-west-1, and the endpoint has to be specified as s3.cubbit.eu. and listen — if you set a custom tenant endpoint, you must use s3.{tenant_name}.cubbit.eu, because the generic s3.cubbit.eu endpoint will not work in that case. no cap.

going through the whole "make a new remote" journey with rclone config, every prompt should be answered like this:

name> cubbit-ds3 (or any name you like)
Storage> s3
provider> Cubbit
env_auth> false
access_key_id> YOUR_ACCESS_KEY
secret_access_key> YOUR_SECRET_KEY
region> eu-west-1 (or leave empty)
endpoint> s3.cubbit.eu (or s3.{tenant_name}.cubbit.eu)
acl>

and the config file that falls out of that should look like:

[cubbit-ds3]
type = s3
provider = Cubbit
access_key_id = ACCESS_KEY
secret_access_key = SECRET_KEY
region = eu-west-1
endpoint = s3.cubbit.eu

then you can start using Cubbit DS3 with rclone fr fr. for example, to make a new bucket and copy files into it, run:

rclone mkdir cubbit-ds3:my-bucket
rclone copy /path/to/files cubbit-ds3:my-bucket

main character setup complete 💅

---

💙 DigitalOcean Spaces

Spaces (https://www.digitalocean.com/products/object-storage/) is an S3-interoperable (https://developers.digitalocean.com/documentation/spaces/) object storage service from cloud provider DigitalOcean. slay.

to connect to DigitalOcean Spaces you'll need an access key and a secret key. you can retrieve these on the Applications & API (https://cloud.digitalocean.com/settings/api/tokens) page of the DigitalOcean control panel. rclone config is gonna want them for your access_key_id and secret_access_key, so yeah.

when it asks for a region or location_constraint, just press enter to use the default value. the region must be included in the endpoint setting (e.g. nyc3.digitaloceanspaces.com). the default values work fine for the other settings, no stress 🌸

going through the whole new-remote process with rclone config, each prompt should be answered like so:

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 config 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 =

once it's configured, you can create a new Space and start copying files. for example:

rclone mkdir spaces:my-new-space
rclone copy /path/to/files spaces:my-new-space

---

🏠 Dreamhost

Dreamhost DreamObjects (https://www.dreamhost.com/cloud/storage/) is an object storage system based on CEPH. vintage but valid.

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 =

---

🌈 Exaba

Exaba (https://exaba.com/) is an on-premises, S3-compatible storage for service providers and large enterprises. it's quick to deploy, with dynamic node management, tenant accounting, and a built-in key management system. it delivers secure, high-performance data storage with flexible, usage-based pricing. corporate but make it ✨

a container version exaba/exaba (https://hub.docker.com/r/exaba/exaba) is free for end-users, and on that page you can find instructions on how to set it up. you'll need to log into the admin first (on port 9006 by default) to set up the container, then you can use the service on port 9000. two ports, one destiny 🎀

you can also join the exaba support slack (https://join.slack.com/t/exabasupport/shared_invite/zt-3b5jycjs3-0gDNyv60xKsAdNgjX72amQ) if you need more help. community support era 💜

an rclone config walkthrough might look like this, but details may vary depending exactly on how you've set up the container:

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> exaba

Option Storage.
Type of storage to configure.
Storage> s3

Option provider.
Choose your S3 provider.
provider> Exaba

Option env_auth.
env_auth> 1

Option access_key_id.
access_key_id> XXX

Option secret_access_key.
secret_access_key> YYY

Option region.
region>

Option endpoint.
endpoint> http://127.0.0.1:9000/

Option location_constraint.
location_constraint>

Option acl.
acl>

Edit advanced config?
y) Yes
n) No (default)
y/n> n

and the config generated will end up looking like this:

[exaba]
type = s3
provider = Exaba
access_key_id = XXX
secret_access_key = XXX
endpoint = http://127.0.0.1:9000/

---

🔥 Fastly Object Storage

Fastly Object Storage (https://www.fastly.com/products/storage) is an S3-compatible object storage service from Fastly. it provides three regions — US East, US West, and EU Central — with mandatory server-side encryption. no opting out, it's required, don't even try it 💀

here's an example of making a 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

Enter name for new remote.
name> fastly

Option Storage.
Type of storage to configure.
Storage> s3

Option provider.
Choose your S3 provider.
provider> Fastly

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.
env_auth> false

Option access_key_id.
AWS Access Key ID.
access_key_id> YOUR_ACCESS_KEY

Option secret_access_key.
AWS Secret Access Key (password).
secret_access_key> YOUR_SECRET_KEY

Option region.
Region where your bucket will be created and your data stored.
region> us-east

Option endpoint.
Endpoint for S3 API.
endpoint> us-east.object.fastlystorage.app

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: Fastly
- access_key_id: YOUR_ACCESS_KEY
- secret_access_key: YOUR_SECRET_KEY
- region: us-east
- endpoint: us-east.object.fastlystorage.app
Keep this "fastly" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

And bestie, this is what your config file should look like when the dust settles: 💅

[fastly]
type = s3
provider = Fastly
access_key_id = YOUR_ACCESS_KEY
secret_access_key = YOUR_SECRET_KEY
region = us-east
endpoint = us-east.object.fastlystorage.app

---

💖 Google Cloud Storage 💖

GoogleCloudStorage (https://cloud.google.com/storage/docs) is an S3-interoperable (https://cloud.google.com/storage/docs/interoperability) object storage service from Google Cloud Platform. it's giving corporate cloud but make it interoperable ✨

To connect to Google Cloud Storage you will need an access key and a secret key. These can be retrieved by creating an HMAC key (https://cloud.google.com/storage/docs/authentication/managing-hmackeys). yeah bestie, HMAC, not OAuth, it's a whole thing, just go make one 🫶

[gs]
type = s3
provider = GCS
access_key_id = your_access_key
secret_access_key = your_secret_key
endpoint = https://storage.googleapis.com

⚠️ Heads up fr fr: --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 (https://issuetracker.google.com/u/0/issues/312292516). not rclone's fault bestie, we're just the messenger 😭

---

🌸 Hetzner Object Storage 🌸

Here's an example of making a Hetzner Object Storage (https://www.hetzner.com/storage/object-storage/) configuration. First run:

rclone config

This will guide you through an interactive setup process. walk with me 💫

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> my-hetzner
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, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, Hetzner, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, Storj, Synology, TencentCOS, Wasabi, Qiniu 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 / Hetzner Object Storage
   \ (Hetzner)
[snip]
provider> Hetzner
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> 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_KEY
Option region.
Region to connect to.
Choose a number from below, or type in your own value.
Press Enter to leave empty.
 1 / Helsinki
   \ (hel1)
 2 / Falkenstein
   \ (fsn1)
 3 / Nuremberg
   \ (nbg1)
region>
Option endpoint.
Endpoint for Hetzner Object Storage
Choose a number from below, or type in your own value.
Press Enter to leave empty.
 1 / Helsinki
   \ (hel1.your-objectstorage.com)
 2 / Falkenstein
   \ (fsn1.your-objectstorage.com)
 3 / Nuremberg
   \ (nbg1.your-objectstorage.com)
endpoint>
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>
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)
acl>
Edit advanced config?
y) Yes
n) No (default)
y/n>
Configuration complete.
Options:
- type: s3
- provider: Hetzner
- access_key_id: ACCESS_KEY
- secret_access_key: SECRET_KEY
Keep this "my-hetzner" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d>
Current remotes:

Name                 Type
====                 ====
my-hetzner           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>

This will leave the config file looking like this. 🎀

[my-hetzner]
type = s3
provider = Hetzner
access_key_id = ACCESS_KEY
secret_access_key = SECRET_KEY
region = hel1
endpoint = hel1.your-objectstorage.com
acl = private

---

💜 Hitachi Content Platform (HCP) 💜

Here's an example of making a Hitachi Content Platform (HCP) (https://www.hitachivantara.com/en-us/products/storage/content-platform.html) configuration. First run:

rclone config

This will guide you through an interactive setup process. let's goooo 🔥

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> my-hcp
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, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, HCP, Hetzner, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, Storj, Synology, TencentCOS, Wasabi, Qiniu 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 / Hitachi Content Platform (HCP)
   \ (HCP)
[snip]
provider> HCP
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> 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_KEY
Option endpoint.
Endpoint for HCP S3 compatible API.
Enter a value. Press Enter to leave empty.
endpoint> https://hcp.example.com
Edit advanced config?
y) Yes
n) No (default)
y/n>
Configuration complete.
Options:
- type: s3
- provider: HCP
- access_key_id: ACCESS_KEY
- secret_access_key: SECRET_KEY
- endpoint: https://hcp.example.com
Keep this "my-hcp" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d>
Current remotes:

Name                 Type
====                 ====
my-hcp               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>

and boom, your config file ends up looking exactly like this 💖

[my-hcp]
type = s3
provider = HCP
access_key_id = ACCESS_KEY
secret_access_key = SECRET_KEY
endpoint = https://hcp.example.com

Known limitations 🚧

okay bestie, these ones have been spotted out in the wild with HCP version 9.7.x. no cap.

Automatic directory objects

HCP is out here auto-creating zero-byte directory objects (keys ending in /) for every single path component whenever an object gets stored. and these directory objects? HCP manages them internally — so deleting one through the S3 API doesn't actually delete it, it just drops a delete marker with a special version ID (-3) that cannot itself be deleted 😭. which means rclone literally can't fully purge a bucket on HCP — you'll have leftover directory objects chilling there after a purge or delete operation. it's giving unkillable.

Transparent gzip decompression

HCP transparently decompresses objects that were uploaded with Content-Encoding: gzip before it stores them (docs: https://docs.hitachivantara.com/r/en-us/content-platform/9.6.x/mk-95hcph002/using-the-hitachi-api-for-amazon-s3/working-with-objects/creating-an-object ). so the stored object ends up holding the raw (uncompressed) data, but the Content-MD5 rclone sent was computed over the compressed bytes 🙈. HCP is gonna reject those uploads with a BadDigest error. to dodge that entirely: do not set content-encoding: gzip in object metadata when you're using HCP. periodt.

Huawei OBS 🌸

Object Storage Service (OBS) is out here providing stable, secure, efficient, and easy-to-use cloud storage — letting you store basically any volume of unstructured data in any format and access it from anywhere. iconic behavior.

OBS offers an S3 interface, so you can copy and modify the config below and just drop it into your rclone configuration file ✨

[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

or, if you're a chatty girlie, you can also configure it through the interactive command line 💅

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

IBM COS (S3) 🧊

info you store with IBM Cloud Object Storage gets encrypted and dispersed across multiple geographic locations, and you reach it through an implementation of the S3 API. this service is running on the distributed storage tech from IBM's Cloud Object Storage System (formerly Cleversafe). more deets right here: <http://www.ibm.com/cloud/object-storage>

to set up access to IBM COS S3, just follow along bestie 👑

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. enter the name for the configuration

name> <YOUR NAME>

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 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. enter the 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. specify the endpoint for IBM COS. for Public IBM COS, pick from the option below. for On Premise IBM COS, enter an endpoint address.

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. specify a IBM COS Location Constraint. the location constraint has to match endpoint when you're using IBM Cloud Public. for on-prem COS, don't select 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

8. bestie it's ACL time 💅 Pick a canned ACL. IBM Cloud (Storage) supports "public-read" and "private". IBM Cloud(Infra) supports literally every canned ACL. And On-Premise COS? Also supports all the canned ACLs. Slay.

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

9. Okay so now you scroll through the config it just showed you, vibe check it 🌸, accept it, save that remote, and dip. Your config file should be giving exactly 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

10. Time to actually run rclone commands, this is the fun part fr fr ✨

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

IBM IAM authentication 🔐

If you're using IBM IAM authentication with an IBM API KEY, bestie you gotta fill in these extra parameters too, no skipping:

1. Select false for env_auth
2. Leave access_key_id and secret_access_key blank
3. Paste your ibm_api_key

Option ibm_api_key.
IBM API Key to be used to obtain IAM token
Enter a value of type string. Press Enter for the default (1).
ibm_api_key>

4. Paste your ibm_resource_instance_id

Option ibm_resource_instance_id.
IBM service instance id
Enter a value of type string. Press Enter for the default (2).
ibm_resource_instance_id>

5. In advanced settings type true for v2_auth

Option v2_auth.
If true use v2 authentication.
If this is false (the default) then rclone will use v4 authentication.
If it is set then rclone will use v2 authentication.
Use this only if v4 signatures don't work, e.g. pre Jewel/v10 CEPH.
Enter a boolean value (true or false). Press Enter for the default (true).
v2_auth>

---

IDrive e2 🦋

Here's an example of making an IDrive e2 (https://www.idrive.com/e2/) configuration. First run:

rclone config

This will guide you through an interactive setup process, hand-held style 🫶

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

---

Impossible Cloud 🌈

Impossible Cloud (https://www.impossiblecloud.com/) is a European S3-compatible object storage provider with regions in Europe and the US. Very demure, very European 🇪🇺

Heads up bestie, this one matters: Impossible Cloud does not preserve the Cache-Control, Content-Disposition, Content-Encoding or Content-Language system metadata fields on retrieval, even when they were set at upload time. And because the Content-Encoding response header is also dropped, the --s3-decompress flag has no effect on objects stored there 😭 Other metadata such as Content-Type and the modification time round-trip normally, so those are fine.

Here's an example of making an Impossible Cloud 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

…and the transcript just keeps rolling, bestie. Here's the rest of the Impossible Cloud setup, every line of it 👇

              Enter name for new remote.
              name> my-impossible-cloud
              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, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, Hetzner, HuaweiOBS, IBMCOS, IDrive, ImpossibleCloud, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, Storj, Synology, TencentCOS, Wasabi, Qiniu 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 / Impossible Cloud Object Storage
                 \ (ImpossibleCloud)
              [snip]
              provider> ImpossibleCloud
              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> 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_KEY
              Option region.
              Region to connect to.
              Choose a number from below, or type in your own value.
              Press Enter to leave empty.
               1 / Frankfurt, Germany
                 \ (eu-central-2)
               2 / Amsterdam, Netherlands
                 \ (eu-west-1)
               3 / London, UK
                 \ (eu-west-2)
               4 / Paris, France
                 \ (eu-west-3)
               5 / Poznań, Poland
                 \ (eu-east-1)
               6 / Copenhagen, Denmark
                 \ (eu-north-1)
               7 / New York, USA
                 \ (us-east-1)
              region> 1
              Option endpoint.
              Endpoint for Impossible Cloud Object Storage
              Choose a number from below, or type in your own value.
              Press Enter to leave empty.
               1 / Frankfurt, Germany
                 \ (eu-central-2.storage.impossibleapi.net)
               2 / Amsterdam, Netherlands
                 \ (eu-west-1.storage.impossibleapi.net)
               3 / London, UK
                 \ (eu-west-2.storage.impossibleapi.net)
               4 / Paris, France
                 \ (eu-west-3.storage.impossibleapi.net)
               5 / Poznań, Poland
                 \ (eu-east-1.storage.impossibleapi.net)
               6 / Copenhagen, Denmark
                 \ (eu-north-1.storage.impossibleapi.net)
               7 / New York, USA
                 \ (us-east-1.storage.impossibleapi.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>
              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)
              acl>
              Edit advanced config?
              y) Yes
              n) No (default)
              y/n>
              Configuration complete.
              Options:
              - type: s3
              - provider: ImpossibleCloud
              - access_key_id: ACCESS_KEY
              - secret_access_key: SECRET_KEY
              - region: eu-central-2
              - endpoint: eu-central-2.storage.impossibleapi.net
              Keep this "my-impossible-cloud" remote?
              y) Yes this is OK (default)
              e) Edit this remote
              d) Delete this remote
              y/e/d>
              Current remotes:

              Name                 Type
              ====                 ====
              my-impossible-cloud  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>

and literally this is what your config file ends up looking like, no cap 💅

       [my-impossible-cloud]
       type = s3
       provider = ImpossibleCloud
       access_key_id = ACCESS_KEY
       secret_access_key = SECRET_KEY
       region = eu-central-2
       endpoint = eu-central-2.storage.impossibleapi.net
       acl = private

---

🌸 Intercolo Object Storage 🌸

Intercolo Object Storage (https://intercolo.de/object-storage) is giving GDPR-compliant, transparently priced, S3-compatible cloud storage, and it's hosted in Frankfurt, Germany. Immaculate. 🇩🇪

ok so here's a lil example of making a configuration for Intercolo.

First run:

rclone config

and it's gonna walk you through an interactive setup process, hand in hand, like a bestie 🫶

       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> intercolo

       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 / Intercolo Object Storage
          \ (Intercolo)
       [snip]
       provider> Intercolo

       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> false

       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_KEY

       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-fra)
       region> 1

       Option endpoint.
       Endpoint for Intercolo Object Storage.
       Choose a number from below, or type in your own value.
       Press Enter to leave empty.
        1 / Frankfurt, Germany
          \ (de-fra.i3storage.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>

       Edit advanced config?
       y) Yes
       n) No (default)
       y/n> n

       Configuration complete.
       Options:
       - type: s3
       - provider: Intercolo
       - access_key_id: ACCESS_KEY
       - secret_access_key: SECRET_KEY
       - region: de-fra
       - endpoint: de-fra.i3storage.com
       Keep this "intercolo" remote?
       y) Yes this is OK (default)
       e) Edit this remote
       d) Delete this remote
       y/e/d> y

and this is what the config file says afterwards, iconic ✨

       [intercolo]
       type = s3
       provider = Intercolo
       access_key_id = ACCESS_KEY
       secret_access_key = SECRET_KEY
       region = de-fra
       endpoint = de-fra.i3storage.com

---

💜 IONOS Cloud 💜

IONOS S3 Object Storage (https://cloud.ionos.com/storage/object-storage) is a service offered by IONOS for storing and accessing unstructured data. To connect to the service, you're gonna need an access key and a secret key — those live in the Data Center Designer (https://dcd.ionos.com/), you get there by selecting Manager resources > Object Storage Key Manager. Slay, go fetch them 🎀

Here's 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:

okay so you're staring at the storage picker, bestie — let's pick s3 and keep it moving 💅

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

Now type IONOS — that's the provider we're doing here:

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

Then just smash that Enter to take the default, which is Enter AWS credentials in the next step:

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>

Drop in your Access Key and Secret key, okay? ✨ You can grab both from the Data Center Designer (https://dcd.ionos.com/) — click the menu "Manager resources" / "Object Storage Key Manager". iykyk.

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

Pick the region where your bucket actually lives, queen 👑:

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

And then the endpoint from that same region — they gotta match, fr fr:

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

Now hit Enter for the default, or pick whichever ACL setting your heart desires:

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.
[snip]
acl>

Press Enter again to bounce past the advanced config — no notes, it's giving minimal 💅:

Edit advanced config?
y) Yes
n) No (default)
y/n>

Then Enter to save the whole thing, and q to dip out of the config 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

Done! 🎀 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:

3. Copy a file from local to remote

rclone copy /Users/file.txt ionos-fra:my-bucket

4. 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

---

🌸 Leviia Cloud Object Storage 🌸

Leviia Object Storage (https://www.leviia.com/object-storage/), backup and secure your data in a 100% French cloud, independent of GAFAM.. 🥐

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

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

6. Select endpoint for Leviia.

   / The default endpoint
 1 | Leviia.
   \ (s3.leviia.com)
[snip]
endpoint> 1

7. Choose 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.
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> 1
Edit advanced config? (y/n)
y) Yes
n) No (default)
y/n> n
Remote config
--------------------
[leviia]
- 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 🦋

Here's an example of making a Liara Object Storage (https://liara.ir/landing/object-storage) configuration. First run:

rclone config

This will guide you through an interactive setup process.

okay bestie so we're mid-rclone config for Liara and the wizard is doing its lil thing 💅 the whole vibe is ✨interactive✨ and here's literally every keystroke, no cap:

              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 boom — your config file is gonna end up looking exactly like this, fr fr 🫶

              [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 🌈

okay so if you're setting up a Linode Object Storage (https://www.linode.com/products/object-storage/) config, it goes a lil something like this. kick it off with:

rclone config

and it's gonna hold your hand through the whole interactive setup, bestie 🎀

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

              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

and your config file ends up looking like this 💜

              [linode]
              type = s3
              provider = Linode
              access_key_id = ACCESS_KEY
              secret_access_key = SECRET_ACCESS_KEY
              endpoint = eu-central-1.linodeobjects.com

heads up babes 🌸 Linode Object Storage is Ceph-backed. rclone defaults sign_accept_encoding to false for this provider so that SigV4 requests don't fail with SignatureDoesNotMatch (peep the Ceph section 👀).

---

🍓 Magalu 🍓

want a Magalu Object Storage (https://magalu.cloud/object-storage/) config? iconic, let's go. first run:

rclone config

and the wizard's got you, no thoughts head empty, just follow along ✨

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

magalu, part two — the saga continues 💅

Okay so we're still in the middle of the Magalu rclone config interview and it is still asking questions, because of course it is. Here's the rest of the convo, bestie:

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

quick note on that acl question — if you hand it an empty string, rclone does not add an X-Amz-Acl: header at all, and the default private gets used instead. And remember the ACL is a fresh write, not a copy — S3 doesn't carry the source's ACL over during a server-side copy. 🫶

And boom, the config file ends up looking like this:

[magalu]
type = s3
provider = Magalu
access_key_id = ACCESS_KEY
secret_access_key = SECRET_ACCESS_KEY
endpoint = br-ne1.magaluobjects.com

---

MEGA S4 🌈

MEGA S4 Object Storage (https://mega.io/objectstorage) is an S3 compatible object storage system. It's got one single pricing tier, no extra charges for data transfers or API requests, and it's included in existing Pro plans. No cap, that's a vibe. 😌

Here's an example of making a configuration. First run:

rclone config

and it'll walk you through the whole interactive setup process, like so:

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> megas4

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,... Mega, ...
   \ (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 / MEGA S4 Object Storage
   \ (Mega)
[snip]
provider> Mega

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> XXX

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> XXX

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 / Mega S4 eu-central-1 (Amsterdam)
   \ (s3.eu-central-1.s4.mega.io)
 2 / Mega S4 eu-central-2 (Bettembourg)
   \ (s3.eu-central-2.s4.mega.io)
 3 / Mega S4 ca-central-1 (Montreal)
   \ (s3.ca-central-1.s4.mega.io)
 4 / Mega S4 ca-west-1 (Vancouver)
   \ (s3.ca-west-1.s4.mega.io)
endpoint> 1

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: Mega
- access_key_id: XXX
- secret_access_key: XXX
- endpoint: s3.eu-central-1.s4.mega.io
Keep this "megas4" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

Look at those endpoint options — Amsterdam, Bettembourg, Montreal, Vancouver. Pick your city, pick your vibe. 🌍✨ And that leaves the config file looking like:

[megas4]
type = s3
provider = Mega
access_key_id = XXX
secret_access_key = XXX
endpoint = s3.eu-central-1.s4.mega.io

---

Minio 🐙

Minio (https://minio.io/) is an object storage server built for cloud application developers and devops.

It's super easy to install and it gives you an S3 compatible server that rclone can talk to. Obsessed.

To use it, install Minio following the instructions here (https://docs.minio.io/docs/minio-quickstart-guide).

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

Those details need to go into rclone config like this. Note that it is important to put the region in as stated above. Don't skip it, bestie, it matters:

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 you're set up, for example, to copy files into a bucket:

rclone copy /path/to/files minio:bucket

slay. 🎀

---

Netease NOS 🧚

For Netease NOS, configure as per the configurator — just run rclone config setting the provider to Netease. This will automatically set force_path_style = false, which is necessary for it to run properly. It just does it for you, no notes. 💖

---

Outscale 🌸

OUTSCALE Object Storage (OOS) (https://en.outscale.com/storage/outscale-object-storage/) 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 (https://docs.outscale.com/en/userguide/OUTSCALE-Object-Storage-OOS.html).

Here's an example of an OOS configuration that you can paste straight 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

Or you can also run rclone config to go through the interactive setup process instead, if that's more your energy:

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

(psst — the snip lines are just the long option lists getting trimmed in the docs, that's not rclone hiding anything from you, iykyk 💜)

...okay bestie we were literally mid-outscale setup, so let's just keep the transcript rolling ✨

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

and that's the whole <hotpink>outscale</hotpink> remote, slayed 🎀 peep the receipts at the end: it spat out endpoint: oos.eu-west-2.outscale.com because you picked 1 for both region (Paris, France → eu-west-2) and endpoint (Outscale EU West 2 (Paris)).

also note the acl menu is literally clipped with [snip] in the docs — like, they said "you get the idea" 😭 — but don't worry, the next provider spells out the entire canned-ACL menu for you, so stay tuned.

---

🦋 OVHcloud 🦋

OVHcloud Object Storage (https://www.ovhcloud.com/en-ie/public-cloud/object-storage/) is an S3-compatible general-purpose object storage platform and it's available in all OVHcloud regions, which is giving coverage, honestly 💅

to actually use the platform you're gonna need an access key and a secret key. want the full lore on how to interact with it? the documentation lives at https://ovh.to/8stqhuo 🫶

here's an example of making an OVHcloud Object Storage configuration with rclone config ✨

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> ovhcloud-rbx

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, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, OVHcloud, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, Storj, Synology, TencentCOS, Wasabi, Qiniu and others
   \ (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 / OVHcloud Object Storage
   \ (OVHcloud)
[...]
provider> OVHcloud

okay so <purple>Storage</purple> is always the mega-list of S3-compliant providers (it's ✨long✨, hence the [...]), and then provider is where you pick your actual vibe. this bestie went with OVHcloud. the XX bits are just placeholder numbers standing in for "wherever it lands in the list", iykyk.

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> my_access

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> my_secret

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 / Gravelines, France
   \ (gra)
 2 / Roubaix, France
   \ (rbx)
 3 / Strasbourg, France
   \ (sbg)
 4 / Paris, France (3AZ)
   \ (eu-west-par)
 5 / Frankfurt, Germany
   \ (de)
 6 / London, United Kingdom
   \ (uk)
 7 / Warsaw, Poland
   \ (waw)
 8 / Beauharnois, Canada
   \ (bhs)
 9 / Toronto, Canada
   \ (ca-east-tor)
10 / Singapore
   \ (sgp)
11 / Sydney, Australia
   \ (ap-southeast-syd)
12 / Mumbai, India
   \ (ap-south-mum)
13 / Vint Hill, Virginia, USA
   \ (us-east-va)
14 / Hillsboro, Oregon, USA
   \ (us-west-or)
15 / Roubaix, France (Cold Archive)
   \ (rbx-archive)
region> 2

Option endpoint.
Endpoint for OVHcloud Object Storage.
Choose a number from below, or type in your own value.
Press Enter to leave empty.
 1 / OVHcloud Gravelines, France
   \ (s3.gra.io.cloud.ovh.net)
 2 / OVHcloud Roubaix, France
   \ (s3.rbx.io.cloud.ovh.net)
 3 / OVHcloud Strasbourg, France
   \ (s3.sbg.io.cloud.ovh.net)
 4 / OVHcloud Paris, France (3AZ)
   \ (s3.eu-west-par.io.cloud.ovh.net)
 5 / OVHcloud Frankfurt, Germany
   \ (s3.de.io.cloud.ovh.net)
 6 / OVHcloud London, United Kingdom
   \ (s3.uk.io.cloud.ovh.net)
 7 / OVHcloud Warsaw, Poland
   \ (s3.waw.io.cloud.ovh.net)
 8 / OVHcloud Beauharnois, Canada
   \ (s3.bhs.io.cloud.ovh.net)
 9 / OVHcloud Toronto, Canada
   \ (s3.ca-east-tor.io.cloud.ovh.net)
10 / OVHcloud Singapore
   \ (s3.sgp.io.cloud.ovh.net)
11 / OVHcloud Sydney, Australia
   \ (s3.ap-southeast-syd.io.cloud.ovh.net)
12 / OVHcloud Mumbai, India
   \ (s3.ap-south-mum.io.cloud.ovh.net)
13 / OVHcloud Vint Hill, Virginia, USA
   \ (s3.us-east-va.io.cloud.ovh.us)
14 / OVHcloud Hillsboro, Oregon, USA
   \ (s3.us-west-or.io.cloud.ovh.us)
15 / OVHcloud Roubaix, France (Cold Archive)
   \ (s3.rbx-archive.io.cloud.ovh.net)
endpoint> 2

fifteen regions and fifteen endpoints, one-to-one, no cap 🧚 they even line up numerically, which is so satisfying ngl. env_auth> 1 means "imma type my creds in right now" — that's the false option — and 2 (the true one) is the one that says "go fetch them from the environment (env vars or IAM)". also, env_auth only even matters if access_key_id and secret_access_key are blank, so if you're filling them in like this bestie did, it's just vibes.

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.
   \ (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

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: OVHcloud
- access_key_id: my_access
- secret_access_key: my_secret
- region: rbx
- endpoint: s3.rbx.io.cloud.ovh.net
- acl: private
Keep this "ovhcloud-rbx" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

here's the full ACL menu the Outscale section clipped out, bestie 👑 and okay let's talk about it for a sec:

• acl is the canned ACL used when creating buckets and storing or copying objects. it's used for creating objects, and if bucket_acl isn't set, for creating buckets too.
• it's applied when server-side copying objects, because S3 doesn't copy the ACL from the source — it writes a fresh one instead. periodt.
• if acl is an empty string then no X-Amz-Acl: header is added at all and the default (private) gets used.

heads up: option 3 (public-read-write) — "Granting this on a bucket is generally not recommended." 💀 like the docs are being polite but that's a no from me. and options 5 (bucket-owner-read) and 6 (bucket-owner-full-control) both come with "If you specify this canned ACL when creating a bucket, Amazon S3 ignores it." so, y'know. noted.

then Edit advanced config? → n (default), and it hands you the final summary. y/e/d> y = keep this remote, she's a keeper 💖

your configuration file should now look like this:

[ovhcloud-rbx]
type = s3
provider = OVHcloud
access_key_id = my_access
secret_access_key = my_secret
region = rbx
endpoint = s3.rbx.io.cloud.ovh.net
acl = private

and that's <rainbow>ovhcloud-rbx</rainbow> all set up and looking absolutely correct in your config file 🦋💅

🌸 Petabox 🌸

ok bestie so here's the whole vibe of setting up a Petabox (https://petabox.io/) config. First thing you do is run:

rclone config

and then it just walks you through the whole interactive setup, no cap:

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 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 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.
   \ (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

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 after all that, your config file is just sitting there looking like this 💅

[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

---

💜 Pure Storage FlashBlade 💜

Pure Storage FlashBlade (https://www.purestorage.com/products/unstructured-data-storage.html) is like, a high performance S3-compatible object store. main character storage fr.

FlashBlade supports most modern S3 features, including:

• ListObjectsV2
• Multipart uploads with AWS-compatible ETags
• Advanced checksum algorithms (SHA256, CRC32, CRC32C) with trailer support (Purity//FB 4.4.2+)
• Object versioning and lifecycle management
• Virtual hosted-style requests (requires DNS configuration)

So to configure rclone for Pure Storage FlashBlade, first run:

rclone config

and it'll hold your hand through the whole interactive setup:

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> flashblade

Option Storage.
Type of storage to configure.
Choose a number from below, or type in your own value.
[snip]
 4 / Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, FlashBlade, GCS, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Rclone, Scaleway, SeaweedFS, Selectel, Storj, Synology, TencentCOS, Wasabi, Qiniu 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]
 9 / Pure Storage FlashBlade Object Storage
   \ (FlashBlade)
[snip]
provider> FlashBlade

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_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> SECRET_ACCESS_KEY

Option endpoint.
Endpoint for S3 API.
Required when using an S3 clone.
Enter a value. Press Enter to leave empty.
endpoint> https://s3.flashblade.example.com

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: FlashBlade
- access_key_id: ACCESS_KEY_ID
- secret_access_key: SECRET_ACCESS_KEY
- endpoint: https://s3.flashblade.example.com
Keep this "flashblade" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

And boom, that leaves you with this stored in ~/.config/rclone/rclone.conf:

[flashblade]
type = s3
provider = FlashBlade
access_key_id = ACCESS_KEY_ID
secret_access_key = SECRET_ACCESS_KEY
endpoint = https://s3.flashblade.example.com

🫶 Note bestie: the FlashBlade endpoint should be the S3 data VIP. For virtual-hosted style requests, make sure your DNS is set up right — subdomains of the endpoint hostname should resolve to a FlashBlade data VIP. So like, if your endpoint is https://s3.flashblade.example.com, then bucket-name.s3.flashblade.example.com should also resolve to that data VIP. iykyk 💀

---

🦋 Qiniu Cloud Object Storage (Kodo) 🦋

Qiniu Cloud Object Storage (Kodo) (https://www.qiniu.com/en/products/kodo), 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.

okay bestie, the wizard's still mid-glow-up and it just asked which storage type you want — and obviously you're picking s3 🫶

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. 💫 It's literally in the list, just scroll to it.

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. 🔑 (access_key_id and secret_access_key, same energy.)

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 regions.

Choose a number from below, or type in your own value
   / 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

and then rclone gets very specific about it: 🌸

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

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

side note: location_constraint is only used when creating buckets, ok? so don't stress about it later 💅

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

(yes the storage-class prompt literally says Tencent COS in the middle of the Qiniu section — that's just what it prints, don't @ me 😭)

---

🌸 FileLu S5 🌸

FileLu S5 Object Storage (https://s5lu.com) is an S3-compatible object storage situation. It's giving multiple region options (Global, US-East, EU-Central, AP-Southeast, and ME-Central) — all while using a single endpoint (s5lu.com). FileLu S5 is designed for scalability, security, and simplicity, with predictable pricing and no hidden charges for data transfers or API requests. obsessed. ✨

Here's an example of making a 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

Enter name for new remote.
name> s5lu

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,... FileLu, ...
   \ (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 / FileLu S5 Object Storage
   \ (FileLu)
[snip]
provider> FileLu

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> XXX

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> XXX

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 / Global
   \ (global)
 2 / North America (US-East)
   \ (us-east)
 3 / Europe (EU-Central)
   \ (eu-central)
 4 / Asia Pacific (AP-Southeast)
   \ (ap-southeast)
 5 / Middle East (ME-Central)
   \ (me-central)
region> 1

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: FileLu
- access_key_id: XXX
- secret_access_key: XXX
- endpoint: s5lu.com
Keep this "s5lu" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

This will leave the config file looking like this. 📝

[s5lu]
type = s3
provider = FileLu
access_key_id = XXX
secret_access_key = XXX
endpoint = s5lu.com

---

🌈 Rabata 🌈

Rabata (https://rabata.io) is an S3-compatible secure cloud storage service that offers flat, transparent pricing (no API request fees) while supporting standard S3 APIs. ngl it's suitable for backup, application storage, media workflows, and archive use cases. 🎀

⚠️ real talk: server side copy is not implemented with Rabata, which also means modification time of objects cannot be updated. periodt, no notes.

Rclone config: 💜

rclone config
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> Rabata

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 / Rabata Cloud Storage
   \ (Rabata)
[snip]
provider> Rabata

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> 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> SECRET_ACCESS_KEY

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 / EU (Ireland)
   \ (eu-west-1)
 3 / EU (London)
   \ (eu-west-2)
region> 3

Option endpoint.
Endpoint for Rabata Object Storage.
Choose a number from below, or type in your own value.
Press Enter to leave empty.
 1 / US East (N. Virginia)
   \ (s3.us-east-1.rabata.io)
 2 / EU West (Ireland)
   \ (s3.eu-west-1.rabata.io)
 3 / EU West (London)
   \ (s3.eu-west-2.rabata.io)
endpoint> 3

Option location_constraint.
location 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 / EU (Ireland)
   \ (eu-west-1)
 3 / EU (London)
   \ (eu-west-2)
location_constraint> 3

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: Rabata
- access_key_id: ACCESS_KEY_ID
- secret_access_key: SECRET_ACCESS_KEY
- region: eu-west-2
- endpoint: s3.eu-west-2.rabata.io
- location_constraint: eu-west-2
Keep this "rabata" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

Current remotes:

Name                 Type
====                 ====
rabata               s3

ok bestie that's the whole Rabata glow-up complete, remote saved, we love to see it 💖

---

RackCorp</p> 🌸

RackCorp Object Storage (https://www.rackcorp.com/storage/s3storage) 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. sovereignty queen behaviour honestly 👑

Before you can use RackCorp Object Storage, you'll need to sign up (https://www.rackcorp.com/signup) for an account on our portal (https://portal.rackcorp.com). 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, no cap. For details see the rclone serve s3 (https://rclone.org/commands/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 (https://rclone.org/commands/rclone_serve_s3/#bugs) which will be fixed in due course. 💀 it's a whole workaround, just leave it in, bestie.

---

Scaleway ✨

Scaleway (https://www.scaleway.com/object-storage/) 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 (https://www.scaleway.com/en/glacier-cold-storage/) 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.

🚨 bestie listen — 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). Fr fr, they are locked away until you go get them. 😭

---

Scality 💜

Scality (https://www.scality.com/) RING and ARTESCA both expose an S3-compatible object storage API that works with rclone using s3 as the type and Scality as the provider.

Both products are S3 clones, so you always need to set the endpoint to the S3 API of your deployment (the S3 Connector service on RING, or the S3 data-service endpoint on ARTESCA). The Scality provider uses path-style addressing (endpoint/bucket/key) which is supported out of the box and does not require any wildcard/virtual-host DNS entries. no DNS gymnastics required, we stay winning 🧚

Get your access key, secret key and endpoint from your Scality administrator (on ARTESCA these are created per account under Identity > Accounts in the UI; on RING they are created with vaultclient or the S3 Console).

Here is an example of making a Scality 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

Enter name for new remote.
name> scality

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, ...Scaleway, Scality, SeaweedFS, ...
   \ (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 / Scality (RING / ARTESCA)
   \ (Scality)
[snip]
provider> Scality

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> S3_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> S3_SECRET_KEY

Option region.
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>

Option endpoint.
Endpoint for S3 API.
Required when using an S3 clone.
Enter a value. Press Enter to leave empty.
endpoint> https://s3.example.com

Edit advanced config?
y) Yes
n) No (default)
y/n>

Configuration complete.
Options:
- type: s3
- provider: Scality
- access_key_id: S3_ACCESS_KEY
- secret_access_key: S3_SECRET_KEY
- endpoint: https://s3.example.com
Keep this "scality" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

iconic. we ate that entire config walkthrough and left no crumbs 💅

This will leave the config file looking like this.

  [scality]
  type = s3
  provider = Scality
  access_key_id = S3_ACCESS_KEY
  secret_access_key = S3_SECRET_KEY
  endpoint = https://s3.example.com

---

🌊 Seagate Lyve Cloud 💙

Seagate Lyve Cloud (https://www.seagate.com/gb/en/services/cloud/storage/) is an S3 compatible object storage platform from Seagate (https://seagate.com/) and it's built for enterprise use, bestie. Big corporate energy, but the config is chill. 🏢✨

Here's a whole config run-through for a remote called remote — you can literally name yours whatever you want, boo. 🫶 But heads up: to create an access key and secret key you're gonna need to make a service account first. No shortcuts there.

$ 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

Okay so step one, pick the 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

Then choose LyveCloud as your S3 provider — it's right there in the list, go get it:

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

Now just take the default (aka smash that enter key 💅) so you can type your access key and secret straight into 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 the region blank, bestie, don't overthink it:

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>

Now the important one — enter your Lyve Cloud endpoint. 🫣 This field cannot be kept empty. Like, you literally cannot skip it, so don't even try:

Endpoint for Lyve Cloud S3 API.
Required when using an S3 clone.
Please type in your LyveCloud endpoint.
Examples:
- s3.us-west-1.{account_name}.lyve.seagate.com (US West 1 - California)
- s3.eu-west-1.{account_name}.lyve.seagate.com (US West 1 - Ireland)
Enter a value.
endpoint> s3.us-west-1.global.lyve.seagate.com

Leave the location constraint blank too:

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>

And pick the default ACL, which is private:

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 bestie, your config file should end up looking exactly like this:

[remote]
type = s3
provider = LyveCloud
access_key_id = XXX
secret_access_key = YYY
endpoint = s3.us-east-1.lyvecloud.seagate.com

---

🌿 SeaweedFS 🌱

SeaweedFS (https://github.com/chrislusf/seaweedfs/) is a distributed storage system for blobs, objects, files, and data lake — iconic behavior, honestly — with O(1) disk seek and a scalable file metadata store. It's got an S3 compatible object storage interface. ✨

And plot twist: SeaweedFS can also act as a gateway to remote S3 compatible object store (https://github.com/chrislusf/seaweedfs/wiki/Gateway-to-Remote-Object-Storage) so it can cache data and metadata with asynchronous write back — that's for fast local speed and to minimize access cost. Caching queen behavior, we love to see it. 👑

So let's 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"
      ]
    }
  ]
}

Then to use rclone with SeaweedFS, that config above should end up looking something like this in your rclone config:

[seaweedfs_s3]
type = s3
provider = SeaweedFS
access_key_id = any
secret_access_key = any
endpoint = localhost:8333

And once it's all set up, for example to copy files into a bucket:

rclone copy /path/to/files seaweedfs_s3:foo

Slay. That's it. 💖

---

🧊 Selectel 💠

Selectel Cloud Storage (https://selectel.ru/services/cloud/storage/) is an S3 compatible storage system packing triple redundancy storage, automatic scaling, high availability and a comprehensive IAM system. Triple redundancy?? Obsessed. 😭✨

Selectel has a whole section on their website dedicated to configuring rclone (https://docs.selectel.ru/en/cloud/object-storage/tools/rclone/) that shows you how to make the right API keys. Go check it, bestie.

From rclone v1.69 Selectel is a supported operator — so please choose the Selectel provider type, okay? No cap.

Also lowkey important: use "vHosted" access for the buckets (which is the recommended default), not "path style". Don't be out here picking path style, iykyk.

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 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 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:

[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

Ate that up, no crumbs. 🍓

---

🖥️ Servercore 🛡️

Servercore Object Storage (https://servercore.com/services/object-storage/) is an S3 compatible object storage system that gives you scalable and secure storage solutions for businesses of all sizes. Big, small, whatever — it's giving flexible. ✨

Here's the rclone config example:

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> servercore

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 ..., Servercore, ...
   \ (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 / Servercore Object Storage
   \ (Servercore)
[snip]
provider> Servercore

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 where your is data stored.
Choose a number from below, or type in your own value.
Press Enter to leave empty.
 1 / St. Petersburg
   \ (ru-1)
 2 / Moscow
   \ (gis-1)
 3 / Moscow
   \ (ru-7)
 4 / Tashkent, Uzbekistan
   \ (uz-2)
 5 / Almaty, Kazakhstan
   \ (kz-1)
region> 1

Option endpoint.
Endpoint for Servercore 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)
 2 / Moscow
   \ (s3.gis-1.storage.selcloud.ru)
 3 / Moscow
   \ (s3.ru-7.storage.selcloud.ru)
 4 / Tashkent, Uzbekistan
   \ (s3.uz-2.srvstorage.uz)
 5 / Almaty, Kazakhstan
   \ (s3.kz-1.srvstorage.kz)
endpoint> 1

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: Servercore
- access_key_id: ACCESS_KEY
- secret_access_key: SECRET_ACCESS_KEY
- region: ru-1
- endpoint: s3.ru-1.storage.selcloud.ru
Keep this "servercore" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

and boom, that's the whole Servercore glow-up bestie, look at that final config being all neat and tidy 💅

---

🌈 Spectra Logic 🌈

Spectra Logic (https://www.spectralogic.com/blackpearl-nearline-object-gateway) is an on-prem S3-compatible object storage gateway that exposes local object storage and policy-tiers data to Spectra tape and public clouds under a single namespace for backup and archiving. one namespace to rule them all, fr fr 🎀

The S3 compatible gateway is configured using rclone config with a type of s3 and with a provider name of SpectraLogic. Here is an example run of the configurator.

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> spectralogic

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 ..., SpectraLogic, ...
   \ (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 / SpectraLogic BlackPearl
   \ (SpectraLogic)
[snip]
provider> SpectraLogic

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 endpoint.
Endpoint for S3 API.
Required when using an S3 clone.
Enter a value. Press Enter to leave empty.
endpoint> https://bp.example.com

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: s3
- provider: SpectraLogic
- access_key_id: ACCESS_KEY
- secret_access_key: SECRET_ACCESS_KEY
- endpoint: https://bp.example.com
Keep this "spectratest" 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:

[spectratest]
type = s3
provider = SpectraLogic
access_key_id = ACCESS_KEY
secret_access_key = SECRET_ACCESS_KEY
endpoint = https://bp.example.com

not the name mismatch between the remote you typed and the one you keep, that's just how the example rolls, don't come for me 🙈

---

🦋 Storj 🦋

Storj is a decentralized cloud storage which can be used through its native protocol or an S3 compatible gateway. two doors, one vibe ✨

The S3 compatible gateway is configured using rclone config with a type of s3 and with a provider name of Storj. Here is an example run of the configurator.

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

Note that s3 credentials are generated when you create an access grant (https://docs.storj.io/dcs/api-reference/s3-compatible-gateway#usage). so like, go make the grant first bestie, the keys literally don't exist until you do 🔑

💀 Backend quirks 💀

• --chunk-size is forced to be 64 MiB or greater. This will use more memory than the default of 5 MiB. (yes, more RAM, that's the tradeoff, iykyk)
• Server side copy is disabled as it isn't currently supported in the gateway.
• GetTier and SetTier are not supported.

😭 Backend bugs 😭

Due to issue #39 (https://github.com/storj/gateway-mt/issues/39) uploading multipart files via the S3 gateway causes them to lose their metadata. For rclone's purpose this means that the modification time is not stored, nor is any MD5SUM (if one is available from the source). the metadata just… evaporates 💀

This has the following consequences:

• Using rclone rcat will fail as the metadata doesn't match after upload
• Uploading files with rclone mount will fail for the same reason
  • This can worked around by using --vfs-cache-mode writes or --vfs-cache-mode full or setting --s3-upload-cutoff large
• Files uploaded via a multipart upload won't have their modtimes
  • This will mean that rclone sync will likely keep trying to upload files bigger than --s3-upload-cutoff
  • This can be worked around with --checksum or --size-only or setting --s3-upload-cutoff large
  • The maximum value for --s3-upload-cutoff is 5GiB though

One general purpose workaround is to set --s3-upload-cutoff 5G. This means that rclone will upload files smaller than 5GiB as single parts. Note that this can be set in the config file with upload_cutoff = 5G or configured in the advanced settings. If you regularly transfer files larger than 5G then using --checksum or --size-only in rclone sync is the recommended workaround. screenshot this section honestly 🫶

🧚 Comparison with the native protocol 🧚

Use the the native protocol 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. (rip your bandwidth, but the downloads are chef's kiss 👑)

Use this backend and the S3 compatible Hosted Gateway 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.

For more detailed comparison please check the documentation of the storj backend. go read it, it's giving thorough ✨

---

🍓 Synology C2 Object Storage 🍓

Synology C2 Object Storage (https://c2.synology.com/en-global/object-storage/overview) provides a secure, S3-compatible, and cost-effective cloud storage solution without API request, download fees, and deletion penalty. no fees?? no penalties?? periodt 💅

The way this works is you point rclone config at a type of s3 and a provider name of Synology, and boom, you're in. Here's an actual run of the configurator so you know exactly what's coming bestie 🎀

First run:

rclone config

This right here is gonna walk you through the whole interactive setup process, step by step, no jumpscares:

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

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

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

---

🌸 Tencent COS 🌸

Tencent Cloud Object Storage (COS) (https://intl.cloud.tencent.com/product/cos) is a distributed storage service that Tencent Cloud offers up for unstructured data. And like, it's secure, it's stable, it's massive, it's convenient, low-delay and low-cost — it's giving full package deal ✨

Wanna get rclone talking to Tencent COS? Follow along, bestie:

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 config 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. Drop in your SecretId and SecretKey from Tencent Cloud 🔑

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. Pick the endpoint for Tencent COS — this is the standard endpoint for each 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 your 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

---

🦋 Tencent COS Global Acceleration Endpoint 🦋

Okay so when you're using the Global Acceleration Endpoint (cos.accelerate.myqcloud.com), rclone is gonna automatically set no_check_bucket = true for you — because this acceleration endpoint simply doesn't support the CreateBucket call, and that's the call rclone leans on to make sure a bucket exists. No bucket-creating energy here, bestie 💅

Global Acceleration is a per-bucket feature, so the move is: first create the bucket in one physical region, then go enable it in the Tencent Cloud console. Order matters, iykyk 🌈

---

👑 US3 👑

US3 (https://www.ucloud.cn/site/product/ufile.html) Object Storage is a service that provides cloud storage for unstructured files for internet applications.

To configure access to US3, follow the steps below:

1. First run:

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 US3.

name> US3

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 US3 provider.

Choose a number from below, or type in your own value.
XX / Amazon Web Services (AWS) S3
   \ (AWS)
[snip]
XX / UCloud Object Storage (US3)
   \ (US3)
[snip]
provider> US3

5. Enter your SecretId and SecretKey of US3.

…and the configurator just keeps going bestie, no breaks:

• 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> 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.
   • 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 / North China (Beijing 2) — "s3-cn-bj.ufileos.com"
     • 2 / North China (Ulanqab) — "s3-cn-wlcb.ufileos.com"
     • 3 / Shanghai — "s3-cn-sh2.ufileos.com"
     • 4 / South China (Guangzhou) — "s3-cn-gd.ufileos.com"
     • [snip]
   • endpoint> 1
7. Choose acl and storage class.
   • 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 — and heads up, this ACL is applied when server-side copying objects, because S3 doesn't copy the ACL from the source, it writes a fresh one instead. 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.
     • 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)
   • acl> 1
   • The storage class to use when storing new objects in US3. 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

Then the payoff, and honestly? iconic:

Configuration complete.
Options:
- type: s3
- provider: US3
- access_key_id: xx
- secret_access_key: xx
- endpoint: s3-cn-bj.ufileos.com
- acl: private

Keep this "US3" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y
Current remotes:

Name                 Type
====                 ====
US3                  s3

---

🌸 Wasabi 🌸

Wasabi (https://wasabi.com) 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. 💸✨

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 =

---

🌈 Zadara Object Storage 🌈

Zadara Object Storage (https://www.zadara.com) is a fully-managed, enterprise-grade, S3-compatible storage solution that provides scalable, multi-tenant object storage with flexible deployment options (on-prem, hybrid, or cloud). ✨

Zadara Object Storage can be configured using rclone config with s3 as the type and Zadara as the provider name. Here is an example run of the configurator.

Authentication and endpoint information, including the region field, should be fetched from Zadara's Object Storage management interface

To configure access to Zadara Object Storage, 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> Zadara-Object-Storage

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.

XX / Zadara Object Storage
   \ (Zadara)

provider> Zadara

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> S3_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> S3_SECRET_KEY

Option region.
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.
   / The default region.
 1 | Leave location constraint empty.
   \ (us-east-1)
region>

Option endpoint. Endpoint for S3 API. Required when using an S3 clone. Enter a value. Press Enter to leave empty. endpoint> https://vsa-00000001-public-zadara-cloud-01.zadarazios.com

Edit advanced config? y) Yes n) No (default) y/n>

Configuration complete. Options:

• type: s3
• provider: Zadara
• access_key_id: S3_ACCESS_KEY
• secret_access_key: S3_SECRET_KEY
• endpoint: https://vsa-00000001-public-zadara-cloud-01.zadarazios.com Keep this "Zadara-Object-Storage" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

and boom 💥 your config file ends up looking exactly like this:

[Zadara-Object-Storage] type = s3 provider = Zadara access_key_id = S3_ACCESS_KEY secret_access_key = S3_SECRET_KEY endpoint = https://vsa-00000001-public-zadara-cloud-01.zadarazios.com

---

## 🌈 Zata Object Storage

<lavender>Zata Object Storage</lavender> (https://zata.ai/) is giving secure, S3-compatible cloud storage that's built for scaling and performance, and it's for literally every kind of data-storage need you could have. ✨

First, run:

rclone config

and it will walk you through an interactive setup like this, bestie:

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

Enter name for new remote. name> my zata storage

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.

XX / Zata (S3 compatible Gateway) \ (Zata)

provider> Zata

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 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 region. Region where you can connect with. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / Indore, Madhya Pradesh, India \ (us-east-1) region> 1

Option endpoint. Endpoint for Zata Object Storage. Choose a number from below, or type in your own value. Press Enter to leave empty. 1 / South Asia Endpoint \ (idr01.zata.ai) 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>

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.

\ (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.

\ (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: Zata
• access_key_id: xxx
• secret_access_key: xxx
• region: us-east-1
• endpoint: idr01.zata.ai Keep this "my zata storage" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d>

and then your config file is sitting there looking like this 💅:

[my zata storage] type = s3 provider = Zata access_key_id = xxx secret_access_key = xxx region = us-east-1 endpoint = idr01.zata.ai

---

## 🧚 Zero Services (ZERO-Z3)

<cyan>Zero Services GmbH</cyan> (https://lp.zeroservices.eu/zero-z3/) serves up <lavender>ZERO-Z3</lavender>, S3-compatible object storage hosted in the EU on its very own network (AS215197). It's built on Ceph RADOS Gateway, no cap. 🫶

First, run:

rclone config

and this is the interactive setup process, step by step:

n) New remote n/s/q> n

Enter name for new remote. name> zero-z3

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, ..., ZeroServices, ... and others \ (s3) Storage> s3

Option provider. Choose your S3 provider. [snip] XX / Zero Services GmbH (ZERO-Z3) \ (ZeroServices) provider> ZeroServices

Option env_auth. Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars). 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. access_key_id> ACCESS_KEY

Option secret_access_key. AWS Secret Access Key (password). secret_access_key> SECRET_KEY

Option region. Region to connect to. 1 / Frankfurt 1 \ (zero-fra1) 2 / Frankfurt 2 \ (zero-fra2) 3 / Eyl 1 \ (zero-eyl1) region> 2

Option endpoint. Endpoint for ZERO-Z3. 1 / Frankfurt 1 \ (fra1.s3.zeroservices.eu) 2 / Frankfurt 2 \ (fra.s3.zeroservices.eu) 3 / Eyl 1 \ (eyl1.s3.zeroservices.eu) endpoint> 2

Option acl. Canned ACL used when creating buckets and storing or copying objects. [snip] acl> 1

Edit advanced config? y/n> n

Configuration complete. Options:

• type: s3
• provider: ZeroServices
• access_key_id: ACCESS_KEY
• secret_access_key: SECRET_KEY
• region: zero-fra2
• endpoint: fra.s3.zeroservices.eu Keep this "zero-z3" remote? y/e/d> y

---

## 🧠 Memory usage

okay so the number-one reason rclone eats a ton of memory is <hotpink>one single directory with millions of files in it</hotpink>. Even though s3 doesn't really have the concept of directories, rclone still does its sync directory by directory, because it wants to stay compatible with normal filing systems. 🌸

Rclone loads each directory into memory as rclone objects. Each rclone object takes `0.5k-1k` of memory, so that's approximately `1GB` per `1,000,000` files, and the sync for that directory does **not** start until the whole thing is loaded into memory. So yeah, for huge directories the sync can take a *long* time to even get going. 😭

To sync a directory with `100,000,000` files in it you'd need approximately `100 GB` of memory. At some point the amount of memory becomes difficult to actually provide, so there's a workaround for this (https://github.com/rclone/rclone/wiki/Big-syncs-with-millions-of-files) which involves a bit of scripting. 🐚

And 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 can't determine free space for an rclone mount, and they 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` (https://rclone.org/overview/#optional-features) and `rclone about` (https://rclone.org/commands/rclone_about/).

---

## 🗄️ Archive

The <lavender>Archive</lavender> backend gives you **read only** access to the content of archive files on cloud storage, without downloading the complete archive. Which means you could mount a large archive file and use only the parts of it your application actually needs, instead of having to extract the whole thing first. iconic. ✨

The archive files are recognised by their extension.

- <cyan>Zip</cyan> — `.zip`
- <cyan>Squashfs</cyan> — `.sqfs`

The supported archive file types are cloud friendly — a single file can be found and downloaded without downloading the whole archive. <rainbow>iconic behaviour honestly</rainbow> 🌈

If you just want to create, list or extract archives and don't want to mount them, then bestie, you might find the `rclone archive` commands way more convenient:

- **`rclone archive create`** — https://rclone.org/commands/rclone_archive_create/
- **`rclone archive list`** — https://rclone.org/commands/rclone_archive_list/
- **`rclone archive extract`** — https://rclone.org/commands/rclone_archive_extract/

These commands support a wider range of non cloud friendly archives (but <red>not squashfs</red>, sorry girlies) and they **can't** be used for `rclone mount` or any other rclone commands (like `rclone check`). Different tool for a different job 💅

## ✨ Configuration ✨

This backend is best used without configuration. Zero setup, we love a low-effort queen 🫶

Use it by putting the string `:archive:` in front of another remote, say `remote:dir` to make `:archive:remote:dir`.

Any archives in `remote:dir` will become directories, and any files may be read out of them individually.

For example:

$ rclone lsf s3:rclone/dir 100files.sqfs 100files.zip

Note that `100files.zip` and `100files.sqfs` are now directories:

$ rclone lsf :archive:s3:rclone/dir 100files.sqfs/ 100files.zip/

Which we can look inside:

$ rclone lsf :archive:s3:rclone/dir/100files.zip/ cofofiy5jun gigi hevupaz5z kacak/ kozemof/ lamapaq4 qejahen quhenen2rey soboves8 vibat/ wose xade zilupot

Files **not** in an archive can be read and written as normal. Files **in** an archive can only be read. <yellow>read-only vibes, no writing, no cap</yellow> 📖

The archive backend can also be used in a configuration file. Use the `remote` variable to point to the destination of the archive.

[remote] type = archive remote = s3:rclone/dir/100files.zip

Gives:

$ rclone lsf remote: cofofiy5jun gigi hevupaz5z kacak/ ...

## 🌸 Modification times 🌸

Modification times are preserved with an accuracy depending on the archive type.

$ rclone lsl --max-depth 1 :archive:s3:rclone/dir/100files.zip 12 2025-10-27 14:39:20.000000000 cofofiy5jun 81 2025-10-27 14:39:20.000000000 gigi 58 2025-10-27 14:39:20.000000000 hevupaz5z 6 2025-10-27 14:39:20.000000000 lamapaq4 43 2025-10-27 14:39:20.000000000 qejahen 66 2025-10-27 14:39:20.000000000 quhenen2rey 95 2025-10-27 14:39:20.000000000 soboves8 71 2025-10-27 14:39:20.000000000 wose 76 2025-10-27 14:39:20.000000000 xade 15 2025-10-27 14:39:20.000000000 zilupot

For zip and squashfs files this is `1s`. <lavender>one second of precision, she's doing her best 💜</lavender>

---

## 🎀 Hashes 🎀

Which hash is supported depends on the archive type. Zip files use `CRC32`, Squashfs don't support any hashes. For example:

$ rclone hashsum crc32 :archive:s3:rclone/dir/100files.zip/ b2288554 cofofiy5jun a87e62b6 wose f90f630b xade c7d0ef29 gigi f1c64740 soboves8 cb7b4a5d quhenen2rey 5115242b kozemof/fonaxo afeabd9a qejahen 71202402 kozemof/fijubey5di bd99e512 kozemof/napux ...

Hashes will be checked when the file is read from the archive and used as part of syncing if possible. <mint>integrity check queen ✅</mint>

$ rclone copy -vv :archive:s3:rclone/dir/100files.zip /tmp/100files ... 2025/10/27 14:56:44 DEBUG : kacak/turovat5c/yuyuquk: crc32 = abd05cc8 OK 2025/10/27 14:56:44 DEBUG : kacak/turovat5c/yuyuquk.aeb661dc.partial: renamed to: kacak/turovat5c/yuyuquk 2025/10/27 14:56:44 INFO : kacak/turovat5c/yuyuquk: Copied (new) ...

## 🦋 Zip 🦋

The Zip file format (https://en.wikipedia.org/wiki/ZIP_(file_format)) is a widely used archive format that bundles one or more files and folders into a single file, primarily for easier storage or transmission. It typically uses compression (most commonly the `DEFLATE` algorithm) to reduce the overall size of the archived content. Zip files are supported natively by most modern operating systems.

Rclone does **not** support the following advanced features of Zip files:

- Splitting large archives into smaller parts
- Password protection
- Zstd compression

<pink>so no split zips, no passwords, no zstd — noted bestie, don't come for her 💖</pink>

## 💜 Squashfs 💜

Squashfs is a compressed, read-only file system format primarily used in Linux-based systems. It's designed to compress entire file systems (including files, directories, and metadata) into a single archive file, which can then be mounted and read directly, appearing as a normal directory structure. Because it's read-only and highly compressed, Squashfs is ideal for live CDs/USBs, embedded devices with limited storage, and software package distribution, as it saves space and ensures the integrity of the original files.

Rclone supports the following squashfs compression formats:

- Gzip
- Lzma
- Xz
- Zstd

These are <red>not yet working</red>:

- Lzo — Not yet supported
- Lz4 — Broken with `"error decompressing: lz4: bad magic number"`

Rclone works fastest with large squashfs block sizes. For example:

mksquashfs 100files 100files.sqfs -comp zstd -b 1M

<yellow>big blocks = big speed, iykyk ⚡</yellow>

## 👑 Limitations 👑

Files in the archive backend are **read only**. It isn't possible to create archives with the archive backend yet. However you can create archives with `rclone archive create` (https://rclone.org/commands/rclone_archive_create/).

Only `.zip` and `.sqfs` archives are supported as these are the only common archiving formats which make it easy to read directory listings from the archive without downloading the whole archive.

Internally the archive backend uses the VFS to access files. It isn't possible to configure the internal VFS yet which might be useful. <peach>future feature energy, manifesting 🙈</peach>

## 🌈 Archive Formats 🌈

Here's a table rating common archive formats on their Cloud Optimization, which is based on their ability to access a single file without reading the entire archive.

This capability depends on whether the format has a central index (or "table of contents") that a program can read first to find the exact location of a specific file.

### ✨ Ideas for improvements ✨

Okay so bestie, here's the tea on what could get upgraded someday 👀

- Adding <cyan>ISO</cyan> support would be pretty easy actually, because the library we use, `go-diskfs` (`https://github.com/diskfs/go-diskfs/`), already supports it. 💅
- We could also add `ext4` and `fat32` the same way — but ngl, in my experience those just aren't very common as files, so it's probably not worth the effort. 🙈
- `go-diskfs` can also read partitions, which we could potentially take advantage of. 👑

It would also be possible to add <purple>write support</purple> — but heads up, that would **only** be for creating brand-new archives, **not** for updating existing ones. Periodt.

---

### ✨ Standard options ✨

Here are the Standard options specific to archive (Read archives). 🎀

- **`--archive-remote`** — Remote to wrap to read archives from. 💖

  Normally it should contain a `':'` and a path, like `"myremote:path/to/dir"`, `"myremote:bucket"` or `"myremote:"`.

  If this is left empty, then the archive backend will use the root as the remote. 🌸

  This means you can use `:archive:remote:path` and it will be equivalent to setting `remote="remote:path"`. ✨

  Properties:

  - Config: `remote`
  - Env Var: `RCLONE_ARCHIVE_REMOTE`
  - Type: `string`
  - Required: `false`

---

### ✨ Advanced options ✨

Here are the Advanced options specific to archive (Read archives). 🦋

- **`--archive-description`** — Description of the remote. 💜

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_ARCHIVE_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

### ✨ Metadata ✨

Any metadata supported by the underlying remote is read and written. 🫶

See the metadata (`https://rclone.org/docs/#metadata`) docs for more info. 📚

---

# 👑 Backblaze B2 👑

B2 is Backblaze's cloud storage system (`https://www.backblaze.com/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 🌈

Here is an example of making a b2 configuration. First run

okay so to actually set this up you literally just run:

rclone config

and it walks you through everything, super cozy interactive style. 💖

To authenticate you'll need EITHER your Account ID (a short hex number) **and** your Master Application Key (a long hex number) **OR** an Application Key — and bestie, the Application Key is the recommended method, fr fr. Scroll down for the full tea on generating and using one.

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 now you can use it 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 (https://www.backblaze.com/docs/cloud-storage-application-keys).

You can use these with rclone too 🫶 — you'll need 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, B2 will hit you with `401` errors. 😭

## `--fast-list`

This remote supports `--fast-list`, which lets you use fewer transactions in exchange for more memory. See the rclone docs (https://rclone.org/docs/#fast-list) 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 🚫

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these characters get replaced too:

- **Character** `\` — **Value** `0x5C` — **Replacement** `＼`

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), 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 (https://rclone.org/overview/#features) 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` (https://github.com/rclone/rclone/issues/1767)).

File sizes below `--b2-upload-cutoff` will **always** have an SHA1 regardless of the source. 💅

## 🚀 Transfers 🚀

Backblaze recommends that you do lots 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 definitely too low for Backblaze B2 though.

Note that 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 (https://www.backblaze.com/docs/cloud-storage-file-versions). 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. These can be deleted as required with `delete`.

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.

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 the `--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

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/v4/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` (https://github.com/rclone/rclone/issues/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

## 👀 Viewing versions with `--b2-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

<pink>Showing that the current version is unchanged</pink> — but bestie, older versions? Absolutely visible. 💖 Each of those older ones has the <cyan>UTC date</cyan> that it got uploaded to the server slapped onto it, accurate to the <purple>nearest millisecond</purple>. So like, timestamped to the *millisecond*. Obsessed.

> ⚠️ Heads up though: when you're using `--b2-versions`, **no file write operations are permitted**. Like, at all. So you literally cannot upload files or delete them. It's giving read-only era. No cap.

---

## 🎀 B2 and `rclone link` 🎀

Rclone can generate file share links for <mint>private B2 buckets</mint>. Slay. So you can get one for a single file, like:

./rclone link B2:bucket/path/to/file.txt https://f002.backblazeb2.com/file/bucket/path/to/file.txt?Authorization=xxxxxxxx

or if you run it on a directory, you get this instead:

./rclone link B2:bucket/path https://f002.backblazeb2.com/file/bucket/path?Authorization=xxxxxxxx

And then — the way this works, iykyk — you can take that authorization token (the part of the url from the `?Authorization=` onwards) and use it on <hotpink>any file path under that directory</hotpink>. Bestie, ANY path. 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 <cyan>Standard</cyan> options specific to `b2` (Backblaze B2). 🫶

- **`--b2-account`** — Account ID or Application Key ID.
  - Config: `account`
  - Env Var: `RCLONE_B2_ACCOUNT`
  - Type: `string`
  - Required: `true`

- **`--b2-key`** — Application Key.
  - Config: `key`
  - Env Var: `RCLONE_B2_KEY`
  - Type: `string`
  - Required: `true`

- **`--b2-hard-delete`** — Permanently delete files on remote removal, otherwise hide files.
  - Config: `hard_delete`
  - Env Var: `RCLONE_B2_HARD_DELETE`
  - Type: `bool`
  - Default: `false`

---

## 💅 Advanced options 💅

And here are the <purple>Advanced</purple> options specific to `b2` (Backblaze B2). Yes, there are *so many*. We're doing all of them. 🌸

- **`--b2-endpoint`** — Endpoint for the service.

  Leave blank normally.

  - 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 <red>for debugging purposes only</red>. 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 (https://www.backblaze.com/docs/cloud-storage-integration-checklist).

  - 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. Periodt.

  - Config: `versions`
  - Env Var: `RCLONE_B2_VERSIONS`
  - Type: `bool`
  - Default: `false`

- **`--b2-version-at`** — Show file versions as they were at the specified time.

  > 🚨 Same energy: when using this, **no file write operations are permitted**, so you can't upload files or delete them.

  - 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`).

  - 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`.

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

  - Config: `chunk_size`
  - Env Var: `RCLONE_B2_CHUNK_SIZE`
  - Type: `SizeSuffix`
  - Default: `96Mi`

- **`--b2-upload-concurrency`** — Concurrency for multipart uploads.

  This is the number of chunks of the same file that are uploaded concurrently.

  > 😭 Note that chunks are stored in memory and there may be up to `--transfers` * `--b2-upload-concurrency` chunks stored at once in memory. Memory girlies, beware.

  - Config: `upload_concurrency`
  - Env Var: `RCLONE_B2_UPLOAD_CONCURRENCY`
  - Type: `int`
  - Default: `4`

- **`--b2-disable-checksum`** — Disable checksums for large (> upload cutoff) files.

  Normally rclone will calculate the `SHA1` checksum of the input before uploading it so it can add it to metadata on the object. This is great for data integrity checking but can cause long delays for large files to start uploading.

  - 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 as 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 blank if you want to use the endpoint provided by Backblaze.

  Rclone will <red>not</red> follow a redirect from this endpoint which downgrades `HTTPS` to `HTTP`, and will <red>not</red> send the `Authorization` header or the SSE-C key headers once a redirect has left the host and port of this endpoint.

  The URL provided here <yellow>SHOULD</yellow> have the protocol and <yellow>SHOULD NOT</yellow> have a trailing slash or specify the `/file/bucket` subpath as rclone will request files with `"{download_url}/file/{bucket_name}/{path}"`.

  Example: `> https://mysubdomain.mydomain.tld` (No trailing `"/"`, `"file"` or `"bucket"`)

  - Config: `download_url`
  - Env Var: `RCLONE_B2_DOWNLOAD_URL`
  - Type: `string`
  - Required: `false`

- **`--b2-download-auth-duration`** — Time before the public link authorization token will expire in `s` or suffix `ms|s|m|h|d`.

  This is used in combination with `rclone link` for making files accessible to the public and sets the duration before the download authorization token will expire.

  The minimum value is `1 second`. The maximum value is `one week`.

  - Config: `download_auth_duration`
  - Env Var: `RCLONE_B2_DOWNLOAD_AUTH_DURATION`
  - Type: `Duration`
  - Default: `1w`

- **`--b2-lifecycle`** — Set the number of 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. This is to create versions of files on delete and overwrite and to keep them indefinitely.

  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.

  - 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 (https://rclone.org/overview/#encoding) for more info.

  - Config: `encoding`
  - Env Var: `RCLONE_B2_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot`

- **`--b2-sse-customer-algorithm`** — If using SSE-C, the server-side encryption algorithm used when storing this object in B2.

  - Config: `sse_customer_algorithm`
  - Env Var: `RCLONE_B2_SSE_CUSTOMER_ALGORITHM`
  - Type: `string`
  - Required: `false`
  - Examples:
    - `""`
      - None
    - `"AES256"`
      - Advanced Encryption Standard (256 bits key length)

- **`--b2-sse-customer-key`** — To use SSE-C, you may provide the secret encryption key encoded in a UTF-8 compatible string to encrypt/decrypt your data

  Alternatively you can provide `--sse-customer-key-base64`.

  - Config: `sse_customer_key`
  - Env Var: `RCLONE_B2_SSE_CUSTOMER_KEY`
  - Type: `string`
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--b2-sse-customer-key-base64`** — To use SSE-C, you may provide the secret encryption key encoded in Base64 format to encrypt/decrypt your data

  Alternatively you can provide `--sse-customer-key`.

  - Config: `sse_customer_key_base64`
  - Env Var: `RCLONE_B2_SSE_CUSTOMER_KEY_BASE64`
  - Type: `string`
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--b2-sse-customer-key-md5`** — If using SSE-C you may provide the secret encryption key MD5 checksum (optional).

  If you leave it blank, this is calculated automatically from the `sse_customer_key` provided.

  - Config: `sse_customer_key_md5`
  - Env Var: `RCLONE_B2_SSE_CUSTOMER_KEY_MD5`
  - Type: `string`
  - Required: `false`
  - Examples:
    - `""`
      - None

- **`--b2-description`** — Description of the remote.

  - Config: `description`
  - Env Var: `RCLONE_B2_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

## 🌈 Backend commands 🌈

Here are the commands specific to the `b2` backend. Main character commands only. 👑

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the `backend` (https://rclone.org/commands/rclone_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` (https://rclone.org/rc/#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.

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 (which is literally the default, bestie, the vibes are *pristine*), it just returns `[]`. Empty. Nada. Nothing to see here 💅

Wanna reset your current lifecycle rules? Say less:

rclone backend lifecycle b2:bucket -o daysFromHidingToDeleting=30 rclone backend lifecycle b2:bucket -o daysFromUploadingToHiding=5 -o daysFromHidingToDeleting=1

It'll run, then print the shiny new lifecycle rules right back at you, just like the example up there ^^^. Obsessed.

Heads up though: rclone only lets you set lifecycles for the **whole bucket**, with `fileNamePrefix` = `""`. That's the house rules, no negotiating 🫶

And you **can't** disable versioning with B2. Not a thing. The best you can do is set `daysFromHidingToDeleting` to `1` day. You can also enable `hard_delete` in the config, which means deletions won't cause versions — but overwrites will *still* make versions. Pick your poison 🍓

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 gets deleted. `0` means off.
- **"daysFromStartingToCancelingUnfinishedLargeFiles"** — cancels any unfinished large file versions after this many days.
- **"daysFromUploadingToHiding"** — this many days after uploading, a file gets hidden.

## 💫 cleanup

Removes unfinished large file uploads. Yeet them into the void, fr fr.

rclone backend cleanup remote: [options] [<arguments>+]

This command removes unfinished large file uploads older than `max-age`, which defaults to `24` hours. Old uploads = ghosted 👻

Ngl, you can use `--interactive`/`-i` or `--dry-run` with this command to see what it *would* do before it actually does it. Always peek first, bestie.

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. You know the drill ✨

Options:

- **"max-age"** — max age of upload to delete.

## 🌸 cleanup-hidden

Removes old versions of files. The hidden ones. The secret ones. Gone 💀

rclone backend cleanup-hidden remote: [options] [<arguments>+]

This command removes any old hidden versions of files.

Same deal as before: you can use `--interactive`/`-i` or `--dry-run` with this command to see what it would do first.

rclone backend cleanup-hidden b2:bucket/path/to/dir

## ⚠️ Limitations

`rclone about` is **not supported** by the B2 backend. RIP. Backends without this capability can't determine free space for an rclone mount, and they can't use policy `mfs` (most free space) as a member of an rclone union remote. So, like, plan around that 😭

See List of backends that do not support rclone about (<https://rclone.org/overview/#optional-features>) and rclone about (<https://rclone.org/commands/rclone_about/>).

---

# 📦 Box 📦

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. Go off, nest as much as you want 🦋

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. So helpful of her 💖

## 🌈 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 / 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 (<https://rclone.org/remote_setup/>) for how to set it up on a machine without an internet-connected web browser available. No browser? No problem 🧚

Quick note: 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. It's on `http://127.0.0.1:53682/` and this may require you to unblock it temporarily if you're running a host firewall. Just a lil heads up 👑

Once configured, you can then use rclone like this (replace `remote` with the name you gave your remote):

List directories in top level of your 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 "Enterprise" account type with Box with single sign on (SSO), you need to create a password to use Box with rclone. This can be done at your Enterprise Box account by going to Settings, "Account" Tab, and then set the password in the "Authentication" field. Iconic of them to hide it there, honestly.

Once you've done this, you can setup your Enterprise Box account using the same procedure detailed above, using the password you just set. Easy 💅

## 😭 Invalid refresh token

According to the box docs (<https://developer.box.com/v2.0/docs/oauth-20#section-6-using-the-access-and-refresh-tokens>):

> Each `refresh_token` is valid for one use in 60 days.

This means that 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 this you'll need to use oauth2 again to update the refresh token. You can use the methods in the remote setup docs (<https://rclone.org/remote_setup/>), bearing in mind that if you use the copy-the-config-file method, you should **not** use that remote on the computer you did the authentication on. Important!!! Don't do it 🙈

Here's 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 Token already configured - replace it? 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 allows modification times to be set on objects accurate to **1 second**. These will be used to detect whether objects need syncing or not. Precision, slay.

Box supports SHA1 type hashes, so you can use the `--checksum` flag. 🎀

## 🚫 Restricted filename characters

In addition to the default restricted characters set (<https://rclone.org/overview/#restricted-characters>) the following characters are also replaced:

Character   Value   Replacement
────────────────────────────────
`\`         0x5C        `＼`

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         `␠`

Invalid UTF-8 bytes will also be replaced (<https://rclone.org/overview/#invalid-utf8>), as they can't be used in JSON strings. JSON said no, so rclone said no 🌈

### ✨ Transfers ✨

Okay so for any file bigger than 50 MiB, rclone switches to a chunked transfer, periodt. It'll upload up to `--transfers` chunks at the same time (and those slots are shared among **all** the multipart uploads going on). The chunks get buffered in memory and are normally 8 MiB a pop — so heads up bestie, bumping `--transfers` up will also bump your memory use up. 🤯

### 🗑️ Deleting files

Depending on the enterprise settings for your user, the item will either be *actually* yeeted out of Box, or just moved to the trash. No in-between.

Emptying the trash **is** possible with the `rclone cleanup` command — but it deletes every trashed file and folder one by one, so it can take a genuinely ridiculous amount of time. 😭 Emptying the trash from the WebUI doesn't have that limitation, so the move is: empty that trash via the WebUI, babe. 💅

### 📁 Root folder ID

You can set the `root_folder_id` for rclone. This is the directory (identified by its Folder ID) that rclone treats as the root of your Box drive. 🌳

Normally you just leave this blank and rclone figures out the correct root all by itself — she's self-sufficient like that.

But you *can* set it to lock rclone into one specific folder hierarchy.

To do that you have to find the Folder ID of the directory you want rclone to show. It's the last segment of the URL when you open that folder in the Box web interface. Easy.

So if the folder you want rclone to use has a URL like `https://app.box.com/folder/11xxxxxxxxx8` in your browser, then you drop `11xxxxxxxxx8` in as the `root_folder_id` in the config. Slay. ✨

### 🌸 Standard options

Here are the Standard options specific to box (Box).

- **`--box-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_BOX_CLIENT_ID`
  - Type: string
  - Required: false

- **`--box-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:

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

  A leading `~` will be expanded in the file name, and so will environment variables like `${RCLONE_CONFIG_DIR}`.

  Properties:

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

  Properties:

  - Config: `access_token`
  - Env Var: `RCLONE_BOX_ACCESS_TOKEN`
  - Type: string
  - Required: false

- **`--box-box-sub-type`**

  Properties:

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

  Properties:

  - Config: `token`
  - Env Var: `RCLONE_BOX_TOKEN`
  - Type: string
  - Required: false

- **`--box-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:

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

  Properties:

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

  > Heads up: this option is **NOT** supported by all backends. 👀

  Properties:

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

  Properties:

  - 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).

  Properties:

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

  Properties:

  - Config: `commit_retries`
  - Env Var: `RCLONE_BOX_COMMIT_RETRIES`
  - Type: int
  - Default: `100`

- **`--box-list-chunk`** — Size of listing chunk 1-1000.

  Properties:

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

  Properties:

  - 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 lets rclone, when it's using a JWT service account, 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 be 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/`

  Properties:

  - 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 (`https://rclone.org/overview/#encoding`) for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_BOX_ENCODING`
  - Type: Encoding
  - Default: `Slash,BackSlash,Del,Ctl,RightSpace,InvalidUtf8,Dot`

- **`--box-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_BOX_DESCRIPTION`
  - Type: string
  - Required: false

### 💀 Limitations

Bestie, listen. Box is case insensitive, so you literally cannot have one file called `Hello.doc` and another called `hello.doc`. They're the same file to Box. 😭

Box file names can't contain the `\` character. rclone maps it back and forth to an identical-looking unicode equivalent: `＼` (U+FF3C Fullwidth Reverse Solidus). Sneaky but it works. 🧚

Box only supports filenames up to 255 characters in length.

Box has API rate limits (`https://developer.box.com/guides/api-calls/permissions-and-errors/rate-limits/`) which sometimes slow rclone down. Not rclone's fault, the API is just like that. 🙈

`rclone about` is **not** supported by the Box backend. And backends without this capability can't determine free space for an `rclone mount`, and 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` (`https://rclone.org/overview/#optional-features`) and `rclone about` (`https://rclone.org/commands/rclone_about/`).

### 👑 Get your own Box App ID

Here's how to create your own Box App ID for rclone, step by step:

1. Go to the Box Developer Console (`https://app.box.com/developers/console`) and log in, then click **My Apps** on the sidebar. Click **Create New App** and select **Custom App**.

2. On the first screen in the box that pops up, you can pretty much enter whatever you want. The **App Name** can be whatever. For **Purpose** choose **automation** so you don't have to fill out anything else. Click **Next**.

3. On 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, let's be real, you do). Leave the others unchecked. Click **Save Changes** at the top right.

---

## 🫶 Cache

The cache remote wraps another existing remote and stores the file structure and its data for long-running tasks like `rclone mount`.

> It is **deprecated** so it's not recommended for use with new installations and may be removed at some point. 🚨

### 🦋 Status

The cache backend code is working, but it currently doesn't have a maintainer, so there are outstanding bugs (`https://github.com/rclone/rclone/issues?q=is%3Aopen+is%3Aissue+label%3Abug+label%3A%22Remote%3A+Cache%22`) which aren't getting fixed. 💀

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 — 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

<purple>and boom</purple>, your remote is built 💅 now you can actually *use* the thing, like this:

List directories in top level of your drive

rclone lsd test-cache:

List all the files in your drive

rclone ls test-cache:

To start a cached mount

rclone mount --allow-other test-cache: /var/tmp/test-cache

---

## ✍️ Write Features ✍️

### 🌙 Offline uploading

ok so bestie, to make writing through cache way more <mint>reliable</mint>, the backend now supports this feature — you switch it on by specifying a <hotpink>`cache-tmp-upload-path`</hotpink>.

A file goes through these states when you're using this feature:

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 <lavender>in sequence</lavender> and only <bold>one file</bold> 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 though 😭 — a mounted cache remote does <bold>not</bold> add any retry or fallback mechanism to the upload operation. That's gonna depend on the implementation of the wrapped remote. Consider using <hotpink>Offline uploading</hotpink> 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 <mint>almost immediately</mint> 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. 👑

### 🎬 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 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. 🙈

### 🪟 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. 🫶

- Issue #1935 (`https://github.com/rclone/rclone/issues/1935`)

- Issue #1907 (`https://github.com/rclone/rclone/issues/1907`)

- Issue #1834 (`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.

There are a couple of enhancements in track to add these but in the meantime there is a <red>valid concern</red> that the expiring cache listings can lead to cloud provider throttles or bans due to repeated queries on it for very large mounts.

Some recommendations:

- don't use a very small interval for entry information (`--cache-info-age`)

- while writes aren't yet optimised, you can still write through cache which gives you the advantage of adding the file in the cache at the same time if configured to do so.

Future enhancements:

- Issue #1937 (`https://github.com/rclone/rclone/issues/1937`)

- Issue #1936 (`https://github.com/rclone/rclone/issues/1936`)

### 🔐 cache and crypt

One common scenario is to keep your data encrypted in the cloud provider using the `crypt` remote. `crypt` uses a similar technique to wrap around an existing remote and handles this translation in a seamless way.

There is an issue with wrapping the remotes in this order: **cloud remote -> crypt -> cache**

During testing, I experienced a lot of bans with the remotes in this order. I 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 in this order yields better results: **cloud remote -> cache -> crypt**

### 📍 absolute remote paths

cache can not differentiate between relative and absolute paths for the wrapped remote. Any path given in the `remote` config setting and on the command line will be passed to the wrapped remote as is, but for storing the chunks on disk the path will be made relative by removing any leading `/` character.

This behavior is irrelevant for most backend types, but there are backends where a leading `/` changes the effective directory, e.g. in the `sftp` backend paths starting with a `/` are relative to the root of the SSH server and paths without are relative to the user home directory. 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. 💅

### 🎛️ 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 do not add the flag.

### 🧹 `rc cache/expire`

Okay so this one purges a remote from the cache backend 💅, and it's chill about what you hand it — it supports **either a directory or a file**. And yes bestie, it handles both **encrypted and unencrypted file names** if the cache is wrapped by crypt. She's flexible like that ✨.

Params:

- `remote` = path to remote (**required**, not optional, don't skip her)
- `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). Your starter pack, basically 🎀

- **`--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 😬).

  - Config: `remote`
  - Env Var: `RCLONE_CACHE_REMOTE`
  - Type: `string`
  - Required: `true`

- **`--cache-plex-url`** — The URL of the Plex server. She's pointing at your Plex, periodt 🍓

  - Config: `plex_url`
  - Env Var: `RCLONE_CACHE_PLEX_URL`
  - Type: `string`
  - Required: `false`

- **`--cache-plex-username`** — The username of the Plex user.

  - 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` (`https://rclone.org/commands/rclone_obscure/`). Do NOT just type your raw password in here, I'm begging 😭

  - 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. Lowkey important fr fr.

  - 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. She stays in sync, iconic 👑

  - 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. Out with the old, in with the new 🦋

  - 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). This is where the main characters live 💅

- **`--cache-plex-insecure`** — Skip all certificate verification when connecting to the Plex server. Living dangerously, I see 🙈

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

  - 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"`. She follows her bestie, no cap 🫶

  - 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. Fresh start energy ✨

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

  - 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. Like buffering-era YouTube, tragic 😭

  - 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. More workers = more slay, but your CPU is gonna feel it 💀

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

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

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

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

  - Config: `writes`
  - Env Var: `RCLONE_CACHE_WRITES`
  - Type: `bool`
  - Default: `false`

- **`--cache-tmp-upload-path`** — Directory to keep temporary files until they are uploaded.

  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. No staging area, straight to the cloud 🚀

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

  Note that only one file is uploaded at a time and it can take longer to start the upload if a queue formed for this purpose. One at a time bestie, she's not multitasking 💅

  - 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. Forever-ever? Forever-ever 🫶

  - 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 (`https://rclone.org/commands/rclone_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` (`https://rclone.org/rc/#backend-command`).

### 📊 `stats`

Print stats on the cache backend in JSON format. Numbers but make it ✨aesthetic✨.

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. Big file? Never heard of her — she's a bunch of little files now 💅

## ⚙️ 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.

Okay so first things first: sanity check that your chosen remote actually works. We're calling it `remote:path` down here. And note — anything *inside* `remote:path` gets chunked, anything outside it does **not**. So if you're running a bucket-based remote (S3, B2, swift, the usual suspects 🪣) you should probably tuck the bucket into the remote itself, like `s3:bucket`.

Then you configure chunker with `rclone config`. We're naming this one `overlay` so it stays clearly separate from the remote it wraps 💖

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 🎀

For normal everyday use, make absolutely sure the remote has a `:` in it. Fr fr. If you give a remote **without** the `:`, rclone goes and uses a local directory with that name instead. So a remote of `/path/to/secret/files` means rclone chunks stuff inside that very directory. And a remote of `name` means rclone drops the files into a directory called `name` inside your current directory. Yes bestie, it's giving "path, not remote" 😭

## Chunking 🔪

When rclone kicks off a file upload, chunker checks the file size. If it doesn't exceed the chunk size you configured, chunker just passes the file straight through to the wrapped remote (though hold up — see the caveat below 👇). If the file *is* large, chunker transparently cuts the data into pieces with temporary names and streams them out one by one, on the fly. Every data chunk holds the specified number of bytes, except the last one, which may have less. And if the file size isn't known in advance (that's a *streaming upload*), chunker internally creates a temporary copy, records its size, and repeats the above process.

When the upload completes, the temporary chunk files are finally renamed. This scheme guarantees operations can run in parallel and, from the outside, look atomic. A similar method with hidden temporary chunks gets used for other operations too (copy/move/rename, etc.). If an operation fails, the hidden chunks are normally destroyed, and the target composite file stays intact. Immaculate behaviour, no notes 💅

When a composite file download is requested, chunker transparently assembles it by concatenating the data chunks in order. And since the split is trivial, you could literally concatenate the data chunks by hand and get the original content back. Iconic.

When the `list` command scans a directory on the wrapped remote, the potential chunk files get accounted for, grouped, and assembled into composite directory entries. Any temporary chunks are hidden away.

`list` and other commands can sometimes come across composite files with missing or invalid chunks — like when they're shadowed by a like-named directory or another file. That usually means the wrapped filesystem has been directly tampered with, or damaged 💀. If chunker detects a missing chunk it'll print a warning by default, skip the whole incomplete group of chunks, and carry on with the current command. You can set the `--chunker-fail-hard` flag to make commands abort with an error message in those cases instead.

> Caveat: as it stands now, chunker will **always** create a temporary file in the backend and then rename it — even if the file is below the chunk threshold. That means unnecessary API calls, and it can severely restrict throughput when you're handling transfers mostly made of small files on some backends (hi, Box 👋). A workaround is to use chunker only for files above the chunk threshold via `--min-size`, then run a separate call without chunker over the remaining files.

## Chunk names 🧩

The default chunk name format is `*.rclone_chunk.###`, so out of the box your chunk names are `BIG_FILE_NAME.rclone_chunk.001`, `BIG_FILE_NAME.rclone_chunk.002`, etc. You can set another name format with the `name_format` configuration file option. The format uses an asterisk `*` as the placeholder for the base file name, plus one or more consecutive hash characters `#` as the placeholder for the sequential chunk number. There must be one and only one asterisk. The number of consecutive hash characters defines the *minimum* length of the string representing a chunk number. If the decimal chunk number has fewer digits than the number of hashes, it gets left-padded with zeros. If the decimal string is longer, it's left intact. By default numbering starts from 1, but there's another option that lets you start from 0 — e.g. for compatibility with legacy software 🫶

For example, if the name format is `big_*-##.part`, the 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` only assembles composite directory entries when chunk names match the configured format, and it treats non-conforming file names as normal non-chunked files.

When using `norename` transactions, chunk names additionally get a unique file version suffix. For example, `BIG_FILE_NAME.rclone_chunk.001_bp562k`.

## Metadata 📝

Besides data chunks, chunker by default creates a metadata object for a composite file. That object is named after the original file. Chunker lets you 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 these 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's no field for the composite file name, because it's simply equal to the name of the meta object on the wrapped remote. Please refer to the 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 scans the directory for all files that follow the configured chunk name format, groups them by detecting chunks with the same base name, and shows the group names as virtual composite files. This method is more prone to missing-chunk errors (especially a missing last chunk) than the format with metadata enabled. Be warned, bestie 💀

## Hashsums 💅

Chunker supports hashsums only when a compatible metadata is present. So if you choose a metadata format of `none`, chunker will report the hashsum as `UNSUPPORTED`.

Please note that by default metadata is stored only for composite files. If a file is smaller than the configured chunk size, chunker will transparently redirect hash requests to the wrapped remote — so support depends on that. You'll see the empty string as a hashsum of the requested type for small files if the wrapped remote doesn't support it.

Many storage backends support MD5 and SHA1 hash types, and so does chunker. With chunker you can choose one or the other, but not both. MD5 is set by default as the most supported type. Since chunker keeps hashes for composite files and falls back to the wrapped remote hash for non-chunked ones, we advise you to choose the same hash type as supported by the wrapped remote, so that your file listings look coherent ✨

If your storage backend does not support MD5 or SHA1 but you need consistent file hashing, configure chunker with `md5all` or `sha1all`. These two modes guarantee the given hash for all files. If the wrapped remote doesn't support it, chunker will then add metadata to all files, even small ones. However, 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.

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 provides a guarantee that the given hashsum is available. Also, chunker will reject a server-side copy or move operation if source and destination hashsum types are different, resulting in extra network bandwidth, too. In some rare cases this may be undesired, so chunker provides two optional choices: `sha1quick` and `md5quick`. If the source does not support the primary hash type and the quick mode is enabled, chunker will try to fall back to the secondary type. This will save CPU and bandwidth but can result in empty hashsums at the 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. Not me warning you twice about the same thing — it's that serious 😤

### 🕰️ Modification times 🕰️

Chunker keeps track of modification times by leaning on the wrapped remote, so whether that even works is entirely up to the wrapped remote, bestie. 💅 For a small non-chunked file, the chunker overlay just... manipulates the modification time of the wrapped remote file, easy peasy. 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 grabs the modification time off the **first data chunk**. That's the whole vibe. ✨

### 🚚 Migrations 🚚

So the idiomatic way to migrate to a different chunk size, hash type, transaction style or chunk naming scheme is literally just:

- Collect all your chunked files under a directory and have your chunker remote point to it.
- 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.
- 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 server-side copy if possible. 🫶
- After checking data integrity you may remove 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 will eat up your account quota. 😭 Please note that the `deletefile` command deletes only active chunks of a file. As a workaround, you can use a 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. Iconic cleanup behavior, no cap. 🧹

### 💀 Caveats and Limitations 💀

Chunker **requires** the wrapped remote to support server-side move (or copy + delete) operations — otherwise it will explicitly refuse to start. Periodt. Why? Because internally it renames temporary chunk files to their final names once 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 base file name without path by **255 characters**. Using rclone's crypt remote as a base file system limits the 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).

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. If you desperately need to change critical chunking settings, you should run data migration as described above. Fr fr, don't skip that step. 🙈

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 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 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 🌸

okay so this one is a backend for the <pink>Cloudinary</pink> platform — `https://cloudinary.com/` ✨

### ✨ About Cloudinary ✨

Cloudinary (`https://cloudinary.com/`) is literally an **image and video API platform** 💅 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. the way that's a whole lot of people trusting it? not me being impressed 🫶

### 💸 Accounts & Pricing 💸

To use this backend you need to create a free account (`https://cloudinary.com/users/register_free`) on Cloudinary 🎀 Start with the free plan, it's got generous usage limits. Then, as your requirements grow (character development but make it infrastructure ✨), upgrade to a plan that best fits your needs. Pricing deets are at `https://cloudinary.com/pricing`.

### 🔐 Securing Your Credentials 🔐

Please refer to the docs: `https://rclone.org/docs/#configuration-encryption-cheatsheet` 🫶 protect those creds, bestie, fr fr.

### 🛠️ Configuration 🛠️

Here is an example of making a Cloudinary configuration.

First, create a `cloudinary.com` account (`https://cloudinary.com/users/register_free`) 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 **md5 and timestamps** for any successful Put automatically — and read-only 🔒 So it just... does it. iconic behaviour tbh.

### ⭐ Standard options ⭐

Here are the Standard options specific to cloudinary (Cloudinary).

**`--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).

**`--cloudinary-encoding`** — The encoding for the backend.

See the encoding section in the overview (`https://rclone.org/overview/#encoding`) 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`

**`--cloudinary-adjust-media-files-extensions`** — Cloudinary handles media formats as a file attribute and strips it from the name, which is unlike most other file systems

Properties:

- Config: `adjust_media_files_extensions`
- Env Var: `RCLONE_CLOUDINARY_ADJUST_MEDIA_FILES_EXTENSIONS`
- Type: `bool`
- Default: `true`

**`--cloudinary-media-extensions`** — Cloudinary supported media extensions

Properties:

- Config: `media_extensions`
- Env Var: `RCLONE_CLOUDINARY_MEDIA_EXTENSIONS`
- Type: `stringArray`
- Default: `[3ds 3g2 3gp ai arw avi avif bmp bw cr2 cr3 djvu dng eps3 fbx flif flv gif glb gltf hdp heic heif ico indd jp2 jpe jpeg jpg jxl jxr m2ts mov mp4 mpeg mts mxf obj ogv pdf ply png psd svg tga tif tiff ts u3ma usdz wdp webm webp wmv]`

**`--cloudinary-description`** — Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_CLOUDINARY_DESCRIPTION`
- Type: `string`
- Required: `false`

# 🎀 Citrix ShareFile 🎀

<rainbow>Citrix ShareFile</rainbow> (<blue>https://sharefile.com</blue>) is a secure file sharing and transfer service that's <hotpink>aimed at business</hotpink> — like, it's giving corporate, it's giving "we have compliance people". 💼✨

---

## 💖 Configuration 💖

The initial setup for Citrix ShareFile is all about getting a token from Citrix ShareFile, which you grab in your browser. No cap, `rclone config` walks you through the whole thing like a supportive bestie. 🫶

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

Need to do this on a machine that doesn't have an internet-connected web browser handy? Check the remote setup docs (<blue>https://rclone.org/remote_setup/</blue>) for how to set it up. 💅

Heads up bestie — rclone runs a webserver on your local machine to collect the token as returned from Citrix ShareFile. 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 <red>it may require you to unblock it temporarily if you're running a host firewall</red>. 🚨

Once configured you can then use rclone like this (swap `remote` for the name you gave your remote):

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 a ShareFile directory called `backup`

rclone copy /home/source remote:backup

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. 🦋

---

## 🌸 Modification times and hashes 🌸

ShareFile allows modification times to be set on objects accurate to <yellow>1 second</yellow>. These will be used to detect whether objects need syncing or not. ⏱️

ShareFile supports <purple>MD5</purple> type hashes, so you can use the `--checksum` flag. 🔥

---

## ✨ Transfers ✨

For files above <yellow>128 MiB</yellow> 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 <yellow>64 MiB</yellow>, so increasing `--transfers` will increase memory use. 🧠💥

---

## 💜 Restricted filename characters 💜

On top of the default restricted characters set (<blue>https://rclone.org/overview/#restricted-characters</blue>), these characters are also replaced:

- `\` — `0x5C` — replaced with `＼`
- `*` — `0x2A` — replaced with `＊`
- `<` — `0x3C` — replaced with `＜`
- `>` — `0x3E` — replaced with `＞`
- `?` — `0x3F` — replaced with `？`
- `:` — `0x3A` — replaced with `：`
- `|` — `0x7C` — replaced with `｜`
- `"` — `0x22` — replaced with `＂`

File names also can't **start** or **end** with the following characters. These only get replaced if they are the first or last character in the name:

- `SP` — `0x20` — replaced with `␠`
- `.` — `0x2E` — replaced with `．`

Invalid UTF-8 bytes will also be replaced (<blue>https://rclone.org/overview/#invalid-utf8</blue>), because they can't be used in JSON strings. 🫠

---

## 👑 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 <purple>RFC 6749</purple>.

> Note that this option is **NOT** supported by all backends. 😭

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. 📦

<yellow>Must a power of 2 >= 256k.</yellow>

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 (<blue>https://rclone.org/overview/#encoding</blue>) 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 ⚠️

Important bestie: ShareFile is <red>case insensitive</red>, so you can't have a file called `"Hello.doc"` and one called `"hello.doc"`. They'd be the same file and the vibe would be chaos. 💀

ShareFile only supports filenames up to <yellow>256 characters</yellow> 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 (<blue>https://rclone.org/overview/#optional-features</blue>) and `rclone about` (<blue>https://rclone.org/commands/rclone_about/</blue>).

---

# 🧚 Crypt 🧚

Rclone crypt remotes **encrypt and decrypt other remotes**. 🔒🦋

A remote of type `crypt` does **not** access a storage system (<blue>https://rclone.org/overview/</blue>) directly. Instead it *wraps* another remote, which in turn accesses the storage system. This is similar to how `alias` (<blue>https://rclone.org/alias/</blue>), `union` (<blue>https://rclone.org/union/</blue>), `chunker` (<blue>https://rclone.org/chunker/</blue>) and a few others work. It makes the usage very flexible — 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` (<blue>https://rclone.org/commands/rclone_mount/</blue>) a crypt remote. 💅

<pink>okay so</pink> accessing a storage system through a crypt remote gives you <hotpink>client-side encryption</hotpink> — that's the whole point, bestie — and it means your data can live somewhere you <italic>do not</italic> trust to stay uncompromised, and still be safe. 💅

When you're working against the crypt remote, rclone encrypts everything <purple>before uploading</purple> and decrypts everything <purple>after downloading</purple>, on your local system, on the fly, as needed — so what's chilling at rest in the wrapped remote stays encrypted. 🔐

But <red>important reality check</red>: if you access that storage system with some other app that isn't rclone, or you hit the wrapped remote <italic>directly</italic> with rclone, there is <bold>no encryption or decryption happening at all</bold>. Downloading existing content just hands you the encrypted (scrambled) format, and anything you upload won't become encrypted. Nope. Zero. 🫠

The encryption itself is secret-key encryption (aka symmetric key encryption) — a password (or pass phrase) is used to generate the <bold>real</bold> encryption key. You can supply that password yourself, or you may choose to let rclone generate one for you. It gets stored in the configuration file, in a <italic>lightly obscured</italic> form. If you're in an environment where you can't keep your config secured, you should absolutely add configuration encryption (https://rclone.org/docs/#configuration-encryption) as protection. 🛡️

As long as you have that configuration file, you'll be able to decrypt your data. Without the configuration file, as long as you remember the password (or keep it somewhere safe), you can re-create the configuration and gain access to the existing data. You can also configure a corresponding remote in a different installation to reach the same data. See below for guidance on changing your password. ✨

Encryption uses cryptographic salt (https://en.wikipedia.org/wiki/Salt_(cryptography)) to permute the encryption key, so the same string can get encrypted in different ways. When you configure the crypt remote, entering a salt is optional — or you can let rclone generate a unique one. If it's omitted, rclone uses a built-in unique string. Normally in cryptography the salt is stored right alongside the encrypted content and nobody has to memorize it. <hotpink>That is NOT how it works in rclone</hotpink>, because rclone doesn't store any additional information on the remotes. So using a custom salt is effectively <bold>a second password that you must memorize</bold>. 😭

File content encryption is performed using NaCl SecretBox (https://godoc.org/golang.org/x/crypto/nacl/secretbox), based on XSalsa20 cipher and Poly1305 for integrity. Names (file names and directory names) are also encrypted by default, but that has some implications, which is why it's possible to turn it off. 🎀

---

### 🌸 Configuration 🌸

Here's an example of how to make a remote called <italic>secret</italic>. 🧚

To use crypt, first set up the underlying remote. Follow the `rclone config` instructions for that specific backend.

Before configuring the crypt remote, check that the underlying remote is actually working. In this example the underlying remote is called <italic>remote</italic>. We're going to configure a path <italic>path</italic> within this remote to contain the encrypted content. Anything inside `remote:path` will be encrypted, and anything outside will not be. 🦋

Configure crypt using `rclone config`. In this example the crypt remote is called <italic>secret</italic>, so we can tell it apart from the underlying remote.

When you're done, you can use the crypt remote named <italic>secret</italic> just like any other remote, e.g. `rclone copy D:\docs secret:\docs`, and rclone will encrypt and decrypt on the fly as needed. If you access the wrapped remote `remote:path` directly, you <bold>bypass the encryption</bold> — anything you read will be in encrypted form, and anything you write will be unencrypted. To dodge all that mess, it's best to configure a dedicated path for encrypted content and access it <italic>exclusively</italic> 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>

> <red>Important</red> 💀 The crypt password stored in `rclone.conf` is <italic>lightly obscured</italic>. That only protects it from cursory inspection. It is <bold>not secure</bold> unless configuration encryption (https://rclone.org/docs/#configuration-encryption) of `rclone.conf` is specified.

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 somewhere else, it will be compatible — but the obscured version will be different, because of 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 you're configuring the remote to encrypt/decrypt, you can specify <italic>any</italic> string that rclone accepts as a source/destination of other commands. 🫶

The primary use case is specifying the path into an already configured remote (e.g. `remote:path/to/dir` or `remote:bucket`), so that data sitting in an untrusted location can be stored encrypted. 👑

You may also specify a local filesystem path, like `/path/to/dir` on Linux or `C:\path\to\dir` on Windows. Point a crypt remote at a local filesystem path and boom — you can use rclone as a utility for <bold>pure local file encryption</bold>, for example keeping encrypted files on a removable USB drive. 🔥

> **Note:** a string that doesn't contain a `:` will be treated by rclone as a relative path in the local filesystem. For example, if you enter the name `remote` without the trailing `:`, it'll be treated as a subdirectory of the current directory with the 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 <italic>and</italic> through a crypt remote for encrypted content, it's recommended to point the crypt remote at a separate directory within the wrapped remote. If you use a bucket-based storage system (e.g. `Swift`, `S3`, `Google Compute Storage`, `B2`), it's generally advisable to wrap the crypt remote around a specific bucket (`s3:bucket`). If you wrap it around the entire root of the storage (`s3:`) and use the optional file name encryption, rclone will encrypt the bucket name. 🪣💅

---

### 💜 Changing password 💜

If your password — or the configuration file containing a lightly obscured form of that password — gets compromised, you need to re-encrypt your data with a new password. And here's the thing, babes: since rclone uses secret-key encryption, where the encryption key is generated <italic>directly</italic> from the password kept on the client, it is <bold>not possible</bold> to change the password/key of already encrypted content. 🚫

Just changing the password configured for an existing crypt remote means you'll no longer be able to decrypt <italic>any</italic> of the previously encrypted content. 😭 The only possibility is to re-upload everything through 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.

> **Note, bestie, read this one:** a security problem related to the random password generator was 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. See issue #4783 (`https://github.com/rclone/rclone/issues/4783`) for more details, and a tool you can use to check if you are affected.

---

### ✨ Example ✨

Okay so create the following file structure using "standard" 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 🦋

**Off**

- doesn't hide file names or directory structure
- allows for longer file names (~246 characters)
- can use sub paths and copy single files

**Standard**

- 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

**Obfuscation**

This is a simple "rotate" 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 "hello" may become "53.jgnnq".

Obfuscation is **not** a strong encryption of filenames, but hinders automated scanning tools picking up on filename patterns. It is an intermediate between "off" and "standard" 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.

Obfuscation cannot be relied upon for strong protection.

- 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 "Standard" 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:

**True**

Encrypts the whole file path including directory names Example: `1/12/123.txt` is encrypted to `p0e52nreeaj0a5ea7s64m4j72s/l42g6771hnv3an9cgc8cr2n1ng/qgm4avr35m5loi1th53ato71v0`

**False**

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 extremely strong crypto authenticator.

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).
  - **Config:** `remote`
  - **Env Var:** `RCLONE_CRYPT_REMOTE`
  - **Type:** `string`
  - **Required:** `true`

- **`--crypt-filename-encryption`** — How to encrypt the filenames.
  - **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.
  - **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` (`https://rclone.org/commands/rclone_obscure/`).
  - **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` (`https://rclone.org/commands/rclone_obscure/`).
  - **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.
  - **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.
  - **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.
  - **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.
  - **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.
  - **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.

description. It's giving "let me pick the encoding that fits your remote's whole vibe":

<pink>**Properties:**</pink>

- **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`** — okay so if you set this, it <hotpink>overrides</hotpink> the default suffix of `".bin"`. And bestie, setting suffix to `"none"` gives you an empty suffix, which is genuinely useful when your path length is hanging on by a thread. 😭

  <pink>**Properties:**</pink>

  - **Config:** `suffix`
  - **Env Var:** `RCLONE_CRYPT_SUFFIX`
  - **Type:** `string`
  - **Default:** `".bin"`

- **`--crypt-description`** — just a lil description of the remote, no biggie. 🎀

  <pink>**Properties:**</pink>

  - **Config:** `description`
  - **Env Var:** `RCLONE_CRYPT_DESCRIPTION`
  - **Type:** `string`
  - **Required:** false

---

### 🦋 Metadata

Any metadata supported by the underlying remote is read and written. Slay.

See the metadata (`https://rclone.org/docs/#metadata`) docs for more info. iykyk.

---

### ✨ Backend commands

Here are the commands specific to the crypt backend. Not me having commandsss 💅

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend (`https://rclone.org/commands/rclone_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 (`https://rclone.org/rc/#backend-command`).

---

### 🧚 encode

Encode the given filename(s). iconic.

rclone backend encode remote: [options] [<arguments>+]

This encodes the filenames given as arguments returning a list of strings of the encoded results. periodt.

Usage examples:

rclone backend encode crypt: file1 [file2...] rclone rc backend/command command=encode fs=crypt: file1 [file2...]

---

### 🌸 decode

Decode the given filename(s). reverse uno card 🫶

rclone backend decode remote: [options] [<arguments>+]

This decodes the filenames given as arguments returning a list of strings of the decoded results. It will return an error if any of the inputs are invalid. yes bestie, it checks. ⚠️

Usage examples:

rclone backend decode crypt: encryptedfile1 [encryptedfile2...] rclone rc backend/command command=decode fs=crypt: encryptedfile1 [encryptedfile2...]

---

### 👑 Backing up an encrypted remote

So if you wanna backup an encrypted remote, the recommendation is fr fr to use `rclone sync` **on the encrypted files**, and make sure the passwords are the <rainbow>same</rainbow> in the new encrypted remote. Don't skip that part bestie, it matters.

This is gonna have the following advantages 💖

- `rclone sync` will check the checksums while copying
- you can use `rclone check` between the encrypted remotes
- you don't decrypt and encrypt unnecessarily (which is giving wasteful, not giving efficient)

For example, let's say you have your original remote at `remote:` with the encrypted version at `eremote:` with path `remote:crypt`. You would then set up the new remote `remote2:` and then the encrypted version `eremote2:` with path `remote2:crypt` using the same passwords as `eremote:`. 🎀

To sync the two remotes you would do

rclone sync --interactive remote:crypt remote2:crypt

And to check the integrity you would do

rclone check remote:crypt remote2:crypt

---

### 🌈 File formats

### 🔥 File encryption

Files are encrypted 1:1 source file to destination object. The file has a header and is divided into chunks. So clean.

### 💜 Header

- 8 bytes magic string `RCLONE\x00\x00`
- 24 bytes Nonce (IV)

The initial nonce is generated from the operating systems crypto strong random number generator. The nonce is incremented for each chunk read making sure each nonce is unique for each block written. The chance of a nonce being reused is minuscule. If you wrote an exabyte of data (10¹⁸ bytes) you would have a probability of approximately 2×10⁻³² of reusing a nonce. math girlies stand up 📐✨

### ⭐ Chunk

Each chunk will contain 64 KiB of data, except for the last one which may have less data. The data chunk is in standard NaCl SecretBox 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

64k chunk size was chosen as the best performing chunk size (the authenticator takes too much time below this and the 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

1 byte file will encrypt to

- 32 bytes header
- 17 bytes data chunk

49 bytes total

1 MiB (1048576 bytes) file will encrypt to

- 32 bytes header
- 16 chunks of 65552 bytes

1048864 bytes total (a 0.03% overhead). This is the overhead for big files.

### 🦋 Name encryption

File names are encrypted segment by segment - the path is broken up into `/` separated strings and these are encrypted individually.

File segments are padded using PKCS#7 to a multiple of 16 bytes before encryption.

They are then encrypted with EME using AES with 256 bit key. EME (ECB-Mix-ECB) is a wide-block encryption mode presented in the 2003 paper "A Parallelizable Enciphering Mode" by Halevi and Rogaway. very demure, very scholarly 📚

This makes for deterministic encryption which is what we want - the same filename must encrypt to the same thing otherwise we can't find it on the cloud storage system.

This means that

- filenames with the same name will encrypt the same
- filenames which start the same won't have a common prefix

A version string of the form `-vYYYY-MM-DD-HHMMSS-NNN` on the end of a file name (as added by `--b2-versions` / `--s3-versions`) is left in plain text so that versioned files can be found. Directory names are encrypted in full. Rclone before v1.76 left such a suffix in plain text on directory names too, so a directory named like this created by an older rclone will appear in listings with a warning but can't be opened or removed until renamed on the underlying remote to the name given in the warning. 💀 noted, bestie, don't panic.

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 are 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). lowercase girlie behavior fr fr 💅

### 🌸 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. <hotpink>always</hotpink>, bestie. 🫶

---

### 💖 See Also

- rclone cryptdecode (`https://rclone.org/commands/rclone_cryptdecode/`) - Show forward/reverse mapping of encrypted filenames.

# ✨ Compress 💅

## 🚨 Warning 🚨

> <red>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.</red>

Okay bestie, serious talk first: the Compress remote slaps a whole compression layer onto another remote, and it's <hotpink>iconic</hotpink> when you've got remotes stuffed with big files that compress real nice. It is <red>best used with remotes containing many large compressible files</red> — know that. ✨

---

## 🛠️ Configuration

Using this one is literally so easy? All you gotta do is point at another remote and pick a compression mode. Like this:

$ rclone config Current remotes:

Name Type ==== ==== remote_to_press sometype

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> compress

Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. ... 12 / Compress a remote \ (compress) ... Storage> compress

Option remote. Remote to compress. Enter a value. remote> remote_to_press:subdir

Option mode. Compression mode. Choose a number from below, or type in your own value of type string. Press Enter for the default (gzip). 1 / Standard gzip compression with fastest parameters. \ (gzip) 2 / Zstandard compression — fast modern algorithm offering adjustable speed-to-compression tradeoffs. \ (zstd) mode> gzip

Option level. GZIP (levels -2 to 9):

• -2 — Huffman encoding only. Only use if you know what you're doing.
• -1 (default) — recommended; equivalent to level 5.
• 0 — turns off compression.
• 1–9 — increase compression at the cost of speed. Going past 6 generally offers very little return.

ZSTD (levels 0 to 4):

• 0 — turns off compression entirely.
• 1 — fastest compression with the lowest ratio.
• 2 (default) — good balance of speed and compression.
• 3 — better compression, but uses about 2–3x more CPU than the default.
• 4 — best possible compression ratio (highest CPU cost).

Notes:

• Choose GZIP for wide compatibility; ZSTD for better speed/ratio tradeoffs.
• Negative gzip levels: -2 = Huffman-only, -1 = default (≈ level 5). Enter a value. level> -1

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

• type: compress
• remote: remote_to_press:subdir
• mode: gzip
• level: -1 Keep this "compress" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

---

## 🗜️ Compression Algorithms

- **GZIP** — the tried-and-true <green>OG</green> algorithm, well-established and widely adopted, and it strikes a solid balance between compression speed and ratio. It supports compression levels from `-2` to `9`, and the default `-1` (roughly equivalent to level 5) offers an effective middle ground for most scenarios. 🫶

- **Zstandard (zstd)** — a modern, high-performance algorithm that gives you <purple>precise control</purple> over the trade-off between speed and compression efficiency. Compression levels range from `0` (no compression) to `4` (maximum compression). 🦋

---

## 📁 File types

Open a remote wrapped by compress and you'll see... so many files, each with an extension matching whatever compression algorithm you picked. These are standard files that various archive programs can open just fine, but they've also got some <lavender>hidden metadata</lavender> that lets rclone use them. You can download and decompress these files whenever you want, no cap — BUT: <red>do not manually delete or rename files</red>. Files without correct metadata will not be recognized by rclone. 💀

---

## 🏷️ File names

The compressed files get named `*.###########.gz` where `*` is the base file and the `#` part is the base64 encoded size of the uncompressed file. And bestie, listen: <hotpink>the file names should not be changed by anything other than the rclone compression backend</hotpink>. Hands off, okay? 🙈

---

## ⚙️ 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.
    - `"zstd"`
      - Zstandard compression — fast modern algorithm offering adjustable speed-to-compression tradeoffs.

- **`--compress-level`** —

  GZIP (levels -2 to 9): - -2 — Huffman encoding only. Only use if you know what you're doing. - -1 (default) — recommended; equivalent to level 5. - 0 — turns off compression. - 1–9 — increase compression at the cost of speed. Going past 6 generally offers very little return.

  ZSTD (levels 0 to 4): - 0 — turns off compression entirely. - 1 — fastest compression with the lowest ratio. - 2 (default) — good balance of speed and compression. - 3 — better compression, but uses about 2–3x more CPU than the default. - 4 — best possible compression ratio (highest CPU cost).

  Notes: - Choose GZIP for wide compatibility; ZSTD for better speed/ratio tradeoffs. - Negative gzip levels: -2 = Huffman-only, -1 = default (≈ level 5).

  Properties:

  - Config: `level`
  - Env Var: `RCLONE_COMPRESS_LEVEL`
  - Type: `string`
  - Required: `true`

---

## 🌈 Advanced options

Here are the Advanced options specific to compress (Compress a remote). 💜

- **`--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 (https://rclone.org/docs/#metadata) docs for more info. 💖

## 🦋 Combine 🦋

Okay so the <purple>combine</purple> backend is literally the friend-group of backends — it takes a bunch of remotes and smushes them together into one single directory tree. Bestie, it's giving "found family" 🫶

So like, say you've got 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. Obsessed, honestly 💅

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.

See the Google Drive docs (https://rclone.org/drive/#drives) for full info.

### ⭐ Standard options ⭐

Here are the Standard options specific to combine (Combine several remotes into one).

#### <cyan>`--combine-upstreams`</cyan>

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).

#### <cyan>`--combine-description`</cyan>

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 (https://rclone.org/docs/#metadata) docs for more info.

---

## 👑 DOI 👑

The DOI remote is a <hotpink>read only</hotpink> remote for reading files from digital object identifiers (DOI).

Currently, the DOI backend supports DOIs hosted with:

- InvenioRDM (https://inveniosoftware.org/products/rdm/)
  - Zenodo (https://zenodo.org)
  - CaltechDATA (https://data.caltech.edu)
  - Other InvenioRDM repositories (https://inveniosoftware.org/showcase/)
- Dataverse (https://dataverse.org)
  - Harvard Dataverse (https://dataverse.harvard.edu)
  - Other Dataverse repositories (https://dataverse.org/installations)

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. 🦋

### 🎀 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 Enter name for new remote. name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / DOI datasets \ (doi) [snip] Storage> doi Option doi. The DOI or the doi.org URL. Enter a value. doi> 10.5281/zenodo.5876941 Edit advanced config? y) Yes n) No (default) y/n> n Configuration complete. Options:

• type: doi
• doi: 10.5281/zenodo.5876941 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 doi (DOI datasets).

#### <cyan>`--doi-doi`</cyan>

The DOI or the doi.org URL.

Properties:

- **Config:** `doi`
- **Env Var:** `RCLONE_DOI_DOI`
- **Type:** `string`
- **Required:** `true`

### 🔥 Advanced options 🔥

Here are the Advanced options specific to doi (DOI datasets).

#### <cyan>`--doi-provider`</cyan>

DOI provider.

The DOI provider can be set when rclone does not automatically recognize a supported DOI provider.

Properties:

- **Config:** `provider`
- **Env Var:** `RCLONE_DOI_PROVIDER`
- **Type:** `string`
- **Required:** `false`
- **Examples:**
  - `"auto"`
    - Auto-detect provider
  - `"zenodo"`
    - Zenodo
  - `"dataverse"`
    - Dataverse
  - `"invenio"`
    - Invenio

#### <cyan>`--doi-doi-resolver-api-url`</cyan>

The URL of the DOI resolver API to use.

The DOI resolver can be set for testing or for cases when the canonical DOI resolver API cannot be used.

Defaults to `"https://doi.org/api"`.

Properties:

- **Config:** `doi_resolver_api_url`
- **Env Var:** `RCLONE_DOI_DOI_RESOLVER_API_URL`
- **Type:** `string`
- **Required:** `false`

#### <cyan>`--doi-description`</cyan>

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_DOI_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

### 💜 Backend commands 💜

Here are the commands specific to the doi backend.

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend (https://rclone.org/commands/rclone_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 (https://rclone.org/rc/#backend-command).

#### <mint>`metadata`</mint>

Show metadata about the DOI.

rclone backend metadata remote: [options] [<arguments>+]

This command returns a JSON object with some information about the DOI.

Usage example:

rclone backend metadata doi:

It returns a JSON object representing metadata about the DOI. 🍓

#### <mint>`set`</mint>

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 doi backend.

Usage examples:

rclone backend set doi: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=doi: [-o opt_name=opt_value] [-o opt_name2=opt_value2] rclone rc backend/command command=set fs=doi: -o doi=NEW_DOI

The option keys are named as they are in the config file.

This rebuilds the connection to the doi 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. 💅

# 🦋 Drime 🦋

<pink>Drime</pink> (<blue>https://drime.cloud/</blue>) is a cloud storage and transfer service that is *lowkey obsessed* with fast, resilient file delivery. It's giving both free and paid tiers, and the whole vibe is high-speed uploads plus link sharing. 💅

To set up Drime you gotta log in, navigate to <purple>Settings</purple> → <purple>Developer</purple>, and create a token that you'll use as your API access key. Give it a sensible name bestie, then copy that token for use in your config. 🎀

---

## 🛠 Configuration 🛠

Here's a run-through of `rclone config` to make a remote called `remote`.

First off, run this:

rclone config

Then just follow the interactive setup, no thoughts head empty, it literally walks you through it:

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 / Drime \ (drime) Storage> drime

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> YOUR_API_ACCESS_TOKEN

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

• type: drime
• access_token: YOUR_API_ACCESS_TOKEN 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 use `rclone` like this (swap `remote` out for whatever name you gave your remote ✨):

List the directories and files chillin' at the top level of your Drime:

rclone lsf remote:

To copy a local directory to a Drime directory called `backup`:

rclone copy /home/source remote:backup

---

## ⏰ Modification times and hashes ⏰

Okay so, Drime <red>does not support modification times or hashes</red>. Not a single one. 😭

Which means by default your syncs will only look at the **size** of the file to figure out if it needs updating. That's it. That's the whole vibe check.

You *can* use the `--update` flag, which will use the time the object was uploaded instead. For many operations this is genuinely sufficient to tell if something has changed. **But** — and this is the important part — files created with timestamps in the past will be **missed** by the sync if you're using `--update`. So watch out bestie. 💀

---

## 🚫 Restricted filename characters 🚫

On top of the <purple>default restricted characters set</purple> (<blue>https://rclone.org/overview/#restricted-characters</blue>) these characters also get replaced:

- `\` — value `0x5C` — replaced with `＼`

File names also can't **start** or **end** with these characters. They only get swapped out if they're the first or last character in the name:

- `SP` — value `0x20` — replaced with `␠`

Invalid UTF-8 bytes will also be replaced (<blue>https://rclone.org/overview/#invalid-utf8</blue>), because no cap they literally cannot be used in JSON strings. 🫠

---

## 🌱 Root folder ID 🌱

You can set the `root_folder_id` for rclone. This is the directory (identified by its **Folder ID**) that rclone will consider to be the root of your Drime drive.

Normally you just leave this blank and let rclone figure out the correct root itself, and it'll fill in the value in the config file. Main character energy, honestly. 👑

But if you *want*, 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.

You can do it with rclone, like so:

$ 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 you want is the part **before** the `;`, so you could set:

root_folder_id = d6341f53-ee65-4f29-9f59-d11e8070b2a0

…to lock rclone onto the `Files` directory. 🎯

---

## ✨ Standard options ✨

Here are the Standard options specific to `drime` (Drime).

- **`--drime-access-token`** — API Access token
  You can get this from the web control panel.

  Properties:
  - Config: `access_token`
  - Env Var: `RCLONE_DRIME_ACCESS_TOKEN`
  - Type: `string`
  - Required: `false`

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to `drime` (Drime).

- **`--drime-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_DRIME_ROOT_FOLDER_ID`
  - Type: `string`
  - Required: `false`

- **`--drime-workspace-id`** — Account ID
  Leave this blank normally unless you wish to specify a Workspace ID.

  Properties:
  - Config: `workspace_id`
  - Env Var: `RCLONE_DRIME_WORKSPACE_ID`
  - Type: `string`
  - Required: `false`

- **`--drime-list-chunk`** — Number of items to list in each call

  Properties:
  - Config: `list_chunk`
  - Env Var: `RCLONE_DRIME_LIST_CHUNK`
  - Type: `int`
  - Default: `1000`

- **`--drime-hard-delete`** — Delete files permanently rather than putting them into the trash.

  Properties:
  - Config: `hard_delete`
  - Env Var: `RCLONE_DRIME_HARD_DELETE`
  - Type: `bool`
  - Default: `false`

- **`--drime-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_DRIME_UPLOAD_CUTOFF`
  - Type: `SizeSuffix`
  - Default: `5Mi`

- **`--drime-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" or google photos or google docs) they will be uploaded as multipart uploads using this chunk size.

  Note that `--drime-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`.

  Properties:
  - Config: `chunk_size`
  - Env Var: `RCLONE_DRIME_CHUNK_SIZE`
  - Type: `SizeSuffix`
  - Default: `5Mi`

- **`--drime-upload-concurrency`** — Concurrency for multipart uploads and copies.

  This is the number of chunks of the same file that are uploaded concurrently for multipart uploads and copies.

  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_DRIME_UPLOAD_CONCURRENCY`
  - Type: `int`
  - Default: `4`

- **`--drime-encoding`** — The encoding for the backend.

  See the encoding section in the overview (<blue>https://rclone.org/overview/#encoding</blue>) for more info.

  Properties:
  - Config: `encoding`
  - Env Var: `RCLONE_DRIME_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,Del,Ctl,LeftSpace,RightSpace,InvalidUtf8,Dot`

- **`--drime-description`** — Description of the remote.

  Properties:
  - Config: `description`
  - Env Var: `RCLONE_DRIME_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

## 💀 Limitations 💀

Drime only supports filenames up to **255 bytes** in length, where filenames are encoded in UTF8. That's the ceiling bestie, no going over. 🙈

---

# 🌈 Dropbox 🌈

Paths are specified as `remote:path`

Dropbox paths may be as deep as required, e.g. `remote:directory/subdirectory`. Go off, nest as much as you want. 🦋

---

## 🛠 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, bestie, it's got you. 💖

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:

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

See the remote setup docs (<blue>https://rclone.org/remote_setup/</blue>) for how to set it up on a machine without an internet-connected web browser available.

> Heads up: rclone runs a webserver on your local machine to collect the token as returned from Dropbox. 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, or use manual mode. Don't let a firewall ruin the moment. 🧱😭

You can then use it like this,

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. It's giving corporate. 💼✨

When using Dropbox for business, `remote:` and `remote:path/to/file` 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. 🌟

You can then use team folders like this: `remote:/TeamFolder` and `remote:/TeamFolder/path/to/file`.

---

A leading `/` for a Dropbox personal account will do **nothing**, bestie 💀 — literally zero. All it does is cost you an extra HTTP transaction, so like… don't. Just don't.

---

## 🕰️ Modification times and hashes ✨

Dropbox *does* support modified times, but here's the tea 🍵: the **only** way to set a modification time is to **re-upload the file**. That's it. That's the whole trick.

Which means — if you uploaded your data with an older version of rclone that didn't support the v2 API and modified times, rclone is gonna look at that and go "fixing time!!" and re-upload *all* your old data just to correct the modtimes. 😭 If you do **not** want that chaos, use the `--size-only` or `--checksum` flag to shut it down.

Dropbox also has its own hash type (https://www.dropbox.com/developers/reference/content-hash) which gets checked for **all** transfers. Every single one. No cap. 💅

---

## 🚫 Restricted filename characters 🎀

Here's the list of characters that get swapped out, because Dropbox said no:

- `NUL` — `0x00` — replaced with `␀`
- `/` — `0x2F` — replaced with `／`
- `DEL` — `0x7F` — replaced with `␡`
- `\` — `0x5C` — replaced with `＼`

File names *also* cannot **end** with the following characters. Important nuance bestie — these only get replaced if they're the **last character in the name**:

- `SP` — `0x20` — replaced with `␠`

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), because they literally can't be used in JSON strings. JSON said nope 🙅‍♀️

---

## 📦 Batch mode uploads 🔥

Using batch mode uploads is **very important for performance** when you're on the Dropbox API. Like, this is not optional-if-you-want-speed energy. Go read the dropbox performance guide (https://developers.dropbox.com/dbx-performance-guide) for the full context.

There are **3 modes** rclone can use for uploads. Let's meet them 👑

### `--dropbox-batch-mode off`

In this mode rclone will **not** use upload batching. This was the default before rclone v1.55. The downside? It is very likely to hit `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 it continues, which *really* slows down transfers. 🐌

This will happen especially if `--transfers` is large, so this mode isn't recommended — except for compatibility or for 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 getting `too_many_requests` errors. Slay. ✨

This mode ensures **full data integrity**. 💖

Note that there may be a pause when quitting rclone while rclone finishes up the last batch using this mode — it's just tidying up, don't panic.

### `--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. Which 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. Tradeoff queen 💅

This provides the maximum possible upload speed, especially with lots of small files — but rclone can't check the file got uploaded properly using this mode. 👀

If you're using this mode, then running "rclone check" after the transfer completes is **recommended**. Or you could do an initial transfer with `--dropbox-batch-mode async` and then do a final transfer with `--dropbox-batch-mode sync` (the default). Best of both worlds fr fr.

Note that there may be a pause when quitting rclone while rclone finishes up the last batch using this mode.

---

## 📤 Exporting files 🌈

Certain files in Dropbox are "exportable", such as Dropbox Paper documents. These files need to be converted to another format in order to be downloaded. Often multiple formats are available for conversion.

When rclone downloads an exportable file, it chooses the format to download based on the `--dropbox-export-formats` setting. By default, the export formats are `html,md`, which are sensible defaults for Dropbox Paper. 🎀

Rclone chooses the **first** format ID in the export formats list that Dropbox supports for a given file. If no format in the list is usable, rclone will choose the default format that Dropbox suggests.

Rclone will change the extension to correspond to the export format. Here are some examples of how extensions are mapped:

- File type: Paper — Filename in Dropbox: `mydoc.paper` — Filename in rclone: `mydoc.html`
- File type: Paper template — Filename in Dropbox: `mydoc.papert` — Filename in rclone: `mydoc.papert.html`
- File type: other — Filename in Dropbox: `mydoc` — Filename in rclone: `mydoc.html`

Importing exportable files is **not yet** supported by rclone. 🙈

Here are the supported export extensions known by rclone. Note that rclone does **not currently** support other formats not on this list, even if Dropbox supports them. Also, Dropbox could change the list of supported formats at any time — so like, stay on your toes.

- Format ID `html` — Name `HTML` — HTML document
- Format ID `md` — Name `Markdown` — Markdown text format

---

## ⚙️ Standard options 🌸

Here are the Standard options specific to dropbox (Dropbox).

### `--dropbox-client-id`

OAuth Client Id.

Leave blank normally. (seriously, leave it blank unless you know what you're doing 💅)

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). Buckle up, there's a bunch.

### `--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.

Note that this option is **NOT supported by all backends**. 👑

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-impersonate-admin`

Team admin ID to use when performing actions as a team administrator.

This sets the `Dropbox-API-Select-Admin` header with the given team member ID (for example `"dbmid:..."`).

This takes a team member ID directly rather than an email address.

Note that if you want to use impersonate_admin, you should make sure this flag is set when running "rclone config" as this will cause rclone to request the `team_data.member` scope which it won't normally.

Using the `team_data.member` 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 `team_data.member`.

Properties:

- Config: `impersonate_admin`
- Env Var: `RCLONE_DROPBOX_IMPERSONATE_ADMIN`
- 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. 😭

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. ✨

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-skip-shared-folders`

Instructs rclone to skip all shared folders.

<pink>Okay so when this is set</pink>, any folder that's a shared folder mount point gets <hotpink>yeeted straight out of directory listings</hotpink> — regardless of ownership, no cap. It's giving very useful if you'd rather back up your shared folders separately with their own remote configured with the shared folder namespace. 🎀

- **Config:** `skip_shared_folders`
- **Env Var:** `RCLONE_DROPBOX_SKIP_SHARED_FOLDERS`
- **Type:** `bool`
- **Default:** `false`

- **`--dropbox-skip-unowned-folders`** — tells rclone to skip shared folders that aren't owned by the current user, periodt. ✨
  - When it's set, any folder that's a shared folder mount point **and** not owned by the current user is excluded from directory listings. This is the move when you're backing up multiple Dropbox accounts that share common folders, so you don't duplicate the same shared data across all of them. 💅
  - <yellow>Note:</yellow> in Dropbox Business, 'Team Folders' are owned by the Team. For standard team members these folders evaluate as 'unowned' (editor/viewer access), so they'll be excluded by this flag. To back up Team Folders, don't use this flag, or run the backup using a Team Admin account. 👑
  - If `--dropbox-skip-shared-folders` is also enabled, this flag has <red>no effect</red>.
  - Heads up bestie, this makes an extra API call per shared folder mount point.
  - **Properties:**
    - **Config:** `skip_unowned_folders`
    - **Env Var:** `RCLONE_DROPBOX_SKIP_UNOWNED_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 (`https://rclone.org/overview/#encoding`) 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-export-formats`** — comma separated list of preferred formats for exporting files. 🎀
  - Certain Dropbox files can only be accessed by exporting them to another format. These include Dropbox Paper documents. 📄
  - For each such file, rclone will choose the first format on this list that Dropbox considers valid. If none of them is valid, it'll choose Dropbox's default format.
  - Known formats include: `"html"`, `"md"` (markdown)
  - **Properties:**
    - **Config:** `export_formats`
    - **Env Var:** `RCLONE_DROPBOX_EXPORT_FORMATS`
    - **Type:** `CommaSepList`
    - **Default:** `html,md`

- **`--dropbox-skip-exports`** — skip exportable files in all listings. 👻
  - If given, exportable files practically become **invisible** to rclone. Not me making whole files disappear fr fr.
  - **Properties:**
    - **Config:** `skip_exports`
    - **Env Var:** `RCLONE_DROPBOX_SKIP_EXPORTS`
    - **Type:** `bool`
    - **Default:** `false`

- **`--dropbox-show-all-exports`** — show all exportable files in listings. ✨
  - Adding this flag lets all exportable files be server side copied. Note that rclone doesn't add extensions to the exportable file names in this mode.
  - > <red>Do NOT use this flag when trying to download exportable files</red> — rclone will fail to download them. 😭
  - **Properties:**
    - **Config:** `show_all_exports`
    - **Env Var:** `RCLONE_DROPBOX_SHOW_ALL_EXPORTS`
    - **Type:** `bool`
    - **Default:** `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 (`https://rclone.org/dropbox/#batch-mode`)
  - This has 3 possible values:
    - `off` — no batching
    - `sync` — batch uploads and check completion (default)
    - `async` — batch upload and don't check completion
  - Rclone will close any outstanding batches when it exits, which may make a delay on quit. 🐢
  - **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. It has to be **less than 1000**.
  - By default this is `0`, which means rclone will calculate the batch size depending on the setting of `batch_mode`. Like it does the math for you, cute.
    - `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 **great idea** if you're uploading lots of small files, since it makes them a lot quicker. You can use `--transfers 32` to maximise throughput. 🔥
  - **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. ⏳
  - If an upload batch is idle for more than this long, then it gets uploaded.
  - 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-description`** — description of the remote. 🌈
  - **Properties:**
    - **Config:** `description`
    - **Env Var:** `RCLONE_DROPBOX_DESCRIPTION`
    - **Type:** `string`
    - **Required:** `false`

---

# 💀 Limitations 💀 (aka the plot twists)

Bestie, settle in, because Dropbox has some quirks and we're listing every single one. 🙈

- Dropbox is <hotpink>case insensitive</hotpink>, so you literally can't have a file called `Hello.doc` and one called `hello.doc`. Pick a lane.
- There are some file names such as `thumbs.db` that Dropbox can't store. There's a full list of them in the "Ignored Files" section of this document (`https://www.dropbox.com/en/help/145`). 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. 🫶
- Some errors may occur if you try to sync copyright-protected files, because Dropbox has its own copyright detector (`https://techcrunch.com/2014/03/30/how-dropbox-knows-when-youre-sharing-copyrighted-stuff-without-actually-looking-at-your-stuff/`) 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`. 🧚
- 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 (`https://forum.rclone.org/t/rclone-link-dropbox-permissions/23211`) and the dropbox SDK issue (`https://github.com/dropbox/dropbox-sdk-go-unofficial/issues/75`). 🔗
- Modification times for Dropbox Paper documents are <yellow>not exact</yellow>, and may not change for some period after the document is edited. To make sure you get recent changes in a sync, either wait an hour or so, or use `--ignore-times` to force a full sync. ⏰

---

# 👑 Get your own Dropbox App ID 👑

When you use rclone with Dropbox in its default configuration, you're using **rclone's App ID**. This is shared between all the rclone users. It's giving community pool energy. 🌊

Here's how to create your own Dropbox App ID for rclone:

1. Log into the Dropbox App console (`https://www.dropbox.com/developers/apps/create`) 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 (`https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/How-to-create-team-folder-inside-my-app-s-folder/m-p/601005/highlight/true#M27911`)). 💅

4. Name your App. The app name is <hotpink>global</hotpink>, 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 for Storage Made Easy's Enterprise File Fabric™ (<https://storagemadeeasy.com/about/>) — it's the whole ✨ software solution ✨ that pulls your File *and* Object Storage together and unifies it all behind one global file system. Bestie, it's giving "one filesystem to rule them all" and honestly? We love that for us. 🫶

---

### 🎀 Configuration 🎀

okay so the first setup step for the Enterprise File Fabric backend is grabbing a token from the Enterprise File Fabric, and yes you literally do that in your browser. luckily `rclone config` holds your hand through the whole thing like the icon that it is. 💅

Here's how you'd make a remote called `remote`. First things first:

rclone config

and then it walks you through it, interactive style:

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 it's configured you can use rclone like this (swap `remote` for whatever name you gave yours, bestie 🦋):

List the directories in the top level of your Enterprise File Fabric:

rclone lsd remote:

List *all* the files in your Enterprise File Fabric:

rclone ls remote:

To copy a local directory onto 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, accurate to **1 second**, and rclone uses those to figure out whether objects need syncing or not. so precise, slay.

The Enterprise File Fabric does **not** support any data hashes at this time. no hashes, we cope. 😭

---

### 🚫 Restricted filename characters 🚫

The default restricted characters set (<https://rclone.org/overview/#restricted-characters>) will be replaced.

Invalid UTF-8 bytes will also be replaced (<https://rclone.org/overview/#invalid-utf8>), because babes, they literally can't be used in JSON strings. it's not a vibe, it's just a format limit. 💀

---

### 🫙 Empty files 🫙

Empty files aren't supported by the Enterprise File Fabric. so rclone does a little workaround: it 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. iconic behaviour, honestly. ✨

---

### 📁 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 work out the correct root all by itself, main character energy. 👑

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 plot twist — you can use `rclone lsf` to find them, like so:

$ 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`. periodt. 💅

---

### 🌟 Standard options 🌟

Here are the Standard options specific to `filefabric` (Enterprise File Fabric).

#### `--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's 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-term commitment, we love to see it. 💖

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).

#### `--filefabric-token`

Session Token.

This is a session token which rclone caches in the config file. It's usually valid for **1 hour**.

**Don't set this value** — rclone will set it automatically. hands off, bestie, it's got it. 🙈

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.

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.

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 (<https://rclone.org/overview/#encoding>) 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

# 💖 FileLu 💖

<pink>FileLu</pink> (`https://filelu.com/`) is that reliable cloud storage bestie offering features like secure file uploads, downloads, flexible storage options, and sharing capabilities. With support for high storage limits and seamless integration with rclone, FileLu makes managing files in the cloud a whole *easy* experience. Its cross-platform file backup services let you upload and back up files from literally any internet-connected device. 🦋

> Heads up bestie 👑 — FileLu now has a fully featured S3 backend called FileLu S5, an industry standard S3 compatible object store. Slay.

## ✨ Configuration ✨

Here's an example of how to make a remote called `filelu`. 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> filelu Type of storage to configure. Choose a number from below, or type in your own value [snip] xx / FileLu Cloud Storage \ "filelu" [snip] Storage> filelu Enter your FileLu Rclone Key: key> YOUR_FILELU_RCLONE_KEY RC_xxxxxxxxxxxxxxxxxxxxxxxx Configuration complete.

Keep this "filelu" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y

## 🎀 Paths 🎀

A path with **no** initial `/` will operate in the Rclone directory, iykyk.

A path **with** an initial `/` will operate at the root, where you can see the Rclone directory.

$ rclone lsf TestFileLu:/ CCTV/ Camera/ Documents/ Music/ Photos/ Rclone/ Vault/ Videos/

## 🧚 Example Commands 🧚

Make a new folder named `foldername` in the Rclone directory:

rclone mkdir filelu:foldername

Delete a folder on FileLu:

rclone rmdir filelu:/folder/path/

Delete a file on FileLu:

rclone delete filelu:/hello.txt

List files from your FileLu account:

rclone ls filelu:

List all folders:

rclone lsd filelu:

Copy a specific file to the FileLu root:

rclone copy D:\hello.txt filelu:

Copy files from a local directory to a FileLu directory:

rclone copy D:/local-folder filelu:/remote-folder/path/

Download a file from FileLu into a local directory:

rclone copy filelu:/file-path/hello.txt D:/local-folder

Move files from a local directory to a FileLu directory:

rclone move D:\local-folder filelu:/remote-path/

Sync files from a local directory to a FileLu directory:

rclone sync --interactive D:/local-folder filelu:/remote-path/

Mount remote to local Linux:

rclone mount filelu: /root/mnt --vfs-cache-mode full

Mount remote to local Windows:

rclone mount filelu: D:/local_mnt --vfs-cache-mode full

Get storage info about the FileLu account:

rclone about filelu:

And literally all the other rclone commands are supported by this backend. 💅

## 🌸 FolderID instead of folder path 🌸

We use the **FolderID** instead of the folder name to prevent errors when users have identical folder names or paths. Think about it bestie: if a user has two or three folders named `"test_folders"`, the system may become confused and won't know which folder to move. 😭 In large storage systems, some clients have hundreds of thousands of folders and a few millions of files, so duplicate folder names or paths are quite common. So yeah, FolderID it is.

## 💜 Modification Times and Hashes 💜

FileLu supports both modification times and MD5 hashes.

FileLu only supports filenames and folder names up to **255 characters** in length, where a character is a Unicode character. No cap. ✨

## 🍓 Duplicated Files 🍓

When uploading and syncing via Rclone, FileLu does **not** allow uploading duplicate files within the same directory. However — plot twist — you *can* upload duplicate files, provided they are in different directories (folders). 🌈

## 💀 Failure to Log / Invalid Credentials or KEY 💀

Make sure you have the correct Rclone key, which can be found in My Account (`https://filelu.com/account/`). Every single time you toggle Rclone OFF and ON in My Account, a new `RC_xxxxxxxxxxxxxxxxxxxx` key is generated. Be sure to update your Rclone configuration with the new key, fr fr. 🙈

If you're connecting to your FileLu remote for the first time and encounter an error such as:

Failed to create file system for "my-filelu-remote:": couldn't login: Invalid credentials

...then ensure your Rclone Key is correct. That's it, that's the fix.

## 🔥 Process killed 🔥

Accounts with large files or extensive metadata may experience **significant memory usage** during list/sync operations. So make sure the system running rclone has sufficient memory and CPU to handle these operations, bestie — no one wants their process getting killed mid-sync. 😭

## 🌟 Standard options 🌟

Here are the Standard options specific to `filelu` (FileLu Cloud Storage).

### `--filelu-key`

Your FileLu Rclone key from My Account

Properties:

- **Config:** `key`
- **Env Var:** `RCLONE_FILELU_KEY`
- **Type:** `string`
- **Required:** `true`

## ⭐ Advanced options ⭐

Here are the Advanced options specific to `filelu` (FileLu Cloud Storage).

### `--filelu-upload-cutoff`

Cutoff for switching to chunked upload. Any files larger than this will be uploaded in chunks of `chunk_size`.

Properties:

- **Config:** `upload_cutoff`
- **Env Var:** `RCLONE_FILELU_UPLOAD_CUTOFF`
- **Type:** `SizeSuffix`
- **Default:** `500Mi`

### `--filelu-chunk-size`

Chunk size to use for uploading. Used for multipart uploads.

Properties:

- **Config:** `chunk_size`
- **Env Var:** `RCLONE_FILELU_CHUNK_SIZE`
- **Type:** `SizeSuffix`
- **Default:** `64Mi`

### `--filelu-encoding`

The encoding for the backend.

See the encoding section in the overview (`https://rclone.org/overview/#encoding`) for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_FILELU_ENCODING`
- **Type:** `Encoding`
- **Default:** `Slash,LtGt,DoubleQuote,SingleQuote,BackQuote,Dollar,Colon,Question,Asterisk,Pipe,Hash,Percent,BackSlash,CrLf,Del,Ctl,LeftSpace,LeftPeriod,LeftTilde,LeftCrLfHtVt,RightSpace,RightPeriod,RightCrLfHtVt,InvalidUtf8,Dot,SquareBracket,Semicolon,Exclamation`

### `--filelu-description`

Description of the remote.

Properties:

- **Config:** `description`
- **Env Var:** `RCLONE_FILELU_DESCRIPTION`
- **Type:** `string`
- **Required:** `false`

## 🌈 Limitations 🌈

This backend uses a custom library implementing the FileLu API. While it supports file transfers, some advanced features may not yet be available. Please report any issues to the rclone forum (`https://forum.rclone.org/`) for troubleshooting and updates — the community ate and left no crumbs, they'll help you out. 🫶

For further information, visit FileLu's website (`https://filelu.com/`).

## 💖 Configuration 💖

okay bestie, listen up, because this first bit is **so** important 🫶 Setting up Filen means you need an API key for your account, and rn the *only* way to get one is through the Filen CLI (<pink>`https://github.com/FilenCloudDienste/filen-cli`</pink>). so yeah — download the CLI first, log in, then run the <mint>`export-api-key`</mint> command. that's the whole vibe, no cap.

> ⚠️ <yellow>**lowkey crucial:**</yellow> if you change your Filen account password, you **have** to update your rclone config with the new password *and* a freshly re-exported API key (via <mint>`export-api-key`</mint>). do not forget. i am begging. 😭

here's an example of making a remote called <purple>`FilenRemote`</purple> ✨ First run:

rclone config

and it will hold your hand through the interactive setup like this:

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n

name> FilenRemote Option Storage.

Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / Filen \ "filen" [snip] Storage> filen

Option Email. The email of your Filen account Enter a value. Email> youremail@provider.com

Option Password. The password of your Filen account 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:

Option API Key. An API Key for your Filen account Get this using the Filen CLI export-api-key command You can download the Filen CLI from https://github.com/FilenCloudDienste/filen-cli 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

Configuration complete. Options:

• type: filen
• Email: youremail@provider.com
• Password: * ENCRYPTED *
• API Key: * ENCRYPTED * Keep this "FilenRemote" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

look at you go, configuring remotes like a whole main character 👑

---

## 🕰️ Modification times and hashes 🕰️

Modification times are <green>fully supported for files</green>, but for <purple>directories</purple>, only the **creation time** matters. that's the rule, okay?

Filen supports <cyan>Blake3</cyan> hashes. slay. 🔥

---

## 🚫 Restricted filename characters 🚫

Invalid UTF-8 bytes will be replaced (see the overview: <pink>`https://rclone.org/overview/#invalid-utf8`</pink>). that's it, that's the tea 🍓

---

## 🔑 API Key 🔑

(this one's just a lil signpost in the original — nothing hiding under here, bestie, the real API key deets live up in Configuration 💅)

---

## ⭐ Standard options ⭐

Here are the Standard options specific to <purple>filen</purple> (Filen). yes, we're doing all of them, and yes, i'm excited about it 💖

### <cyan>`--filen-email`</cyan>

Email of your Filen account 📧

Properties:

- Config: `email`
- Env Var: `RCLONE_FILEN_EMAIL`
- Type: `string`
- Required: `true`

---

### <cyan>`--filen-password`</cyan>

Password of your Filen account 🔒

> <yellow>**NB**</yellow> Input to this must be obscured — see <mint>`rclone obscure`</mint> (<pink>`https://rclone.org/commands/rclone_obscure/`</pink>).

Properties:

- Config: `password`
- Env Var: `RCLONE_FILEN_PASSWORD`
- Type: `string`
- Required: `true`

---

### <cyan>`--filen-api-key`</cyan>

API Key for your Filen account 🗝️

Get this using the Filen CLI `export-api-key` command. You can download the Filen CLI from <pink>`https://github.com/FilenCloudDienste/filen-cli`</pink>.

> <yellow>**NB**</yellow> Input to this must be obscured — see <mint>`rclone obscure`</mint> (<pink>`https://rclone.org/commands/rclone_obscure/`</pink>).

Properties:

- Config: `api_key`
- Env Var: `RCLONE_FILEN_API_KEY`
- Type: `string`
- Required: `true`

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to <purple>filen</purple> (Filen). buckle up, these ones are spicy 🌶️ (well. the first two are. the rest are ✨internal✨, ok)

### <cyan>`--filen-upload-concurrency`</cyan>

Concurrency for chunked uploads. 🚀

This is the upper limit for how many transfers for the same file are running concurrently.

> 💀 <red>**DANGER:**</red> setting this above to a value smaller than `1` will cause uploads to **deadlock**. do not do that. i'm serious.

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. go faster bestie 💨

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_FILEN_UPLOAD_CONCURRENCY`
- Type: `int`
- Default: `16`

---

### <cyan>`--filen-encoding`</cyan>

The encoding for the backend. 🧚

See the encoding section in the overview (<pink>`https://rclone.org/overview/#encoding`</pink>) for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_FILEN_ENCODING`
- Type: `Encoding`
- Default: `Slash,Del,Ctl,InvalidUtf8,Dot`

---

### <cyan>`--filen-master-keys`</cyan>

Master Keys (**internal use only**) 🤫

Properties:

- Config: `master_keys`
- Env Var: `RCLONE_FILEN_MASTER_KEYS`
- Type: `string`
- Required: `false`

---

### <cyan>`--filen-private-key`</cyan>

Private RSA Key (**internal use only**) 🔐

Properties:

- Config: `private_key`
- Env Var: `RCLONE_FILEN_PRIVATE_KEY`
- Type: `string`
- Required: `false`

---

### <cyan>`--filen-public-key`</cyan>

Public RSA Key (**internal use only**) 🔓

Properties:

- Config: `public_key`
- Env Var: `RCLONE_FILEN_PUBLIC_KEY`
- Type: `string`
- Required: `false`

---

### <cyan>`--filen-auth-version`</cyan>

Authentication Version (**internal use only**) 🪪

Properties:

- Config: `auth_version`
- Env Var: `RCLONE_FILEN_AUTH_VERSION`
- Type: `string`
- Required: `false`

---

### <cyan>`--filen-base-folder-uuid`</cyan>

UUID of Account Root Directory (**internal use only**) 📁

Properties:

- Config: `base_folder_uuid`
- Env Var: `RCLONE_FILEN_BASE_FOLDER_UUID`
- Type: `string`
- Required: `false`

---

### <cyan>`--filen-description`</cyan>

Description of the remote. 📝

Properties:

- Config: `description`
- Env Var: `RCLONE_FILEN_DESCRIPTION`
- Type: `string`
- Required: `false`

---

that's the whole Filen situation, bestie — go forth and sync 💜✨

# 💖 Files.com 💖

<cyan>Files.com</cyan> (https://www.files.com/) is a cloud storage service that gives you a secure and easy way to store and share your files. It's giving "your files, but with a bodyguard" energy. 🫶

The initial setup for filescom is literally just authenticating with your Files.com account. You do that by handing over your site subdomain, username, and password. Or — plot twist — you can authenticate using an API Key from Files.com (https://www.files.com/docs/sdk-and-apis/api-keys/) instead. Either way, `rclone config` walks you through it, no stress. ✨

## 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. <purple>Bestie era unlocked.</purple> 🎀

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

---

## Restricted filename characters 🚫

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters) the following characters are **also** replaced:

- Character: `\`
- Value: `0x5C`
- Replacement: `＼`

File names also can't **end** with the following characters. These only get replaced if they are the *last* character in the name:

- `SP` — `0x20` — `␠`
- `LF` — `0x0A` — `␊`
- `CR` — `0x0D` — `␍`
- `HT` — `0x09` — `␉`
- `VT` — `0x0B` — `␋`

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8). 😭

<hotpink>Heads up bestie:</hotpink> Files.com treats the replacements `／` and `＼` as if they were `/` and `\`, and the names `．` and `．．` as if they were `.` and `..`, and rejects them with `Invalid path`. This means that files with `/` or `\` in their names, or which are called `.` or `..`, **can't be stored on Files.com**. Periodt. 💀

---

## Hashes 🔐

In December 2024 files.com started supporting more checksums (https://www.files.com/blog/2024/11/01/new-modern-checksum-options-now-available-with-opt).

However if you want hashes you **must** enable them in your site by visiting the "File Integrity" section in "Data Governance" to configure your settings and select the checksum algorithms that meet your requirements. 👑

Rclone currently only support `CRC32` and `MD5` for use in syncing but selecting more checksums will not affect rclone's operations.

For use with rclone, selecting at least `MD5` is recommended so rclone can do an end to end integrity check. <mint>Do it for the vibes. Do it for the integrity check.</mint> ✅

---

## 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` (https://rclone.org/commands/rclone_obscure/). No plaintext, we don't do that here. 🙈

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 (https://rclone.org/overview/#encoding) 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 — the classic, the OG, the one that's been around longer than your fave. Rclone FTP support is provided using the `github.com/jlaffaye/ftp` (https://godoc.org/github.com/jlaffaye/ftp) package. 🧚

## Limitations of Rclone's FTP backend 🚧

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 (https://rclone.org/docs/#connection-strings) 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` (https://rclone.org/commands/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`. <yellow>And listen:</yellow> the default FTPS port is `990`, **not** `21` — and it can be set with `--ftp-port`. Don't get caught out, bestie. 💅

### ✨ TLS Options ✨

ok so for <pink>Implicit</pink> AND <pink>Explicit</pink> TLS you can use these flags, and they're FTP-backend-specific, iykyk 💅:

--ftp-no-check-certificate Do not verify the TLS certificate of the server --ftp-disable-tls13 Disable TLS 1.3 (workaround for FTP servers with buggy TLS) --ftp-tls-cache-size int Size of TLS session cache for all control and data connections (default 32)

BUT bestie, the plot twist is you can <hotpink>also</hotpink> use any of the global TLS flags, like:

--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 --no-check-certificate Do not verify the server SSL certificate (insecure)

And if you need those to live in the config file so they apply <purple>to just the FTP backend</purple> and nowhere else, use the override syntax, periodt:

override.ca_cert = XXX override.client_cert = XXX override.client_key = XXX

---

### 🌸 Restricted filename characters 🌸

On top of the default restricted characters set (`https://rclone.org/overview/#restricted-characters`), these ones get replaced too:

File names literally **cannot end** with the following characters. And the replacement is only limited to the **last character** in a file name — so it's giving surgical precision 🎀:

- Character `SP` — Value `0x20` — Replacement `␠`

And not every FTP server can handle every character in file names, so watch out:

- `proftpd` — forbidden characters: `*`
- `pureftpd` — forbidden characters: `\ [ ]`

Good news tho 💖 — this backend's interactive configuration wizard hands you a selection of sensible encoding settings for the major FTP servers: <cyan>ProFTPd</cyan>, <cyan>PureFTPd</cyan>, <cyan>VsFTPd</cyan>. Just hit a selection number when it prompts you. Slay.

---

### 👑 Standard options 👑

Here are the Standard options specific to ftp (FTP). bestie we're going in order, no skipping 🫶

**`--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` (`https://rclone.org/commands/rclone_obscure/`). Don't rawdog your password in there, bestie 😭

Properties:

  - Config: `pass`
  - Env Var: `RCLONE_FTP_PASS`
  - Type: `string`
  - Required: `false`

**`--ftp-tls`**

Use Implicit FTPS (FTP over TLS).

When you're on implicit FTP over TLS the client connects using TLS <purple>right from the start</purple>, 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 (FTP over TLS).

With explicit FTP over TLS the client explicitly asks the server for security so it can upgrade a plain text connection to an encrypted one. **Cannot** be used in combination with implicit FTPS.

Properties:

  - Config: `explicit_tls`
  - Env Var: `RCLONE_FTP_EXPLICIT_TLS`
  - Type: `bool`
  - Default: `false`

---

### 🔥 Advanced options 🔥

Here are the Advanced options specific to ftp (FTP). buckle up babes, this is the long one ✨

**`--ftp-concurrency`**

Maximum number of FTP simultaneous connections, `0` for unlimited.

> Note that setting this is **very likely** to cause deadlocks so it should be used with care. 💀

If you are 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 server advertises support.

Properties:

  - Config: `disable_epsv`
  - Env Var: `RCLONE_FTP_DISABLE_EPSV`
  - Type: `bool`
  - Default: `false`

**`--ftp-disable-mlsd`**

Disable using MLSD even if 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 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 (VsFtpd quirk)

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. This will disable the use of MLSD.

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 TLS session cache for all control and data connections.

TLS cache allows to resume TLS sessions and reuse PSK between connections. Increase if default size is not enough resulting in TLS resumption errors. 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 (workaround for FTP servers with buggy TLS)

Properties:

  - Config: `disable_tls13`
  - Env Var: `RCLONE_FTP_DISABLE_TLS13`
  - Type: `bool`
  - Default: `false`

**`--ftp-allow-insecure-tls-ciphers`**

Allow insecure TLS ciphers

Setting this flag will allow the usage of the following TLS ciphers **in addition to the secure defaults** (so yeah, it's exactly as sketchy as it sounds, be careful bestie 🙈):

- `TLS_RSA_WITH_AES_128_GCM_SHA256`

Properties:

  - Config: `allow_insecure_tls_ciphers`
  - Env Var: `RCLONE_FTP_ALLOW_INSECURE_TLS_CIPHERS`
  - 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 FTP password when 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-http-proxy`**

URL for HTTP CONNECT proxy

Set this to a URL for an HTTP proxy which supports the HTTP CONNECT verb.

Supports the format `http://user:pass@host:port`, `http://host:port`, `http://host`.

Example:

http://myUser:myPass@proxyhostname.example.com:8000

Properties:

  - Config: `http_proxy`
  - Env Var: `RCLONE_FTP_HTTP_PROXY`
  - Type: `string`
  - Required: `false`

**`--ftp-no-check-upload`**

Don't check the upload is OK

Normally rclone will try to check the upload exists after it has uploaded a file, to make sure the size and modification time are as expected.

This flag stops rclone doing these checks. This enables uploading to folders which are write only.

> You will **likely need to use the `--inplace` flag also** if 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 (`https://rclone.org/overview/#encoding`) 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 — passive is the only supported one. Rclone's FTP implementation is **not compatible with active mode**, because the library it uses doesn't support it (`https://github.com/jlaffaye/ftp/issues/29`). And honestly it will likely **never** be supported, due to security concerns. So that door is closed fr fr 💀

Rclone's FTP backend supports **no checksums at all**, but it can compare file sizes.

`rclone about` is **not supported** by the FTP backend. And backends without this capability can't determine free space for an rclone mount, and 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` (`https://rclone.org/overview/#optional-features`) and `rclone about` (`https://rclone.org/commands/rclone_about/`).

And last thing, 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. Not a bug, just how it is 🦋

- `--timeout` isn't supported (but `--contimeout` is, bestie — yes they're literally different things 💅).

- `--bind` isn't supported. nope, not a thing here ✨

- Rclone's FTP backend *could* support server-side move but does not at present. (it's giving "someday, maybe" energy 😭)

- The `ftp_proxy` environment variable is not currently supported. 🙈

## Modification times ✨

File modification time (timestamps) is supported to <green>1 second resolution</green> for the major FTP servers: <pink>ProFTPd</pink>, <pink>PureFTPd</pink>, <pink>VsFTPd</pink>, and <pink>FileZilla FTP server</pink>. Heads up though — the <yellow>VsFTPd</yellow> 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. (iykyk 😭)

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. slay ✨
- A value of `3153600000000000000` (or another large number) means "unsupported". 💀

---

# Gofile 🍓

Gofile (<blue>https://gofile.io</blue>) is a content storage and distribution platform. Its aim is to provide 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 "My Profile" section. Copy the "Account API token" for use in the config file.

> Note that if you wish to connect rclone to Gofile you will need a premium account. 👑

## 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

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 (replace `remote` with the name you gave your remote):

List directories and files in the top level of your Gofile:

rclone lsf remote:

To copy a local directory to a Gofile directory called `backup`:

rclone copy /home/source remote:backup

## Modification times and hashes 🦋

Gofile supports modification times with a resolution of <green>1 second</green>.

Gofile supports MD5 hashes, so you can use the `--checksum` flag. 💖

## Restricted filename characters 🌸

In addition to the default restricted characters set (<blue>https://rclone.org/overview/#restricted-characters</blue>) the following characters are also replaced:

Character Value Replacement ──────────────────────────────── ! 0x21 ！ " 0x22 ＂

• 0x2A ＊ : 0x3A ： < 0x3C ＜

0x3E ＞

? 0x3F ？ \ 0x5C ＼

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 ──────────────────────────────── . 0x2E ．

Invalid UTF-8 bytes will also be replaced (<blue>https://rclone.org/overview/#invalid-utf8</blue>), 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. Note that `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 (<blue>https://rclone.org/overview/#encoding</blue>) 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 <yellow>255 characters</yellow> in length, where a character is a unicode character.

Directories should not be cached for more than 24h 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 100,000 items. 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:

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 / Google Cloud Storage (this is not Google Drive) \ "google cloud storage" [snip] Storage> google cloud storage Google Application Client Id - leave blank normally. client_id> Google Application Client Secret - leave blank normally. client_secret> Project number optional - needed only for list/create/delete buckets - see your developer console. project_number> 12345678 Service Account Credentials JSON file path - needed only if you want use SA instead of interactive login. service_account_file> Access Control List for new objects. Choose a number from below, or type in your own value 1 / Object owner gets OWNER access, and all Authenticated Users get READER access. \ "authenticatedRead" 2 / Object owner gets OWNER access, and project team owners get OWNER access. \ "bucketOwnerFullControl" 3 / Object owner gets OWNER access, and project team owners get READER access. \ "bucketOwnerRead" 4 / Object owner gets OWNER access [default if left blank]. \ "private" 5 / Object owner gets OWNER access, and project team members get access according to their roles. \ "projectPrivate" 6 / Object owner gets OWNER access, and all Users get READER access. \ "publicRead" object_acl> 4 Access Control List for new buckets. Choose a number from below, or type in your own value 1 / Project team owners get OWNER access, and all Authenticated Users get READER access. \ "authenticatedRead" 2 / Project team owners get OWNER access [default if left blank]. \ "private" 3 / Project team members get access according to their roles. \ "projectPrivate" 4 / Project team owners get OWNER access, and all Users get READER access. \ "publicRead" 5 / Project team owners get OWNER access, and all Users get WRITER access. \ "publicReadWrite" bucket_acl> 2 Location for the newly created buckets. Choose a number from below, or type in your own value 1 / Empty for default location (US). \ "" 2 / Multi-regional location for Asia. \ "asia" 3 / Multi-regional location for Europe. \ "eu" 4 / Multi-regional location for United States. \ "us" 5 / Taiwan. \ "asia-east1" 6 / Tokyo. \ "asia-northeast1" 7 / Singapore. \ "asia-southeast1" 8 / Sydney. \ "australia-southeast1" 9 / Belgium. \ "europe-west1" 10 / London. \ "europe-west2" 11 / Iowa. \ "us-central1" 12 / South Carolina. \ "us-east1" 13 / Northern Virginia. \ "us-east4" 14 / Ohio. \ "us-east5" 15 / Oregon. \ "us-west1" location> 12 The storage class to use when storing objects in Google Cloud Storage. Choose a number from below, or type in your own value 1 / Default \ "" 2 / Multi-regional storage class \ "MULTI_REGIONAL" 3 / Regional storage class \ "REGIONAL" 4 / Nearline storage class \ "NEARLINE" 5 / Coldline storage class \ "COLDLINE" 6 / Durable reduced availability storage class \ "DURABLE_REDUCED_AVAILABILITY" storage_class> 5 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: google cloud storage
• client_id:
• client_secret:
• token: {"AccessToken":"xxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","RefreshToken":"x/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxx","Expiry":"2014-07-17T20:49:14.929208288+01:00","Extra":null}
• project_number: 12345678
• object_acl: private
• bucket_acl: private Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y

Okay bestie, that whole wall of text was just you manifesting a <purple>remote</purple> ✨ and here's the part that matters: see the remote setup docs (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available. Like, that machine is offline, it's giving cozy but inconvenient 💅.

> Heads up! rclone runs a <hotpink>webserver</hotpink> on your local machine to collect the token as returned from Google if using web browser to automatically authenticate. 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, or use manual mode. Literally just a lil temporary guest, no cap.

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

You can set up rclone with Google Cloud Storage in an <cyan>unattended mode</cyan>, 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. Fr fr, the machines that just vibe and work with nobody watching 🫶.

To get credentials for Google Cloud Platform IAM Service Accounts (https://cloud.google.com/iam/docs/service-accounts), please head to the Service Account (https://console.cloud.google.com/permissions/serviceaccounts) section of the Google Developer Console. Service Accounts behave just like normal User permissions in Google Cloud Storage ACLs (https://cloud.google.com/storage/docs/access-control), so you can limit their access (e.g. make them read only). 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. Iconic behavior honestly 👑.

To use a Service Account instead of 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. They also bypass oauth login flow, which is simpler on remote VMs that lack a web browser. Security but make it ✨convenient✨.

If you already have a working service account, skip to step 3.

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 (https://cloud.google.com/compute/docs/access/service-accounts)

- Guide on Service Accounts using Key Files (less secure, but similar concepts) (https://forum.rclone.org/t/access-using-google-service-account/24822/2)

---

### 🦋 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-but-don't-touch energy, respectfully 🙈.

---

### 💖 Application Default Credentials

If no other source of credentials is provided, rclone will fall back to Application Default Credentials (https://cloud.google.com/video-intelligence/docs/common/auth#authenticating_with_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 (https://cloud.google.com/container-registry/docs/advanced-authentication#gcloud_as_a_docker_credential_helper).

Note that in the case application default credentials are used, there is no need to explicitly configure a project number. Periodt 💅.

### <cyan>--fast-list</cyan>

ok so this remote is one of the cool kids — it **supports `--fast-list`** ✨ which means you can get away with **fewer transactions** in exchange for using **more memory**. Pick your fighter: less network chatter, more RAM. Head to the rclone docs at `https://rclone.org/docs/#fast-list` for the full lore 📖

---

### Custom upload headers 🌸

You can set custom upload headers with the **`--header-upload`** flag. Google Cloud Storage is down for the headers described in the working with metadata documentation at `https://cloud.google.com/storage/docs/gsutil/addlhelp/WorkingWithObjectMetadata` 🫶

The ones it speaks fluently:

- `Cache-Control`
- `Content-Disposition`
- `Content-Encoding`
- `Content-Language`
- `Content-Type`
- `X-Goog-Storage-Class`
- `X-Goog-Meta-`

Like, for example:

--header-upload "Content-Type text/potato"

And bestie, peep this — that **last one** in the list is specifically for setting **custom metadata**, and it goes like:

--header-upload "x-goog-meta-key: value"

💅

---

### Modification times ⏰

Google Cloud Storage stores `md5sum` **natively** — iconic, no notes. Meanwhile Google's gsutil tool (`https://cloud.google.com/storage/docs/gsutil`) stores modification time with **one-second precision** as `goog-reserved-file-mtime` in the file metadata.

So to keep things compatible 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**

When rclone needs to get the modification time from object metadata, it reads the metadata in this order, no skipping: `mtime`, then `goog-reserved-file-mtime`, then `object updated time` 👑

> ⚠️ Heads up: rclone's **default modify window is `1ns`**. Files uploaded by gsutil only carry timestamps with **one-second precision**. So if you use rclone to sync files that were previously uploaded by gsutil, rclone **will attempt to update modification time for all these files**. If you want to dodge those possibly unnecessary updates, use `--modify-window 1s`. Consider yourself warned, bestie 💖

---

### Restricted filename characters 🚫

Here's the forbidden list, the characters that get swapped out:

- `NUL` — value `0x00` — replaced with `␀`
- `LF` — value `0x0A` — replaced with `␊`
- `CR` — value `0x0D` — replaced with `␍`
- `/` — value `0x2F` — replaced with `／`

And **invalid UTF-8 bytes will also be replaced** (see `https://rclone.org/overview/#invalid-utf8`), because real talk, they can't be used in JSON strings 💀

---

## ✨ Standard options ✨

Okay so here are the **Standard options** specific to google cloud storage (Google Cloud Storage — this is **not** Google Drive, iykyk) 🎀

---

- **`--gcs-client-id`** — OAuth Client Id.
  Leave blank normally.
  - **Config:** `client_id`
  - **Env Var:** `RCLONE_GCS_CLIENT_ID`
  - **Type:** `string`
  - **Required:** `false`

- **`--gcs-client-secret`** — OAuth Client Secret.
  Leave blank normally.
  - **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.
  - **Config:** `project_number`
  - **Env Var:** `RCLONE_GCS_PROJECT_NUMBER`
  - **Type:** `string`
  - **Required:** `false`

- **`--gcs-user-project`** — User project.
  Optional — needed only for requester pays.
  - **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}`.
  - **Config:** `service_account_file`
  - **Env Var:** `RCLONE_GCS_SERVICE_ACCOUNT_FILE`
  - **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.
  - **Config:** `anonymous`
  - **Env Var:** `RCLONE_GCS_ANONYMOUS`
  - **Type:** `bool`
  - **Default:** `false`

- **`--gcs-object-acl`** — Access Control List for new objects.
  - **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.
  - **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`
  - **Config:** `bucket_policy_only`
  - **Env Var:** `RCLONE_GCS_BUCKET_POLICY_ONLY`
  - **Type:** `bool`
  - **Default:** `false`

- **`--gcs-location`** — Location for the newly created buckets.
  - **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-east5"`
      - Ohio
    - `"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.
  - **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.
  - **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 👑

And now the **Advanced options** specific to google cloud storage (Google Cloud Storage — again, **not** Google Drive, bestie) 🦋

---

- **`--gcs-token`** — OAuth Access Token as a JSON blob.
  - **Config:** `token`
  - **Env Var:** `RCLONE_GCS_TOKEN`
  - **Type:** `string`
  - **Required:** `false`

- **`--gcs-auth-url`** — Auth server URL.
  Leave blank to use the provider defaults.
  - **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.
  - **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.
  > ⚠️ Note that this option is **NOT** supported by all backends, so don't come for me if yours ghosts you 💀
  - **Config:** `client_credentials`
  - **Env Var:** `RCLONE_GCS_CLIENT_CREDENTIALS`
  - **Type:** `bool`
  - **Default:** `false`

- **`--gcs-access-token`** — Short-lived access token.

Leave blank normally, bestie. You only need this if you wanna use a short-lived access token instead of doing the whole interactive login dance. 💅

Properties:

- **Config:** `access_token`
- **Env Var:** `RCLONE_GCS_ACCESS_TOKEN`
- **Type:** string
- **Required:** false

---

## --gcs-directory-markers

Uploads a lil empty object with a trailing slash whenever a new directory gets created ✨

Okay so real talk: bucket-based remotes literally do not support empty folders. So this option makes an empty object that ends with `/` to keep that folder existing. Iconic workaround behavior, honestly.

Properties:

- **Config:** `directory_markers`
- **Env Var:** `RCLONE_GCS_DIRECTORY_MARKERS`
- **Type:** bool
- **Default:** false

---

## --gcs-no-check-bucket

If set, rclone won't even attempt to check that the bucket exists or create it. 🫶

This is lowkey useful when you're tryna minimise the number of transactions rclone does and you already know the bucket is there.

Properties:

- **Config:** `no_check_bucket`
- **Env Var:** `RCLONE_GCS_NO_CHECK_BUCKET`
- **Type:** bool
- **Default:** false

---

## --gcs-decompress

If set, this will decompress gzip encoded objects 😭

So here's the thing: you can upload objects to GCS with `Content-Encoding: gzip` set. Normally rclone will download these files as compressed objects.

But if this flag is on, rclone decompresses those `Content-Encoding: gzip` files as they're received. The tradeoff, bestie: rclone can't check the size and hash anymore, but the file contents will be decompressed. Periodt.

Properties:

- **Config:** `decompress`
- **Env Var:** `RCLONE_GCS_DECOMPRESS`
- **Type:** bool
- **Default:** false

---

## --gcs-endpoint

Custom endpoint for the storage API. Leave it blank to use the provider default 🌸

> Heads up: when you use a custom endpoint that includes a subpath (like `example.org/custom/endpoint`), the subpath gets **ignored** during upload operations because of a limitation in the underlying Google API Go client library. Download and listing operations still work correctly with the full endpoint path. So if you need subpath support for uploads, just don't put subpaths in your custom endpoint config. That's the move. 💀

Properties:

- **Config:** `endpoint`
- **Env Var:** `RCLONE_GCS_ENDPOINT`
- **Type:** string
- **Required:** false
- **Examples:**
  - `"storage.example.org"`
    - Specify a custom endpoint
  - `"storage.example.org:4443"`
    - Specifying a custom endpoint with port
  - `"storage.example.org:4443/gcs/api"`
    - Specifying a subpath, see the note, uploads won't use the custom path!

---

## --gcs-encoding

The encoding for the backend 🎀

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_GCS_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,CrLf,InvalidUtf8,Dot`

---

## --gcs-description

Description of the remote. Just a lil label for ur baby 🦋

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 backends without this capability can't determine free space for an rclone mount, and can't be used as a member of an rclone union remote with policy `mfs` (most free space). So yeah, that's a no from GCS.

See List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/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 ur heart desires, bestie 🫶

---

## Configuration

The initial setup for drive involves getting a token from Google drive which you need to do in your browser. `rclone config` walks you through it, hand in hand, like a good friend. ✨

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 to use rclone's shared client_id, or if you are using a service account. The shared client_id is being retired and will stop working during 2026, so creating your own is now strongly recommended. See https://rclone.org/drive/#making-your-own-client-id for how to create your own. client_id> Google Application Client Secret Leave blank to use rclone's shared client_id, or if you are using a service account. If you created your own client_id then enter its client secret here. 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.

\ "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 rclone's shared Google Drive client_id is being retired and will stop working during 2026. Create your own to avoid interruption: https://rclone.org/drive/#making-your-own-client-id

Continue using the shared client_id anyway? y) Yes n) No (default) y/n> n Google Application Client Id client_id> 1234567890-abcdefghijklmnop.apps.googleusercontent.com Google Application Client Secret client_secret> GOCSPX-your-client-secret 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: 1234567890-abcdefghijklmnop.apps.googleusercontent.com
• client_secret: GOCSPX-your-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 (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available. Bestie we got u even offline 💖

Note that rclone runs a webserver on your local machine to collect the token as returned from Google if using web browser to automatically authenticate. 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, or use manual mode.

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 (https://developers.google.com/drive/v3/web/about-auth).

A comma-separated list is allowed e.g. `drive.readonly,drive.file`.

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. When in doubt, vibe check says: pick this one. 💅

---

### drive.readonly

This allows read only access to all files. Files may be listed and downloaded but not uploaded, renamed or deleted. Look, don't touch energy. 👀

---

### 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.

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.

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 secret garden 🌸

---

### 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, no chaos. 🦋

---

## 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. Let rclone cook 🧚

<purple>However</purple> — and this is the fun part — you *can* set this to lock rclone down to one specific folder hierarchy, or to reach into the data hanging out in the <cyan>"Computers"</cyan> tab on the drive web interface (that's where stuff from Google's Backup and Sync desktop program lives).

But ngl? That's not the easiest method. The cute way is: make a shortcut to a folder over in <cyan>"Computers"</cyan> and drop it into <cyan>"My Drive."</cyan> Like, right-click the folder, hit <cyan>"Organize"</cyan>, then pick <cyan>"Add shortcut"</cyan> in the Google Drive web interface. Once that shortcut is chillin' in <cyan>"My Drive,"</cyan> rclone will show you the folder and you can play with it. See also <cyan>Shortcuts</cyan> 💫

If you *do* decide to switch up your root folder though, you're gonna have to hunt down the <purple>Folder ID</purple> of the directory you want rclone to display. It's the last segment of the URL when you open that folder in the drive web interface.

So if the folder you want rclone to use has a URL that looks like

https://drive.google.com/drive/folders/1XyfxxxxxxxxxxxxxxxxxxxxxxxxxKHCh

in the browser, then you use `1XyfxxxxxxxxxxxxxxxxxxxxxxxxxKHCh` as the `root_folder_id` in the config ✨

> NB folders under the <cyan>"Computers"</cyan> tab seem to be read only (drive gives a `500` error) when using rclone — but bestie, they're also read-only in the Google Drive web interface, probably because this folder is managed by the Google Drive Desktop tool. Top-level folders in <cyan>"Computers"</cyan> are read-only, BUT you can still interact with folders inside them using rclone 🫶 Those are also the folders you can make a shortcut for, exactly like I described above.

There doesn't appear to be an API to discover the folder IDs of the <cyan>"Computers"</cyan> tab — please contact us if you know otherwise! 🙈

Also note bestie: rclone can't access any data under the <cyan>"Backups"</cyan> tab on the google drive web interface yet 💀

---

## 🧑💼 Service Account support

Okay so you can set up rclone with Google Drive in an *unattended* mode — aka not tied to any specific end-user Google account. This is the moment when you wanna sync files onto machines that don't have actively logged-in users, like build machines 👑

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 during `rclone config` and rclone won't use the browser based authentication flow at all. And if you'd rather just stuff the contents of the credentials file straight 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 you're the administrator of a Google Workspace. The goal: 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`*.

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 (`https://console.developers.google.com`).

- You must have a project — create one if you don't, and make sure you are on the selected project.

- Then go to <cyan>"IAM & admin"</cyan> -> <cyan>"Service Accounts"</cyan>.

- Use the <cyan>"Create Service Account"</cyan> button. Fill in <cyan>"Service account name"</cyan> and <cyan>"Service account ID"</cyan> with something that identifies your client.

- Select <cyan>"Create And Continue"</cyan>. Step 2 and 3 are optional.

- Click on the newly created service account

- Click <cyan>"Keys"</cyan> and then <cyan>"Add Key"</cyan> and then <cyan>"Create new key"</cyan>

- Choose type <cyan>"JSON"</cyan> 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 <cyan>"Delete service account key"</cyan> button 🔑

---

### 2. Allowing API access to example.com Google Drive

- Go to *`example.com`*'s Workspace Admin Console (`https://admin.google.com`)

- Go into <cyan>"Security"</cyan> (or use the search bar)

- Select <cyan>"Access and data control"</cyan> and then <cyan>"API controls"</cyan>

- Click <cyan>"Manage domain-wide delegation"</cyan>

- Click <cyan>"Add new"</cyan>

- In the <cyan>"Client ID"</cyan> field enter the service account's <cyan>"Client ID"</cyan> — this can be found in the Developer Console under <cyan>"IAM & Admin"</cyan> -> <cyan>"Service Accounts"</cyan>, then <cyan>"View Client ID"</cyan> for the newly created service account. It is a ~21 character numerical string.

- In the next field, <cyan>"OAuth Scopes"</cyan>, enter `https://www.googleapis.com/auth/drive` to grant read/write access to Google Drive specifically. You can also use `https://www.googleapis.com/auth/drive.readonly` for read only access with `--drive-scope=drive.readonly`.

- Click <cyan>"Authorise"</cyan>

---

### 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`.

> Note: 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 😌

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 lets you use fewer transactions in exchange for more memory. Check the rclone docs (`https://rclone.org/docs/#fast-list`) for more details 👀

It does this by combining multiple list calls into a single API request.

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`.

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 (`https://rclone.org/overview/#invalid-utf8`), 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 💅

---

## 🔁 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 (`https://support.google.com/drive/answer/9700156`) (API (`https://developers.google.com/drive/api/v3/shortcuts`)). These will (by September `2020`) replace the ability for files or folders to be in multiple folders at once (`https://cloud.google.com/blog/products/g-suite/simplifying-google-drives-folder-structure-and-sharing-models`) ✨

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.

- Bestie, when you update a shortcut file with a **non-shortcut** file? The shortcut gets yeeted and a fresh new file is uploaded right where the shortcut was. ✨

- When you **server-side move** (rename) it, it's the <pink>shortcut</pink> that gets renamed — NOT the destination file. 🙅‍♀️

- When you **server-side copy** it, the shortcut itself is copied, not the contents of the shortcut. (Unless `--drive-copy-shortcut-content` is in play, in which case the contents of the shortcut DO get copied. iykyk.)

- When you **delete** it, the shortcut gets deleted — not the linked file. 💅

- When you **set the modification time**, the modification time of the **linked file** is what gets set.

For shortcuts pointing to **folders**:

- When **listing**, the shortcut shows up as a folder, and that folder will contain the contents of the linked folder (including any sub folders). 🦋

- When **downloading**, the contents of the linked folder and its sub contents are downloaded.

- When **uploading** to a shortcut folder, the file lands 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 get copied, not the shortcut.

- When **deleting** with `rclone rmdir` or `rclone purge`, the shortcut is deleted — not the linked folder.

> 🚨 <red>NB</red> — When deleting with `rclone remove` or `rclone mount`, the **contents of the linked folder will be deleted**. Not the shortcut. The actual stuff. Be so careful bestie. 😭

The `rclone backend` command (https://rclone.org/commands/rclone_backend/) can be used to create shortcuts. 🎀

Shortcuts can be completely ignored with the `--drive-skip-shortcuts` flag or the corresponding `skip_shortcuts` configuration setting.

When `rclone lsf --format i` lists a file shortcut, the ID field contains the **target file ID** followed by the **shortcut ID**, separated by a tab. This internal tab is not changed by `--separator`. 👑

If you have a folder shortcut that points at one of its own parent folders, that's an infinite recursion situation, and it's giving cursed. 💀 Rclone detects this, leaves the offending shortcut out of the listing, and logs an **ERROR**, so the rest of the drive can still be copied. Slay.

---

### 🌸 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`. 🙈

---

### 💖 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. Bestie it's a whole thing.

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 a **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. 👇

- export-formats: *(none)*, import-formats: `odt`, Upload Ext: `odt`, Document Ext: `odt` → **Allowed: Yes**
- export-formats: *(none)*, import-formats: `docx,odt`, Upload Ext: `odt`, Document Ext: `odt` → **Allowed: Yes**
- export-formats: *(none)*, import-formats: `docx`, Upload Ext: `docx`, Document Ext: `docx` → **Allowed: Yes**
- export-formats: *(none)*, 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**

This limitation can be disabled by specifying `--drive-allow-import-name-change`. When using this flag, 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 extensions 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. <red>Heads up fr.</red>

Here are the possible export extensions with their corresponding mime types. Most of these can also be used for importing, but there are 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. 🧚

This list can be changed by Google Drive at any time and might not represent the currently available conversions. (So don't come for me if it's different, it's Google's list not mine. 💀)

- `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

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). 👑

---

### 💜 `--drive-client-id`

Google Application Client Id

Leave blank to use rclone's shared `client_id`, or if you are using a service account. The shared `client_id` is being retired and will stop working during **2026**, so creating your own is now strongly recommended. See https://rclone.org/drive/#making-your-own-client-id for how to create your own. 🫶

Properties:

- Config: `client_id`
- Env Var: `RCLONE_DRIVE_CLIENT_ID`
- Type: `string`
- Required: false

---

### 💜 `--drive-client-secret`

Google Application Client Secret

Leave blank to use rclone's shared `client_id`, or if you are using a service account. If you created your own `client_id` then enter its client secret here.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_DRIVE_CLIENT_SECRET`
- Type: `string`
- Required: false

- **`--drive-scope`** — <pink>okay bestie</pink>, this is a 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`** — path to a Service Account Credentials JSON file. 🎀 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`

## <rainbow>Advanced options</rainbow> ✨

Here are the Advanced options specific to `drive` (Google Drive). 👑

- **`--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. Note that this option is **NOT** supported by all backends.

  - **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`** — Only consider files owned by the authenticated user. 💜

  - **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 permanently. ♻️ Defaults to `true`, namely sending files to the trash. Use `--drive-use-trash=false` to delete files permanently instead.

  - **Properties:**
    - **Config:** `use_trash`
    - **Env Var:** `RCLONE_DRIVE_USE_TRASH`
    - **Type:** `bool`
    - **Default:** `true`

- **`--drive-copy-shortcut-content`** — Server side copy contents of shortcuts instead of the shortcut. 🔥 When doing server side copies, normally rclone will copy shortcuts as shortcuts. If this flag is used then rclone will copy the contents of shortcuts rather than shortcuts themselves when doing 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 given, gdocs practically become invisible to rclone.

  - **Properties:**
    - **Config:** `skip_gdocs`
    - **Env Var:** `RCLONE_DRIVE_SKIP_GDOCS`
    - **Type:** `bool`
    - **Default:** `false`

- **`--drive-show-all-gdocs`** — Show all Google Docs including non-exportable ones in listings. 🌟 If you try a server side copy on a Google Form without this flag, you will get this error:

No export formats found for "application/vnd.google-apps.form"

However adding this flag will allow the form to be server side copied. Note that rclone doesn't add extensions to the Google Docs file names in this mode.

> Do **not** use this flag when trying to download Google Docs - rclone will fail to download them. 💀

- **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 get checksum errors when transferring Google photos or videos. Setting this flag will cause Google photos and videos to return a blank checksums. Google photos are identified by being in the `"photos"` space. Corrupted checksums are caused by Google modifying the image/video but not updating 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. 🫂 Instructs rclone to operate on your `"Shared with me"` folder (where Google Drive lets you access the files and folders others have shared with you). This works both with the `"list"` (`lsd`, `lsl`, etc.) and the `"copy"` commands (`copy`, `sync`, etc.), and with all 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 will show trashed files in their original directory structure.

- **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: See `export_formats`. 🚫

- **Properties:**
  - **Config:** `formats`
  - **Env Var:** `RCLONE_DRIVE_FORMATS`
  - **Type:** `string`
  - **Required:** `false`

- **`--drive-export-formats`** — Comma separated list of 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`** — Comma separated list of 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 uploading Google docs. 🔄 E.g. `file.doc` to `file.docx`. This will confuse sync and reupload 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 file created date instead of modified date. 📅 Useful when 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. This side effect can be avoided by using the `--checksum` flag.

This feature was implemented to retain photos capture date as recorded by google photos. You will first need to check the `"Create a Google Photos folder"` option in your google drive settings. You can then 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 date file was shared instead of modified date. 🤝 Note that, as with `--drive-use-created-date`, this flag may have unexpected consequences when uploading/downloading files. If both this flag and `--drive-use-created-date` are set, the created date is used.

- **Properties:**
  - **Config:** `use_shared_date`
  - **Env Var:** `RCLONE_DRIVE_USE_SHARED_DATE`
  - **Type:** `bool`
  - **Default:** `false`

- **`--drive-list-chunk`** — Size of listing chunk `100-1000`, `0` to disable. 🧩

- **Properties:**
  - **Config:** `list_chunk`
  - **Env Var:** `RCLONE_DRIVE_LIST_CHUNK`
  - **Type:** `int`
  - **Default:** `1000`

- **`--drive-impersonate`** — Impersonate this user when using a service account. 🎭

- **Properties:**
  - **Config:** `impersonate`
  - **Env Var:** `RCLONE_DRIVE_IMPERSONATE`
  - **Type:** `string`
  - **Required:** `false`

- **`--drive-upload-cutoff`** — Cutoff for switching to chunked upload. ✂️

- **Properties:**
  - **Config:** `upload_cutoff`
  - **Env Var:** `RCLONE_DRIVE_UPLOAD_CUTOFF`
  - **Type:** `SizeSuffix`
  - **Default:** `8Mi`

- **`--drive-chunk-size`** — Upload chunk size. 📦 Must be 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_DRIVE_CHUNK_SIZE`
  - **Type:** `SizeSuffix`
  - **Default:** `8Mi`

- **`--drive-acknowledge-abuse`** — Set to allow files which 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 supply this flag to rclone to indicate you acknowledge the risks of downloading the file and rclone will download it anyway.

Note that if you are using service account it will need Manager permission (not Content Manager) to for this flag to work. If the SA does not have the right permission, Google will just ignore the flag.

- **Properties:**
  - **Config:** `acknowledge_abuse`
  - **Env Var:** `RCLONE_DRIVE_ACKNOWLEDGE_ABUSE`

- **Type:** bool
- **Default:** false

---

## `--drive-keep-revision-forever`

Keep new head revision of each file forever. 🔒✨ forever-forever, no take-backs.

**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 instead of telling you how big the file *is*, it tells you how much of your storage quota it's eating. And bestie, that's the current version **plus** any older versions that have been set to keep forever. The way that stacks up… 💀

> **WARNING:** This flag may have some unexpected consequences. 👀

It is **not** recommended to set this flag in your config. The recommended usage is using the flag form `--drive-size-as-quota` when doing `rclone ls/lsl/lsf/lsjson/etc` only.

If you do use this flag for syncing (**not** recommended) then you will need to use `--ignore size` also. Periodt.

**Properties:**

- **Config:** `size_as_quota`
- **Env Var:** `RCLONE_DRIVE_SIZE_AS_QUOTA`
- **Type:** bool
- **Default:** false

---

## `--drive-v2-download-min-size`

If Object's are greater, use 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`

Minimum time to sleep between API calls. 😴 girl needs her beauty rest between requests.

**Properties:**

- **Config:** `pacer_min_sleep`
- **Env Var:** `RCLONE_DRIVE_PACER_MIN_SLEEP`
- **Type:** Duration
- **Default:** `100ms`

---

## `--drive-pacer-burst`

Number of API calls to allow without sleeping. no naps, just go go go 🔥

**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. 🫠

Allow server-side operations (e.g. copy) to work across different drive configs.

This can be useful if you wish to do a server-side copy between two different Google drives. Note that this isn't enabled by default because it isn't easy to tell if it will work between any two configurations. like. it *might* slay, it might not, nobody knows 💅

**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 can be re-enabled here. When the issue is solved this flag will be removed.

**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 be fatal. 💀 like, end-the-sync fatal.

At the time of writing it is only possible to upload `750 GiB` of data to Google Drive a day (this is an undocumented limit). 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 don't document so it may break in the future. 🙈 (iykyk — undocumented strings are the messiest exes)

**See:** `https://github.com/rclone/rclone/issues/3857`

**Properties:**

- **Config:** `stop_on_upload_limit`
- **Env Var:** `RCLONE_DRIVE_STOP_ON_UPLOAD_LIMIT`
- **Type:** bool
- **Default:** false

---

## `--drive-stop-on-download-limit`

Make download limit errors be fatal. 💀

At the time of writing it is only possible to download `10 TiB` of data from Google Drive a day (this is an undocumented limit). 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 don't document so it may break in the future. 🙈

**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. 👋 not today, shortcuts.

Normally rclone dereferences shortcut files making them appear as if they are the original file (see the shortcuts section). If this flag is set then rclone will ignore shortcut files completely.

**Properties:**

- **Config:** `skip_shortcuts`
- **Env Var:** `RCLONE_DRIVE_SKIP_SHORTCUTS`
- **Type:** bool
- **Default:** false

---

## `--drive-skip-dangling-shortcuts`

If set skip dangling shortcut files. 🍂 gone but not forgotten, actually just not shown.

If this is set then rclone will not show any dangling shortcuts in listings.

**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. 🔑

If you need to access files shared with a link like this

https://drive.google.com/drive/folders/XXX?resourcekey=YYY&usp=sharing

Then you will need to use the first part `"XXX"` as the `"root_folder_id"` and the second part `"YYY"` as the `"resource_key"` otherwise you will get `404` not found errors when trying to access the directory. 😭 the 404 jumpscare is real

**See:** `https://developers.google.com/drive/api/guides/resource-keys`

This resource key requirement only applies to a subset of old files. 👵

<rainbow>Note also that opening the folder once in the web interface (with the user you've authenticated rclone with) seems to be enough so that the resource key is not needed.</rainbow> ✨ little hack, iconic 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. 🐛

Normally rclone will work around a bug in Google Drive when using `--fast-list` (`ListR`) where the search `"(A in parents) or (B in parents)"` returns nothing sometimes.

**See:** `#3114`, `#4289` and `https://issuetracker.google.com/issues/149522397`

Rclone detects this by finding no items in more than one directory when listing and retries them as lists of individual directories.

This means that if you have a lot of empty directories rclone will end up listing them all individually and this can take many more API calls. 📞📞📞 it's giving call center energy

This flag allows the work-around to be disabled. This is not recommended in normal use - only if you have a particular case you are 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. 👑

Owner is a standard part of the file metadata so is easy to read. But it isn't always desirable to set the owner from the metadata.

Note that you can't set the owner on Shared Drives, and that setting ownership will generate an email to the new owner (this can't be disabled), and you can't transfer ownership to someone outside your organization. 📧 the email is automatic and it is *not* optional bestie

**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.

Reading permissions metadata from files can be done quickly, but it isn't always desirable to set the permissions from the metadata.

Note that rclone drops any inherited permissions on Shared Drives and any owner permission on My Drives as these are duplicated in the owner metadata. 🗑️ dropped, delicious, we love a clean duplicate

**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. 🏷️

Reading labels metadata from files takes an extra API transaction and will slow down listings. It isn't always desirable to set the labels from the metadata. 🐌 the slowdown is real, notice her

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 JSON dump of this format.

When setting labels, the label and fields must already exist - rclone will not create them. This means that if you are transferring labels from two different accounts you will have to create the labels in advance and use the metadata mapper to translate the IDs between the two accounts. 😮‍💨 you have to build it yourself first, no hand-holding

**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-metadata-enforce-expansive-access`

Whether the request should enforce expansive access rules.

From Feb 2026 this flag will be set by default so this flag can be used for testing before then. ⏰ mark your calendars bestie, future-you says hi

**See:** `https://developers.google.com/workspace/drive/api/guides/limited-expansive-access`

**Properties:**

- **Config:** `metadata_enforce_expansive_access`
- **Env Var:** `RCLONE_DRIVE_METADATA_ENFORCE_EXPANSIVE_ACCESS`
- **Type:** bool
- **Default:** false

---

## `--drive-encoding`

The encoding for the backend.

See the encoding section in the overview (`https://rclone.org/overview/#encoding`) for more info. 🔤

**Properties:**

- **Config:** `encoding`
- **Env Var:** `RCLONE_DRIVE_ENCODING`
- **Type:** Encoding
- **Default:** `InvalidUtf8`

---

## `--drive-env-auth`

Get 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. 🤫 only then, don't be messy about it

**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 name tag for your remote, cute

**Properties:**

- **Config:** description
- **Env Var:** `RCLONE_DRIVE_DESCRIPTION`
- **Type:** string
- **Required:** false

### ✨ Metadata ✨

Okay bestie, so user metadata lives in the `properties` field of the drive object — that's just where Google keeps it, no biggie 💅

Metadata is supported on **files and directories**. Yes, both. Slay.

Here are the possible system metadata items for the drive backend. Every single one, no skips 🫶

- **`btime`** — Time of file birth (creation) with mS accuracy. *Type:* `RFC 3339`. *Example:* `2006-01-02T15:04:05.999Z07:00`. *Read Only:* `N`. ⚠️ Note that this is only writable on fresh uploads — it can't be written for updates. (So if you're trying to set birth time on an existing file… nope, sorry bestie 😭)
- **`content-type`** — The MIME type of the file. *Type:* `string`. *Example:* `text/plain`. *Read Only:* `N`
- **`copy-requires-writer-permission`** — Whether the options to copy, print, or download this file, should be disabled for readers and commenters. *Type:* `boolean`. *Example:* `true`. *Read Only:* `N`
- **`description`** — A short description of the file. *Type:* `string`. *Example:* `Contract for signing`. *Read Only:* `N`
- **`folder-color-rgb`** — The color for a folder or a shortcut to a folder as an RGB hex string. *Type:* `string`. *Example:* `881133`. *Read Only:* `N`
- **`labels`** — Labels attached to this file in a JSON dump of Googled drive format. Enable with `--drive-metadata-labels`. *Type:* `JSON`. *Example:* `[]`. *Read Only:* `N`
- **`mtime`** — Time of last modification with mS accuracy. *Type:* `RFC 3339`. *Example:* `2006-01-02T15:04:05.999Z07:00`. *Read Only:* `N`
- **`owner`** — The owner of the file. Usually an email address. Enable with `--drive-metadata-owner`. *Type:* `string`. *Example:* `user@example.com`. *Read Only:* `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`. *Type:* `JSON`. *Example:* `{}`. *Read Only:* `N`
- **`starred`** — Whether the user has starred the file. *Type:* `boolean`. *Example:* `false`. *Read Only:* `N`
- **`viewed-by-me`** — Whether the file has been viewed by this user. *Type:* `boolean`. *Example:* `true`. *Read Only:* `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. *Type:* `boolean`. *Example:* `false`. *Read Only:* `N`

See the metadata docs for more info (https://rclone.org/docs/#metadata) 💖

---

### 🎀 Backend commands 🎀

Here are the commands specific to the drive backend. Like, the lil extra ones that are just for Drive, iykyk.

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend command docs for more info on how to pass options and arguments (https://rclone.org/commands/rclone_backend/).

These can be run on a running backend using the rc command `backend/command` (https://rclone.org/rc/#backend-command). So you can poke at a live one, no restart needed 👑

---

### get

Get command for fetching the drive config parameters. It's giving "peek behind the curtain" energy 🔍

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. The glow-up command fr ✨

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. It's giving "shortcut era" 💅

rclone backend shortcut remote: [options] [<arguments>+]

This command creates shortcuts from files or directories.

Usage examples:

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:"`. 😭 (permission drama, classic)

Options:

- **`"target"`** — Optional target remote for the shortcut destination.

---

### drives

List the Shared Drives available to this account. Main character inventory moment 👑

rclone backend drives remote: [options] [<arguments>+]

This command lists the Shared Drives (Team Drives) available to this account.

Usage example:

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. Obsessed with this, honestly 🌈

---

### untrash

Untrash files and directories. The "oops bring it back" command 🙈

rclone backend untrash remote: [options] [<arguments>+]

This command untrashes all the files and directories in the directory passed in recursively.

Usage example:

rclone backend untrash drive:directory rclone backend --interactive untrash drive:directory subdir

This takes an optional directory to trash which make this easier to use via the API.

Use the `--interactive`/`-i` or `--dry-run` flag to see what would be restored before restoring it. (Please do this, bestie — always vibe check before you commit 💖)

Result:

{ "Untrashed": 17, "Errors": 0 }

---

### copyid

Copy files by ID. Because sometimes you've got the ID and not the path, and that's valid ✨

rclone backend copyid remote: [options] [<arguments>+]

This command copies files by ID.

Usage examples:

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. (iykyk — that trailing slash MATTERS 💅)

If the destination is a drive backend then server-side copying will be attempted if possible. Zero data transfer, so fast, slay 🔥

Use the `--interactive`/`-i` or `--dry-run` flag to see what would be copied before copying.

---

### moveid

Move files by ID. Same energy as copyid but it *moves* 🦋

rclone backend moveid remote: [options] [<arguments>+]

This command moves files by ID.

Usage examples:

rclone backend moveid drive: ID path rclone backend moveid drive: ID1 path1 ID2 path2

It moves the drive file with ID given to the path (an rclone path which will be passed internally to `rclone moveto`).

The path should end with a `/` to indicate move 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 moving will be attempted if possible.

Use the `--interactive`/`-i` or `--dry-run` flag to see what would be moved beforehand.

---

### exportformats

Dump the export formats for debug purposes. Lowkey a nerd moment and I respect it 🧚

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. The big-brain one, fr fr 👑

- **`rclone backend query remote: [options] [<arguments>+]`** — lists files based on a query, bestie 💅

This command lists files based on a query.

Usage example:

rclone backend query drive: query

The query syntax is documented at Google Drive Search query terms and operators (`https://developers.google.com/drive/api/guides/ref-search-terms`).

For example:

rclone backend query drive: "'0ABc9DEFGHIJKLMNop0QRatUVW3X' in parents and name contains 'foo'"

If the query contains literal `'` or `\` characters, these need to be escaped with `\` characters. `'` becomes `\'` and `\` becomes `\\`, for example to match a file named "foo ' \.txt":

rclone backend query drive: "name = 'foo ' \.txt'"

The result is a JSON array of matches, for example:

[ { "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 🛟

Rescue or delete any orphaned files. iykyk, this one is a whole rescue mission 🦋

rclone backend rescue remote: [options] [<arguments>+]

This command rescues or deletes any orphaned files or directories.

Sometimes files can get orphaned in Google Drive. This means that they are no longer in any folder in Google Drive. 😭 Literally floating in the void with no parent folder, no cap.

This command finds those files and either rescues them to a directory you specify or deletes them.

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 <hotpink>quite a lot</hotpink> of rate limiting. This causes rclone to be limited to transferring about 2 files per second only. Individual files may be transferred much faster at 100s of MiB/s but lots of small files can take a long time. 😮‍💨 The small-files girlies really do suffer out here.

Server side copies are also subject to a separate rate limit. If you see <red>User rate limit exceeded</red> 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.

---

## 📄 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. It's giving "we literally don't know her size bestie" 🙈

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 — experiment to find out if it does work for you! 🧚

---

## 👯 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.

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates. 💀

Use `rclone dedupe` to fix duplicated files.

Note that this isn't just a problem with rclone, even Google Photos on Android duplicates files on drive sometimes.

---

## 😭 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 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. ⏳

---

## 🔐 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.

---

## 👑 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.

This shared client_id is being retired and will stop working during 2026. To avoid interruption you **must** create and use your own client_id, so creating one is now **required** rather than merely recommended. New remotes created with `rclone config` will warn you if you leave the client_id blank. ⚠️ Like, this is not a drill bestie.

Using your own client_id has other benefits too. There is a global rate limit on the number of queries per second that each client_id can do set by Google. 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.

Here is how to create your own Google Drive client ID for rclone:

1. Log into the Google API Console (`https://console.developers.google.com/`) 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 click "Get started". On the next screen, enter an "Application name" ("rclone" is OK); enter "User Support Email" (your own email is OK); Next, under Audience select "External". Next enter your own contact information, agree to terms and click "Create". You should now see `rclone` (or your project name) in a box in the top left of the 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).

   You will also have to add some scopes (`https://developers.google.com/drive/api/guides/api-specific-auth`), 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.

   To do this, click Data Access on the left side panel, click "add or remove scopes" and select the three above and press update or go to the "Manually add scopes" text box (scroll down) and enter `https://www.googleapis.com/auth/docs,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.metadata.readonly`, press add to table then update.

   You should now see the three scopes on your Data access page. Now press save at the bottom! 💾

6. After adding scopes, click Audience. Scroll down and click "+ Add users". Add yourself as a test user and press save.

7. Go to Overview on the left panel, click "Create OAuth client". Choose an application type of "Desktop app" and click "Create". (the default name is fine)

8. It will show you a client ID and client secret. Make a note of these. (If you selected "External" at Step 5 continue to Step 9. If you chose "Internal" you don't need to publish and can skip straight to Step 10 but your destination drive must be part of the same Google Workspace.)

9. Go to "Audience" and then click "PUBLISH APP" button and confirm. Add yourself as a test user if you haven't already.

   (If the "PUBLISH APP" button is greyed out, Google now requires a homepage URL and a privacy policy URL before publishing, even for a personal single-user app. Go to "Branding" in the left panel, fill in "Application home page" and "Application privacy policy link" — a free GitHub Pages site is fine for these if you don't have a domain of your own — then "Authorized domains" with the domain you used, and click Save. Return to "Audience" and the "PUBLISH APP" button should now be available.)

10. Provide the noted client ID and client secret to rclone.

11. Run the web-based authorization flow from within `rclone config`, by answering "Y" when it asks "Token already configured - replace it?".

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. ✨

<purple>In most cases verification is not actually required.</purple> Google exempts a number of app categories (https://support.google.com/cloud/answer/13464323) from mandatory verification, including:

- <mint>**Personal Use apps**</mint>: if the app is for your personal use (fewer than 100 users), you and your limited number of users can keep using it without verification — you will just need to click through the "unverified app" warning screen during sign-in. Verification is only required if you want to grow your user base beyond 100 users.
- <mint>**Development/Testing/Staging apps**</mint>: apps in development, testing or staging mode are not subject to verification (but are limited to the 100-user cap and the unverified-app warning until verified).

So for typical personal rclone use you can leave the app unverified, accept the warning screen, and publish it (rather than leaving it in "Testing") to avoid the weekly grant expiry described above. lowkey the move 💅

(Thanks to @balazer on github for these instructions.) 🫶

Sometimes, creation of an OAuth consent in Google API Console fails due to an error message <red>"The request failed because changes to one of the field of the resource is not supported"</red>. As a convenient workaround, the necessary Google Drive API key can be created on the Python Quickstart (https://developers.google.com/drive/api/v3/quickstart/python) page. Just push the <yellow>Enable the Drive API</yellow> button to receive the Client ID and Secret. Note that it will automatically create a new project in the API Console. (sneaky of it, but okay 🎀)

---

# 🦋 Google Photos 🦋

The rclone backend for Google Photos (https://www.google.com/photos/about/) is a specialized backend for transferring photos and videos to and from Google Photos. it's giving camera roll energy 📸✨

> <hotpink>**NB**</hotpink> 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.

> <hotpink>**NB**</hotpink> From March 31, 2025 rclone can only download photos it uploaded. This limitation is due to policy changes at Google. You may need to run `rclone config reconnect remote:` to make rclone work again after upgrading to rclone v1.70. 😭

## 🌸 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. fr fr it holds your hand the whole way 🫶

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

OAuth Client Id. Creating your own is now strongly recommended. If you leave this blank rclone uses a shared client_id which is being retired and will stop working during 2026. See https://rclone.org/googlephotos/#making-your-own-client-id for how to create your own. Enter a string value. Press Enter for the default (""). client_id> OAuth Client Secret. Leave blank to use rclone's shared client_id. If you created your own client_id then enter its client secret here. 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 rclone's shared Google Photos client_id is being retired and will stop working during 2026. Create your own to avoid interruption: https://rclone.org/googlephotos/#making-your-own-client-id

Continue using the shared client_id anyway? y) Yes n) No (default) y/n> n OAuth Client Id. client_id> 1234567890-abcdefghijklmnop.apps.googleusercontent.com OAuth Client Secret. client_secret> GOCSPX-your-client-secret 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

See the remote setup docs (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available. 🧚

Note that rclone runs a webserver on your local machine to collect the token as returned from Google if using web browser to automatically authenticate. 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, or use manual mode. ikyk the firewall always wants to start something 🙈

This remote is called `remote` and can now be used like this

See all the albums in your photos

rclone lsd remote:album

Make a new album

rclone mkdir remote:album/newAlbum

List the contents of an album

rclone ls remote:album/newAlbum

Sync `/home/local/images` to the Google Photos, removing any excess files in the album.

rclone sync --interactive /home/local/image remote:album/newAlbum

## 🌸 Layout 🌸

As Google Photos is not a general purpose cloud storage system, the backend is laid out to help you navigate it. 🗺️✨

The directories under `media` show different ways of categorizing the media. Each file will appear multiple times. So if you want to make a backup of your google photos you might choose to backup `remote:media/by-month`. (NB `remote:media/by-day` is rather slow at the moment so avoid for syncing.) 💀

Note that all your photos and videos will appear somewhere under `media`, but they may not appear under `album` unless you've 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 two writable parts of the tree, the `upload` directory and sub directories of the `album` directory. 👑

The `upload` directory is for uploading files you don't want to put into albums. This will be empty to start with and will contain the files you've uploaded for one rclone session only, becoming empty again when you restart rclone. The use case for this would be if you have a load of files you just want to once off dump into Google Photos. For repeated syncing, uploading to `album` will work better. 🎀

Directories within the `album` directory are also writeable and you may create new directories (albums) under `album`. If you copy files with a directory hierarchy in there then rclone will create albums with the `/` character in them. For example 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`

This means that you can use the `album` path pretty much like a normal filesystem and it is a good target for repeated syncing. slay 🫶

The `shared-album` directory shows albums shared with you or by you. This is similar to 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.

Creating your own is now strongly recommended. If you leave this blank rclone uses a shared client_id which is being retired and will stop working during 2026. See https://rclone.org/googlephotos/#making-your-own-client-id for how to create your own.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_GPHOTOS_CLIENT_ID`
- Type: string
- Required: false

### 🌸 --gphotos-client-secret 🌸

OAuth Client Secret.

Leave blank to use rclone's shared client_id. If you created your own client_id then enter its client secret here.

Properties:

- Config: `client_secret`

- **`Env Var`**: `RCLONE_GPHOTOS_CLIENT_SECRET`
  - **`Type`**: string
  - **`Required`**: false

- **`--gphotos-read-only`** — flips the whole Google Photos backend into read-only mode, bestie 💅

  If you go read-only, rclone asks for <mint>read-only access</mint> to your photos and that's it. Otherwise? rclone wants <hotpink>full access</hotpink>. That's the whole vibe check.

  Properties:

  - **`Config`**: read_only
  - **`Env Var`**: `RCLONE_GPHOTOS_READ_ONLY`
  - **`Type`**: bool
  - **`Default`**: false

---

## ✨ Advanced options ✨

okay so these are the <purple>Advanced options</purple> that are specifically for google photos (Google Photos). extremely specific, no notes 🫶

- **`--gphotos-token`** — the OAuth Access Token, delivered to you as a JSON blob 🫠

  Properties:

  - **`Config`**: token
  - **`Env Var`**: `RCLONE_GPHOTOS_TOKEN`
  - **`Type`**: string
  - **`Required`**: false

- **`--gphotos-auth-url`** — the Auth server URL.

  Leave it blank and you get the provider defaults. blank = default, always 💖

  Properties:

  - **`Config`**: auth_url
  - **`Env Var`**: `RCLONE_GPHOTOS_AUTH_URL`
  - **`Type`**: string
  - **`Required`**: false

- **`--gphotos-token-url`** — the Token server url.

  Leave blank → provider defaults. same deal, iconic 💅

  Properties:

  - **`Config`**: token_url
  - **`Env Var`**: `RCLONE_GPHOTOS_TOKEN_URL`
  - **`Type`**: string
  - **`Required`**: false

- **`--gphotos-client-credentials`** — use the client credentials OAuth flow.

  This one uses the <cyan>OAUTH2 client Credentials Flow</cyan> exactly as described in RFC 6749. very official.

  Heads up though: this option is <red>NOT</red> supported by all backends. not every backend wants that energy 🙈

  Properties:

  - **`Config`**: client_credentials
  - **`Env Var`**: `RCLONE_GPHOTOS_CLIENT_CREDENTIALS`
  - **`Type`**: bool
  - **`Default`**: false

- **`--gphotos-read-size`** — set this to actually read the size of media items.

  Normally rclone does <italic>not</italic> read the size of media items, because that costs another transaction. For syncing it's literally unnecessary. <mint>However</mint> — rclone mount needs to know file sizes <italic>before</italic> it reads them, so if you're using rclone mount and you want to read the media, turning this flag on is recommended. do it for the mount bestie 🎀

  Properties:

  - **`Config`**: read_size
  - **`Env Var`**: `RCLONE_GPHOTOS_READ_SIZE`
  - **`Type`**: bool
  - **`Default`**: false

- **`--gphotos-start-year`** — a year. it limits which photos get downloaded to only the ones uploaded <italic>after</italic> that year. time gate ✨

  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. So when syncing, archived media is <italic>not visible</italic> in directory listings and it does not get transferred. periodt.

  Lowkey important: media in albums is always visible and synced, no matter its archive status. albums don't play by the archive rules 👑

  With this flag, archived media is always visible in directory listings and gets 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 🔥

  Here's the tea: the Google API will hand you images and video which aren't full resolution, and/or are missing EXIF data. which is giving "why is it like this".

  But if you use the <cyan>gphotosdl</cyan> proxy then you can download original, unchanged images. slay.

  This runs a headless browser in the background. very main character.

  Download the software from gphotosdl (https://github.com/rclone/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

- **`--gphotos-encoding`** — the encoding for the backend.

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info. iykyk.

Properties:

- **`Config`**: encoding
- **`Env Var`**: `RCLONE_GPHOTOS_ENCODING`
- **`Type`**: Encoding
- **`Default`**: Slash,CrLf,InvalidUtf8,Dot

- **`--gphotos-batch-mode`** — upload file batching sync|async|off.

This sets the batch mode used by rclone.

This has 3 possible values

- `off` — no batching
- `sync` — batch uploads and check completion (default)
- `async` — batch upload and don't check completion

Rclone will close any outstanding batches when it exits, which may make a delay on quit. just a lil heads up 🫶

Properties:

- **`Config`**: batch_mode
- **`Env Var`**: `RCLONE_GPHOTOS_BATCH_MODE`
- **`Type`**: string
- **`Default`**: "sync"

- **`--gphotos-batch-size`** — max number of files in an upload batch.

This sets the batch size of files to upload. It <italic>has</italic> to be less than 50. no negotiating.

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

Rclone will close any outstanding batches when it exits, which may make a delay on quit.

Setting this is a <mint>great idea</mint> if you are uploading lots of small files, because it will make them a lot quicker. You can use `--transfers 32` to maximise throughput. go off 💅

Properties:

- **`Config`**: batch_size
- **`Env Var`**: `RCLONE_GPHOTOS_BATCH_SIZE`
- **`Type`**: int
- **`Default`**: 0

- **`--gphotos-batch-timeout`** — 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. bye girl 👋

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

- **`--gphotos-description`** — description of the remote ✨

Properties:

- **`Config`**: description
- **`Env Var`**: `RCLONE_GPHOTOS_DESCRIPTION`
- **`Type`**: string
- **`Required`**: false

---

## 🚧 Limitations 🚧

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. so like… it goes up and then immediately gets humbled 💀

> NB From March 31, 2025 rclone can only download photos <italic>it</italic> uploaded. This limitation is due to policy changes at Google. You may need to run `rclone config reconnect remote:` to make rclone work again after upgrading to rclone v1.70. not a drill.

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.. (yes that double period is in the original, we don't judge 😭)

`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. big L honestly.

See List of backends that do not support `rclone about` (https://rclone.org/overview/#optional-features) See `rclone about` (https://rclone.org/commands/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 (https://issuetracker.google.com/issues/112096115).

The current google API does not allow photos to be downloaded at original resolution. This is <red>very important</red> 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. ok that's actually kind of scary 😭

> 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 (https://issuetracker.google.com/issues/113672044). the compression is giving "we did our best".

> NB you can use the `--gphotos-proxy` flag to use a headless browser to download images in full resolution.

---

## 👯 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!). long ID representation, we love to see it 💅

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 <italic>first</italic> 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. it's fine it's 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 <italic>not</italic> the modification date of the media on local disk. This means that rclone cannot use the dates from Google Photos for syncing purposes. sorry bestie, them's the rules.

---

## 📏 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. just vibes, no numbers.

It is possible to read the size of the media, but this needs an extra HTTP HEAD request per media item so is <red>very slow</red> 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 🔬✨

---

## 📸 Albums 📸

Rclone can only upload files to albums <italic>it</italic> created. This is a limitation of the Google Photos API (https://developers.google.com/photos/library/guides/manage-albums). no crashing other people's albums.

Rclone can remove files it uploaded from albums it created only.

---

## 🗑️ 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 (https://issuetracker.google.com/issues/109759781). it's gone but not <italic>gone</italic> gone.

Rclone cannot delete files anywhere except under `album`.

---

## 💔 Deleting albums 💔

The Google Photos API does not support deleting albums — see bug #135714733 (https://issuetracker.google.com/issues/135714733). the album stays forever, she's immortal 👑

### 🌸 Making your own client_id 🌸

Okay bestie, listen up, because this one is **important**. When you use rclone with Google Photos in its default configuration, you're using *rclone's* client_id. And that client_id is shared between **all** the rclone users. Every single one. The whole girlies-and-they-dies population. 💀

> <red>This shared client_id is being retired and will stop working during 2026.</red> Not a drill. To avoid interruption you **must** create and use your own client_id — so creating one is now **required** rather than optional. New remotes created with `rclone config` will warn you if you leave the client_id blank.

So go follow the steps in the google drive docs (`https://rclone.org/drive/#making-your-own-client-id`) but like… with these little differences, okay? ✨

- At step 3, instead of enabling the `"Google Drive API"`, search for and enable the `"Photos Library API"`.
- At step 5, you will need to add different scopes. Use these scopes instead of the drive ones:

https://www.googleapis.com/auth/photoslibrary.appendonly https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata

---

## Hasher 👑

Hasher is a special *overlay* backend that makes remotes which handle checksums for other remotes. It's giving personal assistant for hashes. It's 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 — vibe check it first, fr fr.

Let's call the base remote `myRemote:path` here. Note that **anything inside** `myRemote:path` will be handled by hasher and **anything outside won't**. 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. Pick your fighter. 🎀

### 🦋 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 the section for the base remote and create a 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.

## 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 *sticky* 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 (`https://rclone.org/docs/#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 (`https://rclone.org/commands/rclone_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 (`https://rclone.org/rc/#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!!. So like, don't @ me. 💀

### 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 💅

- <purple>any time a hash is requested</purple>, 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 <red>disable checksum caching completely</red>. 💀

If you set `max_age = off`, checksums in cache will never age, unless you fully rewrite or delete the file. no cap, they're immortal 👑

### Cache storage 🎀

Cached checksums are stored as bolt database files under rclone cache directory, usually `~/.cache/rclone/kv/`. Databases are maintained <hotpink>one per base backend</hotpink>, 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 <green>can be shared between multiple rclone processes</green>. 🫶

---

# 🌸 Huawei Drive 🌸

Paths are specified as `huaweidrive:path`

Huawei Drive paths may be as deep as required, e.g. `huaweidrive:directory/subdirectory`. 🦋

## Configuration ⚙️

The initial setup for Huawei Drive involves getting a token from Huawei Drive 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:

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 / Huawei Drive \ "huaweidrive" [snip] Storage> huaweidrive OAuth Client Id - leave blank to use rclone's default. client_id> OAuth Client Secret - leave blank to use rclone's default. 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: huaweidrive
• client_id:
• client_secret:
• token: {"access_token":"XXX","token_type":"Bearer","refresh_token":"XXX","expiry":"2024-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 (`https://rclone.org/remote_setup/`) for how to set it up on a machine without an internet-connected web browser available. 🙈

Note that rclone runs a webserver on your local machine to collect the token as returned from Huawei if using web browser to automatically authenticate. 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, or use manual mode. 🔥

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

## Getting your own Client ID and Secret 🔑

When you use rclone with Huawei Drive in its default configuration you are using rclone's `client_id`. This is shared between <rainbow>all the rclone users</rainbow>. There is a global rate limit on the number of queries per second that each `client_id` can do set by Huawei. 😭

It is <bold>strongly recommended</bold> 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 a separate client ID for each service to avoid rate limiting issues. 🫶

Here is how to create your own Huawei Drive client ID for rclone:

Follow the detailed guides for complete setup instructions:

- Huawei HMS Core Web App Preparations (`https://developer.huawei.com/consumer/cn/doc/HMSCore-Guides/web-preparations-0000001050050891`)

- Huawei HMS Core Server Preparations (`https://developer.huawei.com/consumer/cn/doc/HMSCore-Guides/server-preparations-0000001050185577#section194911701377`)

Rclone uses the web application access method to connect to Huawei Drive. Before starting, you need to implement quick login authorization through Huawei Account Open Service. With user authorization credentials, rclone can call Huawei Cloud Drive Service APIs. ✨

## Create Server Application 🛠️

Before accessing Drive service, developers need to create a server application first. For details, please refer to the WEB Application Access Development Preparation section in the "Huawei Account Service Development Guide". 📖

## Enable Drive Application Switch 🎚️

1. Log in to AppGallery Connect with your Huawei account. 🔑

2. Create a project or select an existing project. 📁

3. Add a web application to the project. 🌐

4. Open "Project settings" for the application and copy the OAuth 2.0 Client ID and Client Secret from the "General" tab. 📋

5. Open "API Management" for the project and enable "Cloud Drive". ☁️

6. Add `http://127.0.0.1:53682/` as a redirect URI for the OAuth 2.0 Client ID. 🔁

The older Huawei Developer Console may show some of the same credential information, but AppGallery Connect is the place to create the project, application, API permission, and redirect URI used by rclone. 💅

## Sign Huawei Cloud Drive Privacy Notice and User Agreement 📝

Guide users to visit `https://cloud.huawei.com/`. First-time users need to sign the agreement before they can use Huawei Cloud Drive Service. ✍️

## Application Access to Obtain Authentication Credential Access Token 🎟️

Applications accessing Drive should use authentication credential Access Token. For specific acquisition methods, please refer to the WEB Application Access Development Guide section in the "Huawei Account Service Development Guide". 📚

Key steps summary:

1. Create or select a project in AppGallery Connect. ✨

2. Add a web application to the project. 🌸

3. Enable Cloud Drive in API Management. ☁️

4. Configure `http://127.0.0.1:53682/` as the OAuth redirect URI. 🔁

5. Copy the OAuth 2.0 Client ID and Client Secret from the application. 📋

6. Provide the client ID and client secret to rclone during configuration. 🫶

## Scopes 🔭

Rclone uses the following OAuth2 scopes when accessing Huawei Drive:

- `https://www.huawei.com/auth/drive` — Full access to Huawei Drive files (excluding application data folder) 👑

- `https://www.huawei.com/auth/drive.file` — Access to files created by the application 🍓

- `openid` — OpenID Connect authentication 🪪

- `profile` — Access to basic profile information 🙋‍♀️

The `drive.file` scope is included in the default set used by rclone. ✅

Alternative scopes available (not used by rclone by default):

- `https://www.huawei.com/auth/drive.appdata` — Access to application data folder 📂

- `https://www.huawei.com/auth/drive.readonly` — Read-only access to file metadata and content 👀

- `https://www.huawei.com/auth/drive.metadata` — Read/write access to file metadata only 🏷️

- `https://www.huawei.com/auth/drive.metadata.readonly` — Read-only access to file metadata only 🧐

The default scopes provide read/write access to all files in your Huawei Drive. 💜

## Modification times and hashes 🕰️

Huawei Drive <red>does not support setting modification times</red>. The API always uses server-side timestamps, so file modification times from the source are not preserved during upload. Modification times are available as read-only metadata (`mtime`, `btime`). 😭

Hash algorithm `SHA256` is supported for file integrity verification. 🔐

## Restricted filename characters 🚫

Huawei Drive has strict restrictions on file and directory names:

- Cannot contain: `< > | : " * ? / \` or emoji characters 😱

- Cannot be exactly `.` or `..`

- Maximum length: 250 bytes 📏

- Single quotes must be escaped with `\'` in API calls

These restrictions are handled by rclone's encoding:

- Backslashes `\` are encoded 💅

- Invalid UTF-8 sequences are encoded
- Right-side spaces are encoded

Invalid characters will be replaced (`https://rclone.org/overview/#invalid-utf8`) according to the encoding settings. ✨

## Resumable uploads 🔄

Huawei Drive supports resumable uploads for files larger than the upload cutoff (default `20MB`). Files are uploaded in chunks which allows for recovery from network interruptions. 🫶

## File size limits 📦

The maximum file size for Huawei Drive is <hotpink>50 GiB</hotpink>. 💀

## Quota information 📊

To view your current quota you can use the `rclone about remote:` command which will display your usage and quota information. 👑

---

## Standard options ✨

Here are the Standard options specific to `huaweidrive` (Huawei Drive). 🚗

## `--huaweidrive-client-id`

OAuth Client Id. 🪪

Leave blank normally.

Properties:

- Config: `client_id`
- Env Var: `RCLONE_HUAWEIDRIVE_CLIENT_ID`
- Type: `string`
- Required: `false`

## `--huaweidrive-client-secret`

OAuth Client Secret. 🤫

Leave blank normally.

Properties:

- Config: `client_secret`
- Env Var: `RCLONE_HUAWEIDRIVE_CLIENT_SECRET`
- Type: `string`
- Required: `false`

## Advanced options 🔥

Here are the Advanced options specific to `huaweidrive` (Huawei Drive). 💅

## `--huaweidrive-token`

OAuth Access Token as a JSON blob. 🎟️

Properties:

- Config: `token`
- Env Var: `RCLONE_HUAWEIDRIVE_TOKEN`
- Type: `string`
- Required: `false`

## `--huaweidrive-auth-url`

Auth server URL. 🌐

Leave blank to use the provider defaults.

Properties:

- Config: `auth_url`
- Env Var: `RCLONE_HUAWEIDRIVE_AUTH_URL`
- Type: `string`
- Required: `false`

## `--huaweidrive-token-url`

Token server url. 🔑

Leave blank to use the provider defaults.

Properties:

- Config: `token_url`
- Env Var: `RCLONE_HUAWEIDRIVE_TOKEN_URL`
- Type: `string`
- Required: `false`

- **`--huaweidrive-client-credentials`** — bestie, this flips on the client credentials OAuth flow. It uses the OAUTH2 client Credentials Flow exactly like RFC 6749 describes it. Heads up tho: this option is **NOT** supported by all backends 💀

  Properties:

  - Config: `client_credentials`
  - Env Var: `RCLONE_HUAWEIDRIVE_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: `false`

- **`--huaweidrive-root-folder-id`** — the ID of the root folder, obviously ✨ Normally it gets auto-detected all on its own, but if that ever flops, or you're just impatient and want a speedier startup, you can set it by hand. Otherwise leave it blank, like, always.

  Properties:

  - Config: `root_folder_id`
  - Env Var: `RCLONE_HUAWEIDRIVE_ROOT_FOLDER_ID`
  - Type: string
  - Required: `false`

- **`--huaweidrive-chunk-size`** — the upload chunk size. Rules are rules: it's gotta be a power of 2 that's `>=` 256k and `<=` 64MB. No vibe-checking your way around that one 🎀

  Properties:

  - Config: `chunk_size`
  - Env Var: `RCLONE_HUAWEIDRIVE_CHUNK_SIZE`
  - Type: SizeSuffix
  - Default: `8Mi`

- **`--huaweidrive-list-chunk`** — size of the listing chunk, valid range 1-1000. Keep it in the window, girl.

  Properties:

  - Config: `list_chunk`
  - Env Var: `RCLONE_HUAWEIDRIVE_LIST_CHUNK`
  - Type: int
  - Default: `1000`

- **`--huaweidrive-upload-cutoff`** — the cutoff for switching over to resumable upload 👑 Any file bigger than this gets uploaded with resumable upload instead. The minimum is `0` and the maximum is 20 MiB (that's the Huawei Drive API limit for single request uploads, so like, respect it).

  Properties:

  - Config: `upload_cutoff`
  - Env Var: `RCLONE_HUAWEIDRIVE_UPLOAD_CUTOFF`
  - Type: SizeSuffix
  - Default: `20Mi`

- **`--huaweidrive-encoding`** — the encoding for the backend. Slide over to the encoding section in the overview for more info: `https://rclone.org/overview/#encoding`

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_HUAWEIDRIVE_ENCODING`
  - Type: Encoding
  - Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftSpace,LeftPeriod,LeftTilde,RightSpace,RightPeriod,InvalidUtf8,Dot`

- **`--huaweidrive-description`** — a lil description of the remote. Cute, right? 🦋

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_HUAWEIDRIVE_DESCRIPTION`
  - Type: string
  - Required: `false`

---

## 🌸 Metadata 🌸

Huawei Drive can read **and** write custom metadata. Obsessed, actually.

User metadata gets set using the `"properties"` field in the API. System metadata includes the standard file info stuff, like:

- `content-type`: MIME type of the object
- `description`: User-provided description
- `favorite`: Whether file is marked as favorite
- `btime`/`mtime`/`utime`: Various timestamps
- `sha256`: File hash
- `recycled`/`has-thumbnail`: File status flags

Custom metadata keys can be, like, any string at all, and they'll be stored in the file's properties. Periodt.

Here are the possible system metadata items for the `huaweidrive` backend:

- **`btime`** — Time when the file was created (RFC 3339). Type: `RFC 3339`. Read Only: `Y`
- **`content-type`** — MIME type of the object. Type: `string`. Read Only: `Y`
- **`description`** — Description of the file. Type: `string`. Read Only: `N`
- **`favorite`** — Whether the file is marked as favorite (true/false). Type: `string`. Read Only: `N`
- **`has-thumbnail`** — Whether the file has a thumbnail (true/false). Type: `string`. Read Only: `Y`
- **`mtime`** — Time when the file content was last modified (RFC 3339). Type: `RFC 3339`. Read Only: `Y`
- **`recycled`** — Whether the file is in recycle bin (true/false). Type: `string`. Read Only: `Y`
- **`sha256`** — SHA256 hash of the file. Type: `string`. Read Only: `Y`
- **`utime`** — Time when the file was last edited by the current user (RFC 3339). Type: `RFC 3339`. Read Only: `Y`

See the metadata docs for more info: `https://rclone.org/docs/#metadata`

---

## Limitations

Huawei Drive has some rate limiting going on, which may cause rclone to slow down transfers so it doesn't slam into those limits. It's giving considerate. 😌

### File name restrictions

- File names cannot contain: `<` `>` `|` `:` `"` `*` `?` `/` `\`
- File names cannot be exactly `.` or `..`
- Maximum file name length is 250 bytes
- Some unicode characters including emojis are not supported

> Not the emojis 😭 but fr fr, that's what it says.

### API rate limits

Huawei Drive imposes API rate limits. Rclone automatically handles these by backing off whenever limits are hit. No panicking required.

### OAuth2 token expiry

- Access tokens expire after 1 hour
- Refresh tokens expire after 180 days
- Rclone will automatically refresh tokens as needed

### File size limits

- Maximum file size is 50 GiB
- Files larger than this cannot be uploaded

### Upload behavior

- Files smaller than `upload_cutoff` (default 20MB) are uploaded in a single request using content or multipart method
- Larger files are uploaded using resumable uploads with configurable chunk size
- Maximum single chunk size for resumable uploads is 64MB
- Resumable uploads support automatic retry on network errors
- SHA256 hash verification is supported for uploaded files

### Server-side operations

- Server-side copy: Files can be copied within Huawei Drive without downloading and re-uploading
- Server-side move: Files and directories can be moved/renamed on the server side
- Directory move: Entire directories can be moved with a single API call

### Directory operations

- Huawei Drive supports creating empty directories
- Recursive listing is supported via `--fast-list` for efficient directory traversal
- Huawei Drive has a special `"applicationData"` folder for app-specific data (not accessible via rclone's default configuration)

### Error handling

The common errors and what they actually mean:

- `401 Unauthorized`: Invalid credentials or expired token
- `403 Forbidden`: Usually indicates insufficient permissions or API quota exceeded
- `404 Not Found`: File or directory does not exist
- `409 Conflict`: Directory already exists
- `429 Too Many Requests`: API rate limit exceeded, rclone will automatically retry

### Performance tuning

For better performance, bestie:

- Increase `--transfers` for concurrent operations (default is 4)
- Adjust `chunk_size` based on your network speed and file sizes
- Use `--fast-list` for operations on directories with many files to reduce API calls

### Making backups

Huawei Drive is suitable for backups, with some considerations:

- Use `rclone sync` rather than `rclone copy` to maintain exact directory structure
- Consider using `--backup-dir` to preserve deleted files
- Verify transfers with `--checksum` flag for critical data
- Be aware of the 50 GiB file size limit for individual files

### Supported features

Huawei Drive supports the following rclone features:

- Copy - Server-side copy of files
- Move - Server-side move/rename of files
- DirMove - Server-side move of directories
- ListR - Recursive listing for `--fast-list`
- About - Storage quota information
- Purge - Delete directory and all contents
- CleanUp - Empty the trash
- UserInfo - Get user account information
- Metadata - Read and write file metadata/properties
- ChangeNotify - Poll for remote changes (used by `rclone mount` and `rclone rc vfs/poll-interval`)

### Integration with other services

Huawei Drive can be used as a backend for various rclone operations:

- Mount as a local filesystem using `rclone mount`
- Serve over HTTP using `rclone serve http`
- Serve over FTP using `rclone serve ftp`
- Serve over WebDAV using `rclone serve webdav`

> Note that some operations may be slower than local storage due to API limitations and network latency. Not everything can be instant, babe 💅

# 🌈 HDFS 🌈

ok so bestie, HDFS (https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) is a distributed file-system, and it's part of the Apache Hadoop (https://hadoop.apache.org/) framework. big cluster energy fr fr 💅

Paths get written as `remote:` or `remote:path/to/dir`. that's it, that's the address system ✨

---

## 🎀 Configuration 🎀

here's a lil example of how to make a remote called `remote`. first run:

rclone config

and it will walk you through the whole interactive setup thing:

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

This remote is called `remote` and now you can use it 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

---

## 🧚 Setting up your own HDFS instance for testing 🧚

You may start with a manual setup (https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/SingleCluster.html) or use the docker image from the tests:

If you want to build the docker image:

git clone https://github.com/rclone/rclone.git cd rclone/fstest/testserver/images/test-hdfs docker build --rm -t rclone/test-hdfs .

Or you can just use the latest one 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. give it a sec, she's waking up 😴

For this docker image the remote needs to be configured 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.) 🫠 so like, don't put anything precious in there, it's giving ephemeral.

---

## ⏰ Modification times ⏰

Time accurate to 1 second is stored. slay, one second of precision, that's the vibe ✨

## 🔍 Checksum 🔍

No checksums are implemented. nope, none, zero, nada 💀

## 📊 Usage information 📊

You can use the `rclone about remote:` command which will display filesystem size and current usage. cute lil stat check 👑

## 🙈 Restricted filename characters 🙈

In addition to the default restricted characters set (https://rclone.org/overview/#restricted-characters) the following characters are also replaced:

- `:` — value `0x3A` — replaced with `：`

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8).

---

## ✨ 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 (https://rclone.org/overview/#encoding) 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 💀

- Erasure coding not supported, see issue #8808 (https://github.com/rclone/rclone/issues/8808)
- No server-side Move or DirMove.
- Checksums not implemented.

---

# 🦋 HiDrive 🦋

ok bestie, 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 💜

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. she'll hold your hand the whole time 🫶

## 🌸 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 / 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

> You should be aware that 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. 🚨 like, do NOT be handing those out, they're the keys to your whole account.

See the remote setup docs (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available.

Note that rclone runs a webserver on your local machine to collect the token as returned from 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 (replace remote with the name you gave your remote):

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. periodt 💅

It is possible to encrypt rclone's configuration file. You can find information on securing your configuration file by viewing the configuration encryption docs (https://rclone.org/docs/#configuration-encryption).

## ⌛ Invalid refresh token ⌛

As can be verified on HiDrive's OAuth guide (https://developer.hidrive.com/basics-flows/), each `refresh_token` (for Native Applications) is valid for 60 days. If used to access HiDrive, its validity will be automatically extended.

This means that if you:

- Don't use the HiDrive remote for 60 days

all good — **but** if that refresh token's gone and done, rclone will just hand you back an error whose text is basically screaming "this refresh token is invalid or expired" 😭💔

To fix it you've gotta re-authorize rclone to access your HiDrive account. Run:

rclone config reconnect remote:

and the whole process is *very* similar to that initial setup we already walked through. same energy, just round two 🎀

---

### Modification times and hashes ⏰

HiDrive lets you set modification times on objects, and it's accurate down to **1 second**. slay.

HiDrive also has its own hash type (`https://static.hidrive.com/dev/0001`) which rclone uses to double-check the integrity of file contents after a transfer goes through successfully. vibe check passed ✅

### Restricted filename characters 🚫

HiDrive literally cannot store files or folders whose names include `/` (`0x2F`) or null-bytes (`0x00`). Every other character is fair game. *But also* — files or folders can't be named `.` or `..` either. picky much 🙄

So rclone will automatically swap those characters out for you whenever you store or access files/folders with those kinds of names.

You can read about how this filename encoding works in general over in the main docs (`https://rclone.org/overview/#restricted-filenames`).

> Keep in mind that HiDrive only supports file or folder names with a length of **255 characters or less**. no novel-length filenames bestie 💀

### Transfers 📦

HiDrive caps file sizes per single request at a max of **2 GiB**. To let you store bigger files *and* get better upload performance, the hidrive backend switches to a chunked transfer for files larger than **96 MiB**. Rclone uploads multiple parts/chunks of the file at the same time, and any chunks in the process of being uploaded get buffered in memory — so on systems with limited resources you might wanna restrict this behaviour. lowkey memory-hungry 💅

You can customize all of this with the following 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 section below about configuration options for more deets 👇

### Root folder 🌳

You can set the root folder for rclone — this is the directory rclone treats as the root of your HiDrive.

Usually you leave this blank and rclone just uses the root of the account. easy!

But you *can* set it to lock rclone into a specific folder hierarchy. Here's how it works: the contents of the `root_prefix` option get prepended to any paths rclone accesses. For example, these two ways of accessing the home directory are equivalent:

rclone lsd --hidrive-root-prefix="/users/test/" remote:path rclone lsd remote:/users/test/path

See the section below about configuration options for more deets 👇

### Directory member count 🔢

By default rclone knows the number of directory members contained in a directory — for example, `rclone lsd` uses this info.

But grabbing that info costs extra time on HiDrive's API. When you're dealing with large directory structures, it might be worth dodging that time cost, especially when you don't explicitly need the number. For that, use the `disable_fetching_member_count` option.

See the section below about configuration options for more deets 👇

### 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.
  - Note that this option is **NOT** supported by all backends.
  - 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 (`https://rclone.org/overview/#encoding`) 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.

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. That means rclone will **not** be able to access or show any symlinks stored in the hidrive-remote. So symlinks can't be individually removed, copied, or moved — except when you remove, copy, or move the parent folder. sorry bestie, that's just the rules 😭

This does not affect the `.rclonelink`-files that rclone uses to encode and store symbolic links. those are safe 🫶

#### 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. so like… your "sparse" file is not staying sparse. just so you know ✨

---

## HTTP 🌐

The HTTP remote is a **read only** remote for reading files of a webserver. The webserver should provide file listings which rclone will read and turn into a remote. This has been tested with common webservers such as Apache/Nginx/Caddy and will likely work with file listings from most web servers. (If it doesn't then please file an issue, or send a pull request!) 👑

Paths are given to you as `remote:` or `remote:path` — that's the whole vibe, bestie 💖

The `remote:` bit is your configured url, and whatever path comes after it gets resolved relative to that url, following the URL standard. So like, if your remote url is `https://beta.rclone.org/branch` and your path is `fix`, the resolved URL is `https://beta.rclone.org/branch/fix` — but if your path is `/fix`, the resolved URL is `https://beta.rclone.org/fix`, because an absolute path gets resolved from the root of the domain. ALSO important: the path can't change the scheme, host, or user of the configured url, so a path like `//other.example.com/fix` is straight up **rejected**. 🚫

If the path after `remote:` ends with `/` it gets assumed to be a directory, okay? But if it *doesn't* end with `/`, then a HEAD request gets sent and the response is what decides if it's treated as a file or a directory (run with `-vv` to see the details, nosey 👀). When `--http-no-head` is specified, a path without an ending `/` is *always* assumed to be a file. So if rclone incorrectly assumes the path is a file, the solution is to specify the path with an ending `/`. And when you *know* the path is a directory, ending it with `/` is always better because it avoids the initial HEAD request. Efficiency queen 👑

To just download a single file it is easier to use `copyurl` (https://rclone.org/commands/rclone_copyurl/).

## <cyan>Configuration</cyan> ✨

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

## <lavender>Read only</lavender> 🔒

This remote is read only — you *can't* upload files to an HTTP server. Sorry babe, no uploads allowed, it's giving spectator mode 💅

## <peach>Servers without directory listings</peach> 🌸

Rclone normally needs the HTTP server to return a parseable directory listing in order to discover files. BUT 💡 if the path points directly at a single file (i.e. it does not end with `/` and the initial HEAD request reports it as a file), rclone will skip the *parent directory listing entirely* and access the file directly. Iconic behaviour honestly.

This means rclone can be used to download individual files on HTTP servers that have directory listings disabled, as long as you know the exact URL of each file. For example, given a server that serves `https://example.com/path/file.txt` but returns an error or an unparseable response for `https://example.com/path/`:

rclone copy --http-url https://example.com :http:path/file.txt /tmp/

You can use this as a remote in other rclone commands too:

rclone hashsum crc32 --http-url "https://getsamplefiles.com" :archive::http:download/zip/sample-1.zip

If you just want to download a file or multiple files by URL then using `copyurl` (https://rclone.org/commands/rclone_copyurl/) is more efficient. Just saying 💁

## <mint>Modification times</mint> ⏰

Most HTTP servers store time accurate to 1 second.

## <yellow>Checksum</yellow> 🎀

No checksums are stored. That's it, that's the whole section, she's empty bestie 😭

## <purple>Usage without a config file</purple> 🦋

Since the http remote only has *one* config parameter it is 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':

Look at her go, no config needed, low maintenance queen ✨

## <hotpink>Standard options</hotpink> 💖

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

## <cyan>Advanced options</cyan> 🔥

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 comma separated list of key,value pairs. Standard CSV encoding (https://godoc.org/encoding/csv) 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"'`.

  The headers are only sent to the host in the configured URL. If the server redirects to another host (including a subdomain or a different port) the headers are **not** sent to it, or to any further hop in that redirect chain. When headers are set, a redirect from `https` to `http` is **refused** as it would send them in cleartext. 🚨 Safety first, bestie.

  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. Chaos potential, fr fr.

  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. ⚡ Fast but messy, tradeoffs are real.

  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

## <lavender>Metadata</lavender> 🏷️

HTTP metadata keys are case insensitive and are always returned in lower case. No shouting allowed 💅

Here are the possible system metadata items for the http backend.

- `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-disposition-filename` — Filename retrieved from Content-Disposition header; type string; example `file.txt`; 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

See the metadata (https://rclone.org/docs/#metadata) docs for more info.

---

## <hotpink>Backend commands</hotpink> 👑

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 (https://rclone.org/commands/rclone_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` (https://rclone.org/rc/#backend-command).

### <mint>set</mint> 🎀

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. Live updates, we love to see it ✨

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. Silent but powerful 🫥

## <red>Limitations</red> 💀

`rclone about` is **not** supported 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. Yeah so that's just not a thing here, sorry bestie 😭

See List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

# 🖼️💖 ImageKit 💖🖼️

Okay bestie, so this right here is a backend for the ImageKit.io (`https://imagekit.io/`) storage service. ✨

ImageKit.io (`https://imagekit.io/`) provides real-time image and video optimizations, transformations, and CDN delivery. Over 1,000 businesses and 70,000 developers trust ImageKit with their images and videos on the web. Like, over a *thousand* businesses?? That's not a vibe check, that's a whole vibe <italic>institution</italic>. 👑

To use this backend, you need to create an account (`https://imagekit.io/registration/`) on ImageKit. 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 (`https://imagekit.io/plans`). Free plan to start, glow-up later — the character arc is <italic>arc-ing</italic>. 🌱➡️🌸

---

## 🎀 Configuration 🎀

Here is an example of making an `imagekit` configuration.

Firstly create a ImageKit.io (`https://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. Fresh folder, fresh era. 🦋

rclone mkdir imagekit-media-library:directory

List the contents of a directory.

rclone ls imagekit-media-library:directory

---

## ⏰ Modified time and hashes ⏰

ImageKit does not support modification times or hashes yet. Nope, not yet, don't @ me. 😭

---

## 🧮 Checksums 🧮

No checksums are supported. Zero. None. It's giving <italic>trust fall</italic>. 💀

---

## ⭐ 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 (`https://imagekit.io/dashboard/developer/api-keys`)

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 (`https://imagekit.io/dashboard/developer/api-keys`)

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 (`https://imagekit.io/dashboard/developer/api-keys`)

Properties:

- Config: `private_key`
- Env Var: `RCLONE_IMAGEKIT_PRIVATE_KEY`
- Type: `string`
- Required: `true`

> 🤫 Bestie. That private key? That's the <italic>secret</italic> secret. Do not be posting it in the group chat.

---

## 🚀 Advanced options 🚀

Here are the Advanced options specific to `imagekit` (ImageKit.io).

### `--imagekit-only-signed`

If you have configured Restrict unsigned image URLs 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 (`https://rclone.org/overview/#encoding`) 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.

Every single one of these is read only (`Y`), so admire, don't touch. 🌸 Here's the whole lineup, with the columns being Name, Help, Type, Example, and Read Only:

- **`aws-tags`** — AI generated tags by AWS Rekognition associated with the image. Type: `string`. Example: `tag1,tag2`. Read Only: `Y`
- **`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`
- **`custom-coordinates`** — Custom coordinates of the file. Type: `string`. Example: `0,0,100,100`. Read Only: `Y`
- **`file-type`** — Type of the file. Type: `string`. Example: `image`. Read Only: `Y`
- **`google-tags`** — AI generated tags by Google Cloud Vision associated with the image. Type: `string`. Example: `tag1,tag2`. Read Only: `Y`
- **`has-alpha`** — Whether the image has alpha channel or not. Type: `bool`. Read Only: `Y`
- **`height`** — Height of the image or video in pixels. Type: `int`. Read Only: `Y`
- **`is-private-file`** — Whether the file is private or not. Type: `bool`. Read Only: `Y`
- **`mtime`** — Time of last modification, read from the file's `updatedAt` field. Type: `RFC 3339`. Example: `2006-01-02T15:04:05.999999999Z07:00`. Read Only: `Y`
- **`size`** — Size of the object in bytes. Type: `int64`. Read Only: `Y`
- **`tags`** — Tags associated with the file. Type: `string`. Example: `tag1,tag2`. Read Only: `Y`
- **`width`** — Width of the image or video in pixels. Type: `int`. Read Only: `Y`

See the metadata (`https://rclone.org/docs/#metadata`) docs for more info. ✨

## 🍎 Configuration ✨

okay bestie so the very first time you set up an iCloud backend, you gotta go get yourself a trust token/session 💖. That means using your actual regular Apple ID password plus 2FA — either a prompt on a trusted device or an SMS code slid to a trusted phone number 📱.

> <red>IMPORTANT:</red> App-specific passwords are **NOT** accepted, bestie, don't even try it. Only use your regular Apple ID password and 2FA. periodt 💅

This backend is serving *two* Apple services, and you get to pick:

- **`drive`** — iCloud Drive (this is the default, bestie)
- **`photos`** — iCloud Photos 🦋

`rclone config` literally walks you through the token creation, no cap. The catch? The trust token is valid for **30 days**. After that you're gonna have to reauthenticate with `rclone reconnect` or `rclone config` again. She expires, unfortunately 😭

---

## 🔐 Authentication

rclone talks to Apple using **SRP** (Secure Remote Password) — that's `https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol`, and it's the *exact same protocol* the iCloud web interface uses. The way that your password is **never** sent to Apple's servers?? Iconic. Instead a cryptographic proof gets exchanged that verifies you know the password without actually revealing it. Chef's kiss 👑

The authentication flow is giving:

1. rclone initiates a session with Apple's identity service
2. An SRP key exchange takes place (your password is used locally to derive a key)
3. Apple sends a 2FA prompt to your trusted devices, or lets you request an SMS code
4. After you enter the 2FA code, rclone receives a trust token for future sessions

Here's an example of how to make a Photos remote called `icloudphotos`. For iCloud Drive, just leave `service` at its default `drive` value, easy. 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> icloudphotos 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 service. iCloud service to use. Choose a number from below, or type in your own value of type string. Press Enter for the default (drive). 1 / iCloud Drive \ (drive) 2 / iCloud Photos \ (photos) service> 2 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: enter your 2FA code or type 'sms' for a text message Enter a value. config_2fa> 2FACODE Remote config

---

[icloudphotos]

• type: iclouddrive
• service: photos
• 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

---

## 🦋 iCloud Photos

The iCloud Drive backend also supports accessing iCloud Photos, you just set the `service` option to `photos`:

rclone lsd iclouddrive: --iclouddrive-service photos

This presents a **read-only** hierarchy rooted at photo libraries, and it's structured like this:

- **Level 1:** Photo libraries — your personal library (`PrimarySync`) and any Shared Photo Library (`SharedSync-XXXX`)
- **Level 2+:** Albums and folders within a library, nested recursively as in Apple Photos
- **Leaf level:** Photos/videos within an album, including Live Photo `.MOV` companions 🎀

Examples, bestie:

List libraries

rclone lsd iclouddrive: --iclouddrive-service photos

List albums in your primary library

rclone lsd iclouddrive:PrimarySync/ --iclouddrive-service photos

List photos in an album

rclone ls iclouddrive:PrimarySync/All\ Photos/ --iclouddrive-service photos

Download a photo

rclone copy iclouddrive:PrimarySync/Favorites/IMG_0001.HEIC /tmp/ --iclouddrive-service photos

You can either:

- set `service = photos` in `rclone config` for a dedicated Photos remote, or
- keep `service = drive` and pass `--iclouddrive-service photos` whenever you need it

Your call, queen 👑

---

## 🏷️ Metadata

With `--metadata`, Photos entries expose these read-only metadata keys:

- `width`
- `height`
- `added-time`
- `favorite`
- `hidden`

These metadata keys are **only** available when `service = photos`. Don't come looking for them anywhere else 🙈

---

## 💾 Caching

iCloud Photos caches album listings to disk so subsequent access is fast, because she's efficient like that. On the first run, listing a large album uses parallel `startRank` partitions to fetch pages concurrently 🔥. After that, a lightweight change check (~200ms) determines whether the cache is still valid. Literally 200ms, we love a quick vibe check.

Cache location: `~/.cache/rclone/iclouddrive-photos/<remote>/<zone>/`

To clear the cache: just delete that directory or run `rclone config reconnect`. That's it, that's the whole thing ✨

---

## 🌸 FUSE mounts

For mounting iCloud Photos via `rclone mount`, these flags are *recommended*, and honestly they're the moment:

rclone mount remote: /mnt/photos \ --iclouddrive-service photos \ --vfs-refresh \ --dir-cache-time 1h \ --vfs-cache-mode full \ --attr-timeout 1m \ --read-only

- `--vfs-refresh` pre-warms directory caches in the background on mount start so that albums are ready when you browse them 💅
- `--dir-cache-time 1h` extends the in-memory cache lifetime beyond the default 5 minutes (change detection is fast, so this is safe)
- `--vfs-cache-mode full` caches downloaded photos and videos to local disk for fast repeated access
- `--attr-timeout 1m` reduces kernel attribute lookups (safe because the backend is read-only)
- `--read-only` prevents confusing write errors, no thank you to chaos 💀

> Heads up: the first listing of a very large album (e.g. 75,000 items in "All Photos") can take **several minutes** due to API pagination limits. This happens once — subsequent listings use the disk cache. So don't panic, she's just warming up 🧚

---

## 🚫 Limitations

iCloud Photos is **read-only**. Upload, delete, rename, and move operations are **not supported**. Sorry babe, no writing, only looking 🙈

---

## 🛡️ Advanced Data Protection

Advanced Data Protection **is supported** ✅

On iPhone, `Settings > Apple Account > iCloud > 'Access iCloud Data on the Web'` must be **ON**.

If ADP is enabled on your account, rclone requests PCS cookies after 2FA. Apple *may* require approval on a trusted device before those cookies are issued, so keep an eye on your phone 👀

---

## 🩹 Troubleshooting

### PCS cookie errors with ADP

If you see `Missing PCS cookies from the request` or a `requestPCS: error`, the ADP approval flow did not complete successfully. She got stuck, it happens 😭

Check that `'Access iCloud Data on the Web'` is enabled and approve any prompt on your trusted device.

Then run `rclone reconnect remote:`.

If the remote still has stale auth state, clear the `cookies` and `trust_token` fields in the config, or delete and recreate the remote. Fresh start energy, periodt 💖

---

## ⚙️ Standard options

Here are the Standard options specific to iclouddrive (iCloud Drive and Photos).

### `--iclouddrive-service`

iCloud service to use.

Properties:

- **Config:** `service`
- **Env Var:** `RCLONE_ICLOUDDRIVE_SERVICE`
- **Type:** string
- **Default:** `"drive"`
- **Examples:**
  - `"drive"`
    - iCloud Drive
  - `"photos"`
    - iCloud Photos

### `--iclouddrive-apple-id`

Apple ID.

Properties:

- **Config:** `apple_id`
- **Env Var:** `RCLONE_ICLOUDDRIVE_APPLE_ID`
- **Type:** string
- **Required:** true

### `--iclouddrive-password`

Password.

> NB Input to this must be obscured - see `rclone obscure` (`https://rclone.org/commands/rclone_obscure/`).

Properties:

- **Config:** `password`
- **Env Var:** `RCLONE_ICLOUDDRIVE_PASSWORD`
- **Type:** string
- **Required:** true

---

## 🌟 Advanced options

Here are the Advanced options specific to iclouddrive (iCloud Drive and Photos).

### `--iclouddrive-client-id`

Client ID for iCloud API access.

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 (`https://rclone.org/overview/#encoding`) 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

---

## 🏷️ Metadata

Metadata is **read-only** and available for the **Photos service only**.

Here are the possible system metadata items for the iclouddrive backend.

- **`added-time`** — Time the item was added to the iCloud library — Type: `RFC 3339` — Example: `2006-01-02T15:04:05Z` — Read Only: Y
- **`favorite`** — Whether the item is marked as favorite — Type: `bool` — Read Only: Y
- **`height`** — Image height in pixels — Type: `int` — Read Only: Y
- **`hidden`** — Whether the item is hidden — Type: `bool` — Read Only: Y
- **`width`** — Image width in pixels — Type: `int` — Read Only: Y

See the metadata (`https://rclone.org/docs/#metadata`) docs for more info.

---

# 🌐 Internet Archive

The Internet Archive backend utilizes Items on archive.org (`https://archive.org/`)

Refer to IAS3 API documentation (`https://archive.org/services/docs/api/ias3.html`) for the API this backend uses.

Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in too, e.g. `remote:item/path/to/dir`.

Unlike S3, listing up all items uploaded by you isn't supported. Nope, not a thing 🙈

Once you have made a remote, you can use it like this:

Make a new item

okay bestie, so you wanna actually *do* stuff with your Internet Archive item?? say less 💅 here's the trio of moves you'll be living in:

- **make a fresh item on the remote** — very "new era, new me" energy:

rclone mkdir remote:item

- **peek at what's inside an item** — lowkey nosy but honestly same:

rclone ls remote:item

- **sync `/home/local/directory` up to the remote item, nuking any extra files that are chillin' in there**:

rclone sync --interactive /home/local/directory remote:item

---

## Notes

so the tea is: Internet Archive's architecture is *built different* 😭 it doesn't just do your write operations immediately — it **enqueues** them (plus some extra post-processings) into a **per-item queue**. You can stalk that queue for any given item right here: <https://catalogd.archive.org/history/item-name-here> 👀

and because of that whole queue situation, **your uploads and deletes are not gonna show up right away** — they take a lil minute to actually be available. (patience, queen 🧚)

and plot twist: that per-item queue gets enqueued into *another* queue — the **Item Deriver Queue**. Wanna vibe-check that one? Right here: <https://catalogd.archive.org/catalog.php?whereami=1> ✨

> ⚠️ this Item Deriver Queue has a **limit**, and if it's full it may straight up **block you from uploading — or even from deleting**. So please, for the love of everything, **avoid uploading a ton of tiny little files**. It behaves way better when you don't do that. fr fr.

you can *optionally* make rclone wait for the server to finish its lil processing tasks, by setting a **non-zero value** to the `wait_archive` key 🎀 the upside? rclone can then do a normal file comparison like a well-behaved bestie. Just make sure you set a **big enough value** (like `30m0s` for smaller files) because depending on the server's queue this can take a *long* time. ngl it's giving "waiting for your food at a packed restaurant" 😭

---

## About metadata

this backend is fully that girl — it supports **setting, updating and reading metadata** for each file 💖 and that metadata will show up as **file metadata on Internet Archive** itself. iconic behavior.

BUT. some fields are reserved. by *both* Internet Archive and rclone. and we do not touch those, periodt. 🙅

**Reserved by Internet Archive:**

- `name`
- `source`
- `size`
- `md5`
- `crc32`
- `sha1`
- `format`
- `old_version`
- `viruscheck`
- `summation`

if you try to set values for any of these keys, it gets **ignored with a warning** 💀 the *one* exception is setting `mtime` — and doing that gives you **identical behavior to setting ModTime**. cute.

**Reserved by rclone:** every key that starts with `rclone-`. Setting values for these gives you **warnings**, but the values *do* get set according to your request. so like, it'll sass you about it and then do it anyway 🫶

if a key has **multiple values**, only **the first one** comes back to you. this is a genuine limitation of rclone — it only supports one value per key. it can pop up when you do a **server-side copy**. just so you're not confused later 💅

and reading metadata will *also* hand you any **custom** (non-standard and non-reserved) keys you've got going on. love that for us.

---

## Filtering auto generated files

here's the annoying part 🙈 Internet Archive **automatically creates metadata files** after your upload. and guess what — these cause ✨problems✨ when you're doing an `rclone sync`, because rclone will try to delete them... and **fail**. 😭 you can't change these metadata files either, because Internet Archive made them automatically. not up to us, babes.

the fix? exclude them from the sync using **metadata filtering** (<https://rclone.org/filtering/#metadata>):

rclone sync ... --metadata-exclude "source=metadata" --metadata-exclude "format=Metadata"

what that does is exclude *any* file that has the `source=metadata` or `format=Metadata` flags — which are exactly the ones slapped onto Internet Archive's auto-created files. bye felicia 👋

---

## Configuration

okay here's a whole example of setting up an `internetarchive` config ✨ most of it applies to the other providers too, and any differences get spelled out below.

**First run:**

rclone config

and it'll walk you through an interactive setup process. here's exactly how that looks:

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

(yes it asks you about advanced config *twice* — she contains multitudes 🎀)

---

## Standard options

here are the Standard options that are specific to `internetarchive` (Internet Archive) 💖

### `--internetarchive-access-key-id`

the IAS3 Access Key.

leave it blank for anonymous access 🕵️ you can grab one right here: <https://archive.org/account/s3.php>

Properties:

- Config: `access_key_id`
- Env Var: `RCLONE_INTERNETARCHIVE_ACCESS_KEY_ID`
- Type: string
- Required: false

### `--internetarchive-secret-access-key`

the IAS3 Secret Key (password). 🤫

leave it blank for anonymous access.

Properties:

- Config: `secret_access_key`
- Env Var: `RCLONE_INTERNETARCHIVE_SECRET_ACCESS_KEY`
- Type: string
- Required: false

### `--internetarchive-item-derive`

whether to trigger derive on the IA item or not. 🧬 if you set it to `false`, the item will **not** be derived by IA upon upload.

so what even *is* the derive process? it produces a bunch of **secondary files** from an upload, to make that upload more usable on the web. setting this to `false` is genuinely useful when you're uploading files that are **already in a format IA can display**, or when you just wanna reduce the burden on IA's infrastructure 🫶 (be kind to the servers, bestie)

Properties:

- Config: `item_derive`
- Env Var: `RCLONE_INTERNETARCHIVE_ITEM_DERIVE`
- Type: bool
- Default: `true`

---

## Advanced options

and these are the Advanced options specific to `internetarchive` (Internet Archive) 👑

### `--internetarchive-endpoint`

the IAS3 Endpoint.

leave it blank for the default value.

Properties:

- Config: `endpoint`
- Env Var: `RCLONE_INTERNETARCHIVE_ENDPOINT`
- Type: string
- Default: `"https://s3.us.archive.org"`

### `--internetarchive-front-endpoint`

Host of InternetArchive Frontend.

leave it blank for the default value.

Properties:

- Config: `front_endpoint`
- Env Var: `RCLONE_INTERNETARCHIVE_FRONT_ENDPOINT`
- Type: string
- Default: `"https://archive.org"`

### `--internetarchive-item-metadata`

metadata to be set on the **IA item** — pspsps note that this is *different* from file-level metadata, which you'd set using `--metadata-set` 📝

format is `key=value`, and the `x-archive-meta-` prefix gets added automatically. she does it for you, no need to thank her 💅

Properties:

- Config: `item_metadata`
- Env Var: `RCLONE_INTERNETARCHIVE_ITEM_METADATA`
- Type: stringArray
- Default: `[]`

### `--internetarchive-disable-checksum`

don't ask the server to test against the 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 that checksum 🔍 this is **great for data integrity checking**, but ngl it can cause **long delays for large files to start uploading** 😭 so there's a real trade-off here.

Properties:

- Config: `disable_checksum`
- Env Var: `RCLONE_INTERNETARCHIVE_DISABLE_CHECKSUM`
- Type: bool
- Default: `true`

### `--internetarchive-wait-archive`

timeout for waiting on the server's processing tasks (specifically `archive` and `book_op`) to finish ⏳

**only enable this if you need to be guaranteed that things are reflected after write operations.** `0` disables the waiting. and heads up — **no errors get thrown in case of timeout**, so don't expect a dramatic announcement if it gives up 🙈

Properties:

- Config: `wait_archive`
- Env Var: `RCLONE_INTERNETARCHIVE_WAIT_ARCHIVE`
- Type: Duration
- Default: `0s`

### `--internetarchive-encoding`

the encoding for the backend.

see the encoding section in the overview (<https://rclone.org/overview/#encoding>) for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_INTERNETARCHIVE_ENCODING`
- Type: Encoding
- Default: `Slash,LtGt,CrLf,Del,Ctl,InvalidUtf8,Dot`

### `--internetarchive-description`

description of the remote. a lil name tag for your remote, basically 🏷️

Properties:

- Config: `description`
- Env Var: `RCLONE_INTERNETARCHIVE_DESCRIPTION`
- Type: string
- Required: false

---

## Metadata

so these are the **metadata fields provided by Internet Archive** 💖 and reminder: if there are multiple values for a key, only **the first one** gets returned. that's a limitation of Rclone — it supports exactly one value per one key. (again: can be triggered by a server-side copy, so if something looks missing, that might be why 👀)

and here's the cute part — **the owner is able to add custom keys**, and the metadata feature grabs **all** the keys, including those custom ones. we love an inclusive queen 👑

here are all the possible system metadata items for the `internetarchive` backend ⭐

okay so before we say bye to Internet Archive, here's the metadata moment you've been waiting for 💅 — every key it hands over, what type it is, a lil example, and whether it's read-only or you can push your own vibes in there:

- **`crc32`** — CRC32 calculated by Internet Archive · type: `string` · example: `01234567` · read only: **Y**
- **`format`** — Name of format identified by Internet Archive · type: `string` · example: `Comma-Separated Values` · read only: **Y**
- **`md5`** — MD5 hash calculated by Internet Archive · type: `string` · example: `01234567012345670123456701234567` · read only: **Y**
- **`mtime`** — Time of last modification, managed by Rclone · type: `RFC 3339` · example: `2006-01-02T15:04:05.999999999Z` · read only: **Y**
- **`name`** — Full file path, without the bucket part · type: `filename` · example: `backend/internetarchive/internetarchive.go` · read only: **Y**
- **`old_version`** — Whether the file was replaced and moved by keep-old-version flag · type: `boolean` · example: `true` · read only: **Y**
- **`rclone-ia-mtime`** — Time of last modification, managed by Internet Archive · type: `RFC 3339` · example: `2006-01-02T15:04:05.999999999Z` · read only: **N**
- **`rclone-mtime`** — Time of last modification, managed by Rclone · type: `RFC 3339` · example: `2006-01-02T15:04:05.999999999Z` · read only: **N**
- **`rclone-update-track`** — Random value used by Rclone for tracking changes inside Internet Archive · type: `string` · example: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` · read only: **N**
- **`sha1`** — SHA1 hash calculated by Internet Archive · type: `string` · example: `0123456701234567012345670123456701234567` · read only: **Y**
- **`size`** — File size in bytes · type: `decimal number` · example: `123456` · read only: **Y**
- **`source`** — The source of the file · type: `string` · example: `original` · read only: **Y**
- **`summation`** — Check `https://forum.rclone.org/t/31922` for how it is used · type: `string` · example: `md5` · read only: **Y**
- **`viruscheck`** — The last time viruscheck process was run for the file (?) · type: `unixtime` · example: `1654191352` · read only: **Y**

See the metadata docs for more info — `https://rclone.org/docs/#metadata`, go read it bestie, it's giving encyclopedia but in a good way 🫶

---

## 👑 Internxt Drive

Internxt Drive (`https://internxt.com`) is a <purple>zero-knowledge encrypted</purple> cloud storage service. Zero-knowledge meaning the whole point is that nobody but you can read your stuff. Obsessed honestly. 🦋

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

### 💀 Limitations

> Note: The Internxt backend may not work with all account types. Please refer to Internxt plan details (`https://internxt.com/pricing`) or contact Internxt support (`https://help.internxt.com`) to verify rclone compatibility with your subscription.

so yeah, check your plan before you commit, fr fr. Not all subscriptions are built for this.

### 🌸 Configuration

Here's literally how you make a remote called `internxt`. Run `rclone config` and follow the prompts like the main character you are ✨

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> internxt Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Internxt Drive \ "internxt" [snip] Storage> internxt

Option email. Email of your Internxt account. Enter a value. email> user@example.com

Option pass. Password. Enter a value. password>

Edit advanced config? y) Yes n) No (default) y/n> n

Configuration complete. Options:

• type: internxt
• email: user@example.com
• pass: * ENCRYPTED * Keep this "internxt" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

If you have two-factor authentication enabled on your Internxt account, you will be prompted to enter the code during login. 🔐 Don't panic, it's just the vibes check.

### 🛡️ Security Considerations

The authentication process stores your password and mnemonic in the rclone configuration file. It is **strongly recommended** to encrypt your rclone config to protect these sensitive credentials:

rclone config password

This will prompt you to set a password that encrypts your entire configuration file. Do it. Do not skip this one, I am begging 😭🔒

### 🎀 Usage Examples

List files

rclone ls internxt:

Copy files to Internxt

rclone copy /local/path internxt:remote/path

Sync local directory to Internxt

rclone sync /local/path internxt:remote/path

Mount Internxt Drive as a local filesystem

rclone mount internxt: /path/to/mountpoint

Check storage usage

rclone about internxt:

slay, that last one is *chef's kiss* for checking how much room you've got left 💅

### ⏰ Modification times and hashes

The Internxt backend does not support hashes.

Modification times are read from the server but cannot be set. The backend reports `ModTimeNotSupported` precision, so modification times will not be used for sync comparisons.

Translation: it can *see* the times but it can't *set* them, so don't count on that for your sync logic. periodt.

### 🚫 Restricted filename characters

The Internxt backend replaces the default restricted characters set (`https://rclone.org/overview/#restricted-characters`).

---

### ⚙️ Standard options

Here are the Standard options specific to `internxt` (Internxt Drive).

- **`--internxt-email`** — Email of your Internxt account.

  Properties:

  - Config: `email`
  - Env Var: `RCLONE_INTERNXT_EMAIL`
  - Type: `string`
  - Required: `true`

- **`--internxt-pass`** — Password.

  > NB Input to this must be obscured — see `rclone obscure` (`https://rclone.org/commands/rclone_obscure/`).

  Properties:

  - Config: `pass`
  - Env Var: `RCLONE_INTERNXT_PASS`
  - Type: `string`
  - Required: `true`

### 🔥 Advanced options

Here are the Advanced options specific to `internxt` (Internxt Drive).

- **`--internxt-skip-hash-validation`** — Skip hash validation when downloading files.

  By default, hash validation is disabled. Set this to `false` to enable validation.

  Properties:

  - Config: `skip_hash_validation`
  - Env Var: `RCLONE_INTERNXT_SKIP_HASH_VALIDATION`
  - Type: `bool`
  - Default: `true`

- **`--internxt-upload-concurrency`** — Concurrency for multipart uploads.

  This is the number of chunks of the same file that are uploaded concurrently.

  Note that each chunk is buffered in memory. 🧠 so like, mind your RAM bestie.

  Properties:

  - Config: `upload_concurrency`
  - Env Var: `RCLONE_INTERNXT_UPLOAD_CONCURRENCY`
  - Type: `int`
  - Default: `4`

- **`--internxt-upload-cutoff`** — Cutoff for switching to multipart upload.

  Any files larger than this will be uploaded in chunks of `chunk_size`. The minimum is `100 MiB` and the maximum is `5 GiB`.

  Properties:

  - Config: `upload_cutoff`
  - Env Var: `RCLONE_INTERNXT_UPLOAD_CUTOFF`
  - Type: `SizeSuffix`
  - Default: `100Mi`

- **`--internxt-chunk-size`** — Chunk size for multipart uploads.

  Files larger than `upload_cutoff` will be uploaded in chunks of this size.

  Memory usage is approximately `chunk_size * upload_concurrency`.

  Properties:

  - Config: `chunk_size`
  - Env Var: `RCLONE_INTERNXT_CHUNK_SIZE`
  - Type: `SizeSuffix`
  - Default: `30Mi`

- **`--internxt-encoding`** — The encoding for the backend.

  See the encoding section in the overview (`https://rclone.org/overview/#encoding`) for more info.

  Properties:

  - Config: `encoding`
  - Env Var: `RCLONE_INTERNXT_ENCODING`
  - Type: `Encoding`
  - Default: `Slash,BackSlash,CrLf,RightPeriod,InvalidUtf8,Dot`

- **`--internxt-description`** — Description of the remote.

  Properties:

  - Config: `description`
  - Env Var: `RCLONE_INTERNXT_DESCRIPTION`
  - Type: `string`
  - Required: `false`

---

## 🌈 Jottacloud

Jottacloud is a cloud storage service provider from a Norwegian company, using its own datacenters in Norway. 🇳🇴 home turf energy, we love that.

In addition to the official service at `jottacloud.com` (`https://www.jottacloud.com/`), it also provides <pink>white-label</pink> solutions to different companies. The following are currently supported by this backend, using a different authentication setup as described below:

- Elkjøp (with subsidiaries):

  - Elkjøp Cloud (`cloud.elkjop.no`)
  - Elgiganten Cloud (`cloud.elgiganten.dk`)
  - Elgiganten Cloud (`cloud.elgiganten.se`)
  - ELKO Cloud (`cloud.elko.is`)
  - Gigantti Cloud (`cloud.gigantti.fi`)

- Telia

  - Telia Cloud (`cloud.telia.se`)
  - Telia Sky (`sky.telia.no`)

- Tele2

  - Tele2 Cloud (`mittcloud.tele2.se`)

- Onlime

  - Onlime (`onlime.dk`)

- MediaMarkt

  - MediaMarkt Cloud (`mediamarkt.jottacloud.com`)
  - Let's Go Cloud (`letsgo.jotta.cloud`)

- Phonero

  - Phonero Sky (`sky.phonero.no`)

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

### 🔐 Authentication

Authentication in Jottacloud is in general based on OAuth and OpenID Connect (OIDC). There are different variants to choose from, depending on which service you are using, e.g. a white-label service may only support one of them. Note that there is no documentation to rely on, so the descriptions provided here are based on observations and may not be accurate.

ngl we're kind of reverse-engineering the vibe here, but don't worry — we've got the details coming up next 💖

<purple>okok so before we even get into the config stuff, there's some OAuth ✨lore✨ you need, because Jottacloud does something spicy with tokens.</purple>

Jottacloud uses two optional OAuth security mechanisms, called <hotpink>"Refresh Token Rotation"</hotpink> and <hotpink>"Automatic Reuse Detection"</hotpink>, and bestie, they have <italic>implications</italic>. 😭

So normally access tokens expire after one hour, and after that they need to be refreshed (rotated) — and that operation needs the refresh token handed over. Rclone does this automatically for you, no stress. That part is just standard OAuth, very demure. 🎀

But in Jottacloud, a refresh operation doesn't just make a new access token — it makes a brand new refresh token too and **invalidates the old one you supplied**. It's keeping receipts, tracking the history of refresh tokens, aka a <rainbow>token family</rainbow>, all descending from the original refresh token issued after the first authentication. That's how it sniffs out anyone trying to reuse an old refresh token. And if it catches that reuse? Immediate invalidation of the current refresh token, and effectively the *entire* refresh token family. 💀

So once that current refresh token is invalidated, next time rclone goes to refresh, it's gonna fail with something like:

CRITICAL: Failed to create file system for "remote:": (...): couldn't fetch token: invalid_grant: maybe token expired? - try refreshing with "rclone config reconnect remote:"

And if you run rclone with verbosity level 2 (`-vv`), you'll see a debug message with an extra error description straight from the OAuth response:

DEBUG : remote: got fatal oauth error: oauth2: "invalid_grant" "Session doesn't have required client"

> fyi bestie, the error description used to say `"Stale token"` instead of `"Session doesn't have required client"`, so if you're reading some older description of this whole situation, that's what you're seeing. 🧚

When this happens you have to re-authenticate before you can use your remote again, like with the `config reconnect` command (it's over at https://rclone.org/commands/rclone_config_reconnect/) — which is literally what the error message suggests. Do that and you get an entirely new refresh token (family). slay. ✨

<pink>how do you even end up here though?</pink> Classic scenario: you make a Jottacloud remote with rclone in one place, then copy the config file to a second place, and start using rclone there for the same remote. Eventually one of them does a token refresh with an invalidated token — i.e. refresh token reuse — and boom, both instances start failing with the `invalid_grant` error. You <bold>can</bold> copy remote configurations, but you must then replace the token for one of them using the `config reconnect` command (https://rclone.org/commands/rclone_config_reconnect/).

You can also get a peek at your active tokens in your service's web UI: go to "Settings", then "Security" (which lands you at https://www.jottacloud.com/web/secure or similar). Down on that page there's a section called "My logged in devices". It's a list of entries that seems to represent your currently valid refresh tokens, or refresh token families. On the right side of that list there's a button ("X") you can click to revoke (invalidate) one — which means you still have access using an existing access token until it expires, but you won't be able to do a token refresh. ngl, that whole "My logged in devices" feature seems to behave a little differently with different authentication variants and across the different (white-label) services. 🫶

---

### ✨ Standard ✨

This is an OAuth variant built for command-line apps. It's primarily supported by the official service (<cyan>jottacloud.com</cyan>), but some of the white-label services might support it too. 💅

Here's the cute part: the info you need to authenticate — domain name, endpoint to connect to, all of it — gets found automatically, because it's encoded right into the login token you supply (coming up next). So you don't have to specify which service you're configuring at all. 👑

When you configure a remote, you're asked for a <hotpink>single-use personal login token</hotpink>, which you have to manually generate from the account security settings in the service's web interface. You don't need a web browser on the same machine like with traditional OAuth — but you do need a web browser *somewhere*, and you need to be able to copy the generated string into your rclone config session. 🎀

So: log into your service's web UI, navigate to "Settings" and then "Security" — or, for the official service, just use the direct link rclone shows you while configuring the remote: https://www.jottacloud.com/web/secure. Scroll down to the "Personal login token" section and hit the "Generate" button. Copy the string it shows you and paste it wherever rclone asks for it. Rclone then uses that to do an initial token request and receives a regular OAuth token, which it stores in your remote config. You'll also get a new entry in the "My logged in devices" list in the web interface, with device name and application name `"Jottacloud CLI"`. ⭐

Every time a new token gets created this way — i.e. a new personal login token is generated and traded in for an OAuth token — you get a completely new refresh token family, with a new entry in "My logged in devices". You can make as many remotes as you want and run multiple rclone instances on the same or different machines, as long as you configure them separately like this, and don't get yourself tangled up in the refresh token reuse issue from earlier. periodt. 💜

### ✨ Traditional ✨

Jottacloud also supports a more traditional OAuth variant. Most of the white-label services support this, and for many of them it's the *only* option, because they don't do personal login tokens. This method relies on pre-defined service-specific domain names and endpoints, so rclone needs you to say which service you're configuring. Which also means: any change to an existing white-label service, or adding a new one, needs an update in the rclone backend implementation. 🙈

When you configure a remote, you have to interactively log in to an OAuth authorization web site, and a one-time authorization code gets sent back to rclone behind the scenes, which it uses to request an OAuth token. So you need to be on a machine with an internet-connected web browser. If you need it on a machine where that's not the case, you'll have to create the config on a different machine and copy it over from there. Also — heads up — the Jottacloud backend does <bold>not</bold> support the rclone `authorize` command. See the remote setup docs for the details. 🌸

Jottacloud does some form of strict session management when you authenticate this way, which leads to some unexpected cases of that `invalid_grant` error we talked about, and effectively limits you to only using a single active authentication on the same machine. Like: you can only create a single rclone remote, and you can't even log in with the service's official desktop client while you have an rclone remote configured — otherwise you'll eventually get all sessions invalidated and be forced to re-authenticate. 😭

Once you've successfully authenticated, there'll be an entry in the "My logged in devices" list in the web interface representing your session, typically listed with application name `"Jottacloud for Desktop"` or similar (it depends on the white-label service configuration).

### ✨ Legacy ✨

Originally Jottacloud used an OAuth variant that required your account's username and password to be specified. When Jottacloud migrated to the newer methods, some white-label versions (the ones from Elkjøp) kept using this legacy method for a long time. Currently there are no known uses of this, and it's still supported by rclone, but <red>the support will be removed in a future version.</red> 💀

### ✨ 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

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 / Jottacloud \ (jottacloud) [snip] Storage> jottacloud

Option client_id. OAuth Client Id. Leave blank normally. Enter a value. Press Enter to leave empty. client_id>

Option client_secret. OAuth Client Secret. Leave blank normally. Enter a value. Press Enter to leave empty. client_secret>

Edit advanced config? y) Yes n) No (default) y/n> n

Option config_type. Type of authentication. Choose a number from below, or type in an existing value of type string. Press Enter for the default (standard). / Standard authentication.

1 | applications, and you will be asked to enter a single-use personal login

\ (standard) / Traditional authentication.

2 | It has a limitation of only a single active authentication at a time. You

\ (traditional) / Legacy authentication. 3 | This is no longer supported by any known services and not recommended

\ (legacy) config_type> 1

Option config_login_token. Personal login token. Generate it from the account security settings in the web interface of your service, for the official service on https://www.jottacloud.com/web/secure. Enter a value. config_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> n

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 that's locked in, you can run rclone like this (and yeah, swap `remote` for whatever name you blessed your remote with, bestie 💅):

List the top-level directories in your Jottacloud:

rclone lsd remote:

List every single file in your Jottacloud:

rclone ls remote:

Copy a local directory into a Jottacloud directory called `backup`:

rclone copy /home/source remote:backup

---

### Devices and Mountpoints

Okay so here's the lore 📖 — the official Jottacloud client registers a <pink>device</pink> for every computer you install it on, and it shows them all off in the backup section of the UI. For each folder you pick for backup, it makes a <pink>mountpoint</pink> inside that device. And there's one built-in device called `Jotta` that's special — it holds the mountpoints `Archive`, `Sync` and a few others, which power the matching features in the official clients.

With rclone, you'll usually want the standard `Jotta/Archive` device/mountpoint combo. <cyan>But</cyan> — say you want to reach files from the sync or backup stuff the official clients do — rclone lets you pick other devices and mountpoints during config. Options, bestie ✨

You're allowed to create new devices and mountpoints. Every device <italic>except</italic> the built-in `Jotta` device gets treated as a backup device by the official Jottacloud clients, and the mountpoints living on them are individual backup sets.

With the built-in `Jotta` device though? Only existing, built-in mountpoints can be selected. Besides the `Archive` and `Sync` we mentioned, it might also hold a bunch of others like: `Latest`, `Links`, `Shared` and `Trash`. All of those are <hotpink>special</hotpink> mountpoints with a different internal representation than the "regular" ones. Rclone only supports them to a <red>very limited degree</red>. Generally you should avoid these unless you genuinely know what you're doing 👀.

---

### `--fast-list`

This backend supports `--fast-list`, which lets you use fewer transactions in exchange for using more memory. Peep the rclone docs (https://rclone.org/docs/#fast-list) for the details.

Heads up though: the implementation in Jottacloud <yellow>always</yellow> uses just a single API request to grab the whole entire list, so on big folders that could mean a long, awkward wait before the first results even show up 😭.

Also note: with rclone version 1.58 and newer, info about MIME types (https://rclone.org/overview/#mime-type) and the metadata item `utime` are <red>not available</red> when you're using `--fast-list`.

---

### Modification times and hashes

Jottacloud lets modification times be set on objects accurate to <green>1 second</green>. These get used to figure out whether objects need syncing or not.

Jottacloud supports <mint>MD5</mint> type hashes, so yes you can use the `--checksum` flag, queen 👑.

Now the tea ☕ — Jottacloud requires the MD5 hash <italic>before</italic> upload, so if the source doesn't have an MD5 checksum, the file gets cached temporarily on disk (in the location given by `--temp-dir` (https://rclone.org/docs/#temp-dir-string)) before it goes up. Small files get cached in memory instead — see the `--jottacloud-md5-memory-limit` flag. When you're uploading from local disk the source checksum is <green>always</green> available, so this whole thing doesn't apply. And starting with rclone version 1.52, the same is true for encrypted remotes (in older versions the crypt backend wouldn't calculate hashes for uploads from local disk, so the Jottacloud backend had to do it the way described above).

---

### Restricted filename characters

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these characters also get replaced:

- `"` — 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 `0x7C` → replaced with `｜`
- `%` — value `0x25` → replaced with `％`

Invalid UTF-8 bytes will also get replaced (https://rclone.org/overview/#invalid-utf8), because bestie, they literally cannot be used in XML strings 💀.

---

### Deleting files

By default, rclone sends <italic>all</italic> the files to the trash when it deletes stuff. They get permanently deleted automatically after <yellow>30 days</yellow>. Wanna skip the trash and nuke files immediately? Use the `--jottacloud-hard-delete` flag, or set the matching environment variable. Emptying the trash is supported by the `cleanup` command (https://rclone.org/commands/rclone_cleanup/).

---

### 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 <mint>current</mint> version — older ones can be accessed via the Jottacloud Website.

Versioning can be turned off with the `--jottacloud-no-versions` option. It does this by deleting the remote file <italic>before</italic> uploading a new version. And if the upload then fails? <red>No version of the file will be available in the remote.</red> So like, be careful with that one 🙈.

---

### Quota information

To see your current quota, use the `rclone about remote:` command — it'll show your usage limit (unless it's unlimited) plus your current usage. Slay ✨

---

### 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.

> Note that this option is <red>NOT</red> supported by all backends.

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 (https://rclone.org/overview/#encoding) for more info.

Properties:

- **Config:** `encoding`
- **Env Var:** `RCLONE_JOTTACLOUD_ENCODING`
- **Type:** Encoding
- **Default:** `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Percent,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 <yellow>limited</yellow> support for metadata — currently it's an extended set of timestamps.

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 (https://rclone.org/docs/#metadata) docs for more info.

---

### Limitations

Okay so important: Jottacloud is <hotpink>case insensitive</hotpink>, so you literally cannot have one file called `"Hello.doc"` and another called `"hello.doc"` at the same time. Pick a lane, bestie 💅

Okay so heads up bestie, Jottacloud is <pink>kinda picky</pink> about what you can name your files 😭 There are <yellow>quite a few characters</yellow> that straight up can't live in Jottacloud file names. <italic>Not even one.</italic>

But don't spiral! Rclone is gonna map those names to and from an <rainbow>identical looking unicode equivalent</rainbow> for you 🪄 Like, say a file has a `?` chillin' in it — rclone maps it to `？` instead. Same vibe, different character, no cap.

> 🚨 Also putting this here so you don't get caught lacking: Jottacloud only supports filenames up to **`255` characters** in length. That's the ceiling, bestie. The <red>limit</red>. The hard stop. 💀

---

## 🛠️ Troubleshooting ✨

ngl, Jottacloud has some <peach>inconsistent behaviours</peach> when it comes to deleted files and folders 🙈 and that can make your `Copy`, `Move` and `DirMove` operations to previously deleted paths just… <red>fail</red>. It's giving messy. It's giving haunted. 👻

The fix? <green>Emptying the trash</green> should help in such cases 🫶 Like, clear it out, girl, and try again. Spring cleaning era. 🧹✨

# 👑 Koofr 👑

<rainbow>okay bestie</rainbow> so Koofr is one of those backends that actually plays nice with a few providers at once, and we're gonna walk through every single bit of it, no skipping, periodt 💅

Paths get written as `remote:path`

And yes, they can go as deep as you want, like `remote:directory/subdirectory`.

## ✨ Configuration ✨

So the first thing you gotta do, bestie, is make an **application password** for rclone. Open up the Koofr web app at `https://app.koofr.net/app/admin/preferences/password`, give the password a cute lil name like `rclone`, and hit generate. Iconic behavior honestly.

Here's a whole example of making a remote called `koofr`. First you run:

rclone config

and it walks you through the whole interactive setup, like this:

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 the advanced config if you wanna drop in your own service URL — like if you're running an on-premise or white label Koofr instance 🏠 — or pick an alternative mount instead of your primary storage.

Once it's all configured, you use rclone like this:

List the directories at the top level of your Koofr:

rclone lsd koofr:

List ALL the files in your Koofr:

rclone ls koofr:

And to copy a local directory to a Koofr directory called `backup`:

rclone copy /home/source koofr:backup

## 🚫 Restricted filename characters 🚫

On top of the default restricted characters set (`https://rclone.org/overview/#restricted-characters`), these characters also get swapped out:

- `\` — value `0x5C` — replacement `＼`

Invalid UTF-8 bytes get replaced too (`https://rclone.org/overview/#invalid-utf8`), because bestie, they literally cannot be used in XML strings. No cap.

---

## ⭐ Standard options ⭐

Here's the Standard options that are specific to koofr (Koofr, Digi Storage and other Koofr-compatible storage providers). Obsessed with how tidy this is.

### `--koofr-provider`

Choose your storage provider.

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.

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: The input to this one **must** be obscured — see `rclone obscure` (`https://rclone.org/commands/rclone_obscure/`). Don't skip this, bestie, it's not a vibe to paste your plaintext password in. 🙈

Properties:

- **Config:** `password`
- **Env Var:** `RCLONE_KOOFR_PASSWORD`
- **Provider:** `koofr`
- **Type:** string
- **Required:** true

---

## 💖 Advanced options 💖

And here are the Advanced options specific to koofr (Koofr, Digi Storage and other Koofr-compatible storage providers). Very much the "iykyk" tier of settings.

### `--koofr-mountid`

Mount ID of the mount to use.

If you leave it out, the primary mount gets 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're using a mount ID that points to a Dropbox or Amazon Drive backend. 🫶

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 (`https://rclone.org/overview/#encoding`) 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 😭

Real talk: Koofr is **case insensitive**, so you literally cannot have one file called `"Hello.doc"` and another one called `"hello.doc"`. Pick a lane, babe.

---

# 🌈 Providers 🌈

## Koofr

This is the original Koofr (`https://koofr.eu`) storage provider — the main example, the one we literally just described in the configuration section above. Main character energy tbh.

## Digi Storage

Digi Storage (`https://www.digi.ro/servicii/online/digi-storage`) is a cloud storage service run by Digi.ro (`https://www.digi.ro/`) that provides a Koofr API. Slay.

Here's an example of how to make a remote called `ds`. First run:

rclone config

and it'll guide you through the 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> 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 might also wanna hook up some other public or private storage provider that runs a Koofr API compatible service — you just gotta provide the base URL to connect to. That's it, that's the whole vibe. ✨

Here's an example of how to make a remote called `other`. First run:

rclone config

and it'll guide 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> 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 saga bestie, more coming, don't go anywhere 💜

## <pink>Linkbox</p> 🎀

Linkbox is a private cloud drive, and you can find it at https://linkbox.to/. It's giving "your own lil corner of the internet" energy. 💖

### <purple>Configuration</purple>

Okay bestie, here's literally how you make a remote for Linkbox:

You're gonna need:
- An API token from https://www.linkbox.to/admin/account
- The email and password for your Linkbox account

> **Note:** As of v1.74, email and password are required in addition to the API token. The API token is used for uploads and modifications, while email/password authentication is used for listing and downloading files. If you have an existing Linkbox remote, you will need to reconfigure it with `rclone config` to edit the remote and add the email and password. 👀

First run this:

rclone config

It'll hold your hand through the whole interactive setup, 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> YOUR_API_TOKEN

Option email. Email for login Enter a value. email> your@email.com

Option password. Password for login Enter a value. password> YOUR_PASSWORD

Configuration complete. Options:

• type: linkbox
• token: XXXXXXXXXXX
• email: your@email.com
• password: * ENCRYPTED * Keep this "linkbox" remote? y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

### <cyan>Standard options</cyan>

Here are the Standard options specific to linkbox (Linkbox). 💅

### --linkbox-token

Token from https://www.linkbox.to/admin/account

Properties:

- Config: token
- Env Var: `RCLONE_LINKBOX_TOKEN`
- Type: string
- Required: true

### --linkbox-email

Email for login

Properties:

- Config: email
- Env Var: `RCLONE_LINKBOX_EMAIL`
- Type: string
- Required: true

### --linkbox-password

Password for login

> **NB** Input to this must be obscured — see rclone obscure (https://rclone.org/commands/rclone_obscure/). 🔐

Properties:

- Config: password
- Env Var: `RCLONE_LINKBOX_PASSWORD`
- Type: string
- Required: true

### <mint>Advanced options</mint>

Here are the Advanced options specific to linkbox (Linkbox).

### --linkbox-description

Description of the remote.

Properties:

- Config: description
- Env Var: `RCLONE_LINKBOX_DESCRIPTION`
- Type: string
- Required: false

### <yellow>Limitations</yellow>

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings. No cap. 😭

---

## <hotpink>Mail.ru Cloud</hotpink> 🦋

Mail.ru Cloud (https://cloud.mail.ru/) is a cloud storage provided by a Russian internet company, Mail.Ru Group (https://mail.ru). The official desktop client is Disk-O: (https://disk-o.cloud/en), and it's available on Windows and Mac OS. ✨

### <purple>Features highlights</purple>

- 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, the hash algorithm is a modified SHA1
- If a particular file is already present in storage, one can quickly submit file hash instead of long file upload (this optimization is supported by rclone)

### <cyan>Configuration</cyan>

Here's an example of making a mailru configuration. 📝

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 not 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"
- Select the permissions level. For some reason just "Full access to Cloud" (WebDav) doesn't work for Rclone currently. You have to select "Full access to Mail, Cloud and Calendar" (all protocols). (thread on forum.rclone.org (https://forum.rclone.org/t/failed-to-create-file-system-for-mailru-failed-to-authorize-oauth2-invalid-username-or-password-username-or-password-is-incorrect/49298))
- 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

### <mint>Modification times and hashes</mint>

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". 💀

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 is computed as a SHA1 of the file data bytes concatenated with a decimal representation of the data length. 🔥

### <yellow>Emptying Trash</yellow>

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 still occupies part of total quota. 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. ⚠️

### <peach>Quota information</peach>

To view your current quota you can use the `rclone about remote:` command which will display your usage limit (quota) and the current usage.

### <lavender>Restricted filename characters</lavender>

In addition to the default restricted characters set (https://rclone.org/overview/#restricted-characters) the following characters are also replaced:

- `"` — Value 0x22 — Replacement ＂
- `*` — Value 0x2A — Replacement ＊
- `:` — Value 0x3A — Replacement ：
- `<` — Value 0x3C — Replacement ＜
- `>` — Value 0x3E — Replacement ＞
- `?` — Value 0x3F — Replacement ？
- `\` — Value 0x5C — Replacement ＼
- `|` — Value 0x7C — Replacement ｜

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings. 😭

### <cyan>Standard options</cyan>

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 (https://rclone.org/commands/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 <green>especially</green> efficient in case of generally available files like popular books, video or audio clips, because files are searched by hash in <pink>all accounts of all mailru users</pink>. 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 <red>not even try</red> 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). bestie these are the deep-cuts, the iykyk settings 💅

---

### `--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.

Note that this option is **NOT supported by all backends.** ⚠️

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:

- 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).
  - `"*"`
    - All files will be attempted for speedup.
  - `.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`

This option allows you to disable speedup (put by hash) for large files.

Reason is that preliminary hashing can exhaust your RAM or disk space. 💀 like bestie it will EAT your resources

Properties:

- Config: `speedup_max_disk`
- Env Var: `RCLONE_MAILRU_SPEEDUP_MAX_DISK`
- Type: SizeSuffix
- Default: `3Gi`
- Examples:
  - `"0"`
    - Completely disable speedup (put by hash).
  - `"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 larger than the size given below will always be hashed on disk.

Properties:

- 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 file checksum is mismatched or invalid. 😳

Properties:

- Config: `check_hash`
- Env Var: `RCLONE_MAILRU_CHECK_HASH`
- Type: bool
- Default: `true`
- Examples:
  - `"true"`
    - Fail with error.
  - `"false"`
    - Ignore and continue.

---

### `--mailru-encoding`

The encoding for the backend.

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

- 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. 🌸

Properties:

- Config: `description`
- Env Var: `RCLONE_MAILRU_DESCRIPTION`
- Type: string
- Required: false

---

## 🦋 Limitations 🦋

File size limits depend on your account. 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.

> Note that Mailru is <hotpink>case insensitive</hotpink> so you can't have a file called `"Hello.doc"` and one called `"hello.doc"`. 💀 pick a lane bestie, the server will fr fr just see them as the same thing

# 🦋 Mega 🦋

Okay bestie, listen. <pink>Mega</pink> (`https://mega.nz/`) is a cloud storage and file hosting service that's <italic>famous</italic> for its security vibe — like, literally all your files get encrypted <rainbow>locally</rainbow> before they ever get uploaded. Which means nobody (and I mean <bold>nobody</bold>, not even the Mega employees themselves) can peek at your files without knowing the key used for that encryption. Iconic behavior honestly. 🔐✨

This here is the rclone backend for Mega, and it supports all the file transfer features of Mega using that exact same client side encryption. Chef's kiss. 👑

> Heads up queen: <bold>MEGA S4 Object Storage</bold>, which is an S3 compatible object store, also works with rclone — and that's the one recommended for new projects. Just so you know. 💅

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

---

## 🌸 Configuration 🌸

Here's a lil example of how to make a remote called `remote`. First run:

rclone config

This will guide you through an 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 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

> <hotpink>NOTE:</hotpink> the encryption keys need to have been already generated after a regular login via the browser, otherwise attempting to use the credentials in rclone will <bold>fail</bold>. So go log in on the website first, bestie. 💀

Once configured you can then use rclone like this (replace `remote` with the name you gave your remote, duh):

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 🔤

- `NUL` — `0x00` — replaced with `␀`
- `/` — `0x2F` — replaced with `／`

Invalid UTF-8 bytes will also be replaced (see `https://rclone.org/overview/#invalid-utf8`), because they literally can't be used in JSON strings. Not our fault, take it up with JSON. 💅

---

## 👯 Duplicated files 👯

Mega can have two files with <italic>exactly</italic> the same name and path — unlike a normal file system, which could never. 🙈

Duplicated files cause problems with the syncing and you will see messages in the log about duplicates.

Use `rclone dedupe` to fix duplicated files. Slay and clean up your mess. ✨

---

## 😵 Failure to log-in 😵

### 🔍 Object not found 🔍

If you are connecting to your Mega remote for the first time, 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 (`https://forum.rclone.org/search?q=mega`) 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. Don't mix them up bestie, they are not the same girl. 💀

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. Like, sometimes the drama is the punctuation. 😭

### 🚫 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.

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. Lowkey still under investigation fr fr. 🔬

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. Be the main character who cracks the case. 🕵️‍♀️

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 not you, it's the block. 💅

---

## ✨ Standard options ✨

Here are the Standard options specific to mega (Mega).

- **`--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` (`https://rclone.org/commands/rclone_obscure/`).

  Properties:

  - Config: `pass`
  - Env Var: `RCLONE_MEGA_PASS`
  - Type: `string`
  - Required: `true`

- **`--mega-2fa`** — The 2FA code of your MEGA account if the account is set up with one

  Properties:

  - Config: `2fa`
  - Env Var: `RCLONE_MEGA_2FA`
  - Type: `string`
  - Required: `false`

---

## 🔥 Advanced options 🔥

Here are the Advanced options specific to mega (Mega).

- **`--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. ⚠️ Like, gone gone. No undo button. Be careful bestie.

  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 (`https://rclone.org/overview/#encoding`) 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 (`https://forum.rclone.org/t/rclone-with-mega-appears-to-work-only-in-some-accounts/40233/4`). Not your fave moment, we know. 😭

---

## 🌈 Limitations 🌈

This backend uses the `go-mega` go library (`https://github.com/t3rm1n4l/go-mega`) 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 (`https://github.com/meganz/sdk`) source code so there are likely quite a few errors still remaining in this library. It's giving ✨ adventure ✨ honestly.

Mega allows duplicate files which may confuse rclone. 🙈

# 💾 Memory

okay so bestie, the memory backend is literally just an in-RAM situation. It does **not** persist its data — like, at all, it forgets everything the second you look away 🙈 — so if you want your files to actually survive, use the local backend for that instead.

The memory backend behaves like a bucket-based remote (think s3 energy 🪣, same shape). Because it has <pink>no parameters</pink> you can just use it with the `:memory:` remote name. iconic behavior, 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`. yes, nano-freaking-seconds. precise queen 💅

---

## 🚫 Restricted filename characters

The memory backend replaces the default restricted characters set (https://rclone.org/overview/#restricted-characters).

---

## 🔧 Advanced options

Here are the Advanced options specific to memory (In memory object storage system.).

### `--memory-discard`

If set all writes will be discarded and reads will return an error

If set then when files are uploaded the contents not be saved. The files will appear to have been uploaded but will give an error on read. Files will have their MD5 sum calculated on upload which takes very little CPU time and allows the transfers to be checked.

This can be useful for testing performance.

Probably most easily used by using the connection string syntax:

:memory,discard:bucket

Properties:

- Config: `discard`
- Env Var: `RCLONE_MEMORY_DISCARD`
- Type: `bool`
- Default: `false`

### `--memory-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_MEMORY_DESCRIPTION`
- Type: `string`
- Required: `false`

---

# 🌐 Akamai NetStorage

Paths are specified as `remote:` You may put subdirectories in too, e.g. `remote:/path/to/dir`. If you have a CP code you can use that as the folder after the domain such as `<domain>/<cpcode>/<internal directories within cpcode>`.

For example, this is commonly configured with or without a CP code:

- With a CP code. `[your-domain-prefix]-nsu.akamaihd.net/123456/subdirectory/`
- Without a CP code. `[your-domain-prefix]-nsu.akamaihd.net`

### 👀 See all buckets

rclone lsd remote:

The initial setup for Netstorage involves getting an account and secret. Use `rclone config` to walk you through the setup process.

---

## ⚙️ Configuration

Here's an example of how to make a remote called `ns1`.

1. To begin the interactive configuration process, enter this command:

rclone config

2. Type `n` to create a new remote.

n) New remote d) Delete remote q) Quit config e/n/d/q> n

3. For this example, enter `ns1` when you reach the `name>` prompt.

name> ns1

4. Enter `netstorage` as the 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 XX / NetStorage \ "netstorage" Storage> netstorage

5. Select between the HTTP or HTTPS protocol. Most users should choose HTTPS, which is the default. HTTP is provided primarily for debugging purposes.

Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value 1 / HTTP protocol \ "http" 2 / HTTPS protocol \ "https" protocol> 1

6. Specify your NetStorage host, CP code, and any necessary content paths using this format: `<domain>/<cpcode>/<content>/`

Enter a string value. Press Enter for the default (""). host> baseball-nsu.akamaihd.net/123456/content/

7. Set the netstorage account name

Enter a string value. Press Enter for the default (""). account> username

8. Set the Netstorage account secret/G2O key which will be used for authentication purposes. Select the `y` option to set your own password then enter your secret. Note: The secret is stored in the `rclone.conf` file with hex-encoded encryption.

y) Yes type in my own password g) Generate random password y/g> y Enter the password: password: Confirm the password: password:

9. View the summary and confirm your remote configuration.

[ns1] type = netstorage protocol = http host = baseball-nsu.akamaihd.net/123456/content/ account = username secret = * ENCRYPTED *

---

y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y

This remote is called `ns1` and can now be used. slay 🎀

---

## ✨ Example operations

Get started with `rclone` and NetStorage with these examples. For additional `rclone` commands, visit <https://rclone.org/commands/>.

### 📂 See contents of a directory in your project

rclone lsd ns1:/974012/testing/

### 🔁 Sync the contents local with remote

rclone sync . ns1:/974012/testing/

### ⬆️ Upload local content to remote

rclone copy notes.txt ns1:/974012/testing/

### 🗑️ Delete content on remote

rclone delete ns1:/974012/testing/notes.txt

### 🚚 Move or copy content between CP codes

Your credentials must have access to two CP codes on the same remote. You can't perform operations between different remotes.

rclone move ns1:/974012/testing/notes.txt ns1:/974450/testing2/

---

## 🌟 Features

### 🔗 Symlink Support

The Netstorage backend changes the rclone `--links`, `-l` behavior. When uploading, instead of creating the `.rclonelink` file, use the "symlink" API in order to create the corresponding symlink on the remote. The `.rclonelink` file will not be created, the upload will be intercepted and only the symlink file that matches the source file name with no suffix will be created on the remote.

This will effectively allow commands like `copy/copyto`, `move/moveto` and `sync` to upload from local to remote and download from remote to local directories with symlinks. Due to internal rclone limitations, it is not possible to upload an individual symlink file to any remote backend. You can always use the "backend symlink" command to create a symlink on the NetStorage server, refer to "symlink" section below.

Individual symlink files on the remote can be used with the commands like "cat" to print the destination name, or "delete" to delete symlink, or `copy`, `copy/to` and `move/moveto` to download from the remote to local. Note: individual symlink files on the remote should be specified including the suffix `.rclonelink`.

> Note: No file with the suffix `.rclonelink` should ever exist on the server since it is not possible to actually upload/create a file with `.rclonelink` suffix with rclone, it can only exist if it is manually created through a non-rclone method on the remote. 😭

### 📁 Implicit vs. Explicit Directories

With NetStorage, directories can exist in one of two forms:

1. **Explicit Directory**. This is an actual, physical directory that you have created in a storage group.

2. **Implicit Directory**. This refers to a directory within a path that has not been physically created. For example, during upload of a file, nonexistent subdirectories can be specified in the target path. NetStorage creates these as "implicit." While the directories aren't physically created, they exist implicitly and the noted path is connected with the uploaded file.

Rclone will intercept all file uploads and `mkdir` commands for the NetStorage remote and will explicitly issue the `mkdir` command for each directory in the uploading path. This will help with the interoperability with the other Akamai services such as SFTP and the Content Management Shell (CMShell). Rclone will not guarantee correctness of operations with implicit directories which might have been created as a result of using an upload API directly.

### ⚡ `--fast-list` / ListR support

NetStorage remote supports the ListR feature by using the "list" 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 such as `lsf -R` will use ListR by default. To disable this, include the `--disable listR` option to use the non-recursive method of listing objects.

- Rclone will not use the ListR method for some commands. Commands such as `sync` don't use ListR by default. To force using the ListR method, include the `--fast-list` option.

There are pros and cons of using the ListR method, refer to rclone documentation (https://rclone.org/docs/#fast-list). In general, the `sync` command over an existing deep tree on the remote will run faster with the "--fast-list" flag but with extra memory usage as a side effect. It might also result in higher CPU utilization but the whole task can be completed faster.

> Note: There is a known limitation that "lsf -R" will display number of files in the directory and directory size as `-1` when ListR method is used. The workaround is to pass "--disable listR" flag if these numbers are important in the output. 💀

### 🧹 Purge

NetStorage remote supports the `purge` feature by using the "quick-delete" NetStorage API action. The quick-delete action is disabled by default for security reasons and can be enabled for the account through the Akamai portal. Rclone will first try to use quick-delete action for the purge command and if this functionality is disabled then will fall back to a standard delete method.

> 📌 bestie heads up: go read the **NetStorage Usage API** (https://learn.akamai.com/en-us/webhelp/netstorage/netstorage-http-api-developer-guide/GUID-15836617-9F50-405A-833C-EA2556756A30.html) for the deets on using `"quick-delete"`. In general? using `quick-delete` will **not** delete the tree immediately, and objects targeted for quick-delete may still be accessible. So like… don't assume it's gone-gone 💀

---

### ✨ Standard options

Here are the Standard options specific to netstorage (Akamai NetStorage). ✨

#### `--netstorage-host`

Domain+path of NetStorage host to connect to.

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` (https://rclone.org/commands/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 (https://rclone.org/commands/rclone_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 (https://rclone.org/rc/#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.

Usage example:

rclone backend symlink <src> <path>

---

## ☁️ Microsoft Azure Blob Storage

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`. 💙

### ✨ Configuration

Here is an example of making a Microsoft Azure Blob Storage configuration. For 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 / 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

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 `/home/local/directory` to the remote container, deleting any excess files in the container.

rclone sync --interactive /home/local/directory remote:container

### ✨ `--fast-list`

This remote supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs (https://rclone.org/docs/#fast-list) for more details. 💅

### ✨ Modification times and hashes

The modification time is stored as metadata on the object with the `mtime` key. It is stored using RFC3339 Format time with nanosecond precision. The metadata is supplied during directory listings so there is no performance overhead to using it. ⏱️

If you wish to use the Azure standard `LastModified` time stored on the object as the modified time, then use the `--use-server-modtime` flag. Note that rclone can't set `LastModified`, so using the `--update` flag when syncing is recommended if using `--use-server-modtime`.

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.

### ✨ Metadata and tags

Rclone can map arbitrary metadata to Azure Blob headers, user metadata, and tags when `--metadata` is enabled (or when using `--metadata-set` / `--metadata-mapper`). 🏷️

- **Headers**: Set these keys in metadata to map to the corresponding blob headers:
  - `cache-control`, `content-disposition`, `content-encoding`, `content-language`, `content-type`.
- **User metadata**: Any other non-reserved keys are written as user metadata (keys are normalized to lowercase). Keys starting with `x-ms-` are reserved and are not stored as user metadata.
- **Tags**: Provide `x-ms-tags` as a comma-separated list of `key=value` pairs, e.g. `x-ms-tags=env=dev,team=sync`. These are applied as blob tags on upload and on server-side copies. Whitespace around keys/values is ignored.
- **Modtime override**: Provide `mtime` in RFC3339/RFC3339Nano format to override the stored modtime persisted in user metadata. If `mtime` cannot be parsed, rclone logs a debug message and ignores the override.

Notes: - Rclone ignores reserved `x-ms-*` keys (except `x-ms-tags`) for user metadata.

### ✨ Performance

When uploading large files, increasing the value of `--azureblob-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 (https://rclone.org/overview/#restricted-characters) the following characters are also replaced:

- `/` — value `0x2F` — replacement `／`
- `\` — 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:

- `.` — value `0x2E` — replacement `．`

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings. 😭

### ✨ Authentication

There are a number of ways of supplying credentials for Azure Blob Storage. Rclone tries them in the order of the sections below. 🔑

### ✨ 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 💫

okay so when you're using Managed Service Identity, here's the whole vibe: if the VM(SS) that this program is running on has a system-assigned identity, that one gets used by default. and if the resource has **no** system-assigned identity but <hotpink>exactly one</hotpink> user-assigned identity, then that user-assigned identity gets used by default too. easy peasy. 🫶

but bestie, if the resource has *multiple* user-assigned identities, you're gonna need to unset `env_auth` and set `use_msi` instead. go peek at the `use_msi` section, it's all there. 👑

and if you're operating in disconnected clouds, or private clouds like Azure Stack, you may want to set `disable_instance_discovery = true`. what does that do, you ask? it controls whether rclone requests Microsoft Entra instance metadata from `https://login.microsoft.com/` **before** authenticating. setting it to true skips that request entirely — which means <red>you</red> are responsible for making sure the configured authority is valid and trustworthy. no pressure or anything. 💅

---

### 🛂 Env Auth: 3. Azure CLI credentials (as used by the `az` tool)

Credentials that were created with the `az` tool can be picked up using `env_auth`. obsessed with the convenience honestly.

like, say 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 :azureblob,env_auth,account=ACCOUNT:CONTAINER

or, alternate route:

rclone lsf --azureblob-env-auth --azureblob-account=ACCOUNT :azureblob:CONTAINER

which is completely analogous to using the `az` tool like:

az storage blob list --container-name CONTAINER --account-name ACCOUNT --auth-mode login

### 🔑 Account and Shared Key

This one is the most straight forward and the least flexible way. literally just fill in the `account` and `key` lines and leave the rest blank. that's the whole recipe, no notes. ✨

### 🎟️ 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`.

you can get an account level SAS URL or a container level SAS URL from the Azure portal or the Azure Storage Explorer. and for a *container level* SAS URL specifically, right click on a container in the Azure Blob explorer in the Azure portal. yes, right click. that's the move. 🖱️

if you use a container level SAS URL, rclone operations are only permitted on that one particular container, e.g.

rclone ls azureblob:container

you can also list that single container from the root. this will only show the container specified by the SAS URL.

$ rclone lsd azureblob: container/

and note that you <red>can't</red> see or access any other containers — this will fail:

rclone ls azureblob:othercontainer

container level SAS URLs are useful for temporarily letting third parties access a single container, or for putting credentials into an untrusted environment like a CI build server. so iconic for that use case honestly. 🔥

### 🕵️ 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. cute, flexible, love that for you. 🎀

### 📜 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` (https://rclone.org/commands/rclone_obscure/). don't skip that part bestie, it matters.

### 🧍 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 also **not interactive**, so it isn't compatible with any form of multi-factor authentication, and the application must already have user or admin consent. on top of all that, this credential can only authenticate work and school accounts — it can't authenticate Microsoft accounts. so like... know what you're getting into. 💀

> NB `password` must be obscured — see `rclone obscure` (https://rclone.org/commands/rclone_obscure/).

### 🪪 Managed Service Identity Credentials

if `use_msi` is set then managed service identity credentials are used. this authentication <hotpink>only</hotpink> 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 **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 equivalent to using `env_auth`.

### 🤝 Federated Identity Credentials

if these variables are set, rclone will authenticate with federated identity.

- `tenant`: tenant ID of the storage
- `client_id`: client ID of the application the user will authenticate to storage
- `msi_client_id`: managed identity client ID of the application the user will authenticate to

by default `"api://AzureADTokenExchange"` is used as the scope for token retrieval over MSI. this token is then exchanged for the actual storage token using `'tenant'` and `'client_id'`. that's the whole handshake, slay. ⭐

### 🖥️ Azure CLI tool az

if `use_az` is set, use the Azure CLI tool `az` (https://learn.microsoft.com/en-us/cli/azure/) 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. pick a lane bestie. 🙈

### 👻 Anonymous

if you want to access resources with public anonymous access then set `account` only. and you can do this without even making an rclone config:

rclone lsf :azureblob,account=ACCOUNT:CONTAINER

---

### 🌟 Standard options

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 the 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-connection-string`

Storage Connection String.

connection string for the storage. leave blank if using other auth methods.

**Properties:**

  - Config: `connection_string`
  - Env Var: `RCLONE_AZUREBLOB_CONNECTION_STRING`
  - Type: string
  - Required: false

### `--azureblob-tenant`

ID of the service principal's tenant. also called its directory ID.

set this if you're 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 you're 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 you're 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 you're 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 you're using:

  - Service principal with certificate

and the certificate has a password.

> NB input to this must be obscured — see `rclone obscure` (https://rclone.org/commands/rclone_obscure/).

**Properties:**

  - Config: `client_certificate_password`
  - Env Var: `RCLONE_AZUREBLOB_CLIENT_CERTIFICATE_PASSWORD`
  - Type: string
  - Required: false

---

### 🚀 Advanced options

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 you're 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 you're 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 you're using:

  - User with username and password

> NB input to this must be obscured — see `rclone obscure` (https://rclone.org/commands/rclone_obscure/).

**Properties:**

  - Config: `password`

and the rest of that `password` property rundown, because we're thorough like that 💅:

- Env Var: `RCLONE_AZUREBLOB_PASSWORD`
- Type: string
- Required: false

---

- **`--azureblob-service-principal-file`** — 💳 path to a file that's holding credentials for a <purple>service principal</purple>.

  Leave it blank normally, bestie, fr fr. You only need this one if you wanna authenticate with a service principal instead of doing the whole interactive-login thing.

$ 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

Peep the "Create an Azure service principal" page at https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli and the "Assign an Azure role for access to blob data" page at https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-rbac-cli for all the extra deets ✨

Lowkey it might be way more convenient to just yeet the credentials straight 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.

Only set this to true if you're an application authenticating in disconnected clouds, or private clouds like <cyan>Azure Stack</cyan>.

It's the thing that decides whether rclone asks for Microsoft Entra instance metadata from https://login.microsoft.com/ before authenticating.

Setting this to true skips that request, which means <hotpink>you</hotpink> are now the one responsible for making sure the configured authority is actually valid and trustworthy. No pressure or anything 😭

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 (and heads up: this only works in Azure).

When true, use a managed service identity (https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/) to authenticate to Azure Storage instead of a SAS token or account key.

If the VM(SS) this program is running on has a system-assigned identity, that's the one that gets used by default. If the resource has no system-assigned one but has exactly one user-assigned identity, that user-assigned identity gets used by default. And if the resource has multiple user-assigned identities? Then you have to explicitly say which one to use with exactly one of the `msi_object_id`, `msi_client_id`, or `msi_mi_res_id` parameters. Pick one, bestie, not all three 👑

Properties:

- Config: `use_msi`
- Env Var: `RCLONE_AZUREBLOB_USE_MSI`
- Type: bool
- Default: false

---

- **`--azureblob-msi-object-id`** — 🆔 the Object ID of the user-assigned MSI to use, if any.

Leave it blank if you specified `msi_client_id` or `msi_mi_res_id`.

Properties:

- Config: `msi_object_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_OBJECT_ID`
- Type: string
- Required: false

---

- **`--azureblob-msi-client-id`** — 🆔 the Object ID of the user-assigned MSI to use, if any. (yes it says Object ID, that's literally what it says, don't come for me 🌸)

Leave it blank if you specified `msi_object_id` or `msi_mi_res_id`.

Properties:

- Config: `msi_client_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_CLIENT_ID`
- Type: string
- Required: false

---

- **`--azureblob-msi-mi-res-id`** — 🆔 the Azure resource ID of the user-assigned MSI to use, if any.

Leave it blank if you specified `msi_client_id` or `msi_object_id`.

Properties:

- Config: `msi_mi_res_id`
- Env Var: `RCLONE_AZUREBLOB_MSI_MI_RES_ID`
- Type: string
- Required: false

---

- **`--azureblob-use-emulator`** — 🧪 uses the local storage emulator if you provide it as `'true'`.

Leave it blank if you're using a real Azure storage endpoint, obviously.

Properties:

- Config: `use_emulator`
- Env Var: `RCLONE_AZUREBLOB_USE_EMULATOR`
- Type: bool
- Default: false

---

- **`--azureblob-use-az`** — 🖥️ use the Azure CLI tool `az` for authentication.

Set this to use the Azure CLI tool `az` (https://learn.microsoft.com/en-us/cli/azure/) as the <rainbow>sole</rainbow> means of authentication.

Setting it can be genuinely useful if you wanna use the `az` CLI on a host that has a System Managed Identity you do *not* want to use. Like, respect the boundaries, host.

Don't set `env_auth` at the same time. They're not friends.

Properties:

- Config: `use_az`
- Env Var: `RCLONE_AZUREBLOB_USE_AZ`
- Type: bool
- Default: false

---

- **`--azureblob-endpoint`** — 🌐 endpoint for the service.

Leave it 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`) — <red>deprecated</red>, bestie, it's giving legacy 😭

Properties:

- Config: `upload_cutoff`
- Env Var: `RCLONE_AZUREBLOB_UPLOAD_CUTOFF`
- Type: string
- Required: false

---

- **`--azureblob-chunk-size`** — 📦 upload chunk size.

> Not me reminding you that this is stored in memory and there may be up to `--transfers` * `--azureblob-upload-concurrency` chunks stored at once in memory. Memory is not infinite, queen 💀

Properties:

- Config: `chunk_size`
- Env Var: `RCLONE_AZUREBLOB_CHUNK_SIZE`
- Type: SizeSuffix
- Default: `4Mi`

---

- **`--azureblob-upload-concurrency`** — 🚀 concurrency for multipart uploads.

This is how many chunks of the <hotpink>same file</hotpink> get uploaded at the same time.

If you're uploading a small number of big files over high-speed links and those uploads aren't fully using your bandwidth, bumping this up may legit speed up your transfers.

In tests, upload speed goes up almost linearly with upload concurrency. Like, to fill a gigabit pipe you might need to raise this to 64. Just know it'll eat more memory.

> And again: chunks are stored in memory, and there may be up to `--transfers` * `--azureblob-upload-concurrency` chunks stored at once in memory. Your RAM is the main character here, protect her 🫶

Properties:

- Config: `upload_concurrency`
- Env Var: `RCLONE_AZUREBLOB_UPLOAD_CONCURRENCY`
- Type: int
- Default: 16

---

- **`--azureblob-copy-cutoff`** — ✂️ cutoff for switching to multipart copy.

Any files bigger than this that need a server-side copy get copied in chunks of `chunk_size` using the put block list API.

Files smaller than this limit get copied with the Copy Blob API. Small file, simple life ✨

Properties:

- Config: `copy_cutoff`
- Env Var: `RCLONE_AZUREBLOB_COPY_CUTOFF`
- Type: SizeSuffix
- Default: `8Mi`

---

- **`--azureblob-copy-concurrency`** — 🌀 concurrency for multipart copy.

This is how many chunks of the same file get copied at the same time.

These chunks are <green>not</green> buffered in memory, and Microsoft recommends setting this value to greater than 1000 in the azcopy documentation.

https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-optimize#increase-concurrency

In tests, copy speed increases almost linearly with copy concurrency. Iconic behaviour, honestly.

Properties:

- Config: `copy_concurrency`
- Env Var: `RCLONE_AZUREBLOB_COPY_CONCURRENCY`
- Type: int
- Default: 512

---

- **`--azureblob-copy-total-concurrency`** — 🎚️ global concurrency limit for multipart copy chunks.

This caps the total number of multipart copy chunks running at once <purple>across all files</purple>.

Set it to `0` to disable this limiter entirely.

Properties:

- Config: `copy_total_concurrency`
- Env Var: `RCLONE_AZUREBLOB_COPY_TOTAL_CONCURRENCY`
- Type: int
- Default: 0

---

- **`--azureblob-use-copy-blob`** — 📋 whether to use the Copy Blob API when copying to the same storage account.

If true (and true is the default), rclone uses the Copy Blob API for copies to the same storage account even when the size is above the `copy_cutoff`.

Rclone assumes that "the same storage account" means the same config, and it does <red>not</red> check for the same storage account across different configs. It's trusting like that 🙈

There should be no need to change this value.

Properties:

- Config: `use_copy_blob`
- Env Var: `RCLONE_AZUREBLOB_USE_COPY_BLOB`
- Type: bool
- Default: true

---

- **`--azureblob-list-chunk`** — 📜 size of blob list.

This sets how many blobs get requested in each listing chunk. Default is the maximum, 5000.

"List blobs" requests are permitted 2 minutes per megabyte to complete. If an operation is averaging longer than 2 minutes per megabyte, it will time out (source: https://docs.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-blob-service-operations#exceptions-to-default-timeout-interval). So you can use this to limit how many blob items come back, to dodge that timeout.

Properties:

- Config: `list_chunk`
- Env Var: `RCLONE_AZUREBLOB_LIST_CHUNK`
- Type: int
- Default: 5000

---

- **`--azureblob-use-arrow-list`** — 🏹 use the Apache Arrow listing format.

If set, directory listings get fetched using the ListBlobs Apache Arrow response format instead of XML. Arrow responses are smaller and <green>much</green> cheaper to parse, which makes listing huge containers several times faster. Combine it with `list_parallelism` for the biggest gains 👑

"Blob Listing with Apache Arrow" is in public preview at Microsoft and is only supported on flat namespace accounts. On accounts with a hierarchical namespace (ADLS Gen2), or anywhere the feature isn't available, the server hands back XML and the listing transparently falls back to the normal XML path (logged at debug level). No drama, it just quietly pivots 💅

Properties:

- Config: `use_arrow_list`
- Env Var: `RCLONE_AZUREBLOB_USE_ARROW_LIST`
- Type: bool
- Default: false

---

- **`--azureblob-list-parallelism`** — 🧵 number of parallel shards to list a directory with.

If you set this greater than 1, the blob name keyspace of each directory gets split into ranges which are listed concurrently using the Arrow `startFrom`/`endBefore` range parameters. This can <rainbow>dramatically</rainbow> speed up listing containers with millions of objects, for both recursive (ListR) and single directory listings. Speed keeps improving right up to a parallelism of around 30.

This does nothing unless `use_arrow_list` is also set, because Arrow is the only listing path that supports server-side name ranges. If the account doesn't support range listing (e.g. it has a hierarchical namespace) the listing falls back to sequential. The default of 0 (or 1) lists sequentially.

Properties:

- Config: `list_parallelism`
- Env Var: `RCLONE_AZUREBLOB_LIST_PARALLELISM`
- Type: int
- Default: 0

---

- **`--azureblob-access-tier`** — 🧊 access tier of blob: `hot`, `cool`, `cold` or `archive`.

Archived blobs can be restored by setting access tier to `hot`, `cool` or `cold`. Leave blank if you intend to use the default access tier, which is set at account level

<pink>okay so</pink> if there is literally no "access tier" specified, rclone does <italic>not</italic> apply any tier at all. none. nada. 🫶

rclone performs the "Set Tier" operation on blobs while uploading, so iykyk — <purple>if objects are not modified, specifying "access tier" to a new one will have no effect.</purple> and here's the part you actually need to hear:

> 🚨 if blobs are sitting in the `archive tier` over on the remote, and you try to do data transfer operations *from* that remote, it will <red>not be allowed</red>. the user has to first restore by tiering the blob to `Hot`, `Cool`, or `Cold`. periodt.

**The stats 💅:**

- **Config:** `access_tier`
- **Env Var:** `RCLONE_AZUREBLOB_ACCESS_TIER`
- **Type:** string
- **Required:** false

---

- **`--azureblob-archive-tier-delete`** — delete archive tier blobs before overwriting.

archive tier blobs <hotpink>cannot</hotpink> be updated, like, ever. so without this flag, if you attempt to update an archive tier blob, rclone will hit you with this error:

can't update archive tier blob without --azureblob-archive-tier-delete

but with this flag set, then before rclone attempts to overwrite an archive tier blob, it will <pink>delete the existing blob first</pink> before uploading its replacement. and bestie, i need you to know this has the potential for **data loss** if the upload fails (unlike updating a normal blob) 💀 and it also may cost more since deleting archive tier blobs early may be chargable. so. yeah. be careful.

**The stats 💅:**

- **Config:** `archive_tier_delete`
- **Env Var:** `RCLONE_AZUREBLOB_ARCHIVE_TIER_DELETE`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-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 add it to the metadata on the object. this is <green>so slay</green> for data integrity checking but ngl it can cause long delays for large files to start uploading.

**The stats 💅:**

- **Config:** `disable_checksum`
- **Env Var:** `RCLONE_AZUREBLOB_DISABLE_CHECKSUM`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-encoding`** — the encoding for the backend.

peep the encoding section in the overview (https://rclone.org/overview/#encoding) for more info. 👀

**The stats 💅:**

- **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.

**The stats 💅:**

- **Config:** `public_access`
- **Env Var:** `RCLONE_AZUREBLOB_PUBLIC_ACCESS`
- **Type:** string
- **Required:** false
- **The 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`** — upload an empty object with a trailing slash when a new directory is created.

empty folders are <red>unsupported</red> for bucket based remotes, so this option creates an empty object ending with `/`, to persist the folder. 🫶

this object also has the metadata `hdi_isfolder = true` to conform to the Microsoft standard.

**The stats 💅:**

- **Config:** `directory_markers`
- **Env Var:** `RCLONE_AZUREBLOB_DIRECTORY_MARKERS`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-no-check-container`** — if set, don't attempt to check the container exists or create it.

this can be useful when trying to minimise the number of transactions rclone does, if you already *know* the container exists. like, you got this, bestie, no need for the extra check 💅

**The stats 💅:**

- **Config:** `no_check_container`
- **Env Var:** `RCLONE_AZUREBLOB_NO_CHECK_CONTAINER`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-no-head-object`** — if set, do not do HEAD before GET when getting objects.

**The stats 💅:**

- **Config:** `no_head_object`
- **Env Var:** `RCLONE_AZUREBLOB_NO_HEAD_OBJECT`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-delete-snapshots`** — set to specify how to deal with snapshots on blob deletion.

**The stats 💅:**

- **Config:** `delete_snapshots`
- **Env Var:** `RCLONE_AZUREBLOB_DELETE_SNAPSHOTS`
- **Type:** string
- **Required:** false
- **The choices 🎀:**
  - `""`
    - by default, the delete operation <red>fails</red> 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-decompress`** — if set this will decompress gzip encoded objects.

it is possible to upload objects to Azure Blob Storage with `"Content-Encoding: gzip"` set. normally rclone will download these files as compressed objects.

but if this flag is set, then rclone will decompress these files with `"Content-Encoding: gzip"` as they are received. which means rclone <hotpink>can't check the size and hash</hotpink> — but the file contents will be decompressed. so there's a tradeoff, iykyk. 🦋

**The stats 💅:**

- **Config:** `decompress`
- **Env Var:** `RCLONE_AZUREBLOB_DECOMPRESS`
- **Type:** bool
- **Default:** false

---

- **`--azureblob-description`** — description of the remote.

**The stats 💅:**

- **Config:** `description`
- **Env Var:** `RCLONE_AZUREBLOB_DESCRIPTION`
- **Type:** string
- **Required:** false

---

## 🌸 Metadata 🌸

user metadata is stored as `x-ms-meta-` keys. Azure metadata keys are **case insensitive** and are always returned in <purple>lower case</purple>. no cap.

here are the possible system metadata items for the `azureblob` backend 👇

- **`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:** `Hot`
  - **Read Only:** Y

peep the metadata (https://rclone.org/docs/#metadata) docs for more info. 💖

---

## 🎀 Custom upload headers 🎀

you can set custom upload headers with the `--header-upload` flag. the glow-up list:

- `Cache-Control`
- `Content-Disposition`
- `Content-Encoding`
- `Content-Language`
- `Content-Type`
- `X-MS-Tags`

eg `--header-upload "Content-Type: text/potato"` or `--header-upload "X-MS-Tags: foo=bar"`. ✨

---

## 💀 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. lowkey convenient.

`rclone about` is <red>not supported</red> by the Microsoft Azure Blob storage 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 (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

---

## 🧚 Azure Storage Emulator Support 🧚

you can run rclone with the storage emulator (usually `azurite`). iconic.

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 want to 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:` — and yes bestie, you may put subdirectories in too, e.g. `remote:path/to/dir`. 💅

## 🌈 Configuration 🌈

here is 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:

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 Files Storage \ "azurefiles" [snip]

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 you've done all that config-ing, bestie, you can actually *use* rclone. Let's go 💅

See every file chilling at the top level:

rclone lsf remote:

Make a brand new directory in the root:

rclone mkdir remote:dir

Recursively list the contents:

rclone ls remote:

Sync `/home/local/directory` up to the remote directory, and <red>delete any excess files in the directory</red> (yes, it really deletes them, no cap, be careful 🙈):

rclone sync --interactive /home/local/directory remote:dir

---

### Modified time 🕰️

The modified time is stored as the SMB `LastWriteTime` property on files. It has a precision of `100 ns`. Like, it's *precise* precise ✨

---

### Performance 🚀

When you're uploading large files, cranking up the value of `--azurefiles-upload-concurrency` will bump your performance — at the cost of using more memory. The default of `16` is set quite conservatively so it uses 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.

> ngl, that "maybe be" is straight from the original, we're not fixing it, it's iconic 💀

---

### Restricted filename characters 🚫

On top of the default restricted characters set (`https://rclone.org/overview/#restricted-characters`), these characters also get swapped out:

- `"` — 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 also can't *end* with the following character. 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 (`https://rclone.org/overview/#invalid-utf8`), because they literally can't be used in JSON strings. Sorry babe 🌸

---

### Hashes 🔐

MD5 hashes are stored with files. But not *all* files will have MD5 hashes, because these have to be uploaded along with the file.

---

### Authentication 🪪

There are a whole bunch of ways of supplying credentials for Azure Files Storage. Rclone tries them in the order of the sections below, so like, first one that works wins 💖

---

### 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 — depends on which environment variables 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. If the resource has no system-assigned but exactly one user-assigned identity, that user-assigned identity will be used by default.

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.

If you're 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` skips that request — which makes *you* responsible for making sure the configured authority is valid and trustworthy. 👑

---

### 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`.

So 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 :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. Simple, clean, no drama ✨

---

### 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.

> <red>NB</red> `client_certificate_password` must be obscured — see rclone obscure (`https://rclone.org/commands/rclone_obscure/`). Do not skip this bestie, fr fr 😭

---

### 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.

> <red>NB</red> `password` must be obscured — see rclone obscure (`https://rclone.org/commands/rclone_obscure/`). 💅

---

### Managed Service Identity Credentials 🪪

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 equivalent to using `env_auth`.

---

### Federated Identity Credentials 🤝

If these variables are set, rclone will authenticate with federated identity.

- `tenant`: tenant ID of the storage
- `client_id`: client ID of the application the user will authenticate to storage
- `msi_client_id`: managed identity client ID of the application the user will authenticate to

By default `"api://AzureADTokenExchange"` is used as scope for token retrieval over MSI. This token is then exchanged for actual storage token using `'tenant'` and `'client_id'`. Cute little token swap, we love to see it 🫶

---

### Azure CLI tool az 🛠️

If `use_az` is set, use Azure CLI tool `az` (`https://learn.microsoft.com/en-us/cli/azure/`) 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. Like, just don't 🙈

---

### 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 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_AZUREFILES_ACCOUNT`
- 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`** — the Storage Account Shared Key 🔑 leave this blank if you're rolling with a SAS URL or the Emulator instead.

  Properties:

  - Config: `key`

  - Env Var: `RCLONE_AZUREFILES_KEY`

  - Type: string

  - Required: false

- **`--azurefiles-sas-url`** — SAS URL, and it's for <hotpink>container level access only</hotpink> bestie. Leave it blank if you're using account/key or the Emulator.

  Properties:

  - Config: `sas_url`

  - Env Var: `RCLONE_AZUREFILES_SAS_URL`

  - Type: string

  - Required: false

- **`--azurefiles-connection-string`** — the Storage Connection String. Like, connection string for the storage, periodt. Leave it blank if you're using other auth methods.

  Properties:

  - Config: `connection_string`

  - Env Var: `RCLONE_AZUREFILES_CONNECTION_STRING`

  - Type: string

  - Required: false

- **`--azurefiles-tenant`** — the ID of the service principal's tenant 🏠 it's also called its directory ID. Set this if you're 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 you're using. Set this if you're 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 you're 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, private key included 🎀 Set this if you're 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 you're using:

  - Service principal with certificate

  And the certificate has a password, obviously 💅

  > NB: input to this <red>must</red> be obscured — see `rclone obscure` (`https://rclone.org/commands/rclone_obscure/`).

  Properties:

  - Config: `client_certificate_password`

  - Env Var: `RCLONE_AZUREFILES_CLIENT_CERTIFICATE_PASSWORD`

  - Type: string

  - Required: false

- **`--azurefiles-share-name`** — the Azure Files Share Name 🦋 this one is <hotpink>required</hotpink> and it's literally the name of the share you wanna access.

  Properties:

  - Config: `share_name`

  - Env Var: `RCLONE_AZUREFILES_SHARE_NAME`

  - Type: string

  - Required: false

---

### ✨ Advanced options ✨

Here are the Advanced options specific to azurefiles (Microsoft Azure Files) 👑

---

- **`--azurefiles-client-send-certificate-chain`** — send the certificate chain when you're using certificate auth ⛓️ it specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When it's set to `true`, the auth requests include that 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 <red>must</red> be obscured — see `rclone obscure` (`https://rclone.org/commands/rclone_obscure/`).

  Properties:

  - Config: `password`

  - Env Var: `RCLONE_AZUREFILES_PASSWORD`

  - Type: string

  - Required: false

- **`--azurefiles-service-principal-file`** — path to a file containing credentials for use with a service principal. Leave it blank normally, you only need it if you wanna 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

Check out the "Create an Azure service principal" (`https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli`) and "Assign an Azure role for access to blob data" (`https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-rbac-cli`) pages for more deets 👀

Ngl it may be more convenient to just shove 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-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 decides whether rclone requests Microsoft Entra instance metadata from `https://login.microsoft.com/` before authenticating.

Setting this to `true` will skip that request, which makes <red>you</red> responsible for making sure the configured authority is valid and trustworthy. No pressure bestie 😭

Properties:

- Config: `disable_instance_discovery`

- Env Var: `RCLONE_AZUREFILES_DISABLE_INSTANCE_DISCOVERY`

- Type: bool

- Default: false

- **`--azurefiles-use-msi`** — use a managed service identity to authenticate (only works in Azure, iykyk ☁️). When `true`, use a managed service identity (`https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/`) to authenticate to Azure Storage instead of a SAS token or account key.

If the VM(SS) this program is running on has a system-assigned identity, it'll be used by default. If the resource has no system-assigned identity but has exactly *one* user-assigned identity, that user-assigned identity gets used by default. And if the resource has multiple user-assigned identities, the one 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 it blank if `msi_client_id` or `msi_mi_res_id` is 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 it blank if `msi_object_id` or `msi_mi_res_id` is 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 it blank if `msi_client_id` or `msi_object_id` is specified.

Properties:

- Config: `msi_mi_res_id`

- Env Var: `RCLONE_AZUREFILES_MSI_MI_RES_ID`

- Type: string

- Required: false

- **`--azurefiles-use-emulator`** — uses the local storage emulator if you provide it as `'true'` 🖥️ Leave it blank if you're using a real azure storage endpoint.

Properties:

- Config: `use_emulator`

- Env Var: `RCLONE_AZUREFILES_USE_EMULATOR`

- Type: bool

- Default: false

- **`--azurefiles-use-az`** — use the Azure CLI tool `az` for authentication ✨ Set this to use the Azure CLI tool `az` (`https://learn.microsoft.com/en-us/cli/azure/`) as the *sole* means of authentication.

Setting this can be useful if you wanna use the `az` CLI on a host with a System Managed Identity that you do <italic>not</italic> want to use.

> Don't set `env_auth` at the same time, bestie — that's not the vibe 💀

Properties:

- Config: `use_az`

- Env Var: `RCLONE_AZUREFILES_USE_AZ`

- Type: bool

- Default: false

- **`--azurefiles-endpoint`** — endpoint for the service. Leave it blank normally, fr fr.

Properties:

- Config: `endpoint`

- Env Var: `RCLONE_AZUREFILES_ENDPOINT`

- Type: string

- Required: false

- **`--azurefiles-chunk-size`** — the upload chunk size 🧩 heads up that this is stored in memory, so there may be up to `"--transfers"` * `"--azurefile-upload-concurrency"` chunks stored at once in memory. Plan accordingly, okay? 😭

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 get uploaded concurrently.

If you're uploading small numbers of large files over high-speed links and those uploads aren't fully using your bandwidth, then bumping this up may help 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's gonna be. When rclone doesn't know, it uses this value instead.

This gets used when rclone is streaming data, and the most common uses are:

- Uploading files with `--vfs-cache-mode off` with `rclone mount`

- Using `rclone rcat`

- Copying files with unknown length

You'll need this much free space in the share, because 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 (`https://rclone.org/overview/#encoding`) 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. Yes bestie, you get to decorate your uploads 💅

- Cache-Control
- Content-Disposition
- Content-Encoding
- Content-Language
- Content-Type

Example, she's serving potato: `--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. That's just the way it is, no cap.

---

# 👑 Microsoft OneDrive

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`. Go as deep as your little heart desires, it does not care. 🌊

## ✨ 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, 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:

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 (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available. No browser, no problem, there's a whole guide. 💖

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. Lowkey important, so peek at your firewall if things are acting weird. 🔥

Once configured you can then use rclone like this (replace `remote` with the name you gave your remote):

List directories in top level of your OneDrive

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

rclone uses a default Client ID when talking to OneDrive, unless a custom `client_id` is specified in the config. The default Client ID and Key are shared by all rclone users when performing requests. It's giving community pool energy. 🌈

You may choose to create and use your own Client ID, in case the default one does not work well for you. For example, you might see throttling. If the shared one is being a hater, go make your own. 👑

## 🌸 Creating Client ID for OneDrive Personal

To create your own Client ID, please follow these steps:

1. Open <https://portal.azure.com/?quickstart=true#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview> and then under the Add menu click App registration.

  - If you have not created an Azure account, you will be prompted to. This is free, but you need to provide a phone number, address, and credit card for identity verification.

2. Enter a name for your app, choose account type Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox), select Web in Redirect URI, then type (do not copy and paste) `http://localhost:53682/` and click Register. Copy and keep the Application (client) ID under the app name for later use.

> <red>Do not copy and paste that redirect URI — actually *type* it.</red> Microsoft is picky like that, sorry bestie. 😭

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). Screenshot it, write it on your hand, do whatever — it's gone after. 💀

4. Under manage select API permissions, click Add a permission and select Microsoft Graph then select delegated permissions.

5. Search and select the following permissions: Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, offline_access, User.Read and Sites.Read.All (if custom access scopes are configured, select the permissions accordingly). Once selected click Add permissions at the bottom.

Now the application is complete. Run `rclone config` to create or edit a OneDrive remote. Supply the app ID and password as Client ID and Secret, respectively. rclone will walk you through the remaining steps. Slay. 💅

The `access_scopes` option allows you to configure the permissions requested by rclone. See Microsoft Docs (https://docs.microsoft.com/en-us/graph/permissions-reference#files-permissions) for more information about the different scopes.

The `Sites.Read.All` permission is required if you need to search SharePoint sites when configuring the remote (https://github.com/rclone/rclone/pull/5883). However, if that permission is not assigned, you need to exclude `Sites.Read.All` from your access scopes or set `disable_site_permission` option to `true` in the advanced options. Pick your fighter, both work. ✨

## 💜 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. It's not you, it's the org's security settings being extra. 🙈

You may try to verify you account (https://docs.microsoft.com/en-us/azure/active-directory/develop/publisher-verification-overview), or try to limit the App to your organization only, as shown below.

1. Make sure to create the App with your business account.

2. Follow the steps above to create an App. However, we need a different account type here: Accounts in this organizational directory only (*** - Single tenant). Note that you can also change the account type after creating the App.

3. Find the tenant ID (https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant) of your organization.

4. In the rclone config, set `auth_url` to `https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize`.

5. In the rclone config, set `token_url` to `https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token`.

Note: If you have a special region, you may need a different host in step 4 and 5. Here are some hints (https://github.com/rclone/rclone/blob/bc23bf11db1c78c6ebbf8ea538fbebf7058b4176/backend/onedrive/onedrive.go#L86). iykyk, the source code always knows. 🔍

## 🌈 Using OAuth Client Credential flow

OAuth Client Credential flow will allow rclone to use permissions directly associated with the Azure AD Enterprise application, rather that adopting the context of an Azure AD user account. Yeah, it's main character app energy instead of borrowing your user's whole personality. 👑

This flow can be enabled by following the steps below:

1. Create the Enterprise App registration in the Azure AD portal and obtain a Client ID and Client Secret as described above.

2. Ensure that the application has the appropriate permissions and they are assigned as Application Permissions

3. Configure the remote, ensuring that Client ID and Client Secret are entered correctly.

4. In the Advanced Config section, enter `true` for `client_credentials` and in the tenant section enter the tenant ID.

When it comes to choosing the type of the connection work with the client credentials flow. In particular the "onedrive" option does not work. You can use the "sharepoint" option or if that does not find the correct drive ID type it in manually with the "driveid" option. <red>Heads up: the `onedrive` option is a no-go here.</red>

To back up any user's data using this flow, grant your Azure AD application the necessary Microsoft Graph Application permissions (such as Files.Read.All, Sites.Read.All and/or Sites.Selected). With these permissions, rclone can access drives across the tenant, but it needs to know which user or drive you want. Supply a specific `drive_id` corresponding to that user's OneDrive, or a SharePoint site ID for SharePoint libraries. You can obtain a user's drive ID using Microsoft Graph (e.g. `/users/{userUPN}/drive`) and then configure it in rclone. Once the correct drive ID is provided, rclone will back up that user's data using the app-only token without requiring their credentials. Fr fr, no user login needed at all. 😳

> <hotpink>NOTE</hotpink> Assigning permissions directly to the application means that anyone with the Client ID and Client Secret can access your OneDrive files. Take care to safeguard these credentials. <red>Seriously, guard them like your life depends on it — that's the whole key to the castle.</red> 🫶🔐

### 🦋 Non-admin access to Business OneDrive 🦋

Okay so bestie, if you do **not** have admin access to your org's OneDrive for Business, you can still slide in there — you just have to manually hand over the SharePoint tenant URL and drive ID. How does that even work? It overrides the base API URL, swapping the standard Microsoft Graph endpoint out for the SharePoint v2.0 endpoint. Sneaky but effective, no cap. 💅

### 🔍 Steps to manually obtain credentials 🔍

1. Open your browser and navigate to `https://[your-tenant].sharepoint.com/`

2. Open Developer Tools (press <kbd>F12</kbd>) and go to the Network tab.

3. Search for `driveAccessToken` in the network requests.

4. Extract the following information from the response:

".driveUrl": "{tenant_url}/v2.0/drives/{drive_id}", ".driveAccessToken": "access_token={access_token}"

### ⚙️ Rclone configuration ⚙️

Now take those extracted values and use them to configure your remote:

type = onedrive token = {"access_token":"{access_token}","token_type":"Bearer","refresh_token":"","expiry":"2045-12-31T23:59:59Z"} drive_id = {drive_id} tenant_url = {tenant_url} drive_type = business

Quick heads up: since the exact expiry time cannot be determined from web traffic, set the expiry to a future date. Fair warning though — that token will eventually expire and you will need to repeat the whole process to obtain a new one. Annoying, I know. 😭

### 🕐 Modification times and hashes 🕐

OneDrive allows modification times to be set on objects accurate to **1 second**. These will be used to detect whether objects need syncing or not.

OneDrive Personal, OneDrive for Business and Sharepoint Server support QuickXorHash (<https://docs.microsoft.com/en-us/onedrive/developer/code-snippets/quickxorhash>).

Before rclone `1.62` the default hash for Onedrive Personal was `SHA1`. For rclone `1.62` and above the default for all Onedrive backends is `QuickXorHash`. Glow up era. ✨

Starting from July 2023 `SHA1` support is being phased out in Onedrive Personal in favour of `QuickXorHash`. If necessary the `--onedrive-hash-type` flag (or `hash_type` config option) can be used to select `SHA1` during the transition period if this is important your workflow.

For all types of OneDrive you can use the `--checksum` flag.

### ⚡ --fast-list ⚡

This remote supports `--fast-list` which allows you to use fewer transactions in exchange for more memory. See the rclone docs (<https://rclone.org/docs/#fast-list>) for more details.

This must be enabled with the `--onedrive-delta` flag (or `delta = true` in the config file) as it can cause performance degradation. ⚠️

It does this by using the delta listing facilities of OneDrive which returns all the files in the remote very efficiently. This is much more efficient than listing directories recursively and is Microsoft's recommended way of reading all the file information from a drive. Iconic behaviour honestly. 👑

This can be useful with `rclone mount` and `rclone rc vfs/refresh recursive=true` (<https://rclone.org/rc/#vfs-refresh>)) to very quickly fill the mount with information about all the files.

The API used for the recursive listing (`ListR`) only supports listing from the root of the drive. This will become increasingly inefficient the further away you get from the root as rclone will have to discard files outside of the directory you are using. 🥲

Some commands (like `rclone lsf -R`) will use `ListR` by default - you can turn this off with `--disable ListR` if you need to.

### 🚫 Restricted filename characters 🚫

In addition to the default restricted characters set (<https://rclone.org/overview/#restricted-characters>) the following characters are also replaced:

- Character `"`, Value `0x22`, Replacement `＂`
- Character `*`, Value `0x2A`, Replacement `＊`
- Character `:`, Value `0x3A`, Replacement `：`
- Character `<`, Value `0x3C`, Replacement `＜`
- Character `>`, Value `0x3E`, Replacement `＞`
- Character `?`, Value `0x3F`, Replacement `？`
- Character `\`, Value `0x5C`, Replacement `＼`
- Character `|`, Value `0x7C`, 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 `␠`
- Character `.`, Value `0x2E`, Replacement `．`

File names can also **not begin** with the following characters. These only get replaced if they are the **first** character in the name:

- Character `SP`, Value `0x20`, Replacement `␠`
- Character `~`, Value `0x7E`, Replacement `～`

Invalid UTF-8 bytes will also be replaced (<https://rclone.org/overview/#invalid-utf8>), as they can't be used in JSON strings.

### 🗑️ Deleting files 🗑️

Any files you delete with rclone will end up in the trash. Microsoft doesn't provide an API to permanently delete files, nor to empty the trash, so you will have to do that with one of Microsoft's apps or via the OneDrive website. Not me having to go through the actual website like it's 2012. 💀

---

### ✨ Standard options ✨

Here are the Standard options specific to onedrive (Microsoft OneDrive).

- **`--onedrive-client-id`** — OAuth Client Id.

  Leave blank normally.

  Properties:

  - Config: `client_id`
  - Env Var: `RCLONE_ONEDRIVE_CLIENT_ID`
  - Type: string
  - Required: false

- **`--onedrive-client-secret`** — OAuth Client Secret.

  Leave blank normally.

  Properties:

  - Config: `client_secret`
  - Env Var: `RCLONE_ONEDRIVE_CLIENT_SECRET`
  - Type: string
  - Required: false

- **`--onedrive-region`** — Choose national cloud region for OneDrive.

  Properties:

  - Config: `region`
  - Env Var: `RCLONE_ONEDRIVE_REGION`
  - Type: string
  - Default: `"global"`
  - Examples:
    - `"global"`
      - Microsoft Cloud Global
    - `"us"`
      - Microsoft Cloud for US Government
    - `"de"`
      - Microsoft Cloud Germany (deprecated - try global region first).
    - `"cn"`
      - Azure and Office 365 operated by Vnet Group in China

- **`--onedrive-tenant`** — ID of the service principal's tenant. Also called its directory ID.

  Set this if using - Client Credential flow

  Properties:

  - Config: `tenant`
  - Env Var: `RCLONE_ONEDRIVE_TENANT`
  - Type: string
  - Required: false

---

### 🔥 Advanced options 🔥

Here are the Advanced options specific to onedrive (Microsoft OneDrive).

- **`--onedrive-token`** — OAuth Access Token as a JSON blob.

  Properties:

  - Config: `token`
  - Env Var: `RCLONE_ONEDRIVE_TOKEN`
  - Type: string
  - Required: false

- **`--onedrive-auth-url`** — Auth server URL.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `auth_url`
  - Env Var: `RCLONE_ONEDRIVE_AUTH_URL`
  - Type: string
  - Required: false

- **`--onedrive-token-url`** — Token server url.

  Leave blank to use the provider defaults.

  Properties:

  - Config: `token_url`
  - Env Var: `RCLONE_ONEDRIVE_TOKEN_URL`
  - Type: string
  - Required: false

- **`--onedrive-client-credentials`** — Use client credentials OAuth flow.

  This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

  Note that this option is **NOT** supported by all backends.

  Properties:

  - Config: `client_credentials`
  - Env Var: `RCLONE_ONEDRIVE_CLIENT_CREDENTIALS`
  - Type: bool
  - Default: false

- **`--onedrive-upload-cutoff`** — Cutoff for switching to chunked upload.

  Any files larger than this will be uploaded in chunks of `chunk_size`.

  This is disabled by default as uploading using single part uploads causes rclone to use twice the storage on Onedrive business as when rclone sets the modification time after the upload Onedrive creates a new version.

  See: <https://github.com/rclone/rclone/issues/1716>

  Properties:

  - Config: `upload_cutoff`
  - Env Var: `RCLONE_ONEDRIVE_UPLOAD_CUTOFF`
  - Type: SizeSuffix
  - Default: off

- **`--onedrive-tenant-url`** — The tenant URL for non-admin OneDrive access.

  Set this to your SharePoint tenant URL to use the SharePoint v2.0 API endpoint instead of the standard Microsoft Graph API. This allows accessing business OneDrive without admin consent.

  The URL can be found in your browser's developer tools by searching for `"driveAccessToken"` in the network requests. Look for the `".driveUrl"` field which contains the tenant URL and drive ID.

  Example: `https://your-tenant.sharepoint.com/_api`

  Properties:

  - Config: `tenant_url`
  - Env Var: `RCLONE_ONEDRIVE_TENANT_URL`
  - Type: string
  - Required: 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

- **`--onedrive-drive-id`** — The ID of the drive to use.

  Properties:

  - Config: `drive_id`
  - Env Var: `RCLONE_ONEDRIVE_DRIVE_ID`
  - Type: string
  - Required: false

- **`--onedrive-drive-type`** — The type of the drive (personal | business | documentLibrary).

  Properties:

  - Config: `drive_type`
  - Env Var: `RCLONE_ONEDRIVE_DRIVE_TYPE`
  - Type: string
  - Required: false

- **`--onedrive-root-folder-id`** — ID of the root folder.

  This isn't normally needed, but in special circumstances you might know the folder ID that you wish to access but not be able to get there through a path traversal.

  Properties:

  - Config: `root_folder_id`
  - Env Var: `RCLONE_ONEDRIVE_ROOT_FOLDER_ID`
  - Type: string
  - Required: false

- **`--onedrive-access-scopes`** — Set scopes to be requested by rclone.

  Choose or manually enter a custom space separated list with all scopes, that rclone should request.

  Properties:

  - Config: `access_scopes`
  - Env Var: `RCLONE_ONEDRIVE_ACCESS_SCOPES`
  - Type: SpaceSepList
  - Default: `Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access`
  - Examples:
    - `"Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access"`
      - Read and write access to all resources
    - `"Files.Read Files.Read.All Sites.Read.All offline_access"`
      - Read only access to all resources
    - `"Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All offline_access"`
      - Read and write access to all resources, without the ability to browse SharePoint sites.
      - Same as if `disable_site_permission` was set to true

- **`--onedrive-expose-onenote-files`** — makes yr OneNote files actually show up in directory listings 💅

  So by default rclone is lowkey hiding OneNote files from directory listings, bc operations like "Open" and "Update" just won't work on them. But that same behaviour can 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`** — <yellow>Deprecated: use `--server-side-across-configs` instead.</yellow>

  Lets server-side operations (like, say, `copy`) work *across different* onedrive configs. Iconic, but conditional bestie.

  It'll work if you're copying between two OneDrive Personal drives AND the files you're copying are already shared between them. It should also function for a user who has access permissions both between Onedrive for business and SharePoint under the same tenant, and between SharePoint and another SharePoint under the same tenant. In other cases tho, rclone falls back to a normal copy (which is slightly slower, ngl).

  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 creates versions when rclone uploads new files overwriting an existing one, and also when it sets the modification time. And those versions eat up space out of your quota, which is giving storage goblin energy fr.

  This flag checks for versions after file upload and after setting modification time, and removes all but the last version. Periodt.

  Properties:

  - Config: `no_versions`
  - Env Var: `RCLONE_ONEDRIVE_NO_VERSIONS`
  - Type: bool
  - Default: false

- **`--onedrive-hard-delete`** — permanently delete files on removal 💀

  Normally files get sent to the recycle bin when you delete them. Setting this flag makes them get permanently deleted instead. **Use with care** bestie, there is no undo arc here.

  This works with OneDrive for Business, SharePoint document libraries, and OneDrive personal accounts, including free accounts.

  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"`
      - Anyone with the link has access, without needing to sign in.
      - This may include people outside of your organization.
      - Anonymous link support may be disabled by an administrator.
    - `"organization"`
      - Anyone signed into your organization (tenant) can use the link to get access.
      - Only available in OneDrive for Business and SharePoint.

- **`--onedrive-link-type`** — 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.
      - Only available in OneDrive personal.

- **`--onedrive-link-password`** — sets the password for links created by the `link` command 🔐

  At the time of writing, this works with OneDrive for Business and OneDrive personal paid accounts.

  OneDrive personal free accounts can't set a password or an expiry time (with `--expire`) on links. Sorry to the free-tier girlies 💔

  Properties:

  - Config: `link_password`
  - Env Var: `RCLONE_ONEDRIVE_LINK_PASSWORD`
  - Type: string
  - Required: false

- **`--onedrive-hash-type`** — specify the hash in use for the backend 🧬

  This specifies the hash type in use. If set to `"auto"` it will use the default hash which is QuickXorHash.

  Before rclone 1.62 an SHA1 hash was used by default for Onedrive Personal. For 1.62 and later the default is to use a QuickXorHash for all onedrive types. If an SHA1 hash is desired then set this option accordingly.

  From July 2023 QuickXorHash will be the only available hash for both OneDrive for Business and OneDrive Personal.

  This can be set to `"none"` to not use any hashes.

  If the hash requested does not exist on the object, it will be returned as an empty string which is treated as a missing hash by rclone.

  Properties:

  - Config: `hash_type`
  - Env Var: `RCLONE_ONEDRIVE_HASH_TYPE`
  - Type: string
  - Default: `"auto"`
  - Examples:
    - `"auto"`
      - Rclone chooses the best hash
    - `"quickxor"`
      - QuickXor
    - `"sha1"`
      - SHA1
    - `"sha256"`
      - SHA256
    - `"crc32"`
      - CRC32
    - `"none"`
      - None - don't use any hashes

- **`--onedrive-av-override`** — allows download of files the server thinks has a virus 🦠

  The onedrive/sharepoint server may check files uploaded with an Anti Virus checker. If it detects any potential viruses or malware it will block download of the file.

  In this case you will see a message like this

server reports this file is infected with a virus - use --onedrive-av-override to download anyway: Infected (name of virus): 403 Forbidden:

If you are **100%** sure you want to download this file anyway then use the `--onedrive-av-override` flag, or `av_override = true` in the config file. (100% sure is a very high bar bestie, think about it first.)

When set, malware-flagged files are downloaded via Microsoft Graph beta APIs with `Prefer: forceInfectedDownload` (`contentStream`, then `/content`). Clean files continue to use the stable v1.0 endpoint.

> This is a beta API and may change. It works reliably with application permissions (`client_credentials`). With delegated (user) login on OneDrive for Business, Microsoft often still blocks the download. `tenant_url` configurations fall back to the legacy `AVOverride` query parameter.

Properties:

- Config: `av_override`
- Env Var: `RCLONE_ONEDRIVE_AV_OVERRIDE`
- Type: bool
- Default: false

- **`--onedrive-delta`** — if set, rclone will use delta listing to implement recursive listings ⚡

If this flag is set the onedrive backend will advertise `ListR` support for recursive listings.

Setting this flag speeds up these things **greatly**:

rclone lsf -R onedrive: rclone size onedrive: rclone rc vfs/refresh recursive=true

However the delta listing API only works at the root of the drive. If you use it not at the root then it recurses from the root and discards all the data that is not under the directory you asked for. So it will be correct but may not be very efficient. Correct but wasteful, it's giving overachiever with bad time management 😭

This is why this flag is not set as the default.

As a rule of thumb, if nearly all of your data is under rclone's root directory (the `root/directory` in `onedrive:root/directory`) then using this flag will be a big performance win. If your data is mostly not under the root then using this flag will be a big performance loss.

It is recommended if you are mounting your onedrive at the root (or near the root when using crypt) and using `rclone rc vfs/refresh`.

Properties:

- Config: `delta`
- Env Var: `RCLONE_ONEDRIVE_DELTA`
- Type: bool
- Default: false

- **`--onedrive-metadata-permissions`** — control whether permissions should be read or written in metadata 🔑

Reading permissions metadata from files can be done quickly, but it isn't always desirable to set the permissions from the metadata.

Properties:

- Config: `metadata_permissions`
- Env Var: `RCLONE_ONEDRIVE_METADATA_PERMISSIONS`
- Type: Bits
- Default: off
- Examples:
  - `"off"`
    - Do not read or write the value
  - `"read"`
    - Read the value only
  - `"write"`
    - Write the value only
  - `"read,write"`
    - Read and Write the value.
  - `"failok"`
    - If writing fails log errors only, don't fail the transfer

- **`--onedrive-encoding`** — the encoding for the backend ✨

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

- Config: `encoding`
- Env Var: `RCLONE_ONEDRIVE_ENCODING`
- Type: Encoding
- Default: `Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8,Dot`

- **`--onedrive-description`** — description of the remote 📝

Properties:

- Config: `description`
- Env Var: `RCLONE_ONEDRIVE_DESCRIPTION`
- Type: string
- Required: false

---

## 🗂️ Metadata 🗂️

OneDrive supports **System Metadata** (not User Metadata, as of this writing) for both files and directories. Much of the metadata is read-only, and there are some differences between OneDrive Personal and Business (see table below for details).

Permissions are also supported, if `--onedrive-metadata-permissions` is set. The accepted values for `--onedrive-metadata-permissions` are `"read"`, `"write"`, `"read,write"`, and `"off"` (the default). `"write"` supports adding new permissions, updating the `"role"` of existing permissions, and removing permissions. Updating and removing require the Permission ID to be known, so it is recommended to use `"read,write"` instead of `"write"` if you wish to update/remove permissions. (iykyk — know the ID or keep the read on 💅)

Permissions are read/written in JSON format using the same schema as the OneDrive API (https://learn.microsoft.com/en-us/onedrive/developer/rest-api/resources/permission?view=odsp-graph-online), which differs slightly between OneDrive Personal and Business.

Example for OneDrive Personal:

[ { "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" } ]

<rainbow>okay so writing permissions??</rainbow> 💅 yeah bestie, you literally pass in a `"permissions"` metadata key using this exact same format. no cap. And the `--metadata-mapper` tool (over at https://rclone.org/docs/#metadata-mapper) is <hotpink>so</hotpink> helpful for this, fr fr.

When you're adding permissions, you can drop an email address in the `User.ID` or `DisplayName` properties of `grantedTo` or `grantedToIdentities`. Orrr you can hand over an `ObjectID` in `User.ID`. Either way: <yellow>at least one valid recipient must be provided</yellow> in order to add a permission for a user. ✨ And 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"]}]" } }

> 😭 heads up bestie: adding a permission can <bold>fail</bold> if a conflicting permission already exists for the file/folder. rude, but that's the vibe.

To update an existing permission, include both the Permission ID *and* the new roles to be assigned. And listen — `roles` is literally the **only** property that can be changed. periodt.

To remove permissions, pass in a blob containing only the permissions you wish to keep (which can be empty, to remove all of them 🫶). Note that the `owner` role will be ignored, as it cannot be removed. iconic but untouchable, iykyk.

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 omit `--onedrive-metadata-permissions`. save yourself the drama, babe.

Metadata and permissions are supported for Folders (directories) as well as Files. Note that setting the `mtime` or `btime` on a Folder requires one extra API call on OneDrive Business **only**.

OneDrive does not currently support User Metadata. When writing metadata, only writeable system properties will be written — any read-only or unrecognized keys passed in will be ignored. 💀

TIP: to see the metadata and permissions for any file or folder, run:

rclone lsjson remote:path --stat -M --onedrive-metadata-permissions read

Here are the possible system metadata items for the onedrive backend. 👑

- **`btime`** — Time of file birth (creation) with S accuracy. 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`** — Display name of the user that created the item. Type: string. Example: `John Doe`. Read Only: **Y**.
- **`created-by-id`** — ID of the user that created the item. Type: string. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read Only: **Y**.
- **`description`** — A short description of the file. Max 1024 characters. No longer supported by Microsoft. 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`** — Display name of the user that last modified the item. Type: string. Example: `John Doe`. Read Only: **Y**.
- **`last-modified-by-id`** — ID of the user that last modified the item. Type: string. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read Only: **Y**.
- **`malware-detected`** — Whether OneDrive has detected that the item contains malware. Type: boolean. Example: `true`. Read Only: **Y**.
- **`mtime`** — Time of last modification with S accuracy. Type: RFC 3339. Example: `2006-01-02T15:04:05Z`. Read Only: **N**.
- **`package-type`** — If present, indicates that this item is a package instead of a folder or file. Packages are treated like files in some contexts and folders in others. Type: string. Example: `oneNote`. Read Only: **Y**.
- **`permissions`** — Permissions in a JSON dump of OneDrive format. Enable with `--onedrive-metadata-permissions`. Properties: `id`, `grantedTo`, `grantedToIdentities`, `invitation`, `inheritedFrom`, `link`, `roles`, `shareId`. Type: JSON. Example: `{}`. Read Only: **N**.
- **`shared-by-id`** — ID of the user that shared the item (if shared). Type: string. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read Only: **Y**.
- **`shared-owner-id`** — ID of the owner of the shared item (if shared). Type: string. Example: `48d31887-5fad-4d73-a9f5-3c356e68a038`. Read Only: **Y**.
- **`shared-scope`** — If shared, indicates the scope of how the item is shared: `anonymous`, `organization`, or `users`. Type: string. Example: `users`. Read Only: **Y**.
- **`shared-time`** — Time when the item was shared, with S accuracy. Type: RFC 3339. Example: `2006-01-02T15:04:05Z`. Read Only: **Y**.
- **`utime`** — Time of upload with S accuracy. Type: RFC 3339. Example: `2006-01-02T15:04:05Z`. Read Only: **Y**.

See the metadata docs for more info: https://rclone.org/docs/#metadata 🌸

---

### Impersonate other users as Admin 👑

So unlike Google Drive and impersonating any domain user via service accounts, OneDrive requires you to authenticate as an <bold>admin account</bold>, and manually set up a remote per user you wish to impersonate. it's giving extra steps but we ball. 🧚

1. In Microsoft 365 Admin Center (https://admin.microsoft.com), open each user you need to "impersonate" and go to the OneDrive section. There is a heading called "Get access to files", you need to click to create the link, this creates the link of the format `https://{tenant}-my.sharepoint.com/personal/{user_name_domain_tld}/` but also changes the permissions so you your admin user has access.

2. Then in powershell run the following commands:

Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force Import-Module Microsoft.Graph.Files Connect-MgGraph -Scopes "Files.ReadWrite.All"

Follow the steps to allow access to your admin user

Then run this for each user you want to impersonate to get the Drive ID

Get-MgUserDefaultDrive -UserId '{emailaddress}'

This will give you output of the format:

Name Id DriveType CreatedDateTime

---- -- --------- ---------------

OneDrive b!XYZ123 business 14/10/2023 1:00:58 pm

3. Then in rclone add a onedrive remote type, and use the Type in driveID with the DriveID you got in the previous step. One remote per user. It will then confirm the drive ID, and hopefully give you a message of `Found drive "root" of type "business"` and then include the URL of the format `https://{tenant}-my.sharepoint.com/personal/{user_name_domain_tld}/Documents` 💖

### Limitations 😭

If you don't use rclone for 90 days the refresh token will expire. This will result in authorization problems. This is easy to fix by running the `rclone config reconnect remote:` command to get a new token and refresh token. slay, problem solved.

### Naming 🎀

Note that OneDrive is case insensitive so you can't have a file called `"Hello.doc"` and one called `"hello.doc"`. pick a lane bestie.

There are quite a few characters that can't be in OneDrive file names. These can't occur on Windows platforms, but on non-Windows platforms they are common. Rclone will map these names to and from an identical looking unicode equivalent. For example if a file has a `?` in it will be mapped to `？` instead. ✨🦋

## File sizes 💾

Biggest file you can possibly yeet up in here? **250 GiB** — same for both OneDrive Personal and OneDrive for Business (Updated 13 Jan 2021) (https://support.microsoft.com/en-us/office/invalid-file-names-and-file-types-in-onedrive-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa?ui=en-us&rs=en-us&ad=us#individualfilesize).

## Path length 📏

Okay so the **entire** path — filename included — has to be **fewer than 400 characters** for OneDrive, OneDrive for Business and SharePoint Online. And if you're out here encrypting file and folder names with rclone, bestie, pay attention to this one, because encrypted names are typically *longer* than the original ones and they will absolutely blow past that limit 💀

## Number of files 🗂️

OneDrive seems to be OK with at least **50,000 files** in a folder, no cap. But at **100,000** rclone will get errors listing the directory like `couldn't list files: UnknownError:`. See #2707 (https://github.com/rclone/rclone/issues/2707) for more info.

An official document about the limitations for different types of OneDrive can be found here (https://support.office.com/en-us/article/invalid-file-names-and-file-types-in-onedrive-onedrive-for-business-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa).

## Versions 🌀

Every single change in a file makes OneDrive go "new version, who dis" and create a fresh version of that file. And that counts against a user's quota, so it's not free real estate. For example, changing the modification time of a file creates a **second version**, so the file apparently uses *twice* the space. Not a vibe.

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. Heads up though: this takes extra transactions, so only enable it if you actually need it.

## Disabling versioning 🙈

Starting October 2018, users will no longer be able to disable versioning by default. This is because Microsoft has brought an update (https://techcommunity.microsoft.com/t5/Microsoft-OneDrive-Blog/New-Updates-to-OneDrive-and-SharePoint-Team-Site-Versioning/ba-p/204390) to the mechanism. To change this new default setting, a PowerShell command is required to be run by a SharePoint admin. If you are an admin, you can run these commands in PowerShell to change that setting:

1. `Install-Module -Name Microsoft.Online.SharePoint.PowerShell` (in case you haven't installed this already)

2. `Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking`

3. `Connect-SPOService -Url https://YOURSITE-admin.sharepoint.com -Credential YOU@YOURSITE.COM` (replacing `YOURSITE`, `YOU`, `YOURSITE.COM` with the actual values; this will prompt for your credentials)

4. `Set-SPOTenant -EnableMinimumVersionRequirement $False`

5. `Disconnect-SPOService` (to disconnect from the server)

Below are the steps for normal users to disable versioning. If you don't see the "No Versioning" option, make sure the above requirements are met.

User Weropol (https://github.com/Weropol) has found a method to disable versioning on OneDrive:

1. Open the settings menu by clicking on the gear symbol at the top of the OneDrive Business page.

2. Click **Site settings**.

3. Once on the Site settings page, navigate to **Site Administration** > **Site libraries and lists**.

4. Click **Customize "Documents"**.

5. Click **General Settings** > **Versioning Settings**.

6. Under **Document Version History** select the option **No versioning**. Note: This will disable the creation of new file versions, but will not remove any previous versions. Your documents are safe. 🫶

7. Apply the changes by clicking **OK**.

8. Use rclone to upload or modify files. (I also use the `--no-update-modtime` flag)

9. Restore the versioning settings after using rclone. (Optional)

## Cleanup 🧹

OneDrive supports `rclone cleanup`, which causes rclone to look through every file under the path supplied and delete all versions but the current version. Because this involves traversing all the files, then querying each file for versions, it can be quite slow, ngl. Rclone does `--checkers` tests in parallel, which helps. The command also supports `--interactive`/`-i` or `--dry-run`, which is a *great* way to see what it would do before you commit 💅

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

## Troubleshooting 🚨

### Excessive throttling or blocked on SharePoint

If you experience excessive throttling or is being blocked on SharePoint then it may help to set the user agent explicitly with a flag like this: `--user-agent "ISV|rclone.org|rclone/v1.55.1"`

The specific details can be found in the Microsoft document: Avoid getting throttled or blocked in SharePoint Online (https://docs.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online#how-to-decorate-your-http-traffic-to-avoid-throttling)

### Unexpected file size/hash differences on Sharepoint

It is a known (https://github.com/OneDrive/onedrive-api-docs/issues/935#issuecomment-441741631) issue that Sharepoint (**not** OneDrive or OneDrive for Business) silently modifies uploaded files, mainly Office files (`.docx`, `.xlsx`, etc.), causing file size and hash checks to fail. There are also other situations that will cause OneDrive to report inconsistent file sizes. To use rclone with such affected files on Sharepoint, you may disable these checks with the following command line arguments:

--ignore-checksum --ignore-size

Alternatively, if you have write access to the OneDrive files, it may be possible to fix this problem for certain files, by attempting the steps below. Open the web interface for OneDrive (https://onedrive.live.com) and find the affected files (which will be in the error messages/log for rclone). Simply click on each of these files, causing OneDrive to open them on the web. This will cause each file to be converted in place to a format that is functionally equivalent but which will no longer trigger the size discrepancy. Once all problematic files are converted you will no longer need the ignore options above. Slay ✨

### Replacing/deleting existing files on Sharepoint gets "item not found"

It is a known (https://github.com/OneDrive/onedrive-api-docs/issues/1068) issue that Sharepoint (**not** OneDrive or OneDrive for Business) may return "item not found" errors when users try to replace or delete uploaded files; this seems to mainly affect Office files (`.docx`, `.xlsx`, etc.) and web files (`.html`, `.aspx`, etc.). As a workaround, you may use the `--backup-dir <BACKUP_DIR>` command line argument so rclone moves the files to be replaced/deleted into a given backup directory (instead of directly replacing/deleting them). For example, to instruct rclone to move the files into the directory `rclone-backup-dir` on backend `mysharepoint`, you may use:

--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 that rclone can't use the OneDrive for Business API with your account. You can't do much about it, maybe write an email to your admins. ✉️

However, there are other ways to interact with your OneDrive account. Have a look at the WebDAV backend: <https://rclone.org/webdav/#sharepoint>

### invalid_grant (AADSTS50076)

Error: invalid_grant Code: AADSTS50076 Description: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '...'.

If you see the error above after enabling multi-factor authentication for your account, you can fix it by refreshing your OAuth refresh token. To do that, run `rclone config`, and choose to edit your OneDrive backend. Then, you don't need to actually make any changes until you reach this question: `Token already configured - replace it?`. 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. Iconic behavior tbh 👑

### Invalid request when making public links

On Sharepoint and OneDrive for Business, `rclone link` may return an "Invalid request" error. A possible cause is that the organisation admin didn't allow public links to be made for the organisation/sharepoint library. To fix the permissions as an admin, take a look at the docs: 1 (https://docs.microsoft.com/en-us/sharepoint/turn-external-sharing-on-or-off), 2 (https://support.microsoft.com/en-us/office/set-up-and-manage-access-requests-94b26e0b-2822-49d4-929a-8455698654b3).

### Can not access Shared with me files

**Shared with me files** is not supported by rclone currently (https://github.com/rclone/rclone/issues/4062), but there is a workaround:

1. Visit https://onedrive.live.com (https://onedrive.live.com/)

2. Right click a item in **Shared**, then click **Add shortcut to My files** in the context [IMAGE: make_shortcut (https://user-images.githubusercontent.com/60313789/206118040-7e762b3b-aa61-41a1-8649-cc18889f3572.png)]

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 (https://i.imgur.com/0S8H3li.png)] [IMAGE: rclone_mount (https://i.imgur.com/2Iq66sW.png)]

Listing such a shortcut may still fail with

invalidRequest: The provided drive id appears to be malformed, or does not represent a valid drive.

as the drive it points to can't always be read with the drive ID the API supplies. Personal Vault is a shortcut of the same kind and fails to list in the same way, though it reports `invalidResourceId: ObjectHandle is Invalid`.

A normal listing reports the error for that folder and carries on, so the rest of the drive is still listed, and excluding the folder (for example with `--exclude "/Personal Vault/**"`) avoids the error.

A recursive listing with `--fast-list` stops at the first error, so listing the root of a drive which has one of these shortcuts in it will fail. Filters don't help here as the folder is listed by the backend before the filters are applied — use `--disable ListR` (or don't use `--fast-list`) on such a drive.

## 💖 Live Photos uploaded from iOS (small video clips in .heic files) 💖

okay so back in 2020 the iOS OneDrive app introduced uploading and storing Live Photos (links: `https://techcommunity.microsoft.com/t5/microsoft-onedrive-blog/live-photos-come-to-onedrive/ba-p/1953452` and `https://support.apple.com/en-gb/HT207310`). And bestie, the <pink>usage and download</pink> of those uploaded Live Photos is *still* work-in-progress, which introduces several issues when copying, synchronising and mounting — both in rclone and in the native OneDrive client on Windows. 😭

The root cause is so easy to see. Locate one of your Live Photos in the OneDrive web interface, then download the photo from the web interface. The size of the downloaded `.heic` file is <hotpink>smaller</hotpink> than the size displayed in the web interface. Why? Because the downloaded file only contains a single frame (a still photo) extracted from the Live Photo (a movie) stored in OneDrive. it's giving scam but it's just Microsoft 💀

Those different sizes make rclone copy/sync 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)

You can work around these recopies by adding `--ignore-size`. <yellow>Please note</yellow> that this workaround only syncs the still-picture, <bold>not</bold> the movie clip, and it relies on modification dates being correctly updated on all files in all situations. 👀

The different sizes will also make `rclone check` 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 make `rclone mount` 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 ✨🚗

Paths are specified as `remote:path`

Paths may be as deep as required, e.g. `remote:directory/subdirectory`.

## 🛠️ 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:

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

List directories in top level of your OpenDrive

rclone lsd remote:

List all the files in your OpenDrive

rclone ls remote:

To copy a local directory to an OpenDrive directory called `backup`

rclone copy /home/source remote:backup

## ⏰ Modification times and hashes ⏰

OpenDrive lets modification times be set on objects, accurate to 1 second. These will be used to detect whether objects need syncing or not. 🕐

The <cyan>MD5</cyan> hash algorithm is supported. 💖

## 🚫 Restricted filename characters 🚫

Character · Value · Replacement

- `NUL` — `0x00` → `␀`
- `/` — `0x2F` → `／`
- `"` — `0x22` → `＂`
- `*` — `0x2A` → `＊`
- `:` — `0x3A` → `：`
- `<` — `0x3C` → `＜`
- `>` — `0x3E` → `＞`
- `?` — `0x3F` → `？`
- `\` — `0x5C` → `＼`
- `|` — `0x7C` → `｜`

File names also <bold>can't begin or end</bold> with the following characters. These only get replaced if they are the first or last character in the name:

- `SP` — `0x20` → `␠`
- `HT` — `0x09` → `␉`
- `LF` — `0x0A` → `␊`
- `VT` — `0x0B` → `␋`
- `CR` — `0x0D` → `␍`

Invalid UTF-8 bytes will also be replaced (`https://rclone.org/overview/#invalid-utf8`), because they can't be used in JSON strings. periodt 🌈

## ⚙️ Standard options ⚙️

Here are the Standard options 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` (`https://rclone.org/commands/rclone_obscure/`).

Properties:

- Config: `password`
- Env Var: `RCLONE_OPENDRIVE_PASSWORD`
- Type: `string`
- Required: `true`

## 🔥 Advanced options 🔥

Here are the Advanced options specific to `opendrive` (OpenDrive).

### `--opendrive-encoding`

The encoding for the backend.

See the encoding section in the overview (`https://rclone.org/overview/#encoding`) 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-access`

Files and folders will be uploaded with this access permission (default private)

Properties:

- Config: `access`
- Env Var: `RCLONE_OPENDRIVE_ACCESS`
- Type: `string`
- Default: `"private"`
- Examples:
  - `"private"`
    - The file or folder access can be granted in a way that will allow select users to view, read or write what is absolutely essential for them.
  - `"public"`
    - The file or folder can be downloaded by anyone from a web browser. The link can be shared in any way,
  - `"hidden"`
    - The file or folder can be accessed has the same restrictions as Public if the user knows the URL of the file or folder link in order to access the contents

### `--opendrive-description`

Description of the remote.

Properties:

- Config: `description`
- Env Var: `RCLONE_OPENDRIVE_DESCRIPTION`
- Type: `string`
- Required: `false`

## 😬 Limitations 😬

So OpenDrive is <red>case insensitive</red>, which means you can't have a file called `"Hello.doc"` and one called `"hello.doc"` at the same time. ngl, rude.

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, it will be mapped to `？` instead. 🎀

`rclone about` is <bold>not supported</bold> 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 (`https://rclone.org/overview/#optional-features`) and `rclone about` (`https://rclone.org/commands/rclone_about/`).

---

# 👑 Oracle Object Storage 👑

Object Storage provided by the Oracle Cloud Infrastructure (OCI). Read more at `oracle.com`:

- Oracle Object Storage Overview (`https://docs.oracle.com/iaas/Content/Object/Concepts/objectstorageoverview.htm`)
- Oracle Object Storage FAQ (`https://www.oracle.com/cloud/storage/object-storage/faq/`)

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's 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

bestie you just watched a whole config wizard speedrun itself 😭💖 that's the whole Q&A flow, numbers and all.

---

See all buckets — the vibe check on what's already out there 👀

rclone lsd remote:

Create a new bucket — new bucket, who dis 🪣✨

rclone mkdir remote:bucket

List the contents of a bucket — and yes you can keep it shallow if the nesting is doing too much 🌊

rclone ls remote:bucket
rclone ls remote:bucket --max-depth 1

---

Authentication Providers 🪪✨

OCI ships with several authentication methods, and honestly, picking one is giving choose your fighter. Wanna learn more about them? Go read the docs, bestie: oci authentication methods (https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm).

These choices can be specified in the rclone config file. Periodt.

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:

• One can use this method from any server within OCI or on-premises or from other cloud provider.

Considerations:

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

⚠️ read that last one again bestie. if that user gets yeeted, the config file is cooked and any automation leaning on those credentials just goes down with it. no cap.

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 no credentials have to be stored and managed. (iconic behaviour honestly ✨)

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.
• It is applicable for oci compute instances only. It cannot be used on external instance or resources.

👀 "everyone who has access to this machine" — yeah, that's a whole trust exercise. know who's on your box.

Resource Principal 🍓🧩

Resource principal auth is very similar to instance principal auth but used for resources that are not compute instances such as serverless functions (https://docs.oracle.com/en-us/iaas/Content/Functions/Concepts/functionsoverview.htm). 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 (https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm). 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. 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 metadata on the object as opc-meta-mtime as floating point since the epoch, accurate to 1 ns.

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.

The MD5 hash algorithm is supported.

🫠 heads up: that extra HEAD request per read? it's a real cost, not a vibe. and those past-5Gb files are getting a full upload, not a cheeky copy — plan accordingly.

---

Multipart uploads 🧩🔥

rclone supports multipart uploads with OOS which means that it can upload files bigger than 5 GiB. yesss big files, we love to see it.

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.

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.

💀 do the math on that memory formula before you crank the concurrency to like 64, bestie. --transfers * --oos-upload-concurrency * --oos-chunk-size is not a suggestion, it's a bill your RAM is gonna have to pay.

---

Standard options ⭐🎀

Here are the Standard options specific to oracleobjectstorage (Oracle Cloud Infrastructure Object Storage).

--oos-provider 🔐

Choose your Auth Provider

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 🗂️
  • Config: namespace
  • Env Var: RCLONE_OOS_NAMESPACE
  • Type: string
  • Required: true
• --oos-compartment — Specify compartment OCID, if you need to list buckets.

Listing objects works without a compartment OCID, bestie — but the moment you wanna list buckets you need it. 💅

• Config: compartment
• Env Var: RCLONE_OOS_COMPARTMENT
• Provider: !no_auth
• Type: string
• Required: false

• --oos-region — Object storage Region 🌍
  • Config: region
  • Env Var: RCLONE_OOS_REGION
  • Type: string
  • Required: true
• --oos-endpoint — Endpoint for Object storage API.

Leave it blank and rclone just uses the default endpoint for the region, no stress. ✨

• Config: endpoint
• Env Var: RCLONE_OOS_ENDPOINT
• Type: string
• Required: false

• --oos-config-file — Path to OCI config file 📄
  • 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 🎀
  • 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 ✨

Ok so these are the Advanced options specific to oracleobjectstorage (Oracle Cloud Infrastructure Object Storage). The main character options, fr fr. 🫶

---

• --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
  • 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 get uploaded in chunks of chunk_size. The minimum is 0 and the maximum is 5 GiB. No cap.

• Config: upload_cutoff
• Env Var: RCLONE_OOS_UPLOAD_CUTOFF
• Type: SizeSuffix
• Default: 200Mi

• --oos-chunk-size — Chunk size to use for uploading. 🧩

When you're uploading files larger than upload_cutoff, or files with unknown size (like, say, from rclone rcat, or ones uploaded with rclone mount) they get uploaded as multipart uploads using this chunk size.

Heads up: upload_concurrency chunks of this size are buffered in memory per transfer. So yeah, it's giving RAM.

If you're 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. 😭

• Config: chunk_size
• Env Var: RCLONE_OOS_CHUNK_SIZE
• Type: SizeSuffix
• Default: 5Mi

• --oos-max-upload-parts — Maximum number of parts in a multipart upload. 🧮

This option defines the maximum number of multipart chunks to use when doing a multipart upload.

OCI has max parts limit of 10,000 chunks.

Rclone will automatically increase the chunk size when uploading a large file of a known size to stay below this number of chunks limit.

• Config: max_upload_parts
• Env Var: RCLONE_OOS_MAX_UPLOAD_PARTS
• Type: int
• Default: 10000

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

• Config: upload_concurrency
• Env Var: RCLONE_OOS_UPLOAD_CONCURRENCY
• Type: int
• Default: 10

• --oos-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 5 GiB.

• Config: copy_cutoff
• Env Var: RCLONE_OOS_COPY_CUTOFF
• Type: SizeSuffix
• Default: 4.656Gi

• --oos-copy-timeout — Timeout for copy. ⏳

Copy is an asynchronous operation, so specify a timeout to wait for the copy to succeed.

• Config: copy_timeout
• Env Var: RCLONE_OOS_COPY_TIMEOUT
• Type: Duration
• Default: 1m0s

• --oos-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 add it to metadata on the object. This is great for data integrity checking but can cause long delays for large files to start uploading.

• 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 (https://rclone.org/overview/#encoding) for more info.

• 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 successfully uploaded parts for manual recovery. 💀

It should be set to true for resuming uploads across different sessions.

WARNING: Storing parts of an incomplete multipart upload counts towards space usage on object storage and will add additional costs if not cleaned up. Not the vibe, bestie. 🚨

• 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 previously started multipart upload for the object. This will be helpful to speed up multipart transfers by resuming uploads from a past session. ⏪

WARNING: If chunk size differs in the resumed session from the past incomplete session, then the resumed multipart upload is aborted and a new multipart upload is started with the new chunk size. 😱

The flag leave_parts_on_error must be true to resume and optimize to skip parts that were already uploaded successfully.

• Config: attempt_resume_upload
• Env Var: RCLONE_OOS_ATTEMPT_RESUME_UPLOAD
• Type: bool
• Default: false

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

• 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.'
  • 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 information, see Using Your Own Keys for Server-Side Encryption (https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm)
  • Config: sse_customer_key
  • Env Var: RCLONE_OOS_SSE_CUSTOMER_KEY
  • Type: string
  • Required: false
  • Examples:
    • ""
      • None
• --oos-sse-customer-key-sha256 — If 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). 🧾
  • 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 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 used to call the Key Management service to generate a data encryption key or to encrypt or decrypt a data encryption key. 🗝️ Please note only one of sse_customer_key_file|sse_customer_key|sse_kms_key_id is needed.
  • Config: sse_kms_key_id
  • Env Var: RCLONE_OOS_SSE_KMS_KEY_ID
  • Type: string
  • Required: false
  • Examples:
    • ""
      • None

okay bestie we're back in Oracle Object Storage land and we are still going through flags ✨ buckle up, we're basically fluent in OOS now 💅

---

• --oos-sse-customer-algorithm — bestie if you're doing SSE-C, this is the optional header that says the encryption algorithm is "AES256". Object Storage supports "AES256" as the encryption algorithm. For more deets, go read Using Your Own Keys for Server-Side Encryption at https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm 🫶

Properties, no skipping:

• Config: sse_customer_algorithm
• Env Var: RCLONE_OOS_SSE_CUSTOMER_ALGORITHM
• Type: string
• Required: false
• Examples:
  • ""
    • None
  • "AES256"
    • AES256

• --oos-decompress — set this and rclone will decompress gzip encoded objects 🫧

So here's the situation: you can upload objects to object storage with Content-Encoding: gzip set on them. Normally rclone will just download those files as compressed objects, no biggie.

But if this flag is on, rclone decompresses these files with Content-Encoding: gzip as they arrive. Which sounds iconic until you remember — because of that, rclone can't check the size and hash 😭 but the file contents will be decompressed. Tradeoffs, bestie.

Properties:

• Config: decompress
• Env Var: RCLONE_OOS_DECOMPRESS
• Type: bool
• Default: false

• --oos-description — a lil description of the remote, so future you remembers what this thing even is 💖

Properties:

• Config: description
• Env Var: RCLONE_OOS_DESCRIPTION
• Type: string
• Required: false

🌸 Metadata 🌸

User metadata is stored as opc-meta- keys. Not me being obsessed with prefix naming conventions, but periodt.

Here are the possible system metadata items for the oracleobjectstorage backend:

• opc-meta-atime — Time of last access. Type: ISO 8601. Example: 2025-06-30T22:27:43-04:00. Read Only: N
• opc-meta-btime — Time of file birth (creation). Type: ISO 8601. Example: 2025-06-30T22:27:43-04:00. Read Only: N
• opc-meta-gid — Group ID of owner. Type: decimal number. Example: 500. Read Only: N
• opc-meta-mode — File type and mode. Type: octal, unix style. Example: 0100664. Read Only: N
• opc-meta-mtime — Time of last modification. Type: ISO 8601. Example: 2025-06-30T22:27:43-04:00. Read Only: N
• opc-meta-uid — User ID of owner. Type: decimal number. Example: 500. Read Only: N

See the metadata docs at https://rclone.org/docs/#metadata for more info 💜

---

🎀 Backend commands 🎀

Here are the commands specific to the oracleobjectstorage backend. It's giving custom, it's giving exclusive 🔥

Run them with:

rclone backend COMMAND remote:

The help below explains what arguments each command takes.

See the backend command at https://rclone.org/commands/rclone_backend/ for more info on how to pass options and arguments.

These can be run on a running backend using the rc command backend/command — docs at https://rclone.org/rc/#backend-command ✨

rename

change the name of an object. very demure, very mindful 🎀

rclone backend rename remote: [options] [<arguments>+]

This command can be used to rename a object.

Usage example:

rclone backend rename oos:bucket relative-object-path-under-bucket object-new-name

list-multipart-uploads

List the unfinished multipart uploads. the messy ones. we're calling them out 💀

rclone backend list-multipart-uploads remote: [options] [<arguments>+]

This command lists the unfinished multipart uploads in JSON format.

Usage example:

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 bucket, with a bucket or with a bucket and 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. spring cleaning era 🧹✨

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.

Usage examples:

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. bring them back from the archives bestie, main character resurrection arc 👑

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 — please please please test first 🙈

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 — head to https://rclone.org/oracleobjectstorage/tutorial_mount/ and get you some 🦋

✨ QingStor ✨

Bestie, paths are literally remote:bucket (or just remote: if you're doing the lsd command, cute). You can tuck subdirectories in there too, like remote:bucket/path/to/dir 🫶

---

🌈 Configuration

Okay so here's how you make a QingStor config. First, run:

rclone config

It's giving guided tour, and it'll walk you through the whole interactive setup. Look:

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 all over the place, like so 💅

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 (periodt):

rclone sync --interactive /home/local/directory remote:bucket

---

🦋 --fast-list

This remote is on the --fast-list roster, meaning you can use fewer transactions in exchange for more memory. It's giving trade-off, and if you want the tea, go read the rclone docs at https://rclone.org/docs/#fast-list 🔥

---

🎀 Multipart uploads

rclone supports multipart uploads with QingStor, which means it can upload files bigger than 5 GiB. Not to be dramatic but that's iconic. Just know that files uploaded with multipart upload don't have an MD5SUM — that's just how it is, no cap 😭

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 buckets. And here's the thing: QingStor does not ever remove incomplete multipart uploads, so you may need to run this from time to time. Like, housekeeping bestie, don't skip it 🧹

---

🌸 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. Which is lowkey annoying but that's the vibe. If you try to access a bucket from the wrong zone you'll get an error: incorrect zone, the bucket is not in 'XXX' zone. Rude, but noted 💀

---

💜 Authentication

There are two ways to hand rclone 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, just like in the default restricted characters set (https://rclone.org/overview/#restricted-characters). Heads up though: 0x7F is not replaced. 🙈

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), because they literally can't be used in JSON strings. Slay for safety.

---

👑 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. Main character energy for the auth flow.

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. Keep it secret, keep it safe bestie 🤫

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. Because sometimes the internet is not giving 🫠

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. Fire 🔥

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). Not a drill, bestie 😭

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 (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_QINGSTOR_ENCODING
• Type: Encoding
• Default: Slash,Ctl,InvalidUtf8

--qingstor-description

Description of the remote. Just a lil label for your baby ✨

Properties:

• Config: description
• Env Var: RCLONE_QINGSTOR_DESCRIPTION
• Type: string
• Required: false

---

💀 Limitations

rclone about is not supported by the qingstor backend. Which means backends without this capability can't determine free space for an rclone mount, and can't use policy mfs (most free space) as a member of an rclone union remote. Sad but true 😭

See List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

💖 Quatrix 💖

Quatrix by Maytech is Quatrix Secure Compliant File Sharing | Maytech (https://www.maytech.net/products/quatrix-business).

Paths are specified as remote:path

Paths may be as deep as required, e.g., remote:directory/subdirectory.

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 a lil 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 you've configured it you can then use rclone like this (replace remote with the name you gave your remote, bestie 💅):

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

API Key is created with no expiration date. 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.

$ rclone config
Current remotes:

Name                 Type
====                 ====
remote               quatrix

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: 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 1 microsecond. These will be used to detect whether objects need syncing or not. So precise, we love that ✨

Quatrix does not support hashes, so you cannot use the --checksum flag. That's just how it is, fr fr 😭

---

🚫 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 cannot be equal to . or .. nor contain / , \ or non-printable ascii.

---

📤 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. 🧠✨

---

🗑️ Deleting files

Files you delete with rclone will end up in Trash 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. Iconic behavior honestly 👑

---

⚙️ Standard options

Here are the Standard options specific to quatrix (Quatrix by Maytech).

--quatrix-api-key

API key for accessing Quatrix account

Properties:

• Config: api_key
• Env Var: RCLONE_QUATRIX_API_KEY
• Type: string
• Required: true

--quatrix-host

Host name of Quatrix account

Properties:

• 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 (https://rclone.org/overview/#encoding) for more info.

Properties:

• 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

Properties:

• 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

Properties:

• 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 not be less than 'transfers'*'minimal_chunk_size'

Properties:

• 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

Properties:

• Config: hard_delete
• Env Var: RCLONE_QUATRIX_HARD_DELETE
• Type: bool
• Default: false

--quatrix-skip-project-folders

Skip project folders in operations

Properties:

• Config: skip_project_folders
• Env Var: RCLONE_QUATRIX_SKIP_PROJECT_FOLDERS
• Type: bool
• Default: false

--quatrix-description

Description of the remote.

Properties:

• 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 will fail. This can be fixed by freeing up the space or increasing the quota. ✨

okay so if your uploads are suddenly failing, it's probably the quota. free up space or bump it, bestie, no biggie 🫶

---

🤝 Server-side operations

Quatrix supports server-side operations (copy and move). In case of conflict, files are overwritten during server-side operation. The way that everything just moves on the server side? obsessed 💅🦋

🦋 Sia 🦋

Sia (sia.tech (<https://sia.tech/>)) is a decentralized cloud storage platform built on top of blockchain (<https://wikipedia.org/wiki/Blockchain>) technology. bestie, with rclone you can just use it like any other remote filesystem, or even mount Sia folders right on your local machine. the tech behind it involves a whole bunch of new concepts — Siacoins and Wallet, Blockchain and Consensus, Renting and Hosting, and so on. if you're new to all this, lowkey please go familiarise yourself first using their excellent support documentation (<https://support.sia.tech/>). it's giving homework but it's worth it bestie. 💖

✨ Introduction ✨

Before you can use rclone with Sia, you'll need a running copy of Sia-UI or siad (the Sia daemon) locally on your computer or on your local network (e.g. a NAS). pls follow the Get started (<https://sia.tech/get-started>) guide and install one of them. no skipping, fr fr.

rclone interacts with the Sia network by talking to the Sia daemon via HTTP API (<https://docs.sia.tech/>), which is usually available on port 9980. by default you'll be running the daemon locally on the same computer, so it's totally safe to leave the API password blank — the API URL will be http://127.0.0.1:9980, which makes external access impossible. iconic security-by-default behaviour, we love to see it. 💅

However, if you want to access a Sia daemon running on another node — for example because of memory constraints, or because you want to share a 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 (<https://github.com/SiaFoundation/siad/pkgs/container/siad>) because Sia-UI does not support this mode natively.
• Run it on an 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, read these, they matter:

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. 🔥
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.

🚨 okay so note 3 is the "please don't" one. running without an API password is insecure and strongly discouraged. do not do the thing. the vibes are bad on that one, periodt.

🌸 Configuration 🌸

Here's 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 (<https://rclone.org/commands/rclone_obscure/>).

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. yes it's literally checking your ID at the door. 💅

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 (<https://rclone.org/overview/#encoding>) 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 (<https://rclone.org/overview/#encoding>) them for you, but you'd better be aware. 👀

---

🦋 Swift 🦋

Swift refers to OpenStack Object Storage (<https://docs.openstack.org/swift/latest/>). Commercial implementations of that being:

• Rackspace Cloud Files (<https://www.rackspace.com/cloud/files/>)
• Memset Memstore (<https://www.memset.com/cloud/storage/>)
• OVH Object Storage (<https://www.ovhcloud.com/en/public-cloud/object-storage/>)
• Oracle Cloud Storage (<https://docs.oracle.com/en-us/iaas/integration/doc/configure-object-storage.html>)
• Blomp Cloud Storage (<https://www.blomp.com/cloud-storage/>)
• IBM Bluemix Cloud ObjectStorage Swift (<https://console.bluemix.net/docs/infrastructure/objectstorage-swift/index.html>)

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. no cap, that's the whole path vibe. 🫶

🌸 Configuration 🌸

Here's an example of making a swift configuration. First run

rclone config

This will guide you through an interactive setup process.

okay bestie, buckle up, because this is what the whole thing looks like when you actually run it 💅

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 /home/local/directory to the remote container, deleting any excess files in the container.

rclone sync --interactive /home/local/directory remote:container

---

🌸 Configuration from an OpenStack credentials file 🌸

An OpenStack credentials file typically looks something like this (without the comments, bestie — the comments are for us)

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

The config file needs to look something like this, where $OS_USERNAME represents the value of the OS_USERNAME variable — 123abc567xy in the example above. Slay 💅

[remote]
type = swift
user = $OS_USERNAME
key = $OS_PASSWORD
auth = $OS_AUTH_URL
tenant = $OS_TENANT_NAME

ngl, you may (or may not) need to set region too — try without it first, fr fr.

---

🦋 Configuration from the environment 🦋

If you prefer, you can configure rclone to use swift using a standard set of OpenStack environment variables. Main character energy ✨

When you run through the config, make sure you choose true for env_auth and leave everything else blank. That's the whole vibe.

rclone will then set any empty config parameters from the environment using standard OpenStack environment variables. There is a list of the variables in the docs for the swift library: https://godoc.org/github.com/ncw/swift#Connection.ApplyEnvironment

---

🔥 Using an alternate authentication method 🔥

If your OpenStack installation uses a non-standard authentication method that might not be yet supported by rclone or the underlying swift library, you can authenticate externally (like, calling the openstack commands manually to get a token, iykyk). Then you just need to pass the two configuration variables auth_token and storage_url. If they are both provided, the other variables are ignored — rclone will not try to authenticate, but instead assume it is already authenticated and use these two variables to access the OpenStack installation. Periodt.

---

💜 Using rclone without a config file 💜

You can use rclone with swift without a config file, if you want, like this:

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 use fewer transactions in exchange for more memory. See the rclone docs at https://rclone.org/docs/#fast-list for more details. It's giving efficiency, bestie 🫶

---

🌈 --update and --use-server-modtime 🌈

As noted below, the modified time is stored on metadata on the object. It 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, because it requires an extra API call to retrieve the metadata. 😭

For many operations, the time the object was last uploaded to the remote is sufficient to determine if it is "dirty". By using --update along with --use-server-modtime, you can avoid the extra API call and simply upload files whose local modtime is newer than the time it was last uploaded. Obsessed with this one, honestly.

---

🧚 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. So precise, so iconic ✨

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 💖

Heads up bestie — these characters get swapped out:

• NUL — value 0x00 — replacement ␀
• / — value 0x2F — replacement ／

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings. No cap.

---

👑 Standard options 👑

Here are the Standard options specific to swift (OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH)). Let's gooo 💅

• --swift-env-auth — Get swift credentials from environment variables in standard OpenStack form.
  • 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).
  • Config: user
  • Env Var: RCLONE_SWIFT_USER
  • Type: string
  • Required: false
• --swift-key — API key or password (OS_PASSWORD).
  • Config: key
  • Env Var: RCLONE_SWIFT_KEY
  • Type: string
  • Required: false
• --swift-auth — Authentication URL for server (OS_AUTH_URL).
  • 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).
  • Config: user_id
  • Env Var: RCLONE_SWIFT_USER_ID
  • Type: string
  • Required: false
• --swift-domain — User domain — optional (v3 auth) (OS_USER_DOMAIN_NAME)
  • Config: domain
  • Env Var: RCLONE_SWIFT_DOMAIN
  • Type: string
  • Required: false
• --swift-tenant — Tenant name — optional for v1 auth, this or tenant_id required otherwise (OS_TENANT_NAME or OS_PROJECT_NAME).
  • Config: tenant
  • Env Var: RCLONE_SWIFT_TENANT
  • Type: string
  • Required: false
• --swift-tenant-id — Tenant ID — optional for v1 auth, this or tenant required otherwise (OS_TENANT_ID).
  • 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).
  • Config: tenant_domain
  • Env Var: RCLONE_SWIFT_TENANT_DOMAIN
  • Type: string
  • Required: false
• --swift-region — Region name — optional (OS_REGION_NAME).
  • Properties:
    • Config: region

…and here are the deets of that property list, bestie:

• Config: region
• Env Var: RCLONE_SWIFT_REGION
• Type: string
• Required: false

---

• --swift-storage-url — the Storage URL, optional 🫶 (that's OS_STORAGE_URL in the wild).
  • Config: storage_url
  • Env Var: RCLONE_SWIFT_STORAGE_URL
  • Type: string
  • Required: false
• --swift-auth-token — an Auth Token from some alternate authentication flow, also optional (OS_AUTH_TOKEN) ✨
  • Config: auth_token
  • Env Var: RCLONE_SWIFT_AUTH_TOKEN
  • Type: string
  • Required: false
• --swift-application-credential-id — your Application Credential ID (OS_APPLICATION_CREDENTIAL_ID) 💅
  • Config: application_credential_id
  • Env Var: RCLONE_SWIFT_APPLICATION_CREDENTIAL_ID
  • Type: string
  • Required: false
• --swift-application-credential-name — your Application Credential Name (OS_APPLICATION_CREDENTIAL_NAME) 🎀
  • Config: application_credential_name
  • Env Var: RCLONE_SWIFT_APPLICATION_CREDENTIAL_NAME
  • Type: string
  • Required: false
• --swift-application-credential-secret — your Application Credential Secret (OS_APPLICATION_CREDENTIAL_SECRET). yes queen, keep it secret 🔒
  • Config: application_credential_secret
  • Env Var: RCLONE_SWIFT_APPLICATION_CREDENTIAL_SECRET
  • Type: string
  • Required: false
• --swift-auth-version — the AuthVersion, optional — set it to 1, 2, or 3 if your auth URL has no version baked into it (ST_AUTH_VERSION).
  • Config: auth_version
  • Env Var: RCLONE_SWIFT_AUTH_VERSION
  • Type: int
  • Default: 0
• --swift-endpoint-type — which endpoint type to pull out of the service catalogue (OS_ENDPOINT_TYPE).
  • Config: endpoint_type
  • Env Var: RCLONE_SWIFT_ENDPOINT_TYPE
  • Type: string
  • Default: "public"
  • Examples:
    • "public"
      • Public — that's the default, pick this one if you're not sure 🫡
    • "internal"
      • Internal — uses the internal service net
    • "admin"
      • Admin
• --swift-storage-policy — the storage policy rclone should use when it's making a brand new container 🌱
  • It applies that specified storage policy at container-creation time. The policy cannot be changed afterwards. ⚠️ Which config values are allowed and what they even mean? That's all up to your Swift storage provider, bestie.
  • 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 🚀

okay so these are the Advanced options specific to swift (OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH)). read carefully, they're the spicy ones 🌶️

• --swift-leave-parts-on-error — if true, rclone avoids calling abort upload when something fails.
  • Set it to true if you want to resume uploads across different sessions. it's giving "don't throw away my progress" 💜
  • 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 if rclone listings show fewer objects than expected, or if repeated syncs keep copying objects that literally never changed 😭
  • It's safe to enable, but rclone may make more API calls than necessary. no cap.
  • This is one of a pair of workarounds for Swift API implementations that don't do pagination the way you'd expect. See also partial_page_fetch_threshold 👀
  • Config: fetch_until_empty_page
  • Env Var: RCLONE_SWIFT_FETCH_UNTIL_EMPTY_PAGE
  • Type: bool
  • Default: false
• --swift-partial-page-fetch-threshold — when paginating, fetch if the current page is within this percentage of the limit.
  • Consider using this if rclone listings show fewer objects than expected, or if repeated syncs copy objects that never changed 🙈
  • It's safe to enable, but rclone may make more API calls than necessary.
  • The other half of that workaround pair for Swift API implementations that don't paginate as expected. See also fetch_until_empty_page.
  • Config: partial_page_fetch_threshold
  • Env Var: RCLONE_SWIFT_PARTIAL_PAGE_FETCH_THRESHOLD
  • Type: int
  • Default: 0
• --swift-chunk-size — above this size, files get chunked.
  • Above this size, files will be chunked into a _segments container or a .file-segments directory. (Peep the use_segments_container option for the tea on that one ☕) The default for this is 5 GiB, which is also its maximum value, which means only files above this size get chunked.
  • Rclone uploads chunked files as dynamic large objects (DLO).
  • Config: chunk_size
  • Env Var: RCLONE_SWIFT_CHUNK_SIZE
  • Type: SizeSuffix
  • Default: 5Gi
• --swift-no-chunk — don't chunk files during streaming upload.
  • When you're doing streaming uploads (e.g. using rcat or mount with --vfs-cache-mode off), setting this flag makes the swift backend not upload chunked files.
  • Heads up: this will limit the maximum streamed upload size to 5 GiB. That's actually useful, because non-chunked files are easier to deal with and they have an MD5SUM 💖
  • Rclone will still chunk files bigger than chunk_size when doing normal copy operations. so it's not a global no-chunk zone.
  • 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 cannot transparently store files bigger than 5 GiB. There are two schemes for chunking large files, static large objects (SLO) or dynamic large objects (DLO), and the API does not let rclone figure out whether a file is a static or dynamic large object without doing a HEAD on the object. Since these two need to be treated differently, that means rclone has to issue HEAD requests for objects — for example when reading checksums. 🫠
  • When no_large_objects is set, rclone will assume that there are no static or dynamic large objects stored. That means it can stop doing those extra HEAD calls, which in turn massively boosts performance, especially when doing a swift to swift transfer with --checksum set 🔥
  • Setting this option implies no_chunk, and also that no files will be uploaded in chunks, so files bigger than 5 GiB will just fail on upload. 💀
  • If you set this option and there are static or dynamic large objects, then this will give incorrect hashes for them. Downloads will succeed, but other operations such as Remove and Copy will fail.
  • Config: no_large_objects
  • Env Var: RCLONE_SWIFT_NO_LARGE_OBJECTS
  • Type: bool
  • Default: false
• --swift-use-segments-container — choose destination for large object segments.
  • Swift cannot transparently store files bigger than 5 GiB, and rclone will chunk files larger than chunk_size (default 5 GiB) in order to upload them.
  • If this value is true, the chunks get stored in an additional container named the same as the destination container but with _segments appended. That means there won't be any duplicated data in the original container — but having another container may not be acceptable to everyone. 🤷
  • If this value is false, the chunks get stored in a .file-segments directory in the root of the container. This directory will be omitted when listing the container. Some providers (eg Blomp) require this mode, since creating additional containers isn't allowed. If it is desired to see the .file-segments directory in the root, then this flag must be set to true.
  • If this value is unset (the default), then rclone will choose the value to use. It will be false unless rclone detects any auth_urls that it knows need it to be true. In that case you'll see a message in the DEBUG log. 👑
  • Config: use_segments_container
  • Env Var: RCLONE_SWIFT_USE_SEGMENTS_CONTAINER
  • Type: Tristate
  • Default: unset
• --swift-encoding — the encoding for the backend.
  • See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.
  • Config: encoding
  • Env Var: RCLONE_SWIFT_ENCODING
  • Type: Encoding
  • Default: Slash,InvalidUtf8
• --swift-description — Description of the remote. just give it a cute lil label ✨
  • Config: description
  • Env Var: RCLONE_SWIFT_DESCRIPTION
  • Type: string
  • Required: false

😔 Limitations 😔

The Swift API doesn't return a correct MD5SUM for segmented files (Dynamic or Static Large Objects), so rclone won't check or use the MD5SUM for those. that's just how it is, bestie, we don't make the rules 🫶

🩺 Troubleshooting 🩺

Rclone gives Failed to create file system for "remote:": Bad Request

• Due to an oddity of the underlying swift library, it gives a "Bad Request" error rather than a more sensible error when the authentication fails for Swift. iconic of it, honestly 💀
• So this most likely means your username / password is wrong. You can investigate further with the --dump bodies flag.
• This may also be caused by specifying the region when you shouldn't have (e.g. OVH).

Rclone gives Failed to create file system: Response didn't have storage url and auth token

This is most likely caused by forgetting to specify your tenant when setting up a swift remote. been there 🙈

OVH Cloud Archive

To use rclone with OVH cloud archive, first use 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 to object storage — you just simply run the command you like (move, copy or sync) to upload the objects. Once uploaded, the objects will show in a "Frozen" state within the OVH control panel. ❄️

Retrieving Objects

To retrieve objects, use rclone copy as normal. If the objects are in a frozen state, then rclone will ask for them all to be unfrozen and it will wait at the end of the output with a message like the following:

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 for the time specified, then retry the copy. so like, go make a snack, it'll get there 🍓

✨ pCloud ✨

okay bestie so paths here are literally just remote:path and that's the whole vibe 💅

and they can go as deep as you want fr fr, like remote:directory/subdirectory — no cap, nest away 🫶

---

🌸 Configuration

the first-time setup is all about snagging a token from pCloud, and yes you do it in your browser, sorry babe. rclone config holds your hand the entire way through it tho 💖

here's a whole example of making a remote called remote. run this first:

rclone config

and then it walks you through the interactive thing, looking like this exactly:

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

need to do this on a machine with no internet-connected web browser? iconic problem, they got you — check the remote setup docs over at https://rclone.org/remote_setup/ 💫

heads up bestie: if you're doing remote config with rclone authorize and your pcloud server is the EU region, you HAVE to set the hostname in 'Edit advanced config', otherwise you might get a token error 😭 not a vibe.

also just so you know, rclone spins up a lil webserver on your local machine to grab the token back from pCloud. it only runs from the second it opens your browser to the second you get your verification code back. it lives at http://127.0.0.1:53682/ and honestly it might need you to temporarily unblock it if you're running a host firewall 🙈

once it's all configured you can use rclone like this (swap remote for whatever name you gave yours):

list the directories at the top level of your pCloud:

rclone lsd remote:

list ALL the files in your pCloud:

rclone ls remote:

copy a local directory into 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, and those get used to figure out whether stuff needs syncing or not. but here's the thing — to set a Modification time, pCloud requires the object be re-uploaded. yeah. it's giving extra 💀

on the hash front: pCloud supports MD5 and SHA1 hashes in the US region, and SHA1 and SHA256 hashes in the EU region, so you can totally use the --checksum flag 🎀

---

🎀 Restricted filename characters

on top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these ones also get replaced:

• Character \, value 0x5C → replaced with ＼

invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), since they literally can't be used in JSON strings, periodt ✨

---

💀 Deleting files

deleted files get moved to the trash. how long they sit there is up to your subscription level. and you can use rclone cleanup to empty the trash whenever you feel like it 🗑️

---

🫶 Emptying the trash

okay so due to an API limitation, the rclone cleanup command only works if you set your username and password in the advanced options for this backend. and since we generally wanna avoid storing user passwords in the rclone config file, the advice is: only set this up if you actually need rclone cleanup to work. no cap 🙈

---

👑 Root folder ID

you can set the root_folder_id for rclone. this is the directory (identified by its Folder ID) that rclone will consider to be the root of your pCloud drive.

normally you leave this blank and rclone figures out the correct root all by itself, main character energy 🌟

BUT you can set it 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. you can do that by running the rclone lsf command using a basic configuration setup that does NOT include the root_folder_id parameter.

the command will enumerate the available directories, which lets you locate the right Folder ID for later use.

example:

$ rclone lsf --dirs-only -Fip --csv TestPcloud:
dxxxxxxxx2,My Music/
dxxxxxxxx3,My Pictures/
dxxxxxxxx4,My Videos/

so if the folder you want rclone to use is My Music/, then take the returned id from the rclone lsf command (ex. dxxxxxxxx2) and use it as the value of the root_folder_id variable in the config file 💅

---

🦋 Change notifications and mounts

the pCloud backend supports real-time updates for rclone mounts via change notifications. rclone uses pCloud's diff long-polling API to detect changes and will automatically refresh directory listings in the mounted filesystem whenever changes happen. lowkey magic ✨

notes and behavior:

• works automatically when using rclone mount and requires no additional configuration 👑
• notifications are directory-scoped: when rclone detects a change, it refreshes the affected directory so new/removed/renamed files become visible promptly
• updates are near real-time. the backend uses a long-poll with short fallback polling intervals, so you should see changes appear quickly without manual refreshes

if you wanna debug or verify notifications, there's a lil helper command:

rclone test changenotify remote:

this will log incoming change notifications for the given remote 🔥

---

⭐ 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.

note that this option is NOT supported by all backends, so don't come for me if it doesn't work somewhere else 💀

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 (https://rclone.org/overview/#encoding) 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'll need to set it by hand if you're 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 (https://rclone.org/commands/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 🦋

okay bestie, meet PikPak — it's a private cloud drive (https://mypikpak.com/) ✨

Paths are specified as remote:path, and they can go as deep as you want, like remote:directory/subdirectory — no cap, nest away 💅

---

🌸 Configuration 🌸

Here's a whole example of building a PikPak remote, step by step, so you literally can't mess it up 🫶

First you run:

rclone config

And it walks you through the interactive setup like the cutest little wizard ever:

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

---

⏰ Modification times and hashes ⏰

PikPak keeps modification times on objects, and it updates them when you upload objects — but it does not support changing only the modification time 💀

The MD5 hash algorithm is supported 👑

---

✨ Standard options ✨

Here are the Standard options 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 (https://rclone.org/commands/rclone_obscure/) 🔐

Properties:

• Config: pass
• Env Var: RCLONE_PIKPAK_PASS
• Type: string
• Required: true

---

🔥 Advanced options 🔥

Here are the Advanced options 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-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_PIKPAK_UPLOAD_CUTOFF
• Type: SizeSuffix
• Default: 200Mi

--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: 4

--pikpak-encoding

The encoding for the backend.

See the encoding section in the overview (https://rclone.org/overview/#encoding) 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 specific to the pikpak backend.

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend (https://rclone.org/commands/rclone_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 (https://rclone.org/rc/#backend-command). ⭐

---

🌈 addurl 🌈

Add offline download task for url.

rclone backend addurl remote: [options] [<arguments>+]

This command adds offline download task for url.

Usage examples:

rclone backend addurl pikpak:dirpath url
rclone backend addurl pikpak:dirpath url -o name=custom_filename.zip

Downloads will be stored in 'dirpath'. If 'dirpath' is invalid, download will fallback to default 'My Pack' folder. 🍓

Options:

• "name": Custom filename for the downloaded file.

---

🧚 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 examples:

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, gather round, because this one is the premium one, not the freebie. This is the backend for Pixeldrain's premium filesystem feature. It is not the same as pixeldrain's free file sharing product — like, different girl entirely. The filesystem requires either a Pro subscription or the Prepaid plan. More information on subscriptions lives right here: https://pixeldrain.com/#pro.

Wanna know what it can and can't do? An overview of the filesystem's features and limitations is available in the filesystem guide at https://pixeldrain.com/filesystem on pixeldrain. Go read it, iykyk. 📖✨

---

🫶 Usage with account

To use the personal filesystem you will need a pixeldrain account (https://pixeldrain.com/register) and either the Prepaid plan or one of the Patreon-based subscriptions. You literally need both, no skipping. After registering and subscribing, your personal filesystem will be available at this link: https://pixeldrain.com/d/me. 🎀

Go to the API keys page (https://pixeldrain.com/user/api_keys) 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. Slay.

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 there's a whole no-account route?? It is possible to gain 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, 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. So helpful fr fr.

Enter this directory ID in the rclone config and you will be able to access the directory. That's it, that's the whole vibe. ✨

---

🌸 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.

Properties:

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

Properties:

• 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). Ooh fancy.

💅 --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.

Properties:

• Config: api_url
• Env Var: RCLONE_PIXELDRAIN_API_URL
• Type: string
• Default: "https://pixeldrain.com/api"

💅 --pixeldrain-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_PIXELDRAIN_DESCRIPTION
• Type: string
• Required: false

---

🦋 Metadata

Pixeldrain supports file modes and creation times. Iconic behaviour honestly.

Here are the possible system metadata items for the pixeldrain backend.

• btime — Time of file birth (creation). Type: RFC 3339. Example: 2006-01-02T15:04:05.999999999Z07:00. Read Only: N
• mode — File mode. Type: octal, unix style. Example: 755. Read Only: N
• mtime — Time of last modification. Type: RFC 3339. Example: 2006-01-02T15:04:05.999999999Z07:00. Read Only: N

See the metadata (https://rclone.org/docs/#metadata) docs for more info. 🫶

premiumize.me Paths are specified as <code>remote:path</code>

Paths may be as deep as required, e.g. <code>remote:directory/subdirectory</code>.

🌸 Configuration

The initial setup for premiumize.me (https://premiumize.me/) involves getting a token from premiumize.me which you need to do in your browser. <code>rclone config</code> 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:

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 (https://rclone.org/remote_setup/) for how to set it up on a machine without an internet-connected web browser available. 🦋

Note that rclone runs a webserver on your local machine to collect the token as returned from premiumize.me. This only runs from the moment it opens your browser to the moment you get back the verification code. This is on <code>http://127.0.0.1:53682/</code> and this it may require you to unblock it temporarily if you are running a host firewall. 🙈

Once configured you can then use rclone like this (replace remote with the name you gave your remote):

List directories in top level of your 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

premiumize.me does not support modification times or hashes, therefore syncing will default to <code>--size-only</code> checking. Note that using <code>--update</code> will work.

🎀 Restricted filename characters

In addition to the default restricted characters set (https://rclone.org/overview/#restricted-characters) the following characters are also replaced:

Character Value Replacement ──────────────────────────────── \ 0x5C ＼ " 0x22 ＂

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be used in JSON strings.

✨ 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

🔥 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.

Note that this option is NOT supported by all backends.

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 (https://rclone.org/overview/#encoding) 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

Note that premiumize.me is case insensitive so you can't have a file called <code>"Hello.doc"</code> and one called <code>"hello.doc"</code>. 😭

premiumize.me file names can't have the <code></code> or <code>"</code> characters in. rclone maps these to and from an identical looking unicode equivalents <code>＼</code> and <code>＂</code>

premiumize.me only supports filenames up to <code>255</code> characters in length.

---

💜 Proton Drive

Proton Drive (https://proton.me/drive) is an end-to-end encrypted Swiss vault for your files that protects your data. 🔐

This is an rclone backend for Proton Drive which supports the file transfer features of Proton Drive using the same client-side encryption.

Due to the fact that 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.

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 (https://forum.rclone.org/) if you find an incompatibility. 🫶

Paths are specified as <code>remote:path</code>

Paths may be as deep as required, e.g. <code>remote:directory/subdirectory</code>.

🌈 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. ⚠️

Once configured you can then use rclone like this (replace remote with the name you gave your remote):

List directories in top level of your 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.

The SHA1 hash algorithm is supported.

💅 Restricted filename characters

Invalid UTF-8 bytes will be replaced (https://rclone.org/overview/#invalid-utf8), also left and right spaces will be removed (code reference (https://github.com/ProtonMail/Web- Clients/blob/b4eba99d241af4fdae06ff7138bd651a40ef5d3c/applications/dri- ve/src/app/store/_links/validation.ts#L51))

🍓 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 password (https://proton.me/support/the-difference-between-the-mailbox-password-and-login-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 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 <code>rclone obscure</code> (https://rclone.org/commands/rclone_obscure/).

Properties:

• Config: password
• Env Var: RCLONE_PROTONDRIVE_PASSWORD
• Type: string

• Required: true

---

• --protondrive-2fa — your 2FA code, bestie 💖

You can also just hand it over like --protondrive-2fa=000000

This is the two-factor authentication code for your proton drive account — only needed if you set that account up with 2FA in the first place. No 2FA, no problem, skip it ✨

Properties:

• Config: 2fa
• Env Var: RCLONE_PROTONDRIVE_2FA
• Type: string
• Required: false

• --protondrive-otp-secret-key — the OTP secret key 🔐

You can also pass it as --protondrive-otp-secret-key=ABCDEFGHIJKLMNOPQRSTUVWXYZ234567

This is the OTP secret key belonging to your proton drive account, for when your account is set up with two-factor authentication.

NB — what you feed in here must be obscured. See rclone obscure (<https://rclone.org/commands/rclone_obscure/>). Don't be out here pasting raw secrets, it's giving security breach 😭

Properties:

• Config: otp_secret_key
• Env Var: RCLONE_PROTONDRIVE_OTP_SECRET_KEY
• Type: string
• Required: false

---

✨ Advanced options ✨

Here are the Advanced options specific to protondrive (Proton Drive) 💅 the deep-cut settings, iykyk.

• --protondrive-mailbox-password — the mailbox password of your two-password proton account 🫶

Want the whole tea on what a mailbox password even is? The official knowledge base article has you covered: <https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password>

NB — input to this one must be obscured too. See rclone obscure (<https://rclone.org/commands/rclone_obscure/>).

Properties:

• Config: mailbox_password
• Env Var: RCLONE_PROTONDRIVE_MAILBOX_PASSWORD
• Type: string
• Required: false

• --protondrive-encoding — the encoding for the backend 🌈

Peep the encoding section in the overview (<https://rclone.org/overview/#encoding>) for the full rundown.

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 👑

Okay so here's the situation: the size of the encrypted file is gonna be different from (as in, bigger than) the original file size. Unless you've got an actual reason to want the post-encryption size, just set this to true — because features like Open() need to be supplied with the original content size, and they will straight up fail to operate properly without it 💀

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 identifies the client that is currently performing the API request. Third-party Proton Drive integrations should use the form external-drive-<project>@<version>. If this option is left empty, rclone derives a compliant value from its own version. This value is sent with every API request; the option itself is optional.

Properties:

• Config: app_version
• Env Var: RCLONE_PROTONDRIVE_APP_VERSION
• Type: string
• Required: false

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

You can also set the value via --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. No upload. Zero. None. 😭

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're mounting ProtonDrive as a VFS, please disable this feature, because the current implementation doesn't update or clear the cache when there are external changes. Not me warning you twice 🙈

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 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. Stale data is not the vibe. 💀

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 🚧

Okay bestie, let's be real about how this whole thing is built, because the lore matters 📖✨

This backend uses the Proton-API-Bridge (<https://github.com/henrybear327/Proton-API-Bridge>), which is based on go-proton-api (<https://github.com/henrybear327/go-proton-api>), a fork of the official repo (<https://github.com/ProtonMail/go-proton-api>).

There is no official API documentation available from Proton Drive. But — thanks to Proton open sourcing proton-go-api (<https://github.com/ProtonMail/go-proton-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! Iconic behavior honestly 👑

proton-go-api (<https://github.com/ProtonMail/go-proton-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. It's giving skeleton, not full fit 💅

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 cap, we're all just doing our best out here 🌸

---

💾 put.io 💾

Ok bestie, paths here are literally just remote:path, no notes.

And put.io paths can go as deep as you want, fr fr — like remote:directory/subdirectory. Nest away. 🪆

🎀 Configuration 🎀

So the very first setup for put.io means snagging a token from put.io, and you do that in your browser. rclone config holds your hand the whole way through it. 🫶

Here's how you'd make a remote called remote. First run:

rclone config

And it'll walk you through an interactive setup process like this:

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

Wanna know how to do this on a machine with no internet-connected web browser? Go read the remote setup docs, they got you: https://rclone.org/remote_setup/ ✨

Heads up bestie 👀 — if you use the web browser auto-auth, rclone spins up a lil webserver on your local machine to catch the token that comes back from put.io. It's only alive from the second it opens your browser until you get that verification code back. It lives at http://127.0.0.1:53682/ and lowkey you might need to unblock it temporarily if you've got a host firewall running, or just use manual mode instead.

Then you can use it like this, periodt:

List the directories at the top level of your put.io:

rclone lsd remote:

List all the files in your put.io:

rclone ls remote:

To copy a local directory into a put.io directory called backup:

rclone copy /home/source remote:backup

🔒 Restricted filename characters 🔒

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these characters get replaced too:

• \ — value 0x5C — gets replaced with ＼

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), because they straight up can't be used in JSON strings. 💀

⚙️ Standard options ⚙️

Here are the Standard options specific to putio (Put.io):

--putio-client-id

OAuth Client Id.

Leave blank normally, bestie.

Properties:

• Config: client_id
• Env Var: RCLONE_PUTIO_CLIENT_ID
• Type: string
• Required: false

--putio-client-secret

OAuth Client Secret.

Leave blank normally.

Properties:

• Config: client_secret
• Env Var: RCLONE_PUTIO_CLIENT_SECRET
• Type: string
• Required: false

🌈 Advanced options 🌈

Here are the Advanced options specific to putio (Put.io):

--putio-token

OAuth Access Token as a JSON blob.

Properties:

• Config: token
• Env Var: RCLONE_PUTIO_TOKEN
• Type: string
• Required: false

--putio-auth-url

Auth server URL.

Leave blank to use the provider defaults.

Properties:

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

Properties:

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

Not gonna lie — this option is NOT supported by all backends. 😭

Properties:

• 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 (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_PUTIO_ENCODING
• Type: Encoding
• Default: Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot

--putio-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_PUTIO_DESCRIPTION
• Type: string
• Required: false

🚧 Limitations 🚧

put.io has rate limiting, okay? So when you hit a limit, rclone automatically retries after waiting the amount of time requested by the server. It's giving patience. 💅

If you want to avoid ever hitting these limits, you may use the --tpslimit flag with a low number. Just know that the imposed limits may be different for different operations, and they may change over time. 🙈

---

🔐 Proton Drive 🔐

Proton Drive (https://proton.me/drive) is an end-to-end encrypted Swiss vault for your files that protects your data. Iconic behavior honestly. 👑

This is an rclone backend for Proton Drive which supports the file transfer features of Proton Drive using the same client-side encryption.

And 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. Detecting fr fr. 🕵️‍♀️

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 (https://forum.rclone.org/) 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. No keys, no vibes. 😭

Once configured you can then use rclone like this (replace remote with the name you gave your remote):

List directories in top level of your 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. Not yet bestie, not yet.

The SHA1 hash algorithm is supported. ✨

🔒 Restricted filename characters 🔒

Invalid UTF-8 bytes will be replaced (https://rclone.org/overview/#invalid-utf8), also left and right spaces will be removed (code reference: https://github.com/ProtonMail/Web-Clients/blob/b4eba99d241af4fdae06ff7138bd651a40ef5d3c/applications/drive/src/app/store/_links/validation.ts#L51)

👯 Duplicated files 👯

Proton Drive can not have two files with exactly the same name and path. Nope. If the conflict occurs, depending on the advanced config, the file might or might not be overwritten.

📬 Mailbox password (https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password) 📬

Please set your mailbox password in the advanced config section. Do it, don't skip it. 🙏

🗄️ 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 (https://rclone.org/commands/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

This is the 2FA code your Proton Drive account wants when it's set up with two-factor authentication.

Properties:

• Config: 2fa
• Env Var: RCLONE_PROTONDRIVE_2FA
• Type: string
• Required: false

---

• --protondrive-otp-secret-key — the OTP secret key 🔑

You can also hand it over like this: --protondrive-otp-secret-key=ABCDEFGHIJKLMNOPQRSTUVWXYZ234567

It's the OTP secret key for your Proton Drive account, needed when that account has two-factor authentication switched on.

NB: whatever you feed in here must be obscured — go see rclone obscure (https://rclone.org/commands/rclone_obscure/). no plaintext confessions 💀

Properties:

• Config: otp_secret_key
• Env Var: RCLONE_PROTONDRIVE_OTP_SECRET_KEY
• Type: string
• Required: false

Advanced options ✨

Here are the Advanced options specific to protondrive (Proton Drive) — the afterparty options, if you will 🎀

--protondrive-mailbox-password

The mailbox password of your two-password proton account.

For more info on what a mailbox password even is, check the 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 (https://rclone.org/commands/rclone_obscure/). obscure it, bestie, i'm begging 🙈

Properties:

• Config: mailbox_password
• Env Var: RCLONE_PROTONDRIVE_MAILBOX_PASSWORD
• Type: string
• Required: false

--protondrive-encoding

The encoding for the backend.

Scroll the encoding section in the overview (https://rclone.org/overview/#encoding) for the full lore.

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 is gonna be different from (bigger than) the original file size. Unless you've got an actual reason to want the size after encryption, set this to true — because features like Open() that need to be handed the original content size will straight up fail to work 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 identifies the client that's currently performing the API request. Third-party Proton Drive integrations should use the form external-drive-<project>@<version>. If this option is left empty, rclone derives a compliant value from its own version. This value is sent with every API request; the option itself is optional.

Properties:

• Config: app_version
• Env Var: RCLONE_PROTONDRIVE_APP_VERSION
• Type: string
• Required: false

--protondrive-replace-existing-draft

Create a new revision when a filename conflict is detected.

So, tea time ☕: when a file upload gets cancelled or fails before it finishes, a draft gets created — and then the next upload of that same file to that same location gets reported as a conflict.

You can also set the value with --protondrive-replace-existing-draft=true.

If you set this to true, the draft gets replaced and then the upload operation restarts. But — and this is the important bit — if other clients are uploading to the same file location at the same time, the behavior is currently unknown. 👀 It needs to be true for integration tests. If it's set to false, you get this error back: a draft exist - usually this means a file is being uploaded at another client, or, there was a failed upload attempt — and no upload happens at all.

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're mounting ProtonDrive as a VFS, please disable this feature, because 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 rclone is the only instance performing operations on the mount point. The event system — that's the proton API system that gives you visibility into what's changed on the drive — is yet to be implemented, so updates from other clients won't be reflected in the cache. Which means: if there are concurrent clients hitting the same mount point, we might have a problem with caching stale data. 😬

Properties:

• Config: enable_caching
• Env Var: RCLONE_PROTONDRIVE_ENABLE_CACHING
• Type: bool
• Default: true

--protondrive-description

Description of the remote. Just a lil label so you remember which one's which 🏷️

Properties:

• Config: description
• Env Var: RCLONE_PROTONDRIVE_DESCRIPTION
• Type: string
• Required: false

Limitations 💀

This backend uses the Proton-API-Bridge (https://github.com/henrybear327/Proton-API-Bridge), which is based on go-proton-api (https://github.com/henrybear327/go-proton-api), a fork of the official repo (https://github.com/ProtonMail/go-proton-api).

There is no official API documentation available from Proton Drive. But — and this is the iconic part — thanks to Proton open sourcing proton-go-api (https://github.com/ProtonMail/go-proton-api) plus the web, iOS, and Android client codebases, we don't have to completely reverse engineer the APIs by just watching the web client traffic! 👑

proton-go-api (https://github.com/ProtonMail/go-proton-api) provides the basic building blocks of API calls and error handling, like 429 exponential back-off, but honestly it's pretty much just a barebones interface to the Proton API. For example, the encryption and decryption of Proton Drive files? Not provided in this library. nope 🙈

The Proton-API-Bridge attempts to bridge that gap, so rclone can be built on top of it quickly. This codebase handles the intricate tasks before and after calling Proton APIs — especially the complex encryption scheme — which lets developers implement features for other software on top of it too. There are likely quite a few errors in this library, because there isn't official documentation available. fr fr 😭

---

Seafile 🌊

This is a backend for the Seafile (https://www.seafile.com/) storage service:

• It works with both the free community edition or the professional edition. 💖
• Seafile versions 6.x, 7.x, 8.x and 9.x are all supported. ✨
• Encrypted libraries are also supported. 🔒
• It supports 2FA enabled users. 🔑
• Using a Library API Token is not supported. 💀

Configuration

There are two distinct modes you can set up your remote in:

• you point your remote to the root of the server, 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 specific library 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'll need the URL of your server, your email (or username) and your password. 🫶

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 root of your seafile server and can now be used like this:

See all libraries:

rclone lsd seafile:

Create a new library:

rclone mkdir seafile:library

List the contents of a library:

rclone ls seafile:library

Sync /home/local/directory to the remote library, deleting any excess files in the library:

rclone sync --interactive /home/local/directory seafile:library

Configuration in library mode

Here's an example of a configuration in library mode with a user that has two-factor authentication enabled. Your 2FA code will be asked at the end of the configuration, and will attempt to authenticate you:

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

okay so bestie if you're side-eyeing that blank pass = line, don't worry 💖 You'll notice your password is blank in the configuration, and that's on purpose fr — it's because we only need the password to authenticate you once. That's it. One time. Slay.

You specified My Library during the configuration, so the root of the remote is pointing right at the root of the library My Library 👑

See all files in the library:

rclone lsd seafile:

Create a new directory inside the library:

rclone mkdir seafile:directory

List the contents of a directory:

rclone ls seafile:directory

Sync /home/local/directory to the remote library, deleting any excess files in the library. (Yeah, sync is a delete-things kind of command, so keep your eyes open 👀)

rclone sync --interactive /home/local/directory seafile:

---

✨ --fast-list ✨

Seafile version 7+ supports --fast-list, which is giving fewer transactions in exchange for more memory. See the rclone docs at https://rclone.org/docs/#fast-list for more details. Also, big note: this is not supported on seafile server version 6.x. Nope. Not a vibe there 🙈

---

🚫 Restricted filename characters 🚫

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these characters also get replaced, no exceptions:

• / — value 0x2F — becomes ／
• " — value 0x22 — becomes ＂
• \ — value 0x5C — becomes ＼

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), because, and I cannot stress this enough, they literally cannot be used in JSON strings. It's giving structural impossibility 💅

---

🔗 Seafile and rclone link 🔗

Rclone can generate share links, but for non-encrypted libraries only — that's the rule, periodt. And the link can be either for a file or for a directory:

$ rclone link seafile:seafile-tutorial.doc
http://my.seafile.server/f/fdcd8a2f93f84b8b90f4/

or if you run it 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 🎀 So if you run a link command on a file/dir that has already been shared, you will get the exact same link back. Same link, every time. It's consistent, it's iconic, it's just how it is.

---

🌈 Compatibility 🌈

This backend has been actively developed using the seafile docker image (https://github.com/haiwen/seafile-docker) 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 6.0 are not supported — hard no, do not pass go 🛑 Versions between 6.0 and 6.3 haven't been tested and might not work properly, so like... proceed with caution bestie.

Each new version of rclone is automatically tested against the latest docker image (https://hub.docker.com/r/seafileltd/seafile-mc/) of the seafile community server. Automated. Every time. Obsessed 💖

---

⭐ 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 (https://rclone.org/commands/rclone_obscure/). Like, do not just paste your raw password in there, that's not the move 🙈

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 — so blank = everything that's not encrypted, got it?

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 (https://rclone.org/commands/rclone_obscure/). Same deal as the password, bestie, obscure it or don't bother 💅

Properties:

• Config: library_key
• Env Var: RCLONE_SEAFILE_LIBRARY_KEY
• Type: string
• Required: false

---

👑 Advanced options 👑

Here are the Advanced options specific to seafile (seafile).

🦋 --seafile-create-library

Should rclone create a library if it doesn't exist.

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 (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_SEAFILE_ENCODING
• Type: Encoding
• Default: Slash,DoubleQuote,BackSlash,Ctl,InvalidUtf8,Dot

🦋 --seafile-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_SEAFILE_DESCRIPTION
• Type: string
• Required: false

---

🦋 SFTP 🦋

SFTP is the Secure (or SSH) File Transfer Protocol (https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol), and it's lowkey everywhere.

The SFTP backend can be used with a bunch of different providers, including:

• Hetzner Storage Box
• rsync.net

SFTP runs over SSH v2 and is installed as standard with most modern SSH installations — it's just there, no setup arc required ✨

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 the remote machine (i.e. /). One slash and the whole vibe changes, no cap 😭

Note that some SFTP servers will need the leading / — Synology is a good example of this. rsync.net and Hetzner, on the other hand, require users to OMIT the leading /. So like, read the room (and the provider docs) before you spam slashes.

Note that by default rclone will try to execute shell commands on the server, see shell access considerations.

---

⚙️ 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. (Deleting. Excess. Files. You have been warned, bestie 💀)

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 💖

okay bestie, the SFTP remote lets you log in three whole ways and you get to pick your fave:

• Password
• Key file, including certificate signed keys
• ssh-agent

Key files have to be PEM-encoded private key files, k? Like /home/$USER/.ssh/id_rsa — that's the vibe. Only unencrypted OpenSSH files, or PEM encrypted files, are supported. That's the whole list, no cap.

You can hand over that key file either as an external file (via key_file) or stuffed right inside the rclone config file itself (via key_pem). If you're doing key_pem in the config, the entry has to sit on a single line, with a new line ('\n' or '\r\n') separating the lines. Like this, bestie:

key_pem = -----BEGIN RSA PRIVATE KEY-----\nMaMbaIXtE\n0gAMbMbaSsd\nMbaass\n-----END RSA PRIVATE KEY-----

And this little number will generate it correctly for key_pem so you can paste it into your config:

awk '{printf "%s\\n", $0}' < ~/.ssh/id_rsa

Now, if you don't specify pass, key_file, or key_pem, or ask_password, rclone is just gonna go try to hit up an ssh-agent on its own. You can also set key_use_agent to force the usage of an ssh-agent. And in that case, you can also specify key_file or key_pem to force the usage of one specific key inside the ssh-agent. Specificity?? We love her. 💅

Using an ssh-agent is literally the only way to load encrypted OpenSSH keys at the moment. That's it. That's the only door. 🚪

And if you set the ask_password option, rclone will prompt you for a password whenever it needs one and no password has been configured. Very "I'll ask when I need to" of it. 🫶

🎀 Certificate-signed keys 🎀

With traditional key-based authentication, you configure your private key only, and the public key that's built into it gets used during the authentication process. Simple. Iconic.

But 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.

✨ Note: this is not the traditional public key paired with your private key, the one you'd typically save as /home/$USER/.ssh/id_rsa.pub. Setting that path in pubkey_file will not work. Don't do it. Learn from my mistakes. 😭

Example, bestie:

[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. Efficient.

🚨 Note: 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. And like… bestie. 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. 😭 Not the vibe. Rclone will produce a warning saying No host key validation is being performed every single time the backend is started in this mode. Every time. It's yelling at you. Listen to it.

Host key matching, using standard ssh known_hosts files, can be turned on by enabling the known_hosts_file option. This can point to the file maintained by OpenSSH, or it can point to a unique file of your own. To explicitly disable host key checking and silence the warning, the known_hosts_file option can be set to none.

Alternatively, rclone can maintain server host keys in a host_keys setting in the config file. And this can be updated automatically with --sftp-pin-host-key. Obsessed with automated trust. ✨

These options are described below 👇

🌸 Using the OpenSSH known_hosts file 🌸

Using the OpenSSH known_hosts file looks like this:

[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 though, bestie, and they're real:

• rclone will not manage this file for you. If the key is missing or wrong then the connection will be refused. It's giving "figure it out yourself."
• 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

And 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. That's the fix. You're welcome. 💅

The known_hosts_file setting can be set during rclone config as an advanced option.

👑 Host key pinning 👑

As an alternative to maintaining a known_hosts file, rclone supports Trust On First Use (TOFU) host key pinning via the --sftp-pin-host-key command-line flag. Yes, TOFU. We love a tofu moment. 🍜 (no that's not what it means but the energy is immaculate)

The recommended workflow is:

1. For the very first connection to a new remote, run rclone once with --sftp-pin-host-key. Rclone records the server's host key into the remote's host_keys config option and logs the SHA256 fingerprint:

$ rclone --sftp-pin-host-key lsd remote:
2026/01/01 12:00:00 NOTICE: sftp://sftpuser@example.com:22/: Accepted ssh-ed25519 host key SHA256:abc... for example.com:22 on first use
2026/01/01 12:00:00 NOTICE: sftp://sftpuser@example.com:22/: Pinned ssh-ed25519 host key SHA256:abc... for example.com:22 in config

2. For every subsequent run, omit the flag. Rclone consults the pinned host_keys and refuses the connection on any mismatch. She remembered. 💖

This is a strict improvement over the default of no host key validation, but note that the first connection itself is unauthenticated. Rclone detects later key changes — not a man-in-the-middle who is already on-path the very first time you connect. Ideally do the first connection over a trusted network, or cross-check the fingerprint rclone logs against one provided out of band by the server operator. Do the paranoid thing. It's cute. 🔥

If known_hosts_file is also set, it takes precedence and --sftp-pin-host-key is ignored.

After the first successful connection the config will contain a new line:

[remote]
type = sftp
host = example.com
user = sftpuser
pass =
host_keys = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

The host_keys field is always validated against the offered host key when non-empty, so you can also pin a known key by hand without ever running with the flag. Each entry is the complete public key — the algorithm and base64 fields of a known_hosts line — not its SHA256 fingerprint:

rclone config update remote host_keys "ssh-ed25519 AAAAC3..."

⚠️ Setting pin_host_key = true persistently in the config file is not recommended: while it is set, rclone will accept any new host key algorithm the server later presents, widening the trust surface beyond the initial pin. Using --sftp-pin-host-key as a one-shot flag keeps each unauthenticated trust event a deliberate decision. One and done, bestie. That's the move.

🦋 Re-pinning after a legitimate key change 🦋

If the server's host key is legitimately rotated, rclone will refuse the connection with an error containing both the stored and offered SHA256 fingerprints. To accept the new key, clear the stored value and re-run once with the flag:

rclone config update remote host_keys ""
rclone --sftp-pin-host-key lsd remote:

Alternatively, edit host_keys directly to replace or add the new entry. Multiple entries (separated by commas) are supported. Commas!! Not spaces. Commas. 😤

💀 Limitations 💀

• If the server uses an @cert-authority-signed host certificate, host key pinning cannot validate it (the certificate is re-issued periodically even though the underlying CA is unchanged). Use known_hosts_file with an @cert-authority entry instead.
• On-the-fly remotes (:sftp,host=...:) cannot persist the pinned key — rclone will log a warning and re-accept the server key on every run, so the flag only provides first-connect fingerprint logging. Named remotes used with connection string overrides (remote,port=2022:) are fine: the pinned key is saved to the remote's config section.
• If the ssh option is set, the configured ssh program makes the connection and does its own host key validation, so host_keys is not consulted and --sftp-pin-host-key pins nothing. It's giving "not my department."
• Load-balanced SFTP endpoints that present a different host key per backend node will produce a mismatch when a later connection lands on a different node. Re-run with --sftp-pin-host-key after clearing host_keys, or repeat the first-connect step until each node's key has been observed, appending the additional entries to host_keys by hand (comma-separated).
• rclone does not yet support OpenSSH's hostkeys@openssh.com extension, the non-RFC mechanism that helps clients learn additional host keys during rotation. This is being tracked upstream at https://github.com/golang/go/issues/37245

🍓 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. Script bestie behavior. 🫶

🌈 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 types 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. It's doing a vibe check on your shell. 🧚

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 https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse). 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 behave differently, which rclone must handle. Every shell is a different girl and rclone is out here learning all their languages. 💅

Rclone tries to auto-detect what type of shell is used on the server, the first time you access the SFTP remote. If a remote shell session actually gets created, it goes looking for clues that it's CMD or PowerShell, and if it can't tell what it is, it falls back to Unix. If it can't even make a remote shell session happen at all, then shell command execution is fully disabled, periodt. The result gets stored in the SFTP remote configuration, in the option shell_type, so the auto-detection only has to happen, like, once 💅. If you manually set a value for this option before first run, the auto-detection gets skipped entirely — and if you set a different value later, that overrides whatever was already there. The value none can be set to avoid any attempts at executing shell commands, e.g. if that's not allowed on the server. And heads up bestie: if you have shell_type = none in the configuration, then the ssh must not be set. 🫶

When the server is rclone serve sftp (https://rclone.org/commands/rclone_serve_sftp/), the rclone SFTP remote will detect this as a Unix type shell — even if it's running on Windows 👑. This server doesn't actually have a shell, but it accepts input commands matching the specific ones that the SFTP backend relies on for Unix shells, e.g. md5sum and df. It also handles the string escape rules used for Unix shell. So treating it as a Unix type shell from an SFTP remote will therefore always be correct, and it supports all the features ✨.

Shell access considerations 🐚

The shell type auto-detection logic, described above, means that by default rclone will try to run a shell command the very first time a new sftp remote is accessed. If you configure an sftp remote without a config file — e.g. an on the fly (https://rclone.org/docs/#backend-path-to-dir) remote — rclone will have nowhere to store the result, and it will re-run the command on every single access 😭. To avoid this you should explicitly set the shell_type option to the correct value, or to none if you want to prevent rclone from executing any remote shell commands.

It is also super important to note that, 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 💀. 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. no cap.

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. If there is 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. By default MD5 and SHA-1 are considered, but also CRC32, SHA-256, BLAKE3, XXH3 and XXH128 are supported, and the option hashes can be set to specify which to consider 💖.

Normally this requires an external utility being available on the server. E.g. for MD5 checksums, by default rclone will try commands md5sum, md5 and rclone md5sum, and the first one found usable will be picked. 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 for MD5, SHA-1 and SHA-256 when no external checksum commands are found (see shell access). This assumes PowerShell version 4.0 or newer ⭐.

The options md5sum_command, sha1_command, etc. can be used to customize the commands to be executed for calculation of checksums. You can for example set a specific path to where the md5sum executable is located, or specify some other tool that prints checksums in compatible format. The value can include command-line arguments, or even shell script blocks as with PowerShell. Rclone has subcommands hashsum (https://rclone.org/commands/rclone_hashsum/), md5sum (https://rclone.org/commands/rclone_md5sum/) and sha1sum (https://rclone.org/commands/rclone_sha1sum/) that use a 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 an 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. The 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 completely 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 (you get the same effect by setting option hashes to none or options md5sum_command, sha1_command etc. to none). Set option shell_type to none to not only disable checksumming, but also disable all other functionality that is 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 (https://rclone.org/commands/rclone_about/) command, but it depends on the server. 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). 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 (https://rclone.org/commands/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 '', 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 (https://rclone.org/commands/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 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 💀.

This must be false if you use either ciphers or key_exchange advanced options.

Properties:

Properties:

• Config: use_insecure_cipher
• Env Var: RCLONE_SFTP_USE_INSECURE_CIPHER
• Type: bool
• Default: false
• Examples:
  • "false"
    • just use the default Cipher list, bb 💅
  • "true"
    • this one lets you use the aes128-cbc cipher plus the diffie-hellman-group-exchange-sha256 and diffie-hellman-group-exchange-sha1 key exchange. yes fr, those exact ones. 🙈

---

• --sftp-disable-hashcheck — turn OFF the whole "hey lemme run some SSH commands real quick to see if this server does file hashing" thing.

Leave it blank, or set it to false, and hashing stays on (that's the recommended vibe ✨). Set it to true and hashing is off, periodt.

Properties:

• Config: disable_hashcheck
• Env Var: RCLONE_SFTP_DISABLE_HASHCHECK
• Type: bool
• Default: false

---

• --sftp-ssh — path and arguments for an external ssh binary. 🦋

Normally rclone just uses its own internal ssh library to talk to the SFTP server, no drama. But that library doesn't implement every possible ssh option out there, so sometimes you're gonna wanna hand the whole thing off to an external ssh binary instead.

Heads up bestie: when you use this option, rclone ignores all the internal config and just expects you to have configured that ssh binary with the user/host/port and whatever else it needs.

Important The ssh command has to log in without asking for a password, so it needs to be set up with keys or certificates. No password prompts, iykyk. 🔑

rclone will run the command you gave it either with the extra arguments "-s sftp" (to reach the SFTP subsystem) or with commands like "md5sum /path/to/file" tacked on the end to read checksums.

Any arguments with spaces in them should be wrapped in "double quotes".

An example setting might be:

ssh -o ServerAliveInterval=20 user@example.com

Lowkey important: when you're using an external ssh binary, rclone opens a brand new ssh connection for every single hash it calculates. iconic but also 😭

Properties:

• Config: ssh
• Env Var: RCLONE_SFTP_SSH
• Type: SpaceSepList
• Default: (empty)

---

✨ Advanced options ✨

Here are the Advanced options specific to sftp (SSH/SFTP). buckle up babe, this is where it gets good 💖

---

• --sftp-known-hosts-file — optional path to a known_hosts file. 🎀

Set this and you turn on server host key validation. Set it to none to silence that "No host key validation" notice rclone keeps yelling at you about.

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"
    • uses OpenSSH's known_hosts file 💫

---

• --sftp-pin-host-key — pin the server host key on the first connection (Trust On First Use). 👑

This is meant for one-time use as the --sftp-pin-host-key command-line flag. Run rclone once with the flag and boom, the server's host key gets recorded into the host_keys config option. On later runs (without the flag) that host_keys value gets consulted and any mismatch is refused. no cap.

Setting this option persistently in the config file is not recommended. While it's set, rclone will also accept any new host key algorithm the server later presents, which widens the trust surface way beyond that first pin. To pin a new key after a legit key change, just re-run with the flag. 🌸

The first connection is unauthenticated, so ideally do it over a trusted network, or cross-check the fingerprint rclone logs against one you got out of band.

If known_hosts_file is also set, that one takes precedence and this option is simply ignored.

Properties:

• Config: pin_host_key
• Env Var: RCLONE_SFTP_PIN_HOST_KEY
• Type: bool
• Default: false

---

• --sftp-host-keys — pinned host keys for this remote, used to verify the server. 🔒

It's a comma-separated list of "algo base64-key" entries (same format as the second and third fields of an OpenSSH known_hosts line). Usually this gets populated automatically by running once with --sftp-pin-host-key, but you can hand-set it to pin a server's public key you got out of band. Note that each entry is the complete public key, not its SHA256 fingerprint.

When it's non-empty, the host key the server offers must match one of the entries or the connection is refused. To re-pin after a legit key change, clear this option and reconnect with --sftp-pin-host-key, or just edit the value directly.

At most 16 entries may be pinned.

Properties:

• Config: host_keys
• Env Var: RCLONE_SFTP_HOST_KEYS
• Type: CommaSepList
• Default: (empty)

---

• --sftp-ask-password — let rclone ask for the SFTP password when it needs one. 🫶

If this is set and no password was 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 used by SSH shell commands. 💅

This is what lets checksum calculation work when the SFTP path and the SSH path are different. This issue affects, among others, Synology NAS boxes.

E.g. if shared folders live in directories representing volumes:

rclone sync /home/local/directory remote:/directory --sftp-path-override /volume2/directory

E.g. if the home directory lives inside a shared folder called "home":

rclone sync /home/local/directory remote:/home/directory --sftp-path-override /volume1/homes/USER/directory

Wanna specify only the path to the SFTP remote's root, and let rclone add any relative subpaths automatically (including unwrapping/decrypting remotes as needed)? Just slap the '@' character at the beginning of the path. ✨

E.g. that first example above could be rewritten as:

rclone sync /home/local/directory remote:/directory --sftp-path-override @/volume2

Note that when you use this method with Synology "home" folders, you should specify the full /homes/USER path instead of /home.

E.g. the second example above should be 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-encoding — the encoding for the backend. 🌈

Check out the encoding section in the overview (https://rclone.org/overview/#encoding) for all the deets.

Properties:

• Config: encoding
• Env Var: RCLONE_SFTP_ENCODING
• Type: Encoding
• Default: Slash,Del,Ctl,Dot

---

• --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 any. 🐚

Leave it blank and rclone will autodetect for you, bestie.

Properties:

• Config: shell_type
• Env Var: RCLONE_SFTP_SHELL_TYPE
• Type: string
• Required: false
• Examples:
  • "none"
    • no shell access at all
  • "unix"
    • Unix shell
  • "powershell"
    • PowerShell
  • "cmd"
    • Windows Command Prompt

---

• --sftp-hashes — comma separated list of supported checksum types. 🧮

Properties:

• Config: hashes
• Env Var: RCLONE_SFTP_HASHES
• Type: CommaSepList
• Default: (empty)

---

• --sftp-md5sum-command — the command used to read MD5 hashes.

Leave blank for autodetect.

Properties:

• Config: md5sum_command
• Env Var: RCLONE_SFTP_MD5SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-sha1sum-command — the command used to read SHA-1 hashes.

Leave blank for autodetect.

Properties:

• Config: sha1sum_command
• Env Var: RCLONE_SFTP_SHA1SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-crc32sum-command — the command used to read CRC-32 hashes.

Leave blank for autodetect.

Properties:

• Config: crc32sum_command
• Env Var: RCLONE_SFTP_CRC32SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-sha256sum-command — the command used to read SHA-256 hashes.

Leave blank for autodetect.

Properties:

• Config: sha256sum_command
• Env Var: RCLONE_SFTP_SHA256SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-blake3sum-command — the command used to read BLAKE3 hashes.

Leave blank for autodetect.

Properties:

• Config: blake3sum_command
• Env Var: RCLONE_SFTP_BLAKE3SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-xxh3sum-command — the command used to read XXH3 hashes.

Leave blank for autodetect.

Properties:

• Config: xxh3sum_command
• Env Var: RCLONE_SFTP_XXH3SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-xxh128sum-command — the command used to read XXH128 hashes.

Leave blank for autodetect.

Properties:

• Config: xxh128sum_command
• Env Var: RCLONE_SFTP_XXH128SUM_COMMAND
• Type: string
• Required: false

---

• --sftp-skip-links — set this to skip any symlinks and any other non regular files. 🚫🔗

This only affects listing: symlinks and other non regular files get omitted from directory listings. It is not a security control and does not stop writes from following symlinks on the server — confining an SFTP account to a directory has to be enforced server side (for example with a chroot jail or restricted permissions). fr fr, do not rely on this for that.

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 a sftp server on the remote host.

The subsystem option is ignored when server_command is defined. 💀

If you're adding server_command to the configuration file please note that it should not be enclosed in quotes, since 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 limit how many open files you can have, and calling Stat after opening the file will make the server throw an error. Setting this flag calls Fstat instead of Stat, and Fstat works on an already-open file handle. slay.

It's been found that this helps with IBM Sterling SFTP servers that have their "extractability" level set to 1, which means only 1 file can be opened at any given time.

Properties:

• Config: use_fstat
• Env Var: RCLONE_SFTP_USE_FSTAT
• Type: bool
• Default: false

• --sftp-disable-concurrent-reads — flip this on and we don't do concurrent reads, periodt.

Normally concurrent reads are safe safe and turning them off is literally just gonna tank your performance, bestie, which is why this one is off by default. But some servers be gatekeeping how many times a file can be downloaded 😤 and concurrent reads can trip that limit. So if your server keeps hitting you with

Failed to copy: file does not exist

then yeah, you might need to enable this flag.

Oh and heads up: if concurrent reads are disabled, the use_fstat option is just ignored. Bye.

Properties:

• Config: disable_concurrent_reads
• Env Var: RCLONE_SFTP_DISABLE_CONCURRENT_READS
• Type: bool
• Default: false

• --sftp-disable-concurrent-writes — set it and no concurrent writes, simple as that.

Normally rclone uses concurrent writes to upload files, and the way that it improves performance greatly — especially for distant servers — is iconic ngl. This option disables concurrent writes should that be necessary.

Properties:

• Config: disable_concurrent_writes
• Env Var: RCLONE_SFTP_DISABLE_CONCURRENT_WRITES
• Type: bool
• Default: false

• --sftp-idle-timeout — max time before we close 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_SFTP_IDLE_TIMEOUT
• Type: Duration
• Default: 1m0s

• --sftp-chunk-size — the upload and download chunk size 🎀

This controls the maximum size of payload in SFTP protocol packets. The RFC limits this to 32768 bytes (32k), which is the default. BUT 💅 a lot of servers support larger sizes — typically limited to a maximum total package size of 256k — and setting it larger will increase transfer speed dramatically on high latency links. This includes OpenSSH, and for example, using the value of 255k works well, leaving plenty of room for overhead while still being within a total packet size of 256k.

⚠️ Bestie, please 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.

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, 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, fr fr.

If you are 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 run (eg md5sum).

Pass multiple variables space separated, eg

VAR1=value VAR2=value

and pass variables with 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:

• --sftp-ciphers — space separated list of ciphers to be used for session encryption, ordered by preference 🔐

At least one must match with server configuration. This can be checked for example using ssh -Q cipher.

This must not be set 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:

• --sftp-key-exchange — space separated list of key exchange algorithms, ordered by preference 🔑

At least one must match with server configuration. This can be checked for example using ssh -Q kex.

This must not be set 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:

• --sftp-macs — space separated list of MACs (message authentication code) algorithms, ordered by preference 🧚

At least one must match with server configuration. This can be checked for example using ssh -Q mac.

Example:

umac-64-etm@openssh.com umac-128-etm@openssh.com hmac-sha2-256-etm@openssh.com

Properties:

• Config: macs
• Env Var: RCLONE_SFTP_MACS
• Type: SpaceSepList
• Default:

• --sftp-host-key-algorithms — space separated list of host key algorithms, ordered by preference 🎀

At least one must match with server configuration. This can be checked for example using ssh -Q HostKeyAlgorithms.

Note: This can affect the outcome of key negotiation with the server even if server host key validation is not enabled.

Example:

ssh-ed25519 ssh-rsa ssh-dss

Properties:

• Config: host_key_algorithms
• Env Var: RCLONE_SFTP_HOST_KEY_ALGORITHMS
• Type: SpaceSepList
• Default:

• --sftp-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_SFTP_SOCKS_PROXY
• Type: string
• Required: false

• --sftp-http-proxy — URL for HTTP CONNECT proxy 🌐

Set this to a URL for an HTTP proxy which supports the HTTP CONNECT verb.

Supports the format http://user:pass@host:port, http://host:port, http://host.

Example:

http://myUser:myPass@proxyhostname.example.com:8000

Properties:

• Config: http_proxy
• Env Var: RCLONE_SFTP_HTTP_PROXY
• Type: string
• Required: false

• --sftp-copy-is-hardlink — set to enable server side copies using hardlinks 👑

The SFTP protocol does not define a copy command so normally server side copies are not allowed with the sftp backend.

However the SFTP protocol does support hardlinking, and if you enable this flag then the sftp backend will support server side copies. These will be implemented by doing a hardlink from the source to the destination.

Not all sftp servers support this.

Note that hardlinking two files together will use no additional space as the source and the destination will be the same file.

This feature may be useful backups made with --copy-dest.

Properties:

• Config: copy_is_hardlink
• Env Var: RCLONE_SFTP_COPY_IS_HARDLINK
• Type: bool
• Default: false

• --sftp-description — description of the remote 💖

Properties:

• Config: description
• Env Var: RCLONE_SFTP_DESCRIPTION
• Type: string
• Required: false

---

💀 Limitations 💀

On some SFTP servers (e.g. Synology) the paths are different for SSH and SFTP so the hashes can't be calculated properly. You can either use --sftp-path-override or disable_hashcheck.

The only ssh agent supported under Windows is Putty's pageant.

The Go SSH library disables the use of the aes128-cbc cipher by default, due to security concerns. 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 (http://www.isg.rhul.ac.uk/~kp/SandPfinal.pdf).

SFTP isn't supported under plan9 until this issue (https://github.com/pkg/sftp/issues/156) is fixed.

Note that since SFTP isn't HTTP based the following flags don't work with it: --dump headers, --dump bodies, --dump auth.

Note that --timeout and --contimeout are both supported.

---

🌈 rsync.net 🌈

rsync.net is supported through the SFTP backend.

See rsync.net's documentation of rclone examples (https://www.rsync.net/products/rclone.html).

---

📦 Hetzner Storage Box 📦

Hetzner Storage Boxes are supported through the SFTP backend on port 23.

See Hetzner's documentation for details (https://docs.hetzner.com/robot/storage-box/access/access-ssh-rsync-borg#rclone)

🌈 Shade

Ok bestie, this one's a whole backend for the Shade platform — like, https://shade.inc/ — and we're about to get into it. ✨

🦋 About Shade

So basically Shade (https://shade.inc/) is an AI-powered cloud NAS that makes your cloud files act like a local drive?? Iconic behaviour honestly. It's optimized for media and creative workflows, and it gives you fast, secure access plus natural-language search, easy sharing, and scalable cloud storage. Chef's kiss. 👑

💸 Accounts & Pricing

To use this backend you need to make a free account (https://app.shade.inc/) on Shade. You can start free and get 20GB of storage for free — like, actually free, no cap. 🎀

📁 Usage

Paths are specified as remote:path

Paths may be as deep as required, e.g. remote:directory/subdirectory.

⚙️ Configuration

Here's an example of making a Shade configuration, step by step, like a little tutorial for my besties. 🫶

First, create a create a free account (https://app.shade.inc/) account and choose a plan.

You will need to log in and get the API Key and Drive ID for your account from the settings section of your account and created drive respectively.

Now run

rclone config

Follow this interactive process:

$ rclone config
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

Enter name for new remote.
name> Shade

Option Storage.
Type of storage to configure.
Choose a number from below, or type in your own value.
[OTHER OPTIONS]
xx / Shade FS
   \ (shade)
[OTHER OPTIONS]
Storage> xx

Option drive_id.
The ID of your drive, see this in the drive settings. Individual rclone configs must be made per drive.
Enter a value.
drive_id> [YOUR_ID]

Option api_key.
An API key for your account.
Enter a value.
api_key> [YOUR_API_KEY]

Edit advanced config?
y) Yes
n) No (default)
y/n> n

Configuration complete.
Options:
- type: shade
- drive_id: [YOUR_ID]
- api_key: [YOUR_API_KEY]
Keep this "Shade" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y

🕐 Modification times and hashes

Shade does not support hashes and writing mod times. It's giving "we don't do that here" and honestly, we cope. 😭

📤 Transfers

Shade uses multipart uploads by default. This means that files will be chunked and sent up to Shade concurrently. In order to configure how many simultaneous uploads you want to use, upload the 'concurrency' option in the advanced config section. Note that this uses more memory and initiates more http requests. 💅

🗑️ Deleting files

Please note that when deleting files in Shade via rclone it will delete the file instantly, instead of sending it to the trash. This means that it will not be recoverable.

⚠️ Bestie read this twice: gone is gone. No trash, no undo, no resurrection arc. 🙈

✨ Standard options

Here are the Standard options specific to shade (Shade FS).

💖 --shade-drive-id

The ID of your drive, see this in the drive settings. Individual rclone configs must be made per drive.

Properties:

• Config: drive_id
• Env Var: RCLONE_SHADE_DRIVE_ID
• Type: string
• Required: true

💖 --shade-api-key

An API key for your account.

Properties:

• Config: api_key
• Env Var: RCLONE_SHADE_API_KEY
• Type: string
• Required: true

🔥 Advanced options

Here are the Advanced options specific to shade (Shade FS).

🌟 --shade-endpoint

Endpoint for the service.

Leave blank normally.

Properties:

• Config: endpoint
• Env Var: RCLONE_SHADE_ENDPOINT
• Type: string
• Required: false

🌟 --shade-chunk-size

Chunk size to use for uploading.

Any files larger than this will be uploaded in chunks of this size.

Note that this is stored in memory per transfer, so increasing it will increase memory usage.

Minimum is 5MB, maximum is 5GB.

Properties:

• Config: chunk_size
• Env Var: RCLONE_SHADE_CHUNK_SIZE
• Type: SizeSuffix
• Default: 64Mi

🌟 --shade-upload-concurrency

Concurrency for multipart uploads and copies. This is the number of chunks of the same file that are uploaded concurrently for multipart uploads and copies.

Properties:

• Config: upload_concurrency
• Env Var: RCLONE_SHADE_UPLOAD_CONCURRENCY
• Type: int
• Default: 4

🌟 --shade-max-upload-parts

Maximum amount of parts in a multipart upload.

Properties:

• Config: max_upload_parts
• Env Var: RCLONE_SHADE_MAX_UPLOAD_PARTS
• Type: int
• Default: 10000

🌟 --shade-token

JWT Token for performing Shade FS operations. Don't set this value - rclone will set it automatically

Properties:

• Config: token
• Env Var: RCLONE_SHADE_TOKEN
• Type: string
• Required: false

🌟 --shade-token-expiry

JWT Token Expiration time. Don't set this value - rclone will set it automatically

Properties:

• Config: token_expiry
• Env Var: RCLONE_SHADE_TOKEN_EXPIRY
• Type: string
• Required: false

🌟 --shade-encoding

The encoding for the backend.

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_SHADE_ENCODING
• Type: Encoding
• Default: Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot

🌟 --shade-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_SHADE_DESCRIPTION
• Type: string
• Required: false

🚧 Limitations

Note that Shade is case insensitive so you can't have a file called "Hello.doc" and one called "hello.doc". Pick one, bestie. 😭

Shade only supports filenames up to 255 characters in length.

rclone about is not supported by the Shade 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 (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/)

🛠️ Backend commands

Here are the commands specific to the shade backend.

Run them with

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend (https://rclone.org/commands/rclone_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 (https://rclone.org/rc/#backend-command).

✨💖 SMB 💖✨

Okay bestie, SMB is a communication protocol for sharing files over a network (<https://en.wikipedia.org/wiki/Server_Message_Block>).

This one leans on the go-smb2 library (<https://github.com/CloudSoda/go-smb2/>) to do all the talking with the SMB protocol.

Paths go like remote:sharename (or just remote: if you're doing the lsd command 🌸). You can totally drop subdirectories in there too, like remote:item/path/to/dir.

📝 Notes

The very first path segment has to be the name of the share — the one you typed when you started sharing on Windows. On smbd, it's the section title in smb.conf (usually chillin' in /etc/samba/). Not sure what shares exist? Just query the root, like rclone lsd remote: 🦋

You can't get at shared printers from rclone. Obviously. 💀

You also can't use Anonymous access to log in — nope, not a thing here. You have to use the guest user with an empty password instead. The rclone client tries to dodge 8.3 names when uploading files by encoding trailing spaces and periods. Alternatively, the local backend (<https://rclone.org/local/#paths-on-windows>) on Windows can reach SMB servers using UNC paths, via \\server\share. That trick does not apply to non-Windows OSes like Linux and macOS, sorry bestie. 🙈

⚙️ Configuration

Here's an example of setting up a SMB configuration.

First run

rclone config

This will walk you through an interactive setup process, like a lil guided tour 💅

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 / SMB / CIFS
   \ (smb)
Storage> smb

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

🌟 Standard options

Here are the Standard options specific to smb (SMB / CIFS). ✨

--smb-host

SMB server hostname to connect to.

E.g. "example.com".

Properties:

• Config: host
• Env Var: RCLONE_SMB_HOST
• Type: string
• Required: true

--smb-user

SMB username.

Leave blank to use the current user name.

Properties:

• Config: user
• Env Var: RCLONE_SMB_USER
• Type: string
• Required: false

--smb-port

SMB port number.

Properties:

• Config: port
• Env Var: RCLONE_SMB_PORT
• Type: int
• Default: 445

--smb-pass

SMB password.

NB Input to this must be obscured — see rclone obscure (<https://rclone.org/commands/rclone_obscure/>).

Properties:

• Config: pass
• Env Var: RCLONE_SMB_PASS
• Type: string
• Required: false

--smb-domain

Domain name for NTLM authentication.

Properties:

• Config: domain
• Env Var: RCLONE_SMB_DOMAIN
• Type: string
• Default: "WORKGROUP"

--smb-spn

Service principal name.

Rclone shows this name to the server. Some servers use it as extra authentication, and it often needs to be set for clusters. For example:

cifs/remotehost:1020

Leave blank if you're not sure. 🫶

Properties:

• Config: spn
• Env Var: RCLONE_SMB_SPN
• Type: string
• Required: false

--smb-use-kerberos

Use Kerberos authentication.

If set, rclone will use Kerberos authentication instead of NTLM. This needs a valid Kerberos configuration and credentials cache available — either in the default locations or as specified by the KRB5_CONFIG and KRB5CCNAME environment variables.

Properties:

• Config: use_kerberos
• Env Var: RCLONE_SMB_USE_KERBEROS
• Type: bool
• Default: false

🔥 Advanced options

Here are the Advanced options specific to smb (SMB / CIFS).

--smb-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_SMB_IDLE_TIMEOUT
• Type: Duration
• Default: 1m0s

--smb-hide-special-share

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

--smb-case-insensitive

Whether the server is configured to be case-insensitive.

Always true on Windows shares.

Properties:

• Config: case_insensitive
• Env Var: RCLONE_SMB_CASE_INSENSITIVE
• Type: bool
• Default: true

--smb-kerberos-ccache

Path to the Kerberos credential cache (krb5cc).

Overrides the default KRB5CCNAME environment variable and lets this instance of the SMB backend use a different Kerberos cache file. Super useful when you're mounting multiple SMB with different credentials or running in multi-user environments. 👑

Supported formats:

• FILE:/path/to/ccache – Use the specified file.
• DIR:/path/to/ccachedir – Use the primary file inside the specified directory.
• /path/to/ccache – Interpreted as a file path.

Properties:

• Config: kerberos_ccache
• Env Var: RCLONE_SMB_KERBEROS_CCACHE
• Type: string
• Required: false

--smb-encoding

The encoding for the backend.

See the encoding section in the overview (<https://rclone.org/overview/#encoding>) 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

--smb-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_SMB_DESCRIPTION
• Type: string
• Required: false

---

🌈 Storj 🌈

Storj (<https://storj.io>) 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 lets you store, back up, and archive large amounts of data in a decentralized manner. So cute, so decentralized ✨

🧚 Backend options

Storj can be used both with this native backend and with the s3 backend using the Storj S3 compatible gateway (<https://rclone.org/s3/#storj>) (shared or private).

Use this backend to take advantage of client-side encryption, plus to get the best possible download performance. Uploads get erasure-coded locally, so a 1gb upload will result in 2.68gb of data being uploaded to storage nodes across the network. 😭 (yes, really)

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, so a 1GB upload will result in only 1GB of data being uploaded to storage nodes across the network. Slay 🫶

Side by side comparison with more details:

• Characteristics:
  • Storj backend: 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
  • S3 backend: 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.
• Typical usage:
  • Storj backend: Server environments and desktops with enough resources, internet speed and connectivity — and applications where storjs client-side encryption is required.
  • S3 backend: Desktops and similar with limited resources, internet speed or connectivity.
• Security:
  • Storj backend: strong. Private encryption key doesn't need to leave the local computer.
  • S3 backend: weaker. Private encryption key is shared with (<https://docs.storj.io/dcs/api-reference/s3-compatible-gateway#security-and-encryption>) the authentication service of the hosted gateway, where it's stored encrypted. It can be stronger when combining with the rclone crypt backend.
• Bandwidth usage (upload):
  • Storj backend: 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.
  • S3 backend: normal. Only the raw data is uploaded, erasure coding happens on the gateway.
• Bandwidth usage (download)
• Storj backend: it's giving 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).
  • S3 backend: normal. Only the raw data is downloaded, erasure coding happens on the shared gateway. Simple as that 💅
• CPU usage:
  • Storj backend: higher, but more predictable. Erasure code and encryption/decryption happens locally which requires significant CPU usage.
  • S3 backend: less. Erasure code and encryption/decryption happens on shared s3 gateways (and as is, it depends on the current load on the gateways).
• TCP connection usage:
  • Storj backend: 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 (https://rclone.org/storj/#known-issues) may be required.
  • S3 backend: normal. Only one connection per download/upload thread is required to the shared gateway.
• Overall performance:
  • Storj backend: 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.
  • S3 backend: 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.
• Decentralization:
  • Storj backend: high. Data is downloaded directly from the distributed cloud of storage providers.
  • S3 backend: low. Requires a running S3 gateway (either self-hosted or Storj-hosted).
• Limitations:
  • Storj backend: rclone checksum is not possible without download, as checksum metadata is not calculated during upload 💀
  • S3 backend: secret encryption key is shared with the gateway 🙈

---

⚙️ Configuration ⚙️

To make a new Storj configuration you need one of the following, bestie — pick your fighter:

• Access Grant that someone else shared with you.
• API Key (https://storj.dev/learn/concepts/access/access-grants/api-key) of a Storj project you are a member of.

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 cap 💖

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

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> existing
Access Grant.
Enter a string value. Press Enter for the default ("").
access_grant> your-access-grant-received-by-someone-else
Remote config
Configuration complete.
Options:
- 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). Lock in 🎀

--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). Yes bestie, there's more 👑

--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. Let's gooo 🦋

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. Don't forget it, bestie, it's lowkey essential 💅

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 modified files will be copied. ✨

List objects

Use the ls command to list recursively all objects in a bucket.

rclone ls remote:bucket

Add the folder to the remote path to list recursively all objects in this folder.

$ rclone ls remote:bucket
/path/to/dir/

Use the lsf command to list non-recursively all objects in a bucket or a folder.

rclone lsf remote:bucket/path/to/dir/

Download objects

Use the copy command to download an object.

rclone copy --progress remote:bucket/path/to/dir/file.ext /home/local/directory/

The --progress flag is for displaying progress information. Remove it if you don't need this information.

Use a folder in the remote path to download all its objects.

rclone copy --progress remote:bucket/path/to/dir/ /home/local/directory/

Delete objects

Use the deletefile command to delete a single object.

rclone deletefile remote:bucket/path/to/dir/file.ext

Use the delete command to delete all object in a folder.

rclone delete remote:bucket/path/to/dir/

Print the total size of objects

Use the size command to print the total size of objects in a bucket or a folder.

rclone size remote:bucket/path/to/dir/

Sync two Locations

Use the sync command to sync the source to the destination, changing the destination only, deleting any excess files.

rclone sync --interactive --progress /home/local/directory/ remote:bucket/path/to/dir/

Heads up bestie — sync changes the destination only and deletes excess files there, so vibe check your paths before you hit enter 💀

The --progress flag is just there so you can watch the little bars go ✨ — if you don't need that info, drop it, it's not that deep.

bestie, this can genuinely cause data loss, so please test first with the --dry-run flag so you can see exactly what would be copied and deleted. no cap. 💀

You can also do the sync the other way around — Storj ➡️ your local file system:

rclone sync --interactive --progress remote:bucket/path/to/dir/ /home/local/directory/

Or between two Storj buckets, iconic glow-up style:

rclone sync --interactive --progress remote-us:bucket/path/to/dir/ remote-europe:bucket/path/to/dir/

Or even between some other cloud storage and Storj, because rclone does not play favourites:

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. 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. 😭

Go peek at List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

Known issues 🫠

If you get errors like too many open files, this usually happens when the default ulimit for system max open files is exceeded. Native Storj protocol opens a large number of TCP connections (each of which is counted as an open file). For a single upload stream you can expect 110 TCP connections to be opened. For a single download stream you can expect 35. This batch of connections will be opened for every 64 MiB segment and you should also expect TCP connections to be reused. If you do many transfers you eventually open a connection to most storage nodes (thousands of nodes). it's giving swarm energy fr fr 🐝

To fix these, please raise your system limits. You can do this issuing a ulimit -n 65536 just before you run rclone. To change the limits more permanently you can add this 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. 📚

---

🍬 SugarSync 🍬

SugarSync (https://sugarsync.com) is a cloud service that enables active synchronization of files across computers and other devices for file backup, access, syncing, and sharing. very "my files follow me around like a loyal little duckling" of it 🦆

Configuration 🔧

The initial setup for SugarSync involves getting a token from SugarSync which you can do with rclone. rclone config walks you through it. slay, hand-held the whole way 🫶

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

Note that the config asks for your email and password but doesn't store them, it only uses them to get the initial token. your secrets stay your secrets, periodt 💅

Once configured you can then use rclone like this (replace remote with the name you gave your remote):

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. 🎀 (the top level is like, decorative only, bestie)

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 as rclone can read the time files were uploaded.

Restricted filename characters 🚫

SugarSync replaces the default restricted characters set (https://rclone.org/overview/#restricted-characters) except for DEL.

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), 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. gone gone, no recycle bin era 🔥

Standard options ⭐

Here are the Standard options specific to sugarsync (Sugarsync).

• --sugarsync-app-id — Sugarsync App ID.

Leave blank to use rclone's.

Properties:

• Config: app_id
• Env Var: RCLONE_SUGARSYNC_APP_ID
• Type: string
• Required: false

• --sugarsync-access-key-id — Sugarsync Access Key ID.

Leave blank to use rclone's.

Properties:

• Config: access_key_id
• Env Var: RCLONE_SUGARSYNC_ACCESS_KEY_ID
• Type: string
• Required: false

• --sugarsync-private-access-key — Sugarsync Private Access Key.

Leave blank to use rclone's.

Properties:

• Config: private_access_key
• Env Var: RCLONE_SUGARSYNC_PRIVATE_ACCESS_KEY
• Type: string
• Required: false

• --sugarsync-hard-delete — Permanently delete files if true otherwise put them in the deleted files.

Properties:

• Config: hard_delete
• Env Var: RCLONE_SUGARSYNC_HARD_DELETE
• Type: bool
• Default: 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:

• Config: refresh_token
• Env Var: RCLONE_SUGARSYNC_REFRESH_TOKEN
• Type: string
• Required: false

• --sugarsync-authorization — Sugarsync authorization.

Leave blank normally, will be auto configured by rclone.

Properties:

• Config: authorization
• Env Var: RCLONE_SUGARSYNC_AUTHORIZATION
• Type: string
• Required: false

• --sugarsync-authorization-expiry — Sugarsync authorization expiry.

Leave blank normally, will be auto configured by rclone.

Properties:

• Config: authorization_expiry
• Env Var: RCLONE_SUGARSYNC_AUTHORIZATION_EXPIRY
• Type: string
• Required: false

• --sugarsync-user — Sugarsync user.

Leave blank normally, will be auto configured by rclone.

Properties:

• Config: user
• Env Var: RCLONE_SUGARSYNC_USER
• Type: string
• Required: false

• --sugarsync-root-id — Sugarsync root id.

Leave blank normally, will be auto configured by rclone.

Properties:

• Config: root_id
• Env Var: RCLONE_SUGARSYNC_ROOT_ID
• Type: string
• Required: false

• --sugarsync-deleted-id — Sugarsync deleted folder id.

Leave blank normally, will be auto configured by rclone.

Properties:

• Config: deleted_id
• Env Var: RCLONE_SUGARSYNC_DELETED_ID
• Type: string
• Required: false

• --sugarsync-encoding — The encoding for the backend.

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_SUGARSYNC_ENCODING
• Type: Encoding
• Default: Slash,Ctl,InvalidUtf8,Dot

• --sugarsync-description — Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_SUGARSYNC_DESCRIPTION
• Type: string
• Required: false

Limitations 🌸

rclone about is not supported by the SugarSync 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. yeah, it just doesn't know how much room is left, don't ask her 💀

See List of backends that do not support rclone about (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

✨ Uloz.to ✨

Ok bestie, so paths here are literally just written like remote:path 💅

And they can go as deep as you need, no cap — like remote:directory/subdirectory.

The whole initial setup is just you filling in your user credentials, and rclone config holds your hand through the entire thing 🫶

---

🎀 Configuration

Here's a whole example of how to make a remote called remote. First, run:

rclone config

It'll walk you through an interactive setup, 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 / Uloz.to
   \ "ulozto"
[snip]
Storage> ulozto

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 that's all set up, you can use rclone like this (and swap remote out for whatever name you gave yours):

List the folders sitting in your root level folder:

rclone lsd remote:

List every single file in your root folder:

rclone ls remote:

And to copy a local folder into a Uloz.to folder called backup:

rclone copy /home/source remote:backup

---

🌸 User credentials

The only reliable method is authenticating the user with a username and password, periodt. Uloz.to does also offer an API key, but that one's reserved for Uloz.to's own in-house application, and using it in other circumstances is like… unreliable bestie 😭

---

🦋 Modification times and hashes

Uloz.to does not let you set a custom modification time, and you can't retrieve the hashes after upload either. So what does the integration do? 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 gets verified on upload. After that though, the backend only serves the client-side calculated hashes. You can also grab hashes when you create a file download link, but honestly that's impractical for list-like use cases.

---

🧚 Restricted filename characters

On top of the default restricted characters set (https://rclone.org/overview/#restricted-characters), these characters get replaced too:

• \ — value 0x5C — replacement ＼

Invalid UTF-8 bytes get replaced as well (https://rclone.org/overview/#invalid-utf8), because they literally can't be used inside JSON strings. Bye 💀

---

🔥 Transfers

All files are currently uploaded using a single HTTP request, so if you're uploading big files you need a stable connection, no cap. Rclone will upload up to --transfers chunks at the same time, shared across all uploads.

---

💀 Deleting files

By default, files get moved to the recycle bin, whereas folders are deleted immediately. Trashed files are permanently deleted after 30 days in the recycle bin.

Emptying the trash is currently not implemented in rclone. So don't come for me.

---

👑 Root folder ID

You can set the root_folder_slug for rclone. This is the folder (identified by its Folder slug) that rclone treats as the root of your Uloz.to drive.

Normally you just leave this blank and rclone figures out the correct root by itself. But you can set it to restrict rclone to one specific folder hierarchy.

To do that, you'll need to find the Folder slug of the folder you want as root. It's the last segment of the URL when you open that folder in the Uloz.to web interface.

So for example, for exploring a folder with URL https://uloz.to/fm/my-files/foobar, you'd use foobar as the root slug.

root_folder_slug can be used alongside a specific path in the remote path too. Like, if your remote's root_folder_slug corresponds to /foo/bar, then remote:baz/qux refers 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 (https://rclone.org/commands/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' with no 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 (https://rclone.org/overview/#encoding) 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 them. rclone maps this to and from an identical looking unicode equivalent ＼ (U+FF3C Fullwidth Reverse Solidus).

Uloz.to only supports filenames up to 255 characters in length.

Uloz.to rate limits access to the API, but the exact details are undisclosed 👀 Practical testing reveals that hitting the rate limit during normal use is very rare, though not impossible with a higher number of concurrently uploaded files.

rclone about is not supported by the Uloz.to backend. Even though there's an endpoint to retrieve that info for the UI, it's not exposed in the API. Backends without this capability can't determine free space for an rclone mount, and they 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 (https://rclone.org/overview/#optional-features) and rclone about (https://rclone.org/commands/rclone_about/).

---

🌈 Union 🌈

The union backend joins several remotes together so you get one single unified view of all of them. It's giving main character energy, honestly 💅

During the initial setup with rclone config you'll specify the upstream remotes as a space separated list. Those upstream remotes can be local paths or other remotes, whatever you vibe with.

The attributes :ro, :nc and :writeback can be attached to the end of the remote to tag it as read only, no create, or writeback — like 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 too. Say you have a union remote named backup with the remotes mydrive:private/backup. Then running rclone mkdir backup:desktop is exactly the same as running rclone mkdir mydrive:private/backup/desktop.

There is no special handling of paths containing .. segments. Running rclone mkdir backup:../desktop is exactly the same as running rclone mkdir mydrive:private/backup/../desktop. Yeah, fr fr, it doesn't clean that up for you 😭

---

🎀 Configuration

Here's 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

Okay bestie so that's the whole interactive setup, start to finish, and then the fun part starts 💖

Once you've got it configured you can just… use rclone like a normal person. Like this:

• Listing directories in the top level across remote1:dir1, remote2:dir2 and remote3:dir3:

rclone lsd remote:

• Listing all the files in remote1:dir1, remote2:dir2 and remote3:dir3:

rclone ls remote:

• Copying another local directory into the union directory called source, which is gonna land in remote3:dir3:

rclone copy C:\source remote:source

🌸 Behavior / Policies 🌸

The whole vibe of this union backend is inspired by trapexit/mergerfs (https://github.com/trapexit/mergerfs). Every function gets sorted into one of 3 categories: action, create and search. Those functions (and the categories themselves) get handed a policy, and that policy decides which file or directory gets picked when that behavior runs 🎀

Any policy can technically be assigned to any function or category — but some combos are, and I say this with love, not it. For instance: rand (random) is lowkey perfect for file creation (create), but if you used it for delete and there was more than one copy of a file, the behavior would get extremely weird. So. Don't.

🧚 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 — size, about

💅 Path Preservation 💅

Okay so the policies below come in two flavors: path preserving and non-path preserving.

Every policy that starts with ep (epff, eplfs, eplus, epmfs, eprand) is path preserving. And ep literally stands for existing path, no cap ✨

A path preserving policy will only consider upstreams where the relative path you're touching already exists.

When you're using non-path preserving policies, paths get created in the target upstreams as needed. Simple as that.

🍓 Quota Relevant Policies 🍓

Some policies are nosy — they rely on quota info. Those ones should only be used if your upstreams actually 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

Wanna check if your upstream supports the field? Just run rclone about remote: [flags] and see if the required field exists. Easy 💖

🎀 Filters 🎀

Policies basically go search your upstream remotes and build a list of files / paths for the functions to work on. The policy is the one doing the filtering and the sorting. The policy type defines the sorting, but the filtering is mostly uniform, and here's how it goes:

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

And if all remotes get filtered, an error comes back at you. Sorry not sorry 😭

👑 Policy descriptions 👑

These policy definitions are inspired by trapexit/mergerfs (https://github.com/trapexit/mergerfs) but they're not exactly the same — some definitions had to change because of the much larger latency of remote file systems. Fr fr.

• 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 🦋

You can slap the tag :writeback on an upstream remote to build yourself a little cache system, like this:

[union]
type = union
action_policy = all
create_policy = all
search_policy = ff
upstreams = /local:writeback remote:dir

So when files are opened for read: if the file is in remote:dir but not in /local, then rclone will copy that 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'll use --multi-thread-streams if you configured it. And every copy gets logged with an INFO log 📝

When files are written, they get written to both remote:dir and /local. Both. Slay.

You can add as many remotes as you want to upstreams, but there should only be one :writeback tag.

Heads up bestie: 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, that's on you. You'll 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.

Properties:

• Config: min_free_space
• Env Var: RCLONE_UNION_MIN_FREE_SPACE
  • Type: SizeSuffix
  • Default: 1Gi
• --union-description — a lil description of the remote, just for you bestie 💖

Properties:

• Config: description
• Env Var: RCLONE_UNION_DESCRIPTION
• Type: string
• Required: false

📝 Metadata

Any metadata that the underlying remote supports? Yeah, rclone reads it and writes it. Full send both ways 💅

Peep the metadata docs for the whole scoop: https://rclone.org/docs/#metadata

---

🌐 WebDAV

Paths go like remote:path — that's the whole vibe.

And they can be as deep as you want, no cap. Like remote:directory/subdirectory, go off 🦋

⚙️ Configuration

okay so to set up a WebDAV remote you're gonna need three things: a URL for it, plus a username and a password. And here's the tea — if you already know what kind of system you're connecting to, rclone can flip on some extra features for you ✨

So like, here's how you make a remote called remote. First things first, run:

rclone config

It's gonna hold your hand through an interactive setup, fr fr:

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 you've got it all configured, you can use rclone like this — just swap remote out for whatever name you gave yours 💅

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? It does not support modified times, periodt. But the way that it does work with Fastmail Files, ownCloud or Nextcloud? rclone will support modified times there 🔥

Same deal with hashes — plain WebDAV doesn't support them, but when you're rolling with Fastmail Files, ownCloud or Nextcloud, rclone supports SHA1 and MD5 hashes. And depending on the exact version of ownCloud or Nextcloud, hashes might show up on all objects, or only on objects that had a hash uploaded along with them. With Nextcloud specifically, rclone asks the server to calculate the SHA1 for uploads that had no hash to send — like streamed uploads — and then after it sets the modification time, that stored hash gets discarded. Rip 😭

🌟 Standard options

Here are the Standard options specific to webdav (WebDAV). Slay.

--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 10 PHP based WebDAV server
  • "infinitescale"
    • ownCloud Infinite Scale
  • "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.

Heads up bestie: if NTLM authentication is being used, the username has to be in the format 'Domain' 👑

Properties:

• Config: user
• Env Var: RCLONE_WEBDAV_USER
• Type: string
• Required: false

--webdav-pass

Password.

NB! What you put in here has to be obscured — see rclone obscure (https://rclone.org/commands/rclone_obscure/) 🫶

Properties:

• Config: pass
• Env Var: RCLONE_WEBDAV_PASS
• Type: string
• Required: false

--webdav-bearer-token

Bearer token instead of user/pass (e.g. a Macaroon).

Properties:

• Config: bearer_token
• Env Var: RCLONE_WEBDAV_BEARER_TOKEN
• Type: string
• Required: false

💎 Advanced options

Here are the Advanced options specific to webdav (WebDAV). Oh we're going deeper, obsessed 🌸

--webdav-bearer-token-command

Command to run to get a bearer token.

Properties:

• Config: bearer_token_command
• Env Var: RCLONE_WEBDAV_BEARER_TOKEN_COMMAND
• Type: string
• Required: false

--webdav-encoding

The encoding for the backend.

Check the encoding section in the overview (https://rclone.org/overview/#encoding) for more info, iykyk.

Default encoding is Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Hash,Percent,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8 for sharepoint-ntlm, or identity otherwise.

Properties:

• Config: encoding
• Env Var: RCLONE_WEBDAV_ENCODING
• Type: string
• Required: false

--webdav-headers

Set HTTP headers for all transactions.

Use this to set additional HTTP headers for every single transaction, fr fr.

The input format is a comma separated list of key,value pairs. Standard CSV encoding (https://godoc.org/encoding/csv) may be used.

So like, to set a Cookie, use 'Cookie,name=value', or '"Cookie","name=value"'.

And you can set multiple headers, e.g. '"Cookie","name=value","Authorization","xxx"'.

Here's the important bit though: the headers are only sent to the host in the configured URL. If the server redirects to another host (including a subdomain or a different port), the headers are not sent to it, or to any further hop in that redirect chain. The one exception is the directory listing and file download requests when auth_redirect is set — because that keeps all credentials across redirects 💅

Properties:

• Config: headers
• Env Var: RCLONE_WEBDAV_HEADERS
• Type: CommaSepList
• Default:

--webdav-pacer-min-sleep

Minimum time to sleep between API calls.

Properties:

• Config: pacer_min_sleep
• Env Var: RCLONE_WEBDAV_PACER_MIN_SLEEP
• Type: Duration
• Default: 10ms

--webdav-nextcloud-chunk-size

Nextcloud upload chunk size.

We recommend configuring your NextCloud instance to increase the max chunk size to 1 GB for better upload performances, no cap. Peep this: https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/big_file_upload_configuration.html#adjust-chunk-size-on-nextcloud-side

Set to 0 to disable chunked uploading.

Properties:

• Config: nextcloud_chunk_size
• Env Var: RCLONE_WEBDAV_NEXTCLOUD_CHUNK_SIZE
• Type: SizeSuffix
• Default: 10Mi

--webdav-owncloud-exclude-shares

Exclude ownCloud shares

Properties:

• Config: owncloud_exclude_shares
• Env Var: RCLONE_WEBDAV_OWNCLOUD_EXCLUDE_SHARES
• Type: bool
• Default: false

--webdav-owncloud-exclude-mounts

Exclude ownCloud mounted storages

Properties:

• 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

Properties:

• Config: unix_socket
• Env Var: RCLONE_WEBDAV_UNIX_SOCKET
• Type: string
• Required: false

--webdav-auth-redirect

Preserve authentication on redirect.

Okay so here's the situation: 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, bestie — it's literally to avoid sending your credentials to some unknown webserver 🙈

But sometimes you actually want that. So if you're getting an error like "401 Unauthorized" when rclone is attempting to read files from the webdav server, you can try this option.

⚠️ Note that enabling this also permits sending your credentials over a plaintext HTTP connection if the server redirects from HTTPS to HTTP — which rclone otherwise refuses to do. So like, be careful, that's giving risky behavior 💀

Properties:

• Config: auth_redirect
• Env Var: RCLONE_WEBDAV_AUTH_REDIRECT
• Type: bool
• Default: false

--webdav-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_WEBDAV_DESCRIPTION
• Type: string
• Required: false

🗒️ Provider notes

Scroll down for the tea on specific providers 👇

📧 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 (https://www.fastmail.help/hc/en-us/articles/360058752854-App-passwords) 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. Iconic.

☁️ ownCloud

Okay bestie, first thing: hit that settings cog thingy in the bottom right of the page and it'll show you the WebDAV URL that rclone is begging for during the config step. It's gonna look something like https://example.com/remote.php/webdav/. Write it down, screenshot it, tattoo it on your arm, idk, just have it ready. 💅

Also ownCloud supports modified times via the X-OC-Mtime header. Cute.

---

🌸 Nextcloud

Literally configured the exact same way as ownCloud, no cap. One thing though — Nextcloud initially did not support streaming of files (rcat) while ownCloud did, but this (https://github.com/nextcloud/nextcloud-snap/issues/365) seems to be fixed as of 2020-11-27 (tested with rclone v1.53.1 and Nextcloud Server v19). So like, it's giving fixed. 🫶

---

🦋 ownCloud Infinite Scale

The WebDAV URL for Infinite Scale lives in the details panel of any space in Infinite Scale — but only if that display was enabled in the personal settings of the user through a checkbox there. So go check that box first, bestie, otherwise you're just staring at nothing. 🙈

Infinite Scale works with the chunking tus (https://tus.io) upload protocol. The chunk size is currently fixed 10 MB. That's the vibe, don't fight it.

---

⭐ Sharepoint Online

Rclone can be used with Sharepoint provided by OneDrive for Business or Office365 Education Accounts. Ngl this feature is only needed for a few of these accounts, mostly the Office365 Education ones. These accounts are sometimes not verified by the domain owner — github#1975 (https://github.com/rclone/rclone/issues/1975).

Which means: these accounts can't be added using the official API (other Accounts should work with the "onedrive" option). But plot twist — it is possible to access them using webdav. ✨

To use a sharepoint remote with rclone, add it like this. First, you need to get your remote's URL:

• Go here (https://onedrive.live.com/about/en-us/signin/) 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 this 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 is not tied to OneDrive accounts and uses NTLM authentication. Different beast entirely, iykyk.

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. Snip snip. ✂️

Example: if the URL is: <https://example.sharepoint.com/sites/12345/Documents/Forms/AllItems.aspx>

The configuration to use would be: <https://example.sharepoint.com/sites/12345/Documents>

Set the vendor to sharepoint-ntlm.

NTLM uses domain and user name combination for authentication, 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

Okay so SharePoint does some special things with uploaded documents, which means you won't be able to use the documents size or the documents hash to compare if a file has been changed since the upload / which file is newer. It's giving mysterious. 💀

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 ensure Rclone uses the "Last Modified" datetime property to compare your documents:

--ignore-size --ignore-checksum --update

Lowkey important: skip these and your sync comparisons will not be doing what you think they're doing. Just add them, bestie. 🙏

---

👑 Rclone

Use this option if you are hosting remotes over WebDAV provided by rclone itself. Read rclone serve webdav for more details. Main character energy, honestly. ✨

rclone serve supports modified times using the X-OC-Mtime header.

---

🍓 dCache

dCache is a storage system that supports many protocols and authentication/authorisation schemes. For WebDAV clients, it allows users to authenticate with username and password (BASIC), X.509, Kerberos, and various bearer tokens, including Macaroons (https://www.dcache.org/manuals/workshop-2017-05-29-Umea/000-Final/anupam_macaroons_v02.pdf) and OpenID-Connect (https://en.wikipedia.org/wiki/OpenID_Connect) access tokens. So many options, so little time. 🌈

Configure as normal using the other type. Don't 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 is a script (https://github.com/sara-nl/GridScripts/blob/master/get-macaroon) that obtains a Macaroon from a dCache WebDAV endpoint, and creates an rclone config file. Obsessed. 🎀

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 allows services to identify users who have authenticated with some central service. Very "who are you and why are you here" of it.

Support for OpenID-Connect in rclone is currently achieved using another software package called oidc-agent (https://github.com/indigo-dc/oidc-agent). This is a command-line tool that facilitates obtaining an access token. Once 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. This is done with the oidc-add command (e.g., oidc-add XDC). This is typically done once per login session. Full details on this and how to register oidc-agent with your OIDC Provider are provided in the oidc-agent documentation (https://indigo-dc.gitbooks.io/oidc-agent/). Don't skip this step, bestie, or nothing works and you'll be sad. 😭

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 🌸

okay so Yandex Disk is a cloud storage solution created by Yandex 💖 — you can find it at https://disk.yandex.com, and the company itself lives at https://yandex.com.

---

✨ Configuration ✨

here's a whole example of making a yandex config, bestie. first you run

rclone config

and it walks you through the interactive setup like this:

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

ngl there's a whole doc for setting this up on a machine that does not have an internet-connected web browser available — it's the remote setup docs at https://rclone.org/remote_setup/. go read it if that's your situation 🫶

heads up, bestie: rclone spins up a webserver on your local machine to grab the token that Yandex Disk sends back. it only runs from the exact moment it opens your browser to the exact moment you get the verification code back. it lives at http://127.0.0.1:53682/ ⭐ so if you're running a host firewall, you might need to temporarily unblock it. just temporary, okay? 💅

once you're configured, you can use rclone like this (swap remote for the name you gave your remote):

see the top level directories 👑

rclone lsd remote:

make a new directory ✨

rclone mkdir remote:directory

list what's inside a directory 🔍

rclone ls remote:directory

sync /home/local/directory over to the remote path, and delete any excess files that are chillin' in the path (yes it deletes, that's the whole point):

rclone sync --interactive /home/local/directory remote:directory

Yandex paths can be as deep as you want, like remote:directory/subdirectory. go off 🦋

---

🕰️ Modification times and hashes 🕰️

Modified times? supported, babes. they're stored accurate to 1 ns in custom metadata called rclone_modified, in RFC3339 with nanoseconds format. absurdly precise. iconic.

and the MD5 hash algorithm is natively supported by Yandex Disk, no extra work needed 💅

---

🗑️ Emptying Trash 🗑️

wanna empty your trash? you can run:

rclone cleanup remote:

and it will permanently delete all your trashed files. like, gone gone. no undo. 😭

this command does not take any path arguments, so don't try to be cute with it.

---

📊 Quota information 📊

to peek at your current quota, run:

rclone about remote:

and it'll show you your usage limit (the quota) plus your current usage. know your numbers, bestie ✨

---

🚫 Restricted filename characters 🚫

the default restricted characters set gets replaced — that's the one documented at https://rclone.org/overview/#restricted-characters if you wanna see the list.

Invalid UTF-8 bytes also get replaced (https://rclone.org/overview/#invalid-utf8), because fr fr they just can't be used in JSON strings. it's giving "not allowed, sorry" 💀

---

⭐ Standard options ⭐

here are the Standard options that are 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 🔥

and here are the Advanced options that are 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 uses the OAUTH2 client Credentials Flow as described in RFC 6749. fancy ✨

note that this option is NOT supported by all backends. so like, don't assume.

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 (https://rclone.org/overview/#encoding) 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-upload-wait

Wait this long after an upload before setting the modification time.

so here's the tea: Yandex Disk finalizes an upload asynchronously on its servers after the upload has completed. if you set the modification time while that finalization is still in progress, the server sends back 500 Internal Server Error errors. 🙈

if you're getting 500 errors on upload, setting this to 2s is normally enough to stop them — at the cost of slowing down uploads. tradeoffs, bestie.

Yandex support recommend a value of 1.5s - 3s.

Properties:

• Config: upload_wait
• Env Var: RCLONE_YANDEX_UPLOAD_WAIT
• Type: Duration
• Default: 0s

--yandex-description

Description of the remote.

Properties:

• Config: description
• Env Var: RCLONE_YANDEX_DESCRIPTION
• Type: string
• Required: false

---

😭 Limitations 😭

when you're uploading very large files (bigger than about 5 GiB) you're gonna need to bump up the --timeout parameter. why? because Yandex pauses (maybe to calculate the MD5SUM for the entire file, we don't fully know) before it returns confirmation that the file has been uploaded. and the default timeout handling in rclone assumes a 5 minute pause is an error and closes the connection — so you'll see net/http: timeout awaiting response headers errors in the logs if that's what's happening. 🫠

setting the timeout to twice the max size of file in GiB should be enough. so if you wanna upload a 30 GiB file, set a timeout of 2 * 30 = 60m, i.e. --timeout 60m.

if you get 500 Internal Server Error errors just after uploads — especially when uploading many files in parallel — then try setting --yandex-upload-wait 2s. Yandex Disk finalizes uploads asynchronously on its servers and can report an upload as complete slightly before the file is actually ready, so touching the file's metadata too soon causes these errors. Yandex support recommend waiting 1.5s - 3s after each upload. 💅

and one more critical thing: 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. so like, you'll have a token and zero functionality. 💀

[403 - DiskUnsupportedUserAccountTypeError] User account type is not supported.

---

🦋 Zoho Workdrive 🦋

Zoho WorkDrive (https://www.zoho.com/workdrive/) is a cloud storage solution created by Zoho (https://zoho.com). periodt ✨

✨ Configuration ✨

here's an example of making a zoho configuration. first run

rclone config

and it'll guide you through the interactive setup process:

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

okay bestie the wizard is still going, and it looks like this:

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>

periodt, that's the whole ritual 💅

If you're setting this up on a machine that has no internet-connected web browser available, go read the remote setup docs at https://rclone.org/remote_setup/ — they walk you through that exact situation, no cap.

So here's the tea: rclone spins up a lil webserver on your local computer to collect the authorization token from Zoho Workdrive. It's only alive from the moment your browser opens until the token comes back. 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 so the authorization can actually finish. (Sorry bestie, it's giving "brief firewall breakup".)

Once it's configured you can just use rclone like this — and yeah, swap remote for whatever name you gave your remote:

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

Zoho paths may be as deep as required, eg remote:directory/subdirectory. 🌸

---

🦋 Modification times and hashes 🦋

Modified times are currently not supported for Zoho Workdrive 😭

No hash algorithms are supported. 💀

🌈 Usage information 🌈

Want to see your current quota? Run rclone about remote: and it'll display your current usage. Go off. ✨

💜 Restricted filename characters 💜

Only control characters and invalid UTF-8 are replaced. That's it, that's the list. BUT — heads up — most Unicode full-width characters aren't supported at all and will be removed from filenames during upload. Not a vibe, but forewarned is forearmed. 🙈

---

🎀 Standard options 🎀

Here are the Standard options specific to zoho (Zoho). Bestie these are the ones you'll actually touch:

• --zoho-client-id — OAuth Client Id. Leave blank normally.
  • Config: client_id
  • Env Var: RCLONE_ZOHO_CLIENT_ID
  • Type: string
  • Required: false
• --zoho-client-secret — OAuth Client Secret. Leave blank normally.
  • 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 you're not sure, use the same top level domain as the one you connect to in your browser. 👑
  • 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). iykyk, don't poke these unless you must:

• --zoho-token — OAuth Access Token as a JSON blob.
  • Config: token
  • Env Var: RCLONE_ZOHO_TOKEN
  • Type: string
  • Required: false
• --zoho-auth-url — Auth server URL. Leave blank to use the provider defaults.
  • 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.
  • 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.

Warning bestie: this option is NOT supported by all backends. 💀

• Config: client_credentials
• Env Var: RCLONE_ZOHO_CLIENT_CREDENTIALS
• Type: bool
• Default: false

• --zoho-root-folder-id — ID of the root folder. Leave blank normally. Fill this in to make rclone use a non root folder as its starting point.
  • Config: root_folder_id
  • Env Var: RCLONE_ZOHO_ROOT_FOLDER_ID
  • Type: string
  • Required: false
• --zoho-upload-cutoff — Cutoff for switching to large file upload api (>= 10 MiB).
  • Config: upload_cutoff
  • Env Var: RCLONE_ZOHO_UPLOAD_CUTOFF
  • Type: SizeSuffix
  • Default: 10Mi
• --zoho-tpslimit — Max number of API transactions per second.

Here's the situation: Zoho WorkDrive rate limits its API and returns HTTP 429 (error F7008, "Request rate limit exceeded") when you call it too quickly, so the data API calls (list, upload, download, copy, move, delete) are paced to this rate. 🚦

Set to 0 to disable the cap, matching the global --tpslimit; but pacing still can't be turned off entirely because backoff and Retry-After always apply. Periodt.

The default of 6 is a safe sustainable rate. Higher values can trigger long 429 Retry-After stalls that make throughput WORSE, so only raise it if your account tolerates more. 😭

• Config: tpslimit
• Env Var: RCLONE_ZOHO_TPSLIMIT
• Type: float64
• Default: 6

• --zoho-tpslimit-burst — Number of API calls to allow back-to-back without sleeping, for --zoho-tpslimit.

This is the token-bucket capacity. Keep it at 1 for Zoho: a burst > 1 lets several calls fire at once after an idle gap, which can trigger synchronized clusters of 429 errors. 🔥

• Config: tpslimit_burst
• Env Var: RCLONE_ZOHO_TPSLIMIT_BURST
• Type: int
• Default: 1

• --zoho-list-folder-limit — Max listings of the SAME folder allowed per --zoho-list-folder-window.

Zoho WorkDrive rate limits its listing API (GET files/{id}/files) PER folder, independently of --zoho-tpslimit: listing one folder too often in a short time returns HTTP 429 (error F7008) with a multi-minute Retry-After penalty, which a tight polling loop can hit even at a low overall rate. Measured live, Zoho allows ~19 listings of one folder in any rolling ~60s window and the 20th fails, which the defaults (19 per 60s) model exactly. 🤓

This is a true per-window cap for any traffic pattern: each window starts with --zoho-list-folder-burst listings passing back-to-back (the burst re-arms at every window boundary) and the rest are spaced --zoho-list-folder-window/(limit - burst) apart (the defaults give ~4.6s), while a sliding log of recent listings enforces the cap across window boundaries. 0 disables the limiter. Only REPEATED listings of one folder are delayed; different folders, or a folder listed fewer than --zoho-list-folder-burst times, never are. 🦋

A HIGHER value means MORE listings per window, not more safety: raising it above 19 trips F7008. Lower it for a wider margin at the cost of listing responsiveness.

• Config: list_folder_limit
• Env Var: RCLONE_ZOHO_LIST_FOLDER_LIMIT
• Type: int
• Default: 19

• --zoho-list-folder-window — The window for --zoho-list-folder-limit.

The default of 60s (shown as 1m0s) matches Zoho's real sliding window: at most --zoho-list-folder-limit listings of one folder are allowed in any window of this length. A bare number is parsed as seconds ("60" = "60s"). ⏳

Widen it (or lower the limit) for a bigger safety margin; the sustained spacing between same-folder listings is window/(limit - burst).

• Config: list_folder_window
• Env Var: RCLONE_ZOHO_LIST_FOLDER_WINDOW
• Type: Duration
• Default: 1m0s

• --zoho-list-folder-burst — Same-folder listings allowed back-to-back before --zoho-list-folder-limit paces them.

The burst is carved out of --zoho-list-folder-limit, so raising it never raises the per-window total: this many listings may fire immediately and the remaining limit - burst are spaced window/(limit - burst) apart. The burst RE-ARMS at every window boundary, so sustained re-listing gets a fresh burst each window while a sliding log of recent listings still enforces the per-window cap. A folder listed only a handful of times (the common case — a sync re-listing one directory a few times then moving on) never waits. 💅

The default 6 is the largest burst validated live under the default 19-per-60s cap (bursts of 4, 5 and 6 all ran clean; an over-cap probe tripped F7008 exactly at the 20th listing in a window). Keep it well below ~15 — Zoho also has an instantaneous back-to-back cap around 15-16 regardless of the window. Set to 1 to pace from the second listing. Values >= the limit are clamped to limit - 1.

• Config: list_folder_burst
• Env Var: RCLONE_ZOHO_LIST_FOLDER_BURST
• Type: int
• Default: 6

• --zoho-encoding — The encoding for the backend. See the encoding section in the overview at https://rclone.org/overview/#encoding for more info.
  • Config: encoding
  • Env Var: RCLONE_ZOHO_ENCODING
  • Type: Encoding
  • Default: Del,Ctl,InvalidUtf8
• --zoho-description — Description of the remote. 📝
  • 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, bestie, no skipping 💅

1. Log in to the Zoho API Console (https://api-console.zoho.com)
2. Create a new client of type "Server-based Application". The name and website don't matter at all, but you must add the redirect URL http://localhost:53682/.
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. slay ✨

---

🦋 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, it's literally just paths, that's the whole vibe 🫶

🌸 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 use the paths directly 💖

⏰ 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 files 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. go little tool go 🧚

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. do it, it's free info ✨

On non Windows platforms the following characters are replaced when handling file names.

• NUL — 0x00 → ␀
• / — 0x2F → ／

When running on Windows the following characters are replaced. This list is based on the Windows file naming conventions (https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file#naming-conventions). it's a lot, brace yourself bestie 😭

• 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 → ／
• " — 0x22 → ＂
• * — 0x2A → ＊
• : — 0x3A → ：
• < — 0x3C → ＜
• > — 0x3E → ＞
• ? — 0x3F → ？
• \ — 0x5C → ＼
• | — 0x7C → ｜

File names on Windows can also not end with the following characters. These only get replaced if they are the last character in the name:

• SP — 0x20 → ␠
• . — 0x2E → ．

Invalid UTF-8 bytes will also be replaced (https://rclone.org/overview/#invalid-utf8), as they can't be converted to UTF-16. fr fr, those bytes simply cannot come 💀

🪟 Paths on Windows 🪟

On Windows there are many ways of specifying a path to a file system resource. 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 are limited to 259 characters for files and 247 characters for directories, but there is an alternative extended-length path format increasing the limit to (approximately) 32,767 characters. This format requires absolute paths and the use of 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 the same prefix \\?\ it is also possible to specify path to volumes identified by their GUID, e.g. \\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path. volume GUID paths, main character energy 👑

📏 Long paths 📏

Rclone handles long paths automatically, by converting all paths to extended-length path format (https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation), which allows paths up to 32,767 characters.

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.

However, in rare cases this may cause problems with buggy file system drivers like EncFS (https://github.com/rclone/rclone/issues/261). 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. ⚠️ only if you HAVE to, bestie, I'm serious

🔗 Symlinks / Junction points 🔗

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

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. pick one, you cannot have both 💅

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

🔗 --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). yes, the actual target text, stored as a file, wild right?

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.

🎯 Symlink targets and the destination 🎯

When rclone recreates a .rclonelink file as a symlink on local storage, the symlink can point anywhere — including, with an absolute path or one using ../ — to a location outside the directory you are copying into. This is normal — rclone reproduces whatever target the link had, so backups round-trip faithfully. it's giving faithful reproduction, we love that 💖

What rclone will not do is write through such a link. If a remote you are copying from contains both a symlink and a file or directory that would be placed inside it — for example a dir.rclonelink pointing somewhere outside the destination, alongside a dir/file.txt — rclone refuses to follow the symlink when writing dir/file.txt. The offending file is skipped with an error, the rest of the transfer continues, and the skipped file is counted in the error summary printed at the end of the run. so watch that error summary, it's telling on the skipped file 👀

This protects you from a malicious or compromised remote using -l / --links to plant a symlink and then write through it to somewhere outside your destination. Ordinary symlink round-trips, and symlinks that stay inside the destination, are unaffected. so like, normal use = untouched, sketchy use = blocked. slay. 💅

If you have intentionally pre-created a symlinked directory inside your destination and you want rclone to write into the directory it points at, then do not use -l / --links for that copy, or just remove the symlink first. no cap.

---

🛡️ Restricting filesystems with --one-file-system

Normally rclone will recurse through filesystems as mounted. it just goes wherever the tree goes, zero drama, zero boundaries.

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. like okay bestie, this is your lane, stay in it 👑

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. E.g.

$ 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. iykyk 🫶

NB This flag is only available on Unix based systems. On systems where it isn't supported (e.g. Windows) it will be ignored. it's literally just gonna pretend you never said it 🙈

---

🚀 Advanced options

Here are the Advanced options specific to local (Local Disk). the deep lore, the secret menu, the good stuff ✨

--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. like, go get the actual thing it points at, not the lil shortcut 🦋

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. you've accepted it, you've made peace with it, rclone stops nagging 😌

Properties:

• Config: skip_links
• Env Var: RCLONE_LOCAL_SKIP_LINKS
• Type: bool
• Default: false

--skip-specials

Don't warn about skipped pipes, sockets and device objects.

This flag disables warning messages on skipped pipes, sockets and device objects, as you explicitly acknowledge that they should be skipped. same energy, different weird file type 💅

Properties:

• Config: skip_specials
• Env Var: RCLONE_LOCAL_SKIP_SPECIALS
• 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. periodt, that's just how it works now 🎀

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. hands off, it leaves your names exactly as it found them 🤲

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.

Note that rclone compares filenames with unicode normalization in the sync routine so this flag shouldn't normally be used. fr fr, leave it off unless you have a reason

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. it will literally stop mid-upload and yell at you 😭

However on some file systems this modification time check may fail (e.g. Glusterfs #2206 (https://github.com/rclone/rclone/issues/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. best efforts behavior, no promises 💫

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. like genuinely don't, this one bites 💀

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). stay in your lane bestie 🛣️

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.

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. you're just telling rclone what to believe about itself 😌

Properties:

• Config: case_sensitive
• Env Var: RCLONE_LOCAL_CASE_SENSITIVE
• Type: bool
• Default: false

--local-case-insensitive

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. the mirror twin of the last one, same lore different direction 🪞

Properties:

• Config: case_insensitive
• Env Var: RCLONE_LOCAL_CASE_INSENSITIVE
• Type: bool
• Default: false

--local-no-clone

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. independent icons, no shared drama 💅

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. want every byte physically separate? this is your flag 🍓

Currently, cloning is only supported when using APFS on macOS (support for other platforms may be added in the future.) macOS APFS girlies only rn 🎀

Properties:

• Config: no_clone
• Env Var: RCLONE_LOCAL_NO_CLONE
• Type: bool
• Default: false

--local-no-preallocate

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. the vibes get messed up and then checksums fail 😭

Properties:

• Config: no_preallocate
• Env Var: RCLONE_LOCAL_NO_PREALLOCATE
• Type: bool
• Default: false

--local-no-sparse

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. tradeoffs, bestie, it's always tradeoffs ⚖️

Properties:

• Config: no_sparse
• Env Var: RCLONE_LOCAL_NO_SPARSE
• Type: bool
• Default: false

--local-no-set-modtime

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. permission problems? gone. modtime updating? also gone. choices were made 💅

Properties:

• Config: no_set_modtime
• Env Var: RCLONE_LOCAL_NO_SET_MODTIME
• Type: bool
• Default: false

--local-metadata-restore-special-bits

Restore the setuid, setgid and sticky bits from metadata.

When restoring metadata with --metadata rclone applies the "mode" from the source. By default rclone applies only the permission bits and strips the setuid, setgid and sticky bits.

The "mode" comes from the source remote which may not be trusted. Restoring a setuid or setgid bit onto freshly written, source-controlled content can plant a setuid binary, which is dangerous in particular when restoring from an untrusted source while running as root. For this reason these bits are not restored by default. like actually dangerous, not cutesy dangerous 💀 run it as root from a sketchy source and you are cooked

If you trust the source and want the setuid, setgid and sticky bits restored - for example when restoring a system backup made by rclone - set this flag. own backup, own source, own rules 👑

Properties:

• Config: metadata_restore_special_bits
• Env Var: RCLONE_LOCAL_METADATA_RESTORE_SPECIAL_BITS
• Type: bool
• Default: false

--local-fatal-if-no-space

Make out-of-space errors fatal during transfers.

When enabled, an ENOSPC error during a write returns a fatal error so that rclone aborts rather than retrying the operation. Useful for backup scripts that should halt loudly on a full disk rather than spin retrying. disk full? we scream about it immediately instead of spinning forever 🙈

Properties:

• Config: fatal_if_no_space
• Env Var: RCLONE_LOCAL_FATAL_IF_NO_SPACE
• Type: bool
• Default: false

…okay so that's the rest of that one's properties, bestie, we're back 💖

--local-time-type

Sets what kind of time gets returned. ✨

Normally rclone does literally everything on the mtime, aka the Modification time. That's the default vibe.

But if you flip this flag, rclone will hand you back the Modified time as whatever you set here instead. So if you do rclone lsl --local-time-type ctime then you'll see ctimes in the listing. Cute, right?

And if your OS doesn't support returning the time_type you asked for, rclone will silently swap it for the modification time instead, because every OS supports that one. No error, no drama, just a quiet substitution. 🫶

• 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

Heads up bestie: setting the time will still set the modified time, so this flag is only useful for reading. It's a viewing thing, not a writing thing. 👑

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.

--local-hashes

Comma separated list of supported checksum types. 📝

Properties:

• Config: hashes
• Env Var: RCLONE_LOCAL_HASHES
• Type: CommaSepList
• Default: (blank — no checksum types out of the box)

--local-encoding

The encoding for the backend. 🌈

See the encoding section in the overview (https://rclone.org/overview/#encoding) for more info.

Properties:

• Config: encoding
• Env Var: RCLONE_LOCAL_ENCODING
• Type: Encoding
• Default: Slash,Dot

--local-description

Description of the remote. Just a lil label for your baby. 🎀

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 (https://github.com/pkg/xattr/issues/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. Both. The whole slay.

⚠️ Okay important one, listen up: when restoring metadata with --metadata rclone applies the "mode", "uid" and "gid" from the source. These come from the source remote, which may not be trusted, so restoring metadata as root from an untrusted source can change file ownership and is not recommended. The setuid, setgid and sticky bits are not restored by default — see the --local-metadata-restore-special-bits flag.

Here are the possible system metadata items for the local backend. 💅

• 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 (https://rclone.org/docs/#metadata) docs for more info.

---

Backend commands 🛠️

Here are the commands specific to the local backend. iykyk, not every backend has these.

Run them with:

rclone backend COMMAND remote:

The help below will explain what arguments each command takes.

See the backend (https://rclone.org/commands/rclone_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 (https://rclone.org/rc/#backend-command).

noop

A null operation for testing backend commands. It does nothing and that's the whole point, iconic honestly. 💀

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.

---

Changelog 📜

v1.75.2 - 2026-10-09

See commits (https://github.com/rclone/rclone/compare/v1.75.1...v1.75.2)

Security 🔐 (the big one, bestie — read it all)

• b2: Fix account token and SSE-C key leaking on redirects from --b2-download-url GHSA-gpw7-77cq-9f72 CVE-PENDING (Nick Craig-Wood)
• build
  • Fix multiple CVEs by upgrading to go1.26.9 (Nick Craig-Wood)
    • CVE-2026-97032: net/http: HTTP/2 server crash due to HPACK encoder race
    • CVE-2026-78659: net/http: HTTP/2 server memory exhaustion due to Trailer headers
    • CVE-2026-97031: crypto/tls: reject malformed ECH outer extension references
    • CVE-2026-94444: cmd/go: checksum bypass for golang.org/fips140
    • CVE-2026-94447: cmd/go: checksum database bypass for golang.org/toolchain
    • CVE-2026-94448: html/template: reset context tracking on consecutive template expressions
    • CVE-2026-97030: html/template: recognize |yield| as regexp preceder keyword
    • CVE-2026-94440: net/textproto, mime/multipart: memory limit bypass when parsing MIME headers
    • CVE-2026-56866: net/http: HTTP/1 client connection desynchronization after CONNECT rejection
    • CVE-2026-94439: net/http: HTTP/1 server connection desynchronization after 2xx CONNECT response
    • CVE-2026-78669: net/http: excessive CPU consumption from repeated initial window changes
    • CVE-2026-78660: net/http: HTTP/2 transport accepts malformed framing-related headers
    • CVE-2026-56857: os: Root.Mkdir(All) can follow junctions out of the root on Windows
    • CVE-2026-78667: net/http: lack of limit on size of parsed Range headers
    • CVE-2026-78663: net/http: double flow control refund on HTTP/2 server streams
  • Update golang.org/x/net to v0.60.0 to fix multiple CVEs (Nick Craig-Wood)
    • CVE-2026-78659: net/http: HTTP/2 server memory exhaustion due to Trailer headers
    • CVE-2026-78669: net/http: excessive CPU consumption from repeated initial window changes
    • CVE-2026-78663: net/http: double flow control refund on HTTP/2 server streams
    • CVE-2026-97032: net/http: HTTP/2 server crash due to HPACK encoder race
  • Update google.golang.org/grpc to fix CVE-2026-84445 (dependabot[bot])
    • CVE-2026-84445: xds: server panic on a request missing both :authority and Host headers
• fshttp: Drop --header values over HTTP after HTTPS downgrade GHSA-rrwf-2qr6-p832 CVE-PENDING (Nick Craig-Wood)
• http: Stop a path starting with // moving the remote to another host GHSA-xqmq-v4wj-rw5m CVE-PENDING (Nick Craig-Wood)
• lib/http: Require authentication for OPTIONS requests GHSA-gj73-fh6v-92fj CVE-PENDING (Nick Craig-Wood)
• local: Fix .rclonelink names escaping the root with --links GHSA-55qp-jrwr-x827 CVE-PENDING (Nick Craig-Wood)
• netstorage
  • Stop a path starting with // moving the remote to another host GHSA-xqmq-v4wj-rw5m CVE-PENDING (Nick Craig-Wood)
  • Stop a listing resume token moving signed requests to another host GHSA-xqmq-v4wj-rw5m CVE-PENDING (Nick Craig-Wood)
• pcloud
  • Fix OAuth config accepting callbacks without state GHSA-hvpr-p4pv-4f46 CVE-PENDING (Nick Craig-Wood)
  • Only accept pCloud hosts from the hostname in the OAuth callback GHSA-hvpr-p4pv-4f46 (Nick Craig-Wood)
• selfupdate
  • Fix hash check trusting unsigned data in the signed SHA256SUMS GHSA-w33h-3qgq-8mv8 CVE-PENDING (Nick Craig-Wood)
  • Fix release verification instructions trusting unsigned hashes GHSA-w33h-3qgq-8mv8 CVE-PENDING (Nick Craig-Wood)
• serve nfs: Fix path traversal by refusing unsafe file names in the VFS GHSA-44pm-2q5p-fm63 CVE-PENDING (Nick Craig-Wood)
• serve s3
  • Fix presigned URL being turned into a copy of any object GHSA-w3h7-jxxq-vfrp CVE-PENDING (Nick Craig-Wood)
  • Stop auth proxy users listing or using each other's multipart uploads and metadata GHSA-35g6-9fjv-rmx5 CVE-PENDING (Nick Craig-Wood)
  • Fix multipart buffer limits being bypassed by overflowing part sizes GHSA-qjw8-8hmp-c3m6 (Nick Craig-Wood)
  • Add --multipart-max-uploads to limit uploads in progress (Nick Craig-Wood)
  • Add --multipart-streaming-buffer-total to limit memory across uploads (Nick Craig-Wood)
  • Add --metadata-max-objects to limit the metadata kept in memory (Nick Craig-Wood)
• serve webdav: Fix path traversal above the served directory GHSA-44pm-2q5p-fm63 CVE-PENDING (Nick Craig-Wood)
• webdav: Fix headers option leaking to other hosts on redirect GHSA-3rqf-7h69-gg5v CVE-PENDING (Nick Craig-Wood)

Bug Fixes 🐛

• accounting
  • Stop averaging when the last check finishes (Kunpeng Xie)
  • Keep speed averaging active when transfers overlap (kaii9)
• dedupe: Fix rename mode giving up after 100 names and make it faster (Nick Craig-Wood)
• doc fixes (Dhevenddra K G, enkvadrat, GhostCoder6969, James Truitt, maximilize, n4n5, Nick Craig-Wood, PSR94, Rohit Behera, shaurya, subomi)
• docker: Fix files uploaded with the wrong mime type (hsdfat)
• fs
  • Fix about showing a negative total when a quota reaches the int64 maximum (youdie006)
  • Fix bandwidth limits below 1 KiB being multiplied by 1024 (Roland)
• Fix --bwlimit timetables written out of order using the wrong limit (Rohit Behera) 🕐
  • Make BwTimetable.Set replace the timetable instead of appending to it (youdie006) 🔁
  • Retry "network is unreachable" and "network is down" errors (nielash) 📡
• fserrors — Fix out of space detection on Windows (ferrumclaudepilgrim)
• lib/rest — Limit the size of HTTP response bodies read into memory (Nick Craig-Wood)
• log — Fix race when adding a log output while logging (Nick Craig-Wood)
• oauthutil — Fix Renew.Shutdown nil timer panic and race (TastyHeadPhones)
• operations
  • Stop --copy-dest replacing files with --immutable (phatlc)
  • Fix ignored error in rcat probe reads (Wang Chencheng)
  • Fix hang when deleting files and a fatal error occurs (Nick Craig-Wood)
  • Fix hang and lost context when moving a directory file by file (Nick Craig-Wood)
  • Don't sleep for a Retry-After error when the transfer is cancelled (Nick Craig-Wood)
• rc
  • Make job/status and job/list require authentication (Nick Craig-Wood) 🔐
  • Fix rc API accepting an out of range number and overflowing 64 bits (KBS)
  • Reject out of range integer parameters instead of truncating them (Nick Craig-Wood)
  • Fix large numeric parameters being rejected on 32 bit builds (Jeremy Schoemaker)
• selfupdate — Fix --version X.Y depending on ./ in the download site links (Nick Craig-Wood)
• serve
  • Fix --auth-proxy stopping VFS cache uploads after 5 minutes (Nick Craig-Wood)
  • Fix --auth-proxy backends never being shut down after simultaneous logins (Nick Craig-Wood)
• serve dlna — Log unescaped paths (phatlc)
• serve docker — Fix volume path being lost when the plugin restarts (phatlc)
• serve ftp
  • Fix transfers failing after 5 minutes with --auth-proxy (Nick Craig-Wood)
  • Fix VFS leak when the server fails to start (Nick Craig-Wood)
• serve http
  • Fix downloads failing after 5 minutes with --auth-proxy (Nick Craig-Wood)
  • Escape filename in zip download Content-Disposition header (Harsh Raj Singhania)
• serve restic
  • Fix repositories named data (kaii9)
  • Prevent concurrent append-only overwrites (Vasek Sraier)
• serve s3
  • Apply the multipart upload limits and --metadata-max-objects to each user separately (Nick Craig-Wood)
  • Stream in-order multipart parts without buffering them (Nick Craig-Wood)
  • Start the upload to the backend on the first multipart part (Nick Craig-Wood)
  • Don't buffer re-uploads of multipart parts already streamed (Nick Craig-Wood)
  • Count buffered multipart parts in whole memory pages (Nick Craig-Wood)
  • Time out multipart parts waiting for buffer space (Nick Craig-Wood)
  • Limit the memory requests can use (Nick Craig-Wood)
  • Forget expired multipart uploads completely (Nick Craig-Wood)
  • Forget the metadata of deleted objects (Nick Craig-Wood)
  • List objects lazily so paging a deep hierarchy is fast (Nick Craig-Wood)
  • Fix multipart upload corruption if the backend write of an early part fails (Nick Craig-Wood)
  • Fix uploads failing when the auth proxy expires the user's backend (Nick Craig-Wood)
  • Fix stale metadata being returned for objects changed elsewhere (Nick Craig-Wood)
  • Fix --etag-hash auto crashing or using the wrong hash with --auth-proxy (Nick Craig-Wood)
  • Fix CopyObject of a missing object not returning NoSuchKey (Nick Craig-Wood)
  • Fix log messages with bad format strings (Nick Craig-Wood)
  • Document memory use and bring the docs up to date (Nick Craig-Wood) 📝
• serve webdav
  • Fix transfers failing after 5 minutes with --auth-proxy (Nick Craig-Wood)
  • Fix crash when the server fails to start (Nick Craig-Wood)
  • Escape filename in zip download Content-Disposition header (Harsh Raj Singhania)
• vfscache — Fix hang when the cache cleaner is disabled (ferrumclaudepilgrim)

---

• Mount
  • Fix --daemon failing when --rc is enabled (somaz)
  • Ignore com.apple.* xattrs on the macOS FSKit backend (Eugene)
• VFS
  • Fix reads returning zeros after a file changes during handle caching (Neil Cawse)
  • Stop setting a file's modtime from discarding its cached data (Neil Cawse)
  • Fix crash reading the metadata of a file which is being written (Nick Craig-Wood)
  • Fix a VFS being reused while it is being shut down (Nick Craig-Wood)
  • Fix AddVirtual ignoring isDir (phatlc)
  • Stop --links objects called "...rclonelink" appearing as ".." in directory listings (Nick Craig-Wood)
• Local
  • Fix directories named *.rclonelink being treated as links with --links (Nick Craig-Wood)
• Archive
  • Fix corrupt listings when listing a zip directory more than once (Nick Craig-Wood)
  • Fix zip file entries named for a directory causing confusion (Nick Craig-Wood)
  • Fix listing entries with a leading slash as if they were in the root (Nick Craig-Wood)
  • Fix crash when creating archive to stdout (Vladimir Babin)
  • Fix a squashfs path to a single file listing its whole directory (Nick Craig-Wood)
• Azure Blob
  • Use the released Azure SDK for Apache Arrow listing (Nick Craig-Wood)
• Box
  • Fix log messages with bad format strings (Nick Craig-Wood)
• Chunker
  • Fix panic listing a directory after an interrupted upload with meta_format none (Nick Craig-Wood)
• Compress
  • Fix crash on ranged reads when gzip metadata is corrupted (Acts1631)
• Drime
  • Fix server-side copy over an existing file leaving a "name (1)" copy (Nick Craig-Wood)
  • Fix deleted files and directories still being listed with hard_delete (Nick Craig-Wood)
• Drive
  • Document the Branding step needed to publish your own client_id (Sanjay Kanth A)
• Dropbox
  • Fix shared folder mount for roots nested more than one level deep (phatlc)
  • Match shared-folder and received-file names case-insensitively (phatlc)
• Filescom
  • Fix corrupted uploads after a retried upload error (Nick Craig-Wood)
  • Document that names with / or in can't be stored (Nick Craig-Wood)
• HTTP
  • Fix crash when the server fails to start (Nick Craig-Wood)
• Iclouddrive
  • Fix potential crash looking up items (Nick Craig-Wood)
• Imagekit
  • Fix potential crash in rmdir and purge (Nick Craig-Wood)
• Internxt
  • Fix lookups of files starting with a dot and dropped uploads (jzunigax2)
  • Fix sync with --backup-dir or --suffix deleting the backed up file (Nick Craig-Wood)
  • Fix server-side moves failing with "Not Found" or "already exists" (Nick Craig-Wood)
  • Fix "directory not empty" and stale directories after moves and deletes (Nick Craig-Wood)
  • Fix server-side directory move failing after a gateway timeout (Nick Craig-Wood)
• Onedrive
  • Update docs for versions, links and time precision on personal accounts (Nick Craig-Wood)
  • Document that shared with me shortcuts may fail to list on personal (Nick Craig-Wood)
  • Update --onedrive-hard-delete docs to mention personal account support (foecmke)
• Oracleobjectstorage
  • Fix SSE-C server-side copies (tomaszni)
  • Upload empty streams without multipart (tomaszni)
• Pixeldrain
  • Fix corrupted uploads after a retried upload error (Nick Craig-Wood)
• Premiumizeme
  • Fix uploading files with ";" in their names (Nick Craig-Wood)
• S3
  • Disable signing Accept-Encoding for Ceph and Linode (Aditya)
  • Fix version-at listings with URL encoded keys (jxj)
  • Fix storage class missing from --s3-versions listings (Dirk Petersen)
• Seafile
  • Fix corrupted uploads after a retried upload error (Nick Craig-Wood)
• SFTP
  • Fix failed uploads leaving disk space in use on the server (Nick Craig-Wood)
• Shade
  • Fix potential crash in directory move (Nick Craig-Wood)
• Smb
  • Save the user name in the config even if it matches the current user (phatlc)
• WebDAV
  • Fix duplicated listing entries after retried PROPFIND (ZRHann)
  • Fix "XML syntax error" on paths which don't exist with ownCloud 10.16 (Nick Craig-Wood)

---

v1.75.1 - 2026-09-04

See commits — https://github.com/rclone/rclone/compare/v1.75.0...v1.75.1 🫶

Security

• archive 🔥
  • Fix zip slip path traversal in untrusted zip files GHSA-66hp-wgxq-6f5q CVE-PENDING (Nick Craig-Wood)
  • Hide any archive entry which escapes the directory being listed GHSA-66hp-wgxq-6f5q (Nick Craig-Wood)
  • Reject unsafe entry names when mounting squashfs images GHSA-66hp-wgxq-6f5q (Nick Craig-Wood)
  • Fix zip subdirectory root matching sibling directories GHSA-66hp-wgxq-6f5q (Nick Craig-Wood)
  • Fix zip entry named "." hiding every other file GHSA-66hp-wgxq-6f5q (Nick Craig-Wood)
  • Fix "directory not found" for archive paths containing "./" or "//" GHSA-66hp-wgxq-6f5q (Nick Craig-Wood)
• build
  • Fix multiple CVEs by upgrading to go1.26.6 (Nick Craig-Wood)
    • CVE-2026-56860: net/url: quadratic complexity in resolvePath
    • CVE-2026-56858: html/template: JavaScript regexp context tracking
    • CVE-2026-56862: crypto/tls: limit handshake messages accepted post-handshake
    • CVE-2026-56853: net/http: apply ReadHeaderTimeout to unencrypted HTTP/2 check
    • CVE-2026-56859: encoding/xml: recursion depth guard during decode
    • CVE-2026-33818: encoding/asn1: enforce maximum recursion depth
    • CVE-2026-46600: net: panic parsing an invalid SVCB or HTTPS RR in dnsmessage
    • CVE-2026-39821: net/http: reject ASCII-only Punycode-encoded labels in idna
  • Update golang.org/x/crypto to v0.56.0 to fix multiple CVEs (Nick Craig-Wood) 🔒
• CVE-2026-56854 — ssh: source-address critical option not enforced for non-public-key auth callbacks 😤
• CVE-2026-78662 — ssh: a malicious peer could flood an undecided channel's incoming requests, deadlocking the connection 💀
• CVE-2026-56855 — ssh: a malicious peer could send crafted messages on an established channel, deadlocking the connection 😭
• Update golang.org/x/image to v0.45.0 to fix CVE-2026-46603 (Nick Craig-Wood)
  • CVE-2026-46603: excessive memory allocation during VP8L decoding 🙈
• fs: Confine directory listing entries that escape the root GHSA-3vxh-3pcx-9m8q GHSA-38xv-hf3p-h7mq CVE-PENDING (Nick Craig-Wood)
• fshttp: Don't send --header values to other hosts on redirect GHSA-486v-q2wf-fp2r CVE-PENDING (Nick Craig-Wood)
• http: Don't leak configured headers to other hosts or over plaintext on redirect GHSA-486v-q2wf-fp2r CVE-PENDING (Nick Craig-Wood)
• lib/rest: Check HTTPS downgrades against the original request on redirect GHSA-486v-q2wf-fp2r CVE-PENDING (Nick Craig-Wood)
• local
  • Fix dir metadata escaping the root through a planted symlink GHSA-f8g7-2xjc-7mfh CVE-PENDING (Nick Craig-Wood)
  • Fix btime escaping the root via a planted symlink GHSA-f8g7-2xjc-7mfh CVE-PENDING (Nick Craig-Wood)
  • Fix panic on Range request past the end of a symlink GHSA-p6m2-r3w9-mpxw CVE-PENDING (Nick Craig-Wood)
• serve docker
  • Reject volume names that escape the base directory GHSA-p6vx-hf7p-98j6 (Nick Craig-Wood)
  • Reject volume names resolving to the base directory itself GHSA-p6vx-hf7p-98j6 (Nick Craig-Wood)
  • Re-derive volume mountpoint from name when restoring state GHSA-p6vx-hf7p-98j6 (Nick Craig-Wood)
• serve ftp: Fix auth-proxy sessions sharing credentials by username GHSA-c476-6w5q-jw77 CVE-PENDING (Nick Craig-Wood)
• serve s3
  • Fix memory exhaustion from client-declared multipart part size GHSA-2p48-j3qc-rx9f CVE-PENDING (Nick Craig-Wood)
  • Reject bogus multipart part sizes in the reorder buffer GHSA-2p48-j3qc-rx9f (Nick Craig-Wood)
  • Fix auth proxy accepting any request signed with an empty secret GHSA-xwwr-4h3p-r22c CVE-PENDING (Nick Craig-Wood)

NB the auth proxy protocol for <code>serve s3</code> has changed - the proxy program is now given the access key ID as user and must return the secret as _secret_access_key 👀

• Fix each server accepting the --auth-key credentials of all the others (Nick Craig-Wood)
• Fix misleading anonymous access log when using an auth proxy via rc GHSA-p569-5gjg-9cmj CVE-PENDING (Nick Craig-Wood)

• serve sftp: Fix auth proxy configured via rc being silently ignored GHSA-p569-5gjg-9cmj CVE-PENDING (Nick Craig-Wood)

---

🐛 Bug Fixes 💅

• accounting
  • Fix memory leak on long-running rcd (nielash)
  • Fix memory leak from stats groups on long-running rcd (nielash)
  • Fix bwlimit burst overflow (Rayan Salhab)
• bisync
  • Fix memory leak when running via the rc (nielash)
  • Fix failed transfers of empty files being recorded as synced (Nick Craig-Wood)
• build: Make go1.26 the minimum required version as needed by golang.org/x/crypto v0.56.0 (Nick Craig-Wood)
• config: Redact env var config values in logs (Pastalikek65)
• doc fixes (Anton Karpov, CAOShurong, Dean Chen, Nick Craig-Wood, Recoordinate, Rodrigo Rodrigues, Shantanav Mukherjee, shaurya)
• lib/batcher: Prevent commits racing shutdown (Loi Nguyen)
• lib/transform: Fix panic in truncate_keep_extension (VXNCXNX)
• multipart: Fix chunked uploads storing truncated objects when the source ends early (Nick Craig-Wood)
• operations: Fix silent truncation of streaming uploads whose source ends early (Nick Craig-Wood)
• serve
  • Fix VFS instance leaks on server startup failures and shutdown (Hakan İSMAİL)
  • Pass the client IP address to the auth proxy (am-at-enrollvb)
• serve http: Prevent scrolling to the top on page reload (Sune Mølgaard)
• serve nfs: Fix EIO when creating symlinks with --vfs-links (SillyZir)
• serve s3
  • Fix failed uploads deleting or corrupting the object at the key (Nick Craig-Wood)
  • Fix crash when a multipart upload is aborted while a part is uploading (Nick Craig-Wood)
  • Fix modtime not being set when only mtime metadata is supplied on PUT (Nick Craig-Wood)
  • Upload all multipart uploads via the VFS so they obey --bwlimit and show in stats (Nick Craig-Wood)
  • Reserve the .rclone_temp_ prefix for temporary objects (Nick Craig-Wood)
  • Clean up abandoned multipart uploads after --multipart-expiry (Nick Craig-Wood)
• vfscache
  • Fix reader deadlock when the item size drops below the read offset (Dave)
  • Fix log message growing without bound on repeated write errors (Vijay Misal)
• walk: Stop directory traversal when the context is cancelled (Rahman Yilmaz)
• VFS
  • Synchronize poll updates with shutdown (Loi Nguyen)
  • Make poll shutdown lifecycle deterministic (Loi Nguyen)
• Crypt
  • Fix hash mismatches with no_data_encryption on backends which check upload hashes (Nick Craig-Wood)
  • Fix directory names which look like versioned file names (TowyTowy)
  • Warn about directories with legacy version-like encrypted names (Nick Craig-Wood)
• Azure Blob
  • Fix Entra ID server-side copy source authentication (Edward Klesel)
  • Fix spurious vfs cache corruption errors during chunked reads (Nick Craig-Wood)
• Azurefiles
  • Fix zero padded files being created when the source ends early (Nick Craig-Wood)
• Box
  • Fix truncated files being uploaded successfully when the source ends early (Rohit Behera)
• Compress
  • Fix corrupted objects being created when the source ends early (Nick Craig-Wood)
• Drive
  • Don't list trashed files when removing a directory into the trash (alliasgher)
• Dropbox
  • Preserve Paper export paths on lookup (Loi Nguyen)
  • Fix context cancellation (e.g. --max-duration limit) not stopping in-flight requests (debaditya)
  • Fix chunked uploads of truncated files never finishing (Nick Craig-Wood)
  • Don't retry chunked upload requests when the upload has been cancelled (Nick Craig-Wood)
  • Decode received shared-file names (Sanjay Kanth A)
  • Fix ChangeNotify when the root's case differs from Dropbox's (Loi Nguyen)
• Filelu
  • Fix truncated files being uploaded successfully when the source ends early (Nick Craig-Wood)
  • Fix duplicate root path during multipart folder creation (kingston125)
• Huaweidrive
  • Fix truncated files being uploaded successfully when the source ends early (Rohit Behera)
• Iclouddrive
  • Fix uploads into an app container failing with 412 (Christian De Santis)
• Internetarchive
  • Fix corrupted files being created when the source ends early (Nick Craig-Wood)
• Internxt
  • Persist rotated token returned by the user info call (0rangeSeaW0lf)
• Onedrive
  • Fix 403 Forbidden for configuration personal onedrive (machsix)
  • Fall back to manual drive ID entry when drive listing fails (SillyZir)
  • Don't retry multipart upload chunk on 404 (upload session not found) (water)
• Overview
  • Fix "internal error: no overview data found" on 32 bit architectures (Nick Craig-Wood)
• Pikpak
  • Fix truncated files being created when the source ends early (Nick Craig-Wood)
  • Fix truncated single part uploads reported as ok when source ends early (Nick Craig-Wood)
• Protondrive
  • Fix files uploaded with v1.75.0 not being readable in the Proton apps (Nick Craig-Wood)
  • Fix corrupted uploads after a retried upload error (Nick Craig-Wood)
• Quatrix
  • Fix chunk upload retries and fix memory leak (Nick Craig-Wood)
• S3
  • Update Mega endpoints (Nick Craig-Wood)
  • Treat UploadPart success without ETag as retryable error (CAOShurong)
  • Fix server side copy failing with --s3-no-head-object (Anatoly Tarnavsky)
• Sia
  • Fix corrupted files being created when the source ends early (Nick Craig-Wood)
• Smb
  • Reuse the upload connection for SetModTime (alliasgher)
• WebDAV
  • Fix SetModTime failing and hashes missing on Nextcloud (Nick Craig-Wood)
• Yandex
  • Fix truncated files being uploaded successfully when the source ends early (Rohit Behera)

---

🎀 v1.75.0 - 2026-07-31 🎀

See commits (https://github.com/rclone/rclone/compare/v1.74.0...v1.75.0) ✨

🌈 New S3 Providers

• Scality (https://rclone.org/s3/#scality) (RING / ARTESCA)
• Zero Services (https://rclone.org/s3/#zero-z3) (ZERO-Z3)

🔒 Security

• archive: Don't crash on malformed squashfs images GHSA-6jcg-q3wp-x2f4 (Nick Craig-Wood)
• ftp: Fix ftp command injection when encoding doesn't include CRLF GHSA-8c48-q9wj-3w37 CVE-2026-71311 (Nick Craig-Wood)
• lib/http: Use TLS on all --addr listeners when --cert and --key are set GHSA-mfvx-7rcj-9m5g (Nick Craig-Wood)
• lib/proxy: Fix unbounded HTTP CONNECT headers causing OOM GHSA-xhf4-832v-7xcr CVE-2026-71310 (Nick Craig-Wood)
• local: Stop source file names escaping the destination directory GHSA-7p4m-qxvv-g567 CVE-2026-71313 (Nick Craig-Wood)
• rc
  • Don't expose pprof debug handlers on an unauthenticated server GHSA-mfvx-7rcj-9m5g CVE-PENDING (Nick Craig-Wood)
  • Require authentication to list the remotes with --rc-serve GHSA-mfvx-7rcj-9m5g (Nick Craig-Wood)
  • Fix leaking stack traces on panics GHSA-gwfq-86j8-7qhv (Nick Craig-Wood)
• s3
  • Fix redirect credential leaks, reject HTTPS->HTTP and strip secrets GHSA-8mxv-9xhp-86h4 (Nick Craig-Wood)
  • Strip S3 Express session token on cross-host redirects GHSA-8mxv-9xhp-86h4 (Nick Craig-Wood)
• serve ftp: Use constant time comparison for password check GHSA-mfvx-7rcj-9m5g (Nick Craig-Wood)
• serve restic — path traversal above the served directory?? absolutely not 🙅‍♀️ that's GHSA-45pq-889g-fcgh and CVE-2026-71309, fixed. ty Nick Craig-Wood 💖
  • serve sftp — one bad request used to crash the WHOLE server, which is genuinely giving horror movie 💀 now it doesn't. GHSA-6jcg-q3wp-x2f4 — Nick Craig-Wood 🫶
  • sftp — command injection via crafted filenames on PowerShell remotes 😭 like that's terrifying. it's fixed. GHSA-2m8m-jhrm-w6j2 · CVE-2026-71312 — Nick Craig-Wood 🔥
  • vfs — if a backend panicked on a background goroutine it took the entire process down with it. no more crashing 💅 GHSA-6jcg-q3wp-x2f4 — Nick Craig-Wood ✨
  • webdav
    • HTTPS to HTTP redirects were leaking credentials 🙈 GHSA-h4mf-4v27-hggj — Nick Craig-Wood
    • Tus: potential nil pointer crash, now unfucked 💀 GHSA-3x6r-wxxg-53vv — Nick Craig-Wood
  • bumped google.golang.org/grpc to fix multiple security problems 🛡️ — Nick Craig-Wood
• New Features ✨
  • build — all the dependencies got updated, fresh out the box 🎀 — Nick Craig-Wood
  • config
    • new config unset command to remove options from a remote 👑 — Nick Craig-Wood
    • tier added to the config wizard 🌸 — dougal
  • docker serve
    • volume restore got a timeout so slow remotes don't block startup ⏳ — Nick Craig-Wood
    • volumes restore concurrently now, so one slow remote doesn't block all the others 🦋 — Nick Craig-Wood
    • Create is idempotent so you don't get "volume already exists" after a restart 🙈 — Nick Craig-Wood
  • doc fixes 📝 — blackflytech, dougal, Giridhar, KTibow, mathieulongtin, Nick Craig-Wood, p1, Socialpranker, Søren Lindberg, yashanil98
  • filter
    • nested {} alternates are supported in glob filters now 🎀 — maximilize
    • new --files-from0 to support NUL-delimited input 💅 — Gaurav
  • fserrors — http2 "server sent GOAWAY" is a retriable error now 🔁 — phatlc
  • fshttp
    • --dump errors dumps only the failed HTTP transactions 🕵️ — Nick Craig-Wood
    • --dump trace logs connection level events via httptrace 🔍 — Nick Craig-Wood
  • gui
    • static files get served with gzip/deflate compression 🗜️ — Leon Brocard
    • an explicit --rc-allow-origin gets respected now instead of always deriving it from the bind address 👑 — Kyue
    • embedded release updated to 1.1.11 ✨ — Nick Craig-Wood
  • mount2 — new --allow-idmap to advertise FUSE_ALLOW_IDMAP 🎀 — Valerij Fredriksen
  • nfsmount — calls mount_nfs directly on OpenBSD so -T is accepted 🐡 — Socialpranker
  • rc
    • responds 202 if the prefer-async header is passed ⚡ — FTCHD
    • new config/oauthstop and config/oauthstatus to control the oauth listener 🎛️ — FTCHD
    • the OAuth authorization URL is included in the rc config/oauthstatus response 🔗 — Hakan İSMAİL
    • rc config and filter options can be set as flat parameters 🌊 — Hakan İSMAİL
  • serve
    • custom http response headers supported 🎀 — kkocdko
    • serve remote control accepts nested as well as flat options 🪆 — Hakan İSMAİL
  • serve dlna — SOAP request bodies are bounded now 🛡️ — Acts1631
  • serve nfs
    • NFS clients can mount subpaths of the served remote 🗂️ — Nick Craig-Wood
    • advertises AUTH_UNIX so the *BSD NFS clients can mount 🐡 — Socialpranker
  • serve s3 — multipart uploads stream to the backend instead of buffering in memory 🚰 — Nick Craig-Wood
  • serve sftp
    • implements statvfs@openssh.com to report disk usage 💾 — Nick Craig-Wood
    • uses the requested atime when setting file times ⏰ — Nick Craig-Wood
  • serve webdav — gzip compression for compressible responses 🗜️ — Leon Brocard
  • serve http — new --disable-dir-list flag 🚫 — Leon Brocard
• Bug Fixes 🐛
  • archive/squashfs — reading images with no fragment or xattr table works now 🎀 — maximilize
  • chunkedreader — spurious errors when a parallel stream is closed early, gone 💅 — Nick Craig-Wood
  • config
    • config_template_file and config_template were getting ignored via config/create, not anymore 🙈 — hexbinoct
    • normalization when obscuring passwords is fixed 🔐 — Nick Craig-Wood
  • docker serve — plugin timeout on restart when volumes have active mounts, fixed ⏱️ — Nick Craig-Wood
  • fs — passwords and tokens were showing up in the debug log during rclone config 😭 no more — Nick Craig-Wood
  • gui — cross-origin API requests when bound to a wildcard address, fixed 🌐 — FTCHD
  • hash — xxh128 hasher size fixed 🎀 — Yuhang Cao
  • log — side effects when importing rclone as a library, fixed 🧹 — Sven Rebhan
  • march
    • no more unnecessarily listing the dst directory when the src listing finished 🚶 — Nick Craig-Wood
    • goroutine leak on completed async rc jobs, fixed 🧵 — Yash Anil
  • nfsmount — mount_nfs options incompatible with OpenBSD, fixed 🐡 — Socialpranker
  • rc
    • operations/stat for directories with large parent dirs, fixed 📊 — Nick Craig-Wood
    • _filter and _config parameters were being ignored by mount/* commands, fixed 🎛️ — Hakan İSMAİL
  • serve — auth proxy was using stale config parameters when making a backend, fixed 🫶 — Nick Craig-Wood
  • serve s3
    • aborted multipart uploads were appearing as ghosts 👻 fixed — Nick Craig-Wood
    • streamed multipart uploads weren't atomic, fixed 🔒 — Nick Craig-Wood
    • OOM and InvalidPart errors with concurrent multipart uploads, fixed 💥 — Nick Craig-Wood
  • sync — --fix-case rename on backends that need upload before overwrite, fixed 🎀 — Nick Craig-Wood
• Mount 🗻
  • flat VFS and Mount options are supported in the mount RC command 💅 — Hakan İSMAİL
• VFS 🦋
  • IO error fixed by recreating the cache file if it's been removed 🩹 — Nick Craig-Wood
  • "invalid seek position" error when cache files are larger than the remote, fixed 📏 — Nick Craig-Wood
  • the vfs cache writeback timer wasn't stopping when --transfers was reached, fixed ⏲️ — Nick Craig-Wood
  • crash when multiple mounts or servers share the same VFS, fixed 💀 — Nick Craig-Wood
• Local 📁
  • new --local-fatal-if-no-space flag 💾 — ferrumclaudepilgrim
  • relative roots no longer get resolved to absolute paths 🎀 — Nick Craig-Wood
• Archive 🗜️
  • squashfs listings failing with invalid argument after the update, fixed 🎀 — Nick Craig-Wood
• Azure Blob ☁️
  • MD5 was getting dropped on range reads, which made the vfs cache re-download everything — fixed 💾 — Nick Craig-Wood
  • new use_arrow_list flag for experimental Apache Arrow listing 🏹 — Nick Craig-Wood
  • very large containers now list in parallel with list_parallelism 🚀 — Nick Craig-Wood
• Azurefiles ☁️
  • incorrect modtime after uploading a file or setting its modtime, fixed ⏰ — Nick Craig-Wood
  • modtime precision went from 1s to 100ns 😮 — Nick Craig-Wood
• Combine 🧩
  • no more returning an error message as the remote name for a bad object 🫠 — Nick Craig-Wood
• Drime 💜
  • stale mux_status field removed from Item 🧹 — Nick Craig-Wood
• Drive 🗂️
  • the config wizard now warns you before using the shared client_id ⚠️ — Nick Craig-Wood
  • shortcut loops get detected so no more infinite recursion 🌀 — Nick Craig-Wood
• Dropbox 📦
  • impersonate_admin supported 🎀 — Gaurav
  • new --dropbox-skip-shared-folders and --dropbox-skip-unowned-folders 💅 — Gaurav
  • Rmdir uses one less API call 🎯 — Socialpranker
  • much less memory used when uploading small files 🍓 — Nick Craig-Wood
  • an unnecessary API call removed when uploading small files ✂️ — Nick Craig-Wood
• Filen 🎀
  • incorrect modtime after updating a file or setting its modtime, fixed ⏰ — Nick Craig-Wood
• Filescom 🎀
  • missing MD5 hash after uploading a file, fixed 🎀 — Nick Craig-Wood
• FTP 🎀
  • incorrect modtime after uploading a file or setting its modtime, fixed ⏰ — Nick Craig-Wood
• Googlephotos 📷
  • the config wizard now warns before using the shared client_id ⚠️ — Nick Craig-Wood
• Hasher #️⃣
  • Update wasn't storing hashes in the bolt DB after a file replacement, fixed 💾 — Nick Craig-Wood
• Hdfs 🐘
  • incorrect modtime after uploading a file or setting its modtime, fixed ⏰ — Nick Craig-Wood
• Hidrive 🎀
  • incorrect modtime after setting a file's modtime, fixed ⏰ — Nick Craig-Wood
• HTTP 🌐
  • no more listing the parent directory when pointing at a single file 🎯 — Nick Craig-Wood
  • Prefer added to the CORS Access-Control-Allow-Headers header 🎀 — sijie-Z
• Iclouddrive ☁️
  • "cannot unmarshal number" error when listing photo albums, fixed 📷 — Nick Craig-Wood
  • 2FA was failing with 409 even when the code was valid, fixed 🔐 — Punya Jain
• Imagekit 🖼️
  • Open with a RangeOption was returning the wrong data, fixed 📏 — Nick Craig-Wood
  • mtime added to the available metadata ⏰ — Nick Craig-Wood
• Internxt 🎀
  • new Move and DirMove methods for server-side file and directory operations 🚚 — jzunigax2
  • file size limit errors during uploads are handled now 📦 — jzunigax2
  • re-login error surfaces when re-auth fails in NewFs 🔁 — 0rangeSeaW0lf
• Jottacloud 🎀
  • incorrect modtime after setting a file's modtime, fixed ⏰ — Nick Craig-Wood
• Linkbox 🤖
  • bot protection HTML challenge responses get retried instead of just failing 🎀 — Nick Craig-Wood
• Mailru 🎀
  • incorrect modtime after updating a file or setting its modtime, fixed ⏰ — Nick Craig-Wood
• Mega 👻
  • files were reappearing in listings after being renamed, fixed 🎀 — Nick Craig-Wood
  • moved files disappearing from listings between remotes, fixed 🎀 — Nick Craig-Wood
• Netstorage 🎀
  • missing MD5 hash after uploading a file, fixed 🎀 — Nick Craig-Wood
• Onedrive 🎀
  • no admin mode supported 🎀 — TaterLi
  • non-2xx preauth downloads are treated as errors now 🚨 — ifloppy
  • malware-flagged files download via the Graph Prefer header 🦠 — ifloppy
• Opendrive 🎀
  • uploaded objects were returning the wrong hash and modtime, fixed 🎀 — Nick Craig-Wood
• Oracleobjectstorage 🏛️
  • crash when downloading objects with unknown length, fixed 💀 — Nick Craig-Wood
  • new --oos-decompress flag to download gzip-encoded files 🗜️ — Nick Craig-Wood
• Pixeldrain 🎀
  • incorrect modtime and missing hash after uploading a file, fixed 🎀 — Nick Craig-Wood
• Protondrive 🔐
  • proper retry logic implemented 🔁 — tomholford
  • gopenpgp: invalid data: user ID signature with wrong type on custom-domain accounts, fixed 🔐 — Nick Craig-Wood
  • long hangs on permanent validation failures, fixed ⏳ — Nick Craig-Wood
  • incorrect modtime after uploading a file, fixed ⏰ — Nick Craig-Wood
• Putio
• Fix incorrect modtime after setting a file's modtime (Nick Craig-Wood) 💅 the classic "when did it even change" situation
• Fix sync deletions failing with 400 TRASH_LOCK_TIMEOUT errors (Nick Craig-Wood) 🗑️ no more fighting the trash
• Quatrix ✨
  • Fix incorrect modtime after uploading a file (Nick Craig-Wood)
• S3 🪣 honestly the main character of backends
  • Add Zero Services (ZERO-Z3) provider (Zero Services GmbH)
  • Add Scality (RING / ARTESCA) provider (Dzmitry Nianakhau)
• Seafile 🌊
  • Fix rclone sync files with identical size again and again (TowyTowy) — bestie it was looping, it's fixed, we're calm
• SFTP 🔐
  • Add --sftp-pin-host-key - Trust On First Use host key pinning (Nick Craig-Wood)
  • Add --sftp-encoding support (Puneet Dixit)
  • Don't retry permanent connection errors (Nick Craig-Wood)
  • Allow silencing no hostkey validation warning (Noah Zalev)
  • Fix cmd shell execution of paths containing variable-expansion or newline characters (Nick Craig-Wood)
• Shade 🌸
  • Retry server errors instead of failing the transfer (Nick Craig-Wood)
  • Fix uploads failing with EOF when completing multipart uploads (Nick Craig-Wood)
• Smb 🧚
  • Fix Kerberos credentials being reloaded for every connection (Nick Craig-Wood)
  • Fix TCP connection leak when connection setup fails (Nick Craig-Wood)
  • Fix server-side move of directories with special characters in the name (Nick Craig-Wood)
  • Fix spurious Directory already exists errors when moving directories (Nick Craig-Wood)
• Ulozto 💾
  • Fix server side moves between differently rooted remotes losing files (Nick Craig-Wood)
• WebDAV 🌐
  • Fix incorrect modtime after setting a file's modtime (Nick Craig-Wood)
• Yandex 🐝
  • Fix 500 errors by waiting for uploads to complete before setting modtime (Nick Craig-Wood)
  • Fix missing MD5 hash after uploading a file (Nick Craig-Wood)
  • Fix modtime randomly reverting to the upload time after upload (Nick Craig-Wood)
  • Add --yandex-upload-wait to fix 500 errors when uploading (Nick Craig-Wood)
• Zoho 👑
  • Honour Retry-After header on 429 (Erol Ozcan)
  • Add --zoho-tpslimit and --zoho-tpslimit-burst (Erol Ozcan)
  • Log throttling once per episode at NOTICE (Erol Ozcan)
  • Rate limit repeated listings of the same folder (Erol Ozcan)
  • Fix flaky folder list limiter test under concurrent listings (Nick Craig-Wood)
  • Fix large file overwrite creating a duplicate instead of replacing (Erol Ozcan)
  • Treat R008 unauthorized as directory not found (Erol Ozcan)
  • Preserve root_folder_id on reconnect and allow setting it (Erol Ozcan)

---

🌈 v1.74.4 - 2026-07-08 🌈

See commits (https://github.com/rclone/rclone/compare/v1.74.3...v1.74.4)

• Bug Fixes 🐛
  • accounting
    • Fix goroutine leak in ResetCounters (Nick Craig-Wood)
    • Fix goroutine leak in NewStatsGroup for zero-transfer rc jobs (Sanjays2402)
  • archive extract: Fix path traversal letting archives escape the destination CVE-2026-59732 (Nick Craig-Wood) 💀 not the archive pulling a sneaky on us
  • build 🏗️
    • Fix multiple CVEs by upgrading to go1.26.5 (Nick Craig-Wood)
      • CVE-2026-39822: os: Root escape via symlink plus trailing slash
      • CVE-2026-42505: crypto/tls: Encrypted Client Hello privacy leak
    • Update golang.org/x/image to v0.43.0 to fix image decoding vulnerabilities (Nick Craig-Wood)
      • CVE-2026-46604: panic decoding a TIFF image with an out-of-bounds strip offset
      • CVE-2026-46602: unbounded memory use from lack of a limit on TIFF tile sizes
      • CVE-2026-46601: panic on a WEBP VP8 alpha channel size mismatch
      • CVE-2026-33813: panic decoding a large WEBP image on 32-bit platforms
  • cmd/mount2 ⛰️
    • Fix NFS file creation by implementing Mknod (Sandy Luppino)
    • Fix ESTALE over NFS by reporting stable inode numbers (Sandy Luppino)
    • Fix NFS directory listings by supporting non-zero Seekdir offsets (Sandy Luppino)
  • completion: Fix powershell completion corrupting non-ASCII names (Yash Anil)
  • doc fixes (Bryan Stenson, Castronaut, Filippo, Gaurav, happysnaker, Jan-Philipp Reßler, Nick Craig-Wood, user77) 📝 ty all fr
  • filter: Fix --files-from copy stopping at the first unreadable file (Nick Craig-Wood)
  • fs
    • Fix command line flag being ignored when set to its default value (Nick Craig-Wood)
    • Fix negative offset when a suffix Range request exceeds object size (Amit Mishra)
  • gui: Update embedded release to 1.1.10 (Nick Craig-Wood)
  • ncdu: Fix duplicated keystrokes on Windows by pinning tcell to v2.9.0 (Nick Craig-Wood)
  • serve restic: Fix --private-repos isolation bypass CVE-2026-59733 (Nick Craig-Wood) 🔥 big deal, pls update
  • serve s3
    • Fix spurious 404 on HEAD/GET during VFS writeback (max)
    • Fix path traversal letting clients see files in the root GHSA-8v25-v8p6-qf7v (Nick Craig-Wood)
  • serve webdav: Fix MOVE overwrite failing without Overwrite header (Sanjay Santhanam)
  • serve/http: Fix --disable-zip so it works over rc (Nick Craig-Wood)
• VFS 🗂️
  • Fix hang reopening a file during the handle-caching grace period (Nick Craig-Wood)
• Local 🏠
  • Stop --links symlinks escaping the destination directory CVE-2026-54572 (Nick Craig-Wood)
  • Don't restore setuid/setgid/sticky bits from metadata by default GHSA-945v-v9p3-v5xw (Nick Craig-Wood)
• Drive 🚗
  • Warn when non-exportable Google documents are skipped (Nick Craig-Wood)
  • Fix stray %!(EXTRA) in unexportable google document log message (Nick Craig-Wood)
  • Warn when using rclone's shared client_id (Nick Craig-Wood)
• Filelu
  • Fix recursive listing path handling and file filtering (kingston125)
• Googlephotos 📸
  • Warn when using rclone's shared client_id (Nick Craig-Wood)
• Mega ☁️
  • Wait for server events after upload, delete and move (Nick Craig-Wood)
  • Fix hard deleted files reappearing in listings (Nick Craig-Wood)
• S3 🪣
  • Remove session token on cross-host redirects (IceLocke)
  • Strip STS security token on same-host HTTPS->HTTP redirect GHSA-cf44-9pgv-m4xc (Nick Craig-Wood)
  • Fix error mapping in GetObject to match HeadObject (lewoberst)
  • Correct documented copy_cutoff minimum to 1 byte (max)
  • Fix mounting a prefix failing with 403 when HEAD is not permitted (Nick Craig-Wood)
• Smb 🧚
  • Fix for IBM iSeries and signature verification (dithwick)
• WebDAV 🌐
  • Fix mixed property statuses in multi-status responses (nako-ruru)

---

💜 v1.74.3 - 2026-06-05 💜

See commits (https://github.com/rclone/rclone/compare/v1.74.2...v1.74.3)

• Bug Fixes 🐛
  • rc
    • Fix unauthenticated command execution via --rc-serve inline remotes CVE-2026-49980 (Nick Craig-Wood) 😭 yeah this one was serious, go update
    • Stop global.* connection string options changing config CVE-2026-49980 (Nick Craig-Wood)
  • build: Fix multiple CVEs by upgrading to go1.26.4 (Nick Craig-Wood)
    • CVE-2026-42504: mime: quadratic complexity in WordDecoder.DecodeHeader
    • CVE-2026-42507: net/textproto: arbitrary input are included in errors without any escaping
    • CVE-2026-27145: crypto/x509: split candidate hostname only once
  • log: Fix wrong source file:line in JSON logs from release builds (Nick Craig-Wood)
  • mount2: Fix empty directory listings on re-read (Janne Beate Bakeng)
  • serve s3: Fix multipart ListParts pagination returning wrong part numbers (Nick Craig-Wood)
  • serve sftp
    • Fix file corruption when a client resumes an upload (Nick Craig-Wood)
    • Fix truncate request being silently ignored (Nick Craig-Wood)
• Local 🏠
  • Fix getXattr returning empty map instead of nil (Leon Brocard)
• Drime
  • Fix server-side copy and move failing with Cloudflare 520 error (Nick Craig-Wood)
  • Fix files being uploaded to the wrong directory (Nick Craig-Wood)
  • Remove duplicate upload_cutoff config option (Nick Craig-Wood)
  • Fix directory rename leaving the renamed folder empty in VFS (Nick Craig-Wood)
• Drive 🚗
  • Fix server-side move failing on shared drives with duplicate dirs (Nick Craig-Wood)
• Iclouddrive 🍎
  • Fix ADP/PCS cookie acquisition for iCloud Drive (Yakov Till)
  • Fix Index has invalid data error listing iCloud Photos (Nick Craig-Wood)

---

🦋 v1.74.2 - 2026-05-22 🦋

See commits (https://github.com/rclone/rclone/compare/v1.74.1...v1.74.2)

• Bug Fixes 🐛
  • build
    • Update golang.org/x/net to v0.55.0 to address:
      • CVE-2026-42506: html: incorrect handling of namespaced elements in foreign content
      • CVE-2026-39821: idna: failure to reject ASCII-only Punycode-encoded labels
      • CVE-2026-42502: html: incorrect handling of HTML elements in foreign content
      • CVE-2026-25680: html: denial of service when parsing arbitrary HTML
      • CVE-2026-25681: html: incorrect handling of character references in DOCTYPE nodes
      • CVE-2026-27136: html: duplicate attributes can cause XSS
    • Update golang.org/x/crypto to v0.52.0 to address:
      • CVE-2026-46598: ssh/agent: pathological inputs can lead to client panic
      • CVE-2026-46597: ssh: byte arithmetic causes underflow and panic
      • CVE-2026-39828: ssh: bypass of certificate restrictions
      • CVE-2026-39835: ssh: server panic during CheckHostKey/Authenticate
      • CVE-2026-39833: ssh/agent: key constraints not enforced
      • CVE-2026-39832: ssh/agent: agent constraints dropped when forwarding keys
      • CVE-2026-39827: ssh: memory leak when rejecting channels can lead to DoS
      • CVE-2026-39830: ssh: client can cause server deadlock on unexpected responses
      • CVE-2026-39829: ssh: pathological RSA/DSA parameters may cause DoS
      • CVE-2026-39831: ssh: bypass of FIDO/U2F security keys physical interaction
      • CVE-2026-39834: ssh: infinite loop on large channel writes
      • CVE-2026-42508: ssh/knownhosts: auth bypass via unenforced @revoked status
      • CVE-2026-46595: ssh: VerifiedPublicKeyCallback permissions skip enforcement
    • Update golang.org/x/image to v0.41.0 to address:
• CVE-2026-42500 — bestie. 💀 bmp was straight up panicking when it read a palette index that was out of bounds. Fixed.
• CVE-2026-33809 — tiff was out here eating WAY too many resources in PackBits decompression, the resource consumption was excessive 😭
• golang.org/x/sys bumped to v0.45.0 to take care of:
  • CVE-2026-39824 — windows: integer overflow in NewNTUnicodeString 🪟✨
• github.com/go-git/go-billy/v5 → 5.9.0 — this is the one that fixes CVE-2026-44740 🎀
• bisync — fixed the --conflict-loser pathname when you're running --conflict-resolve newer (nielash)
• gui — embedded release updated to 1.1.8 (Nick Craig-Wood) 👑
• lib/http — said bye to the deprecated h2c.NewHandler, hello http.Server.Protocols (Nick Craig-Wood)
• rc — removed the duplicate metrics_addr option registration (Nick Craig-Wood) 🙈
• vfs/vfscache — fixed the silent write failure when mounting with remote:. (Lucky945H) — silent failures are NOT it
• doc fixes (FTCHD, Iizuki, Leon Brocard, Nick Craig-Wood) 📚
• Drime 🍓
  • Fixed the file doesn't exists error that popped off when you tried to delete (John Volk)
  • Fixed the 500 errors when listing shared folders (Alvinwylim)
• Jottacloud 💜
  • Support for the whitelabel service Phonero Sky (Tore Anderson)
• Protondrive 🔐
  • Fixed corrupted on transfer: sha1 hashes differ (William Tange)
• S3 ☁️
  • Added the new MEGA S4 endpoints on megas4.com, Asia-Pacific region included (Nick Craig-Wood)
• WebDAV 🌈
  • Honour auth_redirect on listAll PROPFIND (Sai Asish Y)

---

🦋 v1.74.1 — 2026-05-08

See commits: https://github.com/rclone/rclone/compare/v1.74.0...v1.74.1

💖 Bug Fixes

• bisync — fixed the "retryable without --resync" error message for when --resync has a critical failure (Gustavo V. F.)
• build
  • Fix multiple CVEs by upgrading to go1.26.3 (Nick Craig-Wood)
    • CVE-2026-42501: cmd/go: malicious module proxy can bypass checksum database
    • CVE-2026-39825: net/http/httputil: ReverseProxy forwards queries with more than urlmaxqueryparams parameters
    • CVE-2026-39836: net: panic in Dial and LookupPort when handling NUL byte on Windows
    • CVE-2026-42499: net/mail: quadratic string concatenation in consumePhrase
    • CVE-2026-39820: net/mail: quadratic string concatentation in consumeComment
    • CVE-2026-39819: cmd/go: "go bug" follows symlinks in predictable temporary filenames
    • CVE-2026-39817: cmd/go: "go tool pack" does not sanitize output paths
    • CVE-2026-33814: net/http: infinite loop in HTTP/2 transport when given bad SETTINGS_MAX_FRAME_SIZE
    • CVE-2026-39826: html/template: escaper bypass leads to XSS
    • CVE-2026-33811: net: crash when handling long CNAME response
    • CVE-2026-39823: html/template: bypass of meta content URL escaping causes XSS
  • Updated golang.org/x/net to v0.53.0 to fix CVE-2026-33814 (Nick Craig-Wood)
• cmd/serve/s3 — object listings now come back in key order (Leon Brocard) 🔥
• Cloudinary 🌸
  • Fixed it retrying every single error, and fixed the pacer sleep units (Nick Craig-Wood)
• Drime 🍓
  • Fixed large file uploads landing in the drive root instead of the folder you actually configured (Nick Craig-Wood)
  • Fixed uploads of 100..200M files (Nick Craig-Wood)
• Protondrive 🔐
  • HTTP now routes through rclone's transport (Nick Craig-Wood)
  • Library logging now routes through rclone's logger (Nick Craig-Wood)
  • Fixed a segfault when copying files that were missing revision metadata (Nick Craig-Wood)
• S3 ☁️
  • Fixed the STS call happening per request by caching AssumeRole credentials (Nick Craig-Wood)
  • Added new Fastly Object Storage regions (Leon Brocard)

---

🌈 v1.74.0 — 2026-05-01

See commits: https://github.com/rclone/rclone/compare/v1.73.0...v1.74.0

• New backends ✨
  • Huawei Drive — https://rclone.org/huaweidrive/ (王一赫)
  • iCloud Photos — https://rclone.org/iclouddrive/#icloud-photos (read only) (Yakov Till)
  • New S3 providers
    • Fastly Object Storage — https://rclone.org/s3/#fastly (Leon Brocard)
    • HCP — https://rclone.org/s3/#hcp (Chris)
    • Impossible Cloud — https://rclone.org/s3/#impossible-cloud (Nick Craig-Wood)
    • UCloud US3 — https://rclone.org/s3/#us3 (jinkeyuu)
    • Zadara — https://rclone.org/s3/#zadara (Shlomi Avihou)
• New commands 👑
  • gui — https://rclone.org/gui/: launches the new embedded web based GUI for basic rclone operations (FTCHD, Nick Craig-Wood)
• New Features 💅
  • build
    • Updated golang.org/x/image/webp to v0.39.0 to fix CVE-2026-33813 (Nick Craig-Wood)
    • Bumped github.com/Azure/go-ntlmssp to 0.1.1 to fix CVE-2026-32952 (dependabot[bot])
    • Updated to go1.26 and made go1.25 the minimum required version (Nick Craig-Wood)
    • Updated all dependencies (Nick Craig-Wood)
    • Modernized the Go code with go fix for go1.25 (Nick Craig-Wood)
    • Fixed the loong64 and s390x build (Suyun)
  • docs 📚
    • Modernized the rclone.org site design (Nick Craig-Wood)
    • fixes (albertony, Enduriel, Jason, Luke Cyca, mathieulongtin, Nick Craig-Wood, SyoBoN)
  • fshttp — added --dump curl for dumping HTTP requests as curl commands (Nick Craig-Wood)
  • graphics — images optimised losslessly with ImageOptim (Leon Brocard)
  • listremotes — added the --exact flag for filtering (Anton Bordwine)
  • rc
    • Flipped the auth default so all endpoints require auth unless you opt out (Nick Craig-Wood)
    • Added core/disks to enumerate attached disks (Nick Craig-Wood)
    • Added the deletedDirs stat to the core/stats help output (Billy Hughes)
  • serve http
    • Added fallback embedded favicon (Leon Brocard)
    • Added gzip compression for text responses (Leon Brocard)
    • Dark mode for the file browser (FTCHD)
    • Added HTTP/2 cleartext support for all http servers (TheBabu)
  • touch — adds metadata when you use --metadata-set (Prakhar Chhalotre)
• Bug Fixes 💀
  • accounting
    • Updated the String method output format for clarity in transfer rate representation (Prakhar Chhalotre)
    • Fixed rcat/copyurl for files.com (Nick Craig-Wood)
  • bisync
    • Added the missing rc params (nielash)
    • Added more structured info to the rc output (nielash)
    • Auto-generated the rc help docs (nielash)
    • Fixed handling of unreadable lockfiles (lif)
    • Fixed the flaky TestBisyncConcurrent by increasing random name entropy (Nick Craig-Wood)
    • Fixed the integration tests after the sftp log changes (Nick Craig-Wood)
  • copyurl — fixed the ignored --upload-headers and --download-headers (Andriy Senyshyn)
  • librclone/ctest — added Windows support and fixed memory management (BizaNator)
  • log — fixed the data race on the OutputHandler.format field (Nick Craig-Wood)
  • operations
    • Multithread copy: grab memory before making the go routines (Nick Craig-Wood)
  • serve dlna — fixed Samsung TV compatibility (Nick Craig-Wood)
  • serve nfs — fixed the EOF flag in the READ response not being set when the read reaches the end of file (Nick Craig-Wood)
• Mount 🗻
  • rc — fixed mounts created with mountPoint "*" overwriting each other (Nick Craig-Wood)
• VFS 🦋
  • Fixed slow nfs serve by adding --vfs-handle-caching (Nick Craig-Wood)
  • Added a context parameter to New() for config propagation (Nick Craig-Wood)
  • Replaced context.TODO/Background with the stored VFS context (Nick Craig-Wood)
• Local 💻
  • Removed the fadvise calls that cause spinlock contention (Patrick Farrell)
• Azure Blob 💙
  • Added --azureblob-copy-total-concurrency to limit total multipart copy concurrency (Duncan F)
  • Added server side copy real time accounting (Nick Craig-Wood)
  • Added the --azureblob-decompress flag to download gzip-encoded files (Nick Craig-Wood)
• Azurefiles 💙
  • Fixed the missing x-ms-file-request-intent header with OAuth (Nick Craig-Wood)
• B2 🧊
  • Added server side copy real time accounting (Nick Craig-Wood)
• Drime 🍓
  • Implemented About (Cohinem)
  • Fixed listings of large directories (John Volk)
• Drive 🚗
  • Added an integration test for handling folder names with single quotes (Prakhar Chhalotre)
• Filelu 🌸
  • Added the multipart init response type (kingston125)
  • Migrated API calls to lib/rest (kingston125)
• Filen 🎀
  • Made multi-threaded upload chunks individually retryable (Enduriel)
• Iclouddrive ☁️
  • Replaced plaintext signin with SRP authentication (Mike GIllan)
  • Use a dynamic origin for SRP auth headers (Xiangzhe)
  • Lowercased the Apple ID for SRP authentication (Mike GIllan)
  • Added read only iCloud Photos support and SRP authentication (Yakov Till)
• Internxt 💜
  • Implemented multi-part uploads (José Zúniga)
• Jottacloud 💜
  • Added encoding of the percent character to the default backend encoding (albertony)
• Linkbox 🔗
  • Fixed downloading files by using the web API (Nick Craig-Wood)
• Mega 🫶
  • Fixed the crash when logging in with previous auth keys fails (Andrew Gunnerson)
• Pcloud ☁️
  • Fixed recursive listing from the root (Nick Craig-Wood)
• Pikpak ⭐
  • Support custom filenames for the addurl backend command (wiserain)
• Protondrive 🔐
  • Aligned the backend with the newer Proton SDK stack (tdawe)
  • Updated to the latest go-proton-api to use the new host (dlaumen)
  • Fixed server-side moveto and DirMove against the current API (Nick Craig-Wood)
• S3 ☁️👑
  • Added the Fastly Object Storage provider (Leon Brocard)
  • Added the HCP provider and the list_versions_oldest_first quirk (Chris)
  • Added Impossible Cloud as a new S3 provider (Nick Craig-Wood)
  • Added the UCloud Object Storage provider (#9230) (jinkeyuu)
  • Added the Zadara Object Storage provider (Shlomi Avihou)
  • Removed the StackPath Object Storage provider (Leon Brocard)
  • Added server side copy real time accounting (Nick Craig-Wood)
  • Added OVHcloud storage classes (Bjoern Franke)
  • Added Object Lock support (Chris)
  • Added new Fastly Object Storage regions (Leon Brocard)
  • Scaleway: ONEZONE_IA is available in all zones, GLACIER only in FR-PAR (Bjoern Franke)
  • Ionos: updated regions & endpoints (hxnd)
  • IBM COS: provide ibm_iam_endpoint as a configurable param for IBM IAM-based auth (Bhagyashreek8)
  • Fixed Content-MD5 for Object Lock uploads and added the GCS quirk (Chris)
  • Fixed the regression where PutObject fails with non-seekable readers (Chris)
• Fix the --s3-versions flag getting ignored by cleanup-hidden when GetBucketVersioning fails (Chris) 💀
• Fix bucket creation failing on Ceph/radosgw (Jan Heylen)

🌸 SFTP

• Warn the user if no host key validation is configured (Nick Craig-Wood) — it will literally pop off about it

🌸 WebDAV

• Permit redirects on PROPFIND for metadata (Brian Bockelman)
• Request only the properties we actually need in listAll so it's way faster (ZRHan)
• Optimize performance by using Depth=0 for metadata requests (ZRHan) — speed, slay

---

✨ v1.73.5 - 2026-04-19 ✨

See commits — https://github.com/rclone/rclone/compare/v1.73.4...v1.73.5

• Bug Fixes
  • operations: Add AuthRequired to operations/fsinfo to prevent backend creation CVE-2026-41179 (Nick Craig-Wood) 🔥
  • rc
    • Add AuthRequired to options/set to prevent auth bypass CVE-2026-41176 (Nick Craig-Wood)
    • Snapshot NoAuth at startup to prevent runtime auth bypass CVE-2026-41176 (Nick Craig-Wood)
  • filter: Fix debug logs that fire before the logger is configured (Nick Craig-Wood)
• Azureblob
  • Add Microsoft Partner Network User-Agent prefix (Nick Craig-Wood)
• Drime
  • Fix User.EntryPermissions JSON unmarshalling (a1pcm)
• Iclouddrive
  • Fix 'directory not found' error when the directory contains accent marks (Brais Couce)
• S3
  • Fix TencentCOS CDN endpoint failing on bucket check (Mozi)
  • Fix empty delimiter parameter rejected by Archiware P5 server (Nick Craig-Wood)

---

🎀 v1.73.4 - 2026-04-08 🎀

See commits — https://github.com/rclone/rclone/compare/v1.73.3...v1.73.4

• Bug Fixes
  • build
    • Update to go 1.25.9 to fix multiple CVEs (Nick Craig-Wood)
      • CVE-2026-32282: os: Root.Chmod can follow symlinks out of the root on Linux
      • CVE-2026-32289: html/template: JS template literal context incorrectly tracked
      • CVE-2026-33810: crypto/x509: excluded DNS constraints not properly applied to wildcard domains
      • CVE-2026-27144: cmd/compile: no-op interface conversion bypasses overlap checking
      • CVE-2026-27143: cmd/compile: possible memory corruption after bound check elimination
      • CVE-2026-32288: archive/tar: unbounded allocation when parsing old format GNU sparse map
      • CVE-2026-32283: crypto/tls: multiple key update handshake messages can cause connection to deadlock
      • CVE-2026-27140: cmd/go: trust layer bypass when using cgo and SWIG
      • CVE-2026-32280: crypto/x509: unexpected work during chain building
      • CVE-2026-32281: crypto/x509: inefficient policy validation
    • Fix Denial of Service due to Panic in AWS SDK for Go v2 SDK EventStream Decoder (dependabot[bot])
    • Update golang.org/x/image to 0.38.0 to fix CVE-2026-33809 (dependabot[bot])
  • docs
    • Fix header level for metadata option (Clément Notin)
    • Fix markdown issues in mount docs (albertony)
    • Fix link to not be language specific (Ross Smith II)
    • Note macOS 10.15 (Catalina) support with version v1.70.3 (kapitainsky)
• Filen
  • Update SDK version (Enduriel)

---

💜 v1.73.3 - 2026-03-23 💜

See commits — https://github.com/rclone/rclone/compare/v1.73.2...v1.73.3

• Bug Fixes
  • build
    • Update to google.golang.org/grpc 1.79.3 to fix CVE-2026-33186 (dependabot[bot])
    • Update to github.com/buger/jsonparser 1.1.2 to fix GHSA-6g7g-w4f8-9c9x (dependabot[bot])
  • doc fixes
    • Added text to the label showing version-introduced info (Jan-Philipp Reßler)
    • Clarify Filen password change requires updating both password and API key in rclone config (Jason)
    • s3: clarify multi tenant support for Cubbit (Marco Ferretti)
    • jottacloud: Fix broken link (albertony)
  • lib/rest: Fix URLPathEscapeAll breaking WebDAV servers (eg nzbdav) with strict path matching (Andrew Furman)
  • list: Fix nil pointer panic in Sorter when temp file creation fails (Nick Craig-Wood) 😭

---

🦋 v1.73.2 - 2026-03-06 🦋

See commits — https://github.com/rclone/rclone/compare/v1.73.1...v1.73.2

• Bug Fixes
  • build
    • Update to go 1.25.8 to fix CVE-2026-27137 CVE-2026-27138 CVE-2026-25679 CVE-2026-27142 (Nick Craig-Wood)
    • Update github.com/cloudflare/circl to v1.6.3 to fix CVE-2026-1229 (Nick Craig-Wood)
    • Update to golang.org/x/net v0.51.0 to fix CVE-2026-27141 (Nick Craig-Wood)
  • docs fixes:
    • bisync: Add group Sync to the bisync command (Jan-Philipp Reßler)
    • Note that --use-server-modtime only works on some backends (Nick Craig-Wood)
    • Document unsupported S3 object keys with double slashes (Adam Kasztenny)
    • Fix headers hierarchy for mount.md (Dark Dragon)
    • Fix new drive flag typo in changelog (razorloves)
• Archive
  • Extract: fix extraction with "./" prefix from tar entry paths (Varun Chawla)
• Drime
  • Fix chunk-uploaded files ignoring workspace ID (a1pcm)
• Internxt
  • Fix Entry doesn't belong in directory errors on windows (jzunigax2)
• WebDAV
  • Escape reserved characters in URL path segments (Varun Chawla)
  • Add missing headers for CORS (Romāns Potašovs)

---

🍓 v1.73.1 - 2026-02-17 🍓

See commits — https://github.com/rclone/rclone/compare/v1.73.0...v1.73.1

• Bug Fixes
  • accounting: Fix missing server side stats from core/stats rc (Nick Craig-Wood)
  • build
    • Fix CVE-2025-68121 by updating go to 1.25.7 or later (Nick Craig-Wood)
    • Bump github.com/go-chi/chi/v5 from 5.2.3 to 5.2.5 to fix GO-2026-4316 (albertony)
  • docs: Extend copyurl docs with an example of CSV FILENAMEs starting with a path. (Jack Kelly)
  • march: Fix runtime: program exceeds 10000-thread limit (Nick Craig-Wood)
  • pacer
    • Fix deadlock between pacer token and --max-connections (Nick Craig-Wood)
    • Re-read the sleep time as it may be stale (Nick Craig-Wood)
• Drime
  • Fix files and directories being created in the default workspace (Nick Craig-Wood)
• Filelu
  • Avoid buffering entire file in memory (kingston125)
  • Add multipart upload support with configurable cutoff (kingston125)
• Filen
  • Fix 32 bit targets not being able to list directories (Enduriel)
  • Fix potential panic in case of error during upload (Enduriel)
• Internxt
  • Implement re-login under refresh logic, improve retry logic (José Zúniga) -S3
  • Set list_version to 2 for FileLu S3 configuration (kingston125)

---

👑 v1.73.0 - 2026-01-30 👑

See commits — https://github.com/rclone/rclone/compare/v1.72.0...v1.73.0

• New backends
  • Shade — https://rclone.org/shade/ (jhasse-shade)
  • Drime — https://rclone.org/drime/ (dougal)
  • Filen — https://rclone.org/filen/ (Enduriel)
  • Internxt — https://rclone.org/internxt/ (jzunigax2)
  • New S3 providers
    • Bizfly Cloud Simple Storage — https://rclone.org/s3/#bizflycloud (vupn0712)
• New Features
  • docs: Add Support Tiers — https://rclone.org/tiers/ to the documentation (Nick Craig-Wood)
  • rc: Add operations/hashsumfile — https://rclone.org/rc/#operations-hashsumfile to sum a single file only (Nick Craig-Wood)
  • serve webdav: Implement download directory as Zip (Leo)
• Bug Fixes
  • fs: fix bwlimit: correct reporting (Mikel Olasagasti Uranga)
  • log: fix systemd adding extra newline (dougal)
  • docs: fixes (albertony, darkdragon-001, Duncan Smart, hyusap, Marc-Philip, Nick Craig-Wood, vicerace, vyv03354, yuval-cloudinary, yy)
  • serve s3: Make errors in --s3-auth-key fatal (Nick Craig-Wood)
• Mount
  • Fix OpenBSD mount support. (Nick Owens)
• Azure Blob
  • Add metadata and tags support across upload and copy paths (Cliff Frey)
  • Factor the common auth into a library (Nick Craig-Wood)
• Azurefiles
  • Factor the common auth into a library (Nick Craig-Wood)
• B2
  • Support authentication with new bucket restricted application keys (DianaNites)
• Drive
  • Add --drive-metadata-enforce-expansive-access flag (Nick Craig-Wood)
  • Fix crash when trying to creating shortcut to a Google doc (Nick Craig-Wood)
• FTP
  • Add http proxy authentication support (Nicolas Dessart)
• Mega
  • Reverts TLS workaround (necaran)
• Memory
  • Add --memory-discard flag for speed testing (Nick Craig-Wood)
• OneDrive
  • Fix cancelling multipart upload (Nick Craig-Wood)
  • Fix setting modification time on directories for OneDrive Personal (Nick Craig-Wood)
  • Fix OneDrive Personal no longer supports description (Nick Craig-Wood)
  • Fix require sign in for OneDrive Personal (Nick Craig-Wood)
  • Fix permissions on OneDrive Personal (Nick Craig-Wood)
• Oracle Object Storage
  • Eliminate unnecessary heap allocation (Qingwei Li)
• Pcloud
  • Add support for ChangeNotify to enable real-time updates in mount (masrlinu)
• Protondrive
  • Update to use forks of upstream modules to unblock development (Nick Craig-Wood)
• S3
  • Add ability to specify an IAM role for cross-account interaction (Vladislav Tropnikov)
  • Linode: updated endpoints to use ISO 3166-1 alpha-2 standard (jbagwell-akamai)
  • Fix Copy ignoring storage class (vupn0712)
• SFTP
  • Add http proxy authentication support (Nicolas Dessart)
  • Eliminate unnecessary heap allocation (Qingwei Li)

---

🧚 v1.72.1 - 2025-12-10 🧚

See commits — https://github.com/rclone/rclone/compare/v1.72.0...v1.72.1

• Bug Fixes
  • build: update to go1.25.5 to fix CVE-2025-61729 — https://pkg.go.dev/vuln/GO-2025-4155
  • doc fixes (Duncan Smart, Nick Craig-Wood)
  • configfile: Fix piped config support (Jonas Tingeborn)
  • log
    • Fix PID not included in JSON log output (Tingsong Xu)
    • Fix backtrace not going to the --log-file (Nick Craig-Wood)
• Google Cloud Storage
  • Improve endpoint parameter docs (Johannes Rothe)
• S3
  • Add missing regions for Selectel provider (Nick Craig-Wood)

---

🌈 v1.72.0 - 2025-11-21 🌈

See commits — https://github.com/rclone/rclone/compare/v1.71.0...v1.72.0

• New backends
• Archive backend to read archives on cloud storage. (Nick Craig-Wood)
• New S3 providers 💅
  • Cubbit Object Storage (https://rclone.org/s3/#Cubbit) (Marco Ferretti)
  • FileLu S5 Object Storage (https://rclone.org/s3/#filelu-s5) (kingston125)
  • Hetzner Object Storage (https://rclone.org/s3/#hetzner) (spiffytech)
  • Intercolo Object Storage (https://rclone.org/s3/#intercolo) (Robin Rolf)
  • Rabata S3-compatible secure cloud storage (https://rclone.org/s3/#Rabata) (dougal)
  • Servercore Object Storage (https://rclone.org/s3/#servercore) (dougal)
  • SpectraLogic (https://rclone.org/s3/#spectralogic) (dougal)
• New commands ✨
  • rclone archive (https://rclone.org/commands/rclone_archive/): the command that makes archive files AND reads them back, like a lil two-for-one (Fawzib Rojas)
  • rclone config string (https://rclone.org/commands/rclone_config_string/): for making connection strings, bestie (Nick Craig-Wood)
  • rclone test speed (https://rclone.org/commands/rclone_test_speed/): a whole new command to test how fast a specified remote actually is (dougal)
• New Features 🌈
  • backends: a whole bunch of backends got a paged listing (ListP) interface added
    • this is giving progress bars while listing huge directories AND lower memory usage, we love to see it 🫶
  • build
    • Bump golang.org/x/crypto from 0.43.0 to 0.45.0 to fix CVE-2025-58181 (dependabot[bot])
    • Modernize code and tests (Nick Craig-Wood, russcoss, juejinyuxitu, reddaisyy, dulanting, Oleksandr Redko)
    • Update all dependencies (Nick Craig-Wood)
    • Enable support for aix/ppc64 (Lakshmi-Surekha)
  • check: Improved reporting of differences in sizes and contents (albertony)
  • copyurl: Added --url to read URLs from a CSV file (S-Pegg1, dougal)
  • docs:
    • markdown linting (albertony)
    • fixes (albertony, Andrew Gunnerson, anon-pradip, Claudius Ellsel, dougal, iTrooz, Jean-Christophe Cura, Joseph Brownlee, kapitainsky, Matt LaPaglia, n4n5, Nick Craig-Wood, nielash, SublimePeace, Ted Robertson, vastonus)
  • fs: remove unnecessary Seek call on log file (Aneesh Agrawal)
  • hashsum: Improved output format when listing algorithms (albertony)
  • lib/http: Cleanup indentation and other whitespace in the http serve template (albertony)
  • lsf: Add support for unix and unixnano time formats (Motte)
  • oauthutil: Improved debug logs from token refresh (albertony)
  • rc
    • Add job/batch (https://rclone.org/rc/#job-batch) for sending batches of rc commands to run concurrently (Nick Craig-Wood)
    • Add runningIds and finishedIds to job/list (https://rclone.org/rc/#job-list) (n4n5)
    • Add osVersion, osKernel and osArch to core/version (https://rclone.org/rc/#core-version) (Nick Craig-Wood)
    • Make sure fatal errors run via the rc don't crash rclone (Nick Craig-Wood)
    • Add executeId to job statuses in job/list (https://rclone.org/rc/#job-list) (Nikolay Kiryanov)
    • config/unlock: rename parameter to configPassword, accept old as well (Nick Craig-Wood)
  • serve http: Download folders as zip (dougal)
• Bug Fixes 🐛
  • build
    • Fix tls: failed to verify certificate: x509: negative serial number (Nick Craig-Wood)
  • march
    • Fix --no-traverse being very slow (Nick Craig-Wood)
  • serve s3: Fix log output to remove the EXTRA messages (iTrooz)
• Mount
  • Windows: improve error message on missing WinFSP (divinity76)
• Local
  • Add --skip-specials to ignore special files (Adam Dinwoodie)
• Azure Blob
  • Add ListP interface (dougal)
• Azurefiles
  • Add ListP interface (Nick Craig-Wood)
• B2
  • Add ListP interface (dougal)
  • Add Server-Side encryption support (fries1234)
  • Fix "expected a FileSseMode but found: ''" (dougal)
  • Allow individual old versions to be deleted with --b2-versions (dougal)
• Box
  • Add ListP interface (Nick Craig-Wood)
  • Allow configuration with config file contents (Dominik Sander)
• Compress
  • Add zstd compression (Alex)
• Drive
  • Add ListP interface (Nick Craig-Wood)
• Dropbox
  • Add ListP interface (Nick Craig-Wood)
  • Fix error moving just created objects (Nick Craig-Wood)
• FTP
  • Fix SOCKS proxy support (dougal)
  • Fix transfers from servers that return 250 ok messages (jijamik)
• Google Cloud Storage
  • Add ListP interface (dougal)
  • Fix --gcs-storage-class to work with server side copy for objects (Riaz Arbi)
• HTTP
  • Add basic metadata and provide it via serve (Oleg Kunitsyn)
• Jottacloud
  • Add support for Let's Go Cloud (from MediaMarkt) as a whitelabel service (albertony)
  • Add support for MediaMarkt Cloud as a whitelabel service (albertony)
  • Added support for traditional oauth authentication also for the main service (albertony)
  • Abort attempts to run unsupported rclone authorize command (albertony)
  • Improved token refresh handling (albertony)
  • Fix legacy authentication (albertony)
  • Fix authentication for whitelabel services from Elkjøp subsidiaries (albertony)
• Mega
  • Implement 2FA login (iTrooz)
• Memory
  • Add ListP interface (dougal)
• Onedrive
  • Add ListP interface (Nick Craig-Wood)
• Oracle Object Storage
  • Add ListP interface (dougal)
• Pcloud
  • Add ListP interface (Nick Craig-Wood)
• Proton Drive
  • Automated 2FA login with OTP secret key (Microscotch)
• S3
  • Make it easier to add new S3 providers (dougal)
  • Add --s3-use-data-integrity-protections quirk to fix BadDigest error in Alibaba, Tencent (hunshcn)
  • Add support for --upload-header, If-Match and If-None-Match (Sean Turner)
  • Fix single file copying behavior with low permission (hunshcn)
• SFTP
  • Fix zombie SSH processes with --sftp-ssh (Copilot)
• Smb
  • Optimize smb mount performance by avoiding stat checks during initialization (Sudipto Baral)
• Swift
  • Add ListP interface (dougal)
  • If storage_policy isn't set, use the root containers policy (Andrew Ruthven)
  • Report disk usage in segment containers (Andrew Ruthven)
• Ulozto
  • Implement the About functionality (Lukas Krejci)
  • Fix downloads returning HTML error page (aliaj1)
• WebDAV
  • Optimize bearer token fetching with singleflight (hunshcn)
  • Add ListP interface (Nick Craig-Wood)
  • Use SpaceSepList to parse bearer token command (hunshcn)
  • Add Access-Control-Max-Age header for CORS preflight caching (viocha)
  • Fix out of memory with sharepoint-ntlm when uploading large file (Nick Craig-Wood)

---

v1.71.2 - 2025-10-20 🌸

See commits (https://github.com/rclone/rclone/compare/v1.71.1...v1.71.2)

• Bug Fixes
  • build
    • update Go to 1.25.3
    • Update Docker image Alpine version to fix CVE-2025-9230
  • bisync: Fix race when CaptureOutput is used concurrently (Nick Craig-Wood)
  • doc fixes (albertony, dougal, iTrooz, Matt LaPaglia, Nick Craig-Wood)
  • index: Add missing providers (dougal)
  • serve http: Fix: logging URL on start (dougal)
• Azurefiles
  • Fix server side copy not waiting for completion (Vikas Bhansali)
• B2
  • Fix 1TB+ uploads (dougal)
• Google Cloud Storage
  • Add region us-east5 (Dulani Woods)
• Mega
  • Fix 402 payment required errors (Nick Craig-Wood)
• Pikpak
  • Fix unnecessary retries by using URL expire parameter (Youfu Zhang)

---

v1.71.1 - 2025-09-24 ✨

See commits (https://github.com/rclone/rclone/compare/v1.71.0...v1.71.1)

• Bug Fixes
  • bisync: Fix error handling for renamed conflicts (nielash)
  • march: Fix deadlock when using --fast-list on syncs (Nick Craig-Wood)
  • operations: Fix partial name collisions for non --inplace copies (Nick Craig-Wood)
  • pacer: Fix deadlock with --max-connections (Nick Craig-Wood)
  • doc fixes (albertony, anon-pradip, Claudius Ellsel, dougal, Jean-Christophe Cura, Nick Craig-Wood, nielash)
• Mount
  • Do not log successful unmount as an error (Tilman Vogel)
• VFS
  • Fix SIGHUP killing serve instead of flushing directory caches (dougal)
• Local
  • Fix rmdir "Access is denied" on windows (nielash)
• Box
  • Fix about after change in API return (Nick Craig-Wood)
• Combine
  • Propagate SlowHash feature (skbeh)
• Drive
  • Update making your own client ID instructions (Ed Craig-Wood)
• Internet Archive
  • Fix server side copy files with spaces (Nick Craig-Wood)

---

v1.71.0 - 2025-08-22 👑

See commits (https://github.com/rclone/rclone/compare/v1.70.0...v1.71.0)

• New S3 providers 💖
  • Exaba (https://rclone.org/s3/#exaba) (Nick Craig-Wood)
    • We've been working with Exaba and they would love early adopters, self-hosters and testers
  • OVHcloud Object Storage (https://rclone.org/s3/#ovhcloud) (Florent Vennetier)
  • Zata (https://rclone.org/s3/#Zata) ($@M@RTH_)
• New Features
  • Allow global config to be overridden or set on backend creation (https://rclone.org/docs/#globalconfig) (Nick Craig-Wood)
  • bisync: Promoted from beta to stable (nielash)
  • build
    • Update to go1.25 and make go1.24 the minimum required version (Nick Craig-Wood)
    • Update all dependencies (Nick Craig-Wood)
    • Upgrade golangci-lint to v2 and fix code and config (albertony)
    • Add markdown linting to workflow and fix all the docs (albertony)
    • Extend check for edits of autogenerated files to all commits in a pull request (albertony)
    • Set default shell to bash in build.yml (Ross Smith II)
  • config
    • Make parsing of Duration options consistent (albertony)
    • Add error if RCLONE_CONFIG_PASS was supplied it but didn't decrypt the config (n4n5)
  • copy, copyto: Implement logger flags to store result of sync (Marvin Rösch)
  • doc fixes (albertony, Ali Zein Yousuf, Binbin Qian, curlwget, Ed Craig-Wood, jinjingroad, Lucas Bremgartner, n4n5, Nick Craig-Wood)
  • hash: Add support for BLAKE3, XXH3, XXH128 (albertony)
  • `http
• Add --client-pass support for encrypted --client-key files (Nick Craig-Wood)
  • Allow setting of --http-proxy from the command line (Nick Craig-Wood)
• lib/mmap — bestie they converted this to use unsafe.Slice so we can dodge the deprecated reflect.SliceHeader era, iconic behavior (cui) 💅
• lib/transform — Avoid empty charmap entry, no more awkward blank vibes in the charmap (albertony) 🦋
• log — Log rotation options when you're using --log-file (https://rclone.org/docs/#log-file-string) like finally your logs can ✨rotate✨ (Nick Craig-Wood)
• move, moveto — Implemented logger flags to store the result of sync, receipts for your moves basically (Marvin Rösch)
• pool — Unify memory between multipart and asyncreader so they share one pool, sharing is caring fr (Nick Craig-Wood)
• purge — Exit with a fatal error if filters are set on rclone purge, it's giving safety rails bestie, no accidental nuking (Nick Craig-Wood) 😭
• rc
  • Add config/unlock to unlock the config file (n4n5) 🔓
  • Fix config/listremotes to send an empty array instead of nil (n4n5)
  • Populate transfer snapshot with "what" value (Timothy Jacobs)
• serve sftp — Add support for more hashes: crc32, sha256, blake3, xxh3, xxh128, the whole hash roster showed up and ate (albertony) 🔥
• transform — Add truncate_keep_extension and truncate_bytes (nielash)

---

• Bug Fixes 🐛
  • about — Fix potential overflow of about in various backends (Nick Craig-Wood)
  • accounting
    • Fix incorrect stats with --transfers=1 (Yu Xin)
    • Fix stats (speed=0 and eta=nil) when starting jobs via rc (Nick Craig-Wood)
  • bisync
    • Fix concurrent runs via rc (nielash)
    • Fix --no-slow-hash settings on path2 (nielash)
  • config — fixed the problem reading pasted tokens over 4095 bytes, long tokens are safe now (Nick Craig-Wood)
  • oauthutil — Fix nil pointer crash when started with an expired token, no more instant death on stale creds (Nick Craig-Wood) 💀
  • operations — Fix too many connections open when using --max-buffer-memory (Nick Craig-Wood)
  • pool — Fix deadlock with --max-buffer-memory and multipart transfers (Nick Craig-Wood)
  • rc — Fix operations/check ignoring the oneWay parameter (houance)
  • Mount — Fix identification of symlinks in directory listings (huangnauh)
  • Local
    • Configurable supported hashes (albertony)
    • Fix --copy-links on Windows when listing Junction points (Anagh Kumar Baranwal)
  • Azure Blob
    • Add support for client assertion based authentication (Vikas Bhansali)
    • Fix deadlock with --max-connections with InvalidBlockOrBlob errors (Nick Craig-Wood)
    • Fix double accounting for multipart uploads (Nick Craig-Wood)
  • Azurefiles
    • Add support for client assertion based authentication (Vikas Bhansali)
    • Fix hash getting erased when modtime is set (nielash)
  • Box — Fix about: cannot unmarshal number 1.0e+18 into Go struct field, big numbers were simply too much for it (Nick Craig-Wood)
  • Combine — Fix directory not found errors with ListP interface (Nick Craig-Wood)
  • Filescom — Document that hashes need to be enabled, iykyk (Nick Craig-Wood)
  • FTP
    • Allow insecure TLS ciphers (Anagh Kumar Baranwal)
    • Make TLS config default to the global TLS config (Nick Craig-Wood)
      • This allows --ca-cert, --client-cert etc to be used.
      • This also allows override.ca_cert = XXX to be used in the config file.
  • Googlephotos — Added warning for Google Photos compatibility-fixes (raider13209)
  • Imagekit
    • Return correct error when attempting to upload zero length files (Nick Craig-Wood)
    • Don't low level retry uploads (Nick Craig-Wood)
    • Remove server side Copy method as it was downloading and uploading, not very server-side of it ngl (Nick Craig-Wood) 🙈
  • Internetarchive — Fix server side copy of files with & (Nick Craig-Wood)
  • Mega — Fix tls handshake failure (necaran)
  • Oracleobjectstorage — Add read only metadata support (praveen-solanki-oracle)
  • Pikpak
    • Rewrite upload to bypass AWS S3 manager (wiserain)
    • Enhance Move for better handling of error and name collision (wiserain)
    • Enhance Copy method to handle name collisions and improve error management (wiserain)
    • Add file name integrity check during upload (wiserain)
  • S3
    • Add --s3-use-arn-region flag (Nick Craig-Wood)
    • Fix memory leak by cloning strings (liubingrun)
    • Fix multipart upload and server side copy when using bucket policy SSE-C (Albin Parou)
    • Fix Content-Type: aws-chunked causing upload errors with --metadata (Nick Craig-Wood)
  • SFTP — Add support for more hashes: crc32, sha256, blake3, xxh3, xxh128 (albertony)
  • Smb
    • Add --smb-kerberos-ccache option to set kerberos ccache per smb backend (Sudipto Baral)
    • Refresh Kerberos credentials when the ccache file changes (Sudipto Baral)
    • Improve multithreaded upload performance using multiple connections (Sudipto Baral)

---

🎀 v1.70.3 - 2025-07-09 🎀

See commits (https://github.com/rclone/rclone/compare/v1.70.2...v1.70.3)

• Bug Fixes
  • check: Fix difference report (it was reporting error counts, messy) (albertony)
  • march: Fix deadlock when using --no-traverse (Nick Craig-Wood)
  • doc fixes (albertony, Nick Craig-Wood)
• Azure Blob — Fix server side copy error "requires exactly one scope" (Nick Craig-Wood)
• B2 — Fix finding objects when using --b2-version-at (Davide Bizzarri)
• Linkbox — Fix upload error "user upload file not exist" (Nick Craig-Wood)
• Pikpak — Improve error handling for missing links and unrecoverable 500s (wiserain)
• WebDAV — Fix setting modtime to that of local object instead of remote (WeidiDeng)

---

🌸 v1.70.2 - 2025-06-27 🌸

See commits (https://github.com/rclone/rclone/compare/v1.70.1...v1.70.2)

• Bug Fixes
  • convmv: Make --dry-run logs less noisy, volume down bestie (nielash)
  • sync: Avoid copying dir metadata to itself (nielash)
  • build: Bump github.com/go-chi/chi/v5 from 5.2.1 to 5.2.2 to fix GHSA-vrw8-fxc6-2r93 (dependabot[bot]) 🔥
  • convmv: Fix moving to unicode-equivalent name (nielash)
  • log: Fix deadlock when using systemd logging (Nick Craig-Wood)
  • pacer: Fix nil pointer deref in RetryError (Nick Craig-Wood)
  • doc fixes (Ali Zein Yousuf, Nick Craig-Wood)
• Local — Fix --skip-links on Windows when skipping Junction points (Nick Craig-Wood)

---

🦋 v1.70.1 - 2025-06-19 🦋

See commits (https://github.com/rclone/rclone/compare/v1.70.0...v1.70.1)

• Bug Fixes
  • convmv: Fix spurious "error running command echo" on Windows (Nick Craig-Wood)
  • doc fixes (albertony, Ed Craig-Wood, jinjingroad)

---

👑 v1.70.0 - 2025-06-17 👑

See commits (https://github.com/rclone/rclone/compare/v1.69.0...v1.70.0)

• New backends
  • DOI (https://rclone.org/doi/) (Flora Thiebaut)
  • FileLu (https://rclone.org/filelu/) (kingston125)
  • New S3 providers:
    • MEGA S4 (https://rclone.org/s3/#mega) (Nick Craig-Wood)
    • Pure Storage FlashBlade (https://rclone.org/s3/#pure-storage-flashblade) (Jeremy Daer)
• New commands
  • convmv (https://rclone.org/commands/rclone_convmv/): for moving and transforming files (nielash)
• New Features
  • Add --max-connections (https://rclone.org/docs/#max-connections-n) to control maximum backend concurrency (Nick Craig-Wood)
  • Add --max-buffer-memory (https://rclone.org/docs/#max-buffer-memory) to limit total buffer memory usage (Nick Craig-Wood)
  • Add transform library and --name-transform (https://rclone.org/docs/#name-transform-stringarray) flag (nielash)
  • sync: Implement --list-cutoff (https://rclone.org/docs/#list-cutoff) to allow on disk sorting for reduced memory use (Nick Craig-Wood)
  • accounting: Add listed stat for number of directory entries listed (Nick Craig-Wood)
  • backend: Skip hash calculation when the hashType is None (Oleksiy Stashok)
  • build
    • Update to go1.24 and make go1.22 the minimum required version (Nick Craig-Wood)
    • Disable docker builds on PRs & add missing dockerfile changes (Anagh Kumar Baranwal)
    • Modernize Go usage (Nick Craig-Wood)
    • Update all dependencies (Nick Craig-Wood)
  • cmd/authorize: Show required arguments in help text (simwai)
  • cmd/config: add --no-output option (Jess)
  • cmd/gitannex
    • Tweak parsing of "rcloneremotename" config (Dan McArdle)
    • Permit remotes with options (Dan McArdle)
    • Reject unknown layout modes in INITREMOTE (Dan McArdle)
  • docker image: Add label org.opencontainers.image.source for release notes in Renovate dependency updates (Robin Schneider)
  • doc fixes (albertony, Andrew Kreimer, Ben Boeckel, Christoph Berger, Danny Garside, Dimitri Papadopoulos, eccoisle, Ed Craig-Wood, Fernando Fernández, jack, Jeff Geerling, Jugal Kishore, kingston125, luzpaz, Markus Gerstel, Matt Ickstadt, Michael Kebe, Nick Craig-Wood, PrathameshLakawade, Ser-Bul, simonmcnair, Tim White, Zachary Vorhies) 💖
  • filter:
    • Add --hash-filter to deterministically select a subset of files (Nick Craig-Wood)
    • Show --min-size and --max-size in --dump filters (Nick Craig-Wood)
  • hash: Add SHA512 support for file hashes (Enduriel)
  • http servers: Add --user-from-header to use for authentication (Moises Lima)
  • lib/batcher: Deprecate unused option: batch_commit_timeout (Dan McArdle)
  • log:
    • Remove github.com/sirupsen/logrus and replace with log/slog (Nick Craig-Wood)
    • Add --windows-event-log-level to support Windows Event Log (Nick Craig-Wood)
  • rc
    • Add add short parameter to core/stats to not return transferring and checking (Nick Craig-Wood)
    • In options/info make FieldName contain a "." if it should be nested (Nick Craig-Wood)
    • Add rc control for serve commands (Nick Craig-Wood)
    • rcserver: Improve content-type check (Jonathan Giannuzzi)
  • serve nfs
    • Update docs to note Windows is not supported (Zachary Vorhies)
    • Change the format of --nfs-cache-type symlink file handles (Nick Craig-Wood)
    • Make metadata files have special file handles (Nick Craig-Wood)
  • touch: Make touch obey --transfers (Nick Craig-Wood)
  • version: Add --deps flag to show dependencies and other build info (Nick Craig-Wood)
• Bug Fixes
  • serve s3:
    • Fix ListObjectsV2 response (fhuber)
• Remove redundant handler initialization (Tho Neyugn) 💅
• stats: Fix goroutine leak and improve stats accounting process (Nathanael Demacon)
• VFS 🦋
  • Add --vfs-metadata-extension to expose metadata sidecar files (Nick Craig-Wood)
• Azure Blob ✨
  • Add support for x-ms-tags header (Trevor Starick)
  • Cleanup uncommitted blocks on upload errors (Nick Craig-Wood)
  • Speed up server side copies for small files (Nick Craig-Wood)
  • Implement multipart server side copy (Nick Craig-Wood)
  • Remove uncommitted blocks on InvalidBlobOrBlock error (Nick Craig-Wood)
  • Fix handling of objects with // in (Nick Craig-Wood)
  • Handle retry error codes more carefully (Nick Craig-Wood)
  • Fix errors not being retried when doing single part copy (Nick Craig-Wood)
  • Fix multipart server side copies of 0 sized files (Nick Craig-Wood)
• Azurefiles
  • Add --azurefiles-use-az and --azurefiles-disable-instance-discovery (b-wimmer)
• B2
  • Add SkipDestructive handling to backend commands (Pat Patterson)
  • Use file id from listing when not presented in headers (ahxxm)
• Cloudinary 🌸
  • Automatically add/remove known media files extensions (yuval-cloudinary)
  • Var naming convention (yuval-cloudinary)
• Drive
  • Added backend moveid command (Spencer McCullough)
• Dropbox
  • Support Dropbox Paper (Dave Vasilevsky)
• FTP
  • Add --ftp-http-proxy to connect via HTTP CONNECT proxy
• Gofile
  • Update to use new direct upload endpoint (wbulot)
• Googlephotos
  • Update read only and read write scopes to meet Google's requirements. (Germán Casares)
• Iclouddrive
  • Fix panic and files potentially downloaded twice (Clément Wehrung)
• Internetarchive
  • Add --internetarchive-metadata="key=value" for setting item metadata (Corentin Barreau)
• Onedrive
  • Fix "The upload session was not found" errors (Nick Craig-Wood)
  • Re-add --onedrive-upload-cutoff flag (Nick Craig-Wood)
  • Fix crash if no metadata was updated (Nick Craig-Wood)
• Opendrive
  • Added --opendrive-access flag to handle permissions (Joel K Biju)
• Pcloud
  • Fix "Access denied. You do not have permissions to perform this operation" on large uploads (Nick Craig-Wood)
• S3 🔥
  • Fix handling of objects with // in (Nick Craig-Wood)
  • Add IBM IAM signer (Alexander Minbaev)
  • Split the GCS quirks into --s3-use-x-id and --s3-sign-accept-encoding (Nick Craig-Wood)
  • Implement paged listing interface ListP (Nick Craig-Wood)
  • Add Pure Storage FlashBlade provider support (Jeremy Daer)
  • Require custom endpoint for Lyve Cloud v2 support (PrathameshLakawade)
  • MEGA S4 support (Nick Craig-Wood)
• SFTP
  • Add --sftp-http-proxy to connect via HTTP CONNECT proxy (Nick Craig-Wood)
• Smb
  • Add support for kerberos authentication (Jonathan Giannuzzi)
  • Improve connection pooling efficiency (Jonathan Giannuzzi)
• WebDAV
  • Retry propfind on 425 status (Jörn Friedrich Dreyer)
  • Add an ownCloud Infinite Scale vendor that enables tus chunked upload support (Klaas Freitag)

v1.69.3 - 2025-05-21

See commits: https://github.com/rclone/rclone/compare/v1.69.2...v1.69.3

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])
• build: Update github.com/ebitengine/purego to work around bug in go1.24.3 (Nick Craig-Wood)

---

v1.69.2 - 2025-05-01

See commits: https://github.com/rclone/rclone/compare/v1.69.1...v1.69.2

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: https://github.com/rclone/rclone/compare/v1.69.0...v1.69.1

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)
• fs: Fix confusing "didn't find section in config file" error (Nick Craig-Wood)
• doc fixes (Christoph Berger, Dimitri Papadopoulos, Matt Ickstadt, Nick Craig-Wood, Tim White, Zachary Vorhies)
• build: Added parallel docker builds and caching for go build in the container (Anagh Kumar Baranwal)
• VFS
  • Fix the cache failing to upload symlinks when --links was specified (Nick Craig-Wood)
  • Fix race detected by race detector (Nick Craig-Wood)
  • Close the change notify channel on Shutdown (izouxv)
• B2
  • Fix "fatal error: concurrent map writes" (Nick Craig-Wood)
• Iclouddrive
  • Add notes on ADP and Missing PCS cookies (Nick Craig-Wood)
• Onedrive
  • Mark German (de) region as deprecated (Nick Craig-Wood)
• S3
  • Added new storage class to magalu provider (Bruno Fernandes)
  • Add DigitalOcean regions SFO2, LON1, TOR1, BLR1 (jkpe)
  • Add latest Linode Object Storage endpoints (jbagwell-akamai)

---

v1.69.0 - 2025-01-12

See commits: https://github.com/rclone/rclone/compare/v1.68.0...v1.69.0

New backends

• ICloud Drive (https://rclone.org/iclouddrive/) (lostb1t)
• Cloudinary (https://rclone.org/cloudinary/) (yuval-cloudinary)
• New S3 providers:
  • Outscale (https://rclone.org/s3/#outscale) (Matthias Gatto)
  • Selectel (https://rclone.org/s3/#selectel) (Nick Craig-Wood)

Security fixes

bestie this part is serious, ok? read it twice.

• serve sftp: Resolve CVE-2024-45337 - Misuse of ServerConfig.PublicKeyCallback may cause authorization bypass (dependabot)
  • Rclone was not vulnerable to this.
  • See https://github.com/advisories/GHSA-v778-237x-gjrc
• build: 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.
  • See https://github.com/advisories/GHSA-w32m-9786-jp63

New Features

• accounting: Write the current bwlimit to the log on SIGUSR2 (Nick Craig-Wood)
• bisync: Change exit code from 2 to 7 for critically aborted run (albertony)
• build
  • Update all dependencies (Nick Craig-Wood)
  • Replace Windows-specific NewLazyDLL with NewLazySystemDLL (albertony)
• cmd: Change exit code from 1 to 2 for syntax and usage errors (albertony)
• docker serve: make sure all mount and VFS options are parsed (Nick Craig-Wood)
• doc fixes (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)
• fs: Make --links flag global and add new --local-links and --vfs-links flags (Nick Craig-Wood)
• http servers: Disable automatic authentication skipping for unix sockets in http servers (Moises Lima)
  • This was making it impossible to use unix sockets with an proxy
  • This might now cause rclone to need authentication where it didn't before
• oauthutil: add support for OAuth client credential flow (Martin Hassack, Nick Craig-Wood)
• operations: make log messages consistent for mkdir/rmdir at INFO level (Nick Craig-Wood)
• rc: Add relative to vfs/queue-set-expiry (https://rclone.org/rc/#vfs-queue-set-expiry) (Nick Craig-Wood)
• serve dlna: Sort the directory entries by directories first then alphabetically by name (Nick Craig-Wood)
• serve nfs
  • Introduce symlink support (Nick Craig-Wood)
  • Implement --nfs-cache-type symlink (Nick Craig-Wood)
• size: Make output compatible with -P (Nick Craig-Wood) 👑
• test makefiles — Add --flat flag for making directories with many entries (Nick Craig-Wood)

💖 Bug Fixes 💖

• accounting
  • Fix global error acounting (Benjamin Legrand) — bestie the typo stays, it's part of history now 🫶
  • Fix debug printing when debug wasn't set (Nick Craig-Wood)
  • Fix race stopping/starting the stats counter (Nick Craig-Wood)
• rc/job — Use mutex for adding listeners thread safety (hayden.pan)
• serve docker — Fix incorrect GID assignment (TAKEI Yuya)
• serve nfs — Fix missing inode numbers which was messing up ls -laR (Nick Craig-Wood)
• serve s3 — Fix Last-Modified timestamp (Nick Craig-Wood)
• serve sftp — Fix loading of authorized keys file with comment on last line (albertony)

🧚 Mount 🧚

• Introduce symlink support (Filipe Azevedo, Nick Craig-Wood) — iconic behaviour fr
• Better snap mount error message (divinity76)
• mount2 — Fix missing . and .. entries (Filipe Azevedo)

🦋 VFS 🦋

• With --vfs-used-is-size value is calculated and then thrown away (Ilias Ozgur Can Leonard) — the way that it does work and then ✨nothing✨
• 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) — no more ghosting, we don't do that here 💅
• Add remote name to vfs cache log messages (Nick Craig-Wood)

🍓 Cache 🍓

• Fix parent not getting pinned when remote is a file (nielash)

💜 Azure Blob 💜

• 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)

🔥 Azurefiles 🔥

• Fix missing x-ms-file-request-intent header (Nick Craig-Wood)

⭐ B2 ⭐

• Add daysFromStartingToCancelingUnfinishedLargeFiles to backend lifecycle command (Louis Laureys)

🎀 Box 🎀

• Fix server-side copying a file over existing dst (nielash)
• Fix panic when decoding corrupted PEM from JWT file (Nick Craig-Wood)

👑 Drive 👑

• Add support for markdown format (Noam Ross)
• Implement rclone backend rescue to rescue orphaned files (Nick Craig-Wood)

🌸 Dropbox 🌸

• Fix server side copying over existing object (Nick Craig-Wood)
• Fix return status when full to be fatal error (Nick Craig-Wood)

💅 FTP 💅

• 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)

🫶 Gofile 🫶

• Fix server side copying over existing object (Nick Craig-Wood)

🌈 Google Cloud Storage 🌈

• Add access token auth with --gcs-access-token (Leandro Piccilli)
• Update docs on service account access tokens (Anthony Metzidis)

😭 Googlephotos 😭

• Implement --gphotos-proxy to allow download of full resolution media (Nick Craig-Wood)
• Fix nil pointer crash on upload (Nick Craig-Wood)

💀 HTTP 💀

• Fix incorrect URLs with initial slash (Oleg Kunitsyn)

🦋 Onedrive 🦋

• 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)

🍓 Opendrive 🍓

• Add rclone about support to backend (quiescens)

✨ Oracle Object Storage ✨

• Make specifying compartmentid optional (Manoj Ghosh)
• Quit multipart uploads if the context is cancelled (Nick Craig-Wood)

💜 Pikpak 💜

• Add option to use original file links (wiserain)

🧚 Protondrive 🧚

• Improve performance of Proton Drive backend (Lawrence Murray)

⭐ Putio ⭐

• Fix server side copying over existing object (Nick Craig-Wood)

🔥 S3 🔥

• 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)

🌸 SFTP 🌸

• Allow inline ssh public certificate for sftp (Dimitar Ivanov)
• Fix nil check when using auth proxy (Nick Craig-Wood)

🎀 Smb 🎀

• Add initial support for Kerberos authentication (more work needed). (Francesco Frassinelli)
• Fix panic if stat fails (Nick Craig-Wood)

👑 Sugarsync 👑

• Fix server side copying over existing object (Nick Craig-Wood)

🙈 WebDAV 🙈

• 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)

🌈 Yandex 🌈

• Fix server side copying over existing object (Nick Craig-Wood)

💖 Zoho 💖

• 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: https://github.com/rclone/rclone/compare/v1.68.1...v1.68.2

💅 Security fixes 💅

• local backend — 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
  • See https://github.com/rclone/rclone/security/advisories/GHSA-hrxh-9w67-g4cv
• build — 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

Okay so when a changelog says "Security fixes", we read. No skimming, bestie. 🚨

🫶 Bug Fixes 🫶

• accounting — Fix wrong message on SIGUSR2 to enable/disable bwlimit (Nick Craig-Wood)
• bisync — Fix output capture restoring the wrong output for logrus (Dimitrios Slamaris)
• dlna — Fix loggingResponseWriter disregarding log level (Simon Bos)
• serve s3 — Fix excess locking which was making serve s3 single threaded (Nick Craig-Wood)
• doc fixes (Nick Craig-Wood, tgfisher, Alexandre Hamez, Randy Bush)

🦋 Local 🦋

• Fix permission and ownership on symlinks with --links and --metadata (Nick Craig-Wood)
• Fix --copy-links on macOS when cloning (nielash)

🌸 Onedrive 🌸

• Fix Retry-After handling to look at 503 errors also (Nick Craig-Wood)

💜 Pikpak 💜

• Fix cid/gcid calculations for fs.OverrideRemote (wiserain)
• Fix fatal crash on startup with token that can't be refreshed (Nick Craig-Wood)

🔥 S3 🔥

• Fix crash when using --s3-download-url after migration to SDKv2 (Nick Craig-Wood)
• Storj provider: fix server-side copy of files bigger than 5GB (Kaloyan Raev)
• Fix multitenant multipart uploads with CEPH (Nick Craig-Wood)

---

🎀 v1.68.1 - 2024-09-24 🎀

See commits: https://github.com/rclone/rclone/compare/v1.68.0...v1.68.1

✨ Bug Fixes ✨

• build — Fix docker release build (ttionya)
• doc fixes (Nick Craig-Wood, Pawel Palucha)
• fs
  • Fix --dump filters not always appearing (Nick Craig-Wood)
  • Fix setting stringArray config values from environment variables (Nick Craig-Wood)
• rc — Fix default value of --metrics-addr (Nick Craig-Wood)
• serve docker — Add missing vfs-read-chunk-streams option in docker volume driver (Divyam)

🧚 Onedrive 🧚

• Fix spurious "Couldn't decode error response: EOF" DEBUG (Nick Craig-Wood)

💖 Pikpak 💖

• Fix login issue where token retrieval fails (wiserain)

⭐ S3 ⭐

• Fix rclone ignoring static credentials when env_auth=true (Nick Craig-Wood)

---

💜 v1.68.0 - 2024-09-08 💜

See commits: https://github.com/rclone/rclone/compare/v1.67.0...v1.68.0

🌈 New backends 🌈

• Files.com (Sam Harrison)
• Gofile (https://rclone.org/gofile/) (Nick Craig-Wood)
• Pixeldrain (https://rclone.org/pixeldrain/) (Fornax)

🦋 Changed backends 🦋

• S3 (https://rclone.org/s3/) backend updated to use AWS SDKv2 (https://github.com/aws/aws-sdk-go-v2) as v1 is now unsupported.
  • The matrix of providers and auth methods is huge and there could be problems with obscure combinations.
  • Please report problems in a new issue (https://github.com/rclone/rclone/issues/new/choose) on Github.

👑 New commands 👑

• config encryption (https://rclone.org/commands/rclone_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 (https://github.com/golang/go/issues/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 (https://rclone.org/rc/#options-info) call to enumerate options (Nick Craig-Wood) 👑
  • Add option blocks parameter to options/get (https://rclone.org/rc/#options-get) and options/info (Nick Craig-Wood)
  • Add vfs/queue (https://rclone.org/rc/#vfs-queue) to show the status of the upload queue (Nick Craig-Wood)
  • Add vfs/queue-set-expiry (https://rclone.org/rc/#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 (https://rclone.org/docs/#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 (https://rclone.org/commands/rclone_mount/#vfs-read-chunk-streams-0-1) 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 (https://github.com/rclone/rclone/compare/v1.66.0...v1.67.0)

• New backends 🦋
  • uloz.to (https://rclone.org/ulozto/) (iotmaestro)
  • New S3 providers
    • Magalu Object Storage (https://rclone.org/s3/#magalu) (Bruno Fernandes)
• New commands ✨
  • gitannex (https://rclone.org/commands/rclone_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 (Nick Craig-Wood)
    • Fix incorrect modtime on some multipart transfers (Nick Craig-Wood)
    • Fix hashing problem in integration tests (Nick Craig-Wood)
  • rc
    • Fix stats groups being ignored in operations/check (Nick Craig-Wood)
    • Fix incorrect Content-Type in HTTP API (Kyle Reynolds)
  • serve s3
    • Fix Last-Modified header format (Butanediol)
    • Fix in-memory metadata storing wrong modtime (nielash)
    • Fix XML of error message (Nick Craig-Wood)
  • serve webdav — Fix webdav with --baseurl under Windows (Nick Craig-Wood)
  • serve dlna — Make BrowseMetadata more compliant (albertony)
  • serve http — Added Content-Length header when HTML directory is served (Sunny)
  • sync
    • Don't sync directories if they haven't been modified (Nick Craig-Wood)
    • Don't test reading metadata if we can't write it (Nick Craig-Wood)
    • Fix case normalisation (problem on on s3) (Nick Craig-Wood)
    • Fix management of empty directories to make it more accurate (Nick Craig-Wood)
    • Fix creation of empty directories when --create-empty-src-dirs=false (Nick Craig-Wood)
    • Fix directory modification times not being set (Nick Craig-Wood)
    • Fix "failed to update directory timestamp or metadata: directory not found" (Nick Craig-Wood)
    • Fix expecting SFTP to have MkdirMetadata method: optional feature not implemented (Nick Craig-Wood)
  • test info — Improve cleanup of temp files (Kyle Reynolds)
  • touch — Fix using -R on certain backends (Nick Craig-Wood)
• Mount 🫶
  • Add --direct-io flag to force uncached access (Nick Craig-Wood)
• VFS
  • Fix download loop when file size shrunk (Nick Craig-Wood)
  • Fix renaming a directory (nielash)
• Local
  • Add --local-time-type to use mtime/atime/btime/ctime as the time (Nick Craig-Wood)
  • Allow SeBackupPrivilege and/or SeRestorePrivilege to work on Windows (Charles Hamilton)
• Azure Blob
  • Fix encoding issue with dir path comparison (nielash)
• B2
  • Add new cleanup (https://rclone.org/b2/#cleanup) and cleanup-hidden backend commands. (Pat Patterson)
  • Update B2 URLs to new home (Nick Craig-Wood)
• Chunker
  • Fix startup when root points to composite multi-chunk file without metadata (nielash)
  • Fix case-insensitive comparison on local without metadata (nielash)
  • Fix "finalizer already set" error (nielash)
• Drive
• Add backend query (https://rclone.org/drive/#query) command for general purpose querying of files (John-Paul Smith) 🔎
  • Stop sending notification emails when setting permissions (Nick Craig-Wood) 📭
  • Fix server side copy with metadata from my drive to shared drive (Nick Craig-Wood)
  • Set all metadata permissions and return error summary instead of stopping on the first error (Nick Craig-Wood)
  • Make errors setting permissions into no retry errors (Nick Craig-Wood)
  • Fix description being overwritten on server side moves (Nick Craig-Wood)
  • Allow setting metadata to fail if failok flag is set (Nick Craig-Wood)
  • Fix panic when using --metadata-mapper on large google doc files (Nick Craig-Wood) 😱
• Dropbox
  • Add --dropbox-root-namespace to override the root namespace (Bill Fraser)
• Google Cloud Storage
  • Fix encoding issue with dir path comparison (nielash)
• Hdfs
  • Fix f.String() not including subpath (nielash)
• Http
  • Add --http-no-escape to not escape URL metacharacters in path names (Kyle Reynolds)
• Jottacloud
  • Set metadata on server side copy and move (albertony)
• Linkbox
  • Fix working with names longer than 8-25 Unicode chars. (Vitaly)
  • Fix list paging and optimized synchronization. (gvitali)
• Mailru
  • Attempt to fix throttling by increasing min sleep to 100ms (Nick Craig-Wood)
• Memory
  • Fix dst mutating src after server-side copy (nielash)
  • Fix deadlock in operations.Purge (nielash)
  • Fix incorrect list entries when rooted at subdirectory (nielash)
• Onedrive
  • Add --onedrive-hard-delete to permanently delete files (Nick Craig-Wood) 💀
  • Make server-side copy work in more scenarios (YukiUnHappy)
  • Fix "unauthenticated: Unauthenticated" errors when downloading (Nick Craig-Wood)
  • Fix --metadata-mapper being called twice if writing permissions (nielash)
  • Set all metadata permissions and return error summary instead of stopping on the first error (nielash)
  • Make errors setting permissions into no retry errors (Nick Craig-Wood)
  • Skip writing permissions with 'owner' role (nielash)
  • Fix references to deprecated permissions properties (nielash)
  • Add support for group permissions (nielash)
  • Allow setting permissions to fail if failok flag is set (Nick Craig-Wood)
• Pikpak
  • Make getFile() usage more efficient to avoid the download limit (wiserain)
  • Improve upload reliability and resolve potential file conflicts (wiserain)
  • Implement configurable chunk size for multipart upload (wiserain)
• Protondrive
  • Don't auth with an empty access token (Michał Dzienisiewicz)
• Qingstor
  • Disable integration tests as test account suspended (Nick Craig-Wood)
• Quatrix
  • Fix f.String() not including subpath (nielash)
• S3
  • Add new AWS region il-central-1 Tel Aviv (yoelvini)
  • Update Scaleway's configuration options (Alexandre Lavigne)
  • Ceph: fix quirks when creating buckets to fix trying to create an existing bucket (Thomas Schneider)
  • Fix encoding issue with dir path comparison (nielash)
  • Fix 405 error on HEAD for delete marker with versionId (nielash)
  • Validate --s3-copy-cutoff size before copy (hoyho)
• SFTP
  • Add --sftp-connections to limit the maximum number of connections (Tomasz Melcer)
• Storj
  • Update storj.io/uplink to latest release (JT Olio)
  • Update bio on request (Nick Craig-Wood)
• Swift
  • Implement --swift-use-segments-container to allow >5G files on Blomp (Nick Craig-Wood)
• Union
  • Fix deleting dirs when all remotes can't have empty dirs (Nick Craig-Wood)
• WebDAV
  • Fix setting modification times erasing checksums on owncloud and nextcloud (nielash)
  • owncloud: Add --webdav-owncloud-exclude-mounts which allows excluding mounted folders when listing remote resources (Thomas Müller)
• Zoho
  • Fix throttling problem when uploading files (Nick Craig-Wood)
  • Use cursor listing for improved performance (Nick Craig-Wood)
  • Retry reading info after upload if size wasn't returned (Nick Craig-Wood)
  • Remove simple file names complication which is no longer needed (Nick Craig-Wood)
  • Sleep for 60 seconds if rate limit error received (Nick Craig-Wood)

---

🦋 v1.66.0 - 2024-03-10 🦋

See commits (https://github.com/rclone/rclone/compare/v1.65.0...v1.66.0)

✨ Major features ✨

• Rclone will now sync directory modification times if the backend supports it.
  • This can be disabled with --no-update-dir-modtime (https://rclone.org/docs/#no-update-dir-modtime)
  • See the overview (https://rclone.org/overview/#features) and look for the D flags in the ModTime column to see which backends support it. 👀
• Rclone will now sync directory metadata if the backend supports it when -M/--metadata is in use.
  • See the overview (https://rclone.org/overview/#features) and look for the D flags in the Metadata column to see which backends support it.
• Bisync has received many updates see below for more details or bisync's changelog (https://rclone.org/bisync/#changelog) 🎀

🗑️ Removed backends 🗑

• amazonclouddrive: Remove Amazon Drive backend code and docs (Nick Craig-Wood)

🌟 New Features 🌟

• backend
  • Add description field for all backends (Paul Stern)
• build
  • Update to go1.22 and make go1.20 the minimum required version (Nick Craig-Wood)
  • Fix CVE-2024-24786 by upgrading google.golang.org/protobuf (Nick Craig-Wood)
• check: Respect --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: Add more detailed logging for file includes/excludes (Kyle Reynolds)
• lsf
  • Add --time-format flag (nielash)
  • Make metadata appear for directories (Nick Craig-Wood)
• lsjson: Make metadata appear for directories (Nick Craig-Wood)
• rc
  • Add srcFs and dstFs to core/stats and core/transferred stats (Nick Craig-Wood)
  • Add operations/hashsum to the rc as rclone hashsum equivalent (Nick Craig-Wood)
  • Add config/paths to the rc as rclone config paths equivalent (Nick Craig-Wood)
• sync
  • Optionally report list of synced paths to file (nielash)
  • Implement directory sync for mod times and metadata (Nick Craig-Wood)
  • Don't set directory modtimes if already set (nielash)
  • Don't sync directory modtimes from backends which don't have directories (Nick Craig-Wood)

🐛 Bug Fixes 🐛

• backend
  • Make backends which use oauth implement the Shutdown and shutdown the oauth properly (rkonfj)
• bisync
  • Handle unicode and case normalization consistently (nielash)
  • Partial uploads known issue on local/ftp/sftp has been resolved (unless using --inplace) (nielash)
  • Fixed handling of unicode normalization and case insensitivity, support for --fix-case (https://rclone.org/docs/#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
  • Fix exit after external unmount (nielash)
  • Fix --volname being ignored (nielash)
• operations
  • Fix renaming a file on macOS (nielash)
  • Fix case-insensitive moves in operations.Move (nielash)
  • Fix TestCaseInsensitiveMoveFileDryRun on chunker integration tests (nielash)
  • Fix TestMkdirModTime test (Nick Craig-Wood)
  • Fix TestSetDirModTime for backends with SetDirModTime but not Metadata (Nick Craig-Wood)
  • Fix typo in log messages (nielash)
• serve nfs: Fix writing files via Finder on macOS (nielash)
• serve restic: Fix error handling (Michael Eischer)
• serve webdav: Fix --baseurl without leading / (Nick Craig-Wood)
• stats: Fix race between ResetCounters and stopAverageLoop called from time.AfterFunc (Nick Craig-Wood)
• sync
  • --fix-case flag to rename case insensitive dest (nielash)
  • Use operations.DirMove instead of sync.MoveDir for --fix-case (nielash)
• systemd: 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 🌸

• 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 (https://rclone.org/docs/#color-autoneveralways) (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, whenever check isn't available. 💅
• Bisync now fully supports comparing based on any combination of size, modtime, and checksum — lifting the prior restriction on backends that don't do modtime. (nielash) 🔥
• Bisync now supports a "Graceful Shutdown" mode so you can cleanly cancel a run early without needing --resync. (nielash) ✨
• New --recover flag gives you robust recovery in the event of interruptions, again without requiring --resync. (nielash) 🫶
• A new --max-lock setting lets lock files automatically renew and expire, which is so much better for automatic recovery when a run gets interrupted. (nielash) 👑
• Bisync now auto-resolves sync conflicts and lets you customize rename behavior with the new --conflict-resolve, --conflict-loser, and --conflict-suffix flags. (nielash) 🎀
• A new --resync-mode flag gives you more control over which version of a file gets kept during a --resync. (nielash) 🦋
• Bisync now supports --retries (https://rclone.org/docs/#retries-int) and --retries-sleep (when --resilient is set). (nielash)
• Clarify file operation directions in dry-run logs (Kyle Reynolds) 🧚
• Local 💖
  • Fix cleanRootPath on Windows after the 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: https://github.com/rclone/rclone/compare/v1.65.1...v1.65.2

• 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 (https://github.com/rclone/rclone/issues/7590) (Nick Craig-Wood)

⚠️ bestie that one is literally marked IMPORTANT for a reason — data corruption is not the vibe. Update, fr fr. 💀

---

v1.65.1 - 2024-01-08 🌸

See commits: https://github.com/rclone/rclone/compare/v1.65.0...v1.65.1

• 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)
• Oracleobjectstorage 🧡
  • Fix object storage endpoint for custom endpoints (Manoj Ghosh)
  • Multipart copy create bucket if it doesn't exist. (Manoj Ghosh)
• Protondrive 🛡️
  • Fix CVE-2023-45286 / GHSA-xwh9-gc39-5298 (Nick Craig-Wood)
• S3 🪣
  • Fix crash if no UploadId in multipart upload (Nick Craig-Wood)
• Smb 🪟
  • Fix shares not listed by updating go-smb2 (halms)
• Union 🤝
  • Fix rclone move a file over itself deleting the file (Nick Craig-Wood)

---

v1.65.0 - 2023-11-26 👑

See commits: https://github.com/rclone/rclone/compare/v1.64.0...v1.65.0

• New backends 🎉
  • Azure Files (karan, moongdal, Nick Craig-Wood)
  • ImageKit (Abhinav Dhiman)
  • Linkbox (viktor, Nick Craig-Wood)
• New commands ⌨️
  • serve s3: Let rclone act as an S3 compatible server (Mikubill, Artur Neumann, Saw-jan, Nick Craig-Wood)
  • 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)
• New Features ✨
  • 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)
  • 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)
• Implement --partial-suffix — it's giving control over the extension of your temporary file names 💅 (Volodymyr)
• rc
  • Add operations/check to the rc API ✨ (Nick Craig-Wood)
  • Always report an error as JSON, no cap (Nick Craig-Wood)
  • Set the Last-Modified header for files served by --rc-serve 🕐 (Nikita Shoshin)
• size — don't show a duplicate object count when it's less than 1k (albertony)

💀 Bug Fixes

• fshttp — fix --contimeout being straight-up ignored 😤 (你知道未来吗)
• march — fix excessive parallelism when you use --no-traverse (Nick Craig-Wood)
• ncdu — fix the crash that happened when re-entering a changed directory after a rescan 😭 (Nick Craig-Wood)
• operations
  • Fix overwrite of destination when a multi-thread transfer fails (Nick Craig-Wood)
  • Fix invalid UTF-8 when truncating file names when you're not using --in-place (Nick Craig-Wood)
• serve dnla — fix crash on graceful exit 🫠 (wuxingzhong)

🗻 Mount

• Disable mount for freebsd, and alias cmount as mount on that platform (Nick Craig-Wood)

🦋 VFS

• Add the --vfs-refresh flag to read all the directories on start ✨ (Beyond Meat)
• Implement the Name() method in WriteFileHandle and ReadFileHandle (Saleh Dindar)
• Add the go-billy dependency and make sure vfs.Handle implements billy.File (Saleh Dindar)
• Error out early if it can't upload a 0 length file (Nick Craig-Wood)

🖥️ Local

• Fix copying from Windows Volume Shadows (Nick Craig-Wood)

🧊 Azure Blob

• Add support for the cold tier (Ivan Yanitra)

☁️ B2

• Implement rclone backend lifecycle to read and set bucket lifecycles (Nick Craig-Wood)
• Implement --b2-lifecycle to control the lifecycle when creating buckets (Nick Craig-Wood)
• Fix listing all buckets when it's not needed (Nick Craig-Wood)
• Fix multi-thread upload with copyto going to the wrong name (Nick Craig-Wood)
• Fix server side chunked copy when the file size was exactly --b2-copy-cutoff (Nick Craig-Wood)
• Fix streaming chunked files that are an exact multiple of the chunk size (Nick Craig-Wood)

📦 Box

• Filter more EventIDs when polling (David Sze)
• Add more logging for polling (David Sze)
• Fix the performance problem when reading metadata for single files (Nick Craig-Wood)

📁 Drive

• 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 a comma-separated list of scopes (Keigo Imai)
• Fix the error updating created time metadata on an existing object (Nick Craig-Wood)
• Fix integration tests by enabling metadata support from the context (Nick Craig-Wood)

💧 Dropbox

• Factor batcher into lib/batcher (Nick Craig-Wood)
• Fix missing encoding for rclone purge (Nick Craig-Wood)

🌩️ Google Cloud Storage

• Fix 400 Bad request errors when using multi-thread copy (Nick Craig-Wood)

📸 Googlephotos

• Implement batcher for uploads (Nick Craig-Wood)

🐘 Hdfs

• Added support for a list of namenodes in the hdfs remote config (TayopasedaRJ)

🌐 HTTP

• Implement set backend command to update a running backend (Nick Craig-Wood)
• Enable methods used with WebDAV (Alen Šiljak)

📝 Jottacloud

• Add support for reading and writing metadata (albertony)

🔷 Onedrive

• Implement the ListR method, which gives --fast-list support (Nick Craig-Wood)
  • This must be enabled with the --onedrive-delta flag ⚠️

🚀 Quatrix

• Add partial upload support (Oksana Zhykina)
• Overwrite files on conflict during server-side move (Oksana Zhykina)

🪣 S3

• Add the 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 the --s3-disable-multipart-uploads flag (Nick Craig-Wood)
• Detect looping when using gcs and versions (Nick Craig-Wood)

🔐 SFTP

• Implement --sftp-copy-is-hardlink to server side copy as a hardlink (Nick Craig-Wood)

🖥️ Smb

• Fix incorrect about size by switching to the github.com/cloudsoda/go-smb2 fork (Nick Craig-Wood)
• Fix the modtime of multithread uploads by setting PartialUploads (Nick Craig-Wood)

🕸️ WebDAV

• Added an rclone vendor to work with rclone serve webdav (Adithya Kumar)

---

🌸 v1.64.2 - 2023-10-19

Go peep the commits bestie 👉 https://github.com/rclone/rclone/compare/v1.64.1...v1.64.2

💀 Bug Fixes

• selfupdate — fix the "invalid hashsum signature" error (Nick Craig-Wood)
• build — fix docker build running out of space 😭 (Nick Craig-Wood)

---

✨ v1.64.1 - 2023-10-17

The receipts, right here 👉 https://github.com/rclone/rclone/compare/v1.64.0...v1.64.1

💀 Bug Fixes

• cmd — make --progress output logs in the same format as without it (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 being ignored in copy if the operation was a multiThreadCopy (Vitor Gomes)
  • Fix the error message on delete to have the file name in it (Nick Craig-Wood)
• serve sftp — return a 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)

🗻 Mount

• Fix automount not detecting the drive is ready (Nick Craig-Wood)

🦋 VFS

• Fix update dir modification time (Saleh Dindar)

🧊 Azure Blob

• Fix "fatal error: concurrent map writes" (Nick Craig-Wood)

☁️ B2

• Fix multipart upload: corrupted on transfer: sizes differ XXX vs 0 (Nick Craig-Wood)
• Fix locking window when getting the 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)

🔷 Onedrive

• Fix the configurator to allow /teams/ID in the config (Nick Craig-Wood)

🗄️ Oracleobjectstorage

• Fix OpenOptions being ignored in uploadMultipart with chunkWriter (Nick Craig-Wood)

🪣 S3

• Fix slice bounds out of range error when listing (Nick Craig-Wood)
• Fix OpenOptions being ignored in uploadMultipart with chunkWriter (Vitor Gomes)

🌌 Storj

• Update storj.io/uplink to v1.12.0 (Kaloyan Raev)

---

💖 v1.64.0 - 2023-09-11

Go look at the diff yourself, iconic behaviour 👉 https://github.com/rclone/rclone/compare/v1.63.0...v1.64.0

🌈 New backends

• Proton Drive (https://rclone.org/protondrive/) (Chun-Hung Tseng)
• Quatrix (https://rclone.org/quatrix/) (Oksana, Volodymyr Kit)
• New S3 providers
  • Synology C2 (https://rclone.org/s3/#synology-c2) (BakaWang)
  • Leviia (https://rclone.org/s3/#leviia) (Benjamin)
• New Jottacloud providers
  • Onlime (https://rclone.org/jottacloud/) (Fjodor42)
  • Telia Sky (https://rclone.org/jottacloud/) (NoLooseEnds)

🔥 Major changes

• Multi-thread transfers 🚀 (Vitor Gomes, Nick Craig-Wood, Manoj Ghosh, Edwin Mackenzie-Owen)
  • 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 the --multi-thread docs (https://rclone.org/docs/#multi-thread-cutoff) for more info

🆕 New commands

• rclone config redacted — support mechanism for showing redacted config (Nick Craig-Wood)

✨ New Features

• accounting
  • Show server side stats in their own lines and not as bytes transferred (Nick Craig-Wood)
• bisync
  • Add the new --ignore-listing-checksum flag to distinguish it 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)
  • Fix the 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)
  • Update dependencies (Nick Craig-Wood)
  • Add snap installation (hideo aoyama)
  • Change the Winget Releaser job to ubuntu-latest (sitiom)
• cmd — refactor and use sysdnotify in more commands (eNV25)
• config — add the --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)
• fs
  • Use atomic types everywhere (Roberto Ricci)
  • When the --max-transfer limit is reached, exit with code (10) (kapitainsky)
  • Add rclone completion powershell — basic implementation only (Nick Craig-Wood)
• http servers — allow CORS to be set with the --allow-origin flag (yuudi)
• lib/rest — remove unnecessary nil check (Eng Zer Jun)
• ncdu — add keybinding to rescan the filesystem (eNV25)
• rc
  • Add executeId to job listings (yuudi)
  • Add core/du to measure local disk usage (Nick Craig-Wood)
  • Add operations/settier to the API (Drew Stinnett)
• rclone test info — add the --check-base32768 flag to check it can store all base32768 characters (Nick Craig-Wood)
• rmdirs — remove directories concurrently, controlled by --checkers (Nick Craig-Wood)

💀 Bug Fixes

• accounting 🧮 — bestie, we're not gonna stop calculating that average transfer speed until the operation is fully complete. patience is a virtue (Jacob Hands)
• fs — fixed transferTime not being set in JSON logs, it was ghosting us (Jacob Hands)
• fshttp — fixed --bind 0.0.0.0 letting IPv6 sneak in and --bind ::0 letting IPv4 sneak in, like no ma'am, stay in your lane (Nick Craig-Wood)
• operations — fixed the overlapping check on case insensitive file systems (Nick Craig-Wood)
• serve dlna — fixed MIME type when the backend can't identify it (Nick Craig-Wood)
• serve ftp — fixed a race condition when using the auth proxy, we do not stan races (Nick Craig-Wood)
• serve sftp — fixed hash calculations with --vfs-cache-mode full (Nick Craig-Wood)
• serve webdav — fixed error: Expecting fs.Object or fs.Directory, got nil 💀 (Nick Craig-Wood)
• sync — fixed the lockup happening with --cutoff-mode=soft and --max-duration (Nick Craig-Wood)

---

🖥️ Mount

• fixed mount parsing for linux, it was giving nothing and now it's giving correct (Anagh Kumar Baranwal)

🗂️ VFS

• added --vfs-cache-min-free-space so you can control the minimum free space on the disk that's holding your cache, lowkey essential (Nick Craig-Wood)
• added a cache cleaner for directories so memory usage goes down, thank you (Anagh Kumar Baranwal)
• parent directory modtimes now get updated on vfs actions (David Pedersen)
• virtual directory status stays accurate and there's less deadlock potential now (Anagh Kumar Baranwal)
• made sure struct field is aligned for atomic access, alignment is the moment (Roberto Ricci)

📁 Local

• Rmdir returns an error if the path is not a dir, no pretending bestie (zjx20)

☁️ Azure Blob

• implemented OpenChunkWriter and multi-thread uploads (Nick Craig-Wood)
• fixed creation of directory markers (Nick Craig-Wood)
• fixed purging with directory markers (Nick Craig-Wood)

🅱️ B2

• implemented OpenChunkWriter and multi-thread uploads (Nick Craig-Wood)
• fixed rclone link when the object path contains special characters (Alishan Ladhani)

📦 Box

• added polling support (David Sze)
• added --box-impersonate so you can impersonate a user ID, we love a shapeshift era (Nick Craig-Wood)
• fixed the unhelpful decoding of error messages into decimal numbers, that was so unserious (Nick Craig-Wood)

🧩 Chunker

• updated the documentation to mention the issue with small files (Ricardo D'O. Albanus)

🗜️ Compress

• fixed ChangeNotify (Nick Craig-Wood)

🚗 Drive

• added --drive-fast-list-bug-fix to control the ListR bug workaround (Nick Craig-Wood)

🥖 Fichier

• implemented DirMove (Nick Craig-Wood)
• fixed error code parsing (alexia)

📡 FTP

• added socks_proxy support for SOCKS5 proxies (Zach)
• fixed 425 "TLS session of data connection not resumed" errors (Nick Craig-Wood)

🐘 Hdfs

• retry "replication in progress" errors when uploading (Nick Craig-Wood)
• fixed uploading to the wrong object on Update with overridden remote name (Nick Craig-Wood)

🌐 HTTP

• CORS should not be sent if it's not set, boundaries babes (yuudi)
• fixed webdav OPTIONS response (yuudi)

🛞 Opendrive

• fixed List on a just-deleted-and-remade directory (Nick Craig-Wood)

🔮 Oracleobjectstorage

• use rclone's rate limiter in multipart transfers (Manoj Ghosh)
• implemented OpenChunkWriter and multi-thread uploads (Manoj Ghosh)

🪣 S3

• refactored multipart upload to use OpenChunkWriter and ChunkWriter (Vitor Gomes)
• factored the generic multipart upload into lib/multipart (Nick Craig-Wood)
• fixed purging of the root directory with --s3-directory-markers (Nick Craig-Wood)
• added the rclone backend set command to update the running config (Nick Craig-Wood)
• added the rclone backend restore-status command (Nick Craig-Wood)

🔐 SFTP

• stop uploads re-using the same ssh connection, it's for performance bestie (Nick Craig-Wood)
• added --sftp-ssh to specify an external ssh binary to use (Nick Craig-Wood)
• added socks_proxy support for SOCKS5 proxies (Zach)
• support dynamic --sftp-path-override (nielash)
• fixed the spurious warning when using --sftp-ssh (Nick Craig-Wood)

🪟 Smb

• implemented multi-threaded writes for copies to smb (Edwin Mackenzie-Owen)

🛰️ Storj

• performance improvement for large file uploads, we love to see it (Kaloyan Raev)

🕊️ Swift

• fixed HEADing 0-length objects when --swift-no-large-objects is set (Julian Lepinski)

🔗 Union

• added :writback to act as a simple cache (Nick Craig-Wood)

🌍 WebDAV

• Nextcloud: fixed segment violation in low-level retry (Paul)

📊 Zoho

• removed the Range requests workarounds to fix the integration tests (Nick Craig-Wood)

---

💖 v1.63.1 - 2023-07-17

See commits (https://github.com/rclone/rclone/compare/v1.63.0...v1.63.1)

🐛 Bug Fixes

• build — fixed macos builds for versions < 12 (Anagh Kumar Baranwal)
• dirtree — fixed performance with large directories of directories and --fast-list (Nick Craig-Wood)
• operations
  • fixed deadlock when using lsd/ls with --progress (Nick Craig-Wood)
  • fixed .rclonelink files not being converted back to symlinks (Nick Craig-Wood)
• doc fixes (Dean Attali, Mahad, Nick Craig-Wood, Sawada Tsunayoshi, Vladislav Vorobev)

📁 Local

• fixed partial directory read for corrupted filesystem (Nick Craig-Wood)

📦 Box

• fixed reconnect failing with HTTP 400 Bad Request (albertony)

🪟 Smb

• fixed "Statfs failed: bucket or container name is needed" when mounting (Nick Craig-Wood)

🌍 WebDAV

• Nextcloud: fixed the must-use /dav/files/USER endpoint not /webdav error (Paul)
• Nextcloud chunking: added more guidance for the user to check the config (darix)

---

🌈 v1.63.0 - 2023-06-30

See commits (https://github.com/rclone/rclone/compare/v1.62.0...v1.63.0)

✨ New backends

• Pikpak (https://rclone.org/pikpak/) (wiserain)
• New S3 providers
  • petabox.io (https://rclone.org/s3/#petabox) (Andrei Smirnov)
  • Google Cloud Storage (https://rclone.org/s3/#google-cloud-storage) (Anthony Pessy)
• New WebDAV providers
  • Fastmail (https://rclone.org/webdav/#fastmail-files) (Arnavion)

💥 Major changes

• 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 (https://rclone.org/docs/#inplace) flag.
  • This behaviour will also happen if the backend is wrapped, for example sftp wrapped with crypt.
• The s3 (https://rclone.org/s3/#s3-directory-markers), azureblob and gcs backends now support directory markers so empty directories are supported (Jānis Bebrītis, Nick Craig-Wood)
• The --default-time (https://rclone.org/docs/#default-time-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 — added --separator option to the 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)
• 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 an 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 with errors on --files-from (douchen)
• fs
  • Fix interaction between --progress and --interactive (Nick Craig-Wood)
  • Fix infinite recursive call in pacer ModifyCalculator (fixes issue reported by the staticcheck linter) (albertony)
• lib/atexit — ensure OnError only calls cancel function once (Nick Craig-Wood)
• lib/rest — fix problems re-using HTTP connections (Nick Craig-Wood)
• rc
  • Fix operations/stat with trailing / (Nick Craig-Wood)
  • Fix missing --rc flags (Nick Craig-Wood)
  • Fix output of Time values in options/get (Nick Craig-Wood)
• serve dlna — fix potential data race (Nick Craig-Wood)
• version — fix reported os/kernel version for windows (albertony)

🖥️ Mount

• Added --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 rclone mount error when installed via homebrew (Nick Craig-Wood)
• Added _netdev to the example mount so it gets treated as a remote-fs and not a local-fs — ty Anagh Kumar Baranwal 💖
• Mount2
  • bumped the go-fuse version up (Anagh Kumar Baranwal)
  • fixed statfs (Anagh Kumar Baranwal)
  • xattrs disabled (Anagh Kumar Baranwal)
• VFS
  • new MkdirAll function that makes a directory and everything underneath it, bestie (Nick Craig-Wood)
  • fixed reload: "failed to add virtual dir entry: file does not exist" (Nick Craig-Wood)
  • writing into a read only directory was spawning spurious directory entries — fixed (WeidiDeng)
  • potential data race handled (Nick Craig-Wood)
  • backends were getting Shutdown way too early when startup takes ages — fixed (Nick Craig-Wood)
• Local
  • filtering of symlinks with the -l/--links flag fixed (Nick Craig-Wood)
  • /path/to/file.rclonelink behaves when -l/--links is in use (Nick Craig-Wood)
  • crash with --metadata on Android? gone (Nick Craig-Wood)
• Cache
  • backends were shutting down while still in use when used via the rc — fixed (Nick Craig-Wood)
• Crypt
  • new --crypt-suffix option so you can set a custom suffix for encrypted files (jladbrook)
  • new --crypt-pass-bad-blocks to allow corrupted file output (Nick Craig-Wood)
  • reading 0 length files fixed (Nick Craig-Wood)
  • tries not to hand you an "unexpected EOF" error anymore (Nick Craig-Wood)
  • less allocations, we love to see it (albertony)
  • Dropbox is now the recommended pick for base32768 encoding (Nick Craig-Wood)
• Azure Blob
  • empty directory markers (Nick Craig-Wood)
  • azure workload identities supported now (Tareq Sharafy)
  • azure blob uploads with multiple bits of metadata fixed (Nick Craig-Wood)
  • azurite compatibility fixed by sending nil tier if it's set to an empty string (Roel Arents)
• Combine
  • missing methods implemented (Nick Craig-Wood)
  • goroutine stack overflow on a bad object fixed (Nick Craig-Wood)
• Drive
  • new --drive-env-auth to grab IAM credentials from runtime (Peter Brunner)
  • drive service account guide updated (Juang, Yi-Lin)
  • change notify was picking up files outside the root — fixed (Nick Craig-Wood)
  • trailing slash was getting folders mis-identified as files — fixed (Nick Craig-Wood)
  • incorrect remote after Update on an object — fixed (Nick Craig-Wood)
• Dropbox
  • the --dropbox-pacer-min-sleep flag is implemented now (Nick Craig-Wood)
  • the dropbox batcher was stalling — fixed (Misty)
• Fichier
  • new --ficicher-cdn option to use the CDN for download (Nick Craig-Wood)
• FTP
  • log message priority lowered to debug when SetModTime isn't supported (Tobias Gion)
  • "unsupported LIST line" errors on startup fixed (Nick Craig-Wood)
  • "501 Not a valid pathname." errors when creating directories fixed (Nick Craig-Wood)
• Google Cloud Storage
  • empty directory markers (Jānis Bebrītis, Nick Craig-Wood)
  • added --gcs-user-project, which requester pays needs (Christopher Merry)
• HTTP
  • added client certificate user auth middleware. This can auth serve restic from the username in the client cert. (Peter Fern)
• Jottacloud
  • vfs writeback was stuck in a failed upload loop with file versioning disabled — fixed (albertony)
• Onedrive
  • new --onedrive-av-override flag to download files flagged as virus (Nick Craig-Wood)
  • quickxorhash fixed on 32 bit architectures (Nick Craig-Wood)
  • any list errors during rclone cleanup get reported now (albertony)
• Putio
  • uploading to the wrong object on Update with an overridden remote name — fixed (Nick Craig-Wood)
  • modification times weren't being preserved for server side copy and move — fixed (Nick Craig-Wood)
  • server side copy failures (400 errors) fixed (Nick Craig-Wood)
• S3
  • empty directory markers (Jānis Bebrītis, Nick Craig-Wood)
  • Scaleway storage classes updated (Brian Starkey)
  • --s3-versions on individual objects fixed (Nick Craig-Wood)
  • hang on aborting multipart upload with iDrive e2 fixed (Nick Craig-Wood)
  • missing "tier" metadata fixed (Nick Craig-Wood)
  • V3sign fixed: added the missing subresource delete (cc)
  • Arvancloud Domain and region changes fixed and the provider alphabetised (Ehsan Tadayon)
  • Qiniu KODO quirks fixed, virtualHostStyle is false (zzq)
• SFTP
  • new --sftp-host-key-algorithms so you can specify SSH host key algorithms (Joel)
  • using --sftp-key-use-agent and --sftp-key-file together no longer needs the private key file (Arnav Singh)
  • move now allows overwriting existing files (Nick Craig-Wood)
  • no more statting directories before listing them (Nick Craig-Wood)
  • won't check whether a remote points to a file if it ends with / (Nick Craig-Wood)
• Sharefile
  • streamed transfers disabled because they just don't work anymore (Nick Craig-Wood)
• Smb
  • code cleanup so ctx doesn't get overwritten before first use (fixes issue reported by the staticcheck linter) (albertony)
• Storj
  • "uplink: too many requests" errors when uploading to the same file — fixed (Nick Craig-Wood)
  • uploading to the wrong object on Update with an overridden remote name — fixed (Nick Craig-Wood)
• Swift
  • 404 error when deleting an object is ignored now (Nick Craig-Wood)
• Union
  • missing methods implemented (Nick Craig-Wood)
  • errors can be unwrapped for inspection (Nick Craig-Wood)
• Uptobox
  • new --uptobox-private flag to make all uploaded files private (Nick Craig-Wood)
  • improper regex fixed (Aaron Gokaslan)
  • Update was returning the wrong object — fixed (Nick Craig-Wood)
  • rmdir was declaring that directories weren't empty — fixed (Nick Craig-Wood)
• WebDAV
  • nextcloud: chunked uploads supported now (Paul)
  • modtime set using propset for owncloud and nextcloud (WeidiDeng)
  • pacer minSleep is configurable with --webdav-pacer-min-sleep (ed)
  • server side copy/move not overwriting — fixed (WeidiDeng)
  • modtime on server side copy for owncloud and nextcloud fixed (Nick Craig-Wood)
• Yandex
  • 400 Bad Request on transfer failure fixed (Nick Craig-Wood)
• Zoho
  • downloads with a Range: header were returning the wrong data — fixed (Nick Craig-Wood)

---

v1.62.2 - 2023-03-16 🎀

Receipts if you need em, bestie: https://github.com/rclone/rclone/compare/v1.62.1...v1.62.2

• Bug Fixes
  • docker volume plugin: added the missing fuse3 dependency (Nick Craig-Wood)
  • docs: fixed the size documentation (asdffdsazqqq)
• FTP
  • 426 errors on downloads with vsftpd fixed (Lesmiscore)

---

v1.62.1 - 2023-03-15 ✨

Receipts: https://github.com/rclone/rclone/compare/v1.62.0...v1.62.1

• Bug Fixes
  • docker: added the missing fuse3 dependency (cycneuramus)
  • build: updated the release docs to be way more careful with the tag (Nick Craig-Wood)
  • build: Github release is now set to draft while binaries are uploading (Nick Craig-Wood)

---

v1.62.0 - 2023-03-14 👑

Receipts: https://github.com/rclone/rclone/compare/v1.61.0...v1.62.0

• New Features
  • accounting: checkers now show what they're doing (Nick Craig-Wood)
  • authorize: custom templates supported (Hunter Wittenborn)
  • build
    • updated to go1.20 (Nick Craig-Wood, Anagh Kumar Baranwal)
    • winget releaser workflow added (Ryan Caezar Itang)
    • dependabot added (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: emits an INFO message when it can't work out directory filters (Nick Craig-Wood)
  • fs
    • added multiple ca certificate support. (alankrit)
    • added --max-delete-size, a delete size threshold (Leandro Sacchet)
  • fspath: the symbols @ and + are allowed in remote names now (albertony)
  • lib/terminal: enabled windows console virtual terminal sequences processing (ANSI/VT100 colors) (albertony)
  • move: if --check-first and --order-by are both set then deletes happen with perfect ordering (Nick Craig-Wood)
  • serve http: supports --auth-proxy (Matthias Baur)
• Bug Fixes
  • accounting
    • no more negative ETA values at very slow speeds (albertony)
    • ETA string length is limited (albertony)
    • elapsed time is shown human readable when it goes over a day (albertony)
  • all: applied codeql fixes (Aaron Gokaslan)
  • build
    • fixed the condition for a manual workflow run (albertony)
    • fixed building for ARMv5 and ARMv6 (albertony)
      • selfupdate: considers the ARM version
      • install.sh: fixed the ARMv6 download
      • version: reports the ARM version
  • deletefile: returns error code 4 if the file does not exist (Nick Craig-Wood)
  • docker: fixed the volume plugin not remounting the volume on docker restart (logopk)
  • fs: fixed race conditions in --max-delete and --max-delete-size (Nick Craig-Wood)
  • lib/oauthutil: handles fatal errors better (Alex Chen)
  • mount2: fixed --allow-non-empty (Nick Craig-Wood)
  • operations: fixed concurrency — use --checkers unless transferring files (Nick Craig-Wood)
  • serve ftp: fixed timestamps older than 1 year in listings (Nick Craig-Wood)
  • sync: fixed concurrency — use --checkers unless transferring files (Nick Craig-Wood)
  • tree
    • fixed a nil pointer exception on stat failure (Nick Craig-Wood)
    • fixed colored output on windows (albertony)
    • fixed the display of files with illegal Windows file system names (Nick Craig-Wood)
• Mount
  • fixed creating and renaming files on case insensitive backends (Nick Craig-Wood)
  • \\?\ prefixed paths are no longer treated as network share paths on windows (albertony)
  • fixed the check for an empty mount point on Linux (Nick Craig-Wood)
  • fixed --allow-non-empty (Nick Craig-Wood)
  • avoids incorrect or premature overlap check on windows (albertony)
  • updated to fuse3 after the bazil.org/fuse update (Nick Craig-Wood)
• VFS
  • uploaded files retain modtime with non-modtime backends (Nick Craig-Wood)
  • fixed incorrect modtime on fs which don't support setting modtime (Nick Craig-Wood)
  • fixed rename of a directory containing files to be uploaded (Nick Craig-Wood)
• Local
  • fixed %!w(<nil>) in the "failed to read directory" error (Marks Polakovs)
  • fixed 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 (https://github.com/rclone/rclone/compare/v1.61.0...v1.61.1)

• 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 (https://github.com/rclone/rclone/compare/v1.60.0...v1.61.0)

• New backends 🆕
  • New S3 providers
    • Liara LOS (https://rclone.org/s3/#liara-cloud) (MohammadReza)
• New Features ✨
  • build: Add vulnerability testing using govulncheck (albertony)
  • cmd: Enable SIGINFO (Ctrl-T) handler on FreeBSD, NetBSD, OpenBSD and Dragonfly BSD (x3-apptech)
  • config: Add config/setpath (https://rclone.org/rc/#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 (https://rclone.org/filtering/#metadata) 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 (https://rclone.org/rc/#debug-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 (https://www.stonebranch.com/) 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 (https://github.com/rclone/rclone/compare/v1.60.0...v1.60.1)

• 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 💜

See commits (https://github.com/rclone/rclone/compare/v1.59.0...v1.60.0)

• New backends 🎉
  • Oracle object storage (https://rclone.org/oracleobjectstorage/) (Manoj Ghosh)
  • SMB (https://rclone.org/smb/) / CIFS (Windows file sharing) (Lesmiscore)
  • New S3 providers ✨
    • IONOS Cloud Storage (https://rclone.org/s3/#ionos) (Dmitry Deniskin)
    • Qiniu KODO (https://rclone.org/s3/#qiniu) (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 ✨

See commits (https://github.com/rclone/rclone/compare/v1.59.1...v1.59.2)

• 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 🎀

See commits (https://github.com/rclone/rclone/compare/v1.59.0...v1.59.1)

• 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 👑

See commits (https://github.com/rclone/rclone/compare/v1.58.0...v1.59.0)

• New backends
  • Combine multiple remotes in one directory tree (Nick Craig-Wood)
  • Hidrive (https://rclone.org/hidrive/) (Ovidiu Victor Tatar)
  • Internet Archive (https://rclone.org/internetarchive/) (Lesmiscore (Naoya Ozaki))
  • New S3 providers
    • ArvanCloud AOS (https://rclone.org/s3/#arvan-cloud) (ehsantdy)
    • Cloudflare R2 (https://rclone.org/s3/#cloudflare-r2) (Nick Craig-Wood)
    • Huawei OBS (https://rclone.org/s3/#huawei-obs) (m00594701)
    • IDrive e2 (https://rclone.org/s3/#idrive-e2) (vyloy)
• New commands
  • test makefile (https://rclone.org/commands/rclone_test_makefile/): Create a single file for testing (Nick Craig-Wood)
• New Features
  • Metadata framework (https://rclone.org/docs/#metadata) 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 (https://manz-solutions.at/) 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 (https://staticcheck.io/) (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 (CrossR)
    • Replace termbox with tcell's termbox wrapper (eNV25)
    • Display correct path in delete confirmation dialog (Roberto Ricci)
  • operations
    • Speed up hash checking by aborting the other hash if first returns nothing (Nick Craig-Wood)
    • Use correct src/dst in some log messages (zzr93)
  • rcat: Check checksums by default like copy does (Nick Craig-Wood)
  • selfupdate: Replace deprecated x/crypto/openpgp package with ProtonMail/go-crypto (albertony)
  • serve ftp: Check --passive-port arguments are correct (Nick Craig-Wood)
  • size: Warn about inaccurate results when objects with unknown size (albertony)
  • sync: Overlap check is now filter-sensitive so --backup-dir can be in the root provided it is filtered (Nick)
  • test info: Check file name lengths using 1,2,3,4 byte unicode characters (Nick Craig-Wood)
  • test makefile(s): --sparse, --zero, --pattern, --ascii, --chargen flags to control file contents (Nick Craig-Wood)
  • Make sure we call the Shutdown method on backends (Martin Czygan)

🐛 Bug Fixes (the receipts 💅)

• accounting: Fix unknown length file transfers counting 3 transfers each (buda)
• ncdu: Fix issue where dir size is summed when file sizes are -1 (albertony)
• sync/copy/move
  • Fix --fast-list --create-empty-src-dirs and --exclude (Nick Craig-Wood)
  • Fix --max-duration and --cutoff-mode soft (Nick Craig-Wood)
• Fix fs cache unpin (Martin Czygan)
• Set proper exit code for errors that are not low-level retried (e.g. size/timestamp changing) (albertony)

🖥️ Mount

• Support windows/arm64 (may still have problems - see #5828 https://github.com/rclone/rclone/issues/5828) (Nick Craig-Wood)
• Log IO errors at ERROR level (Nick Craig-Wood)
• Ignore _netdev mount argument (Hugal31)

🌌 VFS

• Add --vfs-fast-fingerprint for less accurate but faster fingerprints (Nick Craig-Wood)
• Add --vfs-disk-space-total-size option to manually set the total disk space (Claudio Maradonna)
• vfscache: Fix fatal error: sync: unlock of unlocked mutex error (Nick Craig-Wood)

📁 Local

• Fix parsing of --local-nounc flag (Nick Craig-Wood)
• Add Metadata support (Nick Craig-Wood)

🔐 Crypt

• Support metadata (Nick Craig-Wood)

☁️ Azure Blob

• Calculate Chunksize/blocksize to stay below maxUploadParts (Leroy van Logchem)
• Use chunksize lib to determine chunksize dynamically (Derek Battams)
• Case insensitive access tier (Rob Pickerill)
• Allow remote emulator (azurite) (Lorenzo Maiorfi)

🅱️ B2

• Add --b2-version-at flag to show file versions at time specified (SwazRGB)
• Use chunksize lib to determine chunksize dynamically (Derek Battams)

✂️ Chunker

• Mark as not supporting metadata (Nick Craig-Wood)

🗜️ Compress

• Support metadata (Nick Craig-Wood)

🚗 Drive

• Make backend config -o config add a combined AllDrives: remote (Nick Craig-Wood)
• Make --drive-shared-with-me work with shared drives (Nick Craig-Wood)
• Add --drive-resource-key for accessing link-shared files (Nick Craig-Wood)
• Add backend commands exportformats and importformats for debugging (Nick Craig-Wood)
• Fix 404 errors on copy/server side copy objects from public folder (Nick Craig-Wood)
• Update Internal OAuth consent screen docs (Phil Shackleton)
• Moved root_folder_id to advanced section (Abhiraj)

📦 Dropbox

• Migrate from deprecated api (m8rge)
• Add logs to show when poll interval limits are exceeded (Nick Craig-Wood)
• Fix nil pointer exception on dropbox impersonate user not found (Nick Craig-Wood)

🥖 Fichier

• Parse api error codes and them accordingly (buengese)

📡 FTP

• Add support for disable_utf8 option (Jason Zheng)
• Revert to upstream github.com/jlaffaye/ftp from our fork (Nick Craig-Wood)

🪣 Google Cloud Storage

• Add --gcs-no-check-bucket to minimise transactions and perms (Nick Gooding)
• Add --gcs-decompress flag to decompress gzip-encoded files (Nick Craig-Wood)
  • by default these will be downloaded compressed (which previously failed)

#️⃣ Hasher

• Support metadata (Nick Craig-Wood)

🌐 HTTP

• Fix missing response when using custom auth handler (albertony)

🇳🇴 Jottacloud

• Add support for upload to custom device and mountpoint (albertony)
• Always store username in config and use it to avoid initial API request (albertony)
• Fix issue with server-side copy when destination is in trash (albertony)
• Fix listing output of remote with special characters (albertony)

📮 Mailru

• Fix timeout by using int instead of time.Duration for keeping number of seconds (albertony)

🗄️ Mega

• Document using MEGAcmd to help with login failures (Art M. Gallagher)

🪟 Onedrive

• Implement --poll-interval for onedrive (Hugo Laloge)
• Add access scopes option (Sven Gerber)

🛞 Opendrive

• Resolve lag and truncate bugs (Scott Grimes)

☁️ Pcloud

• Fix about with no free space left (buengese)
• Fix cleanup (buengese)

🧺 S3

• Use PUT Object instead of presigned URLs to upload single part objects (Nick Craig-Wood)
• Backend restore command to skip non-GLACIER objects (Vincent Murphy)
• Use chunksize lib to determine chunksize dynamically (Derek Battams)
• Retry RequestTimeout errors (Nick Craig-Wood)
• Implement reading and writing of metadata (Nick Craig-Wood)

🔑 SFTP

• Add support for about and hashsum on windows server (albertony)
• Use vendor-specific VFS statistics extension for about if available (albertony)
• Add --sftp-chunk-size to control packets sizes for high latency links (Nick Craig-Wood)
• Add --sftp-concurrency to improve high latency transfers (Nick Craig-Wood)
• Add --sftp-set-env option to set environment variables (Nick Craig-Wood)
• Add Hetzner Storage Boxes to supported sftp backends (Anthrazz)

🛰️ Storj

• Fix put which lead to the file being unreadable when using mount (Erik van Velzen)

🤝 Union

• Add min_free_space option for lfs/eplfs policies (Nick Craig-Wood)
• Fix uploading files to union of all bucket based remotes (Nick Craig-Wood)
• Fix get free space for remotes which don't support it (Nick Craig-Wood)
• Fix eplus policy to select correct entry for existing files (Nick Craig-Wood)
• Support metadata (Nick Craig-Wood)

⬆️ Uptobox

• Fix root path handling (buengese)

🕸️ WebDAV

• Add SharePoint in other specific regions support (Noah Hsu)

🇷🇺 Yandex

• Handle api error on server-side move (albertony)

🏢 Zoho

• Add Japan and China regions (buengese)

---

🎀 v1.58.1 - 2022-04-29

See commits https://github.com/rclone/rclone/compare/v1.58.0...v1.58.1

🐛 Bug Fixes

• build: Update github.com/billziss-gh to github.com/winfsp (Nick Craig-Wood)
• filter: Fix timezone of --min-age/-max-age from UTC to local as documented (Nick Craig-Wood)
• rc/js: Correct RC method names (Sơn Trần-Nguyễn)
• docs
  • Fix some links to command pages (albertony)
  • Add --multi-thread-streams note to --transfers. (Zsolt Ero)

🖥️ Mount

• Fix --devname and fusermount: unknown option 'fsname' when mounting via rc (Nick Craig-Wood)

🌌 VFS

• Remove wording which suggests VFS is only for mounting (Nick Craig-Wood)

📦 Dropbox

• Fix retries of multipart uploads with incorrect_offset error (Nick Craig-Wood)

🪣 Google Cloud Storage

• Use the s3 pacer to speed up transactions (Nick Craig-Wood)
• pacer: Default the Google pacer to a burst of 100 to fix gcs pacing (Nick Craig-Wood)

🇳🇴 Jottacloud

• Fix scope in token request (albertony)

🗃️ Netstorage

• Fix unescaped HTML in documentation (Nick Craig-Wood)
• Make levels of headings consistent (Nick Craig-Wood)
• Add support contacts to netstorage doc (Nil Alexandrov)

🪟 Onedrive

• Note that sharepoint also changes web files (.html, .aspx) (GH)

🎬 Putio

• Handle rate limit errors (Berkan Teber)
• Fix multithread download and other ranged requests (rafma0)

🧺 S3

• Add ChinaMobile EOS to provider list (GuoXingbin)
• Sync providers in config description with providers (Nick Craig-Wood)

🔑 SFTP

• Fix OpenSSH 8.8+ RSA keys incompatibility (KARBOWSKI Piotr)
• Note that Scaleway C14 is deprecating SFTP in favor of S3 (Adrien Rey-Jarthon)

🛰️ Storj

• Fix bucket creation on Move (Nick Craig-Wood)

🕸️ WebDAV

• Don't override Referer if user sets it (Nick Craig-Wood)

---

✨ v1.58.0 - 2022-03-18

See commits https://github.com/rclone/rclone/compare/v1.57.0...v1.58.0

🌱 New backends

• Akamai Netstorage (Nil Alexandrov)
• Seagate Lyve https://rclone.org/s3/#lyve, SeaweedFS, Storj, RackCorp via s3 backend
• Storj https://rclone.org/storj/ (renamed from Tardigrade - your old config files will continue working)

🆕 New commands

• bisync https://rclone.org/bisync/ - experimental bidirectional cloud sync (Ivan Andreev, Chris Nelson)

💫 New Features

• build
  • Add windows/arm64 build (rclone mount not supported yet) (Nick Craig-Wood)
  • Raise minimum go version to go1.15 (Nick Craig-Wood)
• config: Allow dot in remote names and improve config editing (albertony)
• dedupe: Add quit as a choice in interactive mode (albertony)
• dlna: Change icons to the newest ones. (Alain Nussbaumer)
• filter: Add {{ regexp }} syntax https://rclone.org/filtering/#regexp to pattern matches (Nick Craig-Wood)
• fshttp: Add prometheus metrics for HTTP status code (Michał Matczuk)
• hashsum — now supports creating a hash from data you pipe in on stdin, which is lowkey so useful (albertony) 💖
• librclone
  • lets you pass an empty string or null as input instead of an empty json object, no more awkward empty {} energy (albertony)
  • added support for mount commands, slay (albertony)
• operations — server-side moves now show up in stats, the way it should be (Ole Frost) ✨
• rc — you can now disable authentication for the web gui if you want (negative0)
• tree — dipped the obsolete --human flag, it's been replaced by the global --human-readable (albertony)
• version — now reports the correct friendly-name for newer Windows 10/11 versions, finally (albertony)
• Bug Fixes 💀
  • build
    • fixed the ARM architecture version in .deb packages after the nfpm change (Nick Craig-Wood)
    • hard forked github.com/jlaffaye/ftp to fix go get github.com/rclone/rclone (Nick Craig-Wood)
  • oauthutil — fixed a crash when the webbrowser requests /robots.txt (Nick Craig-Wood)
  • operations — fixed a goroutine leak in the case of a copy retry (Ankur Gupta)
  • rc
    • fixed the operations/publiclink default for the expires parameter (Nick Craig-Wood)
    • fixed missing computation of transferQueueSize when summing up the statistics group (Carlo Mion)
    • fixed missing StatsInfo fields in the computation of the group sum (Carlo Mion)
  • sync — fixed --max-duration so it doesn't retry when the duration is exceeded, no cap (Nick Craig-Wood)
  • touch — fixed the issue where a directory was created instead of a file, iconic behaviour honestly (albertony)
• Mount
  • added --devname to set the device name sent to FUSE for mount display (Nick Craig-Wood) 🎀
• VFS
  • added the vfs/stats remote control to show statistics (Nick Craig-Wood) ✨
  • fixed the failed to _ensure cache internal error: downloaders is nil error (Nick Craig-Wood)
  • fixed handling of special characters in file names (Bumsu Hyeon)
• Local
  • fixed hash invalidation which caused errors with local crypt mount (Nick Craig-Wood)
• Crypt
  • added base64 and base32768 filename encoding options (Max Sum, Sinan Tan) 💅
• Azure Blob
  • implemented the --azureblob-upload-concurrency parameter to speed up uploads (Nick Craig-Wood)
  • removed the 100MB upper limit on chunk_size since it is no longer needed (Nick Craig-Wood)
  • raised --azureblob-upload-concurrency to 16 by default (Nick Craig-Wood)
  • fixed a crash with a SAS URL and no container (Nick Craig-Wood)
• Compress
  • fixed a crash if metadata upload failed (Nick Craig-Wood)
  • fixed a memory leak (Nick Craig-Wood) 😭
• Drive
  • added --drive-copy-shortcut-content (Abhiraj)
  • disabled the OAuth OOB flow (copy a token) due to Google deprecation (Nick Craig-Wood)
    • see the deprecation note (https://developers.googleblog.com/2022/02/making-oauth-flows-safer.html#disallowed-oob).
  • added the --drive-skip-dangling-shortcuts flag (Nick Craig-Wood)
  • when using a link type, --drive-export-formats now shows all doc types (Nick Craig-Wood)
• Dropbox
  • sped up directory listings by specifying 1000 items in a chunk (Nick Craig-Wood)
  • saves an API request when at the root (Nick Craig-Wood)
• Fichier
  • implemented About functionality (Gourav T)
• FTP
  • added --ftp-ask-password to prompt for the password when needed (Borna Butkovic)
• Google Cloud Storage
  • added missing regions (Nick Craig-Wood)
  • disabled the OAuth OOB flow (copy a token) due to Google deprecation (Nick Craig-Wood)
    • see the deprecation note (https://developers.googleblog.com/2022/02/making-oauth-flows-safer.html#disallowed-oob).
• Googlephotos
  • disabled the OAuth OOB flow (copy a token) due to Google deprecation (Nick Craig-Wood)
    • see the deprecation note (https://developers.googleblog.com/2022/02/making-oauth-flows-safer.html#disallowed-oob).
• Hasher
  • fixed a crash on object not found (Nick Craig-Wood)
• Hdfs
  • added file (Move) and directory move (DirMove) support (Andy Jackson)
• HTTP
  • improved recognition of a URL pointing to a single file (albertony)
• Jottacloud
  • changed the API used by recursive list (ListR) (Kim)
  • added support for Tele2 Cloud (Fredric Arklid)
• Koofr
  • added the Digistorage service as a Koofr provider (jaKa)
• Mailru
  • fixed int32 overflow on arm32 (Ivan Andreev)
• Onedrive
  • added a config option for the oauth scope Sites.Read.All (Charlie Jiang)
  • minor optimization of quickxorhash (Isaac Levy)
  • added the --onedrive-root-folder-id flag (Nick Craig-Wood)
  • no more retrying on a 400 pathIsTooLong error (ctrl-q)
• Pcloud
  • added support for recursive list (ListR) (Niels van de Weem)
  • fixed pre-1970 time stamps (Nick Craig-Wood)
• S3
  • uses ListObjectsV2 for faster listings (Felix Bunemann)
    • falls back to ListObject v1 on unsupported providers (Nick Craig-Wood)
  • uses the ETag on multipart transfers to verify the transfer was OK (Nick Craig-Wood)
    • added the --s3-use-multipart-etag provider quirk to disable this on unsupported providers (Nick Craig-Wood)
  • New Providers
    • RackCorp object storage (bbabich)
    • Seagate Lyve Cloud storage (Nick Craig-Wood)
    • SeaweedFS (Chris Lu)
    • Storj Shared gateways (Márton Elek, Nick Craig-Wood)
  • added Wasabi AP Northeast 2 endpoint info (lindwurm)
  • added the GLACIER_IR storage class (Yunhai Luo)
  • documented the Content-MD5 workaround for object-lock enabled buckets (Paulo Martins)
  • fixed multipart upload with --no-head (Nick Craig-Wood)
  • simplified content length processing in s3 with download url (Logeshwaran Murugesan)
• SFTP
  • added rclone to the list of supported md5sum/sha1sum commands to look for (albertony)
  • refactored so we only have one way of running remote commands (Nick Craig-Wood)
  • fixed timeout on hashing large files by sending keepalives (Nick Craig-Wood)
  • fixed unnecessary seeking when uploading and downloading files (Nick Craig-Wood)
  • updated the docs on how to create a known_hosts file (Nick Craig-Wood)
• Storj
  • renamed the tardigrade backend to the storj backend (Nick Craig-Wood)
  • implemented server side Move for files (Nick Craig-Wood)
  • updated the docs to explain the differences between s3 and this backend (Elek, Márton)
• Swift
  • fixed About so it shows info about the current container only (Nick Craig-Wood)
• Union
  • fixed treatment of remotes with // in (Nick Craig-Wood)
  • fixed a deadlock when one part of a multi-upload fails (Nick Craig-Wood)
  • fixed eplus policy returning nil (Vitor Arruda)
• Yandex
  • added permanent deletion support (deinferno)

---

🌈 v1.57.0 - 2021-11-01 🌈

See commits (https://github.com/rclone/rclone/compare/v1.56.0...v1.57.0)

• New backends 🦋
  • Sia: for Sia decentralized cloud (Ian Levesque, Matthew Sevey, Ivan Andreev)
  • Hasher: caches hashes and enables hashes for backends that don't support them (Ivan Andreev)
• New commands ✨
  • lsjson --stat: to get info about a single file/dir and the operations/stat api (Nick Craig-Wood)
  • config paths: show configured paths (albertony)
• New Features 💖
  • about: made human-readable output more consistent with other commands (albertony)
  • build
    • use go1.17 for building and make go1.14 the minimum supported (Nick Craig-Wood)
    • updated Go to 1.16 and NDK to 22b for Android builds (x0b)
  • config
    • support hyphens in remote names coming from an environment variable (albertony)
    • made the temporary directory user-configurable (albertony)
    • converted the --cache-dir value to an absolute path (albertony)
    • don't override MIME types from OS defaults (albertony)
  • docs
    • toc styling and header levels cleanup (albertony)
    • extended the documentation on valid remote names (albertony)
    • mentioned make for building and the cmount tag for macos (Alex Chen)
    • ...and many more contributions too numerous to mention!
  • fs: Move with --ignore-existing will not delete skipped files (Nathan Collins)
  • hashsum
    • treat hash values in a sum file as case insensitive (Ivan Andreev)
    • don't put ERROR or UNSUPPORTED in the output (Ivan Andreev)
  • lib/encoder: added encoding of square brackets (Ivan Andreev)
  • lib/file: improved the error message when attempting to create a dir on a nonexistent drive on windows (albertony)
  • lib/http: factored the password hash salt into options with a default (Nolan Woods)
  • lib/kv: added a key-value database api (Ivan Andreev)
  • librclone
    • added the RcloneFreeString function (albertony)
    • free strings in the python example (albertony)
  • log: optionally print the pid in logs (Ivan Andreev)
  • ls: introduced the --human-readable global option to print human-readable sizes (albertony)
  • ncdu: introduced the key u to toggle human-readable (albertony)
  • operations: added rmdirs -v output (Justin Winokur)
  • serve sftp
    • generate an ECDSA server key as well as RSA (Nick Craig-Wood)
    • generate an Ed25519 server key as well as ECDSA and RSA (albertony)
  • serve docker
    • allow customizing the proxy settings of the docker plugin (Ivan Andreev)
    • build the docker plugin for multiple platforms (Thomas Stachl)
  • size: include the human-readable count (albertony)
  • touch: added support for touching files in a directory, with the recursive option, filtering and --dry-run/-i (albertony)
  • tree: the option to print human-readable sizes was removed in favor of the global option (albertony)
• Bug Fixes 💀
  • lib/http
    • fixed a bad username check in the single auth secret provider (Nolan Woods)
    • fixed handling of SSL credentials (Nolan Woods)
  • serve ftp: ensure modtime is passed as UTC always to fix timezone oddities (Nick Craig-Wood)
  • serve sftp: fixed generation of server keys on windows (albertony)
  • serve docker: fixed octal umask (Ivan Andreev)
• Mount
  • enable rclone to be run as a mount helper direct from the fstab (Ivan Andreev)
  • use procfs to validate mount on linux (Ivan Andreev)
  • correctly daemonize for compatibility with automount (Ivan Andreev)
• VFS
  • ensure names used in the cache path are legal on the current OS (albertony)
• Not me literally ignoring ECLOSED when truncating file handles to fix that intermittent bad file descriptor error — slay, Nick Craig-Wood 💅
• Local — bestie, we pulled the default OS encoding out of the local backend and into a shared encoder lib, so now it’s giving teamwork realness (albertony)
• Crypt — now returns the wrapped object even with --crypt-no-data-encryption (Ivan Andreev), and fixed uploads with --crypt-no-data-encryption too (Nick Craig-Wood) 💖
• Azure Blob — added --azureblob-no-head-object because we can (Tatsuya Noyori)
• Box — okay so:
  • listings of heavily used directories are literally more reliable now (Nick Craig-Wood)
  • when doing cleanup it deletes as much as possible (Nick Craig-Wood)
  • added --box-list-chunk to control listing chunk size (Nick Craig-Wood)
  • deletes items in parallel in cleanup using --checkers threads (Nick Craig-Wood)
  • added --box-owned-by to only show items owned by the login passed (Nick Craig-Wood)
  • retries operation_blocked_temporary errors (Nick Craig-Wood)
• Chunker — Md5all must create metadata if the base hash is slow, no cap (Ivan Andreev)
• Drive — the glow-up:
  • sped up directory listings by constraining the API listing using the current filters (fotile96, Ivan Andreev)
  • fixed buffering for single request upload for files smaller than --drive-upload-cutoff (YenForYang)
  • added -o config option to backend drives to make config for all shared drives (Nick Craig-Wood)
• Dropbox — added --dropbox-batch-commit-timeout to control batch timeout, periodt (Nick Craig-Wood)
• Filefabric — made backoff exponential for error_background to fix errors (Nick Craig-Wood), and fixed directory move after API change (Nick Craig-Wood)
• FTP — the whole vibe:
  • enabled tls session cache by default (Ivan Andreev)
  • added option to disable tls13 (Ivan Andreev)
  • fixed timeout after long uploads (Ivan Andreev)
  • added support for precise time (Ivan Andreev)
  • enabled CI for ProFtpd, PureFtpd, VsFtpd (Ivan Andreev)
• Googlephotos — used encoder for album names to fix albums with control characters (Parth Shukla)
• Jottacloud — fr fr:
  • implemented SetModTime to support modtime-only changes (albertony)
  • improved error handling with SetModTime and corrupt files in general (albertony)
  • added support for UserInfo (rclone config userinfo) feature (albertony)
  • returns direct download link from rclone link command (albertony)
• Koofr — created direct share link (Dmitry Bogatov)
• Pcloud — added sha256 support (Ken Enrique Morel)
• Premiumizeme — fixed directory listing after API changes (Nick Craig-Wood), fixed server side move after API change (Nick Craig-Wood), fixed server side directory move after API changes (Nick Craig-Wood)
• S3 — main character energy:
  • added support to use CDN URL to download the file (Logeshwaran)
  • added AWS Snowball Edge to providers examples (r0kk3rz)
  • uses a combination of SDK retries and rclone retries (Nick Craig-Wood)
  • fixed IAM Role for Service Account not working and other auth problems (Nick Craig-Wood)
  • fixed shared_credentials_file auth after reverting incorrect fix (Nick Craig-Wood)
  • fixed corrupted on transfer: sizes differ 0 vs xxxx with Ceph (Nick Craig-Wood)
• Seafile — fixed error when not configured for 2fa (Fred)
• SFTP — fixed timeout when doing MD5SUM of large file (Nick Craig-Wood)
• Swift — updated OCI URL (David Liu) and documented OVH Cloud Archive (HNGamingUK)
• Union — fixed rename not working with union of local disk and bucket based remote (Nick Craig-Wood)

---

✨ v1.56.2 - 2021-10-01 ✨

See commits at https://github.com/rclone/rclone/compare/v1.56.1...v1.56.2

💖 Bug Fixes 💖

• serve http: re-added missing auth to http service — bestie, we needed that (Nolan Woods)
• build: updated golang.org/x/sys to fix crash on macOS when compiled with go1.17 (Herby Gillot)

🦋 FTP 🦋

• fixed deadlock after failed update when concurrency=1 (Ivan Andreev)

---

🌸 v1.56.1 - 2021-09-19 🌸

See commits at https://github.com/rclone/rclone/compare/v1.56.0...v1.56.1

💖 Bug Fixes 💖

• accounting: fixed maximum bwlimit by scaling scale max token bucket size (Nick Craig-Wood)
• rc: fixed speed does not update in core/stats (negative0)
• selfupdate: fixed --quiet option, not quite quiet (yedamo)
• serve http: fixed serve http exiting directly after starting (Cnly)
• build
  • applied gofmt from golang 1.17 (Ivan Andreev)
  • updated Go to 1.16 and NDK to 22b for android/any (x0b)

🎀 Mount 🎀

• fixed --daemon mode (Ivan Andreev)

🦋 VFS 🦋

• fixed duplicates on rename (Nick Craig-Wood)
• fixed crash when truncating a just uploaded object (Nick Craig-Wood)
• fixed issue where empty dirs would build up in cache meta dir (albertony)

🚗 Drive 🚗

• fixed instructions for auto config (Greg Sadetsky)
• fixed lsf example without drive-impersonate (Greg Sadetsky)

☁️ Onedrive ☁️

• handled HTTP 400 better in PublicLink (Alex Chen)
• clarified the process for creating custom client_id (Mariano Absatz)

☁️ Pcloud ☁️

• now returns an early error when Put is called with an unknown size (Nick Craig-Wood)
• tries harder to delete a failed upload (Nick Craig-Wood)

🪣 S3 🪣

• added Wasabi's AP-Northeast endpoint info (hota)
• fixed typo in s3 documentation (Greg Sadetsky)

🌊 Seafile 🌊

• fixed 2fa config state machine (Fred)

🔐 SFTP 🔐

• removed spurious error message on --sftp-disable-concurrent-reads (Nick Craig-Wood)

🍬 Sugarsync 🍬

• fixed initial connection after config re-arrangement (Nick Craig-Wood)

---

👑 v1.56.0 - 2021-07-20 👑

See commits at https://github.com/rclone/rclone/compare/v1.55.0...v1.56.0

🌈 New backends 🌈

• Uptobox (https://rclone.org/uptobox/) (buengese) — new bestie alert!

✨ New commands ✨

• serve docker (https://rclone.org/commands/rclone_serve_docker/) (Antoine GIRARD) (Ivan Andreev)
  • and accompanying docker volume plugin (https://rclone.org/docker/)
• checksum (https://rclone.org/commands/rclone_checksum/) to check files against a file of checksums (Ivan Andreev)
  • this is also available as rclone md5sum -C etc
• config touch (https://rclone.org/commands/rclone_config_touch/): ensure config exists at configured location (albertony)
• test changenotify (https://rclone.org/commands/rclone_test_changenotify/): command to help debugging changenotify (Nick Craig-Wood)

💀 Deprecations 💀

• dbhashsum: removed command deprecated a year ago (Ivan Andreev)
• cache: deprecated cache backend (Ivan Andreev)

🔥 New Features 🔥

• reworked config system so it can be used non-interactively via cli and rc API.
  • See docs in config create (https://rclone.org/commands/rclone_config_create/)
  • This is a very big change to all the backends so may cause breakages - please file bugs!
• 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
  • added --disable-http2 for global http2 disable (Nick Craig-Wood)
  • made --dump imply -vv (Alex Chen)
  • use binary prefixes for size and rate units (albertony)
  • use decimal prefixes for counts (albertony)
  • added 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)
  • added 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)
  • replaced 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: implemented graceful DSCP error handling (Tyson Moore)
• lib/http - provides an abstraction for a central http server that services can bind routes to (Nolan Woods)
  • added --template config and flags to serve/data (Nolan Woods)
  • added 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: added --size flag for more efficient uploads of known size (Nazar Mishturak)
• serve sftp: added --stdio flag to serve via stdio (Tom)
• sync: don't warn about --no-traverse when --files-from is set (Nick Gaya)
• test makefiles
  • added --seed flag and make data generated repeatable (Nick Craig-Wood)
  • added log levels and speed summary (Nick Craig-Wood)

💖 Bug Fixes 💖

• accounting: fixed startTime of statsGroups.sum (Haochen Tong)
• cmd/ncdu: fixed out of range panic in delete (buengese)
• config
  • fixed issues with memory-only config file paths (albertony)
  • fixed in memory config not saving on the fly backend config (Nick Craig-Wood)
• fshttp: fixed address parsing for DSCP (Tyson Moore)
• ncdu: updated termbox-go library to fix crash (Nick Craig-Wood)
• oauthutil: fixed old authorize result not recognised (Cnly)
• operations: don't update timestamps of files in --compare-dest (Nick Gaya)
• selfupdate: fixed archive name on macos (Ivan Andreev)

🎀 Mount 🎀

• refactored before adding serve docker (Antoine GIRARD)

🦋 VFS 🦋

• added cache reset for --vfs-cache-max-size handling at cache poll interval (Leo Luan)
• fixed modtime changing when reading file into cache (Nick Craig-Wood)
• avoided 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)
• Local 🗂️ — literally your own disk, bestie, we love a home-field advantage
  • 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)
• Crypt 🔐 — secrets stay secret, periodt
  • Support timestamped filenames from --b2-versions (Dominik Mydlil)
• B2 💙
  • 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)
• Box 📦
  • 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)
• Drive 🚗💨
  • Switch to the Drives API for looking up shared drives (Nick Craig-Wood)
  • Fix some google docs being treated as files (Nick Craig-Wood)
• Dropbox 🎀
  • Add --dropbox-batch-mode flag to speed up uploading (Nick Craig-Wood)
    • Read the batch mode docs (https://rclone.org/dropbox/#batch-mode) 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)
• Fichier 🇫🇷
  • Check if more than one upload link is returned (Nick Craig-Wood)
  • Support downloading password protected files and folders (Florian Penzkofer)
  • Make error messages report text from the API (Nick Craig-Wood)
  • 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)
• 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)
• 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)
• WebDAV 🕸️
  • Fix sharepoint auth over http (Nick Craig-Wood)
  • Add headers option (Antoon Prins)

---

v1.55.1 - 2021-04-26 ✨

See commits 👀 — https://github.com/rclone/rclone/compare/v1.55.0...v1.55.1

• Bug Fixes 🐛 — the glow-up patch, no cap
  • 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)

okay bestie, that one ^ is a data-loss bug fix, so it's giving "please upgrade immediately" energy 🔥

• 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 💖 — https://github.com/rclone/rclone/compare/v1.54.0...v1.55.0

• New commands 👑
  • selfupdate (https://rclone.org/commands/rclone_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 (https://rclone.org/commands/rclone_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 (https://rclone.org/docs/#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 (https://cs3mesh4eosc.eu/).
      • 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 the occasional failure to unmount with CTRL-C (Nick Craig-Wood) 💅
• Fix deadlock calling Finalise while Run is running (Nick Craig-Wood) — no more deadlock drama besties
• lib/rest: Fix multipart uploads not stopping on context cancel (Nick Craig-Wood)

---

🌈 Mount 🌈

• Allow mounting to the root directory on windows (albertony) 🪟
• Improved handling of relative paths on windows (albertony)
• Fix unicode issues with accented characters on macOS (Nick Craig-Wood) — éàü we see you, we love you
• 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) — she scans, she reports, she serves
• 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) 😭 copy paste betrayal
• 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) — sometimes you just want the vibes, unencrypted
• Log hash ok on upload (albertony)

⭐ Azure Blob ⭐

• Add container public access level support. (Manish Kumar)

🍓 B2 🍓

• Fix HTML files downloaded via cloudflare (Nick Craig-Wood)

🫶 Box 🫶

• Fix transfers getting stuck on token expiry after API change (Nick Craig-Wood)

🧚 Chunker 🧚

• Partially implement no-rename transactions (Maxwell Calman)

🔥 Drive 🔥

• 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)

🌸 Dropbox 🌸

• 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) 👀

💜 Fichier 💜

• Implement copy & move (buengese)
• Implement public link (buengese)

🌈 FTP 🌈

• 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)

💖 Hdfs 💖

• Fix permissions for when directory is created (Lucas Messenger)

✨ Onedrive ✨

• Make --timeout 0 work properly (Nick Craig-Wood)

👑 S3 👑

• Fix --s3-profile which wasn't working (Nick Craig-Wood)

🦋 SFTP 🦋

• 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)

⭐ Swift ⭐

• Update github.com/ncw/swift to v2.0.0 (Nick Craig-Wood)
• Implement copying large objects (nguyenhuuluan434)

🎀 Union 🎀

• 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)

🌈 WebDAV 🌈

• 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)

💅 Yandex 💅

• Make --timeout 0 work properly (Nick Craig-Wood)

🫶 Zoho 🫶

• Replace client id - you will need to run rclone config reconnect after this (buengese) ⚠️ yeah you gotta re-auth bestie
• Add forgotten setupRegion() to NewFs - this finally fixes regions other than EU (buengese)

---

🎉 v1.54.1 - 2021-03-08 🎉

See commits: https://github.com/rclone/rclone/compare/v1.54.0...v1.54.1

💖 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) ⚠️ fr fr don't do it

🍓 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: https://github.com/rclone/rclone/compare/v1.53.0...v1.54.0

✨ New backends ✨

• Compression remote (experimental) (buengese)
• Enterprise File Fabric (Nick Craig-Wood)
  • This work was sponsored by Storage Made Easy (https://storagemadeeasy.com/) 🫶
• 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 (https://digitalis.io/) 🫶
• 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ý) 😭 not the s3ize, iconic, keeping it exactly as written
  • 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 — hiii so enabling systemd logging while you're using --log-file was lowkey not working, and that's now fixed 💅 (Nick Craig-Wood)
• check — the error count in the log message now actually matches up, no more confusing math bestie (Nick Craig-Wood)
• move — fixed a whole data loss situation for when the source and the destination are literally the same object 😭😭 (Nick Craig-Wood)
• operations
  • --cutoff-mode hard was not cutting off immediately. It is now. periodt (Nick Craig-Wood)
  • fixed the --immutable error message (Nick Craig-Wood)
• sync
  • fixed --cutoff-mode soft & cautious so it stops ending the transfer early 🙈 (Nick Craig-Wood)
  • fixed --immutable errors retrying a million times (Nick Craig-Wood)
• Docs 📚
  • so many fixes plus a full rewrite of the filtering docs (edwardxml)
  • tons of spelling and grammar fixes (Josh Soref)
  • doc fixes for the commands delete, purge, rmdir, rmdirs and mount (albertony)
  • and thank you to these icons for many doc fixes too numerous to even 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 👑
  • systemd status now gets updated with cache stats (Hekmon)
  • the bazil/fuse based mount is disabled on macOS (Nick Craig-Wood)
    • and rclone mount now actually runs rclone cmount under macOS (Nick Craig-Wood)
  • implemented mknod so NFS file creation works (Nick Craig-Wood)
  • no more calling umount more than once, we simply do not do that (Nick Craig-Wood)
  • more user friendly mounting as a network drive on windows ✨ (albertony)
  • now detects if uid or gid are set in the same option string, like -o uid=123,gid=456 (albertony)
  • it will no longer try to unmount if the fs has already been destroyed (Nick Craig-Wood)
• VFS 🦋
  • fixed virtual entries causing deleted files to still show up (they were haunting us fr) (Nick Craig-Wood)
  • fixed the "file already exists" error for stale cache files (Nick Craig-Wood)
  • fixed file leaks with --vfs-cache-mode full and --buffer-size 0 (Nick Craig-Wood)
  • fixed the invalid cache path on windows when using :backend: as the remote (albertony)
• Local
  • keeps listing files/folders when a circular symlink is detected, instead of just giving up (Manish Gupta)
  • new flag --local-zero-size-links to fix sync on some virtual filesystems (Riccardo Iaconelli)
• Azure Blob
  • added support for service principals (James Lim)
  • added support for managed identities (Brad Ackerman)
  • added examples for access tier (Bob Pusateri)
  • now utilizes the streaming capabilities from the SDK for multipart uploads (Denis Neuling)
  • fixed setting of mime types (Nick Craig-Wood)
  • fixed a 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)
  • fixed crash on startup (Nick Craig-Wood)
  • fixed memory usage by upgrading the SDK to v0.13.0 and implementing a TransferManager (Nick Craig-Wood)
  • now requires go1.14+ to compile due to SDK changes (Nick Craig-Wood)
• B2
  • NewObject now uses less expensive API calls (Nick Craig-Wood)
    • this will improve --files-from and restic serve in particular 💅
  • fixed a crash on an empty file name (lluuaapp)
• Box
  • fixed NewObject for files that differ in case (Nick Craig-Wood)
  • fixed finding directories in a case insensitive way (Nick Craig-Wood)
• Chunker
  • skip long local hashing, hash in-transit (fixes) (Ivan Andreev)
  • set Features ReadMimeType to false as Object.MimeType is not supported (Nick Craig-Wood)
  • fixed case-insensitive NewObject, and test metadata detection (Ivan Andreev)
• Drive
  • implemented the rclone backend copyid command for copying files by ID (Nick Craig-Wood)
  • added flag --drive-stop-on-download-limit to stop transfers when the download limit is exceeded (Anagh Kumar Baranwal)
  • implemented a CleanUp workaround for team drives (buengese)
  • shortcut resolution and creation can now be retried (Nick Craig-Wood)
  • logs that emptying the trash can take some time ⏳ (Nick Craig-Wood)
  • added xdg office icons to xdg desktop files (Pau Rodriguez-Estivill)
• Dropbox
  • added support for viewing shared files and folders (buengese)
  • enabled short lived access tokens (Nick Craig-Wood)
  • implemented IDer on Objects so rclone lsf etc can read the IDs (buengese)
  • set Features ReadMimeType to false as Object.MimeType is not supported (Nick Craig-Wood)
  • made malformed_path errors from too-long files not retriable (Nick Craig-Wood)
  • test file name length before upload to fix the upload loop (Nick Craig-Wood)
• Fichier
  • set Features ReadMimeType to true as Object.MimeType is supported (Nick Craig-Wood)
• FTP
  • added --ftp-disable-msld option to ignore MLSD for really old servers (Nick Craig-Wood)
  • made --tpslimit actually apply (Nick Craig-Wood)
• Google Cloud Storage
  • storage class object header support (Laurens Janssen)
  • fixed anonymous client to use rclone's HTTP client (Nick Craig-Wood)
  • fixed Entry doesn't belong in directory "" (same as directory) - ignoring (Nick Craig-Wood)
• Googlephotos
  • new flag --gphotos-include-archived to show archived photos as well (Nicolas Rueff)
• Jottacloud
  • stopped erroneously reporting support for writing mime types (buengese)
  • added support for Telia Cloud (Patrik Nordlén)
• Mailru
  • accepts special folders eg camera-upload (Ivan Andreev)
  • avoids prehashing of large local files (Ivan Andreev)
  • fixed uploads after recent changes on the server (Ivan Andreev)
  • fixed range requests after June 2020 changes on the server (Ivan Andreev)
  • fixed invalid timestamp on corrupted files (fixes) (Ivan Andreev)
  • removed deprecated protocol quirks (Ivan Andreev)
• Memory
  • fixed setting of mime types (Nick Craig-Wood)
• Onedrive
  • added support for the China region operated by 21vianet and other regional suppliers (NyaMisty)
  • warns on gateway timeout errors (Nick Craig-Wood)
  • falls back to normal copy if server-side copy is unavailable (Alex Chen)
  • fixed server-side copy being completely disabled on OneDrive for Business (Cnly)
  • (business only) workaround to replace an existing file on server-side copy (Alex Chen)
  • enhanced link creation with expiry, scope, type and password (Nick Craig-Wood)
  • removed % and # from the set of encoded characters (Alex Chen)
  • support addressing site by server-relative URL (kice)
• Opendrive
  • fixed finding directories in a case insensitive way (Nick Craig-Wood)
• Pcloud
  • fixed setting of mime types (Nick Craig-Wood)
• Premiumizeme
  • fixed finding directories in a case insensitive way (Nick Craig-Wood)
• Qingstor
  • fixed error propagation in CleanUp (Nick Craig-Wood)
  • fixed rclone cleanup (Nick Craig-Wood)
• S3
  • added --s3-disable-http2 to disable http/2 (Anagh Kumar Baranwal)
  • completed the SSE-C implementation (Nick Craig-Wood)
    • fixed hashes on small files with AWS:KMS and SSE-C (Nick Craig-Wood)
    • added MD5 metadata to objects uploaded with SSE-AWS/SSE-C (Nick Craig-Wood)
  • added --s3-no-head parameter to minimise transactions on upload (Nick Craig-Wood)
  • updated docs with a Reducing Costs section (Nick Craig-Wood)
  • added error handling for error code 429 indicating too many requests (Anagh Kumar Baranwal)
  • added requester pays option (kelv)
  • fixed copy multipart with v2 auth failing with 'SignatureDoesNotMatch' (Louis Koo)
• SFTP
  • allow cert based auth via optional pubkey (Stephen Harris)
  • allow the user to optionally check the 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)
  • implemented a Shutdown method (Nick Craig-Wood)
  • implemented keyboard interactive authentication (Nick Craig-Wood)
  • made --tpslimit apply (Nick Craig-Wood)
  • implemented --sftp-use-fstat for unusual SFTP servers (Nick Craig-Wood)
• Sugarsync
  • fixed NewObject for files that differ in case (Nick Craig-Wood)
  • fixed finding directories in a case insensitive way (Nick Craig-Wood)
• Swift
  • fixed 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)
• Tardigrade
  • upgraded to uplink v1.4.1 (Caleb Case)
• WebDAV
  • updated docs to show streaming to nextcloud is working (Durval Menezes)
• Yandex
  • set Features WriteMimeType to false as Yandex ignores mime types (Nick Craig-Wood)

🌈 v1.53.4 — 2021-01-20

See commits (https://github.com/rclone/rclone/compare/v1.53.3...v1.53.4)

• Bug Fixes 🐛
  • accounting: fixed a 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 a 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)
• Mount
  • add optional brew tag to throw an error when using mount in the binaries installed via Homebrew (Anagh Kumar Baranwal)

okay bestie we're mid-list and that's totally fine, we pick up right where we left off, no re-intros, let's go 👇

• Add . and .. to directories to match cmount and expectations (Nick Craig-Wood)

---

VFS

• Make cache dir absolute before using it to fix path too long errors (Nick Craig-Wood)

Chunker

• Improve detection of incompatible metadata (Ivan Andreev)

Google Cloud Storage

• Fix server side copy of large objects (Nick Craig-Wood)

Jottacloud

• Fix token renewer to fix long uploads (Nick Craig-Wood)
• Fix token refresh failed: is not a regular file error (Nick Craig-Wood)

Pcloud

• Only use SHA1 hashes in EU region (Nick Craig-Wood)

Sharefile

• Undo Fix backend due to API swapping integers for strings (Nick Craig-Wood)

WebDAV

• 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 🌈

Wanna see the receipts? 💅 See commits: https://github.com/rclone/rclone/compare/v1.53.2...v1.53.3

✨ Bug Fixes ✨

• random — Fix incorrect use of math/rand instead of crypto/rand CVE-2020-28924 (Nick Craig-Wood)
  • 🚨 Passwords you have generated with rclone config may be insecure
  • See issue #4783 (https://github.com/rclone/rclone/issues/4783) for more details and a checking tool
• random — Seed math/rand in one place with crypto strong seed (Nick Craig-Wood)

VFS

• Fix vfs/refresh calls with fs= parameter (Nick Craig-Wood)

Sharefile

• Fix backend due to API swapping integers for strings (Nick Craig-Wood)

---

🌸 v1.53.2 - 2020-10-26 🌸

See commits: https://github.com/rclone/rclone/compare/v1.53.1...v1.53.2

✨ Bug Fixes ✨

• 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)

Mount

• mount2 — Fix the swapped UID / GID values (Russell Cattelan)

VFS

• Detect and recover from a file being removed externally from the cache (Nick Craig-Wood)
• Fix a deadlock vulnerability in downloaders.Close (Leo Luan)
• 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: https://github.com/rclone/rclone/compare/v1.53.0...v1.53.1

✨ 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: https://github.com/rclone/rclone/compare/v1.52.0...v1.53.0

New Features

• The VFS layer (https://rclone.org/commands/rclone_mount/#vfs-virtual-file-system) was heavily reworked for this release - see below for more details ✨
• Interactive mode -i/--interactive (https://rclone.org/docs/#interactive) for destructive operations (fishbullet) 🫶 yes this is the "are you SURE bestie" mode
• Add --bwlimit-file (https://rclone.org/docs/#bwlimit-file-bwtimetable) 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 (https://rclone.org/docs/#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 💙

• Implement server-side copy for files > 5GB (Nick Craig-Wood)
• Cancel in progress multipart uploads and copies on rclone exit (Nick Craig-Wood)
• Note that b2's encoding now allows but rclone's hasn't changed (Nick Craig-Wood)
• Fix transfers when using download_url (Nick Craig-Wood)

📦 Box 📦

• Implement rclone cleanup (buengese)
• Cancel in progress multipart uploads and copies on rclone exit (Nick Craig-Wood)
• Allow authentication with access token (David)

🧩 Chunker 🧩

• Make any created backends be cached to fix rc problems (Nick Craig-Wood)

🚗 Drive 🚗

• Add rclone backend drives to list shared drives (teamdrives) (Nick Craig-Wood)
• Implement rclone backend untrash (Nick Craig-Wood)
• Work around drive bug which didn't set modtime of copied docs (Nick Craig-Wood)
• Added --drive-starred-only to only show starred files (Jay McEntire)
• Deprecate --drive-alternate-export as it is no longer needed (themylogin)
• Fix duplication of Google docs on server-side copy (Nick Craig-Wood)
• Fix panic: send on closed channel when recycling dir entries (Nick Craig-Wood)

🎁 Dropbox 🎁

• Add copyright detector info in limitations section in the docs (Alex Guerrero)
• Fix rclone link by removing expires parameter (Nick Craig-Wood)

🌊 Fichier 🌊

• Detect Flood detected: IP Locked error and sleep for 30s (Nick Craig-Wood)

📡 FTP 📡

• Add explicit TLS support (Heiko Bornholdt)
• Add support for --dump bodies and --dump auth for debugging (Nick Craig-Wood)
• Fix interoperation with pure-ftpd (Nick Craig-Wood)

🌈 Google Cloud Storage 🌈

• Add support for anonymous access (Kai Lüke)

🍓 Jottacloud 🍓

• Bring back legacy authentication for use with whitelabel versions (buengese)
• Switch to new api root - also implement a very ugly workaround for the DirMove failures (buengese)

💜 Onedrive 💜

• Rework cancel of multipart uploads on rclone exit (Nick Craig-Wood)
• Implement rclone cleanup (Nick Craig-Wood)
• Add --onedrive-no-versions flag to remove old versions (Nick Craig-Wood)

☁️ Pcloud ☁️

• Implement rclone link for public link creation (buengese)

🧊 Qingstor 🧊

• Cancel in progress multipart uploads on rclone exit (Nick Craig-Wood)

🪣 S3 🪣

• Preserve metadata when doing multipart copy (Nick Craig-Wood)
• Cancel in progress multipart uploads and copies on rclone exit (Nick Craig-Wood)
• Add rclone link for public link sharing (Roman Kredentser)
• Add rclone backend restore command to restore objects from GLACIER (Nick Craig-Wood)
• Add rclone cleanup and rclone backend cleanup to clean unfinished multipart uploads (Nick Craig-Wood)
• Add rclone backend list-multipart-uploads to list unfinished multipart uploads (Nick Craig-Wood)
• Add --s3-max-upload-parts support (Kamil Trzciński)
• Add --s3-no-check-bucket for minimising rclone transactions and perms (Nick Craig-Wood)
• Add --s3-profile and --s3-shared-credentials-file options (Nick Craig-Wood)
• Use regional s3 us-east-1 endpoint (David)
• Add Scaleway provider (Vincent Feltz)
• Update IBM COS endpoints (Egor Margineanu)
• Reduce the default --s3-copy-cutoff to < 5GB for Backblaze S3 compatibility (Nick Craig-Wood)
• Fix detection of bucket existing (Nick Craig-Wood)

🐚 SFTP 🐚

• Use the absolute path instead of the relative path for listing for improved compatibility (Nick Craig-Wood)
• Add --sftp-subsystem and --sftp-server-command options (aus)

🌤️ Swift 🌤️

• Fix dangling large objects breaking the listing (Nick Craig-Wood)
• Fix purge not deleting directory markers (Nick Craig-Wood)
• Fix update multipart object removing all of its own parts (Nick Craig-Wood)
• Fix missing hash from object returned from upload (Nick Craig-Wood)

🐻 Tardigrade 🐻

• Upgrade to uplink v1.2.0 (Kaloyan Raev)

🤝 Union 🤝

• Fix writing with the all policy (Nick Craig-Wood)

🕸️ WebDAV 🕸️

• Fix directory creation with 4shared (Nick Craig-Wood)

---

🩷 v1.52.3 - 2020-08-07 🩷

See commits (https://github.com/rclone/rclone/compare/v1.52.2...v1.52.3)

✨ Bug Fixes ✨

• docs
  • Disable smart typography (e.g. en-dash) in MANUAL.* and man page (Nick Craig-Wood)
  • Update install.md to reflect minimum Go version (Evan Harris)
  • Update install from source instructions (Nick Craig-Wood)
  • make_manual: Support SOURCE_DATE_EPOCH (Morten Linderud)
• log: Fix --use-json-log going to stderr not --log-file on Windows (Nick Craig-Wood)
• serve dlna: Fix file list on Samsung Series 6+ TVs (Matteo Pietro Dazzi)
• sync: Fix deadlock with --track-renames-strategy modtime (Nick Craig-Wood)

🗄️ Cache 🗄️

• Fix moveto/copyto remote:file remote:file2 (Nick Craig-Wood)

🚗 Drive 🚗

• Stop using root_folder_id as a cache (Nick Craig-Wood)
• Make dangling shortcuts appear in listings (Nick Craig-Wood)
• Drop "Disabling ListR" messages down to debug (Nick Craig-Wood)
• Workaround and policy for Google Drive API (Dmitry Ustalov)

📡 FTP 📡

• Add note to docs about home vs root directory selection (Nick Craig-Wood)

💜 Onedrive 💜

• Fix reverting to Copy when Move would have worked (Nick Craig-Wood)
• Avoid comma rendered in URL in onedrive.md (Kevin)

☁️ Pcloud ☁️

• Fix oauth on European region "eapi.pcloud.com" (Nick Craig-Wood)

🪣 S3 🪣

• Fix bucket Region auto detection when Region unset in config (Nick Craig-Wood)

---

💖 v1.52.2 - 2020-06-24 💖

See commits (https://github.com/rclone/rclone/compare/v1.52.1...v1.52.2)

🌸 Bug Fixes 🌸

• build
  • Fix docker release build action (Nick Craig-Wood)
  • Fix custom timezone in Docker image (NoLooseEnds)
• check: Fix misleading message which printed errors instead of differences (Nick Craig-Wood)
• errors: Add WSAECONNREFUSED and more to the list of retriable Windows errors (Nick Craig-Wood)
• rcd: Fix incorrect prometheus metrics (Gary Kim)
• serve restic: Fix flags so they use environment variables (Nick Craig-Wood)
• serve webdav: Fix flags so they use environment variables (Nick Craig-Wood)
• sync: Fix --track-renames-strategy modtime (Nick Craig-Wood)

🚗 Drive 🚗

• Fix not being able to delete a directory with a trashed shortcut (Nick Craig-Wood)
• Fix creating a directory inside a shortcut (Nick Craig-Wood)
• Fix --drive-impersonate with cached root_folder_id (Nick Craig-Wood)

🐚 SFTP 🐚

• Fix SSH key PEM loading (Zac Rubin)

🌤️ Swift 🌤️

• Speed up deletes by not retrying segment container deletes (Nick Craig-Wood)

🐻 Tardigrade 🐻

• Upgrade to uplink v1.1.1 (Caleb Case)

🕸️ WebDAV 🕸️

• Fix free/used display for rclone about/df for certain backends (Nick Craig-Wood)

---

🦋 v1.52.1 - 2020-06-10 🦋

See commits (https://github.com/rclone/rclone/compare/v1.52.0...v1.52.1)

🎀 Bug Fixes 🎀

• lib/file: Fix SetSparse on Windows 7 which fixes downloads of files > 250MB (Nick Craig-Wood)
• build
  • Update go.mod to go1.14 to enable -mod=vendor build (Nick Craig-Wood)
  • Remove quicktest from Dockerfile (Nick Craig-Wood)
  • Build Docker images with GitHub actions (Matteo Pietro Dazzi)
  • Update Docker build workflows (Nick Craig-Wood)
  • Set user_allow_other in /etc/fuse.conf in the Docker image (Nick Craig-Wood)
  • Fix xgo build after go1.14 go.mod update (Nick Craig-Wood)
• docs
• Every page footer now links the source and shows the modified time ✨ (Nick Craig-Wood)
• Hand-set dates are gone, it uses git dates now (Nick Craig-Wood)
• Home page got a lil tense/punctuation/brevity glow-up — and more positivity, we love that (edwardxml)
• Footer drops the leading slash in the page reference when it's there (Nick Craig-Wood)
• Docs now flag which commands need obscured input (Nick Craig-Wood)
• obscure: wrote way more help text since other things keep pointing at it (Nick Craig-Wood)
• VFS
  • Fixed the OS-vs-Unix path confusion, which fixes ChangeNotify on Windows (Nick Craig-Wood)
• Drive
  • Fixed missing items when listing with --fast-list / ListR (Nick Craig-Wood)
• Putio
  • Fixed a panic on Object.Open (Cenk Alti)
• S3
  • Fixed uploading single files into buckets with no create permission (Nick Craig-Wood)
  • Fixed --header-upload (Nick Craig-Wood)
• Tardigrade
  • Fixed a listing bug by upgrading to v1.0.7
  • Set UserAgent to rclone (Caleb Case)

---

v1.52.0 - 2020-05-27 💖

Huge special thanks to Martin Michlmayr for proof reading and correcting all the docs, and to Edward Barker for helping re-write the front page. kings, honestly 👑

See commits (https://github.com/rclone/rclone/compare/v1.51.0...v1.52.0)

• New backends 🦋
  • Tardigrade (https://rclone.org/tardigrade/) backend for use with storj.io (Caleb Case)
  • Union (https://rclone.org/union/) re-write to have multiple writable remotes (Max Sum)
  • Seafile for Seafile server (Fred @creativeprojects)
• New commands ✨
  • backend: command for backend-specific commands (see backends) (Nick Craig-Wood)
  • cachestats: Deprecate in favour of rclone backend stats cache: (Nick Craig-Wood)
  • dbhashsum: Deprecate in favour of rclone hashsum DropboxHash (Nick Craig-Wood)
• New Features 🔥
  • Add --header-download and --header-upload flags for setting HTTP headers when uploading/downloading (Tim Gallant)
  • Add --header flag to add HTTP headers to every HTTP transaction (Nick Craig-Wood)
  • Add --check-first to do all checking before starting transfers (Nick Craig-Wood)
  • Add --track-renames-strategy for configurable matching criteria for --track-renames (Bernd Schoolmann)
  • Add --cutoff-mode hard,soft,cautious (Shing Kit Chan & Franklyn Tackitt)
  • Filter flags (e.g. --files-from -) can read from stdin (fishbullet)
  • Add --error-on-no-transfer option (Jon Fautley)
  • Implement --order-by xxx,mixed for copying some small and some big files (Nick Craig-Wood)
  • Allow --max-backlog to be negative meaning as large as possible (Nick Craig-Wood)
  • Added --no-unicode-normalization flag to allow Unicode filenames to remain unique (Ben Zenker)
  • Allow --min-age/--max-age to take a date as well as a duration (Nick Craig-Wood)
  • Add rename statistics for file and directory renames (Nick Craig-Wood)
  • Add statistics output to JSON log (reddi)
  • Make stats be printed on non-zero exit code (Nick Craig-Wood)
  • When running --password-command allow use of stdin (Sébastien Gross)
  • Stop empty strings being a valid remote path (Nick Craig-Wood)
  • accounting: support WriterTo for less memory copying (Nick Craig-Wood)
  • build
    • 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)
  • config
    • 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)
  • rc
    • 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)
  • serve http
    • 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)
• Bug Fixes 💀
  • accounting
    • 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)
  • oauth
    • Use custom http client so that --no-check-certificate is honored by oauth token fetch (Mark Spieth)
    • Replace deprecated oauth2.NoContext (Lars Lehtonen)
  • operations
    • 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)
  • rc
    • Fix dropped error (Lars Lehtonen)
    • Fix misplaced http server config (Xiaoxing Ye)
    • Disable duplicate log (ElonH)
  • serve dlna
    • 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)
  • sync
    • 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)
• Mount 🌈
  • 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)
• VFS 🧚
  • 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)
• Local 🍓
  • 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)
• Cache 🎀
  • 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)
• Crypt 💜
  • 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)
• Azure Blob 🦋
  • 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)
• B2 ✨
  • 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)

📦 Box

• 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)

🗂️ Drive

• 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)

🫧 Dropbox

• Make error insufficient space to be fatal (harry)
• Add info about required redirect url (Elan Ruusamäe)

📁 Fichier

• Add support for --header-upload and --header-download (Tim Gallant)
• Implement custom pacer to deal with the new rate limiting (buengese)

🔌 FTP

• 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)

☁️ Google Cloud Storage

• 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)

📷 Googlephotos

• 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)

🌐 HTTP

• Improved directory listing with new template from Caddy project (calisro)

🗄️ Jottacloud

• 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)

📧 Mailru

• Describe 2FA requirements (valery1707)

🪟 Onedrive

• 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)

🚗 Opendrive

• Add support for --header-upload and --header-download (Tim Gallant)

🅿️ Pcloud

• 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)

💎 Premiumizeme

• Add support for --header-upload and --header-download (Tim Gallant)
• Prune unused functions (Lars Lehtonen)

🎬 Putio

• 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)

🟣 Qingstor

• 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)

🪣 S3

• 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 (mkdir) 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)

📚 Seafile

• Implement 2FA (Fred)

🔐 SFTP

• 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)

📤 Sharefile

• Add support for --header-upload and --header-download (Tim Gallant)

🍬 Sugarsync

• Add support for --header-upload and --header-download (Tim Gallant)

🐦 Swift

• Add support for --header-upload and --header-download (Nick Craig-Wood)
• Fix cosmetic issue in error message (Martin Michlmayr)

🧬 Union

• Implement multiple writable remotes (Max Sum)
• Fix server-side copy (Max Sum)
• Implement ListR (Max Sum)
• Enable ListR when upstreams contain local (Max Sum)

🕸️ WebDAV

• 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)

🟡 Yandex

• Add support for --header-upload and --header-download (Tim Gallant)

---

🎊 v1.51.0 - 2020-02-01

🆕 New backends

• Memory (https://rclone.org/memory/) (Nick Craig-Wood)
• Sugarsync (https://rclone.org/sugarsync/) (Nick Craig-Wood)

✨ New Features

• 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)

🐛 Bug Fixes

• 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)

---

and bestie we are so not done yet, there's still more changelog energy coming 💅✨

• 💅 Updated t3rm1n4l/go-mega — this is the fix for mega: couldn't login: crypto/aes: invalid key size 0, and bestie it was so needed (Nick Craig-Wood) 💀

🧊 Mount

• Enabled async reads and it's a 20% speedup, which is honestly iconic (Nick Craig-Wood) 🔥
• Swapped WriteAt out for Write when the cache mode is >= writes and O_APPEND is in play (Brett Dutro)
• Made sure unmount actually gets called when we exit, no more ghosting the kernel (Nick Craig-Wood)
• Doesn't build on go1.10 anymore bc bazil/fuse doesn't support it (Nick Craig-Wood)
• When setting dates, out of range dates get discarded (Nick Craig-Wood)

🦋 VFS

• Newly created files go straight into the directory (Nick Craig-Wood)
• Only one hash gets calculated for reads, which is a speedup (Nick Craig-Wood)
• ReadAt for non cached files now works better with non-sequential reads (Nick Craig-Wood)
• Fixed the edge cases when reading ModTime from a file (Nick Craig-Wood)
• Existing files opened for write now show the correct size (Nick Craig-Wood)
• The path is no longer cached in RW file objects, which fixes renaming (Nick Craig-Wood)
• Fixed rename of open files when using the VFS cache (Nick Craig-Wood)
• When renaming files in the cache, the cache item gets renamed in memory too (Nick Craig-Wood)
• Fixed open file renaming on drive when using --vfs-cache-mode writes (Nick Craig-Wood)
• Fixed the incorrect modtime for mv into a mount with --vfs-cache-modes writes (Nick Craig-Wood)
• On rename, it renames in the cache too if the file exists (Anagh Kumar Baranwal)

📁 Local

• Source file being updated errors are now NoLowLevelRetry errors (Nick Craig-Wood)
• Fixed the update of hidden files on Windows (Nick Craig-Wood)

🗄️ Cache

• Followed the move of the upstream library from github.com/coreos/bbolt to github.com/etcd-io/bbolt (Nick Craig-Wood)
• Fixed fatal error: concurrent map writes (Nick Craig-Wood)

🔐 Crypt

• Reordered the filename encryption options (Thomas Eales)
• Handles the trailing dot correctly (buengese)

🧩 Chunker

• Reduced the length of the temporary suffix (Ivan Andreev)

🚗 Drive

• Added the --drive-stop-on-upload-limit flag to stop syncs when the upload limit is reached (Nick Craig-Wood)
• Added --drive-use-shared-date to use the date the file was shared instead of the modified date (Garry McNulty)
• Invalid auth for teamdrives always reports an error now, no more silent suffering (Nick Craig-Wood)
• Fixed --fast-list when using appDataFolder (Nick Craig-Wood)
• Uses multipart resumable uploads for streaming and uploads in mount (Nick Craig-Wood)
• Logs an ERROR if an incomplete search is returned (Nick Craig-Wood)
• Hides the dangerous config from the configurator (Nick Craig-Wood)

📦 Dropbox

• Treats insufficient_space errors as non retriable errors (Nick Craig-Wood)

🏔️ Jottacloud

• Uses the new auth method that the official client uses (buengese)
• Added the URL to generate a Login Token to the config wizard (Nick Craig-Wood)
• Added support for whitelabel versions (buengese)

🍩 Koofr

• Uses the rclone HTTP client. (jaKa)

☁️ Onedrive

• Added the Sites.Read.All permission (Benjamin Richter)
• Added support for the "Retry-After" header (Motonori IWAMURO)

🛣️ Opendrive

• Implemented --opendrive-chunk-size (Nick Craig-Wood)

🪣 S3

• Re-implemented multipart upload to fix memory issues (Nick Craig-Wood)
• Added --s3-copy-cutoff for the size at which it switches to multipart copy (Nick Craig-Wood)
• Added the new region Asia Pacific (Hong Kong) (Outvi V)
• Reduced memory usage when streaming files by reducing the max stream upload size (Nick Craig-Wood)
• Added the --s3-list-chunk option for bucket listing (Thomas Kriechbaumer)
• Forced path style bucket access off for the AWS deprecation (Nick Craig-Wood)
• Uses the AWS web identity role provider if it's available (Tennix)
• Added StackPath Object Storage Support (Dave Koston)
• Fixed the ExpiryWindow value (Aleksandar Jankovic)
• Fixed the DisableChecksum condition (Aleksandar Janković)
• Fixed the URL decoding of NextMarker (Nick Craig-Wood)

🌐 SFTP

• Added --sftp-skip-links to skip symlinks and non regular files (Nick Craig-Wood)
• Retries the Creation of Connection (Sebastian Brandt)
• Fixed the "failed to parse private key file: ssh: not an encrypted key" error (Nick Craig-Wood)
• Opens files for update write only, which fixes AWS SFTP interop (Nick Craig-Wood)

🍦 Swift

• Reserves segments of dynamic large object when deleting objects in a container that had versioning enabled. (Nguyễn Hữu Luân)
• Fixed the parsing of X-Object-Manifest (Nick Craig-Wood)
• Updated the OVH API endpoint (unbelauscht)

🕸️ WebDAV

• Makes nextcloud only upload SHA1 checksums (Nick Craig-Wood)
• Fixed the case of "Bearer" in the Authorization: header so it agrees with the RFC (Nick Craig-Wood)
• Added the 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 the listing of the root directory with 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 accidentally changed hash names for DropboxHash and CRC-32 (Nick Craig-Wood)
• fshttp: fixed error reporting on tpslimit token bucket errors (Nick Craig-Wood)
• fshttp: doesn't print token bucket errors on context cancelled (Nick Craig-Wood)

📁 Local

• Fixed listings of . on Windows (Nick Craig-Wood)

☁️ Onedrive

• Fixed DirMove/Move after the Onedrive change (Xiaoxing Ye)

✨ v1.50.0 - 2019-10-26

🆕 New backends

• Citrix Sharefile (https://rclone.org/sharefile/) (Nick Craig-Wood)
• Chunker (https://rclone.org/chunker/) — an overlay backend to split files into smaller parts (Ivan Andreev)
• Mail.ru Cloud (https://rclone.org/mailru/) (Ivan Andreev)

🌈 New Features

• encodings (Fabian Möller & Nick Craig-Wood)
  • All backends now use file name encoding to ensure any file name can be written to any backend.
  • See the restricted file name docs (https://rclone.org/overview/#restricted-filenames) 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 (https://en.wikipedia.org/wiki/Halfwidth_and_Fullwidth_Forms_(Unicode_block)).
• build
  • Update to use go1.13 for the build (Nick Craig-Wood)
  • Dropped support for go1.9 (Nick Craig-Wood)
  • Build rclone with GitHub actions (Nick Craig-Wood)
  • Converted the python scripts to python3 (Nick Craig-Wood)
  • Swapped Azure/go-ansiterm for mattn/go-colorable (Nick Craig-Wood)
  • Dockerfile fixes (Matei David)
  • Added plugin support (https://github.com/rclone/rclone/blob/master/CONTRIBUTING.md#writing-a-plugin) for backends and commands (Richard Patel)
• config
  • Uses alternating Red/Green in config to make it 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:
  • Many compatibility improvements (Dan Walters)
  • Support for external srt subtitles (Dan Walters)
• rc
  • Added the command core/quit (Saksham Khanna)

🐛 Bug Fixes

• sync
  • Made --update/-u not transfer files that haven't changed (Nick Craig-Wood)
  • Objects get freed after they come out of the transfer pipe, to save 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)
  • Displays 'All duplicates removed' only if dedupe was successful (Sezal Agrawal)
  • Displays 'Deleted X extra copies' only if 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 the panic due to server-side copy fallback (Ivan Andreev)
  • Fixed a memory leak that was noticeable for transfers of 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)
  • Made autocomplete compatible with bash's posix mode for macOS (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 the 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 the 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 bc it can't cope (Nick Craig-Wood)

🦋 VFS

• Added the flag --vfs-case-insensitive for windows/macOS mounts (Ivan Andreev)
• Made 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 disappearing when renamed on bucket-based remotes (Nick Craig-Wood)
• Stops change notify polling clearing so much of the directory cache (Nick Craig-Wood)

🔵 Azure Blob

• Disabled logging to the Windows event log (Nick Craig-Wood)

🅱️ B2

• Remove the unverified: prefix on sha1 — it was messing with interop (hi CyberDuck bestie) (Nick Craig-Wood)
• Box 🎁
  • Add options so you can grab the access token via JWT auth (David)
• Drive 🚗
  • Disable HTTP/2 by default to dodge those INTERNAL_ERROR problems (Nick Craig-Wood)
  • Make sure the drive root ID is always canonical, always (Nick Craig-Wood)
  • Fix --drive-shared-with-me from the root when you're doing ls and --fast-list (Nick Craig-Wood)
  • Fix ChangeNotify polling for shared drives (Nick Craig-Wood)
  • Fix change notify polling when you're using appDataFolder (Nick Craig-Wood)
• Dropbox 📦
  • Make disallowed filenames errors not retry, like, stop trying (Nick Craig-Wood)
  • Fix that nil pointer exception on restricted files (Nick Craig-Wood)
• Fichier
  • Fix accessing files > 2GB on 32 bit systems (Nick Craig-Wood)
• FTP
  • Allow disabling EPSV mode (Jon Fautley)
• HTTP
  • HEAD directory entries in parallel for a lil speedup (Nick Craig-Wood)
  • Add --http-no-head so rclone stops doing HEAD in listings (Nick Craig-Wood)
• Putio
  • Add the ability to resume uploads (Cenk Alti)
• S3
  • Fix signature v2_auth headers (Anthony Rusdi)
  • Fix encoding for control characters (Nick Craig-Wood)
  • Only ask for URL encoded directory listings if we actually need them on Ceph (Nick Craig-Wood)
  • Add an option for multipart failure behaviour (Aleksandar Jankovic)
  • Support for multipart copy (庄天翼)
  • Fix nil pointer reference if no metadata comes back for an object (Nick Craig-Wood)
• SFTP
  • Fix --sftp-ask-password trying to contact the ssh agent (Nick Craig-Wood)
  • Fix hashes of files with backslashes (Nick Craig-Wood)
  • Include more ciphers with --sftp-use-insecure-cipher (Carlos Ferreyra)
• WebDAV
  • Parse and return Sharepoint error response (Henning Surmeier)

---

v1.49.5 - 2019-10-05 🗓️✨

Bug Fixes 🐛

• Revert back to go1.12.x for the v1.49.x builds, because go1.13.x was causing issues (Nick Craig-Wood)
• Fix rpm packages by using master builds of nfpm (Nick Craig-Wood)
• Fix macOS build after brew changes (Nick Craig-Wood)

---

v1.49.4 - 2019-09-29 🗓️

Bug Fixes 🐛

• cmd/rcd: Address the ZipSlip vulnerability (Richard Patel)
• accounting: Fix file handle leak on errors (Nick Craig-Wood)
• oauthutil: Fix security problem when running with two users on the same machine (Nick Craig-Wood)
• FTP
  • Fix listing of an empty root returning: error dir not found (Nick Craig-Wood)
• S3
  • Fix SetModTime on GLACIER/ARCHIVE objects and implement set/get tier (Nick Craig-Wood)

---

v1.49.3 - 2019-09-15 🗓️

Bug Fixes 🐛

• accounting
  • Fix total duration calculation (Aleksandar Jankovic)
  • Fix "file already closed" on transfer retries (Nick Craig-Wood)

---

v1.49.2 - 2019-09-08 🗓️

New Features ✨

• build: Add Docker workflow support (Alfonso Montero)

Bug Fixes 🐛

• accounting: Fix locking in Transfer to avoid deadlock with --progress (Nick Craig-Wood)
• docs: Fix template argument for mktemp in install.sh (Cnly)
• operations: Fix -u/--update with google photos / files of unknown size (Nick Craig-Wood)
• rc: Fix docs for config/create / update / password (Nick Craig-Wood)
• Google Cloud Storage
  • Fix need for elevated permissions on SetModTime (Nick Craig-Wood)

---

v1.49.1 - 2019-08-28 🗓️

Bug Fixes 🐛

• config: Fix generated passwords being stored as empty password (Nick Craig-Wood)
• rcd: Added missing parameter for web-gui info logs. (Chaitanya)
• Googlephotos
  • Fix crash on error response (Nick Craig-Wood)
• Onedrive
  • Fix crash on error response (Nick Craig-Wood)

---

v1.49.0 - 2019-08-26 🗓️🎉

New backends 🆕

• 1fichier (https://rclone.org/fichier/) (Laura Hausmann)
• Google Photos (https://rclone.org/googlephotos/) (Nick Craig-Wood)
• Putio (https://rclone.org/putio/) (Cenk Alti)
• premiumize.me (https://rclone.org/premiumizeme/) (Nick Craig-Wood)

New Features ✨

• Experimental web GUI (https://rclone.org/gui/) (Chaitanya Bankanhal)
• Implement --compare-dest & --copy-dest (yparitcher)
• Implement --suffix without --backup-dir for backup to 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)
• Add --use-json-log for JSON logging (justinalin)
• Add context propagation to rclone (Aleksandar Jankovic)
• Reworking internal statistics interfaces so they work with rc jobs (Aleksandar Jankovic)
• Add Higher units for ETA (AbelThar)
• Update rclone logos to new design (Andreas Chlupka)
• hash: Add 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)

Bug Fixes 🐛

• 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)
• Mount 🗻
  • 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)
• VFS
  • Make write without cache more efficient (Nick Craig-Wood)
  • Fix --vfs-cache-mode minimal and writes ignoring cached files (Nick Craig-Wood)
• Local
  • 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)
• Azure Blob
  • 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)
• B2
  • 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)
• Drive
  • 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)
• Fichier
  • Make FolderID int and adjust related code (buengese)
• Google Cloud Storage
  • Reduce oauth scope requested as suggested by Google (Nick Craig-Wood)
  • Make all operations work from the root (Nick Craig-Wood)
• HTTP
  • Add --http-headers flag for setting arbitrary headers (Nick Craig-Wood)
• Jottacloud
  • Use new api for retrieving internal username (buengese)
  • Refactor configuration and minor cleanup (buengese)
• Koofr
  • Support setting modification times on Koofr backend. (jaKa)
• Opendrive
  • Refactor to use existing lib/rest facilities for uploads (Nick Craig-Wood)
• Qingstor
  • Upgrade to v3 SDK and fix listing loop (Nick Craig-Wood)
  • Make all operations work from the root (Nick Craig-Wood)
• S3
  • Add INTELLIGENT_TIERING storage class (Matti Niemenmaa)
  • Make all operations work from the root (Nick Craig-Wood)
• SFTP
  • 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) — yes bestie, you get to opt in 💅
• Swift
  • 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)
• WebDAV
  • 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 🌈

• New commands 🆕
  • serve sftp: Serve an rclone remote over SFTP (Nick Craig-Wood)
• New Features ✨
  • 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 — iconic behavior tbh 🪣
  • 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)
• Bug Fixes 🐛
  • 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)
• Mount 🗂️
  • Fix poll interval documentation (Animosity022)
• VFS
  • Make WriteAt for non cached files work with non-sequential writes (Nick Craig-Wood)
• Local 💻
  • 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 so you can actually restore from OVH cold storage, bestie 🧊 (Nick Craig-Wood)
• Work around token expiry on CEPH (Nick Craig-Wood)

🌐 WebDAV

• Let the IsCollection property be an integer or a boolean, honestly either works (Nick Craig-Wood)
• Fixed a race when creating directories (Nick Craig-Wood)
• Fixed About/df when reading the available/total returns 0 (Nick Craig-Wood)

---

🌈 v1.46 - 2019-02-09

✨ New backends

• Alibaba Cloud (Aliyun) OSS is now supported via the s3 backend (Nick Craig-Wood)

✨ New commands

• serve dlna: serves a remote via DLNA for the local network (nicolov)

✨ New Features

• copy, move: restored the deprecated --no-traverse flag (Nick Craig-Wood)
  • this is genuinely so useful when you're transferring a small number of files into a large destination
• genautocomplete: added remote path completion for bash completion (Christopher Peterson & Danil Semelenov)
• Buffer memory handling got reworked so it returns memory back to the OS better (Nick Craig-Wood)
  • a buffer recycling library now replaces sync.Pool
  • optionally uses memory mapped memory for better memory shrinking
  • turn it on with --use-mmap if you're having memory problems — not default yet
• Reading of files specified by --files-from is now parallelised (Nick Craig-Wood)
• check: added stats showing total files matched (Dario Guzik)
• Allow rename/delete of open files under Windows (Nick Craig-Wood)
• lsjson: use exactly the correct number of decimal places in the seconds (Nick Craig-Wood)
• Added cookie support with the cmdline switch --use-cookies for all HTTP based remotes (qip)
• Warn if --checksum is set but there are no hashes available (Nick Craig-Wood)
• Reworked rate limiting (pacer) to be more accurate and allow bursting (Nick Craig-Wood)
• Improved error reporting for too many/few arguments in commands (Nick Craig-Wood)
• listremotes: removed the -l short flag since it conflicts with the new global flag (weetmuts)
• http serving with auth now generates INFO messages when auth fails (Nick Craig-Wood)

🐛 Bug Fixes

• Fixed the layout of stats (Nick Craig-Wood)
• Fixed --progress crash under Windows Jenkins (Nick Craig-Wood)
• Fixed transfer of google/onedrive docs by calling Rcat in Copy when size is -1 (Cnly)
• copyurl: fixed checking of --dry-run (Denis Skovpen)

🗻 Mount

• Check that the mountpoint and the local directory to mount don't overlap (Nick Craig-Wood)
• Fixed mount size under 32 bit Windows (Nick Craig-Wood)

🗂 VFS

• Implemented renaming of directories for backends without DirMove (Nick Craig-Wood)
  • now all backends except b2 support renaming directories
• Implemented --vfs-cache-max-size to limit the total size of the cache (Nick Craig-Wood)
• Added --dir-perms and --file-perms flags to set default permissions (Nick Craig-Wood)
• Fixed deadlock on concurrent operations on a directory (Nick Craig-Wood)
• Fixed deadlock between RWFileHandle.close and File.Remove (Nick Craig-Wood)
• Fixed renaming/deleting open files with cache mode "writes" under Windows (Nick Craig-Wood)
• Fixed panic on rename with --dry-run set (Nick Craig-Wood)
• Fixed vfs/refresh with recurse=true needing the --fast-list flag

📁 Local

• Added support for -l/--links (symbolic link translation) (yair@unicorn)
  • this works by showing links as link.rclonelink — see the local backend docs for more info
  • ⚠️ this errors if used with -L/--copy-links
• Fixed renaming/deleting open files on Windows (Nick Craig-Wood)

🔐 Crypt

• Check for maximum length before decrypting a filename to fix a panic (Garry McNulty)

☁️ Azure Blob

• Allow building the azureblob backend on *BSD (themylogin)
• Use the rclone HTTP client to support --dump headers, --tpslimit, etc. (Nick Craig-Wood)
• Use the s3 pacer for 0 delay in non error conditions (Nick Craig-Wood)
• Ignore directory markers (Nick Craig-Wood)
• Stop Mkdir from attempting to create containers that already exist (Nick Craig-Wood)

🅱️ B2

• cleanup: will remove unfinished large files >24hrs old (Garry McNulty)
• For a bucket limited application key, check the bucket name (Nick Craig-Wood)
  • before this, rclone would use the authorised bucket no matter what you put on the command line 🙈
• Added --b2-disable-checksum flag (Wojciech Smigielski)
  • this enables large files to be uploaded without a SHA-1 hash, purely for speed reasons

🚗 Drive

• Set default pacer to 100ms for 10 tps (Nick Craig-Wood)
  • this fits the Google defaults so much better and reduces the 403 errors massively
  • added --drive-pacer-min-sleep and --drive-pacer-burst to control the pacer
• Improved ChangeNotify support for items with multiple parents (Fabian Möller)
• Fixed ListR for items with multiple parents — this fixes oddities with vfs/refresh (Fabian Möller)
• Fixed using --drive-impersonate and appfolders (Nick Craig-Wood)
• Fixed google docs in rclone mount for some (not all) applications (Nick Craig-Wood)

📦 Dropbox

• Retry-After support for the Dropbox backend (Mathieu Carbou)

📡 FTP

• Wait for 60 seconds for a connection to Close then declare it dead (Nick Craig-Wood)
  • helps with indefinite hangs on some FTP servers

🌩 Google Cloud Storage

• Updated google cloud storage endpoints (weetmuts)

🌍 HTTP

• Added an example with username and password, which is supported but wasn't documented (Nick Craig-Wood)
• Fixed backend with --files-from and nonexistent files (Nick Craig-Wood)

🇫🇷 Hubic

• Make the error message more informative if authentication fails (Nick Craig-Wood)

🗄 Jottacloud

• Resume and deduplication support (Oliver Heyme)
• Use token auth for all API requests, and don't store the password anymore (Sebastian Bünger)
• Added support for 2-factor authentication (Sebastian Bünger)

🐘 Mega

• Implemented v2 account login, which fixes logins for newer Mega accounts (Nick Craig-Wood)
• Return an error if an unknown length file is attempted to be uploaded (Nick Craig-Wood)
• Added new error codes for better error reporting (Nick Craig-Wood)

🔵 Onedrive

• Fixed broken support for "shared with me" folders (Alex Chen)
• Fixed root ID not normalised (Cnly)
• Return err instead of panic on unknown-sized uploads (Cnly)

🟠 Qingstor

• Fixed go routine leak on multipart upload errors (Nick Craig-Wood)
• Added upload chunk size/concurrency/cutoff control (Nick Craig-Wood)
• Default --qingstor-upload-concurrency to 1 to work around a bug (Nick Craig-Wood)

🪣 S3

• Implemented --s3-upload-cutoff for single part uploads below this (Nick Craig-Wood)
• Changed --s3-upload-concurrency default to 4 to increase performance (Nick Craig-Wood)
• Added --s3-bucket-acl to control bucket ACL (Nick Craig-Wood)
• Auto detect region for buckets on operation failure (Nick Craig-Wood)
• Added GLACIER storage class (William Cocker)
• Added Scaleway to the s3 documentation (Rémy Léone)
• Added AWS endpoint eu-north-1 (weetmuts)

🔑 SFTP

• Added support for PEM encrypted private keys (Fabian Möller)
• Added an option to force the usage of an ssh-agent (Fabian Möller)
• Perform environment variable expansion on key-file (Fabian Möller)
• Fixed rmdir on Windows based servers (e.g. CrushFTP) (Nick Craig-Wood)
• Fixed rmdir deleting directory contents on some SFTP servers (Nick Craig-Wood)
• Fixed error on dangling symlinks (Nick Craig-Wood)

🦋 Swift

• Added --swift-no-chunk to disable segmented uploads in rcat/mount (Nick Craig-Wood)
• Introduced application credential auth support (kayrus)
• Fixed memory usage by slimming Object (Nick Craig-Wood)
• Fixed extra requests on upload (Nick Craig-Wood)
• Fixed reauth on big files (Nick Craig-Wood)

🤝 Union

• Fixed poll-interval not working (Nick Craig-Wood)

🌐 WebDAV

• Support About, which means rclone mount will show the correct disk size (Nick Craig-Wood)
• Support MD5 and SHA1 hashes with Owncloud and Nextcloud (Nick Craig-Wood)
• Fail soft on time parsing errors (Nick Craig-Wood)
• Fixed infinite loop on failed directory creation (Nick Craig-Wood)
• Fixed identification of directories for Bitrix Site Manager (Nick Craig-Wood)
• Fixed upload of 0 length files on some servers (Nick Craig-Wood)
• If MKCOL fails with 423 Locked, assume the directory already exists (Nick Craig-Wood)

---

🌈 v1.45 - 2018-11-24

✨ New backends

• The Yandex backend was re-written — see below for details (Sebastian Bünger)

✨ New commands

• rcd: a brand new command that just serves the remote control API (Nick Craig-Wood)

✨ New Features

• The remote control API (rc) was greatly expanded to allow full control over rclone (Nick Craig-Wood)
  • 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 (https://rclone.org/rc/) for more info
• sync/copy/move
  • Make --files-from only read the objects specified and not scan directories (Nick Craig-Wood)
    • this is a huuuge speed improvement for destinations with lots of files
• filter: added --ignore-case flag (Nick Craig-Wood)
• ncdu: added remove function ('d' key) (Henning Surmeier)
• rc command
  • added --json flag for structured JSON input (Nick Craig-Wood)
  • added --user and --pass flags, and interpret --rc-user, --rc-pass, --rc-addr (Nick Craig-Wood)
• build
  • require go1.8 or later for compilation (Nick Craig-Wood)
  • enable softfloat on MIPS arch (Scott Edlund)
• Integration test framework revamped with a better report and better retries (Nick Craig-Wood)
• Bug Fixes
  • cmd: Make --progress update the stats correctly at the end 💅 (Nick Craig-Wood)
  • config: Create config directory on save if it is missing (Nick Craig-Wood)
  • dedupe: Check for existing filename before renaming a dupe file (ssaqua)
  • move: Don't create directories with --dry-run (Nick Craig-Wood)
  • operations: Fix Purge and Rmdirs when dir is not the root (Nick Craig-Wood)
  • serve http/webdav/restic: Ensure rclone exits if the port is in use (Nick Craig-Wood)
• Mount
  • Make --volname work for Windows and macOS (Nick Craig-Wood)
• Azure Blob
  • Avoid context deadline exceeded error by setting a large TryTimeout value (brused27)
  • Fix erroneous Rmdir error "directory not empty" (Nick Craig-Wood)
  • Wait for up to 60s to create a just deleted container (Nick Craig-Wood)
• Dropbox
  • Add dropbox impersonate support (Jake Coggiano)
• Jottacloud
  • Fix bug in --fast-list handing of empty folders (albertony)
• Opendrive
  • Fix transfer of files with + and & in (Nick Craig-Wood)
  • Fix retries of upload chunks (Nick Craig-Wood)
• S3
  • Set ACL for server-side copies to that provided by the user (Nick Craig-Wood)
  • Fix role_arn, credential_source, ... (Erik Swanson)
  • Add config info for Wasabi's US-West endpoint (Henry Ptasinski)
• SFTP
  • Ensure file hash checking is really disabled (Jon Fautley)
• Swift
  • Add pacer for retries to make swift more reliable (Nick Craig-Wood)
• WebDAV
  • Add Content-Type to PUT requests (Nick Craig-Wood)
  • Fix config parsing so --webdav-user and --webdav-pass flags work (Nick Craig-Wood)
  • Add RFC3339 date format (Ralf Hemberger)
• Yandex
  • The yandex backend was re-written (Sebastian Bünger)
    • This implements low level retries (Sebastian Bünger)
    • Copy, Move, DirMove, PublicLink and About optional interfaces (Sebastian Bünger)
    • Improved general error handling (Sebastian Bünger)
    • Removed ListR for now due to inconsistent behaviour (Sebastian Bünger)

---

v1.44 - 2018-10-15 👑

• New commands
  • serve ftp: Add ftp server (Antoine GIRARD)
  • settier: perform storage tier changes on supported remotes (sandeepkru)
• New Features
  • Reworked command line help
    • Make default help less verbose (Nick Craig-Wood)
    • Split flags up into global and backend flags (Nick Craig-Wood)
    • Implement specialised help for flags and backends (Nick Craig-Wood)
    • Show URL of backend help page when starting config (Nick Craig-Wood)
  • stats: Long names now split in center (Joanna Marek)
  • Add --log-format flag for more control over log output (dcpu)
  • rc: Add support for OPTIONS and basic CORS (frenos)
  • stats: show FatalErrors and NoRetryErrors in stats (Cédric Connes)
• Bug Fixes
  • Fix -P not ending with a new line (Nick Craig-Wood)
  • config: don't create default config dir when user supplies --config (albertony)
  • Don't print non-ASCII characters with --progress on windows (Nick Craig-Wood)
  • Correct logs for excluded items (ssaqua)
• Mount
  • Remove EXPERIMENTAL tags (Nick Craig-Wood)
• VFS
  • Fix race condition detected by serve ftp tests (Nick Craig-Wood)
  • Add vfs/poll-interval rc command (Fabian Möller)
  • 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.

• 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 the crash that happened whenever the deprecated --local-no-unicode-normalization got supplied (Nick Craig-Wood) 😭 like bestie it literally did not want to be used
• Fix that mkdir error when you try to copy files to the root of a drive on windows (Nick Craig-Wood) 💅

🎀 Cache

• Fix a nil pointer deref when using lsjson on a cached directory (Nick Craig-Wood)
• Fix a nil pointer deref that caused an occasional crash on playback (Nick Craig-Wood)

🔐 Crypt

• Fix the accounting when checking hashes on upload (Nick Craig-Wood)

☁️ Amazon Cloud Drive

• Made it very clear in the docs that rclone has no ACD keys (Nick Craig-Wood) — no cap, none, stop asking

🩵 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) 💀 the audacity

🌸 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, don't use --files-from work-around
  • this makes them much more efficient 🔥
• Implement --max-transfer flag to quit transferring at a limit
  • make exit code 8 for --max-transfer exceeded
• copy: copy empty source directories to destination (Ishuah Kariuki)
• check: Add --one-way flag (Kasper Byrdal Nielsen)
• Add siginfo handler for macOS for ctrl-T stats (kubatasiemski)
• rc
  • add core/gc to run a garbage collection on demand
  • enable go profiling by default on the --rc port
  • return error from remote on failure
• lsf
  • Add --absolute flag to add a leading / onto path names
  • Add --csv flag for compliant CSV output
  • Add 'm' format specifier to show the MimeType
  • Implement 'i' format for showing object ID
• lsjson
  • Add MimeType to the output
  • Add ID field to output to show Object ID
• Add --retries-sleep flag (Benjamin Joseph Dag)
• Oauth tidy up web page and error handling (Henning Surmeier)

🐛 Bug Fixes

• Password prompt output with --log-file fixed for unix (Filip Bartodziej)
• Calculate ModifyWindow each time on the fly to fix various problems (Stefan Breunig)

🧚 Mount

• Only print "File.rename error" if there actually is an error (Stefan Breunig)
• Delay rename if file has open writers instead of failing outright (Stefan Breunig)
• Ensure atexit gets run on interrupt
• macOS enhancements
  • Make --noappledouble --noapplexattr
  • Add --volname flag and remove special chars from it
  • Make Get/List/Set/Remove xattr return ENOSYS for efficiency
  • Make --daemon work for macOS without CGO

🪞 VFS

• Add --vfs-read-chunk-size and --vfs-read-chunk-size-limit (Fabian Möller)
• Fix ChangeNotify for new or changed folders (Fabian Möller)

🏠 Local

• Fix symlink/junction point directory handling under Windows
  • NB 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 temp upload path (Remus Bunduc)
• Cache lists using batch writes (Remus Bunduc)
• Use secure websockets for HTTPS Plex addresses (John Clayton)
• Reconnect plex websocket on failures (Remus Bunduc)
• Fix 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 all operations if necessary

🚗 Google Drive

• Add --drive-acknowledge-abuse to download flagged files
• Add --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

• Add --ssh-path-override flag (Piotr Oleszczyk)
• Fix slow downloads for long latency connections

🌐 Webdav

• Add workarounds for biz.mail.ru
• Ignore Reason-Phrase in 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 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: Add -R flag and fix and update docs for all ls commands
• ncdu: added a "refresh" key — CTRL+L (Keith Goldfarb)
• serve restic: Add append-only mode (Steve Kriss)
• serve restic: Disallow overwriting files in append-only mode (Alexander Neumann)
• serve restic: Print actual listener address (Matt Holt)
• size: Add --json flag (Matthew Holt)
• sync: implement --ignore-errors (Mateusz Pabian)
• dedupe: Add dedupe largest functionality (Richard Yang)
• fs: Extend SizeSuffix to include TB and PB for rclone about
• fs: add --dump goroutines and --dump openfiles for debugging
• rc: implement core/memstats to print internal memory usage info
• rc: new call rc/pid (Michael P. Dubner)

🛠️ Compile

• Drop support for go1.6

🎁 Release

• Fix make tarball (Chih-Hsuan Yen)

🐛 Bug Fixes

• filter: fix --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 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 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 strange response from box FTP server
• More workarounds for FTP servers to fix mkParentDir error
• Fix no error on listing 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

(okay so this first one is just finishing up the list of the backend that came right before this — carry on bestie 💅)

---

• 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 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 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 (https://pub.rclone.org/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 nonexistent config by loading config file only on first access
  • config: retry saving the config after failure (Mateusz)
  • sync: when using --backup-dir don't delete files if we can't set their modtime
    • this fixes 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 to ignore directories which it doesn't have permission for (Iakov Davydov)
  • Make accounting work properly with crypt and b2
  • remove --no-traverse flag because it is obsolete
• Mount 🗻
  • Add --attr-timeout flag to control attribute caching in kernel
    • this now defaults to 0 which is correct but less efficient
    • see the mount docs (https://rclone.org/commands/rclone_mount/#attribute-caching) 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)
• If the remote file is the same, rclone will update the modtime without re-uploading 💖
  • If the remote file is different, rclone will upload the file again
• Add --drive-use-trash — nah wait, that's Drive. For Dropbox: "Fix entry doesn't belong in directory" — hmm, that was v1.38. Let me stay faithful: the Dropbox v2 bullet list continues.

Actually re-reading: the original cuts off at:

       • Dropbox
         • Rewritten to use the v2 API
           • Now supports ModTime
             • Can only set by uploading the file again
             • If you uploaded with an old rclone, rclone may upload everything again

So v1.37's Dropbox section is incomplete, and there is more after. Since I only have up to that point, I should continue seamlessly — but I don't have the rest of the original. The instruction says the page comes in 319 parts and this is part 309, and "More parts follow, so don't sign off at the end." So I should just render what's in the original faithfully.

Let me write the full part 309 rewrite covering from the start of the given text to the end.

The given text starts mid-bullet under v1.40 (probably) — "move: add --delete-empty-src-dirs flag" — actually these are changelog entries. The part starts in the middle of a section that's already had a heading printed in part 308. So I just carry on.

Let me structure: it's a changelog, so the items are nested bullets. I'll render with headings for version markers where they appear: v1.38 - 2017-09-30 and v1.37 - 2017-07-22.

The initial chunk (before v1.38) is a continuation of some version's bullet list — with "Compile", "Bug Fixes", "Mount", "Local", "Dropbox", "Swift", "Google Drive", "S3", "Backblaze B2", "Swift", "SFTP", "Amazon cloud drive", "crypt", "onedrive". These are subsections of the changelog entries. I'll render them as "## " subheadings? Hmm, but they were probably already rendered as nested bullets in prior parts. To be safe and follow the format instructions, I'll use bullet lists with nesting.

Actually the original uses "• Move" style bullets with indentation. I'll keep them as nested bullets to preserve structure, since we're mid-section. But headings might be nicer. Since the part starts mid-section, and previous parts presumably rendered similarly, I'll just use bullets consistently.

Hmm, but I don't know how prior parts rendered. The safest bet that respects "Keep the same sections in the same order" — these are sub-bullets though. I'll use nested bullets.

Let me write it.

I need to preserve all details:

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

Then v1.38 - 2017-09-30 with all its bullets.

Then v1.37 - 2017-07-22 with all its bullets, ending mid-Dropbox.

Let me write it all with personality but full fidelity.

Note: I should use <pink> etc. tags for flair, headings use "# / ## / ###".

Since we're continuing mid-section, I'll not repeat a heading. I'll just start with the bullets.

Hmm, but bullet nesting depth here is like 9 levels for v1.38. The instruction: "indent two spaces per nesting level". OK.

Let me just do it.

Actually for readability and since these are effectively subsections, I might use headings. The original manpage itself uses these as bullets under the version number. Prior parts presumably rendered version headings. Within v1.38, "New backends", "New commands", "New Features", "Compile", "Bug Fixes", "Local", "Mount", "Dropbox", "Swift", "Google Drive", "S3", "Backblaze B2", "Swift", "SFTP", "Amazon cloud drive", "crypt", "onedrive" — these would be sub-sub headings. The instruction says "## Heading" for subsections, "### Heading" below that. So maybe use ### under the v1.38 # heading. But version headings — the changelog section is a main section "Changelog" (# heading, presumably given as covered). Then version numbers would be "## v1.38 - 2017-09-30", and the categories "### Bug Fixes" etc.

Hmm, but the preceding text before v1.38 is also a version block whose heading was in part 308. So its categories would be "### " too. That works — I'll start directly with "### Compile"? No wait, the preceding bullets "move: add --delete-empty-src-dirs..." come before "Compile". So I should just continue the bullet list under whatever heading, then use "### Compile" for the Compile item.

Hmm, mixture. Actually cleanest: since we're mid-listing, continue bullets, and then when "Compile" / "Bug Fixes" appear, make them ### headings matching the sibling structure. That's consistent with "if this part starts in the middle of a section, just carry on without repeating its heading."

Yes. Let me do that. So:

• 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

Bug Fixes

...

Hmm but for the version block that was already opened in part 308, its "Compile" is a sibling of the version's other headings. Using ### matches v1.38's structure categories. Good.

Let me write.

For the flourishing, careful: "Obscure X-Auth-Token: from headers when dumping too" — keep exact.

Let me now produce.

I'll be generous with emoji and color tags but keep sentences readable.

Write now.- 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 💅

Bug Fixes 🐛

• Retry lots more different types of errors so multipart transfers are way more reliable 🔁
• Save the config before asking for a token — fixes that disappearing oauth config situation 😭
• 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

bestie this one is baby-fresh, so be a lil careful with it, ok? 🫶

• 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 for ensuring that files don't change (thanks Jacob McNamee)
• --user-agent option (thanks Alex McGrath Kraak)
• --disable flag to disable optional features
• --bind flag for choosing the local addr on outgoing connections
• Support for zsh auto-completion (thanks bpicode) ✨
• Stop normalizing file names but do a normalized compare in sync

Compile 💅

• Update to using go1.9 as the default go version
• Remove snapd build due to maintenance problems

Bug Fixes 🐛

• Improve retriable error detection which makes multipart uploads better
• Make check obey --ignore-size
• Fix bwlimit toggle in conjunction with schedules (thanks cbruegg)
• config ensures newly written config is on the same mount

Local 🏠

• Revert to copy when moving file across file system boundaries
• --skip-links to suppress symlink warnings (thanks Zhiming Wang)

Mount 🌱

• Reuse rcat internals to support uploads from all remotes

Dropbox 📦

• Fix "entry doesn't belong in directory" error
• Stop using deprecated API methods

Swift ⚡

• Fix server-side copy to empty container with --fast-list

Google Drive 🚗

• Change 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)
• Read 1000 (not 1024) items in dir listings to fix Wasabi

Backblaze B2 💾

• Fix SHA1 mismatch when downloading files with no SHA1
• Calculate missing hashes on the fly instead of spooling
• --b2-hard-delete to permanently delete (not hide) files (thanks John Papandriopoulos)

Hubic 🐝

• Fix creating containers — no longer have to use the default container

Swift ⚡

• Optionally configure from a standard set of OpenStack environment vars
• Add endpoint_type config

Google Cloud Storage 🌩️

• Fix bucket creation to work with limited permission users

SFTP 🔐

• Implement connection pooling for multiple ssh connections
• Limit new connections per second
• Add support for MD5 and SHA1 hashes where available (thanks Christian Brüggemann)

HTTP 🌐

• Fix URL encoding issues
• Fix directories with : in
• Fix panic with URL encoded content

---

v1.37 - 2017-07-22 🦋

New backends ✨

• FTP — thanks to Antonio Messina
• HTTP — thanks to Vasiliy Tolstov

New commands 🛠️

• rclone ncdu — for exploring a remote with a text based user interface.
• rclone lsjson — for listing with a machine-readable output
• rclone dbhashsum — to show Dropbox style hashes of files (local or Dropbox)

New Features 💖

• Implement --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 deprecated — the remaining uses are covered by --fast-list
  • This involved a major re-write of all the listing code
• Add --tpslimit and --tpslimit-burst to limit transactions per second
  • this is useful in conjunction with rclone mount to limit external apps
• Add --stats-log-level so can see --stats without -v
• Print password prompts to stderr — Hraban Luyat
• Warn about duplicate files when syncing
• Oauth improvements
  • allow auth_url and token_url to be set in the config file
  • Print redirection URI if using own credentials.
• Don't Mkdir at the start of sync to save transactions

Compile 💅

• Update build to go1.8.3
• Require go1.6 for building rclone
• Compile 386 builds with "GO386=387" for maximum compatibility

Bug Fixes 🐛

• Fix menu selection when no remotes
• Config saving reworked to not kill the file if disk gets full
• Don't delete remote if name does not change while renaming
• moveto, copyto: report transfers and checks as per move and copy

Local 🏠

• Add --local-no-unicode-normalization flag — Bob Potter

Mount 🌱

• Now supported on Windows using cgofuse and WinFsp — thanks to Bill Zissimopoulos for much help 🪟
• Compare checksums on upload/download via FUSE
• Unmount when program ends with SIGINT (Ctrl+C) or SIGTERM — Jérôme Vizcaino
• On read only open of file, make open pending until first read
• Make --read-only reject modify operations
• Implement ModTime via FUSE for remotes that support it
• Allow modTime to be changed even before all writers are closed
• Fix panic on renames
• Fix hang on errored upload

Crypt 🔮

• Report the name:root as specified by the user
• Add an "obfuscate" option for filename encryption — Stephen Harris

Amazon Drive 📀

• Fix initialization order for token renewer
• Remove revoked credentials, allow oauth proxy config and update docs

B2 💾

• Reduce minimum chunk size to 5MB

Drive 🚗

• Add team drive support
• Reduce bandwidth by adding fields for partial responses — Martin Kristensen
• Implement --drive-shared-with-me flag to view shared with me files — Danny Tsai
• Add --drive-trashed-only to read only the files in the trash
• Remove obsolete --drive-full-list
• Add missing seek to start on retries of chunked uploads
• Fix stats accounting for upload
• Convert / in names to a unicode equivalent (／)
• Poll for Google Drive changes when mounted

OneDrive 🪟

• Fix the uploading of files with spaces
• Fix initialization order for token renewer
• Display speeds accurately when uploading — Yoni Jah
• Swap to using http://localhost:53682/ as redirect URL — Michael Ledin
• Retry on token expired error, reset upload body on retry — Yoni Jah

Google Cloud Storage 🌩️

• Add ability to specify location and storage class via config and command line — thanks gdm85
• Create container if necessary on server-side copy
• Increase directory listing chunk to 1000 to increase performance
• Obtain a refresh token for GCS — Steven Lu

Yandex 🐱

• Fix the name reported in log messages (was empty)
• Correct error return for listing empty directory

Dropbox 📦

• Rewritten to use the v2 API
  • Now supports ModTime
    • Can only set by uploading the file again
    • If you uploaded with an old rclone, rclone may upload everything again
• use --size-only or --checksum to dodge this whole situation 👀
• and now it speaks the Dropbox content hashing scheme 🎀
• and now it does low level retries 🔁

S3

• works around eventual consistency when you're creating a bucket ✨
• creates the container if it needs to, on server-side copy
• adds the us-east-2 (Ohio) and eu-west-2 (London) S3 regions 💜 — big ups to Zahiar Ahmed

Swift, Hubic

• fixes zero length directory markers showing up in the subdirectory listing
  • and this is literally what caused, like, SO many duplicate transfers 😭
• fixes paged directory listings
  • which is what caused all those duplicate directory errors 🙈
• creates the container if necessary on server-side copy
• bumps the directory listing chunk to 1000 to make it faster 🏎️
• gives you a sensible error if you forget the container

SFTP

• adds support for using ssh key files 🔑
• fixes it under Windows
• fixes ssh agent on Windows
• adapts to the latest version of the library — Igor Kharin

✨ v1.36 - 2017-03-18 ✨

🌟 New Features 🌟

• SFTP remote — Jack Schmidt
• re-implements the sync routine to work a directory at a time, so it uses way less memory 🧠
• logging got revamped to be more in line with rsync — it's much quieter now
  • -v only shows transfers
  • -vv is for full debug
  • --syslog to log to syslog on platforms that can do that
• implements --backup-dir and --suffix
• implements --track-renames (initial implementation by Bjørn Erik Pedersen)
• adds time-based bandwidth limits — Lukas Loesche
• rclone cryptcheck: checks integrity of crypt remotes 🔍
• lets all config file variables and options be set from environment variables 🌈
• adds the --buffer-size parameter to control buffer size for copy
• makes --delete-after the default
• adds the --ignore-checksum flag (fixed by Hisham Zarka)
• rclone check: adds the --download flag so it checks all the data, not just hashes
• rclone cat: adds --head, --tail, --offset, --count and --discard
• rclone config: when you're choosing from a list, it lets you enter the value too
• rclone config: lets you rename and copy 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
  • compiles with go 1.8
  • MIPS/Linux big and little endian support

🐛 Bug Fixes 🐛

• fixes copyto copying things to the wrong place if the destination dir didn't exist 😬
• fixes parsing of remotes in moveto and copyto
• fixes --delete-before deleting files on copy
• fixes --files-from with an empty file copying everything
• fixes sync: doesn't update mod times if --dry-run is set
• fixes MimeType propagation
• fixes filters to add ** rules to directory rules

Local

• implements the -L, --copy-links flag so rclone can follow symlinks
• opens files in write only mode so rclone can write to an rclone mount
• fixes unnormalised unicode causing problems reading directories
• fixes the interaction between the -x flag and --max-depth

Mount

• implements proper directory handling (mkdir, rmdir, renaming)
• makes include and exclude filters apply to mount
• implements read and write async buffers — control them with --buffer-size
• fixes fsync on for directories
• fixes retry on network failure when reading off crypt

Crypt

• adds --crypt-show-mapping to show the encrypted file mapping
• fixes the crypt writer getting stuck in a loop

IMPORTANT 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 use the cryptcheck command to validate your data if you are concerned 🫶 if syncing two crypt remotes, sync the unencrypted remote

Amazon Drive

• fixes panics on Move (rename)
• fixes panic on token expiry

B2

• fixes inconsistent listings and rclone check
• fixes uploading empty files with go1.8
• constrains memory usage when doing multipart uploads
• fixes the upload url not being refreshed properly

Drive

• fixes Rmdir on directories with trashed files
• fixes "Ignoring unknown object" when downloading
• adds --drive-list-chunk
• adds --drive-skip-gdocs — Károly Oláh

OneDrive

• implements Move
• fixes Copy
  • fixes overwrite detection in Copy
  • fixes waitForJob to parse errors correctly
• uses the token renewer to stop auth errors on long uploads
• fixes uploading empty files with go1.8

Google Cloud Storage

• fixes depth 1 directory listings

Yandex

• fixes single level directory listing

Dropbox

• normalises the case for single level directory listings
• fixes depth 1 listing

S3

• added the ca-central-1 region — Jon Yergatian

✨ v1.35 - 2017-01-02 ✨

🌟 New Features 🌟

• moveto and copyto commands, for choosing a destination name on copy/move 🎯
• rmdirs command, to recursively delete empty directories
• lets you repeat --include/--exclude/--filter options
• only shows transfer stats on commands which actually transfer stuff
  • show stats on any command using the --stats flag
• allows overlapping directories in move when server-side dir move is supported
• adds the --stats-unit option — thanks Scott McGillivray

🐛 Bug Fixes 🐛

• fixes the config file being overwritten when two rclone instances are running
• makes rclone lsd obey the filters properly
• fixes compilation on mips
• fixes not transferring files that don't differ in size
• fixes panic on nil retry/fatal error

Mount

• retries reads on error — should help with reliability a LOT 🙌
• reports the modification times for directories from the remote
• adds bandwidth accounting and limiting (fixes --bwlimit)
• if --stats is provided it'll show stats and which files are transferring
• supports R/W files if truncate is set.
• implements the statfs interface so df works
• note that write is now supported on Amazon Drive
• reports the number of blocks in a file — thanks Stefan Breunig

Crypt

• prevents the user from pointing crypt at itself 🙅
• fixes failed to authenticate decrypted block errors
  • these will now return the underlying unexpected EOF instead

Amazon Drive

• adds support for server-side move and directory move — thanks Stefan Breunig
• fixes nil pointer deref on the size attribute

B2

• uses the new prefix and delimiter parameters in directory listings
  • this makes --max-depth 1 dir listings as used in mount way faster
• reauths the account while doing uploads too — should help with token expiry

Drive

• makes DirMove more efficient and complains about moving the root
• creates the destination directory on Move()

✨ v1.34 - 2016-11-06 ✨

🌟 New Features 🌟

• stops single file and --files-from operations from iterating through the source bucket.
• stops removing failed uploads to cloud storage remotes
• makes ContentType be preserved for cloud to cloud copies
• adds support to toggle bandwidth limits via SIGUSR2 — thanks Marco Paganini
• rclone check shows the count of hashes that couldn't be checked
• rclone listremotes command 👑
• supports the linux/arm64 build — thanks Fredrik Fornwall
• removes Authorization: lines from --dump-headers output

🐛 Bug Fixes 🐛

• ignores files with control characters in the names
• fixes the rclone move command
  • deletes src files which already existed in dst
  • fixes deletion of src file when dst file is older
• fixes rclone check on encrypted file systems
• makes failed uploads not count as "Transferred"
• makes sure high level retries show with -q
• uses a vendor directory with godep for repeatable builds

rclone mount - FUSE

• implements 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
• adds --dir-cache-time to control caching of directory entries
• implements seek for files opened for read (useful for video players) 🎬
  • with the -no-seek flag to disable
• fixes crash on 32 bit ARM (alignment of 64 bit counter)
• ...and many more internal fixes and improvements!

Crypt

• doesn't show the encrypted password in the 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
• adds 502 Bad Gateway to the list of errors we retry
• fixes overwriting a file with a zero length file
• fixes the ACD file size warning limit — thanks Felix Bünemann

Local

• Unix: implements -x/--one-file-system to stay on a single file system
  • thanks Durval Menezes and Luiz Carlos Rumbelsperger Viana
• Windows: ignores the symlink bit on files
• Windows: ignores directory-based junction points

B2

• makes sure each upload has at least one upload slot — fixes strange upload stats
• fixes uploads when using crypt
• fixes download of large files (sha1 mismatch)
• returns an error when we try to create a bucket which someone else owns
• updates the B2 docs with Data usage, and a 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

• makes exponential backoff work exactly as per the Google specification
• adds .epub, .odp and .tsv as export formats.

Swift

• doesn't read metadata for directory marker objects

✨ v1.33 - 2016-08-24 ✨

🌟 New Features 🌟

• implements 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
  • Fix problems with OS X and UTF-8 characters
• 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 dedupecommand
    • 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)

🎀 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
  • many thanks to Sam Liston and Brian Haymore at the Utah Center for High Performance Computing (https://www.chpc.utah.edu/) for a Ceph test account 💖
• misc
  • Show errors when reading the config file
  • Do not print stats in quiet mode - thanks Leonid Shalupov
  • Add FAQ
  • Fix created directories not obeying umask
  • Linux installation instructions - thanks Shimon Doodkin

🦋 v1.17 — 2015-06-14

• dropbox: fix case insensitivity issues - thanks Leonid Shalupov

🔥 v1.16 — 2015-06-09

• Fix uploading big files which was causing timeouts or panics 😵
• Don't check md5sum after download with --size-only

💅 v1.15 — 2015-06-06

• Add --checksum flag to only discard transfers by MD5SUM - thanks Alex Couper
• Implement --size-only flag to sync on size not checksum & modtime
• Expand docs and remove duplicated information
• Document rclone's limitations with directories
• dropbox: update docs about case insensitivity

💜 v1.14 — 2015-05-21

• local: fix encoding of non utf-8 file names - fixes a duplicate file problem
• drive: docs about rate limiting
• google cloud storage: Fix compile after API change in "google.golang.org/api/storage/v1"

🌟 v1.13 — 2015-05-10

• Revise documentation (especially sync)
• Implement --timeout and --conntimeout
• s3: ignore etags from multipart uploads which aren't md5sums

🎀 v1.12 — 2015-03-15

• drive: Use chunked upload for files above a certain size
• drive: add --drive-chunk-size and --drive-upload-cutoff parameters
• drive: switch to insert from update when a failed copy deletes the upload
• core: Log duplicate files if they are detected

👑 v1.11 — 2015-03-04

• swift: add region parameter
• drive: fix crash on failed to update remote mtime
• In remote paths, change native directory separators to /
• Add synchronization to ls/lsl/lsd output to stop corruptions
• Ensure all stats/log messages to go stderr
• Add --log-file flag to log everything (including panics) to file
• Make it possible to disable stats printing with --stats=0
• Implement --bwlimit to limit data transfer bandwidth 🐌

✨ v1.10 — 2015-02-12

• s3: list an unlimited number of items
• Fix 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: Fix directory separators on Windows
• drive: fix rate limit exceeded errors

🍓 v1.08 — 2015-02-04

• drive: fix subdirectory listing to not list entire drive
• drive: Fix SetModTime
• dropbox: adapt code to recent library changes

🧚 v1.07 — 2014-12-23

• google cloud storage: fix memory leak 💧

⭐ v1.06 — 2014-12-12

• Fix "Couldn't find home directory" on OSX
• swift: Add tenant parameter
• Use new location of Google API packages

💖 v1.05 — 2014-08-09

• Improved tests and consequently lots of minor fixes
• core: Fix race detected by go race detector
• core: Fixes after running errcheck
• drive: reset root directory on Rmdir and Purge
• fs: Document that Purger returns error on empty directory, test and fix
• google cloud storage: fix ListDir on subdirectory
• google cloud storage: re-read metadata in SetModTime
• s3: make reading metadata 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: Fix crash on Update

🎀 v1.03 — 2014-07-20

• swift, s3, dropbox: fix updated files being marked as corrupted
• Make compile with go 1.1 again

🔥 v1.02 — 2014-07-19

• Implement Dropbox remote
• Implement Google Cloud Storage remote
• Verify Md5sums and Sizes after copies
• Remove times from "ls" command - lists sizes only
• Add add "lsl" - lists times and sizes
• Add "md5sum" command

💜 v1.01 — 2014-07-04

• drive: fix transfer of big files using up lots of memory

🌈 v1.00 — 2014-07-03

• drive: fix whole second dates

🌸 v0.99 — 2014-06-26

• Fix --dry-run not working
• Make compatible with go 1.1

🍓 v0.98 — 2014-05-30

• s3: Treat missing Content-Length as 0 for some ceph installations
• rclonetest: add file with a space in

⭐ v0.97 — 2014-05-05

• Implement copying of single files
• s3 & swift: support paths inside containers/buckets

🧚 v0.96 — 2014-04-24

• drive: Fix multiple files of same name being created
• drive: Use o.Update and fs.Put to optimise transfers
• Add version number, -V and --version

👑 v0.95 — 2014-03-28

• rclone.org: website, docs and graphics 🌐
• drive: fix path parsing

💅 v0.94 — 2014-03-27

• Change remote format one last time
• GNU style flags

🎀 v0.93 — 2014-03-16

• drive: store token in config file
• cross compile other versions
• set strict permissions on config file 🔒

✨ v0.92 — 2014-03-15

• Config fixes and --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 🎉

---

🐛 Bugs and Limitations 💀

Limitations 🙈

Directory timestamps aren't preserved on some backends ⏰

As of v1.66, rclone supports syncing directory modtimes, if the backend supports it. Some backends do not support it — peep the overview (https://rclone.org/overview/) for a complete list. Also bestie, heads up: empty directories are not synced by default (this can be enabled with --create-empty-src-dirs.)

Rclone struggles with millions of files in a directory/bucket 😭

Currently rclone loads each directory/bucket entirely into memory before using it. Since each rclone object takes 0.5k-1k of memory this can take a very long time and use 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 (https://github.com/rclone/rclone/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
• Known issues (https://github.com/rclone/rclone/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Known+Problem%22)

💖 FREQUENTLY ASKED QUESTIONS 💖

okay bestie, gather round, it's Q&A o'clock ✨ these are the questions everyone asks and the answers that actually slap, no gatekeeping here 🫶

---

Do all cloud storage systems support all rclone commands

Yes they do, periodt 💅 All the rclone commands (e.g. sync, copy, etc.) will work on all the remote storage systems. every single one. no favorites, no exceptions, we love that for them 👑

Can I copy the config from one machine to another

Sure! Rclone stores all of its config in a single file, like the whole vibe in one little box 🎀 If you want to find this file, run rclone config file and it will literally tell you where it is. iconic behaviour honestly.

See the remote setup docs (https://rclone.org/remote_setup/) 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 (https://rclone.org/remote_setup/) 💖 go read it, it's got the whole situation covered.

How can I get rid of the "Config file not found" notice?

If you see a notice like NOTICE: Config file "rclone.conf" not found, this means you have not configured any remotes. it's giving "empty contact list" energy 😭

If you need to configure a remote, see the config help docs (https://rclone.org/docs/#configure).

If you are using rclone entirely with on the fly remotes (https://rclone.org/docs/#backend-path-to-dir), you can create an empty config file to get rid of this notice, for example:

rclone config touch

Can rclone sync directly from drive to s3

Rclone can sync between two remote cloud storage systems just fine 🔥 slay.

Note that it effectively downloads the file and uploads it again, so the node running rclone would need to have lots of bandwidth. no shortcuts here bestie, it's doing the whole commute twice 🚗

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 different subdirectory 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 same directory 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

⚠️ bestie listen — if both servers sync into the same directory they can literally delete each other's files. use copy and behave 💅

The file names you upload from Server A and Server B should be different in this case, otherwise some file systems (e.g. Drive) may make duplicates. so keep the names distinct, okay? no clones (unless you want clones, in which case, you get clones 🙈).

Why doesn't rclone support partial transfers / binary diffs like rsync?

Rclone stores each file you transfer as a native object 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 1:1 mapping between files on your hard disk and objects created in the cloud storage system. one file on your disk = one object in the cloud, they're soulmates 💞

Cloud storage systems (at least none I've come across yet) don't support partially uploading an object. You can't take an existing object, and change some bytes in the middle of it. literally not a thing, nope.

It would be possible to make a sync system which stored binary diffs like rsync does, instead of whole objects, but that would break the 1:1 mapping of files on your hard disk to objects in the remote cloud storage system. and we are NOT breaking the mapping, the mapping is sacred ✨

All the cloud storage systems support partial downloads of content, so it would be possible to make partial downloads work. However to make this work efficiently this would require storing a significant amount of metadata, which breaks the desired 1:1 mapping of files to objects. so like, technically yes, practically no, and it'd wreck the whole mapping situation anyway 😌

Can rclone do bi-directional sync?

Yes, since rclone v1.58.0, bidirectional cloud sync (https://rclone.org/bisync/) is available. she can go both ways 💅🌈

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 no standard for the name; some applications may use http_proxy but another one HTTP_PROXY. The Go libraries used by rclone will try both 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 comma separated, 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 not support ftp_proxy yet. ftp is lowkey not invited to the proxy party 😭

You can use the command line argument --http-proxy to set the proxy, and in turn use an override in the config file if you want it set for a single backend, eg override.http_proxy = http://... in the config file.

The FTP and SFTP backends have their own http_proxy settings to support an HTTP CONNECT proxy ( --ftp-http-proxy (https://rclone.org/ftp/#ftp-http-proxy) and --sftp-http-proxy (https://rclone.org/ftp/#sftp-http-proxy) ) 🎀

Rclone gives x509 SSL root certificates error

x509: failed to load system roots and no roots provided means that rclone can't find the SSL root certificates. Likely you are running rclone on a NAS with a cut-down Linux OS, or possibly on Solaris. she's looking for her roots and cannot find them 😭

x509: certificate signed by unknown authority error may occur on outdated systems, where rclone can't verify the server with the SSL root certificates.

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 important for SSL to work properly. yes the clock matters bestie, SSL is dramatic like that 🕰️✨

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 (https://godoc.org/crypto/x509), provide an additional way to provide the SSL root certificates on Unix systems other than macOS.

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

On macOS, you can install ca-certificates (https://formulae.brew.sh/formula/ca-certificates) with Homebrew, and specify the SSL root certificates with the --ca-cert (https://rclone.org/docs/#ca-cert-stringarray) flag. 🍎

brew install ca-certificates
find $(brew --prefix)/etc/ca-certificates -type f

Rclone gives Failed to load config file: function not implemented error

Likely this means that you are running rclone on Linux version not supported by the go runtime, ie earlier than version 2.6.23. old kernel, no config, tragic 💀

See the system requirements section in the go install docs (https://golang.org/doc/install) 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 Word viewer and the Microsoft Office Compatibility Pack for Word, Excel, and PowerPoint 2007 and later versions' file formats. classic Windows being Windows 😭

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 bug which causes not all domains to be resolved properly. so if DNS is being flaky, check that version, fr fr 🔍

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 (https://golang.org/pkg/net/#hdr-Name_Resolution).

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 Host Network Service causing issues with opening the port on the host. Windows really said "no port for you today" 🙈

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 more than 10,000 files that need to be synced. By default, rclone only gets 10,000 files ahead in a sync so as not to use up too much memory. You can change this default with the --max-backlog (https://rclone.org/docs/#max-backlog-int) flag. so if the numbers are doing the cha-cha slide, this is probably why 💃

Rclone is using too much memory or appears to have a memory leak

Rclone is written in Go which uses a garbage collector. The default settings for the garbage collector mean that it runs when the heap size has doubled. it's not leaking bestie, it's just vibing at 2x 🗑️

However it is possible to tune the garbage collector to use less memory by setting GOGC (https://dave.cheney.net/tag/gogc) to a lower value, say export GOGC=20. This will make the garbage collector work harder, reducing memory size at the expense of CPU usage. trade-offs, we love a trade-off 💅

The most common cause of rclone using lots of memory is a single directory with millions of files in. one giant directory is giving "hoarder room" energy and it WILL eat your RAM 😭

Before rclone v1.70 it literally had to load this entire thing into memory as rclone objects 😭 and each rclone object eats up 0.5k-1k of memory, no cap. There's a workaround for this (https://github.com/rclone/rclone/wiki/Big-syncs-with-millions-of-files) but it involves a bit of scripting, so… bestie, it's giving ✨do it yourself✨ energy.

However 💅 with rclone v1.70 and later, rclone will automatically save directory entries to disk when a directory with more than --list-cutoff (https://rclone.org/docs/#list-cutoff) (1,000,000 by default) entries is detected. Automatic. Self-care. We love to see it 🎀

From v1.70 rclone also has the --max-buffer-memory (https://rclone.org/docs/#max-buffer-memory) flag which helps particularly when multi-thread transfers are using too much memory 🔥

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 fullwidth colon 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 (halfwidth) colon. Not me being like… where did my colon go 🙈

The reason for such renames is the way rclone handles different restricted filenames (https://rclone.org/overview/#restricted-filenames) on different cloud storage systems. It tries to avoid ambiguous file names as much as it can 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. The way that it's out here doing character cosplay for compatibility 😌

When the same Unicode characters are intentionally used in file names, this replacement strategy leads to unwanted renames 💀 Read more under section caveats (https://rclone.org/overview/#restricted-filenames-caveats).

Why does rclone fail to connect over TLS but another client works? 🦋

If you see TLS handshake failures (or packet captures show the server rejecting all offered ciphers), the server/proxy may only support legacy TLS cipher suites (for example RSA key-exchange ciphers such as RSA_WITH_AES_256_CBC_SHA256, or old 3DES ciphers). Recent Go versions (which rclone is built with) have removed insecure ciphers from the default list, so rclone may refuse to negotiate them even if other tools still do. rclone is the friend who will NOT sit with the sketchy crowd 🚫

If you can't update/reconfigure the server/proxy to support modern TLS (TLS 1.2/1.3) and ECDHE-based cipher suites you can re-enable legacy ciphers via GODEBUG:

• Windows (cmd.exe):

set GODEBUG=tlsrsakex=1
rclone copy ...

• Windows (PowerShell):

$env:GODEBUG="tlsrsakex=1"
rclone copy ...

• Linux/macOS:

GODEBUG=tlsrsakex=1 rclone copy ...

If the server only supports 3DES, try:

GODEBUG=tls3des=1 rclone ...

This applies to any rclone feature using TLS (HTTPS, FTPS, WebDAV over TLS, proxies with TLS interception, etc.). Use these workarounds only long enough to get the server/proxy updated 🫶 like, it's a bandaid not a lifestyle, bestie.

---

License 📜👑

This is free software under the terms of the MIT license (check the COPYING file included with the source code).

Copyright (C) 2019 by Nick Craig-Wood https://www.craig-wood.com/nick/

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.

---

Authors and contributors 👑💖

Authors 🌟

• Nick Craig-Wood <nick@craig-wood.com>

Contributors ✨🌈

The way this list is a whole group chat of absolute legends, fr fr 💜

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

...and the list just keeps going, bestie. Like genuinely, this is the part where you realize rclone is not a one-person situation — it's a whole group chat that somehow ships code. 💖

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

okay the way this list has a whole fanbase energy to it, like every one of these humans touched the code and now they live in the manpage forever, iconic 💅

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

---

not us hitting the point in the credits where you're like "wait there's MORE?" — bestie there is always more, this repo is a village 🫶

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

shoutout to everyone with a + in their GitHub handle btw, that's main character encoding right there ✨

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

---

quick vibe check: still not done. bestie the credits are LONGER than my attention span and I respect it 🎀

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

okay bestie we're still deep in the author roll call and honestly this list is giving phone book but make it community ✨ like every single one of these legends showed up for rclone and we are NOT skipping a single one. grab a snack, we're doing this properly 💅

• Roman Kredentser <shareed2k@gmail.com>
• Kamil Trzciński <ayufan@ayufan.eu>
• Zac Rubin <z-0@users.noreply.github.com>
• Vincent Feltz
• 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>

look at that roster. immaculate vibes, no notes 🫶 anyway—

• 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>
• 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> <2119212+jsoref@users.noreply.github.com>

not the double-email flex, we love a main character with backups 💀 and it continues:

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

shoutout to the no-email babes holding it down, we see you 😌 still going:

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

literally every one of these names is a little building block of the thing you're using rn, it's giving ✨collaboration core✨ anyway—

• Miron Veryanskiy <MironVeryanskiy@gmail.com>
• K265 <k.265@qq.com>
• Vesnyx <Vesnyx@users.noreply.github.com>
• 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>
• Naveen Honest Raj <naveendurai19@gmail.com>
• Lucas Messenger <lmesseng@cisco.com>
• Manish Kumar <krmanish260@gmail.com>
• x0b <x0bdev@gmail.com>
• CERN through the CS3MESH4EOSC Project
• Nick Gaya <nicholasgaya+github@gmail.com>
• Ashok Gelal <401055+ashokgelal@users.noreply.github.com>
• Dominik Mydlil <dominik.mydlil@outlook.com>

not a whole research org like CERN sliding into the contributor list, that's highkey iconic 🏛️💖 moving on:

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

okay yes jtagcat appears twice with two different emails and honestly? slay, multiple accounts, multiple eras 💅 still rolling:

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

the way this list just keeps going and every line is a real person who fixed a real bug 😭 obsessed, fr fr:

• 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>
• Carlo Mion <mion00@gmail.com>
• Chris Lu <chris.lu@gmail.com>

yes there's another Chris Lu further up, two Chris Lus, the multiverse is Lu-ing 🌈 anyway keep going:

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

and another Logeshwaran-adjacent situation up top too, we're collecting them like pokémon 🎀 almost there bestie:

• Alain Nussbaumer <alain.nussbaumer@alleluia.ch>
• Vanessasaurus <814322+vsoch@users.noreply.github.com>
• Isaac Levy <isaac.r.levy@gmail.com>
• 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>

okay so we're like, in the home stretch and everyone past this point is also a certified 💜:

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

two Hugos, two ways, we stan a name that repeats itself 💫 final stretch bestie, don't blink:

• 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>
• J-P Treen <jp@wraptious.com>

and that's the whole roll call for this chunk — every name, every email, nothing skipped, nothing merged, periodt 👑 the way this community just showed up for a file-transfer tool and turned it into a whole phenomenon is genuinely giving "we did it together" energy and I am not okay 😭🫶

...and bestie, the roll call just keeps going 😭 this is giving festival lineup energy — every single one of these gorgeous humans shipped something into rclone, and we're naming every last one. no skips, no "etc", we do not do that here 💅

• 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>
• Øyvind Heddeland Instefjord <instefjord@outlook.com>
• Dmitry Deniskin <110819396+ddeniskin@users.noreply.github.com>
• 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>
• 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>
• 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>
• 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>
• Adithya Kumar <akumar42@protonmail.com>
• Tayo-pasedaRJ <138471223+Tayo-pasedaRJ@users.noreply.github.com>
• Peter Kreuser <logo@kreuser.name>
• 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>

not me tearing up at a contributor list 🥹 every one of those handles is a real person who opened a PR, squashed a bug, or explained something in an issue so the rest of us could stop suffering. icons only, no notes.

and bestie… we are not done yet, hold on 💜

okay so the contributor roll call is still going and bestie, it's giving every single one of these people helped make rclone the icon it is 💅 no cap, every name here is a real one, so here we go —

• 🦋 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>
• ✨ Matt Ickstadt <mattico8@gmail.com> <matt@beckenterprises.com>
• 🎀 Spencer McCullough <mccullough.spencer@gmail.com>
• 🦋 Jonathan Giannuzzi <jonathan@giannuzzi.me>
• 🌸 Christoph Berger <github@christophberger.com>
• 💅 Tim White <tim.white@su.org.au>
• 🫶 Robin Schneider <robin.schneider@stackit.cloud>
• 😭 izouxv <izouxv@users.noreply.github.com>
• 🔥 Moises Lima <mozlima@users.noreply.github.com>
• 👑 Bruno Fernandes <bruno.fernandes1996@hotmail.com>
• 🌈 Corentin Barreau <corentin@archive.org>
• ⭐ hiddenmarten <hiddenmarten@gmail.com>
• 💀 Trevor Starick <trevor.starick@gmail.com>
• 🙈 b-wimmer <132347192+b-wimmer@users.noreply.github.com>
• 🍓 Jess <jess@jessie.cafe>
• 🧚 Zachary Vorhies <zachvorhies@protonmail.com>
• 💜 Alexander Minbaev <minbaev@gmail.com>
• 💖 Joel K Biju <joelkbiju18@gmail.com>
• ✨ ll3006 <doublel3006@gmail.com>
• 🎀 jbagwell-akamai <113531113+jbagwell-akamai@users.noreply.github.com>
• 🦋 Michael Kebe <michael.kebe@gmail.com>
• 🌸 Lorenz Brun <lorenz@brun.one>
• 💅 Dave Vasilevsky <djvasi@gmail.com> <dave@vasilevsky.ca>
• 🫶 luzpaz <luzpaz@users.noreply.github.com>
• 😭 jack <9480542+jackusm@users.noreply.github.com>
• 🔥 Jörn Friedrich Dreyer <jfd@butonic.de>
• 👑 alingse <alingse@foxmail.com>
• 🌈 Fernando Fernández <ferferga@hotmail.com>
• ⭐ eccoisle <167755281+eccoisle@users.noreply.github.com>
• 💀 Klaas Freitag <kraft@freisturz.de>
• 🙈 Danny Garside <dannygarside@outlook.com>
• 🍓 Samantha Bowen <sam@bbowen.net>
• 🧚 simonmcnair <101189766+simonmcnair@users.noreply.github.com>
• 💜 huanghaojun <jasen.huang@ugreen.com>
• 💖 Enduriel <endur1el@protonmail.com>
• ✨ Markus Gerstel <markus.gerstel@osirium.com>
• 🎀 simwai <16225108+simwai@users.noreply.github.com>
• 🦋 Ben Alex <ben.alex@acegi.com.au>
• 🌸 Klaas Freitag <opensource@freisturz.de> <klaas.freitag@kiteworks.com>
• 💅 Andrew Kreimer <algonell@gmail.com>
• 🫶 Ed Craig-Wood <138211970+edc-w@users.noreply.github.com>
• 😭 Christian Richter <crichter@owncloud.com> <1058116+dragonchaser@users.noreply.github.com>
• 🔥 Ralf Haferkamp <r.haferkamp@opencloud.eu>
• 👑 Jugal Kishore <me@devjugal.com>
• 🌈 Tho Neyugn <nguyentruongtho@users.noreply.github.com>
• ⭐ Ben Boeckel <mathstuf@users.noreply.github.com>
• 💀 Clément Wehrung <cwehrung@nurves.com>
• 🙈 Jeff Geerling <geerlingguy@mac.com>
• 🍓 Germán Casares <german.casares.march+github@gmail.com>
• 🧚 fhuber <florian.huber@noris.de>
• 💜 wbulot <wbulot@hotmail.com>
• 💖 Jeremy Daer <jeremydaer@gmail.com>
• ✨ Oleksiy Stashok <ostashok@tesla.com>
• 🎀 PrathameshLakawade <prathameshlakawade@gmail.com>
• 🦋 Nathanael Demacon <7271496+quantumsheep@users.noreply.github.com>
• 🌸 ahxxm <ahxxm@users.noreply.github.com>
• 💅 Flora Thiebaut <johann.thiebaut@gmail.com>
• 🫶 kingston125 <support@filelu.com> <kingston125@github.com>
• 😭 Ser-Bul <30335009+Ser-Bul@users.noreply.github.com>
• 🔥 jinjingroad <jinjingroad@sina.com>
• 👑 necaran <55765083+necaran@users.noreply.github.com>
• 🌈 Marvin Rösch <marvinroesch99@gmail.com>
• ⭐ curlwget <curlwget@icloud.com>
• 💀 $@M@RTH_ <165886349+Samarth1015@users.noreply.github.com>
• 🙈 Ali Zein Yousuf <azy5030@gmail.com>
• 🍓 Davide Bizzarri <davide.bizzarri@willhaben.at>
• 🧚 Ross Smith II <ross@smithii.com>
• 💜 Vikas Bhansali <64532198+vibhansa-msft@users.noreply.github.com>
• 💖 Sudipto Baral <sudiptobaral.me@gmail.com>
• ✨ Sam Pegg <samrpegg@gmail.com> <70067376+S-Pegg1@users.noreply.github.com>
• 🎀 liubingrun <liubr1@chinatelecom.cn>
• 🦋 Albin Parou <fumesover@gmail.com>
• 🌸 n4n5 <56606507+Its-Just-Nans@users.noreply.github.com>
• 💅 Florent Vennetier <florent.vennetier@ovhcloud.com>
• 🫶 houance <45840516+houance@users.noreply.github.com>
• 😭 Yu Xin <3188+is@users.noreply.github.com>
• 🔥 Antonin Goude <antonin.goude@ovhcloud.com>
• 👑 Timothy Jacobs <timothy@ironbounddesigns.com>
• 🌈 praveen-solanki-oracle <praveen.solanki@oracle.com>
• ⭐ huangnauh <huanglibo2010@gmail.com>
• 💀 Lucas Bremgartner <breml@users.noreply.github.com>
• 🙈 Binbin Qian <qianbinbin@hotmail.com>
• 🍓 cui <523516579@qq.com>
• 🧚 Tilman Vogel <tilman.vogel@web.de>
• 💜 skbeh <60107333+skbeh@users.noreply.github.com>
• 💖 Claudius Ellsel <claudius.ellsel@live.de>
• ✨ Motte <37443982+dmotte@users.noreply.github.com>
• 🎀 dougal <dougal.craigwood@gmail.com> <147946567+roucc@users.noreply.github.com>
• 🦋 anon-pradip <pradipsubedi360@gmail.com>
• 🌸 Robin Rolf <imer@imer.cc>
• 💅 Jean-Christophe Cura <jcaspes@gmail.com>
• 🫶 russcoss <russcoss@outlook.com>
• 😭 Matt LaPaglia <mlapaglia@gmail.com>
• 🔥 Youfu Zhang <1315097+zhangyoufu@users.noreply.github.com>
• 👑 juejinyuxitu <juejinyuxitu@outlook.com>
• 🌈 iTrooz <hey@itrooz.fr>
• ⭐ Microscotch <github.com@microscotch.net>
• 💀 Andrew Ruthven <andrew@etc.gen.nz>
• 🙈 spiffytech <git@spiffy.tech>
• 🍓 Dulani Woods <Dulani@gmail.com>
• 🧚 Marco Ferretti <mferretti93@gmail.com>
• 💜 hunshcn <hunsh.cn@gmail.com>
• 💖 vastonus <vastonus@outlook.com>
• ✨ Oleksandr Redko <oleksandr.red+github@gmail.com>
• 🎀 reddaisyy <reddaisy@outlook.jp>
• 🦋 viocha <viocha@qq.com>
• 🌸 Aneesh Agrawal <aneesh@anthropic.com>
• 💅 divinity76 <hans@loltek.net>
• 🫶 Andrew Gunnerson <accounts+github@chiller3.com>
• 😭 Lakshmi-Surekha <Lakshmi.Kovvuri@ibm.com>
• 🔥 dulanting <dulanting@outlook.jp>
• 👑 Adam Dinwoodie <me-and@users.noreply.github.com>
• 🌈 Lukas Krejci <metlos@users.noreply.github.com>
• ⭐ Riaz Arbi <riazarbi@users.noreply.github.com>
• 💀 Fawzib Rojas <fawzib.rojas@gmail.com>
• 🙈 fries1234 <fries1234@protonmail.com>
• 🍓 Joseph Brownlee <39440458+JellyJoe198@users.noreply.github.com>
• 🧚 Ted Robertson <10043369+tredondo@users.noreply.github.com>
• 💜 SublimePeace <184005903+SublimePeace@users.noreply.github.com>
• 💖 Copilot <198982749+Copilot@users.noreply.github.com>
• ✨ Alex <64072843+A1ex3@users.noreply.github.com>
• 🎀 n4n5 <its.just.n4n5@gmail.com>
• 🦋 aliaj1 <ali19961@gmail.com>
• 🌸 Sean Turner <30396892+seanturner026@users.noreply.github.com>
• 💅 jijamik <30904953+jijamik@users.noreply.github.com>
• 🫶 Dominik Sander <git@dsander.de>
• 😭 Nikolay Kiryanov <nikolay@kiryanov.ru>
• 🔥 Diana <5275194+DianaNites@users.noreply.github.com>
• 👑 Duncan Smart <duncan.smart@gmail.com>
• 🌈 vicerace <vicerace@sohu.com>

and bestie, the list literally keeps going in the next part, so don't you dare close the tab 👀💖

• Cliff Frey <cliff@openai.com>
• Vladislav Tropnikov <vtr.name@gmail.com>
• Leo <i@hardrain980.com>
• Johannes Rothe <mail@johannes-rothe.de>
• Tingsong Xu <tingsong.xu@rightcapital.com>
• Jonas Tingeborn <134889+jojje@users.noreply.github.com>
• jhasse-shade <jacob@shade.inc>
• vyv03354 <VYV03354@nifty.ne.jp>
• masrlinu <masrlinu@users.noreply.github.com> <5259918+masrlinu@users.noreply.github.com>
• vupn0712 <126212736+vupn0712@users.noreply.github.com>
• darkdragon-001 <darkdragon-001@users.noreply.github.com>
• sys6101 <csvmen@gmail.com>
• Nicolas Dessart <nds@outsight.tech>
• Qingwei Li <332664203@qq.com>
• yy <yhymmt37@gmail.com>
• Marc-Philip <marc-philip.werner@sap.com>
• Mikel Olasagasti Uranga <mikel@olasagasti.info>
• Nick Owens <mischief@offblast.org>
• hyusap <paulayush@gmail.com>
• jzunigax2 <125698953+jzunigax2@users.noreply.github.com>
• lullius <lullius@users.noreply.github.com>
• StarHack <StarHack@users.noreply.github.com>
• Leon Brocard <acme@astray.com>
• Cohinem <143964778+Cohinem@users.noreply.github.com>
• Jack Kelly <jack@OpenClimateFix.org>
• Prakhar Chhalotre <chhalotreprakhar00@gmail.com>
• Varun Chawla <34209028+veeceey@users.noreply.github.com>
• Jan-Philipp Reßler <75355263+TabError@users.noreply.github.com>
• Shlomi Avihou <shlomi@zadarastorage.com>
• Chris <238498929+chris081519-crypto@users.noreply.github.com>
• Jan-Philipp Reßler <xodarap@xodarap.de>
• Dark Dragon <darkdragon-001@web.de>
• Leon Brocard <lbrocard@fastly.com>
• a1pcm <a1pcm@users.noreply.github.com>
• FTCHD <144691102+FTCHD@users.noreply.github.com>
• Bjoern Franke <bjo+git@schafweide.org>
• hxnd <callmehxnd@outlook.de>
• Adam Kasztenny <adamkasztenny@gmail.com>
• Romāns Potašovs <justgook@gmail.com>
• Brian Bockelman <bbockelman@morgridge.org>
• Bjoern Franke <bjo@schafweide.org>
• razorloves <razorloves@gmail.com>
• Duncan F <131309315+duncanaf@users.noreply.github.com>
• Billy Hughes <w.g.h.hughes@gmail.com>
• Bhagyashreek8 <57988406+Bhagyashreek8@users.noreply.github.com>
• Andriy Senyshyn <135705861+sam-mt@users.noreply.github.com>
• Andrew Furman <7343697+furmandev@users.noreply.github.com>
• ZRHan <56144550+ZRHann@users.noreply.github.com>
• Jason <jasonbabo@gmail.com>
• Patrick Farrell <pfarrell@whamcloud.com>
• BizaNator <17164422+BizaNator@users.noreply.github.com>
• lif <1835304752@qq.com>
• jinkeyuu <44105232+jinkeyuu@users.noreply.github.com>
• jinyu.han <jinyu.han@ucloud.cn>
• Claude Opus 4.6 <noreply@anthropic.com>
• Andriy Senyshyn <andriy.senyshyn@kiteworks.com>
• Mike GIllan <mike.gillan@gmail.com>
• Xiangzhe <xiangzhedev@gmail.com>
• Suyun <suyun@aosc.io>
• TheBabu <ariq.haqq@gmail.com>
• Brais Couce <braiscouce@gmail.com>
• Mozi <29089388+pzhlkj6612@users.noreply.github.com>
• SyoBoN <syobon@syobon.net>
• Jan Heylen <heyleke@gmail.com>
• tdawe <90407556+tdawe1@users.noreply.github.com>
• Anton Bordwine <54022438+antonchuvashow@users.noreply.github.com>
• mathieulongtin <617359+mathieulongtin@users.noreply.github.com>
• Luke Cyca <me@lukecyca.com>
• dlaumen <262192488+dlaumen@users.noreply.github.com>
• Yakov Till <37628546+Lyapsus@users.noreply.github.com>
• Chris Coughlan <chris@coughlan.io>
• John Volk <volkjohn@users.noreply.github.com>
• 王一赫 <wyihe5220@gmail.com>
• Gustavo V. F. <31892323+Gustavo-V-F@users.noreply.github.com>
• Sven Rebhan <36194019+srebhan@users.noreply.github.com>
• Copilot <223556219+Copilot@users.noreply.github.com>
• KTibow <KTibow@users.noreply.github.com>
• kkocdko <31189892+kkocdko@users.noreply.github.com>
• Tim Schumacher <tim@tschumacher.net>
• ferrumclaudepilgrim <ferrumclaudepilgrim@users.noreply.github.com>
• Alvinwylim <31592545+Alvinwylim@users.noreply.github.com>
• Tore Anderson <tore@fud.no>
• Sai Asish Y <say.apm35@gmail.com>
• Lucky945H <1355363613@qq.com>
• William Tange <github@tan.ge>
• TaterLi <admin@lijingquan.net>
• KyokoMiki <161209740+kyokomiki@users.noreply.github.com>
• Iizuki <36295229+Iizuki@users.noreply.github.com>
• tomholford <16504501+tomholford@users.noreply.github.com> <tomholford@users.noreply.github.com>
• caltechustc <caltechustc@outlook.com>
• Valerij Fredriksen <freva@users.noreply.github.com>
• Hakan İSMAİL <93117749+Hakanbaban53@users.noreply.github.com>
• Brian King <BrianDKing@gmail.com>
• Puneet Dixit <puneetdixit4321@gmail.com>
• Yakov Till <yakov.till@gmail.com>
• Janne Beate Bakeng <436265+jbbakeng@users.noreply.github.com>
• IceLocke <lockeice@gmail.com>
• nako-ruru <nako_ruru@163.com>
• bright <nako_ruru@sina.com>
• Filippo <57143294+FilippoMuschera@users.noreply.github.com>
• Gaurav <amvermagaurav007@gmail.com>
• Yuhang Cao <caoyuhang@fwerkor.com>
• Yash Anil <yashanil98@gmail.com>
• yashanil98 <79158725+yashanil98@users.noreply.github.com>
• lewoberst <github@jan-o-sch.net>
• max <max@example.com>
• Bryan Stenson <bryan.stenson@gmail.com>
• happysnaker <73147033+happysnaker@users.noreply.github.com>
• Jan Schlien <rclone-github@jan-o-sch.net>
• user77 <abubakarm@gmail.com>
• maximilize <3752128+maximilize@users.noreply.github.com>
• dithwick <46924962+dithwick@users.noreply.github.com>
• Sandy Luppino <s.luppino@opendrives.com>
• Sanjays2402 <51058514+Sanjays2402@users.noreply.github.com>
• blackflytech <blackflytech@outlook.com>
• Amit Mishra <amit.mishra.eee21@itbhu.ac.in>
• Erol Ozcan <erol.ozcan@gmail.com>
• TowyTowy <towy@airreps.link>
• 0rangeSeaW0lf <0sw-8m4k2v@waku.li>
• sijie-Z <sijie-zhou@users.noreply.github.com>
• Søren Lindberg <deeferentleeg@gmail.com>
• Kyue <Gooh456@users.noreply.github.com>
• Giridhar <80974392+giri256@users.noreply.github.com>
• p1 <giridharpavan593@gmail.com>
• Zero Services GmbH <info@zeroservices.eu>
• Noah Zalev <github@nzalev.ca>
• Acts1631 <69813585+acts-1631@users.noreply.github.com>
• ifloppy <68799904+ifloppy@users.noreply.github.com>
• Dzmitry Nianakhau <dzmitry.nianakhau@scality.com>
• Anupam Mediratta <mediratta@gmail.com>
• Socialpranker <273312799+Socialpranker@users.noreply.github.com>
• phatlc <phatle.hsd@gmail.com>
• Punya Jain <4511945+punya10@users.noreply.github.com>

okay and that's literally the whole credits roll bestie 😭✨ every single one of them showed up, did the thing, and left their name in the history books. iconic behavior only. slay 💖

---

💌 Contact the rclone project 💌

🌸 Forum

Forum for questions and general discussion:

• <https://forum.rclone.org>

💼 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. yes bestie, your random 3am bug report is welcome here 🫶

🐦 Twitter

You can also follow Nick on twitter for rclone announcements:

• @njcw (<https://twitter.com/njcw>)

📧 Email

Or if all else fails or you want to ask something private or confidential

• <info@rclone.com>

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.

---

👑 AUTHORS 👑

Nick Craig-Wood. 💅

that's it. that's the author. one (1) legend, no cap. 🎀

---

and that's a wrap on this whole entire manual, bestie 🦋 this was User Manual, dated Oct 09, 2026, brought to you as rclone(1). go forth and rclone something gorgeous 💖✨🍓