X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=doc%2Fusing.but;h=7d184b7c21c3cd32c3a1df42b93e7b118ab92e3a;hb=8d48caa849907d6737fbdaee5fc49907beb899c2;hp=6d5d44ba439ff17d64282116f25576a3d5cc1ce4;hpb=f3ac927d3339224a0d978f6c29d497b7676e895e;p=PuTTY.git diff --git a/doc/using.but b/doc/using.but index 6d5d44ba..7d184b7c 100644 --- a/doc/using.but +++ b/doc/using.but @@ -1,5 +1,3 @@ -\define{versionidusing} \versionid $Id$ - \C{using} Using PuTTY This chapter provides a general introduction to some more advanced @@ -91,7 +89,7 @@ and down by pressing \i{Shift-PgUp} and \i{Shift-PgDn}. You can scroll a line at a time using \i{Ctrl-PgUp} and \i{Ctrl-PgDn}. These are still available if you configure the scrollbar to be invisible. -By default the last 200 lines scrolled off the top are +By default the last 2000 lines scrolled off the top are preserved for you to look at. You can increase (or decrease) this value using the configuration box; see \k{config-scrollback}. @@ -123,6 +121,9 @@ and hit the Copy button to copy them to the \i{clipboard}. If you are reporting a bug, it's often useful to paste the contents of the Event Log into your bug report. +(The Event Log is not the same as the facility to create a log file +of your session; that's described in \k{using-logging}.) + \S2{using-specials} \ii{Special commands} Depending on the protocol used for the current session, there may be @@ -200,6 +201,29 @@ resets associated timers and counters). For more information about repeat key exchanges, see \k{config-ssh-kex-rekey}. } +\b \I{host key cache}Cache new host key type + +\lcont{ +Only available in SSH-2. This submenu appears only if the server has +host keys of a type that PuTTY doesn't already have cached, and so +won't consider. Selecting a key here will allow PuTTY to use that key +now and in future: PuTTY will do a fresh key-exchange with the selected +key, and immediately add that key to its permanent cache (relying on +the host key used at the start of the connection to cross-certify the +new key). That key will be used for the rest of the current session; +it may not actually be used for future sessions, depending on your +preferences (see \k{config-ssh-hostkey-order}). + +Normally, PuTTY will carry on using a host key it already knows, even +if the server offers key formats that PuTTY would otherwise prefer, +to avoid host key prompts. As a result, if you've been using a server +for some years, you may still be using an older key than a new user +would use, due to server upgrades in the meantime. The SSH protocol +unfortunately does not have organised facilities for host key migration +and rollover, but this allows you to \I{host keys, upgrading}manually +upgrade. +} + \b \I{Break, SSH special command}Break \lcont{ @@ -318,8 +342,9 @@ If you find that special characters (\i{accented characters}, for example, or \i{line-drawing characters}) are not being displayed correctly in your PuTTY session, it may be that PuTTY is interpreting the characters sent by the server according to the wrong \e{character -set}. There are a lot of different character sets available, so it's -entirely possible for this to happen. +set}. There are a lot of different character sets available, and no +good way for PuTTY to know which to use, so it's entirely possible +for this to happen. If you click \q{Change Settings} and look at the \q{Translation} panel, you should see a large number of character sets which you can @@ -330,10 +355,10 @@ information.) \H{using-x-forwarding} Using \i{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. +\i{graphical 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 Cygwin/X, X-Win32, or Exceed. This will probably @@ -366,21 +391,16 @@ point at display 10 or above on the SSH server machine itself: 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 \I{X11 authentication}authentication -to connect, then PuTTY cannot currently support it. If this is a problem for -you, you should mail the PuTTY authors \#{FIXME} and give details -(see \k{feedback}). - For more options relating to X11 forwarding, see \k{config-ssh-x11}. \H{using-port-forwarding} Using \i{port forwarding} in SSH -The SSH protocol has the ability to forward arbitrary \i{network -connection}s 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 \i{POP-3} server on a remote -machine without your POP-3 password being visible to network -sniffers. +The SSH protocol has the ability to forward arbitrary \I{network +connection}network (TCP) 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 +\i{POP-3} server on a remote machine without your POP-3 password being +visible to network sniffers. In order to use port forwarding to \I{local port forwarding}connect from your local machine to a port on a remote server, you need to: @@ -427,15 +447,17 @@ number on the \e{server} (note that most servers will not allow you to use \I{privileged port}port numbers under 1024 for this purpose). An alternative way to forward local connections to remote hosts is -to use \I{dynamic port forwarding}dynamic SOCKS proxying. For -this, you will need to select the \q{Dynamic} radio button instead -of \q{Local}, and then you should not enter anything into the -\q{Destination} box (it will be ignored). This will cause PuTTY to -listen on the port you have specified, and provide a SOCKS proxy -service to any programs which connect to that port. So, in -particular, you can forward other PuTTY connections through it by -setting up the Proxy control panel (see \k{config-proxy} for -details). +to use \I{dynamic port forwarding}dynamic SOCKS proxying. In this +mode, PuTTY acts as a SOCKS server, which SOCKS-aware programs can +connect to and open forwarded connections to the destination of their +choice, so this can be an alternative to long lists of static +forwardings. To use this mode, you will need to select the \q{Dynamic} +radio button instead of \q{Local}, and then you should not enter +anything into the \q{Destination} box (it will be ignored). PuTTY will +then listen for SOCKS connections on the port you have specified. +Most \i{web browsers} can be configured to connect to this SOCKS proxy +service; also, you can forward other PuTTY connections through it by +setting up the Proxy control panel (see \k{config-proxy} for details). The source port for a forwarded connection usually does not accept connections from any machine except the \I{localhost}SSH client or @@ -565,7 +587,7 @@ 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 \i{telnet -URLs} in web browsers): +URLs} in \i{web browsers}): \c putty.exe telnet://host[:port]/ @@ -585,7 +607,9 @@ use the \c{-load} option (described in \k{using-cmdline-load}). If invoked with the \c{-cleanup} option, rather than running as normal, PuTTY will remove its \I{removing registry entries}registry entries and \i{random seed file} from the local machine (after -confirming with the user). +confirming with the user). It will also attempt to remove information +about recently launched sessions stored in the \q{jump list} on +Windows 7 and up. Note that on \i{multi-user systems}, \c{-cleanup} only removes registry entries and files associated with the currently logged-in @@ -878,9 +902,8 @@ The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1 or version \I{SSH-2}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}). +These options are equivalent to selecting the SSH protocol version in +the SSH panel of the PuTTY configuration box (see \k{config-ssh-prot}). \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an \i{Internet protocol version} @@ -899,6 +922,10 @@ The \c{-i} option allows you to specify the name of a private key file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the server. This option is only meaningful if you are using SSH. +If you are using Pageant, you can also specify a \e{public} key file +(in RFC 4716 or OpenSSH format) to identify a specific key file to use. +(This won't work if you're not running Pageant, of course.) + For general information on \i{public-key authentication}, see \k{pubkey}. @@ -909,12 +936,25 @@ authentication} box in the Auth panel of the PuTTY configuration box \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{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 \k{config-loghost} for more detail -on this. +This option overrides PuTTY's normal SSH \I{host key cache}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 +\k{config-loghost} for more detail on this. + +\S2{using-cmdline-hostkey} \i\c{-hostkey}: \I{manually configuring +host keys}manually specify an expected host key + +This option overrides PuTTY's normal SSH \I{host key cache}host key +caching policy by telling it exactly what host key to expect, which +can be useful if the normal automatic host key store in the Registry +is unavailable. The argument to this option should be either a host key +fingerprint, or an SSH-2 public key blob. See +\k{config-ssh-kex-manual-hostkeys} for more information. + +You can specify this option more than once if you want to configure +more than one key to be accepted. \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s @@ -945,3 +985,60 @@ DSR/DTR. For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of 19200, 8 data bits, no parity, 1 stop bit and no flow control. + +\S2{using-cmdline-sshlog} \i\c{-sessionlog}, \i\c{-sshlog}, +\i\c{-sshrawlog}: specify session logging + +These options cause the PuTTY network tools to write out a \i{log +file}. Each of them expects a file name as an argument, e.g. +\cq{-sshlog putty.log} causes an SSH packet log to be written to a +file called \cq{putty.log}. The three different options select +different logging modes, all available from the GUI too: + +\b \c{-sessionlog} selects \q{All session output} logging mode. + +\b \c{-sshlog} selects \q{SSH packets} logging mode. + +\b \c{-sshrawlog} selects \q{SSH packets and raw data} logging mode. + +For more information on logging configuration, see \k{config-logging}. + +\S2{using-cmdline-proxycmd} \i\c{-proxycmd}: specify a local proxy +command + +This option enables PuTTY's mode for running a \I{Local proxy}command +on the local machine and using it as a proxy for the network +connection. It expects a shell command string as an argument. + +See \k{config-proxy-type} for more information on this, and on other +proxy settings. In particular, note that since the special sequences +described there are understood in the argument string, literal +backslashes must be doubled (if you want \c{\\} in your command, you +must put \c{\\\\} on the command line). + +\S2{using-cmdline-restrict-acl} \i\c{-restrict-acl}: restrict the +\i{Windows process ACL} + +This option (on Windows only) causes PuTTY (or another PuTTY tool) to +try to lock down the operating system's access control on its own +process. If this succeeds, it should present an extra obstacle to +malware that has managed to run under the same user id as the PuTTY +process, by preventing it from attaching to PuTTY using the same +interfaces debuggers use and either reading sensitive information out +of its memory or hijacking its network session. + +This option is not enabled by default, because this form of +interaction between Windows programs has many legitimate uses, +including accessibility software such as screen readers. Also, it +cannot provide full security against this class of attack in any case, +because PuTTY can only lock down its own ACL \e{after} it has started +up, and malware could still get in if it attacks the process between +startup and lockdown. So it trades away noticeable convenience, and +delivers less real security than you might want. However, if you do +want to make that tradeoff anyway, the option is available. + +A PuTTY process started with \c{-restrict-acl} will pass that on to +any processes started with Duplicate Session, New Session etc. +(However, if you're invoking PuTTY tools explicitly, for instance as a +proxy command, you'll need to arrange to pass them the +\c{-restrict-acl} option yourself, if that's what you want.)