X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=doc%2Fplink.but;h=44cf8d7d584652f0e196ba144bec4af9e0f13827;hb=4abd468e14d110f2085f7a693687a9c19e1d47e1;hp=12b08bb3caaebe1d711d21c627b220361705ec65;hpb=54a4337c6afca452270a8513c9439aee056b135c;p=PuTTY.git diff --git a/doc/plink.but b/doc/plink.but index 12b08bb3..44cf8d7d 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -1,12 +1,234 @@ +\versionid $Id: plink.but,v 1.16 2002/08/07 19:20:06 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. + +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}. 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. + +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% + +This will only work for the lifetime of that particular console +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} 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 +version of Plink you're using, and gives you a brief summary of how to +use Plink: + +\c Z:\sysosd>plink +\c PuTTY Link: command-line connection utility +\c Release 0.50 +\c Usage: plink [options] [user@]host [command] +\c Options: +\c -v show verbose messages +\c -ssh force use of ssh protocol +\c -P port connect to specified port +\c -pw passw login with specified password + +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. + +\S{plink-options} Plink command line 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. + +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 +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. + +\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 +\c{CVS_RSH} to point to Plink: + +\c set CVS_RSH=\path\to\plink.exe + +You also need to arrange to be able to connect to a remote host +without any interactive prompts, as described in +\k{plink-usage-batch}. + +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 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 + +\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 non-interactively, as described in +\k{plink-usage-batch}. + +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 \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 + +or (if you're using a saved session): -\# Explain that Plink is probably not what you want if you want to -\# run an interactive session in a Command Prompt window +\c cvs -d :ext:user@sessionname:/path/to/repository co module -\# Explain that Plink is really for batch-file use, and that -\# therefore it works best with public-key authentication; link to -\# that chapter +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. -\# Give instructions on how to set up Plink with CVS +\# \H{plink-whatelse} Using Plink with... ?