X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/9c77ddf65fc39fdb5d35ed6b06c3817fc9f56982..HEAD:/doc/psftp.but diff --git a/doc/psftp.but b/doc/psftp.but index d9c070c1..be8ac3f6 100644 --- a/doc/psftp.but +++ b/doc/psftp.but @@ -1,19 +1,19 @@ \define{versionidpsftp} \versionid $Id$ -\C{psftp} Using PSFTP to transfer files securely +\C{psftp} Using \i{PSFTP} to transfer files securely -\i{PSFTP}, the PuTTY SFTP client, is a tool for transferring files +\i{PSFTP}, the PuTTY SFTP client, is a tool for \i{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 +new \i{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 +much like the Windows \i\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 @@ -57,24 +57,23 @@ options. (The ones not supported by PSFTP are clearly marked.) 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 +\S{psftp-option-b} \I{-b-PSFTP}\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: +prefer to \I{batch scripts in PSFTP}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 @@ -82,15 +81,18 @@ 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 +PSFTP will terminate after it finishes executing the batch script. + +\S{psftp-option-bc} \I{-bc-PSFTP}\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 @@ -102,6 +104,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 @@ -113,15 +116,16 @@ you might see this: \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 +\S{psftp-option-be} \I{-be-PSFTP}\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 +\S{psftp-usage-options-batch} \I{-batch-PSFTP}\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 @@ -139,7 +143,10 @@ 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 +Any line starting with a \cw{#} will be treated as a \i{comment} +and ignored. + +\S{psftp-quoting} \I{quoting, in PSFTP}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 @@ -147,10 +154,10 @@ 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: +Sometimes you will need to specify \I{spaces in filenames}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" @@ -173,6 +180,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{\i{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 \i{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 @@ -182,6 +231,8 @@ 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}. +You can optionally specify a port as well: +\c{open user@host.name 22}. 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 @@ -191,12 +242,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 @@ -207,7 +265,7 @@ If you type \c{help} with a command name - for example, \c{help get} command. \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the -remote working directory +remote \i{working directory} PSFTP maintains a notion of your \q{working directory} on the server. This is the default directory that other commands will @@ -223,7 +281,7 @@ 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 +local \i{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 @@ -237,7 +295,7 @@ display your current local working directory, type \c{lpwd}. \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, +To \i{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: @@ -252,7 +310,7 @@ 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} +To fetch an entire directory \i{recursive}ly, you can use the \c{-r} option: \c get -r mydir @@ -265,7 +323,7 @@ from interpreting anything as a switch after it. For example, \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 +To \i{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: @@ -280,7 +338,7 @@ 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} +To send an entire directory \i{recursive}ly, you can use the \c{-r} option: \c put -r mydir @@ -306,13 +364,16 @@ file2.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 +under which to store the retrieved file), or a \i{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 +\i{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 @@ -326,8 +387,15 @@ 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 +\S{psftp-cmd-dir} The \c{dir} command: \I{listing files}list remote files To list the files in your remote working directory, just type \c{dir}. @@ -338,22 +406,29 @@ 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. +\I{changing permissions on files}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 @@ -368,10 +443,12 @@ 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). +\b The actual permissions being added or removed. These can be +\I{read permission}\c{r} (permission to read the file), +\I{write permission}\c{w} (permission to write to the file), and +\I{execute permission}\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: @@ -380,63 +457,94 @@ 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: +\i{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; +\i{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 +\i{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 +\q{\i{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: +To \I{deleting files}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}. \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories -To create a directory on the server, type \c{mkdir} and then the +To \i{create a directory} on the server, type \c{mkdir} and then the 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: +To \i{remove a directory} on the server, type \c{rmdir} and then the +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 \i{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 + +You can also move the file into a different directory and change the +name: + +\c mv oldfile dir/newname -To rename a file on the server, type \c{ren}, then the current file -name, and then the new file name: +To move one or more files into an existing subdirectory, specify the +files (using wildcards if desired), and then the destination +directory: -\c ren oldfile newname +\c mv file dir +\c mv file1 dir1/file2 dir2 +\c mv *.c *.h .. -The \c{rename} and \c{mv} commands work exactly the same way as -\c{ren}. +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 +\S{psftp-cmd-pling} The \c{!} command: run a \i{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 @@ -452,7 +560,7 @@ the way before downloading an updated version, you might type: using the Windows \c{ren} command to rename files on your local PC. -\H{psftp-pubkey} Using public key authentication with PSFTP +\H{psftp-pubkey} Using \i{public key authentication} with PSFTP Like PuTTY, PSFTP can authenticate using a public key instead of a password. There are three ways you can do this.