X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/9a313f60eebeac980c0285abcfb03342512f96f6..c725e24c2ffb016d5a86654f8612cf8c6e33e346:/doc/psftp.but diff --git a/doc/psftp.but b/doc/psftp.but index 9aa0c50e..cdfadea5 100644 --- a/doc/psftp.but +++ b/doc/psftp.but @@ -1,4 +1,4 @@ -\versionid $Id: psftp.but,v 1.1 2001/12/14 12:15:43 simon Exp $ +\versionid $Id: psftp.but,v 1.5 2002/08/07 19:20:06 simon Exp $ \C{psftp} Using PSFTP to transfer files securely @@ -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 @@ -153,12 +121,58 @@ 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>} prompt. You can now type commands to perform file-transfer functions. This section lists all the available commands. +\S{psftp-quoting} General quoting rules for PSFTP commands + +Most PSFTP commands are considered by the PSFTP command interpreter +as a sequence of words, separated by spaces. For example, the +command \c{ren oldfilename newfilename} splits up into three words: +\c{ren} (the command name), \c{oldfilename} (the name of the file to +be renamed), and \c{newfilename} (the new name to give the file). + +Sometimes you will need to specify file names that \e{contain} +spaces. In order to do this, you can surround the file name with +double quotes. This works equally well for local file names and +remote file names: + +\c psftp> get "spacey file name.txt" "save it under this name.txt" + +The double quotes themselves will not appear as part of the file +names; they are removed by PSFTP and their only effect is to stop +the spaces inside them from acting as word separators. + +If you need to \e{use} a double quote (on some types of remote +system, such as Unix, you are allowed to use double quotes in file +names), you can do this by doubling it. This works both inside and +outside double quotes. For example, this command + +\c psftp> ren ""this"" "a file with ""quotes"" in it" + +will take a file whose current name is \c{"this"} (with a double +quote character at the beginning and the end) and rename it to a +file whose name is \c{a file with "quotes" in it}. + +(The one exception to the PSFTP quoting rules is the \c{!} command, +which passes its command line straight to Windows without splitting +it up into words at all. See \k{psftp-cmd-pling}.) + \S{psftp-cmd-open} The \c{open} command: start a session If you started PSFTP by double-clicking in the GUI, or just by @@ -198,11 +212,24 @@ remote working directory PSFTP maintains a notion of your \q{working directory} on the server. This is the default directory that other commands will operate on. For example, if you type \c{get filename.dat} then PSFTP -will look for \c{filename.dat} in your working directory on the -server. +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}. + +\S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the +local working directory + +As well as having a working directory on the remote server, PSFTP +also has a working directory on your local machine (just like any +other Windows process). This is the default local directory that +other commands will operate on. For example, if you type \c{get +filename.dat} then PSFTP will save the resulting file as +\c{filename.dat} in your local working directory. -To change your working directory, use the \c{cd} command. To display -your current working directory, type \c{pwd}. +To change your local working directory, use the \c{lcd} command. To +display your current local working directory, type \c{lpwd}. \S{psftp-cmd-get} The \c{get} command: fetch a file from the server @@ -362,3 +389,47 @@ name, and then the new file name: The \c{rename} and \c{mv} commands work exactly the same way as \c{ren}. + +\S{psftp-cmd-pling} The \c{!} command: run a local Windows command + +You can run local Windows commands using the \c{!} command. This is +the only PSFTP command that is not subject to the command quoting +rules given in \k{psftp-quoting}. If any command line begins with +the \c{!} character, then the rest of the line will be passed +straight to Windows without further translation. + +For example, if you want to move an existing copy of a file out of +the way before downloading an updated version, you might type: + +\c psftp> !ren myfile.dat myfile.bak +\c psftp> get myfile.dat + +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. + +Firstly, PSFTP can use PuTTY saved sessions in place of hostnames. +So you might do this: + +\b Run PuTTY, and create a PuTTY saved session (see +\k{config-saving}) which specifies your private key file (see +\k{config-ssh-privkey}). You will probably also want to specify a +username to log in as (see \k{config-username}). + +\b In PSFTP, you can now use the name of the session instead of a +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 +is running (see \k{pageant}). So you would do this: + +\b Ensure Pageant is running, and has your private key stored in it. + +\b Specify a user and host name to PSFTP as normal. PSFTP will +automatically detect Pageant and try to use the keys within it. + +For more general information on public-key authentication, see +\k{pubkey}.