From 9a313f60eebeac980c0285abcfb03342512f96f6 Mon Sep 17 00:00:00 2001 From: simon Date: Fri, 14 Dec 2001 12:15:43 +0000 Subject: [PATCH] Add a chapter to the manual describing PSFTP. git-svn-id: svn://svn.tartarus.org/sgt/putty@1485 cda61777-01e9-0310-a592-d414129be87e --- doc/Makefile | 2 +- doc/pscp.but | 6 +- doc/psftp.but | 364 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 370 insertions(+), 2 deletions(-) create mode 100644 doc/psftp.but diff --git a/doc/Makefile b/doc/Makefile index f61b7c5b..0c8a661c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,4 +1,4 @@ -CHAPTERS = blurb intro gs using config pscp plink pubkey pageant faq +CHAPTERS = blurb intro gs using config pscp psftp plink pubkey pageant faq INPUTS = $(patsubst %,%.but,$(CHAPTERS)) diff --git a/doc/pscp.but b/doc/pscp.but index b9fd4bdd..dcc60e30 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -1,4 +1,4 @@ -\versionid $Id: pscp.but,v 1.17 2001/09/24 22:00:46 simon Exp $ +\versionid $Id: pscp.but,v 1.18 2001/12/14 12:15:43 simon Exp $ \#FIXME: Need examples @@ -7,6 +7,10 @@ \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files securely between computers using an SSH connection. +If you have an SSH 2 server, you might prefer PSFTP (see \k{psftp}) +for interactive use. PSFTP does not in general work with SSH 1 +servers, however. + \H{pscp-starting} Starting PSCP PSCP is a command line application. This means that you cannot just diff --git a/doc/psftp.but b/doc/psftp.but new file mode 100644 index 00000000..9aa0c50e --- /dev/null +++ b/doc/psftp.but @@ -0,0 +1,364 @@ +\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}. -- 2.11.0