X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/f5e8038f91120319f30126b8b943252d523a5322..0622ea7168aa265db70be885fbffb050f29f0205:/doc/plink.but diff --git a/doc/plink.but b/doc/plink.but index cdee880e..a1ef625f 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -1,44 +1,40 @@ -\versionid $Id: plink.but,v 1.5 2001/04/18 15:23:36 owen Exp $ +\versionid $Id: plink.but,v 1.13 2001/12/31 16:15:19 simon Exp $ \C{plink} Using the command-line connection tool Plink -\# Explain Plink +\i{Plink} (PuTTY Link) is a command-line connection tool similar to +UNIX \c{ssh}. It is mostly used for automated operations, such as +making CVS access a repository on a remote server. -\# Explain that Plink is probably not what you want if you want to -\# run an interactive session in a Command Prompt window - -\# Explain that Plink is really for batch-file use, and that -\# therefore it works best with public-key authentication; link to -\# that chapter - -\# Give instructions on how to set up Plink with CVS - -\i{Plink} (PuTTY Link), is a command-line connection tool similar to -UNIX \c{ssh}. It is probably not what you want if you want to run an +Plink is probably not what you want if you want to run an interactive session in a console window. \H{plink-starting} Starting Plink -Plink is a command line application. This means that you cannot just -double-click on its icon to run it and instead you have to bring up a -\i{console window}. With Windows 95, 98, and ME, this is called an -\q{MS-DOS Prompt} and with Windows NT and 2000 it is called a -\q{Command Prompt}. It should be available from the Programs section +Plink is a command line application. This means that you cannot just +double-click on its icon to run it and instead you have to bring up +a \i{console window}. In Windows 95, 98, and ME, this is called an +\q{MS-DOS Prompt}, and in Windows NT and 2000 it is called a +\q{Command Prompt}. It should be available from the Programs section of your Start Menu. -To start Plink it will need either to be on your \i{\c{PATH}} or in your -current directory. To add the directory containing Plink to your -\c{PATH} environment variable, type into the console window: +In order to use Plink, the file \c{plink.exe} will need either to be +on your \i{\c{PATH}} or in your current directory. To add the +directory containing Plink to your \c{PATH} environment variable, +type into the console window: -\c set PATH C:\path\to\putty\directory;%PATH% +\c set PATH=C:\path\to\putty\directory;%PATH% This will only work for the lifetime of that particular console -window. To set your \c{PATH} more permanently on Windows NT, use the +window. To set your \c{PATH} more permanently on Windows NT, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set} command like the one above. -\H{plink-usage} Plink Usage +\H{plink-usage} Using Plink + +This section describes the basics of how to use Plink for +interactive logins and for automated processes. Once you've got a console window to type into, you can just type \c{plink} on its own to bring up a usage message. This tells you the @@ -55,11 +51,112 @@ use Plink: \c -P port connect to specified port \c -pw passw login with specified password -\S{plink-usage-basics} The basics +Once this works, you are ready to use Plink. + +\S{plink-usage-interactive} Using Plink for interactive logins + +To make a simple interactive connection to a remote server, just +type \c{plink} and then the host name: + +\c Z:\sysosd>plink login.example.com +\c +\c Debian GNU/Linux 2.2 flunky.example.com +\c flunky login: + +You should then be able to log in as normal and run a session. The +output sent by the server will be written straight to your command +prompt window, which will most likely not interpret terminal control +codes in the way the server expects it to. So if you run any +full-screen applications, for example, you can expect to see strange +characters appearing in your window. Interactive connections like +this are not the main point of Plink. + +In order to connect with a different protocol, you can give the +command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}. +To make an SSH connection, for example: + +\c Z:\sysosd>plink -ssh login.example.com +\c login as: + +If you have already set up a PuTTY saved session, then instead of +supplying a host name, you can give the saved session name. This +allows you to use public-key authentication, specify a user name, +and use most of the other features of PuTTY: + +\c Z:\sysosd>plink my-ssh-session +\c Sent username "fred" +\c Authenticating with public key "fred@winbox" +\c Last login: Thu Dec 6 19:25:33 2001 from :0.0 +\c fred@flunky:~$ + +\S{plink-usage-batch} Using Plink for automated connections + +More typically Plink is used with the SSH protocol, to enable you to +talk directly to a program running on the server. To do this you +have to ensure Plink is \e{using} the SSH protocol. You can do this +in several ways: + +\b Use the \c{-ssh} option as described in +\k{plink-usage-interactive}. + +\b Set up a PuTTY saved session that describes the server you are +connecting to, and that also specifies the protocol as SSH. + +\b Set the Windows environment variable \c{PLINK_PROTOCOL} to the +word \c{ssh}. + +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. + +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. +For example, \c{plink login.example.com -l fred}. + +\b Set up a PuTTY saved session that describes the server you are +connecting to, and that also specifies the username to log in as +(see \k{config-username}). + +To avoid being prompted for a password, you should almost certainly +set up public-key authentication. (See \k{pubkey} for a general +introduction to public-key authentication.) Again, you can do this +in two ways: + +\b Set up a PuTTY saved session that describes the server you are +connecting to, and that also specifies a private key file (see +\k{config-ssh-privkey}). For this to work without prompting, your +private key will need to have no passphrase. + +\b Store the private key in Pageant. See \k{pageant} for further +information. + +Once you have done all this, you should be able to run a remote +command on the SSH server machine and have it execute automatically +with no prompting: + +\c Z:\sysosd>plink login.example.com -l fred echo hello, world +\c hello, world +\c +\c Z:\sysosd> + +Or, if you have set up a saved session with all the connection +details: + +\c Z:\sysosd>plink mysession echo hello, world +\c hello, world +\c +\c Z:\sysosd> + +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 -These are the command line options that Plink accepts. +This section describes the command line options that Plink accepts. \S2{plink-usage-options-v}\c{-v} show verbose messages @@ -83,16 +180,99 @@ information about the connection being made, for example: This information can be useful for diagnosing problems. -\S2{plink-usage-options-ssh}\c{-ssh} force use of ssh protocol +\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 -\H{plink-pubkey} Using public key authentication with Plink +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. + +\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 +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 +to do next. + +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 +without any interactive prompting (see \k{plink-usage-batch}), you +can use it for lots of scripting and batch purposes. For example, to +start a backup on a remote machine, you might use a command like: + +\c plink root@myserver /etc/backups/do-backup.sh + +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 + +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. + \H{plink-cvs} Using Plink with \i{CVS} To use Plink with CVS, you need to set the environment variable @@ -101,50 +281,38 @@ To use Plink with CVS, you need to set the environment variable \c set CVS_RSH=\path\to\plink.exe You also need to arrange to be able to connect to a remote host -without a password. To do this, either: +without any interactive prompts, as described in +\k{plink-usage-batch}. -\b Run PuTTY, and create a PuTTY saved session (see \k{config-saving}) -with the protocol set to SSH (see \k{config-hostname}) and specifies -your private key file (see \k{config-auth}). You will probably also -want to specify a username to log in as (see \k{config-username}). You should then be able to run CVS as follows: \c cvs -d :ext:user@sessionname:/path/to/repository co module -If you specified a username in your saved session, you can just say: +If you specified a username in your saved session, you don't even +need to specify the \q{user} part of this, and you can just say: \c cvs -d :ext:sessionname:/path/to/repository co module -Alternatively, you can use Pageant if Pageant is running (see -\k{pageant}). To do this, you would: - -\b Ensure Pageant is running, and has your private key stored in it. - -\b Run CVS as follows: - -\c cvs -d :ext:user@hostname:/path/to/repository co module - \H{plink-wincvs} Using Plink with \i{WinCVS} Plink can also be used with WinCVS. Firstly, arrange for Plink to be -able to connect to a remote host without a password. \k{plink-cvs} -has instructions on this. +able to connect to a remote host non-interactively, as described in +\k{plink-usage-batch}. -In WinCVS, bring up the \e{Preferences} dialogue box from the -\e{Admin} menu, and switch to the \e{Ports} tab. Tick the box there -labelled \e{Check for an alternate rsh name} and in the text entry -field to the right enter the full path to \c{plink.exe}. Select -\e{OK} on the \e{Preferences} dialogue box. +Then, in WinCVS, bring up the \q{Preferences} dialogue box from the +\e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there +labelled \q{Check for an alternate \cw{rsh} name} and in the text +entry field to the right enter the full path to \c{plink.exe}. +Select \q{OK} on the \q{Preferences} dialogue box. -Next, select \e{Command Line} from the WinCVS \e{Admin} menu, and type +Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type a CVS command as in \k{plink-cvs}, for example: \c cvs -d :ext:user@hostname:/path/to/repository co module -Select the folder you want to check out to with the \e{Change Folder} -button, and click \e{OK} to check out your module. Once you've got +Select the folder you want to check out to with the \q{Change Folder} +button, and click \q{OK} to check out your module. Once you've got modules checked out, WinCVS will happily invoke plink from the GUI for CVS operations. -\H{plink-whatelse} Using Plink with... ? - +\# \H{plink-whatelse} Using Plink with... ?