3.8 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). 3.8.1 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 a server called `host': putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host If this syntax is used, settings are taken from the Default Settings (see section 4.1.2); `user' overrides these settings if supplied. Also, you can specify a protocol, which will override the default protocol (see section 22.214.171.124). For telnet sessions, the following alternative syntax is supported (this makes PuTTY suitable for use as a URL handler for telnet URLs in web browsers): putty.exe telnet://host[:port]/ To start a connection to a serial port, e.g. COM1: putty.exe -serial com1 In order to start an existing saved session called `sessionname', use the `-load' option (described in section 126.96.36.199). putty.exe -load "session name" 3.8.2 `-cleanup' If invoked with the `-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). Note that on multi-user systems, `-cleanup' only removes registry entries and files associated with the currently logged-in user. 3.8.3 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. 188.8.131.52 `-load': load a saved session The `-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. 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 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 `putty @sessionname' it will have the same effect as `putty -load "sessionname"'. With the `@' form, no double quotes are required, and the `@' sign must be the very first thing on the command line. This form of the option is deprecated.) 184.108.40.206 Selecting a protocol: `-ssh', `-telnet', `-rlogin', `-raw' `- serial' To choose which protocol you want to connect with, you can use one of these options: - `-ssh' selects the SSH protocol. - `-telnet' selects the Telnet protocol. - `-rlogin' selects the Rlogin protocol. - `-raw' selects the raw protocol. - `-serial' selects a serial connection. 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 section 4.1.1). 220.127.116.11 `-v': increase verbosity Most of the PuTTY tools can be made to tell you more about what they are doing by supplying the `-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. 18.104.22.168 `-l': specify a login name You can specify the user name to log in as on the remote server using the `-l' option. For example, `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 section 4.14.1). 22.214.171.124 `-L', `-R' and `-D': set up port forwardings As well as setting up port forwardings in the PuTTY configuration (see section 4.24), you can also set up forwardings on the command line. The command-line options work just like the ones in Unix `ssh' programs. To forward a local port (say 5110) to a remote destination (say popserver.example.com port 110), you can write something like one of these: putty -L 5110:popserver.example.com:110 -load mysession plink mysession -L 5110:popserver.example.com:110 To forward a remote port to a local destination, just use the `-R' option instead of `-L': putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession plink mysession -R 5023:mytelnetserver.myhouse.org:23 To specify an IP address for the listening end of the tunnel, prepend it to the argument: plink -L 127.0.0.5:23:localhost:23 myhost To set up SOCKS-based dynamic port forwarding on a local port, use the `-D' option. For this one you only have to pass the port number: putty -D 4096 -load mysession For general information on port forwarding, see section 3.5. These options are not available in the file transfer tools PSCP and PSFTP. 126.96.36.199 `-m': read a remote command or script from a file The `-m' option performs a similar function to the `Remote command' box in the SSH panel of the PuTTY configuration box (see section 4.18.1). However, the `-m' option expects to be given a local file name, and it will read a command from that file. With some servers (particularly Unix systems), you can even put multiple lines in this file and execute more than one command in sequence, or a whole shell script; but this is arguably an abuse, and cannot be expected to work on all servers. In particular, it is known _not_ to work with certain `embedded' servers, such as Cisco routers. This option is not available in the file transfer tools PSCP and PSFTP. 188.8.131.52 `-P': specify a port number The `-P' option 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: putty -telnet -P 9696 host.name plink -telnet -P 9696 host.name (Note that this option is more useful in Plink than in PuTTY, because in PuTTY you can write `putty -telnet host.name 9696' in any case.) This option is equivalent to the port number control in the Session panel of the PuTTY configuration box (see section 4.1.1). 184.108.40.206 `-pw': specify a password A simple way to automate a remote login is to supply your password on the command line. This is _not recommended_ for reasons of security. If you possibly can, we recommend you set up public-key authentication instead. See chapter 8 for details. Note that the `-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. 220.127.116.11 `-agent' and `-noagent': control use of Pageant for authentication The `-agent' option turns on SSH authentication using Pageant, and `-noagent' turns it off. These options are only meaningful if you are using SSH. See chapter 9 for general information on Pageant. These options are equivalent to the agent authentication checkbox in the Auth panel of the PuTTY configuration box (see section 4.20.3). 18.104.22.168 `-A' and `-a': control agent forwarding The `-A' option turns on SSH agent forwarding, and `-a' turns it off. These options are only meaningful if you are using SSH. See chapter 9 for general information on Pageant, and section 9.4 for information on agent forwarding. Note that there is a security risk involved with enabling this option; see section 9.5 for details. These options are equivalent to the agent forwarding checkbox in the Auth panel of the PuTTY configuration box (see section 4.20.6). These options are not available in the file transfer tools PSCP and PSFTP. 22.214.171.124 `-X' and `-x': control X11 forwarding The `-X' option turns on X11 forwarding in SSH, and `-x' turns it off. These options are only meaningful if you are using SSH. For information on X11 forwarding, see section 3.4. These options are equivalent to the X11 forwarding checkbox in the X11 panel of the PuTTY configuration box (see section 4.23). These options are not available in the file transfer tools PSCP and PSFTP. 126.96.36.199 `-t' and `-T': control pseudo-terminal allocation The `-t' option ensures PuTTY attempts to allocate a pseudo-terminal at the server, and `-T' stops it from allocating one. These options are only meaningful if you are using SSH. These options are equivalent to the `Don't allocate a pseudo- terminal' checkbox in the SSH panel of the PuTTY configuration box (see section 4.22.1). These options are not available in the file transfer tools PSCP and PSFTP. 188.8.131.52 `-N': suppress starting a shell or command The `-N' option prevents PuTTY from attempting to start a shell or command on the remote server. You might want to use this option if you are only using the SSH connection for port forwarding, and your user account on the server does not have the ability to run a shell. This feature is only available in SSH protocol version 2 (since the version 1 protocol assumes you will always want to run a shell). This option is equivalent to the `Don't start a shell or command at all' checkbox in the SSH panel of the PuTTY configuration box (see section 4.18.2). This option is not available in the file transfer tools PSCP and PSFTP. 184.108.40.206 `-nc': make a remote network connection in place of a remote shell or command The `-nc' option prevents Plink (or PuTTY) from attempting to start a shell or command on the remote server. Instead, it will instruct the remote server to open a network connection to a host name and port number specified by you, and treat that network connection as if it were the main session. You specify a host and port as an argument to the `-nc' option, with a colon separating the host name from the port number, like this: plink host1.example.com -nc host2.example.com:1234 You might want to use this feature if you needed to make an SSH connection to a target host which you can only reach by going through a proxy host, and rather than using port forwarding you prefer to use the local proxy feature (see section 4.15.1 for more about local proxies). In this situation you might select `Local' proxy type, set your local proxy command to be `plink %proxyhost - nc %host:%port', enter the target host name on the Session panel, and enter the directly reachable proxy host name on the Proxy panel. This feature is only available in SSH protocol version 2 (since the version 1 protocol assumes you will always want to run a shell). It is not available in the file transfer tools PSCP and PSFTP. It is available in PuTTY itself, although it is unlikely to be very useful in any tool other than Plink. Also, `-nc' uses the same server functionality as port forwarding, so it will not work if your server administrator has disabled port forwarding. (The option is named `-nc' after the Unix program `nc', short for `netcat'. The command `plink host1 -nc host2:port' is very similar in functionality to `plink host1 nc host2 port', which invokes `nc' on the server and tells it to connect to the specified destination. However, Plink's built-in `-nc' option does not depend on the `nc' program being installed on the server.) 220.127.116.11 `-C': enable compression The `-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 `Enable compression' checkbox in the SSH panel of the PuTTY configuration box (see section 4.18.3). 18.104.22.168 `-1' and `-2': specify an SSH protocol version The `-1' and `-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 `1 only' or `2 only' in the SSH panel of the PuTTY configuration box (see section 4.18.4). 22.214.171.124 `-4' and `-6': specify an Internet protocol version The `-4' and `-6' options force PuTTY to use the older Internet protocol IPv4 or the newer IPv6 for most outgoing connections. These options are equivalent to selecting your preferred Internet protocol version as `IPv4' or `IPv6' in the Connection panel of the PuTTY configuration box (see section 4.13.4). 126.96.36.199 `-i': specify an SSH private key The `-i' option allows you to specify the name of a private key file in `*.PPK' format 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 chapter 8. This option is equivalent to the `Private key file for authentication' box in the Auth panel of the PuTTY configuration box (see section 4.20.8). 188.8.131.52 `-loghost': specify a logical host name This option overrides PuTTY's normal SSH host key caching policy by telling it the name of the host you expect your connection to end up at (in cases where this differs from the location PuTTY thinks it's connecting to). It can be a plain host name, or a host name followed by a colon and a port number. See section 4.13.5 for more detail on this. 184.108.40.206 `-pgpfp': display PGP key fingerprints This option causes the PuTTY tools not to run as normal, but instead to display the fingerprints of the PuTTY PGP Master Keys, in order to aid with verifying new versions. See appendix E for more information. 220.127.116.11 `-sercfg': specify serial port configuration This option specifies the configuration parameters for the serial port (baud rate, stop bits etc). Its argument is interpreted as a comma-separated list of configuration options, which can be as follows: - Any single digit from 5 to 9 sets the number of data bits. - `1', `1.5' or `2' sets the number of stop bits. - Any other numeric string is interpreted as a baud rate. - A single lower-case letter specifies the parity: `n' for none, `o' for odd, `e' for even, `m' for mark and `s' for space. - A single upper-case letter specifies the flow control: `N' for none, `X' for XON/XOFF, `R' for RTS/CTS and `D' for DSR/DTR. For example, `-sercfg 19200,8,n,1,N' denotes a baud rate of 19200, 8 data bits, no parity, 1 stop bit and no flow control.