94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
|
# Taskserver {#module-services-taskserver}
|
||
|
|
|
||
|
|
Taskserver is the server component of
|
||
|
|
[Taskwarrior](https://taskwarrior.org/), a free and
|
||
|
|
open source todo list application.
|
||
|
|
|
||
|
|
*Upstream documentation:* <https://taskwarrior.org/docs/#taskd>
|
||
|
|
|
||
|
|
## Configuration {#module-services-taskserver-configuration}
|
||
|
|
|
||
|
|
Taskserver does all of its authentication via TLS using client certificates,
|
||
|
|
so you either need to roll your own CA or purchase a certificate from a
|
||
|
|
known CA, which allows creation of client certificates. These certificates
|
||
|
|
are usually advertised as "server certificates".
|
||
|
|
|
||
|
|
So in order to make it easier to handle your own CA, there is a helper tool
|
||
|
|
called {command}`nixos-taskserver` which manages the custom CA along
|
||
|
|
with Taskserver organisations, users and groups.
|
||
|
|
|
||
|
|
While the client certificates in Taskserver only authenticate whether a user
|
||
|
|
is allowed to connect, every user has its own UUID which identifies it as an
|
||
|
|
entity.
|
||
|
|
|
||
|
|
With {command}`nixos-taskserver` the client certificate is created
|
||
|
|
along with the UUID of the user, so it handles all of the credentials needed
|
||
|
|
in order to setup the Taskwarrior client to work with a Taskserver.
|
||
|
|
|
||
|
|
## The nixos-taskserver tool {#module-services-taskserver-nixos-taskserver-tool}
|
||
|
|
|
||
|
|
Because Taskserver by default only provides scripts to setup users
|
||
|
|
imperatively, the {command}`nixos-taskserver` tool is used for
|
||
|
|
addition and deletion of organisations along with users and groups defined
|
||
|
|
by [](#opt-services.taskserver.organisations) and as well for
|
||
|
|
imperative set up.
|
||
|
|
|
||
|
|
The tool is designed to not interfere if the command is used to manually set
|
||
|
|
up some organisations, users or groups.
|
||
|
|
|
||
|
|
For example if you add a new organisation using {command}`nixos-taskserver
|
||
|
|
org add foo`, the organisation is not modified and deleted no
|
||
|
|
matter what you define in
|
||
|
|
{option}`services.taskserver.organisations`, even if you're adding
|
||
|
|
the same organisation in that option.
|
||
|
|
|
||
|
|
The tool is modelled to imitate the official {command}`taskd`
|
||
|
|
command, documentation for each subcommand can be shown by using the
|
||
|
|
{option}`--help` switch.
|
||
|
|
|
||
|
|
## Declarative/automatic CA management {#module-services-taskserver-declarative-ca-management}
|
||
|
|
|
||
|
|
Everything is done according to what you specify in the module options,
|
||
|
|
however in order to set up a Taskwarrior client for synchronisation with a
|
||
|
|
Taskserver instance, you have to transfer the keys and certificates to the
|
||
|
|
client machine.
|
||
|
|
|
||
|
|
This is done using {command}`nixos-taskserver user export $orgname
|
||
|
|
$username` which is printing a shell script fragment to stdout
|
||
|
|
which can either be used verbatim or adjusted to import the user on the
|
||
|
|
client machine.
|
||
|
|
|
||
|
|
For example, let's say you have the following configuration:
|
||
|
|
```ShellSession
|
||
|
|
{
|
||
|
|
services.taskserver.enable = true;
|
||
|
|
services.taskserver.fqdn = "server";
|
||
|
|
services.taskserver.listenHost = "::";
|
||
|
|
services.taskserver.organisations.my-company.users = [ "alice" ];
|
||
|
|
}
|
||
|
|
```
|
||
|
|
This creates an organisation called `my-company` with the
|
||
|
|
user `alice`.
|
||
|
|
|
||
|
|
Now in order to import the `alice` user to another machine
|
||
|
|
`alicebox`, all we need to do is something like this:
|
||
|
|
```ShellSession
|
||
|
|
$ ssh server nixos-taskserver user export my-company alice | sh
|
||
|
|
```
|
||
|
|
Of course, if no SSH daemon is available on the server you can also copy
|
||
|
|
& paste it directly into a shell.
|
||
|
|
|
||
|
|
After this step the user should be set up and you can start synchronising
|
||
|
|
your tasks for the first time with {command}`task sync init` on
|
||
|
|
`alicebox`.
|
||
|
|
|
||
|
|
Subsequent synchronisation requests merely require the command {command}`task
|
||
|
|
sync` after that stage.
|
||
|
|
|
||
|
|
## Manual CA management {#module-services-taskserver-manual-ca-management}
|
||
|
|
|
||
|
|
If you set any options within
|
||
|
|
[service.taskserver.pki.manual](#opt-services.taskserver.pki.manual.ca.cert).*,
|
||
|
|
{command}`nixos-taskserver` won't issue certificates, but you can
|
||
|
|
still use it for adding or removing user accounts.
|