github.com/ncw/rclone@v1.48.1-0.20190724201158-a35aa1360e3e/docs/content/docs.md (about) 1 --- 2 title: "Documentation" 3 description: "Rclone Usage" 4 date: "2019-02-25" 5 --- 6 7 Configure 8 --------- 9 10 First, you'll need to configure rclone. As the object storage systems 11 have quite complicated authentication these are kept in a config file. 12 (See the `--config` entry for how to find the config file and choose 13 its location.) 14 15 The easiest way to make the config is to run rclone with the config 16 option: 17 18 rclone config 19 20 See the following for detailed instructions for 21 22 * [1Fichier](/fichier/) 23 * [Alias](/alias/) 24 * [Amazon Drive](/amazonclouddrive/) 25 * [Amazon S3](/s3/) 26 * [Backblaze B2](/b2/) 27 * [Box](/box/) 28 * [Cache](/cache/) 29 * [Crypt](/crypt/) - to encrypt other remotes 30 * [DigitalOcean Spaces](/s3/#digitalocean-spaces) 31 * [Dropbox](/dropbox/) 32 * [FTP](/ftp/) 33 * [Google Cloud Storage](/googlecloudstorage/) 34 * [Google Drive](/drive/) 35 * [Google Photos](/googlephotos/) 36 * [HTTP](/http/) 37 * [Hubic](/hubic/) 38 * [Jottacloud](/jottacloud/) 39 * [Koofr](/koofr/) 40 * [Mega](/mega/) 41 * [Microsoft Azure Blob Storage](/azureblob/) 42 * [Microsoft OneDrive](/onedrive/) 43 * [Openstack Swift / Rackspace Cloudfiles / Memset Memstore](/swift/) 44 * [OpenDrive](/opendrive/) 45 * [Pcloud](/pcloud/) 46 * [QingStor](/qingstor/) 47 * [SFTP](/sftp/) 48 * [Union](/union/) 49 * [WebDAV](/webdav/) 50 * [Yandex Disk](/yandex/) 51 * [The local filesystem](/local/) 52 53 Usage 54 ----- 55 56 Rclone syncs a directory tree from one storage system to another. 57 58 Its syntax is like this 59 60 Syntax: [options] subcommand <parameters> <parameters...> 61 62 Source and destination paths are specified by the name you gave the 63 storage system in the config file then the sub path, eg 64 "drive:myfolder" to look at "myfolder" in Google drive. 65 66 You can define as many storage paths as you like in the config file. 67 68 Subcommands 69 ----------- 70 71 rclone uses a system of subcommands. For example 72 73 rclone ls remote:path # lists a remote 74 rclone copy /local/path remote:path # copies /local/path to the remote 75 rclone sync /local/path remote:path # syncs /local/path to the remote 76 77 The main rclone commands with most used first 78 79 * [rclone config](/commands/rclone_config/) - Enter an interactive configuration session. 80 * [rclone copy](/commands/rclone_copy/) - Copy files from source to dest, skipping already copied. 81 * [rclone sync](/commands/rclone_sync/) - Make source and dest identical, modifying destination only. 82 * [rclone move](/commands/rclone_move/) - Move files from source to dest. 83 * [rclone delete](/commands/rclone_delete/) - Remove the contents of path. 84 * [rclone purge](/commands/rclone_purge/) - Remove the path and all of its contents. 85 * [rclone mkdir](/commands/rclone_mkdir/) - Make the path if it doesn't already exist. 86 * [rclone rmdir](/commands/rclone_rmdir/) - Remove the path. 87 * [rclone rmdirs](/commands/rclone_rmdirs/) - Remove any empty directories under the path. 88 * [rclone check](/commands/rclone_check/) - Check if the files in the source and destination match. 89 * [rclone ls](/commands/rclone_ls/) - List all the objects in the path with size and path. 90 * [rclone lsd](/commands/rclone_lsd/) - List all directories/containers/buckets in the path. 91 * [rclone lsl](/commands/rclone_lsl/) - List all the objects in the path with size, modification time and path. 92 * [rclone md5sum](/commands/rclone_md5sum/) - Produce an md5sum file for all the objects in the path. 93 * [rclone sha1sum](/commands/rclone_sha1sum/) - Produce a sha1sum file for all the objects in the path. 94 * [rclone size](/commands/rclone_size/) - Return the total size and number of objects in remote:path. 95 * [rclone version](/commands/rclone_version/) - Show the version number. 96 * [rclone cleanup](/commands/rclone_cleanup/) - Clean up the remote if possible. 97 * [rclone dedupe](/commands/rclone_dedupe/) - Interactively find duplicate files and delete/rename them. 98 * [rclone authorize](/commands/rclone_authorize/) - Remote authorization. 99 * [rclone cat](/commands/rclone_cat/) - Concatenate any files and send them to stdout. 100 * [rclone copyto](/commands/rclone_copyto/) - Copy files from source to dest, skipping already copied. 101 * [rclone genautocomplete](/commands/rclone_genautocomplete/) - Output shell completion scripts for rclone. 102 * [rclone gendocs](/commands/rclone_gendocs/) - Output markdown docs for rclone to the directory supplied. 103 * [rclone listremotes](/commands/rclone_listremotes/) - List all the remotes in the config file. 104 * [rclone mount](/commands/rclone_mount/) - Mount the remote as a mountpoint. 105 * [rclone moveto](/commands/rclone_moveto/) - Move file or directory from source to dest. 106 * [rclone obscure](/commands/rclone_obscure/) - Obscure password for use in the rclone.conf 107 * [rclone cryptcheck](/commands/rclone_cryptcheck/) - Check the integrity of a crypted remote. 108 * [rclone about](/commands/rclone_about/) - Get quota information from the remote. 109 110 See the [commands index](/commands/) for the full list. 111 112 Copying single files 113 -------------------- 114 115 rclone normally syncs or copies directories. However, if the source 116 remote points to a file, rclone will just copy that file. The 117 destination remote must point to a directory - rclone will give the 118 error `Failed to create file system for "remote:file": is a file not a 119 directory` if it isn't. 120 121 For example, suppose you have a remote with a file in called 122 `test.jpg`, then you could copy just that file like this 123 124 rclone copy remote:test.jpg /tmp/download 125 126 The file `test.jpg` will be placed inside `/tmp/download`. 127 128 This is equivalent to specifying 129 130 rclone copy --files-from /tmp/files remote: /tmp/download 131 132 Where `/tmp/files` contains the single line 133 134 test.jpg 135 136 It is recommended to use `copy` when copying individual files, not `sync`. 137 They have pretty much the same effect but `copy` will use a lot less 138 memory. 139 140 Syntax of remote paths 141 ---------------------- 142 143 The syntax of the paths passed to the rclone command are as follows. 144 145 ### /path/to/dir 146 147 This refers to the local file system. 148 149 On Windows only `\` may be used instead of `/` in local paths 150 **only**, non local paths must use `/`. 151 152 These paths needn't start with a leading `/` - if they don't then they 153 will be relative to the current directory. 154 155 ### remote:path/to/dir 156 157 This refers to a directory `path/to/dir` on `remote:` as defined in 158 the config file (configured with `rclone config`). 159 160 ### remote:/path/to/dir 161 162 On most backends this is refers to the same directory as 163 `remote:path/to/dir` and that format should be preferred. On a very 164 small number of remotes (FTP, SFTP, Dropbox for business) this will 165 refer to a different directory. On these, paths without a leading `/` 166 will refer to your "home" directory and paths with a leading `/` will 167 refer to the root. 168 169 ### :backend:path/to/dir 170 171 This is an advanced form for creating remotes on the fly. `backend` 172 should be the name or prefix of a backend (the `type` in the config 173 file) and all the configuration for the backend should be provided on 174 the command line (or in environment variables). 175 176 Here are some examples: 177 178 rclone lsd --http-url https://pub.rclone.org :http: 179 180 To list all the directories in the root of `https://pub.rclone.org/`. 181 182 rclone lsf --http-url https://example.com :http:path/to/dir 183 184 To list files and directories in `https://example.com/path/to/dir/` 185 186 rclone copy --http-url https://example.com :http:path/to/dir /tmp/dir 187 188 To copy files and directories in `https://example.com/path/to/dir` to `/tmp/dir`. 189 190 rclone copy --sftp-host example.com :sftp:path/to/dir /tmp/dir 191 192 To copy files and directories from `example.com` in the relative 193 directory `path/to/dir` to `/tmp/dir` using sftp. 194 195 Quoting and the shell 196 --------------------- 197 198 When you are typing commands to your computer you are using something 199 called the command line shell. This interprets various characters in 200 an OS specific way. 201 202 Here are some gotchas which may help users unfamiliar with the shell rules 203 204 ### Linux / OSX ### 205 206 If your names have spaces or shell metacharacters (eg `*`, `?`, `$`, 207 `'`, `"` etc) then you must quote them. Use single quotes `'` by default. 208 209 rclone copy 'Important files?' remote:backup 210 211 If you want to send a `'` you will need to use `"`, eg 212 213 rclone copy "O'Reilly Reviews" remote:backup 214 215 The rules for quoting metacharacters are complicated and if you want 216 the full details you'll have to consult the manual page for your 217 shell. 218 219 ### Windows ### 220 221 If your names have spaces in you need to put them in `"`, eg 222 223 rclone copy "E:\folder name\folder name\folder name" remote:backup 224 225 If you are using the root directory on its own then don't quote it 226 (see [#464](https://github.com/ncw/rclone/issues/464) for why), eg 227 228 rclone copy E:\ remote:backup 229 230 Copying files or directories with `:` in the names 231 -------------------------------------------------- 232 233 rclone uses `:` to mark a remote name. This is, however, a valid 234 filename component in non-Windows OSes. The remote name parser will 235 only search for a `:` up to the first `/` so if you need to act on a 236 file or directory like this then use the full path starting with a 237 `/`, or use `./` as a current directory prefix. 238 239 So to sync a directory called `sync:me` to a remote called `remote:` use 240 241 rclone sync ./sync:me remote:path 242 243 or 244 245 rclone sync /full/path/to/sync:me remote:path 246 247 Server Side Copy 248 ---------------- 249 250 Most remotes (but not all - see [the 251 overview](/overview/#optional-features)) support server side copy. 252 253 This means if you want to copy one folder to another then rclone won't 254 download all the files and re-upload them; it will instruct the server 255 to copy them in place. 256 257 Eg 258 259 rclone copy s3:oldbucket s3:newbucket 260 261 Will copy the contents of `oldbucket` to `newbucket` without 262 downloading and re-uploading. 263 264 Remotes which don't support server side copy **will** download and 265 re-upload in this case. 266 267 Server side copies are used with `sync` and `copy` and will be 268 identified in the log when using the `-v` flag. The `move` command 269 may also use them if remote doesn't support server side move directly. 270 This is done by issuing a server side copy then a delete which is much 271 quicker than a download and re-upload. 272 273 Server side copies will only be attempted if the remote names are the 274 same. 275 276 This can be used when scripting to make aged backups efficiently, eg 277 278 rclone sync remote:current-backup remote:previous-backup 279 rclone sync /path/to/files remote:current-backup 280 281 Options 282 ------- 283 284 Rclone has a number of options to control its behaviour. 285 286 Options that take parameters can have the values passed in two ways, 287 `--option=value` or `--option value`. However boolean (true/false) 288 options behave slightly differently to the other options in that 289 `--boolean` sets the option to `true` and the absence of the flag sets 290 it to `false`. It is also possible to specify `--boolean=false` or 291 `--boolean=true`. Note that `--boolean false` is not valid - this is 292 parsed as `--boolean` and the `false` is parsed as an extra command 293 line argument for rclone. 294 295 Options which use TIME use the go time parser. A duration string is a 296 possibly signed sequence of decimal numbers, each with optional 297 fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid 298 time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". 299 300 Options which use SIZE use kByte by default. However, a suffix of `b` 301 for bytes, `k` for kBytes, `M` for MBytes, `G` for GBytes, `T` for 302 TBytes and `P` for PBytes may be used. These are the binary units, eg 303 1, 2\*\*10, 2\*\*20, 2\*\*30 respectively. 304 305 ### --backup-dir=DIR ### 306 307 When using `sync`, `copy` or `move` any files which would have been 308 overwritten or deleted are moved in their original hierarchy into this 309 directory. 310 311 If `--suffix` is set, then the moved files will have the suffix added 312 to them. If there is a file with the same path (after the suffix has 313 been added) in DIR, then it will be overwritten. 314 315 The remote in use must support server side move or copy and you must 316 use the same remote as the destination of the sync. The backup 317 directory must not overlap the destination directory. 318 319 For example 320 321 rclone sync /path/to/local remote:current --backup-dir remote:old 322 323 will sync `/path/to/local` to `remote:current`, but for any files 324 which would have been updated or deleted will be stored in 325 `remote:old`. 326 327 If running rclone from a script you might want to use today's date as 328 the directory name passed to `--backup-dir` to store the old files, or 329 you might want to pass `--suffix` with today's date. 330 331 See `--compare-dest` and `--copy-dest`. 332 333 ### --bind string ### 334 335 Local address to bind to for outgoing connections. This can be an 336 IPv4 address (1.2.3.4), an IPv6 address (1234::789A) or host name. If 337 the host name doesn't resolve or resolves to more than one IP address 338 it will give an error. 339 340 ### --bwlimit=BANDWIDTH_SPEC ### 341 342 This option controls the bandwidth limit. Limits can be specified 343 in two ways: As a single limit, or as a timetable. 344 345 Single limits last for the duration of the session. To use a single limit, 346 specify the desired bandwidth in kBytes/s, or use a suffix b|k|M|G. The 347 default is `0` which means to not limit bandwidth. 348 349 For example, to limit bandwidth usage to 10 MBytes/s use `--bwlimit 10M` 350 351 It is also possible to specify a "timetable" of limits, which will cause 352 certain limits to be applied at certain times. To specify a timetable, format your 353 entries as "WEEKDAY-HH:MM,BANDWIDTH WEEKDAY-HH:MM,BANDWIDTH..." where: 354 WEEKDAY is optional element. 355 It could be written as whole world or only using 3 first characters. 356 HH:MM is an hour from 00:00 to 23:59. 357 358 An example of a typical timetable to avoid link saturation during daytime 359 working hours could be: 360 361 `--bwlimit "08:00,512 12:00,10M 13:00,512 18:00,30M 23:00,off"` 362 363 In this example, the transfer bandwidth will be every day set to 512kBytes/sec at 8am. 364 At noon, it will raise to 10Mbytes/s, and drop back to 512kBytes/sec at 1pm. 365 At 6pm, the bandwidth limit will be set to 30MBytes/s, and at 11pm it will be 366 completely disabled (full speed). Anything between 11pm and 8am will remain 367 unlimited. 368 369 An example of timetable with WEEKDAY could be: 370 371 `--bwlimit "Mon-00:00,512 Fri-23:59,10M Sat-10:00,1M Sun-20:00,off"` 372 373 It mean that, the transfer bandwidth will be set to 512kBytes/sec on Monday. 374 It will raise to 10Mbytes/s before the end of Friday. 375 At 10:00 on Sunday it will be set to 1Mbyte/s. 376 From 20:00 at Sunday will be unlimited. 377 378 Timeslots without weekday are extended to whole week. 379 So this one example: 380 381 `--bwlimit "Mon-00:00,512 12:00,1M Sun-20:00,off"` 382 383 Is equal to this: 384 385 `--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"` 386 387 Bandwidth limits only apply to the data transfer. They don't apply to the 388 bandwidth of the directory listings etc. 389 390 Note that the units are Bytes/s, not Bits/s. Typically connections are 391 measured in Bits/s - to convert divide by 8. For example, let's say 392 you have a 10 Mbit/s connection and you wish rclone to use half of it 393 - 5 Mbit/s. This is 5/8 = 0.625MByte/s so you would use a `--bwlimit 394 0.625M` parameter for rclone. 395 396 On Unix systems (Linux, MacOS, …) the bandwidth limiter can be toggled by 397 sending a `SIGUSR2` signal to rclone. This allows to remove the limitations 398 of a long running rclone transfer and to restore it back to the value specified 399 with `--bwlimit` quickly when needed. Assuming there is only one rclone instance 400 running, you can toggle the limiter like this: 401 402 kill -SIGUSR2 $(pidof rclone) 403 404 If you configure rclone with a [remote control](/rc) then you can use 405 change the bwlimit dynamically: 406 407 rclone rc core/bwlimit rate=1M 408 409 ### --buffer-size=SIZE ### 410 411 Use this sized buffer to speed up file transfers. Each `--transfer` 412 will use this much memory for buffering. 413 414 When using `mount` or `cmount` each open file descriptor will use this much 415 memory for buffering. 416 See the [mount](/commands/rclone_mount/#file-buffering) documentation for more details. 417 418 Set to 0 to disable the buffering for the minimum memory usage. 419 420 Note that the memory allocation of the buffers is influenced by the 421 [--use-mmap](#use-mmap) flag. 422 423 ### --checkers=N ### 424 425 The number of checkers to run in parallel. Checkers do the equality 426 checking of files during a sync. For some storage systems (eg S3, 427 Swift, Dropbox) this can take a significant amount of time so they are 428 run in parallel. 429 430 The default is to run 8 checkers in parallel. 431 432 ### -c, --checksum ### 433 434 Normally rclone will look at modification time and size of files to 435 see if they are equal. If you set this flag then rclone will check 436 the file hash and size to determine if files are equal. 437 438 This is useful when the remote doesn't support setting modified time 439 and a more accurate sync is desired than just checking the file size. 440 441 This is very useful when transferring between remotes which store the 442 same hash type on the object, eg Drive and Swift. For details of which 443 remotes support which hash type see the table in the [overview 444 section](/overview/). 445 446 Eg `rclone --checksum sync s3:/bucket swift:/bucket` would run much 447 quicker than without the `--checksum` flag. 448 449 When using this flag, rclone won't update mtimes of remote files if 450 they are incorrect as it would normally. 451 452 ### --compare-dest=DIR ### 453 454 When using `sync`, `copy` or `move` DIR is checked in addition to the 455 destination for files. If a file identical to the source is found that 456 file is NOT copied from source. This is useful to copy just files that 457 have changed since the last backup. 458 459 You must use the same remote as the destination of the sync. The 460 compare directory must not overlap the destination directory. 461 462 See `--copy-dest` and `--backup-dir`. 463 464 ### --config=CONFIG_FILE ### 465 466 Specify the location of the rclone config file. 467 468 Normally the config file is in your home directory as a file called 469 `.config/rclone/rclone.conf` (or `.rclone.conf` if created with an 470 older version). If `$XDG_CONFIG_HOME` is set it will be at 471 `$XDG_CONFIG_HOME/rclone/rclone.conf`. 472 473 If there is a file `rclone.conf` in the same directory as the rclone 474 executable it will be preferred. This file must be created manually 475 for Rclone to use it, it will never be created automatically. 476 477 If you run `rclone config file` you will see where the default 478 location is for you. 479 480 Use this flag to override the config location, eg `rclone 481 --config=".myconfig" .config`. 482 483 ### --contimeout=TIME ### 484 485 Set the connection timeout. This should be in go time format which 486 looks like `5s` for 5 seconds, `10m` for 10 minutes, or `3h30m`. 487 488 The connection timeout is the amount of time rclone will wait for a 489 connection to go through to a remote object storage system. It is 490 `1m` by default. 491 492 ### --copy-dest=DIR ### 493 494 When using `sync`, `copy` or `move` DIR is checked in addition to the 495 destination for files. If a file identical to the source is found that 496 file is server side copied from DIR to the destination. This is useful 497 for incremental backup. 498 499 The remote in use must support server side copy and you must 500 use the same remote as the destination of the sync. The compare 501 directory must not overlap the destination directory. 502 503 See `--compare-dest` and `--backup-dir`. 504 505 ### --dedupe-mode MODE ### 506 507 Mode to run dedupe command in. One of `interactive`, `skip`, `first`, `newest`, `oldest`, `rename`. The default is `interactive`. See the dedupe command for more information as to what these options mean. 508 509 ### --disable FEATURE,FEATURE,... ### 510 511 This disables a comma separated list of optional features. For example 512 to disable server side move and server side copy use: 513 514 --disable move,copy 515 516 The features can be put in in any case. 517 518 To see a list of which features can be disabled use: 519 520 --disable help 521 522 See the overview [features](/overview/#features) and 523 [optional features](/overview/#optional-features) to get an idea of 524 which feature does what. 525 526 This flag can be useful for debugging and in exceptional circumstances 527 (eg Google Drive limiting the total volume of Server Side Copies to 528 100GB/day). 529 530 ### -n, --dry-run ### 531 532 Do a trial run with no permanent changes. Use this to see what rclone 533 would do without actually doing it. Useful when setting up the `sync` 534 command which deletes files in the destination. 535 536 ### --ignore-case-sync ### 537 538 Using this option will cause rclone to ignore the case of the files 539 when synchronizing so files will not be copied/synced when the 540 existing filenames are the same, even if the casing is different. 541 542 ### --ignore-checksum ### 543 544 Normally rclone will check that the checksums of transferred files 545 match, and give an error "corrupted on transfer" if they don't. 546 547 You can use this option to skip that check. You should only use it if 548 you have had the "corrupted on transfer" error message and you are 549 sure you might want to transfer potentially corrupted data. 550 551 ### --ignore-existing ### 552 553 Using this option will make rclone unconditionally skip all files 554 that exist on the destination, no matter the content of these files. 555 556 While this isn't a generally recommended option, it can be useful 557 in cases where your files change due to encryption. However, it cannot 558 correct partial transfers in case a transfer was interrupted. 559 560 ### --ignore-size ### 561 562 Normally rclone will look at modification time and size of files to 563 see if they are equal. If you set this flag then rclone will check 564 only the modification time. If `--checksum` is set then it only 565 checks the checksum. 566 567 It will also cause rclone to skip verifying the sizes are the same 568 after transfer. 569 570 This can be useful for transferring files to and from OneDrive which 571 occasionally misreports the size of image files (see 572 [#399](https://github.com/ncw/rclone/issues/399) for more info). 573 574 ### -I, --ignore-times ### 575 576 Using this option will cause rclone to unconditionally upload all 577 files regardless of the state of files on the destination. 578 579 Normally rclone would skip any files that have the same 580 modification time and are the same size (or have the same checksum if 581 using `--checksum`). 582 583 ### --immutable ### 584 585 Treat source and destination files as immutable and disallow 586 modification. 587 588 With this option set, files will be created and deleted as requested, 589 but existing files will never be updated. If an existing file does 590 not match between the source and destination, rclone will give the error 591 `Source and destination exist but do not match: immutable file modified`. 592 593 Note that only commands which transfer files (e.g. `sync`, `copy`, 594 `move`) are affected by this behavior, and only modification is 595 disallowed. Files may still be deleted explicitly (e.g. `delete`, 596 `purge`) or implicitly (e.g. `sync`, `move`). Use `copy --immutable` 597 if it is desired to avoid deletion as well as modification. 598 599 This can be useful as an additional layer of protection for immutable 600 or append-only data sets (notably backup archives), where modification 601 implies corruption and should not be propagated. 602 603 ## --leave-root ### 604 605 During rmdirs it will not remove root directory, even if it's empty. 606 607 ### --log-file=FILE ### 608 609 Log all of rclone's output to FILE. This is not active by default. 610 This can be useful for tracking down problems with syncs in 611 combination with the `-v` flag. See the [Logging section](#logging) 612 for more info. 613 614 Note that if you are using the `logrotate` program to manage rclone's 615 logs, then you should use the `copytruncate` option as rclone doesn't 616 have a signal to rotate logs. 617 618 ### --log-format LIST ### 619 620 Comma separated list of log format options. `date`, `time`, `microseconds`, `longfile`, `shortfile`, `UTC`. The default is "`date`,`time`". 621 622 ### --log-level LEVEL ### 623 624 This sets the log level for rclone. The default log level is `NOTICE`. 625 626 `DEBUG` is equivalent to `-vv`. It outputs lots of debug info - useful 627 for bug reports and really finding out what rclone is doing. 628 629 `INFO` is equivalent to `-v`. It outputs information about each transfer 630 and prints stats once a minute by default. 631 632 `NOTICE` is the default log level if no logging flags are supplied. It 633 outputs very little when things are working normally. It outputs 634 warnings and significant events. 635 636 `ERROR` is equivalent to `-q`. It only outputs error messages. 637 638 ### --low-level-retries NUMBER ### 639 640 This controls the number of low level retries rclone does. 641 642 A low level retry is used to retry a failing operation - typically one 643 HTTP request. This might be uploading a chunk of a big file for 644 example. You will see low level retries in the log with the `-v` 645 flag. 646 647 This shouldn't need to be changed from the default in normal operations. 648 However, if you get a lot of low level retries you may wish 649 to reduce the value so rclone moves on to a high level retry (see the 650 `--retries` flag) quicker. 651 652 Disable low level retries with `--low-level-retries 1`. 653 654 ### --max-backlog=N ### 655 656 This is the maximum allowable backlog of files in a sync/copy/move 657 queued for being checked or transferred. 658 659 This can be set arbitrarily large. It will only use memory when the 660 queue is in use. Note that it will use in the order of N kB of memory 661 when the backlog is in use. 662 663 Setting this large allows rclone to calculate how many files are 664 pending more accurately and give a more accurate estimated finish 665 time. 666 667 Setting this small will make rclone more synchronous to the listings 668 of the remote which may be desirable. 669 670 ### --max-delete=N ### 671 672 This tells rclone not to delete more than N files. If that limit is 673 exceeded then a fatal error will be generated and rclone will stop the 674 operation in progress. 675 676 ### --max-depth=N ### 677 678 This modifies the recursion depth for all the commands except purge. 679 680 So if you do `rclone --max-depth 1 ls remote:path` you will see only 681 the files in the top level directory. Using `--max-depth 2` means you 682 will see all the files in first two directory levels and so on. 683 684 For historical reasons the `lsd` command defaults to using a 685 `--max-depth` of 1 - you can override this with the command line flag. 686 687 You can use this command to disable recursion (with `--max-depth 1`). 688 689 Note that if you use this with `sync` and `--delete-excluded` the 690 files not recursed through are considered excluded and will be deleted 691 on the destination. Test first with `--dry-run` if you are not sure 692 what will happen. 693 694 ### --max-transfer=SIZE ### 695 696 Rclone will stop transferring when it has reached the size specified. 697 Defaults to off. 698 699 When the limit is reached all transfers will stop immediately. 700 701 Rclone will exit with exit code 8 if the transfer limit is reached. 702 703 ### --modify-window=TIME ### 704 705 When checking whether a file has been modified, this is the maximum 706 allowed time difference that a file can have and still be considered 707 equivalent. 708 709 The default is `1ns` unless this is overridden by a remote. For 710 example OS X only stores modification times to the nearest second so 711 if you are reading and writing to an OS X filing system this will be 712 `1s` by default. 713 714 This command line flag allows you to override that computed default. 715 716 ### --multi-thread-cutoff=SIZE ### 717 718 When downloading files to the local backend above this size, rclone 719 will use multiple threads to download the file. (default 250M) 720 721 Rclone preallocates the file (using `fallocate(FALLOC_FL_KEEP_SIZE)` 722 on unix or `NTSetInformationFile` on Windows both of which takes no 723 time) then each thread writes directly into the file at the correct 724 place. This means that rclone won't create fragmented or sparse files 725 and there won't be any assembly time at the end of the transfer. 726 727 The number of threads used to dowload is controlled by 728 `--multi-thread-streams`. 729 730 Use `-vv` if you wish to see info about the threads. 731 732 This will work with the `sync`/`copy`/`move` commands and friends 733 `copyto`/`moveto`. Multi thread downloads will be used with `rclone 734 mount` and `rclone serve` if `--vfs-cache-mode` is set to `writes` or 735 above. 736 737 **NB** that this **only** works for a local destination but will work 738 with any source. 739 740 ### --multi-thread-streams=N ### 741 742 When using multi thread downloads (see above `--multi-thread-cutoff`) 743 this sets the maximum number of streams to use. Set to `0` to disable 744 multi thread downloads. (Default 4) 745 746 Exactly how many streams rclone uses for the download depends on the 747 size of the file. To calculate the number of download streams Rclone 748 divides the size of the file by the `--multi-thread-cutoff` and rounds 749 up, up to the maximum set with `--multi-thread-streams`. 750 751 So if `--multi-thread-cutoff 250MB` and `--multi-thread-streams 4` are 752 in effect (the defaults): 753 754 - 0MB.250MB files will be downloaded with 1 stream 755 - 250MB..500MB files will be downloaded with 2 streams 756 - 500MB..750MB files will be downloaded with 3 streams 757 - 750MB+ files will be downloaded with 4 streams 758 759 ### --no-gzip-encoding ### 760 761 Don't set `Accept-Encoding: gzip`. This means that rclone won't ask 762 the server for compressed files automatically. Useful if you've set 763 the server to return files with `Content-Encoding: gzip` but you 764 uploaded compressed files. 765 766 There is no need to set this in normal operation, and doing so will 767 decrease the network transfer efficiency of rclone. 768 769 ### --no-traverse ### 770 771 The `--no-traverse` flag controls whether the destination file system 772 is traversed when using the `copy` or `move` commands. 773 `--no-traverse` is not compatible with `sync` and will be ignored if 774 you supply it with `sync`. 775 776 If you are only copying a small number of files (or are filtering most 777 of the files) and/or have a large number of files on the destination 778 then `--no-traverse` will stop rclone listing the destination and save 779 time. 780 781 However, if you are copying a large number of files, especially if you 782 are doing a copy where lots of the files under consideration haven't 783 changed and won't need copying then you shouldn't use `--no-traverse`. 784 785 See [rclone copy](/commands/rclone_copy/) for an example of how to use it. 786 787 ### --no-update-modtime ### 788 789 When using this flag, rclone won't update modification times of remote 790 files if they are incorrect as it would normally. 791 792 This can be used if the remote is being synced with another tool also 793 (eg the Google Drive client). 794 795 ### -P, --progress ### 796 797 This flag makes rclone update the stats in a static block in the 798 terminal providing a realtime overview of the transfer. 799 800 Any log messages will scroll above the static block. Log messages 801 will push the static block down to the bottom of the terminal where it 802 will stay. 803 804 Normally this is updated every 500mS but this period can be overridden 805 with the `--stats` flag. 806 807 This can be used with the `--stats-one-line` flag for a simpler 808 display. 809 810 Note: On Windows until[this bug](https://github.com/Azure/go-ansiterm/issues/26) 811 is fixed all non-ASCII characters will be replaced with `.` when 812 `--progress` is in use. 813 814 ### -q, --quiet ### 815 816 Normally rclone outputs stats and a completion message. If you set 817 this flag it will make as little output as possible. 818 819 ### --retries int ### 820 821 Retry the entire sync if it fails this many times it fails (default 3). 822 823 Some remotes can be unreliable and a few retries help pick up the 824 files which didn't get transferred because of errors. 825 826 Disable retries with `--retries 1`. 827 828 ### --retries-sleep=TIME ### 829 830 This sets the interval between each retry specified by `--retries` 831 832 The default is 0. Use 0 to disable. 833 834 ### --size-only ### 835 836 Normally rclone will look at modification time and size of files to 837 see if they are equal. If you set this flag then rclone will check 838 only the size. 839 840 This can be useful transferring files from Dropbox which have been 841 modified by the desktop sync client which doesn't set checksums of 842 modification times in the same way as rclone. 843 844 ### --stats=TIME ### 845 846 Commands which transfer data (`sync`, `copy`, `copyto`, `move`, 847 `moveto`) will print data transfer stats at regular intervals to show 848 their progress. 849 850 This sets the interval. 851 852 The default is `1m`. Use 0 to disable. 853 854 If you set the stats interval then all commands can show stats. This 855 can be useful when running other commands, `check` or `mount` for 856 example. 857 858 Stats are logged at `INFO` level by default which means they won't 859 show at default log level `NOTICE`. Use `--stats-log-level NOTICE` or 860 `-v` to make them show. See the [Logging section](#logging) for more 861 info on log levels. 862 863 Note that on macOS you can send a SIGINFO (which is normally ctrl-T in 864 the terminal) to make the stats print immediately. 865 866 ### --stats-file-name-length integer ### 867 By default, the `--stats` output will truncate file names and paths longer 868 than 40 characters. This is equivalent to providing 869 `--stats-file-name-length 40`. Use `--stats-file-name-length 0` to disable 870 any truncation of file names printed by stats. 871 872 ### --stats-log-level string ### 873 874 Log level to show `--stats` output at. This can be `DEBUG`, `INFO`, 875 `NOTICE`, or `ERROR`. The default is `INFO`. This means at the 876 default level of logging which is `NOTICE` the stats won't show - if 877 you want them to then use `--stats-log-level NOTICE`. See the [Logging 878 section](#logging) for more info on log levels. 879 880 ### --stats-one-line ### 881 882 When this is specified, rclone condenses the stats into a single line 883 showing the most important stats only. 884 885 ### --stats-one-line-date ### 886 887 When this is specified, rclone enables the single-line stats and prepends 888 the display with a date string. The default is `2006/01/02 15:04:05 - ` 889 890 ### --stats-one-line-date-format ### 891 892 When this is specified, rclone enables the single-line stats and prepends 893 the display with a user-supplied date string. The date string MUST be 894 enclosed in quotes. Follow [golang specs](https://golang.org/pkg/time/#Time.Format) for 895 date formatting syntax. 896 897 ### --stats-unit=bits|bytes ### 898 899 By default, data transfer rates will be printed in bytes/second. 900 901 This option allows the data rate to be printed in bits/second. 902 903 Data transfer volume will still be reported in bytes. 904 905 The rate is reported as a binary unit, not SI unit. So 1 Mbit/s 906 equals 1,048,576 bits/s and not 1,000,000 bits/s. 907 908 The default is `bytes`. 909 910 ### --suffix=SUFFIX ### 911 912 When using `sync`, `copy` or `move` any files which would have been 913 overwritten or deleted will have the suffix added to them. If there 914 is a file with the same path (after the suffix has been added), then 915 it will be overwritten. 916 917 The remote in use must support server side move or copy and you must 918 use the same remote as the destination of the sync. 919 920 This is for use with files to add the suffix in the current directory 921 or with `--backup-dir`. See `--backup-dir` for more info. 922 923 For example 924 925 rclone sync /path/to/local/file remote:current --suffix .bak 926 927 will sync `/path/to/local` to `remote:current`, but for any files 928 which would have been updated or deleted have .bak added. 929 930 ### --suffix-keep-extension ### 931 932 When using `--suffix`, setting this causes rclone put the SUFFIX 933 before the extension of the files that it backs up rather than after. 934 935 So let's say we had `--suffix -2019-01-01`, without the flag `file.txt` 936 would be backed up to `file.txt-2019-01-01` and with the flag it would 937 be backed up to `file-2019-01-01.txt`. This can be helpful to make 938 sure the suffixed files can still be opened. 939 940 ### --syslog ### 941 942 On capable OSes (not Windows or Plan9) send all log output to syslog. 943 944 This can be useful for running rclone in a script or `rclone mount`. 945 946 ### --syslog-facility string ### 947 948 If using `--syslog` this sets the syslog facility (eg `KERN`, `USER`). 949 See `man syslog` for a list of possible facilities. The default 950 facility is `DAEMON`. 951 952 ### --tpslimit float ### 953 954 Limit HTTP transactions per second to this. Default is 0 which is used 955 to mean unlimited transactions per second. 956 957 For example to limit rclone to 10 HTTP transactions per second use 958 `--tpslimit 10`, or to 1 transaction every 2 seconds use `--tpslimit 959 0.5`. 960 961 Use this when the number of transactions per second from rclone is 962 causing a problem with the cloud storage provider (eg getting you 963 banned or rate limited). 964 965 This can be very useful for `rclone mount` to control the behaviour of 966 applications using it. 967 968 See also `--tpslimit-burst`. 969 970 ### --tpslimit-burst int ### 971 972 Max burst of transactions for `--tpslimit`. (default 1) 973 974 Normally `--tpslimit` will do exactly the number of transaction per 975 second specified. However if you supply `--tps-burst` then rclone can 976 save up some transactions from when it was idle giving a burst of up 977 to the parameter supplied. 978 979 For example if you provide `--tpslimit-burst 10` then if rclone has 980 been idle for more than 10*`--tpslimit` then it can do 10 transactions 981 very quickly before they are limited again. 982 983 This may be used to increase performance of `--tpslimit` without 984 changing the long term average number of transactions per second. 985 986 ### --track-renames ### 987 988 By default, rclone doesn't keep track of renamed files, so if you 989 rename a file locally then sync it to a remote, rclone will delete the 990 old file on the remote and upload a new copy. 991 992 If you use this flag, and the remote supports server side copy or 993 server side move, and the source and destination have a compatible 994 hash, then this will track renames during `sync` 995 operations and perform renaming server-side. 996 997 Files will be matched by size and hash - if both match then a rename 998 will be considered. 999 1000 If the destination does not support server-side copy or move, rclone 1001 will fall back to the default behaviour and log an error level message 1002 to the console. Note: Encrypted destinations are not supported 1003 by `--track-renames`. 1004 1005 Note that `--track-renames` is incompatible with `--no-traverse` and 1006 that it uses extra memory to keep track of all the rename candidates. 1007 1008 Note also that `--track-renames` is incompatible with 1009 `--delete-before` and will select `--delete-after` instead of 1010 `--delete-during`. 1011 1012 ### --delete-(before,during,after) ### 1013 1014 This option allows you to specify when files on your destination are 1015 deleted when you sync folders. 1016 1017 Specifying the value `--delete-before` will delete all files present 1018 on the destination, but not on the source *before* starting the 1019 transfer of any new or updated files. This uses two passes through the 1020 file systems, one for the deletions and one for the copies. 1021 1022 Specifying `--delete-during` will delete files while checking and 1023 uploading files. This is the fastest option and uses the least memory. 1024 1025 Specifying `--delete-after` (the default value) will delay deletion of 1026 files until all new/updated files have been successfully transferred. 1027 The files to be deleted are collected in the copy pass then deleted 1028 after the copy pass has completed successfully. The files to be 1029 deleted are held in memory so this mode may use more memory. This is 1030 the safest mode as it will only delete files if there have been no 1031 errors subsequent to that. If there have been errors before the 1032 deletions start then you will get the message `not deleting files as 1033 there were IO errors`. 1034 1035 ### --fast-list ### 1036 1037 When doing anything which involves a directory listing (eg `sync`, 1038 `copy`, `ls` - in fact nearly every command), rclone normally lists a 1039 directory and processes it before using more directory lists to 1040 process any subdirectories. This can be parallelised and works very 1041 quickly using the least amount of memory. 1042 1043 However, some remotes have a way of listing all files beneath a 1044 directory in one (or a small number) of transactions. These tend to 1045 be the bucket based remotes (eg S3, B2, GCS, Swift, Hubic). 1046 1047 If you use the `--fast-list` flag then rclone will use this method for 1048 listing directories. This will have the following consequences for 1049 the listing: 1050 1051 * It **will** use fewer transactions (important if you pay for them) 1052 * It **will** use more memory. Rclone has to load the whole listing into memory. 1053 * It *may* be faster because it uses fewer transactions 1054 * It *may* be slower because it can't be parallelized 1055 1056 rclone should always give identical results with and without 1057 `--fast-list`. 1058 1059 If you pay for transactions and can fit your entire sync listing into 1060 memory then `--fast-list` is recommended. If you have a very big sync 1061 to do then don't use `--fast-list` otherwise you will run out of 1062 memory. 1063 1064 If you use `--fast-list` on a remote which doesn't support it, then 1065 rclone will just ignore it. 1066 1067 ### --timeout=TIME ### 1068 1069 This sets the IO idle timeout. If a transfer has started but then 1070 becomes idle for this long it is considered broken and disconnected. 1071 1072 The default is `5m`. Set to 0 to disable. 1073 1074 ### --transfers=N ### 1075 1076 The number of file transfers to run in parallel. It can sometimes be 1077 useful to set this to a smaller number if the remote is giving a lot 1078 of timeouts or bigger if you have lots of bandwidth and a fast remote. 1079 1080 The default is to run 4 file transfers in parallel. 1081 1082 ### -u, --update ### 1083 1084 This forces rclone to skip any files which exist on the destination 1085 and have a modified time that is newer than the source file. 1086 1087 If an existing destination file has a modification time equal (within 1088 the computed modify window precision) to the source file's, it will be 1089 updated if the sizes are different. 1090 1091 On remotes which don't support mod time directly (or when using 1092 `--use-server-mod-time`) the time checked will be the uploaded time. 1093 This means that if uploading to one of these remotes, rclone will skip 1094 any files which exist on the destination and have an uploaded time that 1095 is newer than the modification time of the source file. 1096 1097 This can be useful when transferring to a remote which doesn't support 1098 mod times directly (or when using `--use-server-mod-time` to avoid extra 1099 API calls) as it is more accurate than a `--size-only` check and faster 1100 than using `--checksum`. 1101 1102 ### --use-mmap ### 1103 1104 If this flag is set then rclone will use anonymous memory allocated by 1105 mmap on Unix based platforms and VirtualAlloc on Windows for its 1106 transfer buffers (size controlled by `--buffer-size`). Memory 1107 allocated like this does not go on the Go heap and can be returned to 1108 the OS immediately when it is finished with. 1109 1110 If this flag is not set then rclone will allocate and free the buffers 1111 using the Go memory allocator which may use more memory as memory 1112 pages are returned less aggressively to the OS. 1113 1114 It is possible this does not work well on all platforms so it is 1115 disabled by default; in the future it may be enabled by default. 1116 1117 ### --use-server-modtime ### 1118 1119 Some object-store backends (e.g, Swift, S3) do not preserve file modification 1120 times (modtime). On these backends, rclone stores the original modtime as 1121 additional metadata on the object. By default it will make an API call to 1122 retrieve the metadata when the modtime is needed by an operation. 1123 1124 Use this flag to disable the extra API call and rely instead on the server's 1125 modified time. In cases such as a local to remote sync using `--update`, 1126 knowing the local file is newer than the time it was last uploaded to the 1127 remote is sufficient. In those cases, this flag can speed up the process and 1128 reduce the number of API calls necessary. 1129 1130 Using this flag on a sync operation without also using `--update` would cause 1131 all files modified at any time other than the last upload time to be uploaded 1132 again, which is probably not what you want. 1133 1134 ### -v, -vv, --verbose ### 1135 1136 With `-v` rclone will tell you about each file that is transferred and 1137 a small number of significant events. 1138 1139 With `-vv` rclone will become very verbose telling you about every 1140 file it considers and transfers. Please send bug reports with a log 1141 with this setting. 1142 1143 ### -V, --version ### 1144 1145 Prints the version number 1146 1147 SSL/TLS options 1148 --------------- 1149 1150 The outoing SSL/TLS connections rclone makes can be controlled with 1151 these options. For example this can be very useful with the HTTP or 1152 WebDAV backends. Rclone HTTP servers have their own set of 1153 configuration for SSL/TLS which you can find in their documentation. 1154 1155 ### --ca-cert string 1156 1157 This loads the PEM encoded certificate authority certificate and uses 1158 it to verify the certificates of the servers rclone connects to. 1159 1160 If you have generated certificates signed with a local CA then you 1161 will need this flag to connect to servers using those certificates. 1162 1163 ### --client-cert string 1164 1165 This loads the PEM encoded client side certificate. 1166 1167 This is used for [mutual TLS authentication](https://en.wikipedia.org/wiki/Mutual_authentication). 1168 1169 The `--client-key` flag is required too when using this. 1170 1171 ### --client-key string 1172 1173 This loads the PEM encoded client side private key used for mutual TLS 1174 authentication. Used in conjunction with `--client-cert`. 1175 1176 ### --no-check-certificate=true/false ### 1177 1178 `--no-check-certificate` controls whether a client verifies the 1179 server's certificate chain and host name. 1180 If `--no-check-certificate` is true, TLS accepts any certificate 1181 presented by the server and any host name in that certificate. 1182 In this mode, TLS is susceptible to man-in-the-middle attacks. 1183 1184 This option defaults to `false`. 1185 1186 **This should be used only for testing.** 1187 1188 Configuration Encryption 1189 ------------------------ 1190 Your configuration file contains information for logging in to 1191 your cloud services. This means that you should keep your 1192 `.rclone.conf` file in a secure location. 1193 1194 If you are in an environment where that isn't possible, you can 1195 add a password to your configuration. This means that you will 1196 have to enter the password every time you start rclone. 1197 1198 To add a password to your rclone configuration, execute `rclone config`. 1199 1200 ``` 1201 >rclone config 1202 Current remotes: 1203 1204 e) Edit existing remote 1205 n) New remote 1206 d) Delete remote 1207 s) Set configuration password 1208 q) Quit config 1209 e/n/d/s/q> 1210 ``` 1211 1212 Go into `s`, Set configuration password: 1213 ``` 1214 e/n/d/s/q> s 1215 Your configuration is not encrypted. 1216 If you add a password, you will protect your login information to cloud services. 1217 a) Add Password 1218 q) Quit to main menu 1219 a/q> a 1220 Enter NEW configuration password: 1221 password: 1222 Confirm NEW password: 1223 password: 1224 Password set 1225 Your configuration is encrypted. 1226 c) Change Password 1227 u) Unencrypt configuration 1228 q) Quit to main menu 1229 c/u/q> 1230 ``` 1231 1232 Your configuration is now encrypted, and every time you start rclone 1233 you will now be asked for the password. In the same menu, you can 1234 change the password or completely remove encryption from your 1235 configuration. 1236 1237 There is no way to recover the configuration if you lose your password. 1238 1239 rclone uses [nacl secretbox](https://godoc.org/golang.org/x/crypto/nacl/secretbox) 1240 which in turn uses XSalsa20 and Poly1305 to encrypt and authenticate 1241 your configuration with secret-key cryptography. 1242 The password is SHA-256 hashed, which produces the key for secretbox. 1243 The hashed password is not stored. 1244 1245 While this provides very good security, we do not recommend storing 1246 your encrypted rclone configuration in public if it contains sensitive 1247 information, maybe except if you use a very strong password. 1248 1249 If it is safe in your environment, you can set the `RCLONE_CONFIG_PASS` 1250 environment variable to contain your password, in which case it will be 1251 used for decrypting the configuration. 1252 1253 You can set this for a session from a script. For unix like systems 1254 save this to a file called `set-rclone-password`: 1255 1256 ``` 1257 #!/bin/echo Source this file don't run it 1258 1259 read -s RCLONE_CONFIG_PASS 1260 export RCLONE_CONFIG_PASS 1261 ``` 1262 1263 Then source the file when you want to use it. From the shell you 1264 would do `source set-rclone-password`. It will then ask you for the 1265 password and set it in the environment variable. 1266 1267 If you are running rclone inside a script, you might want to disable 1268 password prompts. To do that, pass the parameter 1269 `--ask-password=false` to rclone. This will make rclone fail instead 1270 of asking for a password if `RCLONE_CONFIG_PASS` doesn't contain 1271 a valid password. 1272 1273 1274 Developer options 1275 ----------------- 1276 1277 These options are useful when developing or debugging rclone. There 1278 are also some more remote specific options which aren't documented 1279 here which are used for testing. These start with remote name eg 1280 `--drive-test-option` - see the docs for the remote in question. 1281 1282 ### --cpuprofile=FILE ### 1283 1284 Write CPU profile to file. This can be analysed with `go tool pprof`. 1285 1286 #### --dump flag,flag,flag #### 1287 1288 The `--dump` flag takes a comma separated list of flags to dump info 1289 about. These are: 1290 1291 #### --dump headers #### 1292 1293 Dump HTTP headers with `Authorization:` lines removed. May still 1294 contain sensitive info. Can be very verbose. Useful for debugging 1295 only. 1296 1297 Use `--dump auth` if you do want the `Authorization:` headers. 1298 1299 #### --dump bodies #### 1300 1301 Dump HTTP headers and bodies - may contain sensitive info. Can be 1302 very verbose. Useful for debugging only. 1303 1304 Note that the bodies are buffered in memory so don't use this for 1305 enormous files. 1306 1307 #### --dump requests #### 1308 1309 Like `--dump bodies` but dumps the request bodies and the response 1310 headers. Useful for debugging download problems. 1311 1312 #### --dump responses #### 1313 1314 Like `--dump bodies` but dumps the response bodies and the request 1315 headers. Useful for debugging upload problems. 1316 1317 #### --dump auth #### 1318 1319 Dump HTTP headers - will contain sensitive info such as 1320 `Authorization:` headers - use `--dump headers` to dump without 1321 `Authorization:` headers. Can be very verbose. Useful for debugging 1322 only. 1323 1324 #### --dump filters #### 1325 1326 Dump the filters to the output. Useful to see exactly what include 1327 and exclude options are filtering on. 1328 1329 #### --dump goroutines #### 1330 1331 This dumps a list of the running go-routines at the end of the command 1332 to standard output. 1333 1334 #### --dump openfiles #### 1335 1336 This dumps a list of the open files at the end of the command. It 1337 uses the `lsof` command to do that so you'll need that installed to 1338 use it. 1339 1340 ### --memprofile=FILE ### 1341 1342 Write memory profile to file. This can be analysed with `go tool pprof`. 1343 1344 Filtering 1345 --------- 1346 1347 For the filtering options 1348 1349 * `--delete-excluded` 1350 * `--filter` 1351 * `--filter-from` 1352 * `--exclude` 1353 * `--exclude-from` 1354 * `--include` 1355 * `--include-from` 1356 * `--files-from` 1357 * `--min-size` 1358 * `--max-size` 1359 * `--min-age` 1360 * `--max-age` 1361 * `--dump filters` 1362 1363 See the [filtering section](/filtering/). 1364 1365 Remote control 1366 -------------- 1367 1368 For the remote control options and for instructions on how to remote control rclone 1369 1370 * `--rc` 1371 * and anything starting with `--rc-` 1372 1373 See [the remote control section](/rc/). 1374 1375 Logging 1376 ------- 1377 1378 rclone has 4 levels of logging, `ERROR`, `NOTICE`, `INFO` and `DEBUG`. 1379 1380 By default, rclone logs to standard error. This means you can redirect 1381 standard error and still see the normal output of rclone commands (eg 1382 `rclone ls`). 1383 1384 By default, rclone will produce `Error` and `Notice` level messages. 1385 1386 If you use the `-q` flag, rclone will only produce `Error` messages. 1387 1388 If you use the `-v` flag, rclone will produce `Error`, `Notice` and 1389 `Info` messages. 1390 1391 If you use the `-vv` flag, rclone will produce `Error`, `Notice`, 1392 `Info` and `Debug` messages. 1393 1394 You can also control the log levels with the `--log-level` flag. 1395 1396 If you use the `--log-file=FILE` option, rclone will redirect `Error`, 1397 `Info` and `Debug` messages along with standard error to FILE. 1398 1399 If you use the `--syslog` flag then rclone will log to syslog and the 1400 `--syslog-facility` control which facility it uses. 1401 1402 Rclone prefixes all log messages with their level in capitals, eg INFO 1403 which makes it easy to grep the log file for different kinds of 1404 information. 1405 1406 Exit Code 1407 --------- 1408 1409 If any errors occur during the command execution, rclone will exit with a 1410 non-zero exit code. This allows scripts to detect when rclone 1411 operations have failed. 1412 1413 During the startup phase, rclone will exit immediately if an error is 1414 detected in the configuration. There will always be a log message 1415 immediately before exiting. 1416 1417 When rclone is running it will accumulate errors as it goes along, and 1418 only exit with a non-zero exit code if (after retries) there were 1419 still failed transfers. For every error counted there will be a high 1420 priority log message (visible with `-q`) showing the message and 1421 which file caused the problem. A high priority message is also shown 1422 when starting a retry so the user can see that any previous error 1423 messages may not be valid after the retry. If rclone has done a retry 1424 it will log a high priority message if the retry was successful. 1425 1426 ### List of exit codes ### 1427 * `0` - success 1428 * `1` - Syntax or usage error 1429 * `2` - Error not otherwise categorised 1430 * `3` - Directory not found 1431 * `4` - File not found 1432 * `5` - Temporary error (one that more retries might fix) (Retry errors) 1433 * `6` - Less serious errors (like 461 errors from dropbox) (NoRetry errors) 1434 * `7` - Fatal error (one that more retries won't fix, like account suspended) (Fatal errors) 1435 * `8` - Transfer exceeded - limit set by --max-transfer reached 1436 1437 Environment Variables 1438 --------------------- 1439 1440 Rclone can be configured entirely using environment variables. These 1441 can be used to set defaults for options or config file entries. 1442 1443 ### Options ### 1444 1445 Every option in rclone can have its default set by environment 1446 variable. 1447 1448 To find the name of the environment variable, first, take the long 1449 option name, strip the leading `--`, change `-` to `_`, make 1450 upper case and prepend `RCLONE_`. 1451 1452 For example, to always set `--stats 5s`, set the environment variable 1453 `RCLONE_STATS=5s`. If you set stats on the command line this will 1454 override the environment variable setting. 1455 1456 Or to always use the trash in drive `--drive-use-trash`, set 1457 `RCLONE_DRIVE_USE_TRASH=true`. 1458 1459 The same parser is used for the options and the environment variables 1460 so they take exactly the same form. 1461 1462 ### Config file ### 1463 1464 You can set defaults for values in the config file on an individual 1465 remote basis. If you want to use this feature, you will need to 1466 discover the name of the config items that you want. The easiest way 1467 is to run through `rclone config` by hand, then look in the config 1468 file to see what the values are (the config file can be found by 1469 looking at the help for `--config` in `rclone help`). 1470 1471 To find the name of the environment variable, you need to set, take 1472 `RCLONE_CONFIG_` + name of remote + `_` + name of config file option 1473 and make it all uppercase. 1474 1475 For example, to configure an S3 remote named `mys3:` without a config 1476 file (using unix ways of setting environment variables): 1477 1478 ``` 1479 $ export RCLONE_CONFIG_MYS3_TYPE=s3 1480 $ export RCLONE_CONFIG_MYS3_ACCESS_KEY_ID=XXX 1481 $ export RCLONE_CONFIG_MYS3_SECRET_ACCESS_KEY=XXX 1482 $ rclone lsd MYS3: 1483 -1 2016-09-21 12:54:21 -1 my-bucket 1484 $ rclone listremotes | grep mys3 1485 mys3: 1486 ``` 1487 1488 Note that if you want to create a remote using environment variables 1489 you must create the `..._TYPE` variable as above. 1490 1491 ### Other environment variables ### 1492 1493 * RCLONE_CONFIG_PASS` set to contain your config file password (see [Configuration Encryption](#configuration-encryption) section) 1494 * HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof). 1495 * HTTPS_PROXY takes precedence over HTTP_PROXY for https requests. 1496 * The environment values may be either a complete URL or a "host[:port]" for, in which case the "http" scheme is assumed.