Attachment 221815 Details for Bug 252919 – Draft of man page for rclone (unfinished, for advice)

Draft of man page for rclone (unfinished, for advice)

rclone.1 (text/plain), 12.73 KB, created by Alexis Praga on 2021-01-22 18:52:58 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Alexis Praga

Created: 2021-01-22 18:52:58 UTC

Size: 12.73 KB

patch

obsolete

>.Dd January 21, 2021
>.Dt RCLONE 1
>.Os
>.Sh NAME
>.Nm rclone
>.Nd syncs your files to cloud storage
>.Sh SYNOPSIS
>.Nm
>.Op Ar option
>.Ar command
>.Op Ar parameters ...
>.Sh DESCRIPTION
>.Nm
>is a command line program to manage files between two storage systems. It supports a wide range of cloud storage providers, hence being is sometimes called
>.Qq The Swiss army knife of cloud storage .
>It provides functionnality similar to
>.Xr rsync 1 ,
>.Xr cp 1 ,
>.Xr rm  1 ,
>.Xr mv 1 ,
>.Xr mount 1 ,
>.Xr ls 1 ,
>.Xr ncdu 1 ,
>.Xr tree 1 ,
>.Xr rm 1 , and
>.Xr cat 1 .
>As such, it can be used to backup or restore data, mirror storage system, mount cloud storage as a disk,
>account for data and union filesystems.
>.Pp
>.Ss Configuration
>This is first step, which can easily be done by running :
>.Dl rclone config
>.Pp
>Details instructions for configuring the numerous cloud providers are given in
>.Xr rclone-config 1 .
>.Pp
>.Ss Running commands
>The commands are as follows:
>.Bl -tag
>.It Cm about
>Get quota information from the remote
>.It Cm authorize
>Remote authorization
>.It Cm  backend
>Run a backend specific command.
>.It Cm  cat
>Concatenates any files and sends them to stdout.
>.It Cm  check
>Checks the files in the source and destination match.
>.It Cm  cleanup
>Clean up the remote if possible.
>.It Cm  config
>Enter an interactive configuration session.
>.It Cm  copy
>Copy files from source to dest, skipping already copied.
>.It Cm  copyto
>Copy files from source to dest, skipping already copied.
>.It Cm  copyurl
>Copy url content to dest.
>.It Cm  cryptcheck
>Cryptcheck checks the integrity of a crypted remote.
>.It Cm  cryptdecode
>Cryptdecode returns unencrypted file names.
>.It Cm  dedupe
>Interactively find duplicate filenames and delete/rename them.
>.It Cm  delete
>Remove the contents of path.
>.It Cm  deletefile
>Remove a single file from remote.
>.It Cm  genautocomplete
>Output completion script for a given shell.
>.It Cm  gendocs
>Output markdown docs for rclone to the directory supplied.
>.It Cm  hashsum
>Produces a hashsum file for all the objects in the path.
>.It Cm  help
>Show help for rclone commands, flags and backends.
>.It Cm  link
>Generate public link to file/folder.
>.It Cm  listremotes
>List all the remotes in the config file.
>.It Cm  ls
>List the objects in the path with size and path.
>.It Cm  lsd
>List all directories/containers/buckets in the path.
>.It Cm  lsf
>List directories and objects in remote:path formatted for parsing.
>.It Cm  lsjson
>List directories and objects in the path in JSON format.
>.It Cm  lsl
>List the objects in path with modification time, size and path.
>.It Cm  md5sum
>Produces an md5sum file for all the objects in the path.
>.It Cm  mkdir
>Make the path if it doesn't already exist.
>.It Cm  mount
>Mount the remote as file system on a mountpoint.
>.It Cm  move
>Move files from source to dest.
>.It Cm  moveto
>Move file or directory from source to dest.
>.It Cm  ncdu
>Explore a remote with a text based user interface.
>.It Cm  obscure
>Obscure password for use in the rclone config file.
>.It Cm  purge
>Remove the path and all of its contents.
>.It Cm  rc
>Run a command against a running rclone.
>.It Cm  rcat
>Copies standard input to file on remote.
>.It Cm  rcd
>Run rclone listening to remote control commands only.
>.It Cm  rmdir
>Remove the path if empty.
>.It Cm  rmdirs
>Remove empty directories under the path.
>.It Cm  serve
>Serve a remote over a protocol.
>.It Cm  settier
>Changes storage class/tier of objects in remote.
>.It Cm  sha1sum
>Produces an sha1sum file for all the objects in the path.
>.It Cm  size
>Prints the total size and number of objects in remote:path.
>.It Cm  sync
>Make source and dest identical, modifying destination only.
>.It Cm  touch
>Create new file or change file modification time.
>.It Cm  tree
>List the contents of the remote in a tree like fashion.
>.It Cm  version
>Show the version number.
>.El
>
>
>.Ss Remote paths
>On local file system, the leading '/' will differentiate between relative directories, like
>.Em path/to/dir
>or absolute, like
>.Em /path/to/dir .
>.Pp
>However, the leading '/' is ignored on most remotes, so
>.Em remote:path/to/dir
>and
>.Em remote:/path/to/dir
>refers to the same directory. This is not the case for fTP, SFTP, Dropbox for business :
>.Em remote:path/to/dir
>refers to your home directory, while
>.Em remote:/path/to/dir
>referts to a directory in the root
>.Pp
>An advanced form for creating remotes on the fly is to use
>.Em :backend:path/to/dir .
>For example, listing all the directories in the root of folder on
>.Lk https://pub.rclone.org/ :
>.Dl rclone lsd --http-url https://pub.rclone.org :http:
>Other examples are given in
>.Sx
>.Pp
> Remote names may only contain 0-9, A-Z ,a-z ,_ , - and space. They  may not start with -.
>.Sx Special characters
>Spaces or shell metacharacters (e.g. *, ?, $, ', ", etc.) must be quoted by single quotes (').
>If you want to send a single quote ('), you will need to used a double quote (").
>.Pp
>As a colon (:) mark a remote name in
>.Nm ,
>this may conflict with some filenames. Use either the absolute path or prefix the filename with ./, like this :
>.Dl    rclone sync -i ./sync:me remote:path
>.Dl    rclone sync -i /full/path/to/sync:me remote:path
>.Ss Server Side Copy
>Most remotes (but not all) support server-side copy.
>This means that copying one folder to another will be done in-place by the server.
>Remotes which don't support server-side copy will download and
>re-upload in this case.
>.Pp
>Server side copies are used with
>.Cm sync
>and
>.Cm copy
>and will be
>identified in the log when using the
>.Fl v
>flag.  The
>.Cm move
>command
>may also use them if remote doesn't support server-side move directly.
>This is done by issuing a server-side copy then a delete which is much
>quicker than a download and re-upload.
>.Pp
>Server side copies will only be attempted if the remote names are the
>same.
>
>.Ss Options
>Options that take parameters can have the values passed in two ways,
>--option=value or --option value. However boolean (true/false)
>options behave slightly differently to the other options in that
>--boolean sets the option to true and the absence of the flag sets
>it to false.  It is also possible to specify --boolean=false or
>--boolean=true.  Note that --boolean false is not valid - this is
>parsed as --boolean and the false is parsed as an extra command
>line argument for rclone.
>
>Options which use TIME use the go time parser.  A duration string is a
>possibly signed sequence of decimal numbers, each with optional
>fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid
>time units are "ns", "us" (or "Âµs"), "ms", "s", "m", "h".
>
>Options which use SIZE use kByte by default.  However, a suffix of b
>for bytes, k for kBytes, M for MBytes, G for GBytes, T for
>TBytes and P for PBytes may be used.  These are the binary units, e.g.
>1, 2\*\*10, 2\*\*20, 2\*\*30 respectively.
>.Bl -tag -width Ds
>.It Fl -backup-dir Ar dir
>This will contain any files which would have been overwritten or deleted by
>.Cm sync ,
>.Cm copy
>or
>.Cm move.
>Original hierarchy is preserved.
>If
>.Fl -suffix
>is set, the moved files will have the suffix added
>to them.  If there is a file with the same path (after the suffix has
>been added) in DIR, then it will be overwritten.
>.Pp
>The remote in use must support server-side move or copy and you must
>use the same remote as the destination of the sync.  The backup
>directory must not overlap the destination directory.
>.It Fl -bind Ar string
>Local address to bind to for outgoing connections.  This can be an
>IPv4 address (1.2.3.4), an IPv6 address (1234::789A) or host name.  If
>the host name doesn't resolve or resolves to more than one IP address
>it will give an error.
>.It Fl -bwlimit Ar bandwidth
>Controls the bandwidth limit. For the duration of the session,
>specify the desired bandwidth in kBytes/s (not kBit/s !!), or use a suffix
>.Ar b|k|M|G (in Bytes).
>The
>default is 0 which means to not limit bandwidth.
>For example, to limit bandwidth usage to 10 MBytes/s use
>.Fl -bwlimit Ar 10M
>.Pp
>To set limits at certain times,specify a "timetable" by format your
>entries as
>.Ar bandwidth
>.Op Ar weekday- Ns
>.Ar HH:MM Ns , Op Ar weekday- Ns
>.Ar HH:MM ...
>where : HH:MM is an hour from 00:00 to 23:59.
>An example of a typical timetable to avoid link saturation during daytime
>working hours could be:
>.Dl Fl -bwlimit "08:00,512 12:00,10M 13:00,512 18:00,30M 23:00,off"
>It mean that, the transfer bandwidth will be set to 512kBytes/sec on Monday.
>It will raise to 10Mbytes/s before the end of Friday.
>At 10:00 on Sunday it will be set to 1Mbyte/s.
>From 20:00 at Sunday will be unlimited.
>.Pp
>Timeslots without weekday are extended to whole week.
>So this:
>.Dl Fl -bwlimit "Mon-00:00,512 12:00,1M Sun-20:00,off"
>Is equal to this:
>.Dl Fl -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"
>.Pp
>Bandwidth limits only apply to the data transfer. They don't apply to the
>bandwidth of the directory listings etc.
>.Pp
>On Unix systems (Linux, macOS, â¦) the bandwidth limiter can be toggled by
>sending a SIGUSR2 signal to rclone. This allows to remove the limitations
>of a long running rclone transfer and to restore it back to the value specified
>with --bwlimit quickly when needed. Assuming there is only one rclone instance
>running, you can toggle the limiter like this:
>.Dl kill -SIGUSR2 $(pidof rclone)
>.Pp
>If you configure rclone with a [remote control](/rc) then you can use
>change the bwlimit dynamically:
>.Dl rclone rc core/bwlimit rate=1M
>.It Fl --bwlimit-file=BANDWIDTH_SPEC ##
>.It Fl --buffer-size=SIZE TODO
>.It Fl --check-first TODO
>.It Fl --checkers=N TODO
>.It Fl -c, --checksum TODO
>.It Fl --compare-dest=DIR TODO
>.It Fl --config=CONFIG_FILE TODO
>.It Fl --contimeout=TIME TODO
>.It Fl --copy-dest=DIR TODO
>.It Fl --dedupe-mode MODE TODO
>.It Fl --disable FEATURE,FEATURE,... TODO
>.It Fl -n, --dry-run TODO
>.It Fl --expect-continue-timeout=TIME TODO
>.It Fl --error-on-no-transfer TODO
>.It Fl --header TODO
>.It Fl --header-download TODO
>.It Fl --header-upload TODO
>.It Fl --ignore-case-sync TODO
>.It Fl --ignore-checksum TODO
>.It Fl --ignore-existing TODO
>.It Fl --ignore-size TODO
>.It Fl -I, --ignore-times TODO
>.It Fl --immutable TODO
>.It Fl -i / --interactive {#interactive}
>.It Fl --leave-root #TODO
>.It Fl --log-file=FILE TODO
>.It Fl --log-format LIST TODO
>.It Fl --log-level LEVEL TODO
>.It Fl --use-json-log TODO
>.It Fl --low-level-retries NUMBER TODO
>.It Fl --max-backlog=N TODO
>.It Fl --max-delete=N TODO
>.It Fl --max-depth=N TODO
>.It Fl --max-duration=TIME TODO
>.It Fl --max-transfer=SIZE TODO
>.It Fl --cutoff-mode=hard|soft|cautious TODO
>.It Fl --modify-window=TIME TODO
>.It Fl --multi-thread-cutoff=SIZE TODO
>.It Fl --multi-thread-streams=N TODO
>.It Fl --no-check-dest TODO
>.It Fl --no-gzip-encoding TODO
>.It Fl --no-traverse TODO
>.It Fl --no-unicode-normalization TODO
>.It Fl --no-update-modtime TODO
>.It Fl --order-by string TODO
>.It Fl --password-command SpaceSepList TODO
>.It Fl -P, --progress TODO
>.It Fl --progress-terminal-title TODO
>.It Fl -q, --quiet TODO
>.It Fl --refresh-times TODO
>.It Fl --retries int TODO
>.It Fl --retries-sleep=TIME TODO
>.It Fl --size-only TODO
>.It Fl --stats=TIME TODO
>.It Fl --stats-file-name-length integer TODO
>.It Fl --stats-log-level string TODO
>.It Fl --stats-one-line TODO
>.It Fl --stats-one-line-date TODO
>.It Fl --stats-one-line-date-format TODO
>.It Fl --stats-unit=bits|bytes TODO
>.It Fl --suffix=SUFFIX TODO
>.It Fl --suffix-keep-extension TODO
>.It Fl --syslog TODO
>.It Fl --syslog-facility string TODO
>.It Fl --tpslimit float TODO
>.It Fl --tpslimit-burst int TODO
>.It Fl --track-renames TODO
>.It Fl --track-renames-strategy (hash,modtime,leaf,size) TODO
>.It Fl --delete-(before,during,after) TODO
>.It Fl --fast-list TODO
>.It Fl --timeout=TIME TODO
>.It Fl --transfers=N TODO
>.It Fl -u, --update TODO
>.It Fl --use-mmap TODO
>.It Fl --use-server-modtime TODO
>.It Fl -v, -vv, --verbose TODO
>.It Fl -V, --version TODO
>.It Fl --ca-cert string
>.It Fl --client-cert string
>.It Fl --client-key string
>.It Fl --no-check-certificate=true/false TODO
>.El
>.Ss Error codes
>TODO
>.Sh EXAMPLES
>To list a remote
>.Dl $ rclone ls remote:path
>.Pp
>To copy /local/path to the remote
>.Dl $ rclone copy /local/path remote:path
>.Pp
>To sync /local/path to the remote
>.Dl $ rclone sync -i /local/path remote:path #
>.Pp
>To copy a single file, the destination remote must always be a directory. The following command
>will place in test.jpg in /tmp/download:
>.Dl rclone copy remote:test.jpg /tmp/download
>.Ss Advanced remote names
>To list files and directories in
>.Lk https://example.com/path/to/dir/
>.Dl rclone lsf --http-url https://example.com :http:path/to/dir
>.Pp
>To copy files and directories in
>.Lk https://example.com/path/to/dir
>to /tmp/dir:
>.Dl rclone copy --http-url https://example.com :http:path/to/dir /tmp/dir
>.Pp
>To copy files and directories from example.com in the relative
>directory path/to/dir to /tmp/dir using sftp.
>.Dl rclone copy --sftp-host example.com :sftp:path/to/dir /tmp/dir
>.Pp
>.Sh AUTHOR
>.Nm
>was written in Go by
>.An Nick Craig-Wood Aq Mt nick@craig-wood.com
>in 2014.

Actions: View

Attachments on bug 252919: 221815 | 222133