[BACK]Return to sftp.1 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / crypto / external / bsd / openssh / dist

Annotation of src/crypto/external/bsd/openssh/dist/sftp.1, Revision 1.12.2.3

1.12.2.3! pgoyette    1: .\"    $NetBSD: sftp.1,v 1.15 2017/04/18 18:41:46 christos Exp $
1.12.2.1  pgoyette    2: .\" $OpenBSD: sftp.1,v 1.105 2016/07/16 06:57:55 jmc Exp $
1.1       christos    3: .\"
                      4: .\" Copyright (c) 2001 Damien Miller.  All rights reserved.
                      5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
                     14: .\"
                     15: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
                     16: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
                     17: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
                     18: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
                     19: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
                     20: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
                     21: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
                     22: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
                     23: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
                     24: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
                     25: .\"
1.12.2.1  pgoyette   26: .Dd July 16 2016
1.1       christos   27: .Dt SFTP 1
                     28: .Os
                     29: .Sh NAME
                     30: .Nm sftp
                     31: .Nd secure file transfer program
                     32: .Sh SYNOPSIS
                     33: .Nm sftp
                     34: .Bk -words
1.10      christos   35: .Op Fl 1246aCfpqrv
1.1       christos   36: .Op Fl B Ar buffer_size
                     37: .Op Fl b Ar batchfile
1.5       adam       38: .Op Fl c Ar cipher
                     39: .Op Fl D Ar sftp_server_path
1.1       christos   40: .Op Fl F Ar ssh_config
1.5       adam       41: .Op Fl i Ar identity_file
1.6       christos   42: .Op Fl l Ar limit
1.1       christos   43: .Op Fl o Ar ssh_option
1.5       adam       44: .Op Fl P Ar port
1.1       christos   45: .Op Fl R Ar num_requests
                     46: .Op Fl S Ar program
                     47: .Op Fl s Ar subsystem | sftp_server
                     48: .Ar host
                     49: .Ek
                     50: .Nm sftp
                     51: .Oo Ar user Ns @ Oc Ns
                     52: .Ar host Ns Op : Ns Ar
                     53: .Nm sftp
1.6       christos   54: .Oo
                     55: .Ar user Ns @ Oc Ns
1.1       christos   56: .Ar host Ns Oo : Ns Ar dir Ns
1.6       christos   57: .Op Ar /
                     58: .Oc
1.1       christos   59: .Nm sftp
                     60: .Fl b Ar batchfile
                     61: .Oo Ar user Ns @ Oc Ns Ar host
                     62: .Sh DESCRIPTION
                     63: .Nm
                     64: is an interactive file transfer program, similar to
                     65: .Xr ftp 1 ,
                     66: which performs all operations over an encrypted
                     67: .Xr ssh 1
                     68: transport.
                     69: It may also use many features of ssh, such as public key authentication and
                     70: compression.
                     71: .Nm
                     72: connects and logs into the specified
                     73: .Ar host ,
                     74: then enters an interactive command mode.
                     75: .Pp
                     76: The second usage format will retrieve files automatically if a non-interactive
                     77: authentication method is used; otherwise it will do so after
                     78: successful interactive authentication.
                     79: .Pp
                     80: The third usage format allows
                     81: .Nm
                     82: to start in a remote directory.
                     83: .Pp
                     84: The final usage format allows for automated sessions using the
                     85: .Fl b
                     86: option.
                     87: In such cases, it is necessary to configure non-interactive authentication
                     88: to obviate the need to enter a password at connection time (see
                     89: .Xr sshd 8
                     90: and
                     91: .Xr ssh-keygen 1
                     92: for details).
1.7       christos   93: .Pp
                     94: Since some usage formats use colon characters to delimit host names from path
                     95: names, IPv6 addresses must be enclosed in square brackets to avoid ambiguity.
                     96: .Pp
1.1       christos   97: The options are as follows:
                     98: .Bl -tag -width Ds
                     99: .It Fl 1
                    100: Specify the use of protocol version 1.
