alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

nixos/taskserver: Finish module documentation

Browse source 
Apart from the options manual, this should cover the basics for setting
up a Taskserver. I am not a native speaker so this can and (probably)
should be improved, especially the wording/grammar.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
This commit is contained in:
aszlig 2016-04-12 06:19:59 +02:00
parent e2383b84f8
commit dd0d64afea
No known key found for this signature in database
GPG key ID: D0EBD0EC8C2DC961
1 changed files with 94 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
nixos/modules/services/misc/taskserver/doc.xml
View file

@ -32,7 +32,7 @@
<para>
So in order to make it easier to handle your own CA, there is a helper
tool called <command>nixos-taskserver</command> which manages the custom
CA along with Taskserver users and groups.
CA along with Taskserver organisations, users and groups.
</para>
<para>
@ -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.
</para>
</section>
<!-- TODO: Go more into the details of nixos-taskserver. -->
<section>
<title>The nixos-taskserver tool</title>
<para>
Because Taskserver by default only provides scripts to setup users
imperatively, the <command>nixos-taskserver</command> tool is used for
addition and deletion of organisations along with users and groups defined
by <option>services.taskserver.organisations</option> and as well for
imperative set up.
</para>
<para>
The tool is designed to not interfere if the command is used to manually
set up some organisations, users or groups.
</para>
<para>
For example if you add a new organisation using
<command>nixos-taskserver org add foo</command>, the organisation is not
modified and deleted no matter what you define in
<option>services.taskserver.organisations</option>, even if you're adding
the same organisation in that option.
</para>
<para>
The tool is modelled to imitate the official <command>taskd</command>
command, documentation for each subcommand can be shown by using the
<option>--help</option> switch.
</para>
</section>
<section>
<title>Declarative/automatic CA management</title>
<para>
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.
</para>
<para>
This is done using
<command>nixos-taskserver user export $orgname $username</command> 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.
</para>
<para>
For example, let's say you have the following configuration:
<screen>
{
services.taskserver.enable = true;
services.taskserver.fqdn = "server";
services.taskserver.listenHost = "::";
services.taskserver.organisations.NixOS.users = [ "alice" ];
}
</screen>
This creates an organisation called <literal>NixOS</literal> with the user
<literal>alice</literal>.
</para>
<para>
Now in order to import the <literal>alice</literal> user to another
machine <literal>alicebox</literal>, all we need to do is something like
this:
<screen>
$ ssh server nixos-taskserver user export NixOS alice | sh
</screen>
Of course, if no SSH daemon is available on the server you can also copy
&amp; paste it directly into a shell.
</para>
<para>
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</command> on
<literal>alicebox</literal>.
</para>
<para>
Subsequent synchronisation requests merely require the command
<command>task sync</command> after that stage.
</para>
</section>
<section>
<title>Manual CA management</title>
<para>
If you set any options within
<option>service.taskserver.pki.manual.*</option>, the automatic user and
CA management by the <command>nixos-taskserver</command> is disabled and
you need to create certificates and keys by yourself.
</para>
</section>
</chapter>