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