1.5       adam      101: .It Fl 2
                    102: Specify the use of protocol version 2.
                    103: .It Fl 4
                    104: Forces
                    105: .Nm
                    106: to use IPv4 addresses only.
                    107: .It Fl 6
                    108: Forces
                    109: .Nm
                    110: to use IPv6 addresses only.
1.10      christos  111: .It Fl a
                    112: Attempt to continue interrupted transfers rather than overwriting
                    113: existing partial or complete copies of files.
                    114: If the partial contents differ from those being transferred,
                    115: then the resultant file is likely to be corrupt.
1.1       christos  116: .It Fl B Ar buffer_size
                    117: Specify the size of the buffer that
                    118: .Nm
                    119: uses when transferring files.
                    120: Larger buffers require fewer round trips at the cost of higher
                    121: memory consumption.
                    122: The default is 32768 bytes.
                    123: .It Fl b Ar batchfile
                    124: Batch mode reads a series of commands from an input
                    125: .Ar batchfile
                    126: instead of
                    127: .Em stdin .
                    128: Since it lacks user interaction it should be used in conjunction with
                    129: non-interactive authentication.
                    130: A
                    131: .Ar batchfile
                    132: of
                    133: .Sq \-
                    134: may be used to indicate standard input.
                    135: .Nm
                    136: will abort if any of the following
                    137: commands fail:
1.10      christos  138: .Ic get , put , reget , reput, rename , ln ,
1.1       christos  139: .Ic rm , mkdir , chdir , ls ,
                    140: .Ic lchdir , chmod , chown ,
1.6       christos  141: .Ic chgrp , lpwd , df , symlink ,
1.1       christos  142: and
                    143: .Ic lmkdir .
                    144: Termination on error can be suppressed on a command by command basis by
                    145: prefixing the command with a
                    146: .Sq \-
                    147: character (for example,
                    148: .Ic -rm /tmp/blah* ) .
                    149: .It Fl C
                    150: Enables compression (via ssh's
                    151: .Fl C
                    152: flag).
1.5       adam      153: .It Fl c Ar cipher
                    154: Selects the cipher to use for encrypting the data transfers.
                    155: This option is directly passed to
                    156: .Xr ssh 1 .
                    157: .It Fl D Ar sftp_server_path
                    158: Connect directly to a local sftp server
                    159: (rather than via
                    160: .Xr ssh 1 ) .
                    161: This option may be useful in debugging the client and server.
1.1       christos  162: .It Fl F Ar ssh_config
                    163: Specifies an alternative
                    164: per-user configuration file for
                    165: .Xr ssh 1 .
                    166: This option is directly passed to
                    167: .Xr ssh 1 .
1.10      christos  168: .It Fl f
                    169: Requests that files be flushed to disk immediately after transfer.
                    170: When uploading files, this feature is only enabled if the server
                    171: implements the "fsync@openssh.com" extension.
1.5       adam      172: .It Fl i Ar identity_file
                    173: Selects the file from which the identity (private key) for public key
                    174: authentication is read.
                    175: This option is directly passed to
                    176: .Xr ssh 1 .
1.6       christos  177: .It Fl l Ar limit
                    178: Limits the used bandwidth, specified in Kbit/s.
1.1       christos  179: .It Fl o Ar ssh_option
                    180: Can be used to pass options to
                    181: .Nm ssh
                    182: in the format used in
                    183: .Xr ssh_config 5 .
                    184: This is useful for specifying options
                    185: for which there is no separate
                    186: .Nm sftp
                    187: command-line flag.
                    188: For example, to specify an alternate port use:
                    189: .Ic sftp -oPort=24 .
                    190: For full details of the options listed below, and their possible values, see
                    191: .Xr ssh_config 5 .
                    192: .Pp
                    193: .Bl -tag -width Ds -offset indent -compact
                    194: .It AddressFamily
                    195: .It BatchMode
                    196: .It BindAddress
