Preview: MANUAL.html
Size: 1.93 MB
//usr/share/doc/rclone/MANUAL.html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<meta name="author" content="Nick Craig-Wood" />
<title>rclone(1) User Manual</title>
<style>
html {
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 12px;
}
h1 {
font-size: 1.8em;
}
}
@media print {
html {
background-color: white;
}
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
font-size: 85%;
margin: 0;
hyphens: manual;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">rclone(1) User Manual</h1>
<p class="author">Nick Craig-Wood</p>
<p class="date">Sep 09, 2025</p>
</header>
<h1 id="rclone-syncs-your-files-to-cloud-storage">Rclone syncs your
files to cloud storage</h1>
<p><img width="50%" src="logo_on_light__horizontal_color.svg" alt="rclone logo" style="float:right; padding: 5px;" ></p>
<ul>
<li><a href="#about">About rclone</a></li>
<li><a href="#what">What can rclone do for you?</a></li>
<li><a href="#features">What features does rclone have?</a></li>
<li><a href="#providers">What providers does rclone support?</a></li>
<li><a href="https://rclone.org/downloads/">Download</a></li>
<li><a href="https://rclone.org/install/">Install</a></li>
<li><a href="https://rclone.org/donate/">Donate.</a></li>
</ul>
<h2 id="about">About rclone</h2>
<p>Rclone is a command-line program to manage files on cloud storage. It
is a feature-rich alternative to cloud vendors’ web storage interfaces.
<a href="#providers">Over 40 cloud storage products</a> support rclone
including S3 object stores, business & consumer file storage
services, as well as standard transfer protocols.</p>
<p>Rclone has powerful cloud equivalents to the unix commands rsync, cp,
mv, mount, ls, ncdu, tree, rm, and cat. Rclone’s familiar syntax
includes shell pipeline support, and <code>--dry-run</code> protection.
It is used at the command line, in scripts or via its <a
href="/rc">API</a>.</p>
<p>Users call rclone <em>“The Swiss army knife of cloud storage”</em>,
and <em>“Technology indistinguishable from magic”</em>.</p>
<p>Rclone really looks after your data. It preserves timestamps and
verifies checksums at all times. Transfers over limited bandwidth;
intermittent connections, or subject to quota can be restarted, from the
last good file transferred. You can <a
href="https://rclone.org/commands/rclone_check/">check</a> the integrity
of your files. Where possible, rclone employs server-side transfers to
minimise local bandwidth use and transfers from one provider to another
without using local disk.</p>
<p>Virtual backends wrap local and cloud file systems to apply <a
href="https://rclone.org/crypt/">encryption</a>, <a
href="https://rclone.org/compress/">compression</a>, <a
href="https://rclone.org/chunker/">chunking</a>, <a
href="https://rclone.org/hasher/">hashing</a> and <a
href="https://rclone.org/union/">joining</a>.</p>
<p>Rclone <a href="https://rclone.org/commands/rclone_mount/">mounts</a>
any local, cloud or virtual filesystem as a disk on Windows, macOS,
linux and FreeBSD, and also serves these over <a
href="https://rclone.org/commands/rclone_serve_sftp/">SFTP</a>, <a
href="https://rclone.org/commands/rclone_serve_http/">HTTP</a>, <a
href="https://rclone.org/commands/rclone_serve_webdav/">WebDAV</a>, <a
href="https://rclone.org/commands/rclone_serve_ftp/">FTP</a> and <a
href="https://rclone.org/commands/rclone_serve_dlna/">DLNA</a>.</p>
<p>Rclone is mature, open-source software originally inspired by rsync
and written in <a href="https://golang.org">Go</a>. The friendly support
community is familiar with varied use cases. Official Ubuntu, Debian,
Fedora, Brew and Chocolatey repos. include rclone. For the latest
version <a href="https://rclone.org/downloads/">downloading from
rclone.org</a> is recommended.</p>
<p>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.</p>
<p>Rclone does the heavy lifting of communicating with cloud
storage.</p>
<h2 id="what">What can rclone do for you?</h2>
<p>Rclone helps you:</p>
<ul>
<li>Backup (and encrypt) files to cloud storage</li>
<li>Restore (and decrypt) files from cloud storage</li>
<li>Mirror cloud data to other cloud services or locally</li>
<li>Migrate data to the cloud, or between cloud storage vendors</li>
<li>Mount multiple, encrypted, cached or diverse cloud storage as a
disk</li>
<li>Analyse and account for data held on cloud storage using <a
href="https://rclone.org/commands/rclone_lsf/">lsf</a>, <a
href="https://rclone.org/commands/rclone_lsjson/">ljson</a>, <a
href="https://rclone.org/commands/rclone_size/">size</a>, <a
href="https://rclone.org/commands/rclone_ncdu/">ncdu</a></li>
<li><a href="https://rclone.org/union/">Union</a> file systems together
to present multiple local and/or cloud file systems as one</li>
</ul>
<h2 id="features">Features</h2>
<ul>
<li>Transfers
<ul>
<li>MD5, SHA1 hashes are checked at all times for file integrity</li>
<li>Timestamps are preserved on files</li>
<li>Operations can be restarted at any time</li>
<li>Can be to and from network, e.g. two different cloud providers</li>
<li>Can use multi-threaded downloads to local disk</li>
</ul></li>
<li><a href="https://rclone.org/commands/rclone_copy/">Copy</a> new or
changed files to cloud storage</li>
<li><a href="https://rclone.org/commands/rclone_sync/">Sync</a> (one
way) to make a directory identical</li>
<li><a href="https://rclone.org/commands/rclone_move/">Move</a> files to
cloud storage deleting the local after verification</li>
<li><a href="https://rclone.org/commands/rclone_check/">Check</a> hashes
and for missing/extra files</li>
<li><a href="https://rclone.org/commands/rclone_mount/">Mount</a> your
cloud storage as a network disk</li>
<li><a href="https://rclone.org/commands/rclone_serve/">Serve</a> local
or remote files over <a
href="https://rclone.org/commands/rclone_serve_http/">HTTP</a>/<a
href="https://rclone.org/commands/rclone_serve_webdav/">WebDav</a>/<a
href="https://rclone.org/commands/rclone_serve_ftp/">FTP</a>/<a
href="https://rclone.org/commands/rclone_serve_sftp/">SFTP</a>/<a
href="https://rclone.org/commands/rclone_serve_dlna/">DLNA</a></li>
<li>Experimental <a href="https://rclone.org/gui/">Web based
GUI</a></li>
</ul>
<h2 id="providers">Supported providers</h2>
<p>(There are many others, built on standard protocols such as WebDAV or
S3, that work out of the box.)</p>
<ul>
<li>1Fichier</li>
<li>Akamai Netstorage</li>
<li>Alibaba Cloud (Aliyun) Object Storage System (OSS)</li>
<li>Amazon Drive</li>
<li>Amazon S3</li>
<li>Backblaze B2</li>
<li>Box</li>
<li>Ceph</li>
<li>China Mobile Ecloud Elastic Object Storage (EOS)</li>
<li>Arvan Cloud Object Storage (AOS)</li>
<li>Citrix ShareFile</li>
<li>Cloudflare R2</li>
<li>DigitalOcean Spaces</li>
<li>Digi Storage</li>
<li>Dreamhost</li>
<li>Dropbox</li>
<li>Enterprise File Fabric</li>
<li>FTP</li>
<li>Google Cloud Storage</li>
<li>Google Drive</li>
<li>Google Photos</li>
<li>HDFS</li>
<li>Hetzner Storage Box</li>
<li>HiDrive</li>
<li>HTTP</li>
<li>Internet Archive</li>
<li>Jottacloud</li>
<li>IBM COS S3</li>
<li>IDrive e2</li>
<li>IONOS Cloud</li>
<li>Koofr</li>
<li>Mail.ru Cloud</li>
<li>Memset Memstore</li>
<li>Mega</li>
<li>Memory</li>
<li>Microsoft Azure Blob Storage</li>
<li>Microsoft OneDrive</li>
<li>Minio</li>
<li>Nextcloud</li>
<li>OVH</li>
<li>OpenDrive</li>
<li>OpenStack Swift</li>
<li>Oracle Cloud Storage Swift</li>
<li>Oracle Object Storage</li>
<li>ownCloud</li>
<li>pCloud</li>
<li>premiumize.me</li>
<li>put.io</li>
<li>QingStor</li>
<li>Qiniu Cloud Object Storage (Kodo)</li>
<li>Rackspace Cloud Files</li>
<li>rsync.net</li>
<li>Scaleway</li>
<li>Seafile</li>
<li>Seagate Lyve Cloud</li>
<li>SeaweedFS</li>
<li>SFTP</li>
<li>Sia</li>
<li>SMB / CIFS</li>
<li>StackPath</li>
<li>Storj</li>
<li>SugarSync</li>
<li>Tencent Cloud Object Storage (COS)</li>
<li>Uptobox</li>
<li>Wasabi</li>
<li>WebDAV</li>
<li>Yandex Disk</li>
<li>Zoho WorkDrive</li>
<li>The local filesystem</li>
</ul>
<h2 id="virtual-providers">Virtual providers</h2>
<p>These backends adapt or modify other storage providers:</p>
<ul>
<li>Alias: Rename existing remotes</li>
<li>Cache: Cache remotes (DEPRECATED)</li>
<li>Chunker: Split large files</li>
<li>Combine: Combine multiple remotes into a directory tree</li>
<li>Compress: Compress files</li>
<li>Crypt: Encrypt files</li>
<li>Hasher: Hash files</li>
<li>Union: Join multiple remotes to work together</li>
</ul>
<h2 id="links">Links</h2>
<ul>
<li><a href="https://rclone.org/">Home page</a></li>
<li><a href="https://github.com/rclone/rclone">GitHub project page for
source and bug tracker</a></li>
<li><a href="https://forum.rclone.org">Rclone Forum</a></li>
<li><a href="https://rclone.org/downloads/">Downloads</a></li>
</ul>
<h1 id="usage">Usage</h1>
<p>Rclone is a command line program to manage files on cloud storage.
After <a href="https://rclone.org/downloads/">download</a> and <a
href="/install">install</a>, continue here to learn how to use it:
Initial <a href="#configure">configuration</a>, what the <a
href="#basic-syntax">basic syntax</a> looks like, describes the various
<a href="#subcommands">subcommands</a>, the various <a
href="#options">options</a>, and more.</p>
<h2 id="configure">Configure</h2>
<p>First, you’ll need to configure rclone. As the object storage systems
have quite complicated authentication these are kept in a config file.
(See the <a href="#config-config-file"><code>--config</code></a> entry
for how to find the config file and choose its location.)</p>
<p>The easiest way to make the config is to run rclone with the config
option:</p>
<pre><code>rclone config</code></pre>
<p>See the following for detailed instructions for</p>
<ul>
<li><a href="https://rclone.org/fichier/">1Fichier</a></li>
<li><a href="https://rclone.org/netstorage/">Akamai Netstorage</a></li>
<li><a href="https://rclone.org/alias/">Alias</a></li>
<li><a href="https://rclone.org/amazonclouddrive/">Amazon Drive</a></li>
<li><a href="https://rclone.org/s3/">Amazon S3</a></li>
<li><a href="https://rclone.org/b2/">Backblaze B2</a></li>
<li><a href="https://rclone.org/box/">Box</a></li>
<li><a href="https://rclone.org/chunker/">Chunker</a> - transparently
splits large files for other remotes</li>
<li><a href="https://rclone.org/sharefile/">Citrix ShareFile</a></li>
<li><a href="https://rclone.org/compress/">Compress</a></li>
<li><a href="https://rclone.org/combine/">Combine</a></li>
<li><a href="https://rclone.org/crypt/">Crypt</a> - to encrypt other
remotes</li>
<li><a href="https://rclone.org/s3/#digitalocean-spaces">DigitalOcean
Spaces</a></li>
<li><a href="https://rclone.org/koofr/#digi-storage">Digi
Storage</a></li>
<li><a href="https://rclone.org/dropbox/">Dropbox</a></li>
<li><a href="https://rclone.org/filefabric/">Enterprise File
Fabric</a></li>
<li><a href="https://rclone.org/ftp/">FTP</a></li>
<li><a href="https://rclone.org/googlecloudstorage/">Google Cloud
Storage</a></li>
<li><a href="https://rclone.org/drive/">Google Drive</a></li>
<li><a href="https://rclone.org/googlephotos/">Google Photos</a></li>
<li><a href="https://rclone.org/hasher/">Hasher</a> - to handle
checksums for other remotes</li>
<li><a href="https://rclone.org/hdfs/">HDFS</a></li>
<li><a href="https://rclone.org/hidrive/">HiDrive</a></li>
<li><a href="https://rclone.org/http/">HTTP</a></li>
<li><a href="https://rclone.org/internetarchive/">Internet
Archive</a></li>
<li><a href="https://rclone.org/jottacloud/">Jottacloud</a></li>
<li><a href="https://rclone.org/koofr/">Koofr</a></li>
<li><a href="https://rclone.org/mailru/">Mail.ru Cloud</a></li>
<li><a href="https://rclone.org/mega/">Mega</a></li>
<li><a href="https://rclone.org/memory/">Memory</a></li>
<li><a href="https://rclone.org/azureblob/">Microsoft Azure Blob
Storage</a></li>
<li><a href="https://rclone.org/onedrive/">Microsoft OneDrive</a></li>
<li><a href="https://rclone.org/swift/">OpenStack Swift / Rackspace
Cloudfiles / Memset Memstore</a></li>
<li><a href="https://rclone.org/opendrive/">OpenDrive</a></li>
<li><a href="https://rclone.org/oracleobjectstorage/">Oracle Object
Storage</a></li>
<li><a href="https://rclone.org/pcloud/">Pcloud</a></li>
<li><a href="https://rclone.org/premiumizeme/">premiumize.me</a></li>
<li><a href="https://rclone.org/putio/">put.io</a></li>
<li><a href="https://rclone.org/qingstor/">QingStor</a></li>
<li><a href="https://rclone.org/seafile/">Seafile</a></li>
<li><a href="https://rclone.org/sftp/">SFTP</a></li>
<li><a href="https://rclone.org/sia/">Sia</a></li>
<li><a href="https://rclone.org/smb/">SMB</a></li>
<li><a href="https://rclone.org/storj/">Storj</a></li>
<li><a href="https://rclone.org/sugarsync/">SugarSync</a></li>
<li><a href="https://rclone.org/union/">Union</a></li>
<li><a href="https://rclone.org/uptobox/">Uptobox</a></li>
<li><a href="https://rclone.org/webdav/">WebDAV</a></li>
<li><a href="https://rclone.org/yandex/">Yandex Disk</a></li>
<li><a href="https://rclone.org/zoho/">Zoho WorkDrive</a></li>
<li><a href="https://rclone.org/local/">The local filesystem</a></li>
</ul>
<h2 id="basic-syntax">Basic syntax</h2>
<p>Rclone syncs a directory tree from one storage system to another.</p>
<p>Its syntax is like this</p>
<pre><code>Syntax: [options] subcommand <parameters> <parameters...></code></pre>
<p>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.</p>
<p>You can define as many storage paths as you like in the config
file.</p>
<p>Please use the <a href="#interactive"><code>-i</code> /
<code>--interactive</code></a> flag while learning rclone to avoid
accidental data loss.</p>
<h2 id="subcommands">Subcommands</h2>
<p>rclone uses a system of subcommands. For example</p>
<pre><code>rclone ls remote:path # lists a remote
rclone copy /local/path remote:path # copies /local/path to the remote
rclone sync -i /local/path remote:path # syncs /local/path to the remote</code></pre>
<h1 id="rclone-config">rclone config</h1>
<p>Enter an interactive configuration session.</p>
<h2 id="synopsis">Synopsis</h2>
<p>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.</p>
<pre><code>rclone config [flags]</code></pre>
<h2 id="options">Options</h2>
<pre><code> -h, --help help for config</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
<li><a href="https://rclone.org/commands/rclone_config_create/">rclone
config create</a> - Create a new remote with name, type and
options.</li>
<li><a href="https://rclone.org/commands/rclone_config_delete/">rclone
config delete</a> - Delete an existing remote.</li>
<li><a
href="https://rclone.org/commands/rclone_config_disconnect/">rclone
config disconnect</a> - Disconnects user from remote</li>
<li><a href="https://rclone.org/commands/rclone_config_dump/">rclone
config dump</a> - Dump the config file as JSON.</li>
<li><a href="https://rclone.org/commands/rclone_config_file/">rclone
config file</a> - Show path of configuration file in use.</li>
<li><a href="https://rclone.org/commands/rclone_config_password/">rclone
config password</a> - Update password in an existing remote.</li>
<li><a href="https://rclone.org/commands/rclone_config_paths/">rclone
config paths</a> - Show paths used for configuration, cache, temp
etc.</li>
<li><a
href="https://rclone.org/commands/rclone_config_providers/">rclone
config providers</a> - List in JSON format all the providers and
options.</li>
<li><a
href="https://rclone.org/commands/rclone_config_reconnect/">rclone
config reconnect</a> - Re-authenticates user with remote.</li>
<li><a href="https://rclone.org/commands/rclone_config_show/">rclone
config show</a> - Print (decrypted) config file, or the config for a
single remote.</li>
<li><a href="https://rclone.org/commands/rclone_config_touch/">rclone
config touch</a> - Ensure configuration file exists.</li>
<li><a href="https://rclone.org/commands/rclone_config_update/">rclone
config update</a> - Update options in an existing remote.</li>
<li><a href="https://rclone.org/commands/rclone_config_userinfo/">rclone
config userinfo</a> - Prints info about logged in user of remote.</li>
</ul>
<h1 id="rclone-copy">rclone copy</h1>
<p>Copy files from source to dest, skipping identical files.</p>
<h2 id="synopsis-1">Synopsis</h2>
<p>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
<a href="https://rclone.org/commands/rclone_sync/">sync</a> command
instead.</p>
<p>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.</p>
<p>To copy single files, use the <a
href="https://rclone.org/commands/rclone_copyto/">copyto</a> command
instead.</p>
<p>If dest:path doesn’t exist, it is created and the source:path
contents go there.</p>
<p>For example</p>
<pre><code>rclone copy source:sourcepath dest:destpath</code></pre>
<p>Let’s say there are two files in sourcepath</p>
<pre><code>sourcepath/one.txt
sourcepath/two.txt</code></pre>
<p>This copies them to</p>
<pre><code>destpath/one.txt
destpath/two.txt</code></pre>
<p>Not to</p>
<pre><code>destpath/sourcepath/one.txt
destpath/sourcepath/two.txt</code></pre>
<p>If you are familiar with <code>rsync</code>, rclone always works as
if you had written a trailing <code>/</code> - meaning “copy the
contents of this directory”. This applies to all commands and whether
you are talking about the source or destination.</p>
<p>See the <a
href="https://rclone.org/docs/#no-traverse">–no-traverse</a> 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.</p>
<p>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:</p>
<pre><code>rclone copy --max-age 24h --no-traverse /path/to/src remote:</code></pre>
<p><strong>Note</strong>: Use the
<code>-P</code>/<code>--progress</code> flag to view real-time transfer
statistics.</p>
<p><strong>Note</strong>: Use the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag to test without copying
anything.</p>
<pre><code>rclone copy source:path dest:path [flags]</code></pre>
<h2 id="options-1">Options</h2>
<pre><code> --create-empty-src-dirs Create empty source dirs on destination after copy
-h, --help help for copy</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-1">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-sync">rclone sync</h1>
<p>Make source and dest identical, modifying destination only.</p>
<h2 id="synopsis-2">Synopsis</h2>
<p>Sync the source to the destination, changing the destination only.
Doesn’t transfer files that are identical on source and destination,
testing by size and modification time or MD5SUM. Destination is updated
to match source, including deleting files if necessary (except duplicate
objects, see below). If you don’t want to delete files from destination,
use the <a href="https://rclone.org/commands/rclone_copy/">copy</a>
command instead.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<pre><code>rclone sync -i SOURCE remote:DESTINATION</code></pre>
<p>Note that files in the destination won’t be deleted if there were any
errors at any point. Duplicate objects (files with the same name, on
those providers that support it) are also not yet handled.</p>
<p>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. See
extended explanation in the <a
href="https://rclone.org/commands/rclone_copy/">copy</a> command if
unsure.</p>
<p>If dest:path doesn’t exist, it is created and the source:path
contents go there.</p>
<p>It is not possible to sync overlapping remotes. However, you may
exclude the destination from the sync with a filter rule or by putting
an exclude-if-present file inside the destination directory and sync to
a destination that is inside the source directory.</p>
<p><strong>Note</strong>: Use the
<code>-P</code>/<code>--progress</code> flag to view real-time transfer
statistics</p>
<p><strong>Note</strong>: Use the <code>rclone dedupe</code> command to
deal with “Duplicate object/directory found in source/destination -
ignoring” errors. See <a
href="https://forum.rclone.org/t/sync-not-clearing-duplicates/14372">this
forum post</a> for more info.</p>
<pre><code>rclone sync source:path dest:path [flags]</code></pre>
<h2 id="options-2">Options</h2>
<pre><code> --create-empty-src-dirs Create empty source dirs on destination after sync
-h, --help help for sync</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-2">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-move">rclone move</h1>
<p>Move files from source to dest.</p>
<h2 id="synopsis-3">Synopsis</h2>
<p>Moves the contents of the source directory to the destination
directory. Rclone will error if the source and destination overlap and
the remote does not support a server-side directory move operation.</p>
<p>To move single files, use the <a
href="https://rclone.org/commands/rclone_moveto/">moveto</a> command
instead.</p>
<p>If no filters are in use and if possible this will server-side move
<code>source:path</code> into <code>dest:path</code>. After this
<code>source:path</code> will no longer exist.</p>
<p>Otherwise for each file in <code>source:path</code> selected by the
filters (if any) this will move it into <code>dest:path</code>. If
possible a server-side move will be used, otherwise it will copy it
(server-side if possible) into <code>dest:path</code> then delete the
original (if no errors on copy) in <code>source:path</code>.</p>
<p>If you want to delete empty source directories after move, use the
<code>--delete-empty-src-dirs</code> flag.</p>
<p>See the <a
href="https://rclone.org/docs/#no-traverse">–no-traverse</a> option for
controlling whether rclone lists the destination directory or not.
Supplying this option when moving a small number of files into a large
destination can speed transfers up greatly.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<p><strong>Note</strong>: Use the
<code>-P</code>/<code>--progress</code> flag to view real-time transfer
statistics.</p>
<pre><code>rclone move source:path dest:path [flags]</code></pre>
<h2 id="options-3">Options</h2>
<pre><code> --create-empty-src-dirs Create empty source dirs on destination after move
--delete-empty-src-dirs Delete empty source dirs after move
-h, --help help for move</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-3">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-delete">rclone delete</h1>
<p>Remove the files in path.</p>
<h2 id="synopsis-4">Synopsis</h2>
<p>Remove the files in path. Unlike <a
href="https://rclone.org/commands/rclone_purge/">purge</a> it obeys
include/exclude filters so can be used to selectively delete files.</p>
<p><code>rclone delete</code> only deletes files but leaves the
directory structure alone. If you want to delete a directory and all of
its contents use the <a
href="https://rclone.org/commands/rclone_purge/">purge</a> command.</p>
<p>If you supply the <code>--rmdirs</code> flag, it will remove all
empty directories along with it. You can also use the separate command
<a href="https://rclone.org/commands/rclone_rmdir/">rmdir</a> or <a
href="https://rclone.org/commands/rclone_rmdirs/">rmdirs</a> to delete
empty directories only.</p>
<p>For example, to delete all files bigger than 100 MiB, you may first
want to check what would be deleted (use either):</p>
<pre><code>rclone --min-size 100M lsl remote:path
rclone --dry-run --min-size 100M delete remote:path</code></pre>
<p>Then proceed with the actual delete:</p>
<pre><code>rclone --min-size 100M delete remote:path</code></pre>
<p>That reads “delete everything with a minimum size of 100 MiB”, hence
delete all files bigger than 100 MiB.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<pre><code>rclone delete remote:path [flags]</code></pre>
<h2 id="options-4">Options</h2>
<pre><code> -h, --help help for delete
--rmdirs rmdirs removes empty directories but leaves root intact</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-4">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-purge">rclone purge</h1>
<p>Remove the path and all of its contents.</p>
<h2 id="synopsis-5">Synopsis</h2>
<p>Remove the path and all of its contents. Note that this does not obey
include/exclude filters - everything will be removed. Use the <a
href="https://rclone.org/commands/rclone_delete/">delete</a> command if
you want to selectively delete files. To delete empty directories only,
use command <a
href="https://rclone.org/commands/rclone_rmdir/">rmdir</a> or <a
href="https://rclone.org/commands/rclone_rmdirs/">rmdirs</a>.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<pre><code>rclone purge remote:path [flags]</code></pre>
<h2 id="options-5">Options</h2>
<pre><code> -h, --help help for purge</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-5">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-mkdir">rclone mkdir</h1>
<p>Make the path if it doesn’t already exist.</p>
<pre><code>rclone mkdir remote:path [flags]</code></pre>
<h2 id="options-6">Options</h2>
<pre><code> -h, --help help for mkdir</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-6">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-rmdir">rclone rmdir</h1>
<p>Remove the empty directory at path.</p>
<h2 id="synopsis-6">Synopsis</h2>
<p>This removes empty directory given by path. Will not remove the path
if it has any objects in it, not even empty subdirectories. Use command
<a href="https://rclone.org/commands/rclone_rmdirs/">rmdirs</a> (or <a
href="https://rclone.org/commands/rclone_delete/">delete</a> with option
<code>--rmdirs</code>) to do that.</p>
<p>To delete a path and any objects in it, use <a
href="https://rclone.org/commands/rclone_purge/">purge</a> command.</p>
<pre><code>rclone rmdir remote:path [flags]</code></pre>
<h2 id="options-7">Options</h2>
<pre><code> -h, --help help for rmdir</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-7">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-check">rclone check</h1>
<p>Checks the files in the source and destination match.</p>
<h2 id="synopsis-7">Synopsis</h2>
<p>Checks the files in the source and destination match. It compares
sizes and hashes (MD5 or SHA1) and logs a report of files that don’t
match. It doesn’t alter the source or destination.</p>
<p>For the <a href="https://rclone.org/crypt/">crypt</a> remote there is
a dedicated command, <a
href="https://rclone.org/commands/rclone_cryptcheck/">cryptcheck</a>,
that are able to check the checksums of the crypted files.</p>
<p>If you supply the <code>--size-only</code> flag, it will only compare
the sizes not the hashes as well. Use this for a quick check.</p>
<p>If you supply the <code>--download</code> 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.</p>
<p>If you supply the <code>--checkfile HASH</code> flag with a valid
hash name, the <code>source:path</code> must point to a text file in the
SUM format.</p>
<p>If you supply the <code>--one-way</code> 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.</p>
<p>The <code>--differ</code>, <code>--missing-on-dst</code>,
<code>--missing-on-src</code>, <code>--match</code> and
<code>--error</code> flags write paths, one per line, to the file name
(or stdout if it is <code>-</code>) supplied. What they write is
described in the help below. For example <code>--differ</code> will
write all paths which are present on both the source and destination but
different.</p>
<p>The <code>--combined</code> 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.</p>
<ul>
<li><code>= path</code> means path was found in source and destination
and was identical</li>
<li><code>- path</code> means path was missing on the source, so only in
the destination</li>
<li><code>+ path</code> means path was missing on the destination, so
only in the source</li>
<li><code>* path</code> means path was present in source and destination
but different.</li>
<li><code>! path</code> means there was an error reading or hashing the
source or dest.</li>
</ul>
<pre><code>rclone check source:path dest:path [flags]</code></pre>
<h2 id="options-8">Options</h2>
<pre><code> -C, --checkfile string Treat source:path as a SUM file with hashes of 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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-8">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-ls">rclone ls</h1>
<p>List the objects in the path with size and path.</p>
<h2 id="synopsis-8">Synopsis</h2>
<p>Lists the objects in the source path to standard output in a human
readable format with size and path. Recurses by default.</p>
<p>Eg</p>
<pre><code>$ rclone ls swift:bucket
60295 bevajer5jef
90613 canole
94467 diwogej7
37600 fubuwic</code></pre>
<p>Any of the filtering options can be applied to this command.</p>
<p>There are several related list commands</p>
<ul>
<li><code>ls</code> to list size and path of objects only</li>
<li><code>lsl</code> to list modification time, size and path of objects
only</li>
<li><code>lsd</code> to list directories only</li>
<li><code>lsf</code> to list objects and directories in easy to parse
format</li>
<li><code>lsjson</code> to list objects and directories in JSON
format</li>
</ul>
<p><code>ls</code>,<code>lsl</code>,<code>lsd</code> are designed to be
human-readable. <code>lsf</code> is designed to be human and
machine-readable. <code>lsjson</code> is designed to be
machine-readable.</p>
<p>Note that <code>ls</code> and <code>lsl</code> recurse by default -
use <code>--max-depth 1</code> to stop the recursion.</p>
<p>The other list commands
<code>lsd</code>,<code>lsf</code>,<code>lsjson</code> do not recurse by
default - use <code>-R</code> to make them recurse.</p>
<p>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).</p>
<pre><code>rclone ls remote:path [flags]</code></pre>
<h2 id="options-9">Options</h2>
<pre><code> -h, --help help for ls</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-9">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-lsd">rclone lsd</h1>
<p>List all directories/containers/buckets in the path.</p>
<h2 id="synopsis-9">Synopsis</h2>
<p>Lists the directories in the source path to standard output. Does not
recurse by default. Use the <code>-R</code> flag to recurse.</p>
<p>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, Eg</p>
<pre><code>$ rclone lsd swift:
494000 2018-04-26 08:43:20 10000 10000files
65 2018-04-26 08:43:20 1 1File</code></pre>
<p>Or</p>
<pre><code>$ 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</code></pre>
<p>If you just want the directory names use
<code>rclone lsf --dirs-only</code>.</p>
<p>Any of the filtering options can be applied to this command.</p>
<p>There are several related list commands</p>
<ul>
<li><code>ls</code> to list size and path of objects only</li>
<li><code>lsl</code> to list modification time, size and path of objects
only</li>
<li><code>lsd</code> to list directories only</li>
<li><code>lsf</code> to list objects and directories in easy to parse
format</li>
<li><code>lsjson</code> to list objects and directories in JSON
format</li>
</ul>
<p><code>ls</code>,<code>lsl</code>,<code>lsd</code> are designed to be
human-readable. <code>lsf</code> is designed to be human and
machine-readable. <code>lsjson</code> is designed to be
machine-readable.</p>
<p>Note that <code>ls</code> and <code>lsl</code> recurse by default -
use <code>--max-depth 1</code> to stop the recursion.</p>
<p>The other list commands
<code>lsd</code>,<code>lsf</code>,<code>lsjson</code> do not recurse by
default - use <code>-R</code> to make them recurse.</p>
<p>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).</p>
<pre><code>rclone lsd remote:path [flags]</code></pre>
<h2 id="options-10">Options</h2>
<pre><code> -h, --help help for lsd
-R, --recursive Recurse into the listing</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-10">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-lsl">rclone lsl</h1>
<p>List the objects in path with modification time, size and path.</p>
<h2 id="synopsis-10">Synopsis</h2>
<p>Lists the objects in the source path to standard output in a human
readable format with modification time, size and path. Recurses by
default.</p>
<p>Eg</p>
<pre><code>$ 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</code></pre>
<p>Any of the filtering options can be applied to this command.</p>
<p>There are several related list commands</p>
<ul>
<li><code>ls</code> to list size and path of objects only</li>
<li><code>lsl</code> to list modification time, size and path of objects
only</li>
<li><code>lsd</code> to list directories only</li>
<li><code>lsf</code> to list objects and directories in easy to parse
format</li>
<li><code>lsjson</code> to list objects and directories in JSON
format</li>
</ul>
<p><code>ls</code>,<code>lsl</code>,<code>lsd</code> are designed to be
human-readable. <code>lsf</code> is designed to be human and
machine-readable. <code>lsjson</code> is designed to be
machine-readable.</p>
<p>Note that <code>ls</code> and <code>lsl</code> recurse by default -
use <code>--max-depth 1</code> to stop the recursion.</p>
<p>The other list commands
<code>lsd</code>,<code>lsf</code>,<code>lsjson</code> do not recurse by
default - use <code>-R</code> to make them recurse.</p>
<p>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).</p>
<pre><code>rclone lsl remote:path [flags]</code></pre>
<h2 id="options-11">Options</h2>
<pre><code> -h, --help help for lsl</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-11">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-md5sum">rclone md5sum</h1>
<p>Produces an md5sum file for all the objects in the path.</p>
<h2 id="synopsis-11">Synopsis</h2>
<p>Produces an md5sum file for all the objects in the path. This is in
the same format as the standard md5sum tool produces.</p>
<p>By default, the hash is requested from the remote. If MD5 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 MD5 for any remote.</p>
<p>For other algorithms, see the <a
href="https://rclone.org/commands/rclone_hashsum/">hashsum</a> command.
Running <code>rclone md5sum remote:path</code> is equivalent to running
<code>rclone hashsum MD5 remote:path</code>.</p>
<p>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).</p>
<pre><code>rclone md5sum remote:path [flags]</code></pre>
<h2 id="options-12">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-12">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-sha1sum">rclone sha1sum</h1>
<p>Produces an sha1sum file for all the objects in the path.</p>
<h2 id="synopsis-12">Synopsis</h2>
<p>Produces an sha1sum file for all the objects in the path. This is in
the same format as the standard sha1sum tool produces.</p>
<p>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.</p>
<p>For other algorithms, see the <a
href="https://rclone.org/commands/rclone_hashsum/">hashsum</a> command.
Running <code>rclone sha1sum remote:path</code> is equivalent to running
<code>rclone hashsum SHA1 remote:path</code>.</p>
<p>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).</p>
<p>This command can also hash data received on STDIN, if not passing a
remote:path.</p>
<pre><code>rclone sha1sum remote:path [flags]</code></pre>
<h2 id="options-13">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-13">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-size">rclone size</h1>
<p>Prints the total size and number of objects in remote:path.</p>
<h2 id="synopsis-13">Synopsis</h2>
<p>Counts objects in the path and calculates the total size. Prints the
result to standard output.</p>
<p>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
<code>--human-readable</code> is not considered). Use option
<code>--json</code> to format output as JSON instead.</p>
<p>Recurses by default, use <code>--max-depth 1</code> to stop the
recursion.</p>
<p>Some backends do not always provide file sizes, see for example <a
href="https://rclone.org/googlephotos/#size">Google Photos</a> and <a
href="https://rclone.org/drive/#limitations-of-google-docs">Google
Drive</a>. 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.</p>
<pre><code>rclone size remote:path [flags]</code></pre>
<h2 id="options-14">Options</h2>
<pre><code> -h, --help help for size
--json Format output as JSON</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-14">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-version">rclone version</h1>
<p>Show the version number.</p>
<h2 id="synopsis-14">Synopsis</h2>
<p>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).</p>
<p>For example:</p>
<pre><code>$ 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</code></pre>
<p>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”.</p>
<p>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.</p>
<pre><code>$ rclone version --check
yours: 1.42.0.6
latest: 1.42 (released 2018-06-16)
beta: 1.42.0.5 (released 2018-06-17)</code></pre>
<p>Or</p>
<pre><code>$ 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</code></pre>
<pre><code>rclone version [flags]</code></pre>
<h2 id="options-15">Options</h2>
<pre><code> --check Check for new version
-h, --help help for version</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-15">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-cleanup">rclone cleanup</h1>
<p>Clean up the remote if possible.</p>
<h2 id="synopsis-15">Synopsis</h2>
<p>Clean up the remote if possible. Empty the trash or delete old file
versions. Not supported by all remotes.</p>
<pre><code>rclone cleanup remote:path [flags]</code></pre>
<h2 id="options-16">Options</h2>
<pre><code> -h, --help help for cleanup</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-16">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-dedupe">rclone dedupe</h1>
<p>Interactively find duplicate filenames and delete/rename them.</p>
<h2 id="synopsis-16">Synopsis</h2>
<p>By default <code>dedupe</code> 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.</p>
<p>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.</p>
<p>However if <code>--by-hash</code> 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.</p>
<p>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.</p>
<p>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
<code>dedupe</code> command will not be interactive.</p>
<p><code>dedupe</code> 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 <code>--size-only</code> 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.</p>
<p>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.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<p>Here is an example run.</p>
<p>Before - with duplicates</p>
<pre><code>$ 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</code></pre>
<p>Now the <code>dedupe</code> session</p>
<pre><code>$ 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</code></pre>
<p>The result being</p>
<pre><code>$ 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</code></pre>
<p>Dedupe can be run non interactively using the
<code>--dedupe-mode</code> flag or by using an extra parameter with the
same value</p>
<ul>
<li><code>--dedupe-mode interactive</code> - interactive as above.</li>
<li><code>--dedupe-mode skip</code> - removes identical files then skips
anything left.</li>
<li><code>--dedupe-mode first</code> - removes identical files then
keeps the first one.</li>
<li><code>--dedupe-mode newest</code> - removes identical files then
keeps the newest one.</li>
<li><code>--dedupe-mode oldest</code> - removes identical files then
keeps the oldest one.</li>
<li><code>--dedupe-mode largest</code> - removes identical files then
keeps the largest one.</li>
<li><code>--dedupe-mode smallest</code> - removes identical files then
keeps the smallest one.</li>
<li><code>--dedupe-mode rename</code> - removes identical files then
renames the rest to be different.</li>
<li><code>--dedupe-mode list</code> - lists duplicate dirs and files
only and changes nothing.</li>
</ul>
<p>For example, to rename all the identically named photos in your
Google Photos directory, do</p>
<pre><code>rclone dedupe --dedupe-mode rename "drive:Google Photos"</code></pre>
<p>Or</p>
<pre><code>rclone dedupe rename "drive:Google Photos"</code></pre>
<pre><code>rclone dedupe [mode] remote:path [flags]</code></pre>
<h2 id="options-17">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-17">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-about">rclone about</h1>
<p>Get quota information from the remote.</p>
<h2 id="synopsis-17">Synopsis</h2>
<p><code>rclone about</code> prints quota information about a remote to
standard output. The output is typically used, free, quota and trash
contents.</p>
<p>E.g. Typical output from <code>rclone about remote:</code> is:</p>
<pre><code>Total: 17 GiB
Used: 7.444 GiB
Free: 1.315 GiB
Trashed: 100.000 MiB
Other: 8.241 GiB</code></pre>
<p>Where the fields are:</p>
<ul>
<li>Total: Total size available.</li>
<li>Used: Total size used.</li>
<li>Free: Total space available to this user.</li>
<li>Trashed: Total space used by trash.</li>
<li>Other: Total amount in other storage (e.g. Gmail, Google
Photos).</li>
<li>Objects: Total number of objects in the storage.</li>
</ul>
<p>All sizes are in number of bytes.</p>
<p>Applying a <code>--full</code> flag to the command prints the bytes
in full, e.g.</p>
<pre><code>Total: 18253611008
Used: 7993453766
Free: 1411001220
Trashed: 104857602
Other: 8849156022</code></pre>
<p>A <code>--json</code> flag generates conveniently machine-readable
output, e.g.</p>
<pre><code>{
"total": 18253611008,
"used": 7993453766,
"trashed": 104857602,
"other": 8849156022,
"free": 1411001220
}</code></pre>
<p>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.</p>
<p>Some backends does not support the <code>rclone about</code> command
at all, see complete list in <a
href="https://rclone.org/overview/#optional-features">documentation</a>.</p>
<pre><code>rclone about remote: [flags]</code></pre>
<h2 id="options-18">Options</h2>
<pre><code> --full Full numbers instead of human-readable
-h, --help help for about
--json Format output as JSON</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-18">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-authorize">rclone authorize</h1>
<p>Remote authorization.</p>
<h2 id="synopsis-18">Synopsis</h2>
<p>Remote authorization. Used to authorize a remote or headless rclone
from a machine with a browser - use as instructed by rclone config.</p>
<p>Use the –auth-no-open-browser to prevent rclone to open auth link in
default browser automatically.</p>
<pre><code>rclone authorize [flags]</code></pre>
<h2 id="options-19">Options</h2>
<pre><code> --auth-no-open-browser Do not automatically open auth link in default browser
-h, --help help for authorize</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-19">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-backend">rclone backend</h1>
<p>Run a backend-specific command.</p>
<h2 id="synopsis-19">Synopsis</h2>
<p>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.</p>
<p>You can discover what commands a backend implements by using</p>
<pre><code>rclone backend help remote:
rclone backend help <backendname></code></pre>
<p>You can also discover information about the backend using (see <a
href="https://rclone.org/rc/#operations-fsinfo">operations/fsinfo</a> in
the remote control docs for more info).</p>
<pre><code>rclone backend features remote:</code></pre>
<p>Pass options to the backend command with -o. This should be key=value
or key, e.g.:</p>
<pre><code>rclone backend stats remote:path stats -o format=json -o long</code></pre>
<p>Pass arguments to the backend by placing them on the end of the
line</p>
<pre><code>rclone backend cleanup remote:path file1 file2 file3</code></pre>
<p>Note to run these commands on a running backend then see <a
href="https://rclone.org/rc/#backend-command">backend/command</a> in the
rc docs.</p>
<pre><code>rclone backend <command> remote:path [opts] <args> [flags]</code></pre>
<h2 id="options-20">Options</h2>
<pre><code> -h, --help help for backend
--json Always output in JSON format
-o, --option stringArray Option in the form name=value or name</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-20">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-bisync">rclone bisync</h1>
<p>Perform bidirectional synchronization between two paths.</p>
<h2 id="synopsis-20">Synopsis</h2>
<p>Perform bidirectional synchronization between two paths.</p>
<p><a href="https://rclone.org/bisync/">Bisync</a> 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 <code>New</code>, <code>Newer</code>,
<code>Older</code>, and <code>Deleted</code> files. - Propagate changes
on Path1 to Path2, and vice-versa.</p>
<p>See <a href="https://rclone.org/bisync/">full bisync description</a>
for details.</p>
<pre><code>rclone bisync remote1:path1 remote2:path2 [flags]</code></pre>
<h2 id="options-21">Options</h2>
<pre><code> --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")
--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
--localtime Use local time in listings (default: UTC)
--no-cleanup Retain working files (useful for troubleshooting and testing).
--remove-empty-dirs Remove empty directories at the final cleanup step.
-1, --resync Performs the resync run. Path1 files may overwrite Path2 versions. Consider using --verbose or --dry-run first.
--workdir string Use custom working dir - useful for testing. (default: $HOME/.cache/rclone/bisync)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-21">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-cat">rclone cat</h1>
<p>Concatenates any files and sends them to stdout.</p>
<h2 id="synopsis-21">Synopsis</h2>
<p>rclone cat sends any files to standard output.</p>
<p>You can use it like this to output a single file</p>
<pre><code>rclone cat remote:path/to/file</code></pre>
<p>Or like this to output any file in dir or its subdirectories.</p>
<pre><code>rclone cat remote:path/to/dir</code></pre>
<p>Or like this to output any .txt files in dir or its
subdirectories.</p>
<pre><code>rclone --include "*.txt" cat remote:path/to/dir</code></pre>
<p>Use the <code>--head</code> flag to print characters only at the
start, <code>--tail</code> for the end and <code>--offset</code> and
<code>--count</code> to print a section in the middle. Note that if
offset is negative it will count from the end, so
<code>--offset -1 --count 1</code> is equivalent to
<code>--tail 1</code>.</p>
<pre><code>rclone cat remote:path [flags]</code></pre>
<h2 id="options-22">Options</h2>
<pre><code> --count int Only print N characters (default -1)
--discard Discard the output instead of printing
--head int Only print the first N characters
-h, --help help for cat
--offset int Start printing at offset N (or from end if -ve)
--tail int Only print the last N characters</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-22">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-checksum">rclone checksum</h1>
<p>Checks the files in the source against a SUM file.</p>
<h2 id="synopsis-22">Synopsis</h2>
<p>Checks that hashsums of source files match the SUM file. It compares
hashes (MD5, SHA1, etc) and logs a report of files which don’t match. It
doesn’t alter the file system.</p>
<p>If you supply the <code>--download</code> flag, it will download the
data from remote and calculate the contents hash on the fly. This can be
useful for remotes that don’t support hashes or if you really want to
check all the data.</p>
<p>Note that hash values in the SUM file are treated as case
insensitive.</p>
<p>If you supply the <code>--one-way</code> 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.</p>
<p>The <code>--differ</code>, <code>--missing-on-dst</code>,
<code>--missing-on-src</code>, <code>--match</code> and
<code>--error</code> flags write paths, one per line, to the file name
(or stdout if it is <code>-</code>) supplied. What they write is
described in the help below. For example <code>--differ</code> will
write all paths which are present on both the source and destination but
different.</p>
<p>The <code>--combined</code> 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.</p>
<ul>
<li><code>= path</code> means path was found in source and destination
and was identical</li>
<li><code>- path</code> means path was missing on the source, so only in
the destination</li>
<li><code>+ path</code> means path was missing on the destination, so
only in the source</li>
<li><code>* path</code> means path was present in source and destination
but different.</li>
<li><code>! path</code> means there was an error reading or hashing the
source or dest.</li>
</ul>
<pre><code>rclone checksum <hash> sumfile src:path [flags]</code></pre>
<h2 id="options-23">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-23">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-completion">rclone completion</h1>
<p>Generate the autocompletion script for the specified shell</p>
<h2 id="synopsis-23">Synopsis</h2>
<p>Generate the autocompletion script for rclone for the specified
shell. See each sub-command’s help for details on how to use the
generated script.</p>
<h2 id="options-24">Options</h2>
<pre><code> -h, --help help for completion</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-24">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
<li><a href="https://rclone.org/commands/rclone_completion_bash/">rclone
completion bash</a> - Generate the autocompletion script for bash</li>
<li><a href="https://rclone.org/commands/rclone_completion_fish/">rclone
completion fish</a> - Generate the autocompletion script for fish</li>
<li><a
href="https://rclone.org/commands/rclone_completion_powershell/">rclone
completion powershell</a> - Generate the autocompletion script for
powershell</li>
<li><a href="https://rclone.org/commands/rclone_completion_zsh/">rclone
completion zsh</a> - Generate the autocompletion script for zsh</li>
</ul>
<h1 id="rclone-completion-bash">rclone completion bash</h1>
<p>Generate the autocompletion script for bash</p>
<h2 id="synopsis-24">Synopsis</h2>
<p>Generate the autocompletion script for the bash shell.</p>
<p>This script depends on the ‘bash-completion’ package. If it is not
installed already, you can install it via your OS’s package manager.</p>
<p>To load completions in your current shell session:</p>
<pre><code>source <(rclone completion bash)</code></pre>
<p>To load completions for every new session, execute once:</p>
<h3 id="linux">Linux:</h3>
<pre><code>rclone completion bash > /etc/bash_completion.d/rclone</code></pre>
<h3 id="macos">macOS:</h3>
<pre><code>rclone completion bash > $(brew --prefix)/etc/bash_completion.d/rclone</code></pre>
<p>You will need to start a new shell for this setup to take effect.</p>
<pre><code>rclone completion bash</code></pre>
<h2 id="options-25">Options</h2>
<pre><code> -h, --help help for bash
--no-descriptions disable completion descriptions</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-25">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_completion/">rclone
completion</a> - Generate the autocompletion script for the specified
shell</li>
</ul>
<h1 id="rclone-completion-fish">rclone completion fish</h1>
<p>Generate the autocompletion script for fish</p>
<h2 id="synopsis-25">Synopsis</h2>
<p>Generate the autocompletion script for the fish shell.</p>
<p>To load completions in your current shell session:</p>
<pre><code>rclone completion fish | source</code></pre>
<p>To load completions for every new session, execute once:</p>
<pre><code>rclone completion fish > ~/.config/fish/completions/rclone.fish</code></pre>
<p>You will need to start a new shell for this setup to take effect.</p>
<pre><code>rclone completion fish [flags]</code></pre>
<h2 id="options-26">Options</h2>
<pre><code> -h, --help help for fish
--no-descriptions disable completion descriptions</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-26">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_completion/">rclone
completion</a> - Generate the autocompletion script for the specified
shell</li>
</ul>
<h1 id="rclone-completion-powershell">rclone completion powershell</h1>
<p>Generate the autocompletion script for powershell</p>
<h2 id="synopsis-26">Synopsis</h2>
<p>Generate the autocompletion script for powershell.</p>
<p>To load completions in your current shell session:</p>
<pre><code>rclone completion powershell | Out-String | Invoke-Expression</code></pre>
<p>To load completions for every new session, add the output of the
above command to your powershell profile.</p>
<pre><code>rclone completion powershell [flags]</code></pre>
<h2 id="options-27">Options</h2>
<pre><code> -h, --help help for powershell
--no-descriptions disable completion descriptions</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-27">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_completion/">rclone
completion</a> - Generate the autocompletion script for the specified
shell</li>
</ul>
<h1 id="rclone-completion-zsh">rclone completion zsh</h1>
<p>Generate the autocompletion script for zsh</p>
<h2 id="synopsis-27">Synopsis</h2>
<p>Generate the autocompletion script for the zsh shell.</p>
<p>If shell completion is not already enabled in your environment you
will need to enable it. You can execute the following once:</p>
<pre><code>echo "autoload -U compinit; compinit" >> ~/.zshrc</code></pre>
<p>To load completions in your current shell session:</p>
<pre><code>source <(rclone completion zsh); compdef _rclone rclone</code></pre>
<p>To load completions for every new session, execute once:</p>
<h3 id="linux-1">Linux:</h3>
<pre><code>rclone completion zsh > "${fpath[1]}/_rclone"</code></pre>
<h3 id="macos-1">macOS:</h3>
<pre><code>rclone completion zsh > $(brew --prefix)/share/zsh/site-functions/_rclone</code></pre>
<p>You will need to start a new shell for this setup to take effect.</p>
<pre><code>rclone completion zsh [flags]</code></pre>
<h2 id="options-28">Options</h2>
<pre><code> -h, --help help for zsh
--no-descriptions disable completion descriptions</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-28">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_completion/">rclone
completion</a> - Generate the autocompletion script for the specified
shell</li>
</ul>
<h1 id="rclone-config-create">rclone config create</h1>
<p>Create a new remote with name, type and options.</p>
<h2 id="synopsis-28">Synopsis</h2>
<p>Create a new remote of <code>name</code> with <code>type</code> and
options. The options should be passed in pairs of <code>key</code>
<code>value</code> or as <code>key=value</code>.</p>
<p>For example, to make a swift remote of name myremote using auto
config you would do:</p>
<pre><code>rclone config create myremote swift env_auth true
rclone config create myremote swift env_auth=true</code></pre>
<p>So for example if you wanted to configure a Google Drive remote but
using remote authorization you would do this:</p>
<pre><code>rclone config create mydrive drive config_is_local=false</code></pre>
<p>Note that if the config process would normally ask a question the
default is taken (unless <code>--non-interactive</code> is used). Each
time that happens rclone will print or DEBUG a message saying how to
affect the value taken.</p>
<p>If any of the parameters passed is a password field, then rclone will
automatically obscure them if they aren’t already obscured before
putting them in the config file.</p>
<p><strong>NB</strong> If the password parameter is 22 characters or
longer and consists only of base64 characters then rclone can get
confused about whether the password is already obscured or not and put
unobscured passwords into the config file. If you want to be 100%
certain that the passwords get obscured then use the
<code>--obscure</code> flag, or if you are 100% certain you are already
passing obscured passwords then use <code>--no-obscure</code>. You can
also set obscured passwords using the
<code>rclone config password</code> command.</p>
<p>The flag <code>--non-interactive</code> is for use by applications
that wish to configure rclone themselves, rather than using rclone’s
text based configuration questions. If this flag is set, and rclone
needs to ask the user a question, a JSON blob will be returned with the
question in it.</p>
<p>This will look something like (some irrelevant detail removed):</p>
<pre><code>{
"State": "*oauth-islocal,teamdrive,,",
"Option": {
"Name": "config_is_local",
"Help": "Use auto config?\n * Say Y if not sure\n * Say N if you are working on a remote or headless machine\n",
"Default": true,
"Examples": [
{
"Value": "true",
"Help": "Yes"
},
{
"Value": "false",
"Help": "No"
}
],
"Required": false,
"IsPassword": false,
"Type": "bool",
"Exclusive": true,
},
"Error": "",
}</code></pre>
<p>The format of <code>Option</code> is the same as returned by
<code>rclone config providers</code>. The question should be asked to
the user and returned to rclone as the <code>--result</code> option
along with the <code>--state</code> parameter.</p>
<p>The keys of <code>Option</code> are used as follows:</p>
<ul>
<li><code>Name</code> - name of variable - show to user</li>
<li><code>Help</code> - help text. Hard wrapped at 80 chars. Any URLs
should be clicky.</li>
<li><code>Default</code> - default value - return this if the user just
wants the default.</li>
<li><code>Examples</code> - the user should be able to choose one of
these</li>
<li><code>Required</code> - the value should be non-empty</li>
<li><code>IsPassword</code> - the value is a password and should be
edited as such</li>
<li><code>Type</code> - type of value, eg <code>bool</code>,
<code>string</code>, <code>int</code> and others</li>
<li><code>Exclusive</code> - if set no free-form entry allowed only the
<code>Examples</code></li>
<li>Irrelevant keys <code>Provider</code>, <code>ShortOpt</code>,
<code>Hide</code>, <code>NoPrefix</code>, <code>Advanced</code></li>
</ul>
<p>If <code>Error</code> is set then it should be shown to the user at
the same time as the question.</p>
<pre><code>rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"</code></pre>
<p>Note that when using <code>--continue</code> all passwords should be
passed in the clear (not obscured). Any default config values should be
passed in with each invocation of <code>--continue</code>.</p>
<p>At the end of the non interactive process, rclone will return a
result with <code>State</code> as empty string.</p>
<p>If <code>--all</code> 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.</p>
<p>Note that <code>bin/config.py</code> in the rclone source implements
this protocol as a readable demonstration.</p>
<pre><code>rclone config create name type [key value]* [flags]</code></pre>
<h2 id="options-29">Options</h2>
<pre><code> --all Ask the full set of config questions
--continue Continue the configuration process with an answer
-h, --help help for create
--no-obscure Force any passwords not to be obscured
--non-interactive Don't interact with user and return questions
--obscure Force any passwords to be obscured
--result string Result - use with --continue
--state string State - use with --continue</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-29">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-delete">rclone config delete</h1>
<p>Delete an existing remote.</p>
<pre><code>rclone config delete name [flags]</code></pre>
<h2 id="options-30">Options</h2>
<pre><code> -h, --help help for delete</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-30">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-disconnect">rclone config disconnect</h1>
<p>Disconnects user from remote</p>
<h2 id="synopsis-29">Synopsis</h2>
<p>This disconnects the remote: passed in to the cloud storage
system.</p>
<p>This normally means revoking the oauth token.</p>
<p>To reconnect use “rclone config reconnect”.</p>
<pre><code>rclone config disconnect remote: [flags]</code></pre>
<h2 id="options-31">Options</h2>
<pre><code> -h, --help help for disconnect</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-31">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-dump">rclone config dump</h1>
<p>Dump the config file as JSON.</p>
<pre><code>rclone config dump [flags]</code></pre>
<h2 id="options-32">Options</h2>
<pre><code> -h, --help help for dump</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-32">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-edit">rclone config edit</h1>
<p>Enter an interactive configuration session.</p>
<h1 id="synopsis-30">Synopsis</h1>
<p>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.</p>
<pre><code>rclone config edit [flags]</code></pre>
<h1 id="options-33">Options</h1>
<pre><code> -h, --help help for edit</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h1 id="see-also-33">SEE ALSO</h1>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-file">rclone config file</h1>
<p>Show path of configuration file in use.</p>
<pre><code>rclone config file [flags]</code></pre>
<h2 id="options-34">Options</h2>
<pre><code> -h, --help help for file</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-34">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-password">rclone config password</h1>
<p>Update password in an existing remote.</p>
<h2 id="synopsis-31">Synopsis</h2>
<p>Update an existing remote’s password. The password should be passed
in pairs of <code>key</code> <code>password</code> or as
<code>key=password</code>. The <code>password</code> should be passed in
in clear (unobscured).</p>
<p>For example, to set password of a remote of name myremote you would
do:</p>
<pre><code>rclone config password myremote fieldname mypassword
rclone config password myremote fieldname=mypassword</code></pre>
<p>This command is obsolete now that “config update” and “config create”
both support obscuring passwords directly.</p>
<pre><code>rclone config password name [key value]+ [flags]</code></pre>
<h2 id="options-35">Options</h2>
<pre><code> -h, --help help for password</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-35">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-paths">rclone config paths</h1>
<p>Show paths used for configuration, cache, temp etc.</p>
<pre><code>rclone config paths [flags]</code></pre>
<h2 id="options-36">Options</h2>
<pre><code> -h, --help help for paths</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-36">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-providers">rclone config providers</h1>
<p>List in JSON format all the providers and options.</p>
<pre><code>rclone config providers [flags]</code></pre>
<h2 id="options-37">Options</h2>
<pre><code> -h, --help help for providers</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-37">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-reconnect">rclone config reconnect</h1>
<p>Re-authenticates user with remote.</p>
<h2 id="synopsis-32">Synopsis</h2>
<p>This reconnects remote: passed in to the cloud storage system.</p>
<p>To disconnect the remote use “rclone config disconnect”.</p>
<p>This normally means going through the interactive oauth flow
again.</p>
<pre><code>rclone config reconnect remote: [flags]</code></pre>
<h2 id="options-38">Options</h2>
<pre><code> -h, --help help for reconnect</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-38">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-show">rclone config show</h1>
<p>Print (decrypted) config file, or the config for a single remote.</p>
<pre><code>rclone config show [<remote>] [flags]</code></pre>
<h2 id="options-39">Options</h2>
<pre><code> -h, --help help for show</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-39">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-touch">rclone config touch</h1>
<p>Ensure configuration file exists.</p>
<pre><code>rclone config touch [flags]</code></pre>
<h2 id="options-40">Options</h2>
<pre><code> -h, --help help for touch</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-40">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-update">rclone config update</h1>
<p>Update options in an existing remote.</p>
<h2 id="synopsis-33">Synopsis</h2>
<p>Update an existing remote’s options. The options should be passed in
pairs of <code>key</code> <code>value</code> or as
<code>key=value</code>.</p>
<p>For example, to update the env_auth field of a remote of name
myremote you would do:</p>
<pre><code>rclone config update myremote env_auth true
rclone config update myremote env_auth=true</code></pre>
<p>If the remote uses OAuth the token will be updated, if you don’t
require this add an extra parameter thus:</p>
<pre><code>rclone config update myremote env_auth=true config_refresh_token=false</code></pre>
<p>Note that if the config process would normally ask a question the
default is taken (unless <code>--non-interactive</code> is used). Each
time that happens rclone will print or DEBUG a message saying how to
affect the value taken.</p>
<p>If any of the parameters passed is a password field, then rclone will
automatically obscure them if they aren’t already obscured before
putting them in the config file.</p>
<p><strong>NB</strong> If the password parameter is 22 characters or
longer and consists only of base64 characters then rclone can get
confused about whether the password is already obscured or not and put
unobscured passwords into the config file. If you want to be 100%
certain that the passwords get obscured then use the
<code>--obscure</code> flag, or if you are 100% certain you are already
passing obscured passwords then use <code>--no-obscure</code>. You can
also set obscured passwords using the
<code>rclone config password</code> command.</p>
<p>The flag <code>--non-interactive</code> is for use by applications
that wish to configure rclone themselves, rather than using rclone’s
text based configuration questions. If this flag is set, and rclone
needs to ask the user a question, a JSON blob will be returned with the
question in it.</p>
<p>This will look something like (some irrelevant detail removed):</p>
<pre><code>{
"State": "*oauth-islocal,teamdrive,,",
"Option": {
"Name": "config_is_local",
"Help": "Use auto config?\n * Say Y if not sure\n * Say N if you are working on a remote or headless machine\n",
"Default": true,
"Examples": [
{
"Value": "true",
"Help": "Yes"
},
{
"Value": "false",
"Help": "No"
}
],
"Required": false,
"IsPassword": false,
"Type": "bool",
"Exclusive": true,
},
"Error": "",
}</code></pre>
<p>The format of <code>Option</code> is the same as returned by
<code>rclone config providers</code>. The question should be asked to
the user and returned to rclone as the <code>--result</code> option
along with the <code>--state</code> parameter.</p>
<p>The keys of <code>Option</code> are used as follows:</p>
<ul>
<li><code>Name</code> - name of variable - show to user</li>
<li><code>Help</code> - help text. Hard wrapped at 80 chars. Any URLs
should be clicky.</li>
<li><code>Default</code> - default value - return this if the user just
wants the default.</li>
<li><code>Examples</code> - the user should be able to choose one of
these</li>
<li><code>Required</code> - the value should be non-empty</li>
<li><code>IsPassword</code> - the value is a password and should be
edited as such</li>
<li><code>Type</code> - type of value, eg <code>bool</code>,
<code>string</code>, <code>int</code> and others</li>
<li><code>Exclusive</code> - if set no free-form entry allowed only the
<code>Examples</code></li>
<li>Irrelevant keys <code>Provider</code>, <code>ShortOpt</code>,
<code>Hide</code>, <code>NoPrefix</code>, <code>Advanced</code></li>
</ul>
<p>If <code>Error</code> is set then it should be shown to the user at
the same time as the question.</p>
<pre><code>rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"</code></pre>
<p>Note that when using <code>--continue</code> all passwords should be
passed in the clear (not obscured). Any default config values should be
passed in with each invocation of <code>--continue</code>.</p>
<p>At the end of the non interactive process, rclone will return a
result with <code>State</code> as empty string.</p>
<p>If <code>--all</code> 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.</p>
<p>Note that <code>bin/config.py</code> in the rclone source implements
this protocol as a readable demonstration.</p>
<pre><code>rclone config update name [key value]+ [flags]</code></pre>
<h2 id="options-41">Options</h2>
<pre><code> --all Ask the full set of config questions
--continue Continue the configuration process with an answer
-h, --help help for update
--no-obscure Force any passwords not to be obscured
--non-interactive Don't interact with user and return questions
--obscure Force any passwords to be obscured
--result string Result - use with --continue
--state string State - use with --continue</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-41">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-config-userinfo">rclone config userinfo</h1>
<p>Prints info about logged in user of remote.</p>
<h2 id="synopsis-34">Synopsis</h2>
<p>This prints the details of the person logged in to the cloud storage
system.</p>
<pre><code>rclone config userinfo remote: [flags]</code></pre>
<h2 id="options-42">Options</h2>
<pre><code> -h, --help help for userinfo
--json Format output as JSON</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-42">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_config/">rclone
config</a> - Enter an interactive configuration session.</li>
</ul>
<h1 id="rclone-copyto">rclone copyto</h1>
<p>Copy files from source to dest, skipping identical files.</p>
<h2 id="synopsis-35">Synopsis</h2>
<p>If source:path is a file or directory then it copies it to a file or
directory named dest:path.</p>
<p>This can be used to upload single files to other than their current
name. If the source is a directory then it acts exactly like the <a
href="https://rclone.org/commands/rclone_copy/">copy</a> command.</p>
<p>So</p>
<pre><code>rclone copyto src dst</code></pre>
<p>where src and dst are rclone paths, either remote:path or
/path/to/local or C:.</p>
<p>This will:</p>
<pre><code>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</code></pre>
<p>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.</p>
<p><strong>Note</strong>: Use the
<code>-P</code>/<code>--progress</code> flag to view real-time transfer
statistics</p>
<pre><code>rclone copyto source:path dest:path [flags]</code></pre>
<h2 id="options-43">Options</h2>
<pre><code> -h, --help help for copyto</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-43">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-copyurl">rclone copyurl</h1>
<p>Copy url content to dest.</p>
<h2 id="synopsis-36">Synopsis</h2>
<p>Download a URL’s content and copy it to the destination without
saving it in temporary storage.</p>
<p>Setting <code>--auto-filename</code> will attempt to automatically
determine the filename from the URL (after any redirections) and used in
the destination path. With <code>--auto-filename-header</code> in
addition, if a specific filename is set in HTTP headers, it will be used
instead of the name from the URL. With <code>--print-filename</code> in
addition, the resulting file name will be printed.</p>
<p>Setting <code>--no-clobber</code> will prevent overwriting file on
the destination if there is one with the same name.</p>
<p>Setting <code>--stdout</code> or making the output file name
<code>-</code> will cause the output to be written to standard
output.</p>
<pre><code>rclone copyurl https://example.com dest:path [flags]</code></pre>
<h2 id="options-44">Options</h2>
<pre><code> -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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-44">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-cryptcheck">rclone cryptcheck</h1>
<p>Cryptcheck checks the integrity of a crypted remote.</p>
<h2 id="synopsis-37">Synopsis</h2>
<p>rclone cryptcheck checks a remote against a <a
href="https://rclone.org/crypt/">crypted</a> remote. This is the
equivalent of running rclone <a
href="https://rclone.org/commands/rclone_check/">check</a>, but able to
check the checksums of the crypted remote.</p>
<p>For it to work the underlying remote of the cryptedremote must
support some kind of checksum.</p>
<p>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.</p>
<p>Use it like this</p>
<pre><code>rclone cryptcheck /path/to/files encryptedremote:path</code></pre>
<p>You can use it like this also, but that will involve downloading all
the files in remote:path.</p>
<pre><code>rclone cryptcheck remote:path encryptedremote:path</code></pre>
<p>After it has run it will log the status of the encryptedremote:.</p>
<p>If you supply the <code>--one-way</code> 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.</p>
<p>The <code>--differ</code>, <code>--missing-on-dst</code>,
<code>--missing-on-src</code>, <code>--match</code> and
<code>--error</code> flags write paths, one per line, to the file name
(or stdout if it is <code>-</code>) supplied. What they write is
described in the help below. For example <code>--differ</code> will
write all paths which are present on both the source and destination but
different.</p>
<p>The <code>--combined</code> 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.</p>
<ul>
<li><code>= path</code> means path was found in source and destination
and was identical</li>
<li><code>- path</code> means path was missing on the source, so only in
the destination</li>
<li><code>+ path</code> means path was missing on the destination, so
only in the source</li>
<li><code>* path</code> means path was present in source and destination
but different.</li>
<li><code>! path</code> means there was an error reading or hashing the
source or dest.</li>
</ul>
<pre><code>rclone cryptcheck remote:path cryptedremote:path [flags]</code></pre>
<h2 id="options-45">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-45">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-cryptdecode">rclone cryptdecode</h1>
<p>Cryptdecode returns unencrypted file names.</p>
<h2 id="synopsis-38">Synopsis</h2>
<p>rclone cryptdecode returns unencrypted file names when provided with
a list of encrypted file names. List limit is 10 items.</p>
<p>If you supply the <code>--reverse</code> flag, it will return
encrypted file names.</p>
<p>use it like this</p>
<pre><code>rclone cryptdecode encryptedremote: encryptedfilename1 encryptedfilename2
rclone cryptdecode --reverse encryptedremote: filename1 filename2</code></pre>
<p>Another way to accomplish this is by using the
<code>rclone backend encode</code> (or <code>decode</code>) command. See
the documentation on the <a href="https://rclone.org/crypt/">crypt</a>
overlay for more info.</p>
<pre><code>rclone cryptdecode encryptedremote: encryptedfilename [flags]</code></pre>
<h2 id="options-46">Options</h2>
<pre><code> -h, --help help for cryptdecode
--reverse Reverse cryptdecode, encrypts filenames</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-46">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-deletefile">rclone deletefile</h1>
<p>Remove a single file from remote.</p>
<h2 id="synopsis-39">Synopsis</h2>
<p>Remove a single file from remote. Unlike <code>delete</code> it
cannot be used to remove a directory and it doesn’t obey include/exclude
filters - if the specified file exists, it will always be removed.</p>
<pre><code>rclone deletefile remote:path [flags]</code></pre>
<h2 id="options-47">Options</h2>
<pre><code> -h, --help help for deletefile</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-47">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-genautocomplete">rclone genautocomplete</h1>
<p>Output completion script for a given shell.</p>
<h2 id="synopsis-40">Synopsis</h2>
<p>Generates a shell completion script for rclone. Run with
<code>--help</code> to list the supported shells.</p>
<h2 id="options-48">Options</h2>
<pre><code> -h, --help help for genautocomplete</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-48">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
<li><a
href="https://rclone.org/commands/rclone_genautocomplete_bash/">rclone
genautocomplete bash</a> - Output bash completion script for
rclone.</li>
<li><a
href="https://rclone.org/commands/rclone_genautocomplete_fish/">rclone
genautocomplete fish</a> - Output fish completion script for
rclone.</li>
<li><a
href="https://rclone.org/commands/rclone_genautocomplete_zsh/">rclone
genautocomplete zsh</a> - Output zsh completion script for rclone.</li>
</ul>
<h1 id="rclone-genautocomplete-bash">rclone genautocomplete bash</h1>
<p>Output bash completion script for rclone.</p>
<h2 id="synopsis-41">Synopsis</h2>
<p>Generates a bash shell autocompletion script for rclone.</p>
<p>This writes to /etc/bash_completion.d/rclone by default so will
probably need to be run with sudo or as root, e.g.</p>
<pre><code>sudo rclone genautocomplete bash</code></pre>
<p>Logout and login again to use the autocompletion scripts, or source
them directly</p>
<pre><code>. /etc/bash_completion</code></pre>
<p>If you supply a command line argument the script will be written
there.</p>
<p>If output_file is “-”, then the output will be written to stdout.</p>
<pre><code>rclone genautocomplete bash [output_file] [flags]</code></pre>
<h2 id="options-49">Options</h2>
<pre><code> -h, --help help for bash</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-49">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_genautocomplete/">rclone
genautocomplete</a> - Output completion script for a given shell.</li>
</ul>
<h1 id="rclone-genautocomplete-fish">rclone genautocomplete fish</h1>
<p>Output fish completion script for rclone.</p>
<h2 id="synopsis-42">Synopsis</h2>
<p>Generates a fish autocompletion script for rclone.</p>
<p>This writes to /etc/fish/completions/rclone.fish by default so will
probably need to be run with sudo or as root, e.g.</p>
<pre><code>sudo rclone genautocomplete fish</code></pre>
<p>Logout and login again to use the autocompletion scripts, or source
them directly</p>
<pre><code>. /etc/fish/completions/rclone.fish</code></pre>
<p>If you supply a command line argument the script will be written
there.</p>
<p>If output_file is “-”, then the output will be written to stdout.</p>
<pre><code>rclone genautocomplete fish [output_file] [flags]</code></pre>
<h2 id="options-50">Options</h2>
<pre><code> -h, --help help for fish</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-50">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_genautocomplete/">rclone
genautocomplete</a> - Output completion script for a given shell.</li>
</ul>
<h1 id="rclone-genautocomplete-zsh">rclone genautocomplete zsh</h1>
<p>Output zsh completion script for rclone.</p>
<h2 id="synopsis-43">Synopsis</h2>
<p>Generates a zsh autocompletion script for rclone.</p>
<p>This writes to /usr/share/zsh/vendor-completions/_rclone by default
so will probably need to be run with sudo or as root, e.g.</p>
<pre><code>sudo rclone genautocomplete zsh</code></pre>
<p>Logout and login again to use the autocompletion scripts, or source
them directly</p>
<pre><code>autoload -U compinit && compinit</code></pre>
<p>If you supply a command line argument the script will be written
there.</p>
<p>If output_file is “-”, then the output will be written to stdout.</p>
<pre><code>rclone genautocomplete zsh [output_file] [flags]</code></pre>
<h2 id="options-51">Options</h2>
<pre><code> -h, --help help for zsh</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-51">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_genautocomplete/">rclone
genautocomplete</a> - Output completion script for a given shell.</li>
</ul>
<h1 id="rclone-gendocs">rclone gendocs</h1>
<p>Output markdown docs for rclone to the directory supplied.</p>
<h2 id="synopsis-44">Synopsis</h2>
<p>This produces markdown docs for the rclone commands to the directory
supplied. These are in a format suitable for hugo to render into the
rclone.org website.</p>
<pre><code>rclone gendocs output_directory [flags]</code></pre>
<h2 id="options-52">Options</h2>
<pre><code> -h, --help help for gendocs</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-52">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-hashsum">rclone hashsum</h1>
<p>Produces a hashsum file for all the objects in the path.</p>
<h2 id="synopsis-45">Synopsis</h2>
<p>Produces a hash file for all the objects in the path using the hash
named. The output is in the same format as the standard md5sum/sha1sum
tool.</p>
<p>By default, the hash is requested from the remote. If the hash 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 any hash for any remote.</p>
<p>For the MD5 and SHA1 algorithms there are also dedicated commands, <a
href="https://rclone.org/commands/rclone_md5sum/">md5sum</a> and <a
href="https://rclone.org/commands/rclone_sha1sum/">sha1sum</a>.</p>
<p>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).</p>
<p>Run without a hash to see the list of all supported hashes, e.g.</p>
<pre><code>$ rclone hashsum
Supported hashes are:
* md5
* sha1
* whirlpool
* crc32
* sha256
* dropbox
* hidrive
* mailru
* quickxor</code></pre>
<p>Then</p>
<pre><code>$ rclone hashsum MD5 remote:path</code></pre>
<p>Note that hash names are case insensitive and values are output in
lower case.</p>
<pre><code>rclone hashsum <hash> remote:path [flags]</code></pre>
<h2 id="options-53">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-53">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-link">rclone link</h1>
<p>Generate public link to file/folder.</p>
<h2 id="synopsis-46">Synopsis</h2>
<p>rclone link will create, retrieve or remove a public link to the
given file or folder.</p>
<pre><code>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</code></pre>
<p>If you supply the –expire flag, it will set the expiration time
otherwise it will use the default (100 years). <strong>Note</strong> not
all backends support the –expire flag - if the backend doesn’t support
it then the link returned won’t expire.</p>
<p>Use the –unlink flag to remove existing public links to the file or
folder. <strong>Note</strong> not all backends support “–unlink” flag -
those that don’t will just ignore it.</p>
<p>If successful, the last line of the output will contain the link.
Exact capabilities depend on the remote, but the link will always by
default be created with the least constraints – e.g. no expiry, no
password protection, accessible without account.</p>
<pre><code>rclone link remote:path [flags]</code></pre>
<h2 id="options-54">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-54">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-listremotes">rclone listremotes</h1>
<p>List all the remotes in the config file.</p>
<h2 id="synopsis-47">Synopsis</h2>
<p>rclone listremotes lists all the available remotes from the config
file.</p>
<p>When used with the <code>--long</code> flag it lists the types
too.</p>
<pre><code>rclone listremotes [flags]</code></pre>
<h2 id="options-55">Options</h2>
<pre><code> -h, --help help for listremotes
--long Show the type as well as names</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-55">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-lsf">rclone lsf</h1>
<p>List directories and objects in remote:path formatted for
parsing.</p>
<h2 id="synopsis-48">Synopsis</h2>
<p>List the contents of the source path (directories and objects) to
standard output in a form which is easy to parse by scripts. By default
this will just be the names of the objects and directories, one per
line. The directories will have a / suffix.</p>
<p>Eg</p>
<pre><code>$ rclone lsf swift:bucket
bevajer5jef
canole
diwogej7
ferejej3gux/
fubuwic</code></pre>
<p>Use the <code>--format</code> option to control what gets listed. By
default this is just the path, but you can use these parameters to
control the output:</p>
<pre><code>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"}</code></pre>
<p>So if you wanted the path, size and modification time, you would use
<code>--format "pst"</code>, or maybe <code>--format "tsp"</code> to put
the path last.</p>
<p>Eg</p>
<pre><code>$ 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</code></pre>
<p>If you specify “h” in the format you will get the MD5 hash by
default, use the <code>--hash</code> 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.</p>
<p>For example, to emulate the md5sum command you can use</p>
<pre><code>rclone lsf -R --hash MD5 --format hp --separator " " --files-only .</code></pre>
<p>Eg</p>
<pre><code>$ rclone lsf -R --hash MD5 --format hp --separator " " --files-only swift:bucket
7908e352297f0f530b84a756f188baa3 bevajer5jef
cd65ac234e6fea5925974a51cdd865cc canole
03b5341b4f234b9d984d03ad076bae91 diwogej7
8fd37c3810dd660778137ac3a66cc06d fubuwic
99713e14a4c4ff553acaf1930fad985b gixacuh7ku</code></pre>
<p>(Though “rclone md5sum .” is an easier way of typing this.)</p>
<p>By default the separator is “;” this can be changed with the
<code>--separator</code> flag. Note that separators aren’t escaped in
the path so putting it last is a good strategy.</p>
<p>Eg</p>
<pre><code>$ 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</code></pre>
<p>You can output in CSV standard format. This will escape things in ”
if they contain ,</p>
<p>Eg</p>
<pre><code>$ 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</code></pre>
<p>Note that the <code>--absolute</code> parameter is useful for making
lists of files to pass to an rclone copy with the
<code>--files-from-raw</code> flag.</p>
<p>For example, to find all the files modified within one day and copy
those only (without traversing the whole directory structure):</p>
<pre><code>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</code></pre>
<p>Any of the filtering options can be applied to this command.</p>
<p>There are several related list commands</p>
<ul>
<li><code>ls</code> to list size and path of objects only</li>
<li><code>lsl</code> to list modification time, size and path of objects
only</li>
<li><code>lsd</code> to list directories only</li>
<li><code>lsf</code> to list objects and directories in easy to parse
format</li>
<li><code>lsjson</code> to list objects and directories in JSON
format</li>
</ul>
<p><code>ls</code>,<code>lsl</code>,<code>lsd</code> are designed to be
human-readable. <code>lsf</code> is designed to be human and
machine-readable. <code>lsjson</code> is designed to be
machine-readable.</p>
<p>Note that <code>ls</code> and <code>lsl</code> recurse by default -
use <code>--max-depth 1</code> to stop the recursion.</p>
<p>The other list commands
<code>lsd</code>,<code>lsf</code>,<code>lsjson</code> do not recurse by
default - use <code>-R</code> to make them recurse.</p>
<p>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).</p>
<pre><code>rclone lsf remote:path [flags]</code></pre>
<h2 id="options-56">Options</h2>
<pre><code> --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 ";")</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-56">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-lsjson">rclone lsjson</h1>
<p>List directories and objects in the path in JSON format.</p>
<h2 id="synopsis-49">Synopsis</h2>
<p>List directories and objects in the path in JSON format.</p>
<p>The output is an array of Items, where each Item looks like this</p>
<pre><code>{
"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",
}</code></pre>
<p>If <code>--hash</code> is not specified the Hashes property won’t be
emitted. The types of hash can be specified with the
<code>--hash-type</code> parameter (which may be repeated). If
<code>--hash-type</code> is set then it implies <code>--hash</code>.</p>
<p>If <code>--no-modtime</code> 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).</p>
<p>If <code>--no-mimetype</code> 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).</p>
<p>If <code>--encrypted</code> is not specified the Encrypted won’t be
emitted.</p>
<p>If <code>--dirs-only</code> is not specified files in addition to
directories are returned</p>
<p>If <code>--files-only</code> is not specified directories in addition
to the files will be returned.</p>
<p>If <code>--metadata</code> is set then an additional Metadata key
will be returned. This will have metadata in rclone standard format as a
JSON object.</p>
<p>if <code>--stat</code> is set then 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.</p>
<p>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
<code>--recursive</code> the Path will always be the same as Name.</p>
<p>If the directory is a bucket in a bucket-based backend, then
“IsBucket” will be set to true. This key won’t be present unless it is
“true”.</p>
<p>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”).</p>
<p>The whole output can be processed as a JSON blob, or alternatively it
can be processed line by line as each item is written one to a line.</p>
<p>Any of the filtering options can be applied to this command.</p>
<p>There are several related list commands</p>
<ul>
<li><code>ls</code> to list size and path of objects only</li>
<li><code>lsl</code> to list modification time, size and path of objects
only</li>
<li><code>lsd</code> to list directories only</li>
<li><code>lsf</code> to list objects and directories in easy to parse
format</li>
<li><code>lsjson</code> to list objects and directories in JSON
format</li>
</ul>
<p><code>ls</code>,<code>lsl</code>,<code>lsd</code> are designed to be
human-readable. <code>lsf</code> is designed to be human and
machine-readable. <code>lsjson</code> is designed to be
machine-readable.</p>
<p>Note that <code>ls</code> and <code>lsl</code> recurse by default -
use <code>--max-depth 1</code> to stop the recursion.</p>
<p>The other list commands
<code>lsd</code>,<code>lsf</code>,<code>lsjson</code> do not recurse by
default - use <code>-R</code> to make them recurse.</p>
<p>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).</p>
<pre><code>rclone lsjson remote:path [flags]</code></pre>
<h2 id="options-57">Options</h2>
<pre><code> --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
--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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-57">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-mount">rclone mount</h1>
<p>Mount the remote as file system on a mountpoint.</p>
<h2 id="synopsis-50">Synopsis</h2>
<p>rclone mount allows Linux, FreeBSD, macOS and Windows to mount any of
Rclone’s cloud storage systems as a file system with FUSE.</p>
<p>First set up your remote using <code>rclone config</code>. Check it
works with <code>rclone ls</code> etc.</p>
<p>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 <code>--daemon</code> flag to force background mode. On Windows
you can run mount in foreground only, the flag is ignored.</p>
<p>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).</p>
<p>On Linux/macOS/FreeBSD start the mount like this, where
<code>/path/to/local/mount</code> is an <strong>empty</strong>
<strong>existing</strong> directory:</p>
<pre><code>rclone mount remote:path/to/files /path/to/local/mount</code></pre>
<p>On Windows you can start a mount in different ways. See <a
href="#mounting-modes-on-windows">below</a> 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.</p>
<p>The following examples will mount to an automatically assigned drive,
to specific drive letter <code>X:</code>, to path
<code>C:\path\parent\mount</code> (where parent directory or drive must
exist, and mount must <strong>not</strong> exist, and is not supported
when <a href="#mounting-modes-on-windows">mounting as a network
drive</a>), and the last example will mount as network share
<code>\\cloud\remote</code> and map it to an automatically assigned
drive:</p>
<pre><code>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</code></pre>
<p>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.</p>
<p>When running in background mode the user will have to stop the mount
manually:</p>
<pre><code># Linux
fusermount -u /path/to/local/mount
# OS X
umount /path/to/local/mount</code></pre>
<p>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.</p>
<p>The size of the mounted file system will be set according to
information retrieved from the remote, the same as returned by the <a
href="https://rclone.org/commands/rclone_about/">rclone about</a>
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 <a href="https://rclone.org/overview/#optional-features">support</a>
the about feature at all, then 1 PiB is set as both the total and the
free size.</p>
<h2 id="installing-on-windows">Installing on Windows</h2>
<p>To run rclone mount on Windows, you will need to download and install
<a href="http://www.secfs.net/winfsp/">WinFsp</a>.</p>
<p><a href="https://github.com/winfsp/winfsp">WinFsp</a> 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 <a
href="https://github.com/winfsp/cgofuse">cgofuse</a>. Both of these
packages are by Bill Zissimopoulos who was very helpful during the
implementation of rclone mount for Windows.</p>
<h3 id="mounting-modes-on-windows">Mounting modes on windows</h3>
<p>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.</p>
<p>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.</p>
<p>When mounting as a fixed disk drive you can either mount to an unused
drive letter, or to a path representing a <strong>nonexistent</strong>
subdirectory of an <strong>existing</strong> parent directory or drive.
Using the special value <code>*</code> will tell rclone to automatically
assign the next available drive letter, starting with Z: and moving
backward. Examples:</p>
<pre><code>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:</code></pre>
<p>Option <code>--volname</code> can be used to set a custom volume name
for the mounted file system. The default is to use the remote name and
path.</p>
<p>To mount as network drive, you can add option
<code>--network-mode</code> to your mount command. Mounting to a
directory path is not supported in this mode, it is a limitation Windows
imposes on junctions, so the remote must always be mounted to a drive
letter.</p>
<pre><code>rclone mount remote:path/to/files X: --network-mode</code></pre>
<p>A volume name specified with <code>--volname</code> will be used to
create the network share path. A complete UNC path, such as
<code>\\cloud\remote</code>, optionally with path
<code>\\cloud\remote\madeup\path</code>, will be used as is. Any other
string will be used as the share part, after a default prefix
<code>\\server\</code>. If no volume name is specified then
<code>\\server\share</code> will be used. You must make sure the volume
name is unique when you are mounting more than one drive, or else the
mount command will fail. The share name will treated as the volume label
for the mapped drive, shown in Windows Explorer etc, while the complete
<code>\\server\share</code> will be reported as the remote UNC path by
<code>net use</code> etc, just like a normal network drive mapping.</p>
<p>If you specify a full network share UNC path with
<code>--volname</code>, this will implicitly set the
<code>--network-mode</code> option, so the following two examples have
same result:</p>
<pre><code>rclone mount remote:path/to/files X: --network-mode
rclone mount remote:path/to/files X: --volname \\server\share</code></pre>
<p>You may also specify the network share UNC path as the mountpoint
itself. Then rclone will automatically assign a drive letter, same as
with <code>*</code> and use that as mountpoint, and instead use the UNC
path specified as the volume name, as if it were specified with the
<code>--volname</code> option. This will also implicitly set the
<code>--network-mode</code> option. This means the following two
examples have same result:</p>
<pre><code>rclone mount remote:path/to/files \\cloud\remote
rclone mount remote:path/to/files * --volname \\cloud\remote</code></pre>
<p>There is yet another way to enable network mode, and to set the share
path, and that is to pass the “native” libfuse/WinFsp option directly:
<code>--fuse-flag --VolumePrefix=\server\share</code>. Note that the
path must be with just a single backslash prefix in this case.</p>
<p><em>Note:</em> In previous versions of rclone this was the only
supported method.</p>
<p><a href="https://en.wikipedia.org/wiki/Drive_mapping">Read more about
drive mapping</a></p>
<p>See also <a href="#limitations">Limitations</a> section below.</p>
<h3 id="windows-filesystem-permissions">Windows filesystem
permissions</h3>
<p>The FUSE emulation layer on Windows must convert between the
POSIX-based permission model used in FUSE, and the permission model used
in Windows, based on access-control lists (ACL).</p>
<p>The mounted filesystem will normally get three entries in its
access-control list (ACL), representing permissions for the POSIX
permission scopes: Owner, group and others. By default, the owner and
group will be taken from the current user, and the built-in group
“Everyone” will be used to represent others. The user/group can be
customized with FUSE options “UserName” and “GroupName”,
e.g. <code>-o UserName=user123 -o GroupName="Authenticated Users"</code>.
The permissions on each entry will be set according to <a
href="#options">options</a> <code>--dir-perms</code> and
<code>--file-perms</code>, which takes a value in traditional <a
href="https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation">numeric
notation</a>.</p>
<p>The default permissions corresponds to
<code>--file-perms 0666 --dir-perms 0777</code>, i.e. read and write
permissions to everyone. This means you will not be able to start any
programs from the mount. To be able to do that you must add execute
permissions, e.g. <code>--file-perms 0777 --dir-perms 0777</code> to add
it to everyone. If the program needs to write files, chances are you
will have to enable <a href="#vfs-file-caching">VFS File Caching</a> as
well (see also <a href="#limitations">limitations</a>).</p>
<p>Note that the mapping of permissions is not always trivial, and the
result you see in Windows Explorer may not be exactly like you expected.
For example, when setting a value that includes write access, this will
be mapped to individual permissions “write attributes”, “write data” and
“append data”, but not “write extended attributes”. Windows will then
show this as basic permission “Special” instead of “Write”, because
“Write” includes the “write extended attributes” permission.</p>
<p>If you set POSIX permissions for only allowing access to the owner,
using <code>--file-perms 0600 --dir-perms 0700</code>, the user group
and the built-in “Everyone” group will still be given some special
permissions, such as “read attributes” and “read permissions”, in
Windows. This is done for compatibility reasons, e.g. to allow users
without additional permissions to be able to read basic metadata about
files like in UNIX. One case that may arise is that other programs
(incorrectly) interprets this as the file being accessible by everyone.
For example an SSH client may warn about “unprotected private key
file”.</p>
<p>WinFsp 2021 (version 1.9) introduces a new FUSE option
“FileSecurity”, that allows the complete specification of file security
descriptors using <a
href="https://docs.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-string-format">SDDL</a>.
With this you can work around issues such as the mentioned “unprotected
private key file” by specifying
<code>-o FileSecurity="D:P(A;;FA;;;OW)"</code>, for file all access (FA)
to the owner (OW).</p>
<h3 id="windows-caveats">Windows caveats</h3>
<p>Drives created as Administrator are not visible to other accounts,
not even an account that was elevated to Administrator with the User
Account Control (UAC) feature. A result of this is that if you mount to
a drive letter from a Command Prompt run as Administrator, and then try
to access the same drive from Windows Explorer (which does not run as
Administrator), you will not be able to see the mounted drive.</p>
<p>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.</p>
<p>To make mapped drives available to the user account that created them
regardless if elevated or not, there is a special Windows setting called
<a
href="https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/mapped-drives-not-available-from-elevated-command#detail-to-configure-the-enablelinkedconnections-registry-entry">linked
connections</a> that can be enabled.</p>
<p>It is 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 <a
href="https://docs.microsoft.com/en-us/sysinternals/downloads/psexec">PsExec</a>,
from Microsoft’s Sysinternals suite, which has option <code>-s</code> 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 <a
href="https://github.com/winfsp/winfsp/wiki/WinFsp-Service-Architecture">WinFsp.Launcher
infrastructure</a>). 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 <a
href="https://rclone.org/docs/#config-config-file"><code>--config</code></a>
option. Read more in the <a href="https://rclone.org/install/">install
documentation</a>.</p>
<p>Note that mapping to a directory path, instead of a drive letter,
does not suffer from the same limitations.</p>
<h2 id="limitations">Limitations</h2>
<p>Without the use of <code>--vfs-cache-mode</code> 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
<code>--vfs-cache-mode writes</code> or
<code>--vfs-cache-mode full</code>. See the <a
href="#vfs-file-caching">VFS File Caching</a> section for more info.</p>
<p>The bucket-based remotes (e.g. Swift, S3, Google Compute Storage, B2)
do not support the concept of empty directories, so empty directories
will have a tendency to disappear once they fall out of the directory
cache.</p>
<p>When <code>rclone mount</code> is invoked on Unix with
<code>--daemon</code> flag, the main rclone program will wait for the
background mount to become ready or until the timeout specified by the
<code>--daemon-wait</code> flag. On Linux it can check mount status
using ProcFS so the flag in fact sets <strong>maximum</strong> 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.</p>
<p>Only supported on Linux, FreeBSD, OS X and Windows at the moment.</p>
<h2 id="rclone-mount-vs-rclone-synccopy">rclone mount vs rclone
sync/copy</h2>
<p>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 <a href="#vfs-file-caching">VFS File Caching</a> for solutions to
make mount more reliable.</p>
<h2 id="attribute-caching">Attribute caching</h2>
<p>You can use the flag <code>--attr-timeout</code> to set the time the
kernel caches the attributes (size, modification time, etc.) for
directory entries.</p>
<p>The default is <code>1s</code> which caches files just long enough to
avoid too many callbacks to rclone from the kernel.</p>
<p>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 <a
href="https://github.com/rclone/rclone/issues/2157">rclone using too
much memory</a>, <a
href="https://forum.rclone.org/t/rclone-1-39-vs-1-40-mount-issue/5112">rclone
not serving files to samba</a> and <a
href="https://github.com/rclone/rclone/issues/2095#issuecomment-371141147">excessive
time listing directories</a>.</p>
<p>The kernel can cache the info about a file for the time given by
<code>--attr-timeout</code>. 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
<code>--attr-timeout 1s</code> this is very unlikely but not impossible.
The higher you set <code>--attr-timeout</code> the more likely it is.
The default setting of “1s” is the lowest setting which mitigates the
problems above.</p>
<p>If you set it higher (<code>10s</code> or <code>1m</code> 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.</p>
<p>If files don’t change on the remote outside of the control of rclone
then there is no chance of corruption.</p>
<p>This is the same as setting the attr_timeout option in
mount.fuse.</p>
<h2 id="filters">Filters</h2>
<p>Note that all the rclone filters can be used to select a subset of
the files to be visible in the mount.</p>
<h2 id="systemd">systemd</h2>
<p>When running rclone mount 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
mount service specified as a requirement will see all files and folders
immediately in this mode.</p>
<p>Note that systemd runs mount units without any environment variables
including <code>PATH</code> or <code>HOME</code>. This means that tilde
(<code>~</code>) expansion will not work and you should provide
<code>--config</code> and <code>--cache-dir</code> explicitly as
absolute paths via rclone arguments. Since mounting requires the
<code>fusermount</code> program, rclone will use the fallback PATH of
<code>/bin:/usr/bin</code> in this scenario. Please ensure that
<code>fusermount</code> is present on this PATH.</p>
<h2 id="rclone-as-unix-mount-helper">Rclone as Unix mount helper</h2>
<p>The core Unix program <code>/bin/mount</code> normally takes the
<code>-t FSTYPE</code> argument then runs the
<code>/sbin/mount.FSTYPE</code> helper program passing it mount options
as <code>-o key=val,...</code> or <code>--opt=...</code>. Automount
(classic or systemd) behaves in a similar way.</p>
<p>rclone by default expects GNU-style flags <code>--key val</code>. To
run it as a mount helper you should symlink rclone binary to
<code>/sbin/mount.rclone</code> and optionally
<code>/usr/bin/rclonefs</code>,
e.g. <code>ln -s /usr/bin/rclone /sbin/mount.rclone</code>. rclone will
detect it and translate command-line arguments appropriately.</p>
<p>Now you can run classic mounts like this:</p>
<pre><code>mount sftp1:subdir /mnt/data -t rclone -o vfs_cache_mode=writes,sftp_key_file=/path/to/pem</code></pre>
<p>or create systemd mount units:</p>
<pre><code># /etc/systemd/system/mnt-data.mount
[Unit]
After=network-online.target
[Mount]
Type=rclone
What=sftp1:subdir
Where=/mnt/data
Options=rw,allow_other,args2env,vfs-cache-mode=writes,config=/etc/rclone.conf,cache-dir=/var/rclone</code></pre>
<p>optionally accompanied by systemd automount unit</p>
<pre><code># /etc/systemd/system/mnt-data.automount
[Unit]
After=network-online.target
Before=remote-fs.target
[Automount]
Where=/mnt/data
TimeoutIdleSec=600
[Install]
WantedBy=multi-user.target</code></pre>
<p>or add in <code>/etc/fstab</code> a line like</p>
<pre><code>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</code></pre>
<p>or use classic Automountd. Remember to provide explicit
<code>config=...,cache-dir=...</code> as a workaround for mount units
being run without <code>HOME</code>.</p>
<p>Rclone in the mount helper mode will split <code>-o</code>
argument(s) by comma, replace <code>_</code> by <code>-</code> and
prepend <code>--</code> 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.</p>
<p>Mount option syntax includes a few extra options treated
specially:</p>
<ul>
<li><code>env.NAME=VALUE</code> will set an environment variable for the
mount process. This helps with Automountd and Systemd.mount which don’t
allow setting custom environment for mount helpers. Typically you will
use <code>env.HTTPS_PROXY=proxy.host:3128</code> or
<code>env.HOME=/root</code></li>
<li><code>command=cmount</code> can be used to run <code>cmount</code>
or any other rclone command rather than the default
<code>mount</code>.</li>
<li><code>args2env</code> will pass mount options to the mount helper
running in background via environment variables instead of command line
arguments. This allows to hide secrets from such commands as
<code>ps</code> or <code>pgrep</code>.</li>
<li><code>vv...</code> will be transformed into appropriate
<code>--verbose=N</code></li>
<li>standard mount options like <code>x-systemd.automount</code>,
<code>_netdev</code>, <code>nosuid</code> and alike are intended only
for Automountd and ignored by rclone.</li>
</ul>
<h2 id="vfs---virtual-file-system">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<pre><code>rclone mount remote:path /path/to/mountpoint [flags]</code></pre>
<h2 id="options-58">Options</h2>
<pre><code> --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)
--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 0777)
--file-perms FileMode File permissions (default 0666)
--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
--max-read-ahead SizeSuffix The number of bytes that can be prefetched for sequential reads (not supported on Windows) (default 128Ki)
--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 int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-58">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-moveto">rclone moveto</h1>
<p>Move file or directory from source to dest.</p>
<h2 id="synopsis-51">Synopsis</h2>
<p>If source:path is a file or directory then it moves it to a file or
directory named dest:path.</p>
<p>This can be used to rename files or upload single files to other than
their existing name. If the source is a directory then it acts exactly
like the <a href="https://rclone.org/commands/rclone_move/">move</a>
command.</p>
<p>So</p>
<pre><code>rclone moveto src dst</code></pre>
<p>where src and dst are rclone paths, either remote:path or
/path/to/local or C:.</p>
<p>This will:</p>
<pre><code>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</code></pre>
<p>This doesn’t transfer files that are identical on src and dst,
testing by size and modification time or MD5SUM. src will be deleted on
successful transfer.</p>
<p><strong>Important</strong>: Since this can cause data loss, test
first with the <code>--dry-run</code> or the
<code>--interactive</code>/<code>-i</code> flag.</p>
<p><strong>Note</strong>: Use the
<code>-P</code>/<code>--progress</code> flag to view real-time transfer
statistics.</p>
<pre><code>rclone moveto source:path dest:path [flags]</code></pre>
<h2 id="options-59">Options</h2>
<pre><code> -h, --help help for moveto</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-59">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-ncdu">rclone ncdu</h1>
<p>Explore a remote with a text based user interface.</p>
<h2 id="synopsis-52">Synopsis</h2>
<p>This displays a text based user interface allowing the navigation of
a remote. It is most useful for answering the question - “What is using
all my disk space?”.</p>
<p>To make the user interface it first scans the entire remote given and
builds an in memory representation. rclone ncdu can be used during this
scanning phase and you will see it building up the directory structure
as it goes along.</p>
<p>You can interact with the user interface using key presses, press ‘?’
to toggle the help on and off. The supported keys are:</p>
<pre><code> ↑,↓ or k,j to Move
→,l to enter
←,h to return
c toggle counts
g toggle graph
a toggle average size in directory
u toggle human-readable format
n,s,C,A sort by name,size,count,average size
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)
? to toggle help on and off
q/ESC/^c to quit</code></pre>
<p>Listed files/directories may be prefixed by a one-character flag,
some of them combined with a description in brackets at end of line.
These flags have the following meaning:</p>
<pre><code>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</code></pre>
<p>This an homage to the <a href="https://dev.yorhel.nl/ncdu">ncdu
tool</a> but for rclone remotes. It is missing lots of features at the
moment but is useful as it stands.</p>
<p>Note that it might take some time to delete big files/directories.
The UI won’t respond in the meantime since the deletion is done
synchronously.</p>
<p>For a non-interactive listing of the remote, see the <a
href="https://rclone.org/commands/rclone_tree/">tree</a> command. To
just get the total size of the remote you can also use the <a
href="https://rclone.org/commands/rclone_size/">size</a> command.</p>
<pre><code>rclone ncdu remote:path [flags]</code></pre>
<h2 id="options-60">Options</h2>
<pre><code> -h, --help help for ncdu</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-60">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-obscure">rclone obscure</h1>
<p>Obscure password for use in the rclone config file.</p>
<h2 id="synopsis-53">Synopsis</h2>
<p>In the rclone config file, human-readable passwords are obscured.
Obscuring them is done by encrypting them and writing them out in
base64. This is <strong>not</strong> a secure way of encrypting these
passwords as rclone can decrypt them - it is to prevent “eyedropping” -
namely someone seeing a password in the rclone config file by
accident.</p>
<p>Many equally important things (like access tokens) are not obscured
in the config file. However it is very hard to shoulder surf a 64
character hex token.</p>
<p>This command can also accept a password through STDIN instead of an
argument by passing a hyphen as an argument. This will use the first
line of STDIN as the password not including the trailing newline.</p>
<pre><code>echo "secretpassword" | rclone obscure -</code></pre>
<p>If there is no data on STDIN to read, rclone obscure will default to
obfuscating the hyphen itself.</p>
<p>If you want to encrypt the config file then please use config file
encryption - see <a
href="https://rclone.org/commands/rclone_config/">rclone config</a> for
more info.</p>
<pre><code>rclone obscure password [flags]</code></pre>
<h2 id="options-61">Options</h2>
<pre><code> -h, --help help for obscure</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-61">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-rc">rclone rc</h1>
<p>Run a command against a running rclone.</p>
<h2 id="synopsis-54">Synopsis</h2>
<p>This runs a command against a running rclone. Use the
<code>--url</code> flag to specify an non default URL to connect on.
This can be either a “:port” which is taken to mean
“http://localhost:port” or a “host:port” which is taken to mean
“http://host:port”</p>
<p>A username and password can be passed in with <code>--user</code> and
<code>--pass</code>.</p>
<p>Note that <code>--rc-addr</code>, <code>--rc-user</code>,
<code>--rc-pass</code> will be read also for <code>--url</code>,
<code>--user</code>, <code>--pass</code>.</p>
<p>Arguments should be passed in as parameter=value.</p>
<p>The result will be returned as a JSON object by default.</p>
<p>The <code>--json</code> parameter can be used to pass in a JSON blob
as an input instead of key=value arguments. This is the only way of
passing in more complicated values.</p>
<p>The <code>-o</code>/<code>--opt</code> option can be used to set a
key “opt” with key, value options in the form <code>-o key=value</code>
or <code>-o key</code>. 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.</p>
<pre><code>-o key=value -o key2</code></pre>
<p>Will place this in the “opt” value</p>
<pre><code>{"key":"value", "key2","")</code></pre>
<p>The <code>-a</code>/<code>--arg</code> 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.</p>
<pre><code>-a value -a value2</code></pre>
<p>Will place this in the “arg” value</p>
<pre><code>["value", "value2"]</code></pre>
<p>Use <code>--loopback</code> to connect to the rclone instance running
<code>rclone rc</code>. This is very useful for testing commands without
having to run an rclone rc server, e.g.:</p>
<pre><code>rclone rc --loopback operations/about fs=/</code></pre>
<p>Use <code>rclone rc</code> to see a list of all possible
commands.</p>
<pre><code>rclone rc commands parameter [flags]</code></pre>
<h2 id="options-62">Options</h2>
<pre><code> -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
--url string URL to connect to rclone remote control (default "http://localhost:5572/")
--user string Username to use to rclone remote control</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-62">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-rcat">rclone rcat</h1>
<p>Copies standard input to file on remote.</p>
<h2 id="synopsis-55">Synopsis</h2>
<p>rclone rcat reads from standard input (stdin) and copies it to a
single remote file.</p>
<pre><code>echo "hello world" | rclone rcat remote:path/to/file
ffmpeg - | rclone rcat remote:path/to/file</code></pre>
<p>If the remote file already exists, it will be overwritten.</p>
<p>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
<code>--streaming-upload-cutoff</code>. 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.</p>
<p>Use the <code>--size</code> flag to preallocate the file in advance
at the remote end and actually stream it, even if remote backend doesn’t
support streaming.</p>
<p><code>--size</code> should be the exact size of the input stream in
bytes. If the size of the stream is different in length to the
<code>--size</code> passed in then the transfer will likely fail.</p>
<p>Note that the upload can also not be retried because the data is not
kept around until the upload succeeds. If you need to transfer a lot of
data, you’re better off caching locally and then
<code>rclone move</code> it to the destination.</p>
<pre><code>rclone rcat remote:path [flags]</code></pre>
<h2 id="options-63">Options</h2>
<pre><code> -h, --help help for rcat
--size int File size hint to preallocate (default -1)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-63">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-rcd">rclone rcd</h1>
<p>Run rclone listening to remote control commands only.</p>
<h2 id="synopsis-56">Synopsis</h2>
<p>This runs rclone so that it only listens to remote control
commands.</p>
<p>This is useful if you are controlling rclone via the rc API.</p>
<p>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.</p>
<p>See the <a href="https://rclone.org/rc/">rc documentation</a> for
more info on the rc flags.</p>
<pre><code>rclone rcd <path to files to serve>* [flags]</code></pre>
<h2 id="options-64">Options</h2>
<pre><code> -h, --help help for rcd</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-64">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-rmdirs">rclone rmdirs</h1>
<p>Remove empty directories under the path.</p>
<h2 id="synopsis-57">Synopsis</h2>
<p>This recursively removes any empty directories (including directories
that only contain empty directories), that it finds under the path. The
root path itself will also be removed if it is empty, unless you supply
the <code>--leave-root</code> flag.</p>
<p>Use command <a
href="https://rclone.org/commands/rclone_rmdir/">rmdir</a> to delete
just the empty directory given by path, not recurse.</p>
<p>This is useful for tidying up remotes that rclone has left a lot of
empty directories in. For example the <a
href="https://rclone.org/commands/rclone_delete/">delete</a> command
will delete files but leave the directory structure (unless used with
option <code>--rmdirs</code>).</p>
<p>To delete a path and any objects in it, use <a
href="https://rclone.org/commands/rclone_purge/">purge</a> command.</p>
<pre><code>rclone rmdirs remote:path [flags]</code></pre>
<h2 id="options-65">Options</h2>
<pre><code> -h, --help help for rmdirs
--leave-root Do not remove root directory if empty</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-65">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-selfupdate">rclone selfupdate</h1>
<p>Update the rclone binary.</p>
<h2 id="synopsis-58">Synopsis</h2>
<p>This command downloads the latest release of rclone and replaces the
currently running binary. The download is verified with a hashsum and
cryptographically signed signature.</p>
<p>If used without flags (or with implied <code>--stable</code> flag),
this command will install the latest stable release. However, some
issues may be fixed (or features added) only in the latest beta release.
In such cases you should run the command with the <code>--beta</code>
flag, i.e. <code>rclone selfupdate --beta</code>. You can check in
advance what version would be installed by adding the
<code>--check</code> flag, then repeat the command without it when you
are satisfied.</p>
<p>Sometimes the rclone team may recommend you a concrete beta or stable
rclone release to troubleshoot your issue or add a bleeding edge
feature. The <code>--version VER</code> flag, if given, will update to
the concrete version instead of the latest one. If you omit micro
version from <code>VER</code> (for example <code>1.53</code>), the
latest matching micro version will be used.</p>
<p>Upon successful update rclone will print a message that contains a
previous version number. You will need it if you later decide to revert
your update for some reason. Then you’ll have to note the previous
version and run the following command:
<code>rclone selfupdate [--beta] OLDVER</code>. If the old version
contains only dots and digits (for example <code>v1.54.0</code>) then
it’s a stable release so you won’t need the <code>--beta</code> flag.
Beta releases have an additional information similar to
<code>v1.54.0-beta.5111.06f1c0c61</code>. (if you are a developer and
use a locally built rclone, the version number will end with
<code>-DEV</code>, you will have to rebuild it as it obviously can’t be
distributed).</p>
<p>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 <code>--package deb</code> or
<code>--package rpm</code> (whichever is correct for your OS) to update
these too. This command with the default <code>--package zip</code> will
update only the rclone executable so the local manual may become
inaccurate after it.</p>
<p>The <code>rclone mount</code> command
(https://rclone.org/commands/rclone_mount/) may or may not support
extended FUSE options depending on the build and OS.
<code>selfupdate</code> will refuse to update if the capability would be
discarded.</p>
<p>Note: Windows forbids deletion of a currently running executable so
this command will rename the old executable to ‘rclone.old.exe’ upon
success.</p>
<p>Please note that this command was not available before rclone version
1.55. If it fails for you with the message
<code>unknown command "selfupdate"</code> then you will need to update
manually following the install instructions located at
https://rclone.org/install/</p>
<pre><code>rclone selfupdate [flags]</code></pre>
<h2 id="options-66">Options</h2>
<pre><code> --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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-66">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-serve">rclone serve</h1>
<p>Serve a remote over a protocol.</p>
<h2 id="synopsis-59">Synopsis</h2>
<p>Serve a remote over a given protocol. Requires the use of a
subcommand to specify the protocol, e.g.</p>
<pre><code>rclone serve http remote:</code></pre>
<p>Each subcommand has its own options which you can see in their
help.</p>
<pre><code>rclone serve <protocol> [opts] <remote> [flags]</code></pre>
<h2 id="options-67">Options</h2>
<pre><code> -h, --help help for serve</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-67">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
<li><a href="https://rclone.org/commands/rclone_serve_dlna/">rclone
serve dlna</a> - Serve remote:path over DLNA</li>
<li><a href="https://rclone.org/commands/rclone_serve_docker/">rclone
serve docker</a> - Serve any remote on docker’s volume plugin API.</li>
<li><a href="https://rclone.org/commands/rclone_serve_ftp/">rclone serve
ftp</a> - Serve remote:path over FTP.</li>
<li><a href="https://rclone.org/commands/rclone_serve_http/">rclone
serve http</a> - Serve the remote over HTTP.</li>
<li><a href="https://rclone.org/commands/rclone_serve_restic/">rclone
serve restic</a> - Serve the remote for restic’s REST API.</li>
<li><a href="https://rclone.org/commands/rclone_serve_sftp/">rclone
serve sftp</a> - Serve the remote over SFTP.</li>
<li><a href="https://rclone.org/commands/rclone_serve_webdav/">rclone
serve webdav</a> - Serve remote:path over WebDAV.</li>
</ul>
<h1 id="rclone-serve-dlna">rclone serve dlna</h1>
<p>Serve remote:path over DLNA</p>
<h2 id="synopsis-60">Synopsis</h2>
<p>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.</p>
<p>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.</p>
<h2 id="server-options">Server options</h2>
<p>Use <code>--addr</code> to specify which IP address and port the
server should listen on, e.g. <code>--addr 1.2.3.4:8000</code> or
<code>--addr :8080</code> to listen to all IPs.</p>
<p>Use <code>--name</code> to choose the friendly server name, which is
by default “rclone (hostname)”.</p>
<p>Use <code>--log-trace</code> in conjunction with <code>-vv</code> to
enable additional debug logging of all UPNP traffic.</p>
<h2 id="vfs---virtual-file-system-1">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-1">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-1">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-1">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-1">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-1">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-1">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-1">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-1">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-1">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-1">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-1">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-1">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-1">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<pre><code>rclone serve dlna remote:path [flags]</code></pre>
<h2 id="options-68">Options</h2>
<pre><code> --addr string The ip:port or :port to bind the DLNA http server to (default ":7879")
--announce-interval duration The interval between SSDP announcements (default 12m0s)
--dir-cache-time duration Time to cache directory entries for (default 5m0s)
--dir-perms FileMode Directory permissions (default 0777)
--file-perms FileMode File permissions (default 0666)
--gid uint32 Override the gid field set by the filesystem (not supported on Windows) (default 1000)
-h, --help help for dlna
--interface stringArray The interface to use for SSDP (repeat as necessary)
--log-trace Enable trace logging of SOAP traffic
--name string Name of DLNA server
--no-checksum Don't compare checksums on up/download
--no-modtime Don't read/write the modification time (can speed things up)
--no-seek Don't allow seeking in files
--poll-interval duration Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
--read-only Only allow read-only access
--uid uint32 Override the uid field set by the filesystem (not supported on Windows) (default 1000)
--umask int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-68">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-docker">rclone serve docker</h1>
<p>Serve any remote on docker’s volume plugin API.</p>
<h2 id="synopsis-61">Synopsis</h2>
<p>This command implements the Docker volume plugin API allowing docker
to use rclone as a data storage mechanism for various cloud providers.
rclone provides <a href="/docker">docker volume plugin</a> based on
it.</p>
<p>To create a docker plugin, one must create a Unix or TCP socket that
Docker will look for when you use the plugin and then it listens for
commands from 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 just run it directly from the command line, for example:</p>
<pre><code>sudo rclone serve docker --base-dir /tmp/rclone-volumes --socket-addr localhost:8787 -vv</code></pre>
<p>Running <code>rclone serve docker</code> will create the said socket,
listening for commands from Docker to create the necessary Volumes.
Normally you need not give the <code>--socket-addr</code> flag. The API
will listen on the unix domain socket at
<code>/run/docker/plugins/rclone.sock</code>. In the example above
rclone will create a TCP socket and a small file
<code>/etc/docker/plugins/rclone.spec</code> containing the socket
address. We use <code>sudo</code> because both paths are writeable only
by the root user.</p>
<p>If you later decide to change listening socket, the docker daemon
must be restarted to reconnect to
<code>/run/docker/plugins/rclone.sock</code> or parse new
<code>/etc/docker/plugins/rclone.spec</code>. Until you restart, any
volume related docker commands will timeout trying to access the old
socket. Running directly is supported on <strong>Linux only</strong>,
not on Windows or MacOS. This is not a problem with managed plugin mode
described in details in the <a href="https://rclone.org/docker">full
documentation</a>.</p>
<p>The command will create volume mounts under the path given by
<code>--base-dir</code> (by default
<code>/var/lib/docker-volumes/rclone</code> available only to root) and
maintain the JSON formatted file <code>docker-plugin.state</code> in the
rclone cache directory with book-keeping records of created and mounted
volumes.</p>
<p>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
path to the config file and cache directory or adjust logging
verbosity.</p>
<h2 id="vfs---virtual-file-system-2">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-2">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-2">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-2">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-2">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-2">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-2">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-2">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-2">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-2">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-2">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-2">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-2">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-2">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<pre><code>rclone serve docker [flags]</code></pre>
<h2 id="options-69">Options</h2>
<pre><code> --allow-non-empty Allow mounting over a non-empty directory (not supported on Windows)
--allow-other Allow access to other users (not supported on Windows)
--allow-root Allow access to root user (not supported on Windows)
--async-read Use asynchronous reads (not supported on Windows) (default true)
--attr-timeout duration Time for which file/directory attributes are cached (default 1s)
--base-dir string Base directory for volumes (default "/var/lib/docker-volumes/rclone")
--daemon Run mount in background and exit parent process (as background output is suppressed, use --log-file with --log-format=pid,... to monitor) (not supported on Windows)
--daemon-timeout duration Time limit for rclone to respond to kernel (not supported on Windows)
--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 0777)
--file-perms FileMode File permissions (default 0666)
--forget-state Skip restoring previous state
--fuse-flag stringArray Flags or arguments to be passed direct to libfuse/WinFsp (repeat if required)
--gid uint32 Override the gid field set by the filesystem (not supported on Windows) (default 1000)
-h, --help help for docker
--max-read-ahead SizeSuffix The number of bytes that can be prefetched for sequential reads (not supported on Windows) (default 128Ki)
--network-mode Mount as remote network drive, instead of fixed disk drive (supported on Windows only)
--no-checksum Don't compare checksums on up/download
--no-modtime Don't read/write the modification time (can speed things up)
--no-seek Don't allow seeking in files
--no-spec Do not write spec file
--noappledouble Ignore Apple Double (._) and .DS_Store files (supported on OSX only) (default true)
--noapplexattr Ignore all "com.apple.*" extended attributes (supported on OSX only)
-o, --option stringArray Option for libfuse/WinFsp (repeat if required)
--poll-interval duration Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
--read-only Only allow read-only access
--socket-addr string Address <host:port> or absolute path (default: /run/docker/plugins/rclone.sock)
--socket-gid int GID for unix socket (default: current process GID) (default 1000)
--uid uint32 Override the uid field set by the filesystem (not supported on Windows) (default 1000)
--umask int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-69">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-ftp">rclone serve ftp</h1>
<p>Serve remote:path over FTP.</p>
<h2 id="synopsis-62">Synopsis</h2>
<p>Run a basic FTP server to serve a remote over FTP protocol. This can
be viewed with a FTP client or you can make a remote of type FTP to read
and write it.</p>
<h2 id="server-options-1">Server options</h2>
<p>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. You can use port :0 to let the
OS choose an available port.</p>
<p>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.</p>
<h3 id="authentication">Authentication</h3>
<p>By default this will serve files without needing a login.</p>
<p>You can set a single username and password with the –user and –pass
flags.</p>
<h2 id="vfs---virtual-file-system-3">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-3">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-3">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-3">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-3">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-3">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-3">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-3">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-3">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-3">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-3">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-3">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-3">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-3">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<h2 id="auth-proxy">Auth Proxy</h2>
<p>If you supply the parameter
<code>--auth-proxy /path/to/program</code> then rclone will use that
program to generate backends on the fly which then are used to
authenticate incoming requests. This uses a simple JSON based protocol
with input on STDIN and output on STDOUT.</p>
<p><strong>PLEASE NOTE:</strong> <code>--auth-proxy</code> and
<code>--authorized-keys</code> cannot be used together, if
<code>--auth-proxy</code> is set the authorized keys option will be
ignored.</p>
<p>There is an example program <a
href="https://github.com/rclone/rclone/blob/master/test_proxy.py">bin/test_proxy.py</a>
in the rclone source code.</p>
<p>The program’s job is to take a <code>user</code> and
<code>pass</code> 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.</p>
<p>This config generated must have this extra parameter -
<code>_root</code> - root to use for the backend</p>
<p>And it may have this parameter - <code>_obscure</code> - comma
separated strings for parameters to obscure</p>
<p>If password authentication was used by the client, input to the proxy
process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"pass": "mypassword"
}</code></pre>
<p>If public-key authentication was used by the client, input to the
proxy process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf"
}</code></pre>
<p>And as an example return this on STDOUT</p>
<pre><code>{
"type": "sftp",
"_root": "",
"_obscure": "pass",
"user": "me",
"pass": "mypassword",
"host": "sftp.example.com"
}</code></pre>
<p>This would mean that an SFTP backend would be created on the fly for
the <code>user</code> and <code>pass</code>/<code>public_key</code>
returned in the output to the host given. Note that since
<code>_obscure</code> is set to <code>pass</code>, rclone will obscure
the <code>pass</code> parameter before creating the backend (which is
required for sftp backends).</p>
<p>The program can manipulate the supplied <code>user</code> in any way,
for example to make proxy to many different sftp backends, you could
make the <code>user</code> be <code>user@example.com</code> and then set
the <code>host</code> to <code>example.com</code> in the output and the
user to <code>user</code>. For security you’d probably want to restrict
the <code>host</code> to a limited list.</p>
<p>Note that an internal cache is keyed on <code>user</code> so only use
that for configuration, don’t use <code>pass</code> or
<code>public_key</code>. This also means that if a user’s password or
public-key is changed the cache will need to expire (which takes 5 mins)
before it takes effect.</p>
<p>This can be used to build general purpose proxies to any kind of
backend that rclone supports.</p>
<pre><code>rclone serve ftp remote:path [flags]</code></pre>
<h2 id="options-70">Options</h2>
<pre><code> --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 0777)
--file-perms FileMode File permissions (default 0666)
--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
--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 int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--user string User name for authentication (default "anonymous")
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-70">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-http">rclone serve http</h1>
<p>Serve the remote over HTTP.</p>
<h2 id="synopsis-63">Synopsis</h2>
<p>Run a basic web server to serve a remote over HTTP. This can be
viewed in a web browser or you can make a remote of type http read from
it.</p>
<p>You can use the filter flags (e.g. <code>--include</code>,
<code>--exclude</code>) to control what is served.</p>
<p>The server will log errors. Use <code>-v</code> to see access
logs.</p>
<p><code>--bwlimit</code> will be respected for file transfers. Use
<code>--stats</code> to control the stats printing.</p>
<h2 id="server-options-2">Server options</h2>
<p>Use <code>--addr</code> to specify which IP address and port the
server should listen on, eg <code>--addr 1.2.3.4:8000</code> or
<code>--addr :8080</code> 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.</p>
<p>If you set <code>--addr</code> to listen on a public or LAN
accessible IP address then using Authentication is advised - see the
next section for info.</p>
<p><code>--server-read-timeout</code> and
<code>--server-write-timeout</code> can be used to control the timeouts
on the server. Note that this is the total time for a transfer.</p>
<p><code>--max-header-bytes</code> controls the maximum number of bytes
the server will accept in the HTTP header.</p>
<p><code>--baseurl</code> controls the URL prefix that rclone serves
from. By default rclone will serve from the root. If you used
<code>--baseurl "/rclone"</code> 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
<code>--baseurl</code>, so <code>--baseurl "rclone"</code>,
<code>--baseurl "/rclone"</code> and <code>--baseurl "/rclone/"</code>
are all treated identically.</p>
<h3 id="ssltls">SSL/TLS</h3>
<p>By default this will serve over http. If you want you can serve over
https. You will need to supply the <code>--cert</code> and
<code>--key</code> flags. If you wish to do client side certificate
validation then you will need to supply <code>--client-ca</code>
also.</p>
<p><code>--cert</code> should be a either a PEM encoded certificate or a
concatenation of that with the CA certificate. <code>--key</code> should
be the PEM encoded private key and <code>--client-ca</code> should be
the PEM encoded client certificate authority certificate.</p>
<p>–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”).</p>
<h3 id="template">Template</h3>
<p><code>--template</code> 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:</p>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">.Name</td>
<td style="text-align: left;">The full path of a file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Title</td>
<td style="text-align: left;">Directory listing of .Name</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Sort</td>
<td style="text-align: left;">The current sort used. This is changeable
via ?sort= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Sort Options: namedirfirst,name,size,time
(default namedirfirst)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Order</td>
<td style="text-align: left;">The current ordering used. This is
changeable via ?order= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Order Options: asc,desc (default asc)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Query</td>
<td style="text-align: left;">Currently unused.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Breadcrumb</td>
<td style="text-align: left;">Allows for creating a relative
navigation</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Link</td>
<td style="text-align: left;">The relative to the root link of the
Text.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .Text</td>
<td style="text-align: left;">The Name of the directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Entries</td>
<td style="text-align: left;">Information about a specific
file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .URL</td>
<td style="text-align: left;">The ‘url’ of an entry.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Leaf</td>
<td style="text-align: left;">Currently same as ‘URL’ but intended to be
‘just’ the name.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .IsDir</td>
<td style="text-align: left;">Boolean for if an entry is a directory or
not.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Size</td>
<td style="text-align: left;">Size in Bytes of the entry.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .ModTime</td>
<td style="text-align: left;">The UTC timestamp of an entry.</td>
</tr>
</tbody>
</table>
<h3 id="authentication-1">Authentication</h3>
<p>By default this will serve files without needing a login.</p>
<p>You can either use an htpasswd file which can take lots of users, or
set a single username and password with the <code>--user</code> and
<code>--pass</code> flags.</p>
<p>Use <code>--htpasswd /path/to/htpasswd</code> to provide an htpasswd
file. This is in standard apache format and supports MD5, SHA1 and
BCrypt for basic authentication. Bcrypt is recommended.</p>
<p>To create an htpasswd file:</p>
<pre><code>touch htpasswd
htpasswd -B htpasswd user
htpasswd -B htpasswd anotherUser</code></pre>
<p>The password file can be updated while rclone is running.</p>
<p>Use <code>--realm</code> to set the authentication realm.</p>
<p>Use <code>--salt</code> to change the password hashing salt from the
default.</p>
<h2 id="vfs---virtual-file-system-4">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-4">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-4">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-4">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-4">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-4">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-4">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-4">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-4">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-4">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-4">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-4">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-4">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-4">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<pre><code>rclone serve http remote:path [flags]</code></pre>
<h2 id="options-71">Options</h2>
<pre><code> --addr string IPaddress:Port or :Port to bind server to (default "127.0.0.1:8080")
--baseurl string Prefix for URLs - leave blank for root
--cert string SSL 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 0777)
--file-perms FileMode File permissions (default 0666)
--gid uint32 Override the gid field set by the filesystem (not supported on Windows) (default 1000)
-h, --help help for http
--htpasswd string A htpasswd file - if not provided no authentication is done
--key string SSL 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")
--no-checksum Don't compare checksums on up/download
--no-modtime Don't read/write the modification time (can speed things up)
--no-seek Don't allow seeking in files
--pass string Password for authentication
--poll-interval duration Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
--read-only Only allow read-only access
--realm string Realm for authentication
--salt string Password hashing salt (default "dlPL2MqE")
--server-read-timeout duration Timeout for server reading data (default 1h0m0s)
--server-write-timeout duration Timeout for server writing data (default 1h0m0s)
--template string User-specified template
--uid uint32 Override the uid field set by the filesystem (not supported on Windows) (default 1000)
--umask int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--user string User name for authentication
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-71">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-restic">rclone serve restic</h1>
<p>Serve the remote for restic’s REST API.</p>
<h2 id="synopsis-64">Synopsis</h2>
<p>Run a basic web server to serve a remove over restic’s REST backend
API over HTTP. This allows restic to use rclone as a data storage
mechanism for cloud providers that restic does not support directly.</p>
<p><a href="https://restic.net/">Restic</a> is a command-line program
for doing backups.</p>
<p>The server will log errors. Use -v to see access logs.</p>
<p><code>--bwlimit</code> will be respected for file transfers. Use
<code>--stats</code> to control the stats printing.</p>
<h2 id="setting-up-rclone-for-use-by-restic">Setting up rclone for use
by restic</h2>
<p>First <a href="https://rclone.org/docs/#configure">set up a remote
for your chosen cloud provider</a>.</p>
<p>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.</p>
<p>Now start the rclone restic server</p>
<pre><code>rclone serve restic -v remote:backup</code></pre>
<p>Where you can replace “backup” in the above by whatever path in the
remote you wish to use.</p>
<p>By default this will serve on “localhost:8080” you can change this
with use of the <code>--addr</code> flag.</p>
<p>You might wish to start this server on boot.</p>
<p>Adding <code>--cache-objects=false</code> 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.</p>
<h2 id="setting-up-restic-to-use-rclone">Setting up restic to use
rclone</h2>
<p>Now you can <a
href="http://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#rest-server">follow
the restic instructions</a> on setting up restic.</p>
<p>Note that you will need restic 0.8.2 or later to interoperate with
rclone.</p>
<p>For the example above you will want to use “http://localhost:8080/”
as the URL for the REST server.</p>
<p>For example:</p>
<pre><code>$ 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</code></pre>
<h3 id="multiple-repositories">Multiple repositories</h3>
<p>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
<strong>must</strong> end with /. Eg</p>
<pre><code>$ export RESTIC_REPOSITORY=rest:http://localhost:8080/user1repo/
# backup user1 stuff
$ export RESTIC_REPOSITORY=rest:http://localhost:8080/user2repo/
# backup user2 stuff</code></pre>
<h3 id="private-repositories">Private repositories</h3>
<p>The<code>--private-repos</code> flag can be used to limit users to
repositories starting with a path of
<code>/<username>/</code>.</p>
<h2 id="server-options-3">Server options</h2>
<p>Use <code>--addr</code> to specify which IP address and port the
server should listen on, e.g. <code>--addr 1.2.3.4:8000</code> or
<code>--addr :8080</code> 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.</p>
<p>If you set <code>--addr</code> to listen on a public or LAN
accessible IP address then using Authentication is advised - see the
next section for info.</p>
<p><code>--server-read-timeout</code> and
<code>--server-write-timeout</code> can be used to control the timeouts
on the server. Note that this is the total time for a transfer.</p>
<p><code>--max-header-bytes</code> controls the maximum number of bytes
the server will accept in the HTTP header.</p>
<p><code>--baseurl</code> controls the URL prefix that rclone serves
from. By default rclone will serve from the root. If you used
<code>--baseurl "/rclone"</code> 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
<code>--baseurl</code>, so <code>--baseurl "rclone"</code>,
<code>--baseurl "/rclone"</code> and <code>--baseurl "/rclone/"</code>
are all treated identically.</p>
<p><code>--template</code> 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:</p>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">.Name</td>
<td style="text-align: left;">The full path of a file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Title</td>
<td style="text-align: left;">Directory listing of .Name</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Sort</td>
<td style="text-align: left;">The current sort used. This is changeable
via ?sort= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Sort Options: namedirfirst,name,size,time
(default namedirfirst)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Order</td>
<td style="text-align: left;">The current ordering used. This is
changeable via ?order= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Order Options: asc,desc (default asc)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Query</td>
<td style="text-align: left;">Currently unused.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Breadcrumb</td>
<td style="text-align: left;">Allows for creating a relative
navigation</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Link</td>
<td style="text-align: left;">The relative to the root link of the
Text.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .Text</td>
<td style="text-align: left;">The Name of the directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Entries</td>
<td style="text-align: left;">Information about a specific
file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .URL</td>
<td style="text-align: left;">The ‘url’ of an entry.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Leaf</td>
<td style="text-align: left;">Currently same as ‘URL’ but intended to be
‘just’ the name.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .IsDir</td>
<td style="text-align: left;">Boolean for if an entry is a directory or
not.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Size</td>
<td style="text-align: left;">Size in Bytes of the entry.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .ModTime</td>
<td style="text-align: left;">The UTC timestamp of an entry.</td>
</tr>
</tbody>
</table>
<h3 id="authentication-2">Authentication</h3>
<p>By default this will serve files without needing a login.</p>
<p>You can either use an htpasswd file which can take lots of users, or
set a single username and password with the <code>--user</code> and
<code>--pass</code> flags.</p>
<p>Use <code>--htpasswd /path/to/htpasswd</code> to provide an htpasswd
file. This is in standard apache format and supports MD5, SHA1 and
BCrypt for basic authentication. Bcrypt is recommended.</p>
<p>To create an htpasswd file:</p>
<pre><code>touch htpasswd
htpasswd -B htpasswd user
htpasswd -B htpasswd anotherUser</code></pre>
<p>The password file can be updated while rclone is running.</p>
<p>Use <code>--realm</code> to set the authentication realm.</p>
<h3 id="ssltls-1">SSL/TLS</h3>
<p>By default this will serve over HTTP. If you want you can serve over
HTTPS. You will need to supply the <code>--cert</code> and
<code>--key</code> flags. If you wish to do client side certificate
validation then you will need to supply <code>--client-ca</code>
also.</p>
<p><code>--cert</code> should be either a PEM encoded certificate or a
concatenation of that with the CA certificate. <code>--key</code> should
be the PEM encoded private key and <code>--client-ca</code> should be
the PEM encoded client certificate authority certificate.</p>
<p>–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”).</p>
<pre><code>rclone serve restic remote:path [flags]</code></pre>
<h2 id="options-72">Options</h2>
<pre><code> --addr string IPaddress:Port or :Port to bind server to (default "localhost:8080")
--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 SSL 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 htpasswd file - if not provided no authentication is done
--key string SSL 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 (default "rclone")
--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
--template string User-specified template
--user string User name for authentication</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-72">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-sftp">rclone serve sftp</h1>
<p>Serve the remote over SFTP.</p>
<h2 id="synopsis-65">Synopsis</h2>
<p>Run an SFTP server to serve a remote over SFTP. This can be used with
an SFTP client or you can make a remote of type <a href="/sftp">sftp</a>
to use with it.</p>
<p>You can use the <a href="/filtering">filter</a> flags
(e.g. <code>--include</code>, <code>--exclude</code>) to control what is
served.</p>
<p>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.</p>
<p>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 <a
href="https://rclone.org/sftp/#sftp-chunk-size">chunk_size</a> option on
an sftp remote.</p>
<p>The server will log errors. Use <code>-v</code> to see access
logs.</p>
<p><code>--bwlimit</code> will be respected for file transfers. Use
<code>--stats</code> to control the stats printing.</p>
<p>You must provide some means of authentication, either with
<code>--user</code>/<code>--pass</code>, an authorized keys file
(specify location with <code>--authorized-keys</code> - the default is
the same as ssh), an <code>--auth-proxy</code>, or set the
<code>--no-auth</code> flag for no authentication when logging in.</p>
<p>If you don’t supply a host <code>--key</code> then rclone will
generate rsa, ecdsa and ed25519 variants, and cache them for later use
in rclone’s cache directory (see
<code>rclone help flags cache-dir</code>) in the “serve-sftp”
directory.</p>
<p>By default the server binds to localhost:2022 - if you want it to be
reachable externally then supply <code>--addr :2022</code> for
example.</p>
<p>Note that the default of <code>--vfs-cache-mode off</code> is fine
for the rclone sftp backend, but it may not be with other SFTP
clients.</p>
<p>If <code>--stdio</code> is specified, rclone will serve SFTP over
stdio, which can be used with sshd via ~/.ssh/authorized_keys, for
example:</p>
<pre><code>restrict,command="rclone serve sftp --stdio ./photos" ssh-rsa ...</code></pre>
<p>On the client you need to set <code>--transfers 1</code> when using
<code>--stdio</code>. 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.</p>
<p>The “restrict” in authorized_keys prevents SHA1SUMs and MD5SUMs from
beeing used. Omitting “restrict” and using
<code>--sftp-path-override</code> to enable checksumming is possible but
less secure and you could use the SFTP server provided by OpenSSH in
this case.</p>
<h2 id="vfs---virtual-file-system-5">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-5">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-5">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-5">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-5">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-5">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-5">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-5">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-5">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-5">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-5">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-5">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-5">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-5">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<h2 id="auth-proxy-1">Auth Proxy</h2>
<p>If you supply the parameter
<code>--auth-proxy /path/to/program</code> then rclone will use that
program to generate backends on the fly which then are used to
authenticate incoming requests. This uses a simple JSON based protocol
with input on STDIN and output on STDOUT.</p>
<p><strong>PLEASE NOTE:</strong> <code>--auth-proxy</code> and
<code>--authorized-keys</code> cannot be used together, if
<code>--auth-proxy</code> is set the authorized keys option will be
ignored.</p>
<p>There is an example program <a
href="https://github.com/rclone/rclone/blob/master/test_proxy.py">bin/test_proxy.py</a>
in the rclone source code.</p>
<p>The program’s job is to take a <code>user</code> and
<code>pass</code> 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.</p>
<p>This config generated must have this extra parameter -
<code>_root</code> - root to use for the backend</p>
<p>And it may have this parameter - <code>_obscure</code> - comma
separated strings for parameters to obscure</p>
<p>If password authentication was used by the client, input to the proxy
process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"pass": "mypassword"
}</code></pre>
<p>If public-key authentication was used by the client, input to the
proxy process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf"
}</code></pre>
<p>And as an example return this on STDOUT</p>
<pre><code>{
"type": "sftp",
"_root": "",
"_obscure": "pass",
"user": "me",
"pass": "mypassword",
"host": "sftp.example.com"
}</code></pre>
<p>This would mean that an SFTP backend would be created on the fly for
the <code>user</code> and <code>pass</code>/<code>public_key</code>
returned in the output to the host given. Note that since
<code>_obscure</code> is set to <code>pass</code>, rclone will obscure
the <code>pass</code> parameter before creating the backend (which is
required for sftp backends).</p>
<p>The program can manipulate the supplied <code>user</code> in any way,
for example to make proxy to many different sftp backends, you could
make the <code>user</code> be <code>user@example.com</code> and then set
the <code>host</code> to <code>example.com</code> in the output and the
user to <code>user</code>. For security you’d probably want to restrict
the <code>host</code> to a limited list.</p>
<p>Note that an internal cache is keyed on <code>user</code> so only use
that for configuration, don’t use <code>pass</code> or
<code>public_key</code>. This also means that if a user’s password or
public-key is changed the cache will need to expire (which takes 5 mins)
before it takes effect.</p>
<p>This can be used to build general purpose proxies to any kind of
backend that rclone supports.</p>
<pre><code>rclone serve sftp remote:path [flags]</code></pre>
<h2 id="options-73">Options</h2>
<pre><code> --addr string IPaddress:Port or :Port to bind server to (default "localhost:2022")
--auth-proxy string A program to use to create the backend from the auth
--authorized-keys string Authorized keys file (default "~/.ssh/authorized_keys")
--dir-cache-time duration Time to cache directory entries for (default 5m0s)
--dir-perms FileMode Directory permissions (default 0777)
--file-perms FileMode File permissions (default 0666)
--gid uint32 Override the gid field set by the filesystem (not supported on Windows) (default 1000)
-h, --help help for sftp
--key stringArray SSH private host key file (Can be multi-valued, leave blank to auto generate)
--no-auth Allow connections with no authentication if set
--no-checksum Don't compare checksums on up/download
--no-modtime Don't read/write the modification time (can speed things up)
--no-seek Don't allow seeking in files
--pass string Password for authentication
--poll-interval duration Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
--read-only Only allow read-only access
--stdio Run an sftp server on stdin/stdout
--uid uint32 Override the uid field set by the filesystem (not supported on Windows) (default 1000)
--umask int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--user string User name for authentication
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-73">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-serve-webdav">rclone serve webdav</h1>
<p>Serve remote:path over WebDAV.</p>
<h2 id="synopsis-66">Synopsis</h2>
<p>Run a basic WebDAV server to serve a remote over HTTP via the WebDAV
protocol. This can be viewed with a WebDAV client, through a web
browser, or you can make a remote of type WebDAV to read and write
it.</p>
<h2 id="webdav-options">WebDAV options</h2>
<h3 id="etag-hash">–etag-hash</h3>
<p>This controls the ETag header. Without this flag the ETag will be
based on the ModTime and Size of the object.</p>
<p>If this flag is set to “auto” then rclone will choose the first
supported hash on the backend or you can use a named hash such as “MD5”
or “SHA-1”. Use the <a
href="https://rclone.org/commands/rclone_hashsum/">hashsum</a> command
to see the full list.</p>
<h2 id="server-options-4">Server options</h2>
<p>Use <code>--addr</code> to specify which IP address and port the
server should listen on, e.g. <code>--addr 1.2.3.4:8000</code> or
<code>--addr :8080</code> 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.</p>
<p>If you set <code>--addr</code> to listen on a public or LAN
accessible IP address then using Authentication is advised - see the
next section for info.</p>
<p><code>--server-read-timeout</code> and
<code>--server-write-timeout</code> can be used to control the timeouts
on the server. Note that this is the total time for a transfer.</p>
<p><code>--max-header-bytes</code> controls the maximum number of bytes
the server will accept in the HTTP header.</p>
<p><code>--baseurl</code> controls the URL prefix that rclone serves
from. By default rclone will serve from the root. If you used
<code>--baseurl "/rclone"</code> 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
<code>--baseurl</code>, so <code>--baseurl "rclone"</code>,
<code>--baseurl "/rclone"</code> and <code>--baseurl "/rclone/"</code>
are all treated identically.</p>
<p><code>--template</code> 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:</p>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">.Name</td>
<td style="text-align: left;">The full path of a file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Title</td>
<td style="text-align: left;">Directory listing of .Name</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Sort</td>
<td style="text-align: left;">The current sort used. This is changeable
via ?sort= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Sort Options: namedirfirst,name,size,time
(default namedirfirst)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Order</td>
<td style="text-align: left;">The current ordering used. This is
changeable via ?order= parameter</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">Order Options: asc,desc (default asc)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Query</td>
<td style="text-align: left;">Currently unused.</td>
</tr>
<tr class="even">
<td style="text-align: left;">.Breadcrumb</td>
<td style="text-align: left;">Allows for creating a relative
navigation</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Link</td>
<td style="text-align: left;">The relative to the root link of the
Text.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .Text</td>
<td style="text-align: left;">The Name of the directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">.Entries</td>
<td style="text-align: left;">Information about a specific
file/directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .URL</td>
<td style="text-align: left;">The ‘url’ of an entry.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Leaf</td>
<td style="text-align: left;">Currently same as ‘URL’ but intended to be
‘just’ the name.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .IsDir</td>
<td style="text-align: left;">Boolean for if an entry is a directory or
not.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">– .Size</td>
<td style="text-align: left;">Size in Bytes of the entry.</td>
</tr>
<tr class="even">
<td style="text-align: left;">– .ModTime</td>
<td style="text-align: left;">The UTC timestamp of an entry.</td>
</tr>
</tbody>
</table>
<h3 id="authentication-3">Authentication</h3>
<p>By default this will serve files without needing a login.</p>
<p>You can either use an htpasswd file which can take lots of users, or
set a single username and password with the <code>--user</code> and
<code>--pass</code> flags.</p>
<p>Use <code>--htpasswd /path/to/htpasswd</code> to provide an htpasswd
file. This is in standard apache format and supports MD5, SHA1 and
BCrypt for basic authentication. Bcrypt is recommended.</p>
<p>To create an htpasswd file:</p>
<pre><code>touch htpasswd
htpasswd -B htpasswd user
htpasswd -B htpasswd anotherUser</code></pre>
<p>The password file can be updated while rclone is running.</p>
<p>Use <code>--realm</code> to set the authentication realm.</p>
<h3 id="ssltls-2">SSL/TLS</h3>
<p>By default this will serve over HTTP. If you want you can serve over
HTTPS. You will need to supply the <code>--cert</code> and
<code>--key</code> flags. If you wish to do client side certificate
validation then you will need to supply <code>--client-ca</code>
also.</p>
<p><code>--cert</code> should be either a PEM encoded certificate or a
concatenation of that with the CA certificate. <code>--key</code> should
be the PEM encoded private key and <code>--client-ca</code> should be
the PEM encoded client certificate authority certificate.</p>
<p>–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”).</p>
<h2 id="vfs---virtual-file-system-6">VFS - Virtual File System</h2>
<p>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.</p>
<p>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.</p>
<p>The VFS layer also implements a directory cache - this caches info
about files and directories (but not the data) in memory.</p>
<h2 id="vfs-directory-cache-6">VFS Directory Cache</h2>
<p>Using the <code>--dir-cache-time</code> 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.</p>
<pre><code>--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)</code></pre>
<p>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.</p>
<p>You can send a <code>SIGHUP</code> 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:</p>
<pre><code>kill -SIGHUP $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use rclone rc to flush the whole directory cache:</p>
<pre><code>rclone rc vfs/forget</code></pre>
<p>Or individual files or directories:</p>
<pre><code>rclone rc vfs/forget file=path/to/file dir=path/to/dir</code></pre>
<h2 id="vfs-file-buffering-6">VFS File Buffering</h2>
<p>The <code>--buffer-size</code> flag determines the amount of memory,
that will be used to buffer data in advance.</p>
<p>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.</p>
<p>This flag is a upper limit for the used memory per open file. The
buffer will only use memory for data that is downloaded but not not yet
read. If the buffer is empty, only a small amount of memory will be
used.</p>
<p>The maximum memory used by rclone for buffering can be up to
<code>--buffer-size * open files</code>.</p>
<h2 id="vfs-file-caching-6">VFS File Caching</h2>
<p>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.</p>
<p>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.</p>
<p>Note that the VFS cache is separate from the cache backend and you
may find that you need one or the other or both.</p>
<pre><code>--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 age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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)</code></pre>
<p>If run with <code>-vv</code> 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 <code>--cache-dir</code> or setting
the appropriate environment variable.</p>
<p>The cache has 4 different modes selected by
<code>--vfs-cache-mode</code>. The higher the cache mode the more
compatible rclone becomes at the cost of using disk space.</p>
<p>Note that files are written back to the remote only when they are
closed and if they haven’t been accessed for
<code>--vfs-write-back</code> 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.</p>
<p>If using <code>--vfs-cache-max-size</code> note that the cache may
exceed this size for two reasons. Firstly because it is only checked
every <code>--vfs-cache-poll-interval</code>. Secondly because open
files cannot be evicted from the cache.</p>
<p>You <strong>should not</strong> run two copies of rclone using the
same VFS cache with the same or overlapping remotes if using
<code>--vfs-cache-mode > off</code>. This can potentially cause data
corruption if you do. You can work around this by giving each rclone its
own cache hierarchy with <code>--cache-dir</code>. You don’t need to
worry about this if the remotes in use don’t overlap.</p>
<h3 id="vfs-cache-mode-off-6">–vfs-cache-mode off</h3>
<p>In this mode (the default) the cache will read directly from the
remote and write directly to the remote without caching anything on
disk.</p>
<p>This will mean some operations are not possible</p>
<ul>
<li>Files can’t be opened for both read AND write</li>
<li>Files opened for write can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files open for read with O_TRUNC will be opened write only</li>
<li>Files open for write only will behave as if O_TRUNC was
supplied</li>
<li>Open modes O_APPEND, O_TRUNC are ignored</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-minimal-6">–vfs-cache-mode minimal</h3>
<p>This is very similar to “off” except that files opened for read AND
write will be buffered to disk. This means that files opened for write
will be a lot more compatible, but uses the minimal disk space.</p>
<p>These operations are not possible</p>
<ul>
<li>Files opened for write only can’t be seeked</li>
<li>Existing files opened for write must have O_TRUNC set</li>
<li>Files opened for write only will ignore O_APPEND, O_TRUNC</li>
<li>If an upload fails it can’t be retried</li>
</ul>
<h3 id="vfs-cache-mode-writes-6">–vfs-cache-mode writes</h3>
<p>In this mode files opened for read only are still read directly from
the remote, write only and read/write files are buffered to disk
first.</p>
<p>This mode should support all normal file system operations.</p>
<p>If an upload fails it will be retried at exponentially increasing
intervals up to 1 minute.</p>
<h3 id="vfs-cache-mode-full-6">–vfs-cache-mode full</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This mode should support all normal file system operations and is
otherwise identical to <code>--vfs-cache-mode</code> writes.</p>
<p>When reading a file rclone will read <code>--buffer-size</code> plus
<code>--vfs-read-ahead</code> bytes ahead. The
<code>--buffer-size</code> is buffered in memory whereas the
<code>--vfs-read-ahead</code> is buffered on disk.</p>
<p>When using this mode it is recommended that
<code>--buffer-size</code> is not set too large and
<code>--vfs-read-ahead</code> is set large if required.</p>
<p><strong>IMPORTANT</strong> 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.</p>
<h3 id="fingerprinting-6">Fingerprinting</h3>
<p>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:</p>
<ul>
<li>size</li>
<li>modification time</li>
<li>hash</li>
</ul>
<p>where available on an object.</p>
<p>On some backends some of these attributes are slow to read (they take
an extra API call per object, or extra work per object).</p>
<p>For example <code>hash</code> is slow with the <code>local</code> and
<code>sftp</code> backends as they have to read the entire file and hash
it, and <code>modtime</code> is slow with the <code>s3</code>,
<code>swift</code>, <code>ftp</code> and <code>qinqstor</code> backends
because they need to do an extra API call to fetch it.</p>
<p>If you use the <code>--vfs-fast-fingerprint</code> 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.</p>
<p>If you are running a vfs cache over <code>local</code>,
<code>s3</code> or <code>swift</code> backends then using this flag is
recommended.</p>
<p>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.</p>
<h2 id="vfs-chunked-reading-6">VFS Chunked Reading</h2>
<p>When rclone reads files from a remote it reads them in chunks. This
means that rather than requesting the whole file rclone reads the chunk
specified. This can reduce the used download quota for some remotes by
requesting only chunks from the remote that are actually read, at the
cost of an increased number of requests.</p>
<p>These flags control the chunking:</p>
<pre><code>--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)</code></pre>
<p>Rclone will start reading a chunk of size
<code>--vfs-read-chunk-size</code>, and then double the size for each
read. When <code>--vfs-read-chunk-size-limit</code> is specified, and
greater than <code>--vfs-read-chunk-size</code>, 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.</p>
<p>With <code>--vfs-read-chunk-size 100M</code> and
<code>--vfs-read-chunk-size-limit 0</code> the following parts will be
downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on. When
<code>--vfs-read-chunk-size-limit 500M</code> is specified, the result
would be 0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so
on.</p>
<p>Setting <code>--vfs-read-chunk-size</code> to <code>0</code> or “off”
disables chunked reading.</p>
<h2 id="vfs-performance-6">VFS Performance</h2>
<p>These flags may be used to enable/disable features of the VFS for
performance or other reasons. See also the <a
href="#vfs-chunked-reading">chunked reading</a> feature.</p>
<p>In particular S3 and Swift benefit hugely from the
<code>--no-modtime</code> flag (or use <code>--use-server-modtime</code>
for a slightly different effect) as each read of the modification time
takes a transaction.</p>
<pre><code>--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.</code></pre>
<p>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.</p>
<pre><code>--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)</code></pre>
<p>When using VFS write caching (<code>--vfs-cache-mode</code> with
value writes or full), the global flag <code>--transfers</code> can be
set to adjust the number of parallel uploads of modified files from the
cache (the related global flag <code>--checkers</code> has no effect on
the VFS).</p>
<pre><code>--transfers int Number of file transfers to run in parallel (default 4)</code></pre>
<h2 id="vfs-case-sensitivity-6">VFS Case Sensitivity</h2>
<p>Linux file systems are case-sensitive: two files can differ only by
case, and the exact case must be used when opening a file.</p>
<p>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.</p>
<p>Usually file systems on macOS are case-insensitive. It is possible to
make macOS file systems case-sensitive but that is not the default.</p>
<p>The <code>--vfs-case-insensitive</code> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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”.</p>
<h2 id="vfs-disk-options-6">VFS Disk Options</h2>
<p>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.</p>
<pre><code>--vfs-disk-space-total-size Manually set the total disk space size (example: 256G, default: -1)</code></pre>
<h2 id="alternate-report-of-used-bytes-6">Alternate report of used
bytes</h2>
<p>Some backends, most notably S3, do not report the amount of bytes
used. If you need this information to be available when running
<code>df</code> on the filesystem, then pass the flag
<code>--vfs-used-is-size</code> to rclone. With this flag set, instead
of relying on the backend to report this information, rclone will scan
the whole remote similar to <code>rclone size</code> and compute the
total used space itself.</p>
<p><em>WARNING.</em> Contrary to <code>rclone size</code>, 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.</p>
<h2 id="auth-proxy-2">Auth Proxy</h2>
<p>If you supply the parameter
<code>--auth-proxy /path/to/program</code> then rclone will use that
program to generate backends on the fly which then are used to
authenticate incoming requests. This uses a simple JSON based protocol
with input on STDIN and output on STDOUT.</p>
<p><strong>PLEASE NOTE:</strong> <code>--auth-proxy</code> and
<code>--authorized-keys</code> cannot be used together, if
<code>--auth-proxy</code> is set the authorized keys option will be
ignored.</p>
<p>There is an example program <a
href="https://github.com/rclone/rclone/blob/master/test_proxy.py">bin/test_proxy.py</a>
in the rclone source code.</p>
<p>The program’s job is to take a <code>user</code> and
<code>pass</code> 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.</p>
<p>This config generated must have this extra parameter -
<code>_root</code> - root to use for the backend</p>
<p>And it may have this parameter - <code>_obscure</code> - comma
separated strings for parameters to obscure</p>
<p>If password authentication was used by the client, input to the proxy
process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"pass": "mypassword"
}</code></pre>
<p>If public-key authentication was used by the client, input to the
proxy process (on STDIN) would look similar to this:</p>
<pre><code>{
"user": "me",
"public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf"
}</code></pre>
<p>And as an example return this on STDOUT</p>
<pre><code>{
"type": "sftp",
"_root": "",
"_obscure": "pass",
"user": "me",
"pass": "mypassword",
"host": "sftp.example.com"
}</code></pre>
<p>This would mean that an SFTP backend would be created on the fly for
the <code>user</code> and <code>pass</code>/<code>public_key</code>
returned in the output to the host given. Note that since
<code>_obscure</code> is set to <code>pass</code>, rclone will obscure
the <code>pass</code> parameter before creating the backend (which is
required for sftp backends).</p>
<p>The program can manipulate the supplied <code>user</code> in any way,
for example to make proxy to many different sftp backends, you could
make the <code>user</code> be <code>user@example.com</code> and then set
the <code>host</code> to <code>example.com</code> in the output and the
user to <code>user</code>. For security you’d probably want to restrict
the <code>host</code> to a limited list.</p>
<p>Note that an internal cache is keyed on <code>user</code> so only use
that for configuration, don’t use <code>pass</code> or
<code>public_key</code>. This also means that if a user’s password or
public-key is changed the cache will need to expire (which takes 5 mins)
before it takes effect.</p>
<p>This can be used to build general purpose proxies to any kind of
backend that rclone supports.</p>
<pre><code>rclone serve webdav remote:path [flags]</code></pre>
<h2 id="options-74">Options</h2>
<pre><code> --addr string IPaddress:Port or :Port to bind server to (default "localhost:8080")
--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 SSL 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 0777)
--disable-dir-list Disable HTML directory list on GET request for a directory
--etag-hash string Which hash to use for the ETag, or auto or blank for off
--file-perms FileMode File permissions (default 0666)
--gid uint32 Override the gid field set by the filesystem (not supported on Windows) (default 1000)
-h, --help help for webdav
--htpasswd string htpasswd file - if not provided no authentication is done
--key string SSL 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")
--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 (default "rclone")
--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 int Override the permission bits set by the filesystem (not supported on Windows) (default 2)
--user string User name for authentication
--vfs-cache-max-age duration Max age of objects in the cache (default 1h0m0s)
--vfs-cache-max-size SizeSuffix Max total size of objects in 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-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-wait duration Time to wait for in-sequence read before seeking (default 20ms)
--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)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-74">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_serve/">rclone serve</a>
- Serve a remote over a protocol.</li>
</ul>
<h1 id="rclone-settier">rclone settier</h1>
<p>Changes storage class/tier of objects in remote.</p>
<h2 id="synopsis-67">Synopsis</h2>
<p>rclone settier changes storage tier or class at remote if supported.
Few cloud storage services provides different storage classes on
objects, for example AWS S3 and Glacier, Azure Blob storage - Hot, Cool
and Archive, Google Cloud Storage, Regional Storage, Nearline, Coldline
etc.</p>
<p>Note that, certain tier changes make objects not available to access
immediately. For example tiering to archive in azure blob storage makes
objects in frozen state, user can restore by setting tier to Hot/Cool,
similarly S3 to Glacier makes object inaccessible.true</p>
<p>You can use it to tier single object</p>
<pre><code>rclone settier Cool remote:path/file</code></pre>
<p>Or use rclone filters to set tier on only specific files</p>
<pre><code>rclone --include "*.txt" settier Hot remote:path/dir</code></pre>
<p>Or just provide remote directory and all files in directory will be
tiered</p>
<pre><code>rclone settier tier remote:path/dir</code></pre>
<pre><code>rclone settier tier remote:path [flags]</code></pre>
<h2 id="options-75">Options</h2>
<pre><code> -h, --help help for settier</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-75">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-test">rclone test</h1>
<p>Run a test command</p>
<h2 id="synopsis-68">Synopsis</h2>
<p>Rclone test is used to run test commands.</p>
<p>Select which test comand you want with the subcommand, eg</p>
<pre><code>rclone test memory remote:</code></pre>
<p>Each subcommand has its own options which you can see in their
help.</p>
<p><strong>NB</strong> Be careful running these commands, they may do
strange things so reading their documentation first is recommended.</p>
<h2 id="options-76">Options</h2>
<pre><code> -h, --help help for test</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-76">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
<li><a
href="https://rclone.org/commands/rclone_test_changenotify/">rclone test
changenotify</a> - Log any change notify requests for the remote passed
in.</li>
<li><a href="https://rclone.org/commands/rclone_test_histogram/">rclone
test histogram</a> - Makes a histogram of file name characters.</li>
<li><a href="https://rclone.org/commands/rclone_test_info/">rclone test
info</a> - Discovers file name or other limitations for paths.</li>
<li><a href="https://rclone.org/commands/rclone_test_makefile/">rclone
test makefile</a> - Make files with random contents of the size
given</li>
<li><a href="https://rclone.org/commands/rclone_test_makefiles/">rclone
test makefiles</a> - Make a random file hierarchy in a directory</li>
<li><a href="https://rclone.org/commands/rclone_test_memory/">rclone
test memory</a> - Load all the objects at remote:path into memory and
report memory stats.</li>
</ul>
<h1 id="rclone-test-changenotify">rclone test changenotify</h1>
<p>Log any change notify requests for the remote passed in.</p>
<pre><code>rclone test changenotify remote: [flags]</code></pre>
<h2 id="options-77">Options</h2>
<pre><code> -h, --help help for changenotify
--poll-interval duration Time to wait between polling for changes (default 10s)</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-77">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-test-histogram">rclone test histogram</h1>
<p>Makes a histogram of file name characters.</p>
<h2 id="synopsis-69">Synopsis</h2>
<p>This command outputs JSON which shows the histogram of characters
used in filenames in the remote:path specified.</p>
<p>The data doesn’t contain any identifying information but is useful
for the rclone developers when developing filename compression.</p>
<pre><code>rclone test histogram [remote:path] [flags]</code></pre>
<h2 id="options-78">Options</h2>
<pre><code> -h, --help help for histogram</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-78">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-test-info">rclone test info</h1>
<p>Discovers file name or other limitations for paths.</p>
<h2 id="synopsis-70">Synopsis</h2>
<p>rclone info 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.</p>
<p><strong>NB</strong> this can create undeletable files and other
hazards - use with care</p>
<pre><code>rclone test info [remote:path]+ [flags]</code></pre>
<h2 id="options-79">Options</h2>
<pre><code> --all Run all tests
--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
--upload-wait duration Wait after writing a file
--write-json string Write results to file</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-79">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-test-makefile">rclone test makefile</h1>
<p>Make files with random contents of the size given</p>
<pre><code>rclone test makefile <size> [<file>]+ [flags]</code></pre>
<h2 id="options-80">Options</h2>
<pre><code> --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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-80">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-test-makefiles">rclone test makefiles</h1>
<p>Make a random file hierarchy in a directory</p>
<pre><code>rclone test makefiles <dir> [flags]</code></pre>
<h2 id="options-81">Options</h2>
<pre><code> --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)
-h, --help help for makefiles
--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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-81">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-test-memory">rclone test memory</h1>
<p>Load all the objects at remote:path into memory and report memory
stats.</p>
<pre><code>rclone test memory remote:path [flags]</code></pre>
<h2 id="options-82">Options</h2>
<pre><code> -h, --help help for memory</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-82">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone_test/">rclone test</a> -
Run a test command</li>
</ul>
<h1 id="rclone-touch">rclone touch</h1>
<p>Create new file or change file modification time.</p>
<h2 id="synopsis-71">Synopsis</h2>
<p>Set the modification time on file(s) as specified by remote:path to
have the current time.</p>
<p>If remote:path does not exist then a zero sized file will be created,
unless <code>--no-create</code> or <code>--recursive</code> is
provided.</p>
<p>If <code>--recursive</code> 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 <code>--dry-run</code>
or the <code>--interactive</code> flag.</p>
<p>If <code>--timestamp</code> is used then sets the modification time
to that time instead of the current time. Times may be specified as one
of:</p>
<ul>
<li>‘YYMMDD’ - e.g. 17.10.30</li>
<li>‘YYYY-MM-DDTHH:MM:SS’ - e.g. 2006-01-02T15:04:05</li>
<li>‘YYYY-MM-DDTHH:MM:SS.SSS’ - e.g. 2006-01-02T15:04:05.123456789</li>
</ul>
<p>Note that value of <code>--timestamp</code> is in UTC. If you want
local time then add the <code>--localtime</code> flag.</p>
<pre><code>rclone touch remote:path [flags]</code></pre>
<h2 id="options-83">Options</h2>
<pre><code> -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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-83">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h1 id="rclone-tree">rclone tree</h1>
<p>List the contents of the remote in a tree like fashion.</p>
<h2 id="synopsis-72">Synopsis</h2>
<p>rclone tree lists the contents of a remote in a similar way to the
unix tree command.</p>
<p>For example</p>
<pre><code>$ rclone tree remote:path
/
├── file1
├── file2
├── file3
└── subdir
├── file4
└── file5
1 directories, 5 files</code></pre>
<p>You can use any of the filtering options with the tree command (e.g.
<code>--include</code> and <code>--exclude</code>. You can also use
<code>--fast-list</code>.</p>
<p>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 <code>--size</code>. Note that not all of them have short
options as they conflict with rclone’s short options.</p>
<p>For a more interactive navigation of the remote see the <a
href="https://rclone.org/commands/rclone_ncdu/">ncdu</a> command.</p>
<pre><code>rclone tree remote:path [flags]</code></pre>
<h2 id="options-84">Options</h2>
<pre><code> -a, --all All files are listed (list . files too)
-C, --color Turn colorization on always
-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</code></pre>
<p>See the <a href="https://rclone.org/flags/">global flags page</a> for
global options not listed here.</p>
<h2 id="see-also-84">SEE ALSO</h2>
<ul>
<li><a href="https://rclone.org/commands/rclone/">rclone</a> - Show help
for rclone commands, flags and backends.</li>
</ul>
<h2 id="copying-single-files">Copying single files</h2>
<p>rclone normally syncs or copies directories. However, if the source
remote points to a file, rclone will just copy that file. The
destination remote must point to a directory - rclone will give the
error
<code>Failed to create file system for "remote:file": is a file not a directory</code>
if it isn’t.</p>
<p>For example, suppose you have a remote with a file in called
<code>test.jpg</code>, then you could copy just that file like this</p>
<pre><code>rclone copy remote:test.jpg /tmp/download</code></pre>
<p>The file <code>test.jpg</code> will be placed inside
<code>/tmp/download</code>.</p>
<p>This is equivalent to specifying</p>
<pre><code>rclone copy --files-from /tmp/files remote: /tmp/download</code></pre>
<p>Where <code>/tmp/files</code> contains the single line</p>
<pre><code>test.jpg</code></pre>
<p>It is recommended to use <code>copy</code> when copying individual
files, not <code>sync</code>. They have pretty much the same effect but
<code>copy</code> will use a lot less memory.</p>
<h2 id="syntax-of-remote-paths">Syntax of remote paths</h2>
<p>The syntax of the paths passed to the rclone command are as
follows.</p>
<h3 id="pathtodir">/path/to/dir</h3>
<p>This refers to the local file system.</p>
<p>On Windows <code>\</code> may be used instead of <code>/</code> in
local paths <strong>only</strong>, non local paths must use
<code>/</code>. See <a
href="https://rclone.org/local/#paths-on-windows">local filesystem</a>
documentation for more about Windows-specific paths.</p>
<p>These paths needn’t start with a leading <code>/</code> - if they
don’t then they will be relative to the current directory.</p>
<h3 id="remotepathtodir">remote:path/to/dir</h3>
<p>This refers to a directory <code>path/to/dir</code> on
<code>remote:</code> as defined in the config file (configured with
<code>rclone config</code>).</p>
<h3 id="remotepathtodir-1">remote:/path/to/dir</h3>
<p>On most backends this is refers to the same directory as
<code>remote:path/to/dir</code> and that format should be preferred. On
a very small number of remotes (FTP, SFTP, Dropbox for business) this
will refer to a different directory. On these, paths without a leading
<code>/</code> will refer to your “home” directory and paths with a
leading <code>/</code> will refer to the root.</p>
<h3 id="backendpathtodir">:backend:path/to/dir</h3>
<p>This is an advanced form for creating remotes on the fly.
<code>backend</code> should be the name or prefix of a backend (the
<code>type</code> in the config file) and all the configuration for the
backend should be provided on the command line (or in environment
variables).</p>
<p>Here are some examples:</p>
<pre><code>rclone lsd --http-url https://pub.rclone.org :http:</code></pre>
<p>To list all the directories in the root of
<code>https://pub.rclone.org/</code>.</p>
<pre><code>rclone lsf --http-url https://example.com :http:path/to/dir</code></pre>
<p>To list files and directories in
<code>https://example.com/path/to/dir/</code></p>
<pre><code>rclone copy --http-url https://example.com :http:path/to/dir /tmp/dir</code></pre>
<p>To copy files and directories in
<code>https://example.com/path/to/dir</code> to
<code>/tmp/dir</code>.</p>
<pre><code>rclone copy --sftp-host example.com :sftp:path/to/dir /tmp/dir</code></pre>
<p>To copy files and directories from <code>example.com</code> in the
relative directory <code>path/to/dir</code> to <code>/tmp/dir</code>
using sftp.</p>
<h3 id="connection-strings">Connection strings</h3>
<p>The above examples can also be written using a connection string
syntax, so instead of providing the arguments as command line parameters
<code>--http-url https://pub.rclone.org</code> they are provided as part
of the remote specification as a kind of connection string.</p>
<pre><code>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</code></pre>
<p>These can apply to modify existing remotes as well as create new
remotes with the on the fly syntax. This example is equivalent to adding
the <code>--drive-shared-with-me</code> parameter to the remote
<code>gdrive:</code>.</p>
<pre><code>rclone lsf "gdrive,shared_with_me:path/to/dir"</code></pre>
<p>The major advantage to using the connection string style syntax is
that it only applies to the remote, not to all the remotes of that type
of the command line. A common confusion is this attempt to copy a file
shared on google drive to the normal drive which <strong>does not
work</strong> because the <code>--drive-shared-with-me</code> flag
applies to both the source and the destination.</p>
<pre><code>rclone copy --drive-shared-with-me gdrive:shared-file.txt gdrive:</code></pre>
<p>However using the connection string syntax, this does work.</p>
<pre><code>rclone copy "gdrive,shared_with_me:shared-file.txt" gdrive:</code></pre>
<p>Note that the connection string only affects the options of the
immediate backend. If for example gdriveCrypt is a crypt based on
gdrive, then the following command <strong>will not work</strong> as
intended, because <code>shared_with_me</code> is ignored by the crypt
backend:</p>
<pre><code>rclone copy "gdriveCrypt,shared_with_me:shared-file.txt" gdriveCrypt:</code></pre>
<p>The connection strings have the following syntax</p>
<pre><code>remote,parameter=value,parameter2=value2:path/to/dir
:backend,parameter=value,parameter2=value2:path/to/dir</code></pre>
<p>If the <code>parameter</code> has a <code>:</code> or <code>,</code>
then it must be placed in quotes <code>"</code> or <code>'</code>,
so</p>
<pre><code>remote,parameter="colon:value",parameter2="comma,value":path/to/dir
:backend,parameter='colon:value',parameter2='comma,value':path/to/dir</code></pre>
<p>If a quoted value needs to include that quote, then it should be
doubled, so</p>
<pre><code>remote,parameter="with""quote",parameter2='with''quote':path/to/dir</code></pre>
<p>This will make <code>parameter</code> be <code>with"quote</code> and
<code>parameter2</code> be <code>with'quote</code>.</p>
<p>If you leave off the <code>=parameter</code> then rclone will
substitute <code>=true</code> which works very well with flags. For
example, to use s3 configured in the environment you could use:</p>
<pre><code>rclone lsd :s3,env_auth:</code></pre>
<p>Which is equivalent to</p>
<pre><code>rclone lsd :s3,env_auth=true:</code></pre>
<p>Note that on the command line you might need to surround these
connection strings with <code>"</code> or <code>'</code> to stop the
shell interpreting any special characters within them.</p>
<p>If you are a shell master then you’ll know which strings are OK and
which aren’t, but if you aren’t sure then enclose them in <code>"</code>
and use <code>'</code> as the inside quote. This syntax works on all
OSes.</p>
<pre><code>rclone copy ":http,url='https://example.com':path/to/dir" /tmp/dir</code></pre>
<p>On Linux/macOS some characters are still interpreted inside
<code>"</code> strings in the shell (notably <code>\</code> and
<code>$</code> and <code>"</code>) so if your strings contain those you
can swap the roles of <code>"</code> and <code>'</code> thus. (This
syntax does not work on Windows.)</p>
<pre><code>rclone copy ':http,url="https://example.com":path/to/dir' /tmp/dir</code></pre>
<h4 id="connection-strings-config-and-logging">Connection strings,
config and logging</h4>
<p>If you supply extra configuration to a backend by command line flag,
environment variable or connection string then rclone will add a suffix
based on the hash of the config to the name of the remote, eg</p>
<pre><code>rclone -vv lsf --s3-chunk-size 20M s3:</code></pre>
<p>Has the log message</p>
<pre><code>DEBUG : s3: detected overridden config - adding "{Srj1p}" suffix to name</code></pre>
<p>This is so rclone can tell the modified remote apart from the
unmodified remote when caching the backends.</p>
<p>This should only be noticeable in the logs.</p>
<p>This means that on the fly backends such as</p>
<pre><code>rclone -vv lsf :s3,env_auth:</code></pre>
<p>Will get their own names</p>
<pre><code>DEBUG : :s3: detected overridden config - adding "{YTu53}" suffix to name</code></pre>
<h3 id="valid-remote-names">Valid remote names</h3>
<p>Remote names are case sensitive, and must adhere to the following
rules: - May only contain <code>0</code>-<code>9</code>,
<code>A</code>-<code>Z</code>, <code>a</code>-<code>z</code>,
<code>_</code>, <code>-</code>, <code>.</code> and space. - May not
start with <code>-</code> or space.</p>
<h2 id="quoting-and-the-shell">Quoting and the shell</h2>
<p>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.</p>
<p>Here are some gotchas which may help users unfamiliar with the shell
rules</p>
<h3 id="linux-osx">Linux / OSX</h3>
<p>If your names have spaces or shell metacharacters
(e.g. <code>*</code>, <code>?</code>, <code>$</code>, <code>'</code>,
<code>"</code>, etc.) then you must quote them. Use single quotes
<code>'</code> by default.</p>
<pre><code>rclone copy 'Important files?' remote:backup</code></pre>
<p>If you want to send a <code>'</code> you will need to use
<code>"</code>, e.g.</p>
<pre><code>rclone copy "O'Reilly Reviews" remote:backup</code></pre>
<p>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.</p>
<h3 id="windows">Windows</h3>
<p>If your names have spaces in you need to put them in <code>"</code>,
e.g.</p>
<pre><code>rclone copy "E:\folder name\folder name\folder name" remote:backup</code></pre>
<p>If you are using the root directory on its own then don’t quote it
(see <a href="https://github.com/rclone/rclone/issues/464">#464</a> for
why), e.g.</p>
<pre><code>rclone copy E:\ remote:backup</code></pre>
<h2 id="copying-files-or-directories-with-in-the-names">Copying files or
directories with <code>:</code> in the names</h2>
<p>rclone uses <code>:</code> 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 <code>:</code> up to the first <code>/</code> so
if you need to act on a file or directory like this then use the full
path starting with a <code>/</code>, or use <code>./</code> as a current
directory prefix.</p>
<p>So to sync a directory called <code>sync:me</code> to a remote called
<code>remote:</code> use</p>
<pre><code>rclone sync -i ./sync:me remote:path</code></pre>
<p>or</p>
<pre><code>rclone sync -i /full/path/to/sync:me remote:path</code></pre>
<h2 id="server-side-copy">Server Side Copy</h2>
<p>Most remotes (but not all - see <a
href="https://rclone.org/overview/#optional-features">the overview</a>)
support server-side copy.</p>
<p>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.</p>
<p>Eg</p>
<pre><code>rclone copy s3:oldbucket s3:newbucket</code></pre>
<p>Will copy the contents of <code>oldbucket</code> to
<code>newbucket</code> without downloading and re-uploading.</p>
<p>Remotes which don’t support server-side copy <strong>will</strong>
download and re-upload in this case.</p>
<p>Server side copies are used with <code>sync</code> and
<code>copy</code> and will be identified in the log when using the
<code>-v</code> flag. The <code>move</code> 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.</p>
<p>Server side copies will only be attempted if the remote names are the
same.</p>
<p>This can be used when scripting to make aged backups efficiently,
e.g.</p>
<pre><code>rclone sync -i remote:current-backup remote:previous-backup
rclone sync -i /path/to/files remote:current-backup</code></pre>
<h2 id="metadata">Metadata support</h2>
<p>Metadata is data about a file which isn’t the contents of the file.
Normally rclone only preserves the modification time and the content
(MIME) type where possible.</p>
<p>Rclone supports preserving all the available metadata on files (not
directories) when using the <code>--metadata</code> or <code>-M</code>
flag.</p>
<p>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 <a
href="https://rclone.org/overview/#features">features table</a> (Eg <a
href="https://rclone.org/local/#metadata">local</a>, <a
href="/s3/#metadata">s3</a>)</p>
<p>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 <code>Content-Type</code>
without the <code>--metadata</code> flag.</p>
<p>Using <code>--metadata</code> when syncing from local to local will
preserve file attributes such as file mode, owner, extended attributes
(not Windows).</p>
<p>Note that arbitrary metadata may be added to objects using the
<code>--metadata-set key=value</code> flag when the object is first
uploaded. This flag can be repeated as many times as necessary.</p>
<h3 id="types-of-metadata">Types of metadata</h3>
<p>Metadata is divided into two type. System metadata and User
metadata.</p>
<p>Metadata which the backend uses itself is called system metadata. For
example on the local backend the system metadata <code>uid</code> will
store the user ID of the file when used on a unix based platform.</p>
<p>Arbitrary metadata is called user metadata and this can be set
however is desired.</p>
<p>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
<code>content-type</code> metadata. In a backend which understands this
(like <code>azureblob</code>) this will become the Content-Type of the
object. In a backend which doesn’t understand this (like the
<code>local</code> backend) this will become user metadata. However
should the local object be copied back to s3, the Content-Type will be
set correctly.</p>
<h3 id="metadata-framework">Metadata framework</h3>
<p>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.</p>
<p>This metadata is stored as a dictionary with string keys and string
values.</p>
<p>There are some limits on the names of the keys (these may be
clarified further in the future).</p>
<ul>
<li>must be lower case</li>
<li>may be <code>a-z</code> <code>0-9</code> containing <code>.</code>
<code>-</code> or <code>_</code></li>
<li>length is backend dependent</li>
</ul>
<p>Each backend can provide system metadata that it understands. Some
backends can also store arbitrary user metadata.</p>
<p>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.</p>
<p>Some backends have limits on the size of the metadata and rclone will
give errors on upload if they are exceeded.</p>
<h3 id="metadata-preservation">Metadata preservation</h3>
<p>The goal of the implementation is to</p>
<ol type="1">
<li>Preserve metadata if at all possible</li>
<li>Interpret metadata if at all possible</li>
</ol>
<p>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.</p>
<p>The consequence of 2 is that you can copy an S3 object with metadata
to Azureblob (say) and have the metadata appear on the Azureblob object
also.</p>
<h3 id="standard-system-metadata">Standard system metadata</h3>
<p>Here is a table of standard system metadata which, if appropriate, a
backend may implement.</p>
<table>
<colgroup>
<col style="width: 48%" />
<col style="width: 30%" />
<col style="width: 20%" />
</colgroup>
<thead>
<tr class="header">
<th>key</th>
<th>description</th>
<th>example</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>mode</td>
<td>File type and mode: octal, unix style</td>
<td>0100664</td>
</tr>
<tr class="even">
<td>uid</td>
<td>User ID of owner: decimal number</td>
<td>500</td>
</tr>
<tr class="odd">
<td>gid</td>
<td>Group ID of owner: decimal number</td>
<td>500</td>
</tr>
<tr class="even">
<td>rdev</td>
<td>Device ID (if special file) => hexadecimal</td>
<td>0</td>
</tr>
<tr class="odd">
<td>atime</td>
<td>Time of last access: RFC 3339</td>
<td>2006-01-02T15:04:05.999999999Z07:00</td>
</tr>
<tr class="even">
<td>mtime</td>
<td>Time of last modification: RFC 3339</td>
<td>2006-01-02T15:04:05.999999999Z07:00</td>
</tr>
<tr class="odd">
<td>btime</td>
<td>Time of file creation (birth): RFC 3339</td>
<td>2006-01-02T15:04:05.999999999Z07:00</td>
</tr>
<tr class="even">
<td>cache-control</td>
<td>Cache-Control header</td>
<td>no-cache</td>
</tr>
<tr class="odd">
<td>content-disposition</td>
<td>Content-Disposition header</td>
<td>inline</td>
</tr>
<tr class="even">
<td>content-encoding</td>
<td>Content-Encoding header</td>
<td>gzip</td>
</tr>
<tr class="odd">
<td>content-language</td>
<td>Content-Language header</td>
<td>en-US</td>
</tr>
<tr class="even">
<td>content-type</td>
<td>Content-Type header</td>
<td>text/plain</td>
</tr>
</tbody>
</table>
<p>The metadata keys <code>mtime</code> and <code>content-type</code>
will take precedence if supplied in the metadata over reading the
<code>Content-Type</code> or modification time of the source object.</p>
<p>Hashes are not included in system metadata as there is a well defined
way of reading those already.</p>
<h2 id="options-85">Options</h2>
<p>Rclone has a number of options to control its behaviour.</p>
<p>Options that take parameters can have the values passed in two ways,
<code>--option=value</code> or <code>--option value</code>. However
boolean (true/false) options behave slightly differently to the other
options in that <code>--boolean</code> sets the option to
<code>true</code> and the absence of the flag sets it to
<code>false</code>. It is also possible to specify
<code>--boolean=false</code> or <code>--boolean=true</code>. Note that
<code>--boolean false</code> is not valid - this is parsed as
<code>--boolean</code> and the <code>false</code> is parsed as an extra
command line argument for rclone.</p>
<h3 id="time-option">Time or duration options</h3>
<p>TIME or DURATION options can be specified as a duration string or a
time string.</p>
<p>A duration string is a possibly signed sequence of decimal numbers,
each with optional fraction and a unit suffix, such as “300ms”, “-1.5h”
or “2h45m”. Default units are seconds or the following abbreviations are
valid:</p>
<ul>
<li><code>ms</code> - Milliseconds</li>
<li><code>s</code> - Seconds</li>
<li><code>m</code> - Minutes</li>
<li><code>h</code> - Hours</li>
<li><code>d</code> - Days</li>
<li><code>w</code> - Weeks</li>
<li><code>M</code> - Months</li>
<li><code>y</code> - Years</li>
</ul>
<p>These can also be specified as an absolute time in the following
formats:</p>
<ul>
<li>RFC3339 - e.g. <code>2006-01-02T15:04:05Z</code> or
<code>2006-01-02T15:04:05+07:00</code></li>
<li>ISO8601 Date and time, local timezone -
<code>2006-01-02T15:04:05</code></li>
<li>ISO8601 Date and time, local timezone -
<code>2006-01-02 15:04:05</code></li>
<li>ISO8601 Date - <code>2006-01-02</code> (YYYY-MM-DD)</li>
</ul>
<h3 id="size-option">Size options</h3>
<p>Options which use SIZE use KiB (multiples of 1024 bytes) by default.
However, a suffix of <code>B</code> for Byte, <code>K</code> for KiB,
<code>M</code> for MiB, <code>G</code> for GiB, <code>T</code> for TiB
and <code>P</code> for PiB may be used. These are the binary units,
e.g. 1, 2**10, 2**20, 2**30 respectively.</p>
<h3 id="backup-dirdir">–backup-dir=DIR</h3>
<p>When using <code>sync</code>, <code>copy</code> or <code>move</code>
any files which would have been overwritten or deleted are moved in
their original hierarchy into this directory.</p>
<p>If <code>--suffix</code> 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 DIR, then it will be overwritten.</p>
<p>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.</p>
<p>For example</p>
<pre><code>rclone sync -i /path/to/local remote:current --backup-dir remote:old</code></pre>
<p>will sync <code>/path/to/local</code> to <code>remote:current</code>,
but for any files which would have been updated or deleted will be
stored in <code>remote:old</code>.</p>
<p>If running rclone from a script you might want to use today’s date as
the directory name passed to <code>--backup-dir</code> to store the old
files, or you might want to pass <code>--suffix</code> with today’s
date.</p>
<p>See <code>--compare-dest</code> and <code>--copy-dest</code>.</p>
<h3 id="bind-string">–bind string</h3>
<p>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.</p>
<h3 id="bwlimitbandwidth_spec">–bwlimit=BANDWIDTH_SPEC</h3>
<p>This option controls the bandwidth limit. For example</p>
<pre><code>--bwlimit 10M</code></pre>
<p>would mean limit the upload and download bandwidth to 10 MiB/s.
<strong>NB</strong> this is <strong>bytes</strong> per second not
<strong>bits</strong> 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
<code>0</code> which means to not limit bandwidth.</p>
<p>The upload and download bandwidth can be specified separately, as
<code>--bwlimit UP:DOWN</code>, so</p>
<pre><code>--bwlimit 10M:100k</code></pre>
<p>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</p>
<pre><code>--bwlimit 10M:off</code></pre>
<p>this would limit the upload bandwidth to 10 MiB/s but the download
bandwidth would be unlimited.</p>
<p>When specified as above the bandwidth limits last for the duration of
run of the rclone binary.</p>
<p>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
<code>WEEKDAY-HH:MM,BANDWIDTH WEEKDAY-HH:MM,BANDWIDTH...</code> where:
<code>WEEKDAY</code> is optional element.</p>
<ul>
<li><code>BANDWIDTH</code> can be a single number, e.g.<code>100k</code>
or a pair of numbers for upload:download, e.g.<code>10M:1M</code>.</li>
<li><code>WEEKDAY</code> can be written as the whole word or only using
the first 3 characters. It is optional.</li>
<li><code>HH:MM</code> is an hour from 00:00 to 23:59.</li>
</ul>
<p>An example of a typical timetable to avoid link saturation during
daytime working hours could be:</p>
<p><code>--bwlimit "08:00,512k 12:00,10M 13:00,512k 18:00,30M 23:00,off"</code></p>
<p>In this example, 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.</p>
<p>An example of timetable with <code>WEEKDAY</code> could be:</p>
<p><code>--bwlimit "Mon-00:00,512 Fri-23:59,10M Sat-10:00,1M Sun-20:00,off"</code></p>
<p>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.</p>
<p>Timeslots without <code>WEEKDAY</code> are extended to the whole
week. So this example:</p>
<p><code>--bwlimit "Mon-00:00,512 12:00,1M Sun-20:00,off"</code></p>
<p>Is equivalent to this:</p>
<p><code>--bwlimit "Mon-00:00,512Mon-12:00,1M Tue-12:00,1M Wed-12:00,1M Thu-12:00,1M Fri-12:00,1M Sat-12:00,1M Sun-12:00,1M Sun-20:00,off"</code></p>
<p>Bandwidth limit apply to the data transfer for all backends. For most
backends the directory listing bandwidth is also included (exceptions
being the non HTTP backends, <code>ftp</code>, <code>sftp</code> and
<code>storj</code>).</p>
<p>Note that the units are <strong>Byte/s</strong>, not
<strong>bit/s</strong>. Typically connections are measured in bit/s - to
convert divide by 8. For example, let’s say you have a 10 Mbit/s
connection and you wish rclone to use half of it - 5 Mbit/s. This is 5/8
= 0.625 MiB/s so you would use a <code>--bwlimit 0.625M</code> parameter
for rclone.</p>
<p>On Unix systems (Linux, macOS, …) the bandwidth limiter can be
toggled by sending a <code>SIGUSR2</code> signal to rclone. This allows
to remove the limitations of a long running rclone transfer and to
restore it back to the value specified with <code>--bwlimit</code>
quickly when needed. Assuming there is only one rclone instance running,
you can toggle the limiter like this:</p>
<pre><code>kill -SIGUSR2 $(pidof rclone)</code></pre>
<p>If you configure rclone with a <a href="/rc">remote control</a> then
you can use change the bwlimit dynamically:</p>
<pre><code>rclone rc core/bwlimit rate=1M</code></pre>
<h3 id="bwlimit-filebandwidth_spec">–bwlimit-file=BANDWIDTH_SPEC</h3>
<p>This option controls per file bandwidth limit. For the options see
the <code>--bwlimit</code> flag.</p>
<p>For example use this to allow no transfers to be faster than 1
MiB/s</p>
<pre><code>--bwlimit-file 1M</code></pre>
<p>This can be used in conjunction with <code>--bwlimit</code>.</p>
<p>Note that if a schedule is provided the file will use the schedule in
effect at the start of the transfer.</p>
<h3 id="buffer-sizesize">–buffer-size=SIZE</h3>
<p>Use this sized buffer to speed up file transfers. Each
<code>--transfer</code> will use this much memory for buffering.</p>
<p>When using <code>mount</code> or <code>cmount</code> each open file
descriptor will use this much memory for buffering. See the <a
href="https://rclone.org/commands/rclone_mount/#file-buffering">mount</a>
documentation for more details.</p>
<p>Set to <code>0</code> to disable the buffering for the minimum memory
usage.</p>
<p>Note that the memory allocation of the buffers is influenced by the
<a href="#use-mmap">–use-mmap</a> flag.</p>
<h3 id="cache-dirdir">–cache-dir=DIR</h3>
<p>Specify the directory rclone will use for caching, to override the
default.</p>
<p>Default value is depending on operating system: - Windows
<code>%LocalAppData%\rclone</code>, if <code>LocalAppData</code> is
defined. - macOS <code>$HOME/Library/Caches/rclone</code> if
<code>HOME</code> is defined. - Unix <code>$XDG_CACHE_HOME/rclone</code>
if <code>XDG_CACHE_HOME</code> is defined, else
<code>$HOME/.cache/rclone</code> if <code>HOME</code> is defined. -
Fallback (on all OS) to <code>$TMPDIR/rclone</code>, where
<code>TMPDIR</code> is the value from <a
href="#temp-dir-dir">–temp-dir</a>.</p>
<p>You can use the <a
href="https://rclone.org/commands/rclone_config_paths/">config paths</a>
command to see the current value.</p>
<p>Cache directory is heavily used by the <a
href="https://rclone.org/commands/rclone_mount/#vfs-file-caching">VFS
File Caching</a> mount feature, but also by <a
href="https://rclone.org/commands/rclone_serve/">serve</a>, <a
href="/gui">GUI</a> and other parts of rclone.</p>
<h3 id="check-first">–check-first</h3>
<p>If this flag is set then in a <code>sync</code>, <code>copy</code> or
<code>move</code>, rclone will do all the checks to see whether files
need to be transferred before doing any of the transfers. Normally
rclone would start running transfers as soon as possible.</p>
<p>This flag can be useful on IO limited systems where transfers
interfere with checking.</p>
<p>It can also be useful to ensure perfect ordering when using
<code>--order-by</code>.</p>
<p>Using this flag can use more memory as it effectively sets
<code>--max-backlog</code> to infinite. This means that all the info on
the objects to transfer is held in memory before the transfers
start.</p>
<h3 id="checkersn">–checkers=N</h3>
<p>Originally controlling just the number of file checkers to run in
parallel, e.g. by <code>rclone copy</code>. Now a fairly universal
parallelism control used by <code>rclone</code> in several places.</p>
<p>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 are run in parallel.</p>
<p>The default is to run 8 checkers in parallel. However, in case of
slow-reacting backends you may need to lower (rather than increase) this
default by setting <code>--checkers</code> to 4 or less threads. This is
especially advised if you are experiencing backend server crashes during
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.</p>
<h3 id="c-checksum">-c, –checksum</h3>
<p>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 the
file hash and size to determine if files are equal.</p>
<p>This is useful when the remote doesn’t support setting modified time
and a more accurate sync is desired than just checking the file
size.</p>
<p>This is very useful when transferring between remotes which store the
same hash type on the object, e.g. Drive and Swift. For details of which
remotes support which hash type see the table in the <a
href="https://rclone.org/overview/">overview section</a>.</p>
<p>Eg <code>rclone --checksum sync s3:/bucket swift:/bucket</code> would
run much quicker than without the <code>--checksum</code> flag.</p>
<p>When using this flag, rclone won’t update mtimes of remote files if
they are incorrect as it would normally.</p>
<h3 id="compare-destdir">–compare-dest=DIR</h3>
<p>When using <code>sync</code>, <code>copy</code> or <code>move</code>
DIR is checked in addition to the destination for files. If a file
identical to the source is found that file is NOT copied from source.
This is useful to copy just files that have changed since the last
backup.</p>
<p>You must use the same remote as the destination of the sync. The
compare directory must not overlap the destination directory.</p>
<p>See <code>--copy-dest</code> and <code>--backup-dir</code>.</p>
<h3 id="configconfig_file">–config=CONFIG_FILE</h3>
<p>Specify the location of the rclone configuration file, to override
the default. E.g. <code>rclone config --config="rclone.conf"</code>.</p>
<p>The exact default is a bit complex to describe, due to changes
introduced through different versions of rclone while preserving
backwards compatibility, but in most cases it is as simple as:</p>
<ul>
<li><code>%APPDATA%/rclone/rclone.conf</code> on Windows</li>
<li><code>~/.config/rclone/rclone.conf</code> on other</li>
</ul>
<p>The complete logic is as follows: Rclone will look for an existing
configuration file in any of the following locations, in priority
order:</p>
<ol type="1">
<li><code>rclone.conf</code> (in program directory, where rclone
executable is)</li>
<li><code>%APPDATA%/rclone/rclone.conf</code> (only on Windows)</li>
<li><code>$XDG_CONFIG_HOME/rclone/rclone.conf</code> (on all systems,
including Windows)</li>
<li><code>~/.config/rclone/rclone.conf</code> (see below for explanation
of ~ symbol)</li>
<li><code>~/.rclone.conf</code></li>
</ol>
<p>If no existing configuration file is found, then a new one will be
created in the following location:</p>
<ul>
<li>On Windows: Location 2 listed above, except in the unlikely event
that <code>APPDATA</code> is not defined, then location 4 is used
instead.</li>
<li>On Unix: Location 3 if <code>XDG_CONFIG_HOME</code> is defined, else
location 4.</li>
<li>Fallback to location 5 (on all OS), when the rclone directory cannot
be created, but if also a home directory was not found then path
<code>.rclone.conf</code> relative to current working directory will be
used as a final resort.</li>
</ul>
<p>The <code>~</code> symbol in paths above represent the home directory
of the current user on any OS, and the value is defined as
following:</p>
<ul>
<li>On Windows: <code>%HOME%</code> if defined, else
<code>%USERPROFILE%</code>, or else
<code>%HOMEDRIVE%\%HOMEPATH%</code>.</li>
<li>On Unix: <code>$HOME</code> if defined, else by looking up current
user in OS-specific user database (e.g. passwd file), or else use the
result from shell command <code>cd && pwd</code>.</li>
</ul>
<p>If you run <code>rclone config file</code> you will see where the
default location is for you.</p>
<p>The fact that an existing file <code>rclone.conf</code> in the same
directory as the rclone executable is always preferred, means that it is
easy to run in “portable” mode by downloading rclone executable to a
writable directory and then create an empty file
<code>rclone.conf</code> in the same directory.</p>
<p>If the location is set to empty string <code>""</code> or path to a
file with name <code>notfound</code>, or the os null device represented
by value <code>NUL</code> on Windows and <code>/dev/null</code> on Unix
systems, then rclone will keep the config file in memory only.</p>
<p>The file format is basic <a
href="https://en.wikipedia.org/wiki/INI_file#Format">INI</a>: Sections
of text, led by a <code>[section]</code> header and followed by
<code>key=value</code> 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 the <code>key=value</code>
entries, where the key is the option name without the
<code>--backend-</code> prefix, in lowercase and with <code>_</code>
instead of <code>-</code>. E.g. option <code>--mega-hard-delete</code>
corresponds to key <code>hard_delete</code>. Only backend options can be
specified. A special, and required, key <code>type</code> identifies the
<a href="https://rclone.org/overview/">storage system</a>, where the
value is the internal lowercase name as returned by command
<code>rclone help backends</code>. Comments are indicated by
<code>;</code> or <code>#</code> at the beginning of a line.</p>
<p>Example:</p>
<pre><code>[megaremote]
type = mega
user = you@example.com
pass = PDPcQVVjVtzFY-GTdDFozqBhTdsPg3qH</code></pre>
<p>Note that passwords are in <a
href="https://rclone.org/commands/rclone_obscure/">obscured</a> form.
Also, many storage systems uses token-based authentication instead of
passwords, and this requires additional steps. It is easier, and safer,
to use the interactive command <code>rclone config</code> instead of
manually editing the configuration file.</p>
<p>The configuration file will typically contain login information, and
should therefore have restricted permissions so that only the current
user can read it. Rclone tries to ensure this when it writes the file.
You may also choose to <a href="#configuration-encryption">encrypt</a>
the file.</p>
<p>When token-based authentication are used, the configuration file must
be writable, because rclone needs to update the tokens inside it.</p>
<h3 id="contimeouttime">–contimeout=TIME</h3>
<p>Set the connection timeout. This should be in go time format which
looks like <code>5s</code> for 5 seconds, <code>10m</code> for 10
minutes, or <code>3h30m</code>.</p>
<p>The connection timeout is the amount of time rclone will wait for a
connection to go through to a remote object storage system. It is
<code>1m</code> by default.</p>
<h3 id="copy-destdir">–copy-dest=DIR</h3>
<p>When using <code>sync</code>, <code>copy</code> or <code>move</code>
DIR is checked in addition to the destination for files. If a file
identical to the source is found that file is server-side copied from
DIR to the destination. This is useful for incremental backup.</p>
<p>The remote in use must support server-side copy and you must use the
same remote as the destination of the sync. The compare directory must
not overlap the destination directory.</p>
<p>See <code>--compare-dest</code> and <code>--backup-dir</code>.</p>
<h3 id="dedupe-mode-mode">–dedupe-mode MODE</h3>
<p>Mode to run dedupe command in. One of <code>interactive</code>,
<code>skip</code>, <code>first</code>, <code>newest</code>,
<code>oldest</code>, <code>rename</code>. The default is
<code>interactive</code>.<br />
See the dedupe command for more information as to what these options
mean.</p>
<h3 id="disable-featurefeature">–disable FEATURE,FEATURE,…</h3>
<p>This disables a comma separated list of optional features. For
example to disable server-side move and server-side copy use:</p>
<pre><code>--disable move,copy</code></pre>
<p>The features can be put in any case.</p>
<p>To see a list of which features can be disabled use:</p>
<pre><code>--disable help</code></pre>
<p>See the overview <a
href="https://rclone.org/overview/#features">features</a> and <a
href="https://rclone.org/overview/#optional-features">optional
features</a> to get an idea of which feature does what.</p>
<p>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).</p>
<h3 id="disable-http2">–disable-http2</h3>
<p>This stops rclone from trying to use HTTP/2 if available. This can
sometimes speed up transfers due to a <a
href="https://github.com/golang/go/issues/37373">problem in the Go
standard library</a>.</p>
<h3 id="dscp-value">–dscp VALUE</h3>
<p>Specify a DSCP value or name to use in connections. This could help
QoS system to identify traffic class. BE, EF, DF, LE, CSx and AFxx are
allowed.</p>
<p>See the description of <a
href="https://en.wikipedia.org/wiki/Differentiated_services">differentiated
services</a> 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 (<a
href="https://tools.ietf.org/html/rfc8622">RFC 8622</a>).</p>
<p>For example, if you configured QoS on router to handle LE properly.
Running:</p>
<pre><code>rclone copy --dscp LE from:/from to:/to</code></pre>
<p>would make the priority lower than usual internet flows.</p>
<p>This option has no effect on Windows (see <a
href="https://github.com/golang/go/issues/42728">golang/go#42728</a>).</p>
<h3 id="n-dry-run">-n, –dry-run</h3>
<p>Do a trial run with no permanent changes. Use this to see what rclone
would do without actually doing it. Useful when setting up the
<code>sync</code> command which deletes files in the destination.</p>
<h3 id="expect-continue-timeouttime">–expect-continue-timeout=TIME</h3>
<p>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.</p>
<p>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.</p>
<p>The default is <code>1s</code>. Set to <code>0</code> to disable.</p>
<h3 id="error-on-no-transfer">–error-on-no-transfer</h3>
<p>By default, rclone will exit with return code 0 if there were no
errors.</p>
<p>This option allows rclone to return exit code 9 if no files were
transferred between the source and destination. This allows using rclone
in scripts, and triggering follow-on actions if data was copied, or
skipping if not.</p>
<p>NB: Enabling this option turns a usually non-fatal error into a
potentially fatal one - please check and adjust your scripts
accordingly!</p>
<h3
id="fs-cache-expire-durationtime">–fs-cache-expire-duration=TIME</h3>
<p>When using rclone via the API rclone caches created remotes for 5
minutes by default in the “fs cache”. This means that if you do repeated
actions on the same remote then rclone won’t have to build it again from
scratch, which makes it more efficient.</p>
<p>This flag sets the time that the remotes are cached for. If you set
it to <code>0</code> (or negative) then rclone won’t cache the remotes
at all.</p>
<p>Note that if you use some flags, eg <code>--backup-dir</code> and if
this is set to <code>0</code> rclone may build two remotes (one for the
source or destination and one for the <code>--backup-dir</code> where it
may have only built one before.</p>
<h3
id="fs-cache-expire-intervaltime">–fs-cache-expire-interval=TIME</h3>
<p>This controls how often rclone checks for cached remotes to expire.
See the <code>--fs-cache-expire-duration</code> documentation above for
more info. The default is 60s, set to 0 to disable expiry.</p>
<h3 id="header">–header</h3>
<p>Add an HTTP header for all transactions. The flag can be repeated to
add multiple headers.</p>
<p>If you want to add headers only for uploads use
<code>--header-upload</code> and if you want to add headers only for
downloads use <code>--header-download</code>.</p>
<p>This flag is supported for all HTTP based backends even those not
supported by <code>--header-upload</code> and
<code>--header-download</code> so may be used as a workaround for those
with care.</p>
<pre><code>rclone ls remote:test --header "X-Rclone: Foo" --header "X-LetMeIn: Yes"</code></pre>
<h3 id="header-download">–header-download</h3>
<p>Add an HTTP header for all download transactions. The flag can be
repeated to add multiple headers.</p>
<pre><code>rclone sync -i s3:test/src ~/dst --header-download "X-Amz-Meta-Test: Foo" --header-download "X-Amz-Meta-Test2: Bar"</code></pre>
<p>See the GitHub issue <a
href="https://github.com/rclone/rclone/issues/59">here</a> for currently
supported backends.</p>
<h3 id="header-upload">–header-upload</h3>
<p>Add an HTTP header for all upload transactions. The flag can be
repeated to add multiple headers.</p>
<pre><code>rclone sync -i ~/src s3:test/dst --header-upload "Content-Disposition: attachment; filename='cool.html'" --header-upload "X-Amz-Meta-Test: FooBar"</code></pre>
<p>See the GitHub issue <a
href="https://github.com/rclone/rclone/issues/59">here</a> for currently
supported backends.</p>
<h3 id="human-readable">–human-readable</h3>
<p>Rclone commands output values for sizes (e.g. number of bytes) and
counts (e.g. number of files) either as <em>raw</em> numbers, or in
<em>human-readable</em> format.</p>
<p>In human-readable format the values are scaled to larger units,
indicated with a suffix shown after the value, and rounded to three
decimals. Rclone consistently uses binary units (powers of 2) for sizes
and decimal units (powers of 10) for counts. The unit prefix for size is
according to IEC standard notation, e.g. <code>Ki</code> for kibi. Used
with byte unit, <code>1 KiB</code> means 1024 Byte. In list type of
output, only the unit prefix appended to the value
(e.g. <code>9.762Ki</code>), while in more textual output the full unit
is shown (e.g. <code>9.762 KiB</code>). For counts the SI standard
notation is used, e.g. prefix <code>k</code> for kilo. Used with file
counts, <code>1k</code> means 1000 files.</p>
<p>The various <a href="https://rclone.org/commands/rclone_ls/">list</a>
commands output raw numbers by default. Option
<code>--human-readable</code> will make them output values in
human-readable format instead (with the short unit prefix).</p>
<p>The <a href="https://rclone.org/commands/rclone_about/">about</a>
command outputs human-readable by default, with a command-specific
option <code>--full</code> to output the raw numbers instead.</p>
<p>Command <a href="https://rclone.org/commands/rclone_size/">size</a>
outputs both human-readable and raw numbers in the same output.</p>
<p>The <a href="https://rclone.org/commands/rclone_tree/">tree</a>
command also considers <code>--human-readable</code>, 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. <code>K</code> instead of
<code>Ki</code>. The reason for this is that it relies on an external
library.</p>
<p>The interactive command <a
href="https://rclone.org/commands/rclone_ncdu/">ncdu</a> shows
human-readable by default, and responds to key <code>u</code> for
toggling human-readable format.</p>
<h3 id="ignore-case-sync">–ignore-case-sync</h3>
<p>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.</p>
<h3 id="ignore-checksum">–ignore-checksum</h3>
<p>Normally rclone will check that the checksums of transferred files
match, and give an error “corrupted on transfer” if they don’t.</p>
<p>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.</p>
<h3 id="ignore-existing">–ignore-existing</h3>
<p>Using this option will make rclone unconditionally skip all files
that exist on the destination, no matter the content of these files.</p>
<p>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.</p>
<p>When performing a <code>move</code>/<code>moveto</code> command, this
flag will leave skipped files in the source location unchanged when a
file with the same name exists on the destination.</p>
<h3 id="ignore-size">–ignore-size</h3>
<p>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 <code>--checksum</code> is set then it only
checks the checksum.</p>
<p>It will also cause rclone to skip verifying the sizes are the same
after transfer.</p>
<p>This can be useful for transferring files to and from OneDrive which
occasionally misreports the size of image files (see <a
href="https://github.com/rclone/rclone/issues/399">#399</a> for more
info).</p>
<h3 id="i-ignore-times">-I, –ignore-times</h3>
<p>Using this option will cause rclone to unconditionally upload all
files regardless of the state of files on the destination.</p>
<p>Normally rclone would skip any files that have the same modification
time and are the same size (or have the same checksum if using
<code>--checksum</code>).</p>
<h3 id="immutable">–immutable</h3>
<p>Treat source and destination files as immutable and disallow
modification.</p>
<p>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
<code>Source and destination exist but do not match: immutable file modified</code>.</p>
<p>Note that only commands which transfer files (e.g. <code>sync</code>,
<code>copy</code>, <code>move</code>) are affected by this behavior, and
only modification is disallowed. Files may still be deleted explicitly
(e.g. <code>delete</code>, <code>purge</code>) or implicitly
(e.g. <code>sync</code>, <code>move</code>). Use
<code>copy --immutable</code> if it is desired to avoid deletion as well
as modification.</p>
<p>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.</p>
<h3 id="interactive">-i / –interactive</h3>
<p>This flag can be used to tell rclone that you wish a manual
confirmation before destructive operations.</p>
<p>It is <strong>recommended</strong> that you use this flag while
learning rclone especially with <code>rclone sync</code>.</p>
<p>For example</p>
<pre><code>$ rclone delete -i /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</code></pre>
<p>The options mean</p>
<ul>
<li><code>y</code>: <strong>Yes</strong>, this operation should go
ahead. You can also press Return for this to happen. You’ll be asked
every time unless you choose <code>s</code> or <code>!</code>.</li>
<li><code>n</code>: <strong>No</strong>, do not do this operation.
You’ll be asked every time unless you choose <code>s</code> or
<code>!</code>.</li>
<li><code>s</code>: <strong>Skip</strong> 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.</li>
<li><code>!</code>: <strong>Do all</strong> 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.</li>
<li><code>q</code>: <strong>Quit</strong> rclone now, just in case!</li>
</ul>
<h3 id="leave-root">–leave-root</h3>
<p>During rmdirs it will not remove root directory, even if it’s
empty.</p>
<h3 id="log-filefile">–log-file=FILE</h3>
<p>Log all of rclone’s output to FILE. This is not active by default.
This can be useful for tracking down problems with syncs in combination
with the <code>-v</code> flag. See the <a href="#logging">Logging
section</a> for more info.</p>
<p>If FILE exists then rclone will append to it.</p>
<p>Note that if you are using the <code>logrotate</code> program to
manage rclone’s logs, then you should use the <code>copytruncate</code>
option as rclone doesn’t have a signal to rotate logs.</p>
<h3 id="log-format-list">–log-format LIST</h3>
<p>Comma separated list of log format options. Accepted options are
<code>date</code>, <code>time</code>, <code>microseconds</code>,
<code>pid</code>, <code>longfile</code>, <code>shortfile</code>,
<code>UTC</code>. Any other keywords will be silently ignored.
<code>pid</code> will tag log messages with process identifier which
useful with <code>rclone mount --daemon</code>. Other accepted options
are explained in the <a href="https://pkg.go.dev/log#pkg-constants">go
documentation</a>. The default log format is
“<code>date</code>,<code>time</code>”.</p>
<h3 id="log-level-level">–log-level LEVEL</h3>
<p>This sets the log level for rclone. The default log level is
<code>NOTICE</code>.</p>
<p><code>DEBUG</code> is equivalent to <code>-vv</code>. It outputs lots
of debug info - useful for bug reports and really finding out what
rclone is doing.</p>
<p><code>INFO</code> is equivalent to <code>-v</code>. It outputs
information about each transfer and prints stats once a minute by
default.</p>
<p><code>NOTICE</code> 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.</p>
<p><code>ERROR</code> is equivalent to <code>-q</code>. It only outputs
error messages.</p>
<h3 id="use-json-log">–use-json-log</h3>
<p>This switches the log format to JSON for rclone. The fields of json
log are level, msg, source, time.</p>
<h3 id="low-level-retries-number">–low-level-retries NUMBER</h3>
<p>This controls the number of low level retries rclone does.</p>
<p>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
<code>-v</code> flag.</p>
<p>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
<code>--retries</code> flag) quicker.</p>
<p>Disable low level retries with
<code>--low-level-retries 1</code>.</p>
<h3 id="max-backlogn">–max-backlog=N</h3>
<p>This is the maximum allowable backlog of files in a sync/copy/move
queued for being checked or transferred.</p>
<p>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.</p>
<p>Setting this large allows rclone to calculate how many files are
pending more accurately, give a more accurate estimated finish time and
make <code>--order-by</code> work more accurately.</p>
<p>Setting this small will make rclone more synchronous to the listings
of the remote which may be desirable.</p>
<p>Setting this to a negative number will make the backlog as large as
possible.</p>
<h3 id="max-deleten">–max-delete=N</h3>
<p>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.</p>
<h3 id="max-depthn">–max-depth=N</h3>
<p>This modifies the recursion depth for all the commands except
purge.</p>
<p>So if you do <code>rclone --max-depth 1 ls remote:path</code> you
will see only the files in the top level directory. Using
<code>--max-depth 2</code> means you will see all the files in first two
directory levels and so on.</p>
<p>For historical reasons the <code>lsd</code> command defaults to using
a <code>--max-depth</code> of 1 - you can override this with the command
line flag.</p>
<p>You can use this command to disable recursion (with
<code>--max-depth 1</code>).</p>
<p>Note that if you use this with <code>sync</code> and
<code>--delete-excluded</code> the files not recursed through are
considered excluded and will be deleted on the destination. Test first
with <code>--dry-run</code> if you are not sure what will happen.</p>
<h3 id="max-durationtime">–max-duration=TIME</h3>
<p>Rclone will stop scheduling new transfers when it has run for the
duration specified.</p>
<p>Defaults to off.</p>
<p>When the limit is reached any existing transfers will complete.</p>
<p>Rclone won’t exit with an error if the transfer limit is reached.</p>
<h3 id="max-transfersize">–max-transfer=SIZE</h3>
<p>Rclone will stop transferring when it has reached the size specified.
Defaults to off.</p>
<p>When the limit is reached all transfers will stop immediately.</p>
<p>Rclone will exit with exit code 8 if the transfer limit is
reached.</p>
<h2 id="metadata--m">–metadata / -M</h2>
<p>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 <a href="metadata%20section">#metadata</a> for more
info.</p>
<h3 id="metadata-set-keyvalue">–metadata-set key=value</h3>
<p>Add metadata <code>key</code> = <code>value</code> when uploading.
This can be repeated as many times as required. See the <a
href="metadata%20section">#metadata</a> for more info.</p>
<h3
id="cutoff-modehardsoftcautious">–cutoff-mode=hard|soft|cautious</h3>
<p>This modifies the behavior of <code>--max-transfer</code> Defaults to
<code>--cutoff-mode=hard</code>.</p>
<p>Specifying <code>--cutoff-mode=hard</code> will stop transferring
immediately when Rclone reaches the limit.</p>
<p>Specifying <code>--cutoff-mode=soft</code> will stop starting new
transfers when Rclone reaches the limit.</p>
<p>Specifying <code>--cutoff-mode=cautious</code> will try to prevent
Rclone from reaching the limit.</p>
<h3 id="modify-windowtime">–modify-window=TIME</h3>
<p>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.</p>
<p>The default is <code>1ns</code> unless this is overridden by a
remote. For example OS X only stores modification times to the nearest
second so if you are reading and writing to an OS X filing system this
will be <code>1s</code> by default.</p>
<p>This command line flag allows you to override that computed
default.</p>
<h3 id="multi-thread-cutoffsize">–multi-thread-cutoff=SIZE</h3>
<p>When downloading files to the local backend above this size, rclone
will use multiple threads to download the file (default 250M).</p>
<p>Rclone preallocates the file (using
<code>fallocate(FALLOC_FL_KEEP_SIZE)</code> on unix or
<code>NTSetInformationFile</code> 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.</p>
<p>The number of threads used to download is controlled by
<code>--multi-thread-streams</code>.</p>
<p>Use <code>-vv</code> if you wish to see info about the threads.</p>
<p>This will work with the
<code>sync</code>/<code>copy</code>/<code>move</code> commands and
friends <code>copyto</code>/<code>moveto</code>. Multi thread downloads
will be used with <code>rclone mount</code> and
<code>rclone serve</code> if <code>--vfs-cache-mode</code> is set to
<code>writes</code> or above.</p>
<p><strong>NB</strong> that this <strong>only</strong> works for a local
destination but will work with any source.</p>
<p><strong>NB</strong> that multi thread copies are disabled for local
to local copies as they are faster without unless
<code>--multi-thread-streams</code> is set explicitly.</p>
<p><strong>NB</strong> on Windows using multi-thread downloads will
cause the resulting files to be <a
href="https://en.wikipedia.org/wiki/Sparse_file">sparse</a>. Use
<code>--local-no-sparse</code> to disable sparse files (which may cause
long delays at the start of downloads) or disable multi-thread downloads
with <code>--multi-thread-streams 0</code></p>
<h3 id="multi-thread-streamsn">–multi-thread-streams=N</h3>
<p>When using multi thread downloads (see above
<code>--multi-thread-cutoff</code>) this sets the maximum number of
streams to use. Set to <code>0</code> to disable multi thread downloads
(Default 4).</p>
<p>Exactly how many streams rclone uses for the download depends on the
size of the file. To calculate the number of download streams Rclone
divides the size of the file by the <code>--multi-thread-cutoff</code>
and rounds up, up to the maximum set with
<code>--multi-thread-streams</code>.</p>
<p>So if <code>--multi-thread-cutoff 250M</code> and
<code>--multi-thread-streams 4</code> are in effect (the defaults):</p>
<ul>
<li>0..250 MiB files will be downloaded with 1 stream</li>
<li>250..500 MiB files will be downloaded with 2 streams</li>
<li>500..750 MiB files will be downloaded with 3 streams</li>
<li>750+ MiB files will be downloaded with 4 streams</li>
</ul>
<h3 id="no-check-dest">–no-check-dest</h3>
<p>The <code>--no-check-dest</code> can be used with <code>move</code>
or <code>copy</code> and it causes rclone not to check the destination
at all when copying files.</p>
<p>This means that:</p>
<ul>
<li>the destination is not listed minimising the API calls</li>
<li>files are always transferred</li>
<li>this can cause duplicates on remotes which allow it (e.g. Google
Drive)</li>
<li><code>--retries 1</code> is recommended otherwise you’ll transfer
everything again on a retry</li>
</ul>
<p>This flag is useful to minimise the transactions if you know that
none of the files are on the destination.</p>
<p>This is a specialized flag which should be ignored by most users!</p>
<h3 id="no-gzip-encoding">–no-gzip-encoding</h3>
<p>Don’t set <code>Accept-Encoding: gzip</code>. This means that rclone
won’t ask the server for compressed files automatically. Useful if
you’ve set the server to return files with
<code>Content-Encoding: gzip</code> but you uploaded compressed
files.</p>
<p>There is no need to set this in normal operation, and doing so will
decrease the network transfer efficiency of rclone.</p>
<h3 id="no-traverse">–no-traverse</h3>
<p>The <code>--no-traverse</code> flag controls whether the destination
file system is traversed when using the <code>copy</code> or
<code>move</code> commands. <code>--no-traverse</code> is not compatible
with <code>sync</code> and will be ignored if you supply it with
<code>sync</code>.</p>
<p>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 <code>--no-traverse</code> will stop rclone listing the
destination and save time.</p>
<p>However, if you are copying a large number of files, especially if
you are doing a copy where lots of the files under consideration haven’t
changed and won’t need copying then you shouldn’t use
<code>--no-traverse</code>.</p>
<p>See <a href="https://rclone.org/commands/rclone_copy/">rclone
copy</a> for an example of how to use it.</p>
<h3 id="no-unicode-normalization">–no-unicode-normalization</h3>
<p>Don’t normalize unicode characters in filenames during the sync
routine.</p>
<p>Sometimes, an operating system will store filenames containing
unicode parts in their decomposed form (particularly macOS). Some cloud
storage systems will then recompose the unicode, resulting in duplicate
files if the data is ever copied back to a local filesystem.</p>
<p>Using this flag will disable that functionality, treating each
unicode character as unique. For example, by default é and é will be
normalized into the same character. With
<code>--no-unicode-normalization</code> they will be treated as unique
characters.</p>
<h3 id="no-update-modtime">–no-update-modtime</h3>
<p>When using this flag, rclone won’t update modification times of
remote files if they are incorrect as it would normally.</p>
<p>This can be used if the remote is being synced with another tool also
(e.g. the Google Drive client).</p>
<h3 id="order-by-string">–order-by string</h3>
<p>The <code>--order-by</code> flag controls the order in which files in
the backlog are processed in <code>rclone sync</code>,
<code>rclone copy</code> and <code>rclone move</code>.</p>
<p>The order by string is constructed like this. The first part
describes what aspect is being measured:</p>
<ul>
<li><code>size</code> - order by the size of the files</li>
<li><code>name</code> - order by the full path of the files</li>
<li><code>modtime</code> - order by the modification date of the
files</li>
</ul>
<p>This can have a modifier appended with a comma:</p>
<ul>
<li><code>ascending</code> or <code>asc</code> - order so that the
smallest (or oldest) is processed first</li>
<li><code>descending</code> or <code>desc</code> - order so that the
largest (or newest) is processed first</li>
<li><code>mixed</code> - order so that the smallest is processed first
for some threads and the largest for others</li>
</ul>
<p>If the modifier is <code>mixed</code> then it can have an optional
percentage (which defaults to <code>50</code>),
e.g. <code>size,mixed,25</code> 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 <code>mixed</code> 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.</p>
<p>If no modifier is supplied then the order is
<code>ascending</code>.</p>
<p>For example</p>
<ul>
<li><code>--order-by size,desc</code> - send the largest files
first</li>
<li><code>--order-by modtime,ascending</code> - send the oldest files
first</li>
<li><code>--order-by name</code> - send the files with alphabetically by
path first</li>
</ul>
<p>If the <code>--order-by</code> flag is not supplied or it is supplied
with an empty string then the default ordering will be used which is as
scanned. With <code>--checkers 1</code> this is mostly alphabetical,
however with the default <code>--checkers 8</code> it is somewhat
random.</p>
<h4 id="limitations-1">Limitations</h4>
<p>The <code>--order-by</code> flag does not do a separate pass over the
data. This means that it may transfer some files out of the order
specified if</p>
<ul>
<li>there are no files in the backlog or the source has not been fully
scanned yet</li>
<li>there are more than <a href="#max-backlog-n">–max-backlog</a> files
in the backlog</li>
</ul>
<p>Rclone will do its best to transfer the best file it has so in
practice this should not cause a problem. Think of
<code>--order-by</code> as being more of a best efforts flag rather than
a perfect ordering.</p>
<p>If you want perfect ordering then you will need to specify <a
href="#check-first">–check-first</a> which will find all the files which
need transferring first before transferring any.</p>
<h3 id="password-command-spaceseplist">–password-command
SpaceSepList</h3>
<p>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 <code>RCLONE_CONFIG_PASS</code> variable.</p>
<p>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
<code>"</code>, if you want a literal <code>"</code> in an argument then
enclose the argument in <code>"</code> and double the <code>"</code>.
See <a href="https://godoc.org/encoding/csv">CSV encoding</a> for more
info.</p>
<p>Eg</p>
<pre><code>--password-command echo hello
--password-command echo "hello with space"
--password-command echo "hello with ""quotes"" and space"</code></pre>
<p>See the <a href="#configuration-encryption">Configuration
Encryption</a> for more info.</p>
<p>See a <a
href="https://github.com/rclone/rclone/wiki/Windows-Powershell-use-rclone-password-command-for-Config-file-password">Windows
PowerShell example on the Wiki</a>.</p>
<h3 id="p-progress">-P, –progress</h3>
<p>This flag makes rclone update the stats in a static block in the
terminal providing a realtime overview of the transfer.</p>
<p>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.</p>
<p>Normally this is updated every 500mS but this period can be
overridden with the <code>--stats</code> flag.</p>
<p>This can be used with the <code>--stats-one-line</code> flag for a
simpler display.</p>
<p>Note: On Windows until <a
href="https://github.com/Azure/go-ansiterm/issues/26">this bug</a> is
fixed all non-ASCII characters will be replaced with <code>.</code> when
<code>--progress</code> is in use.</p>
<h3 id="progress-terminal-title">–progress-terminal-title</h3>
<p>This flag, when used with <code>-P/--progress</code>, will print the
string <code>ETA: %s</code> to the terminal title.</p>
<h3 id="q-quiet">-q, –quiet</h3>
<p>This flag will limit rclone’s output to error messages only.</p>
<h3 id="refresh-times">–refresh-times</h3>
<p>The <code>--refresh-times</code> flag can be used to update
modification times of existing files when they are out of sync on
backends which don’t support hashes.</p>
<p>This is useful if you uploaded files with the incorrect timestamps
and you now wish to correct them.</p>
<p>This flag is <strong>only</strong> useful for destinations which
don’t support hashes (e.g. <code>crypt</code>).</p>
<p>This can be used any of the sync commands <code>sync</code>,
<code>copy</code> or <code>move</code>.</p>
<p>To use this flag you will need to be doing a modification time sync
(so not using <code>--size-only</code> or <code>--checksum</code>). The
flag will have no effect when using <code>--size-only</code> or
<code>--checksum</code>.</p>
<p>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
<code>crypt</code> backend) then rclone will update the timestamp.</p>
<p>Note that some remotes can’t set the modification time without
re-uploading the file so this flag is less useful on them.</p>
<p>Normally if you are doing a modification time sync rclone will update
modification times without <code>--refresh-times</code> provided that
the remote supports checksums <strong>and</strong> 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.</p>
<h3 id="retries-int">–retries int</h3>
<p>Retry the entire sync if it fails this many times it fails (default
3).</p>
<p>Some remotes can be unreliable and a few retries help pick up the
files which didn’t get transferred because of errors.</p>
<p>Disable retries with <code>--retries 1</code>.</p>
<h3 id="retries-sleeptime">–retries-sleep=TIME</h3>
<p>This sets the interval between each retry specified by
<code>--retries</code></p>
<p>The default is <code>0</code>. Use <code>0</code> to disable.</p>
<h3 id="server-side-across-configs">–server-side-across-configs</h3>
<p>Allow server-side operations (e.g. copy or move) to work across
different configurations.</p>
<p>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.</p>
<p>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.</p>
<h3 id="size-only">–size-only</h3>
<p>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.</p>
<p>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.</p>
<h3 id="statstime">–stats=TIME</h3>
<p>Commands which transfer data (<code>sync</code>, <code>copy</code>,
<code>copyto</code>, <code>move</code>, <code>moveto</code>) will print
data transfer stats at regular intervals to show their progress.</p>
<p>This sets the interval.</p>
<p>The default is <code>1m</code>. Use <code>0</code> to disable.</p>
<p>If you set the stats interval then all commands can show stats. This
can be useful when running other commands, <code>check</code> or
<code>mount</code> for example.</p>
<p>Stats are logged at <code>INFO</code> level by default which means
they won’t show at default log level <code>NOTICE</code>. Use
<code>--stats-log-level NOTICE</code> or <code>-v</code> to make them
show. See the <a href="#logging">Logging section</a> for more info on
log levels.</p>
<p>Note that on macOS you can send a SIGINFO (which is normally ctrl-T
in the terminal) to make the stats print immediately.</p>
<h3 id="stats-file-name-length-integer">–stats-file-name-length
integer</h3>
<p>By default, the <code>--stats</code> output will truncate file names
and paths longer than 40 characters. This is equivalent to providing
<code>--stats-file-name-length 40</code>. Use
<code>--stats-file-name-length 0</code> to disable any truncation of
file names printed by stats.</p>
<h3 id="stats-log-level-string">–stats-log-level string</h3>
<p>Log level to show <code>--stats</code> output at. This can be
<code>DEBUG</code>, <code>INFO</code>, <code>NOTICE</code>, or
<code>ERROR</code>. The default is <code>INFO</code>. This means at the
default level of logging which is <code>NOTICE</code> the stats won’t
show - if you want them to then use
<code>--stats-log-level NOTICE</code>. See the <a
href="#logging">Logging section</a> for more info on log levels.</p>
<h3 id="stats-one-line">–stats-one-line</h3>
<p>When this is specified, rclone condenses the stats into a single line
showing the most important stats only.</p>
<h3 id="stats-one-line-date">–stats-one-line-date</h3>
<p>When this is specified, rclone enables the single-line stats and
prepends the display with a date string. The default is
<code>2006/01/02 15:04:05 -</code></p>
<h3 id="stats-one-line-date-format">–stats-one-line-date-format</h3>
<p>When this is specified, rclone enables the single-line stats and
prepends the display with a user-supplied date string. The date string
MUST be enclosed in quotes. Follow <a
href="https://golang.org/pkg/time/#Time.Format">golang specs</a> for
date formatting syntax.</p>
<h3 id="stats-unitbitsbytes">–stats-unit=bits|bytes</h3>
<p>By default, data transfer rates will be printed in bytes per
second.</p>
<p>This option allows the data rate to be printed in bits per
second.</p>
<p>Data transfer volume will still be reported in bytes.</p>
<p>The rate is reported as a binary unit, not SI unit. So 1 Mbit/s
equals 1,048,576 bit/s and not 1,000,000 bit/s.</p>
<p>The default is <code>bytes</code>.</p>
<h3 id="suffixsuffix">–suffix=SUFFIX</h3>
<p>When using <code>sync</code>, <code>copy</code> or <code>move</code>
any files which would have been overwritten or deleted will have the
suffix added to them. If there is a file with the same path (after the
suffix has been added), then it will be overwritten.</p>
<p>The remote in use must support server-side move or copy and you must
use the same remote as the destination of the sync.</p>
<p>This is for use with files to add the suffix in the current directory
or with <code>--backup-dir</code>. See <code>--backup-dir</code> for
more info.</p>
<p>For example</p>
<pre><code>rclone copy -i /path/to/local/file remote:current --suffix .bak</code></pre>
<p>will copy <code>/path/to/local</code> to <code>remote:current</code>,
but for any files which would have been updated or deleted have .bak
added.</p>
<p>If using <code>rclone sync</code> with <code>--suffix</code> and
without <code>--backup-dir</code> then it is recommended to put a filter
rule in excluding the suffix otherwise the <code>sync</code> will delete
the backup files.</p>
<pre><code>rclone sync -i /path/to/local/file remote:current --suffix .bak --exclude "*.bak"</code></pre>
<h3 id="suffix-keep-extension">–suffix-keep-extension</h3>
<p>When using <code>--suffix</code>, setting this causes rclone put the
SUFFIX before the extension of the files that it backs up rather than
after.</p>
<p>So let’s say we had <code>--suffix -2019-01-01</code>, without the
flag <code>file.txt</code> would be backed up to
<code>file.txt-2019-01-01</code> and with the flag it would be backed up
to <code>file-2019-01-01.txt</code>. This can be helpful to make sure
the suffixed files can still be opened.</p>
<h3 id="syslog">–syslog</h3>
<p>On capable OSes (not Windows or Plan9) send all log output to
syslog.</p>
<p>This can be useful for running rclone in a script or
<code>rclone mount</code>.</p>
<h3 id="syslog-facility-string">–syslog-facility string</h3>
<p>If using <code>--syslog</code> this sets the syslog facility
(e.g. <code>KERN</code>, <code>USER</code>). See <code>man syslog</code>
for a list of possible facilities. The default facility is
<code>DAEMON</code>.</p>
<h3 id="temp-dirdir">–temp-dir=DIR</h3>
<p>Specify the directory rclone will use for temporary files, to
override the default. Make sure the directory exists and have accessible
permissions.</p>
<p>By default the operating system’s temp directory will be used: - On
Unix systems, <code>$TMPDIR</code> if non-empty, else <code>/tmp</code>.
- On Windows, the first non-empty value from <code>%TMP%</code>,
<code>%TEMP%</code>, <code>%USERPROFILE%</code>, or the Windows
directory.</p>
<p>When overriding the default with this option, the specified path will
be set as value of environment variable <code>TMPDIR</code> on Unix
systems and <code>TMP</code> and <code>TEMP</code> on Windows.</p>
<p>You can use the <a
href="https://rclone.org/commands/rclone_config_paths/">config paths</a>
command to see the current value.</p>
<h3 id="tpslimit-float">–tpslimit float</h3>
<p>Limit transactions per second to this number. Default is 0 which is
used to mean unlimited transactions per second.</p>
<p>A transaction is roughly defined as an API call; its exact meaning
will depend on the backend. For HTTP based backends it is an HTTP
PUT/GET/POST/etc and its response. For FTP/SFTP it is a round trip
transaction over TCP.</p>
<p>For example, to limit rclone to 10 transactions per second use
<code>--tpslimit 10</code>, or to 1 transaction every 2 seconds use
<code>--tpslimit 0.5</code>.</p>
<p>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).</p>
<p>This can be very useful for <code>rclone mount</code> to control the
behaviour of applications using it.</p>
<p>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.</p>
<p>See also <code>--tpslimit-burst</code>.</p>
<h3 id="tpslimit-burst-int">–tpslimit-burst int</h3>
<p>Max burst of transactions for <code>--tpslimit</code> (default
<code>1</code>).</p>
<p>Normally <code>--tpslimit</code> will do exactly the number of
transaction per second specified. However if you supply
<code>--tps-burst</code> then rclone can save up some transactions from
when it was idle giving a burst of up to the parameter supplied.</p>
<p>For example if you provide <code>--tpslimit-burst 10</code> then if
rclone has been idle for more than 10*<code>--tpslimit</code> then it
can do 10 transactions very quickly before they are limited again.</p>
<p>This may be used to increase performance of <code>--tpslimit</code>
without changing the long term average number of transactions per
second.</p>
<h3 id="track-renames">–track-renames</h3>
<p>By default, rclone doesn’t keep track of renamed files, so if you
rename a file locally then sync it to a remote, rclone will delete the
old file on the remote and upload a new copy.</p>
<p>An rclone sync with <code>--track-renames</code> runs like a normal
sync, but 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.</p>
<p>After the sync, rclone matches up the source only and destination
only objects using the <code>--track-renames-strategy</code> specified
and either renames the destination object or transfers the source and
deletes the destination object. <code>--track-renames</code> is
stateless like all of rclone’s syncs.</p>
<p>To use this flag the destination must support server-side copy or
server-side move, and to use a hash based
<code>--track-renames-strategy</code> (the default) the source and the
destination must have a compatible hash.</p>
<p>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.</p>
<p>Encrypted destinations are not currently supported by
<code>--track-renames</code> if <code>--track-renames-strategy</code>
includes <code>hash</code>.</p>
<p>Note that <code>--track-renames</code> is incompatible with
<code>--no-traverse</code> and that it uses extra memory to keep track
of all the rename candidates.</p>
<p>Note also that <code>--track-renames</code> is incompatible with
<code>--delete-before</code> and will select <code>--delete-after</code>
instead of <code>--delete-during</code>.</p>
<h3
id="track-renames-strategy-hashmodtimeleafsize">–track-renames-strategy
(hash,modtime,leaf,size)</h3>
<p>This option changes the file matching criteria for
<code>--track-renames</code>.</p>
<p>The matching is controlled by a comma separated selection of these
tokens:</p>
<ul>
<li><code>modtime</code> - the modification time of the file - not
supported on all backends</li>
<li><code>hash</code> - the hash of the file contents - not supported on
all backends</li>
<li><code>leaf</code> - the name of the file not including its directory
name</li>
<li><code>size</code> - the size of the file (this is always
enabled)</li>
</ul>
<p>The default option is <code>hash</code>.</p>
<p>Using <code>--track-renames-strategy modtime,leaf</code> would match
files based on modification time, the leaf of the file name and the size
only.</p>
<p>Using <code>--track-renames-strategy modtime</code> or
<code>leaf</code> can enable <code>--track-renames</code> support for
encrypted destinations.</p>
<p>Note that the <code>hash</code> strategy is not supported with
encrypted destinations.</p>
<h3 id="delete-beforeduringafter">–delete-(before,during,after)</h3>
<p>This option allows you to specify when files on your destination are
deleted when you sync folders.</p>
<p>Specifying the value <code>--delete-before</code> will delete all
files present on the destination, but not on the source <em>before</em>
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.</p>
<p>Specifying <code>--delete-during</code> will delete files while
checking and uploading files. This is the fastest option and uses the
least memory.</p>
<p>Specifying <code>--delete-after</code> (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
<code>not deleting files as there were IO errors</code>.</p>
<h3 id="fast-list">–fast-list</h3>
<p>When doing anything which involves a directory listing
(e.g. <code>sync</code>, <code>copy</code>, <code>ls</code> - in fact
nearly every command), rclone normally lists a directory and processes
it before using more directory lists to process any subdirectories. This
can be parallelised and works very quickly using the least amount of
memory.</p>
<p>However, some remotes have a way of listing all files beneath a
directory in one (or a small number) of transactions. These tend to be
the bucket-based remotes (e.g. S3, B2, GCS, Swift).</p>
<p>If you use the <code>--fast-list</code> flag then rclone will use
this method for listing directories. This will have the following
consequences for the listing:</p>
<ul>
<li>It <strong>will</strong> use fewer transactions (important if you
pay for them)</li>
<li>It <strong>will</strong> use more memory. Rclone has to load the
whole listing into memory.</li>
<li>It <em>may</em> be faster because it uses fewer transactions</li>
<li>It <em>may</em> be slower because it can’t be parallelized</li>
</ul>
<p>rclone should always give identical results with and without
<code>--fast-list</code>.</p>
<p>If you pay for transactions and can fit your entire sync listing into
memory then <code>--fast-list</code> is recommended. If you have a very
big sync to do then don’t use <code>--fast-list</code> otherwise you
will run out of memory.</p>
<p>If you use <code>--fast-list</code> on a remote which doesn’t support
it, then rclone will just ignore it.</p>
<h3 id="timeouttime">–timeout=TIME</h3>
<p>This sets the IO idle timeout. If a transfer has started but then
becomes idle for this long it is considered broken and disconnected.</p>
<p>The default is <code>5m</code>. Set to <code>0</code> to disable.</p>
<h3 id="transfersn">–transfers=N</h3>
<p>The number of file transfers to run in parallel. It can sometimes be
useful to set this to a smaller number if the remote is giving a lot of
timeouts or bigger if you have lots of bandwidth and a fast remote.</p>
<p>The default is to run 4 file transfers in parallel.</p>
<p>Look at –multi-thread-streams if you would like to control single
file transfers.</p>
<h3 id="u-update">-u, –update</h3>
<p>This forces rclone to skip any files which exist on the destination
and have a modified time that is newer than the source file.</p>
<p>This can be useful in avoiding needless transfers when transferring
to a remote which doesn’t support modification times directly (or when
using <code>--use-server-modtime</code> to avoid extra API calls) as it
is more accurate than a <code>--size-only</code> check and faster than
using <code>--checksum</code>. On such remotes (or when using
<code>--use-server-modtime</code>) the time checked will be the uploaded
time.</p>
<p>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.</p>
<p>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 <code>--checksum</code> flag is provided.</p>
<p>In all other cases the file will not be updated.</p>
<p>Consider using the <code>--modify-window</code> 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.</p>
<h3 id="use-mmap">–use-mmap</h3>
<p>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 <code>--buffer-size</code>). Memory
allocated like this does not go on the Go heap and can be returned to
the OS immediately when it is finished with.</p>
<p>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.</p>
<p>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.</p>
<h3 id="use-server-modtime">–use-server-modtime</h3>
<p>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.</p>
<p>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
<code>--update</code>, 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.</p>
<p>Using this flag on a sync operation without also using
<code>--update</code> 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.</p>
<h3 id="v--vv-verbose">-v, -vv, –verbose</h3>
<p>With <code>-v</code> rclone will tell you about each file that is
transferred and a small number of significant events.</p>
<p>With <code>-vv</code> rclone will become very verbose telling you
about every file it considers and transfers. Please send bug reports
with a log with this setting.</p>
<p>When setting verbosity as an environment variable, use
<code>RCLONE_VERBOSE=1</code> or <code>RCLONE_VERBOSE=2</code> for
<code>-v</code> and <code>-vv</code> respectively.</p>
<h3 id="v-version">-V, –version</h3>
<p>Prints the version number</p>
<h2 id="ssltls-options">SSL/TLS options</h2>
<p>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.</p>
<h3 id="ca-cert-string">–ca-cert string</h3>
<p>This loads the PEM encoded certificate authority certificate and uses
it to verify the certificates of the servers rclone connects to.</p>
<p>If you have generated certificates signed with a local CA then you
will need this flag to connect to servers using those certificates.</p>
<h3 id="client-cert-string">–client-cert string</h3>
<p>This loads the PEM encoded client side certificate.</p>
<p>This is used for <a
href="https://en.wikipedia.org/wiki/Mutual_authentication">mutual TLS
authentication</a>.</p>
<p>The <code>--client-key</code> flag is required too when using
this.</p>
<h3 id="client-key-string">–client-key string</h3>
<p>This loads the PEM encoded client side private key used for mutual
TLS authentication. Used in conjunction with
<code>--client-cert</code>.</p>
<h3
id="no-check-certificatetruefalse">–no-check-certificate=true/false</h3>
<p><code>--no-check-certificate</code> controls whether a client
verifies the server’s certificate chain and host name. If
<code>--no-check-certificate</code> 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.</p>
<p>This option defaults to <code>false</code>.</p>
<p><strong>This should be used only for testing.</strong></p>
<h2 id="configuration-encryption">Configuration Encryption</h2>
<p>Your configuration file contains information for logging in to your
cloud services. This means that you should keep your
<code>rclone.conf</code> file in a secure location.</p>
<p>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.</p>
<p>To add a password to your rclone configuration, execute
<code>rclone config</code>.</p>
<pre><code>>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></code></pre>
<p>Go into <code>s</code>, Set configuration password:</p>
<pre><code>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></code></pre>
<p>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.</p>
<p>There is no way to recover the configuration if you lose your
password.</p>
<p>rclone uses <a
href="https://godoc.org/golang.org/x/crypto/nacl/secretbox">nacl
secretbox</a> 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.</p>
<p>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.</p>
<p>If it is safe in your environment, you can set the
<code>RCLONE_CONFIG_PASS</code> environment variable to contain your
password, in which case it will be used for decrypting the
configuration.</p>
<p>You can set this for a session from a script. For unix like systems
save this to a file called <code>set-rclone-password</code>:</p>
<pre><code>#!/bin/echo Source this file don't run it
read -s RCLONE_CONFIG_PASS
export RCLONE_CONFIG_PASS</code></pre>
<p>Then source the file when you want to use it. From the shell you
would do <code>source set-rclone-password</code>. It will then ask you
for the password and set it in the environment variable.</p>
<p>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
<code>--password-command="..."</code> command line argument or via the
<code>RCLONE_PASSWORD_COMMAND</code> environment variable.</p>
<p>One useful example of this is using the <code>passwordstore</code>
application to retrieve the password:</p>
<pre><code>export RCLONE_PASSWORD_COMMAND="pass rclone/config"</code></pre>
<p>If the <code>passwordstore</code> password manager holds the password
for the rclone configuration, using the script method means the password
is primarily protected by the <code>passwordstore</code> system, and is
never embedded in the clear in scripts, nor available for examination
using the standard commands available. It is quite possible with long
running rclone sessions for copies of passwords to be innocently
captured in log files or terminal scroll buffers, etc. Using the script
method of supplying the password enhances the security of the config
password considerably.</p>
<p>If you are running rclone inside a script, unless you are using the
<code>--password-command</code> method, you might want to disable
password prompts. To do that, pass the parameter
<code>--ask-password=false</code> to rclone. This will make rclone fail
instead of asking for a password if <code>RCLONE_CONFIG_PASS</code>
doesn’t contain a valid password, and <code>--password-command</code>
has not been supplied.</p>
<p>Whenever running commands that may be affected by options in a
configuration file, rclone will look for an existing file according to
the rules described <a href="#config-config-file">above</a>, and load
any it finds. If an encrypted file is found, this includes decrypting
it, with the possible consequence of a password prompt. When executing a
command line that you know are not actually using anything from such a
configuration file, you can avoid it being loaded by overriding the
location, e.g. with one of the documented special values for memory-only
configuration. Since only backend options can be stored in configuration
files, this is normally unnecessary for commands that do not operate on
backends, e.g. <code>genautocomplete</code>. However, it will be
relevant for commands that do operate on backends in general, but are
used without referencing a stored remote, e.g. listing local filesystem
paths, or <a href="#connection-strings">connection strings</a>:
<code>rclone --config="" ls .</code></p>
<h2 id="developer-options">Developer options</h2>
<p>These options are useful when developing or debugging rclone. There
are also some more remote specific options which aren’t documented here
which are used for testing. These start with remote name e.g.
<code>--drive-test-option</code> - see the docs for the remote in
question.</p>
<h3 id="cpuprofilefile">–cpuprofile=FILE</h3>
<p>Write CPU profile to file. This can be analysed with
<code>go tool pprof</code>.</p>
<h4 id="dump-flagflagflag">–dump flag,flag,flag</h4>
<p>The <code>--dump</code> flag takes a comma separated list of flags to
dump info about.</p>
<p>Note that some headers including <code>Accept-Encoding</code> as
shown may not be correct in the request and the response may not show
<code>Content-Encoding</code> 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.</p>
<p>The available flags are:</p>
<h4 id="dump-headers">–dump headers</h4>
<p>Dump HTTP headers with <code>Authorization:</code> lines removed. May
still contain sensitive info. Can be very verbose. Useful for debugging
only.</p>
<p>Use <code>--dump auth</code> if you do want the
<code>Authorization:</code> headers.</p>
<h4 id="dump-bodies">–dump bodies</h4>
<p>Dump HTTP headers and bodies - may contain sensitive info. Can be
very verbose. Useful for debugging only.</p>
<p>Note that the bodies are buffered in memory so don’t use this for
enormous files.</p>
<h4 id="dump-requests">–dump requests</h4>
<p>Like <code>--dump bodies</code> but dumps the request bodies and the
response headers. Useful for debugging download problems.</p>
<h4 id="dump-responses">–dump responses</h4>
<p>Like <code>--dump bodies</code> but dumps the response bodies and the
request headers. Useful for debugging upload problems.</p>
<h4 id="dump-auth">–dump auth</h4>
<p>Dump HTTP headers - will contain sensitive info such as
<code>Authorization:</code> headers - use <code>--dump headers</code> to
dump without <code>Authorization:</code> headers. Can be very verbose.
Useful for debugging only.</p>
<h4 id="dump-filters">–dump filters</h4>
<p>Dump the filters to the output. Useful to see exactly what include
and exclude options are filtering on.</p>
<h4 id="dump-goroutines">–dump goroutines</h4>
<p>This dumps a list of the running go-routines at the end of the
command to standard output.</p>
<h4 id="dump-openfiles">–dump openfiles</h4>
<p>This dumps a list of the open files at the end of the command. It
uses the <code>lsof</code> command to do that so you’ll need that
installed to use it.</p>
<h3 id="memprofilefile">–memprofile=FILE</h3>
<p>Write memory profile to file. This can be analysed with
<code>go tool pprof</code>.</p>
<h2 id="filtering">Filtering</h2>
<p>For the filtering options</p>
<ul>
<li><code>--delete-excluded</code></li>
<li><code>--filter</code></li>
<li><code>--filter-from</code></li>
<li><code>--exclude</code></li>
<li><code>--exclude-from</code></li>
<li><code>--exclude-if-present</code></li>
<li><code>--include</code></li>
<li><code>--include-from</code></li>
<li><code>--files-from</code></li>
<li><code>--files-from-raw</code></li>
<li><code>--min-size</code></li>
<li><code>--max-size</code></li>
<li><code>--min-age</code></li>
<li><code>--max-age</code></li>
<li><code>--dump filters</code></li>
</ul>
<p>See the <a href="https://rclone.org/filtering/">filtering
section</a>.</p>
<h2 id="remote-control">Remote control</h2>
<p>For the remote control options and for instructions on how to remote
control rclone</p>
<ul>
<li><code>--rc</code></li>
<li>and anything starting with <code>--rc-</code></li>
</ul>
<p>See <a href="https://rclone.org/rc/">the remote control
section</a>.</p>
<h2 id="logging">Logging</h2>
<p>rclone has 4 levels of logging, <code>ERROR</code>,
<code>NOTICE</code>, <code>INFO</code> and <code>DEBUG</code>.</p>
<p>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. <code>rclone ls</code>).</p>
<p>By default, rclone will produce <code>Error</code> and
<code>Notice</code> level messages.</p>
<p>If you use the <code>-q</code> flag, rclone will only produce
<code>Error</code> messages.</p>
<p>If you use the <code>-v</code> flag, rclone will produce
<code>Error</code>, <code>Notice</code> and <code>Info</code>
messages.</p>
<p>If you use the <code>-vv</code> flag, rclone will produce
<code>Error</code>, <code>Notice</code>, <code>Info</code> and
<code>Debug</code> messages.</p>
<p>You can also control the log levels with the <code>--log-level</code>
flag.</p>
<p>If you use the <code>--log-file=FILE</code> option, rclone will
redirect <code>Error</code>, <code>Info</code> and <code>Debug</code>
messages along with standard error to FILE.</p>
<p>If you use the <code>--syslog</code> flag then rclone will log to
syslog and the <code>--syslog-facility</code> control which facility it
uses.</p>
<p>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.</p>
<h2 id="exit-code">Exit Code</h2>
<p>If any errors occur during the command execution, rclone will exit
with a non-zero exit code. This allows scripts to detect when rclone
operations have failed.</p>
<p>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.</p>
<p>When rclone is running it will accumulate errors as it goes along,
and only exit with a non-zero exit code if (after retries) there were
still failed transfers. For every error counted there will be a high
priority log message (visible with <code>-q</code>) showing the message
and which file caused the problem. A high priority message is also shown
when starting a retry so the user can see that any previous error
messages may not be valid after the retry. If rclone has done a retry it
will log a high priority message if the retry was successful.</p>
<h3 id="list-of-exit-codes">List of exit codes</h3>
<ul>
<li><code>0</code> - success</li>
<li><code>1</code> - Syntax or usage error</li>
<li><code>2</code> - Error not otherwise categorised</li>
<li><code>3</code> - Directory not found</li>
<li><code>4</code> - File not found</li>
<li><code>5</code> - Temporary error (one that more retries might fix)
(Retry errors)</li>
<li><code>6</code> - Less serious errors (like 461 errors from dropbox)
(NoRetry errors)</li>
<li><code>7</code> - Fatal error (one that more retries won’t fix, like
account suspended) (Fatal errors)</li>
<li><code>8</code> - Transfer exceeded - limit set by –max-transfer
reached</li>
<li><code>9</code> - Operation successful, but no files transferred</li>
</ul>
<h2 id="environment-variables">Environment Variables</h2>
<p>Rclone can be configured entirely using environment variables. These
can be used to set defaults for options or config file entries.</p>
<h3 id="options-86">Options</h3>
<p>Every option in rclone can have its default set by environment
variable.</p>
<p>To find the name of the environment variable, first, take the long
option name, strip the leading <code>--</code>, change <code>-</code> to
<code>_</code>, make upper case and prepend <code>RCLONE_</code>.</p>
<p>For example, to always set <code>--stats 5s</code>, set the
environment variable <code>RCLONE_STATS=5s</code>. If you set stats on
the command line this will override the environment variable
setting.</p>
<p>Or to always use the trash in drive <code>--drive-use-trash</code>,
set <code>RCLONE_DRIVE_USE_TRASH=true</code>.</p>
<p>Verbosity is slightly different, the environment variable equivalent
of <code>--verbose</code> or <code>-v</code> is
<code>RCLONE_VERBOSE=1</code>, or for <code>-vv</code>,
<code>RCLONE_VERBOSE=2</code>.</p>
<p>The same parser is used for the options and the environment variables
so they take exactly the same form.</p>
<p>The options set by environment variables can be seen with the
<code>-vv</code> flag, e.g. <code>rclone version -vv</code>.</p>
<h3 id="config-file">Config file</h3>
<p>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.</p>
<p>To find the name of the environment variable, you need to set, take
<code>RCLONE_CONFIG_</code> + name of remote + <code>_</code> + name of
config file option and make it all uppercase.</p>
<p>For example, to configure an S3 remote named <code>mys3:</code>
without a config file (using unix ways of setting environment
variables):</p>
<pre><code>$ 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:</code></pre>
<p>Note that if you want to create a remote using environment variables
you must create the <code>..._TYPE</code> variable as above.</p>
<p>Note that the name of a remote created using environment variable is
case insensitive, in contrast to regular remotes stored in config file
as documented <a href="#valid-remote-names">above</a>. You must write
the name in uppercase in the environment variable, but as seen from
example above it will be listed and can be accessed in lowercase, while
you can also refer to the same remote in uppercase:</p>
<pre><code>$ 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</code></pre>
<p>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.</p>
<p>Note also that now rclone has <a
href="#connection-strings">connection strings</a>, it is probably easier
to use those instead which makes the above example</p>
<pre><code>rclone lsd :s3,access_key_id=XXX,secret_access_key=XXX:</code></pre>
<h3 id="precedence">Precedence</h3>
<p>The various different methods of backend configuration are read in
this order and the first one with a value is used.</p>
<ul>
<li>Parameters in connection strings,
e.g. <code>myRemote,skip_links:</code></li>
<li>Flag values as supplied on the command line,
e.g. <code>--skip-links</code></li>
<li>Remote specific environment vars,
e.g. <code>RCLONE_CONFIG_MYREMOTE_SKIP_LINKS</code> (see above).</li>
<li>Backend-specific environment vars,
e.g. <code>RCLONE_LOCAL_SKIP_LINKS</code>.</li>
<li>Backend generic environment vars,
e.g. <code>RCLONE_SKIP_LINKS</code>.</li>
<li>Config file, e.g. <code>skip_links = true</code>.</li>
<li>Default values, e.g. <code>false</code> - these can’t be
changed.</li>
</ul>
<p>So if both <code>--skip-links</code> is supplied on the command line
and an environment variable <code>RCLONE_LOCAL_SKIP_LINKS</code> is set,
the command line flag will take preference.</p>
<p>The backend configurations set by environment variables can be seen
with the <code>-vv</code> flag,
e.g. <code>rclone about myRemote: -vv</code>.</p>
<p>For non backend configuration the order is as follows:</p>
<ul>
<li>Flag values as supplied on the command line,
e.g. <code>--stats 5s</code>.</li>
<li>Environment vars, e.g. <code>RCLONE_STATS=5s</code>.</li>
<li>Default values, e.g. <code>1m</code> - these can’t be changed.</li>
</ul>
<h3 id="other-environment-variables">Other environment variables</h3>
<ul>
<li><code>RCLONE_CONFIG_PASS</code> set to contain your config file
password (see <a href="#configuration-encryption">Configuration
Encryption</a> section)</li>
<li><code>HTTP_PROXY</code>, <code>HTTPS_PROXY</code> and
<code>NO_PROXY</code> (or the lowercase versions thereof).
<ul>
<li><code>HTTPS_PROXY</code> takes precedence over
<code>HTTP_PROXY</code> for https requests.</li>
<li>The environment values may be either a complete URL or a
“host[:port]” for, in which case the “http” scheme is assumed.</li>
</ul></li>
<li><code>USER</code> and <code>LOGNAME</code> 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 <code>$USER</code>.</li>
<li><code>RCLONE_CONFIG_DIR</code> - rclone <strong>sets</strong> this
variable for use in config files and sub processes to point to the
directory holding the config file.</li>
</ul>
<p>The options set by environment variables can be seen with the
<code>-vv</code> and <code>--log-level=DEBUG</code> flags,
e.g. <code>rclone version -vv</code>.</p>
<h1 id="configuring-rclone-on-a-remote-headless-machine">Configuring
rclone on a remote / headless machine</h1>
<p>Some of the configurations (those involving oauth2) require an
Internet connected web browser.</p>
<p>If you are trying to set rclone up on a remote or headless box with
no browser available on it (e.g. a NAS or a server in a datacenter) then
you will need to use an alternative means of configuration. There are
two ways of doing it, described below.</p>
<h2 id="configuring-using-rclone-authorize">Configuring using rclone
authorize</h2>
<p>On the headless box run <code>rclone</code> config but answer
<code>N</code> to the <code>Use auto config?</code> question.</p>
<pre><code>...
Remote config
Use auto config?
* Say Y if not sure
* Say N if you are working on a remote or headless machine
y) Yes (default)
n) No
y/n> n
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 "amazon cloud drive"
Then paste the result below:
result></code></pre>
<p>Then on your main desktop machine</p>
<pre><code>rclone authorize "amazon cloud drive"
If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth
Log in and authorize rclone for access
Waiting for code...
Got code
Paste the following into your remote machine --->
SECRET_TOKEN
<---End paste</code></pre>
<p>Then back to the headless box, paste in the code</p>
<pre><code>result> 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></code></pre>
<h2 id="configuring-by-copying-the-config-file">Configuring by copying
the config file</h2>
<p>Rclone stores all of its config in a single configuration file. This
can easily be copied to configure a remote rclone.</p>
<p>So first configure rclone on your desktop machine with</p>
<pre><code>rclone config</code></pre>
<p>to set up the config file.</p>
<p>Find the config file by running <code>rclone config file</code>, for
example</p>
<pre><code>$ rclone config file
Configuration file is stored at:
/home/user/.rclone.conf</code></pre>
<p>Now transfer it to the remote box (scp, cut paste, ftp, sftp, etc.)
and place it in the correct place (use <code>rclone config file</code>
on the remote box to find out where).</p>
<h2 id="configuring-using-ssh-tunnel">Configuring using SSH Tunnel</h2>
<p>Linux and MacOS users can utilize SSH Tunnel to redirect the headless
box port 53682 to local machine by using the following command:</p>
<pre><code>ssh -L localhost:53682:localhost:53682 username@remote_server</code></pre>
<p>Then on the headless box run <code>rclone</code> config and answer
<code>Y</code> to the <code>Use auto config?</code> question.</p>
<pre><code>...
Remote config
Use auto config?
* Say Y if not sure
* Say N if you are working on a remote or headless machine
y) Yes (default)
n) No
y/n> y</code></pre>
<p>Then copy and paste the auth url
<code>http://127.0.0.1:53682/auth?state=xxxxxxxxxxxx</code> to the
browser on your local machine, complete the auth and it is done.</p>
<h1 id="filtering-includes-and-excludes">Filtering, includes and
excludes</h1>
<p>Filter flags determine which files rclone <code>sync</code>,
<code>move</code>, <code>ls</code>, <code>lsl</code>,
<code>md5sum</code>, <code>sha1sum</code>, <code>size</code>,
<code>delete</code>, <code>check</code> and similar commands apply
to.</p>
<p>They are specified in terms of path/file name patterns; path/file
lists; file age and size, or presence of a file in a directory. Bucket
based remotes without the concept of directory apply filters to object
key, age and size in an analogous way.</p>
<p>Rclone <code>purge</code> does not obey filters.</p>
<p>To test filters without risk of damage to data, apply them to
<code>rclone ls</code>, or with the <code>--dry-run</code> and
<code>-vv</code> flags.</p>
<p>Rclone filter patterns can only be used in filter command line
options, not in the specification of a remote.</p>
<p>E.g. <code>rclone copy "remote:dir*.jpg" /path/to/dir</code> does not
have a filter effect.
<code>rclone copy remote:dir /path/to/dir --include "*.jpg"</code>
does.</p>
<p><strong>Important</strong> Avoid mixing any two of
<code>--include...</code>, <code>--exclude...</code> or
<code>--filter...</code> flags in an rclone command. The results may not
be what you expect. Instead use a <code>--filter...</code> flag.</p>
<h2 id="patterns-for-matching-pathfile-names">Patterns for matching
path/file names</h2>
<h3 id="pattern-syntax">Pattern syntax</h3>
<p>Here is a formal definition of the pattern syntax, <a
href="#examples">examples</a> are below.</p>
<p>Rclone matching rules follow a glob style:</p>
<pre><code>* 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</code></pre>
<p>character-range:</p>
<pre><code>c matches character c (c != \, -, ])
\c matches reserved character c (c = \, -, ])
lo - hi matches character c for lo <= c <= hi</code></pre>
<p>pattern-list:</p>
<pre><code>pattern { , pattern }
comma-separated (without spaces) patterns</code></pre>
<p>character classes (see <a
href="https://golang.org/pkg/regexp/syntax/">Go regular expression
reference</a>) include:</p>
<pre><code>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:]])</code></pre>
<p>regexp for advanced users to insert a regular expression - see <a
href="#regexp">below</a> for more info:</p>
<pre><code>Any re2 regular expression not containing `}}`</code></pre>
<p>If the filter pattern starts with a <code>/</code> then it only
matches at the top level of the directory tree, <strong>relative to the
root of the remote</strong> (not necessarily the root of the drive). If
it does not start with <code>/</code> then it is matched starting at the
<strong>end of the path/file name</strong> but it only matches a
complete path element - it must match from a <code>/</code> separator or
the beginning of the path/file.</p>
<pre><code>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"</code></pre>
<p>The top level of the remote may not be the top level of the
drive.</p>
<p>E.g. for a Microsoft Windows local directory structure</p>
<pre><code>F:
├── bkp
├── data
│ ├── excl
│ │ ├── 123.jpg
│ │ └── 456.jpg
│ ├── incl
│ │ └── document.pdf</code></pre>
<p>To copy the contents of folder <code>data</code> into folder
<code>bkp</code> excluding the contents of subfolder
<code>excl</code>the following command treats <code>F:\data</code> and
<code>F:\bkp</code> as top level for filtering.</p>
<p><code>rclone copy F:\data\ F:\bkp\ --exclude=/excl/**</code></p>
<p><strong>Important</strong> Use <code>/</code> in path/file name
patterns and not <code>\</code> even if running on Microsoft
Windows.</p>
<p>Simple patterns are case sensitive unless the
<code>--ignore-case</code> flag is used.</p>
<p>Without <code>--ignore-case</code> (default)</p>
<pre><code>potato - matches "potato"
- doesn't match "POTATO"</code></pre>
<p>With <code>--ignore-case</code></p>
<pre><code>potato - matches "potato"
- matches "POTATO"</code></pre>
<h2 id="regexp">Using regular expressions in filter patterns</h2>
<p>The syntax of filter patterns is glob style matching (like
<code>bash</code> 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.</p>
<p>The regular expressions used are as defined in the <a
href="https://golang.org/pkg/regexp/syntax/">Go regular expression
reference</a>. Regular expressions should be enclosed in <code>{{</code>
<code>}}</code>. They will match only the last path segment if the glob
doesn’t start with <code>/</code> 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 <a href="#directory_filter">directory filter
rules</a>, as it will instead check every path against the supplied
regular expression(s).</p>
<p>Here is how the <code>{{regexp}}</code> is transformed into an full
regular expression to match the entire path:</p>
<pre><code>{{regexp}} becomes (^|/)(regexp)$
/{{regexp}} becomes ^(regexp)$</code></pre>
<p>Regexp syntax can be mixed with glob syntax, for example</p>
<pre><code>*.{{jpe?g}} to match file.jpg, file.jpeg but not file.png</code></pre>
<p>You can also use regexp flags - to set case insensitive, for
example</p>
<pre><code>*.{{(?i)jpg}} to match file.jpg, file.JPG but not file.png</code></pre>
<p>Be careful with wildcards in regular expressions - you don’t want
them to match path separators normally. To match any file name starting
with <code>start</code> and ending with <code>end</code> write</p>
<pre><code>{{start[^/]*end\.jpg}}</code></pre>
<p>Not</p>
<pre><code>{{start.*end\.jpg}}</code></pre>
<p>Which will match a directory called <code>start</code> with a file
called <code>end.jpg</code> in it as the <code>.*</code> will match
<code>/</code> characters.</p>
<p>Note that you can use <code>-vv --dump filters</code> to show the
filter patterns in regexp format - rclone implements the glob patters by
transforming them into regular expressions.</p>
<h2 id="examples">Filter pattern examples</h2>
<table>
<colgroup>
<col style="width: 27%" />
<col style="width: 20%" />
<col style="width: 17%" />
<col style="width: 35%" />
</colgroup>
<thead>
<tr class="header">
<th>Description</th>
<th>Pattern</th>
<th>Matches</th>
<th>Does not match</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Wildcard</td>
<td><code>*.jpg</code></td>
<td><code>/file.jpg</code></td>
<td><code>/file.png</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.jpg</code></td>
<td><code>/dir/file.png</code></td>
</tr>
<tr class="odd">
<td>Rooted</td>
<td><code>/*.jpg</code></td>
<td><code>/file.jpg</code></td>
<td><code>/file.png</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/file2.jpg</code></td>
<td><code>/dir/file.jpg</code></td>
</tr>
<tr class="odd">
<td>Alternates</td>
<td><code>*.{jpg,png}</code></td>
<td><code>/file.jpg</code></td>
<td><code>/file.gif</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.png</code></td>
<td><code>/dir/file.gif</code></td>
</tr>
<tr class="odd">
<td>Path Wildcard</td>
<td><code>dir/**</code></td>
<td><code>/dir/anyfile</code></td>
<td><code>file.png</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/subdir/dir/subsubdir/anyfile</code></td>
<td><code>/subdir/file.png</code></td>
</tr>
<tr class="odd">
<td>Any Char</td>
<td><code>*.t?t</code></td>
<td><code>/file.txt</code></td>
<td><code>/file.qxt</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.tzt</code></td>
<td><code>/dir/file.png</code></td>
</tr>
<tr class="odd">
<td>Range</td>
<td><code>*.[a-z]</code></td>
<td><code>/file.a</code></td>
<td><code>/file.0</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.b</code></td>
<td><code>/dir/file.1</code></td>
</tr>
<tr class="odd">
<td>Escape</td>
<td><code>*.\?\?\?</code></td>
<td><code>/file.???</code></td>
<td><code>/file.abc</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.???</code></td>
<td><code>/dir/file.def</code></td>
</tr>
<tr class="odd">
<td>Class</td>
<td><code>*.\d\d\d</code></td>
<td><code>/file.012</code></td>
<td><code>/file.abc</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.345</code></td>
<td><code>/dir/file.def</code></td>
</tr>
<tr class="odd">
<td>Regexp</td>
<td><code>*.{{jpe?g}}</code></td>
<td><code>/file.jpeg</code></td>
<td><code>/file.png</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/dir/file.jpg</code></td>
<td><code>/dir/file.jpeeg</code></td>
</tr>
<tr class="odd">
<td>Rooted Regexp</td>
<td><code>/{{.*\.jpe?g}}</code></td>
<td><code>/file.jpeg</code></td>
<td><code>/file.png</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td><code>/file.jpg</code></td>
<td><code>/dir/file.jpg</code></td>
</tr>
</tbody>
</table>
<h2 id="how-filter-rules-are-applied-to-files">How filter rules are
applied to files</h2>
<p>Rclone path/file name filters are made up of one or more of the
following flags:</p>
<ul>
<li><code>--include</code></li>
<li><code>--include-from</code></li>
<li><code>--exclude</code></li>
<li><code>--exclude-from</code></li>
<li><code>--filter</code></li>
<li><code>--filter-from</code></li>
</ul>
<p>There can be more than one instance of individual flags.</p>
<p>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.</p>
<p>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.</p>
<p>Multiple instances of the same flag are processed from left to right
according to their position in the command line.</p>
<p>To mix up the order of processing includes and excludes use
<code>--filter...</code> flags.</p>
<p>Within <code>--include-from</code>, <code>--exclude-from</code> and
<code>--filter-from</code> flags rules are processed from top to bottom
of the referenced file.</p>
<p>If there is an <code>--include</code> or <code>--include-from</code>
flag specified, rclone implies a <code>- **</code> rule which it adds to
the bottom of the internal rule list. Specifying a <code>+</code> rule
with a <code>--filter...</code> flag does not imply that rule.</p>
<p>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.</p>
<p>If rclone does not find a match, after testing against all rules
(including the implied rule if appropriate), the path/file name is
included.</p>
<p>Any path/file included at that stage is processed by the rclone
command.</p>
<p><code>--files-from</code> and <code>--files-from-raw</code> flags
over-ride and cannot be combined with other filter options.</p>
<p>To see the internal combined rule list, in regular expression form,
for a command add the <code>--dump filters</code> flag. Running an
rclone command with <code>--dump filters</code> and <code>-vv</code>
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. <a
href="https://golang.org/pkg/regexp/syntax/">Go regular expression
reference</a></p>
<h3 id="directory_filter">How filter rules are applied to
directories</h3>
<p>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
<code>directory/*</code> or recursively by
<code>directory/**</code>.</p>
<p>Directory filter rules are defined with a closing <code>/</code>
separator.</p>
<p>E.g. <code>/directory/subdirectory/</code> is an rclone directory
filter rule.</p>
<p>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.</p>
<p>If any <a href="#regexp">regular expression filters</a> are in use,
then no directory recursion optimisation is possible, as rclone must
check every path against the supplied regular expression(s).</p>
<p>Directory recursion optimisation occurs if either:</p>
<ul>
<li><p>A source remote does not support the rclone <code>ListR</code>
primitive. local, sftp, Microsoft OneDrive and WebDAV do not support
<code>ListR</code>. Google Drive and most bucket type storage do. <a
href="https://rclone.org/overview/#optional-features">Full
list</a></p></li>
<li><p>On other remotes (those that support <code>ListR</code>), if the
rclone command is not naturally recursive, and provided it is not run
with the <code>--fast-list</code> flag. <code>ls</code>,
<code>lsf -R</code> and <code>size</code> are naturally recursive but
<code>sync</code>, <code>copy</code> and <code>move</code> are
not.</p></li>
<li><p>Whenever the <code>--disable ListR</code> flag is applied to an
rclone command.</p></li>
</ul>
<p>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 <code>--dump filters</code> flag.</p>
<p>E.g. for an include rule</p>
<pre><code>/a/*.jpg</code></pre>
<p>Rclone implies the directory include rule</p>
<pre><code>/a/</code></pre>
<p>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.</p>
<p>E.g. <code>rclone ls remote: --include /directory/</code> will not
match any files. Because it is an <code>--include</code> option the
<code>--exclude **</code> rule is implied, and the
<code>/directory/</code> pattern serves only to optimise access to the
remote by ignoring everything outside of that directory.</p>
<p>E.g. <code>rclone ls remote: --filter-from filter-list.txt</code>
with a file <code>filter-list.txt</code>:</p>
<pre><code>- /dir1/
- /dir2/
+ *.pdf
- **</code></pre>
<p>All files in directories <code>dir1</code> or <code>dir2</code> or
their subdirectories are completely excluded from the listing. Only
files of suffix <code>pdf</code> in the root of <code>remote:</code> or
its subdirectories are listed. The <code>- **</code> rule prevents
listing of any path/files not previously matched by the rules above.</p>
<p>Option <code>exclude-if-present</code> creates a directory exclude
rule based on the presence of a file in a directory and takes precedence
over other rclone directory filter rules.</p>
<p>When using pattern list syntax, if a pattern item contains either
<code>/</code> or <code>**</code>, then rclone will not able to imply a
directory filter rule from this pattern list.</p>
<p>E.g. for an include rule</p>
<pre><code>{dir1/**,dir2/**}</code></pre>
<p>Rclone will match files below directories <code>dir1</code> or
<code>dir2</code> only, but will not be able to use this filter to
exclude a directory <code>dir3</code> from being traversed.</p>
<p>Directory recursion optimisation may affect performance, but normally
not the result. One exception to this is sync operations with option
<code>--create-empty-src-dirs</code>, where any traversed empty
directories will be created. With the pattern list example
<code>{dir1/**,dir2/**}</code> above, this would create an empty
directory <code>dir3</code> on destination (when it exists on source).
Changing the filter to <code>{dir1,dir2}/**</code>, or splitting it into
two include rules <code>--include dir1/** --include dir2/**</code>, will
match the same files while also filtering directories, with the result
that an empty directory <code>dir3</code> will no longer be created.</p>
<h3 id="exclude---exclude-files-matching-pattern"><code>--exclude</code>
- Exclude files matching pattern</h3>
<p>Excludes path/file names from an rclone command based on a single
exclude rule.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p><code>--exclude</code> should not be used with
<code>--include</code>, <code>--include-from</code>,
<code>--filter</code> or <code>--filter-from</code> flags.</p>
<p><code>--exclude</code> has no effect when combined with
<code>--files-from</code> or <code>--files-from-raw</code> flags.</p>
<p>E.g. <code>rclone ls remote: --exclude *.bak</code> excludes all .bak
files from listing.</p>
<p>E.g. <code>rclone size remote: "--exclude /dir/**"</code> returns the
total size of all files on <code>remote:</code> excluding those in root
directory <code>dir</code> and sub directories.</p>
<p>E.g. on Microsoft Windows
<code>rclone ls remote: --exclude "*\[{JP,KR,HK}\]*"</code> lists the
files in <code>remote:</code> with <code>[JP]</code> or
<code>[KR]</code> or <code>[HK]</code> in their name. Quotes prevent the
shell from interpreting the <code>\</code> characters.<code>\</code>
characters escape the <code>[</code> and <code>]</code> so an rclone
filter treats them literally rather than as a character-range. The
<code>{</code> and <code>}</code> define an rclone pattern list. For
other operating systems single quotes are required ie
<code>rclone ls remote: --exclude '*\[{JP,KR,HK}\]*'</code></p>
<h3
id="exclude-from---read-exclude-patterns-from-file"><code>--exclude-from</code>
- Read exclude patterns from file</h3>
<p>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.</p>
<p>For an example <code>exclude-file.txt</code>:</p>
<pre><code># a sample exclude rule file
*.bak
file2.jpg</code></pre>
<p><code>rclone ls remote: --exclude-from exclude-file.txt</code> lists
the files on <code>remote:</code> except those named
<code>file2.jpg</code> or with a suffix <code>.bak</code>. That is
equivalent to
<code>rclone ls remote: --exclude file2.jpg --exclude "*.bak"</code>.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p>The <code>--exclude-from</code> flag is useful where multiple exclude
filter rules are applied to an rclone command.</p>
<p><code>--exclude-from</code> should not be used with
<code>--include</code>, <code>--include-from</code>,
<code>--filter</code> or <code>--filter-from</code> flags.</p>
<p><code>--exclude-from</code> has no effect when combined with
<code>--files-from</code> or <code>--files-from-raw</code> flags.</p>
<p><code>--exclude-from</code> followed by <code>-</code> reads filter
rules from standard input.</p>
<h3 id="include---include-files-matching-pattern"><code>--include</code>
- Include files matching pattern</h3>
<p>Adds a single include rule based on path/file names to an rclone
command.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p><code>--include</code> has no effect when combined with
<code>--files-from</code> or <code>--files-from-raw</code> flags.</p>
<p><code>--include</code> implies <code>--exclude **</code> at the end
of an rclone internal filter list. Therefore if you mix
<code>--include</code> and <code>--include-from</code> flags with
<code>--exclude</code>, <code>--exclude-from</code>,
<code>--filter</code> or <code>--filter-from</code>, you must use
include rules for all the files you want in the include statement. For
more flexibility use the <code>--filter-from</code> flag.</p>
<p>E.g. <code>rclone ls remote: --include "*.{png,jpg}"</code> lists the
files on <code>remote:</code> with suffix <code>.png</code> and
<code>.jpg</code>. All other files are excluded.</p>
<p>E.g. multiple rclone copy commands can be combined with
<code>--include</code> and a pattern-list.</p>
<pre><code>rclone copy /vol1/A remote:A
rclone copy /vol1/B remote:B</code></pre>
<p>is equivalent to:</p>
<pre><code>rclone copy /vol1 remote: --include "{A,B}/**"</code></pre>
<p>E.g. <code>rclone ls remote:/wheat --include "??[^[:punct:]]*"</code>
lists the files <code>remote:</code> directory <code>wheat</code> (and
subdirectories) whose third character is not punctuation. This example
uses an <a href="https://golang.org/pkg/regexp/syntax/">ASCII character
class</a>.</p>
<h3
id="include-from---read-include-patterns-from-file"><code>--include-from</code>
- Read include patterns from file</h3>
<p>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.</p>
<p>For an example <code>include-file.txt</code>:</p>
<pre><code># a sample include rule file
*.jpg
file2.avi</code></pre>
<p><code>rclone ls remote: --include-from include-file.txt</code> lists
the files on <code>remote:</code> with name <code>file2.avi</code> or
suffix <code>.jpg</code>. That is equivalent to
<code>rclone ls remote: --include file2.avi --include "*.jpg"</code>.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p>The <code>--include-from</code> flag is useful where multiple include
filter rules are applied to an rclone command.</p>
<p><code>--include-from</code> implies <code>--exclude **</code> at the
end of an rclone internal filter list. Therefore if you mix
<code>--include</code> and <code>--include-from</code> flags with
<code>--exclude</code>, <code>--exclude-from</code>,
<code>--filter</code> or <code>--filter-from</code>, you must use
include rules for all the files you want in the include statement. For
more flexibility use the <code>--filter-from</code> flag.</p>
<p><code>--exclude-from</code> has no effect when combined with
<code>--files-from</code> or <code>--files-from-raw</code> flags.</p>
<p><code>--exclude-from</code> followed by <code>-</code> reads filter
rules from standard input.</p>
<h3 id="filter---add-a-file-filtering-rule"><code>--filter</code> - Add
a file-filtering rule</h3>
<p>Specifies path/file names to an rclone command, based on a single
include or exclude rule, in <code>+</code> or <code>-</code> format.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p><code>--filter +</code> differs from <code>--include</code>. In the
case of <code>--include</code> rclone implies an
<code>--exclude *</code> rule which it adds to the bottom of the
internal rule list. <code>--filter...+</code> does not imply that
rule.</p>
<p><code>--filter</code> has no effect when combined with
<code>--files-from</code> or <code>--files-from-raw</code> flags.</p>
<p><code>--filter</code> should not be used with <code>--include</code>,
<code>--include-from</code>, <code>--exclude</code> or
<code>--exclude-from</code> flags.</p>
<p>E.g. <code>rclone ls remote: --filter "- *.bak"</code> excludes all
<code>.bak</code> files from a list of <code>remote:</code>.</p>
<h3
id="filter-from---read-filtering-patterns-from-a-file"><code>--filter-from</code>
- Read filtering patterns from a file</h3>
<p>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 <code>+</code> and exclude rules with <code>-</code>.
<code>!</code> clears existing rules. Rules are processed in the order
they are defined.</p>
<p>This flag can be repeated. See above for the order filter flags are
processed in.</p>
<p>Arrange the order of filter rules with the most restrictive first and
work down.</p>
<p>E.g. for <code>filter-file.txt</code>:</p>
<pre><code># a sample filter rule file
- secret*.jpg
+ *.jpg
+ *.png
+ file2.avi
- /dir/Trash/**
+ /dir/**
# exclude everything else
- *</code></pre>
<p><code>rclone ls remote: --filter-from filter-file.txt</code> lists
the path/files on <code>remote:</code> including all <code>jpg</code>
and <code>png</code> files, excluding any matching
<code>secret*.jpg</code> and including <code>file2.avi</code>. It also
includes everything in the directory <code>dir</code> at the root of
<code>remote</code>, except <code>remote:dir/Trash</code> which it
excludes. Everything else is excluded.</p>
<p>E.g. for an alternative <code>filter-file.txt</code>:</p>
<pre><code>- secret*.jpg
+ *.jpg
+ *.png
+ file2.avi
- *</code></pre>
<p>Files <code>file1.jpg</code>, <code>file3.png</code> and
<code>file2.avi</code> are listed whilst <code>secret17.jpg</code> and
files without the suffix .jpg<code>or</code>.png` are excluded.</p>
<p>E.g. for an alternative <code>filter-file.txt</code>:</p>
<pre><code>+ *.jpg
+ *.gif
!
+ 42.doc
- *</code></pre>
<p>Only file 42.doc is listed. Prior rules are cleared by the
<code>!</code>.</p>
<h3
id="files-from---read-list-of-source-file-names"><code>--files-from</code>
- Read list of source-file names</h3>
<p>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.</p>
<p>Other filter flags (<code>--include</code>,
<code>--include-from</code>, <code>--exclude</code>,
<code>--exclude-from</code>, <code>--filter</code> and
<code>--filter-from</code>) are ignored when <code>--files-from</code>
is used.</p>
<p><code>--files-from</code> expects a list of files as its input.
Leading or trailing whitespace is stripped from the input lines. Lines
starting with <code>#</code> or <code>;</code> are ignored.</p>
<p>Rclone commands with a <code>--files-from</code> flag traverse the
remote, treating the names in <code>--files-from</code> as a set of
filters.</p>
<p>If the <code>--no-traverse</code> and <code>--files-from</code> 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 <code>--files-from</code> list and a remote
containing many files.</p>
<p>Rclone commands do not error if any names in the
<code>--files-from</code> file are missing from the source remote.</p>
<p>The <code>--files-from</code> 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.</p>
<p>Paths within the <code>--files-from</code> file are interpreted as
starting with the root specified in the rclone command. Leading
<code>/</code> separators are ignored. See <a
href="#files-from-raw-read-list-of-source-file-names-without-any-processing">–files-from-raw</a>
if you need the input to be processed in a raw manner.</p>
<p>E.g. for a file <code>files-from.txt</code>:</p>
<pre><code># comment
file1.jpg
subdir/file2.jpg</code></pre>
<p><code>rclone copy --files-from files-from.txt /home/me/pics remote:pics</code>
copies the following, if they exist, and only those files.</p>
<pre><code>/home/me/pics/file1.jpg → remote:pics/file1.jpg
/home/me/pics/subdir/file2.jpg → remote:pics/subdir/file2.jpg</code></pre>
<p>E.g. to copy the following files referenced by their absolute
paths:</p>
<pre><code>/home/user1/42
/home/user1/dir/ford
/home/user2/prefect</code></pre>
<p>First find a common subdirectory - in this case <code>/home</code>
and put the remaining files in <code>files-from.txt</code> with or
without leading <code>/</code>, e.g.</p>
<pre><code>user1/42
user1/dir/ford
user2/prefect</code></pre>
<p>Then copy these to a remote:</p>
<pre><code>rclone copy --files-from files-from.txt /home remote:backup</code></pre>
<p>The three files are transferred as follows:</p>
<pre><code>/home/user1/42 → remote:backup/user1/important
/home/user1/dir/ford → remote:backup/user1/dir/file
/home/user2/prefect → remote:backup/user2/stuff</code></pre>
<p>Alternatively if <code>/</code> is chosen as root
<code>files-from.txt</code> will be:</p>
<pre><code>/home/user1/42
/home/user1/dir/ford
/home/user2/prefect</code></pre>
<p>The copy command will be:</p>
<pre><code>rclone copy --files-from files-from.txt / remote:backup</code></pre>
<p>Then there will be an extra <code>home</code> directory on the
remote:</p>
<pre><code>/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</code></pre>
<h3
id="files-from-raw---read-list-of-source-file-names-without-any-processing"><code>--files-from-raw</code>
- Read list of source-file names without any processing</h3>
<p>This flag is the same as <code>--files-from</code> except that input
is read in a raw manner. Lines with leading / trailing whitespace, and
lines starting with <code>;</code> or <code>#</code> are read without
any processing. <a href="https://rclone.org/commands/rclone_lsf/">rclone
lsf</a> has a compatible format that can be used to export file lists
from remotes for input to <code>--files-from-raw</code>.</p>
<h3
id="ignore-case---make-searches-case-insensitive"><code>--ignore-case</code>
- make searches case insensitive</h3>
<p>By default, rclone filter patterns are case sensitive. The
<code>--ignore-case</code> flag makes all of the filters patterns on the
command line case insensitive.</p>
<p>E.g. <code>--include "zaphod.txt"</code> does not match a file
<code>Zaphod.txt</code>. With <code>--ignore-case</code> a match is
made.</p>
<h2 id="quoting-shell-metacharacters">Quoting shell metacharacters</h2>
<p>Rclone commands with filter patterns containing shell metacharacters
may not as work as expected in your shell and may require quoting.</p>
<p>E.g. linux, OSX (<code>*</code> metacharacter)</p>
<ul>
<li><code>--include \*.jpg</code></li>
<li><code>--include '*.jpg'</code></li>
<li><code>--include='*.jpg'</code></li>
</ul>
<p>Microsoft Windows expansion is done by the command, not shell, so
<code>--include *.jpg</code> does not require quoting.</p>
<p>If the rclone error
<code>Command .... needs .... arguments maximum: you provided .... non flag arguments:</code>
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.</p>
<h2 id="other-filters">Other filters</h2>
<h3
id="min-size---dont-transfer-any-file-smaller-than-this"><code>--min-size</code>
- Don’t transfer any file smaller than this</h3>
<p>Controls the minimum size file within the scope of an rclone command.
Default units are <code>KiB</code> but abbreviations <code>K</code>,
<code>M</code>, <code>G</code>, <code>T</code> or <code>P</code> are
valid.</p>
<p>E.g. <code>rclone ls remote: --min-size 50k</code> lists files on
<code>remote:</code> of 50 KiB size or larger.</p>
<p>See <a href="https://rclone.org/docs/#size-option">the size option
docs</a> for more info.</p>
<h3
id="max-size---dont-transfer-any-file-larger-than-this"><code>--max-size</code>
- Don’t transfer any file larger than this</h3>
<p>Controls the maximum size file within the scope of an rclone command.
Default units are <code>KiB</code> but abbreviations <code>K</code>,
<code>M</code>, <code>G</code>, <code>T</code> or <code>P</code> are
valid.</p>
<p>E.g. <code>rclone ls remote: --max-size 1G</code> lists files on
<code>remote:</code> of 1 GiB size or smaller.</p>
<p>See <a href="https://rclone.org/docs/#size-option">the size option
docs</a> for more info.</p>
<h3
id="max-age---dont-transfer-any-file-older-than-this"><code>--max-age</code>
- Don’t transfer any file older than this</h3>
<p>Controls the maximum age of files within the scope of an rclone
command.</p>
<p><code>--max-age</code> applies only to files and not to
directories.</p>
<p>E.g. <code>rclone ls remote: --max-age 2d</code> lists files on
<code>remote:</code> of 2 days old or less.</p>
<p>See <a href="https://rclone.org/docs/#time-option">the time option
docs</a> for valid formats.</p>
<h3
id="min-age---dont-transfer-any-file-younger-than-this"><code>--min-age</code>
- Don’t transfer any file younger than this</h3>
<p>Controls the minimum age of files within the scope of an rclone
command. (see <code>--max-age</code> for valid formats)</p>
<p><code>--min-age</code> applies only to files and not to
directories.</p>
<p>E.g. <code>rclone ls remote: --min-age 2d</code> lists files on
<code>remote:</code> of 2 days old or more.</p>
<p>See <a href="https://rclone.org/docs/#time-option">the time option
docs</a> for valid formats.</p>
<h2 id="other-flags">Other flags</h2>
<h3
id="delete-excluded---delete-files-on-dest-excluded-from-sync"><code>--delete-excluded</code>
- Delete files on dest excluded from sync</h3>
<p><strong>Important</strong> this flag is dangerous to your data - use
with <code>--dry-run</code> and <code>-v</code> first.</p>
<p>In conjunction with <code>rclone sync</code>,
<code>--delete-excluded</code> deletes any files on the destination
which are excluded from the command.</p>
<p>E.g. the scope of <code>rclone sync -i A: B:</code> can be
restricted:</p>
<pre><code>rclone --min-size 50k --delete-excluded sync A: B:</code></pre>
<p>All files on <code>B:</code> which are less than 50 KiB are deleted
because they are excluded from the rclone sync command.</p>
<h3
id="dump-filters---dump-the-filters-to-the-output"><code>--dump filters</code>
- dump the filters to the output</h3>
<p>Dumps the defined filters to standard output in regular expression
format.</p>
<p>Useful for debugging.</p>
<h2 id="exclude-directory-based-on-a-file">Exclude directory based on a
file</h2>
<p>The <code>--exclude-if-present</code> 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.</p>
<p>This flag has a priority over other filter flags.</p>
<p>E.g. for the following directory structure:</p>
<pre><code>dir1/file1
dir1/dir2/file2
dir1/dir2/dir3/file3
dir1/dir2/dir3/.ignore</code></pre>
<p>The command <code>rclone ls --exclude-if-present .ignore dir1</code>
does not list <code>dir3</code>, <code>file3</code> or
<code>.ignore</code>.</p>
<h2 id="common-pitfalls">Common pitfalls</h2>
<p>The most frequent filter support issues on the <a
href="https://forum.rclone.org/">rclone forum</a> are:</p>
<ul>
<li>Not using paths relative to the root of the remote</li>
<li>Not using <code>/</code> to match from the root of a remote</li>
<li>Not using <code>**</code> to match the contents of a directory</li>
</ul>
<h1 id="gui-experimental">GUI (Experimental)</h1>
<p>Rclone can serve a web based GUI (graphical user interface). This is
somewhat experimental at the moment so things may be subject to
change.</p>
<p>Run this command in a terminal and rclone will download and then
display the GUI in a web browser.</p>
<pre><code>rclone rcd --rc-web-gui</code></pre>
<p>This will produce logs like this and rclone needs to continue to run
to serve the GUI:</p>
<pre><code>2019/08/25 11:40:14 NOTICE: A new release for gui is present at https://github.com/rclone/rclone-webui-react/releases/download/v0.0.6/currentbuild.zip
2019/08/25 11:40:14 NOTICE: Downloading webgui binary. Please wait. [Size: 3813937, Path : /home/USER/.cache/rclone/webgui/v0.0.6.zip]
2019/08/25 11:40:16 NOTICE: Unzipping
2019/08/25 11:40:16 NOTICE: Serving remote control on http://127.0.0.1:5572/</code></pre>
<p>This assumes you are running rclone locally on your machine. It is
possible to separate the rclone and the GUI - see below for details.</p>
<p>If you wish to check for updates then you can add
<code>--rc-web-gui-update</code> to the command line.</p>
<p>If you find your GUI broken, you may force it to update by add
<code>--rc-web-gui-force-update</code>.</p>
<p>By default, rclone will open your browser. Add
<code>--rc-web-gui-no-open-browser</code> to disable this feature.</p>
<h2 id="using-the-gui">Using the GUI</h2>
<p>Once the GUI opens, you will be looking at the dashboard which has an
overall overview.</p>
<p>On the left hand side you will see a series of view buttons you can
click on:</p>
<ul>
<li>Dashboard - main overview</li>
<li>Configs - examine and create new configurations</li>
<li>Explorer - view, download and upload files to the cloud storage
systems</li>
<li>Backend - view or alter the backend config</li>
<li>Log out</li>
</ul>
<p>(More docs and walkthrough video to come!)</p>
<h2 id="how-it-works">How it works</h2>
<p>When you run the <code>rclone rcd --rc-web-gui</code> this is what
happens</p>
<ul>
<li>Rclone starts but only runs the remote control API (“rc”).</li>
<li>The API is bound to localhost with an auto-generated username and
password.</li>
<li>If the API bundle is missing then rclone will download it.</li>
<li>rclone will start serving the files from the API bundle over the
same port as the API</li>
<li>rclone will open the browser with a <code>login_token</code> so it
can log straight in.</li>
</ul>
<h2 id="advanced-use">Advanced use</h2>
<p>The <code>rclone rcd</code> may use any of the <a
href="https://rclone.org/rc/#supported-parameters">flags documented on
the rc page</a>.</p>
<p>The flag <code>--rc-web-gui</code> is shorthand for</p>
<ul>
<li>Download the web GUI if necessary</li>
<li>Check we are using some authentication</li>
<li><code>--rc-user gui</code></li>
<li><code>--rc-pass <random password></code></li>
<li><code>--rc-serve</code></li>
</ul>
<p>These flags can be overridden as desired.</p>
<p>See also the <a href="https://rclone.org/commands/rclone_rcd/">rclone
rcd documentation</a>.</p>
<h3 id="example-running-a-public-gui">Example: Running a public GUI</h3>
<p>For example the GUI could be served on a public port over SSL using
an htpasswd file using the following flags:</p>
<ul>
<li><code>--rc-web-gui</code></li>
<li><code>--rc-addr :443</code></li>
<li><code>--rc-htpasswd /path/to/htpasswd</code></li>
<li><code>--rc-cert /path/to/ssl.crt</code></li>
<li><code>--rc-key /path/to/ssl.key</code></li>
</ul>
<h3 id="example-running-a-gui-behind-a-proxy">Example: Running a GUI
behind a proxy</h3>
<p>If you want to run the GUI behind a proxy at <code>/rclone</code> you
could use these flags:</p>
<ul>
<li><code>--rc-web-gui</code></li>
<li><code>--rc-baseurl rclone</code></li>
<li><code>--rc-htpasswd /path/to/htpasswd</code></li>
</ul>
<p>Or instead of htpasswd if you just want a single user and
password:</p>
<ul>
<li><code>--rc-user me</code></li>
<li><code>--rc-pass mypassword</code></li>
</ul>
<h2 id="project">Project</h2>
<p>The GUI is being developed in the: <a
href="https://github.com/rclone/rclone-webui-react">rclone/rclone-webui-react
repository</a>.</p>
<p>Bug reports and contributions are very welcome :-)</p>
<p>If you have questions then please ask them on the <a
href="https://forum.rclone.org/">rclone forum</a>.</p>
<h1 id="remote-controlling-rclone-with-its-api">Remote controlling
rclone with its API</h1>
<p>If rclone is run with the <code>--rc</code> flag then it starts an
HTTP server which can be used to remote control rclone using its
API.</p>
<p>You can either use the <a href="#api-rc">rc</a> command to access the
API or <a href="#api-http">use HTTP directly</a>.</p>
<p>If you just want to run a remote control then see the <a
href="https://rclone.org/commands/rclone_rcd/">rcd</a> command.</p>
<h2 id="supported-parameters">Supported parameters</h2>
<h3 id="rc">–rc</h3>
<p>Flag to start the http server listen on remote requests</p>
<h3 id="rc-addrip">–rc-addr=IP</h3>
<p>IPaddress:Port or :Port to bind server to. (default
“localhost:5572”)</p>
<h3 id="rc-certkey">–rc-cert=KEY</h3>
<p>SSL PEM key (concatenation of certificate and CA certificate)</p>
<h3 id="rc-client-capath">–rc-client-ca=PATH</h3>
<p>Client certificate authority to verify clients with</p>
<h3 id="rc-htpasswdpath">–rc-htpasswd=PATH</h3>
<p>htpasswd file - if not provided no authentication is done</p>
<h3 id="rc-keypath">–rc-key=PATH</h3>
<p>SSL PEM Private key</p>
<h3 id="rc-max-header-bytesvalue">–rc-max-header-bytes=VALUE</h3>
<p>Maximum size of request header (default 4096)</p>
<h3 id="rc-min-tls-versionvalue">–rc-min-tls-version=VALUE</h3>
<p>The minimum TLS version that is acceptable. Valid values are
“tls1.0”, “tls1.1”, “tls1.2” and “tls1.3” (default “tls1.0”).</p>
<h3 id="rc-uservalue">–rc-user=VALUE</h3>
<p>User name for authentication.</p>
<h3 id="rc-passvalue">–rc-pass=VALUE</h3>
<p>Password for authentication.</p>
<h3 id="rc-realmvalue">–rc-realm=VALUE</h3>
<p>Realm for authentication (default “rclone”)</p>
<h3
id="rc-server-read-timeoutduration">–rc-server-read-timeout=DURATION</h3>
<p>Timeout for server reading data (default 1h0m0s)</p>
<h3
id="rc-server-write-timeoutduration">–rc-server-write-timeout=DURATION</h3>
<p>Timeout for server writing data (default 1h0m0s)</p>
<h3 id="rc-serve">–rc-serve</h3>
<p>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</p>
<p>Default Off.</p>
<h3 id="rc-files-pathtodirectory">–rc-files /path/to/directory</h3>
<p>Path to local files to serve on the HTTP server.</p>
<p>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.</p>
<p>If <code>--rc-user</code> or <code>--rc-pass</code> is set then the
URL that is opened will have the authorization in the URL in the
<code>http://user:pass@localhost/</code> style.</p>
<p>Default Off.</p>
<h3 id="rc-enable-metrics">–rc-enable-metrics</h3>
<p>Enable OpenMetrics/Prometheus compatible endpoint at
<code>/metrics</code>.</p>
<p>Default Off.</p>
<h3 id="rc-web-gui">–rc-web-gui</h3>
<p>Set this flag to serve the default web gui on the same port as
rclone.</p>
<p>Default Off.</p>
<h3 id="rc-allow-origin">–rc-allow-origin</h3>
<p>Set the allowed Access-Control-Allow-Origin for rc requests.</p>
<p>Can be used with –rc-web-gui if the rclone is running on different IP
than the web-gui.</p>
<p>Default is IP address on which rc is running.</p>
<h3 id="rc-web-fetch-url">–rc-web-fetch-url</h3>
<p>Set the URL to fetch the rclone-web-gui files from.</p>
<p>Default
https://api.github.com/repos/rclone/rclone-webui-react/releases/latest.</p>
<h3 id="rc-web-gui-update">–rc-web-gui-update</h3>
<p>Set this flag to check and update rclone-webui-react from the
rc-web-fetch-url.</p>
<p>Default Off.</p>
<h3 id="rc-web-gui-force-update">–rc-web-gui-force-update</h3>
<p>Set this flag to force update rclone-webui-react from the
rc-web-fetch-url.</p>
<p>Default Off.</p>
<h3 id="rc-web-gui-no-open-browser">–rc-web-gui-no-open-browser</h3>
<p>Set this flag to disable opening browser automatically when using
web-gui.</p>
<p>Default Off.</p>
<h3
id="rc-job-expire-durationduration">–rc-job-expire-duration=DURATION</h3>
<p>Expire finished async jobs older than DURATION (default 60s).</p>
<h3
id="rc-job-expire-intervalduration">–rc-job-expire-interval=DURATION</h3>
<p>Interval duration to check for expired async jobs (default 10s).</p>
<h3 id="rc-no-auth">–rc-no-auth</h3>
<p>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 <code>operations/list</code> is denied as it involved
creating a remote as is <code>sync/copy</code>.</p>
<p>If this is set then no authorisation will be required on the server
to use these methods. The alternative is to use <code>--rc-user</code>
and <code>--rc-pass</code> and use these credentials in the request.</p>
<p>Default Off.</p>
<h3 id="rc-baseurl">–rc-baseurl</h3>
<p>Prefix for URLs.</p>
<p>Default is root</p>
<h3 id="rc-template">–rc-template</h3>
<p>User-specified template.</p>
<h2 id="api-rc">Accessing the remote control via the rclone rc
command</h2>
<p>Rclone itself implements the remote control protocol in its
<code>rclone rc</code> command.</p>
<p>You can use it like this</p>
<pre><code>$ rclone rc rc/noop param1=one param2=two
{
"param1": "one",
"param2": "two"
}</code></pre>
<p>Run <code>rclone rc</code> on its own to see the help for the
installed remote control commands.</p>
<h2 id="json-input">JSON input</h2>
<p><code>rclone rc</code> also supports a <code>--json</code> flag which
can be used to send more complicated input parameters.</p>
<pre><code>$ 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
}
}</code></pre>
<p>If the parameter being passed is an object then it can be passed as a
JSON string rather than using the <code>--json</code> flag which
simplifies the command line.</p>
<pre><code>rclone rc operations/list fs=/tmp remote=test opt='{"showHash": true}'</code></pre>
<p>Rather than</p>
<pre><code>rclone rc operations/list --json '{"fs": "/tmp", "remote": "test", "opt": {"showHash": true}}'</code></pre>
<h2 id="special-parameters">Special parameters</h2>
<p>The rc interface supports some special parameters which apply to
<strong>all</strong> commands. These start with <code>_</code> to show
they are different.</p>
<h3 id="running-asynchronous-jobs-with-_async-true">Running asynchronous
jobs with _async = true</h3>
<p>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.</p>
<p>If <code>_async</code> has a true value when supplied to an rc call
then it will return immediately with a job id and the task will be run
in the background. The <code>job/status</code> 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.</p>
<p>It is recommended that potentially long running jobs,
e.g. <code>sync/sync</code>, <code>sync/copy</code>,
<code>sync/move</code>, <code>operations/purge</code> are run with the
<code>_async</code> flag to avoid any potential problems with the HTTP
request and response timing out.</p>
<p>Starting a job with the <code>_async</code> flag:</p>
<pre><code>$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop
{
"jobid": 2
}</code></pre>
<p>Query the status to see if the job has finished. For more information
on the meaning of these return parameters see the
<code>job/status</code> call.</p>
<pre><code>$ rclone rc --json '{ "jobid":2 }' job/status
{
"duration": 0.000124163,
"endTime": "2018-10-27T11:38:07.911245881+01:00",
"error": "",
"finished": true,
"id": 2,
"output": {
"_async": true,
"p1": [
1,
"2",
null,
4
],
"p2": {
"a": 1,
"b": 2
}
},
"startTime": "2018-10-27T11:38:07.911121728+01:00",
"success": true
}</code></pre>
<p><code>job/list</code> can be used to show the running or recently
completed jobs</p>
<pre><code>$ rclone rc job/list
{
"jobids": [
2
]
}</code></pre>
<h3 id="setting-config-flags-with-_config">Setting config flags with
_config</h3>
<p>If you wish to set config (the equivalent of the global flags) for
the duration of an rc call only then pass in the <code>_config</code>
parameter.</p>
<p>This should be in the same format as the <code>config</code> key
returned by <a href="#options-get">options/get</a>.</p>
<p>For example, if you wished to run a sync with the
<code>--checksum</code> parameter, you would pass this parameter in your
JSON blob.</p>
<pre><code>"_config":{"CheckSum": true}</code></pre>
<p>If using <code>rclone rc</code> this could be passed as</p>
<pre><code>rclone rc operations/sync ... _config='{"CheckSum":
Showing 512.00 KB of 1.93 MB. Use Edit/Download for full content.
Directory Contents
Dirs: 0 × Files: 5