-\versionid $Id: using.but,v 1.1 2001/11/25 18:59:12 simon Exp $
+\versionid $Id: using.but,v 1.8 2002/09/11 17:30:36 jacob Exp $
\C{using} Using PuTTY
If you double-click the left mouse button, PuTTY will select a whole
word. If you double-click, hold down the second click, and drag the
-mouse, PuTTY will select a sequence of whole words. If you
-\e{triple}-click, or triple-click and drag, then PuTTY will select a
-whole line or sequence of lines.
+mouse, PuTTY will select a sequence of whole words. (You can adjust
+precisely what PuTTY considers to be part of a word; see
+\k{config-charclasses}.) If you \e{triple}-click, or triple-click
+and drag, then PuTTY will select a whole line or sequence of lines.
If you want to select a rectangular region instead of selecting to
the end of each line, you can do this by holding down Alt when you
make your selection. (You can also configure rectangular selection
to be the default, and then holding down Alt gives the normal
-behaviour instead. See \#{FIXME} for details.)
+behaviour instead. See \k{config-rectselect} for details.)
If you have a middle mouse button, then you can use it to adjust an
existing selection if you selected something slightly wrong. (If you
\q{even more}. When you select this, PuTTY will expand to fill the
whole screen and its borders, title bar and scrollbar will
disappear. (You can configure the scrollbar not to disappear in
-full-screen mode if you want to keep it.)
-\#{FIXME, document how and xref to it from here!}
+full-screen mode if you want to keep it; see \k{config-scrollback}.)
When you are in full-screen mode, you can still access the system
menu if you click the left mouse button in the \e{extreme} top left
panel, you should see a large number of character sets which you can
select. Now all you need is to find out which of them you want!
-\H{using-forwarding} Port forwarding and X forwarding in SSH
+\H{using-x-forwarding} Using X11 forwarding in SSH
+
+The SSH protocol has the ability to securely forward X Window System
+applications over your encrypted SSH connection, so that you can run
+an application on the SSH server machine and have it put its windows
+up on your local machine without sending any X network traffic in
+the clear.
+
+In order to use this feature, you will need an X display server for
+your Windows machine, such as X-Win32 or Exceed. This will probably
+install itself as display number 0 on your local machine; if it
+doesn't, the manual for the X server should tell you what it does
+do.
+
+You should then tick the \q{Enable X11 forwarding} box in the
+Tunnels panel (see \k{config-ssh-x11}) before starting your SSH
+session. The \q{X display location} box reads \c{localhost:0} by
+default, which is the usual display location where your X server
+will be installed. If that needs changing, then change it.
+
+Now you should be able to log in to the SSH server as normal. To
+check that X forwarding has been successfully negotiated during
+connection startup, you can check the PuTTY Event Log (see
+\k{using-eventlog}). It should say something like this:
+
+\c 2001-12-05 17:22:01 Requesting X11 forwarding
+\c 2001-12-05 17:22:02 X11 forwarding enabled
+
+If the remote system is Unix or Unix-like, you should also be able
+to see that the \c{DISPLAY} environment variable has been set to
+point at display 10 or above on the SSH server machine itself:
+
+\c fred@unixbox:~$ echo $DISPLAY
+\c unixbox:10.0
+
+If this works, you should then be able to run X applications in the
+remote session and have them display their windows on your PC.
+
+Note that if your PC X server requires authentication to connect,
+then PuTTY cannot currently support it. If this is a problem for
+you, you should mail the authors \#{FIXME} and give details.
+
+\H{using-port-forwarding} Using port forwarding in SSH
+
+The SSH protocol has the ability to forward arbitrary network
+connections over your encrypted SSH connection, to avoid the network
+traffic being sent in clear. For example, you could use this to
+connect from your home computer to a POP-3 server on a remote
+machine without your POP-3 password being visible to network
+sniffers.
+
+In order to use port forwarding to connect from your local machine
+to a port on a remote server, you need to:
+
+\b Choose a port number on your local machine where PuTTY should
+listen for incoming connections. There are likely to be plenty of
+unused port numbers above 3000.
+
+\b Now, before you start your SSH connection, go to the Tunnels
+panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio
+button is set. Enter the local port number into the \q{Source port}
+box. Enter the destination host name and port number into the
+\q{Destination} box, separated by a colon (for example,
+\c{popserver.example.com:110} to connect to a POP-3 server).
+
+\b Now click the \q{Add} button. The details of your port forwarding
+should appear in the list box.
+
+Now start your session and log in. (Port forwarding will not be
+enabled until after you have logged in; otherwise it would be easy
+to perform completely anonymous network attacks, and gain access to
+anyone's virtual private network). To check that PuTTY has set up
+the port forwarding correctly, you can look at the PuTTY Event Log
+(see \k{using-eventlog}). It should say something like this:
+
+\c 2001-12-05 17:22:10 Local port 3110 forwarding to
+\c popserver.example.com:110
+
+Now if you connect to the source port number on your local PC, you
+should find that it answers you exactly as if it were the service
+running on the destination machine. So in this example, you could
+then configure an e-mail client to use \c{localhost:3110} as a POP-3
+server instead of \c{popserver.example.com:110}. (Of course, the
+forwarding will stop happening when your PuTTY session closes down.)
+
+You can also forward ports in the other direction: arrange for a
+particular port number on the \e{server} machine to be forwarded
+back to your PC as a connection to a service on your PC or near it.
+To do this, just select the \q{Remote} radio button instead of the
+\q{Local} one. The \q{Source port} box will now specify a port
+number on the \e{server} (note that most servers will not allow you
+to use port numbers under 1024 for this purpose).
+
+The source port for a forwarded connection usually does not accept
+connections from any machine except the SSH client or server machine
+itself (for local and remote forwardings respectively). There are
+controls in the Tunnels panel to change this:
+
+\b The \q{Local ports accept connections from other hosts} option
+allows you to set up local-to-remote port forwardings in such a way
+that machines other than your client PC can connect to the forwarded
+port.
+
+\b The \q{Remote ports do the same} option does the same thing for
+remote-to-local port forwardings (so that machines other than the
+SSH server machine can connect to the forwarded port.) Note that
+this feature is only available in the SSH 2 protocol, and not all
+SSH 2 servers support it (OpenSSH 3.0 does not, for example).
-\# using X forwarding
+\H{using-rawprot} Making raw TCP connections
-\# using port forwarding
+A lot of Internet protocols are composed of commands and responses
+in plain text. For example, SMTP (the protocol used to transfer
+e-mail), NNTP (the protocol used to transfer Usenet news), and HTTP
+(the protocol used to serve Web pages) all consist of commands in
+readable plain text.
-\H{using-rawprot} Making raw TCP connections
+Sometimes it can be useful to connect directly to one of these
+services and speak the protocol \q{by hand}, by typing protocol
+commands and watching the responses. On Unix machines, you can do
+this using the system's \c{telnet} command to connect to the right
+port number. For example, \c{telnet mailserver.example.com 25} might
+enable you to talk directly to the SMTP service running on a mail
+server.
+
+Although the Unix \c{telnet} program provides this functionality,
+the protocol being used is not really Telnet. Really there is no
+actual protocol at all; the bytes sent down the connection are
+exactly the ones you type, and the bytes shown on the screen are
+exactly the ones sent by the server. Unix \c{telnet} will attempt to
+detect or guess whether the service it is talking to is a real
+Telnet service or not; PuTTY prefers to be told for certain.
+
+In order to make a debugging connection to a service of this type,
+you simply select the fourth protocol name, \q{Raw}, from the
+\q{Protocol} buttons in the \q{Session} configuration panel. (See
+\k{config-hostname}.) You can then enter a host name and a port
+number, and make the connection.
+
+\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{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 a server called \c{host}:
+
+\c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host
+
+If this syntax is used, settings are taken from the Default Settings
+(see \k{config-saving}); \c{user} overrides 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
+web browsers):
+
+\c putty.exe telnet://host[:port]/
+
+In order to start an existing saved session called \c{sessionname},
+use the \c{-load} option (described in \k{using-cmdline-load}).
+
+\c putty.exe -load "session name"
+
+\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}: specify a port number
+
+The \c{-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:
+
+\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}.
-\# Raw protocol
+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}).
projects / u / mdw / putty / blobdiff