Göteborg Bit Factory                                                  June 2013

                          Taskserver Operation Guide
                                   Version 1


Status of this Memo

   This document provides information for the Internet community.  It does not
   specify an Internet standard of any kind.  Distribution of this document is
   not restricted.


Copyright Notice

   Copyright (C) 2010 - 2014, Göteborg Bit Factory.


Abstract

   This document describes the care and feeding of Taskserver.  If you wish to
   run your own Taskserver, this document provides all the information you
   need, provided you have sufficient working knowledge regarding the upkeep of
   servers.  Operating a Taskserver is not for casual users.


Table of Contents

   1      Introduction
   1.1    Requirements
   2      Installation & Setup
   3      Updates
   4      PKI
   5      Server Start/Stop
   6      User Configuration
   6.1      General
   6.2      Organizations
   6.3      Groups
   6.4      Users
   6.5      Redirects
   7      Backups
   8      Monitoring
   9      Troubleshooting
   10     References
   11     Acknowledgements
   12     Authors' Addresses
   13     Full Copyright Statement


1  Introduction

   Operating your own Taskserver is straightforward.  You will need the
   following:

   - A machine capable of running the Taskserver.  See the NEWS file for a list
     of platforms and operating systems on which Taskserver has been tested.
     There are likely other combinations that support Taskserver that have not
     been tested.

   - Connectivity from your client to your server.  This may involve firewall or
     VPN, but access is needed.

   - An open port.  The default is 53589.

   - Tools:  C++ compiler, CMake, make, Perl and Python, Gnu certtools

   - Libraries:  GnuTLS, libuuid

   - Storage: enough storage for task list history per user.  A guideline for
     usage is 1MiB per user, per year.


1.1  Requirements

   In this document, we adopt the convention discussed in Section 1.3.2 of
   [RFC1122] of using the capitalized words MUST, REQUIRED, SHOULD, RECOMMENDED,
   MAY, and OPTIONAL to define the significance of each particular requirement
   specified in this document.

   In brief: "MUST" (or "REQUIRED") means that the item is an absolute
   requirement of the specification; "SHOULD" (or "RECOMMENDED") means there may
   exist valid reasons for ignoring this item, but the full implications should
   be understood before doing so; and "MAY" (or "OPTIONAL") means that this item
   is optional, and may be omitted without careful consideration.


2  Installation & Setup

   Clone the git source repository using:

      $ git clone git://tasktools.org/taskd.git taskd.git

   Use the 'master' branch, which always represents the current stable release,
   build and install.

      $ cd taskd.git
      $ cmake .
      $ make
      $ cd test
      $ make
      $ ./run_all

   Only proceed if there are no test failures.

      $ cd ..
      $ sudo make install

   Verify your build and installation with the diagnostics command:

      $ taskd diagnostics

   A data 'root' is needed.  This will be the root of the directory structure
   that will store all the data.  Choose a root location, create the directory
   and initialize the server:

      $ export TASKDDATA=/path/to/task/server/data
      $ mkdir -p $TASKDDATA
      $ taskd init --data $TASKDDATA

   Basic configuration is needed before the server can be started.  The config
   command makes use of the TASKDDATA variable, otherwise you need to specify
   '--data /path/to/task/server/data' with each command.

      $ taskd config log      /path/to/taskd.log
      $ taskd config pid.file /path/to/taskd.pid
      $ taskd config ip.log   1

   The next step is to allow/deny specific clients.  Taskwarrior has a client
   defined as 'task 2.3.0', so to allow that:

      $ taskd config client.allow 'task [2-9]'
      $ taskd config client.deny none

   Note that the values are regular expressions, and it is necessary to allow
   for some flexibility in the version number.  The above is a very general
   pattern, but it could be more specific.  To allow any client, do this:

      $ taskd config client.allow all
      $ taskd config client.deny none

   To override the confirmation question for each of the above, you can specify
   the '--force' option:

      $ taskd config --force ip.log 1

   View the current configuration with:

      $ taskd config


3  Updates

   Updating Taskserver involves a clone of the repository, build, test and
   install, then a server bounce.

      $ git clone git://tasktools.org/taskd.git taskd.git
      $ cd taskd.git
      $ cmake .
      $ make
      $ cd test
      $ make
      $ ./run_all

   Only proceed if there are no test failures.

   Check the ChangeLog and NEWS files in the distribution for any new or
   obsolete configuration settings that may need to be changed.

      $ cd ..
      $ sudo make install
      $ taskdctl restart


