upstream commit

Add URI support to ssh, sftp and scp.  For example
ssh://user@host or sftp://user@host/path.  The connection parameters
described in draft-ietf-secsh-scp-sftp-ssh-uri-04 are not implemented since
the ssh fingerprint format in the draft uses md5 with no way to specify the
hash function type.  OK djm@

Upstream-ID: 4ba3768b662d6722de59e6ecb00abf2d4bf9cacc

1 files changed, 40 insertions, 37 deletions

diff --git a/sftp.1 b/sftp.1
index c218376fb..49f7febf1 100644
--- a/sftp.1
+++ b/sftp.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: sftp.1,v 1.110 2017/05/03 21:49:18 naddy Exp $
+.\" $OpenBSD: sftp.1,v 1.111 2017/10/21 23:06:24 millert Exp $
 .\"
 .\" Copyright (c) 2001 Damien Miller.  All rights reserved.
 .\"
@@ -22,7 +22,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 3 2017 $
+.Dd $Mdocdate: October 21 2017 $
 .Dt SFTP 1
 .Os
 .Sh NAME
@@ -44,54 +44,52 @@
 .Op Fl R Ar num_requests
 .Op Fl S Ar program
 .Op Fl s Ar subsystem | sftp_server
-.Ar host
-.Ek
-.Nm sftp
-.Oo Ar user Ns @ Oc Ns
-.Ar host Ns Op : Ns Ar
-.Nm sftp
-.Oo
-.Ar user Ns @ Oc Ns
-.Ar host Ns Oo : Ns Ar dir Ns
-.Op Ar /
-.Oc
-.Nm sftp
-.Fl b Ar batchfile
-.Oo Ar user Ns @ Oc Ns Ar host
+.Ar destination
 .Sh DESCRIPTION
 .Nm
-is an interactive file transfer program, similar to
+is a file transfer program, similar to
 .Xr ftp 1 ,
 which performs all operations over an encrypted
 .Xr ssh 1
 transport.
 It may also use many features of ssh, such as public key authentication and
 compression.
-.Nm
-connects and logs into the specified
-.Ar host ,
-then enters an interactive command mode.
 .Pp
-The second usage format will retrieve files automatically if a non-interactive
+The
+.Ar destination
+may be specified either as
+.Oo Ar user Ns @ Oc Ns Ar host Ns Oo : Ns Ar path Oc
+or as an sftp URI in the form
+.No sftp:// Ns Oo Ar user Ns @ Oc Ns Ar host Ns
+.Oo : Ns Ar port Oc Ns Oo / Ns Ar path Oc .
+.Pp
+If the
+.Ar destination
+includes a
+.Ar path
+and it is not a directory,
+.Nm
+will retrieve files automatically if a non-interactive
 authentication method is used; otherwise it will do so after
 successful interactive authentication.
 .Pp
-The third usage format allows
+If no
+.Ar path
+is specified, or if the
+.Ar path
+is a directory,
 .Nm
-to start in a remote directory.
-.Pp
-The final usage format allows for automated sessions using the
-.Fl b
-option.
-In such cases, it is necessary to configure non-interactive authentication
-to obviate the need to enter a password at connection time (see
-.Xr sshd 8
-and
-.Xr ssh-keygen 1
-for details).
+will log in to the specified
+.Ar host
+and enter interactive command mode, changing to the remote directory
+if one was specified.
+An optional trailing slash can be used to force the
+.Ar path
+to be interpreted as a directory.
 .Pp
-Since some usage formats use colon characters to delimit host names from path
-names, IPv6 addresses must be enclosed in square brackets to avoid ambiguity.
+Since the destination formats use colon characters to delimit host
+names from path names or port numbers, IPv6 addresses must be
+enclosed in square brackets to avoid ambiguity.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
@@ -121,7 +119,12 @@ Batch mode reads a series of commands from an input
 instead of
 .Em stdin .
 Since it lacks user interaction it should be used in conjunction with
-non-interactive authentication.
+non-interactive authentication to obviate the need to enter a password
+at connection time (see
+.Xr sshd 8
+and
+.Xr ssh-keygen 1
+for details).
 A
 .Ar batchfile
 of