path: root/usr/src/man/man1/sftp.sunssh.1

'\" te
.\" To view license terms, attribution, and copyright for OpenSSH, the default path is /var/sadm/pkg/SUNWsshdr/install/copyright. If the Solaris operating environment has been installed anywhere other than the default, modify the specified path to access
.\" the file at the installed location.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.TH SFTP 1 "Nov 8, 2007"
.SH NAME
sftp \- secure file transfer program
.SH SYNOPSIS
.LP
.nf
\fBsftp\fR [\fB-1Cv\fR] [\fB-B\fR \fIbuffer_size\fR] [\fB-b\fR \fIbatchfile\fR] [\fB-F\fR \fIssh_config\fR]
      [\fB-o\fR \fIssh_option\fR] [\fB-P\fR \fIsftp_server_path\fR] [\fB-R\fR \fInum_requests\fR]
      [\fB-S\fR \fIprogram\fR] [\fB-s\fR \fIsubsystem\fR | \fIsftp_server\fR] \fIhost\fR
.fi

.LP
.nf
\fBsftp\fR [[\fIuser\fR\fB@\fR]\fIhost\fR[\fB:\fR\fIfile\fR [\fIfile\fR]]]
.fi

.LP
.nf
\fBsftp\fR [[\fIuser\fR\fB@\fR]\fIhost\fR[:\fIdir\fR[\fB/\fR]]]
.fi

.LP
.nf
\fBsftp\fR \fB-b\fR \fIbatchfile\fR [\fIuser\fR\fB@\fR]\fIhost\fR
.fi

.SH DESCRIPTION
.LP
The \fBsftp\fR utility is an interactive file transfer program with a user
interface similar to \fBftp\fR(1) that uses the \fBssh\fR(1) command to create
a secure connection to the server.
.sp
.LP
\fBsftp\fR implements the SSH File Transfer Protocol as defined in IETF
\fBdraft-ietf-secsh-filexfer\fR. There is no relationship between the protocol
used by \fBsftp\fR and the FTP protocol (\fIRFC 959\fR) provided by
\fBftp\fR(1).
.sp
.LP
The first usage format causes \fBsftp\fR to connect to the specified host and
enter an interactive mode. If a username was provided then \fBsftp\fR tries to
log in as the specified user. If a directory is provided then \fBsftp\fR tries
to change the current directory on the server to the specified directory before
entering the interactive mode.
.sp
.LP
The second usage format retrieves the specified file from the server and copies
it to the specified target file or directory on the client. If a username is
specified \fBsftp\fR tries to log in as the specified user.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-b\fR \fIbatchfile\fR\fR
.ad
.RS 30n
Batch mode reads a series of commands from an input \fIbatchfile\fR instead of
\fBstdin\fR. Since it lacks user interaction, it should be used in conjunction
with non-interactive authentication. A batchfile of \fB-\fR can be used to
indicate standard input. \fBsftp\fR aborts if any of the following commands
fail: \fBget\fR, \fBput\fR, \fBrm\fR, \fBrename\fR, \fBln\fR, \fBrm\fR,
\fBmkdir\fR, \fBchdir\fR, \fBls\fR, \fBlchdir\fR, \fBchmod\fR, \fBchown\fR,
\fBchgrp\fR, \fBlpwd\fR, and \fBlmkdir\fR. Termination on error can be
suppressed on a command by command basis by prefixing the command with a
\fB-\fR character (for example, \fB-rm /tmp/blah*\fR).
.RE