4  PKI

   *****************************************************************************
   Warning

   These instructions refer to self-signed certs which are not suitable for
   production use.
   *****************************************************************************

   The server needs a cert, key and crl.  For testing purposes, there is a
   script that will do all of this:

      $ cd taskd.git/pki
      $ ./generate

   Once the various files are created, install them in $TASKDDATA:

      $ cp client.cert.pem $TASKDDATA
      $ cp server.cert.pem $TASKDDATA
      $ cp server.key.pem $TASKDDATA
      $ cp server.crl.pem $TASKDDATA

   Configure the server to use them:

      $ taskd config client.cert $TASKDDATA/client.cert.pem
      $ taskd config server.cert $TASKDDATA/server.cert.pem
      $ taskd config server.key $TASKDDATA/server.key.pem
      $ taskd config server.crl $TASKDDATA/server.crl.pem

   If the server.cert is self-signed, you may want to include the ca.cert.pem
   file like this:

      $ cp ca.cert.pem $TASKDDATA
      $ taskd config ca.cert $TASKDDATA/ca.cert.pem

   Note that the 'client.cert.pem' is intended for use by Taskserver clients
   clients like Taskwarrior and the 'taskd client ...' interface.

   Ordinarily, a new 'client.cert.pem' is generated for each user.

   For every client of the Taskserver, you will need to generate a new
   'client.cert.pem' file, using this:

      $ cd taskd.git/pki
      $ ./generate.client

   The resultant 'client.cert.pem' and 'client.key.pem' files are needed by the
   client.


5  Server Start/Stop

   There is a 'taskdctl' script to perform start/stop/restart.  Use it like
   this:

      $ export TASKDDATA=/path/to/task/server/data
      $ taskdctl start
      $ taskdctl restart
      $ taskdctl stop

   This script is just a convenience, and you can directly run the commands.  To
   start the server:

      $ taskd server --data /path/to/task/server/data

   Or if the TASKDDATA variable is defined:

      $ taskd server

   This can be terminated with Ctrl-C.  To start a daemon server:

      $ taskd server --daemon

   The daemon server needs to be terminated with a kill.  See the pid.file
   config setting for the PID.


6  User Configuration

   The 'config' command is used here to illustrate how to manage users of a
   Taskserver.  The structure of the user accounts is such that future expansion
   to include organizations and groups will not require changes to the data
   root.


6.1  General

   Note that all taskd commands shown support the TASKDDATA environment variable
   but also support '--date /path/to/task/server/data' as well.  In these
   examples, the former is assumed to be set:

      $ export TASKDDATA=/path/to/task/server/data

   Note that the 'taskdctl' script requires TASKDDATA.


6.2  Organizations

   An Organization is the top-level structure on the server.  A user MUST belong
   to one Organization.

   In this example, one organization named 'Public' is created.  An organization
   may contain multiple words, but may not contain a slash (U+002F).

      $ taskd add org Public

   An organization can be removed permanently with:

      $ taskd remove org Public

   This is a destructive command, and not recommended.  It will remove an entire
   set of related groups and users.

   You may suspend an organization:

      $ taskd suspend org Public

   This will prevent any users in that organization from using the server.  This
   is one way to take the server offline, while keeping it running.  A suspended
   organization can be restore with:

      $ taskd resume org Public

   The server supports an unlimited number of organizations.


6.3  Groups

   Groups are equivalent to shared task lists within an organization.  Groups
   are not yet supported.

   The data structures for groups is managed in a similar way to organizations,
   using these commands:

      $ taskd add     group <org> <group>
      $ taskd remove  group <org> <group>
      $ taskd suspend group <org> <group>
      $ taskd resume  group <org> <group>


6.4  Users

   A user must be added to an organization.  When adding a user, a key is
   generated and shown.  This is a user-specific secret key that is needed by
   the client.  For example:

      $ taskd add user Public John_D
      New user key: 1b89dd01-7a33-4890-815f-1f87f090cbe8

   Note that a PKI cert is also needed, see the PKI section.

   The data structures for users is managed in a similar way to organizations,
   using these commands:

      $ taskd add     user <org> <user>
      $ taskd remove  user <org> <key>
      $ taskd suspend user <org> <key>
      $ taskd resume  user <org> <key>