1.10      christos  197: .It CanonicalDomains
                    198: .It CanonicalizeFallbackLocal
                    199: .It CanonicalizeHostname
                    200: .It CanonicalizeMaxDots
                    201: .It CanonicalizePermittedCNAMEs
1.12      christos  202: .It CertificateFile
1.1       christos  203: .It ChallengeResponseAuthentication
                    204: .It CheckHostIP
                    205: .It Cipher
                    206: .It Ciphers
                    207: .It Compression
                    208: .It CompressionLevel
                    209: .It ConnectionAttempts
                    210: .It ConnectTimeout
                    211: .It ControlMaster
                    212: .It ControlPath
1.8       christos  213: .It ControlPersist
1.1       christos  214: .It GlobalKnownHostsFile
                    215: .It GSSAPIAuthentication
                    216: .It GSSAPIDelegateCredentials
                    217: .It HashKnownHosts
                    218: .It Host
                    219: .It HostbasedAuthentication
1.11      christos  220: .It HostbasedKeyTypes
1.1       christos  221: .It HostKeyAlgorithms
                    222: .It HostKeyAlias
                    223: .It HostName
                    224: .It IdentitiesOnly
1.12.2.1  pgoyette  225: .It IdentityAgent
                    226: .It IdentityFile
1.6       christos  227: .It IPQoS
1.8       christos  228: .It KbdInteractiveAuthentication
1.1       christos  229: .It KbdInteractiveDevices
1.6       christos  230: .It KexAlgorithms
1.1       christos  231: .It LogLevel
                    232: .It MACs
                    233: .It NoHostAuthenticationForLocalhost
                    234: .It NumberOfPasswordPrompts
                    235: .It PasswordAuthentication
1.5       adam      236: .It PKCS11Provider
1.1       christos  237: .It Port
                    238: .It PreferredAuthentications
                    239: .It Protocol
                    240: .It ProxyCommand
1.12.2.1  pgoyette  241: .It ProxyJump
1.1       christos  242: .It PubkeyAuthentication
                    243: .It RekeyLimit
                    244: .It RhostsRSAAuthentication
                    245: .It RSAAuthentication
                    246: .It SendEnv
                    247: .It ServerAliveInterval
                    248: .It ServerAliveCountMax
                    249: .It StrictHostKeyChecking
                    250: .It TCPKeepAlive
1.11      christos  251: .It UpdateHostKeys
1.1       christos  252: .It UsePrivilegedPort
                    253: .It User
                    254: .It UserKnownHostsFile
                    255: .It VerifyHostKeyDNS
                    256: .El
1.5       adam      257: .It Fl P Ar port
                    258: Specifies the port to connect to on the remote host.
                    259: .It Fl p
                    260: Preserves modification times, access times, and modes from the
                    261: original files transferred.
                    262: .It Fl q
                    263: Quiet mode: disables the progress meter as well as warning and
                    264: diagnostic messages from
                    265: .Xr ssh 1 .
1.1       christos  266: .It Fl R Ar num_requests
                    267: Specify how many requests may be outstanding at any one time.
                    268: Increasing this may slightly improve file transfer speed
                    269: but will increase memory usage.
1.4       joerg     270: The default is 256 outstanding requests providing for 8MB
1.2       christos  271: of outstanding data with a 32KB buffer.
1.5       adam      272: .It Fl r
                    273: Recursively copy entire directories when uploading and downloading.
                    274: Note that
                    275: .Nm
                    276: does not follow symbolic links encountered in the tree traversal.
