nhyatt/putty-source
1
0
Fork 0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-01-25 01:02:24 +00:00
Code Issues Projects Releases Wiki Activity

Document all the new command-line stuff.

Browse Source 
[originally from svn r1822]
This commit is contained in:
Simon Tatham 2002-08-07 19:20:06 +00:00
parent 54e9304111
commit 4abd468e14
5 changed files with 249 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/config.but
View File

@ -1,4 +1,4 @@
\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
@ -1660,8 +1660,9 @@ version 1 or version 2. \#{FIXME: say something about this elsewhere?}
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}

106
doc/plink.but
View File

@ -1,4 +1,4 @@
\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
@ -151,72 +151,14 @@ details:
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
@ -226,40 +168,6 @@ This may help Plink's behaviour when it is used in automated
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

46
doc/pscp.but
View File

@ -1,4 +1,4 @@
\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
@ -164,6 +164,14 @@ directory on the remote server.
\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
@ -194,42 +202,6 @@ PSCP to descend into any directories you specify, and to copy them and
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

46
doc/psftp.but
View File

@ -1,4 +1,4 @@
\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
@ -49,45 +49,13 @@ any server:
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

233
doc/using.but
View File

@ -1,4 +1,4 @@
\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
@ -337,25 +337,25 @@ you simply select the fourth protocol name, \q{Raw}, from the
\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
@ -364,12 +364,223 @@ web browsers):
\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}).