Initial checkin of an outline for the PuTTY user manual.

[originally from svn r865]

doc/Makefile

@@ -0,0 +1,11 @@
+CHAPTERS = blurb intro gs config pscp plink pubkey pageant trouble
+
+INPUTS = $(patsubst %,%.but,$(CHAPTERS))
+
+# This is temporary. Hack it locally or something.
+BUTTRESS = $(HOME)/src/buttress/build/buttress
+
+Contents.html: $(INPUTS)
+	$(HOME)/src/buttress/build/buttress $(INPUTS)
+	rm -f index.html
+	ln -s Contents.html index.html

doc/blurb.but

@@ -0,0 +1,12 @@
+\title PuTTY User Manual
+
+\cfg{xhtml-leaf-smallest-contents}{2}
+
+\cfg{xhtml-leaf-contains-contents}{true}
+
+\preamble PuTTY is a free (MIT-licensed) Win32 Telnet and SSH
+client. This manual documents PuTTY, and its companion utilities
+PSCP, Plink, Pageant and PuTTYgen.
+
+\copyright Copyright 2001 Simon Tatham. All rights reserved. You may
+distribute this documentation under the MIT licence.

doc/config.but

@@ -0,0 +1,4 @@
+\C{config} Configuring PuTTY
+
+\# Walk the user through the whole config box explaining all the
+\# options.

doc/gs.but

@@ -0,0 +1,3 @@
+\C{gs} Getting started with PuTTY
+
+\# Walk the user through starting an SSH or Telnet session.

doc/intro.but

@@ -0,0 +1,11 @@
+\C{intro} Introduction to PuTTY
+
+\# PuTTY is an SSH and Telnet client
+
+\# Section on `what is Telnet? what is SSH?' for the people who
+\# don't have the first clue what they are. Explain what they're
+\# good for and why you might want to use one, and explain under
+\# what conditions you might _not_ want to use one.
+
+\# Section on `what's the difference between Telnet and SSH?' where
+\# we evangelise - POLITELY! - about SSH and security

doc/pageant.but

@@ -0,0 +1,63 @@
+\C{pageant} Using Pageant for authentication
+
+Pageant is an SSH authentication agent. It holds your private keys
+in memory, already decoded, so that you can use them often without
+needing to type a passphrase.
+
+Currently, Pageant only works with SSH v1.
+
+\H{pageant-start} Getting started with Pageant
+
+Before you run Pageant, you need to have a private key. See [FIXME:
+chapter unwritten] 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 System tray. It will then sit and do nothing.
+
+If you click the Pageant icon with the right mouse button, you will
+see a menu. Select \e{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.
+
+To add a key to Pageant, press the \e{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 \e{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.
+
+When you want to shut down Pageant, click the right button on the
+Pageant icon in the System tray, and select \e{Exit} from the menu.
+Closing the Pageant main window does \e{not} shut down Pageant.
+
+\H{pageant-forward} Using agent forwarding
+
+\# Walk the user through enabling agent forwarding and starting a
+\# second-level session.
+
+\# Demonstrate the use of ssh-add at the remote end.
+
+\H{pageant-security} Security considerations
+
+\# Explain that local use of Pageant allows you convenient one-touch
+\# authentication without ever storing a decrypted key on disk
+
+\# Explain that, despite this, it still doesn't protect you against
+\# your local machine being hacked (swap files, but more importantly
+\# trojans)
+
+\# Explain that forwarding agent connections to a remote site
+\# can be abused by the sysadmin of that site, so you'd better know
+\# you can trust them

doc/plink.but

@@ -0,0 +1,12 @@
+\C{plink} Using the command-line connection tool Plink
+
+\# Explain Plink
+
+\# Explain that Plink is probably not what you want if you want to
+\# run an interactive session in a Command Prompt window
+
+\# Explain that Plink is really for batch-file use, and that
+\# therefore it works best with public-key authentication; link to
+\# that chapter
+
+\# Give instructions on how to set up Plink with CVS

doc/pscp.but

@@ -0,0 +1,6 @@
+\C{pscp} Using PSCP to transfer files securely
+
+\# Explain PSCP: the command line, the modes of use (local->remote
+\# and remote->local, recursive, wildcards).
+
+\# Link to iXplorer.

doc/pubkey.but

@@ -0,0 +1,16 @@
+\C{pubkey} Using public keys for SSH authentication
+
+\# Explain the basic principles of public key authentication. Many
+\# people don't have the faintest idea what it is or why it's good.
+
+\# Explain the dangers of leaving an unprotected private key around.
+\# Explain passphrases, and urge that people NEVER store
+\# unpassphrased keys unless they really need to or they can be sure
+\# the machine is secure.
+
+\# Mention a good length for a passphrase. (I think Schneier
+\# said something about this on counterpane.com once.)
+
+\# In case people don't like the idea of exchanging a short password
+\# typed every time for a longer passphrase typed every time, link
+\# to the Pageant chapter.

doc/trouble.but

@@ -0,0 +1,4 @@
+\C{trouble} Troubleshooting PuTTY
+
+\# This chapter should accumulate common problems as they come up.
+\# It's conceptually the bug-hunting part of the FAQ.