6.5  Redirects

   If traffic on a server becomes too great, organizations can be relocated to
   another server instance.  This simply requires duplicating the disk structure
   under:

      <root>/orgs/<org>

   Then adding a redirect file, like this:

      $ echo 'server.domain.com:1234' > <root>/orgs/<org>/redirect

   Will cause the server to issue 301 codes to the client, with an "info" header
   variable that points to 'server.domain.com:1234'.  The client SHOULD then
   update it's configuration and make a new request.


7  Backups

   The data needing backup consists of only one directory, which is the data
   root.  It is recommended that the server be taken offline for this:

      $ taskdctl stop
      $ <your backup program here>
      $ taskdctl start

   Rotating the Taskserver log file requires the same care.


8  Monitoring

   The Taskserver has a client interface, where arbitrary requests can be sent.
   This can include the 'statistics' request.  Here is an example:

      $ cat stats.request
      type: statistics
      org: <Organization>
      user: <User>
      key: <Key>
      client: taskd 1.0.0
      protocol: v1
      
      
      $

   Note that the request file has two blank lines at the end.  You will need to
   provide a valid organization, user and key.  Once you have a valid request
   file, use the 'client' command to send the request to the server.  The
   response is shown in raw form:

      $ taskd client localhost:53589 stats.request
      >>> stats.request
      <<<
      average request bytes: 0
      average response bytes: 0
      average response time: 0.000000
      code: 200
      errors: 0
      idle: 1.000000
      maximum response time: 0.000000
      status: Ok
      total bytes in: 0
      total bytes out: 0
      tps: 0.000000
      transactions: 1
      uptime: 28
      client: taskd 1.0.0

   This response shows a Taskserver that has been running for only 28 seconds,
   and has processed one transaction.  This response can be easily parsed and
   stored for monitoring purposes.


9  Troubleshooting

   During the alpha and beta stages, some hints for troubleshooting have been
   assembled.  They are:

   - Is the client (taskwarrior) able to communicate through your firewall to
     the server (taskserver)?  By default, port 53589 is used, and must be open
     on the server.

   - If you are unable to open firewall ports, you can use an SSH Tunnel to
     route port 53589 traffic over port 22.

   - Did you follow the instructions for setup exactly?  This is the largest
     cause of misconfiguration.

   - Setting 'debug.tls=2' for both client and server generates diagnostic
     output that can help diagnose problems with TLS handshake, certs, keys,
     and ciphers.  For Taskserver, with debug.cls=2, run the server
     interactively rather than as a daemon, to see the diagnostics.

   - Setting 'ciphers' (Taskserver) or 'taskd.ciphers' (Taskwarrior) can force
     the use of different ciphers.  Use 'gnutls-cli --list' to see a list of
     installed ciphers, and confirm that there is overlap between client and
     server.

   - In the event of a self-signed cert being used, is the CA cert configured?
     Alternatively, is 'taskd.trust=yes' set for Taskwarrior?

   - Please report problems that you see to support@taskwarrior.org.  When
     reporting a problem, please include:

      * Output from 'taskd diagnostics' command
      * Output from 'task diagnostics' command
      * The taskd.log contents


10  References
 
   [RFC640] Postel, J., "Revised FTP Reply Codes", RFC 640, June,
        1975.

   [RFC1122] IETF, "Requirements for Internet Hosts - Communication
        Layers", October 1989.


11  Acknowledgements

   Thanks to everyone listed in the AUTHORS file, for your help in the
   specification, implementation, testing and documentation of this project.


12  Authors' Addresses

   Federico Hernandez
   Email: fredde@taskwarrior.org

   Paul Beckingham
   Email: paul@taskwarrior.org


13  Full Copyright Statement

   Copyright 2010 - 2014, Göteborg Bit Factory.
   All rights reserved.

   This document and translations of it may be copied and furnished to others,
   and derivative works that comment on or otherwise explain it or assist in its
   implementation may be prepared, copied, published and distributed, in whole
   or in part, without restriction of any kind, provided that the above
   copyright notice and this paragraph are included on all such copies and
   derivative works.  However, this document itself may not be modified in any
   way, such as by removing the copyright notice or by omission of certain
   sections.

   The limited permissions granted above are perpetual and will not be revoked
   by the authors or their successors or assigns.

   This document and the information contained herein is provided on an "AS IS"
   basis and the authors disclaim all warranties, express or implied, including
   but not limited to any warranty that the use of the information herein will
   not infringe any rights or any implied warranties of merchantability or
   fitness for a particular purpose.

---