.sp
.ne 2
.na
\fB\fB-B\fR \fIbuffer_size\fR\fR
.ad
.RS 30n
Specifies the size of the buffer that \fBsftp\fR uses when transferring files.
Larger buffers require fewer round trips at the cost of higher memory
consumption. The default is 32768 bytes.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 30n
Enables compression, using the \fB-C\fR flag in \fBssh\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fIssh_config\fR\fR
.ad
.RS 30n
Specifies an alternative per-user configuration file for \fBssh\fR. This option
is directly passed to \fBssh\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIssh_option\fR\fR
.ad
.RS 30n
Specifies an option to be directly passed to \fBssh\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIsftp_server path\fR\fR
.ad
.RS 30n
Executes the specified path as an \fIsftp-server\fR and uses a pipe, rather
than an \fBssh\fR connection, to communicate with it. This option can be useful
in debugging the \fBsftp\fR client and server. The \fB-P\fR and \fB-S\fR
options are mutually exclusive.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fInum_requests\fR\fR
.ad
.RS 30n
Specifies how many requests can be outstanding at any one time. Increasing this
can slightly improve file transfer speed but increases memory usage. The
default is 16 outstanding requests.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsubsystem\fR | \fIsftp_server\fR\fR
.ad
.RS 30n
Specifies the \fBSSH2\fR subsystem or the path for an \fBsftp\fR server on the
remote host. A path is useful for using \fBsftp\fR over protocol version 1, or
when the remote \fBsshd\fR does not have an \fBsftp\fR subsystem configured.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIssh_program\fR \fIpath\fR\fR
.ad
.RS 30n
Uses the specified program instead of \fBssh\fR(1) to connect to the \fBsftp\fR
server. The \fB-P\fR and \fB-S\fR options are mutually exclusive. The program
must understand \fBssh\fR(1) options.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 30n
Raises logging level. This option is also passed to \fBssh\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-1\fR\fR
.ad
.RS 30n
Specifies the use of protocol version 1.
.RE

.SH OPERANDS
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIhostname\fR | \fIuser@hostname\fR\fR
.ad
.RS 28n
The name of the host to which \fBsftp\fR connects and logs into.
.RE

.SH INTERACTIVE COMMANDS
.LP
Once in interactive mode, \fBsftp\fR understands a set of commands similar to
those of \fBftp\fR(1). Commands are case insensitive and path names can be
enclosed in quotes if they contain spaces.
.sp
.ne 2
.na
\fB\fBbye\fR\fR
.ad
.sp .6
.RS 4n
Quits \fBsftp\fR.
.RE

.sp
.ne 2
.na
\fB\fBcd\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Changes remote directory to \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBchgrp\fR \fIgrp path\fR\fR
.ad
.sp .6
.RS 4n
Changes group of file \fIpath\fR to \fIgrp\fR. \fIgrp\fR must be a numeric
\fBGID\fR.
.RE

.sp
.ne 2
.na
\fB\fBchmod\fR \fImode path\fR\fR
.ad
.sp .6
.RS 4n
Changes permissions of file \fIpath\fR to \fImode\fR.
.RE

.sp
.ne 2
.na
\fB\fBchown\fR \fIown path\fR\fR
.ad
.sp .6
.RS 4n
Changes owner of file \fIpath\fR to \fIown\fR. \fIown\fR must be a numeric
\fBUID\fR.
.RE

.sp
.ne 2
.na
\fB\fBexit\fR\fR
.ad
.sp .6
.RS 4n
Quits \fBsftp\fR.
.RE

.sp
.ne 2
.na
\fB\fBget\fR [\fIflags\fR] \fIremote-path\fR [\fIlocal-path\fR]\fR
.ad
.sp .6
.RS 4n
Retrieves the \fIremote-path\fR and stores it on the local machine. If the
local path name is not specified, it is specified the same name it has on the
remote machine. If the \fB-P\fR flag is specified, then the file's full
permission and access time are copied too.
.RE

.sp
.ne 2
.na
\fB\fBhelp\fR\fR
.ad
.sp .6
.RS 4n
Displays help text.
.sp
Identical to the \fB?\fR command.
.RE

.sp
.ne 2
.na
\fB\fBlcd\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Changes local directory to \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBlls\fR [\fIls-options\fR [\fIpath\fR]]\fR
.ad
.sp .6
.RS 4n
Displays local directory listing of either \fIpath\fR or current directory if
\fIpath\fR is not specified.
.RE

