about summary refs log tree commit diff
path: root/nixpkgs/nixos/modules/services/misc/taskserver/doc.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixpkgs/nixos/modules/services/misc/taskserver/doc.xml')
-rw-r--r--nixpkgs/nixos/modules/services/misc/taskserver/doc.xml135
1 files changed, 0 insertions, 135 deletions
diff --git a/nixpkgs/nixos/modules/services/misc/taskserver/doc.xml b/nixpkgs/nixos/modules/services/misc/taskserver/doc.xml
deleted file mode 100644
index f6ead7c37857..000000000000
--- a/nixpkgs/nixos/modules/services/misc/taskserver/doc.xml
+++ /dev/null
@@ -1,135 +0,0 @@
-<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>
-
-  <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 <quote>server certificates</quote>.
-  </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"/> 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>
-{
-  <xref linkend="opt-services.taskserver.enable"/> = true;
-  <xref linkend="opt-services.taskserver.fqdn"/> = "server";
-  <xref linkend="opt-services.taskserver.listenHost"/> = "::";
-  <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>
-
-  <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
-   &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 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>