From 05321f4aef712cd25f547b2eccdbdbd1e4525b94 Mon Sep 17 00:00:00 2001 From: albertony <12441419+albertony@users.noreply.github.com> Date: Mon, 11 Oct 2021 10:35:03 +0200 Subject: [PATCH] docs/sftp: more detailed explanation of pubkey file and certificate --- docs/content/sftp.md | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/docs/content/sftp.md b/docs/content/sftp.md index 471d3fa63..c6aff29eb 100644 --- a/docs/content/sftp.md +++ b/docs/content/sftp.md @@ -25,7 +25,7 @@ would list the home directory of the user cofigured in the rclone remote config (`i.e /home/sftpuser`). However, `rclone lsd remote:/` would list the root directory for remote machine (i.e. `/`) -"Note that some SFTP servers will need the leading / - Synology is a +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 /. @@ -123,25 +123,39 @@ Only unencrypted OpenSSH or PEM encrypted files are supported. The key file can be specified in either an external file (key_file) or contained within the rclone config file (key_pem). If using key_pem in the config file, the entry should be on a -single line with new line ('\n' or '\r\n') separating lines. i.e. +single line with new line ('\n' or '\r\n') separating lines. i.e. -key_pem = -----BEGIN RSA PRIVATE KEY-----\nMaMbaIXtE\n0gAMbMbaSsd\nMbaass\n-----END RSA PRIVATE KEY----- + key_pem = -----BEGIN RSA PRIVATE KEY-----\nMaMbaIXtE\n0gAMbMbaSsd\nMbaass\n-----END RSA PRIVATE KEY----- -This will generate it correctly for key_pem for use in the config: +This will generate it correctly for key_pem for use in the config: awk '{printf "%s\\n", $0}' < ~/.ssh/id_rsa -If you don't specify `pass`, `key_file`, or `key_pem` 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` or `key_pem` can also be specified to force the usage of a specific key in the ssh-agent. +If you don't specify `pass`, `key_file`, or `key_pem` or `ask_password` 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` or `key_pem` 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. +If you set the `ask_password` option, rclone will prompt for a password when +needed and no password has been configured. -If you have a certificate then you can provide the path to the public key that contains the certificate. For example: +#### Certificate-signed keys + +With traditional key-based authentication, you configure your private key only, +and the public key built into it will be used during the authentication process. + +If you have a certificate you may use it to sign your public key, creating a +separate SSH user certificate that should be used instead of the plain public key +extracted from the private key. Then you must provide the path to the +user certificate public key file in `pubkey_file`. + +Note: This is not the traditional public key paired with your private key, +typically saved as `/home/$USER/.ssh/id_rsa.pub`. Setting this path in +`pubkey_file` will not work. + +Example: ``` [remote] @@ -161,7 +175,7 @@ Note: the cert must come first in the file. e.g. cat id_rsa-cert.pub id_rsa > merged_key ``` -### Host key validation ### +### Host key validation By default rclone will not check the server's host key for validation. This can allow an attacker to replace a server with their own and if you use @@ -212,7 +226,7 @@ and you will need to add the appropriate `@cert-authority` entry. The `known_hosts_file` setting can be set during `rclone config` as an advanced option. -### ssh-agent on macOS ### +### 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 @@ -226,7 +240,7 @@ And then at the end of the session These commands can be used in scripts of course. -### Modified time ### +### Modified time Modified times are stored on the server to 1 second precision.