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