public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: format

Browse Source
This commit is contained in:
Graham Christensen
2018-09-29 20:51:11 -04:00
parent 9622cd3b38
commit 8413f22bb3
24 changed files with 1784 additions and 1533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nixos/modules/services/misc/taskserver/doc.xml
+100 -109
View File
@@ -2,101 +2,93 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="module-taskserver">
<title>Taskserver</title>
<title>Taskserver</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
</para>
<section xml:id="module-services-taskserver-configuration">
<title>Configuration</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
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 <quote>server certificates</quote>.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
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 organisations, users and groups.
</para>
<section xml:id="module-services-taskserver-configuration">
<title>Configuration</title>
<para>
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.
</para>
<para>
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.
<para>
With <command>nixos-taskserver</command> 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.
</para>
</section>
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
<title>The nixos-taskserver tool</title>
These certificates are usually advertised as
<quote>server certificates</quote>.
</para>
<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 <xref linkend="opt-services.taskserver.organisations"/> and as well for
imperative set up.
</para>
<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 organisations, users and groups.
</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>
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.
</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>
With <command>nixos-taskserver</command> 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.
</para>
</section>
<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 xml:id="module-services-taskserver-declarative-ca-management">
<title>Declarative/automatic CA management</title>
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
<title>The nixos-taskserver tool</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>
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 <xref linkend="opt-services.taskserver.organisations"/> and as well for
imperative set up.
</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>
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 xml:id="module-services-taskserver-declarative-ca-management">
<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:
<para>
For example, let's say you have the following configuration:
<screen>
{
<xref linkend="opt-services.taskserver.enable"/> = true;
@@ -105,40 +97,39 @@
<link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
}
</screen>
This creates an organisation called <literal>my-company</literal> with the
user <literal>alice</literal>.
</para>
This creates an organisation called <literal>my-company</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:
<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 my-company 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>
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>
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 xml:id="module-services-taskserver-manual-ca-management">
<title>Manual CA management</title>
<para>
Subsequent synchronisation requests merely require the command <command>task
sync</command> after that stage.
</para>
</section>
<section xml:id="module-services-taskserver-manual-ca-management">
<title>Manual CA management</title>
<para>
If you set any options within
<link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
<command>nixos-taskserver</command> won't issue certificates, but you can
still use it for adding or removing user accounts.
</para>
</section>
<para>
If you set any options within
<link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
<command>nixos-taskserver</command> won't issue certificates, but you can
still use it for adding or removing user accounts.
</para>
</section>
</chapter>