144 lines
4.9 KiB
XML
144 lines
4.9 KiB
XML
<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 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>
|
|
<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>
|
|
<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:
|
|
<screen>
|
|
{
|
|
<xref linkend="opt-services.taskserver.enable"/> = true;
|
|
<xref linkend="opt-services.taskserver.fqdn"/> = "server";
|
|
<xref linkend="opt-services.taskserver.listenHost"/> = "::";
|
|
<link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
|
|
}
|
|
</screen>
|
|
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:
|
|
<screen>
|
|
$ ssh server nixos-taskserver user export my-company 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
|
|
<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>
|