375 lines
10 KiB
Markdown
375 lines
10 KiB
Markdown
---
|
|
title: "SFTP"
|
|
description: "SFTP"
|
|
date: "2017-02-01"
|
|
---
|
|
|
|
<i class="fa fa-server"></i> SFTP
|
|
----------------------------------------
|
|
|
|
SFTP is the [Secure (or SSH) File Transfer
|
|
Protocol](https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol).
|
|
|
|
The SFTP backend can be used with a number of different providers:
|
|
|
|
* {{< provider name="C14" home="https://www.online.net/en/storage/c14-cold-storage" config="/sftp/#c14" >}}
|
|
* {{< provider name="rsync.net" home="https://rsync.net/products/rclone.html" config="/sftp/#rsync-net" >}}
|
|
|
|
SFTP runs over SSH v2 and is installed as standard with most modern
|
|
SSH installations.
|
|
|
|
Paths are specified as `remote:path`. If the path does not begin with
|
|
a `/` it is relative to the home directory of the user. An empty path
|
|
`remote:` refers to the user's home directory.
|
|
|
|
"Note that some SFTP servers will need the leading / - Synology is a
|
|
good example of this. rsync.net, on the other hand, requires users to
|
|
OMIT the leading /.
|
|
|
|
Here is an example of making an SFTP configuration. First run
|
|
|
|
rclone config
|
|
|
|
This will guide you through an interactive setup process.
|
|
|
|
```
|
|
No remotes found - make a new one
|
|
n) New remote
|
|
s) Set configuration password
|
|
q) Quit config
|
|
n/s/q> n
|
|
name> remote
|
|
Type of storage to configure.
|
|
Choose a number from below, or type in your own value
|
|
[snip]
|
|
XX / SSH/SFTP Connection
|
|
\ "sftp"
|
|
[snip]
|
|
Storage> sftp
|
|
SSH host to connect to
|
|
Choose a number from below, or type in your own value
|
|
1 / Connect to example.com
|
|
\ "example.com"
|
|
host> example.com
|
|
SSH username, leave blank for current username, ncw
|
|
user> sftpuser
|
|
SSH port, leave blank to use default (22)
|
|
port>
|
|
SSH password, leave blank to use ssh-agent.
|
|
y) Yes type in my own password
|
|
g) Generate random password
|
|
n) No leave this optional password blank
|
|
y/g/n> n
|
|
Path to unencrypted PEM-encoded private key file, leave blank to use ssh-agent.
|
|
key_file>
|
|
Remote config
|
|
--------------------
|
|
[remote]
|
|
host = example.com
|
|
user = sftpuser
|
|
port =
|
|
pass =
|
|
key_file =
|
|
--------------------
|
|
y) Yes this is OK
|
|
e) Edit this remote
|
|
d) Delete this remote
|
|
y/e/d> y
|
|
```
|
|
|
|
This remote is called `remote` and can now be used like this:
|
|
|
|
See all directories in the home directory
|
|
|
|
rclone lsd remote:
|
|
|
|
Make a new directory
|
|
|
|
rclone mkdir remote:path/to/directory
|
|
|
|
List the contents of a directory
|
|
|
|
rclone ls remote:path/to/directory
|
|
|
|
Sync `/home/local/directory` to the remote directory, deleting any
|
|
excess files in the directory.
|
|
|
|
rclone sync /home/local/directory remote:directory
|
|
|
|
### SSH Authentication ###
|
|
|
|
The SFTP remote supports three authentication methods:
|
|
|
|
* Password
|
|
* Key file
|
|
* ssh-agent
|
|
|
|
Key files should be PEM-encoded private key files. For instance `/home/$USER/.ssh/id_rsa`.
|
|
Only unencrypted OpenSSH or PEM encrypted files are supported.
|
|
|
|
If you don't specify `pass` or `key_file` then rclone will attempt to contact an ssh-agent.
|
|
|
|
You can also specify `key_use_agent` to force the usage of an ssh-agent. In this case
|
|
`key_file` can also be specified to force the usage of a specific key in the ssh-agent.
|
|
|
|
Using an ssh-agent is the only way to load encrypted OpenSSH keys at the moment.
|
|
|
|
If you set the `--sftp-ask-password` option, rclone will prompt for a
|
|
password when needed and no password has been configured.
|
|
|
|
### ssh-agent on macOS ###
|
|
|
|
Note that there seem to be various problems with using an ssh-agent on
|
|
macOS due to recent changes in the OS. The most effective work-around
|
|
seems to be to start an ssh-agent in each session, eg
|
|
|
|
eval `ssh-agent -s` && ssh-add -A
|
|
|
|
And then at the end of the session
|
|
|
|
eval `ssh-agent -k`
|
|
|
|
These commands can be used in scripts of course.
|
|
|
|
### Modified time ###
|
|
|
|
Modified times are stored on the server to 1 second precision.
|
|
|
|
Modified times are used in syncing and are fully supported.
|
|
|
|
Some SFTP servers disable setting/modifying the file modification time after
|
|
upload (for example, certain configurations of ProFTPd with mod_sftp). If you
|
|
are using one of these servers, you can set the option `set_modtime = false` in
|
|
your RClone backend configuration to disable this behaviour.
|
|
|
|
<!--- autogenerated options start - DO NOT EDIT, instead edit fs.RegInfo in backend/sftp/sftp.go then run make backenddocs -->
|
|
### Standard Options
|
|
|
|
Here are the standard options specific to sftp (SSH/SFTP Connection).
|
|
|
|
#### --sftp-host
|
|
|
|
SSH host to connect to
|
|
|
|
- Config: host
|
|
- Env Var: RCLONE_SFTP_HOST
|
|
- Type: string
|
|
- Default: ""
|
|
- Examples:
|
|
- "example.com"
|
|
- Connect to example.com
|
|
|
|
#### --sftp-user
|
|
|
|
SSH username, leave blank for current username, ncw
|
|
|
|
- Config: user
|
|
- Env Var: RCLONE_SFTP_USER
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-port
|
|
|
|
SSH port, leave blank to use default (22)
|
|
|
|
- Config: port
|
|
- Env Var: RCLONE_SFTP_PORT
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-pass
|
|
|
|
SSH password, leave blank to use ssh-agent.
|
|
|
|
- Config: pass
|
|
- Env Var: RCLONE_SFTP_PASS
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-key-file
|
|
|
|
Path to PEM-encoded private key file, leave blank or set key-use-agent to use ssh-agent.
|
|
|
|
- Config: key_file
|
|
- Env Var: RCLONE_SFTP_KEY_FILE
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-key-file-pass
|
|
|
|
The passphrase to decrypt the PEM-encoded private key file.
|
|
|
|
Only PEM encrypted key files (old OpenSSH format) are supported. Encrypted keys
|
|
in the new OpenSSH format can't be used.
|
|
|
|
- Config: key_file_pass
|
|
- Env Var: RCLONE_SFTP_KEY_FILE_PASS
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-key-use-agent
|
|
|
|
When set forces the usage of the ssh-agent.
|
|
|
|
When key-file is also set, the ".pub" file of the specified key-file is read and only the associated key is
|
|
requested from the ssh-agent. This allows to avoid `Too many authentication failures for *username*` errors
|
|
when the ssh-agent contains many keys.
|
|
|
|
- Config: key_use_agent
|
|
- Env Var: RCLONE_SFTP_KEY_USE_AGENT
|
|
- Type: bool
|
|
- Default: false
|
|
|
|
#### --sftp-use-insecure-cipher
|
|
|
|
Enable the use of insecure ciphers and key exchange methods.
|
|
|
|
This enables the use of the the following insecure ciphers and key exchange methods:
|
|
|
|
- aes128-cbc
|
|
- aes192-cbc
|
|
- aes256-cbc
|
|
- 3des-cbc
|
|
- diffie-hellman-group-exchange-sha256
|
|
- diffie-hellman-group-exchange-sha1
|
|
|
|
Those algorithms are insecure and may allow plaintext data to be recovered by an attacker.
|
|
|
|
- Config: use_insecure_cipher
|
|
- Env Var: RCLONE_SFTP_USE_INSECURE_CIPHER
|
|
- Type: bool
|
|
- Default: false
|
|
- Examples:
|
|
- "false"
|
|
- Use default Cipher list.
|
|
- "true"
|
|
- Enables the use of the aes128-cbc cipher and diffie-hellman-group-exchange-sha256, diffie-hellman-group-exchange-sha1 key exchange.
|
|
|
|
#### --sftp-disable-hashcheck
|
|
|
|
Disable the execution of SSH commands to determine if remote file hashing is available.
|
|
Leave blank or set to false to enable hashing (recommended), set to true to disable hashing.
|
|
|
|
- Config: disable_hashcheck
|
|
- Env Var: RCLONE_SFTP_DISABLE_HASHCHECK
|
|
- Type: bool
|
|
- Default: false
|
|
|
|
### Advanced Options
|
|
|
|
Here are the advanced options specific to sftp (SSH/SFTP Connection).
|
|
|
|
#### --sftp-ask-password
|
|
|
|
Allow asking for SFTP password when needed.
|
|
|
|
If this is set and no password is supplied then rclone will:
|
|
- ask for a password
|
|
- not contact the ssh agent
|
|
|
|
|
|
- Config: ask_password
|
|
- Env Var: RCLONE_SFTP_ASK_PASSWORD
|
|
- Type: bool
|
|
- Default: false
|
|
|
|
#### --sftp-path-override
|
|
|
|
Override path used by SSH connection.
|
|
|
|
This allows checksum calculation when SFTP and SSH paths are
|
|
different. This issue affects among others Synology NAS boxes.
|
|
|
|
Shared folders can be found in directories representing volumes
|
|
|
|
rclone sync /home/local/directory remote:/directory --ssh-path-override /volume2/directory
|
|
|
|
Home directory can be found in a shared folder called "home"
|
|
|
|
rclone sync /home/local/directory remote:/home/directory --ssh-path-override /volume1/homes/USER/directory
|
|
|
|
- Config: path_override
|
|
- Env Var: RCLONE_SFTP_PATH_OVERRIDE
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-set-modtime
|
|
|
|
Set the modified time on the remote if set.
|
|
|
|
- Config: set_modtime
|
|
- Env Var: RCLONE_SFTP_SET_MODTIME
|
|
- Type: bool
|
|
- Default: true
|
|
|
|
#### --sftp-md5sum-command
|
|
|
|
The command used to read md5 hashes. Leave blank for autodetect.
|
|
|
|
- Config: md5sum_command
|
|
- Env Var: RCLONE_SFTP_MD5SUM_COMMAND
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
#### --sftp-sha1sum-command
|
|
|
|
The command used to read sha1 hashes. Leave blank for autodetect.
|
|
|
|
- Config: sha1sum_command
|
|
- Env Var: RCLONE_SFTP_SHA1SUM_COMMAND
|
|
- Type: string
|
|
- Default: ""
|
|
|
|
<!--- autogenerated options stop -->
|
|
|
|
### Limitations ###
|
|
|
|
SFTP supports checksums if the same login has shell access and `md5sum`
|
|
or `sha1sum` as well as `echo` are in the remote's PATH.
|
|
This remote checksumming (file hashing) is recommended and enabled by default.
|
|
Disabling the checksumming may be required if you are connecting to SFTP servers
|
|
which are not under your control, and to which the execution of remote commands
|
|
is prohibited. Set the configuration option `disable_hashcheck` to `true` to
|
|
disable checksumming.
|
|
|
|
SFTP also supports `about` if the same login has shell
|
|
access and `df` are in the remote's PATH. `about` will
|
|
return the total space, free space, and used space on the remote
|
|
for the disk of the specified path on the remote or, if not set,
|
|
the disk of the root on the remote.
|
|
`about` will fail if it does not have shell
|
|
access or if `df` is not in the remote's PATH.
|
|
|
|
Note that some SFTP servers (eg Synology) the paths are different for
|
|
SSH and SFTP so the hashes can't be calculated properly. For them
|
|
using `disable_hashcheck` is a good idea.
|
|
|
|
The only ssh agent supported under Windows is Putty's pageant.
|
|
|
|
The Go SSH library disables the use of the aes128-cbc cipher by
|
|
default, due to security concerns. This can be re-enabled on a
|
|
per-connection basis by setting the `use_insecure_cipher` setting in
|
|
the configuration file to `true`. Further details on the insecurity of
|
|
this cipher can be found [in this paper]
|
|
(http://www.isg.rhul.ac.uk/~kp/SandPfinal.pdf).
|
|
|
|
SFTP isn't supported under plan9 until [this
|
|
issue](https://github.com/pkg/sftp/issues/156) is fixed.
|
|
|
|
Note that since SFTP isn't HTTP based the following flags don't work
|
|
with it: `--dump-headers`, `--dump-bodies`, `--dump-auth`
|
|
|
|
Note that `--timeout` isn't supported (but `--contimeout` is).
|
|
|
|
|
|
## C14 {#c14}
|
|
|
|
C14 is supported through the SFTP backend.
|
|
|
|
See [C14's documentation](https://www.online.net/en/storage/c14-cold-storage)
|
|
|
|
## rsync.net {#rsync-net}
|
|
|
|
rsync.net is supported through the SFTP backend.
|
|
|
|
See [rsync.net's documentation of rclone examples](https://www.rsync.net/products/rclone.html).
|