Newer
Older
# 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.
* `lockss_props_url`: The URL to the LOCKSS network configuration (default in
`roles/lockss/defaults/main.yml`).
### 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 in `roles/lockss/defaults/main.yml`)
* `lockss_data_dir` (default in `roles/lockss/defaults/main.yml`)
* `lockss_configure_firewall` (default: true)
* `lockss_frontend_port` (default in `roles/lockss/defaults/main.yml`)
These are the ports (all TCP) listened on by the various LOCKSS containers:
* metadata-extraction-service: 24640 (Web API), 24641 (Web config)
* metadata-service: 24650 (Web API), 24651 (Web config)
* repository-service: 24610 (Web API)
* configuration-service: 24620 (Web API), 24621 (Web config)
* poller: 9729 (LOCKSS), 24630 (Web API), 24631 (Web config), 24680 (Web config;
labeled "Serve Content")
* postgres: 5432 (PostgreSQL interface)
* pywb: 8080 ([Pywb](<https://pypi.org/project/pywb/>) Web console)
* solr: 8983 (Solr Web console)
The LOCKSS front-end (written by us) listens on port 80 by default.
## 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
```