Client: Initial version of the man page

TODO: Installation target

diff --git a/client/Makefile b/client/Makefile
index 4ab4e29112e65b928c8874461a3b4e8c2bfbdb07..91b5da4f03e8ff1dcee26a26ebf504e09436e428 100644 (file)
--- a/client/Makefile
+++ b/client/Makefile
@@ -1,9 +1,16 @@
 DIRS+=client
 
-PROGS+=$(o)/client/subauth
+PROGS+=$(o)/client/subauth $(o)/client/subauth.1
 
 $(o)/client/subauth: $(o)/client/subauth.o
 
+# This is a little bit hacky as a2x cannot produce output
+# in a different directory.
+$(o)/%.1: $(s)/%.1.txt
+       $(M)MAN $<
+       $(Q)cp $< $@.txt
+       $(Q)a2x -f manpage $@.txt
+
 .PHONY: install-client
 install:: install-client
 install-client:

diff --git a/client/subauth.1.txt b/client/subauth.1.txt
new file mode 100644 (file)
index 0000000..6820926
--- /dev/null
+++ b/client/subauth.1.txt
@@ -0,0 +1,131 @@
+SUBAUTH(1)
+==========
+
+NAME
+----
+subauth - A client to the sub-authentication service
+
+
+SYNOPSIS
+--------
+*subauth* 'options' 'operation'
+
+
+DESCRIPTION
+-----------
+The sub-authentication service lets local users define sub-accounts
+with different authentication tokens for specific services.
+
+The system administrator defines one or more authentication zones,
+each corresponding to a set of system services. You can use *subauth --zones*
+to list all existing zones.
+
+Each zone can contain an account for each system user. Depending on the
+configuration of the zone, accounts can be manager manually by the administrator,
+or they can be created automatically when the user sets an authentication
+token for the zone.
+
+Every account can be endowed with one of more authentication tokens
+of the following types. Depending on the configuration, all types need
+not be available in all zones.
+
+* *Password:* a user-specified string, usually easy to remember, but hard to
+  guess. This is useful when authenticating manually. Please note that the
+  password must not contain a "+-+" (minus) character, because it is used
+  as a separator in other token types. There may be at most one password
+  per account. You can use *subauth --passwd* to set a password
+  and *subauth --delete-passwd* to remove it.
+
+* *Regular token:* such tokens are generated automatically. They consist
+  of a public identifier (4 hexadecimal digits) and a random secret string.
+  Multiple tokens can be defined for the same account, their public identifiers
+  and optional comments can be listed by the user. This can be useful if you
+  want to let multiple programs remember your credentials: each program can
+  get a unique token and when it ceases to be trusted, the token can be simply
+  removed. Use *subauth --create-token* to have a token generated and *subauth --delete-token*
+  to have it removed.
+
+* *Temporary token:* this is a randomly generated cryptographically signed string,
+  allowing access to the given user in the given zone for a limited time. This
+  can be useful for services which are used so scarcely that it does not make
+  sense to remember permanent credentials of any kind. Use *subauth --temp-token*
+  to obtain a temporary token.
+
+The sub-accounts are managed by the *subauthd*(8) daemon.
+The *subauth*(1) command is a front-end to this daemon, through which
+accounts and tokens can be managed from the shell.
+
+
+OPERATIONS
+----------
+*User commands*
+
+*--zones*::
+       List all known authentication zones.
+
+*-l, --list*::
+       List all accounts of the current user (this can be the user running the
+       command, or a different user given as *--user* if ran by the super-user).
+
+*--passwd*::
+       Set or replace a password for the given account. Requires *--zone*.
+
+*--delete-passwd*::
+       Delete password for the given account. Requires *--zone*.
+
+*--create-token*::
+       Create a new token for the given account. Requires *--zone*.
+       Optionally, a *--comment* can be given.
+
+*--delete-token*::
+       Delete a given token. Requires *--zone* and *--ident*.
+
+*--temp-token*::
+       Create a temporary token. Requires *--zone*.
+       Optionally, token validity can be set with *--expire* (otherwise,
+       a default of 5 minutes will be used).
+
+*--login*::
+       Test if a given password or token (read from standard input) is valid
+       in the given zone. Require *--zone*.
+
+*Administrator commands*
+
+*--create-acct*::
+       Create an account for the current user in the given zone. Requries *--zone*.
+       Usually, a *--user* is also given.
+
+*--delete-acct*::
+       Delete an account for the current user in the given zone. Requires *--zone*.
+       Usually, a *--user* is also given.
+
+*--delete-user*::
+       Deletes all accounts of the current user. Requires *--zone*.
+       Usually, a *--user* is also given.
+
+OPTIONS
+-------
+
+*-u, --user=*'login'::
+       Operate on the given user instead of the user running the command.
+       Only the super-user can operate on somebody else.
+
+*-z, --zone=*'zone'::
+       Specify authentication zone. This is required by most operations.
+
+*-i, --ident=*'id'::
+       Specify token identifier. An asterisk can be used for "all tokens".
+
+*-c, --comment=*'text'::
+       When creating a token, remember this comment with the token. Comments
+       make it easier to recognize the intentions behind different tokens.
+
+*-x, --expire=*'time'::
+       Set lifetime of a temporary token. The time is followed by a unit,
+       which is either "*h*", "*m*", or "*s*". Maximum lifetime can be limited
+       by zone configuration.
+
+
+SEE ALSO
+--------
+*subauthd*(8)

diff --git a/configure b/configure
index 53888b67bc114946e545ac9cde20808581924acd..4707901ed92aeb3052f453094534035dc4d00c17 100755 (executable)
--- a/configure
+++ b/configure
@@ -56,6 +56,8 @@ if (IsSet("CONFIG_APACHE_MOD")) {
        Set("INSTALL_APACHE2_CONFIG_DIR" => '$(INSTALL_PREFIX)etc/apache2');
 }
 
+require UCW::Configure::Doc;
+
 Finish();
 
 Log "\nConfigured, run `make' to build everything.\n";