78fe00da7c
The helper tool so far was only intended for use in automatic PKI handling, but it also is very useful if you have an existing CA. One of the main advantages is that you don't need to specify the data directory anymore and the right permissions are also handled as well. Another advantage is that we now have an uniform management tool for both automatic and manual config, so the documentation in the NixOS manual now applies to the manual PKI config as well. Signed-off-by: aszlig <aszlig@redmoonstudios.org>
144 lines
4.8 KiB
XML
144 lines
4.8 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 <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>
|
|
|
|
<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.my-company.users = [ "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
|
|
<option>service.taskserver.pki.manual.*</option>,
|
|
<command>nixos-taskserver</command> won't issue certificates, but you can
|
|
still use it for adding or removing user accounts.
|
|
</para>
|
|
</section>
|
|
</chapter>
|