# entitlements
A tool to manage entitlements in SUKAT

## Setup

In order to avoid having to activate a virtual environment to run the
scripts, the path to the venv is hardcoded in the scripts'
shebang. Because of this, it's important to use the exact paths listed
in the setup instructions.

 * Clone the repo into `/opt/entitlements`
 * Create a venv in the project directory: `python3 -m venv env`
 * Activate the venv and install dependencies:
   `source env/bin/activate; pip install -r requirements.txt`  
   There may be errors regarding installation of the gssapi
   package. In that case, make sure the apt packages `python3-dev` and
   `heimdal-dev` are both installed on the system.
 * Copy ```config.ini.example``` to ```config.ini``` and update
   with real credentials.
 * Create your entitlement map file according to the value of
   ```entitlement_map``` in ```config.ini```. See ```entmap.conf.example```
   and the section below for details on the format.
 * Run update-entitlements.py to synchronize with SUKAT.

## update-entitlements.py

Synchronizes the entitlements in SUKAT with the desired state from entmap.conf.

```
usage: update-entitlements.py [-h] [--dry-run] [--debug]
                              [--only-add | --only-remove]
                              [<entitlement> ...]

Update entitlements in SUKAT according to entmap.conf.

positional arguments:
  <entitlement>  If present, only act on these entitlements. If not present,
                 act on all entitlements.

options:
  -h, --help     show this help message and exit
  --dry-run      Don't make any changes, only print what would be done.
  --debug        Show extra output for debug purposes.
  --only-add     Only add entitlements, don't remove any.
  --only-remove  Only remove entitlements, don't add any.
```

## manage-entitlements.py

Adds and/or removes entitlements to/from a given user or list of users and
updates entmap.conf to reflect the changes made.

```
usage: manage-entitlements.py [--entmap-update]
                              [<username> ...]
                              [--add, -a <entitlement> ...]
                              [--remove, -r <entitlement> ...]
       manage-entitlements.py -h|--help


Manage entitlements in SUKAT

positional arguments:
  <username>            The user(s) to be acted upon. If no users given, read
                        users from stdin.

options:
  -h, --help            show this help message and exit
  --add [<entitlement> ...], -a [<entitlement> ...]
                        Add one or more entitlements to the given user(s). Can
                        be specified multiple times.
  --remove [<entitlement> ...], -r [<entitlement> ...]
                        Delete one or more entitlements from the given users(s).
                        Can be specified multiple times.
  --entmap-update       Update entmap.conf to reflect the changes made.
```

(Due to a quirk in argparse, the help message printed when the program is run
with the ```--help``` argument is slightly misleading. The above is the actual
correct invocation description.)

Additions to ```entmap.conf``` will be placed after the last occurrence of the
given entitlement, or at the end of the file if it doesn't exist in
the file already.

Removals simply delete the relevant line if it exists. If the line contains a
comment, it will disappear as well.

## entmap.conf

See also ```entmap.conf.example```.

This file lists all entitlement mappings for update-entitlements.py
to maintain. If an entitlement doesn't occur at all in the file,
update-entitlements.py will not touch it.

A ```#``` character starts a comment, which runs to the end of the line.
There is no multiline comment facility.

All whitespace except newline (```\n```) is ignored. Blank lines are allowed.

Each non-comment should match the following format:
```entitlement = [!]handler:query```

 * ```entitlement``` - An entitlement. Will be concatenated with the value of
   ```entitlement_base``` in config.ini. The same entitlement may be specified
   several times with different handler/query combinations.  
   Depending on the environments, there will be restrictions on what
   entitlement names are considered valid.

 * ```handler``` - The facility to be used to process ```query```.  
   If a handler is prefixed with ```!```, the resulting set of users will be
   excluded from the given entitlement. This exclusion has precedence over all
   inclusion mechanisms.

 * ```query``` - A handler-dependent description of who should be
   granted the entitlement.

There are five handlers:
 * ```ldap``` - Takes an LDAP search string as a query. The query should
   result in a list of users who will then be granted the given entitlement.
 * ```daisy``` - Accepts two kinds of queries:
   - ```students``` - Will return all students who have had an active
     registration at DSV at any time during the last 10 semesters.
   - ```course:<id>``` - Requires a Daisy courseSegment ID as a parameter, and
     will return all students currently registered on that courseSegment.
 * ```user``` - Accepts a username as a query. The given user will be granted
   the given entitlement.
 * ```unixgroup``` - Takes the name of a unix group as a query. All members of
   the named group will be granted the given entitlement.
 * ```none``` - Does not take a query (the :query part will be ignored
   if it exists). Indicates that no users should have the given entitlement.
   Useful for removing outdated entitlements.