This implements a remote control protocol activated with the --rc flag and a new command `rclone rc` to use that interface. Still to do * docs - need finishing * tests
2.7 KiB
title | description | date |
---|---|---|
Remote Control | Remote controlling rclone | 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.
FIXME describe other flags
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
Accessing the remote control via HTTP
Rclone implements a simple HTTP based protocol.
Each endpoint takes an JSON object and returns a JSON object or an error. The JSON objects are essentially a map of string names to values.
All calls must made using POST.
The input objects can be supplied using URL parameters, POST
parameters or by supplying "Content-Type: application/json" and a JSON
blob in the body. There are examples of these below using curl
.
The response will be a JSON blob in the body of the response. This is formatted to be reasonably human readable.
If an error occurs then there will be an HTTP error status (usually 400) and the body of the response will contain a JSON encoded error object.
Using POST with URL parameters only
curl -X POST 'http://localhost:5572/rc/noop/?potato=1&sausage=2'
Response
{
"potato": "1",
"sausage": "2"
}
Here is what an error response looks like:
curl -X POST 'http://localhost:5572/rc/error/?potato=1&sausage=2'
{
"error": "arbitrary error on input map[potato:1 sausage:2]",
"input": {
"potato": "1",
"sausage": "2"
}
}
Note that curl doesn't return errors to the shell unless you use the -f
option
$ curl -f -X POST 'http://localhost:5572/rc/error/?potato=1&sausage=2'
curl: (22) The requested URL returned error: 400 Bad Request
$ echo $?
22
Using POST with a form
curl --data "potato=1" --data "sausage=2" http://localhost:5572/rc/noop/
Response
{
"potato": "1",
"sausage": "2"
}
Note that you can combine these with URL parameters too with the POST parameters taking precedence.
curl --data "potato=1" --data "sausage=2" "http://localhost:5572/rc/noop/?rutabaga=3&sausage=4"
Response
{
"potato": "1",
"rutabaga": "3",
"sausage": "4"
}
Using POST with a JSON blob
curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' http://localhost:5572/rc/noop/
response
{
"password": "xyz",
"username": "xyz"
}
This can be combined with URL parameters too if required. The JSON blob takes precedence.
curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' 'http://localhost:5572/rc/noop/?rutabaga=3&potato=4'
{
"potato": 2,
"rutabaga": "3",
"sausage": 1
}