DanielR78/panaceantech
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

checking in all the old panacean stuff

Browse Source
This commit is contained in:
Daniel Romischer
2016-07-25 15:42:39 -04:00
parent c996cdd81f
commit 8fd9e44ae5
1210 changed files with 220657 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
puttysrc/DOC/BLURB.BUT Normal file
View File

@@ -0,0 +1,36 @@
\define{versionidblurb} \versionid $Id: blurb.but 7048 2007-01-01 21:19:14Z jacob $
\title PuTTY User Manual
\cfg{xhtml-leaf-level}{1}
\cfg{xhtml-leaf-smallest-contents}{2}
\cfg{xhtml-leaf-contains-contents}{true}
\cfg{xhtml-body-end}{<p>If you want to provide feedback on this manual
or on the PuTTY tools themselves, see the
<a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/feedback.html">Feedback
page</a>.</p>}
\cfg{html-template-fragment}{%k}{%b}
\cfg{info-max-file-size}{0}
\cfg{xhtml-contents-filename}{index.html}
\cfg{text-filename}{puttydoc.txt}
\cfg{winhelp-filename}{putty.hlp}
\cfg{info-filename}{putty.info}
PuTTY is a free (MIT-licensed) Win32 Telnet and SSH client. This
manual documents PuTTY, and its companion utilities PSCP, PSFTP,
Plink, Pageant and PuTTYgen.
\e{Note to Unix users:} this manual currently primarily documents the
Windows versions of the PuTTY utilities. Some options are therefore
mentioned that are absent from the \i{Unix version}; the Unix version has
features not described here; and the \i\cw{pterm} and command-line
\cw{puttygen} utilities are not described at all. The only
Unix-specific documentation that currently exists is the
\I{man pages for PuTTY tools}man pages.
\copyright This manual is copyright 2001-2007 Simon Tatham. All
rights reserved. You may distribute this documentation under the MIT
licence. See \k{licence} for the licence text in full.

23
puttysrc/DOC/CHM.BUT Normal file
View File

@@ -0,0 +1,23 @@
\# File containing the magic HTML configuration directives to create
\# an MS HTML Help project. We put this on the end of the PuTTY
\# docs build command line to build the HHP and friends.
\cfg{html-leaf-level}{infinite}
\cfg{html-leaf-contains-contents}{false}
\cfg{html-suppress-navlinks}{true}
\cfg{html-suppress-address}{true}
\cfg{html-contents-filename}{index.html}
\cfg{html-template-filename}{%k.html}
\cfg{html-template-fragment}{%k}
\cfg{html-mshtmlhelp-chm}{putty.chm}
\cfg{html-mshtmlhelp-project}{putty.hhp}
\cfg{html-mshtmlhelp-contents}{putty.hhc}
\cfg{html-mshtmlhelp-index}{putty.hhk}
\cfg{html-body-end}{}
\cfg{html-head-end}{<link rel="stylesheet" type="text/css" href="chm.css">}
\versionid $Id: chm.but 7272 2007-02-11 18:13:56Z jacob $

7
puttysrc/DOC/CHM.CSS Normal file
View File

@@ -0,0 +1,7 @@
/* Stylesheet for a Windows .CHM help file */
body { font-size: 75%; font-family: Verdana, Arial, Helvetica, Sans-Serif; }
h1 { font-weight: bold; font-size: 150%; }
h2 { font-weight: bold; font-size: 130%; }
h3 { font-weight: bold; font-size: 120%; }

3097
puttysrc/DOC/CONFIG.BUT Normal file
View File

File diff suppressed because it is too large Load Diff

334
puttysrc/DOC/ERRORS.BUT Normal file
View File

