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