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