nixos/taskserver: convert manual chapter to MD
This commit is contained in:
pennae
parent
0cc9d6cf5d
commit
2928e0c487
@ -566,5 +566,7 @@ in {
|
||||
})
|
||||
];
|
||||
|
||||
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||
# `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`
|
||||
meta.doc = ./doc.xml;
|
||||
}
|
||||
|
||||
93
nixos/modules/services/misc/taskserver/doc.md
Normal file
93
nixos/modules/services/misc/taskserver/doc.md
Normal file
@ -0,0 +1,93 @@
|
||||
# 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.
|
||||
@ -1,135 +1,128 @@
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
version="5.0"
|
||||
xml:id="module-services-taskserver">
|
||||
<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>
|
||||
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-taskserver">
|
||||
<title>Taskserver</title>
|
||||
<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. These certificates
|
||||
are usually advertised as "server certificates".
|
||||
Taskserver is the server component of
|
||||
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a
|
||||
free and open source todo list application.
|
||||
</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.
|
||||
<emphasis>Upstream documentation:</emphasis>
|
||||
<link xlink:href="https://taskwarrior.org/docs/#taskd" role="uri">https://taskwarrior.org/docs/#taskd</link>
|
||||
</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>
|
||||
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>
|
||||
|
||||
<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>
|
||||
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:
|
||||
<screen>
|
||||
<section xml:id="module-services-taskserver-configuration">
|
||||
<title>Configuration</title>
|
||||
<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. These certificates are usually advertised as
|
||||
"server certificates".
|
||||
</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>
|
||||
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>
|
||||
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>
|
||||
<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"></xref> 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 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>
|
||||
<programlisting>
|
||||
{
|
||||
services.taskserver.enable = true;
|
||||
services.taskserver.fqdn = "server";
|
||||
services.taskserver.listenHost = "::";
|
||||
services.taskserver.organisations.my-company.users = [ "alice" ];
|
||||
services.taskserver.fqdn = "server";
|
||||
services.taskserver.listenHost = "::";
|
||||
services.taskserver.organisations.my-company.users = [ "alice" ];
|
||||
}
|
||||
</screen>
|
||||
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:
|
||||
<screen>
|
||||
<prompt>$ </prompt>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
|
||||
& 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 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>
|
||||
</programlisting>
|
||||
<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>
|
||||
<programlisting>
|
||||
$ ssh server nixos-taskserver user export my-company alice | sh
|
||||
</programlisting>
|
||||
<para>
|
||||
Of course, if no SSH daemon is available on the server you can
|
||||
also copy & 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 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>
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user