diff options
Diffstat (limited to 'nixos/modules/services/misc/taskserver/default.xml')
| -rw-r--r-- | nixos/modules/services/misc/taskserver/default.xml | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/nixos/modules/services/misc/taskserver/default.xml b/nixos/modules/services/misc/taskserver/default.xml new file mode 100644 index 000000000000..bbb38211b7ca --- /dev/null +++ b/nixos/modules/services/misc/taskserver/default.xml @@ -0,0 +1,130 @@ +<!-- Do not edit this file directly, edit its companion .md instead + and regenerate this file using nixos/doc/manual/md-to-db.sh --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-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">https://taskwarrior.org/docs/#taskd</link> + </para> + <section xml:id="module-services-taskserver-configuration"> + <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 organisations, 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> + </section> + <section xml:id="module-services-taskserver-nixos-taskserver-tool"> + <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 + <xref linkend="opt-services.taskserver.organisations" /> 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 xml:id="module-services-taskserver-declarative-ca-management"> + <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> + <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: + </para> + <programlisting> +{ + services.taskserver.enable = true; + services.taskserver.fqdn = "server"; + services.taskserver.listenHost = "::"; + services.taskserver.organisations.my-company.users = [ "alice" ]; +} +</programlisting> + <para> + This creates an organisation called <literal>my-company</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: + </para> + <programlisting> +$ ssh server nixos-taskserver user export my-company alice | sh +</programlisting> + <para> + 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 xml:id="module-services-taskserver-manual-ca-management"> + <title>Manual CA management</title> + <para> + If you set any options within + <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*, + <command>nixos-taskserver</command> won’t issue certificates, but + you can still use it for adding or removing user accounts. + </para> + </section> +</chapter> |