title: "Remote Control" description: "Remote controlling rclone" date: "2018-03-05"
Remote controlling rclone
If rclone is run with the --rc flag then it starts an http server
which can be used to remote control rclone.
If you just want to run a remote control then see the rcd command.
NB this is experimental and everything here is subject to change!
Supported parameters
--rc
Flag to start the http server listen on remote requests
--rc-addr=IP
IPaddress:Port or :Port to bind server to. (default "localhost:5572")
--rc-cert=KEY
SSL PEM key (concatenation of certificate and CA certificate)
--rc-client-ca=PATH
Client certificate authority to verify clients with
--rc-htpasswd=PATH
htpasswd file - if not provided no authentication is done
--rc-key=PATH
SSL PEM Private key
--rc-max-header-bytes=VALUE
Maximum size of request header (default 4096)
--rc-user=VALUE
User name for authentication.
--rc-pass=VALUE
Password for authentication.
--rc-realm=VALUE
Realm for authentication (default "rclone")
--rc-server-read-timeout=DURATION
Timeout for server reading data (default 1h0m0s)
--rc-server-write-timeout=DURATION
Timeout for server writing data (default 1h0m0s)
--rc-serve
Enable the serving of remote objects via the HTTP interface. This means objects will be accessible at http://127.0.0.1:5572/ by default, so you can browse to http://127.0.0.1:5572/ or http://127.0.0.1:5572/* to see a listing of the remotes. Objects may be requested from remotes using this syntax http://127.0.0.1:5572/[remote:path]/path/to/object
Default Off.
--rc-files /path/to/directory
Path to local files to serve on the HTTP server.
If this is set then rclone will serve the files in that directory. It will also open the root in the web browser if specified. This is for implementing browser based GUIs for rclone functions.
If --rc-user or --rc-pass is set then the URL that is opened will
have the authorization in the URL in the http://user:pass@localhost/
style.
Default Off.
--rc-no-auth
By default rclone will require authorisation to have been set up on
the rc interface in order to use any methods which access any rclone
remotes. Eg operations/list is denied as it involved creating a
remote as is sync/copy.
If this is set then no authorisation will be required on the server to
use these methods. The alternative is to use --rc-user and
--rc-pass and use these credentials in the request.
Default Off.
Accessing the remote control via the rclone rc command
Rclone itself implements the remote control protocol in its rclone rc command.
You can use it like this
$ rclone rc rc/noop param1=one param2=two
{
"param1": "one",
"param2": "two"
}
Run rclone rc on its own to see the help for the installed remote
control commands.
rclone rc also supports a --json flag which can be used to send
more complicated input parameters.
$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 } }' rc/noop
{
"p1": [
1,
"2",
null,
4
],
"p2": {
"a": 1,
"b": 2
}
}
Special parameters
The rc interface supports some special parameters which apply to
all commands. These start with _ to show they are different.
Running asynchronous jobs with _async = true
If _async has a true value when supplied to an rc call then it will
return immediately with a job id and the task will be run in the
background. The job/status call can be used to get information of
the background job. The job can be queried for up to 1 minute after
it has finished.
It is recommended that potentially long running jobs, eg sync/sync,
sync/copy, sync/move, operations/purge are run with the _async
flag to avoid any potential problems with the HTTP request and
response timing out.
Starting a job with the _async flag:
$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop
{
"jobid": 2
}
Query the status to see if the job has finished. For more information
on the meaning of these return parameters see the job/status call.
$ rclone rc --json '{ "jobid":2 }' job/status
{
"duration": 0.000124163,
"endTime": "2018-10-27T11:38:07.911245881+01:00",
"error": "",
"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
}
job/list can be used to show the running or recently completed jobs
$ rclone rc job/list
{
"jobids": [
2
]
}
Supported commands
cache/expire: Purge a remote from cache
Purge a remote from the cache backend. Supports either a directory or a file. Params:
- remote = path to remote (required)
- withData = true/false to delete cached data (chunks) as well (optional)
Eg
rclone rc cache/expire remote=path/to/sub/folder/
rclone rc cache/expire remote=/ withData=true
cache/fetch: Fetch file chunks
Ensure the specified file chunks are cached on disk.
The chunks= parameter specifies the file chunks to check. It takes a comma separated list of array slice indices. The slice indices are similar to Python slices: start[:end]
start is the 0 based chunk number from the beginning of the file to fetch inclusive. end is 0 based chunk number from the beginning of the file to fetch exclisive. Both values can be negative, in which case they count from the back of the file. The value "-5:" represents the last 5 chunks of a file.
Some valid examples are: ":5,-5:" -> the first and last five chunks "0,-2" -> the first and the second last chunk "0:10" -> the first ten chunks
Any parameter with a key that starts with "file" can be used to specify files to fetch, eg
rclone rc cache/fetch chunks=0 file=hello file2=home/goodbye
File names will automatically be encrypted when the a crypt remote is used on top of the cache.
cache/stats: Get cache stats
Show statistics for the cache remote.
config/create: create the config for a remote.
This takes the following parameters
- name - name of remote
- type - type of new remote
- type - type of the new remote
See the config create command command for more information on the above.
Authentication is required for this call.
config/delete: Delete a remote in the config file.
Parameters:
- name - name of remote to delete
See the config delete command command for more information on the above.
Authentication is required for this call.
config/dump: Dumps the config file.
Returns a JSON object:
- key: value
Where keys are remote names and values are the config parameters.
See the config dump command command for more information on the above.
Authentication is required for this call.
config/get: Get a remote in the config file.
Parameters:
- name - name of remote to get
See the config dump command command for more information on the above.
Authentication is required for this call.
config/listremotes: Lists the remotes in the config file.
Returns
- remotes - array of remote names
See the listremotes command command for more information on the above.
Authentication is required for this call.
config/password: password the config for a remote.
This takes the following parameters
- name - name of remote
- type - type of new remote
See the config password command command for more information on the above.
Authentication is required for this call.
config/providers: Shows how providers are configured in the config file.
Returns a JSON object:
- providers - array of objects
See the config providers command command for more information on the above.
Authentication is required for this call.
config/update: update the config for a remote.
This takes the following parameters
- name - name of remote
- type - type of new remote
See the config update command command for more information on the above.
Authentication is required for this call.
core/bwlimit: Set the bandwidth limit.
This sets the bandwidth limit to that passed in.
Eg
rclone rc core/bwlimit rate=1M
rclone rc core/bwlimit rate=off
The format of the parameter is exactly the same as passed to --bwlimit except only one bandwidth may be specified.
core/gc: Runs a garbage collection.
This tells the go runtime to do a garbage collection run. It isn't necessary to call this normally, but it can be useful for debugging memory problems.
core/memstats: Returns the memory statistics
This returns the memory statistics of the running program. What the values mean are explained in the go docs: https://golang.org/pkg/runtime/#MemStats
The most interesting values for most people are:
- HeapAlloc: This is the amount of memory rclone is actually using
- HeapSys: This is the amount of memory rclone has obtained from the OS
- Sys: this is the total amount of memory requested from the OS
- It is virtual memory so may include unused memory
core/obscure: Obscures a string passed in.
Pass a clear string and rclone will obscure it for the config file:
- clear - string
Returns
- obscured - string
core/pid: Return PID of current process
This returns PID of current process. Useful for stopping rclone process.
core/stats: Returns stats about current transfers.
This returns all available stats
rclone rc core/stats
Returns the following values:
{
"speed": average speed in bytes/sec since start of the process,
"bytes": total transferred bytes since the start of the process,
"errors": number of errors,
"fatalError": whether there has been at least one FatalError,
"retryError": whether there has been at least one non-NoRetryError,
"checks": number of checked files,
"transfers": number of transferred files,
"deletes" : number of deleted files,
"elapsedTime": time in seconds since the start of the process,
"lastError": last occurred error,
"transferring": an array of currently active file transfers:
[
{
"bytes": total transferred bytes for this file,
"eta": estimated time in seconds until file transfer completion
"name": name of the file,
"percentage": progress of the file transfer in percent,
"speed": speed in bytes/sec,
"speedAvg": speed in bytes/sec as an exponentially weighted moving average,
"size": size of the file in bytes
}
],
"checking": an array of names of currently active file checks
[]
}
Values for "transferring", "checking" and "lastError" are only assigned if data is available. The value for "eta" is null if an eta cannot be determined.
core/version: Shows the current version of rclone and the go runtime.
This shows the current version of go and the go runtime
- version - rclone version, eg "v1.44"
- decomposed - version number as [major, minor, patch, subpatch]
- note patch and subpatch will be 999 for a git compiled version
- isGit - boolean - true if this was compiled from the git version
- os - OS in use as according to Go
- arch - cpu architecture in use according to Go
- goVersion - version of Go runtime in use
job/list: Lists the IDs of the running jobs
Parameters - None
Results
- jobids - array of integer job ids
job/status: Reads the status of the job ID
Parameters
- jobid - id of the job (integer)
Results
- finished - boolean
- duration - time in seconds that the job ran for
- endTime - time the job finished (eg "2018-10-26T18:50:20.528746884+01:00")
- error - error from the job or empty string for no error
- finished - boolean whether the job has finished or not
- id - as passed in above
- startTime - time the job started (eg "2018-10-26T18:50:20.528336039+01:00")
- success - boolean - true for success false otherwise
- output - output of the job as would have been returned if called synchronously
operations/about: Return the space used on the remote
This takes the following parameters
- fs - a remote name string eg "drive:"
- remote - a path within that remote eg "dir"
The result is as returned from rclone about --json
Authentication is required for this call.
operations/cleanup: Remove trashed files in the remote or path
This takes the following parameters
- fs - a remote name string eg "drive:"
See the cleanup command command for more information on the above.
Authentication is required for this call.
operations/copyfile: Copy a file from source remote to destination remote
This takes the following parameters
- srcFs - a remote name string eg "drive:" for the source
- srcRemote - a path within that remote eg "file.txt" for the source
- dstFs - a remote name string eg "drive2:" for the destination
- dstRemote - a path within that remote eg "file2.txt" for the destination
This returns
- jobid - ID of async job to query with job/status
Authentication is required for this call.
operations/copyurl: Copy the URL to the object
This takes the following parameters
- fs - a remote name string eg "drive:"
- remote - a path within that remote eg "dir"
- url - string, URL to read from
See the copyurl command command for more information on the above.
Authentication is required for this call.
operations/delete: Remove files in the path
This takes the following parameters
Lines 1–500 of 957. Load more
--- title: "Remote Control" description: "Remote controlling rclone" date: "2018-03-05" --- # Remote controlling rclone # If rclone is run with the `--rc` flag then it starts an http server which can be used to remote control rclone. If you just want to run a remote control then see the [rcd command](/commands/rclone_rcd/). **NB** this is experimental and everything here is subject to change! ## Supported parameters ### --rc Flag to start the http server listen on remote requests ### --rc-addr=IP IPaddress:Port or :Port to bind server to. (default "localhost:5572") ### --rc-cert=KEY SSL PEM key (concatenation of certificate and CA certificate) ### --rc-client-ca=PATH Client certificate authority to verify clients with ### --rc-htpasswd=PATH htpasswd file - if not provided no authentication is done ### --rc-key=PATH SSL PEM Private key ### --rc-max-header-bytes=VALUE Maximum size of request header (default 4096) ### --rc-user=VALUE User name for authentication. ### --rc-pass=VALUE Password for authentication. ### --rc-realm=VALUE Realm for authentication (default "rclone") ### --rc-server-read-timeout=DURATION Timeout for server reading data (default 1h0m0s) ### --rc-server-write-timeout=DURATION Timeout for server writing data (default 1h0m0s) ### --rc-serve Enable the serving of remote objects via the HTTP interface. This means objects will be accessible at http://127.0.0.1:5572/ by default, so you can browse to http://127.0.0.1:5572/ or http://127.0.0.1:5572/* to see a listing of the remotes. Objects may be requested from remotes using this syntax http://127.0.0.1:5572/[remote:path]/path/to/object Default Off. ### --rc-files /path/to/directory Path to local files to serve on the HTTP server. If this is set then rclone will serve the files in that directory. It will also open the root in the web browser if specified. This is for implementing browser based GUIs for rclone functions. If `--rc-user` or `--rc-pass` is set then the URL that is opened will have the authorization in the URL in the `http://user:pass@localhost/` style. Default Off. ### --rc-no-auth By default rclone will require authorisation to have been set up on the rc interface in order to use any methods which access any rclone remotes. Eg `operations/list` is denied as it involved creating a remote as is `sync/copy`. If this is set then no authorisation will be required on the server to use these methods. The alternative is to use `--rc-user` and `--rc-pass` and use these credentials in the request. Default Off. ## Accessing the remote control via the rclone rc command Rclone itself implements the remote control protocol in its `rclone rc` command. You can use it like this ``` $ rclone rc rc/noop param1=one param2=two { "param1": "one", "param2": "two" } ``` Run `rclone rc` on its own to see the help for the installed remote control commands. `rclone rc` also supports a `--json` flag which can be used to send more complicated input parameters. ``` $ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 } }' rc/noop { "p1": [ 1, "2", null, 4 ], "p2": { "a": 1, "b": 2 } } ``` ## Special parameters The rc interface supports some special parameters which apply to **all** commands. These start with `_` to show they are different. ### Running asynchronous jobs with _async = true If `_async` has a true value when supplied to an rc call then it will return immediately with a job id and the task will be run in the background. The `job/status` call can be used to get information of the background job. The job can be queried for up to 1 minute after it has finished. It is recommended that potentially long running jobs, eg `sync/sync`, `sync/copy`, `sync/move`, `operations/purge` are run with the `_async` flag to avoid any potential problems with the HTTP request and response timing out. Starting a job with the `_async` flag: ``` $ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop { "jobid": 2 } ``` Query the status to see if the job has finished. For more information on the meaning of these return parameters see the `job/status` call. ``` $ rclone rc --json '{ "jobid":2 }' job/status { "duration": 0.000124163, "endTime": "2018-10-27T11:38:07.911245881+01:00", "error": "", "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 } ``` `job/list` can be used to show the running or recently completed jobs ``` $ rclone rc job/list { "jobids": [ 2 ] } ``` ## Supported commands <!--- autogenerated start - run make rcdocs - don't edit here --> ### cache/expire: Purge a remote from cache Purge a remote from the cache backend. Supports either a directory or a file. Params: - remote = path to remote (required) - withData = true/false to delete cached data (chunks) as well (optional) Eg rclone rc cache/expire remote=path/to/sub/folder/ rclone rc cache/expire remote=/ withData=true ### cache/fetch: Fetch file chunks Ensure the specified file chunks are cached on disk. The chunks= parameter specifies the file chunks to check. It takes a comma separated list of array slice indices. The slice indices are similar to Python slices: start[:end] start is the 0 based chunk number from the beginning of the file to fetch inclusive. end is 0 based chunk number from the beginning of the file to fetch exclisive. Both values can be negative, in which case they count from the back of the file. The value "-5:" represents the last 5 chunks of a file. Some valid examples are: ":5,-5:" -> the first and last five chunks "0,-2" -> the first and the second last chunk "0:10" -> the first ten chunks Any parameter with a key that starts with "file" can be used to specify files to fetch, eg rclone rc cache/fetch chunks=0 file=hello file2=home/goodbye File names will automatically be encrypted when the a crypt remote is used on top of the cache. ### cache/stats: Get cache stats Show statistics for the cache remote. ### config/create: create the config for a remote. This takes the following parameters - name - name of remote - type - type of new remote - type - type of the new remote See the [config create command](/commands/rclone_config_create/) command for more information on the above. Authentication is required for this call. ### config/delete: Delete a remote in the config file. Parameters: - name - name of remote to delete See the [config delete command](/commands/rclone_config_delete/) command for more information on the above. Authentication is required for this call. ### config/dump: Dumps the config file. Returns a JSON object: - key: value Where keys are remote names and values are the config parameters. See the [config dump command](/commands/rclone_config_dump/) command for more information on the above. Authentication is required for this call. ### config/get: Get a remote in the config file. Parameters: - name - name of remote to get See the [config dump command](/commands/rclone_config_dump/) command for more information on the above. Authentication is required for this call. ### config/listremotes: Lists the remotes in the config file. Returns - remotes - array of remote names See the [listremotes command](/commands/rclone_listremotes/) command for more information on the above. Authentication is required for this call. ### config/password: password the config for a remote. This takes the following parameters - name - name of remote - type - type of new remote See the [config password command](/commands/rclone_config_password/) command for more information on the above. Authentication is required for this call. ### config/providers: Shows how providers are configured in the config file. Returns a JSON object: - providers - array of objects See the [config providers command](/commands/rclone_config_providers/) command for more information on the above. Authentication is required for this call. ### config/update: update the config for a remote. This takes the following parameters - name - name of remote - type - type of new remote See the [config update command](/commands/rclone_config_update/) command for more information on the above. Authentication is required for this call. ### core/bwlimit: Set the bandwidth limit. This sets the bandwidth limit to that passed in. Eg rclone rc core/bwlimit rate=1M rclone rc core/bwlimit rate=off The format of the parameter is exactly the same as passed to --bwlimit except only one bandwidth may be specified. ### core/gc: Runs a garbage collection. This tells the go runtime to do a garbage collection run. It isn't necessary to call this normally, but it can be useful for debugging memory problems. ### core/memstats: Returns the memory statistics This returns the memory statistics of the running program. What the values mean are explained in the go docs: https://golang.org/pkg/runtime/#MemStats The most interesting values for most people are: * HeapAlloc: This is the amount of memory rclone is actually using * HeapSys: This is the amount of memory rclone has obtained from the OS * Sys: this is the total amount of memory requested from the OS * It is virtual memory so may include unused memory ### core/obscure: Obscures a string passed in. Pass a clear string and rclone will obscure it for the config file: - clear - string Returns - obscured - string ### core/pid: Return PID of current process This returns PID of current process. Useful for stopping rclone process. ### core/stats: Returns stats about current transfers. This returns all available stats rclone rc core/stats Returns the following values: ``` { "speed": average speed in bytes/sec since start of the process, "bytes": total transferred bytes since the start of the process, "errors": number of errors, "fatalError": whether there has been at least one FatalError, "retryError": whether there has been at least one non-NoRetryError, "checks": number of checked files, "transfers": number of transferred files, "deletes" : number of deleted files, "elapsedTime": time in seconds since the start of the process, "lastError": last occurred error, "transferring": an array of currently active file transfers: [ { "bytes": total transferred bytes for this file, "eta": estimated time in seconds until file transfer completion "name": name of the file, "percentage": progress of the file transfer in percent, "speed": speed in bytes/sec, "speedAvg": speed in bytes/sec as an exponentially weighted moving average, "size": size of the file in bytes } ], "checking": an array of names of currently active file checks [] } ``` Values for "transferring", "checking" and "lastError" are only assigned if data is available. The value for "eta" is null if an eta cannot be determined. ### core/version: Shows the current version of rclone and the go runtime. This shows the current version of go and the go runtime - version - rclone version, eg "v1.44" - decomposed - version number as [major, minor, patch, subpatch] - note patch and subpatch will be 999 for a git compiled version - isGit - boolean - true if this was compiled from the git version - os - OS in use as according to Go - arch - cpu architecture in use according to Go - goVersion - version of Go runtime in use ### job/list: Lists the IDs of the running jobs Parameters - None Results - jobids - array of integer job ids ### job/status: Reads the status of the job ID Parameters - jobid - id of the job (integer) Results - finished - boolean - duration - time in seconds that the job ran for - endTime - time the job finished (eg "2018-10-26T18:50:20.528746884+01:00") - error - error from the job or empty string for no error - finished - boolean whether the job has finished or not - id - as passed in above - startTime - time the job started (eg "2018-10-26T18:50:20.528336039+01:00") - success - boolean - true for success false otherwise - output - output of the job as would have been returned if called synchronously ### operations/about: Return the space used on the remote This takes the following parameters - fs - a remote name string eg "drive:" - remote - a path within that remote eg "dir" The result is as returned from rclone about --json Authentication is required for this call. ### operations/cleanup: Remove trashed files in the remote or path This takes the following parameters - fs - a remote name string eg "drive:" See the [cleanup command](/commands/rclone_cleanup/) command for more information on the above. Authentication is required for this call. ### operations/copyfile: Copy a file from source remote to destination remote This takes the following parameters - srcFs - a remote name string eg "drive:" for the source - srcRemote - a path within that remote eg "file.txt" for the source - dstFs - a remote name string eg "drive2:" for the destination - dstRemote - a path within that remote eg "file2.txt" for the destination This returns - jobid - ID of async job to query with job/status Authentication is required for this call. ### operations/copyurl: Copy the URL to the object This takes the following parameters - fs - a remote name string eg "drive:" - remote - a path within that remote eg "dir" - url - string, URL to read from See the [copyurl command](/commands/rclone_copyurl/) command for more information on the above. Authentication is required for this call. ### operations/delete: Remove files in the path This takes the following parameters