From 54648a161e50f6a8a6e2788763fe973d8b28aef6 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Tue, 11 Feb 2025 16:06:31 +0000 Subject: [PATCH] Docs: consistently use \- for options. (That's Halibut's non-breaking hyphen.) Triggered by noticing that the changes in 54f6fefe61 happened to come out badly in the text-only rendering, but I noticed there were many more instances in the main docs where non-breaking hyphens would help. --- doc/config.but | 8 +-- doc/errors.but | 2 +- doc/faq.but | 10 +-- doc/index.but | 98 +++++++++++++------------- doc/pageant.but | 20 +++--- doc/pgpkeys.but | 2 +- doc/plink.but | 48 ++++++------- doc/privacy.but | 2 +- doc/pscp.but | 44 ++++++------ doc/psftp.but | 54 +++++++------- doc/pubkey.but | 2 +- doc/udp.but | 2 +- doc/using.but | 182 ++++++++++++++++++++++++------------------------ 13 files changed, 237 insertions(+), 237 deletions(-) diff --git a/doc/config.but b/doc/config.but index fb836ec2..56641b5b 100644 --- a/doc/config.but +++ b/doc/config.but @@ -2006,7 +2006,7 @@ and non-SSH proxying. \b \q{SSH to proxy and use port forwarding} causes PuTTY to use the secondary SSH connection to open a port-forwarding channel to the -final destination host (similar to OpenSSH's \cw{-J} option). +final destination host (similar to OpenSSH's \cw{\-J} option). \b \q{SSH to proxy and execute a command} causes PuTTY to run an arbitrary remote command on the proxy SSH server and use that @@ -2247,7 +2247,7 @@ ability to run a shell. This feature is only available in \i{SSH protocol version 2} (since the version 1 protocol assumes you will always want to run a shell). -This feature can also be enabled using the \c{-N} command-line +This feature can also be enabled using the \c{\-N} command-line option; see \k{using-cmdline-noshell}. If you use this feature in Plink, you will not be able to terminate @@ -2639,7 +2639,7 @@ key not in that list. Another reason is if PuTTY's automated host key management is completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc) is running in a Windows environment without access to the Registry. In -that situation, you will probably want to use the \cw{-hostkey} +that situation, you will probably want to use the \cw{\-hostkey} command-line option to configure the expected host key(s); see \k{using-cmdline-hostkey}. @@ -2970,7 +2970,7 @@ by default. In rare cases you might need to turn it off in order to force authentication by some non-public-key method such as passwords. -This option can also be controlled using the \c{-noagent} +This option can also be controlled using the \c{\-noagent} command-line option. See \k{using-cmdline-agentauth}. See \k{pageant} for more information about Pageant in general. diff --git a/doc/errors.but b/doc/errors.but index ca1a53e0..85ed4bbb 100644 --- a/doc/errors.but +++ b/doc/errors.but @@ -100,7 +100,7 @@ protocol. If the server genuinely only supports SSH-1, then you need to either change the \q{SSH protocol version} setting (see \k{config-ssh-prot}), -or use the \c{-1} command-line option; in any case, you should not +or use the \c{\-1} command-line option; in any case, you should not treat the resulting connection as secure. You might start seeing this message with new versions of PuTTY (from diff --git a/doc/faq.but b/doc/faq.but index 35db12e4..dca41519 100644 --- a/doc/faq.but +++ b/doc/faq.but @@ -159,7 +159,7 @@ If you're having a specific problem with host key checking - perhaps you want an automated batch job to make use of PSCP or Plink, and the interactive host key prompt is hanging the batch process - then the right way to fix it is to add the correct host key to the Registry in -advance, or if the Registry is not available, to use the \cw{-hostkey} +advance, or if the Registry is not available, to use the \cw{\-hostkey} command-line option. That way, you retain the \e{important} feature of host key checking: the right key will be accepted and the wrong ones will not. Adding an option to turn host key checking off completely is @@ -556,7 +556,7 @@ deprecated and may be removed at some point.) \S{faq-startssh}{Question} How can I start an SSH session straight from the command line? -Use the command line \c{putty -ssh host.name}. Alternatively, create +Use the command line \c{putty \-ssh host.name}. Alternatively, create a saved session that specifies the SSH protocol, and start the saved session as shown in \k{faq-startsess}. @@ -628,7 +628,7 @@ have to use backslashes and two sets of quotes: Worse still, in a remote-to-local copy you have to specify the local file name explicitly, otherwise PSCP will complain that they don't -match (unless you specified the \c{-unsafe} option). The following +match (unless you specified the \c{\-unsafe} option). The following command will give an error message: \c c:\>pscp user@host:"\"oo er\"" . @@ -1129,7 +1129,7 @@ feature. If you are using PuTTY on a public PC, or somebody else's PC, you might want to clean this information up when you leave. You can do -that automatically, by running the command \c{putty -cleanup}. See +that automatically, by running the command \c{putty \-cleanup}. See \k{using-cleanup} in the documentation for more detail. (Note that this only removes settings for the currently logged-in user on \i{multi-user systems}.) @@ -1137,7 +1137,7 @@ this only removes settings for the currently logged-in user on If PuTTY was installed from the installer package, it will also appear in \q{Add/Remove Programs}. Current versions of the installer do not offer to remove the above-mentioned items, so if you want them -removed you should run \c{putty -cleanup} before uninstalling. +removed you should run \c{putty \-cleanup} before uninstalling. \S{faq-dsa}{Question} How come PuTTY now supports \i{DSA}, when the website used to say how insecure it was? diff --git a/doc/index.but b/doc/index.but index 9f70d7ab..226e9a34 100644 --- a/doc/index.but +++ b/doc/index.but @@ -231,37 +231,37 @@ saved sessions from \IM{QUIT special character} \cw{QUIT}, special character \IM{QUIT special character} \cw{VQUIT}, special character -\IM{-telnet} \c{-telnet} command-line option -\IM{-raw} \c{-raw} command-line option -\IM{-rlogin} \c{-rlogin} command-line option -\IM{-supdup} \c{-supdup} command-line option -\IM{-ssh} \c{-ssh} command-line option -\IM{-ssh-connection} \c{-ssh-connection} command-line option -\IM{-serial} \c{-serial} command-line option -\IM{-cleanup} \c{-cleanup} command-line option -\IM{-load} \c{-load} command-line option -\IM{-v} \c{-v} command-line option -\IM{-l} \c{-l} command-line option -\IM{-L-upper} \c{-L} command-line option -\IM{-R-upper} \c{-R} command-line option -\IM{-D-upper} \c{-D} command-line option -\IM{-m} \c{-m} command-line option -\IM{-P-upper} \c{-P} command-line option -\IM{-pw} \c{-pw} command-line option -\IM{-pwfile} \c{-pwfile} command-line option -\IM{-A-upper} \c{-A} command-line option -\IM{-a} \c{-a} command-line option -\IM{-X-upper} \c{-X} command-line option -\IM{-x} \c{-x} command-line option -\IM{-T-upper} \c{-T} command-line option -\IM{-t} \c{-t} command-line option -\IM{-C-upper} \c{-C} command-line option -\IM{-N-upper} \c{-N} command-line option -\IM{-1} \c{-1} command-line option -\IM{-2} \c{-2} command-line option -\IM{-i} \c{-i} command-line option -\IM{-pgpfp} \c{-pgpfp} command-line option -\IM{-sercfg} \c{-sercfg} command-line option +\IM{\-telnet} \c{\-telnet} command-line option +\IM{\-raw} \c{\-raw} command-line option +\IM{\-rlogin} \c{\-rlogin} command-line option +\IM{\-supdup} \c{\-supdup} command-line option +\IM{\-ssh} \c{\-ssh} command-line option +\IM{\-ssh\-connection} \c{\-ssh\-connection} command-line option +\IM{\-serial} \c{\-serial} command-line option +\IM{\-cleanup} \c{\-cleanup} command-line option +\IM{\-load} \c{\-load} command-line option +\IM{\-v} \c{\-v} command-line option +\IM{\-l} \c{\-l} command-line option +\IM{-L-upper} \c{\-L} command-line option +\IM{-R-upper} \c{\-R} command-line option +\IM{-D-upper} \c{\-D} command-line option +\IM{\-m} \c{\-m} command-line option +\IM{-P-upper} \c{\-P} command-line option +\IM{\-pw} \c{\-pw} command-line option +\IM{\-pwfile} \c{\-pwfile} command-line option +\IM{-A-upper} \c{\-A} command-line option +\IM{\-a} \c{\-a} command-line option +\IM{-X-upper} \c{\-X} command-line option +\IM{\-x} \c{\-x} command-line option +\IM{-T-upper} \c{\-T} command-line option +\IM{\-t} \c{\-t} command-line option +\IM{-C-upper} \c{\-C} command-line option +\IM{-N-upper} \c{\-N} command-line option +\IM{\-1} \c{\-1} command-line option +\IM{\-2} \c{\-2} command-line option +\IM{\-i} \c{\-i} command-line option +\IM{\-pgpfp} \c{\-pgpfp} command-line option +\IM{\-sercfg} \c{\-sercfg} command-line option \IM{\-share} \c{\-share} command-line option \IM{\-noshare} \c{\-noshare} command-line option @@ -769,22 +769,22 @@ saved sessions from \IM{SFTP} SFTP \IM{SFTP} SSH file transfer protocol -\IM{-unsafe} \c{-unsafe} PSCP command-line option -\IM{-ls-PSCP} \c{-ls} PSCP command-line option -\IM{-p-PSCP} \c{-p} PSCP command-line option -\IM{-q-PSCP} \c{-q} PSCP command-line option -\IM{-r-PSCP} \c{-r} PSCP command-line option -\IM{-batch-PSCP} \c{-batch} PSCP command-line option -\IM{-sftp} \c{-sftp} PSCP command-line option -\IM{-scp} \c{-scp} PSCP command-line option +\IM{\-unsafe} \c{\-unsafe} PSCP command-line option +\IM{-ls-PSCP} \c{\-ls} PSCP command-line option +\IM{-p-PSCP} \c{\-p} PSCP command-line option +\IM{-q-PSCP} \c{\-q} PSCP command-line option +\IM{-r-PSCP} \c{\-r} PSCP command-line option +\IM{-batch-PSCP} \c{\-batch} PSCP command-line option +\IM{\-sftp} \c{\-sftp} PSCP command-line option +\IM{\-scp} \c{\-scp} PSCP command-line option \IM{return value} return value \IM{return value} exit value -\IM{-b-PSFTP} \c{-b} PSFTP command-line option -\IM{-bc-PSFTP} \c{-bc} PSFTP command-line option -\IM{-be-PSFTP} \c{-be} PSFTP command-line option -\IM{-batch-PSFTP} \c{-batch} PSFTP command-line option +\IM{-b-PSFTP} \c{\-b} PSFTP command-line option +\IM{-bc-PSFTP} \c{\-bc} PSFTP command-line option +\IM{-be-PSFTP} \c{\-be} PSFTP command-line option +\IM{-batch-PSFTP} \c{\-batch} PSFTP command-line option \IM{spaces in filenames} spaces in filenames \IM{spaces in filenames} filenames containing spaces @@ -821,9 +821,9 @@ saved sessions from \IM{PLINK_PROTOCOL} \c{PLINK_PROTOCOL} environment variable -\IM{-batch-plink} \c{-batch} Plink command-line option -\IM{-s-plink} \c{-s} Plink command-line option -\IM{-shareexists-plink} \c{-shareexists} Plink command-line option +\IM{-batch-plink} \c{\-batch} Plink command-line option +\IM{-s-plink} \c{\-s} Plink command-line option +\IM{-shareexists-plink} \c{\-shareexists} Plink command-line option \IM{subsystem} subsystem, SSH \IM{subsystem} SSH subsystem @@ -891,9 +891,9 @@ saved sessions from \IM{authentication agent} authentication agent \IM{authentication agent} agent, authentication -\IM{-c-pageant} \c{-c} Pageant command-line option -\IM{--keylist} \c{--keylist} Pageant command-line option -\IM{--openssh-config} \c{--openssh-config} Pageant command-line option +\IM{-c-pageant} \c{\-c} Pageant command-line option +\IM{\-\-keylist} \c{\-\-keylist} Pageant command-line option +\IM{\-\-openssh\-config} \c{\-\-openssh\-config} Pageant command-line option \IM{Windows OpenSSH} Windows OpenSSH \IM{Windows OpenSSH} OpenSSH, on Windows diff --git a/doc/pageant.but b/doc/pageant.but index de6d4cb8..cf3a2955 100644 --- a/doc/pageant.but +++ b/doc/pageant.but @@ -167,7 +167,7 @@ passphrases on startup. If Pageant is already running, this syntax loads keys into the existing Pageant. -You can specify the \cq{--encrypted} option to defer decryption of +You can specify the \cq{\-\-encrypted} option to defer decryption of these keys; see \k{pageant-deferred-decryption}. \S{pageant-cmdline-command} Making Pageant run another program @@ -178,7 +178,7 @@ line. This program (perhaps a PuTTY, or a WinCVS making use of Plink, or whatever) will then be able to use the keys Pageant has loaded. -You do this by specifying the \I{-c-pageant}\c{-c} option followed +You do this by specifying the \I{-c-pageant}\c{\-c} option followed by the command, like this: \c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe @@ -197,7 +197,7 @@ configuration, then \c{ssh.exe} should automatically use Pageant as its agent, so that you can keep your keys in one place and have both SSH clients able to use them. -The option is \i\c{--openssh-config}, and you follow it with a filename. +The option is \i\c{\-\-openssh\-config}, and you follow it with a filename. To refer to this file from your main OpenSSH configuration, you can use the \cq{Include} directive. For example, you might run Pageant @@ -238,7 +238,7 @@ original Windows Subsystem for Linux (now known as WSL 1). So if you ask Pageant to listen on one of these, then your WSL 1 processes can talk directly to Pageant. -To configure this, run Pageant with the option \c{--unix}, followed +To configure this, run Pageant with the option \c{\-\-unix}, followed with a pathname. Then, in WSL 1, set the environment variable \cw{SSH_AUTH_SOCK} to point at the WSL translation of that pathname. @@ -271,18 +271,18 @@ to. \S{pageant-cmdline-keylist} Starting with the key list visible -Start Pageant with the \i\c{--keylist} option to show the main window +Start Pageant with the \i\c{\-\-keylist} option to show the main window as soon as it starts up. \S{pageant-cmdline-restrict-acl} Restricting the \i{Windows process ACL} -Pageant supports the same \i\c{-restrict-acl} option as the other +Pageant supports the same \i\c{\-restrict\-acl} option as the other PuTTY utilities to lock down the Pageant process's access control; see \k{using-cmdline-restrict-acl} for why you might want to do this. -By default, if Pageant is started with \c{-restrict-acl}, it won't +By default, if Pageant is started with \c{\-restrict\-acl}, it won't pass this to any PuTTY sessions started from its System Tray submenu. -Use \c{-restrict-putty-acl} to change this. (Again, see +Use \c{\-restrict\-putty\-acl} to change this. (Again, see \k{using-cmdline-restrict-acl} for details.) \H{pageant-forward} Using \i{agent forwarding} @@ -298,7 +298,7 @@ agent protocol, which PuTTY does not yet support. To enable agent forwarding, first start Pageant. Then set up a PuTTY SSH session in which \q{Allow agent forwarding} is enabled (see \k{config-ssh-agentfwd}). Open the session as normal. (Alternatively, -you can use the \c{-A} command line option; see +you can use the \c{\-A} command line option; see \k{using-cmdline-agent} for details.) If this has worked, your applications on the server should now have @@ -365,7 +365,7 @@ won't ask for a passphrase. Instead, the key will be listed in the main window with \q{(encrypted)} after it. To start Pageant up in the first place with encrypted keys loaded into -it, you can use the \cq{--encrypted} option on the command line. For +it, you can use the \cq{\-\-encrypted} option on the command line. For example: \c C:\PuTTY\pageant.exe --encrypted d:\main.ppk diff --git a/doc/pgpkeys.but b/doc/pgpkeys.but index 9fcd8657..4ad4986a 100644 --- a/doc/pgpkeys.but +++ b/doc/pgpkeys.but @@ -9,7 +9,7 @@ This description is provided as both a web page on the PuTTY site, and an appendix in the PuTTY manual. As of release 0.58, all of the PuTTY executables contain fingerprint -material (usually accessed via the \i\c{-pgpfp} command-line +material (usually accessed via the \i\c{\-pgpfp} command-line option), such that if you have an executable you trust, you can use it to establish a trust path, for instance to a newer version downloaded from the Internet. diff --git a/doc/plink.but b/doc/plink.but index d83d4dd0..81e4e5f1 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -35,7 +35,7 @@ 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 type -\c{plink --help} to bring up a usage message. This tells you the +\c{plink \-\-help} 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: @@ -121,8 +121,8 @@ 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{-ssh-connection}, \c{-telnet}, -\c{-rlogin}, or \c{-raw}. To make an SSH connection, for example: +command line options \c{\-ssh}, \c{\-ssh\-connection}, \c{\-telnet}, +\c{\-rlogin}, or \c{\-raw}. To make an SSH connection, for example: \c C:\>plink -ssh login.example.com \c login as: @@ -138,8 +138,8 @@ and use most of the other features of PuTTY: \c Last login: Thu Dec 6 19:25:33 2001 from :0.0 \c fred@flunky:~$ -(You can also use the \c{-load} command-line option to load a saved -session; see \k{using-cmdline-load}. If you use \c{-load}, the saved +(You can also use the \c{\-load} command-line option to load a saved +session; see \k{using-cmdline-load}. If you use \c{\-load}, the saved session exists, and it specifies a hostname, you cannot also specify a \c{host} or \c{user@host} argument - it will be treated as part of the remote command.) @@ -151,7 +151,7 @@ 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 +\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 @@ -181,8 +181,8 @@ use it; see \k{using-cmdline-hostkey}. 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 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 @@ -230,32 +230,32 @@ options. Plink also supports some of its own options. The following sections describe Plink's specific command-line options. -\S2{plink-option-batch} \I{-batch-plink}\c{-batch}: disable all +\S2{plink-option-batch} \I{-batch-plink}\c{\-batch}: disable all interactive prompts -If you use the \c{-batch} option, Plink will never give an +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 +scripts: using \c{\-batch}, if something goes wrong at connection time, the batch job will fail rather than hang. If another program is invoking Plink on your behalf, then you might -need to arrange that that program passes \c{-batch} to Plink. See +need to arrange that that program passes \c{\-batch} to Plink. See \k{plink-git} for an example involving Git. -\S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem +\S2{plink-option-s} \I{-s-plink}\c{\-s}: remote command is SSH subsystem -If you specify the \c{-s} option, Plink passes the specified command +If you specify the \c{\-s} option, Plink passes the specified command as the name of an SSH \q{\i{subsystem}} rather than an ordinary command line. (This option is only meaningful with the SSH-2 protocol.) -\S2{plink-option-shareexists} \I{-shareexists-plink}\c{-shareexists}: +\S2{plink-option-shareexists} \I{-shareexists-plink}\c{\-shareexists}: test for connection-sharing upstream This option does not make a new connection; instead it allows testing @@ -271,12 +271,12 @@ A Plink invocation of the form: will test whether there is currently a viable \q{upstream} for the session in question, which can be specified using any syntax you'd normally use with Plink to make an actual connection (a host/port -number, a bare saved session name, \c{-load}, etc). It returns a +number, a bare saved session name, \c{\-load}, etc). It returns a zero exit status if a usable \q{upstream} exists, nonzero otherwise. (This option is only meaningful with the SSH-2 protocol.) -\S2{plink-option-sanitise} \I{-sanitise-stderr}\I{-sanitise-stdout}\I{-no-sanitise-stderr}\I{-no-sanitise-stdout}\c{-sanitise-}\e{stream}: control output sanitisation +\S2{plink-option-sanitise} \I{\-sanitise\-stderr}\I{\-sanitise\-stdout}\I{\-no\-sanitise\-stderr}\I{\-no\-sanitise\-stdout}\c{\-sanitise\-}\e{stream}: control output sanitisation In some situations, Plink applies a sanitisation pass to the output received from the server, to strip out control characters such as @@ -301,26 +301,26 @@ But in case Plink guesses wrong about whether you want this sanitisation, you can override it in either direction, using one of these options: -\dt \c{-sanitise-stderr} +\dt \c{\-sanitise\-stderr} \dd Sanitise server data written to Plink's standard error channel, regardless of terminals and consoles and remote ptys. -\dt \c{-no-sanitise-stderr} +\dt \c{\-no\-sanitise\-stderr} \dd Do not sanitise server data written to Plink's standard error channel. -\dt \c{-sanitise-stdout} +\dt \c{\-sanitise\-stdout} \dd Sanitise server data written to Plink's standard output channel. -\dt \c{-no-sanitise-stdout} +\dt \c{\-no\-sanitise\-stdout} \dd Do not sanitise server data written to Plink's standard output channel. -\S2{plink-option-antispoof} \i{-no-antispoof}: turn off authentication spoofing protection prompt +\S2{plink-option-antispoof} \i{\-no\-antispoof}: turn off authentication spoofing protection prompt In SSH, some possible server authentication methods require user input (for example, password authentication, or entering a private key @@ -358,7 +358,7 @@ and so Plink omits the anti-spoofing prompt. But if you still find the protective prompt inconvenient, and you trust the server not to try a trick like this, you can turn it off -using the \cq{-no-antispoof} option. +using the \cq{\-no\-antispoof} option. \H{plink-batch} Using Plink in \i{batch files} and \i{scripts} @@ -394,7 +394,7 @@ This environment variable accepts a whole command line, not just an executable file name. So you can add Plink options to the end of it if you like. For example, if you're using Git in a batch-mode context, where your Git jobs are running unattended and nobody is available to -answer interactive prompts, you might also append the \cq{-batch} +answer interactive prompts, you might also append the \cq{\-batch} option (\k{plink-option-batch}): \c set GIT_SSH_COMMAND="C:\Program Files\PuTTY\plink.exe" -batch diff --git a/doc/privacy.but b/doc/privacy.but index 0f488bf6..fbd14fc1 100644 --- a/doc/privacy.but +++ b/doc/privacy.but @@ -19,7 +19,7 @@ computer, necessary for doing its own job. This information is stored in the user account of the user who runs PuTTY, so it is under your control: you can view it, change it, or delete it. -If you need to delete all of this data, you can use the \c{-cleanup} +If you need to delete all of this data, you can use the \c{\-cleanup} command-line option, as described in \k{using-cleanup}. PuTTY does not transmit your saved session data to any other site. diff --git a/doc/pscp.but b/doc/pscp.but index dd959121..1fb18df6 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -33,7 +33,7 @@ to include a \c{set} command like the one above. \H{pscp-usage} PSCP Usage Once you've got a console window to type into, you can type -\c{pscp -h} to bring up a usage message. This tells you the +\c{pscp \-h} to bring up a usage message. This tells you the version of PSCP you're using, and gives you a brief summary of how to use PSCP: @@ -114,7 +114,7 @@ However, in the second case (using a wildcard for multiple remote files) you may see a warning saying something like \q{warning: remote host tried to write to a file called \cq{terminal.c} when we requested a file called \cq{*.c}. If this is a wildcard, consider -upgrading to SSH-2 or using the \cq{-unsafe} option. Renaming of +upgrading to SSH-2 or using the \cq{\-unsafe} option. Renaming of this file has been disallowed}. This is due to a \I{security risk}fundamental insecurity in the old-style @@ -132,10 +132,10 @@ PSCP will attempt to use the newer \i{SFTP} protocol (part of SSH-2) where possible, which does not suffer from this security flaw. If you are talking to an SSH-2 server which supports SFTP, you will never see this warning. (You can force use of the SFTP protocol, -if available, with \c{-sftp} - see \k{pscp-usage-options-backend}.) +if available, with \c{\-sftp} - see \k{pscp-usage-options-backend}.) If you really need to use a server-side wildcard with an SSH-1 -server, you can use the \i\c{-unsafe} command line option with PSCP: +server, you can use the \i\c{\-unsafe} command line option with PSCP: \c pscp -unsafe fred@example.com:source/*.c c:\source @@ -203,9 +203,9 @@ options. (The ones not supported by PSCP are clearly marked.) PSCP also supports some of its own options. The following sections describe PSCP's specific command-line options. -\S2{pscp-usage-options-ls}\I{-ls-PSCP}\c{-ls} \I{listing files}list remote files +\S2{pscp-usage-options-ls}\I{-ls-PSCP}\c{\-ls} \I{listing files}list remote files -If the \c{-ls} option is given, no files are transferred; instead, +If the \c{\-ls} option is given, no files are transferred; instead, remote files are listed. Only a hostname specification and optional remote file specification need be given. For example: @@ -213,18 +213,18 @@ optional remote file specification need be given. For example: The SCP protocol does not contain within itself a means of listing files. If SCP is in use, this option therefore assumes that the -server responds appropriately to the command \c{ls\_-la}; +server responds appropriately to the command \c{ls\_\-la}; this may not work with all servers. If SFTP is in use, this option should work with all servers. -\S2{pscp-usage-options-p}\I{-p-PSCP}\c{-p} \i{preserve file attributes} +\S2{pscp-usage-options-p}\I{-p-PSCP}\c{\-p} \i{preserve file attributes} By default, files copied with PSCP are \i{timestamp}ed with the date and -time they were copied. The \c{-p} option preserves the original +time they were copied. The \c{\-p} option preserves the original timestamp on copied files. -\S2{pscp-usage-options-q}\I{-q-PSCP}\c{-q} quiet, don't show \i{statistics} +\S2{pscp-usage-options-q}\I{-q-PSCP}\c{\-q} quiet, don't show \i{statistics} By default, PSCP displays a meter displaying the progress of the current transfer: @@ -235,30 +235,30 @@ The fields in this display are (from left to right), filename, size (in kilobytes) of file transferred so far, estimate of how fast the file is being transferred (in kilobytes per second), estimated time that the transfer will be complete, and percentage of the file so far -transferred. The \c{-q} option to PSCP suppresses the printing of +transferred. The \c{\-q} option to PSCP suppresses the printing of these statistics. -\S2{pscp-usage-options-r}\I{-r-PSCP}\c{-r} copies directories \i{recursive}ly +\S2{pscp-usage-options-r}\I{-r-PSCP}\c{\-r} copies directories \i{recursive}ly By default, PSCP will only copy files. Any directories you specify to -copy will be skipped, as will their contents. The \c{-r} option tells +copy will be skipped, as will their contents. The \c{\-r} option tells PSCP to descend into any directories you specify, and to copy them and their contents. This allows you to use PSCP to transfer whole directory structures between machines. -\S2{pscp-usage-options-batch}\I{-batch-PSCP}\c{-batch} avoid interactive prompts +\S2{pscp-usage-options-batch}\I{-batch-PSCP}\c{\-batch} avoid interactive prompts -If you use the \c{-batch} option, PSCP will never give an +If you use the \c{\-batch} option, PSCP 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 PSCP's behaviour when it is used in automated -scripts: using \c{-batch}, if something goes wrong at connection +scripts: using \c{\-batch}, if something goes wrong at connection time, the batch job will fail rather than hang. -\S2{pscp-usage-options-backend}\i\c{-sftp}, \i\c{-scp} force use of +\S2{pscp-usage-options-backend}\i\c{\-sftp}, \i\c{\-scp} force use of particular file transfer protocol As mentioned in \k{pscp-usage-basics}, there are two different file @@ -283,15 +283,15 @@ automation, and avoids security issues with wildcard matching. Normally PSCP will attempt to use the SFTP protocol, and only fall back to the SCP protocol if SFTP is not available on the server. -The \c{-scp} option forces PSCP to use the SCP protocol or quit. +The \c{\-scp} option forces PSCP to use the SCP protocol or quit. -The \c{-sftp} option forces PSCP to use the SFTP protocol or quit. +The \c{\-sftp} option forces PSCP to use the SFTP protocol or quit. When this option is specified, PSCP looks harder for an SFTP server, which may allow use of SFTP with SSH-1 depending on server setup. -\S2{pscp-option-sanitise} \I{-sanitise-stderr}\I{-no-sanitise-stderr}\c{-no-sanitise-stderr}: control error message sanitisation +\S2{pscp-option-sanitise} \I{\-sanitise\-stderr}\I{\-no\-sanitise\-stderr}\c{\-no\-sanitise\-stderr}: control error message sanitisation -The \c{-no-sanitise-stderr} option will cause PSCP to pass through the +The \c{\-no\-sanitise\-stderr} option will cause PSCP to pass through the server's standard-error stream literally, without stripping control characters from it first. This might be useful if the server were sending coloured error messages, but it also gives the server the @@ -325,7 +325,7 @@ hostname: type \c{pscp sessionname:file localfile}, where \c{sessionname} is replaced by the name of your saved session. Secondly, you can supply the name of a private key file on the command -line, with the \c{-i} option. See \k{using-cmdline-identity} for more +line, with the \c{\-i} option. See \k{using-cmdline-identity} for more information. Thirdly, PSCP will attempt to authenticate using Pageant if Pageant diff --git a/doc/psftp.but b/doc/psftp.but index cc4bb259..623e15e8 100644 --- a/doc/psftp.but +++ b/doc/psftp.but @@ -55,14 +55,14 @@ options. (The ones not supported by PSFTP are clearly marked.) PSFTP also supports some of its own options. The following sections describe PSFTP's specific command-line options. -\S{psftp-option-b} \I{-b-PSFTP}\c{-b}: specify a file containing batch commands +\S{psftp-option-b} \I{-b-PSFTP}\c{\-b}: specify a file containing batch commands In normal operation, PSFTP is an interactive program which displays a command line and accepts commands from the keyboard. If you need to do automated tasks with PSFTP, you would probably prefer to \I{batch scripts in PSFTP}specify a set of commands in -advance and have them executed automatically. The \c{-b} option +advance and have them executed automatically. The \c{\-b} option allows you to do this. You use it with a file name containing batch commands. For example, you might create a file called \c{myscript.scr} containing lines like this: @@ -79,14 +79,14 @@ and then you could run the script by typing When you run a batch script in this way, PSFTP will abort the script if any command fails to complete successfully. To change this -behaviour, you can add the \c{-be} option (\k{psftp-option-be}). +behaviour, you can add the \c{\-be} option (\k{psftp-option-be}). PSFTP will terminate after it finishes executing the batch script. -\S{psftp-option-bc} \I{-bc-PSFTP}\c{-bc}: display batch commands as they are run +\S{psftp-option-bc} \I{-bc-PSFTP}\c{\-bc}: display batch commands as they are run -The \c{-bc} option alters what PSFTP displays while processing a -batch script specified with \c{-b}. With the \c{-bc} option, PSFTP +The \c{\-bc} option alters what PSFTP displays while processing a +batch script specified with \c{\-b}. With the \c{\-bc} option, PSFTP will display prompts and commands just as if the commands had been typed at the keyboard. So instead of seeing this: @@ -114,7 +114,7 @@ you might see this: \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn \c psftp> quit -\S{psftp-option-be} \I{-be-PSFTP}\c{-be}: continue batch processing on errors +\S{psftp-option-be} \I{-be-PSFTP}\c{\-be}: continue batch processing on errors When running a batch file, this additional option causes PSFTP to continue processing even if a command fails to complete successfully. @@ -122,22 +122,22 @@ continue processing even if a command fails to complete successfully. You might want this to happen if you wanted to delete a file and didn't care if it was already not present, for example. -\S{psftp-usage-options-batch} \I{-batch-PSFTP}\c{-batch}: avoid +\S{psftp-usage-options-batch} \I{-batch-PSFTP}\c{\-batch}: avoid interactive prompts -If you use the \c{-batch} option, PSFTP will never give an +If you use the \c{\-batch} option, PSFTP 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 PSFTP's behaviour when it is used in automated -scripts: using \c{-batch}, if something goes wrong at connection +scripts: using \c{\-batch}, if something goes wrong at connection time, the batch job will fail rather than hang. -\S2{psftp-option-sanitise} \I{-sanitise-stderr}\I{-no-sanitise-stderr}\c{-no-sanitise-stderr}: control error message sanitisation +\S2{psftp-option-sanitise} \I{\-sanitise\-stderr}\I{\-no\-sanitise\-stderr}\c{\-no\-sanitise\-stderr}: control error message sanitisation -The \c{-no-sanitise-stderr} option will cause PSFTP to pass through the +The \c{\-no\-sanitise\-stderr} option will cause PSFTP to pass through the server's standard-error stream literally, without stripping control characters from it first. This might be useful if the server were sending coloured error messages, but it also gives the server the @@ -317,16 +317,16 @@ specify the local file name after the remote one: This will fetch the file on the server called \c{myfile.dat}, but will save it to your local machine under the name \c{newname.dat}. -To fetch an entire directory \i{recursive}ly, you can use the \c{-r} +To fetch an entire directory \i{recursive}ly, you can use the \c{\-r} option: \c get -r mydir \c get -r mydir newname (If you want to fetch a file whose name starts with a hyphen, you -may have to use the \c{--} special argument, which stops \c{get} +may have to use the \c{\-\-} special argument, which stops \c{get} from interpreting anything as a switch after it. For example, -\cq{get -- -silly-name-}.) +\cq{get \-\- \-silly\-name\-}.) \S{psftp-cmd-put} The \c{put} command: send a file to the server @@ -345,16 +345,16 @@ specify the remote file name after the local one: This will send the local file called \c{myfile.dat}, but will store it on the server under the name \c{newname.dat}. -To send an entire directory \i{recursive}ly, you can use the \c{-r} +To send an entire directory \i{recursive}ly, you can use the \c{\-r} option: \c put -r mydir \c put -r mydir newname (If you want to send a file whose name starts with a hyphen, you may -have to use the \c{--} special argument, which stops \c{put} from -interpreting anything as a switch after it. For example, \cq{put -- --silly-name-}.) +have to use the \c{\-\-} special argument, which stops \c{put} from +interpreting anything as a switch after it. For example, \cq{put \-\- +\-silly\-name\-}.) \S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or send multiple files @@ -374,7 +374,7 @@ that, and a second argument will be treated as an alternative name under which to store the retrieved file), or a \i{wildcard} expression matching more than one file. -The \c{-r} and \c{--} options from \c{get} are also available with +The \c{\-r} and \c{\-\-} options from \c{get} are also available with \c{mget}. \c{mput} is similar to \c{put}, with the same differences. @@ -399,7 +399,7 @@ syntax of \c{get} and \c{put}: These commands are intended mainly for resuming interrupted transfers. They assume that the remote file or directory structure has not changed in any way; if there have been changes, you may end up with -corrupted files. In particular, the \c{-r} option will not pick up +corrupted files. In particular, the \c{\-r} option will not pick up changes to files or directories already transferred in full. \S{psftp-cmd-dir} The \c{dir} command: \I{listing files}list remote files @@ -447,7 +447,7 @@ owning user), \c{g} (members of the owning group), or \c{o} (everybody else - \q{others}), or some combination of those. It can also be \c{a} (\q{all}) to affect everybody at once. -\b A \c{+} or \c{-} sign, indicating whether permissions are to be +\b A \c{+} or \c{\-} sign, indicating whether permissions are to be added or removed. \b The actual permissions being added or removed. These can be @@ -459,7 +459,7 @@ directory). So the above examples would do: -\b The first example: \c{go-rwx} removes read, write and execute +\b The first example: \c{go\-rwx} removes read, write and execute permissions for members of the owning group and everybody else (so the only permissions left are the ones for the file owner). \c{u+w} adds write permission for the file owner. @@ -470,17 +470,17 @@ all files and directories starting with \q{public}. In addition to all this, there are a few extra special cases for \i{Unix} systems. On non-Unix systems these are unlikely to be useful: -\b You can specify \c{u+s} and \c{u-s} to add or remove the Unix +\b You can specify \c{u+s} and \c{u\-s} to add or remove the Unix \i{set-user-ID bit}. This is typically only useful for special purposes; refer to your Unix documentation if you're not sure about it. -\b You can specify \c{g+s} and \c{g-s} to add or remove the Unix +\b You can specify \c{g+s} and \c{g\-s} to add or remove the Unix \i{set-group-ID bit}. On a file, this works similarly to the set-user-ID bit (see your Unix documentation again); on a directory it ensures that files created in the directory are accessible by members of the group that owns the directory. -\b You can specify \c{+t} and \c{-t} to add or remove the Unix +\b You can specify \c{+t} and \c{\-t} to add or remove the Unix \q{\i{sticky bit}}. When applied to a directory, this means that the owner of a file in that directory can delete the file (whereas normally only the owner of the \e{directory} would be allowed to). @@ -585,7 +585,7 @@ hostname: type \c{psftp sessionname}, where \c{sessionname} is replaced by the name of your saved session. Secondly, you can supply the name of a private key file on the command -line, with the \c{-i} option. See \k{using-cmdline-identity} for more +line, with the \c{\-i} option. See \k{using-cmdline-identity} for more information. Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant diff --git a/doc/pubkey.but b/doc/pubkey.but index c421cedb..cdba9f8d 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -655,7 +655,7 @@ three ways: \b Select the private key in PuTTY's configuration. See \k{config-ssh-privkey} for details. -\b Specify the key file on the command line with the \c{-i} option. +\b Specify the key file on the command line with the \c{\-i} option. See \k{using-cmdline-identity} for details. \b Load the private key into Pageant (see \k{pageant}). In this case diff --git a/doc/udp.but b/doc/udp.but index 12b3392b..e8750396 100644 --- a/doc/udp.but +++ b/doc/udp.but @@ -51,7 +51,7 @@ The exceptions to that rule are due to the need for Visual Studio compatibility: \b Don't use variable-length arrays. Visual Studio doesn't support -them even now that it's adopted the rest of C99. We use \cw{-Wvla} +them even now that it's adopted the rest of C99. We use \cw{\-Wvla} when building with gcc and clang, to make it easier to avoid accidentally breaking that rule. diff --git a/doc/using.but b/doc/using.but index 96f5f2a7..2a49ab3f 100644 --- a/doc/using.but +++ b/doc/using.but @@ -646,7 +646,7 @@ window}, or a \i{Windows shortcut}). \S{using-cmdline-session} Starting a session from the command line -\I\c{-ssh}\I\c{-ssh-connection}\I\c{-telnet}\I\c{-rlogin}\I\c{-supdup}\I\c{-raw}\I\c{-serial}These +\I\c{\-ssh}\I\c{\-ssh\-connection}\I\c{\-telnet}\I\c{\-rlogin}\I\c{\-supdup}\I\c{\-raw}\I\c{\-serial}These options allow you to bypass the configuration window and launch straight into a session. @@ -670,20 +670,20 @@ To start a connection to a serial port, e.g. COM1: \c putty.exe -serial com1 In order to start an existing saved session called \c{sessionname}, -use the \c{-load} option (described in \k{using-cmdline-load}). +use the \c{\-load} option (described in \k{using-cmdline-load}). \c putty.exe -load "session name" -\S{using-cleanup} \i\c{-cleanup} +\S{using-cleanup} \i\c{\-cleanup} -If invoked with the \c{-cleanup} option, rather than running as +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). 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 +Note that on \i{multi-user systems}, \c{\-cleanup} only removes registry entries and files associated with the currently logged-in user. @@ -695,9 +695,9 @@ 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} \i\c{-load}: load a saved session +\S2{using-cmdline-load} \i\c{\-load}: load a saved session -\I{saved sessions, loading from command line}The \c{-load} option +\I{saved sessions, loading from command line}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. @@ -712,33 +712,33 @@ call something like (Note that PuTTY itself supports an alternative form of this option, for backwards compatibility. If you execute \i\c{putty @sessionname} -it will have the same effect as \c{putty -load "sessionname"}. With +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{-ssh-connection}, \c{-telnet}, \c{-rlogin}, \c{-supdup}, -\c{-raw}, \c{-serial} +\S2{using-cmdline-protocol} Selecting a protocol: \c{\-ssh}, +\c{\-ssh\-connection}, \c{\-telnet}, \c{\-rlogin}, \c{\-supdup}, +\c{\-raw}, \c{\-serial} To choose which protocol you want to connect with, you can use one of these options: -\b \i\c{-ssh} selects the SSH protocol. +\b \i\c{\-ssh} selects the SSH protocol. -\b \i\c{-ssh-connection} selects the bare ssh-connection protocol. +\b \i\c{\-ssh\-connection} selects the bare ssh-connection protocol. (This is only useful in specialised circumstances; see \k{config-psusan} for more information.) -\b \i\c{-telnet} selects the Telnet protocol. +\b \i\c{\-telnet} selects the Telnet protocol. -\b \i\c{-rlogin} selects the Rlogin protocol. +\b \i\c{\-rlogin} selects the Rlogin protocol. -\b \i\c{-supdup} selects the SUPDUP protocol. +\b \i\c{\-supdup} selects the SUPDUP protocol. -\b \i\c{-raw} selects the raw protocol. +\b \i\c{\-raw} selects the raw protocol. -\b \i\c{-serial} selects a serial connection. +\b \i\c{\-serial} selects a serial connection. Most of these options are not available in the file transfer tools PSCP and PSFTP (which only work with the SSH protocol and the bare @@ -748,26 +748,26 @@ These options are equivalent to the \i{protocol selection} buttons in the Session panel of the PuTTY configuration box (see \k{config-hostname}). -\S2{using-cmdline-v} \i\c{-v}: increase verbosity +\S2{using-cmdline-v} \i\c{\-v}: increase verbosity \I{verbose mode}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 +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} \i\c{-l}: specify a \i{login name} +\S2{using-cmdline-l} \i\c{\-l}: specify a \i{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 +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} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R} -and \I{-D-upper}\c{-D}: set up \i{port forwardings} +\S2{using-cmdline-portfwd} \I{-L-upper}\c{\-L}, \I{-R-upper}\c{\-R} +and \I{-D-upper}\c{\-D}: set up \i{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 @@ -782,7 +782,7 @@ can write something like one of these: \c plink mysession -L 5110:popserver.example.com:110 To forward a \I{remote port forwarding}remote port to a local -destination, just use the \c{-R} option instead of \c{-L}: +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 @@ -793,7 +793,7 @@ tunnel, prepend it to the argument: \c plink -L 127.0.0.5:23:localhost:23 myhost To set up \I{dynamic port forwarding}SOCKS-based dynamic port -forwarding on a local port, use the \c{-D} option. For this one you +forwarding on a local port, use the \c{\-D} option. For this one you only have to pass the port number: \c putty -D 4096 -load mysession @@ -804,12 +804,12 @@ For general information on port forwarding, see These options are not available in the file transfer tools PSCP and PSFTP. -\S2{using-cmdline-m} \i\c{-m}: \I{reading commands from a file}read +\S2{using-cmdline-m} \i\c{\-m}: \I{reading commands from a file}read a remote command or script from a file -The \i\c{-m} option performs a similar function to the \q{\ii{Remote +The \i\c{\-m} option performs a similar function to the \q{\ii{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 +\k{config-command}). However, the \c{\-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 @@ -822,9 +822,9 @@ routers. This option is not available in the file transfer tools PSCP and PSFTP. -\S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number} +\S2{using-cmdline-p} \I{-P-upper}\c{\-P}: specify a \i{port number} -The \c{-P} option is used to specify the port number to connect to. If +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: @@ -838,29 +838,29 @@ any case.) This option is equivalent to the port number control in the Session panel of the PuTTY configuration box (see \k{config-hostname}). -\S2{using-cmdline-pw} \i\c{-pwfile} and \i\c{-pw}: specify a \i{password} +\S2{using-cmdline-pw} \i\c{\-pwfile} and \i\c{\-pw}: specify a \i{password} A simple way to automate a remote login is to supply your password on the command line. -The \c{-pwfile} option takes a file name as an argument. The first +The \c{\-pwfile} option takes a file name as an argument. The first line of text in that file will be used as your password. -The \c{-pw} option takes the password itself as an argument. This is +The \c{\-pw} option takes the password itself as an argument. This is \s{NOT SECURE} if anybody else uses the same computer, because the whole command line (including the password) is likely to show up if -another user lists the running processes. \c{-pw} is retained for -backwards compatibility only; you should use \c{-pwfile} instead. +another user lists the running processes. \c{\-pw} is retained for +backwards compatibility only; you should use \c{\-pwfile} instead. Note that these options only work when you are using the SSH protocol. Due to fundamental limitations of Telnet, Rlogin, and SUPDUP, these protocols do not support automated password authentication. -\S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}: +\S2{using-cmdline-agentauth} \i\c{\-agent} and \i\c{\-noagent}: control use of Pageant for authentication -The \c{-agent} option turns on SSH authentication using Pageant, and -\c{-noagent} turns it off. These options are only meaningful if you +The \c{\-agent} option turns on SSH authentication using Pageant, and +\c{\-noagent} turns it off. These options are only meaningful if you are using SSH. See \k{pageant} for general information on \i{Pageant}. @@ -869,10 +869,10 @@ These options are equivalent to the agent authentication checkbox in the Auth panel of the PuTTY configuration box (see \k{config-ssh-tryagent}). -\S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent +\S2{using-cmdline-agent} \I{-A-upper}\c{\-A} and \i\c{\-a}: control \i{agent forwarding} -The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it +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 \i{Pageant}, and @@ -886,10 +886,10 @@ 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} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11 +\S2{using-cmdline-x11} \I{-X-upper}\c{\-X} and \i\c{\-x}: control \i{X11 forwarding} -The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns +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}. @@ -900,11 +900,11 @@ X11 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} \i\c{-t} and \I{-T-upper}\c{-T}: control +\S2{using-cmdline-pty} \i\c{\-t} and \I{-T-upper}\c{\-T}: control \i{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 +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 @@ -914,10 +914,10 @@ configuration box (see \k{config-ssh-pty}). These options are not available in the file transfer tools PSCP and PSFTP. -\S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a +\S2{using-cmdline-noshell} \I{-N-upper}\c{\-N}: suppress starting a \I{suppressing remote shell}shell or command -The \c{-N} option prevents PuTTY from attempting to start a shell or +The \c{\-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. @@ -932,16 +932,16 @@ at all} checkbox in the SSH panel of the PuTTY configuration box This option is not available in the file transfer tools PSCP and PSFTP. -\S2{using-cmdline-ncmode} \I{-nc}\c{-nc}: make a \i{remote network +\S2{using-cmdline-ncmode} \i\c{\-nc}: make a \i{remote network connection} in place of a remote shell or command -The \c{-nc} option prevents Plink (or PuTTY) from attempting to +The \c{\-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 \c{-nc} option, +You specify a host and port as an argument to the \c{\-nc} option, with a colon separating the host name from the port number, like this: @@ -965,41 +965,41 @@ 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, \c{-nc} uses the same server +in any tool other than Plink. Also, \c{\-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 \c{-nc} after the Unix program +(The option is named \c{\-nc} after the Unix program \W{https://en.wikipedia.org/wiki/Netcat}\c{nc}, short for \q{netcat}. The command \cq{plink host1 -nc host2:port} is very similar in functionality to \cq{plink host1 nc host2 port}, which invokes \c{nc} on the server and tells it to connect to the specified -destination. However, Plink's built-in \c{-nc} option does not +destination. However, Plink's built-in \c{\-nc} option does not depend on the \c{nc} program being installed on the server.) -\S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression} +\S2{using-cmdline-compress} \I{-C-upper}\c{\-C}: enable \i{compression} -The \c{-C} option enables compression of the data sent across the +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} \i\c{-1} and \i\c{-2}: specify an \i{SSH +\S2{using-cmdline-sshprot} \i\c{\-1} and \i\c{\-2}: specify an \i{SSH protocol version} -The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1 +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 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 +\S2{using-cmdline-ipversion} \i\c{\-4} and \i\c{\-6}: specify an \i{Internet protocol version} -The \c{-4} and \c{-6} options force PuTTY to use the older Internet +The \c{\-4} and \c{\-6} options force PuTTY to use the older Internet protocol \i{IPv4} or the newer \i{IPv6} for most outgoing connections. @@ -1007,9 +1007,9 @@ These options are equivalent to selecting your preferred Internet protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of the PuTTY configuration box (see \k{config-address-family}). -\S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key} +\S2{using-cmdline-identity} \i\c{\-i}: specify an SSH \i{private key} -The \c{-i} option allows you to specify the name of a private key +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. @@ -1024,9 +1024,9 @@ 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}). -\S2{using-cmdline-cert} \i\c{-cert}: specify an SSH \i{certificate} +\S2{using-cmdline-cert} \i\c{\-cert}: specify an SSH \i{certificate} -The \c{-cert} option allows you to specify the name of a certificate +The \c{\-cert} option allows you to specify the name of a certificate file containing a signed version of your public key. If you specify this option, PuTTY will present that certificate in place of the plain public key, whenever it tries to authenticate with a key that matches. @@ -1037,7 +1037,7 @@ This option is equivalent to the \q{Certificate to use with the private key} box in the Auth panel of the PuTTY configuration box (see \k{config-ssh-cert}). -\S2{using-cmdline-no-trivial-auth} \i\c{-no-trivial-auth}: disconnect +\S2{using-cmdline-no-trivial-auth} \i\c{\-no\-trivial\-auth}: disconnect if SSH authentication succeeds trivially This option causes PuTTY to abandon an SSH session if the server @@ -1046,7 +1046,7 @@ password or signature or token. See \k{config-ssh-notrivialauth} for why you might want this. -\S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host +\S2{using-cmdline-loghost} \i\c{\-loghost}: specify a \i{logical host name} This option overrides PuTTY's normal SSH \I{host key cache}host key @@ -1056,7 +1056,7 @@ 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 +\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 @@ -1069,13 +1069,13 @@ fingerprint, or an SSH-2 public key blob. See 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 +\S2{using-cmdline-pgpfp} \i\c{\-pgpfp}: display \i{PGP key fingerprint}s 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 \i{verifying new versions}. See \k{pgpkeys} for more information. -\S2{using-cmdline-sercfg} \i\c{-sercfg}: specify serial port +\S2{using-cmdline-sercfg} \i\c{\-sercfg}: specify serial port \i{configuration} This option specifies the configuration parameters for the serial @@ -1096,27 +1096,27 @@ follows: none, \cq{X} for XON/XOFF, \cq{R} for RTS/CTS and \cq{D} for DSR/DTR. -For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of +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}: enable session logging +\S2{using-cmdline-sshlog} \i\c{\-sessionlog}, \i\c{\-sshlog}, +\i\c{\-sshrawlog}: enable 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 +\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{\-sessionlog} selects \q{All session output} logging mode. -\b \c{-sshlog} selects \q{SSH packets} logging mode. +\b \c{\-sshlog} selects \q{SSH packets} logging mode. -\b \c{-sshrawlog} selects \q{SSH packets and raw data} 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-logfileexists} \i\c{-logoverwrite}, \i\c{-logappend}: +\S2{using-cmdline-logfileexists} \i\c{\-logoverwrite}, \i\c{\-logappend}: control behaviour with existing log file If logging has been enabled (in the saved configuration, or by another @@ -1124,7 +1124,7 @@ command-line option), and the specified log file already exists, these options tell the PuTTY network tools what to do so that they don't have to ask the user. See \k{config-logfileexists} for details. -\S2{using-cmdline-proxycmd} \i\c{-proxycmd}: specify a local proxy +\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 @@ -1157,7 +1157,7 @@ sharing (either as an upstream or a downstream). (This option is only meaningful with the SSH-2 protocol.) -\S2{using-cmdline-restrict-acl} \i\c{-restrict-acl}: restrict the +\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 @@ -1178,13 +1178,13 @@ 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 +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.) +\c{\-restrict\-acl} option yourself, if that's what you want.) -If Pageant is started with the \c{-restrict-acl} option, and you use +If Pageant is started with the \c{\-restrict\-acl} option, and you use it to launch a PuTTY session from its \ii{System Tray} submenu, then Pageant will \e{not} default to starting the PuTTY subprocess with a restricted ACL. This is because PuTTY is more likely to suffer reduced @@ -1194,18 +1194,18 @@ Pageant stores the more critical information (hence benefits more from the extra protection), so it's reasonable to want to run Pageant but not PuTTY with the ACL restrictions. You can force Pageant to start subsidiary PuTTY processes with a restricted ACL if you also pass the -\i\c{-restrict-putty-acl} option. +\i\c{\-restrict\-putty\-acl} option. -\S2{using-cmdline-host-ca} \i{\c{-host-ca}}: launch the +\S2{using-cmdline-host-ca} \i{\c{\-host\-ca}}: launch the \I{certificate}host CA configuration -If you start PuTTY with the \c{-host-ca} option, it will not launch a +If you start PuTTY with the \c{\-host\-ca} option, it will not launch a session at all. Instead, it will just display the configuration dialog box for host certification authorities, as described in \k{config-ssh-kex-cert}. When you dismiss that dialog box, PuTTY will terminate. -\S2{using-cmdline-legacy-stdio-prompts} \i{\c{-legacy-stdio-prompts}}: +\S2{using-cmdline-legacy-stdio-prompts} \i{\c{\-legacy\-stdio\-prompts}}: handle Windows console prompts like older versions of PuTTY This option applies to all of PSCP, PSFTP and Plink on Windows: all @@ -1245,15 +1245,15 @@ more awkward. However, we recognise that people may have customised complicated workflows around the old behaviour. So if you need to switch back to -it, you can do so by specifying \c{-legacy-stdio-prompts} on the +it, you can do so by specifying \c{\-legacy\-stdio\-prompts} on the command-line. To fully revert to the previous behaviour, you'd also need to specify -\c{-legacy-charset-handling} (see the next section). (Even without -that option, prompt handling with \c{-legacy-stdio-prompts} may not be +\c{\-legacy\-charset\-handling} (see the next section). (Even without +that option, prompt handling with \c{\-legacy\-stdio\-prompts} may not be fully Unicode-clean.) -\S2{using-cmdline-legacy-charset-handling} \i{\c{-legacy-charset-handling}}: +\S2{using-cmdline-legacy-charset-handling} \i{\c{\-legacy\-charset\-handling}}: handle character set in prompts like older versions of PuTTY This option applies to PuTTY (on all platforms), and also to all of @@ -1281,7 +1281,7 @@ start sending a different sequence of bytes to the server, denying you access (and you wouldn't even be able to see the difference, since the password is not shown when you type it). -\c{-legacy-charset-handling} reverts the PuTTY tools' behaviour to how +\c{\-legacy\-charset\-handling} reverts the PuTTY tools' behaviour to how it was previously: what you type at these prompts will be interpreted according to the \q{Remote character set} (for PuTTY) or Windows' default character set (for the Windows console tools).