Previous | Contents | Index | Next
-b
: specify a file containing batch commands-bc
: display batch commands as they are run-be
: continue batch processing on errors-batch
: avoid interactive promptsopen
command: start a sessionquit
command: end your sessionhelp
command: get quick online helpcd
and pwd
commands: changing the remote working directorylcd
and lpwd
commands: changing the local working directoryget
command: fetch a file from the serverput
command: send a file to the serverreget
and reput
commands: resuming file transfersdir
command: list remote fileschmod
command: change permissions on remote filesdel
command: delete remote filesmkdir
command: create remote directoriesrmdir
command: remove remote directoriesren
command: rename remote files!
command: run a local Windows commandPSFTP, 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:
ftp
program. You can list the contents of directories, browse around the file system, issue multiple get
and put
commands, and eventually log out. By contrast, PSCP is designed to do a single file transfer operation and immediately terminate.
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 PATH
or in your current directory. To add the directory containing PSFTP to your PATH
environment variable, type into the console window:
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:
psftp server.example.com
or perhaps
psftp [email protected]
Alternatively, if you just type 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:\>psftp
psftp: no hostname specified; use "open host.name" to connect
psftp>
At this point you can type open server.example.com
or open [email protected]
to start a session.
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 section 3.7.3 for a description of these 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.
-b
: specify a file containing batch commandsIn 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 -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 myscript.scr
containing lines like this:
cd /home/ftp/users/jeff
del jam-old.tar.gz
ren jam.tar.gz jam-old.tar.gz
put jam.tar.gz
chmod a+r jam.tar.gz
quit
and then you could run the script by typing
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 -be
option (section 6.1.3).
-bc
: display batch commands as they are run
The -bc
option alters what PSFTP displays while processing a batch script. With the -bc
option, PSFTP will display prompts and commands just as if the commands had been typed at the keyboard. So instead of seeing this:
Sent username "fred"
Remote working directory is /home/fred
Listing directory /home/fred/lib
drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
you might see this:
Sent username "fred"
Remote working directory is /home/fred
psftp> dir lib
Listing directory /home/fred/lib
drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
psftp> quit
-be
: continue batch processing on errorsWhen 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.
-batch
: avoid interactive prompts
If you use the -batch
option, PSFTP will never give an interactive prompt while establishing the connection. If the server's host key is invalid, for example (see section 2.2), 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 -batch
, if something goes wrong at connection time, the batch job will fail rather than hang.
Once you have started your PSFTP session, you will see a psftp>
prompt. You can now type commands to perform file-transfer functions. This section lists all the available commands.
Most PSFTP commands are considered by the PSFTP command interpreter as a sequence of words, separated by spaces. For example, the command ren oldfilename newfilename
splits up into three words: ren
(the command name), oldfilename
(the name of the file to be renamed), and newfilename
(the new name to give the file).
Sometimes you will need to specify file names that 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:
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 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
psftp> ren ""this"" "a file with ""quotes"" in it"
will take a file whose current name is "this"
(with a double quote character at the beginning and the end) and rename it to a file whose name is a file with "quotes" in it
.
(The one exception to the PSFTP quoting rules is the !
command, which passes its command line straight to Windows without splitting it up into words at all. See section 6.2.16.)
open
command: start a session
If you started PSFTP by double-clicking in the GUI, or just by typing psftp
at the command line, you will need to open a connection to an SFTP server before you can issue any other commands (except help
and quit
).
To create a connection, type open host.name
, or if you need to specify a user name as well you can type open [email protected]
.
Once you have issued this command, you will not be able to issue it again, 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.
quit
command: end your session
When you have finished your session, type the command 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 bye
and exit
commands, which have exactly the same effect.
help
command: get quick online help
If you type help
, PSFTP will give a short list of the available commands.
If you type help
with a command name - for example, help get
- then PSFTP will give a short piece of help on that particular command.
cd
and pwd
commands: changing the remote working directory
PSFTP maintains a notion of your ‘working directory’ on the server. This is the default directory that other commands will operate on. For example, if you type get filename.dat
then PSFTP will look for filename.dat
in your remote working directory on the server.
To change your remote working directory, use the cd
command. If you don't provide an argument, 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 pwd
.
lcd
and 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 get filename.dat
then PSFTP will save the resulting file as filename.dat
in your local working directory.
To change your local working directory, use the lcd
command. To display your current local working directory, type lpwd
.
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 get
command.
In its simplest form, you just use this with a file name:
get myfile.dat
If you want to store the file locally under a different name, specify the local file name after the remote one:
get myfile.dat newname.dat
This will fetch the file on the server called myfile.dat
, but will save it to your local machine under the name newname.dat
.
put
command: send a file to the server
To upload a file to the server from your local PC, you use the put
command.
In its simplest form, you just use this with a file name:
put myfile.dat
If you want to store the file remotely under a different name, specify the remote file name after the local one:
put myfile.dat newname.dat
This will send the local file called myfile.dat
, but will store it on the server under the name newname.dat
.
reget
and 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 reget
and reput
commands. These work exactly like the get
and 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 reget
and reput
is exactly the same as the syntax of get
and put
:
reget myfile.dat
reget myfile.dat newname.dat
dir
command: list remote files
To list the files in your remote working directory, just type dir
.
You can also list the contents of a different directory by typing dir
followed by the directory name:
dir /home/fred
dir sources
The ls
command works exactly the same way as dir
.
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 chmod
command, which works very much like the Unix chmod
command.
The basic syntax is chmod modes file
, where modes
represents a modification to the file permissions, and file
is the filename to modify. For example:
chmod go-rwx,u+w privatefile
chmod a+r publicfile
chmod 640 groupfile
The 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:
u
(the owning user), g
(members of the owning group), or o
(everybody else - ‘others’), or some combination of those. It can also be a
(‘all’) to affect everybody at once.
+
or -
sign, indicating whether permissions are to be added or removed.
r
(permission to read the file), w
(permission to write to the file), and 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:
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). u+w
adds write permission for the file owner.
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:
u+s
and 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.
g+s
and 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.
+t
and -t
to add or remove the Unix ‘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 directory would be allowed to).
del
command: delete remote files
To delete a file on the server, type del
and then the filename:
del oldfile.dat
The rm
command works exactly the same way as del
.
mkdir
command: create remote directories
To create a directory on the server, type mkdir
and then the directory name:
mkdir newstuff
rmdir
command: remove remote directories
To remove a directory on the server, type rmdir
and then the directory name:
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.
ren
command: rename remote files
To rename a file on the server, type ren
, then the current file name, and then the new file name:
ren oldfile newname
The rename
and mv
commands work exactly the same way as ren
.
!
command: run a local Windows command
You can run local Windows commands using the !
command. This is the only PSFTP command that is not subject to the command quoting rules given in section 6.2.1. If any command line begins with the !
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:
psftp> !ren myfile.dat myfile.bak
psftp> get myfile.dat
using the Windows ren
command to rename files on your local PC.
Like PuTTY, PSFTP can authenticate using a public key instead of a 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:
psftp sessionname
, where sessionname
is replaced by the name of your saved session.
Secondly, you can supply the name of a private key file on the command line, with the -i
option. See section 3.7.3.15 for more information.
Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant is running (see chapter 9). So you would do this:
For more general information on public-key authentication, see chapter 8.
If you want to provide feedback on this manual or on the PuTTY tools themselves, see the Feedback page.
[$Id: blurb.but 4787 2004-11-16 15:27:00Z simon $]