-\versionid $Id: config.but,v 1.34 2002/05/30 12:41:07 jacob Exp $
+\versionid $Id: config.but,v 1.35 2002/08/07 19:20:06 simon Exp $
\C{config} Configuring PuTTY
PuTTY will attempt to use protocol 1 if the server you connect to
does not offer protocol 2, and vice versa.
-If you select \q{2 only} here, PuTTY will only connect if the server
-you connect to offers SSH protocol version 2.
+If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
+if the server you connect to offers the SSH protocol version you
+have specified.
\S{config-ssh-macbug} \q{Imitate SSH 2 MAC bug}
-\versionid $Id: plink.but,v 1.15 2002/03/05 20:39:27 simon Exp $
+\versionid $Id: plink.but,v 1.16 2002/08/07 19:20:06 simon Exp $
\C{plink} Using the command-line connection tool Plink
Then you can set up other programs to run this Plink command and
talk to it as if it were a process on the server machine.
-You may also find it useful to use the \c{-batch} command-line
-option; see \k{plink-usage-options-batch}.
+\S{plink-options} Plink command line options
-\S{plink-usage-options} Options
+Plink accepts all the general command line options supported by the
+PuTTY tools. See \k{using-general-opts} for a description of these
+options.
-This section describes the command line options that Plink accepts.
-
-\S2{plink-usage-options-v}\c{-v} show verbose messages
-
-By default, Plink only displays any password prompts and the output of
-the remote command. The \c{-v} option makes it print extra
-information about the connection being made, for example:
-
-\c Server version: SSH-1.5-OpenSSH-1.2.3
-\c We claim version: SSH-1.5-PuTTY
-\c Using SSH protocol version 1
-\c Received public keys
-\c Host key fingerprint is:
-\c 1023 e3:65:44:44:bd:b1:04:59:bc:e2:3d:a1:4d:09:ce:99
-\c Encrypted session key
-\c Using 3DES encryption
-\c Trying to enable encryption...
-\c Successfully started encryption
-\c Sent username "fred".
-\c Sent username "fred"
-\c fred@example.com's password:
-
-This information can be useful for diagnosing problems.
-
-\S2{plink-usage-options-ssh} Protocol selection options
-
-Plink is most useful when using the SSH protocol. However, it allows
-you to interface to all the protocols supported by PuTTY. You can
-specify the option \c{-ssh} on the command line to select the SSH
-protocol; you can also specify \c{-telnet}, \c{-rlogin} or \c{-raw}
-to select other protocols.
-
-\S2{plink-usage-options-P}\c{-P port} connect to specified port
-
-If your server machine is running its SSH service on a port other
-than the standard one, you can specify an alternative port number to
-connect to using the \c{-P} option, like this:
-
-\c plink -ssh login.example.com -P 5022
-
-\S2{plink-usage-options-pw}\c{-pw passw} login with specified password
-
-A simple way to automate a remote login is to supply your password
-on the Plink command line. This is \e{not recommended} for reasons
-of security. If you possibly can, we recommend you set up public-key
-authentication instead. See \k{pubkey} for details.
-
-Note that the \c{-pw} option only works when you are using the SSH
-protocol. Due to fundamental limitations of Telnet and Rlogin, these
-protocols do not support automated password authentication.
-
-\S2{plink-usage-options-user}\c{-l username} login with specified
-username
-
-As described in \k{plink-usage-batch}, you can specify the user name
-to log in as on the remote server using the \c{-l} option. For
-example, \c{plink login.example.com -l fred}.
-
-\S2{plink-usage-options-batch}\c{-batch} avoid interactive prompts
-
-If you use the \c{-batch} option, Plink will never give an
+In addition to this, Plink accepts one other option: the \c{-batch}
+option. If you use the \c{-batch} option, Plink 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
scripts: using \c{-batch}, if something goes wrong at connection
time, the batch job will fail rather than hang.
-\S2{plink-usage-options-cmdfile} \c{-m filename} read command from a
-file
-
-If the command you want to run on the remote server is particularly
-large, you can read it from a file using the \c{-m} option, instead
-of putting it directly on Plink's command line. On most Unix
-systems, you can even put multiple lines in this file and execute
-more than one command in sequence, or a whole shell script.
-
-\S2{plink-usage-options-portfwd} \c{-L} and \c{-R} set up port
-forwarding
-
-Plink allows you to use port forwarding just as PuTTY does; if you
-have set up a PuTTY saved session that specifies port forwardings,
-and you connect to that session using Plink, then the same port
-forwardings will be set up.
-
-For convenience, Plink also offers the option to set up port
-forwarding on the command line. The command-line options work just
-like the ones in Unix \c{ssh} programs.
-
-To forward a local port (say 5110) to a remote destination (say
-\cw{popserver.example.com} port 110), you can write:
-
-\c plink mysession -L 5110:popserver.example.com:110
-
-And to forward a remote port to a local destination, just use the
-\c{-R} option instead of \c{-L}:
-
-\c plink mysession -R 5023:mytelnetserver.myhouse.org:23
-
-For general information on port forwarding, see
-\k{using-port-forwarding}.
-
\H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
Once you have set up Plink to be able to log in to a remote server
-\versionid $Id: pscp.but,v 1.20 2001/12/31 16:15:19 simon Exp $
+\versionid $Id: pscp.but,v 1.21 2002/08/07 19:20:06 simon Exp $
\#FIXME: Need examples
\S{pscp-usage-options} Options
+PSCP 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 PSCP are clearly marked.)
+
+PSCP also supports some of its own options. The following sections
+describe PSCP's specific command-line options.
+
These are the command line options that PSCP accepts.
\S2{pscp-usage-options-p}\c{-p} preserve file attributes
their contents. This allows you to use PSCP to transfer whole
directory structures between machines.
-\S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages
-
-The \c{-v} option to PSCP makes it print extra information about the
-file transfer. For example:
-
-\c Logging in as "fred".
-\c fred@example.com's password:
-\c Sending command: scp -v -f mibs.tar
-\c Connected to example.com
-\c Sending file modes: C0644 1320960 mibs.tar
-\c mibs.tar | 1290 kB | 67.9 kB/s | ETA: 00:00:00 | 100%
-\c Remote exit status 0
-\c Closing connection
-
-This information may be useful for debugging problems with PSCP.
-
-\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
-
-If the \c{host} you specify is a saved session, PSCP uses any port
-number specified in that saved session. If not, PSCP uses the default
-SSH port, 22. The \c{-P} option allows you specify the port number to
-connect to for PSCP's SSH connection.
-
-\S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
-
-If a password is required to connect to the \c{host}, PSCP will
-interactively prompt you for it. However, this may not always be
-appropriate. If you are running PSCP as part of some automated job,
-it will not be possible to enter a password by hand. The \c{-pw}
-option to PSCP 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{pscp-pubkey}.
-
\S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts
If you use the \c{-batch} option, PSCP will never give an
-\versionid $Id: psftp.but,v 1.4 2001/12/31 16:15:19 simon Exp $
+\versionid $Id: psftp.but,v 1.5 2002/08/07 19:20:06 simon Exp $
\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
-\versionid $Id: using.but,v 1.6 2002/04/18 20:45:01 jacob Exp $
+\versionid $Id: using.but,v 1.7 2002/08/07 19:20:06 simon Exp $
\C{using} Using PuTTY
\k{config-hostname}.) You can then enter a host name and a port
number, and make the connection.
-\H{putty-cmdline} The PuTTY command line
+\H{using-cmdline} The PuTTY command line
PuTTY can be made to do various things without user intervention by
supplying command-line arguments (e.g., from a command prompt window,
or a Windows shortcut).
-\S{putty-cmdline-session} Starting a session from the command line
+\S{using-cmdline-session} Starting a session from the command line
These options allow you to bypass the configuration window and launch
straight into a session.
-To start a connection to \c{host}:
+To start a connection to a server called \c{host}:
-\c putty.exe [-ssh] [user@]host[:port]
+\c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host[:port]
If this syntax is used, settings are taken from the Default Settings
-(see \k{config-saving}); \c{user} and \c{port} override these settings
-if supplied. Also, \c{-ssh} overrides the default protocol, if
-specified.
+(see \k{config-saving}); \c{user} and \c{port} override these
+settings if supplied. Also, you can specify a protocol, which will
+override the default protocol (see \k{using-cmdline-protocol}).
For telnet sessions, the following alternative syntax is supported
(this makes PuTTY suitable for use as a URL handler for telnet URLs in
\c putty.exe telnet://host[:port]/
In order to start an existing saved session called \c{sessionname},
-use the following syntax:
+use the \c{-load} option (described in \k{using-cmdline-load}).
-\c putty.exe @sessionname
+\c putty.exe -load "session name"
-\S{putty-cleanup} \c{-cleanup}
+\S{using-cleanup} \c{-cleanup}
If invoked with the \c{-cleanup} option, rather than running as
normal, PuTTY will remove its registry entries and random seed file
from the local machine (after confirming with the user).
+
+\S{using-general-opts} Standard command-line options
+
+PuTTY and its associated tools support a range of command-line
+options, most of which are consistent across all the tools. This
+section lists the available options in all tools. Options which are
+specific to a particular tool are covered in the chapter about that
+tool.
+
+\S2{using-cmdline-load} \c{-load}: load a saved session
+
+The \c{-load} option causes PuTTY to load configuration details out
+of a saved session. If these details include a host name, then this
+option is all you need to make PuTTY start a session (although Plink
+still requires an explicitly specified host name).
+
+You need double quotes around the session name if it contains spaces.
+
+If you want to create a Windows shortcut to start a PuTTY saved
+session, this is the option you should use: your shortcut should
+call something like
+
+\c d:\path\to\putty.exe -load "my session"
+
+(Note that PuTTY itself supports an alternative form of this option,
+for backwards compatibility. If you execute \c{putty @sessionname}
+it will have the same effect as \c{putty -load "sessionname"}. With
+the \c{@} form, no double quotes are required, and the \c{@} sign
+must be the very first thing on the command line. This form of the
+option is deprecated.)
+
+\S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
+\c{-telnet}, \c{-rlogin}, \c{-raw}
+
+To choose which protocol you want to connect with, you can use one
+of these options:
+
+\b \c{-ssh} selects the SSH protocol.
+
+\b \c{-telnet} selects the Telnet protocol.
+
+\b \c{-rlogin} selects the Rlogin protocol.
+
+\b \c{-raw} selects the raw protocol.
+
+These options are not available in the file transfer tools PSCP and
+PSFTP (which only work with the SSH protocol).
+
+These options are equivalent to the protocol selection buttons in
+the Session panel of the PuTTY configuration box (see
+\k{config-hostname}).
+
+\S2{using-cmdline-v} \c{-v}: increase verbosity
+
+Most of the PuTTY tools can be made to tell you more about what they
+are doing by supplying the \c{-v} option. If you are having trouble
+when making a connection, or you're simply curious, you can turn
+this switch on and hope to find out more about what is happening.
+
+\S2{using-cmdline-l} \c{-l}: specify a login name
+
+You can specify the user name to log in as on the remote server
+using the \c{-l} option. For example, \c{plink login.example.com -l
+fred}.
+
+These options are equivalent to the username selection box in the
+Connection panel of the PuTTY configuration box (see
+\k{config-username}).
+
+\S2{using-cmdline-portfwd} \c{-L} and \c{-R}: set up port forwardings
+
+As well as setting up port forwardings in the PuTTY configuration
+(see \k{config-ssh-portfwd}), you can also set up forwardings on the
+command line. The command-line options work just like the ones in
+Unix \c{ssh} programs.
+
+To forward a local port (say 5110) to a remote destination (say
+\cw{popserver.example.com} port 110), you can write something like
+one of these:
+
+\c putty -L 5110:popserver.example.com:110 -load mysession
+\c plink mysession -L 5110:popserver.example.com:110
+
+And to forward a remote port to a local destination, just use the
+\c{-R} option instead of \c{-L}:
+
+\c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession
+\c plink mysession -R 5023:mytelnetserver.myhouse.org:23
+
+For general information on port forwarding, see
+\k{using-port-forwarding}.
+
+These options are not available in the file transfer tools PSCP and
+PSFTP.
+
+\S2{using-cmdline-m} \c{-m}: read a remote command or script from a
+file
+
+The \c{-m} option performs a similar function to the \q{Remote
+command} box in the SSH panel of the PuTTY configuration box (see
+\k{config-command}). However, the \c{-m} option expects to be given
+a file name, and it will read a command from that file. On most Unix
+systems, you can even put multiple lines in this file and execute
+more than one command in sequence, or a whole shell script.
+
+This option is not available in the file transfer tools PSCP and
+PSFTP.
+
+\S2{using-cmdline-p} \c{-p} or \c{-P}: specify a port number
+
+The \c{-p} option (you can also write it as \c{-P}) is used to
+specify the port number to connect to. If you have a Telnet server
+running on port 9696 of a machine instead of port 23, for example:
+
+\c putty -telnet -p 9696 host.name
+\c plink -telnet -p 9696 host.name
+
+(Note that this option is more useful in Plink than in PuTTY,
+because in PuTTY you can write \c{putty -telnet host.name 9696} in
+any case.)
+
+These options are equivalent to the protocol selection buttons in
+the Session panel of the PuTTY configuration box (see
+\k{config-hostname}).
+
+\S2{using-cmdline-pw} \c{-pw}: specify a password
+
+A simple way to automate a remote login is to supply your password
+on the command line. This is \e{not recommended} for reasons of
+security. If you possibly can, we recommend you set up public-key
+authentication instead. See \k{pubkey} for details.
+
+Note that the \c{-pw} option only works when you are using the SSH
+protocol. Due to fundamental limitations of Telnet and Rlogin, these
+protocols do not support automated password authentication.
+
+\S2{using-cmdline-agent} \c{-A} and \c{-a}: control agent forwarding
+
+The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it
+off. These options are only meaningful if you are using SSH.
+
+See \k{pageant} for general information on Pageant, and
+\k{pageant-forward} for information on agent forwarding. Note that
+there is a security risk involved with enabling this option; see
+\k{pageant-security} for details.
+
+These options are equivalent to the agent forwarding checkbox in the
+Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}).
+
+These options are not available in the file transfer tools PSCP and
+PSFTP.
+
+\S2{using-cmdline-x11} \c{-X} and \c{-x}: control X11 forwarding
+
+The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns
+it off. These options are only meaningful if you are using SSH.
+
+For information on X11 forwarding, see \k{using-x-forwarding}.
+
+These options are equivalent to the X11 forwarding checkbox in the
+Tunnels panel of the PuTTY configuration box (see
+\k{config-ssh-x11}).
+
+These options are not available in the file transfer tools PSCP and
+PSFTP.
+
+\S2{using-cmdline-pty} \c{-t} and \c{-T}: control pseudo-terminal
+allocation
+
+The \c{-t} option ensures PuTTY attempts to allocate a
+pseudo-terminal at the server, and \c{-T} stops it from allocating
+one. These options are only meaningful if you are using SSH.
+
+These options are equivalent to the \q{Don't allocate a
+pseudo-terminal} checkbox in the SSH panel of the PuTTY
+configuration box (see \k{config-ssh-pty}).
+
+These options are not available in the file transfer tools PSCP and
+PSFTP.
+
+\S2{using-cmdline-compress} \c{-C}: enable compression
+
+The \c{-C} option enables compression of the data sent across the
+network. This option is only meaningful if you are using SSH.
+
+This option is equivalent to the \q{Enable compression} checkbox in
+the SSH panel of the PuTTY configuration box (see
+\k{config-ssh-comp}).
+
+\S2{using-cmdline-sshprot} \c{-1} and \c{-2}: specify an SSH protocol
+version
+
+The \c{-1} and \c{-2} options force PuTTY to use version 1 or
+version 2 of the SSH protocol. These options are only meaningful if
+you are using SSH.
+
+These options are equivalent to selecting your preferred SSH
+protocol version as \q{1 only} or \q{2 only} in the SSH panel of the
+PuTTY configuration box (see \k{config-ssh-prot}).
+
+\S2{using-cmdline-identity} \c{-i}: specify an SSH private key
+
+The \c{-i} option allows you to specify the name of a private key
+file which PuTTY will use to authenticate with the server. This
+option is only meaningful if you are using SSH.
+
+For general information on public-key authentication, see \k{pubkey}.
+
+This option is equivalent to the \q{Private key file for
+authentication} box in the Auth panel of the PuTTY configuration box
+(see \k{config-ssh-privkey}).
~mdw / sgt / putty / commitdiff