diff options
author | aszlig <aszlig@redmoonstudios.org> | 2016-04-12 06:19:59 +0200 |
---|---|---|
committer | aszlig <aszlig@redmoonstudios.org> | 2016-04-12 06:19:59 +0200 |
commit | dd0d64afea9f184e4408016ed1413e2284cc67a2 (patch) | |
tree | 621e31860e61aa9d9ea7d0ed5445dcab7bf38348 /nixos/modules | |
parent | e2383b84f88e0e7d35f6a3a846b54c69e3bee6ee (diff) | |
download | nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar.gz nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar.bz2 nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar.lz nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar.xz nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.tar.zst nixlib-dd0d64afea9f184e4408016ed1413e2284cc67a2.zip |
nixos/taskserver: Finish module documentation
Apart from the options manual, this should cover the basics for setting up a Taskserver. I am not a native speaker so this can and (probably) should be improved, especially the wording/grammar. Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Diffstat (limited to 'nixos/modules')
-rw-r--r-- | nixos/modules/services/misc/taskserver/doc.xml | 96 |
1 files changed, 94 insertions, 2 deletions
diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml index b41747872c66..15125b1411bd 100644 --- a/nixos/modules/services/misc/taskserver/doc.xml +++ b/nixos/modules/services/misc/taskserver/doc.xml @@ -32,7 +32,7 @@ <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. + CA along with Taskserver organisations, users and groups. </para> <para> @@ -46,7 +46,99 @@ 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> + </section> + + <section> + <title>The nixos-taskserver tool</title> + + <para> + Because Taskserver by default only provides scripts to setup users + imperatively, the <command>nixos-taskserver</command> tool is used for + addition and deletion of organisations along with users and groups defined + by <option>services.taskserver.organisations</option> and as well for + imperative set up. + </para> + + <para> + The tool is designed to not interfere if the command is used to manually + set up some organisations, users or groups. + </para> + + <para> + For example if you add a new organisation using + <command>nixos-taskserver org add foo</command>, the organisation is not + modified and deleted no matter what you define in + <option>services.taskserver.organisations</option>, even if you're adding + the same organisation in that option. + </para> + + <para> + The tool is modelled to imitate the official <command>taskd</command> + command, documentation for each subcommand can be shown by using the + <option>--help</option> switch. + </para> + </section> + <section> + <title>Declarative/automatic CA management</title> + + <para> + Everything is done according to what you specify in the module options, + however in order to set up a Taskwarrior client for synchronisation with a + Taskserver instance, you have to transfer the keys and certificates to the + client machine. + </para> - <!-- TODO: Go more into the details of nixos-taskserver. --> + <para> + This is done using + <command>nixos-taskserver user export $orgname $username</command> which + is printing a shell script fragment to stdout which can either be used + verbatim or adjusted to import the user on the client machine. + </para> + + <para> + For example, let's say you have the following configuration: +<screen> +{ + services.taskserver.enable = true; + services.taskserver.fqdn = "server"; + services.taskserver.listenHost = "::"; + services.taskserver.organisations.NixOS.users = [ "alice" ]; +} +</screen> + This creates an organisation called <literal>NixOS</literal> with the user + <literal>alice</literal>. + </para> + + <para> + Now in order to import the <literal>alice</literal> user to another + machine <literal>alicebox</literal>, all we need to do is something like + this: +<screen> +$ ssh server nixos-taskserver user export NixOS alice | sh +</screen> + Of course, if no SSH daemon is available on the server you can also copy + & paste it directly into a shell. + </para> + + <para> + After this step the user should be set up and you can start synchronising + your tasks for the first time with <command>task sync init</command> on + <literal>alicebox</literal>. + </para> + + <para> + Subsequent synchronisation requests merely require the command + <command>task sync</command> after that stage. + </para> + </section> + <section> + <title>Manual CA management</title> + + <para> + If you set any options within + <option>service.taskserver.pki.manual.*</option>, the automatic user and + CA management by the <command>nixos-taskserver</command> is disabled and + you need to create certificates and keys by yourself. + </para> </section> </chapter> |