1.1       christos  277: .It Fl S Ar program
                    278: Name of the
                    279: .Ar program
                    280: to use for the encrypted connection.
                    281: The program must understand
                    282: .Xr ssh 1
                    283: options.
                    284: .It Fl s Ar subsystem | sftp_server
                    285: Specifies the SSH2 subsystem or the path for an sftp server
                    286: on the remote host.
                    287: A path is useful for using
                    288: .Nm
                    289: over protocol version 1, or when the remote
                    290: .Xr sshd 8
                    291: does not have an sftp subsystem configured.
                    292: .It Fl v
                    293: Raise logging level.
                    294: This option is also passed to ssh.
                    295: .El
                    296: .Sh INTERACTIVE COMMANDS
                    297: Once in interactive mode,
                    298: .Nm
                    299: understands a set of commands similar to those of
                    300: .Xr ftp 1 .
                    301: Commands are case insensitive.
                    302: Pathnames that contain spaces must be enclosed in quotes.
                    303: Any special characters contained within pathnames that are recognized by
                    304: .Xr glob 3
                    305: must be escaped with backslashes
                    306: .Pq Sq \e .
                    307: .Bl -tag -width Ds
                    308: .It Ic bye
                    309: Quit
                    310: .Nm sftp .
                    311: .It Ic cd Ar path
                    312: Change remote directory to
                    313: .Ar path .
                    314: .It Ic chgrp Ar grp Ar path
                    315: Change group of file
                    316: .Ar path
                    317: to
                    318: .Ar grp .
                    319: .Ar path
                    320: may contain
                    321: .Xr glob 3
                    322: characters and may match multiple files.
                    323: .Ar grp
                    324: must be a numeric GID.
                    325: .It Ic chmod Ar mode Ar path
                    326: Change permissions of file
                    327: .Ar path
                    328: to
                    329: .Ar mode .
                    330: .Ar path
                    331: may contain
                    332: .Xr glob 3
                    333: characters and may match multiple files.
                    334: .It Ic chown Ar own Ar path
                    335: Change owner of file
                    336: .Ar path
                    337: to
                    338: .Ar own .
                    339: .Ar path
                    340: may contain
                    341: .Xr glob 3
                    342: characters and may match multiple files.
                    343: .Ar own
                    344: must be a numeric UID.
1.3       joerg     345: .It Ic df Oo Fl hi Oc Oo Ar path Oc
1.1       christos  346: Display usage information for the filesystem holding the current directory
                    347: (or
                    348: .Ar path
                    349: if specified).
                    350: If the
                    351: .Fl h
                    352: flag is specified, the capacity information will be displayed using
                    353: "human-readable" suffixes.
                    354: The
                    355: .Fl i
                    356: flag requests display of inode information in addition to capacity information.
                    357: This command is only supported on servers that implement the
                    358: .Dq statvfs@openssh.com
                    359: extension.
                    360: .It Ic exit
                    361: Quit
                    362: .Nm sftp .
1.9       christos  363: .It Xo Ic get
1.10      christos  364: .Op Fl afPpr
1.9       christos  365: .Ar remote-path
                    366: .Op Ar local-path
                    367: .Xc
1.1       christos  368: Retrieve the
1.2       christos  369: .Ar remote-file
1.1       christos  370: and store it on the local machine.
                    371: If the local
                    372: path name is not specified, it is given the same name it has on the
                    373: remote machine.
                    374: .Ar remote-path
                    375: may contain
                    376: .Xr glob 3
                    377: characters and may match multiple files.
                    378: If it does and
                    379: .Ar local-path
                    380: is specified, then
                    381: .Ar local-path
                    382: must specify a directory.
1.5       adam      383: .Pp
1.9       christos  384: If the
                    385: .Fl a
                    386: flag is specified, then attempt to resume partial transfers of existing files.
                    387: Note that resumption assumes that any partial copy of the local file matches
                    388: the remote copy.
1.10      christos  389: If the remote file contents differ from the partial local copy then the
                    390: resultant file is likely to be corrupt.
                    391: .Pp
                    392: If the
                    393: .Fl f
                    394: flag is specified, then
                    395: .Xr fsync 2
                    396: will be called after the file transfer has completed to flush the file
                    397: to disk.
1.9       christos  398: .Pp
1.5       adam      399: If either the
1.1       christos  400: .Fl P
1.5       adam      401: or
                    402: .Fl p
