Unix Pageant: man page and online help.

I think Unix Pageant is now more or less usable, though of course I
wouldn't blame anyone for sticking with other SSH agent solutions.

diff --git a/doc/Makefile b/doc/Makefile
index 96a19eb175a55273b0f46eae835065f55c0511a5..0477cb3070dd96a1cd588a6cbd87cf64c3e6d9f6 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -58,7 +58,8 @@ 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
+MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1 \
+           pageant.1
 man: $(MANPAGES)
 
 putty.1: man-putt.but mancfg.but; $(MKMAN)
@@ -68,6 +69,7 @@ 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)
+pageant.1: man-pag.but mancfg.but; $(MKMAN)
 
 mostlyclean:
        rm -f *.html *.txt *.hlp *.cnt *.1 *.info vstr.but *.hh[pck]

diff --git a/doc/man-pag.but b/doc/man-pag.but
new file mode 100644 (file)
index 0000000..15bc5ba
--- /dev/null
+++ b/doc/man-pag.but
@@ -0,0 +1,270 @@
+\cfg{man-identity}{pageant}{1}{2015-05-19}{PuTTY tool suite}{PuTTY tool suite}
+
+\H{pageant-manpage} Man page for Pageant
+
+\S{pageant-manpage-name} NAME
+
+\cw{pageant} - SSH authentication agent for the PuTTY tools
+
+\S{pageant-manpage-synopsis} SYNOPSIS
+
+\c pageant ( -X | -T | --permanent | --debug ) [ key-file... ]
+\e bbbbbbb   bb   bb   bbbbbbbbbbb   bbbbbbb     iiiiiiii
+\c pageant [ key-file... ] --exec command [ args... ]
+\e bbbbbbb   iiiiiiii      bbbbbb iiiiiii   iiii
+\c pageant -a key-file...
+\e bbbbbbb bb iiiiiiii
+\c pageant ( -d | --public | --public-openssh ) key-identifier...
+\e bbbbbbb   bb   bbbbbbbb   bbbbbbbbbbbbbbbb   iiiiiiiiiiiiii
+\c pageant -D
+\e bbbbbbb bb
+\c pageant -l
+\e bbbbbbb bb
+
+\S{pageant-manpage-description} DESCRIPTION
+
+\c{pageant} is both an SSH authentication agent, and also a tool for
+communicating with an already-running agent.
+
+When running as an SSH agent, it listens on a Unix-domain socket for
+connections from client processes running under your user id. Clients
+can load SSH private keys into the agent, or request signatures on a
+given message from a key already in the agent. This permits one-touch
+authentication by SSH client programs, if Pageant is holding a key
+that the server they are connecting to will accept.
+
+\c{pageant} can also act as a client program itself, communicating
+with an already-running agent to add or remove keys, list the keys, or
+extract their public half.
+
+To run \c{pageant} as an agent, you must provide an option to tell it
+what its \e{lifetime} should be. Typically you would probably want
+Pageant to last for the duration of a login session, in which case you
+should use either \cw{-X} or \cw{-T}, depending on whether your login
+session is GUI or purely terminal-based respectively. For example, in
+your X session startup script you might write
+
+\c eval $(pageant -X)
+\e bbbbbbbbbbbbbbbbbb
+
+which will cause Pageant to start running, monitor the X server to
+notice when your session terminates (and then it will terminate too),
+and print on standard output some shell commands to set environment
+variables that client processes will need to find the running agent.
+
+In a terminal-based login, you could do almost exactly the same thing
+but with \cw{-T}:
+
+\c eval $(pageant -T)
+\e bbbbbbbbbbbbbbbbbb
+
+This will cause Pageant to tie its lifetime to that of your
+controlling terminal: when you log out, and the terminal device ceases
+to be associated with your session, Pageant will notice that it has no
+controlling terminal any more, and will terminate automatically.
+
+In either of these modes, you can also add one or more private keys as
+extra command-line arguments, e.g.
+
+\c eval $(pageant -T ~/.ssh/key.ppk)
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+
+in which case Pageant will prompt for the keys' passphrases (if any)
+and start the agent with those keys already loaded. Passphrase prompts
+will use the controlling terminal if one is available, or the GUI if
+one of those is available. If neither is available, no passphrase
+prompting can be done.
+
+To use Pageant to talk to an existing agent, you can add new keys
+using \cw{-a}, list the current set of keys' fingerprints and comments
+with \cw{-l}, extract the full public half of any key using
+\cw{--public} or \cw{--public-openssh}, delete a key using \cw{-d}, or
+delete all keys using \cw{-D}.
+
+\S{pageant-manpage-lifetime} LIFETIME
+
+The following options are called \e{lifetime modes}. They all request
+Pageant to operate in agent mode; each one specifies a different
+method for Pageant to start up and know when to shut down.
+
+\dt \cw{-X}
+
+\dd Pageant will open a connection to your X display, and when that
+connection is lost, it will terminate. This gives it the same lifetime
+as your GUI login session, so in this mode it is suitable for running
+from a startup script such as \cw{.xsession}. The actual agent will be
+a subprocess; the main Pageant process will terminate immediately,
+after printing environment-variable setting commands on standard
+output which should be installed in any process wanting to communicate
+with the agent.
+
+\lcont{
+
+The usual approach would be to run
+
+\c eval $(pageant -X)
+\e bbbbbbbbbbbbbbbbbb
+
+in an X session startup script. However, other possibilities exist,
+such as directing the standard output of \cq{pageant -X} to a file
+which is then sourced by any new shell.
+
+}
+
+\dt \cw{-T}
+
+\dd Pageant will tie its lifetime to that of the login session running
+on its controlling terminal, by noticing when it ceases to have a
+controlling terminal (which will automatically happen as a side effect
+of the session leader process terminating). Like \cw{-X}, Pageant will
+print environment-variable commands on standard output.
+
+\dt \cw{--exec} \e{command}
+
+\dd Pageant will run the provided command as a subprocess, preloaded
+with the appropriate environment variables to access the agent it
+starts up. When the subprocess terminates, Pageant will terminate as
+well.
+
+\lcont{
+
+All arguments on Pageant's command line after \cw{--exec} will be
+treated as part of the command to run, even if they look like other
+valid Pageant options or key files.
+
+}
+
+\dt \cw{--permanent}
+
+\dd Pageant will fork off a subprocess to be the agent, and print
+environment-variable commands on standard output, like \cw{-X} and
+\cw{-T}. However, in this case, it will make no effort to limit its
+lifetime in any way; it will simply run permanently, unless manually
+killed. The environment variable \cw{SSH_AGENT_PID}, set by the
+commands printed by Pageant, permits the agent process to be found for
+this purpose.
+
+\lcont{
+
+This option is not recommended, because any method of manually killing
+the agent carries the risk of the session terminating unexpectedly
+before it manages to happen.
+
+}
+
+\dt \cw{--debug}
+
+\dd Pageant will run in the foreground, without forking. It will print
+its enviroment variable setup commands on standard output, and then it
+will log all agent activity to standard output as well. This is useful
+for debugging what Pageant itself is doing, or what another process is
+doing to it.
+
+\S{pageant-manpage-client} CLIENT OPTIONS
+
+The following options tell Pageant to operate in client mode,
+contacting an existing agent via environment variables that it should
+already have set.
+
+\dt \cw{-a} \e{key-files}
+
+\dd Load the specified private key file(s), decrypt them if necessary
+by prompting for their passphrases, and add them to the
+already-running agent.
+
+\lcont{
+
+The private key files must be in PuTTY's \cw{.ppk} file format.
+
+}
+
+\dt \cw{-l}
+
+\dd List the keys currently in the running agent. Each key's
+fingerprint and comment string will be shown.
+
+\dt \cw{--public} \e{key-identifiers}
+
+\dd Print the public half of each specified key, in the RFC 4716
+standard format (multiple lines, starting with \cq{---- BEGIN SSH2
+PUBLIC KEY ----}).
+
+\lcont{
+
+Each \e{key-identifier} can be any of the following:
+
+\b The name of a file containing the key, either the whole key (again
+in \cw{.ppk} format) or just its public half.
+
+\b The key's comment string, as shown by \cw{pageant -l}.
+
+\b Enough hex digits of the key's fingerprint to be unique among keys
+currently loaded into the agent.
+
+If Pageant can uniquely identify one key by interpreting the
+\e{key-identifier} in any of these ways, it will assume that key was
+the one you meant. If it cannot, you will have to specify more detail.
+
+If you find that your desired \e{key-identifier} string can be validly
+interpreted as more than one of the above \e{kinds} of identification,
+you can disambiguate by prefixing it with \cq{file:}, \cq{comment:} or
+\cq{fp:} to indicate that it is a filename, comment string or
+fingerprint prefix respectively.
+
+}
+
+\dt \cw{--public-openssh} \e{key-identifiers}
+
+\dd Print the public half of each specified key, in the one-line
+format used by OpenSSH, suitable for putting in
+\cw{.ssh/authorized_keys} files.
+
+\dt \cw{-d} \e{key-identifiers}
+
+\dd Delete each specified key from the agent's memory, so that the
+agent will no longer serve it to clients unless it is loaded in again
+using \cw{pageant -a}.
+
+\dt \cw{-D}
+
+\dd Delete all keys from the agent's memory, leaving it completely
+empty.
+
+\S{pageant-manpage-options} OPTIONS
+
+\dt \cw{-v}
+
+\dd Verbose mode. When Pageant runs in agent mode, this option causes
+it to log all agent activity to its standard error. For example, you
+might run
+
+\lcont{
+
+\c eval $(pageant -X -v 2>~/.pageant.log)
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+
+and expect a list of all signatures requested by agent clients to
+build up in that log file.
+
+The log information is the same as that produced by the \cw{--debug}
+lifetime option, but \cw{--debug} sends it to standard output (since
+that is the main point of debugging mode) whereas \cw{-v} in all other
+lifetime modes sends the same log data to standard error (being a
+by-product of the program's main purpose). Using \cw{-v} in
+\cw{--debug} mode has no effect: the log still goes to standard
+output.
+
+}
+
+\dt \cw{--help}
+
+\dd Print a brief summary of command-line options and terminate.
+
+\dt \cw{--version}
+
+\dd Print the version of Pageant.
+
+\dt \cw{--}
+
+\dd Cause all subsequent arguments to be treated as key file names,
+even if they look like options.

diff --git a/unix/uxpgnt.c b/unix/uxpgnt.c
index 95646b3e4fafdb2c8dacd48d6954979e2cf0992c..bfd4f0ffe3e6a018c6e44468f28dc8e288482a84 100644 (file)
--- a/unix/uxpgnt.c
+++ b/unix/uxpgnt.c
@@ -111,7 +111,29 @@ static void usage(void)
 {
     printf("Pageant: SSH agent\n");
     printf("%s\n", ver);
-    printf("FIXME\n");
+    printf("Usage: pageant <lifetime> [key files]\n");
+    printf("       pageant [key files] --exec <command> [args]\n");
+    printf("       pageant -a [key files]\n");
+    printf("       pageant -d [key identifiers]\n");
+    printf("       pageant --public [key identifiers]\n");
+    printf("       pageant --public-openssh [key identifiers]\n");
+    printf("       pageant -l\n");
+    printf("       pageant -D\n");
+    printf("Lifetime options, for running Pageant as an agent:\n");
+    printf("  -X           run with the lifetime of the X server\n");
+    printf("  -T           run with the lifetime of the controlling tty\n");
+    printf("  --permanent  run permanently\n");
+    printf("  --debug      run in debugging mode, without forking\n");
+    printf("  --exec <command>   run with the lifetime of that command\n");
+    printf("Client options, for talking to an existing agent:\n");
+    printf("  -a           add key(s) to the existing agent\n");
+    printf("  -l           list currently loaded key fingerprints and comments\n");
+    printf("  --public     print public keys in RFC 4716 format\n");
+    printf("  --public-openssh   print public keys in OpenSSH format\n");
+    printf("  -d           delete key(s) from the agent\n");
+    printf("  -D           delete all keys from the agent\n");
+    printf("Other options:\n");
+    printf("  -v           verbose mode (in agent mode)\n");
     exit(1);
 }