pSSID GUI

pSSID GUI is a web application for building and managing pSSID configuration through a browser. You define hosts, host groups, schedules, SSID profiles, tests, jobs, and batches, and the application produces the files the pSSID daemon needs, ready for a provision script to deliver to your probes.

The same codebase can be themed for different organizations, and the included installer brings the stack up in one step while keeping the existing security model: HTTPS, optional single sign-on, and an isolated Docker network.

Deployment

There is exactly one supported installation path - bootstrap.sh on a fresh host, or install.sh from a checkout, which the Ansible playbooks and bootstrap.sh also call internally. Every guide below describes that same script; which one to open depends on what you need:

	For
Deploying without SSO	The fastest path: no identity provider, network-controlled access. Includes the one-command bootstrap and the same steps by hand (prerequisites, fetching the source, the playbook or install.sh directly, verifying, starter data).
Deploying with SSO	OIDC sign-in, group membership decides read/write. Same structure: one command, and the by-hand equivalent with the OIDC flags filled in.
Full deployment reference	Everything neither guide above covers: disk sizing on small VMs, TLS modes, editions, upgrades and backups, the provisioning pipeline, metadata and host-regex rules, provenance, the audit trail, and troubleshooting.
Ansible guide	The roles and playbooks that run the installer both guides above describe, remote hosts, site inventories, and every deploy-time variable.

On a VM with a small disk, add PSSID_PULL=true to pull the prebuilt images from the registry instead of building them (~4 GB of Docker storage instead of ~8-10 GB); see deploying to a new VM in the full reference.

Afterwards, one command each keeps the deployment maintained:

make upgrade    # backup, pull the latest release, rebuild, verify health
make backup     # extra on-demand database backup (nightly ones are automatic)
make help       # every operator shortcut (up, down, logs, doctor, ...)

Starter data

Two seeders ship with the project, and they are additive: the pre-load establishes the baseline and the QA dataset layers on top without disturbing it.

• make seed-defaults (scripts/seed-defaults.sh) is the main one. It loads the pre-load starter data for a fresh site: the standard schedules, the eduroam profile, the google http/rtt tests, job-comprehensive, and the all host group (regex .*). No batches or hosts. The installer runs this once on first install, and it can also be run by hand.
• umich/QA/seed-qa.sh (or make seed-qa) is for testing. It is site-specific, so it lives with the rest of the UMich material in umich/ and stays out of the deployment path: it adds the MWireless profile, five more tests, five more jobs, four batches (two of which deliberately share a priority), two probes carrying per-host data, and the rpi4 group (ifacename=wlan0). Between them these exercise every batch and metadata assignment path. Supply the two probe IPs with PSSID_QA_PROBE1 and PSSID_QA_PROBE2. The QA walkthrough has the full demonstration and the expected output.

Documentation

docs/ is the full documentation index - the deployment guides above, working on the code, and security. Everything specific to the University of Michigan deployment - its master Ansible inventory, its live SSO configuration, and the QA dataset - is in umich/; the rest of the repository is vendor-neutral.

System overview

The application runs as a set of Docker containers: client, server, mongo, and nginx, plus redis for session storage and certbot for certificate renewal when single sign-on is enabled.

Users interact with the client in the browser. The client talks to the server, which stores its data in MongoDB. nginx terminates HTTPS and routes traffic into the internal Docker network, so the internal services are not exposed directly.

The application produces two files:

• hosts.ini, an Ansible inventory of the hosts and groups.
• pssid_config.json, the pSSID daemon configuration, which lists the batches to run. It opens with a pssid_metadata header recording when the file was built and who built it - by display name, by login, and by the identity provider's immutable user id, which is the one that stays correct across a rename (see provenance).

You build these in the GUI and write them to the controller with Settings > Configuration > Generate, which validates them against the daemon's rules first. A provision script (bin/provision) then uses Ansible to copy the daemon config onto the probes in hosts.ini and restart the daemon on each one; the copy shipped in this repository is a placeholder that only logs, so a deployment supplies its own. The deployment guide describes the full pipeline.

Configuration file anatomy

The daemon configuration is built from seven components, each with its own page in the dashboard: hosts, host groups, schedules, SSID profiles, tests, jobs, and batches. Test templates on disk define the fields each test type needs. Tests are combined into jobs, and SSID profiles, schedules, and jobs are combined into batches. The batches are what run on the probes.

Access control

Access is configured in shared/config.ts. With single sign-on enabled, users sign in through an OIDC provider, and group membership maps to read or write access in shared/auth-groups.config.json. With SSO disabled, access is open, and OPEN_WRITE decides whether unauthenticated users have read-only or read-write access. Both ship closed: SSO off, writes refused.

Single sign-on is one binary flag, and a deployment can be run either way and switched later without reinstalling. The installer takes the choice (./install.sh --sso=true|false, or PSSID_SSO for the bootstrap), and afterwards:

make sso-status   # what posture is this deployment in right now?
make sso-on       # on: OIDC sign-in, group membership decides read vs write
make sso-off      # off: unauthenticated, OPEN_WRITE decides whether writes are allowed
make writes-on    # allow writes while SSO is off (make writes-off returns to read-only)

make sso-on refuses until the OIDC values are present and names the ones that are missing, rather than flipping the flag and leaving a server that will not boot. The deployment guide covers both postures and provider-specific setup, including a worked Okta example.

The authorization model fails closed throughout. With SSO on, the server validates its configuration at startup and refuses to start on a fault that would otherwise present as a working deployment which authenticates nobody or denies everyone - a session secret too short to be safe, a cookie domain that would loop sign-in forever, an unauthenticated session store, a group mapping that is missing or malformed. Entitlement is checked at sign-in as well as per request, so a user with no mapped group is refused with an explanation rather than reaching an interface that rejects every action. Group membership is read from whichever claim the provider uses (groups, edumember_is_member_of, isMemberOf) and matched exactly, never by prefix.

Every API endpoint carries an explicit read or write guard, and a unit test fails the build if an endpoint is ever added without one. Beyond authorization: Authorization Code flow with PKCE and no token in the browser, signed Redis-backed sessions with both idle and absolute timeouts, cross-origin write refusal, tiered per-IP rate limits, a hardened TLS and security-header policy at nginx, unprivileged capability-dropped containers on read-only root filesystems, and a structured audit line for every state-changing request, every denial and every sign-in - naming the actor by the provider's immutable user id, never including a request body. make test and the CI security job cover these.

Further reading

• Adding fields to the config file
• Backend folders, service files, and test templates
• Frontend directories and components

Testing

make test            # all unit tests (config generation contract, validators, access control)
make smoke           # every user action, end to end, against a running stack
make security-check  # posture of a running deployment (TLS, headers, auth, containers)

Both are wired into CI; the deployment guide describes what each covers.

Troubleshooting

make doctor                          # prerequisites and port conflicts
make ps                              # container status
make logs                            # service logs
curl -k https://<host>/api/health    # server and database health

The deployment guide has more.