1.1       christos  403: flag is specified, then full file permissions and access times are
                    404: copied too.
1.5       adam      405: .Pp
                    406: If the
                    407: .Fl r
                    408: flag is specified then directories will be copied recursively.
                    409: Note that
                    410: .Nm
                    411: does not follow symbolic links when performing recursive transfers.
1.1       christos  412: .It Ic help
                    413: Display help text.
                    414: .It Ic lcd Ar path
                    415: Change local directory to
                    416: .Ar path .
                    417: .It Ic lls Op Ar ls-options Op Ar path
                    418: Display local directory listing of either
                    419: .Ar path
                    420: or current directory if
                    421: .Ar path
                    422: is not specified.
                    423: .Ar ls-options
                    424: may contain any flags supported by the local system's
                    425: .Xr ls 1
                    426: command.
                    427: .Ar path
                    428: may contain
                    429: .Xr glob 3
                    430: characters and may match multiple files.
                    431: .It Ic lmkdir Ar path
                    432: Create local directory specified by
                    433: .Ar path .
1.6       christos  434: .It Xo Ic ln
                    435: .Op Fl s
                    436: .Ar oldpath
                    437: .Ar newpath
                    438: .Xc
                    439: Create a link from
1.1       christos  440: .Ar oldpath
                    441: to
                    442: .Ar newpath .
1.6       christos  443: If the
                    444: .Fl s
                    445: flag is specified the created link is a symbolic link, otherwise it is
                    446: a hard link.
1.1       christos  447: .It Ic lpwd
                    448: Print local working directory.
1.5       adam      449: .It Ic ls Oo Fl 1afhlnrSt Oc Oo Ar path Oc
1.1       christos  450: Display a remote directory listing of either
                    451: .Ar path
                    452: or the current directory if
                    453: .Ar path
                    454: is not specified.
                    455: .Ar path
                    456: may contain
                    457: .Xr glob 3
                    458: characters and may match multiple files.
                    459: .Pp
                    460: The following flags are recognized and alter the behaviour of
                    461: .Ic ls
                    462: accordingly:
                    463: .Bl -tag -width Ds
                    464: .It Fl 1
                    465: Produce single columnar output.
                    466: .It Fl a
                    467: List files beginning with a dot
                    468: .Pq Sq \&. .
                    469: .It Fl f
                    470: Do not sort the listing.
                    471: The default sort order is lexicographical.
1.5       adam      472: .It Fl h
                    473: When used with a long format option, use unit suffixes: Byte, Kilobyte,
                    474: Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
                    475: the number of digits to four or fewer using powers of 2 for sizes (K=1024,
                    476: M=1048576, etc.).
1.1       christos  477: .It Fl l
                    478: Display additional details including permissions
                    479: and ownership information.
                    480: .It Fl n
                    481: Produce a long listing with user and group information presented
                    482: numerically.
                    483: .It Fl r
                    484: Reverse the sort order of the listing.
                    485: .It Fl S
                    486: Sort the listing by file size.
                    487: .It Fl t
                    488: Sort the listing by last modification time.
                    489: .El
                    490: .It Ic lumask Ar umask
                    491: Set local umask to
                    492: .Ar umask .
                    493: .It Ic mkdir Ar path
                    494: Create remote directory specified by
                    495: .Ar path .
                    496: .It Ic progress
                    497: Toggle display of progress meter.
1.10      christos  498: .It Xo Ic put
                    499: .Op Fl afPpr
                    500: .Ar local-path
                    501: .Op Ar remote-path
                    502: .Xc
1.1       christos  503: Upload
                    504: .Ar local-path
                    505: and store it on the remote machine.
                    506: If the remote path name is not specified, it is given the same name it has
                    507: on the local machine.
                    508: .Ar local-path
                    509: may contain
                    510: .Xr glob 3
                    511: characters and may match multiple files.
                    512: If it does and
                    513: .Ar remote-path
                    514: is specified, then
                    515: .Ar remote-path
                    516: must specify a directory.
