diff options
Diffstat (limited to 'nixos/modules/services/misc/taskserver/doc.xml')
| -rw-r--r-- | nixos/modules/services/misc/taskserver/doc.xml | 74 |
1 files changed, 18 insertions, 56 deletions
diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml index 5656bb85b373..902ed14940e5 100644 --- a/nixos/modules/services/misc/taskserver/doc.xml +++ b/nixos/modules/services/misc/taskserver/doc.xml @@ -4,87 +4,58 @@ xml:id="module-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. + 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"/> + <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>. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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> @@ -97,39 +68,30 @@ <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>. + 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: + 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. + 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>. + 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. + 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. + 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> |