340 lines
9.2 KiB
Markdown
340 lines
9.2 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).
|
|
|
|
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.
|
|
|
|
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
|
|
1 / Amazon Drive
|
|
\ "amazon cloud drive"
|
|
2 / Amazon S3 (also Dreamhost, Ceph, Minio)
|
|
\ "s3"
|
|
3 / Backblaze B2
|
|
\ "b2"
|
|
4 / Dropbox
|
|
\ "dropbox"
|
|
5 / Encrypt/Decrypt a remote
|
|
\ "crypt"
|
|
6 / FTP Connection
|
|
\ "ftp"
|
|
7 / Google Cloud Storage (this is not Google Drive)
|
|
\ "google cloud storage"
|
|
8 / Google Drive
|
|
\ "drive"
|
|
9 / Hubic
|
|
\ "hubic"
|
|
10 / Local Disk
|
|
\ "local"
|
|
11 / Microsoft OneDrive
|
|
\ "onedrive"
|
|
12 / Openstack Swift (Rackspace Cloud Files, Memset Memstore, OVH)
|
|
\ "swift"
|
|
13 / SSH/SFTP Connection
|
|
\ "sftp"
|
|
14 / Yandex Disk
|
|
\ "yandex"
|
|
15 / http Connection
|
|
\ "http"
|
|
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 the aes128-cbc cipher. This cipher is 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.
|
|
|
|
#### --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.
|
|
|
|
- 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
|
|
|
|
<!--- 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.
|
|
|
|
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).
|