X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/a88d77d63c57f69abdb74bd636de334311bd5c11..055817455466c8eb60392f30bb7c689763962e17:/doc/plink.but diff --git a/doc/plink.but b/doc/plink.but index cb92aa8e..7e278007 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 $ +\define{versionidplink} \versionid $Id$ \C{plink} Using the command-line connection tool Plink @@ -43,13 +43,36 @@ use Plink: \c Z:\sysosd>plink \c PuTTY Link: command-line connection utility -\c Release 0.50 +\c Release 0.XX \c Usage: plink [options] [user@]host [command] +\c ("host" can also be a PuTTY saved session name) \c Options: +\c -V print version information \c -v show verbose messages -\c -ssh force use of ssh protocol +\c -load sessname Load settings from saved session +\c -ssh -telnet -rlogin -raw +\c force use of a particular protocol \c -P port connect to specified port +\c -l user connect with specified username +\c -m file read remote command(s) from file +\c -batch disable all interactive prompts +\c The following options only apply to SSH connections: \c -pw passw login with specified password +\c -D [listen-IP:]listen-port +\c Dynamic SOCKS-based port forwarding +\c -L [listen-IP:]listen-port:host:port +\c Forward local port to remote address +\c -R [listen-IP:]listen-port:host:port +\c Forward remote port to local address +\c -X -x enable / disable X11 forwarding +\c -A -a enable / disable agent forwarding +\c -t -T enable / disable pty allocation +\c -1 -2 force use of particular protocol version +\c -4 -6 force use of IPv4 or IPv6 +\c -C enable compression +\c -i key private key file for authentication +\c -s remote command is an SSH subsystem (SSH-2 only) +\c -N don't start a shell/command (SSH-2 only) Once this works, you are ready to use Plink. @@ -109,6 +132,19 @@ Usually Plink is not invoked directly by a user, but run automatically by another process. Therefore you typically do not want Plink to prompt you for a user name or a password. +Next, you are likely to need to avoid the various interactive +prompts Plink can produce. You might be prompted to verify the host +key of the server you're connecting to, to enter a user name, or to +enter a password. + +To avoid being prompted for the server host key when using Plink for +an automated connection, you should first make a \e{manual} +connection (using either of PuTTY or Plink) to the same server, +verify the host key (see \k{gs-hostkey} for more information), and +select Yes to add the host key to the Registry. After that, Plink +commands connecting to that server should not give a host key prompt +unless the host key changes. + To avoid being prompted for a user name, you can: \b Use the \c{-l} option to specify a user name on the command line. @@ -151,70 +187,16 @@ 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-usage-options} 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 +\S{plink-options} Plink command line options -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: +Plink accepts all the general command line options supported by the +PuTTY tools. See \k{using-general-opts} for a description of these +options. -\c plink -ssh login.example.com -P 5022 +Plink also supports some of its own options. The following sections +describe Plink's specific command-line options. -\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 +\S2{plink-option-batch} \c{-batch}: disable all interactive prompts If you use the \c{-batch} option, Plink will never give an interactive prompt while establishing the connection. If the @@ -226,39 +208,13 @@ 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}: +\S2{plink-option-s} \c{-s}: remote command is SSH subsystem -\c plink mysession -R 5023:mytelnetserver.myhouse.org:23 +If you specify the \c{-s} option, Plink passes the specified command +as the name of an SSH \q{subsystem} rather than an ordinary command +line. -For general information on port forwarding, see -\k{using-port-forwarding}. +(This option is only meaningful with the SSH-2 protocol.) \H{plink-batch} Using Plink in \i{batch files} and \i{scripts} @@ -272,7 +228,7 @@ start a backup on a remote machine, you might use a command like: Or perhaps you want to fetch all system log lines relating to a particular web area: -\c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs +\c plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog Any non-interactive command you could usefully run on the server command line, you can run in a batch file using Plink in this way.