X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/2e523aed2a4deb0a1202549d4cd869c4725a3e55..64b7adb9100eb6d5c3e61dad7eebb4e8b7b747a1:/doc/config.but diff --git a/doc/config.but b/doc/config.but index 16d15899..27704ee9 100644 --- a/doc/config.but +++ b/doc/config.but @@ -951,7 +951,7 @@ configuration PuTTY has the ability to change its character set configuration in response to commands from the server. Some programs send these -commands unexpectedly or inconveniently. In particular, \I{BitchX} (an +commands unexpectedly or inconveniently. In particular, \i{BitchX} (an IRC client) seems to have a habit of reconfiguring the character set to something other than the user intended. @@ -1240,13 +1240,17 @@ the character set understood by PuTTY. During an interactive session, PuTTY receives a stream of 8-bit bytes from the server, and in order to display them on the screen it -needs to know what character set to interpret them in. - -There are a lot of character sets to choose from. The \q{Received -data assumed to be in which character set} option lets you select -one. By default PuTTY will attempt to choose a character set that is -right for your \i{locale} as reported by Windows; if it gets it wrong, -you can select a different one using this control. +needs to know what character set to interpret them in. Similarly, +PuTTY needs to know how to translate your keystrokes into the encoding +the server expects. Unfortunately, there is no satisfactory +mechanism for PuTTY and the server to communicate this information, +so it must usually be manually configured. + +There are a lot of character sets to choose from. The \q{Remote +character set} option lets you select one. By default PuTTY will +attempt to choose a character set that is right for your \i{locale} as +reported by Windows; if it gets it wrong, you can select a different +one using this control. A few notable character sets are: @@ -1263,9 +1267,10 @@ Euro symbol. line-drawing characters, you can select \q{\i{CP437}}. \b PuTTY also supports \i{Unicode} mode, in which the data coming from -the server is interpreted as being in the \i{UTF-8} encoding of Unicode. -If you select \q{UTF-8} as a character set you can use this mode. -Not all server-side applications will support it. +the server is interpreted as being in the \i{UTF-8} encoding of Unicode, +and keystrokes are sent UTF-8 encoded. If you select \q{UTF-8} as a +character set you can use this mode. Not all server-side applications +will support it. If you need support for a numeric \i{code page} which is not listed in the drop-down list, such as code page 866, then you can try entering @@ -1716,6 +1721,54 @@ IPv6 address available, and fall back to IPv4 if not.) If you need to force PuTTY to use a particular protocol, you can explicitly set this to \q{IPv4} or \q{IPv6}. +\S{config-loghost} \I{logical host name}\q{Logical name of remote host} + +\cfg{winhelp-topic}{connection.loghost} + +This allows you to tell PuTTY that the host it will really end up +connecting to is different from where it thinks it is making a +network connection. + +You might use this, for instance, if you had set up an SSH port +forwarding in one PuTTY session so that connections to some +arbitrary port (say, \cw{localhost} port 10022) were forwarded to a +second machine's SSH port (say, \cw{foovax} port 22), and then +started a second PuTTY connecting to the forwarded port. + +In normal usage, the second PuTTY will access the host key cache +under the host name and port it actually connected to (i.e. +\cw{localhost} port 10022 in this example). Using the logical host +name option, however, you can configure the second PuTTY to cache +the host key under the name of the host \e{you} know that it's +\e{really} going to end up talking to (here \c{foovax}). + +This can be useful if you expect to connect to the same actual +server through many different channels (perhaps because your port +forwarding arrangements keep changing): by consistently setting the +logical host name, you can arrange that PuTTY will not keep asking +you to reconfirm its host key. Conversely, if you expect to use the +same local port number for port forwardings to lots of different +servers, you probably didn't want any particular server's host key +cached under that local port number. + +If you just enter a host name for this option, PuTTY will cache the +SSH host key under the default SSH port for that host, irrespective +of the port you really connected to (since the typical scenario is +like the above example: you connect to a silly real port number and +your connection ends up forwarded to the normal port-22 SSH server +of some other machine). To override this, you can append a port +number to the logical host name, separated by a colon. E.g. entering +\cq{foovax:2200} as the logical host name will cause the host key to +be cached as if you had connected to port 2200 of \c{foovax}. + +If you provide a host name using this option, it is also displayed +in other locations which contain the remote host name, such as the +default window title and the default SSH password prompt. This +reflects the fact that this is the host you're \e{really} connecting +to, which is more important than the mere means you happen to be +using to contact that host. (This applies even if you're using a +protocol other than SSH.) + \H{config-data} The Data panel The Data panel allows you to configure various pieces of data which @@ -1735,6 +1788,22 @@ it explicitly every time. (Some Telnet servers don't support this.) In this box you can type that user name. +\S{config-username-from-env} \q{Use of system username} + +\cfg{winhelp-topic}{connection.usernamefromenv} + +When the previous box (\k{config-username}) is left blank, by default, +PuTTY will prompt for a username at the time you make a connection. + +In some environments, such as large corporate networks with \i{single +sign-on}, a more sensible default may be to use the name of the user +logged in to the local operating system (if any). This control allows +you to change the default behaviour. + +The current system username is displayed in the dialog as a +convenience. It is not saved in the configuration; if a saved session +is later used by a different user, that user's name will be used. + \S{config-termtype} \q{\ii{Terminal-type} string} \cfg{winhelp-topic}{connection.termtype} @@ -2675,6 +2744,27 @@ connections fail. PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you should be sure you know what you're doing. +\S{config-ssh-xauthority} X authority file for local display + +\cfg{winhelp-topic}{ssh.tunnels.xauthority} + +If you are using X11 forwarding, the local X server to which your +forwarded connections are eventually directed may itself require +authorisation. + +Some Windows X servers do not require this: they do authorisation by +simpler means, such as accepting any connection from the local +machine but not from anywhere else. However, if your X server does +require authorisation, then PuTTY needs to know what authorisation +is required. + +One way in which this data might be made available is for the X +server to store it somewhere in a file which has the same format +as the Unix \c{.Xauthority} file. If this is how your Windows X +server works, then you can tell PuTTY where to find this file by +configuring this option. By default, PuTTY will not attempt to find +any authorisation for your local display. + \H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel \cfg{winhelp-topic}{ssh.tunnels.portfwd} @@ -2757,6 +2847,12 @@ that forwarding remain open. Similarly, changes to global settings such as \q{Local ports accept connections from other hosts} only take effect on new forwardings. +If the connection you are forwarding over SSH is itself a second SSH +connection made by another copy of PuTTY, you might find the +\q{logical host name} configuration option useful to warn PuTTY of +which host key it should be expecting. See \k{config-loghost} for +details of this. + \S{config-ssh-portfwd-localhost} Controlling the visibility of forwarded ports