Convert documentation to DocKnot

Move the THANKS section to a separate file to try to reduce the
length of the top-level README a bit.  Start providing a Markdown
README.md as well for GitHub.  Tweak a lot of documentation wording
and move things around to bring the package documentation in line
with my standard templates.

11 files changed, 425 insertions, 0 deletions

diff --git a/docs/metadata/README b/docs/metadata/README
new file mode 100644
index 0000000..26316da
--- /dev/null
+++ b/docs/metadata/README
@@ -0,0 +1,6 @@
+This directory contains configuration for DocKnot used to generate
+documentation files (like README.md) and web pages.  Other documentation
+in this package is generated automatically from these files as part of the
+release process.  For more information, see DocKnot's documentation.
+
+DocKnot is available from <https://www.eyrie.org/~eagle/software/docknot/>.
diff --git a/docs/metadata/blurb b/docs/metadata/blurb
new file mode 100644
index 0000000..c062000
--- /dev/null
+++ b/docs/metadata/blurb
@@ -0,0 +1,6 @@
+remctl is a client/server application that supports remote execution of
+specific commands, using Kerberos GSS-API for authentication.
+Authorization is controlled by a configuration file and ACL files and can
+be set separately for each command, unlike with rsh.  remctl is like a
+Kerberos-authenticated simple CGI server, or a combination of Kerberos ssh
+and sudo without most of the features and complexity of either.
diff --git a/docs/metadata/bootstrap b/docs/metadata/bootstrap
new file mode 100644
index 0000000..0a018f7
--- /dev/null
+++ b/docs/metadata/bootstrap
@@ -0,0 +1,2 @@
+You will also need pkg-config installed to regenerate configure and
+xml2rfc to build the formatted protocol documentation.
diff --git a/docs/metadata/build/middle b/docs/metadata/build/middle
new file mode 100644
index 0000000..4a2820f
--- /dev/null
+++ b/docs/metadata/build/middle
@@ -0,0 +1,72 @@
+Solaris users should look at `examples/remctld.xml`, an SMF manifest for
+running the `remctld` daemon.
+
+To also build the Perl bindings for the libremctl client library, pass the
+`--enable-perl` option to `configure`.  The Perl module build is handled
+by the normal Perl extension build system, and therefore will be built
+with compiler flags defined by your Perl installation and installed into
+your local Perl module directory regardless of the `--prefix` argument to
+`configure`.  To change this, you will need to run `perl Makefile.PL` in
+the `perl` subdirectory of the build tree with appropriate options and
+rebuild the module after running `make` and before running `make install`.
+
+To also build the remctl PECL extension for PHP, pass the `--enable-php`
+option to `configure`.  The PHP PECL module build is handled by the normal
+PHP extension build system and therefore will be installed into your local
+PHP module directory.  The configure script will look for `phpize` on your
+`PATH` by default; if it's in some other directory, set the `PHPIZE`
+environment variable to the full path or set it on the configure command
+line.  The configure script for the PECL extension will be run during the
+build instead of during configure.  This is unfortunately apparently
+unavoidable given how the PECL build system works.
+
+To also build the Python bindings for the libremctl client library, pass
+the `--enable-python` option to configure.  The Python module build is
+handled by the normal Python extension build system, and therefore will be
+installed into your local Python module directory regardless of the
+`--prefix` argument to `configure`.  To change this, you will need to run
+`python setup.py install` by hand in the `python` directory with whatever
+options you want to use.
+
+To also build the Ruby bindings for the libremctl client library, pass
+the `--enable-ruby` option to configure.  The Ruby module build is handled
+by the normal Ruby module build system, and therefore will be installed
+into your local Ruby module directory regardless of the `--prefix`
+argument to `configure`.  To change this, override the `sitedir` variable on
+the `make install` command line, as in:
+
+```
+    make install sitedir=/opt/ruby
+```
+
+The remctl build system also supports a few other environment variables
+that can be set to control aspects of the Perl, Python, and Ruby binding
+build systems.  These are primarily only of use when packaging the
+software.  For more information, a list of the variables, and their
+effects, see the comment at the start of `Makefile.am`.
+
+The Java client and server aren't integrated with the regular build
+system.  For information on building and installing them, see
+`java/README`.
+
+remctl will use pkg-config if it's available to find the build flags for
+libevent.  You can control which pkg-config binary and paths are used with
+the normal pkg-config environment variables of `PKG_CONFIG`,
+`PKG_CONFIG_PATH`, and `PKG_CONFIG_LIBDIR`, and you can override the
+pkg-config results with `LIBEVENT_CFLAGS` and `LIBEVENT_LIBS`.
+Alternately, you can bypass pkg-config by passing one or more of
+`--with-libevent`, `--with-libevent-include`, and `--with-libevent-lib` to
+indicate the install prefix, include directory, or library directory.
+
+remctl will automatically build with PCRE support if pcre-config or the
+PCRE library are found.  You can pass `--with-pcre` to configure to
+specify the root directory where PCRE is installed, or set the include and
+library directories separately with `--with-pcre-include` and
+`--with-pcre-lib`.  You can also set `PCRE_CONFIG` to point to a different
+pcre-config script, or do similar things as with `PATH_KRB5_CONFIG`
+described below.
+
+remctl will automatically build with GPUT support if the GPUT header and
+library are found.  You can pass `--with-gput` to configure to specify the
+root directory where GPUT is installed, or set the include and library
+directories separately with `--with-gput-include` and `--with-gput-lib`.
diff --git a/docs/metadata/description b/docs/metadata/description
new file mode 100644
index 0000000..09aff27
--- /dev/null
+++ b/docs/metadata/description
@@ -0,0 +1,49 @@
+remctl is a client/server application that supports remote execution of
+specific commands, using Kerberos GSS-API for authentication and
+confidentiality.  The commands a given user can execute are controlled by
+a configuration file and ACL files and can easily be tightly limited,
+unlike with rsh.  The mapping of command to backend program is done by the
+configuration file, which allows some additional flexibility compared to
+ssh command restrictions and works with Kerberos authentications rather
+than being limited to public key authentications.
+
+remctld is very similar to a CGI server that uses a different network
+protocol than HTTP, always does strong authentication before executing the
+desired command, and guarantees the data is encrypted on the network.
+Alternately, you can think of it as a very simple combination of Kerberos
+ssh and sudo, without most of the features of both but with simpler
+authorization.
+
+There are a lot of different client/server systems that do something
+similar, including regular rsh, CGI, IBM's sysctl (not to be confused with
+the Linux kernel call and configuration file of the same name), CERN's
+arc, and more elaborate systems like MIT's Moira.  remctl has the
+advantage over many of these schemes of using GSS-API and being about as
+simple as it possibly can be while still being useful.  It doesn't require
+any particular programming language, builds self-contained binaries, and
+uses as minimal of a protocol as possible.
+
+Both C and Java clients and servers are provided, as well as Perl, PHP,
+and Python bindings for the C client library.  For more information about
+the Java client, see `java/README`.  For more information about the PHP
+bindings, see `php/README`.  For more information about the Python
+bindings, see `python/README`.
+
+Also included in the remctl package is an alternate way of running the
+remctl server: remctl-shell.  This program is designed to be run as either
+a shell or a forced command under ssh, using ssh for authentication and
+communicating the authentication information to remctl-shell via either
+environment variables or command-line arguments via the forced command
+configuration.  This version of the server uses simple ssh clients, rather
+than using the remctl client program or libraries.
+
+remctl was originally written by Anton Ushakov as a replacement for IBM's
+sysctl, a client/server application with Kerberos v4 authentication that
+allowed the client to run Tcl code on the server, protected by ACLs.  At
+Stanford, we used sysctl extensively, but mostly only to run external
+programs, so remctl was developed as a Kerberos v5 equivalent that did
+only the portions we needed.
+
+Complete protocol documentation is available in `docs/protocol.html`.
+Also present, as `docs/design.html`, is the original design document (now
+somewhat out of date).
diff --git a/docs/metadata/metadata.json b/docs/metadata/metadata.json
new file mode 100644
index 0000000..771d873
--- /dev/null
+++ b/docs/metadata/metadata.json
@@ -0,0 +1,169 @@
+{
+    "name": "remctl",
+    "version": "3.14",
+    "synopsis": "remote authenticated command execution with ACLs",
+    "maintainer": "Russ Allbery <eagle@eyrie.org>",
+    "copyrights": [
+        {
+            "holder": "Russ Allbery <eagle@eyrie.org>",
+            "years": "2015-2016, 2018",
+        },
+        {
+            "holder": "The Board of Trustees of the Leland Stanford Junior University",
+            "years": "2002-2014",
+        },
+    ],
+    "license": "Expat",
+    "build": {
+        "autotools": true,
+        "automake": "1.11",
+        "autoconf": "2.64",
+        "gssapi": true,
+        "install": true,
+        "kerberos": true,
+        "lancaster": true,
+        "manpages": true,
+        "reduced_depends": true,
+        "type": "Autoconf",
+    },
+    "support": {
+        "email": "eagle@eyrie.org",
+        "github": "rra/remctl",
+        "web": "https://www.eyrie.org/~eagle/software/remctl/",
+    },
+    "vcs": {
+        "type": "Git",
+        "url": "https://git.eyrie.org/git/kerberos/remctl.git",
+        "browse": "https://git.eyrie.org/?p=kerberos/remctl.git",
+        "github": "rra/remctl",
+        "openhub": "https://www.openhub.net/p/remctl",
+        "travis": "rra/remctl",
+    },
+    "readme": {
+        "sections": [
+            { "title": "Building on Windows" },
+        ],
+    },
+    "quote": {
+        "author": "Peter Marshall",
+    },
+    "distribution": {
+        "section": "kerberos",
+        "tarname": "remctl",
+        "version": "remctl",
+    },
+    "packaging": {
+        "debian": "remctl",
+    },
+    "advisories": [
+        {
+            "date": "2018-04-01",
+            "versions": "3.12 and 3.13",
+            "threshold": "3.14",
+        },
+    ],
+    "docs": {
+        "user": [
+            {
+                "name": "java-readme",
+                "title": "Java client and server README",
+            },
+            {
+                "name": "php-readme",
+                "title": "PHP bindings README",
+            },
+            {
+                "name": "python-readme",
+                "title": "Python bindings README",
+            },
+            {
+                "name": "ruby-readme",
+                "title": "Ruby bindings README",
+            },
+            {
+                "name": "remctl",
+                "title": "remctl manual page",
+            },
+            {
+                "name": "remctl-shell",
+                "title": "remctl-shell manual page",
+            },
+            {
+                "name": "remctld",
+                "title": "remctld manual page",
+            },
+            {
+                "name": "thanks",
+                "title": "Thanks and credits",
+            },
+        ],
+        "developer": [
+            {
+                "name": "extending",
+                "title": "Extending remctl",
+            },
+            {
+                "name": "protocol",
+                "title": "Protocol specification",
+            },
+            {
+                "name": "protocol-v4",
+                "title": "Protocol v4 draft",
+            },
+        ],
+        "api": [
+            {
+                "name": "remctl-api",
+                "title": "remctl and remctl_free_result",
+            },
+            {
+                "name": "remctl_new",
+                "title": "remctl_new",
+            },
+            {
+                "name": "remctl_open",
+                "title": "remctl_open",
+            },
+            {
+                "name": "remctl_command",
+                "title": "remctl_command and remctl_commandv",
+            },
+            {
+                "name": "remctl_output",
+                "title": "remctl_output",
+            },
+            {
+                "name": "remctl_noop",
+                "title": "remctl_noop",
+            },
+            {
+                "name": "remctl_close",
+                "title": "remctl_close",
+            },
+            {
+                "name": "remctl_error",
+                "title": "remctl_error",
+            },
+            {
+                "name": "remctl_set_ccache",
+                "title": "remctl_set_ccache",
+            },
+            {
+                "name": "remctl_set_source_ip",
+                "title": "remctl_set_source_ip",
+            },
+            {
+                "name": "remctl_set_timeout",
+                "title": "remctl_set_timeout",
+            },
+            {
+                "name": "net-remctl",
+                "title": "Net::Remctl Perl module",
+            },
+            {
+                "name": "net-remctl-backend",
+                "title": "Net::Remctl::Backend Perl module",
+            },
+        ],
+    },
+}
diff --git a/docs/metadata/quote b/docs/metadata/quote
new file mode 100644
index 0000000..f832afb
--- /dev/null
+++ b/docs/metadata/quote
@@ -0,0 +1 @@
+Small deeds done are better than great deeds planned.
diff --git a/docs/metadata/requirements b/docs/metadata/requirements
new file mode 100644
index 0000000..83bc59e
--- /dev/null
+++ b/docs/metadata/requirements
@@ -0,0 +1,52 @@
+The remctld server and the standard client are written in C and require a
+C compiler and GSS-API libraries to build.  Both will build against either
+MIT Kerberos or Heimdal of any reasonable vintage.  remctl will also build
+against the Kerberos GSS-API implementation shipped with AIX 5.2 (and
+possibly later versions) and the Solaris 10 generic GSS-API library (and
+possibly later versions).  The `remctl_set_ccache` implementation is
+improved by building with Kerberos libraries and a GSS-API library that
+supports `gss_krb5_import_cred`.
+
+The remctld server requires libevent 1.4.x or later.  It's only been
+tested with libevent 1.4.13-stable and later, but should work with 1.4.4
+or later.  It is now only tested with libevent 2.x, so moving to a later
+version of libevent if possible is recommended.
+
+The remctl server will support regex ACLs if the system supports the POSIX
+regex API.  The remctl server also optionally supports PCRE regular
+expressions in ACLs.  To include that support, the PCRE library is
+required.
+
+To build the remctl client for Windows, the Microsoft Windows SDK for
+Windows Vista and the MIT Kerberos for Windows SDK are required, along
+with a Microsoft Windows build environment (probably Visual Studio).
+remctl has only been tested with the 3.2.1 MIT Kerberos for Windows SDK.
+To run the resulting binary, MIT Kerberos for Windows must be installed
+and configured.  The client was tested on Windows XP and Vista and should
+work on Windows 2000 and up; however, the primary maintainer does not use
+or test Windows, so it's always possible Windows support has broken.  The
+server is not supported on Windows.
+
+To build the Perl bindings for the C client library, you will need Perl
+5.8 or later.
+
+To build the PHP bindings for the C client library, you will need PHP 5.x
+or later and phpize, plus any other programs that phpize requires.  PHP
+5.x support has only been tested on 5.2 and 5.3, and PHP support is now
+only tested on PHP 7.x and later.
+
+To build the Python bindings for the C client library, you will need
+Python 2.3 or later (primarily tested with Python 2.7).  Python 3 is not
+(yet) supported.
+
+To build the Ruby bindings for the C client library, you will need Ruby
+1.8 or later (primarily tested with 2.5 and later).
+
+None of the language bindings have been tested on Windows.
+
+A Java client and Java server are available in the java subdirectory, but
+they are not integrated into the normal build or built by default.  There
+is a basic Makefile in that directory that may require some tweaking.  It
+currently requires the Sun Java JDK (1.4.2, 5, or 6) or OpenJDK 6 or
+later.  A considerably better Java client implementation is available on
+the `java` branch in the Git repository but has not yet been merged.
diff --git a/docs/metadata/sections/building-on-windows b/docs/metadata/sections/building-on-windows
new file mode 100644
index 0000000..1d46549
--- /dev/null
+++ b/docs/metadata/sections/building-on-windows
@@ -0,0 +1,31 @@
+(These instructions are not tested by the author and are now dated.
+Updated instructions via a pull request, issue, or email are very
+welcome.)
+
+First, install the Microsoft Windows SDK for Windows Vista if you have not
+already.  This is a free download from Microsoft for users of "Genuine
+Microsoft Windows."  The `vcvars32.bat` environment provided by Visual
+Studio may work as an alternative, but has not been tested.
+
+Next, install the MIT Kerberos for Windows SDK, available for download
+from https://web.mit.edu/kerberos/www/dist/index.html.  remctl has been
+tested with version 3.2.1 but should hopefully work with later versions.
+
+Then, follow these steps:
+
+1. Run the `InitEnv.cmd` script included with the Windows SDK with
+   parameters `"/xp /release"`.
+
+2. Run the `configure.bat` script, giving it as an argument the location
+   of the Kerberos for Windows SDK.  For example, if you installed the KfW
+   SDK in `"c:\KfW SDK"`, you should run:
+
+   ```sh
+       configure "c:\KfW SDK"
+   ```
+
+3. Run `nmake` to start compiling.  You can ignore the warnings.
+
+If all goes well, you will have `remctl.exe` and `remctl.dll`.  The latter
+is a shared library used by the client program.  It exports the same
+interface as the UNIX libremctl library.
diff --git a/docs/metadata/test/prefix b/docs/metadata/test/prefix
new file mode 100644
index 0000000..1afd097
--- /dev/null
+++ b/docs/metadata/test/prefix
@@ -0,0 +1,10 @@
+remctl comes with a comprehensive test suite, but it requires some
+configuration in order to test anything other than low-level utility
+functions.  For the full test suite, you will need to have a keytab that
+can authenticate to a running KDC.  Using a test KDC environment, if you
+have one, is recommended.
+
+Follow the instructions in `tests/config/README` to configure the test
+suite.
+
+Now, you can run the test suite with:
diff --git a/docs/metadata/test/suffix b/docs/metadata/test/suffix
new file mode 100644
index 0000000..a0cf1e3
--- /dev/null
+++ b/docs/metadata/test/suffix
@@ -0,0 +1,27 @@
+On particularly slow or loaded systems, you may see intermittant failures
+from the `server/streaming` test because it's timing-sensitive.
+
+The test suite will also need to be able to bind to 127.0.0.1 on port
+11119 and 14373 to run test network server programs.
+
+To test anonymous authentication, the KDC configured in the test suite
+needs to support service tickets for the anonymous identity (not a
+standard configuration).  This test will be skipped if the KDC does not
+support this.
+
+To test user handling in remctld, you will need the `fakeroot` command
+(available in the `fakeroot` package in Debian and Ubuntu).  This test
+will be skipped if `fakeroot` isn't available.
+
+The following additional Perl modules will be used by the test suite for
+the main package and the Perl bindings if installed:
+
+* Test::MinimumVersion
+* Test::Perl::Critic
+* Test::Pod
+* Test::Spelling
+* Test::Strict
+* Test::Synopsis
+
+All are available on CPAN.  Those tests will be skipped if the modules are
+not available.