--- /dev/null
+\versionid $Id: psftp.but,v 1.1 2001/12/14 12:15:43 simon Exp $
+
+\C{psftp} Using PSFTP to transfer files securely
+
+\i{PSFTP}, the PuTTY SFTP client, is a tool for transferring files
+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
+fall back to if it cannot.)
+
+\b PSFTP allows you to run an interactive file transfer session,
+much like the Windows \c{ftp} program. You can list the contents of
+directories, browse around the file system, issue multiple \c{get}
+and \c{put} commands, and eventually log out. By contrast, PSCP is
+designed to do a single file transfer operation and immediately
+terminate.
+
+\H{psftp-starting} Starting PSFTP
+
+The usual way to start PSFTP is from a command prompt, much like
+PSCP. To do this, it will need either to be on your \i{\c{PATH}} or
+in your current directory. To add the directory containing PSFTP to
+your \c{PATH} environment variable, type into the console window:
+
+\c set PATH=C:\path\to\putty\directory;%PATH%
+
+Unlike PSCP, however, PSFTP has no complex command-line syntax; you
+just specify a host name and perhaps a user name:
+
+\c psftp server.example.com
+
+or perhaps
+
+\c psftp fred@server.example.com
+
+Alternatively, if you just type \c{psftp} on its own (or
+double-click the PSFTP icon in the Windows GUI), you will see the
+PSFTP prompt, and a message telling you PSFTP has not connected to
+any server:
+
+\c C:\>psftp
+\c psftp: no hostname specified; use "open host.name" to connect
+\c psftp>
+
+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.
+
+\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}.
+
+\S{psftp-option-b} \c{-b}: specify a file containing batch commands
+
+In normal operation, PSFTP is an interactive program which displays
+a command line and accepts commands from the keyboard.
+
+If you need to do automated tasks with PSFTP, you would probably
+prefer to specify a set of commands in advance and have them
+executed automatically. The \c{-b} option allows you to do this. You
+use it with a file name containing batch commands. For example, you
+might create a file called \c{myscript.scr} containing lines like
+this:
+
+\c cd /home/ftp/users/jeff
+\c del jam-old.tar.gz
+\c ren jam.tar.gz jam-old.tar.gz
+\c put jam.tar.gz
+\c chmod a+r jam.tar.gz
+\c quit
+
+and then you could run the script by typing
+
+\c psftp user@hostname -b myscript.scr
+
+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}).
+
+\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:
+
+\c Sent username "fred"
+\c Remote working directory is /home/fred
+\c Listing directory /home/fred/lib
+\c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
+\c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
+\c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
+\c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
+\c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
+
+you might see this:
+
+\c Sent username "fred"
+\c Remote working directory is /home/fred
+\c psftp> dir lib
+\c Listing directory /home/fred/lib
+\c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
+\c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
+\c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
+\c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
+\c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
+\c psftp> quit
+
+\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.
+
+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.
+
+\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-cmd-open} The \c{open} command: start a session
+
+If you started PSFTP by double-clicking in the GUI, or just by
+typing \c{psftp} at the command line, you will need to open a
+connection to an SFTP server before you can issue any other
+commands (except \c{help} and \c{quit}).
+
+To create a connection, type \c{open host.name}, or if you need to
+specify a user name as well you can type \c{open user@host.name}.
+
+Once you have issued this command, you will not be able to issue it
+again, \e{even} if the command fails (for example, if you mistype
+the host name or the connection times out). So if the connection is
+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).
+
+You can also use the \c{bye} and \c{exit} commands, which have
+exactly the same effect.
+
+\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
+commands.
+
+If you type \c{help} with a command name - for example, \c{help get}
+- then PSFTP will give a short piece of help on that particular
+command.
+
+\S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
+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.
+
+To change your working directory, use the \c{cd} command. To display
+your current working directory, type \c{pwd}.
+
+\S{psftp-cmd-get} The \c{get} command: fetch a file from the server
+
+To download a file from the server and store it on your local PC,
+you use the \c{get} command.
+
+In its simplest form, you just use this with a file name:
+
+\c get myfile.dat
+
+If you want to store the file locally under a different name,
+specify the local file name after the remote one:
+
+\c get myfile.dat newname.dat
+
+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}.
+
+\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
+\c{put} command.
+
+In its simplest form, you just use this with a file name:
+
+\c put myfile.dat
+
+If you want to store the file remotely under a different name,
+specify the remote file name after the local one:
+
+\c put myfile.dat newname.dat
+
+This will send the local file called \c{myfile.dat}, but will store
+it on the server under the name \c{newname.dat}.
+
+\S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
+resuming file transfers
+
+If a file transfer fails half way through, and you end up with half
+the file stored on your disk, you can resume the file transfer using
+the \c{reget} and \c{reput} commands. These work exactly like the
+\c{get} and \c{put} commands, but they check for the presence of the
+half-written destination file and start transferring from where the
+last attempt left off.
+
+The syntax of \c{reget} and \c{reput} is exactly the same as the
+syntax of \c{get} and \c{put}:
+
+\c reget myfile.dat
+\c reget myfile.dat newname.dat
+
+\S{psftp-cmd-dir} The \c{dir} command: list remote files
+
+To list the files in your remote working directory, just type
+\c{dir}.
+
+You can also list the contents of a different directory by typing
+\c{dir} followed by the directory name:
+
+\c dir /home/fred
+\c dir sources
+
+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.
+
+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:
+
+\c chmod go-rwx,u+w privatefile
+\c chmod a+r publicfile
+\c chmod 640 groupfile
+
+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
+to be using it!) Alternatively, it can be a list of permission
+modifications, separated by commas. Each modification consists of:
+
+\b The people affected by the modification. This can be \c{u} (the
+owning user), \c{g} (members of the owning group), or \c{o}
+(everybody else - \q{others}), or some combination of those. It can
+also be \c{a} (\q{all}) to affect everybody at once.
+
+\b A \c{+} or \c{-} sign, indicating whether permissions are to be
+added or removed.
+
+\b The actual permissions being added or removed. These can be \c{r}
+(permission to read the file), \c{w} (permission to write to the
+file), and \c{x} (permission to execute the file, or in the case of
+a directory, permission to access files within the directory).
+
+So the above examples would do:
+
+\b The first example: \c{go-rwx} removes read, write and execute
+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.
+
+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:
+
+\b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
+set-user-ID bit. This is typically only useful for special purposes;
+refer to your Unix documentation if you're not sure about it.
+
+\b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
+set-group-ID bit. On a file, this works similarly to the set-user-ID
+bit (see your Unix documentation again); on a directory it ensures
+that files created in the directory are accessible by members of the
+group that owns the directory.
+
+\b You can specify \c{+t} and \c{-t} to add or remove the Unix
+\q{sticky bit}. When applied to a directory, this means that the
+owner of a file in that directory can delete the file (whereas
+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:
+
+\c del oldfile.dat
+
+The \c{rm} command works exactly the same way as \c{del}.
+
+\S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
+
+To create a directory on the server, type \c{mkdir} and then the
+directory name:
+
+\c mkdir newstuff
+
+\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:
+
+\c rmdir oldstuff
+
+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
+
+To rename a file on the server, type \c{ren}, then the current file
+name, and then the new file name:
+
+\c ren oldfile newname
+
+The \c{rename} and \c{mv} commands work exactly the same way as
+\c{ren}.
~mdw / sgt / putty / commitdiff