From e5b0d077dd2623867702f2e76afb776856eb77b4 Mon Sep 17 00:00:00 2001 From: simon Date: Wed, 17 Jan 2001 10:11:16 +0000 Subject: [PATCH] Initial checkin of an outline for the PuTTY user manual. git-svn-id: svn://svn.tartarus.org/sgt/putty@865 cda61777-01e9-0310-a592-d414129be87e --- doc/Makefile | 11 ++++++++++ doc/blurb.but | 12 +++++++++++ doc/config.but | 4 ++++ doc/gs.but | 3 +++ doc/intro.but | 11 ++++++++++ doc/pageant.but | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/plink.but | 12 +++++++++++ doc/pscp.but | 6 ++++++ doc/pubkey.but | 16 +++++++++++++++ doc/trouble.but | 4 ++++ 10 files changed, 142 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/blurb.but create mode 100644 doc/config.but create mode 100644 doc/gs.but create mode 100644 doc/intro.but create mode 100644 doc/pageant.but create mode 100644 doc/plink.but create mode 100644 doc/pscp.but create mode 100644 doc/pubkey.but create mode 100644 doc/trouble.but diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..18d30e38 --- /dev/null +++ b/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 diff --git a/doc/blurb.but b/doc/blurb.but new file mode 100644 index 00000000..521d300f --- /dev/null +++ b/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. diff --git a/doc/config.but b/doc/config.but new file mode 100644 index 00000000..6c5d64f6 --- /dev/null +++ b/doc/config.but @@ -0,0 +1,4 @@ +\C{config} Configuring PuTTY + +\# Walk the user through the whole config box explaining all the +\# options. diff --git a/doc/gs.but b/doc/gs.but new file mode 100644 index 00000000..9e75be72 --- /dev/null +++ b/doc/gs.but @@ -0,0 +1,3 @@ +\C{gs} Getting started with PuTTY + +\# Walk the user through starting an SSH or Telnet session. diff --git a/doc/intro.but b/doc/intro.but new file mode 100644 index 00000000..bc1c49a2 --- /dev/null +++ b/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 diff --git a/doc/pageant.but b/doc/pageant.but new file mode 100644 index 00000000..a5827601 --- /dev/null +++ b/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 diff --git a/doc/plink.but b/doc/plink.but new file mode 100644 index 00000000..12b08bb3 --- /dev/null +++ b/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 diff --git a/doc/pscp.but b/doc/pscp.but new file mode 100644 index 00000000..57003d0d --- /dev/null +++ b/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. diff --git a/doc/pubkey.but b/doc/pubkey.but new file mode 100644 index 00000000..937ca27b --- /dev/null +++ b/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. diff --git a/doc/trouble.but b/doc/trouble.but new file mode 100644 index 00000000..feb6d856 --- /dev/null +++ b/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. -- 2.11.0