@@ -0,0 +1,334 @@
\define{versioniderrors} \versionid $Id: errors.but 6461 2005-11-14 09:41:42Z jacob $
\C{errors} Common \i{error messages}
This chapter lists a number of common error messages which PuTTY and
its associated tools can produce, and explains what they mean in
more detail.
We do not attempt to list \e{all} error messages here: there are
many which should never occur, and some which should be
self-explanatory. If you get an error message which is not listed in
this chapter and which you don't understand, report it to us as a
bug (see \k{feedback}) and we will add documentation for it.
\H{errors-hostkey-absent} \q{The server's host key is not cached in
the registry}
\cfg{winhelp-topic}{errors.hostkey.absent}
This error message occurs when PuTTY connects to a new SSH server.
Every server identifies itself by means of a host key; once PuTTY
knows the host key for a server, it will be able to detect if a
malicious attacker redirects your connection to another machine.
If you see this message, it means that PuTTY has not seen this host
key before, and has no way of knowing whether it is correct or not.
You should attempt to verify the host key by other means, such as
asking the machine's administrator.
If you see this message and you know that your installation of PuTTY
\e{has} connected to the same server before, it may have been
recently upgraded to SSH protocol version 2. SSH protocols 1 and 2
use separate host keys, so when you first use \i{SSH-2} with a server
you have only used SSH-1 with before, you will see this message
again. You should verify the correctness of the key as before.
See \k{gs-hostkey} for more information on host keys.
\H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}
\cfg{winhelp-topic}{errors.hostkey.changed}
This message, followed by \q{The server's host key does not match
the one PuTTY has cached in the registry}, means that PuTTY has
connected to the SSH server before, knows what its host key
\e{should} be, but has found a different one.
This may mean that a malicious attacker has replaced your server
with a different one, or has redirected your network connection to
their own machine. On the other hand, it may simply mean that the
administrator of your server has accidentally changed the key while
upgrading the SSH software; this \e{shouldn't} happen but it is
unfortunately possible.
You should contact your server's administrator and see whether they
expect the host key to have changed. If so, verify the new host key
in the same way as you would if it was new.
See \k{gs-hostkey} for more information on host keys.
\H{errors-portfwd-space} \q{Out of space for port forwardings}
PuTTY has a fixed-size buffer which it uses to store the details of
all \i{port forwardings} you have set up in an SSH session. If you
specify too many port forwardings on the PuTTY or Plink command line
and this buffer becomes full, you will see this error message.
We need to fix this (fixed-size buffers are almost always a mistake)
but we haven't got round to it. If you actually have trouble with
this, let us know and we'll move it up our priority list.
\H{errors-cipher-warning} \q{The first cipher supported by the server is
... below the configured warning threshold}
This occurs when the SSH server does not offer any ciphers which you
have configured PuTTY to consider strong enough. By default, PuTTY
puts up this warning only for \ii{single-DES} and \i{Arcfour} encryption.
See \k{config-ssh-encryption} for more information on this message.
\H{errors-toomanyauth} \q{Server sent disconnect message type 2
(protocol error): "Too many authentication failures for root"}
This message is produced by an \i{OpenSSH} (or \i{Sun SSH}) server if it
receives more failed authentication attempts than it is willing to
tolerate.
This can easily happen if you are using Pageant and have a
large number of keys loaded into it, since these servers count each
offer of a public key as an authentication attempt. This can be worked
around by specifying the key that's required for the authentication in
the PuTTY configuration (see \k{config-ssh-privkey}); PuTTY will ignore
any other keys Pageant may have, but will ask Pageant to do the
authentication, so that you don't have to type your passphrase.
On the server, this can be worked around by disabling public-key
authentication or (for Sun SSH only) by increasing \c{MaxAuthTries} in
\c{sshd_config}.
\H{errors-memory} \q{\ii{Out of memory}}
This occurs when PuTTY tries to allocate more memory than the system
can give it. This \e{may} happen for genuine reasons: if the
computer really has run out of memory, or if you have configured an
extremely large number of lines of scrollback in your terminal.
PuTTY is not able to recover from running out of memory; it will
terminate immediately after giving this error.
However, this error can also occur when memory is not running out at
all, because PuTTY receives data in the wrong format. In SSH-2 and
also in SFTP, the server sends the length of each message before the
message itself; so PuTTY will receive the length, try to allocate
space for the message, and then receive the rest of the message. If
the length PuTTY receives is garbage, it will try to allocate a
ridiculous amount of memory, and will terminate with an \q{Out of
memory} error.
This can happen in SSH-2, if PuTTY and the server have not enabled
encryption in the same way (see \k{faq-outofmem} in the FAQ). Some
versions of \i{OpenSSH} have a known problem with this: see
\k{faq-openssh-bad-openssl}.
This can also happen in PSCP or PSFTP, if your \i{login scripts} on the
server generate output: the client program will be expecting an SFTP
message starting with a length, and if it receives some text from
your login scripts instead it will try to interpret them as a
message length. See \k{faq-outofmem2} for details of this.
\H{errors-internal} \q{\ii{Internal error}}, \q{\ii{Internal fault}},
\q{\ii{Assertion failed}}
Any error beginning with the word \q{Internal} should \e{never}
occur. If it does, there is a bug in PuTTY by definition; please see
\k{feedback} and report it to us.
Similarly, any error message starting with \q{Assertion failed} is a
bug in PuTTY. Please report it to us, and include the exact text
from the error message box.
\H{errors-cant-load-key} \q{Unable to use this private key file},
\q{Couldn't load private key}, \q{Key is of wrong type}
\cfg{winhelp-topic}{errors.cantloadkey}
Various forms of this error are printed in the PuTTY window, or
written to the PuTTY Event Log (see \k{using-eventlog}) when trying
public-key authentication, or given by Pageant when trying to load a
private key.
If you see one of these messages, it often indicates that you've tried
to load a key of an inappropriate type into PuTTY, Plink, PSCP, PSFTP,
or Pageant.
You may have specified a key that's inappropriate for the connection
you're making. The SSH-1 and SSH-2 protocols require different private
key formats, and a SSH-1 key can't be used for a SSH-2 connection (or
vice versa).
Alternatively, you may have tried to load an SSH-2 key in a \q{foreign}
format (OpenSSH or \cw{ssh.com}) directly into one of the PuTTY tools,
in which case you need to import it into PuTTY's native format
(\c{*.PPK}) using PuTTYgen - see \k{puttygen-conversions}.
\H{errors-refused} \q{Server refused our public key} or \q{Key
refused}
Various forms of this error are printed in the PuTTY window, or
written to the PuTTY Event Log (see \k{using-eventlog}) when trying
public-key authentication.
If you see one of these messages, it means that PuTTY has sent a
public key to the server and offered to authenticate with it, and
the server has refused to accept authentication. This usually means
that the server is not configured to accept this key to authenticate
this user.
This is almost certainly not a problem with PuTTY. If you see this
type of message, the first thing you should do is check your
\e{server} configuration carefully. Common errors include having
the wrong permissions or ownership set on the public key or the
user's home directory on the server. Also, read the PuTTY Event Log;
the server may have sent diagnostic messages explaining exactly what
problem it had with your setup.
\H{errors-access-denied} \q{Access denied}, \q{Authentication refused}
Various forms of this error are printed in the PuTTY window, or
written to the PuTTY Event Log (see \k{using-eventlog}) during
authentication.
If you see one of these messages, it means that the server has refused
all the forms of authentication PuTTY has tried and it has no further
ideas.
It may be worth checking the Event Log for diagnostic messages from
the server giving more detail.
This error can be caused by buggy SSH-1 servers that fail to cope with
the various strategies we use for camouflaging passwords in transit.
Upgrade your server, or use the workarounds described in
\k{config-ssh-bug-ignore1} and possibly \k{config-ssh-bug-plainpw1}.
\H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect
MAC received on packet}
This error occurs when PuTTY decrypts an SSH packet and its checksum
is not correct. This probably means something has gone wrong in the
encryption or decryption process. It's difficult to tell from this
error message whether the problem is in the client, in the server,
or in between.
A known server problem which can cause this error is described in
\k{faq-openssh-bad-openssl} in the FAQ.
\H{errors-garbled} \q{Incoming packet was garbled on decryption}
This error occurs when PuTTY decrypts an SSH packet and the
decrypted data makes no sense. This probably means something has
gone wrong in the encryption or decryption process. It's difficult
to tell from this error message whether the problem is in the client,
in the server, or in between.
If you get this error, one thing you could try would be to fiddle
with the setting of \q{Miscomputes SSH-2 encryption keys} on the Bugs
panel (see \k{config-ssh-bug-derivekey2}).
Another known server problem which can cause this error is described
in \k{faq-openssh-bad-openssl} in the FAQ.
\H{errors-x11-proxy} \q{PuTTY X11 proxy: \e{various errors}}
This family of errors are reported when PuTTY is doing X forwarding.
They are sent back to the X application running on the SSH server,
which will usually report the error to the user.
When PuTTY enables X forwarding (see \k{using-x-forwarding}) it
creates a virtual X display running on the SSH server. This display
requires authentication to connect to it (this is how PuTTY prevents
other users on your server machine from connecting through the PuTTY
proxy to your real X display). PuTTY also sends the server the
details it needs to enable clients to connect, and the server should
put this mechanism in place automatically, so your X applications
should just work.
A common reason why people see one of these messages is because they
used SSH to log in as one user (let's say \q{fred}), and then used
the Unix \c{su} command to become another user (typically \q{root}).
The original user, \q{fred}, has access to the X authentication data
provided by the SSH server, and can run X applications which are
forwarded over the SSH connection. However, the second user
(\q{root}) does not automatically have the authentication data
passed on to it, so attempting to run an X application as that user
often fails with this error.
If this happens, \e{it is not a problem with PuTTY}. You need to
arrange for your X authentication data to be passed from the user
you logged in as to the user you used \c{su} to become. How you do
this depends on your particular system; in fact many modern versions
of \c{su} do it automatically.
\H{errors-connaborted} \q{Network error: Software caused connection
abort}
This is a generic error produced by the Windows network code when it
kills an established connection for some reason. For example, it might
happen if you pull the network cable out of the back of an
Ethernet-connected computer, or if Windows has any other similar
reason to believe the entire network has become unreachable.
Windows also generates this error if it has given up on the machine
at the other end of the connection ever responding to it. If the
network between your client and server goes down and your client
then tries to send some data, Windows will make several attempts to
send the data and will then give up and kill the connection. In
particular, this can occur even if you didn't type anything, if you
are using SSH-2 and PuTTY attempts a key re-exchange. (See
\k{config-ssh-kex-rekey} for more about key re-exchange.)
(It can also occur if you are using keepalives in your connection.
Other people have reported that keepalives \e{fix} this error for
them. See \k{config-keepalive} for a discussion of the pros and cons
of keepalives.)
We are not aware of any reason why this error might occur that would
represent a bug in PuTTY. The problem is between you, your Windows
system, your network and the remote system.
\H{errors-connreset} \q{Network error: Connection reset by peer}
This error occurs when the machines at each end of a network
connection lose track of the state of the connection between them.
For example, you might see it if your SSH server crashes, and
manages to reboot fully before you next attempt to send data to it.
However, the most common reason to see this message is if you are
connecting through a \i{firewall} or a \i{NAT router} which has timed the
connection out. See \k{faq-idleout} in the FAQ for more details. You
may be able to improve the situation by using keepalives; see
\k{config-keepalive} for details on this.
Note that Windows can produce this error in some circumstances without
seeing a connection reset from the server, for instance if the
connection to the network is lost.
\H{errors-connrefused} \q{Network error: Connection refused}
This error means that the network connection PuTTY tried to make to
your server was rejected by the server. Usually this happens because
the server does not provide the service which PuTTY is trying to
access.
Check that you are connecting with the correct protocol (SSH, Telnet
or Rlogin), and check that the port number is correct. If that
fails, consult the administrator of your server.
\H{errors-conntimedout} \q{Network error: Connection timed out}
This error means that the network connection PuTTY tried to make to
your server received no response at all from the server. Usually
this happens because the server machine is completely isolated from
the network, or because it is turned off.
Check that you have correctly entered the host name or IP address of
your server machine. If that fails, consult the administrator of
your server.
\i{Unix} also generates this error when it tries to send data down a
connection and contact with the server has been completely lost
during a connection. (There is a delay of minutes before Unix gives
up on receiving a reply from the server.) This can occur if you type
things into PuTTY while the network is down, but it can also occur
if PuTTY decides of its own accord to send data: due to a repeat key
exchange in SSH-2 (see \k{config-ssh-kex-rekey}) or due to
keepalives (\k{config-keepalive}).

1430
puttysrc/DOC/FAQ.BUT Normal file
View File

File diff suppressed because it is too large Load Diff

414
puttysrc/DOC/FEEDBACK.BUT Normal file
View File

@@ -0,0 +1,414 @@
\define{versionidfeedback} \versionid $Id: feedback.but 6895 2006-11-08 21:15:30Z jacob $
\A{feedback} \ii{Feedback} and \i{bug reporting}
This is a guide to providing feedback to the PuTTY development team.
It is provided as both a web page on the PuTTY site, and an appendix
in the PuTTY manual.
\K{feedback-general} gives some general guidelines for sending any
kind of e-mail to the development team. Following sections give more
specific guidelines for particular types of e-mail, such as bug
reports and feature requests.
\H{feedback-general} General guidelines
The PuTTY development team gets a \e{lot} of mail. If you can
possibly solve your own problem by reading the manual, reading the
FAQ, reading the web site, asking a fellow user, perhaps posting to a
newsgroup (see \k{feedback-other-fora}), or some other means, then it
would make our lives much easier.
We get so much e-mail that we literally do not have time to answer
it all. We regret this, but there's nothing we can do about it. So
if you can \e{possibly} avoid sending mail to the PuTTY team, we
recommend you do so. In particular, support requests
(\k{feedback-support}) are probably better sent to newsgroups, or
passed to a local expert if possible.
The PuTTY contact email address is a private \i{mailing list} containing
four or five core developers. Don't be put off by it being a mailing
list: if you need to send confidential data as part of a bug report,
you can trust the people on the list to respect that confidence.
Also, the archives aren't publicly available, so you shouldn't be
letting yourself in for any spam by sending us mail.
Please use a meaningful subject line on your message. We get a lot of
mail, and it's hard to find the message we're looking for if they all
have subject lines like \q{PuTTY bug}.
\S{feedback-largefiles} Sending large attachments
Since the PuTTY contact address is a mailing list, e-mails larger
than 40Kb will be held for inspection by the list administrator, and
will not be allowed through unless they really appear to be worth
their large size.
If you are considering sending any kind of large data file to the
PuTTY team, it's almost always a bad idea, or at the very least it
would be better to ask us first whether we actually need the file.
Alternatively, you could put the file on a web site and just send us
the URL; that way, we don't have to download it unless we decide we
actually need it, and only one of us needs to download it instead of
it being automatically copied to all the developers.
Some people like to send mail in MS Word format. Please \e{don't}
send us bug reports, or any other mail, as a Word document. Word
documents are roughly fifty times larger than writing the same
report in plain text. In addition, most of the PuTTY team read their
e-mail on Unix machines, so copying the file to a Windows box to run
Word is very inconvenient. Not only that, but several of us don't
even \e{have} a copy of Word!
Some people like to send us screen shots when demonstrating a
problem. Please don't do this without checking with us first - we
almost never actually need the information in the screen shot.
Sending a screen shot of an error box is almost certainly
unnecessary when you could just tell us in plain text what the error
was. (On some versions of Windows, pressing Ctrl-C when the error
box is displayed will copy the text of the message to the clipboard.)
Sending a full-screen shot is \e{occasionally} useful, but it's
probably still wise to check whether we need it before sending it.
If you \e{must} mail a screen shot, don't send it as a \cw{.BMP}
file. \cw{BMP}s have no compression and they are \e{much} larger
than other image formats such as PNG, TIFF and GIF. Convert the file
to a properly compressed image format before sending it.
Please don't mail us executables, at all. Our mail server blocks all
incoming e-mail containing executables, as a defence against the
vast numbers of e-mail viruses we receive every day. If you mail us
an executable, it will just bounce.
If you have made a tiny modification to the PuTTY code, please send
us a \e{patch} to the source code if possible, rather than sending
us a huge \cw{.ZIP} file containing the complete sources plus your
modification. If you've only changed 10 lines, we'd prefer to
receive a mail that's 30 lines long than one containing multiple
megabytes of data we already have.
\S{feedback-other-fora} Other places to ask for help
There are two Usenet newsgroups that are particularly relevant to the
PuTTY tools:
\b \W{news:comp.security.ssh}\c{comp.security.ssh}, for questions
specific to using the SSH protocol;
\b \W{news:comp.terminals}\c{comp.terminals}, for issues relating to
terminal emulation (for instance, keyboard problems).
Please use the newsgroup most appropriate to your query, and remember
that these are general newsgroups, not specifically about PuTTY.
If you don't have direct access to Usenet, you can access these
newsgroups through Google Groups
(\W{http://groups.google.com/}\cw{groups.google.com}).
\H{feedback-bugs} Reporting bugs
If you think you have found a bug in PuTTY, your first steps should
be:
\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist
page} on the PuTTY website, and see if we already know about the
problem. If we do, it is almost certainly not necessary to mail us
about it, unless you think you have extra information that might be
helpful to us in fixing it. (Of course, if we actually \e{need}
specific extra information about a particular bug, the Wishlist page
will say so.)
\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change
Log} on the PuTTY website, and see if we have already fixed the bug
in the \i{development snapshots}.
\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html}{FAQ}
on the PuTTY website (also provided as \k{faq} in the manual), and
see if it answers your question. The FAQ lists the most common
things which people think are bugs, but which aren't bugs.
\b Download the latest development snapshot and see if the problem
still happens with that. This really is worth doing. As a general
rule we aren't very interested in bugs that appear in the release
version but not in the development version, because that usually
means they are bugs we have \e{already fixed}. On the other hand, if
you can find a bug in the development version that doesn't appear in
the release, that's likely to be a new bug we've introduced since
the release and we're definitely interested in it.
If none of those options solved your problem, and you still need to
report a bug to us, it is useful if you include some general
information:
\b Tell us what \i{version of PuTTY} you are running. To find this out,
use the \q{About PuTTY} option from the System menu. Please \e{do
not} just tell us \q{I'm running the latest version}; e-mail can be
delayed and it may not be obvious which version was the latest at
the time you sent the message.
\b PuTTY is a multi-platform application; tell us what version of what
OS you are running PuTTY on. (If you're running on Unix, or Windows
for Alpha, tell us, or we'll assume you're running on Windows for
Intel as this is overwhelmingly the case.)
\b Tell us what protocol you are connecting with: SSH, Telnet,
Rlogin or Raw mode.
\b Tell us what kind of server you are connecting to; what OS, and
if possible what SSH server (if you're using SSH). You can get some
of this information from the PuTTY Event Log (see \k{using-eventlog}
in the manual).
\b Send us the contents of the PuTTY Event Log, unless you
have a specific reason not to (for example, if it contains
confidential information that you think we should be able to solve
your problem without needing to know).
\b Try to give us as much information as you can to help us
see the problem for ourselves. If possible, give us a step-by-step
sequence of \e{precise} instructions for reproducing the fault.
\b Don't just tell us that PuTTY \q{does the wrong thing}; tell us
exactly and precisely what it did, and also tell us exactly and
precisely what you think it should have done instead. Some people
tell us PuTTY does the wrong thing, and it turns out that it was
doing the right thing and their expectations were wrong. Help to
avoid this problem by telling us exactly what you think it should
have done, and exactly what it did do.
\b If you think you can, you're welcome to try to fix the problem
yourself. A \i{patch} to the code which fixes a bug is an excellent
addition to a bug report. However, a patch is never a \e{substitute}
for a good bug report; if your patch is wrong or inappropriate, and
you haven't supplied us with full information about the actual bug,
then we won't be able to find a better solution.
\b
\W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}
is an article on how to report bugs effectively in general. If your
bug report is \e{particularly} unclear, we may ask you to go away,
read this article, and then report the bug again.
It is reasonable to report bugs in PuTTY's documentation, if you
think the documentation is unclear or unhelpful. But we do need to
be given exact details of \e{what} you think the documentation has
failed to tell you, or \e{how} you think it could be made clearer.
If your problem is simply that you don't \e{understand} the
documentation, we suggest posting to a newsgroup (see
\k{feedback-other-fora}) and seeing if someone
will explain what you need to know. \e{Then}, if you think the
documentation could usefully have told you that, send us a bug
report and explain how you think we should change it.
\H{feedback-features} Requesting extra features
If you want to request a new feature in PuTTY, the very first things
you should do are:
\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist
page} on the PuTTY website, and see if your feature is already on
the list. If it is, it probably won't achieve very much to repeat
the request. (But see \k{feedback-feature-priority} if you want to
persuade us to give your particular feature higher priority.)
\b Check the Wishlist and
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change
Log} on the PuTTY website, and see if we have already added your
feature in the development snapshots. If it isn't clear, download
the latest development snapshot and see if the feature is present.
If it is, then it will also be in the next release and there is no
need to mail us at all.
If you can't find your feature in either the development snapshots
\e{or} the Wishlist, then you probably do need to submit a feature
request. Since the PuTTY authors are very busy, it helps if you try
to do some of the work for us:
\b Do as much of the design as you can. Think about \q{corner
cases}; think about how your feature interacts with other existing
features. Think about the user interface; if you can't come up with
a simple and intuitive interface to your feature, you shouldn't be
surprised if we can't either. Always imagine whether it's possible
for there to be more than one, or less than one, of something you'd
assumed there would be one of. (For example, if you were to want
PuTTY to put an icon in the System tray rather than the Taskbar, you
should think about what happens if there's more than one PuTTY
active; how would the user tell which was which?)
\b If you can program, it may be worth offering to write the feature
yourself and send us a patch. However, it is likely to be helpful
if you confer with us first; there may be design issues you haven't
thought of, or we may be about to make big changes to the code which
your patch would clash with, or something. If you check with the
maintainers first, there is a better chance of your code actually
being usable. Also, read the design principles listed in \k{udp}: if
you do not conform to them, we will probably not be able to accept
your patch.
\H{feedback-feature-priority} Requesting features that have already
been requested
If a feature is already listed on the Wishlist, then it usually
means we would like to add it to PuTTY at some point. However, this
may not be in the near future. If there's a feature on the Wishlist
which you would like to see in the \e{near} future, there are
several things you can do to try to increase its priority level:
\b Mail us and vote for it. (Be sure to mention that you've seen it
on the Wishlist, or we might think you haven't even \e{read} the
Wishlist). This probably won't have very \e{much} effect; if a huge
number of people vote for something then it may make a difference,
but one or two extra votes for a particular feature are unlikely to
change our priority list immediately. Offering a new and compelling
justification might help. Also, don't expect a reply.
\b Offer us money if we do the work sooner rather than later. This
sometimes works, but not always. The PuTTY team all have full-time
jobs and we're doing all of this work in our free time; we may
sometimes be willing to give up some more of our free time in
exchange for some money, but if you try to bribe us for a \e{big}
feature it's entirely possible that we simply won't have the time to
spare - whether you pay us or not. (Also, we don't accept bribes to
add \e{bad} features to the Wishlist, because our desire to provide
high-quality software to the users comes first.)
\b Offer to help us write the code. This is probably the \e{only}
way to get a feature implemented quickly, if it's a big one that we
don't have time to do ourselves.
\H{feedback-support} \ii{Support requests}
If you're trying to make PuTTY do something for you and it isn't
working, but you're not sure whether it's a bug or not, then
\e{please} consider looking for help somewhere else. This is one of
the most common types of mail the PuTTY team receives, and we simply
don't have time to answer all the questions. Questions of this type
include:
\b If you want to do something with PuTTY but have no idea where to
start, and reading the manual hasn't helped, try posting to a
newsgroup (see \k{feedback-other-fora}) and see if someone can explain
it to you.
\b If you have tried to do something with PuTTY but it hasn't
worked, and you aren't sure whether it's a bug in PuTTY or a bug in
your SSH server or simply that you're not doing it right, then try
posting to a newsgroup (see \k{feedback-other-fora}) and see
if someone can solve your problem. Or try doing the same thing with
a different SSH client and see if it works with that. Please do not
report it as a PuTTY bug unless you are really sure it \e{is} a bug
in PuTTY.
\b If someone else installed PuTTY for you, or you're using PuTTY on
someone else's computer, try asking them for help first. They're more
likely to understand how they installed it and what they expected you
to use it for than we are.
\b If you have successfully made a connection to your server and now
need to know what to type at the server's command prompt, or other
details of how to use the server-end software, talk to your server's
system administrator. This is not the PuTTY team's problem. PuTTY is
only a communications tool, like a telephone; if you can't speak the
same language as the person at the other end of the phone, it isn't
the telephone company's job to teach it to you.
If you absolutely cannot get a support question answered any other
way, you can try mailing it to us, but we can't guarantee to have
time to answer it.
\H{feedback-webadmin} Web server administration
If the PuTTY \i{web site} is down (Connection Timed Out), please don't
bother mailing us to tell us about it. Most of us read our e-mail on
the same machines that host the web site, so if those machines are
down then we will notice \e{before} we read our e-mail. So there's
no point telling us our servers are down.
Of course, if the web site has some other error (Connection Refused,
404 Not Found, 403 Forbidden, or something else) then we might
\e{not} have noticed and it might still be worth telling us about it.
If you want to report a problem with our web site, check that you're
looking at our \e{real} web site and not a mirror. The real web site
is at
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\c{http://www.chiark.greenend.org.uk/~sgtatham/putty/};
if that's not where you're reading this, then don't report the
problem to us until you've checked that it's really a problem with
the main site. If it's only a problem with the mirror, you should
try to contact the administrator of that mirror site first, and only
contact us if that doesn't solve the problem (in case we need to
remove the mirror from our list).
\H{feedback-permission} Asking permission for things
PuTTY is distributed under the MIT Licence (see \k{licence} for
details). This means you can do almost \e{anything} you like with
our software, our source code, and our documentation. The only
things you aren't allowed to do are to remove our copyright notices
or the licence text itself, or to hold us legally responsible if
something goes wrong.
So if you want permission to include PuTTY on a magazine cover disk,
or as part of a collection of useful software on a CD or a web site,
then \e{permission is already granted}. You don't have to mail us
and ask. Just go ahead and do it. We don't mind.
(If you want to distribute PuTTY alongside your own application for
use with that application, or if you want to distribute PuTTY within
your own organisation, then we recommend, but do not insist, that
you offer your own first-line technical support, to answer questions
about the interaction of PuTTY with your environment. If your users
mail us directly, we won't be able to tell them anything useful about
your specific setup.)
If you want to use parts of the PuTTY source code in another
program, then it might be worth mailing us to talk about technical
details, but if all you want is to ask permission then you don't
need to bother. You already have permission.
If you just want to link to our web site, just go ahead. (It's not
clear that we \e{could} stop you doing this, even if we wanted to!)
\H{feedback-mirrors} Mirroring the PuTTY web site
\#{This paragraph also in putty-website/mirrors.html}
Mirrors of the PuTTY web site are welcome, especially in regions not
well covered by existing mirrors. (However, if you're in a region that is
already well served by mirrors, you should consider whether yet another one
will be worth the effort.) Please don't bother asking us for permission before
setting up a mirror. You already have permission.
If you mail us \e{after} you have set up the mirror and checked that
it works, and remember to let us know which country your mirror is in,
then we'll add it to the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{Mirrors
page} on the PuTTY website.
If you have technical questions about the process of mirroring, then
you might want to mail us before setting up the mirror (see also the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html#guidelines}{guidelines on the Mirrors page});
but if you just want to ask for permission, you don't need to. You
already have permission.
\H{feedback-compliments} Praise and compliments
One of the most rewarding things about maintaining free software is
getting e-mails that just say \q{thanks}. We are always happy to
receive e-mails of this type.
Regrettably we don't have time to answer them all in person. If you
mail us a compliment and don't receive a reply, \e{please} don't
think we've ignored you. We did receive it and we were happy about
it; we just didn't have time to tell you so personally.
To everyone who's ever sent us praise and compliments, in the past
and the future: \e{you're welcome}!
\H{feedback-address} E-mail address
The actual address to mail is
\cw{<\W{mailto:putty@projects.tartarus.org}{putty@projects.tartarus.org}>}.

155
puttysrc/DOC/GS.BUT Normal file
View File

@@ -0,0 +1,155 @@
\define{versionidgs} \versionid $Id: gs.but 6815 2006-08-28 10:35:12Z simon $
\C{gs} Getting started with PuTTY
This chapter gives a quick guide to the simplest types of
interactive login session using PuTTY.
\H{gs-insecure} \ii{Starting a session}
When you start PuTTY, you will see a \i{dialog box}. This dialog box
allows you to control everything PuTTY can do. See \k{config} for
details of all the things you can control.
You don't usually need to change most of the configuration options.
To start the simplest kind of session, all you need to do is to
enter a few basic parameters.
In the \q{Host Name} box, enter the Internet \i{host name} of the server
you want to connect to. You should have been told this by the
provider of your login account.
Now select a login \i{protocol} to use, from the \q{Connection type}
buttons. For a login session, you should select \i{Telnet},
\i{Rlogin} or \i{SSH}. See \k{which-one} for a description of the
differences between the three protocols, and advice on which one to
use. The fourth protocol, \I{raw protocol}\e{Raw}, is not used for
interactive login sessions; you would usually use this for debugging
other Internet services (see \k{using-rawprot}). The fifth option,
\e{Serial}, is used for connecting to a local serial line, and works
somewhat differently: see \k{using-serial} for more information on
this.
When you change the selected protocol, the number in the \q{Port}
box will change. This is normal: it happens because the various
login services are usually provided on different network ports by
the server machine. Most servers will use the standard port numbers,
so you will not need to change the port setting. If your server
provides login services on a non-standard port, your system
administrator should have told you which one. (For example, many
\i{MUDs} run Telnet service on a port other than 23.)
Once you have filled in the \q{Host Name}, \q{Protocol}, and
possibly \q{Port} settings, you are ready to connect. Press the
\q{Open} button at the bottom of the dialog box, and PuTTY will
begin trying to connect you to the server.
\H{gs-hostkey} \ii{Verifying the host key} (SSH only)
If you are not using the \i{SSH} protocol, you can skip this
section.
If you are using SSH to connect to a server for the first time, you
will probably see a message looking something like this:
\c The server's host key is not cached in the registry. You
\c have no guarantee that the server is the computer you
\c think it is.
\c The server's rsa2 key fingerprint is:
\c ssh-rsa 1024 7b:e5:6f:a7:f4:f9:81:62:5c:e3:1f:bf:8b:57:6c:5a
\c If you trust this host, hit Yes to add the key to
\c PuTTY's cache and carry on connecting.
\c If you want to carry on connecting just once, without
\c adding the key to the cache, hit No.
\c If you do not trust this host, hit Cancel to abandon the
\c connection.
This is a feature of the SSH protocol. It is designed to protect you
against a network attack known as \i\e{spoofing}: secretly
redirecting your connection to a different computer, so that you
send your password to the wrong machine. Using this technique, an
attacker would be able to learn the password that guards your login
account, and could then log in as if they were you and use the
account for their own purposes.
To prevent this attack, each server has a unique identifying code,
called a \e{host key}. These keys are created in a way that prevents
one server from forging another server's key. So if you connect to a
server and it sends you a different host key from the one you were
expecting, PuTTY can warn you that the server may have been switched
and that a spoofing attack might be in progress.
PuTTY records the host key for each server you connect to, in the
Windows \i{Registry}. Every time you connect to a server, it checks
that the host key presented by the server is the same host key as it
was the last time you connected. If it is not, you will see a
warning, and you will have the chance to abandon your connection
before you type any private information (such as a password) into
it.
However, when you connect to a server you have not connected to
before, PuTTY has no way of telling whether the host key is the
right one or not. So it gives the warning shown above, and asks you
whether you want to \I{trusting host keys}trust this host key or
not.
Whether or not to trust the host key is your choice. If you are
connecting within a company network, you might feel that all the
network users are on the same side and spoofing attacks are
unlikely, so you might choose to trust the key without checking it.
If you are connecting across a hostile network (such as the
Internet), you should check with your system administrator, perhaps
by telephone or in person. (Some modern servers have more than one
host key. If the system administrator sends you more than one
\I{host key fingerprint}fingerprint, you should make sure the one
PuTTY shows you is on the list, but it doesn't matter which one it is.)
\# FIXME: this is all very fine but of course in practice the world
doesn't work that way. Ask the team if they have any good ideas for
changes to this section!
\H{gs-login} \ii{Logging in}
After you have connected, and perhaps verified the server's host
key, you will be asked to log in, probably using a \i{username} and
a \i{password}. Your system administrator should have provided you
with these. Enter the username and the password, and the server
should grant you access and begin your session. If you have
\I{mistyping a password}mistyped your password, most servers will
give you several chances to get it right.
If you are using SSH, be careful not to type your username wrongly,
because you will not have a chance to correct it after you press
Return; many SSH servers do not permit you to make two login attempts
using \i{different usernames}. If you type your username wrongly, you
must close PuTTY and start again.
If your password is refused but you are sure you have typed it
correctly, check that Caps Lock is not enabled. Many login servers,
particularly Unix computers, treat upper case and lower case as
different when checking your password; so if Caps Lock is on, your
password will probably be refused.
\H{gs-session} After logging in
After you log in to the server, what happens next is up to the
server! Most servers will print some sort of login message and then
present a \i{prompt}, at which you can type
\I{commands on the server}commands which the
server will carry out. Some servers will offer you on-line help;
others might not. If you are in doubt about what to do next, consult
your system administrator.
\H{gs-logout} \ii{Logging out}
When you have finished your session, you should log out by typing
the server's own logout command. This might vary between servers; if
in doubt, try \c{logout} or \c{exit}, or consult a manual or your
system administrator. When the server processes your logout command,
the PuTTY window should close itself automatically.
You \e{can} close a PuTTY session using the \i{Close button} in the
window border, but this might confuse the server - a bit like
hanging up a telephone unexpectedly in the middle of a conversation.
We recommend you do not do this unless the server has stopped
responding to you and you cannot close the window any other way.

839
puttysrc/DOC/INDEX.BUT Normal file
View File

@@ -0,0 +1,839 @@
\define{versionidindex} \versionid $Id: index.but 6836 2006-08-29 21:46:56Z jacob $
\IM{Unix version} Unix version of PuTTY tools
\IM{Unix version} Linux version of PuTTY tools
\IM{Unix} Unix
\IM{Unix} Linux
\IM{Command Prompt}{command prompt window}{MS-DOS Prompt}{console window} Command Prompt
\IM{Command Prompt}{command prompt window}{MS-DOS Prompt}{console window} MS-DOS Prompt
\IM{Command Prompt}{command prompt window}{MS-DOS Prompt}{console window} console window
\IM{spoof}{spoofed}{spoofing} spoofing
\IM{verifying the host key} verifying the host key
\IM{verifying the host key} host key, verifying
\IM{trusting host keys} trusting host keys
\IM{trusting host keys} host keys, trusting
\IM{host key fingerprint} fingerprint, of SSH host key
\IM{host key fingerprint} host key fingerprint (SSH)
\IM{host key fingerprint} SSH host key fingerprint
\IM{starting a session} starting a session
\IM{starting a session} session, starting
\IM{commands on the server}{remote command} commands on the server
\IM{commands on the server}{remote command} remote commands
\IM{commands on the server}{remote command} server, commands on
\IM{mistyping a password} mistyping a password
\IM{mistyping a password} password, mistyping
\IM{different usernames}{changes of username} different user names
\IM{different usernames}{changes of username} changing user names
\IM{different usernames}{changes of username} user names, different
\IM{different usernames}{changes of username} login names, different
\IM{different usernames}{changes of username} account names, different
\IM{differences between SSH, Telnet and Rlogin} differences between
SSH, Telnet and Rlogin
\IM{differences between SSH, Telnet and Rlogin} protocols,
differences between
\IM{differences between SSH, Telnet and Rlogin} SSH, differences
from Telnet and Rlogin
\IM{differences between SSH, Telnet and Rlogin} Telnet, differences
from SSH and Rlogin
\IM{differences between SSH, Telnet and Rlogin} Rlogin, differences
from SSH and Telnet
\IM{differences between SSH, Telnet and Rlogin} selecting a protocol
\IM{differences between SSH, Telnet and Rlogin} choosing a protocol
\IM{MUD}{MUDs} MUDs
\IM{talker}{talker systems} talker systems
\IM{security hazard}{security risk} security hazard
\IM{SSH-1}{SSH protocol version 1} SSH-1
\IM{SSH-2}{SSH protocol version 2} SSH-2
\IM{terminal window}{PuTTY window} terminal window
\IM{terminal window}{PuTTY window} PuTTY terminal window
\IM{terminal window}{PuTTY window} window, terminal
\IM{copy and paste} copy and paste
\IM{copy and paste} cut and paste
\IM{copy and paste} paste, copy and
\IM{three-button mouse} three-button mouse
\IM{three-button mouse} mouse, three-button
\IM{left mouse button}{left button} left mouse button
\IM{middle mouse button}{middle button} middle mouse button
\IM{right mouse button}{right button} right mouse button
\IM{selecting words}{word-by-word selection} selecting whole words
\IM{selecting words}{word-by-word selection} words, selecting
\IM{selecting lines} selecting whole lines
\IM{selecting lines} lines, selecting
\IM{rectangular selection} rectangular selection
\IM{rectangular selection} selection, rectangular
\IM{adjusting a selection} adjusting a selection
\IM{adjusting a selection} extending a selection
\IM{adjusting a selection} selection, adjusting
\IM{right mouse button, with Ctrl} right mouse button, with Ctrl
\IM{right mouse button, with Ctrl} Ctrl, with right mouse button
\IM{system menu} system menu
\IM{system menu} menu, system
\IM{system menu} window menu
\IM{context menu} context menu
\IM{context menu} menu, context
\IM{context menu} right mouse button menu
\IM{Event Log} Event Log
\IM{Event Log} PuTTY Event Log
\IM{Event Log} Log, Event
\IM{Telnet special commands} Telnet special commands
\IM{Telnet special commands} special commands, in Telnet
\IM{SSH special commands} SSH special commands
\IM{SSH special commands} special commands, in SSH
\IM{Repeat key exchange, SSH special command} Repeat key exchange, SSH special command
\IM{Repeat key exchange, SSH special command} key exchange, forcing repeat
\IM{Repeat key exchange, SSH special command} SSH key exchange, forcing repeat
\IM{accented characters} accented characters
\IM{accented characters} characters, accented
\IM{line-drawing characters} line-drawing characters
\IM{line-drawing characters} box-drawing characters
\IM{line-drawing characters} characters, line-drawing
\IM{line-drawing characters} ANSI graphics
\IM{port forwarding}{port forwardings} port forwarding in SSH
\IM{port forwarding}{port forwardings} SSH port forwarding
\IM{port forwarding}{port forwardings} forwarding ports in SSH
\IM{port forwarding}{port forwardings} tunnelling using SSH
\IM{port forwarding}{port forwardings} SSH tunnelling
\IM{port forwarding, changing mid-session} port forwarding in SSH, changing mid-session
\IM{port forwarding, changing mid-session} SSH port forwarding, changing mid-session
\IM{port forwarding, changing mid-session} forwarding ports in SSH, changing mid-session
\IM{port forwarding, changing mid-session} tunnelling using SSH, changing mid-session
\IM{port forwarding, changing mid-session} SSH tunnelling, changing mid-session
\IM{local port forwarding} local-to-remote port forwarding
\IM{remote port forwarding} remote-to-local port forwarding
\IM{dynamic port forwarding} dynamic port forwarding
\IM{dynamic port forwarding} SOCKS port forwarding
\IM{debugging Internet protocols} debugging Internet protocols
\IM{debugging Internet protocols} Internet protocols, debugging
\IM{debugging Internet protocols} protocols, debugging
\IM{Internet protocol version} Internet Protocol version
\IM{Internet protocol version} version, of Internet Protocol
\IM{raw TCP connections} raw TCP connections
\IM{raw TCP connections} TCP connections, raw
\IM{command-line arguments} command-line arguments
\IM{command-line arguments} arguments, command-line
\IM{command-line arguments} options, command-line
\IM{command-line arguments} switches, command-line
\IM{Windows shortcut} Windows shortcut
\IM{Windows shortcut} shortcut, Windows
\IM{telnet URLs} Telnet URLs
\IM{telnet URLs} URLs, Telnet
\IM{saved sessions, loading from command line} saved sessions,
loading from command line
\IM{saved sessions, loading from command line} loading saved
sessions from command line
\IM{saved sessions, loading from command line} command line, loading
saved sessions from
\IM{putty @sessionname} \c{putty @sessionname}
\IM{putty @sessionname} \c{@sessionname} command-line argument
\IM{protocol selection} protocol selection
\IM{protocol selection} selecting a protocol
\IM{protocol selection} choosing a protocol
\IM{login name}{username} login name
\IM{login name}{username} user name
\IM{login name}{username} account name
\IM{reading commands from a file} reading commands from a file
\IM{reading commands from a file} commands, reading from a file
\IM{agent forwarding} agent forwarding
\IM{agent forwarding} authentication agent forwarding
\IM{agent forwarding} SSH agent forwarding
\IM{agent forwarding} forwarding, SSH agent
\IM{X11 forwarding}{forwarding of X11} X11 forwarding
\IM{X11 forwarding}{forwarding of X11} SSH X11 forwarding
\IM{X11 forwarding}{forwarding of X11} forwarding, of X11
\IM{X11 authentication} X11 authentication
\IM{X11 authentication} authentication, X11
\IM{pseudo-terminal allocation} pseudo-terminal allocation
\IM{pseudo-terminal allocation} pty allocation
\IM{pseudo-terminal allocation} allocation, of pseudo-terminal
\IM{ERASE special character} \cw{ERASE}, special character
\IM{ERASE special character} \cw{VERASE}, special character
\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{-ssh} \c{-ssh} 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{-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{removing registry entries} removing registry entries
\IM{removing registry entries} registry entries, removing
\IM{random seed file} random seed file
\IM{random seed file} \c{putty.rnd} (random seed file)
\IM{putty.rnd} \c{putty.rnd} (random seed file)
\IM{suppressing remote shell} remote shell, suppressing
\IM{suppressing remote shell} shell, remote, suppressing
\IM{SSH protocol version} SSH protocol version
\IM{SSH protocol version} protocol version, SSH
\IM{SSH protocol version} version, of SSH protocol
\IM{PPK} \cw{PPK} file
\IM{PPK} private key file, PuTTY
\IM{PGP key fingerprint} PGP key fingerprint
\IM{PGP key fingerprint} fingerprint, of PGP key
\IM{verifying new versions} verifying new versions of PuTTY
\IM{verifying new versions} new version, verifying
\IM{verifying new versions} upgraded version, verifying
\IM{connection}{network connection} network connection
\IM{connection}{network connection} connection, network
\IM{host name}{hostname} host name
\IM{host name}{hostname} DNS name
\IM{host name}{hostname} server name
\IM{IP address}{Internet address} IP address
\IM{IP address}{Internet address} address, IP
\IM{localhost} \c{localhost}
\IM{loopback IP address}{loopback address} loopback IP address
\IM{loopback IP address}{loopback address} IP address, loopback
\IM{listen address} listen address
\IM{listen address} bind address
\IM{DNS} DNS
\IM{DNS} Domain Name System
\IM{name resolution} name resolution
\IM{name resolution} DNS resolution
\IM{name resolution} host name resolution
\IM{name resolution} server name resolution
\IM{loading and storing saved sessions} sessions, loading and storing
\IM{loading and storing saved sessions} settings, loading and storing
\IM{loading and storing saved sessions} saving settings
\IM{loading and storing saved sessions} storing settings
\IM{loading and storing saved sessions} loading settings
\IM{Default Settings} Default Settings
\IM{Default Settings} settings, default
\IM{Registry} Registry (Windows)
\IM{Registry} Windows Registry
\IM{inactive window} inactive window
\IM{inactive window} window, inactive
\IM{inactive window} terminal window, inactive
\IM{SSH packet log} SSH packet log
\IM{SSH packet log} packet log, SSH
\IM{auto wrap mode}{auto wrap} auto wrap mode
\IM{auto wrap mode}{auto wrap} wrapping, automatic
\IM{auto wrap mode}{auto wrap} line wrapping, automatic
\IM{control sequence}{control codes} control sequences
\IM{control sequence}{control codes} terminal control sequences
\IM{control sequence}{control codes} escape sequences
\IM{cursor coordinates} cursor coordinates
\IM{cursor coordinates} coordinates, cursor
\IM{CR} CR (Carriage Return)
\IM{CR} Carriage Return
\IM{LF} LF (Line Feed)
\IM{LF} Line Feed
\IM{clear screen} clear screen
\IM{clear screen} erase screen
\IM{clear screen} screen, clearing
\IM{blinking text} blinking text
\IM{blinking text} flashing text
\IM{answerback} answerback string
\IM{local echo} local echo
\IM{local echo} echo, local
\IM{remote echo} remote echo
\IM{remote echo} echo, remote
\IM{local line editing} local line editing
\IM{local line editing} line editing, local
\IM{remote-controlled printing} ANSI printing
\IM{remote-controlled printing} remote-controlled printing
\IM{remote-controlled printing} printing, remote-controlled
\IM{Home and End keys} Home key
\IM{Home and End keys} End key
\IM{keypad} keypad, numeric
\IM{keypad} numeric keypad
\IM{Application Cursor Keys} Application Cursor Keys
\IM{Application Cursor Keys} cursor keys, \q{Application} mode
\IM{Application Keypad} Application Keypad
\IM{Application Keypad} keypad, \q{Application} mode
\IM{Application Keypad} numeric keypad, \q{Application} mode
\IM{Num Lock}{NumLock} Num Lock
\IM{NetHack keypad mode} NetHack keypad mode
\IM{NetHack keypad mode} keypad, NetHack mode
\IM{compose key} Compose key
\IM{compose key} DEC Compose key
\IM{terminal bell} terminal bell
\IM{terminal bell} bell, terminal
\IM{terminal bell} beep, terminal
\IM{terminal bell} feep
\IM{Windows Default Beep} Windows Default Beep sound
\IM{Windows Default Beep} Default Beep sound, Windows
\IM{terminal bell, disabling} terminal bell, disabling
\IM{terminal bell, disabling} bell, disabling
\IM{visual bell} visual bell
\IM{visual bell} bell, visual
\IM{PC speaker} PC speaker
\IM{PC speaker} beep, with PC speaker
\IM{sound file} sound file
\IM{sound file} \cw{WAV} file
\IM{bell overload} bell overload mode
\IM{bell overload} terminal bell overload mode
\IM{mouse reporting} mouse reporting
\IM{mouse reporting} \c{xterm} mouse reporting
\IM{links} \c{links} (web browser)
\IM{mc} \c{mc}
\IM{mc} Midnight Commander
\IM{terminal resizing}{window resizing} terminal resizing
\IM{terminal resizing}{window resizing} window resizing
\IM{terminal resizing}{window resizing} resizing, terminal
\IM{destructive backspace} destructive backspace
\IM{destructive backspace} non-destructive backspace
\IM{destructive backspace} backspace, destructive
\IM{Arabic text shaping} Arabic text shaping
\IM{Arabic text shaping} shaping, of Arabic text
\IM{Unicode} Unicode
\IM{Unicode} ISO-10646 (Unicode)
\IM{ASCII} ASCII
\IM{ASCII} US-ASCII
\IM{bidirectional text} bidirectional text
\IM{bidirectional text} right-to-left text
\IM{display becomes corrupted} display corruption
\IM{display becomes corrupted} corruption, of display
\IM{rows} rows, in terminal window
\IM{columns} columns, in terminal window
\IM{window size} window size
\IM{window size} size, of window
\IM{font size} font size
\IM{font size} size, of font
\IM{full screen}{full-screen} full-screen mode
\IM{cursor blinks} blinking cursor
\IM{cursor blinks} flashing cursor
\IM{cursor blinks} cursor, blinking
\IM{font} font
\IM{font} typeface
\IM{minimise} minimise window
\IM{minimise} window, minimising
\IM{maximise} maximise window
\IM{maximise} window, maximising
\IM{closing window}{close window} closing window
\IM{closing window}{close window} window, closing
\IM{Dragon NaturallySpeaking} Dragon NaturallySpeaking
\IM{Dragon NaturallySpeaking} NaturallySpeaking
\IM{AltGr} \q{AltGr} key
\IM{Alt} \q{Alt} key
\IM{CJK} CJK
\IM{CJK} Chinese
\IM{CJK} Japanese
\IM{CJK} Korean
\IM{East Asian Ambiguous characters} East Asian Ambiguous characters
\IM{East Asian Ambiguous characters} CJK ambiguous characters
\IM{character width} character width
\IM{character width} single-width character
\IM{character width} double-width character
\IM{Rich Text Format} Rich Text Format
\IM{Rich Text Format} RTF
\IM{bold}{bold text} bold text
\IM{colour}{colours} colour
\IM{8-bit colour} 8-bit colour
\IM{8-bit colour} colour, 8-bit
\IM{system colours} system colours
\IM{system colours} colours, system
\IM{ANSI colours} ANSI colours
\IM{ANSI colours} colours, ANSI
\IM{cursor colour} cursor colour
\IM{cursor colour} colour, of cursor
\IM{default background} background colour, default
\IM{default background} colour, background, default
\IM{default foreground} foreground colour, default
\IM{default foreground} colour, foreground, default
\IM{TERM} \cw{TERM} environment variable
\IM{logical palettes} logical palettes
\IM{logical palettes} palettes, logical
\IM{breaks in connectivity} connectivity, breaks in
\IM{breaks in connectivity} intermittent connectivity
\IM{idle connections} idle connections
\IM{idle connections} timeout, of connections
\IM{idle connections} connections, idle
\IM{interactive connections}{interactive session} interactive connections
\IM{interactive connections}{interactive session} connections, interactive
\IM{keepalives} keepalives, application
\IM{Nagle's algorithm} Nagle's algorithm
\IM{Nagle's algorithm} \cw{TCP_NODELAY}
\IM{TCP keepalives} TCP keepalives
\IM{TCP keepalives} keepalives, TCP
\IM{TCP keepalives} \cw{SO_KEEPALIVE}
\IM{half-open connections} half-open connections
\IM{half-open connections} connections, half-open
\IM{auto-login username} user name, for auto-login
\IM{auto-login username} login name, for auto-login
\IM{auto-login username} account name, for auto-login
\IM{terminal emulation}{terminal-type} terminal emulation
\IM{terminal emulation}{terminal-type} emulation, terminal
\IM{terminal speed} terminal speed
\IM{terminal speed} speed, terminal
\IM{terminal speed} baud rate, of terminal
\IM{environment variables} environment variables
\IM{environment variables} variables, environment
\IM{proxy} proxy server
\IM{proxy} server, proxy
\IM{HTTP proxy} HTTP proxy
\IM{HTTP proxy} proxy, HTTP
\IM{HTTP proxy} server, HTTP
\IM{HTTP proxy} \cw{CONNECT} proxy (HTTP)
\IM{SOCKS server} SOCKS proxy
\IM{SOCKS server} server, SOCKS
\IM{SOCKS server} proxy, SOCKS
\IM{Telnet proxy} Telnet proxy
\IM{Telnet proxy} TCP proxy
\IM{Telnet proxy} ad-hoc proxy
\IM{Telnet proxy} proxy, Telnet
\IM{Local proxy} local proxy
\IM{Local proxy} proxy command
\IM{Local proxy} command, proxy
\IM{proxy DNS} proxy DNS
\IM{proxy DNS} DNS, with proxy
\IM{proxy DNS} name resolution, with proxy
\IM{proxy DNS} host name resolution, with proxy
\IM{proxy DNS} server name resolution, with proxy
\IM{proxy username} proxy user name
\IM{proxy username} user name, for proxy
\IM{proxy username} login name, for proxy
\IM{proxy username} account name, for proxy
\IM{proxy password} proxy password
\IM{proxy password} password, for proxy
\IM{proxy authentication} proxy authentication
\IM{proxy authentication} authentication, to proxy
\IM{HTTP basic} HTTP \q{basic} authentication
\IM{HTTP basic} \q{basic} authentication (HTTP)
\IM{plaintext password} plain text password
\IM{plaintext password} password, plain text
\IM{Telnet negotiation} Telnet option negotiation
\IM{Telnet negotiation} option negotiation, Telnet
\IM{Telnet negotiation} negotiation, of Telnet options
\IM{firewall}{firewalls} firewalls
\IM{NAT router}{NAT} NAT routers
\IM{NAT router}{NAT} routers, NAT
\IM{NAT router}{NAT} Network Address Translation
\IM{NAT router}{NAT} IP masquerading
\IM{Telnet New Line} Telnet New Line
\IM{Telnet New Line} new line, in Telnet
\IM{.rhosts} \c{.rhosts} file
\IM{.rhosts} \q{rhosts} file
\IM{passwordless login} passwordless login
\IM{passwordless login} login, passwordless
\IM{Windows user name} local user name, in Windows
\IM{Windows user name} user name, local, in Windows
\IM{Windows user name} login name, local, in Windows
\IM{Windows user name} account name, local, in Windows
\IM{local username in Rlogin} local user name, in Rlogin
\IM{local username in Rlogin} user name, local, in Rlogin
\IM{local username in Rlogin} login name, local, in Rlogin
\IM{local username in Rlogin} account name, local, in Rlogin
\IM{privileged port} privileged port
\IM{privileged port} low-numbered port
\IM{privileged port} port, privileged
\IM{remote shell} shell, remote
\IM{remote shell} remote shell
\IM{encryption}{encrypted}{encrypt} encryption
\IM{encryption algorithm} encryption algorithm
\IM{encryption algorithm} cipher algorithm
\IM{encryption algorithm} symmetric-key algorithm
\IM{encryption algorithm} algorithm, encryption
\IM{AES} AES
\IM{AES} Advanced Encryption Standard
\IM{AES} Rijndael
\IM{Arcfour} Arcfour
\IM{Arcfour} RC4
\IM{triple-DES} triple-DES
\IM{single-DES} single-DES
\IM{single-DES} DES
\IM{key exchange} key exchange
\IM{key exchange} kex
\IM{shared secret} shared secret
\IM{shared secret} secret, shared
\IM{key exchange algorithm} key exchange algorithm
\IM{key exchange algorithm} algorithm, key exchange
\IM{Diffie-Hellman key exchange} Diffie-Hellman key exchange
\IM{Diffie-Hellman key exchange} key exchange, Diffie-Hellman
\IM{group exchange} Diffie-Hellman group exchange
\IM{group exchange} group exchange, Diffie-Hellman
\IM{repeat key exchange} repeat key exchange
\IM{repeat key exchange} key exchange, repeat
\IM{challenge/response authentication} challenge/response authentication
\IM{challenge/response authentication} authentication, challenge/response
\IM{security token} security token
\IM{security token} token, security
\IM{one-time passwords} one-time passwords
\IM{one-time passwords} password, one-time
\IM{keyboard-interactive authentication} keyboard-interactive authentication
\IM{keyboard-interactive authentication} authentication, keyboard-interactive
\IM{password expiry} password expiry
\IM{password expiry} expiry, of passwords
\IM{public key authentication}{public-key authentication} public key authentication
\IM{public key authentication}{public-key authentication} RSA authentication
\IM{public key authentication}{public-key authentication} DSA authentication
\IM{public key authentication}{public-key authentication} authentication, public key
\IM{MIT-MAGIC-COOKIE-1} \cw{MIT-MAGIC-COOKIE-1}
\IM{MIT-MAGIC-COOKIE-1} magic cookie
\IM{MIT-MAGIC-COOKIE-1} cookie, magic
\IM{SSH server bugs} SSH server bugs
\IM{SSH server bugs} bugs, in SSH servers
\IM{ignore message} SSH \q{ignore} messages
\IM{ignore message} \q{ignore} messages, in SSH
\IM{message authentication code} message authentication code
\IM{message authentication code} MAC (message authentication code)
\IM{signatures} signature
\IM{signatures} digital signature
\IM{storing configuration in a file} storing settings in a file
\IM{storing configuration in a file} saving settings in a file
\IM{storing configuration in a file} loading settings from a file
\IM{transferring files} transferring files
\IM{transferring files} files, transferring
\IM{receiving files}{download a file} receiving files
\IM{receiving files}{download a file} files, receiving
\IM{receiving files}{download a file} downloading files
\IM{sending files}{upload a file} sending files
\IM{sending files}{upload a file} files, sending
\IM{sending files}{upload a file} uploading files
\IM{listing files} listing files
\IM{listing files} files, listing
\IM{wildcard}{wildcards} wildcards
\IM{wildcard}{wildcards} glob (wildcard)
\IM{PATH} \c{PATH} environment variable
\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{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{spaces in filenames} spaces in filenames
\IM{spaces in filenames} filenames containing spaces
\IM{working directory} working directory
\IM{working directory} current working directory
\IM{resuming file transfers} resuming file transfers
\IM{resuming file transfers} files, resuming transfer of
\IM{changing permissions on files} changing permissions on files
\IM{changing permissions on files} permissions on files, changing
\IM{changing permissions on files} files, changing permissions on
\IM{changing permissions on files} modes of files, changing
\IM{changing permissions on files} access to files, changing
\IM{deleting files} deleting files
\IM{deleting files} files, deleting
\IM{deleting files} removing files
\IM{create a directory} creating directories
\IM{create a directory} directories, creating
\IM{remove a directory} removing directories
\IM{remove a directory} directories, removing
\IM{remove a directory} deleting directories
\IM{rename remote files} renaming files
\IM{rename remote files} files, renaming and moving
\IM{rename remote files} moving files
\IM{local Windows command} local Windows command
\IM{local Windows command} Windows command
\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{subsystem} subsystem, SSH
\IM{subsystem} SSH subsystem
\IM{batch file}{batch files} batch files
\IM{CVS_RSH} \c{CVS_RSH} environment variable
\IM{DSA} DSA
\IM{DSA} Digital Signature Standard
\IM{public-key algorithm} public-key algorithm
\IM{public-key algorithm} asymmetric key algorithm
\IM{public-key algorithm} algorithm, public-key
\IM{generating keys} generating key pairs
\IM{generating keys} creating key pairs
\IM{generating keys} key pairs, generating
\IM{generating keys} public keys, generating
\IM{generating keys} private keys, generating
\IM{authorized_keys file}{authorized_keys} \cw{authorized_keys} file
\IM{key fingerprint} fingerprint, of SSH authentication key
\IM{key fingerprint} public key fingerprint (SSH)
\IM{key fingerprint} SSH public key fingerprint
\IM{SSH-2 public key format} SSH-2 public key file format
\IM{SSH-2 public key format} public key file, SSH-2
\IM{OpenSSH private key format} OpenSSH private key file format
\IM{OpenSSH private key format} private key file, OpenSSH
\IM{ssh.com private key format} \cw{ssh.com} private key file format
\IM{ssh.com private key format} private key file, \cw{ssh.com}
\IM{importing keys} importing private keys
\IM{importing keys} loading private keys
\IM{export private keys} exporting private keys
\IM{export private keys} saving private keys
\IM{.ssh} \c{.ssh} directory
\IM{.ssh2} \c{.ssh2} directory
\IM{authentication agent} authentication agent
\IM{authentication agent} agent, authentication
\IM{-c-pageant} \c{-c} Pageant command-line option
\IM{FAQ} FAQ
\IM{FAQ} Frequently Asked Questions
\IM{supported features} supported features
\IM{supported features} features, supported
\IM{remember my password} storing passwords
\IM{remember my password} password, storing
\IM{login scripts}{startup scripts} login scripts
\IM{login scripts}{startup scripts} startup scripts
\IM{WS2_32.DLL} \cw{WS2_32.DLL}
\IM{WS2_32.DLL} WinSock version 2
\IM{Red Hat Linux} Red Hat Linux
\IM{Red Hat Linux} Linux, Red Hat
\IM{SMB} SMB
\IM{SMB} Windows file sharing
\IM{clean up} clean up after PuTTY
\IM{clean up} uninstalling
\IM{version of PuTTY} version, of PuTTY
\IM{PGP signatures} PGP signatures, of PuTTY binaries
\IM{PGP signatures} signatures, of PuTTY binaries

88
puttysrc/DOC/INTRO.BUT Normal file
View File

@@ -0,0 +1,88 @@
\define{versionidintro} \versionid $Id: intro.but 5593 2005-04-05 18:01:32Z jacob $
\C{intro} Introduction to PuTTY
PuTTY is a free SSH, Telnet and Rlogin client for 32-bit Windows
systems.
\H{you-what} What are SSH, Telnet and Rlogin?
If you already know what SSH, Telnet and Rlogin are, you can safely
skip on to the next section.
SSH, Telnet and Rlogin are three ways of doing the same thing:
logging in to a multi-user computer from another computer, over a
network.
Multi-user operating systems, such as Unix and VMS, usually present
a \i{command-line interface} to the user, much like the \q{\i{Command
Prompt}} or \q{\i{MS-DOS Prompt}} in Windows. The system prints a
prompt, and you type commands which the system will obey.
Using this type of interface, there is no need for you to be sitting
at the same machine you are typing commands to. The commands, and
responses, can be sent over a network, so you can sit at one
computer and give commands to another one, or even to more than one.
SSH, Telnet and Rlogin are \i\e{network protocols} that allow you to
do this. On the computer you sit at, you run a \i\e{client}, which
makes a network connection to the other computer (the \i\e{server}).
The network connection carries your keystrokes and commands from the
client to the server, and carries the server's responses back to
you.
These protocols can also be used for other types of keyboard-based
interactive session. In particular, there are a lot of bulletin
boards, \i{talker systems} and \i{MUDs} (Multi-User Dungeons) which support
access using Telnet. There are even a few that support SSH.
You might want to use SSH, Telnet or Rlogin if:
\b you have an account on a Unix or VMS system which you want to be
able to access from somewhere else
\b your Internet Service Provider provides you with a login account
on a \i{web server}. (This might also be known as a \i\e{shell account}.
A \e{shell} is the program that runs on the server and interprets
your commands for you.)
\b you want to use a \i{bulletin board system}, talker or MUD which can
be accessed using Telnet.
You probably do \e{not} want to use SSH, Telnet or Rlogin if:
\b you only use Windows. Windows computers have their own
ways of networking between themselves, and unless you are doing
something fairly unusual, you will not need to use any of these
remote login protocols.
\H{which-one} How do SSH, Telnet and Rlogin differ?
This list summarises some of the \i{differences between SSH, Telnet
and Rlogin}.
\b SSH (which stands for \q{\i{secure shell}}) is a recently designed,
high-security protocol. It uses strong cryptography to protect your
connection against eavesdropping, hijacking and other attacks. Telnet
and Rlogin are both older protocols offering minimal security.
\b SSH and Rlogin both allow you to \I{passwordless login}log in to the
server without having to type a password. (Rlogin's method of doing this is
insecure, and can allow an attacker to access your account on the
server. SSH's method is much more secure, and typically breaking the
security requires the attacker to have gained access to your actual
client machine.)
\b SSH allows you to connect to the server and automatically send a
command, so that the server will run that command and then
disconnect. So you can use it in automated processing.
The Internet is a hostile environment and security is everybody's
responsibility. If you are connecting across the open Internet, then
we recommend you use SSH. If the server you want to connect to
doesn't support SSH, it might be worth trying to persuade the
administrator to install it.
If your client and server are both behind the same (good) firewall,
it is more likely to be safe to use Telnet or Rlogin, but we still
recommend you use SSH.

29
puttysrc/DOC/LICENCE.BUT Normal file
View File

@@ -0,0 +1,29 @@
\define{versionidlicence} \versionid $Id: licence.but 7048 2007-01-01 21:19:14Z jacob $
\A{licence} PuTTY \ii{Licence}
PuTTY is \i{copyright} 1997-2007 Simon Tatham.
Portions copyright Robert de Bath, Joris van Rantwijk, Delian
Delchev, Andreas Schultz, Jeroen Massar, Wez Furlong, Nicolas Barry,
Justin Bradford, Ben Harris, Malcolm Smith, Ahmad Khalifa, Markus Kuhn,
and CORE SDI S.A.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the \q{Software}), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \q{AS IS}, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

75
puttysrc/DOC/MAKEFILE Normal file
View File

@@ -0,0 +1,75 @@
all: man index.html
# Decide on the versionid policy.
#
# If the user has passed in $(VERSION) on the command line (`make
# VERSION="Release 0.56"'), we use that as an explicit version
# string. Otherwise, we use `svnversion' to examine the checked-out
# documentation source, and if that returns a single revision
# number then we invent a version string reflecting just that
# number. Failing _that_, we resort to versionids.but which shows a
# $Id for each individual file.
#
# So here, we define VERSION using svnversion if it isn't already
# defined ...
ifndef VERSION
SVNVERSION=$(shell test -d .svn && svnversion .)
BADCHARS=$(findstring :,$(SVNVERSION))$(findstring S,$(SVNVERSION))
ifeq ($(BADCHARS),)
ifneq ($(SVNVERSION),)
ifneq ($(SVNVERSION),exported)
VERSION=Built from revision $(patsubst M,,$(SVNVERSION))
endif
endif
endif
endif
# ... and now, we condition our build behaviour on whether or not
# VERSION _is_ defined.
ifdef VERSION
VERSIONIDS=vstr
vstr.but: FORCE
echo \\versionid $(VERSION) > vstr.but
FORCE:;
else
VERSIONIDS=vids
endif
CHAPTERS := $(SITE) blurb intro gs using config pscp psftp plink pubkey
CHAPTERS += pageant errors faq feedback licence udp pgpkeys
CHAPTERS += index $(VERSIONIDS)
INPUTS = $(patsubst %,%.but,$(CHAPTERS))
# This is temporary. Hack it locally or something.
HALIBUT = halibut
index.html: $(INPUTS)
$(HALIBUT) --text --html --winhelp $(INPUTS)
# During formal builds it's useful to be able to build this one alone.
putty.hlp: $(INPUTS)
$(HALIBUT) --winhelp $(INPUTS)
putty.info: $(INPUTS)
$(HALIBUT) --info $(INPUTS)
chm: putty.hhp
putty.hhp: $(INPUTS) chm.but
$(HALIBUT) --html $(INPUTS) chm.but
MKMAN = $(HALIBUT) --man=$@ mancfg.but $<
MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1
man: $(MANPAGES)
putty.1: man-putt.but mancfg.but; $(MKMAN)
puttygen.1: man-pg.but mancfg.but; $(MKMAN)
plink.1: man-pl.but mancfg.but; $(MKMAN)
pscp.1: man-pscp.but mancfg.but; $(MKMAN)
psftp.1: man-psft.but mancfg.but; $(MKMAN)
puttytel.1: man-ptel.but mancfg.but; $(MKMAN)
pterm.1: man-pter.but mancfg.but; $(MKMAN)
mostlyclean:
rm -f *.html *.txt *.hlp *.cnt *.1 *.info vstr.but *.hh[pck]
clean: mostlyclean
rm -f *.chm

207
puttysrc/DOC/MAN-PG.BUT Normal file
View File

@@ -0,0 +1,207 @@
\cfg{man-identity}{puttygen}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{puttygen-manpage} Man page for PuTTYgen
\S{puttygen-manpage-name} NAME
\cw{puttygen} - public-key generator for the PuTTY tools
\S{puttygen-manpage-synopsis} SYNOPSIS
\c puttygen ( keyfile | -t keytype [ -b bits ] )
\e bbbbbbbb iiiiiii bb iiiiiii bb iiii
\c [ -C new-comment ] [ -P ] [ -q ]
\e bb iiiiiiiiiii bb bb
\c [ -O output-type | -l | -L | -p ]
\e bb iiiiiiiiiii bb bb bb
\c [ -o output-file ]
\e bb iiiiiiiiiii
\S{puttygen-manpage-description} DESCRIPTION
\c{puttygen} is a tool to generate and manipulate SSH public and
private key pairs. It is part of the PuTTY suite, although it can
also interoperate with the private key formats used by some other
SSH clients.
When you run \c{puttygen}, it does three things. Firstly, it either
loads an existing key file (if you specified \e{keyfile}), or
generates a new key (if you specified \e{keytype}). Then, it
optionally makes modifications to the key (changing the comment
and/or the passphrase); finally, it outputs the key, or some
information about the key, to a file.
All three of these phases are controlled by the options described in
the following section.
\S{puttygen-manpage-options} OPTIONS
In the first phase, \c{puttygen} either loads or generates a key.
The options to control this are:
\dt \e{keyfile}
\dd Specify a private key file to be loaded. This private key file can
be in the (de facto standard) SSH-1 key format, or in PuTTY's SSH-2
key format, or in either of the SSH-2 private key formats used by
OpenSSH and ssh.com's implementation.
\dt \cw{\-t} \e{keytype}
\dd Specify a type of key to generate. The acceptable values here are
\c{rsa} and \c{dsa} (to generate SSH-2 keys), and \c{rsa1} (to
generate SSH-1 keys).
\dt \cw{\-b} \e{bits}
\dd Specify the size of the key to generate, in bits. Default is 1024.
\dt \cw{\-q}
\dd Suppress the progress display when generating a new key.
In the second phase, \c{puttygen} optionally alters properties of
the key it has loaded or generated. The options to control this are:
\dt \cw{\-C} \e{new\-comment}
\dd Specify a comment string to describe the key. This comment string
will be used by PuTTY to identify the key to you (when asking you to
enter the passphrase, for example, so that you know which passphrase
to type).
\dt \cw{\-P}
\dd Indicate that you want to change the key's passphrase. This is
automatic when you are generating a new key, but not when you are
modifying an existing key.
In the third phase, \c{puttygen} saves the key or information
about it. The options to control this are:
\dt \cw{\-O} \e{output\-type}
\dd Specify the type of output you want \c{puttygen} to produce.
Acceptable options are:
\lcont{
\dt \cw{private}
\dd Save the private key in a format usable by PuTTY. This will either
be the standard SSH-1 key format, or PuTTY's own SSH-2 key format.
\dt \cw{public}
\dd Save the public key only. For SSH-1 keys, the standard public key
format will be used (\q{\cw{1024 37 5698745}...}). For SSH-2 keys, the
public key will be output in the format specified by RFC 4716,
which is a multi-line text file beginning with the line
\q{\cw{---- BEGIN SSH2 PUBLIC KEY ----}}.
\dt \cw{public-openssh}
\dd Save the public key only, in a format usable by OpenSSH. For SSH-1
keys, this output format behaves identically to \c{public}. For
SSH-2 keys, the public key will be output in the OpenSSH format,
which is a single line (\q{\cw{ssh-rsa AAAAB3NzaC1yc2}...}).
\dt \cw{fingerprint}
\dd Print the fingerprint of the public key. All fingerprinting
algorithms are believed compatible with OpenSSH.
\dt \cw{private-openssh}
\dd Save an SSH-2 private key in OpenSSH's format. This option is not
permitted for SSH-1 keys.
\dt \cw{private-sshcom}
\dd Save an SSH-2 private key in ssh.com's format. This option is not
permitted for SSH-1 keys.
If no output type is specified, the default is \c{private}.
}
\dt \cw{\-o} \e{output\-file}
\dd Specify the file where \c{puttygen} should write its output. If
this option is not specified, \c{puttygen} will assume you want to
overwrite the original file if the input and output file types are
the same (changing a comment or passphrase), and will assume you
want to output to stdout if you are asking for a public key or
fingerprint. Otherwise, the \c{\-o} option is required.
\dt \cw{\-l}
\dd Synonym for \q{\cw{-O fingerprint}}.
\dt \cw{\-L}
\dd Synonym for \q{\cw{-O public-openssh}}.
\dt \cw{\-p}
\dd Synonym for \q{\cw{-O public}}.
The following options do not run PuTTYgen as normal, but print
informational messages and then quit:
\dt \cw{\-h}, \cw{\-\-help}
\dd Display a message summarizing the available options.
\dt \cw{\-V}, \cw{\-\-version}
\dd Display the version of PuTTYgen.
\dt \cw{\-\-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
in verifying new files released by the PuTTY team.
\S{puttygen-manpage-examples} EXAMPLES
To generate an SSH-2 RSA key pair and save it in PuTTY's own format
(you will be prompted for the passphrase):
\c puttygen -t rsa -C "my home key" -o mykey.ppk
To generate a larger (2048-bit) key:
\c puttygen -t rsa -b 2048 -C "my home key" -o mykey.ppk
To change the passphrase on a key (you will be prompted for the old
and new passphrases):
\c puttygen -P mykey.ppk
To change the comment on a key:
\c puttygen -C "new comment" mykey.ppk
To convert a key into OpenSSH's private key format:
\c puttygen mykey.ppk -O private-openssh -o my-openssh-key
To convert a key \e{from} another format (\c{puttygen} will
automatically detect the input key type):
\c puttygen my-ssh.com-key -o mykey.ppk
To display the fingerprint of a key (some key types require a
passphrase to extract even this much information):
\c puttygen -l mykey.ppk
To add the OpenSSH-format public half of a key to your authorised
keys file:
\c puttygen -L mykey.ppk >> $HOME/.ssh/authorized_keys
\S{puttygen-manpage-bugs} BUGS
There's currently no way to supply passphrases in batch mode, or
even just to specify that you don't want a passphrase at all.

158
puttysrc/DOC/MAN-PL.BUT Normal file
View File

@@ -0,0 +1,158 @@
\cfg{man-identity}{plink}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{plink-manpage} Man page for Plink
\S{plink-manpage-name} NAME
\cw{plink} \- PuTTY link, command line network connection tool
\S{plink-manpage-synopsis} SYNOPSIS
\c plink [options] [user@]host [command]
\e bbbbb iiiiiii iiiib iiii iiiiiii
\S{plink-manpage-description} DESCRIPTION
\cw{plink} is a network connection tool supporting several protocols.
\S{plink-manpage-options} OPTIONS
The command-line options supported by \cw{plink} are:
\dt \cw{-V}
\dd Show version information and exit.
\dt \cw{-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys and exit,
to aid in verifying new files released by the PuTTY team.
\dt \cw{-v}
\dd Show verbose messages.
\dt \cw{-load} \e{session}
\dd Load settings from saved session.
\dt \cw{-ssh}
\dd Force use of SSH protocol (default).
\dt \cw{-telnet}
\dd Force use of Telnet protocol.
\dt \cw{-rlogin}
\dd Force use of rlogin protocol.
\dt \cw{-raw}
\dd Force raw mode.
\dt \cw{-P} \e{port}
\dd Connect to port \e{port}.
\dt \cw{-l} \e{user}
\dd Set remote username to \e{user}.
\dt \cw{-m} \e{path}
\dd Read remote command(s) from local file \e{path}.
\dt \cw{-batch}
\dd Disable interactive prompts.
\dt \cw{-pw} \e{password}
\dd Set remote password to \e{password}. \e{CAUTION:} this will likely
make the password visible to other users of the local machine (via
commands such as \q{\c{w}}).
\dt \cw{\-L} \cw{[}\e{srcaddr}\cw{:]}\e{srcport}\cw{:}\e{desthost}\cw{:}\e{destport}
\dd Set up a local port forwarding: listen on \e{srcport} (or
\e{srcaddr}:\e{srcport} if specified), and forward any connections
over the SSH connection to the destination address
\e{desthost}:\e{destport}. Only works in SSH.
\dt \cw{\-R} \cw{[}\e{srcaddr}\cw{:]}\e{srcport}\cw{:}\e{desthost}\cw{:}\e{destport}
\dd Set up a remote port forwarding: ask the SSH server to listen on
\e{srcport} (or \e{srcaddr}:\e{srcport} if specified), and to
forward any connections back over the SSH connection where the
client will pass them on to the destination address
\e{desthost}:\e{destport}. Only works in SSH.
\dt \cw{\-D} [\e{srcaddr}:]\e{srcport}
\dd Set up dynamic port forwarding. The client listens on
\e{srcport} (or \e{srcaddr}:\e{srcport} if specified), and
implements a SOCKS server. So you can point SOCKS-aware applications
at this port and they will automatically use the SSH connection to
tunnel all their connections. Only works in SSH.
\dt \cw{-X}
\dd Enable X11 forwarding.
\dt \cw{-x}
\dd Disable X11 forwarding (default).
\dt \cw{-A}
\dd Enable agent forwarding.
\dt \cw{-a}
\dd Disable agent forwarding (default).
\dt \cw{-t}
\dd Enable pty allocation (default if a command is NOT specified).
\dt \cw{-T}
\dd Disable pty allocation (default if a command is specified).
\dt \cw{-1}
\dd Force use of SSH protocol version 1.
\dt \cw{-2}
\dd Force use of SSH protocol version 2.
\dt \cw{-C}
\dd Enable SSH compression.
\dt \cw{-i} \e{path}
\dd Private key file for authentication.
\dt \cw{-s}
\dd Remote command is SSH subsystem (SSH-2 only).
\dt \cw{-N}
\dd Don't start a remote command or shell at all (SSH-2 only).
\S{plink-manpage-more-information} MORE INFORMATION
For more information on plink, it's probably best to go and look at
the manual on the PuTTY web page:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\cw{http://www.chiark.greenend.org.uk/~sgtatham/putty/}
\S{plink-manpage-bugs} BUGS
This man page isn't terribly complete. See the above web link for
better documentation.

116
puttysrc/DOC/MAN-PSCP.BUT Normal file
View File

@@ -0,0 +1,116 @@
\cfg{man-identity}{pscp}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{pscp-manpage} Man page for PSCP
\S{pscp-manpage-name} NAME
\cw{pscp} \- command-line SCP (secure copy) / SFTP client
\S{pscp-manpage-synopsis} SYNOPSIS
\c pscp [options] [user@]host:source target
\e bbbb iiiiiii iiiib iiiibiiiiii iiiiii
\c pscp [options] source [source...] [user@]host:target
\e bbbb iiiiiii iiiiii iiiiii iiiib iiiibiiiiii
\c pscp [options] -ls [user@]host:filespec
\e bbbb iiiiiii bbb iiiib iiiibiiiiiiii
\S{pscp-manpage-description} DESCRIPTION
\cw{pscp} is a command-line client for the SSH-based SCP (secure
copy) and SFTP (secure file transfer protocol) protocols.
\S{pscp-manpage-options} OPTIONS
The command-line options supported by \e{pscp} are:
\dt \cw{-V}
\dd Show version information and exit.
\dt \cw{-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys and exit,
to aid in verifying new files released by the PuTTY team.
\dt \cw{-ls}
\dd Remote directory listing.
\dt \cw{-p}
\dd Preserve file attributes.
\dt \cw{-q}
\dd Quiet, don't show statistics.
\dt \cw{-r}
\dd Copy directories recursively.
\dt \cw{-unsafe}
\dd Allow server-side wildcards (DANGEROUS).
\dt \cw{-v}
\dd Show verbose messages.
\dt \cw{-load} \e{session}
\dd Load settings from saved session.
\dt \cw{-P} \e{port}
\dd Connect to port \e{port}.
\dt \cw{-l} \e{user}
\dd Set remote username to \e{user}.
\dt \cw{-batch}
\dd Disable interactive prompts.
\dt \cw{-pw} \e{password}
\dd Set remote password to \e{password}. \e{CAUTION:} this will likely
make the password visible to other users of the local machine (via
commands such as \q{\c{w}}).
\dt \cw{-1}
\dd Force use of SSH protocol version 1.
\dt \cw{-2}
\dd Force use of SSH protocol version 2.
\dt \cw{-C}
\dd Enable SSH compression.
\dt \cw{-i} \e{path}
\dd Private key file for authentication.
\dt \cw{-scp}
\dd Force use of SCP protocol.
\dt \cw{-sftp}
\dd Force use of SFTP protocol.
\S{pscp-manpage-more-information} MORE INFORMATION
For more information on \cw{pscp} it's probably best to go and look at
the manual on the PuTTY web page:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\cw{http://www.chiark.greenend.org.uk/~sgtatham/putty/}
\S{pscp-manpage-bugs} BUGS
This man page isn't terribly complete. See the above web link for
better documentation.

101
puttysrc/DOC/MAN-PSFT.BUT Normal file
View File

@@ -0,0 +1,101 @@
\cfg{man-identity}{psftp}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{psftp-manpage} Man page for PSFTP
\S{psftp-manpage-name} NAME
\cw{psftp} \- interactive SFTP (secure file transfer protocol) client
\S{psftp-manpage-synopsis} SYNOPSIS
\c psftp [options] [user@]host
\e bbbbb iiiiiii iiiib iiii
\S{psftp-manpage-description} DESCRIPTION
\cw{psftp} is an interactive text-based client for the SSH-based SFTP
(secure file transfer) protocol.
\S{psftp-manpage-options} OPTIONS
The command-line options supported by \cw{psftp} are:
\dt \cw{-V}
\dd Show version information and exit.
\dt \cw{-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys and exit,
to aid in verifying new files released by the PuTTY team.
\dt \cw{-b} \e{batchfile}
\dd Use specified batchfile.
\dt \cw{-bc}
\dd Output batchfile commands.
\dt \cw{-be}
\dd Don't stop batchfile processing on errors.
\dt \cw{-v}
\dd Show verbose messages.
\dt \cw{-load} \e{session}
\dd Load settings from saved session.
\dt \cw{-P} \e{port}
\dd Connect to port \e{port}.
\dt \cw{-l} \e{user}
\dd Set remote username to \e{user}.
\dt \cw{-batch}
\dd Disable interactive prompts.
\dt \cw{-pw} \e{password}
\dd Set remote password to \e{password}. \e{CAUTION:} this will likely
make the password visible to other users of the local machine (via
commands such as \q{\c{w}}).
\dt \cw{-1}
\dd Force use of SSH protocol version 1.
\dt \cw{-2}
\dd Force use of SSH protocol version 2.
\dt \cw{-C}
\dd Enable SSH compression.
\dt \cw{-i} \e{path}
\dd Private key file for authentication.
\S{psftp-manpage-commands} COMMANDS
For a list of commands available inside \cw{psftp}, type \cw{help}
at the \cw{psftp>} prompt.
\S{psftp-manpage-more-information} MORE INFORMATION
For more information on \cw{psftp} it's probably best to go and look at
the manual on the PuTTY web page:
\cw{http://www.chiark.greenend.org.uk/~sgtatham/putty/}
\S{psftp-manpage-bugs} BUGS
This man page isn't terribly complete. See the above web link for
better documentation.

189
puttysrc/DOC/MAN-PTEL.BUT Normal file
View File

@@ -0,0 +1,189 @@
\cfg{man-identity}{puttytel}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{puttytel-manpage} Man page for PuTTYtel
\S{puttytel-manpage-name} NAME
\cw{puttytel} \- GUI Telnet and Rlogin client for X
\S{puttytel-manpage-synopsis} SYNOPSIS
\c puttytel [ options ] [ host ]
\e bbbbbbbb iiiiiii iiii
\S{puttytel-manpage-description} DESCRIPTION
\cw{puttytel} is a graphical Telnet and Rlogin client for X. It
is a direct port of the Windows Telnet and Rlogin client of the same
name, and a cut-down cryptography-free version of PuTTY.
\S{puttytel-manpage-options} OPTIONS
The command-line options supported by \cw{puttytel} are:
\dt \cw{\-\-display} \e{display\-name}
\dd Specify the X display on which to open \cw{puttytel}. (Note this
option has a double minus sign, even though none of the others do.
This is because this option is supplied automatically by GTK.
Sorry.)
\dt \cw{\-fn} \e{font-name}
\dd Specify the font to use for normal text displayed in the terminal.
\dt \cw{\-fb} \e{font-name}
\dd Specify the font to use for bold text displayed in the terminal. If
the \cw{BoldAsColour} resource is set to 1 (the default), bold text
will be displayed in different colours instead of a different font,
so this option will be ignored. If \cw{BoldAsColour} is set to 0
and you do not specify a bold font, \cw{puttytel} will overprint the
normal font to make it look bolder.
\dt \cw{\-fw} \e{font-name}
\dd Specify the font to use for double-width characters (typically
Chinese, Japanese and Korean text) displayed in the terminal.
\dt \cw{\-fwb} \e{font-name}
\dd Specify the font to use for bold double-width characters
(typically Chinese, Japanese and Korean text). Like \cw{-fb}, this
will be ignored unless the \cw{BoldAsColour} resource is set to 0.
\dt \cw{\-geometry} \e{geometry}
\dd Specify the size of the terminal, in rows and columns of text. See
\e{X(7)} for more information on the syntax of geometry
specifications.
\dt \cw{\-sl} \e{lines}
\dd Specify the number of lines of scrollback to save off the top of the
terminal.
\dt \cw{\-fg} \e{colour}
\dd Specify the foreground colour to use for normal text.
\dt \cw{\-bg} \e{colour}
\dd Specify the background colour to use for normal text.
\dt \cw{\-bfg} \e{colour}
\dd Specify the foreground colour to use for bold text, if the
\cw{BoldAsColour} resource is set to 1 (the default).
\dt \cw{\-bbg} \e{colour}
\dd Specify the foreground colour to use for bold reverse-video text, if
the \cw{BoldAsColour} resource is set to 1 (the default). (This
colour is best thought of as the bold version of the background
colour; so it only appears when text is displayed \e{in} the
background colour.)
\dt \cw{\-cfg} \e{colour}
\dd Specify the foreground colour to use for text covered by the cursor.
\dt \cw{\-cbg} \e{colour}
\dd Specify the background colour to use for text covered by the cursor.
In other words, this is the main colour of the cursor.
\dt \cw{\-title} \e{title}
\dd Specify the initial title of the terminal window. (This can be
changed under control of the server.)
\dt \cw{\-sb\-} or \cw{+sb}
\dd Tells \cw{puttytel} not to display a scroll bar.
\dt \cw{\-sb}
\dd Tells \cw{puttytel} to display a scroll bar: this is the opposite of
\cw{\-sb\-}. This is the default option: you will probably only need
to specify it explicitly if you have changed the default using the
\cw{ScrollBar} resource.
\dt \cw{\-log} \e{filename}
\dd This option makes \cw{puttytel} log all the terminal output to a file
as well as displaying it in the terminal.
\dt \cw{\-cs} \e{charset}
\dd This option specifies the character set in which \cw{puttytel}
should assume the session is operating. This character set will be
used to interpret all the data received from the session, and all
input you type or paste into \cw{puttytel} will be converted into
this character set before being sent to the session.
\lcont{ Any character set name which is valid in a MIME header (and
supported by \cw{puttytel}) should be valid here (examples are
\q{\cw{ISO-8859-1}}, \q{\cw{windows-1252}} or \q{\cw{UTF-8}}). Also,
any character encoding which is valid in an X logical font
description should be valid (\q{\cw{ibm-cp437}}, for example).
\cw{puttytel}'s default behaviour is to use the same character
encoding as its primary font. If you supply a Unicode
(\cw{iso10646-1}) font, it will default to the UTF-8 character set.
Character set names are case-insensitive.
}
\dt \cw{\-nethack}
\dd Tells \cw{puttytel} to enable NetHack keypad mode, in which the
numeric keypad generates the NetHack \c{hjklyubn} direction keys.
This enables you to play NetHack with the numeric keypad without
having to use the NetHack \c{number_pad} option (which requires you
to press \q{\cw{n}} before any repeat count). So you can move with
the numeric keypad, and enter repeat counts with the normal number
keys.
\dt \cw{\-help}, \cw{\-\-help}
\dd Display a message summarizing the available options.
\dt \cw{\-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
in verifying new files released by the PuTTY team.
\dt \cw{\-load} \e{session}
\dd Load a saved session by name. This allows you to run a saved session
straight from the command line without having to go through the
configuration box first.
\dt \cw{\-telnet}, \cw{\-rlogin}, \cw{\-raw}
\dd Select the protocol \cw{puttytel} will use to make the connection.
\dt \cw{\-l} \e{username}
\dd Specify the username to use when logging in to the server.
\dt \cw{\-P} \e{port}
\dd Specify the port to connect to the server on.
\S{puttytel-manpage-saved-sessions} SAVED SESSIONS
Saved sessions are stored in a \cw{.putty/sessions} subdirectory in
your home directory.
\S{puttytel-manpage-more-information} MORE INFORMATION
For more information on PuTTY and PuTTYtel, it's probably best to go
and look at the manual on the web page:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\cw{http://www.chiark.greenend.org.uk/~sgtatham/putty/}
\S{puttytel-manpage-bugs} BUGS
This man page isn't terribly complete.

676
puttysrc/DOC/MAN-PTER.BUT Normal file
View File

@@ -0,0 +1,676 @@
\cfg{man-identity}{pterm}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{pterm-manpage} Man page for pterm
\S{pterm-manpage-name} NAME
pterm \- yet another X terminal emulator
\S{pterm-manpage-synopsis} SYNOPSIS
\c pterm [ options ]
\e bbbbb iiiiiii
\S{pterm-manpage-description} DESCRIPTION
\cw{pterm} is a terminal emulator for X. It is based on a port of
the terminal emulation engine in the Windows SSH client PuTTY.
\S{pterm-manpage-options} OPTIONS
The command-line options supported by \cw{pterm} are:
\dt \cw{\-e} \e{command} [ \e{arguments} ]
\dd Specify a command to be executed in the new terminal. Everything on
the command line after this option will be passed straight to the
\cw{execvp} system call; so if you need the command to redirect its
input or output, you will have to use \cw{sh}:
\lcont{
\c pterm -e sh -c 'mycommand < inputfile'
}
\dt \cw{\-\-display} \e{display\-name}
\dd Specify the X display on which to open \cw{pterm}. (Note this
option has a double minus sign, even though none of the others do.
This is because this option is supplied automatically by GTK.
Sorry.)
\dt \cw{\-name} \e{font-name}
\dd Specify the name under which \cw{pterm} looks up X resources.
Normally it will look them up as (for example) \cw{pterm.Font}. If
you specify \q{\cw{\-name xyz}}, it will look them up as
\cw{xyz.Font} instead. This allows you to set up several different
sets of defaults and choose between them.
\dt \cw{\-fn} \e{font-name}
\dd Specify the font to use for normal text displayed in the terminal.
\dt \cw{\-fb} \e{font-name}
\dd Specify the font to use for bold text displayed in the terminal. If
the \cw{BoldAsColour} resource is set to 1 (the default), bold text
will be displayed in different colours instead of a different font,
so this option will be ignored. If \cw{BoldAsColour} is set to 0
and you do not specify a bold font, \cw{pterm} will overprint the
normal font to make it look bolder.
\dt \cw{\-fw} \e{font-name}
\dd Specify the font to use for double-width characters (typically
Chinese, Japanese and Korean text) displayed in the terminal.
\dt \cw{\-fwb} \e{font-name}
\dd Specify the font to use for bold double-width characters
(typically Chinese, Japanese and Korean text). Like \cw{-fb}, this
will be ignored unless the \cw{BoldAsColour} resource is set to 0.
\dt \cw{\-geometry} \e{geometry}
\dd Specify the size of the terminal, in rows and columns of text. See
\e{X(7)} for more information on the syntax of geometry
specifications.
\dt \cw{\-sl} \e{lines}
\dd Specify the number of lines of scrollback to save off the top of the
terminal.
\dt \cw{\-fg} \e{colour}
\dd Specify the foreground colour to use for normal text.
\dt \cw{\-bg} \e{colour}
\dd Specify the background colour to use for normal text.
\dt \cw{\-bfg} \e{colour}
\dd Specify the foreground colour to use for bold text, if the
\cw{BoldAsColour} resource is set to 1 (the default).
\dt \cw{\-bbg} \e{colour}
\dd Specify the foreground colour to use for bold reverse-video text, if
the \cw{BoldAsColour} resource is set to 1 (the default). (This
colour is best thought of as the bold version of the background
colour; so it only appears when text is displayed \e{in} the
background colour.)
\dt \cw{\-cfg} \e{colour}
\dd Specify the foreground colour to use for text covered by the cursor.
\dt \cw{\-cbg} \e{colour}
\dd Specify the background colour to use for text covered by the cursor.
In other words, this is the main colour of the cursor.
\dt \cw{\-title} \e{title}
\dd Specify the initial title of the terminal window. (This can be
changed under control of the server.)
\dt \cw{\-ut\-} or \cw{+ut}
\dd Tells \cw{pterm} not to record your login in the \cw{utmp},
\cw{wtmp} and \cw{lastlog} system log files; so you will not show
up on \cw{finger} or \cw{who} listings, for example.
\dt \cw{\-ut}
\dd Tells \cw{pterm} to record your login in \cw{utmp}, \cw{wtmp} and
\cw{lastlog}: this is the opposite of \cw{\-ut\-}. This is the
default option: you will probably only need to specify it explicitly
if you have changed the default using the \cw{StampUtmp} resource.
\dt \cw{\-ls\-} or \cw{+ls}
\dd Tells \cw{pterm} not to execute your shell as a login shell.
\dt \cw{\-ls}
\dd Tells \cw{pterm} to execute your shell as a login shell: this is
the opposite of \cw{\-ls\-}. This is the default option: you will
probably only need to specify it explicitly if you have changed the
default using the \cw{LoginShell} resource.
\dt \cw{\-sb\-} or \cw{+sb}
\dd Tells \cw{pterm} not to display a scroll bar.
\dt \cw{\-sb}
\dd Tells \cw{pterm} to display a scroll bar: this is the opposite of
\cw{\-sb\-}. This is the default option: you will probably only need
to specify it explicitly if you have changed the default using the
\cw{ScrollBar} resource.
\dt \cw{\-log} \e{filename}
\dd This option makes \cw{pterm} log all the terminal output to a file
as well as displaying it in the terminal.
\dt \cw{\-cs} \e{charset}
\dd This option specifies the character set in which \cw{pterm} should
assume the session is operating. This character set will be used to
interpret all the data received from the session, and all input you
type or paste into \cw{pterm} will be converted into this character
set before being sent to the session.
\lcont{ Any character set name which is valid in a MIME header (and
supported by \cw{pterm}) should be valid here (examples are
\q{\cw{ISO-8859-1}}, \q{\cw{windows-1252}} or \q{\cw{UTF-8}}). Also,
any character encoding which is valid in an X logical font
description should be valid (\q{\cw{ibm-cp437}}, for example).
\cw{pterm}'s default behaviour is to use the same character encoding
as its primary font. If you supply a Unicode (\cw{iso10646-1}) font,
it will default to the UTF-8 character set.
Character set names are case-insensitive.
}
\dt \cw{\-nethack}
\dd Tells \cw{pterm} to enable NetHack keypad mode, in which the
numeric keypad generates the NetHack \c{hjklyubn} direction keys.
This enables you to play NetHack with the numeric keypad without
having to use the NetHack \c{number_pad} option (which requires you
to press \q{\cw{n}} before any repeat count). So you can move with
the numeric keypad, and enter repeat counts with the normal number
keys.
\dt \cw{\-xrm} \e{resource-string}
\dd This option specifies an X resource string. Useful for setting
resources which do not have their own command-line options. For
example:
\lcont{
\c pterm -xrm 'ScrollbarOnLeft: 1'
}
\dt \cw{\-help}, \cw{\-\-help}
\dd Display a message summarizing the available options.
\dt \cw{\-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
in verifying new files released by the PuTTY team.
\S{pterm-manpage-x-resources} X RESOURCES
\cw{pterm} can be more completely configured by means of X
resources. All of these resources are of the form \cw{pterm.FOO} for
some \cw{FOO}; you can make \cw{pterm} look them up under another
name, such as \cw{xyz.FOO}, by specifying the command-line option
\q{\cw{\-name xyz}}.
\dt \cw{pterm.CloseOnExit}
\dd This option should be set to 0, 1 or 2; the default is 2. It
controls what \cw{pterm} does when the process running inside it
terminates. When set to 2 (the default), \cw{pterm} will close its
window as soon as the process inside it terminates. When set to 0,
\cw{pterm} will print the process's exit status, and the window
will remain present until a key is pressed (allowing you to inspect
the scrollback, and copy and paste text out of it).
\lcont{
When this setting is set to 1, \cw{pterm} will close
immediately if the process exits cleanly (with an exit status of
zero), but the window will stay around if the process exits with a
non-zero code or on a signal. This enables you to see what went
wrong if the process suffers an error, but not to have to bother
closing the window in normal circumstances.
}
\dt \cw{pterm.WarnOnClose}
\dd This option should be set to either 0 or 1; the default is 1.
When set to 1, \cw{pterm} will ask for confirmation before closing
its window when you press the close button.
\dt \cw{pterm.TerminalType}
\dd This controls the value set in the \cw{TERM} environment
variable inside the new terminal. The default is \q{\cw{xterm}}.
\dt \cw{pterm.BackspaceIsDelete}
\dd This option should be set to either 0 or 1; the default is 1.
When set to 0, the ordinary Backspace key generates the Backspace
character (\cw{^H}); when set to 1, it generates the Delete
character (\cw{^?}). Whichever one you set, the terminal device
inside \cw{pterm} will be set up to expect it.
\dt \cw{pterm.RXVTHomeEnd}
\dd This option should be set to either 0 or 1; the default is 0. When
it is set to 1, the Home and End keys generate the control sequences
they would generate in the \cw{rxvt} terminal emulator, instead of
the more usual ones generated by other emulators.
\dt \cw{pterm.LinuxFunctionKeys}
\dd This option can be set to any number between 0 and 5 inclusive;
the default is 0. The modes vary the control sequences sent by the
function keys; for more complete documentation, it is probably
simplest to try each option in \q{\cw{pterm \-e cat}}, and press the
keys to see what they generate.
\dt \cw{pterm.NoApplicationKeys}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from ever switching the numeric keypad
into application mode (where the keys send function-key-like
sequences instead of numbers or arrow keys). You probably only need
this if some application is making a nuisance of itself.
\dt \cw{pterm.NoApplicationCursors}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from ever switching the cursor keys
into application mode (where the keys send slightly different
sequences). You probably only need this if some application is
making a nuisance of itself.
\dt \cw{pterm.NoMouseReporting}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from ever enabling mouse reporting
mode (where mouse clicks are sent to the application instead of
controlling cut and paste).
\dt \cw{pterm.NoRemoteResize}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from being able to remotely control
the size of the \cw{pterm} window.
\dt \cw{pterm.NoAltScreen}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from using the \q{alternate screen}
terminal feature, which lets full-screen applications leave the
screen exactly the way they found it.
\dt \cw{pterm.NoRemoteWinTitle}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, it stops the server from remotely controlling the title of
the \cw{pterm} window.
\dt \cw{pterm.NoRemoteQTitle}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, it stops the server from remotely requesting the title of
the \cw{pterm} window.
\lcont{
This feature is a \e{POTENTIAL SECURITY HAZARD}. If a malicious
application can write data to your terminal (for example, if you
merely \cw{cat} a file owned by someone else on the server
machine), it can change your window title (unless you have disabled
this using the \cw{NoRemoteWinTitle} resource) and then use this
service to have the new window title sent back to the server as if
typed at the keyboard. This allows an attacker to fake keypresses
and potentially cause your server-side applications to do things you
didn't want. Therefore this feature is disabled by default, and we
recommend you do not turn it on unless you \e{really} know what
you are doing.
}
\dt \cw{pterm.NoDBackspace}
\dd This option should be set to either 0 or 1; the default is 0.
When set to 1, it disables the normal action of the Delete (\cw{^?})
character when sent from the server to the terminal, which is to
move the cursor left by one space and erase the character now under
it.
\dt \cw{pterm.ApplicationCursorKeys}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, the default initial state of the cursor keys are
application mode (where the keys send function-key-like sequences
instead of numbers or arrow keys). When set to 0, the default state
is the normal one.
\dt \cw{pterm.ApplicationKeypad}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, the default initial state of the numeric keypad is
application mode (where the keys send function-key-like sequences
instead of numbers or arrow keys). When set to 0, the default state
is the normal one.
\dt \cw{pterm.NetHackKeypad}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, the numeric keypad operates in NetHack mode. This is
equivalent to the \cw{\-nethack} command-line option.
\dt \cw{pterm.Answerback}
\dd This option controls the string which the terminal sends in
response to receiving the \cw{^E} character (\q{tell me about
yourself}). By default this string is \q{\cw{PuTTY}}.
\dt \cw{pterm.HideMousePtr}
\dd This option should be set to either 0 or 1; the default is 0. When
it is set to 1, the mouse pointer will disappear if it is over the
\cw{pterm} window and you press a key. It will reappear as soon as
you move it.
\dt \cw{pterm.WindowBorder}
\dd This option controls the number of pixels of space between the text
in the \cw{pterm} window and the window frame. The default is 1.
You can increase this value, but decreasing it to 0 is not
recommended because it can cause the window manager's size hints to
work incorrectly.
\dt \cw{pterm.CurType}
\dd This option should be set to either 0, 1 or 2; the default is 0.
When set to 0, the text cursor displayed in the window is a
rectangular block. When set to 1, the cursor is an underline; when
set to 2, it is a vertical line.
\dt \cw{pterm.BlinkCur}
\dd This option should be set to either 0 or 1; the default is 0. When
it is set to 1, the text cursor will blink when the window is active.
\dt \cw{pterm.Beep}
\dd This option should be set to either 0 or 2 (yes, 2); the default
is 0. When it is set to 2, \cw{pterm} will respond to a bell
character (\cw{^G}) by flashing the window instead of beeping.
\dt \cw{pterm.BellOverload}
\dd This option should be set to either 0 or 1; the default is 0. When
it is set to 1, \cw{pterm} will watch out for large numbers of
bells arriving in a short time and will temporarily disable the bell
until they stop. The idea is that if you \cw{cat} a binary file,
the frantic beeping will mostly be silenced by this feature and will
not drive you crazy.
\lcont{
The bell overload mode is activated by receiving N bells in time T;
after a further time S without any bells, overload mode will turn
itself off again.
Bell overload mode is always deactivated by any keypress in the
terminal. This means it can respond to large unexpected streams of
data, but does not interfere with ordinary command-line activities
that generate beeps (such as filename completion).
}
\dt \cw{pterm.BellOverloadN}
\dd This option counts the number of bell characters which will activate
bell overload if they are received within a length of time T. The
default is 5.
\dt \cw{pterm.BellOverloadT}
\dd This option specifies the time period in which receiving N or more
bells will activate bell overload mode. It is measured in
microseconds, so (for example) set it to 1000000 for one second. The
default is 2000000 (two seconds).
\dt \cw{pterm.BellOverloadS}
\dd This option specifies the time period of silence required to turn
off bell overload mode. It is measured in microseconds, so (for
example) set it to 1000000 for one second. The default is 5000000
(five seconds of silence).
\dt \cw{pterm.ScrollbackLines}
\dd This option specifies how many lines of scrollback to save above the
visible terminal screen. The default is 200. This resource is
equivalent to the \cw{\-sl} command-line option.
\dt \cw{pterm.DECOriginMode}
\dd This option should be set to either 0 or 1; the default is 0. It
specifies the default state of DEC Origin Mode. (If you don't know
what that means, you probably don't need to mess with it.)
\dt \cw{pterm.AutoWrapMode}
\dd This option should be set to either 0 or 1; the default is 1. It
specifies the default state of auto wrap mode. When set to 1, very
long lines will wrap over to the next line on the terminal; when set
to 0, long lines will be squashed against the right-hand edge of the
screen.
\dt \cw{pterm.LFImpliesCR}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, the terminal will return the cursor to the left side of
the screen when it receives a line feed character.
\dt \cw{pterm.WinTitle}
\dd This resource is the same as the \cw{\-T} command-line option:
it controls the initial title of the window. The default is
\q{\cw{pterm}}.
\dt \cw{pterm.TermWidth}
\dd This resource is the same as the width part of the \cw{\-geometry}
command-line option: it controls the number of columns of text in
the window. The default is 80.
\dt \cw{pterm.TermHeight}
\dd This resource is the same as the width part of the \cw{\-geometry}
command-line option: it controls the number of columns of text in
the window. The defaults is 24.
\dt \cw{pterm.Font}
\dd This resource is the same as the \cw{\-fn} command-line option: it
controls the font used to display normal text. The default is
\q{\cw{fixed}}.
\dt \cw{pterm.BoldFont}
\dd This resource is the same as the \cw{\-fb} command-line option: it
controls the font used to display bold text when \cw{BoldAsColour}
is turned off. The default is unset (the font will be bolded by
printing it twice at a one-pixel offset).
\dt \cw{pterm.WideFont}
\dd This resource is the same as the \cw{\-fw} command-line option: it
controls the font used to display double-width characters. The
default is unset (double-width characters cannot be displayed).
\dt \cw{pterm.WideBoldFont}
\dd This resource is the same as the \cw{\-fwb} command-line option: it
controls the font used to display double-width characters in bold,
when \cw{BoldAsColour} is turned off. The default is unset
(double-width characters are displayed in bold by printing them
twice at a one-pixel offset).
\dt \cw{pterm.ShadowBoldOffset}
\dd This resource can be set to an integer; the default is \-1. It
specifies the offset at which text is overprinted when using
\q{shadow bold} mode. The default (1) means that the text will be
printed in the normal place, and also one character to the right;
this seems to work well for most X bitmap fonts, which have a blank
line of pixels down the right-hand side. For some fonts, you may
need to set this to \-1, so that the text is overprinted one pixel
to the left; for really large fonts, you may want to set it higher
than 1 (in one direction or the other).
\dt \cw{pterm.BoldAsColour}
\dd This option should be set to either 0 or 1; the default is 1. It
specifies the default state of auto wrap mode. When set to 1, bold
text is shown by displaying it in a brighter colour; when set to 0,
bold text is shown by displaying it in a heavier font.
\dt \cw{pterm.Colour0}, \cw{pterm.Colour1}, ..., \cw{pterm.Colour21}
\dd These options control the various colours used to display text
in the \cw{pterm} window. Each one should be specified as a triple
of decimal numbers giving red, green and blue values: so that black
is \q{\cw{0,0,0}}, white is \q{\cw{255,255,255}}, red is
\q{\cw{255,0,0}} and so on.
\lcont{
Colours 0 and 1 specify the foreground colour and its bold
equivalent (the \cw{\-fg} and \cw{\-bfg} command-line options).
Colours 2 and 3 specify the background colour and its bold
equivalent (the \cw{\-bg} and \cw{\-bbg} command-line options).
Colours 4 and 5 specify the text and block colours used for the
cursor (the \cw{\-cfg} and \cw{\-cbg} command-line options). Each
even number from 6 to 20 inclusive specifies the colour to be used
for one of the ANSI primary colour specifications (black, red,
green, yellow, blue, magenta, cyan, white, in that order); the odd
numbers from 7 to 21 inclusive specify the bold version of each
colour, in the same order. The defaults are:
\c pterm.Colour0: 187,187,187
\c pterm.Colour1: 255,255,255
\c pterm.Colour2: 0,0,0
\c pterm.Colour3: 85,85,85
\c pterm.Colour4: 0,0,0
\c pterm.Colour5: 0,255,0
\c pterm.Colour6: 0,0,0
\c pterm.Colour7: 85,85,85
\c pterm.Colour8: 187,0,0
\c pterm.Colour9: 255,85,85
\c pterm.Colour10: 0,187,0
\c pterm.Colour11: 85,255,85
\c pterm.Colour12: 187,187,0
\c pterm.Colour13: 255,255,85
\c pterm.Colour14: 0,0,187
\c pterm.Colour15: 85,85,255
\c pterm.Colour16: 187,0,187
\c pterm.Colour17: 255,85,255
\c pterm.Colour18: 0,187,187
\c pterm.Colour19: 85,255,255
\c pterm.Colour20: 187,187,187
\c pterm.Colour21: 255,255,255
}
\dt \cw{pterm.RectSelect}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 0, dragging the mouse over several lines selects to the end
of each line and from the beginning of the next; when set to 1,
dragging the mouse over several lines selects a rectangular region.
In each case, holding down Alt while dragging gives the other
behaviour.
\dt \cw{pterm.MouseOverride}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, if the application requests mouse tracking (so that mouse
clicks are sent to it instead of doing selection), holding down
Shift will revert the mouse to normal selection. When set to 0,
mouse tracking completely disables selection.
\dt \cw{pterm.Printer}
\dd This option is unset by default. If you set it, then
server-controlled printing is enabled: the server can send control
sequences to request data to be sent to a printer. That data will be
piped into the command you specify here; so you might want to set it
to \q{\cw{lpr}}, for example, or \q{\cw{lpr \-Pmyprinter}}.
\dt \cw{pterm.ScrollBar}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 0, the scrollbar is hidden (although Shift-PageUp and
Shift-PageDown still work). This is the same as the \cw{\-sb}
command-line option.
\dt \cw{pterm.ScrollbarOnLeft}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, the scrollbar will be displayed on the left of the
terminal instead of on the right.
\dt \cw{pterm.ScrollOnKey}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, any keypress causes the position of the scrollback to be
reset to the very bottom.
\dt \cw{pterm.ScrollOnDisp}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, any activity in the display causes the position of the
scrollback to be reset to the very bottom.
\dt \cw{pterm.LineCodePage}
\dd This option specifies the character set to be used for the session.
This is the same as the \cw{\-cs} command-line option.
\dt \cw{pterm.NoRemoteCharset}
\dd This option disables the terminal's ability to change its character
set when it receives escape sequences telling it to. You might need
to do this to interoperate with programs which incorrectly change
the character set to something they think is sensible.
\dt \cw{pterm.BCE}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, the various control sequences that erase parts of the
terminal display will erase in whatever the current background
colour is; when set to 0, they will erase in black always.
\dt \cw{pterm.BlinkText}
\dd This option should be set to either 0 or 1; the default is 0. When
set to 1, text specified as blinking by the server will actually
blink on and off; when set to 0, \cw{pterm} will use the less
distracting approach of making the text's background colour bold.
\dt \cw{pterm.StampUtmp}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, \cw{pterm} will log the login in the various system log
files. This resource is equivalent to the \cw{\-ut} command-line
option.
\dt \cw{pterm.LoginShell}
\dd This option should be set to either 0 or 1; the default is 1. When
set to 1, \cw{pterm} will execute your shell as a login shell. This
resource is equivalent to the \cw{\-ls} command-line option.
\S{pterm-manpage-bugs} BUGS
Most of the X resources have silly names. (Historical reasons from
PuTTY, mostly.)

240
puttysrc/DOC/MAN-PUTT.BUT Normal file
View File

@@ -0,0 +1,240 @@
\cfg{man-identity}{putty}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
\H{putty-manpage} Man page for PuTTY
\S{putty-manpage-name} NAME
\cw{putty} - GUI SSH, Telnet and Rlogin client for X
\S{putty-manpage-synopsis} SYNOPSIS
\c putty [ options ] [ host ]
\e bbbbb iiiiiii iiii
\S{putty-manpage-description} DESCRIPTION
\cw{putty} is a graphical SSH, Telnet and Rlogin client for X. It is
a direct port of the Windows SSH client of the same name.
\S{putty-manpage-options} OPTIONS
The command-line options supported by \cw{putty} are:
\dt \cw{\-\-display} \e{display\-name}
\dd Specify the X display on which to open \cw{putty}. (Note this
option has a double minus sign, even though none of the others do.
This is because this option is supplied automatically by GTK.
Sorry.)
\dt \cw{\-fn} \e{font-name}
\dd Specify the font to use for normal text displayed in the terminal.
\dt \cw{\-fb} \e{font-name}
\dd Specify the font to use for bold text displayed in the terminal.
If the \cw{BoldAsColour} resource is set to 1 (the default), bold
text will be displayed in different colours instead of a different
font, so this option will be ignored. If \cw{BoldAsColour} is set to
0 and you do not specify a bold font, \cw{putty} will overprint the
normal font to make it look bolder.
\dt \cw{\-fw} \e{font-name}
\dd Specify the font to use for double-width characters (typically
Chinese, Japanese and Korean text) displayed in the terminal.
\dt \cw{\-fwb} \e{font-name}
\dd Specify the font to use for bold double-width characters
(typically Chinese, Japanese and Korean text). Like \cw{-fb}, this
will be ignored unless the \cw{BoldAsColour} resource is set to 0.
\dt \cw{\-geometry} \e{geometry}
\dd Specify the size of the terminal, in rows and columns of text.
See \e{X(7)} for more information on the syntax of geometry
specifications.
\dt \cw{\-sl} \e{lines}
\dd Specify the number of lines of scrollback to save off the top of the
terminal.
\dt \cw{\-fg} \e{colour}
\dd Specify the foreground colour to use for normal text.
\dt \cw{\-bg} \e{colour}
\dd Specify the background colour to use for normal text.
\dt \cw{\-bfg} \e{colour}
\dd Specify the foreground colour to use for bold text, if the
\cw{BoldAsColour} resource is set to 1 (the default).
\dt \cw{\-bbg} \e{colour}
\dd Specify the foreground colour to use for bold reverse-video
text, if the \cw{BoldAsColour} resource is set to 1 (the default).
(This colour is best thought of as the bold version of the
background colour; so it only appears when text is displayed \e{in}
the background colour.)
\dt \cw{\-cfg} \e{colour}
\dd Specify the foreground colour to use for text covered by the cursor.
\dt \cw{\-cbg} \e{colour}
\dd Specify the background colour to use for text covered by the cursor.
In other words, this is the main colour of the cursor.
\dt \cw{\-title} \e{title}
\dd Specify the initial title of the terminal window. (This can be
changed under control of the server.)
\dt \cw{\-sb\-} or \cw{+sb}
\dd Tells \cw{putty} not to display a scroll bar.
\dt \cw{\-sb}
\dd Tells \cw{putty} to display a scroll bar: this is the opposite of
\cw{\-sb\-}. This is the default option: you will probably only need
to specify it explicitly if you have changed the default using the
\cw{ScrollBar} resource.
\dt \cw{\-log} \e{filename}
\dd This option makes \cw{putty} log all the terminal output to a file
as well as displaying it in the terminal.
\dt \cw{\-cs} \e{charset}
\dd This option specifies the character set in which \cw{putty}
should assume the session is operating. This character set will be
used to interpret all the data received from the session, and all
input you type or paste into \cw{putty} will be converted into
this character set before being sent to the session.
\lcont{ Any character set name which is valid in a MIME header (and
supported by \cw{putty}) should be valid here (examples are
\q{\cw{ISO-8859-1}}, \q{\cw{windows-1252}} or \q{\cw{UTF-8}}). Also,
any character encoding which is valid in an X logical font
description should be valid (\q{\cw{ibm-cp437}}, for example).
\cw{putty}'s default behaviour is to use the same character
encoding as its primary font. If you supply a Unicode
(\cw{iso10646-1}) font, it will default to the UTF-8 character set.
Character set names are case-insensitive.
}
\dt \cw{\-nethack}
\dd Tells \cw{putty} to enable NetHack keypad mode, in which the
numeric keypad generates the NetHack \c{hjklyubn} direction keys.
This enables you to play NetHack with the numeric keypad without
having to use the NetHack \c{number_pad} option (which requires you
to press \q{\cw{n}} before any repeat count). So you can move with
the numeric keypad, and enter repeat counts with the normal number
keys.
\dt \cw{\-help}, \cw{\-\-help}
\dd Display a message summarizing the available options.
\dt \cw{\-pgpfp}
\dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
in verifying new files released by the PuTTY team.
\dt \cw{\-load} \e{session}
\dd Load a saved session by name. This allows you to run a saved session
straight from the command line without having to go through the
configuration box first.
\dt \cw{\-ssh}, \cw{\-telnet}, \cw{\-rlogin}, \cw{\-raw}
\dd Select the protocol \cw{putty} will use to make the connection.
\dt \cw{\-l} \e{username}
\dd Specify the username to use when logging in to the server.
\dt \cw{\-L} \cw{[}\e{srcaddr}\cw{:]}\e{srcport}\cw{:}\e{desthost}\cw{:}\e{destport}
\dd Set up a local port forwarding: listen on \e{srcport} (or
\e{srcaddr}:\e{srcport} if specified), and forward any connections
over the SSH connection to the destination address
\e{desthost}:\e{destport}. Only works in SSH.
\dt \cw{\-R} \cw{[}\e{srcaddr}\cw{:]}\e{srcport}\cw{:}\e{desthost}\cw{:}\e{destport}
\dd Set up a remote port forwarding: ask the SSH server to listen on
\e{srcport} (or \e{srcaddr}:\e{srcport} if specified), and to
forward any connections back over the SSH connection where the
client will pass them on to the destination address
\e{desthost}:\e{destport}. Only works in SSH.
\dt \cw{\-D} [\e{srcaddr}:]\e{srcport}
\dd Set up dynamic port forwarding. The client listens on
\e{srcport} (or \e{srcaddr}:\e{srcport} if specified), and
implements a SOCKS server. So you can point SOCKS-aware applications
at this port and they will automatically use the SSH connection to
tunnel all their connections. Only works in SSH.
\dt \cw{\-P} \e{port}
\dd Specify the port to connect to the server on.
\dt \cw{\-A}, \cw{\-a}
\dd Enable (\cw{\-A}) or disable (\cw{\-a}) SSH agent forwarding.
Currently this only works with OpenSSH and SSH-1.
\dt \cw{\-X}, \cw{\-x}
\dd Enable (\cw{\-X}) or disable (\cw{\-x}) X11 forwarding.
\dt \cw{\-T}, \cw{\-t}
\dd Enable (\cw{\-t}) or disable (\cw{\-T}) the allocation of a
pseudo-terminal at the server end.
\dt \cw{\-C}
\dd Enable zlib-style compression on the connection.
\dt \cw{\-1}, \cw{\-2}
\dd Select SSH protocol version 1 or 2.
\dt \cw{\-i} \e{keyfile}
\dd Specify a private key file to use for authentication. For SSH-2
keys, this key file must be in PuTTY's format, not OpenSSH's or
anyone else's.
\S{putty-manpage-saved-sessions} SAVED SESSIONS
Saved sessions are stored in a \cw{.putty/sessions} subdirectory in
your home directory.
\S{putty-manpage-more-information} MORE INFORMATION
For more information on PuTTY, it's probably best to go and look at
the manual on the web page:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\cw{http://www.chiark.greenend.org.uk/~sgtatham/putty/}
\S{putty-manpage-bugs} BUGS
This man page isn't terribly complete.

3
puttysrc/DOC/MANCFG.BUT Normal file
View File

@@ -0,0 +1,3 @@
\cfg{man-mindepth}{2}
\C{not-shown} Chapter title which is not shown

3
puttysrc/DOC/MANPAGES.BUT Normal file
View File

@@ -0,0 +1,3 @@
\A{man-pages} Man pages for Unix PuTTY
This appendix contains all the man pages for Unix PuTTY.

273
puttysrc/DOC/PAGEANT.BUT Normal file
View File

@@ -0,0 +1,273 @@
\define{versionidpageant} \versionid $Id: pageant.but 6610 2006-03-14 11:21:59Z jacob $
\C{pageant} Using \i{Pageant} for authentication
\cfg{winhelp-topic}{pageant.general}
Pageant is an SSH \i{authentication agent}. It holds your \i{private key}s
in memory, already decoded, so that you can use them often
\I{passwordless login}without needing to type a \i{passphrase}.
\H{pageant-start} Getting started with Pageant
Before you run Pageant, you need to have a private key in \c{*.\i{PPK}}
format. See \k{pubkey} to find out how to generate and use one.
When you run Pageant, it will put an icon of a computer wearing a
hat into the \ii{System tray}. It will then sit and do nothing, until you
load a private key into it.
If you click the Pageant icon with the right mouse button, you will
see a menu. Select \q{View Keys} from this menu. The Pageant main
window will appear. (You can also bring this window up by
double-clicking on the Pageant icon.)
The Pageant window contains a list box. This shows the private keys
Pageant is holding. When you start Pageant, it has no keys, so the
list box will be empty. After you add one or more keys, they will
show up in the list box.
To add a key to Pageant, press the \q{Add Key} button. Pageant will
bring up a file dialog, labelled \q{Select Private Key File}. Find
your private key file in this dialog, and press \q{Open}.
Pageant will now load the private key. If the key is protected by a
passphrase, Pageant will ask you to type the passphrase. When the
key has been loaded, it will appear in the list in the Pageant
window.
Now start PuTTY and open an SSH session to a site that accepts your
key. PuTTY will notice that Pageant is running, retrieve the key
automatically from Pageant, and use it to authenticate. You can now
open as many PuTTY sessions as you like without having to type your
passphrase again.
(PuTTY can be configured not to try to use Pageant, but it will try
by default. See \k{config-ssh-tryagent} and
\k{using-cmdline-agentauth} for more information.)
When you want to shut down Pageant, click the right button on the
Pageant icon in the System tray, and select \q{Exit} from the menu.
Closing the Pageant main window does \e{not} shut down Pageant.
\H{pageant-mainwin} The Pageant main window
The Pageant main window appears when you left-click on the Pageant
system tray icon, or alternatively right-click and select \q{View
Keys} from the menu. You can use it to keep track of what keys are
currently loaded into Pageant, and to add new ones or remove the
existing keys.
\S{pageant-mainwin-keylist} The key list box
\cfg{winhelp-topic}{pageant.keylist}
The large list box in the Pageant main window lists the private keys
that are currently loaded into Pageant. The list might look
something like this:
\c ssh1 1024 22:c3:68:3b:09:41:36:c3:39:83:91:ae:71:b2:0f:04 k1
\c ssh-rsa 1023 74:63:08:82:95:75:e1:7c:33:31:bb:cb:00:c0:89:8b k2
For each key, the list box will tell you:
\b The type of the key. Currently, this can be \c{ssh1} (an RSA key
for use with the SSH-1 protocol), \c{ssh-rsa} (an RSA key for use
with the SSH-2 protocol), or \c{ssh-dss} (a DSA key for use with
the SSH-2 protocol).
\b The size (in bits) of the key.
\b The \I{key fingerprint}fingerprint for the public key. This should be
the same fingerprint given by PuTTYgen, and (hopefully) also the same
fingerprint shown by remote utilities such as \i\c{ssh-keygen} when
applied to your \c{authorized_keys} file.
\b The comment attached to the key.
\S{pageant-mainwin-addkey} The \q{Add Key} button
\cfg{winhelp-topic}{pageant.addkey}
To add a key to Pageant by reading it out of a local disk file,
press the \q{Add Key} button in the Pageant main window, or
alternatively right-click on the Pageant icon in the system tray and
select \q{Add Key} from there.
Pageant will bring up a file dialog, labelled \q{Select Private Key
File}. Find your private key file in this dialog, and press
\q{Open}. If you want to add more than one key at once, you can
select multiple files using Shift-click (to select several adjacent
files) or Ctrl-click (to select non-adjacent files).
Pageant will now load the private key(s). If a key is protected by a
passphrase, Pageant will ask you to type the passphrase.
(This is not the only way to add a private key to Pageant. You can
also add one from a remote system by using agent forwarding; see
\k{pageant-forward} for details.)
\S{pageant-mainwin-remkey} The \q{Remove Key} button
\cfg{winhelp-topic}{pageant.remkey}
If you need to remove a key from Pageant, select that key in the
list box, and press the \q{Remove Key} button. Pageant will remove
the key from its memory.
You can apply this to keys you added using the \q{Add Key} button,
or to keys you added remotely using agent forwarding (see
\k{pageant-forward}); it makes no difference.
\H{pageant-cmdline} The Pageant command line
Pageant can be made to do things automatically when it starts up, by
\I{command-line arguments}specifying instructions on its command line.
If you're starting Pageant from the Windows GUI, you can arrange this
by editing the properties of the \i{Windows shortcut} that it was
started from.
If Pageant is already running, invoking it again with the options
below causes actions to be performed with the existing instance, not a
new one.
\S{pageant-cmdline-loadkey} Making Pageant automatically load keys
on startup
Pageant can automatically load one or more private keys when it
starts up, if you provide them on the Pageant command line. Your
command line might then look like:
\c C:\PuTTY\pageant.exe d:\main.ppk d:\secondary.ppk
If the keys are stored encrypted, Pageant will request the
passphrases on startup.
If Pageant is already running, this syntax loads keys into the
existing Pageant.
\S{pageant-cmdline-command} Making Pageant run another program
You can arrange for Pageant to start another program once it has
initialised itself and loaded any keys specified on its command
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
by the command, like this:
\c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe
\H{pageant-forward} Using \i{agent forwarding}
Agent forwarding is a mechanism that allows applications on your SSH
server machine to talk to the agent on your client machine.
Note that at present, agent forwarding in SSH-2 is only available
when your SSH server is \i{OpenSSH}. The \i\cw{ssh.com} server uses a
different 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
\k{using-cmdline-agent} for details.)
If this has worked, your applications on the server should now have
access to a Unix domain socket which the SSH server will forward
back to PuTTY, and PuTTY will forward on to the agent. To check that
this has actually happened, you can try this command on Unix server
machines:
\c unixbox:~$ echo $SSH_AUTH_SOCK
\c /tmp/ssh-XXNP18Jz/agent.28794
\c unixbox:~$
If the result line comes up blank, agent forwarding has not been
enabled at all.
Now if you run \c{ssh} on the server and use it to connect through
to another server that accepts one of the keys in Pageant, you
should be able to log in without a password:
\c unixbox:~$ ssh -v otherunixbox
\c [...]
\c debug: next auth method to try is publickey
\c debug: userauth_pubkey_agent: trying agent key my-putty-key
\c debug: ssh-userauth2 successful: method publickey
\c [...]
If you enable agent forwarding on \e{that} SSH connection as well
(see the manual for your server-side SSH client to find out how to
do this), your authentication keys will still be available on the
next machine you connect to - two SSH connections away from where
they're actually stored.
In addition, if you have a private key on one of the SSH servers,
you can send it all the way back to Pageant using the local
\i\c{ssh-add} command:
\c unixbox:~$ ssh-add ~/.ssh/id_rsa
\c Need passphrase for /home/fred/.ssh/id_rsa
\c Enter passphrase for /home/fred/.ssh/id_rsa:
\c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
\c unixbox:~$
and then it's available to every machine that has agent forwarding
available (not just the ones downstream of the place you added it).
\H{pageant-security} Security considerations
\I{security risk}Using Pageant for public-key authentication gives you the
convenience of being able to open multiple SSH sessions without
having to type a passphrase every time, but also gives you the
security benefit of never storing a decrypted private key on disk.
Many people feel this is a good compromise between security and
convenience.
It \e{is} a compromise, however. Holding your decrypted private keys
in Pageant is better than storing them in easy-to-find disk files,
but still less secure than not storing them anywhere at all. This is
for two reasons:
\b Windows unfortunately provides no way to protect pieces of memory
from being written to the system \i{swap file}. So if Pageant is holding
your private keys for a long period of time, it's possible that
decrypted private key data may be written to the system swap file,
and an attacker who gained access to your hard disk later on might
be able to recover that data. (However, if you stored an unencrypted
key in a disk file they would \e{certainly} be able to recover it.)
\b Although, like most modern operating systems, Windows prevents
programs from accidentally accessing one another's memory space, it
does allow programs to access one another's memory space
deliberately, for special purposes such as debugging. This means
that if you allow a virus, trojan, or other malicious program on to
your Windows system while Pageant is running, it could access the
memory of the Pageant process, extract your decrypted authentication
keys, and send them back to its master.
Similarly, use of agent \e{forwarding} is a security improvement on
other methods of one-touch authentication, but not perfect. Holding
your keys in Pageant on your Windows box has a security advantage
over holding them on the remote server machine itself (either in an
agent or just unencrypted on disk), because if the server machine
ever sees your unencrypted private key then the sysadmin or anyone
who cracks the machine can steal the keys and pretend to be you for
as long as they want.
However, the sysadmin of the server machine can always pretend to be
you \e{on that machine}. So if you forward your agent to a server
machine, then the sysadmin of that machine can access the forwarded
agent connection and request signatures from your private keys, and
can therefore log in to other machines as you. They can only do this
to a limited extent - when the agent forwarding disappears they lose
the ability - but using Pageant doesn't actually \e{prevent} the
sysadmin (or hackers) on the server from doing this.
Therefore, if you don't trust the sysadmin of a server machine, you
should \e{never} use agent forwarding to that machine. (Of course
you also shouldn't store private keys on that machine, type
passphrases into it, or log into other machines from it in any way
at all; Pageant is hardly unique in this respect.)

141
puttysrc/DOC/PGPKEYS.BUT Normal file
View File

@@ -0,0 +1,141 @@
\define{versionidpgpkeys} \versionid $Id: pgpkeys.but 5598 2005-04-05 19:36:25Z simon $
\A{pgpkeys} PuTTY download keys and signatures
\cfg{winhelp-topic}{pgpfingerprints}
\I{verifying new versions}We create \i{PGP signatures} for all the PuTTY
files distributed from our web site, so that users can be confident
that the files have not been tampered with. Here we identify
our public keys, and explain our signature policy so you can have an
accurate idea of what each signature guarantees.
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
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.
(Note that none of the keys, signatures, etc mentioned here have
anything to do with keys used with SSH - they are purely for verifying
the origin of files distributed by the PuTTY team.)
\H{pgpkeys-pubkey} Public keys
We supply two complete sets of keys. We supply a set of RSA keys,
compatible with both \W{http://www.gnupg.org/}{GnuPG} and PGP2,
and also a set of DSA keys compatible with GnuPG.
In each format, we have three keys:
\b A Development Snapshots key, used to sign the nightly builds.
\b A Releases key, used to sign actual releases.
\b A Master Key. The Master Key is used to sign the other two keys, and
they sign it in return.
Therefore, we have six public keys in total:
\b RSA:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/master-rsa.asc}{Master Key},
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/release-rsa.asc}{Release key},
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/snapshot-rsa.asc}{Snapshot key}
\lcont{
Master Key: 1024-bit; \I{PGP key fingerprint}fingerprint:
\cw{8F\_15\_97\_DA\_25\_30\_AB\_0D\_\_88\_D1\_92\_54\_11\_CF\_0C\_4C}
}
\b DSA:
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/master-dsa.asc}{Master Key},
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/release-dsa.asc}{Release key},
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/keys/snapshot-dsa.asc}{Snapshot key}
\lcont{
Master Key: 1024-bit; fingerprint:
\cw{313C\_3E76\_4B74\_C2C5\_F2AE\_\_83A8\_4F5E\_6DF5\_6A93\_B34E}
}
\H{pgpkeys-security} Security details
The various keys have various different security levels. This
section explains what those security levels are, and how far you can
expect to trust each key.
\S{pgpkeys-snapshot} The Development Snapshots keys
These keys are stored \e{without passphrases}. This is
necessary, because the snapshots are generated every night without
human intervention, so nobody would be able to type a passphrase.
The actual snapshots are built on a team member's home Windows box.
The keys themselves are stored on an independently run Unix box
(the same one that hosts our Subversion repository). After
being built, the binaries are uploaded to this Unix box and then
signed automatically.
Therefore, a signature from one of the Development Snapshots keys
\e{DOES} protect you against:
\b People tampering with the PuTTY binaries between the PuTTY web site
and you.
But it \e{DOES NOT} protect you against:
\b People tampering with the binaries before they are uploaded to the
independent Unix box.
\b The sysadmin of the independent Unix box using his root privilege to
steal the private keys and abuse them, or tampering with the
binaries before they are signed.
\b Somebody getting root on the Unix box.
Of course, we don't believe any of those things is very likely. We
know our sysadmin personally and trust him (both to be competent and
to be non-malicious), and we take all reasonable precautions to
guard the build machine. But when you see a signature, you should
always be certain of precisely what it guarantees and precisely what
it does not.
\S{pgpkeys-release} The Releases keys
The Release keys have passphrases and we can be more careful about
how we use them.
The Release keys are kept safe on the developers' own local
machines, and only used to sign releases that have been built by
hand. A signature from a Release key protects you from almost any
plausible attack.
(Some of the developers' machines have cable modem connections and
might in theory be crackable, but of course the private keys are
still encrypted, so the crack would have to go unnoticed for long
enough to steal a passphrase.)
\S{pgpkeys-master} The Master Keys
The Master Keys sign almost nothing. Their purpose is to bind the
other keys together and certify that they are all owned by the same
people and part of the same integrated setup. The only signatures
produced by the Master Keys, \e{ever}, should be the signatures
on the other keys.
We intend to arrange for the Master Keys to sign each other, to
certify that the DSA keys and RSA keys are part of the same setup.
We have not yet got round to this at the time of writing.
We have collected a few third-party signatures on the Master Keys,
in order to increase the chances that you can find a suitable trust
path to them. We intend to collect more. (Note that the keys on the
keyservers appear to have also collected some signatures from people
who haven't performed any verification of the Master Keys.)
We have uploaded our various keys to public keyservers, so that
even if you don't know any of the people who have signed our
keys, you can still be reasonably confident that an attacker would
find it hard to substitute fake keys on all the public keyservers at
once.

294
puttysrc/DOC/PLINK.BUT Normal file
View File

@@ -0,0 +1,294 @@
\define{versionidplink} \versionid $Id: plink.but 7488 2007-04-29 11:28:54Z simon $
\C{plink} Using the command-line connection tool \i{Plink}
\i{Plink} (PuTTY Link) is a command-line connection tool similar to
UNIX \c{ssh}. It is mostly used for \i{automated operations}, such as
making CVS access a repository on a remote server.
Plink is probably not what you want if you want to run an
\i{interactive session} in a console window.
\H{plink-starting} Starting Plink
Plink is a command line application. This means that you cannot just
double-click on its icon to run it and instead you have to bring up
a \i{console window}. In Windows 95, 98, and ME, this is called an
\q{MS-DOS Prompt}, and in Windows NT, 2000, and XP, it is called a
\q{Command Prompt}. It should be available from the Programs section
of your Start Menu.
In order to use Plink, the file \c{plink.exe} will need either to be
on your \i{\c{PATH}} or in your current directory. To add the
directory containing Plink to your \c{PATH} environment variable,
type into the console window:
\c set PATH=C:\path\to\putty\directory;%PATH%
This will only work for the lifetime of that particular console
window. To set your \c{PATH} more permanently on Windows NT, 2000,
and XP, use the Environment tab of the System Control Panel. On
Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT}
to include a \c{set} command like the one above.
\H{plink-usage} Using Plink
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 just type
\c{plink} on its own 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:
\c Z:\sysosd>plink
\c PuTTY Link: command-line connection utility
\c Release 0.60
\c Usage: plink [options] [user@]host [command]
\c ("host" can also be a PuTTY saved session name)
\c Options:
\c -V print version information and exit
\c -pgpfp print PGP key fingerprints and exit
\c -v show verbose messages
\c -load sessname Load settings from saved session
\c -ssh -telnet -rlogin -raw
\c force use of a particular protocol
\c -P port connect to specified port
\c -l user connect with specified username
\c -batch disable all interactive prompts
\c The following options only apply to SSH connections:
\c -pw passw login with specified password
\c -D [listen-IP:]listen-port
\c Dynamic SOCKS-based port forwarding
\c -L [listen-IP:]listen-port:host:port
\c Forward local port to remote address
\c -R [listen-IP:]listen-port:host:port
\c Forward remote port to local address
\c -X -x enable / disable X11 forwarding
\c -A -a enable / disable agent forwarding
\c -t -T enable / disable pty allocation
\c -1 -2 force use of particular protocol version
\c -4 -6 force use of IPv4 or IPv6
\c -C enable compression
\c -i key private key file for authentication
\c -noagent disable use of Pageant
\c -agent enable use of Pageant
\c -m file read remote command(s) from file
\c -s remote command is an SSH subsystem (SSH-2 only)
\c -N don't start a shell/command (SSH-2 only)
\c -nc host:port
\c open tunnel in place of session (SSH-2 only)
Once this works, you are ready to use Plink.
\S{plink-usage-interactive} Using Plink for interactive logins
To make a simple interactive connection to a remote server, just
type \c{plink} and then the host name:
\c Z:\sysosd>plink login.example.com
\c
\c Debian GNU/Linux 2.2 flunky.example.com
\c flunky login:
You should then be able to log in as normal and run a session. The
output sent by the server will be written straight to your command
prompt window, which will most likely not interpret terminal \i{control
codes} in the way the server expects it to. So if you run any
full-screen applications, for example, you can expect to see strange
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{-telnet}, \c{-rlogin} or \c{-raw}.
To make an SSH connection, for example:
\c Z:\sysosd>plink -ssh login.example.com
\c login as:
If you have already set up a PuTTY saved session, then instead of
supplying a host name, you can give the saved session name. This
allows you to use public-key authentication, specify a user name,
and use most of the other features of PuTTY:
\c Z:\sysosd>plink my-ssh-session
\c Sent username "fred"
\c Authenticating with public key "fred@winbox"
\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
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.)
\S{plink-usage-batch} Using Plink for automated connections
More typically Plink is used with the SSH protocol, to enable you to
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
\k{plink-usage-interactive}.
\b Set up a PuTTY saved session that describes the server you are
connecting to, and that also specifies the protocol as SSH.
\b Set the Windows environment variable \i\c{PLINK_PROTOCOL} to the
word \c{ssh}.
Usually Plink is not invoked directly by a user, but run
automatically by another process. Therefore you typically do not
want Plink to prompt you for a user name or a password.
Next, you are likely to need to avoid the various interactive
prompts Plink can produce. You might be prompted to verify the host
key of the server you're connecting to, to enter a user name, or to
enter a password.
To avoid being prompted for the server host key when using Plink for
an automated connection, you should first make a \e{manual}
connection (using either of PuTTY or Plink) to the same server,
verify the host key (see \k{gs-hostkey} for more information), and
select Yes to add the host key to the Registry. After that, Plink
commands connecting to that server should not give a host key prompt
unless the host key changes.
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 Set up a PuTTY saved session that describes the server you are
connecting to, and that also specifies the username to log in as
(see \k{config-username}).
To avoid being prompted for a password, you should almost certainly
set up \i{public-key authentication}. (See \k{pubkey} for a general
introduction to public-key authentication.) Again, you can do this
in two ways:
\b Set up a PuTTY saved session that describes the server you are
connecting to, and that also specifies a private key file (see
\k{config-ssh-privkey}). For this to work without prompting, your
private key will need to have no passphrase.
\b Store the private key in Pageant. See \k{pageant} for further
information.
Once you have done all this, you should be able to run a remote
command on the SSH server machine and have it execute automatically
with no prompting:
\c Z:\sysosd>plink login.example.com -l fred echo hello, world
\c hello, world
\c
\c Z:\sysosd>
Or, if you have set up a saved session with all the connection
details:
\c Z:\sysosd>plink mysession echo hello, world
\c hello, world
\c
\c Z:\sysosd>
Then you can set up other programs to run this Plink command and
talk to it as if it were a process on the server machine.
\S{plink-options} Plink command line options
Plink accepts all the general command line options supported by the
PuTTY tools. See \k{using-general-opts} for a description of these
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
interactive prompts
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
time, the batch job will fail rather than hang.
\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
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.)
\H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
Once you have set up Plink to be able to log in to a remote server
without any interactive prompting (see \k{plink-usage-batch}), you
can use it for lots of scripting and batch purposes. For example, to
start a backup on a remote machine, you might use a command like:
\c plink root@myserver /etc/backups/do-backup.sh
Or perhaps you want to fetch all system log lines relating to a
particular web area:
\c plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog
Any non-interactive command you could usefully run on the server
command line, you can run in a batch file using Plink in this way.
\H{plink-cvs} Using Plink with \i{CVS}
To use Plink with CVS, you need to set the environment variable
\i\c{CVS_RSH} to point to Plink:
\c set CVS_RSH=\path\to\plink.exe
You also need to arrange to be able to connect to a remote host
without any interactive prompts, as described in
\k{plink-usage-batch}.
You should then be able to run CVS as follows:
\c cvs -d :ext:user@sessionname:/path/to/repository co module
If you specified a username in your saved session, you don't even
need to specify the \q{user} part of this, and you can just say:
\c cvs -d :ext:sessionname:/path/to/repository co module
\H{plink-wincvs} Using Plink with \i{WinCVS}
Plink can also be used with WinCVS. Firstly, arrange for Plink to be
able to connect to a remote host non-interactively, as described in
\k{plink-usage-batch}.
Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
\e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
labelled \q{Check for an alternate \cw{rsh} name} and in the text
entry field to the right enter the full path to \c{plink.exe}.
Select \q{OK} on the \q{Preferences} dialogue box.
Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
a CVS command as in \k{plink-cvs}, for example:
\c cvs -d :ext:user@hostname:/path/to/repository co module
or (if you're using a saved session):
\c cvs -d :ext:user@sessionname:/path/to/repository co module
Select the folder you want to check out to with the \q{Change Folder}
button, and click \q{OK} to check out your module. Once you've got
modules checked out, WinCVS will happily invoke plink from the GUI for
CVS operations.
\# \H{plink-whatelse} Using Plink with... ?

318
puttysrc/DOC/PSCP.BUT Normal file
View File

@@ -0,0 +1,318 @@
\define{versionidpscp} \versionid $Id: pscp.but 7488 2007-04-29 11:28:54Z simon $
\#FIXME: Need examples
\C{pscp} Using \i{PSCP} to transfer files securely
\i{PSCP}, the PuTTY Secure Copy client, is a tool for \i{transferring files}
securely between computers using an SSH connection.
If you have an SSH-2 server, you might prefer PSFTP (see \k{psftp})
for interactive use. PSFTP does not in general work with SSH-1
servers, however.
\H{pscp-starting} Starting PSCP
PSCP is a command line application. This means that you cannot just
double-click on its icon to run it and instead you have to bring up a
\i{console window}. With Windows 95, 98, and ME, this is called an
\q{MS-DOS Prompt} and with Windows NT, 2000, and XP, it is called a
\q{Command Prompt}. It should be available from the Programs section
of your \i{Start Menu}.
To start PSCP it will need either to be on your \i{\c{PATH}} or in your
current directory. To add the directory containing PSCP to your
\c{PATH} environment variable, type into the console window:
\c set PATH=C:\path\to\putty\directory;%PATH%
This will only work for the lifetime of that particular console
window. To set your \c{PATH} more permanently on Windows NT, 2000,
and XP, use the Environment tab of the System Control Panel. On
Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT}
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 just type
\c{pscp} on its own 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:
\c Z:\owendadmin>pscp
\c PuTTY Secure Copy client
\c Release 0.60
\c Usage: pscp [options] [user@]host:source target
\c pscp [options] source [source...] [user@]host:target
\c pscp [options] -ls [user@]host:filespec
\c Options:
\c -V print version information and exit
\c -pgpfp print PGP key fingerprints and exit
\c -p preserve file attributes
\c -q quiet, don't show statistics
\c -r copy directories recursively
\c -v show verbose messages
\c -load sessname Load settings from saved session
\c -P port connect to specified port
\c -l user connect with specified username
\c -pw passw login with specified password
\c -1 -2 force use of particular SSH protocol version
\c -4 -6 force use of IPv4 or IPv6
\c -C enable compression
\c -i key private key file for authentication
\c -noagent disable use of Pageant
\c -agent enable use of Pageant
\c -batch disable all interactive prompts
\c -unsafe allow server-side wildcards (DANGEROUS)
\c -sftp force use of SFTP protocol
\c -scp force use of SCP protocol
(PSCP's interface is much like the Unix \c{scp} command, if you're
familiar with that.)
\S{pscp-usage-basics} The basics
To \I{receiving files}receive (a) file(s) from a remote server:
\c pscp [options] [user@]host:source target
So to copy the file \c{/etc/hosts} from the server \c{example.com} as
user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type:
\c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
To \I{sending files}send (a) file(s) to a remote server:
\c pscp [options] source [source...] [user@]host:target
So to copy the local file \c{c:\\documents\\foo.txt} to the server
\c{example.com} as user \c{fred} to the file \c{/tmp/foo} you would
type:
\c pscp c:\documents\foo.txt fred@example.com:/tmp/foo
You can use \i{wildcards} to transfer multiple files in either
direction, like this:
\c pscp c:\documents\*.doc fred@example.com:docfiles
\c pscp fred@example.com:source/*.c c:\source
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
this file has been disallowed}.
This is due to a \I{security risk}fundamental insecurity in the old-style
\i{SCP protocol}: the client sends the wildcard string (\c{*.c}) to the
server, and the server sends back a sequence of file names that
match the wildcard pattern. However, there is nothing to stop the
server sending back a \e{different} pattern and writing over one of
your other files: if you request \c{*.c}, the server might send back
the file name \c{AUTOEXEC.BAT} and install a virus for you. Since
the wildcard matching rules are decided by the server, the client
cannot reliably verify that the filenames sent back match the
pattern.
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 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:
\c pscp -unsafe fred@example.com:source/*.c c:\source
This will suppress the warning message and the file transfer will
happen. However, you should be aware that by using this option you
are giving the server the ability to write to \e{any} file in the
target directory, so you should only use this option if you trust
the server administrator not to be malicious (and not to let the
server machine be cracked by malicious people). Alternatively, do
any such download in a newly created empty directory. (Even in
\q{unsafe} mode, PSCP will still protect you against the server
trying to get out of that directory using pathnames including
\cq{..}.)
\S2{pscp-usage-basics-user} \c{user}
The \i{login name} on the remote server. If this is omitted, and \c{host}
is a PuTTY saved session, PSCP will use any username specified by that
saved session. Otherwise, PSCP will attempt to use the local Windows
username.
\S2{pscp-usage-basics-host} \I{hostname}\c{host}
The name of the remote server, or the name of an existing PuTTY saved
session. In the latter case, the session's settings for hostname, port
number, cipher type and username will be used.
\S2{pscp-usage-basics-source} \c{source}
One or more source files. \ii{Wildcards} are allowed. The syntax of
wildcards depends on the system to which they apply, so if you are
copying \e{from} a Windows system \e{to} a UNIX system, you should use
Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from}
a UNIX system \e{to} a Windows system, you would use the wildcard
syntax allowed by your UNIX shell (e.g. \c{*}).
If the source is a remote server and you do not specify a full
pathname (in UNIX, a pathname beginning with a \c{/} (slash)
character), what you specify as a source will be interpreted relative
to your \i{home directory} on the remote server.
\S2{pscp-usage-basics-target} \c{target}
The filename or directory to put the file(s). When copying from a
remote server to a local host, you may wish simply to place the
file(s) in the current directory. To do this, you should specify a
target of \c{.}. For example:
\c pscp fred@example.com:/home/tom/.emacs .
...would copy \c{/home/tom/.emacs} on the remote server to the current
directory.
As with the \c{source} parameter, if the target is on a remote server
and is not a full path name, it is interpreted relative to your home
directory on the remote server.
\S{pscp-usage-options} Options
PSCP accepts all the general command line options supported by the
PuTTY tools, except the ones which make no sense in a file transfer
utility. See \k{using-general-opts} for a description of these
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
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:
\c pscp -ls fred@example.com:dir1
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};
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}
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
timestamp on copied files.
\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:
\c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13%
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
these statistics.
\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
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
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
time, the batch job will fail rather than hang.
\S2{pscp-usage-options-backend}\i\c{-sftp}, \i\c{-scp} force use of
particular protocol
As mentioned in \k{pscp-usage-basics}, there are two different file
transfer protocols in use with SSH. Despite its name, PSCP (like many
other ostensible \cw{scp} clients) can use either of these protocols.
The older \i{SCP protocol} does not have a written specification and
leaves a lot of detail to the server platform. \ii{Wildcards} are expanded
on the server. The simple design means that any wildcard specification
supported by the server platform (such as brace expansion) can be
used, but also leads to interoperability issues such as with filename
quoting (for instance, where filenames contain spaces), and also the
security issue described in \k{pscp-usage-basics}.
The newer \i{SFTP} protocol, which is usually associated with SSH-2
servers, is specified in a more platform independent way, and leaves
issues such as wildcard syntax up to the client. (PuTTY's SFTP
wildcard syntax is described in \k{psftp-wildcards}.) This makes it
more consistent across platforms, more suitable for scripting and
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{-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.
\S{pscp-retval} \ii{Return value}
PSCP returns an \i\cw{ERRORLEVEL} of zero (success) only if the files
were correctly transferred. You can test for this in a \i{batch file},
using code such as this:
\c pscp file*.* user@hostname:
\c if errorlevel 1 echo There was an error
\S{pscp-pubkey} Using \i{public key authentication} with PSCP
Like PuTTY, PSCP can authenticate using a public key instead of a
password. There are three ways you can do this.
Firstly, PSCP can use PuTTY saved sessions in place of hostnames
(see \k{pscp-usage-basics-host}). So you would do this:
\b Run PuTTY, and create a PuTTY saved session (see
\k{config-saving}) which specifies your private key file (see
\k{config-ssh-privkey}). You will probably also want to specify a
username to log in as (see \k{config-username}).
\b In PSCP, you can now use the name of the session instead of a
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
information.
Thirdly, PSCP will attempt to authenticate using Pageant if Pageant
is running (see \k{pageant}). So you would do this:
\b Ensure Pageant is running, and has your private key stored in it.
\b Specify a user and host name to PSCP as normal. PSCP will
automatically detect Pageant and try to use the keys within it.
For more general information on public-key authentication, see
\k{pubkey}.

588
puttysrc/DOC/PSFTP.BUT Normal file
View File

@@ -0,0 +1,588 @@
\define{versionidpsftp} \versionid $Id: psftp.but 6717 2006-05-26 12:45:21Z simon $
\C{psftp} Using \i{PSFTP} to transfer files securely
\i{PSFTP}, the PuTTY SFTP client, is a tool for \i{transferring files}
securely between computers using an SSH connection.
PSFTP differs from PSCP in the following ways:
\b PSCP should work on virtually every SSH server. PSFTP uses the
new \i{SFTP} protocol, which is a feature of SSH-2 only. (PSCP will also
use this protocol if it can, but there is an SSH-1 equivalent it can
fall back to if it cannot.)
\b PSFTP allows you to run an interactive file transfer session,
much like the Windows \i\c{ftp} program. You can list the contents of
directories, browse around the file system, issue multiple \c{get}
and \c{put} commands, and eventually log out. By contrast, PSCP is
designed to do a single file transfer operation and immediately
terminate.
\H{psftp-starting} Starting PSFTP
The usual way to start PSFTP is from a command prompt, much like
PSCP. To do this, it will need either to be on your \i{\c{PATH}} or
in your current directory. To add the directory containing PSFTP to
your \c{PATH} environment variable, type into the console window:
\c set PATH=C:\path\to\putty\directory;%PATH%
Unlike PSCP, however, PSFTP has no complex command-line syntax; you
just specify a host name and perhaps a user name:
\c psftp server.example.com
or perhaps
\c psftp fred@server.example.com
Alternatively, if you just type \c{psftp} on its own (or
double-click the PSFTP icon in the Windows GUI), you will see the
PSFTP prompt, and a message telling you PSFTP has not connected to
any server:
\c C:\>psftp
\c psftp: no hostname specified; use "open host.name" to connect
\c psftp>
At this point you can type \c{open server.example.com} or \c{open
fred@server.example.com} to start a session.
PSFTP accepts all the general command line options supported by the
PuTTY tools, except the ones which make no sense in a file transfer
utility. See \k{using-general-opts} for a description of these
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
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
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:
\c cd /home/ftp/users/jeff
\c del jam-old.tar.gz
\c ren jam.tar.gz jam-old.tar.gz
\c put jam.tar.gz
\c chmod a+r jam.tar.gz
and then you could run the script by typing
\c psftp user@hostname -b myscript.scr
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}).
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
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:
\c C:\>psftp fred@hostname -b batchfile
\c Sent username "fred"
\c Remote working directory is /home/fred
\c Listing directory /home/fred/lib
\c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
\c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
\c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
\c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
\c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
you might see this:
\c C:\>psftp fred@hostname -bc -b batchfile
\c Sent username "fred"
\c Remote working directory is /home/fred
\c psftp> dir lib
\c Listing directory /home/fred/lib
\c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
\c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
\c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
\c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
\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
When running a batch file, this additional option causes PSFTP to
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
interactive prompts
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
time, the batch job will fail rather than hang.
\H{psftp-commands} Running PSFTP
Once you have started your PSFTP session, you will see a \c{psftp>}
prompt. You can now type commands to perform file-transfer
functions. This section lists all the available commands.
\S{psftp-quoting} \I{quoting, in PSFTP}General quoting rules for PSFTP commands
Most PSFTP commands are considered by the PSFTP command interpreter
as a sequence of words, separated by spaces. For example, the
command \c{ren oldfilename newfilename} splits up into three words:
\c{ren} (the command name), \c{oldfilename} (the name of the file to
be renamed), and \c{newfilename} (the new name to give the file).
Sometimes you will need to specify \I{spaces in filenames}file names
that \e{contain} spaces. In order to do this, you can surround
the file name with double quotes. This works equally well for
local file names and remote file names:
\c psftp> get "spacey file name.txt" "save it under this name.txt"
The double quotes themselves will not appear as part of the file
names; they are removed by PSFTP and their only effect is to stop
the spaces inside them from acting as word separators.
If you need to \e{use} a double quote (on some types of remote
system, such as Unix, you are allowed to use double quotes in file
names), you can do this by doubling it. This works both inside and
outside double quotes. For example, this command
\c psftp> ren ""this"" "a file with ""quotes"" in it"
will take a file whose current name is \c{"this"} (with a double
quote character at the beginning and the end) and rename it to a
file whose name is \c{a file with "quotes" in it}.
(The one exception to the PSFTP quoting rules is the \c{!} command,
which passes its command line straight to Windows without splitting
it up into words at all. See \k{psftp-cmd-pling}.)
\S{psftp-wildcards} Wildcards in PSFTP
Several commands in PSFTP support \q{\i{wildcards}} to select multiple
files.
For \e{local} file specifications (such as the first argument to
\c{put}), wildcard rules for the local operating system are used. For
instance, PSFTP running on Windows might require the use of \c{*.*}
where PSFTP on Unix would need \c{*}.
For \e{remote} file specifications (such as the first argument to
\c{get}), PSFTP uses a standard wildcard syntax (similar to \i{POSIX}
wildcards):
\b \c{*} matches any sequence of characters (including a zero-length
sequence).
\b \c{?} matches exactly one character.
\b \c{[abc]} matches exactly one character which can be \cw{a},
\cw{b}, or \cw{c}.
\lcont{
\c{[a-z]} matches any character in the range \cw{a} to \cw{z}.
\c{[^abc]} matches a single character that is \e{not} \cw{a}, \cw{b},
or \cw{c}.
Special cases: \c{[-a]} matches a literal hyphen (\cw{-}) or \cw{a};
\c{[^-a]} matches all other characters. \c{[a^]} matches a literal
caret (\cw{^}) or \cw{a}.
}
\b \c{\\} (backslash) before any of the above characters (or itself)
removes that character's special meaning.
A leading period (\cw{.}) on a filename is not treated specially,
unlike in some Unix contexts; \c{get *} will fetch all files, whether
or not they start with a leading period.
\S{psftp-cmd-open} The \c{open} command: start a session
If you started PSFTP by double-clicking in the GUI, or just by
typing \c{psftp} at the command line, you will need to open a
connection to an SFTP server before you can issue any other
commands (except \c{help} and \c{quit}).
To create a connection, type \c{open host.name}, or if you need to
specify a user name as well you can type \c{open user@host.name}.
Once you have issued this command, you will not be able to issue it
again, \e{even} if the command fails (for example, if you mistype
the host name or the connection times out). So if the connection is
not opened successfully, PSFTP will terminate immediately.
\S{psftp-cmd-quit} The \c{quit} command: end your session
When you have finished your session, type the command \c{quit} to
close the connection, terminate PSFTP and return to the command line
(or just close the PSFTP console window if you started it from the
GUI).
You can also use the \c{bye} and \c{exit} commands, which have
exactly the same effect.
\S{psftp-cmd-close} The \c{close} command: close your connection
If you just want to close the network connection but keep PSFTP
running, you can use the \c{close} command. You can then use the
\c{open} command to open a new connection.
\S{psftp-cmd-help} The \c{help} command: get quick online help
If you type \c{help}, PSFTP will give a short list of the available
commands.
If you type \c{help} with a command name - for example, \c{help get}
- then PSFTP will give a short piece of help on that particular
command.
\S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
remote \i{working directory}
PSFTP maintains a notion of your \q{working directory} on the
server. This is the default directory that other commands will
operate on. For example, if you type \c{get filename.dat} then PSFTP
will look for \c{filename.dat} in your remote working directory on
the server.
To change your remote working directory, use the \c{cd} command. If
you don't provide an argument, \c{cd} will return you to your home
directory on the server (more precisely, the remote directory you were
in at the start of the connection).
To display your current remote working directory, type \c{pwd}.
\S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
local \i{working directory}
As well as having a working directory on the remote server, PSFTP
also has a working directory on your local machine (just like any
other Windows process). This is the default local directory that
other commands will operate on. For example, if you type \c{get
filename.dat} then PSFTP will save the resulting file as
\c{filename.dat} in your local working directory.
To change your local working directory, use the \c{lcd} command. To
display your current local working directory, type \c{lpwd}.
\S{psftp-cmd-get} The \c{get} command: fetch a file from the server
To \i{download a file} from the server and store it on your local PC,
you use the \c{get} command.
In its simplest form, you just use this with a file name:
\c get myfile.dat
If you want to store the file locally under a different name,
specify the local file name after the remote one:
\c get myfile.dat newname.dat
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}
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}
from interpreting anything as a switch after it. For example,
\cq{get -- -silly-name-}.)
\S{psftp-cmd-put} The \c{put} command: send a file to the server
To \i{upload a file} to the server from your local PC, you use the
\c{put} command.
In its simplest form, you just use this with a file name:
\c put myfile.dat
If you want to store the file remotely under a different name,
specify the remote file name after the local one:
\c put myfile.dat newname.dat
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}
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-}.)
\S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or
send multiple files
\c{mget} works almost exactly like \c{get}, except that it allows
you to specify more than one file to fetch at once. You can do this
in two ways:
\b by giving two or more explicit file names (\cq{mget file1.txt
file2.txt})
\b by using a wildcard (\cq{mget *.txt}).
Every argument to \c{mget} is treated as the name of a file to fetch
(unlike \c{get}, which will interpret at most one argument like
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
\c{mget}.
\c{mput} is similar to \c{put}, with the same differences.
\S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
\i{resuming file transfers}
If a file transfer fails half way through, and you end up with half
the file stored on your disk, you can resume the file transfer using
the \c{reget} and \c{reput} commands. These work exactly like the
\c{get} and \c{put} commands, but they check for the presence of the
half-written destination file and start transferring from where the
last attempt left off.
The syntax of \c{reget} and \c{reput} is exactly the same as the
syntax of \c{get} and \c{put}:
\c reget myfile.dat
\c reget myfile.dat newname.dat
\c reget -r mydir
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
changes to files or directories already transferred in full.
\S{psftp-cmd-dir} The \c{dir} command: \I{listing files}list remote files
To list the files in your remote working directory, just type
\c{dir}.
You can also list the contents of a different directory by typing
\c{dir} followed by the directory name:
\c dir /home/fred
\c dir sources
And you can list a subset of the contents of a directory by
providing a wildcard:
\c dir /home/fred/*.txt
\c dir sources/*.c
The \c{ls} command works exactly the same way as \c{dir}.
\S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
remote files
\I{changing permissions on files}PSFTP
allows you to modify the file permissions on files and
directories on the server. You do this using the \c{chmod} command,
which works very much like the Unix \c{chmod} command.
The basic syntax is \c{chmod modes file}, where \c{modes} represents
a modification to the file permissions, and \c{file} is the filename
to modify. You can specify multiple files or wildcards. For example:
\c chmod go-rwx,u+w privatefile
\c chmod a+r public*
\c chmod 640 groupfile1 groupfile2
The \c{modes} parameter can be a set of octal digits in the Unix
style. (If you don't know what this means, you probably don't want
to be using it!) Alternatively, it can be a list of permission
modifications, separated by commas. Each modification consists of:
\b The people affected by the modification. This can be \c{u} (the
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
added or removed.
\b The actual permissions being added or removed. These can be
\I{read permission}\c{r} (permission to read the file),
\I{write permission}\c{w} (permission to write to the file), and
\I{execute permission}\c{x} (permission to execute the file, or in
the case of a directory, permission to access files within the
directory).
So the above examples would do:
\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.
\b The second example: \c{a+r} adds read permission for everybody to
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
\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
\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
\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).
\S{psftp-cmd-del} The \c{del} command: delete remote files
To \I{deleting files}delete a file on the server, type \c{del} and
then the filename or filenames:
\c del oldfile.dat
\c del file1.txt file2.txt
\c del *.o
Files will be deleted without further prompting, even if multiple files
are specified.
\c{del} will only delete files. You cannot use it to delete
directories; use \c{rmdir} for that.
The \c{rm} command works exactly the same way as \c{del}.
\S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
To \i{create a directory} on the server, type \c{mkdir} and then the
directory name:
\c mkdir newstuff
You can specify multiple directories to create at once:
\c mkdir dir1 dir2 dir3
\S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
To \i{remove a directory} on the server, type \c{rmdir} and then the
directory name or names:
\c rmdir oldstuff
\c rmdir *.old ancient
Directories will be deleted without further prompting, even if
multiple directories are specified.
Most SFTP servers will probably refuse to remove a directory if the
directory has anything in it, so you will need to delete the
contents first.
\S{psftp-cmd-mv} The \c{mv} command: move and \i{rename remote files}
To rename a single file on the server, type \c{mv}, then the current
file name, and then the new file name:
\c mv oldfile newname
You can also move the file into a different directory and change the
name:
\c mv oldfile dir/newname
To move one or more files into an existing subdirectory, specify the
files (using wildcards if desired), and then the destination
directory:
\c mv file dir
\c mv file1 dir1/file2 dir2
\c mv *.c *.h ..
The \c{rename} and \c{ren} commands work exactly the same way as
\c{mv}.
\S{psftp-cmd-pling} The \c{!} command: run a \i{local Windows command}
You can run local Windows commands using the \c{!} command. This is
the only PSFTP command that is not subject to the command quoting
rules given in \k{psftp-quoting}. If any command line begins with
the \c{!} character, then the rest of the line will be passed
straight to Windows without further translation.
For example, if you want to move an existing copy of a file out of
the way before downloading an updated version, you might type:
\c psftp> !ren myfile.dat myfile.bak
\c psftp> get myfile.dat
using the Windows \c{ren} command to rename files on your local PC.
\H{psftp-pubkey} Using \i{public key authentication} with PSFTP
Like PuTTY, PSFTP can authenticate using a public key instead of a
password. There are three ways you can do this.
Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
So you might do this:
\b Run PuTTY, and create a PuTTY saved session (see
\k{config-saving}) which specifies your private key file (see
\k{config-ssh-privkey}). You will probably also want to specify a
username to log in as (see \k{config-username}).
\b In PSFTP, you can now use the name of the session instead of a
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
information.
Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant
is running (see \k{pageant}). So you would do this:
\b Ensure Pageant is running, and has your private key stored in it.
\b Specify a user and host name to PSFTP as normal. PSFTP will
automatically detect Pageant and try to use the keys within it.
For more general information on public-key authentication, see
\k{pubkey}.

442
puttysrc/DOC/PUBKEY.BUT Normal file
View File

@@ -0,0 +1,442 @@
\define{versionidpubkey} \versionid $Id: pubkey.but 6905 2006-11-15 12:56:48Z jacob $
\C{pubkey} Using public keys for SSH authentication
\H{pubkey-intro} \ii{Public key authentication} - an introduction
Public key authentication is an alternative means of identifying
yourself to a login server, instead of typing a password. It is more
secure and more flexible, but more difficult to set up.
In conventional password authentication, you prove you are who you
claim to be by proving that you know the correct password. The only
way to prove you know the password is to tell the server what you
think the password is. This means that if the server has been
hacked, or \i\e{spoofed} (see \k{gs-hostkey}), an attacker can learn
your password.
Public key authentication solves this problem. You generate a \i\e{key
pair}, consisting of a \i{public key} (which everybody is allowed to
know) and a \i{private key} (which you keep secret and do not give to
anybody). The private key is able to generate \i\e{signatures}.
A signature created using your private key cannot be forged by
anybody who does not have that key; but anybody who has your public
key can verify that a particular signature is genuine.
So you generate a key pair on your own computer, and you copy the
public key to the server. Then, when the server asks you to prove
who you are, PuTTY can generate a signature using your private key.
The server can verify that signature (since it has your public key)
and allow you to log in. Now if the server is hacked or spoofed, the
attacker does not gain your private key or password; they only gain
one signature. And signatures cannot be re-used, so they have gained
nothing.
There is a problem with this: if your private key is stored
unprotected on your own computer, then anybody who gains access to
\e{that} will be able to generate signatures as if they were you. So
they will be able to log in to your server under your account. For
this reason, your private key is usually \i\e{encrypted} when it is
stored on your local machine, using a \i{passphrase} of your choice. In
order to generate a signature, PuTTY must decrypt the key, so you
have to type your passphrase.
This can make public-key authentication less convenient than
password authentication: every time you log in to the server,
instead of typing a short password, you have to type a longer
passphrase. One solution to this is to use an \i\e{authentication
agent}, a separate program which holds decrypted private keys and
generates signatures on request. PuTTY's authentication agent is
called \i{Pageant}. When you begin a Windows session, you start Pageant
and load your private key into it (typing your passphrase once). For
the rest of your session, you can start PuTTY any number of times
and Pageant will automatically generate signatures without you
having to do anything. When you close your Windows session, Pageant
shuts down, without ever having stored your decrypted private key on
disk. Many people feel this is a good compromise between security
and convenience. See \k{pageant} for further details.
There is more than one \i{public-key algorithm} available. The most
common is \i{RSA}, but others exist, notably \i{DSA} (otherwise known as
DSS), the USA's federal Digital Signature Standard. The key types
supported by PuTTY are described in \k{puttygen-keytype}.
\H{pubkey-puttygen} Using \i{PuTTYgen}, the PuTTY key generator
\cfg{winhelp-topic}{puttygen.general}
PuTTYgen is a key generator. It \I{generating keys}generates pairs of
public and private keys to be used with PuTTY, PSCP, and Plink, as well
as the PuTTY authentication agent, Pageant (see \k{pageant}). PuTTYgen
generates RSA and DSA keys.
When you run PuTTYgen you will see a window where you have two
choices: \q{Generate}, to generate a new public/private key pair, or
\q{Load} to load in an existing private key.
\S{puttygen-generating} Generating a new key
This is a general outline of the procedure for generating a new key
pair. The following sections describe the process in more detail.
\b First, you need to select which type of key you want to generate,
and also select the strength of the key. This is described in more
detail in \k{puttygen-keytype} and
\k{puttygen-strength}.
\b Then press the \q{Generate} button, to actually generate the key.
\K{puttygen-generate} describes this step.
\b Once you have generated the key, select a comment field
(\k{puttygen-comment}) and a passphrase (\k{puttygen-passphrase}).
\b Now you're ready to save the private key to disk; press the
\q{Save private key} button. (See \k{puttygen-savepriv}).
Your key pair is now ready for use. You may also want to copy the
public key to your server, either by copying it out of the \q{Public
key for pasting into authorized_keys file} box (see
\k{puttygen-pastekey}), or by using the \q{Save public key} button
(\k{puttygen-savepub}). However, you don't need to do this
immediately; if you want, you can load the private key back into
PuTTYgen later (see \k{puttygen-load}) and the public key will be
available for copying and pasting again.
\K{pubkey-gettingready} describes the typical process of configuring
PuTTY to attempt public-key authentication, and configuring your SSH
server to accept it.
\S{puttygen-keytype} Selecting the type of key
\cfg{winhelp-topic}{puttygen.keytype}
Before generating a key pair using PuTTYgen, you need to select
which type of key you need. PuTTYgen currently supports three types
of key:
\b An \i{RSA} key for use with the SSH-1 protocol.
\b An RSA key for use with the SSH-2 protocol.
\b A \i{DSA} key for use with the SSH-2 protocol.
The SSH-1 protocol only supports RSA keys; if you will be connecting
using the SSH-1 protocol, you must select the first key type or your
key will be completely useless.
The SSH-2 protocol supports more than one key type. The two types
supported by PuTTY are RSA and DSA.
The PuTTY developers \e{strongly} recommend you use RSA.
\I{security risk}\i{DSA} has an intrinsic weakness which makes it very
easy to create a signature which contains enough information to give
away the \e{private} key!
This would allow an attacker to pretend to be you for any number of
future sessions. PuTTY's implementation has taken very careful
precautions to avoid this weakness, but we cannot be 100% certain we
have managed it, and if you have the choice we strongly recommend
using RSA keys instead.
If you really need to connect to an SSH server which only supports
DSA, then you probably have no choice but to use DSA. If you do use
DSA, we recommend you do not use the same key to authenticate with
more than one server.
\S{puttygen-strength} Selecting the size (strength) of the key
\cfg{winhelp-topic}{puttygen.bits}
The \q{Number of bits} input box allows you to choose the strength
of the key PuTTYgen will generate.
Currently 1024 bits should be sufficient for most purposes.
Note that an RSA key is generated by finding two primes of half the
length requested, and then multiplying them together. For example,
if you ask PuTTYgen for a 1024-bit RSA key, it will create two
512-bit primes and multiply them. The result of this multiplication
might be 1024 bits long, or it might be only 1023; so you may not
get the exact length of key you asked for. This is perfectly normal,
and you do not need to worry. The lengths should only ever differ by
one, and there is no perceptible drop in security as a result.
DSA keys are not created by multiplying primes together, so they
should always be exactly the length you asked for.
\S{puttygen-generate} The \q{Generate} button
\cfg{winhelp-topic}{puttygen.generate}
Once you have chosen the type of key you want, and the strength of
the key, press the \q{Generate} button and PuTTYgen will begin the
process of actually generating the key.
First, a progress bar will appear and PuTTYgen will ask you to move
the mouse around to generate randomness. Wave the mouse in circles
over the blank area in the PuTTYgen window, and the progress bar
will gradually fill up as PuTTYgen collects enough randomness. You
don't need to wave the mouse in particularly imaginative patterns
(although it can't hurt); PuTTYgen will collect enough randomness
just from the fine detail of \e{exactly} how far the mouse has moved
each time Windows samples its position.
When the progress bar reaches the end, PuTTYgen will begin creating
the key. The progress bar will reset to the start, and gradually
move up again to track the progress of the key generation. It will
not move evenly, and may occasionally slow down to a stop; this is
unfortunately unavoidable, because key generation is a random
process and it is impossible to reliably predict how long it will
take.
When the key generation is complete, a new set of controls will
appear in the window to indicate this.
\S{puttygen-fingerprint} The \q{\ii{Key fingerprint}} box
\cfg{winhelp-topic}{puttygen.fingerprint}
The \q{Key fingerprint} box shows you a fingerprint value for the
generated key. This is derived cryptographically from the \e{public}
key value, so it doesn't need to be kept secret.
The fingerprint value is intended to be cryptographically secure, in
the sense that it is computationally infeasible for someone to
invent a second key with the same fingerprint, or to find a key with
a particular fingerprint. So some utilities, such as the Pageant key
list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add}
utility, will list key fingerprints rather than the whole public key.
\S{puttygen-comment} Setting a comment for your key
\cfg{winhelp-topic}{puttygen.comment}
If you have more than one key and use them for different purposes,
you don't need to memorise the key fingerprints in order to tell
them apart. PuTTYgen allows you to enter a \e{comment} for your key,
which will be displayed whenever PuTTY or Pageant asks you for the
passphrase.
The default comment format, if you don't specify one, contains the
key type and the date of generation, such as \c{rsa-key-20011212}.
Another commonly used approach is to use your name and the name of
the computer the key will be used on, such as \c{simon@simons-pc}.
To alter the key comment, just type your comment text into the
\q{Key comment} box before saving the private key. If you want to
change the comment later, you can load the private key back into
PuTTYgen, change the comment, and save it again.
\S{puttygen-passphrase} Setting a \i{passphrase} for your key
\cfg{winhelp-topic}{puttygen.passphrase}
The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to
choose a passphrase for your key. The passphrase will be used to
\i{encrypt} the key on disk, so you will not be able to use the key
without first entering the passphrase.
When you save the key, PuTTYgen will check that the \q{Key passphrase}
and \q{Confirm passphrase} boxes both contain exactly the same
passphrase, and will refuse to save the key otherwise.
If you leave the passphrase fields blank, the key will be saved
unencrypted. You should \e{not} do this without good reason; if you
do, your private key file on disk will be all an attacker needs to
gain access to any machine configured to accept that key. If you
want to be able to \i{passwordless login}log in without having to
type a passphrase every time, you should consider using Pageant
(\k{pageant}) so that your decrypted key is only held in memory
rather than on disk.
Under special circumstances you may genuinely \e{need} to use a key
with no passphrase; for example, if you need to run an automated
batch script that needs to make an SSH connection, you can't be
there to type the passphrase. In this case we recommend you generate
a special key for each specific batch script (or whatever) that
needs one, and on the server side you should arrange that each key
is \e{restricted} so that it can only be used for that specific
purpose. The documentation for your SSH server should explain how to
do this (it will probably vary between servers).
Choosing a good passphrase is difficult. Just as you shouldn't use a
dictionary word as a password because it's easy for an attacker to
run through a whole dictionary, you should not use a song lyric,
quotation or other well-known sentence as a passphrase. \i{DiceWare}
(\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using
at least five words each generated randomly by rolling five dice,
which gives over 2^64 possible passphrases and is probably not a bad
scheme. If you want your passphrase to make grammatical sense, this
cuts down the possibilities a lot and you should use a longer one as
a result.
\e{Do not forget your passphrase}. There is no way to recover it.
\S{puttygen-savepriv} Saving your private key to a disk file
\cfg{winhelp-topic}{puttygen.savepriv}
Once you have generated a key, set a comment field and set a
passphrase, you are ready to save your private key to disk.
Press the \q{Save private key} button. PuTTYgen will put up a dialog
box asking you where to save the file. Select a directory, type in a
file name, and press \q{Save}.
This file is in PuTTY's native format (\c{*.\i{PPK}}); it is the one you
will need to tell PuTTY to use for authentication (see
\k{config-ssh-privkey}) or tell Pageant to load (see
\k{pageant-mainwin-addkey}).
\S{puttygen-savepub} Saving your public key to a disk file
\cfg{winhelp-topic}{puttygen.savepub}
RFC 4716 specifies a \I{SSH-2 public key format}standard format for
storing SSH-2 public keys on disk. Some SSH servers (such as
\i\cw{ssh.com}'s) require a public key in this format in order to accept
authentication with the corresponding private key. (Others, such as
OpenSSH, use a different format; see \k{puttygen-pastekey}.)
To save your public key in the SSH-2 standard format, press the
\q{Save public key} button in PuTTYgen. PuTTYgen will put up a
dialog box asking you where to save the file. Select a directory,
type in a file name, and press \q{Save}.
You will then probably want to copy the public key file to your SSH
server machine. See \k{pubkey-gettingready} for general instructions
on configuring public-key authentication once you have generated a
key.
If you use this option with an SSH-1 key, the file PuTTYgen saves
will contain exactly the same text that appears in the \q{Public key
for pasting} box. This is the only existing standard for SSH-1
public keys.
\S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys
file}}
\cfg{winhelp-topic}{puttygen.pastekey}
All SSH-1 servers require your public key to be given to it in a
one-line format before it will accept authentication with your
private key. The \i{OpenSSH} server also requires this for SSH-2.
The \q{Public key for pasting into authorized_keys file} gives the
public-key data in the correct one-line format. Typically you will
want to select the entire contents of the box using the mouse, press
Ctrl+C to copy it to the clipboard, and then paste the data into a
PuTTY session which is already connected to the server.
See \k{pubkey-gettingready} for general instructions on configuring
public-key authentication once you have generated a key.
\S{puttygen-load} Reloading a private key
\cfg{winhelp-topic}{puttygen.load}
PuTTYgen allows you to load an existing private key file into
memory. If you do this, you can then change the passphrase and
comment before saving it again; you can also make extra copies of
the public key.
To load an existing key, press the \q{Load} button. PuTTYgen will
put up a dialog box where you can browse around the file system and
find your key file. Once you select the file, PuTTYgen will ask you
for a passphrase (if necessary) and will then display the key
details in the same way as if it had just generated the key.
If you use the Load command to load a foreign key format, it will
work, but you will see a message box warning you that the key you
have loaded is not a PuTTY native key. See \k{puttygen-conversions}
for information about importing foreign key formats.
\S{puttygen-conversions} Dealing with private keys in other formats
\cfg{winhelp-topic}{puttygen.conversions}
Most SSH-1 clients use a standard format for storing private keys on
disk. PuTTY uses this format as well; so if you have generated an
SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use
it with PuTTY, and vice versa.
However, SSH-2 private keys have no standard format. \I{OpenSSH private
key format}OpenSSH and \I{ssh.com private key format}\cw{ssh.com} have
different formats, and PuTTY's is different again.
So a key generated with one client cannot immediately be used with
another.
Using the \I{importing keys}\q{Import} command from the \q{Conversions}
menu, PuTTYgen can load SSH-2 private keys in OpenSSH's format and
\cw{ssh.com}'s format. Once you have loaded one of these key types, you
can then save it back out as a PuTTY-format key (\c{*.\i{PPK}}) so that
you can use it with the PuTTY suite. The passphrase will be unchanged by this
process (unless you deliberately change it). You may want to change
the key comment before you save the key, since OpenSSH's SSH-2 key
format contains no space for a comment and \cw{ssh.com}'s default
comment format is long and verbose.
PuTTYgen can also \i{export private keys} in OpenSSH format and in
\cw{ssh.com} format. To do so, select one of the \q{Export} options
from the \q{Conversions} menu. Exporting a key works exactly like
saving it (see \k{puttygen-savepriv}) - you need to have typed your
passphrase in beforehand, and you will be warned if you are about to
save a key without a passphrase.
Note that since only SSH-2 keys come in different formats, the export
options are not available if you have generated an SSH-1 key.
\H{pubkey-gettingready} Getting ready for public key authentication
Connect to your SSH server using PuTTY with the SSH protocol. When the
connection succeeds you will be prompted for your user name and
password to login. Once logged in, you must configure the server to
accept your public key for authentication:
\b If your server is using the SSH-1 protocol, you should change
into the \i\c{.ssh} directory and open the file \i\c{authorized_keys}
with your favourite editor. (You may have to create this file if
this is the first key you have put in it). Then switch to the
PuTTYgen window, select all of the text in the \q{Public key for
pasting into authorized_keys file} box (see \k{puttygen-pastekey}),
and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the
PuTTY window and insert the data into the open file, making sure it
ends up all on one line. Save the file.
\b If your server is \i{OpenSSH} and is using the SSH-2 protocol, you
should follow the same instructions, except that in earlier versions
of OpenSSH 2 the file might be called \c{authorized_keys2}. (In
modern versions the same \c{authorized_keys} file is used for both
SSH-1 and SSH-2 keys.)
\b If your server is \i\cw{ssh.com}'s product and is using SSH-2, you
need to save a \e{public} key file from PuTTYgen (see
\k{puttygen-savepub}), and copy that into the \i\c{.ssh2} directory on
the server. Then you should go into that \c{.ssh2} directory, and edit
(or create) a file called \c{authorization}. In this file you should
put a line like \c{Key mykey.pub}, with \c{mykey.pub} replaced by the
name of your key file.
\b For other SSH server software, you should refer to the manual for
that server.
You may also need to ensure that your home directory, your \c{.ssh}
directory, and any other files involved (such as
\c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are
not group-writable or world-writable. You can typically do this by
using a command such as
\c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
Your server should now be configured to accept authentication using
your private key. Now you need to configure PuTTY to \e{attempt}
authentication using your private key. You can do this in any of
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.
See \k{using-cmdline-identity} for details.
\b Load the private key into Pageant (see \k{pageant}). In this case
PuTTY will automatically try to use it for authentication if it can.

4
puttysrc/DOC/SITE.BUT Normal file
View File

@@ -0,0 +1,4 @@
\# Additional configuration for the version of the PuTTY docs
\# actually published as HTML on the website.
\cfg{xhtml-head-end}{<link rel='stylesheet' href='sitestyle.css' type='text/css' />}

389
puttysrc/DOC/UDP.BUT Normal file
View File

@@ -0,0 +1,389 @@
\# This file is so named for tradition's sake: it contains what we
\# always used to refer to, before they were written down, as
\# PuTTY's `unwritten design principles'. It has nothing to do with
\# the User Datagram Protocol.
\define{versionidudp} \versionid $Id: udp.but 5525 2005-03-19 02:29:57Z jacob $
\A{udp} PuTTY hacking guide
This appendix lists a selection of the design principles applying to
the PuTTY source code. If you are planning to send code
contributions, you should read this first.
\H{udp-portability} Cross-OS portability
Despite Windows being its main area of fame, PuTTY is no longer a
Windows-only application suite. It has a working Unix port; a Mac
port is in progress; more ports may or may not happen at a later
date.
Therefore, embedding Windows-specific code in core modules such as
\cw{ssh.c} is not acceptable. We went to great lengths to \e{remove}
all the Windows-specific stuff from our core modules, and to shift
it out into Windows-specific modules. Adding large amounts of
Windows-specific stuff in parts of the code that should be portable
is almost guaranteed to make us reject a contribution.
The PuTTY source base is divided into platform-specific modules and
platform-generic modules. The Unix-specific modules are all in the
\c{unix} subdirectory; the Mac-specific modules are in the \c{mac}
subdirectory; the Windows-specific modules are in the \c{windows}
subdirectory.
All the modules in the main source directory - notably \e{all} of
the code for the various back ends - are platform-generic. We want
to keep them that way.
This also means you should stick to what you are guaranteed by
ANSI/ISO C (that is, the original C89/C90 standard, not C99). Try
not to make assumptions about the precise size of basic types such
as \c{int} and \c{long int}; don't use pointer casts to do
endianness-dependent operations, and so on.
(There are one or two aspects of ANSI C portability which we
\e{don't} care about. In particular, we expect PuTTY to be compiled
on 32-bit architectures \e{or bigger}; so it's safe to assume that
\c{int} is at least 32 bits wide, not just the 16 you are guaranteed
by ANSI C. Similarly, we assume that the execution character
encoding is a superset of the printable characters of ASCII, though
we don't assume the numeric values of control characters,
particularly \cw{'\\n'} and \cw{'\\r'}.)
\H{udp-multi-backend} Multiple backends treated equally
PuTTY is not an SSH client with some other stuff tacked on the side.
PuTTY is a generic, multiple-backend, remote VT-terminal client
which happens to support one backend which is larger, more popular
and more useful than the rest. Any extra feature which can possibly
be general across all backends should be so: localising features
unnecessarily into the SSH back end is a design error. (For example,
we had several code submissions for proxy support which worked by
hacking \cw{ssh.c}. Clearly this is completely wrong: the
\cw{network.h} abstraction is the place to put it, so that it will
apply to all back ends equally, and indeed we eventually put it
there after another contributor sent a better patch.)
The rest of PuTTY should try to avoid knowing anything about
specific back ends if at all possible. To support a feature which is
only available in one network protocol, for example, the back end
interface should be extended in a general manner such that \e{any}
back end which is able to provide that feature can do so. If it so
happens that only one back end actually does, that's just the way it
is, but it shouldn't be relied upon by any code.
\H{udp-globals} Multiple sessions per process on some platforms
Some ports of PuTTY - notably the in-progress Mac port - are
constrained by the operating system to run as a single process
potentially managing multiple sessions.
Therefore, the platform-independent parts of PuTTY never use global
variables to store per-session data. The global variables that do
exist are tolerated because they are not specific to a particular
login session: \c{flags} defines properties that are expected to
apply equally to \e{all} the sessions run by a single PuTTY process,
the random number state in \cw{sshrand.c} and the timer list in
\cw{timing.c} serve all sessions equally, and so on. But most data
is specific to a particular network session, and is therefore stored
in dynamically allocated data structures, and pointers to these
structures are passed around between functions.
Platform-specific code can reverse this decision if it likes. The
Windows code, for historical reasons, stores most of its data as
global variables. That's OK, because \e{on Windows} we know there is
only one session per PuTTY process, so it's safe to do that. But
changes to the platform-independent code should avoid introducing
global variables, unless they are genuinely cross-session.
\H{udp-pure-c} C, not C++
PuTTY is written entirely in C, not in C++.
We have made \e{some} effort to make it easy to compile our code
using a C++ compiler: notably, our \c{snew}, \c{snewn} and
\c{sresize} macros explicitly cast the return values of \cw{malloc}
and \cw{realloc} to the target type. (This has type checking
advantages even in C: it means you never accidentally allocate the
wrong size piece of memory for the pointer type you're assigning it
to. C++ friendliness is really a side benefit.)
We want PuTTY to continue being pure C, at least in the
platform-independent parts and the currently existing ports. Patches
which switch the Makefiles to compile it as C++ and start using
classes will not be accepted. Also, in particular, we disapprove of
\cw{//} comments, at least for the moment. (Perhaps once C99 becomes
genuinely widespread we might be more lenient.)
The one exception: a port to a new platform may use languages other
than C if they are necessary to code on that platform. If your
favourite PDA has a GUI with a C++ API, then there's no way you can
do a port of PuTTY without using C++, so go ahead and use it. But
keep the C++ restricted to that platform's subdirectory; if your
changes force the Unix or Windows ports to be compiled as C++, they
will be unacceptable to us.
\H{udp-security} Security-conscious coding
PuTTY is a network application and a security application. Assume
your code will end up being fed deliberately malicious data by
attackers, and try to code in a way that makes it unlikely to be a
security risk.
In particular, try not to use fixed-size buffers for variable-size
data such as strings received from the network (or even the user).
We provide functions such as \cw{dupcat} and \cw{dupprintf}, which
dynamically allocate buffers of the right size for the string they
construct. Use these wherever possible.
\H{udp-multi-compiler} Independence of specific compiler
Windows PuTTY can currently be compiled with any of four Windows
compilers: MS Visual C, Borland's freely downloadable C compiler,
the Cygwin / \cw{mingw32} GNU tools, and \cw{lcc-win32}.
This is a really useful property of PuTTY, because it means people
who want to contribute to the coding don't depend on having a
specific compiler; so they don't have to fork out money for MSVC if
they don't already have it, but on the other hand if they \e{do}
have it they also don't have to spend effort installing \cw{gcc}
alongside it. They can use whichever compiler they happen to have
available, or install whichever is cheapest and easiest if they
don't have one.
Therefore, we don't want PuTTY to start depending on which compiler
you're using. Using GNU extensions to the C language, for example,
would ruin this useful property (not that anyone's ever tried it!);
and more realistically, depending on an MS-specific library function
supplied by the MSVC C library (\cw{_snprintf}, for example) is a
mistake, because that function won't be available under the other
compilers. Any function supplied in an official Windows DLL as part
of the Windows API is fine, and anything defined in the C library
standard is also fine, because those should be available
irrespective of compilation environment. But things in between,
available as non-standard library and language extensions in only
one compiler, are disallowed.
(\cw{_snprintf} in particular should be unnecessary, since we
provide \cw{dupprintf}; see \k{udp-security}.)
Compiler independence should apply on all platforms, of course, not
just on Windows.
\H{udp-small} Small code size
PuTTY is tiny, compared to many other Windows applications. And it's
easy to install: it depends on no DLLs, no other applications, no
service packs or system upgrades. It's just one executable. You
install that executable wherever you want to, and run it.
We want to keep both these properties - the small size, and the ease
of installation - if at all possible. So code contributions that
depend critically on external DLLs, or that add a huge amount to the
code size for a feature which is only useful to a small minority of
users, are likely to be thrown out immediately.
We do vaguely intend to introduce a DLL plugin interface for PuTTY,
whereby seriously large extra features can be implemented in plugin
modules. The important thing, though, is that those DLLs will be
\e{optional}; if PuTTY can't find them on startup, it should run
perfectly happily and just won't provide those particular features.
A full installation of PuTTY might one day contain ten or twenty
little DLL plugins, which would cut down a little on the ease of
installation - but if you really needed ease of installation you
\e{could} still just install the one PuTTY binary, or just the DLLs
you really needed, and it would still work fine.
Depending on \e{external} DLLs is something we'd like to avoid if at
all possible (though for some purposes, such as complex SSH
authentication mechanisms, it may be unavoidable). If it can't be
avoided, the important thing is to follow the same principle of
graceful degradation: if a DLL can't be found, then PuTTY should run
happily and just not supply the feature that depended on it.
\H{udp-single-threaded} Single-threaded code
PuTTY and its supporting tools, or at least the vast majority of
them, run in only one OS thread.
This means that if you're devising some piece of internal mechanism,
there's no need to use locks to make sure it doesn't get called by
two threads at once. The only way code can be called re-entrantly is
by recursion.
That said, most of Windows PuTTY's network handling is triggered off
Windows messages requested by \cw{WSAAsyncSelect()}, so if you call
\cw{MessageBox()} deep within some network event handling code you
should be aware that you might be re-entered if a network event
comes in and is passed on to our window procedure by the
\cw{MessageBox()} message loop.
Also, the front ends (in particular Windows Plink) can use multiple
threads if they like. However, Windows Plink keeps \e{very} tight
control of its auxiliary threads, and uses them pretty much
exclusively as a form of \cw{select()}. Pretty much all the code
outside \cw{windows/winplink.c} is \e{only} ever called from the one
primary thread; the others just loop round blocking on file handles
and send messages to the main thread when some real work needs
doing. This is not considered a portability hazard because that bit
of \cw{windows/winplink.c} will need rewriting on other platforms in
any case.
One important consequence of this: PuTTY has only one thread in
which to do everything. That \q{everything} may include managing
more than one login session (\k{udp-globals}), managing multiple
data channels within an SSH session, responding to GUI events even
when nothing is happening on the network, and responding to network
requests from the server (such as repeat key exchange) even when the
program is dealing with complex user interaction such as the
re-configuration dialog box. This means that \e{almost none} of the
PuTTY code can safely block.
\H{udp-keystrokes} Keystrokes sent to the server wherever possible
In almost all cases, PuTTY sends keystrokes to the server. Even
weird keystrokes that you think should be hot keys controlling
PuTTY. Even Alt-F4 or Alt-Space, for example. If a keystroke has a
well-defined escape sequence that it could usefully be sending to
the server, then it should do so, or at the very least it should be
configurably able to do so.
To unconditionally turn a key combination into a hot key to control
PuTTY is almost always a design error. If a hot key is really truly
required, then try to find a key combination for it which \e{isn't}
already used in existing PuTTYs (either it sends nothing to the
server, or it sends the same thing as some other combination). Even
then, be prepared for the possibility that one day that key
combination might end up being needed to send something to the
server - so make sure that there's an alternative way to invoke
whatever PuTTY feature it controls.
\H{udp-640x480} 640\u00D7{x}480 friendliness in configuration panels
There's a reason we have lots of tiny configuration panels instead
of a few huge ones, and that reason is that not everyone has a
1600\u00D7{x}1200 desktop. 640\u00D7{x}480 is still a viable
resolution for running Windows (and indeed it's still the default if
you start up in safe mode), so it's still a resolution we care
about.
Accordingly, the PuTTY configuration box, and the PuTTYgen control
window, are deliberately kept just small enough to fit comfortably
on a 640\u00D7{x}480 display. If you're adding controls to either of
these boxes and you find yourself wanting to increase the size of
the whole box, \e{don't}. Split it into more panels instead.
\H{udp-makefiles-auto} Automatically generated \cw{Makefile}s
PuTTY is intended to compile on multiple platforms, and with
multiple compilers. It would be horrifying to try to maintain a
single \cw{Makefile} which handled all possible situations, and just
as painful to try to directly maintain a set of matching
\cw{Makefile}s for each different compilation environment.
Therefore, we have moved the problem up by one level. In the PuTTY
source archive is a file called \c{Recipe}, which lists which source
files combine to produce which binaries; and there is also a script
called \cw{mkfiles.pl}, which reads \c{Recipe} and writes out the
real \cw{Makefile}s. (The script also reads all the source files and
analyses their dependencies on header files, so we get an extra
benefit from doing it this way, which is that we can supply correct
dependency information even in environments where it's difficult to
set up an automated \c{make depend} phase.)
You should \e{never} edit any of the PuTTY \cw{Makefile}s directly.
They are not stored in our source repository at all. They are
automatically generated by \cw{mkfiles.pl} from the file \c{Recipe}.
If you need to add a new object file to a particular binary, the
right thing to do is to edit \c{Recipe} and re-run \cw{mkfiles.pl}.
This will cause the new object file to be added in every tool that
requires it, on every platform where it matters, in every
\cw{Makefile} to which it is relevant, \e{and} to get all the
dependency data right.
If you send us a patch that modifies one of the \cw{Makefile}s, you
just waste our time, because we will have to convert it into a
change to \c{Recipe}. If you send us a patch that modifies \e{all}
of the \cw{Makefile}s, you will have wasted a lot of \e{your} time
as well!
(There is a comment at the top of every \cw{Makefile} in the PuTTY
source archive saying this, but many people don't seem to read it,
so it's worth repeating here.)
\H{udp-ssh-coroutines} Coroutines in \cw{ssh.c}
Large parts of the code in \cw{ssh.c} are structured using a set of
macros that implement (something close to) Donald Knuth's
\q{coroutines} concept in C.
Essentially, the purpose of these macros are to arrange that a
function can call \cw{crReturn()} to return to its caller, and the
next time it is called control will resume from just after that
\cw{crReturn} statement.
This means that any local (automatic) variables declared in such a
function will be corrupted every time you call \cw{crReturn}. If you
need a variable to persist for longer than that, you \e{must} make
it a field in one of the persistent state structures: either the
local state structures \c{s} or \c{st} in each function, or the
backend-wide structure \c{ssh}.
See
\W{http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html}\c{http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html}
for a more in-depth discussion of what these macros are for and how
they work.
\H{udp-compile-once} Single compilation of each source file
The PuTTY build system for any given platform works on the following
very simple model:
\b Each source file is compiled precisely once, to produce a single
object file.
\b Each binary is created by linking together some combination of
those object files.
Therefore, if you need to introduce functionality to a particular
module which is only available in some of the tool binaries (for
example, a cryptographic proxy authentication mechanism which needs
to be left out of PuTTYtel to maintain its usability in
crypto-hostile jurisdictions), the \e{wrong} way to do it is by
adding \cw{#ifdef}s in (say) \cw{proxy.c}. This would require
separate compilation of \cw{proxy.c} for PuTTY and PuTTYtel, which
means that the entire \cw{Makefile}-generation architecture (see
\k{udp-makefiles-auto}) would have to be significantly redesigned.
Unless you are prepared to do that redesign yourself, \e{and}
guarantee that it will still port to any future platforms we might
decide to run on, you should not attempt this!
The \e{right} way to introduce a feature like this is to put the new
code in a separate source file, and (if necessary) introduce a
second new source file defining the same set of functions, but
defining them as stubs which don't provide the feature. Then the
module whose behaviour needs to vary (\cw{proxy.c} in this example)
can call the functions defined in these two modules, and it will
either provide the new feature or not provide it according to which
of your new modules it is linked with.
Of course, object files are never shared \e{between} platforms; so
it is allowable to use \cw{#ifdef} to select between platforms. This
happens in \cw{puttyps.h} (choosing which of the platform-specific
include files to use), and also in \cw{misc.c} (the Windows-specific
\q{Minefield} memory diagnostic system). It should be used
sparingly, though, if at all.
\H{udp-perfection} Do as we say, not as we do
The current PuTTY code probably does not conform strictly to \e{all}
of the principles listed above. There may be the occasional
SSH-specific piece of code in what should be a backend-independent
module, or the occasional dependence on a non-standard X library
function under Unix.
This should not be taken as a licence to go ahead and violate the
rules. Where we violate them ourselves, we're not happy about it,
and we would welcome patches that fix any existing problems. Please
try to help us make our code better, not worse!

894
puttysrc/DOC/USING.BUT Normal file
View File

@@ -0,0 +1,894 @@
\define{versionidusing} \versionid $Id: using.but 7295 2007-02-18 14:02:39Z jacob $
\C{using} Using PuTTY
This chapter provides a general introduction to some more advanced
features of PuTTY. For extreme detail and reference purposes,
\k{config} is likely to contain more information.
\H{using-session} During your session
A lot of PuTTY's complexity and features are in the configuration
panel. Once you have worked your way through that and started
a session, things should be reasonably simple after that.
Nevertheless, there are a few more useful features available.
\S{using-selection} Copying and pasting text
\I{copy and paste}Often in a PuTTY session you will find text on
your terminal screen which you want to type in again. Like most
other terminal emulators, PuTTY allows you to copy and paste the
text rather than having to type it again. Also, copy and paste uses
the \I{Windows clipboard}Windows \i{clipboard}, so that you can
paste (for example) URLs into a web browser, or paste from a word
processor or spreadsheet into your terminal session.
PuTTY's copy and paste works entirely with the \i{mouse}. In order
to copy text to the clipboard, you just click the \i{left mouse
button} in the \i{terminal window}, and drag to \I{selecting text}select
text. When you let go of the button, the text is \e{automatically}
copied to the clipboard. You do not need to press Ctrl-C or
Ctrl-Ins; in fact, if you do press Ctrl-C, PuTTY will send a Ctrl-C
character down your session to the server where it will probably
cause a process to be interrupted.
Pasting is done using the right button (or the middle mouse button,
if you have a \i{three-button mouse} and have set it up; see
\k{config-mouse}). (Pressing \i{Shift-Ins}, or selecting \q{Paste}
from the \I{right mouse button, with Ctrl}Ctrl+right-click
\i{context menu}, have the same effect.) When
you click the \i{right mouse button}, PuTTY will read whatever is in
the Windows clipboard and paste it into your session, \e{exactly} as
if it had been typed at the keyboard. (Therefore, be careful of
pasting formatted text into an editor that does automatic indenting;
you may find that the spaces pasted from the clipboard plus the
spaces added by the editor add up to too many spaces and ruin the
formatting. There is nothing PuTTY can do about this.)
If you \i{double-click} the left mouse button, PuTTY will
\I{selecting words}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. (You can adjust precisely what PuTTY
considers to be part of a word; see \k{config-charclasses}.)
If you \e{triple}-click, or \i{triple-click} and drag, then
PuTTY will \I{selecting lines}select a whole line or sequence of lines.
If you want to select a \I{rectangular selection}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
\k{config-rectselect} for details.)
If you have a \i{middle mouse button}, then you can use it to
\I{adjusting a selection}adjust an existing selection if you
selected something slightly wrong. (If you have configured the
middle mouse button to paste, then the right mouse button does this
instead.) Click the button on the screen, and you can pick up the
nearest end of the selection and drag it to somewhere else.
It's possible for the server to ask to \I{mouse reporting}handle mouse
clicks in the PuTTY window itself. If this happens, the \i{mouse pointer}
will turn into an arrow, and using the mouse to copy and paste will only
work if you hold down Shift. See \k{config-features-mouse} and
\k{config-mouseshift} for details of this feature and how to configure
it.
\S{using-scrollback} \I{scrollback}Scrolling the screen back
PuTTY keeps track of text that has scrolled up off the top of the
terminal. So if something appears on the screen that you want to
read, but it scrolls too fast and it's gone by the time you try to
look for it, you can use the \i{scrollbar} on the right side of the
window to look back up the session \i{history} and find it again.
As well as using the scrollbar, you can also page the scrollback up
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
preserved for you to look at. You can increase (or decrease) this
value using the configuration box; see \k{config-scrollback}.
\S{using-sysmenu} The \ii{System menu}
If you click the left mouse button on the icon in the top left
corner of PuTTY's terminal window, or click the right mouse button
on the title bar, you will see the standard Windows system menu
containing items like Minimise, Move, Size and Close.
PuTTY's system menu contains extra program features in addition to
the Windows standard options. These extra menu commands are
described below.
(These options are also available in a \i{context menu} brought up
by holding Ctrl and clicking with the right mouse button anywhere
in the \i{PuTTY window}.)
\S2{using-eventlog} The PuTTY \i{Event Log}
If you choose \q{Event Log} from the system menu, a small window
will pop up in which PuTTY logs significant events during the
connection. Most of the events in the log will probably take place
during session startup, but a few can occur at any point in the
session, and one or two occur right at the end.
You can use the mouse to select one or more lines of the Event Log,
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.
\S2{using-specials} \ii{Special commands}
Depending on the protocol used for the current session, there may be
a submenu of \q{special commands}. These are protocol-specific
tokens, such as a \q{break} signal, that can be sent down a
connection in addition to normal data. Their precise effect is usually
up to the server. Currently only Telnet, SSH, and serial connections
have special commands.
The \q{break} signal can also be invoked from the keyboard with
\i{Ctrl-Break}.
The following \I{Telnet special commands}special commands are
available in Telnet:
\b \I{Are You There, Telnet special command}Are You There
\b \I{Break, Telnet special command}Break
\b \I{Synch, Telnet special command}Synch
\b \I{Erase Character, Telnet special command}Erase Character
\lcont{
PuTTY can also be configured to send this when the Backspace key is
pressed; see \k{config-telnetkey}.
}
\b \I{Erase Line, Telnet special command}Erase Line
\b \I{Go Ahead, Telnet special command}Go Ahead
\b \I{No Operation, Telnet special command}No Operation
\lcont{
Should have no effect.
}
\b \I{Abort Process, Telnet special command}Abort Process
\b \I{Abort Output, Telnet special command}Abort Output
\b \I{Interrupt Process, Telnet special command}Interrupt Process
\lcont{
PuTTY can also be configured to send this when Ctrl-C is typed; see
\k{config-telnetkey}.
}
\b \I{Suspend Process, Telnet special command}Suspend Process
\lcont{
PuTTY can also be configured to send this when Ctrl-Z is typed; see
\k{config-telnetkey}.
}
\b \I{End Of Record, Telnet special command}End Of Record
\b \I{End Of File, Telnet special command}End Of File
In an SSH connection, the following \I{SSH special commands}special
commands are available:
\b \I{IGNORE message, SSH special command}\I{No-op, in SSH}\ii{IGNORE message}
\lcont{
Should have no effect.
}
\b \I{Repeat key exchange, SSH special command}Repeat key exchange
\lcont{
Only available in SSH-2. Forces a \i{repeat key exchange} immediately (and
resets associated timers and counters). For more information about
repeat key exchanges, see \k{config-ssh-kex-rekey}.
}
\b \I{Break, SSH special command}Break
\lcont{
Only available in SSH-2, and only during a session. Optional
extension; may not be supported by server. PuTTY requests the server's
default break length.
}
\b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc)
\lcont{
Only available in SSH-2, and only during a session. Sends various
POSIX signals. Not honoured by all servers.
}
With a serial connection, the only available special command is
\I{Break, serial special command}\q{Break}.
\S2{using-newsession} Starting new sessions
PuTTY's system menu provides some shortcut ways to start new
sessions:
\b Selecting \i{\q{New Session}} will start a completely new
instance of PuTTY, and bring up the configuration box as normal.
\b Selecting \i{\q{Duplicate Session}} will start a session in a
new window with precisely the same options as your current one -
connecting to the same host using the same protocol, with all the
same terminal settings and everything.
\b In an inactive window, selecting \i{\q{Restart Session}} will
do the same as \q{Duplicate Session}, but in the current window.
\b The \i{\q{Saved Sessions} submenu} gives you quick access to any
sets of stored session details you have previously saved. See
\k{config-saving} for details of how to create saved sessions.
\S2{using-changesettings} \I{settings, changing}Changing your
session settings
If you select \i{\q{Change Settings}} from the system menu, PuTTY will
display a cut-down version of its initial configuration box. This
allows you to adjust most properties of your current session. You
can change the terminal size, the font, the actions of various
keypresses, the colours, and so on.
Some of the options that are available in the main configuration box
are not shown in the cut-down Change Settings box. These are usually
options which don't make sense to change in the middle of a session
(for example, you can't switch from SSH to Telnet in mid-session).
You can save the current settings to a saved session for future use
from this dialog box. See \k{config-saving} for more on saved
sessions.
\S2{using-copyall} \i{Copy All to Clipboard}
This system menu option provides a convenient way to copy the whole
contents of the terminal screen (up to the last nonempty line) and
scrollback to the \i{clipboard} in one go.
\S2{reset-terminal} \I{scrollback, clearing}Clearing and
\I{terminal, resetting}resetting the terminal
The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY
to discard all the lines of text that have been kept after they
scrolled off the top of the screen. This might be useful, for
example, if you displayed sensitive information and wanted to make
sure nobody could look over your shoulder and see it. (Note that
this only prevents a casual user from using the scrollbar to view
the information; the text is not guaranteed not to still be in
PuTTY's memory.)
The \i{\q{Reset Terminal}} option causes a full reset of the
\i{terminal emulation}. A VT-series terminal is a complex piece of
software and can easily get into a state where all the text printed
becomes unreadable. (This can happen, for example, if you
accidentally output a binary file to your terminal.) If this
happens, selecting Reset Terminal should sort it out.
\S2{using-fullscreen} \ii{Full screen} mode
If you find the title bar on a maximised window to be ugly or
distracting, you can select Full Screen mode to maximise PuTTY
\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; see \k{config-scrollback}.)
When you are in full-screen mode, you can still access the \i{system
menu} if you click the left mouse button in the \e{extreme} top left
corner of the screen.
\H{using-logging} Creating a \i{log file} of your \I{session
log}session
For some purposes you may find you want to log everything that
appears on your screen. You can do this using the \q{Logging}
panel in the configuration box.
To begin a session log, select \q{Change Settings} from the system
menu and go to the Logging panel. Enter a log file name, and select
a logging mode. (You can log all session output including the
terminal \i{control sequence}s, or you can just log the printable text.
It depends what you want the log for.) Click \q{Apply} and your log
will be started. Later on, you can go back to the Logging panel and
select \q{Logging turned off completely} to stop logging; then PuTTY
will close the log file and you can safely read it.
See \k{config-logging} for more details and options.
\H{using-translation} Altering your \i{character set} configuration
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.
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
select, and other related options. Now all you need is to find out
which of them you want! (See \k{config-translation} for more
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.
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
install itself as display number 0 on your local machine; if it
doesn't, the manual for the \i{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 \i{\q{X display location}} box is blank by default, which
means that PuTTY will try to use a sensible default such as \c{:0},
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 \i{\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 \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.
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:
\b Choose a \i{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. (You can also use a local loopback
address here; see below for more details.)
\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 \I{remote
port forwarding}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 \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).
The source port for a forwarded connection usually does not accept
connections from any machine except the \I{localhost}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 (including
dynamic 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 honour it (in \i{OpenSSH}, for example, it's usually
disabled by default).
You can also specify an \i{IP address} to \I{listen address}listen
on. Typically a Windows machine can be asked to listen on any single
IP address in the \cw{127.*.*.*} range, and all of these are
\i{loopback address}es available only to the local machine. So if
you forward (for example) \c{127.0.0.5:79} to a remote machine's
\i\cw{finger} port, then you should be able to run commands such as
\c{finger fred@127.0.0.5}.
This can be useful if the program connecting to the forwarded port
doesn't allow you to change the port number it uses. This feature is
available for local-to-remote forwarded ports; SSH-1 is unable to
support it for remote-to-local ports, while SSH-2 can support it in
theory but servers will not necessarily cooperate.
(Note that if you're using Windows XP Service Pack 2, you may need
to obtain a fix from Microsoft in order to use addresses like
\cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
\H{using-rawprot} Making \i{raw TCP connections}
A lot of \I{debugging Internet protocols}Internet protocols are
composed of commands and responses in plain text. For example,
\i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the
protocol used to transfer Usenet news), and \i{HTTP} (the protocol
used to serve Web pages) all consist of commands in readable plain
text.
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, \I{\q{Raw}
protocol}\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-serial} Connecting to a local serial line
PuTTY can connect directly to a local serial line as an alternative
to making a network connection. In this mode, text typed into the
PuTTY window will be sent straight out of your computer's serial
port, and data received through that port will be displayed in the
PuTTY window. You might use this mode, for example, if your serial
port is connected to another computer which has a serial connection.
To make a connection of this type, simply select \q{Serial} from the
\q{Connection type} radio buttons on the \q{Session} configuration
panel (see \k{config-hostname}). The \q{Host Name} and \q{Port}
boxes will transform into \q{Serial line} and \q{Speed}, allowing
you to specify which serial line to use (if your computer has more
than one) and what speed (baud rate) to use when transferring data.
For further configuration options (data bits, stop bits, parity,
flow control), you can use the \q{Serial} configuration panel (see
\k{config-serial}).
After you start up PuTTY in serial mode, you might find that you
have to make the first move, by sending some data out of the serial
line in order to notify the device at the other end that someone is
there for it to talk to. This probably depends on the device. If you
start up a PuTTY serial session and nothing appears in the window,
try pressing Return a few times and see if that helps.
A serial line provides no well defined means for one end of the
connection to notify the other that the connection is finished.
Therefore, PuTTY in serial mode will remain connected until you
close the window using the close button.
\H{using-cmdline} The PuTTY command line
PuTTY can be made to do various things without user intervention by
supplying \i{command-line arguments} (e.g., from a \i{command prompt
window}, or a \i{Windows shortcut}).
\S{using-cmdline-session} Starting a session from the command line
\I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}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 \i{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 \i{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} \i\c{-cleanup}
\cfg{winhelp-topic}{options.cleanup}
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).
Note that on \i{multi-user systems}, \c{-cleanup} only removes
registry entries and files associated with the currently logged-in
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} \i\c{-load}: load a saved session
\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.
You need double quotes around the session name if it contains spaces.
If you want to create a \i{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 \i\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 \i\c{-ssh} selects the SSH protocol.
\b \i\c{-telnet} selects the Telnet protocol.
\b \i\c{-rlogin} selects the Rlogin protocol.
\b \i\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 \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
\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
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}
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} \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
command line. The command-line options work just like the ones in
Unix \c{ssh} programs.
To \I{local port forwarding}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
To forward a \I{remote port forwarding}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
To \I{listen address}specify an IP address for the listening end of the
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
only have to pass the port number:
\c putty -D 4096 -load mysession
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} \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
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 local file name, and it will read a command from that file.
With some servers (particularly Unix systems), you can even put
multiple lines in this file and execute more than one command in
sequence, or a whole shell script; but this is arguably an abuse, and
cannot be expected to work on all servers. In particular, it is known
\e{not} to work with certain \q{embedded} servers, such as \i{Cisco}
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}
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.)
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{-pw}: specify a \i{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-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
are using SSH.
See \k{pageant} for general information on \i{Pageant}.
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
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 \i{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} \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
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} \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
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-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
command on the remote server. You might want to use this option if
you are only using the SSH connection for port forwarding, and your
user account on the server does not have the ability to run a shell.
This feature is only available in SSH protocol version 2 (since the
version 1 protocol assumes you will always want to run a shell).
This option is equivalent to the \q{Don't start a shell or command
at all} checkbox in the SSH panel of the PuTTY configuration box
(see \k{config-ssh-noshell}).
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
connection} in place of a remote shell or command
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,
with a colon separating the host name from the port number, like
this:
\c plink host1.example.com -nc host2.example.com:1234
You might want to use this feature if you needed to make an SSH
connection to a target host which you can only reach by going
through a proxy host, and rather than using port forwarding you
prefer to use the local proxy feature (see \k{config-proxy-type} for
more about local proxies). In this situation you might select
\q{Local} proxy type, set your local proxy command to be \cq{plink
%proxyhost -nc %host:%port}, enter the target host name on the
Session panel, and enter the directly reachable proxy host name on
the Proxy panel.
This feature is only available in SSH protocol version 2 (since the
version 1 protocol assumes you will always want to run a shell). It
is not available in the file transfer tools PSCP and PSFTP. It is
available in PuTTY itself, although it is unlikely to be very useful
in any tool other than Plink. Also, \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
\W{http://www.vulnwatch.org/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
depend on the \c{nc} program being installed on the server.)
\S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{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} \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
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}).
\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
protocol \i{IPv4} or the newer \i{IPv6}.
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}
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.
For general information on \i{public-key authentication}, see
\k{pubkey}.
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-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.

36
puttysrc/DOC/VIDS.BUT Normal file
View File

@@ -0,0 +1,36 @@
\# Invoke the versionid macros defined in all the other manual
\# chapter files.
\versionidblurb
\versionidintro
\versionidgs
\versionidusing
\versionidconfig
\versionidpscp
\versionidpsftp
\versionidplink
\versionidpubkey
\versionidpageant
\versioniderrors
\versionidfaq
\versionidfeedback
\versionidlicence
\versionidudp
\versionidpgpkeys
\versionidindex