-\versionid $Id: psftp.but,v 1.2 2001/12/14 12:22:09 simon Exp $
+\define{versionidpsftp} \versionid $Id$
\C{psftp} Using PSFTP to transfer files securely
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
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
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. 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}.
-To change your working directory, use the \c{cd} command. To display
-your current 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 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
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.
+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:
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.
projects / u / mdw / putty / blobdiff