1.5       adam      517: .Pp
1.10      christos  518: If the
                    519: .Fl a
                    520: flag is specified, then attempt to resume partial
                    521: transfers of existing files.
                    522: Note that resumption assumes that any partial copy of the remote file
                    523: matches the local copy.
                    524: If the local file contents differ from the remote local copy then
                    525: the resultant file is likely to be corrupt.
                    526: .Pp
                    527: If the
                    528: .Fl f
                    529: flag is specified, then a request will be sent to the server to call
                    530: .Xr fsync 2
                    531: after the file has been transferred.
                    532: Note that this is only supported by servers that implement
                    533: the "fsync@openssh.com" extension.
                    534: .Pp
1.7       christos  535: If either the
1.1       christos  536: .Fl P
1.5       adam      537: or
                    538: .Fl p
                    539: flag is specified, then full file permissions and access times are
1.1       christos  540: copied too.
1.5       adam      541: .Pp
                    542: If the
                    543: .Fl r
                    544: flag is specified then directories will be copied recursively.
                    545: Note that
                    546: .Nm
                    547: does not follow symbolic links when performing recursive transfers.
1.1       christos  548: .It Ic pwd
                    549: Display remote working directory.
                    550: .It Ic quit
                    551: Quit
                    552: .Nm sftp .
1.9       christos  553: .It Xo Ic reget
                    554: .Op Fl Ppr
                    555: .Ar remote-path
                    556: .Op Ar local-path
                    557: .Xc
                    558: Resume download of
                    559: .Ar remote-path .
                    560: Equivalent to
                    561: .Ic get
                    562: with the
                    563: .Fl a
                    564: flag set.
1.10      christos  565: .It Xo Ic reput
                    566: .Op Fl Ppr
                    567: .Op Ar local-path
                    568: .Ar remote-path
                    569: .Xc
                    570: Resume upload of
                    571: .Op Ar local-path .
                    572: Equivalent to
                    573: .Ic put
                    574: with the
                    575: .Fl a
                    576: flag set.
1.1       christos  577: .It Ic rename Ar oldpath Ar newpath
                    578: Rename remote file from
                    579: .Ar oldpath
                    580: to
                    581: .Ar newpath .
                    582: .It Ic rm Ar path
                    583: Delete remote file specified by
                    584: .Ar path .
                    585: .It Ic rmdir Ar path
                    586: Remove remote directory specified by
                    587: .Ar path .
                    588: .It Ic symlink Ar oldpath Ar newpath
                    589: Create a symbolic link from
                    590: .Ar oldpath
                    591: to
                    592: .Ar newpath .
                    593: .It Ic version
                    594: Display the
                    595: .Nm
                    596: protocol version.
                    597: .It Ic \&! Ns Ar command
                    598: Execute
                    599: .Ar command
                    600: in local shell.
                    601: .It Ic \&!
                    602: Escape to local shell.
                    603: .It Ic \&?
                    604: Synonym for help.
                    605: .El
                    606: .Sh SEE ALSO
                    607: .Xr ftp 1 ,
                    608: .Xr ls 1 ,
                    609: .Xr scp 1 ,
                    610: .Xr ssh 1 ,
                    611: .Xr ssh-add 1 ,
                    612: .Xr ssh-keygen 1 ,
                    613: .Xr glob 3 ,
                    614: .Xr ssh_config 5 ,
                    615: .Xr sftp-server 8 ,
                    616: .Xr sshd 8
                    617: .Rs
                    618: .%A T. Ylonen
                    619: .%A S. Lehtinen
                    620: .%T "SSH File Transfer Protocol"
                    621: .%N draft-ietf-secsh-filexfer-00.txt
                    622: .%D January 2001
                    623: .%O work in progress material
                    624: .Re

CVSweb <webmaster@jp.NetBSD.org>