# Ansible roles to configure LOCKSS v2

This project provides Ansible roles and an example playbook for configuring
[LOCKSS](<https://www.lockss.org/>) v2 on a Ubuntu or CentOS host.

## Role variables
### Required variables
* `lockss_hostname`: The hostname of the LOCKSS host.
* `lockss_ipaddr`: Probably the same as `lockss_external_ipaddr`.
* `lockss_external_ipaddr`: The external IP address of the LOCKSS host.
* `lockss_db_password`: The password for connecting to the internal PostgreSQL
  database. This should be machine-generated.
* `lockss_ui_password`
* `lockss_admin_email`

### Recommended but optional variables
* `lockss_network_ips`: A list of IP addresses and subnets that will be allowed
  to connect to LOCKSS's communications ports.
* `lockss_admin_ips`: A list of IP addresses and subnets that will be allowed to
  connect to LOCKSS's configuration pages.

### Optional variables
* `lockss_uid`: This and `lockss_gid` are intended for using a data directory
  mounted from another host.
* `lockss_gid`
* `lockss_git_version` (default in `roles/lockss/defaults/main.yml`)
* `lockss_mailhub_host` (default: `localhost`)
* `lockss_mailhub_user`
* `lockss_mailhub_password`
* `lockss_ui_user` (default: `admin`)
* `lockss_data_dir` (default in `roles/lockss/defaults/main.yml`)
* `lockss_configure_firewall` (default: true)

## Ports
All of these are TCP:

* metadata-extraction-service: 24640, 24641
* postgres: 24602
* metadata-service: 24650, 24651
* repository-service: 24610
* configuration-service: 24600, 24606, 24620, 24621
* poller: 9729, 24630, 24631, 24670, 24672, 24674, 24680
* pywb: 24681
* solr: 24603

## Running with Vagrant
The included Vagrantfile will configure and run the example playbook against the
machines defined in `vagrant-machines.yml`, currently Ubuntu 18.04 and CentOS 7.
If the `vagrant-hostsupdater` plugin is installed, Vagrant will add appropriate
entries to `/etc/hosts`, making the LOCKSS configuration page accessible at
`http://lockss-ubuntu.test:24600` and `http://lockss-centos.test:24600`.

## Overcoming network hurdles
Accessing the configuration ports on a firewalled LOCKSS server is inconvenient.
I recommend [sshuttle](https://github.com/sshuttle/sshuttle), available in
Ubuntu's "universe" repository. sshuttle proxies traffic over ssh, but, unlike
ssh's built-in SOCKS proxy, sshuttle uses iptables rules to redirect selected
outbound traffic, so local applications don't need to be reconfigured. It has
better performance and is far easier to set up than ssh's "tun" device
forwarding, and it doesn't require elevated privileges on the target server.

The following would proxy through an ssh connection to `box` all outbound TCP
connections, other than those to port 22, made to `box` by the executing user:

```sh
sshuttle --user $USER -r box box -x box:22
```