From: simon Date: Wed, 7 Aug 2002 19:20:06 +0000 (+0000) Subject: Document all the new command-line stuff. X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/commitdiff_plain/e117a7427fbe82256705a281e29ec0fcfafeb613 Document all the new command-line stuff. git-svn-id: svn://svn.tartarus.org/sgt/putty@1822 cda61777-01e9-0310-a592-d414129be87e --- diff --git a/doc/config.but b/doc/config.but index 678d0f76..397a594d 100644 --- a/doc/config.but +++ b/doc/config.but @@ -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} diff --git a/doc/plink.but b/doc/plink.but index cb92aa8e..44cf8d7d 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -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 diff --git a/doc/pscp.but b/doc/pscp.but index 5da247df..ad0144c7 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -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 diff --git a/doc/psftp.but b/doc/psftp.but index 40094376..cdfadea5 100644 --- a/doc/psftp.but +++ b/doc/psftp.but @@ -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 diff --git a/doc/using.but b/doc/using.but index 62d8eacd..ae093b2d 100644 --- a/doc/using.but +++ b/doc/using.but @@ -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}).