86e5a35491
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
145 lines
2.7 KiB
Markdown
145 lines
2.7 KiB
Markdown
---
|
|
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.
|
|
|
|
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
|
|
}
|
|
```
|