diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml
index b41747872c66..15125b1411bd 100644
--- a/nixos/modules/services/misc/taskserver/doc.xml
+++ b/nixos/modules/services/misc/taskserver/doc.xml
@@ -32,7 +32,7 @@
So in order to make it easier to handle your own CA, there is a helper
tool called nixos-taskserver which manages the custom
- CA along with Taskserver users and groups.
+ CA along with Taskserver organisations, users and groups.
@@ -46,7 +46,99 @@
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
+
+
+ Because Taskserver by default only provides scripts to setup users
+ imperatively, the nixos-taskserver tool is used for
+ addition and deletion of organisations along with users and groups defined
+ by 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
+ nixos-taskserver org add foo, the organisation is not
+ modified and deleted no matter what you define in
+ , even if you're adding
+ the same organisation in that option.
+
+
+
+ The tool is modelled to imitate the official taskd
+ command, documentation for each subcommand can be shown by using the
+ switch.
+
+
+
+ Declarative/automatic 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
+ 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:
+
+{
+ services.taskserver.enable = true;
+ services.taskserver.fqdn = "server";
+ services.taskserver.listenHost = "::";
+ services.taskserver.organisations.NixOS.users = [ "alice" ];
+}
+
+ This creates an organisation called NixOS 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:
+
+$ ssh server nixos-taskserver user export NixOS 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 task sync init on
+ alicebox.
+
+
+
+ Subsequent synchronisation requests merely require the command
+ task sync after that stage.
+
+
+
+ Manual CA management
+
+
+ If you set any options within
+ , the automatic user and
+ CA management by the nixos-taskserver is disabled and
+ you need to create certificates and keys by yourself.
+