.sp
.ne 2
.na
\fB\fBlmkdir\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Creates local directory specified by \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBln\fR \fIoldpath\fR \fInewpath\fR\fR
.ad
.sp .6
.RS 4n
Creates a link from \fIoldpath\fR to \fInewpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBlpwd\fR\fR
.ad
.sp .6
.RS 4n
Prints local working directory.
.RE

.sp
.ne 2
.na
\fB\fBls\fR [\fB-1aflnrSt\fR] [\fIpath\fR]\fR
.ad
.sp .6
.RS 4n
Displays remote directory listing of either \fIpath\fR or current directory if
\fIpath\fR is not specified. \fIpath\fR can contain wildcards.
.sp
The \fBls\fR supports the following options:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 6n
Lists files beginning with a dot (\fB\&.\fR).
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Does not sort the listing. The default sort order is lexicographical.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 6n
Displays additional details including permissions and ownership information.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 6n
Produces a long listing with user and group information presented numerically.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 6n
Reverses the sort order of the listing.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.RS 6n
Sorts the listing by file size.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 6n
Sorts the listing by last modification time.
.RE

.sp
.ne 2
.na
\fB\fB-1\fR\fR
.ad
.RS 6n
Produces single column output.
.RE

.RE

.sp
.ne 2
.na
\fB\fBlumask\fR \fIumask\fR\fR
.ad
.sp .6
.RS 4n
Sets local \fBumask\fR to \fIumask\fR.
.RE

.sp
.ne 2
.na
\fB\fBmkdir\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Creates remote directory specified by \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBput\fR [\fIflags\fR] \fIlocal-path\fR [\fIlocal-path\fR]\fR
.ad
.sp .6
.RS 4n
Uploads \fIlocal-path\fR and stores it on the remote machine. If the remote
path name is not specified, it is specified the same name it has on the local
machine. If the \fB-P\fR flag is specified, then the file's full permission and
access time are copied too.
.RE

.sp
.ne 2
.na
\fB\fBpwd\fR\fR
.ad
.sp .6
.RS 4n
Displays remote working directory.
.RE

.sp
.ne 2
.na
\fB\fBquit\fR\fR
.ad
.sp .6
.RS 4n
Quits \fBsftp\fR.
.RE

.sp
.ne 2
.na
\fB\fBrename\fR \fIoldpath newpath\fR\fR
.ad
.sp .6
.RS 4n
Renames remote file from \fIoldpath\fR to \fInewpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBrm\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Deletes remote file specified by \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBrmdir\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Removes remote directory specified by \fIpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBsymlink\fR \fIoldpath\fR \fInewpath\fR\fR
.ad
.sp .6
.RS 4n
Creates a symbolic link from \fIoldpath\fR to \fInewpath\fR.
.RE

.sp
.ne 2
.na
\fB\fBversion\fR\fR
.ad
.sp .6
.RS 4n
Displays the \fBsftp\fR protocol version.
.RE

.sp
.ne 2
.na
\fB\fB#\fR [\fIcomment\fR]\fR
.ad
.sp .6
.RS 4n
Include a comment. This is useful in batch files.
.RE

.sp
.ne 2
.na
\fB\fB!\fR [\fIcommand\fR]\fR
.ad
.sp .6
.RS 4n
If \fIcommand\fR is not specified, escapes to the local shell.
.sp
If \fIcommand\fR is specified, executes \fIcommand\fR in the local shell.
.RE

.sp
.ne 2
.na
\fB\fB?\fR\fR
.ad
.sp .6
.RS 4n
Displays help text.
.sp
Identical to the \fBhelp\fR command.
.RE

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.LP
\fBftp\fR(1), \fBscp\fR(1), \fBssh\fR(1), \fBssh-add\fR(1),
\fBssh-keygen\fR(1), \fBsshd\fR(1M), \fBattributes\fR(5)