X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/3af9746312c67c3d5d4c4aac7e60ab4bec80ae5d..2ac3322ef9bc032ad942753a56696764aa0b0f74:/doc/psftp.but diff --git a/doc/psftp.but b/doc/psftp.but index 57ba0fa5..5cc26f0a 100644 --- a/doc/psftp.but +++ b/doc/psftp.but @@ -1,4 +1,4 @@ -\versionid $Id: psftp.but,v 1.3 2001/12/16 13:33:04 simon Exp $ +\define{versionidpsftp} \versionid $Id$ \C{psftp} Using PSFTP to transfer files securely @@ -8,8 +8,8 @@ securely between computers using an SSH connection. PSFTP differs from PSCP in the following ways: \b PSCP should work on virtually every SSH server. PSFTP uses the -new SFTP protocol, which is a feature of SSH 2 only. (PSCP will also -use this protocol if it can, but there is an SSH 1 equivalent it can +new SFTP protocol, which is a feature of SSH-2 only. (PSCP will also +use this protocol if it can, but there is an SSH-1 equivalent it can fall back to if it cannot.) \b PSFTP allows you to run an interactive file transfer session, @@ -49,45 +49,13 @@ any server: At this point you can type \c{open server.example.com} or \c{open fred@server.example.com} to start a session. -The following sections describe PSFTP's command-line options. +PSFTP accepts all the general command line options supported by the +PuTTY tools, except the ones which make no sense in a file transfer +utility. See \k{using-general-opts} for a description of these +options. (The ones not supported by PSFTP are clearly marked.) -\S{psftp-option-l} \c{-l}: specify a user name - -The \c{-l} option is an alternative way to specify the user name to -log in as, on the command line. Instead of typing \c{psftp -user@host}, you can also type \c{psftp host -l user}. - -This option does not work in the \c{open} command once PSFTP has -started. - -\S{psftp-option-P} \c{-P}: specify a port number - -If the \c{host} you specify is a saved session, PSFTP uses any port -number specified in that saved session. If not, PSFTP uses the -default SSH port, 22. The \c{-P} option allows you specify the port -number to connect to for PSFTP's SSH connection. - -\S{psftp-option-v}\c{-v}: show verbose messages - -The \c{-v} option to PSFTP makes it print verbose information about -the establishing of the SSH connection. The information displayed is -equivalent to what is shown in the PuTTY Event Log -(\k{using-eventlog}). - -This information may be useful for debugging problems with PSFTP. - -\S{psftp-option-pw} \c{-pw}: specify a password - -If a password is required to connect to the \c{host}, PSFTP will -interactively prompt you for it. However, this may not always be -appropriate. If you are running PSFTP as part of some automated -job, it will not be possible to enter a password by hand. The -\c{-pw} option to PSFTP lets you specify the password to use on the -command line. - -Since specifying passwords in scripts is a bad idea for security -reasons, you might want instead to consider using public-key -authentication; see \k{psftp-pubkey}. +PSFTP also supports some of its own options. The following sections +describe PSFTP's specific command-line options. \S{psftp-option-b} \c{-b}: specify a file containing batch commands @@ -114,15 +82,16 @@ and then you could run the script by typing When you run a batch script in this way, PSFTP will abort the script if any command fails to complete successfully. To change this -behaviour, you can use the \c{-be} option (\k{psftp-option-be}). +behaviour, you can add the \c{-be} option (\k{psftp-option-be}). \S{psftp-option-bc} \c{-bc}: display batch commands as they are run The \c{-bc} option alters what PSFTP displays while processing a -batch script. With the \c{-bc} option, PSFTP will display prompts -and commands just as if the commands had been typed at the keyboard. -So instead of seeing this: +batch script specified with \c{-b}. With the \c{-bc} option, PSFTP +will display prompts and commands just as if the commands had been +typed at the keyboard. So instead of seeing this: +\c C:\>psftp fred@hostname -b batchfile \c Sent username "fred" \c Remote working directory is /home/fred \c Listing directory /home/fred/lib @@ -134,6 +103,7 @@ So instead of seeing this: you might see this: +\c C:\>psftp fred@hostname -bc -b batchfile \c Sent username "fred" \c Remote working directory is /home/fred \c psftp> dir lib @@ -147,12 +117,24 @@ you might see this: \S{psftp-option-be} \c{-be}: continue batch processing on errors -When running a batch file, this option causes PSFTP to continue -processing even if a command fails to complete successfully. +When running a batch file, this additional option causes PSFTP to +continue processing even if a command fails to complete successfully. You might want this to happen if you wanted to delete a file and didn't care if it was already not present, for example. +\S{psftp-usage-options-batch}\c{-batch}: avoid interactive prompts + +If you use the \c{-batch} option, PSFTP will never give an +interactive prompt while establishing the connection. If the +server's host key is invalid, for example (see \k{gs-hostkey}), then +the connection will simply be abandoned instead of asking you what +to do next. + +This may help PSFTP's behaviour when it is used in automated +scripts: using \c{-batch}, if something goes wrong at connection +time, the batch job will fail rather than hang. + \H{psftp-commands} Running PSFTP Once you have started your PSFTP session, you will see a \c{psftp>} @@ -193,6 +175,48 @@ file whose name is \c{a file with "quotes" in it}. which passes its command line straight to Windows without splitting it up into words at all. See \k{psftp-cmd-pling}.) +\S{psftp-wildcards} Wildcards in PSFTP + +Several commands in PSFTP support \q{wildcards} to select multiple +files. + +For \e{local} file specifications (such as the first argument to +\c{put}), wildcard rules for the local operating system are used. For +instance, PSFTP running on Windows might require the use of \c{*.*} +where PSFTP on Unix would need \c{*}. + +For \e{remote} file specifications (such as the first argument to +\c{get}), PSFTP uses a standard wildcard syntax (similar to POSIX +wildcards): + +\b \c{*} matches any sequence of characters (including a zero-length +sequence). + +\b \c{?} matches exactly one character. + +\b \c{[abc]} matches exactly one character which can be \cw{a}, +\cw{b}, or \cw{c}. + +\lcont{ + +\c{[a-z]} matches any character in the range \cw{a} to \cw{z}. + +\c{[^abc]} matches a single character that is \e{not} \cw{a}, \cw{b}, +or \cw{c}. + +Special cases: \c{[-a]} matches a literal hyphen (\cw{-}) or \cw{a}; +\c{[^-a]} matches all other characters. \c{[a^]} matches a literal +caret (\cw{^}) or \cw{a}. + +} + +\b \c{\\} (backslash) before any of the above characters (or itself) +removes that character's special meaning. + +A leading period (\cw{.}) on a filename is not treated specially, +unlike in some Unix contexts; \c{get *} will fetch all files, whether +or not they start with a leading period. + \S{psftp-cmd-open} The \c{open} command: start a session If you started PSFTP by double-clicking in the GUI, or just by @@ -211,12 +235,19 @@ not opened successfully, PSFTP will terminate immediately. \S{psftp-cmd-quit} The \c{quit} command: end your session When you have finished your session, type the command \c{quit} to -terminate PSFTP and return to the command line (or just close the -PSFTP console window if you started it from the GUI). +close the connection, terminate PSFTP and return to the command line +(or just close the PSFTP console window if you started it from the +GUI). You can also use the \c{bye} and \c{exit} commands, which have exactly the same effect. +\S{psftp-cmd-close} The \c{close} command: close your connection + +If you just want to close the network connection but keep PSFTP +running, you can use the \c{close} command. You can then use the +\c{open} command to open a new connection. + \S{psftp-cmd-help} The \c{help} command: get quick online help If you type \c{help}, PSFTP will give a short list of the available @@ -235,8 +266,12 @@ operate on. For example, if you type \c{get filename.dat} then PSFTP will look for \c{filename.dat} in your remote working directory on the server. -To change your remote working directory, use the \c{cd} command. To -display your current remote working directory, type \c{pwd}. +To change your remote working directory, use the \c{cd} command. If +you don't provide an argument, \c{cd} will return you to your home +directory on the server (more precisely, the remote directory you were +in at the start of the connection). + +To display your current remote working directory, type \c{pwd}. \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the local working directory @@ -268,6 +303,17 @@ specify the local file name after the remote one: This will fetch the file on the server called \c{myfile.dat}, but will save it to your local machine under the name \c{newname.dat}. +To fetch an entire directory recursively, you can use the \c{-r} +option: + +\c get -r mydir +\c get -r mydir newname + +(If you want to fetch a file whose name starts with a hyphen, you +may have to use the \c{--} special argument, which stops \c{get} +from interpreting anything as a switch after it. For example, +\cq{get -- -silly-name-}.) + \S{psftp-cmd-put} The \c{put} command: send a file to the server To upload a file to the server from your local PC, you use the @@ -285,6 +331,40 @@ specify the remote file name after the local one: This will send the local file called \c{myfile.dat}, but will store it on the server under the name \c{newname.dat}. +To send an entire directory recursively, you can use the \c{-r} +option: + +\c put -r mydir +\c put -r mydir newname + +(If you want to send a file whose name starts with a hyphen, you may +have to use the \c{--} special argument, which stops \c{put} from +interpreting anything as a switch after it. For example, \cq{put -- +-silly-name-}.) + +\S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or +send multiple files + +\c{mget} works almost exactly like \c{get}, except that it allows +you to specify more than one file to fetch at once. You can do this +in two ways: + +\b by giving two or more explicit file names (\cq{mget file1.txt +file2.txt}) + +\b by using a wildcard (\cq{mget *.txt}). + +Every argument to \c{mget} is treated as the name of a file to fetch +(unlike \c{get}, which will interpret at most one argument like +that, and a second argument will be treated as an alternative name +under which to store the retrieved file), or a wildcard expression +matching more than one file. + +The \c{-r} and \c{--} options from \c{get} are also available with +\c{mget}. + +\c{mput} is similar to \c{put}, with the same differences. + \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands: resuming file transfers @@ -300,6 +380,13 @@ syntax of \c{get} and \c{put}: \c reget myfile.dat \c reget myfile.dat newname.dat +\c reget -r mydir + +These commands are intended mainly for resuming interrupted transfers. +They assume that the remote file or directory structure has not +changed in any way; if there have been changes, you may end up with +corrupted files. In particular, the \c{-r} option will not pick up +changes to files or directories already transferred in full. \S{psftp-cmd-dir} The \c{dir} command: list remote files @@ -312,22 +399,28 @@ You can also list the contents of a different directory by typing \c dir /home/fred \c dir sources +And you can list a subset of the contents of a directory by +providing a wildcard: + +\c dir /home/fred/*.txt +\c dir sources/*.c + The \c{ls} command works exactly the same way as \c{dir}. \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on remote files -PSFTP allows you to modify the file permissions on files on the -server. You do this using the \c{chmod} command, which works very -much like the Unix \c{chmod} command. +PSFTP allows you to modify the file permissions on files and +directories on the server. You do this using the \c{chmod} command, +which works very much like the Unix \c{chmod} command. The basic syntax is \c{chmod modes file}, where \c{modes} represents a modification to the file permissions, and \c{file} is the filename -to modify. For example: +to modify. You can specify multiple files or wildcards. For example: \c chmod go-rwx,u+w privatefile -\c chmod a+r publicfile -\c chmod 640 groupfile +\c chmod a+r public* +\c chmod 640 groupfile1 groupfile2 The \c{modes} parameter can be a set of octal digits in the Unix style. (If you don't know what this means, you probably don't want @@ -354,7 +447,8 @@ permissions for members of the owning group and everybody else (so the only permissions left are the ones for the file owner). \c{u+w} adds write permission for the file owner. -\b The second example: \c{a+r} adds read permission for everybody. +\b The second example: \c{a+r} adds read permission for everybody to +all files and directories starting with \q{public}. In addition to all this, there are a few extra special cases for Unix systems. On non-Unix systems these are unlikely to be useful: @@ -376,9 +470,18 @@ normally only the owner of the \e{directory} would be allowed to). \S{psftp-cmd-del} The \c{del} command: delete remote files -To delete a file on the server, type \c{del} and then the filename: +To delete a file on the server, type \c{del} and then the filename +or filenames: \c del oldfile.dat +\c del file1.txt file2.txt +\c del *.o + +Files will be deleted without further prompting, even if multiple files +are specified. + +\c{del} will only delete files. You cannot use it to delete +directories; use \c{rmdir} for that. The \c{rm} command works exactly the same way as \c{del}. @@ -389,26 +492,47 @@ directory name: \c mkdir newstuff +You can specify multiple directories to create at once: + +\c mkdir dir1 dir2 dir3 + \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories To remove a directory on the server, type \c{rmdir} and then the -directory name: +directory name or names: \c rmdir oldstuff +\c rmdir *.old ancient + +Directories will be deleted without further prompting, even if +multiple directories are specified. Most SFTP servers will probably refuse to remove a directory if the directory has anything in it, so you will need to delete the contents first. -\S{psftp-cmd-ren} The \c{ren} command: rename remote files +\S{psftp-cmd-mv} The \c{mv} command: move and rename remote files + +To rename a single file on the server, type \c{mv}, then the current +file name, and then the new file name: + +\c mv oldfile newname -To rename a file on the server, type \c{ren}, then the current file -name, and then the new file name: +You can also move the file into a different directory and change the +name: -\c ren oldfile newname +\c mv oldfile dir/newname -The \c{rename} and \c{mv} commands work exactly the same way as -\c{ren}. +To move one or more files into an existing subdirectory, specify the +files (using wildcards if desired), and then the destination +directory: + +\c mv file dir +\c mv file1 dir1/file2 dir2 +\c mv *.c *.h .. + +The \c{rename} and \c{ren} commands work exactly the same way as +\c{mv}. \S{psftp-cmd-pling} The \c{!} command: run a local Windows command @@ -429,7 +553,7 @@ using the Windows \c{ren} command to rename files on your local PC. \H{psftp-pubkey} Using public key authentication with PSFTP Like PuTTY, PSFTP can authenticate using a public key instead of a -password. There are two ways you can do this. +password. There are three ways you can do this. Firstly, PSFTP can use PuTTY saved sessions in place of hostnames. So you might do this: @@ -443,7 +567,11 @@ username to log in as (see \k{config-username}). hostname: type \c{psftp sessionname}, where \c{sessionname} is replaced by the name of your saved session. -Secondly, PSFTP will attempt to authenticate using Pageant if Pageant +Secondly, you can supply the name of a private key file on the command +line, with the \c{-i} option. See \k{using-cmdline-identity} for more +information. + +Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant is running (see \k{pageant}). So you would do this: \b Ensure Pageant is running, and has your private key stored in it.