github.com/ncw/rclone@v1.48.1-0.20190724201158-a35aa1360e3e/docs/content/rc.md (about) 1 --- 2 title: "Remote Control" 3 description: "Remote controlling rclone" 4 date: "2018-03-05" 5 --- 6 7 # Remote controlling rclone # 8 9 If rclone is run with the `--rc` flag then it starts an http server 10 which can be used to remote control rclone. 11 12 If you just want to run a remote control then see the [rcd command](/commands/rclone_rcd/). 13 14 **NB** this is experimental and everything here is subject to change! 15 16 ## Supported parameters 17 18 ### --rc 19 20 Flag to start the http server listen on remote requests 21 22 ### --rc-addr=IP 23 24 IPaddress:Port or :Port to bind server to. (default "localhost:5572") 25 26 ### --rc-cert=KEY 27 SSL PEM key (concatenation of certificate and CA certificate) 28 29 ### --rc-client-ca=PATH 30 Client certificate authority to verify clients with 31 32 ### --rc-htpasswd=PATH 33 34 htpasswd file - if not provided no authentication is done 35 36 ### --rc-key=PATH 37 38 SSL PEM Private key 39 40 ### --rc-max-header-bytes=VALUE 41 42 Maximum size of request header (default 4096) 43 44 ### --rc-user=VALUE 45 46 User name for authentication. 47 48 ### --rc-pass=VALUE 49 50 Password for authentication. 51 52 ### --rc-realm=VALUE 53 54 Realm for authentication (default "rclone") 55 56 ### --rc-server-read-timeout=DURATION 57 58 Timeout for server reading data (default 1h0m0s) 59 60 ### --rc-server-write-timeout=DURATION 61 62 Timeout for server writing data (default 1h0m0s) 63 64 ### --rc-serve 65 66 Enable the serving of remote objects via the HTTP interface. This 67 means objects will be accessible at http://127.0.0.1:5572/ by default, 68 so you can browse to http://127.0.0.1:5572/ or http://127.0.0.1:5572/* 69 to see a listing of the remotes. Objects may be requested from 70 remotes using this syntax http://127.0.0.1:5572/[remote:path]/path/to/object 71 72 Default Off. 73 74 ### --rc-files /path/to/directory 75 76 Path to local files to serve on the HTTP server. 77 78 If this is set then rclone will serve the files in that directory. It 79 will also open the root in the web browser if specified. This is for 80 implementing browser based GUIs for rclone functions. 81 82 If `--rc-user` or `--rc-pass` is set then the URL that is opened will 83 have the authorization in the URL in the `http://user:pass@localhost/` 84 style. 85 86 Default Off. 87 88 ### --rc-job-expire-duration=DURATION 89 90 Expire finished async jobs older than DURATION (default 60s). 91 92 ### --rc-job-expire-interval=DURATION 93 94 Interval duration to check for expired async jobs (default 10s). 95 96 ### --rc-no-auth 97 98 By default rclone will require authorisation to have been set up on 99 the rc interface in order to use any methods which access any rclone 100 remotes. Eg `operations/list` is denied as it involved creating a 101 remote as is `sync/copy`. 102 103 If this is set then no authorisation will be required on the server to 104 use these methods. The alternative is to use `--rc-user` and 105 `--rc-pass` and use these credentials in the request. 106 107 Default Off. 108 109 ## Accessing the remote control via the rclone rc command 110 111 Rclone itself implements the remote control protocol in its `rclone 112 rc` command. 113 114 You can use it like this 115 116 ``` 117 $ rclone rc rc/noop param1=one param2=two 118 { 119 "param1": "one", 120 "param2": "two" 121 } 122 ``` 123 124 Run `rclone rc` on its own to see the help for the installed remote 125 control commands. 126 127 `rclone rc` also supports a `--json` flag which can be used to send 128 more complicated input parameters. 129 130 ``` 131 $ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 } }' rc/noop 132 { 133 "p1": [ 134 1, 135 "2", 136 null, 137 4 138 ], 139 "p2": { 140 "a": 1, 141 "b": 2 142 } 143 } 144 ``` 145 146 ## Special parameters 147 148 The rc interface supports some special parameters which apply to 149 **all** commands. These start with `_` to show they are different. 150 151 ### Running asynchronous jobs with _async = true 152 153 If `_async` has a true value when supplied to an rc call then it will 154 return immediately with a job id and the task will be run in the 155 background. The `job/status` call can be used to get information of 156 the background job. The job can be queried for up to 1 minute after 157 it has finished. 158 159 It is recommended that potentially long running jobs, eg `sync/sync`, 160 `sync/copy`, `sync/move`, `operations/purge` are run with the `_async` 161 flag to avoid any potential problems with the HTTP request and 162 response timing out. 163 164 Starting a job with the `_async` flag: 165 166 ``` 167 $ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop 168 { 169 "jobid": 2 170 } 171 ``` 172 173 Query the status to see if the job has finished. For more information 174 on the meaning of these return parameters see the `job/status` call. 175 176 ``` 177 $ rclone rc --json '{ "jobid":2 }' job/status 178 { 179 "duration": 0.000124163, 180 "endTime": "2018-10-27T11:38:07.911245881+01:00", 181 "error": "", 182 "finished": true, 183 "id": 2, 184 "output": { 185 "_async": true, 186 "p1": [ 187 1, 188 "2", 189 null, 190 4 191 ], 192 "p2": { 193 "a": 1, 194 "b": 2 195 } 196 }, 197 "startTime": "2018-10-27T11:38:07.911121728+01:00", 198 "success": true 199 } 200 ``` 201 202 `job/list` can be used to show the running or recently completed jobs 203 204 ``` 205 $ rclone rc job/list 206 { 207 "jobids": [ 208 2 209 ] 210 } 211 ``` 212 213 ## Supported commands 214 <!--- autogenerated start - run make rcdocs - don't edit here --> 215 ### cache/expire: Purge a remote from cache 216 217 Purge a remote from the cache backend. Supports either a directory or a file. 218 Params: 219 - remote = path to remote (required) 220 - withData = true/false to delete cached data (chunks) as well (optional) 221 222 Eg 223 224 rclone rc cache/expire remote=path/to/sub/folder/ 225 rclone rc cache/expire remote=/ withData=true 226 227 ### cache/fetch: Fetch file chunks 228 229 Ensure the specified file chunks are cached on disk. 230 231 The chunks= parameter specifies the file chunks to check. 232 It takes a comma separated list of array slice indices. 233 The slice indices are similar to Python slices: start[:end] 234 235 start is the 0 based chunk number from the beginning of the file 236 to fetch inclusive. end is 0 based chunk number from the beginning 237 of the file to fetch exclusive. 238 Both values can be negative, in which case they count from the back 239 of the file. The value "-5:" represents the last 5 chunks of a file. 240 241 Some valid examples are: 242 ":5,-5:" -> the first and last five chunks 243 "0,-2" -> the first and the second last chunk 244 "0:10" -> the first ten chunks 245 246 Any parameter with a key that starts with "file" can be used to 247 specify files to fetch, eg 248 249 rclone rc cache/fetch chunks=0 file=hello file2=home/goodbye 250 251 File names will automatically be encrypted when the a crypt remote 252 is used on top of the cache. 253 254 ### cache/stats: Get cache stats 255 256 Show statistics for the cache remote. 257 258 ### config/create: create the config for a remote. 259 260 This takes the following parameters 261 262 - name - name of remote 263 - type - type of the new remote 264 265 266 See the [config create command](/commands/rclone_config_create/) command for more information on the above. 267 268 Authentication is required for this call. 269 270 ### config/delete: Delete a remote in the config file. 271 272 Parameters: 273 - name - name of remote to delete 274 275 See the [config delete command](/commands/rclone_config_delete/) command for more information on the above. 276 277 Authentication is required for this call. 278 279 ### config/dump: Dumps the config file. 280 281 Returns a JSON object: 282 - key: value 283 284 Where keys are remote names and values are the config parameters. 285 286 See the [config dump command](/commands/rclone_config_dump/) command for more information on the above. 287 288 Authentication is required for this call. 289 290 ### config/get: Get a remote in the config file. 291 292 Parameters: 293 - name - name of remote to get 294 295 See the [config dump command](/commands/rclone_config_dump/) command for more information on the above. 296 297 Authentication is required for this call. 298 299 ### config/listremotes: Lists the remotes in the config file. 300 301 Returns 302 - remotes - array of remote names 303 304 See the [listremotes command](/commands/rclone_listremotes/) command for more information on the above. 305 306 Authentication is required for this call. 307 308 ### config/password: password the config for a remote. 309 310 This takes the following parameters 311 312 - name - name of remote 313 314 315 See the [config password command](/commands/rclone_config_password/) command for more information on the above. 316 317 Authentication is required for this call. 318 319 ### config/providers: Shows how providers are configured in the config file. 320 321 Returns a JSON object: 322 - providers - array of objects 323 324 See the [config providers command](/commands/rclone_config_providers/) command for more information on the above. 325 326 Authentication is required for this call. 327 328 ### config/update: update the config for a remote. 329 330 This takes the following parameters 331 332 - name - name of remote 333 334 335 See the [config update command](/commands/rclone_config_update/) command for more information on the above. 336 337 Authentication is required for this call. 338 339 ### core/bwlimit: Set the bandwidth limit. 340 341 This sets the bandwidth limit to that passed in. 342 343 Eg 344 345 rclone rc core/bwlimit rate=1M 346 rclone rc core/bwlimit rate=off 347 348 The format of the parameter is exactly the same as passed to --bwlimit 349 except only one bandwidth may be specified. 350 351 ### core/gc: Runs a garbage collection. 352 353 This tells the go runtime to do a garbage collection run. It isn't 354 necessary to call this normally, but it can be useful for debugging 355 memory problems. 356 357 ### core/memstats: Returns the memory statistics 358 359 This returns the memory statistics of the running program. What the values mean 360 are explained in the go docs: https://golang.org/pkg/runtime/#MemStats 361 362 The most interesting values for most people are: 363 364 * HeapAlloc: This is the amount of memory rclone is actually using 365 * HeapSys: This is the amount of memory rclone has obtained from the OS 366 * Sys: this is the total amount of memory requested from the OS 367 * It is virtual memory so may include unused memory 368 369 ### core/obscure: Obscures a string passed in. 370 371 Pass a clear string and rclone will obscure it for the config file: 372 - clear - string 373 374 Returns 375 - obscured - string 376 377 ### core/pid: Return PID of current process 378 379 This returns PID of current process. 380 Useful for stopping rclone process. 381 382 ### core/stats: Returns stats about current transfers. 383 384 This returns all available stats 385 386 rclone rc core/stats 387 388 Returns the following values: 389 390 ``` 391 { 392 "speed": average speed in bytes/sec since start of the process, 393 "bytes": total transferred bytes since the start of the process, 394 "errors": number of errors, 395 "fatalError": whether there has been at least one FatalError, 396 "retryError": whether there has been at least one non-NoRetryError, 397 "checks": number of checked files, 398 "transfers": number of transferred files, 399 "deletes" : number of deleted files, 400 "elapsedTime": time in seconds since the start of the process, 401 "lastError": last occurred error, 402 "transferring": an array of currently active file transfers: 403 [ 404 { 405 "bytes": total transferred bytes for this file, 406 "eta": estimated time in seconds until file transfer completion 407 "name": name of the file, 408 "percentage": progress of the file transfer in percent, 409 "speed": speed in bytes/sec, 410 "speedAvg": speed in bytes/sec as an exponentially weighted moving average, 411 "size": size of the file in bytes 412 } 413 ], 414 "checking": an array of names of currently active file checks 415 [] 416 } 417 ``` 418 Values for "transferring", "checking" and "lastError" are only assigned if data is available. 419 The value for "eta" is null if an eta cannot be determined. 420 421 ### core/version: Shows the current version of rclone and the go runtime. 422 423 This shows the current version of go and the go runtime 424 - version - rclone version, eg "v1.44" 425 - decomposed - version number as [major, minor, patch, subpatch] 426 - note patch and subpatch will be 999 for a git compiled version 427 - isGit - boolean - true if this was compiled from the git version 428 - os - OS in use as according to Go 429 - arch - cpu architecture in use according to Go 430 - goVersion - version of Go runtime in use 431 432 ### job/list: Lists the IDs of the running jobs 433 434 Parameters - None 435 436 Results 437 - jobids - array of integer job ids 438 439 ### job/status: Reads the status of the job ID 440 441 Parameters 442 - jobid - id of the job (integer) 443 444 Results 445 - finished - boolean 446 - duration - time in seconds that the job ran for 447 - endTime - time the job finished (eg "2018-10-26T18:50:20.528746884+01:00") 448 - error - error from the job or empty string for no error 449 - finished - boolean whether the job has finished or not 450 - id - as passed in above 451 - startTime - time the job started (eg "2018-10-26T18:50:20.528336039+01:00") 452 - success - boolean - true for success false otherwise 453 - output - output of the job as would have been returned if called synchronously 454 455 ### operations/about: Return the space used on the remote 456 457 This takes the following parameters 458 459 - fs - a remote name string eg "drive:" 460 461 The result is as returned from rclone about --json 462 463 See the [about command](/commands/rclone_size/) command for more information on the above. 464 465 Authentication is required for this call. 466 467 ### operations/cleanup: Remove trashed files in the remote or path 468 469 This takes the following parameters 470 471 - fs - a remote name string eg "drive:" 472 473 See the [cleanup command](/commands/rclone_cleanup/) command for more information on the above. 474 475 Authentication is required for this call. 476 477 ### operations/copyfile: Copy a file from source remote to destination remote 478 479 This takes the following parameters 480 481 - srcFs - a remote name string eg "drive:" for the source 482 - srcRemote - a path within that remote eg "file.txt" for the source 483 - dstFs - a remote name string eg "drive2:" for the destination 484 - dstRemote - a path within that remote eg "file2.txt" for the destination 485 486 Authentication is required for this call. 487 488 ### operations/copyurl: Copy the URL to the object 489 490 This takes the following parameters 491 492 - fs - a remote name string eg "drive:" 493 - remote - a path within that remote eg "dir" 494 - url - string, URL to read from 495 496 See the [copyurl command](/commands/rclone_copyurl/) command for more information on the above. 497 498 Authentication is required for this call. 499 500 ### operations/delete: Remove files in the path 501 502 This takes the following parameters 503 504 - fs - a remote name string eg "drive:" 505 506 See the [delete command](/commands/rclone_delete/) command for more information on the above. 507 508 Authentication is required for this call. 509 510 ### operations/deletefile: Remove the single file pointed to 511 512 This takes the following parameters 513 514 - fs - a remote name string eg "drive:" 515 - remote - a path within that remote eg "dir" 516 517 See the [deletefile command](/commands/rclone_deletefile/) command for more information on the above. 518 519 Authentication is required for this call. 520 521 ### operations/fsinfo: Return information about the remote 522 523 This takes the following parameters 524 525 - fs - a remote name string eg "drive:" 526 527 This returns info about the remote passed in; 528 529 ``` 530 { 531 // optional features and whether they are available or not 532 "Features": { 533 "About": true, 534 "BucketBased": false, 535 "CanHaveEmptyDirectories": true, 536 "CaseInsensitive": false, 537 "ChangeNotify": false, 538 "CleanUp": false, 539 "Copy": false, 540 "DirCacheFlush": false, 541 "DirMove": true, 542 "DuplicateFiles": false, 543 "GetTier": false, 544 "ListR": false, 545 "MergeDirs": false, 546 "Move": true, 547 "OpenWriterAt": true, 548 "PublicLink": false, 549 "Purge": true, 550 "PutStream": true, 551 "PutUnchecked": false, 552 "ReadMimeType": false, 553 "ServerSideAcrossConfigs": false, 554 "SetTier": false, 555 "SetWrapper": false, 556 "UnWrap": false, 557 "WrapFs": false, 558 "WriteMimeType": false 559 }, 560 // Names of hashes available 561 "Hashes": [ 562 "MD5", 563 "SHA-1", 564 "DropboxHash", 565 "QuickXorHash" 566 ], 567 "Name": "local", // Name as created 568 "Precision": 1, // Precision of timestamps in ns 569 "Root": "/", // Path as created 570 "String": "Local file system at /" // how the remote will appear in logs 571 } 572 ``` 573 574 This command does not have a command line equivalent so use this instead: 575 576 rclone rc --loopback operations/fsinfo fs=remote: 577 578 ### operations/list: List the given remote and path in JSON format 579 580 This takes the following parameters 581 582 - fs - a remote name string eg "drive:" 583 - remote - a path within that remote eg "dir" 584 - opt - a dictionary of options to control the listing (optional) 585 - recurse - If set recurse directories 586 - noModTime - If set return modification time 587 - showEncrypted - If set show decrypted names 588 - showOrigIDs - If set show the IDs for each item if known 589 - showHash - If set return a dictionary of hashes 590 591 The result is 592 593 - list 594 - This is an array of objects as described in the lsjson command 595 596 See the [lsjson command](/commands/rclone_lsjson/) for more information on the above and examples. 597 598 Authentication is required for this call. 599 600 ### operations/mkdir: Make a destination directory or container 601 602 This takes the following parameters 603 604 - fs - a remote name string eg "drive:" 605 - remote - a path within that remote eg "dir" 606 607 See the [mkdir command](/commands/rclone_mkdir/) command for more information on the above. 608 609 Authentication is required for this call. 610 611 ### operations/movefile: Move a file from source remote to destination remote 612 613 This takes the following parameters 614 615 - srcFs - a remote name string eg "drive:" for the source 616 - srcRemote - a path within that remote eg "file.txt" for the source 617 - dstFs - a remote name string eg "drive2:" for the destination 618 - dstRemote - a path within that remote eg "file2.txt" for the destination 619 620 Authentication is required for this call. 621 622 ### operations/publiclink: Create or retrieve a public link to the given file or folder. 623 624 This takes the following parameters 625 626 - fs - a remote name string eg "drive:" 627 - remote - a path within that remote eg "dir" 628 629 Returns 630 631 - url - URL of the resource 632 633 See the [link command](/commands/rclone_link/) command for more information on the above. 634 635 Authentication is required for this call. 636 637 ### operations/purge: Remove a directory or container and all of its contents 638 639 This takes the following parameters 640 641 - fs - a remote name string eg "drive:" 642 - remote - a path within that remote eg "dir" 643 644 See the [purge command](/commands/rclone_purge/) command for more information on the above. 645 646 Authentication is required for this call. 647 648 ### operations/rmdir: Remove an empty directory or container 649 650 This takes the following parameters 651 652 - fs - a remote name string eg "drive:" 653 - remote - a path within that remote eg "dir" 654 655 See the [rmdir command](/commands/rclone_rmdir/) command for more information on the above. 656 657 Authentication is required for this call. 658 659 ### operations/rmdirs: Remove all the empty directories in the path 660 661 This takes the following parameters 662 663 - fs - a remote name string eg "drive:" 664 - remote - a path within that remote eg "dir" 665 - leaveRoot - boolean, set to true not to delete the root 666 667 See the [rmdirs command](/commands/rclone_rmdirs/) command for more information on the above. 668 669 Authentication is required for this call. 670 671 ### operations/size: Count the number of bytes and files in remote 672 673 This takes the following parameters 674 675 - fs - a remote name string eg "drive:path/to/dir" 676 677 Returns 678 679 - count - number of files 680 - bytes - number of bytes in those files 681 682 See the [size command](/commands/rclone_size/) command for more information on the above. 683 684 Authentication is required for this call. 685 686 ### options/blocks: List all the option blocks 687 688 Returns 689 - options - a list of the options block names 690 691 ### options/get: Get all the options 692 693 Returns an object where keys are option block names and values are an 694 object with the current option values in. 695 696 This shows the internal names of the option within rclone which should 697 map to the external options very easily with a few exceptions. 698 699 ### options/set: Set an option 700 701 Parameters 702 703 - option block name containing an object with 704 - key: value 705 706 Repeated as often as required. 707 708 Only supply the options you wish to change. If an option is unknown 709 it will be silently ignored. Not all options will have an effect when 710 changed like this. 711 712 For example: 713 714 This sets DEBUG level logs (-vv) 715 716 rclone rc options/set --json '{"main": {"LogLevel": 8}}' 717 718 And this sets INFO level logs (-v) 719 720 rclone rc options/set --json '{"main": {"LogLevel": 7}}' 721 722 And this sets NOTICE level logs (normal without -v) 723 724 rclone rc options/set --json '{"main": {"LogLevel": 6}}' 725 726 ### rc/error: This returns an error 727 728 This returns an error with the input as part of its error string. 729 Useful for testing error handling. 730 731 ### rc/list: List all the registered remote control commands 732 733 This lists all the registered remote control commands as a JSON map in 734 the commands response. 735 736 ### rc/noop: Echo the input to the output parameters 737 738 This echoes the input parameters to the output parameters for testing 739 purposes. It can be used to check that rclone is still alive and to 740 check that parameter passing is working properly. 741 742 ### rc/noopauth: Echo the input to the output parameters requiring auth 743 744 This echoes the input parameters to the output parameters for testing 745 purposes. It can be used to check that rclone is still alive and to 746 check that parameter passing is working properly. 747 748 Authentication is required for this call. 749 750 ### sync/copy: copy a directory from source remote to destination remote 751 752 This takes the following parameters 753 754 - srcFs - a remote name string eg "drive:src" for the source 755 - dstFs - a remote name string eg "drive:dst" for the destination 756 757 758 See the [copy command](/commands/rclone_copy/) command for more information on the above. 759 760 Authentication is required for this call. 761 762 ### sync/move: move a directory from source remote to destination remote 763 764 This takes the following parameters 765 766 - srcFs - a remote name string eg "drive:src" for the source 767 - dstFs - a remote name string eg "drive:dst" for the destination 768 - deleteEmptySrcDirs - delete empty src directories if set 769 770 771 See the [move command](/commands/rclone_move/) command for more information on the above. 772 773 Authentication is required for this call. 774 775 ### sync/sync: sync a directory from source remote to destination remote 776 777 This takes the following parameters 778 779 - srcFs - a remote name string eg "drive:src" for the source 780 - dstFs - a remote name string eg "drive:dst" for the destination 781 782 783 See the [sync command](/commands/rclone_sync/) command for more information on the above. 784 785 Authentication is required for this call. 786 787 ### vfs/forget: Forget files or directories in the directory cache. 788 789 This forgets the paths in the directory cache causing them to be 790 re-read from the remote when needed. 791 792 If no paths are passed in then it will forget all the paths in the 793 directory cache. 794 795 rclone rc vfs/forget 796 797 Otherwise pass files or dirs in as file=path or dir=path. Any 798 parameter key starting with file will forget that file and any 799 starting with dir will forget that dir, eg 800 801 rclone rc vfs/forget file=hello file2=goodbye dir=home/junk 802 803 ### vfs/poll-interval: Get the status or update the value of the poll-interval option. 804 805 Without any parameter given this returns the current status of the 806 poll-interval setting. 807 808 When the interval=duration parameter is set, the poll-interval value 809 is updated and the polling function is notified. 810 Setting interval=0 disables poll-interval. 811 812 rclone rc vfs/poll-interval interval=5m 813 814 The timeout=duration parameter can be used to specify a time to wait 815 for the current poll function to apply the new value. 816 If timeout is less or equal 0, which is the default, wait indefinitely. 817 818 The new poll-interval value will only be active when the timeout is 819 not reached. 820 821 If poll-interval is updated or disabled temporarily, some changes 822 might not get picked up by the polling function, depending on the 823 used remote. 824 825 ### vfs/refresh: Refresh the directory cache. 826 827 This reads the directories for the specified paths and freshens the 828 directory cache. 829 830 If no paths are passed in then it will refresh the root directory. 831 832 rclone rc vfs/refresh 833 834 Otherwise pass directories in as dir=path. Any parameter key 835 starting with dir will refresh that directory, eg 836 837 rclone rc vfs/refresh dir=home/junk dir2=data/misc 838 839 If the parameter recursive=true is given the whole directory tree 840 will get refreshed. This refresh will use --fast-list if enabled. 841 842 <!--- autogenerated stop --> 843 844 ## Accessing the remote control via HTTP 845 846 Rclone implements a simple HTTP based protocol. 847 848 Each endpoint takes an JSON object and returns a JSON object or an 849 error. The JSON objects are essentially a map of string names to 850 values. 851 852 All calls must made using POST. 853 854 The input objects can be supplied using URL parameters, POST 855 parameters or by supplying "Content-Type: application/json" and a JSON 856 blob in the body. There are examples of these below using `curl`. 857 858 The response will be a JSON blob in the body of the response. This is 859 formatted to be reasonably human readable. 860 861 ### Error returns 862 863 If an error occurs then there will be an HTTP error status (eg 500) 864 and the body of the response will contain a JSON encoded error object, 865 eg 866 867 ``` 868 { 869 "error": "Expecting string value for key \"remote\" (was float64)", 870 "input": { 871 "fs": "/tmp", 872 "remote": 3 873 }, 874 "status": 400 875 "path": "operations/rmdir", 876 } 877 ``` 878 879 The keys in the error response are 880 - error - error string 881 - input - the input parameters to the call 882 - status - the HTTP status code 883 - path - the path of the call 884 885 ### CORS 886 887 The sever implements basic CORS support and allows all origins for that. 888 The response to a preflight OPTIONS request will echo the requested "Access-Control-Request-Headers" back. 889 890 ### Using POST with URL parameters only 891 892 ``` 893 curl -X POST 'http://localhost:5572/rc/noop?potato=1&sausage=2' 894 ``` 895 896 Response 897 898 ``` 899 { 900 "potato": "1", 901 "sausage": "2" 902 } 903 ``` 904 905 Here is what an error response looks like: 906 907 ``` 908 curl -X POST 'http://localhost:5572/rc/error?potato=1&sausage=2' 909 ``` 910 911 ``` 912 { 913 "error": "arbitrary error on input map[potato:1 sausage:2]", 914 "input": { 915 "potato": "1", 916 "sausage": "2" 917 } 918 } 919 ``` 920 921 Note that curl doesn't return errors to the shell unless you use the `-f` option 922 923 ``` 924 $ curl -f -X POST 'http://localhost:5572/rc/error?potato=1&sausage=2' 925 curl: (22) The requested URL returned error: 400 Bad Request 926 $ echo $? 927 22 928 ``` 929 930 ### Using POST with a form 931 932 ``` 933 curl --data "potato=1" --data "sausage=2" http://localhost:5572/rc/noop 934 ``` 935 936 Response 937 938 ``` 939 { 940 "potato": "1", 941 "sausage": "2" 942 } 943 ``` 944 945 Note that you can combine these with URL parameters too with the POST 946 parameters taking precedence. 947 948 ``` 949 curl --data "potato=1" --data "sausage=2" "http://localhost:5572/rc/noop?rutabaga=3&sausage=4" 950 ``` 951 952 Response 953 954 ``` 955 { 956 "potato": "1", 957 "rutabaga": "3", 958 "sausage": "4" 959 } 960 961 ``` 962 963 ### Using POST with a JSON blob 964 965 ``` 966 curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' http://localhost:5572/rc/noop 967 ``` 968 969 response 970 971 ``` 972 { 973 "password": "xyz", 974 "username": "xyz" 975 } 976 ``` 977 978 This can be combined with URL parameters too if required. The JSON 979 blob takes precedence. 980 981 ``` 982 curl -H "Content-Type: application/json" -X POST -d '{"potato":2,"sausage":1}' 'http://localhost:5572/rc/noop?rutabaga=3&potato=4' 983 ``` 984 985 ``` 986 { 987 "potato": 2, 988 "rutabaga": "3", 989 "sausage": 1 990 } 991 ``` 992 993 ## Debugging rclone with pprof ## 994 995 If you use the `--rc` flag this will also enable the use of the go 996 profiling tools on the same port. 997 998 To use these, first [install go](https://golang.org/doc/install). 999 1000 ### Debugging memory use 1001 1002 To profile rclone's memory use you can run: 1003 1004 go tool pprof -web http://localhost:5572/debug/pprof/heap 1005 1006 This should open a page in your browser showing what is using what 1007 memory. 1008 1009 You can also use the `-text` flag to produce a textual summary 1010 1011 ``` 1012 $ go tool pprof -text http://localhost:5572/debug/pprof/heap 1013 Showing nodes accounting for 1537.03kB, 100% of 1537.03kB total 1014 flat flat% sum% cum cum% 1015 1024.03kB 66.62% 66.62% 1024.03kB 66.62% github.com/ncw/rclone/vendor/golang.org/x/net/http2/hpack.addDecoderNode 1016 513kB 33.38% 100% 513kB 33.38% net/http.newBufioWriterSize 1017 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/cmd/all.init 1018 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/cmd/serve.init 1019 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/cmd/serve/restic.init 1020 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/vendor/golang.org/x/net/http2.init 1021 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/vendor/golang.org/x/net/http2/hpack.init 1022 0 0% 100% 1024.03kB 66.62% github.com/ncw/rclone/vendor/golang.org/x/net/http2/hpack.init.0 1023 0 0% 100% 1024.03kB 66.62% main.init 1024 0 0% 100% 513kB 33.38% net/http.(*conn).readRequest 1025 0 0% 100% 513kB 33.38% net/http.(*conn).serve 1026 0 0% 100% 1024.03kB 66.62% runtime.main 1027 ``` 1028 1029 ### Debugging go routine leaks 1030 1031 Memory leaks are most often caused by go routine leaks keeping memory 1032 alive which should have been garbage collected. 1033 1034 See all active go routines using 1035 1036 curl http://localhost:5572/debug/pprof/goroutine?debug=1 1037 1038 Or go to http://localhost:5572/debug/pprof/goroutine?debug=1 in your browser. 1039 1040 ### Other profiles to look at 1041 1042 You can see a summary of profiles available at http://localhost:5572/debug/pprof/ 1043 1044 Here is how to use some of them: 1045 1046 * Memory: `go tool pprof http://localhost:5572/debug/pprof/heap` 1047 * Go routines: `curl http://localhost:5572/debug/pprof/goroutine?debug=1` 1048 * 30-second CPU profile: `go tool pprof http://localhost:5572/debug/pprof/profile` 1049 * 5-second execution trace: `wget http://localhost:5572/debug/pprof/trace?seconds=5` 1050 1051 See the [net/http/pprof docs](https://golang.org/pkg/net/http/pprof/) 1052 for more info on how to use the profiling and for a general overview 1053 see [the Go team's blog post on profiling go programs](https://blog.golang.org/profiling-go-programs). 1054 1055 The profiling hook is [zero overhead unless it is used](https://stackoverflow.com/q/26545159/164234).