commit 2928e0c4876bcedbeb82675b217f9314c4fe2593 · pyrox.dev/nixpkgs

nixos/modules/services/misc/taskserver/default.nix

···

       566
        
           })

     

       567
        
         ];

     

       568
        
       

     

       0
        
       
     

       0
        
       
     

       569
        
         meta.doc = ./doc.xml;

     

       570
        
       }

···

       566
        
           })

     

       567
        
         ];

     

       568
        
       

     

       569
       +
         # Don't edit the docbook xml directly, edit the md and generate it:

     

       570
       +
         # `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`

     

       571
        
         meta.doc = ./doc.xml;

     

       572
        
       }

+93

nixos/modules/services/misc/taskserver/doc.md

···

       1
       +
       # Taskserver {#module-services-taskserver}

     

       2
       +
       

     

       3
       +
       Taskserver is the server component of

     

       4
       +
       [Taskwarrior](https://taskwarrior.org/), a free and

     

       5
       +
       open source todo list application.

     

       6
       +
       

     

       7
       +
       *Upstream documentation:* <https://taskwarrior.org/docs/#taskd>

     

       8
       +
       

     

       9
       +
       ## Configuration {#module-services-taskserver-configuration}

     

       10
       +
       

     

       11
       +
       Taskserver does all of its authentication via TLS using client certificates,

     

       12
       +
       so you either need to roll your own CA or purchase a certificate from a

     

       13
       +
       known CA, which allows creation of client certificates. These certificates

     

       14
       +
       are usually advertised as "server certificates".

     

       15
       +
       

     

       16
       +
       So in order to make it easier to handle your own CA, there is a helper tool

     

       17
       +
       called {command}`nixos-taskserver` which manages the custom CA along

     

       18
       +
       with Taskserver organisations, users and groups.

     

       19
       +
       

     

       20
       +
       While the client certificates in Taskserver only authenticate whether a user

     

       21
       +
       is allowed to connect, every user has its own UUID which identifies it as an

     

       22
       +
       entity.

     

       23
       +
       

     

       24
       +
       With {command}`nixos-taskserver` the client certificate is created

     

       25
       +
       along with the UUID of the user, so it handles all of the credentials needed

     

       26
       +
       in order to setup the Taskwarrior client to work with a Taskserver.

     

       27
       +
       

     

       28
       +
       ## The nixos-taskserver tool {#module-services-taskserver-nixos-taskserver-tool}

     

       29
       +
       

     

       30
       +
       Because Taskserver by default only provides scripts to setup users

     

       31
       +
       imperatively, the {command}`nixos-taskserver` tool is used for

     

       32
       +
       addition and deletion of organisations along with users and groups defined

     

       33
       +
       by [](#opt-services.taskserver.organisations) and as well for

     

       34
       +
       imperative set up.

     

       35
       +
       

     

       36
       +
       The tool is designed to not interfere if the command is used to manually set

     

       37
       +
       up some organisations, users or groups.

     

       38
       +
       

     

       39
       +
       For example if you add a new organisation using {command}`nixos-taskserver

     

       40
       +
       org add foo`, the organisation is not modified and deleted no

     

       41
       +
       matter what you define in

     

       42
       +
       {option}`services.taskserver.organisations`, even if you're adding

     

       43
       +
       the same organisation in that option.

     

       44
       +
       

     

       45
       +
       The tool is modelled to imitate the official {command}`taskd`

     

       46
       +
       command, documentation for each subcommand can be shown by using the

     

       47
       +
       {option}`--help` switch.

     

       48
       +
       

     

       49
       +
       ## Declarative/automatic CA management {#module-services-taskserver-declarative-ca-management}

     

       50
       +
       

     

       51
       +
       Everything is done according to what you specify in the module options,

     

       52
       +
       however in order to set up a Taskwarrior client for synchronisation with a

     

       53
       +
       Taskserver instance, you have to transfer the keys and certificates to the

     

       54
       +
       client machine.

     

       55
       +
       

     

       56
       +
       This is done using {command}`nixos-taskserver user export $orgname

     

       57
       +
       $username` which is printing a shell script fragment to stdout

     

       58
       +
       which can either be used verbatim or adjusted to import the user on the

     

       59
       +
       client machine.

     

       60
       +
       

     

       61
       +
       For example, let's say you have the following configuration:

     

       62
       +
       ```ShellSession

     

       63
       +
       {

     

       64
       +
         services.taskserver.enable = true;

     

       65
       +
         services.taskserver.fqdn = "server";

     

       66
       +
         services.taskserver.listenHost = "::";

     

       67
       +
         services.taskserver.organisations.my-company.users = [ "alice" ];

     

       68
       +
       }

     

       69
       +
       ```

     

       70
       +
       This creates an organisation called `my-company` with the

     

       71
       +
       user `alice`.

     

       72
       +
       

     

       73
       +
       Now in order to import the `alice` user to another machine

     

       74
       +
       `alicebox`, all we need to do is something like this:

     

       75
       +
       ```ShellSession

     

       76
       +
       $ ssh server nixos-taskserver user export my-company alice | sh

     

       77
       +
       ```

     

       78
       +
       Of course, if no SSH daemon is available on the server you can also copy

     

       79
       +
       &amp; paste it directly into a shell.

     

       80
       +
       

     

       81
       +
       After this step the user should be set up and you can start synchronising

     

       82
       +
       your tasks for the first time with {command}`task sync init` on

     

       83
       +
       `alicebox`.

     

       84
       +
       

     

       85
       +
       Subsequent synchronisation requests merely require the command {command}`task

     

       86
       +
       sync` after that stage.

     

       87
       +
       

     

       88
       +
       ## Manual CA management {#module-services-taskserver-manual-ca-management}

     

       89
       +
       

     

       90
       +
       If you set any options within

     

       91
       +
       [service.taskserver.pki.manual](#opt-services.taskserver.pki.manual.ca.cert).*,

     

       92
       +
       {command}`nixos-taskserver` won't issue certificates, but you can

     

       93
       +
       still use it for adding or removing user accounts.

+120 -127

nixos/modules/services/misc/taskserver/doc.xml

···

       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       -
           xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
           version="5.0"

     

       4
       -
           xml:id="module-services-taskserver">

     

       5
       -
        <title>Taskserver</title>

     

       6
       -
        <para>

     

       7
       -
         Taskserver is the server component of

     

       8
       -
         <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and

     

       9
       -
         open source todo list application.

     

       10
       -
        </para>

     

       11
       -
        <para>

     

       12
       -
         <emphasis>Upstream documentation:</emphasis>

     

       13
       -
         <link xlink:href="https://taskwarrior.org/docs/#taskd"/>

     

       14
       -
        </para>

     

       15
       -
        <section xml:id="module-services-taskserver-configuration">

     

       16
       -
         <title>Configuration</title>

     

       17
       -
       

     

       18
       -
         <para>

     

       19
       -
          Taskserver does all of its authentication via TLS using client certificates,

     

       20
       -
          so you either need to roll your own CA or purchase a certificate from a

     

       21
       -
          known CA, which allows creation of client certificates. These certificates

     

       22
       -
          are usually advertised as "server certificates".

     

       23
       -
         </para>

     

       24
       -
       

     

       25
       -
         <para>

     

       26
       -
          So in order to make it easier to handle your own CA, there is a helper tool

     

       27
       -
          called <command>nixos-taskserver</command> which manages the custom CA along

     

       28
       -
          with Taskserver organisations, users and groups.

     

       29
       -
         </para>

     

       30
       -
       

     

       31
        
         <para>

     

       32
       -
          While the client certificates in Taskserver only authenticate whether a user

     

       33
       -
          is allowed to connect, every user has its own UUID which identifies it as an

     

       34
       -
          entity.

     

       35
        
         </para>

     

       36
       -
       

     

       37
        
         <para>

     

       38
       -
          With <command>nixos-taskserver</command> the client certificate is created

     

       39
       -
          along with the UUID of the user, so it handles all of the credentials needed

     

       40
       -
          in order to setup the Taskwarrior client to work with a Taskserver.

     

       41
        
         </para>

     

       42
       -
        </section>

     

       43
       -
        <section xml:id="module-services-taskserver-nixos-taskserver-tool">

     

       44
       -
         <title>The nixos-taskserver tool</title>

     

       45
       -
       

     

       46
       -
         <para>

     

       47
       -
          Because Taskserver by default only provides scripts to setup users

     

       48
       -
          imperatively, the <command>nixos-taskserver</command> tool is used for

     

       49
       -
          addition and deletion of organisations along with users and groups defined

     

       50
       -
          by <xref linkend="opt-services.taskserver.organisations"/> and as well for

     

       51
       -
          imperative set up.

     

       52
       -
         </para>

     

       53
       -
       

     

       54
       -
         <para>

     

       55
       -
          The tool is designed to not interfere if the command is used to manually set

     

       56
       -
          up some organisations, users or groups.

     

       57
       -
         </para>

     

       58
       -
       

     

       59
       -
         <para>

     

       60
       -
          For example if you add a new organisation using <command>nixos-taskserver

     

       61
       -
          org add foo</command>, the organisation is not modified and deleted no

     

       62
       -
          matter what you define in

     

       63
       -
          <option>services.taskserver.organisations</option>, even if you're adding

     

       64
       -
          the same organisation in that option.

     

       65
       -
         </para>

     

       66
       -
       

     

       67
       -
         <para>

     

       68
       -
          The tool is modelled to imitate the official <command>taskd</command>

     

       69
       -
          command, documentation for each subcommand can be shown by using the

     

       70
       -
          <option>--help</option> switch.

     

       71
       -
         </para>

     

       72
       -
        </section>

     

       73
       -
        <section xml:id="module-services-taskserver-declarative-ca-management">

     

       74
       -
         <title>Declarative/automatic CA management</title>

     

       75
       -
       

     

       76
       -
         <para>

     

       77
       -
          Everything is done according to what you specify in the module options,

     

       78
       -
          however in order to set up a Taskwarrior client for synchronisation with a

     

       79
       -
          Taskserver instance, you have to transfer the keys and certificates to the

     

       80
       -
          client machine.

     

       81
       -
         </para>

     

       82
       -
       

     

       83
       -
         <para>

     

       84
       -
          This is done using <command>nixos-taskserver user export $orgname

     

       85
       -
          $username</command> which is printing a shell script fragment to stdout

     

       86
       -
          which can either be used verbatim or adjusted to import the user on the

     

       87
       -
          client machine.

     

       88
       -
         </para>

     

       89
       -
       

     

       90
       -
         <para>

     

       91
       -
          For example, let's say you have the following configuration:

     

       92
       -
       <screen>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       93
        
       {

     

       94
        
         services.taskserver.enable = true;

     

       95
       -
         services.taskserver.fqdn = "server";

     

       96
       -
         services.taskserver.listenHost = "::";

     

       97
       -
         services.taskserver.organisations.my-company.users = [ "alice" ];

     

       98
        
       }

     

       99
       -
       </screen>

     

       100
       -
          This creates an organisation called <literal>my-company</literal> with the

     

       101
       -
          user <literal>alice</literal>.

     

       102
       -
         </para>

     

       103
       -
       

     

       104
       -
         <para>

     

       105
       -
          Now in order to import the <literal>alice</literal> user to another machine

     

       106
       -
          <literal>alicebox</literal>, all we need to do is something like this:

     

       107
       -
       <screen>

     

       108
       -
       <prompt>$ </prompt>ssh server nixos-taskserver user export my-company alice | sh

     

       109
       -
       </screen>

     

       110
       -
          Of course, if no SSH daemon is available on the server you can also copy

     

       111
       -
          &amp; paste it directly into a shell.

     

       112
       -
         </para>

     

       113
       -
       

     

       114
       -
         <para>

     

       115
       -
          After this step the user should be set up and you can start synchronising

     

       116
       -
          your tasks for the first time with <command>task sync init</command> on

     

       117
       -
          <literal>alicebox</literal>.

     

       118
       -
         </para>

     

       119
       -
       

     

       120
       -
         <para>

     

       121
       -
          Subsequent synchronisation requests merely require the command <command>task

     

       122
       -
          sync</command> after that stage.

     

       123
       -
         </para>

     

       124
       -
        </section>

     

       125
       -
        <section xml:id="module-services-taskserver-manual-ca-management">

     

       126
       -
         <title>Manual CA management</title>

     

       127
       -
       

     

       128
       -
         <para>

     

       129
       -
          If you set any options within

     

       130
       -
          <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,

     

       131
       -
          <command>nixos-taskserver</command> won't issue certificates, but you can

     

       132
       -
          still use it for adding or removing user accounts.

     

       133
       -
         </para>

     

       134
       -
        </section>

     

       135
        
       </chapter>

···

       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-taskserver">

     

       2
       +
         <title>Taskserver</title>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       3
        
         <para>

     

       4
       +
           Taskserver is the server component of

     

       5
       +
           <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a

     

       6
       +
           free and open source todo list application.

     

       7
        
         </para>

     

       0
        
       
     

       8
        
         <para>

     

       9
       +
           <emphasis>Upstream documentation:</emphasis>

     

       10
       +
           <link xlink:href="https://taskwarrior.org/docs/#taskd" role="uri">https://taskwarrior.org/docs/#taskd</link>

     

       0
        
       
     

       11
        
         </para>

     

       12
       +
         <section xml:id="module-services-taskserver-configuration">

     

       13
       +
           <title>Configuration</title>

     

       14
       +
           <para>

     

       15
       +
             Taskserver does all of its authentication via TLS using client

     

       16
       +
             certificates, so you either need to roll your own CA or purchase a

     

       17
       +
             certificate from a known CA, which allows creation of client

     

       18
       +
             certificates. These certificates are usually advertised as

     

       19
       +
             &quot;server certificates&quot;.

     

       20
       +
           </para>

     

       21
       +
           <para>

     

       22
       +
             So in order to make it easier to handle your own CA, there is a

     

       23
       +
             helper tool called <command>nixos-taskserver</command> which

     

       24
       +
             manages the custom CA along with Taskserver organisations, users

     

       25
       +
             and groups.

     

       26
       +
           </para>

     

       27
       +
           <para>

     

       28
       +
             While the client certificates in Taskserver only authenticate

     

       29
       +
             whether a user is allowed to connect, every user has its own UUID

     

       30
       +
             which identifies it as an entity.

     

       31
       +
           </para>

     

       32
       +
           <para>

     

       33
       +
             With <command>nixos-taskserver</command> the client certificate is

     

       34
       +
             created along with the UUID of the user, so it handles all of the

     

       35
       +
             credentials needed in order to setup the Taskwarrior client to

     

       36
       +
             work with a Taskserver.

     

       37
       +
           </para>

     

       38
       +
         </section>

     

       39
       +
         <section xml:id="module-services-taskserver-nixos-taskserver-tool">

     

       40
       +
           <title>The nixos-taskserver tool</title>

     

       41
       +
           <para>

     

       42
       +
             Because Taskserver by default only provides scripts to setup users

     

       43
       +
             imperatively, the <command>nixos-taskserver</command> tool is used

     

       44
       +
             for addition and deletion of organisations along with users and

     

       45
       +
             groups defined by

     

       46
       +
             <xref linkend="opt-services.taskserver.organisations"></xref> and

     

       47
       +
             as well for imperative set up.

     

       48
       +
           </para>

     

       49
       +
           <para>

     

       50
       +
             The tool is designed to not interfere if the command is used to

     

       51
       +
             manually set up some organisations, users or groups.

     

       52
       +
           </para>

     

       53
       +
           <para>

     

       54
       +
             For example if you add a new organisation using

     

       55
       +
             <command>nixos-taskserver org add foo</command>, the organisation

     

       56
       +
             is not modified and deleted no matter what you define in

     

       57
       +
             <option>services.taskserver.organisations</option>, even if you're

     

       58
       +
             adding the same organisation in that option.

     

       59
       +
           </para>

     

       60
       +
           <para>

     

       61
       +
             The tool is modelled to imitate the official

     

       62
       +
             <command>taskd</command> command, documentation for each

     

       63
       +
             subcommand can be shown by using the <option>--help</option>

     

       64
       +
             switch.

     

       65
       +
           </para>

     

       66
       +
         </section>

     

       67
       +
         <section xml:id="module-services-taskserver-declarative-ca-management">

     

       68
       +
           <title>Declarative/automatic CA management</title>

     

       69
       +
           <para>

     

       70
       +
             Everything is done according to what you specify in the module

     

       71
       +
             options, however in order to set up a Taskwarrior client for

     

       72
       +
             synchronisation with a Taskserver instance, you have to transfer

     

       73
       +
             the keys and certificates to the client machine.

     

       74
       +
           </para>

     

       75
       +
           <para>

     

       76
       +
             This is done using

     

       77
       +
             <command>nixos-taskserver user export $orgname $username</command>

     

       78
       +
             which is printing a shell script fragment to stdout which can

     

       79
       +
             either be used verbatim or adjusted to import the user on the

     

       80
       +
             client machine.

     

       81
       +
           </para>

     

       82
       +
           <para>

     

       83
       +
             For example, let's say you have the following configuration:

     

       84
       +
           </para>

     

       85
       +
           <programlisting>

     

       86
        
       {

     

       87
        
         services.taskserver.enable = true;

     

       88
       +
         services.taskserver.fqdn = &quot;server&quot;;

     

       89
       +
         services.taskserver.listenHost = &quot;::&quot;;

     

       90
       +
         services.taskserver.organisations.my-company.users = [ &quot;alice&quot; ];

     

       91
        
       }

     

       92
       +
       </programlisting>

     

       93
       +
           <para>

     

       94
       +
             This creates an organisation called <literal>my-company</literal>

     

       95
       +
             with the user <literal>alice</literal>.

     

       96
       +
           </para>

     

       97
       +
           <para>

     

       98
       +
             Now in order to import the <literal>alice</literal> user to

     

       99
       +
             another machine <literal>alicebox</literal>, all we need to do is

     

       100
       +
             something like this:

     

       101
       +
           </para>

     

       102
       +
           <programlisting>

     

       103
       +
       $ ssh server nixos-taskserver user export my-company alice | sh

     

       104
       +
       </programlisting>

     

       105
       +
           <para>

     

       106
       +
             Of course, if no SSH daemon is available on the server you can

     

       107
       +
             also copy &amp; paste it directly into a shell.

     

       108
       +
           </para>

     

       109
       +
           <para>

     

       110
       +
             After this step the user should be set up and you can start

     

       111
       +
             synchronising your tasks for the first time with

     

       112
       +
             <command>task sync init</command> on <literal>alicebox</literal>.

     

       113
       +
           </para>

     

       114
       +
           <para>

     

       115
       +
             Subsequent synchronisation requests merely require the command

     

       116
       +
             <command>task sync</command> after that stage.

     

       117
       +
           </para>

     

       118
       +
         </section>

     

       119
       +
         <section xml:id="module-services-taskserver-manual-ca-management">

     

       120
       +
           <title>Manual CA management</title>

     

       121
       +
           <para>

     

       122
       +
             If you set any options within

     

       123
       +
             <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,

     

       124
       +
             <command>nixos-taskserver</command> won't issue certificates, but

     

       125
       +
             you can still use it for adding or removing user accounts.

     

       126
       +
           </para>

     

       127
       +
         </section>

     

       128
        
       </chapter>