Release 2.1.4.

[u/mdw/catacomb] / pixie.1

diff --git a/pixie.1 b/pixie.1
index 1b73db9..ced4b48 100644 (file)
--- a/pixie.1
+++ b/pixie.1
@@ -26,6 +26,12 @@ pixie \- Catacomb passphrase pixie
 .IR socket ]
 .B \-C
 .RI [ "request args" ...]
+.br
+.B pixie
+.RB [ \-s
+.IR socket ]
+.BR \-P [ P ]
+.I tag
 .SH "DESCRIPTION"
 The passphrase pixie manages passphrases.  When it starts up, it creates
 a Unix-domain socket in a private directory.  Clients may connect to it
@@ -58,10 +64,24 @@ Print a terse usage summary and exit successfully.
 .B "\-C, \-\-client"
 Connect to a running pixie as a client.  If command-line arguments are
 supplied, they are concatenated with spaces between them and submitted
-to the pixie as a request; a reply is read from the pixie and printed
-on stdout.  If no command-line arguments are given, requestss are read
-interactively from stdin and sent to the pixie; the pixie's responses
-are printed on stdout.
+to the pixie as a request; a reply is read from the pixie and formatted:
+information is written to standard output; errors are reported via
+standard error and the exit status.  If no command-line arguments are
+given, requestss are read interactively from stdin and sent to the
+pixie; the pixie's responses are printed on stdout uninterpreted.
+.TP
+.B "\-P, \-\-passphrase"
+Connect to a running pixie and request the passphrase with tag
+.IR tag .
+If no pixie is running then request the passphrase from the terminal.
+Print the result on standard output, followed by a newline.
+.TP
+.B "\-PP, \-\-verify-passphrase"
+Connect to a running pixie and request verification of the passphrase
+with tag
+.IR tag .
+If no pixie is running, request the passphrase from the terminal.  Print
+the result on standard output, followed by a newline.
 .TP
 .B "\-q, \-\-quiet"
 Causes the pixie to emit fewer log messages.
@@ -94,7 +114,7 @@ or
 .RB ` d '
 can be added to specify minutes, hours or days respectively.  A timeout
 of zero means that the pixie will never time out a passphrase.  The
-default is to time out a passphrase after 5 minutes.
+default is to time out a passphrase after 15 minutes.
 .TP
 .B "\-d, \-\-daemon"
 Fork into the background and disassociate from the terminal after
@@ -105,10 +125,13 @@ Send log messages to the syslog rather than stderr.
 .\"
 .SS "Memory management"
 During initialization, the pixie attempts to allocate a block of memory
-from the kernel and protect it against being swapped to disk.  On most
-systems, this requires that the pixie start with root privileges,
-although it will drop them as soon as it can (before parsing
-command-line options).
+from the kernel and protect it against being swapped to disk.  On Linux
+and other systems with
+.B RLIMIT_MEMLOCK
+or similar, this should just work assuming that the limit is set
+sensibly.  On other systems, this requires that the pixie start with
+root privileges, although it will drop them as soon as it can (before
+parsing command-line options, for example).
 .PP
 The locked memory is used for all of the passphrases which the pixie
 stores, and for the buffers used to hold requests from clients.
@@ -222,7 +245,7 @@ using the same syntax as the
 .B \-t
 command-line option.
 .TP
-.B VERIFY " tag \fR[\fIexpire\fR]"
+.BI VERIFY " tag \fR[\fIexpire\fR]"
 Requests a new passphrase named
 .IR tag .
 If the pixie is capable of fetching passphrases, it should ask the user
@@ -231,7 +254,7 @@ the
 .B PASS
 request.
 .TP
-.BI SET "tag \fR[\fIexpire\fR] " \-\- " phrase"
+.BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase"
 Sets the value of the passphrase named
 .I tag
 to be
@@ -287,7 +310,7 @@ sent a passphrase over a hostile or potentially hostile network.  Don't
 do anything else stupid.
 .SH "OTHER CAVEATS"
 The pixie's preinitialization checking doesn't do a thorough audit of a
-directory, in the way that, say
+directory, in the way that, say,
 .BR chkpath (1)
 does.  It's your responsibility to make sure that the full path is
 relatively safe.
@@ -307,4 +330,4 @@ noted in the
 .B auto-pgp
 documentation.
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>