130 lines
5.3 KiB
XML
130 lines
5.3 KiB
XML
<!-- 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>
|