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, 0 insertions, 130 deletions
diff --git a/nixos/modules/services/misc/taskserver/default.xml b/nixos/modules/services/misc/taskserver/default.xml deleted file mode 100644 index bbb38211b7ca..000000000000 --- a/nixos/modules/services/misc/taskserver/default.xml +++ /dev/null @@ -1,130 +0,0 @@ -<!-- 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> |