pyrox.dev
lol
nixos/taskserver: convert manual chapter to MD
+215
-127
+2
nixos/modules/services/misc/taskserver/default.nix
+2
nixos/modules/services/misc/taskserver/default.nix
···
566
566
})
567
567
];
568
568
569
+
# Don't edit the docbook xml directly, edit the md and generate it:
570
+
# `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > doc.xml`
569
571
meta.doc = ./doc.xml;
570
572
}
+93
nixos/modules/services/misc/taskserver/doc.md
+93
nixos/modules/services/misc/taskserver/doc.md
···
1
+
# Taskserver {#module-services-taskserver}
2
+
3
+
Taskserver is the server component of
4
+
[Taskwarrior](https://taskwarrior.org/), a free and
5
+
open source todo list application.
6
+
7
+
*Upstream documentation:* <https://taskwarrior.org/docs/#taskd>
8
+
9
+
## Configuration {#module-services-taskserver-configuration}
10
+
11
+
Taskserver does all of its authentication via TLS using client certificates,
12
+
so you either need to roll your own CA or purchase a certificate from a
13
+
known CA, which allows creation of client certificates. These certificates
14
+
are usually advertised as "server certificates".
15
+
16
+
So in order to make it easier to handle your own CA, there is a helper tool
17
+
called {command}`nixos-taskserver` which manages the custom CA along
18
+
with Taskserver organisations, users and groups.
19
+
20
+
While the client certificates in Taskserver only authenticate whether a user
21
+
is allowed to connect, every user has its own UUID which identifies it as an
22
+
entity.
23
+
24
+
With {command}`nixos-taskserver` the client certificate is created
25
+
along with the UUID of the user, so it handles all of the credentials needed
26
+
in order to setup the Taskwarrior client to work with a Taskserver.
27
+
28
+
## The nixos-taskserver tool {#module-services-taskserver-nixos-taskserver-tool}
29
+
30
+
Because Taskserver by default only provides scripts to setup users
31
+
imperatively, the {command}`nixos-taskserver` tool is used for
32
+
addition and deletion of organisations along with users and groups defined
33
+
by [](#opt-services.taskserver.organisations) and as well for
34
+
imperative set up.
35
+
36
+
The tool is designed to not interfere if the command is used to manually set
37
+
up some organisations, users or groups.
38
+
39
+
For example if you add a new organisation using {command}`nixos-taskserver
40
+
org add foo`, the organisation is not modified and deleted no
41
+
matter what you define in
42
+
{option}`services.taskserver.organisations`, even if you're adding
43
+
the same organisation in that option.
44
+
45
+
The tool is modelled to imitate the official {command}`taskd`
46
+
command, 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
+
51
+
Everything is done according to what you specify in the module options,
52
+
however in order to set up a Taskwarrior client for synchronisation with a
53
+
Taskserver instance, you have to transfer the keys and certificates to the
54
+
client machine.
55
+
56
+
This is done using {command}`nixos-taskserver user export $orgname
57
+
$username` which is printing a shell script fragment to stdout
58
+
which can either be used verbatim or adjusted to import the user on the
59
+
client machine.
60
+
61
+
For 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
+
```
70
+
This creates an organisation called `my-company` with the
71
+
user `alice`.
72
+
73
+
Now 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
+
```
78
+
Of course, if no SSH daemon is available on the server you can also copy
79
+
& paste it directly into a shell.
80
+
81
+
After this step the user should be set up and you can start synchronising
82
+
your tasks for the first time with {command}`task sync init` on
83
+
`alicebox`.
84
+
85
+
Subsequent synchronisation requests merely require the command {command}`task
86
+
sync` after that stage.
87
+
88
+
## Manual CA management {#module-services-taskserver-manual-ca-management}
89
+
90
+
If 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
93
+
still use it for adding or removing user accounts.
+120
-127
nixos/modules/services/misc/taskserver/doc.xml
+120
-127
nixos/modules/services/misc/taskserver/doc.xml
···
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 "server certificates".
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
-
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>
31
3
<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.
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.
35
7
</para>
36
-
37
8
<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.
9
+
<emphasis>Upstream documentation:</emphasis>
10
+
<link xlink:href="https://taskwarrior.org/docs/#taskd" role="uri">https://taskwarrior.org/docs/#taskd</link>
41
11
</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>
12
+
<section xml:id="module-services-taskserver-configuration">
13
+
<title>Configuration</title>
14
+
<para>
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".
20
+
</para>
21
+
<para>
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
25
+
and groups.
26
+
</para>
27
+
<para>
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.
31
+
</para>
32
+
<para>
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.
37
+
</para>
38
+
</section>
39
+
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
40
+
<title>The nixos-taskserver tool</title>
41
+
<para>
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
45
+
groups defined by
46
+
<xref linkend="opt-services.taskserver.organisations"></xref> and
47
+
as well for imperative set up.
48
+
</para>
49
+
<para>
50
+
The tool is designed to not interfere if the command is used to
51
+
manually set up some organisations, users or groups.
52
+
</para>
53
+
<para>
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.
59
+
</para>
60
+
<para>
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>
64
+
switch.
65
+
</para>
66
+
</section>
67
+
<section xml:id="module-services-taskserver-declarative-ca-management">
68
+
<title>Declarative/automatic CA management</title>
69
+
<para>
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.
74
+
</para>
75
+
<para>
76
+
This is done using
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
80
+
client machine.
81
+
</para>
82
+
<para>
83
+
For example, let's say you have the following configuration:
84
+
</para>
85
+
<programlisting>
93
86
{
94
87
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" ];
98
91
}
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>
92
+
</programlisting>
93
+
<para>
94
+
This creates an organisation called <literal>my-company</literal>
95
+
with the user <literal>alice</literal>.
96
+
</para>
97
+
<para>
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:
101
+
</para>
102
+
<programlisting>
103
+
$ ssh server nixos-taskserver user export my-company alice | sh
104
+
</programlisting>
105
+
<para>
106
+
Of course, if no SSH daemon is available on the server you can
107
+
also copy & paste it directly into a shell.
108
+
</para>
109
+
<para>
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>.
113
+
</para>
114
+
<para>
115
+
Subsequent synchronisation requests merely require the command
116
+
<command>task sync</command> after that stage.
117
+
</para>
118
+
</section>
119
+
<section xml:id="module-services-taskserver-manual-ca-management">
120
+
<title>Manual CA management</title>
121
+
<para>
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.
126
+
</para>
127
+
</section>
135
128
</chapter>