depot/third_party/nixpkgs/nixos/modules/services/misc/taskserver/default.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<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 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">https://taskwarrior.org/docs/#taskd</link>
  </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:
    </para>
    <programlisting>
{
  services.taskserver.enable = true;
  services.taskserver.fqdn = &quot;server&quot;;
  services.taskserver.listenHost = &quot;::&quot;;
  services.taskserver.organisations.my-company.users = [ &quot;alice&quot; ];
}
</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 &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>