Document versions for interfaces and features

Add version and compatibility information to all manual pages.
Command-line and configuration options, ACL methods, environment
variables, client library APIs, and other major features are now
annotated with the version of remctl in which they were added.

Change-Id: I739e0d1fbb60f4c02cf309bb5d81561fa494bdad
Reviewed-on: https://gerrit.stanford.edu/1429
Reviewed-by: Russ Allbery <rra@stanford.edu>
Tested-by: Russ Allbery <rra@stanford.edu>

12 files changed, 388 insertions, 240 deletions

diff --git a/docs/api/remctl.pod b/docs/api/remctl.pod
index a01bf74..a8f0023 100644
--- a/docs/api/remctl.pod
+++ b/docs/api/remctl.pod
@@ -39,12 +39,14 @@ GSS-API library may canonicalize I<host> via DNS before determining the
 service principal, depending on your library configuration.  Specifying a
 principal disables this behavior.
 
-The remctl protocol uses Kerberos v5 via GSS-API for authentication.  The
+The remctl protocol uses Kerberos via GSS-API for authentication.  The
 underlying GSS-API library will use the default ticket cache for
 authentication, so to successfully use remctl(), the caller should already
 have Kerberos tickets for an appropriate realm stored in its default
 ticket cache.  The environment variable KRB5CCNAME can be used to control
-which ticket cache is used.
+which ticket cache is used.  If the client needs to control which ticket
+cache is used without changing the environment, use the full client API
+along with remctl_set_ccache(3).
 
 remctl() returns a newly allocated remctl_result struct, which has the
 following members:
@@ -70,11 +72,11 @@ given command may have its own exit status conventions.
 remctl_result_free() frees the remctl_result struct when the calling
 program is through with it.
 
-If you want more control over the steps of the protocol, if you want to
-issue multiple commands on the same connection, or if you need to send
-data as part of the command that contains NULs, use the full API described
-in remctl_new(3), remctl_open(3), remctl_commandv(3), and
-remctl_output(3).
+If you want more control over the steps of the protocol, issue multiple
+commands on the same connection, control the ticket cache or source IP,
+set a timeout on replies, or send data as part of the command that
+contains NULs, use the full API described in L<remctl_new(3)>,
+L<remctl_open(3)>, L<remctl_commandv(3)>, and L<remctl_output(3)>.
 
 =head1 RETURN VALUE
 
@@ -85,6 +87,16 @@ message in the error field or the results of the command filled out as
 described above.  If remctl() returns NULL, errno will be set to an
 appropriate error code (generally ENOMEM).
 
+=head1 COMPATIBILITY
+
+This interface has been provided by the remctl client library since its
+initial release in version 2.0.
+
+The default port was changed to the IANA-registered port of 4373 in
+version 2.11.
+
+Support for IPv6 was added in version 2.4.
+
 =head1 CAVEATS
 
 If the I<principal> argument to remctl() is NULL, most GSS-API libraries
@@ -116,27 +128,27 @@ remctl port and should be phased out.
 The remctl port number, 4373, was derived by tracing the diagonals of a
 QWERTY keyboard up from the letters C<remc> to the number row.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3),
