nixos/taskserver: Add module documentation

It's not by any means exhaustive, but we're still going to change the
implementation, so let's just use this as a starting point.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
This commit is contained in:
aszlig 2016-04-07 14:11:49 +02:00
parent 8b793d1916
commit 64e566a49c
No known key found for this signature in database
GPG key ID: D0EBD0EC8C2DC961
4 changed files with 60 additions and 2 deletions

View file

@ -28,6 +28,7 @@ effect after you run <command>nixos-rebuild</command>.</para>
<xi:include href="postgresql.xml" />
<xi:include href="gitlab.xml" />
<xi:include href="acme.xml" />
<xi:include href="taskserver.xml" />
<!-- Apache; libvirtd virtualisation -->

View file

@ -58,6 +58,7 @@ let
cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml
cp ${../../modules/services/misc/gitlab.xml} configuration/gitlab.xml
cp ${../../modules/security/acme.xml} configuration/acme.xml
cp ${../../modules/services/misc/taskserver/doc.xml} configuration/taskserver.xml
ln -s ${optionsDocBook} options-db.xml
echo "${version}" > version
'';

View file

@ -88,6 +88,8 @@ let
ctlcmd = "${nixos-taskserver}/bin/nixos-taskserver --service-helper";
withMeta = meta: defs: mkMerge [ defs { inherit meta; } ];
in {
options = {
@ -299,7 +301,9 @@ in {
};
};
config = mkIf cfg.enable {
config = withMeta {
doc = ./taskserver.xml;
} (mkIf cfg.enable {
environment.systemPackages = [ pkgs.taskserver nixos-taskserver ];
@ -424,5 +428,5 @@ in {
Group = cfg.group;
};
};
};
});
}

View file

@ -0,0 +1,52 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="module-taskserver">
<title>Taskserver</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
</para>
<section>
<title>Configuration</title>
<para>
Taskserver does all of its authentication via TLS using client
certificates, so you either need to roll your own CA or purchase a
certificate from a known CA, which allows creation of client
certificates.
These certificates are usually advertised as
<quote>server certificates</quote>.
</para>
<para>
So in order to make it easier to handle your own CA, there is a helper
tool called <command>nixos-taskserver</command> which manages the custom
CA along with Taskserver users and groups.
</para>
<para>
While the client certificates in Taskserver only authenticate whether a
user is allowed to connect, every user has its own UUID which identifies
it as an entity.
</para>
<para>
With <command>nixos-taskserver</command> the client certificate is created
along with the UUID of the user, so it handles all of the credentials
needed in order to setup the Taskwarrior client to work with a Taskserver.
</para>
<!-- TODO: Go more into the details of nixos-taskserver. -->
</section>
</chapter>