pyrox.dev
1# Taskserver {#module-services-taskserver}
2
3Taskserver is the server component of
4[Taskwarrior](https://taskwarrior.org/), a free and
5open source todo list application.
6
7*Upstream documentation:* <https://taskwarrior.org/docs/#taskd>
8
9## Configuration {#module-services-taskserver-configuration}
10
11Taskserver does all of its authentication via TLS using client certificates,
12so you either need to roll your own CA or purchase a certificate from a
13known CA, which allows creation of client certificates. These certificates
14are usually advertised as "server certificates".
15
16So in order to make it easier to handle your own CA, there is a helper tool
17called {command}`nixos-taskserver` which manages the custom CA along
18with Taskserver organisations, users and groups.
19
20While the client certificates in Taskserver only authenticate whether a user
21is allowed to connect, every user has its own UUID which identifies it as an
22entity.
23
24With {command}`nixos-taskserver` the client certificate is created
25along with the UUID of the user, so it handles all of the credentials needed
26in order to setup the Taskwarrior client to work with a Taskserver.
27
28## The nixos-taskserver tool {#module-services-taskserver-nixos-taskserver-tool}
29
30Because Taskserver by default only provides scripts to setup users
31imperatively, the {command}`nixos-taskserver` tool is used for
32addition and deletion of organisations along with users and groups defined
33by [](#opt-services.taskserver.organisations) and as well for
34imperative set up.
35
36The tool is designed to not interfere if the command is used to manually set
37up some organisations, users or groups.
38
39For example if you add a new organisation using {command}`nixos-taskserver
40org add foo`, the organisation is not modified and deleted no
41matter what you define in
42{option}`services.taskserver.organisations`, even if you're adding
43the same organisation in that option.
44
45The tool is modelled to imitate the official {command}`taskd`
46command, documentation for each subcommand can be shown by using the
47{option}`--help` switch.
48
49## Declarative/automatic CA management {#module-services-taskserver-declarative-ca-management}
50
51Everything is done according to what you specify in the module options,
52however in order to set up a Taskwarrior client for synchronisation with a
53Taskserver instance, you have to transfer the keys and certificates to the
54client machine.
55
56This is done using {command}`nixos-taskserver user export $orgname
57$username` which is printing a shell script fragment to stdout
58which can either be used verbatim or adjusted to import the user on the
59client machine.
60
61For example, let's say you have the following configuration:
62```ShellSession
63{
64 services.taskserver.enable = true;
65 services.taskserver.fqdn = "server";
66 services.taskserver.listenHost = "::";
67 services.taskserver.organisations.my-company.users = [ "alice" ];
68}
69```
70This creates an organisation called `my-company` with the
71user `alice`.
72
73Now in order to import the `alice` user to another machine
74`alicebox`, all we need to do is something like this:
75```ShellSession
76$ ssh server nixos-taskserver user export my-company alice | sh
77```
78Of course, if no SSH daemon is available on the server you can also copy
79& paste it directly into a shell.
80
81After this step the user should be set up and you can start synchronising
82your tasks for the first time with {command}`task sync init` on
83`alicebox`.
84
85Subsequent synchronisation requests merely require the command {command}`task
86sync` after that stage.
87
88## Manual CA management {#module-services-taskserver-manual-ca-management}
89
90If you set any options within
91[service.taskserver.pki.manual](#opt-services.taskserver.pki.manual.ca.cert).*,
92{command}`nixos-taskserver` won't issue certificates, but you can
93still use it for adding or removing user accounts.