-remctl_output(3), remctl_close(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
-
 =head1 AUTHOR
 
 Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2008, 2009 The Board of Trustees of the Leland Stanford
-Junior University
+Copyright 2007, 2008, 2009, 2014 The Board of Trustees of the Leland
+Stanford Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3),
+remctl_output(3), remctl_close(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_close.pod b/docs/api/remctl_close.pod
index 9508a80..5d53545 100644
--- a/docs/api/remctl_close.pod
+++ b/docs/api/remctl_close.pod
@@ -23,13 +23,10 @@ longer valid.
 remctl_close() is always successful, even if it is unable to send a clean
 protocol quit command to the remote server.
 
-=head1 SEE ALSO
+=head1 COMPATIBILITY
 
-remctl_new(3), remctl_open(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface has been provided by the remctl client library since its
+initial release in version 2.0.
 
 =head1 AUTHOR
 
@@ -37,12 +34,20 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior
-University
+Copyright 2007, 2009, 2014 The Board of Trustees of the Leland Stanford
+Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_command.pod b/docs/api/remctl_command.pod
index 915b73d..805084f 100644
--- a/docs/api/remctl_command.pod
+++ b/docs/api/remctl_command.pod
@@ -32,6 +32,9 @@ I<count>.  This function is most convenient when passing arbitrary data to
 the command, since the iovec struct takes a pointer and a length for each
 chunk of data.  See writev(2) for the layout of the iovec struct.
 
+To control the network timeout for sending the command, see the
+L<remctl_set_timeout(3)> function.
+
 After calling one of these functions, call remctl_output() to get the
 results of the command.
 
@@ -41,13 +44,10 @@ remctl_command() and remctl_commandv() return true on success and false on
 failure.  On failure, the caller should call remctl_error() to retrieve
 the error message.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_open(3), remctl_output(3), remctl_error(3)
+=head1 COMPATIBILITY
 
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+These interfaces have been provided by the remctl client library since its
+initial release in version 2.0.
 
 =head1 AUTHOR
 
@@ -55,12 +55,20 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior
-University
+Copyright 2007, 2009, 2014 The Board of Trustees of the Leland Stanford
+Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_output(3), remctl_error(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_error.pod b/docs/api/remctl_error.pod
index a76fa17..cc9a554 100644
--- a/docs/api/remctl_error.pod
+++ b/docs/api/remctl_error.pod
@@ -29,14 +29,10 @@ remctl_error().
 remctl_error() returns either the previous error or the constant string
 "No error".  It will never return NULL.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3),
-remctl_output(3)
+=head1 COMPATIBILITY
 
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface has been provided by the remctl client library since its
+initial release in version 2.0.
 
 =head1 AUTHOR
 
@@ -44,12 +40,21 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior
-University
+Copyright 2007, 2009, 2014 The Board of Trustees of the Leland Stanford
+Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_command(3), remctl_commandv(3),
+remctl_output(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_new.pod b/docs/api/remctl_new.pod
index c551ab7..0616d1e 100644
--- a/docs/api/remctl_new.pod
+++ b/docs/api/remctl_new.pod
@@ -27,14 +27,10 @@ remctl_new() returns a pointer to an opaque remctl struct on success and
 NULL on failure.  If it returns NULL, errno will be set to an appropriate
 error code (normally ENOMEM).
 
-=head1 SEE ALSO
-
-remctl_open(3), remctl_command(3), remctl_commandv(3), remctl_output(3),
-remctl_close(3)
+=head1 COMPATIBILITY
 
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface has been provided by the remctl client library since its
+initial release in version 2.0.
 
 =head1 AUTHOR
 
@@ -42,12 +38,21 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2009 The Board of Trustees of the Leland Stanford Junior
-University
+Copyright 2007, 2009, 2014 The Board of Trustees of the Leland Stanford
+Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_open(3), remctl_command(3), remctl_commandv(3), remctl_output(3),
+remctl_close(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_noop.pod b/docs/api/remctl_noop.pod
index 6055aa3..9780ffa 100644
--- a/docs/api/remctl_noop.pod
+++ b/docs/api/remctl_noop.pod
@@ -31,13 +31,9 @@ the caller should call remctl_error() to retrieve the error message.  In
 addition to network errors, this function may fail if the server doesn't
 support protocol version 3.
 
-=head1 SEE ALSO
+=head1 COMPATIBILITY
 
-remctl_new(3), remctl_open(3), remctl_command(3), remctl_error(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface was added in version 3.0.
 
 =head1 AUTHOR
 
@@ -45,7 +41,7 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2011 The Board of Trustees of the Leland Stanford Junior
+Copyright 2011, 2014 The Board of Trustees of the Leland Stanford Junior
 University
 
 Copying and distribution of this file, with or without modification, are
@@ -53,4 +49,12 @@ permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_command(3), remctl_error(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_open.pod b/docs/api/remctl_open.pod
index 912cf55..b604776 100644
--- a/docs/api/remctl_open.pod
+++ b/docs/api/remctl_open.pod
@@ -56,18 +56,35 @@ GSS-API library may canonicalize I<host> via DNS before determining the
 service principal, depending on your library configuration.  Specifying a
 principal disables this behavior.
 
-The remctl protocol uses Kerberos v5 via GSS-API for authentication.  The
+The remctl protocol uses Kerberos via GSS-API for authentication.  The
 underlying GSS-API library will use the default ticket cache for
 authentication, so to successfully use remctl_open(), the caller should
 already have Kerberos tickets for an appropriate realm stored in its
-default ticket cache.  The environment variable KRB5CCNAME can be used to
-control which ticket cache is used.
+default ticket cache.  The environment variable KRB5CCNAME or the
+L<remctl_set_ccache(3)> function can be used to control which ticket cache
+is used.
+
+To control the timeout for the connect and for subsequent calls, see the
+L<remctl_set_timeout(3)> function.  To control the source IP used by
+remctl_open(), remctl_open_addrinfo(), and remctl_open_sockaddr(), see the
+L<remctl_set_source_ip(3)> function.
 
 =head1 RETURN VALUE
 
 remctl_open() returns true on success and false on failure.  On failure,
 the caller should call remctl_error() to retrieve the error message.
 
+=head1 COMPATIBILITY
+
+The remctl_open() interface has been provided by the remctl client library
+since its initial release in version 2.0.  remctl_open_addrinfo(),
+remctl_open_sockaddr(), and remctl_open_fd() were added in version 3.4.
+
+The default port was changed to the IANA-registered port of 4373 in
+version 2.11.
+
+Support for IPv6 was added in version 2.4.
+
 =head1 CAVEATS
 
 If the I<principal> argument to remctl_open() is NULL, most GSS-API
@@ -108,26 +125,27 @@ be closed and reopened before another command can be sent.
 The remctl port number, 4373, was derived by tracing the diagonals of a
 QWERTY keyboard up from the letters C<remc> to the number row.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_error(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
-
 =head1 AUTHOR
 
 Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007, 2008, 2009 The Board of Trustees of the Leland Stanford
-Junior University
+Copyright 2007, 2008, 2009, 2014 The Board of Trustees of the Leland
+Stanford Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_error(3), remctl_set_ccache(3),
+remctl_set_source_ip(3), remctl_set_timeout(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_set_ccache.pod b/docs/api/remctl_set_ccache.pod
index cf791ae..40a40fa 100644
--- a/docs/api/remctl_set_ccache.pod
+++ b/docs/api/remctl_set_ccache.pod
@@ -16,10 +16,10 @@ int B<remctl_set_ccache>(struct remctl *I<r>, const char *I<ccache>);
 remctl_set_ccache() tells the the remctl client library to use I<ccache>
 as the credential cache for authentication to a remctl server.  It will
 affect any subsequent remctl_open() calls on the same struct remctl object
-(and may have broader effects; see below).  I<ccache> is normally a path
-to a file in the file system that holds Kerberos credentials, but may take
-other values depending on the underlying Kerberos implementation used by
-GSS-API.
+(and may have broader effects; see L<WARNINGS> below).  I<ccache> is
+normally a path to a file in the file system that holds Kerberos
+credentials, but may take other values depending on the underlying
+Kerberos implementation used by GSS-API.
 
 Calling this function will normally override any KRB5CCNAME environment
 setting.  If the caller wishes to honor that setting, it should either not
@@ -54,6 +54,13 @@ function is not supported.
 This assumes that any failure is due to lack of support from the
 underlying library rather than some other cause.
 
+=head1 COMPATIBILITY
+
+This interface was added in version 3.0, but that version would always
+change the ticket cache used by all GSS-API calls in the same process.
+Support for the gss_krb5_import_cred() method of isolating the changed
+ticket cache to only this remctl client object was added in version 3.5.
+
 =head1 WARNINGS
 
 The effect of this function is only localized to this specific remctl
@@ -67,26 +74,26 @@ even just for remctl operations.  This function may therefore change
 global execution state and may affect other GSS-API operations done
 elsewhere in the same process.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_open(3), remctl_error(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
-
 =head1 AUTHOR
 
 Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2011, 2013 The Board of Trustees of the Leland Stanford Junior
-University
+Copyright 2011, 2013, 2014 The Board of Trustees of the Leland Stanford
+Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_error(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_set_source_ip.pod b/docs/api/remctl_set_source_ip.pod
index 2de68c8..65d0116 100644
--- a/docs/api/remctl_set_source_ip.pod
+++ b/docs/api/remctl_set_source_ip.pod
@@ -32,13 +32,9 @@ remctl_set_source_ip() returns true on success and false on failure.  On
 failure, the caller should call remctl_error() to retrieve the error
 message.
 
-=head1 SEE ALSO
+=head1 COMPATIBILITY
 
-remctl_new(3), remctl_open(3), remctl_error(3)
-
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface was added in version 3.0.
 
 =head1 AUTHOR
 
@@ -46,7 +42,7 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2011 The Board of Trustees of the Leland Stanford Junior
+Copyright 2011, 2014 The Board of Trustees of the Leland Stanford Junior
 University
 
 Copying and distribution of this file, with or without modification, are
@@ -54,4 +50,12 @@ permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_open(3), remctl_error(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/api/remctl_set_timeout.pod b/docs/api/remctl_set_timeout.pod
index e9abeec..870230e 100644
--- a/docs/api/remctl_set_timeout.pod
+++ b/docs/api/remctl_set_timeout.pod
@@ -32,14 +32,9 @@ remctl_set_timeout() returns true on success and false on failure.  The
 only failure case is if I<timeout> is negative.  On failure, the caller
 should call remctl_error() to retrieve the error message.
 
-=head1 SEE ALSO
-
-remctl_new(3), remctl_command(3), remctl_open(3), remctl_output(3),
-remctl_error(3)
+=head1 COMPATIBILITY
 
-The current version of the remctl library and complete details of the
-remctl protocol are available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
+This interface was added in version 3.1.
 
 =head1 AUTHOR
 
@@ -47,7 +42,7 @@ Russ Allbery <eagle@eyrie.org>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2012 The Board of Trustees of the Leland Stanford Junior
+Copyright 2012, 2014 The Board of Trustees of the Leland Stanford Junior
 University
 
 Copying and distribution of this file, with or without modification, are
@@ -55,4 +50,13 @@ permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl_new(3), remctl_command(3), remctl_open(3), remctl_output(3),
+remctl_error(3)
+
+The current version of the remctl library and complete details of the
+remctl protocol are available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/remctl.pod b/docs/remctl.pod
index 0fe4de5..1004548 100644
--- a/docs/remctl.pod
+++ b/docs/remctl.pod
@@ -21,10 +21,9 @@ return message.  The commands must be defined on the server-side before a
 B<remctl> client can execute them, and the user running B<remctl> must be
 authorized to execute the particular command on the server.
 
-Access to remote commands is authenticated via Kerberos v5 GSS-API, so a
-user must have a ticket granting ticket to use B<remctl>.  All
-transmissions to and from the remctld server are encrypted using GSS-API's
-security layer.
+Access to remote commands is authenticated via Kerberos GSS-API, so a user
+must have a ticket granting ticket to use B<remctl>.  All transmissions to
+and from the remctld server are encrypted using GSS-API's security layer.
 
 I<host> is the hostname of the target server.  I<command> and
 I<subcommand> together specify the command to run and correspond to the
@@ -33,11 +32,14 @@ any additional command-line parameters to pass to the remote command.
 
 =head1 OPTIONS
 
+The start of each option description is annotated with the version of
+B<remctl> in which that option was added with its current meaning.
+
 =over 4
 
 =item B<-b> I<source-ip>
 
-When connecting to the remote remctl server, use I<source-ip> as the
+[3.0] When connecting to the remote remctl server, use I<source-ip> as the
 source IP address.  This can be useful on multihomed systems where the
 remctl connections need to be made over a particular network.
 I<source-ip> must be an IP address, not a hostname, and can be either an
@@ -45,28 +47,28 @@ IPv4 or IPv6 address (assuming IPv6 is supported).
 
 =item B<-d>
 
-Turn on extra debugging output of the client-server interaction.
+[1.10] Turn on extra debugging output of the client-server interaction.
 
 =item B<-h>
 
-Show a brief usage message and then exit.
+[1.10] Show a brief usage message and then exit.
 
 =item B<-p> I<port>
 
-Connect to the server on I<port>.  If this option isn't given, the client
-first tries the registered remctl port (4373) and then falls back on the
-legacy port (4444) if that fails.
+[1.0] Connect to the server on I<port>.  If this option isn't given, the
+client first tries the registered remctl port (4373) and then falls back
+on the legacy port (4444) if that fails.
 
 =item B<-s> I<service>
 
-Authenticate to the server with a service ticket for I<service> rather
-than the default server identity of host/I<hostname>.  This may be
+[1.0] Authenticate to the server with a service ticket for I<service>
+rather than the default server identity of host/I<hostname>.  This may be
 necessary with, for instance, a server where B<remctld> is not running as
 root.
 
 =item B<-v>
 
-Print the version of B<remctl> and exit.
+[1.10] Print the version of B<remctl> and exit.
 
 =back
 
@@ -83,6 +85,13 @@ Release an AFS volume called ls.tripwire:
 
     remctl lsdb afs release ls.tripwire
 
+=head1 COMPATIBILITY
+
+The default port was changed to the IANA-registered port of 4373 in
+version 2.11.
+
+Support for IPv6 was added in version 2.4.
+
 =head1 CAVEATS
 
 If no principal is specified with B<-s>, B<remctl> canonicalizes the
@@ -109,26 +118,26 @@ gssapi(3).
 The remctl port number, 4373, was derived by tracing the diagonals of a
 QWERTY keyboard up from the letters C<remc> to the number row.
 
-=head1 SEE ALSO
-
-kinit(1), remctld(8)
-
-The current version of this program is available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
-
 =head1 AUTHOR
 
-Anton Ushakov <antonu@stanford.edu> is the original author.  Updates and
-current maintenance are done by Russ Allbery <eagle@eyrie.org>.
+B<remctl> was originally written by Anton Ushakov.  Updates and current
+maintenance are done by Russ Allbery <eagle@eyrie.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The
-Board of Trustees of the Leland Stanford Junior University
+Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2014
+The Board of Trustees of the Leland Stanford Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+kinit(1), remctld(8)
+
+The current version of this program is available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut
diff --git a/docs/remctld.pod b/docs/remctld.pod
index 6ab0e37..14d2296 100644
--- a/docs/remctld.pod
+++ b/docs/remctld.pod
@@ -20,8 +20,9 @@ remctld [B<-dFhmSvZ>] [B<-b> I<bind-address> [B<-b> I<bind-address> ...]]
 B<remctld> is the server for remctl.  It accepts a connection from remctl,
 receives the command to execute and the arguments, verifies authorization
 of the user and executes the command, returning the result back to the
-client.  All connections are authenticated using GSS-API Kerberos v5, and
-all transmissions are also encrypted using the GSS-API privacy layer.
+client.  All connections are authenticated using Kerberos GSS-API
+Kerberos, and all transmissions are also encrypted using the GSS-API
+privacy layer.
 
 B<remctld> is normally started using B<tcpserver> or from B<inetd>, but it
 may be run in stand-alone mode as a daemon using B<-m>.  Either B<-s> must
@@ -39,54 +40,67 @@ When the command is run, several environment variables will be set
 providing information about the remote connection.  See L<ENVIRONMENT>
 below for more information.
 
+Command-line and configuration options and ACL methods are annotated below
+with the version at which they were added.  For version information for
+more general features, see L<COMPATIBILITY> below.
+
 =head1 OPTIONS
 
+The start of each option description is annotated with the version of
+B<remctld> in which that option was added with its current meaning.
+
 =over 4
 
 =item B<-b> I<bind-address>
 
-When running as a standalone server, bind to the specified local address
-rather than listening on all interfaces.  This option may be given
+[2.17] When running as a standalone server, bind to the specified local
+address rather than listening on all interfaces.  This option may be given
 multiple times to bind to multiple addresses.  I<bind-address> must be an
 IP address (either IPv4 or IPv6), not a hostname.  Only makes sense in
 combination with B<-m>.
 
+This option is ignored if B<remctld> is passed already open sockets via
+the systemd socket activation protocol.  In that case, the bind addresses
+of the sockets should be controlled via the systemd configuration.
+
 =item B<-d>
 
-Enable verbose debug logging to syslog (or to standard output if B<-S> is
-also given).
+[1.10] Enable verbose debug logging to syslog (or to standard output if
+B<-S> is also given).
 
 =item B<-F>
 
-Normally when running in stand-alone mode (B<-m>), B<remctld> backgrounds
-itself to run as a daemon, changes directory to F</>, and drops any
-controlling terminal.  This flag suppresses this behavior, usually for
-debugging or so that B<remctld> can be monitored by other processes.
+[2.8] Normally when running in stand-alone mode (B<-m>), B<remctld>
+backgrounds itself to run as a daemon, changes directory to F</>, and
+drops any controlling terminal.  This flag suppresses this behavior,
+usually for debugging or so that B<remctld> can be monitored by other
+processes.
 
 =item B<-f> I<config>
 
-The configuration file for B<remctld>, overriding the default path.
+[1.0] The configuration file for B<remctld>, overriding the default path.
 
 =item B<-h>
 
-Show a brief usage message and then exit.  This usage method will include
-a list of supported ACL types and can be used to determine if optional ACL
-methods were compiled into a given B<remctld> build.
+[1.10] Show a brief usage message and then exit.  This usage method will
+include a list of supported ACL types and can be used to determine if
+optional ACL methods were compiled into a given B<remctld> build.
 
 =item B<-k> I<keytab>
 
-Use I<keytab> as the keytab for server credentials rather than the system
-default or the value of the KRB5_KTNAME environment variable.  Using B<-k>
-just sets the KRB5_KTNAME environment variable internally in the process.
+[2.8] Use I<keytab> as the keytab for server credentials rather than the
+system default or the value of the KRB5_KTNAME environment variable.
+Using B<-k> just sets the KRB5_KTNAME environment variable internally in
+the process.
 
 =item B<-m>
 
-Enable stand-alone mode.  B<remctld> will listen to its configured port
-and fork a new child for each incoming connection.  By default, when this
-option is used, B<remctld> also changes directory to F</>, backgrounds
-itself, and closes standard input, output, and error.  To not background,
-pass B<-F> as well.  To not close standard output and error and continue
-using them for logging, pass B<-S> as well.
+[2.8] Enable stand-alone mode.  B<remctld> will listen to its configured
+port and fork a new child for each incoming connection.  By default, when
+this option is used, B<remctld> also changes directory to F</>,
+backgrounds itself, and closes standard input, output, and error.  To not
+background, pass B<-F> as well.  To not close standard output and error
+and continue using them for logging, pass B<-S> as well.
 
 To determine the port, B<remctld> attempts to look up the C<remctl>
 service in the local F</etc/services> file and uses the port defined
@@ -95,23 +109,27 @@ registered remctl port.
 
 =item B<-P> I<file>
 
-When running in stand-alone mode (B<-m>), write the PID of B<remctld> to
-I<file>.  This option is ignored unless B<-m> is also given.
+[2.0] When running in stand-alone mode (B<-m>), write the PID of
+B<remctld> to I<file>.  This option is ignored unless B<-m> is also given.
 
 =item B<-p> I<port>
 
-When running in stand-alone mode, listen on port I<port> rather than the
-default.  This option does nothing unless used with B<-m>.
+[1.0] When running in stand-alone mode, listen on port I<port> rather than
+the default.  This option does nothing unless used with B<-m>.
+
+This option is ignored if B<remctld> is passed already open sockets via
+the systemd socket activation protocol.  In that case, the listening port
+should be controlled via the systemd configuration.
 
 =item B<-S>
 
-Rather than logging to syslog, log debug and routine connection messages
-to standard output and error messages to standard error.  This option is
-mostly useful for testing and debugging.
+[2.3] Rather than logging to syslog, log debug and routine connection
+messages to standard output and error messages to standard error.  This
+option is mostly useful for testing and debugging.
 
 =item B<-s> I<service>
 
-Specifies which principal is used as the server identity for client
+[1.0] Specifies which principal is used as the server identity for client
 authentication.  The client must also use the same identity as the server
 identity for authentication to succeed.  By default, B<remctld> accepts
 any principal with a key in the default keytab file (which can be changed
@@ -119,12 +137,12 @@ with the B<-k> option).  This is normally the most desirable behavior.
 
 =item B<-v>
 
-Print the version of B<remctld> and exit.
+[1.10] Print the version of B<remctld> and exit.
 
 =item B<-Z>
 
-When B<remctld> is running in stand-alone mode, after it has set up its
-network socket and is ready to answer requests, raise SIGSTOP.  This
+[3.7] When B<remctld> is running in stand-alone mode, after it has set up
+its network socket and is ready to answer requests, raise SIGSTOP.  This
 signals to upstart, when using C<expect stop>, that the daemon is ready to
 accept connections, and upstart will raise SIGCONT to allow B<remctld> to
 continue.  This option is probably only useful when using upstart as the
@@ -161,7 +179,7 @@ case all files whose names do not contain a period found in that directory
 will be included (in no particular order).  I<file> should be a fully
 qualified path.
 
-The meaning of these fields is:
+The meaning of the fields on each configuration line are:
 
 =over 4
 
@@ -175,12 +193,12 @@ If the keyword C<ALL> is used instead of a specific subcommand, this line
 matches all commands with the given subcommand (so C<ALL ALL> matches any
 command) and can be used to dispatch all commands to the same executable
 with the same ACLs.  Since the first matching entry is used, list entries
-for specific commands first (if any) and then the C<ALL> catch-all.  Note
-that while the subcommand is passed to the executable, the command is not.
-Prior to remctl 2.16, the program run will not be able to distinguish
-between different commands.  From remctl 2.16 on, the environment variable
-REMCTL_COMMAND will contain the command.  (See the ENVIRONMENT section
-below.)
+for specific commands first (if any) and then the C<ALL> catch-all.
+
+Note that while the subcommand is passed to the executable as a
+command-line option, the command is not.  The command is available to the
+executable in the environment variable REMCTL_COMMAND (see L<ENVIRONMENT>
+below).
 
 The command C<help> is handled specially if no such command is defined in
 the configuration file.  See below under the C<help> and C<summary>
@@ -211,14 +229,15 @@ subcommand combination.  (See examples below.)
 
 =item I<option>=I<value>
 
-An option setting that applies to this command.  Supported option settings
-are:
+An option setting that applies to this command.  Supported option
+settings, annotated with the version at which that option was added in its
+current form, are:
 
 =over 4
 
 =item help=I<arg>
 
-Specifies the argument for this command that will print help for a
+[3.2] Specifies the argument for this command that will print help for a
 particular subcommand to standard output.
 
 If remctld receives the command C<help> with one or two arguments, and no
@@ -236,12 +255,12 @@ remctl command.  Also see the C<summary> option.
 
 =item logmask=I<n>[,...]
 
-Limit logging of command arguments.  Any argument listed in the logmask
-list will have its value logged as "**MASKED**".  This is to avoid logging
-the arguments of commands that take private information such as passwords.
-The logmask list should contain argument numbers separated by commas, with
-the I<subcommand> considered argument 1.  The I<command> argument cannot
-be masked.
+[1.4] Limit logging of command arguments.  Any argument listed in the
+logmask list will have its value logged as "**MASKED**".  This is to avoid
+logging the arguments of commands that take private information such as
+passwords.  The logmask list should contain argument numbers separated by
+commas, with the I<subcommand> considered argument 1.  The I<command>
+argument cannot be masked.
 
 For example, if the command is C<admin passwd I<username> I<password>>,
 then you'd want to set logmask to C<3>, so the password argument gets
@@ -250,12 +269,12 @@ I<old-password> I<new-password>>, you'd want to set logmask to C<3,4>.
 
 =item stdin=(I<n> | C<last>)
 
-Specifies that the I<n>th or last argument to the command be passed on
-standard input instead of on the command line.  The value of this option
-must either be the number of argument to pass on standard input (with the
-I<subcommand> considered argument 1) or the special value C<last>, which
-indicates that the final argument (no matter how many there are) be passed
-on standard input.
+[2.14] Specifies that the I<n>th or last argument to the command be passed
+on standard input instead of on the command line.  The value of this
+option must either be the number of argument to pass on standard input
+(with the I<subcommand> considered argument 1) or the special value
+C<last>, which indicates that the final argument (no matter how many there
+are) be passed on standard input.
 
 The I<command> cannot be passed on standard input, so I<n> must be at
 least C<1>.  If this option is set to C<last> and no arguments are given
@@ -272,8 +291,8 @@ contain NUL characters.
 
 =item summary=I<arg>
 
-Specifies the argument for this command that will print a usage summary
-to standard output.
+[3.2] Specifies the argument for this command that will print a usage
+summary to standard output.
 
 If remctld receives the command C<help> with no arguments, and no C<help>
 command is defined in the configuration file, the server will look through
@@ -292,8 +311,8 @@ with a I<subcommand> of C<ALL>.
 
 =item user=(I<username> | I<uid>)
 
-Run this command as the specified user, which can be given as either a
-username or as a UID.  Even if given as a UID, the user must be found in
+[3.1] Run this command as the specified user, which can be given as either
+a username or as a UID.  Even if given as a UID, the user must be found in
 the user database (searched via getpwuid(3)).  B<remctld> will run the
 command as the specified user, including that user's primary and
 supplemental groups.
@@ -311,21 +330,23 @@ If I<method> is omitted, I<acl> must either begin with C</> or must not
 contain C<=>.  Otherwise, it will be parsed as an option instead.  If
 there is any ambiguity, prepend the I<method>.
 
-Each entry is checked in order, and access is granted as soon as an
-entry matches.  If no entry matches, access is denied.  The following
-methods are supported:
+Each entry is checked in order, and access is granted as soon as an entry
+matches.  If no entry matches, access is denied.  The following methods
+may supported; however, be aware that the availability of several ACL
+types depends on whether B<remctld> was built with that support.  Each ACL
+type is annotated with the version in which it was added.
 
 =over 4
 
 =item file
 
-The data is the full path of an ACL file or to a directory containing ACL
-files.  Directories are handled as described for the include directive in
-configuration files.  An ACL file contains one entry per line, in the
-[I<method>:]I<data> form described above.  Entries are handled exactly as
-if they had appeared in the configuration file except that the default
-method is C<princ> instead of C<file>.  Blank lines and lines beginning
-with C<#> are ignored in the ACL files.
+[2.13] The data is the full path of an ACL file or to a directory
+containing ACL files.  Directories are handled as described for the
+include directive in configuration files.  An ACL file contains one entry
+per line, in the [I<method>:]I<data> form described above.  Entries are
+handled exactly as if they had appeared in the configuration file except
+that the default method is C<princ> instead of C<file>.  Blank lines and
+lines beginning with C<#> are ignored in the ACL files.
 
 For backward compatibility, a line like:
 
@@ -345,15 +366,16 @@ files.
 
 =item princ
 
-The data is the name of a Kerberos v5 principal which is to be granted
-access, such as C<username@EXAMPLE.ORG>.
+[2.13] The data is the name of a Kerberos v5 principal which is to be
+granted access, such as C<username@EXAMPLE.ORG>.
 
 =item deny
 
-This method is used to selectively deny access.  The data is parsed as a
-[I<method>:]I<data> and evaluated as described above, with the default
-scheme being C<princ>.  If it matches, access is denied immediately
-without examining any further entries.  Otherwise, processing continues.
+[2.13] This method is used to selectively deny access.  The data is parsed
+as a [I<method>:]I<data> and evaluated as described above, with the
+default scheme being C<princ>.  If it matches, access is denied
+immediately without examining any further entries.  Otherwise, processing
+continues.
 
 Remember that access is granted as soon as an entry matches.  For C<deny>
 rules to be effective, they therefore must come before any ACLs they are
@@ -368,7 +390,7 @@ C<deny:deny:foo> neither denies nor grants access to anyone.
 
 =item gput
 
-This method is used to grant access based on the CMU GPUT (Global
+[2.13] This method is used to grant access based on the CMU GPUT (Global
 Privileged User Table -- see gput(5)).  The data is either a GPUT role
 name or a string of the form I<group>[I<xform>], where I<group> is a GPUT
 role name and I<xform> is a GPUT transform string.  Access is granted if
@@ -380,14 +402,24 @@ by using the C<--with-gput> configure option.
 
 =item pcre
 
-This method is used to grant or deny access based on Perl-compatible
-regular expressions.  The data is taken to be a Perl-compatible regular
-expression and matched against the user identity.  To deny access, use the
-C<deny:pcre:regex> syntax.
+[2.16] This method is used to grant or deny access based on
+Perl-compatible regular expressions.  The data is taken to be a
+Perl-compatible regular expression and matched against the user identity.
+To deny access, use the C<deny:pcre:I<regex>> syntax.
 
 This method is supported only if B<remctld> was compiled with PCRE support
 by using the C<--with-pcre> configure option.
 
+=item regex
+
+[2.16] This method is used to grant or deny access based on POSIX extended
+regular expressions.  The data is taken to be a POSIX extended regular
+expression (like those used by B<egrep>) and matched against the user
+identity.  To deny access, use the C<deny:regex:I<regex>> syntax.
+
+This method is supported only if a library for POSIX-compatible regular
+expressions was found when B<remctld> was built.
+
 =back
 
 To see the list of ACL types supported by a particular build of
@@ -401,11 +433,6 @@ the REMOTE_USER environment variable.  Note that ANYUSER accepts B<any>
 authenticated user, including cross-realm users from foreign Kerberos
 realms.
 
-Support for ACL schemes is new in remctl 2.13.  Prior versions of
-B<remctld> expected only files in the main B<remctld> configuration file,
-and only principals or lines starting with C<include> in those files,
-without any I<method>: prefixes.
-
 =back
 
 =head1 ENVIRONMENT
@@ -441,7 +468,7 @@ When running in stand-alone mode, these environment variables will be
 cleared by B<remctld> before running any commands.
 
 The following environment variables will be set for any commands run via
-B<remctld>:
+B<remctld> (annotated with the version at which they were added):
 
 =over 4
 
@@ -449,34 +476,26 @@ B<remctld>:
 
 =item REMUSER
 
-Set to the Kerberos principal of the authenticated client.  REMUSER has
-always been set by B<remctld>; REMOTE_USER is also set (to the same value)
-starting with remctl 2.1.
+[1.0 for REMUSER, 2.1 for REMOTE_USER] Set to the Kerberos principal of
+the authenticated client.
 
 =item REMOTE_ADDR
 
-The IP address of the remote host.  Currently, this is always an IPv4
-address, but in the future it may be set to an IPv6 address.  This
-environment variable was added in remctl 2.1.
+[2.1] The IP address of the remote host.  This may be IPv4 or IPv6.
 
 =item REMOTE_HOST
 
-The hostname of the remote host, if it was available.  If reverse name
-resolution failed, this environment variable will not be set.  This
-variable was added in remctl 2.1.
+[2.1] The hostname of the remote host, if it was available.  If reverse
+name resolution failed, this environment variable will not be set.
 
 =item REMCTL_COMMAND
 
-The command string that caused this command to be run.  This variable will
-contain only the command, not the subcommand or any additional arguments
-(which are passed as command arguments).  This variable was added in
-remctl 2.16.
+[2.16] The command string that caused this command to be run.  This
+variable will contain only the command, not the subcommand or any
+additional arguments (which are passed as command arguments).
 
 =back
 
-B<remctld> also used to set SCPRINCIPAL for (partial) backward
-compatibility with B<sysctld>, but stopped doing so as of remctl 2.1.
-
 If the B<-k> flag is used, B<remctld> will also set KRB5_KTNAME to the
 provided keytab path.  This is primarily for communication with the
 GSS-API library, but this setting will also be inherited by any commands
@@ -503,6 +522,15 @@ To start B<remctld> in stand-alone mode instead, run:
 
     remctld -m
 
+To start B<remctld> in stand-alone mode in the foreground, use:
+
+    remctld -F -m
+
+This is a typical invocation with systemd using socket activation.  For
+upstart (with C<expect stop>), use:
+
+    remctld -F -m -Z
+
 Example configuration file:
 
  # Comments can be used like this.
@@ -522,7 +550,7 @@ C<accounts passwd> (presumably the password) will not be logged to syslog.
 All commands starting with C<printing> will be passed to
 /usr/local/bin/printthing.
 
-Example ACL file using the scheme support new in remctl 2.13:
+Example ACL file:
 
     # This is a comment.
     deny:baduser@EXAMPLE.ORG
@@ -537,6 +565,45 @@ specific principals C<service/admin@EXAMPLE.ORG> and
 C<service/other@EXAMPLE.ORG>.  The last line takes advantage of the
 default ACL method of C<principal> when processing an ACL file.
 
+=head1 COMPATIBILITY
+
+The version at which various command-line and configuration options and
+ACL methods were added to B<remctld> are noted in their descriptions.
+Below is the version information for more general features, in reverse
+order of when the feature was added.
+
+Support for the systemd readiness protocol and socket activation,
+including honoring the environment variables LISTEN_FDS, LISTEN_PID, and
+NOTIFY_SOCKET, was added in version 3.7.
+
+Special handling of the C<help> and C<summary> commands was added in
+version 3.2.
+
+Support for the C<ALL> keyword in the command field of the configuration
+file was added in version 2.15.  (It has always been supported in the
+subcommand field.)
+
+Support for the C<EMPTY> keyword in the subcommand field of the
+configuration file was added in version 2.15.
+
+Support for ACL schemes and the I<method>:I<data> syntax was added in
+remctl 2.13.  Prior versions of B<remctld> expected only files in the main
+B<remctld> configuration file, and only principals or lines starting with
+C<include> in those files, without any I<method>: prefixes.
+
+The default listening port with the B<-m> option was changed to the
+IANA-registered port of 4373 in version 2.11.
+
+Support for IPv6 addresses in the REMOTE_ADDR environment variable was
+added in version 2.4.
+
+B<remctld> used to set the environment variable SCPRINCIPAL when running
+commands, for (partial) backward compatibility with B<sysctld>, but
+stopped doing so in version 2.1.
+
+C<include> directives in ACL files were added in version 1.11.  C<include>
+directives in configuration files were added in version 1.8.
+
 =head1 CAVEATS
 
 When using Heimdal with triple-DES keys and talking to old clients that
@@ -562,26 +629,26 @@ configuration file.  At most one argument may be passed that way.
 The remctl port number, 4373, was derived by tracing the diagonals of a
 QWERTY keyboard up from the letters C<remc> to the number row.
 
-=head1 SEE ALSO
-
-remctl(1), syslog(3), tcpserver(1)
-
-The current version of this program is available from its web page at
-L<http://www.eyrie.org/~eagle/software/remctl/>.
-
 =head1 AUTHOR
 
-Anton Ushakov <antonu@stanford.edu> is the original author.  Updates and
-current maintenance are done by Russ Allbery <eagle@eyrie.org>.
+B<remctld> was originally written by Anton Ushakov.  Updates and current
+maintenance are done by Russ Allbery <eagle@eyrie.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
-The Board of Trustees of the Leland Stanford Junior University
+Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
+2012, 2014 The Board of Trustees of the Leland Stanford Junior University
 
 Copying and distribution of this file, with or without modification, are
 permitted in any medium without royalty provided the copyright notice and
 this notice are preserved.  This file is offered as-is, without any
 warranty.
   
+=head1 SEE ALSO
+
+remctl(1), syslog(3), tcpserver(1)
+
+The current version of this program is available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
 =cut