Files and services

/usr/local/bin/pss

Executable file.

/opt/pss/config/pss.properties

Global settings, logs, folder paths and so on. After making changes, restart the service.

/opt/pss/config/pss.json

Main settings file. Created and updated automatically. At startup the service attempts to load precisely this file. How the file is built — see The pss.json settings file.

/opt/pss/config/pss_last.json

A copy of the last pss.json that loaded cleanly. It is rewritten at every start where it was pss.json itself that loaded; a start on a fallback file does not update it — otherwise it would stop being the last known-good one. It serves as the first fallback if the main file could not be parsed. On a node that has never been restarted since installation, and where the settings directory is closed to writing, this file does not exist.

/opt/pss/config/pss_back.json

A backup copy of the previous working configuration. It is created only when settings are restored from a previously saved copy in the web interface (Maintenance) and is used as the fallback after pss_last.json. The service keeps no regular backup, so on a node where settings have never been restored this file does not exist.

/opt/pss/config/pss_default.json

Default settings file. Shipped with the package and applied as the last fallback if neither pss.json nor pss_last.json nor pss_back.json can be loaded. It is also the source of the working pss.json created at the very first start: the file sets the web interface port 8808 and the admin / admin account.

/opt/pss/config/bad/

Archive of corrupted pss.json files. If the main settings file cannot be parsed at startup, it is moved here with a name of the form pss_YYYYMMDD_HHMMSS.json. The directory is created automatically and does not grow without bound: the twenty files with the highest names are kept. For more details, see the Behavior at startup and on configuration errors section.

/opt/pss/data

Data storage folder. Created and updated automatically. Can be changed in the global settings file.

/usr/lib/systemd/system/pss.service

systemd unit file for the service.

/var/log/pss

Log output folder. Can be changed in the global settings file.

The service name is pss. Runs as the pss user.

Work with the key is provided by the protection system package aksusbd — it includes the hasplmd and aksusbd services. The pstreamer package declares a dependency on it, version 10.33 or newer: it does not contain the protection service itself, but lies in the same repository, so the package manager installs it alongside. An older protection service cannot load the vendor libraries that pstreamer places in /var/hasplm.

Behavior at startup and on configuration errors

At startup, the service sequentially attempts to load the settings files from the /opt/pss/config folder:

1. pss.json — main settings file.

2. pss_last.json — a copy of the last configuration that loaded cleanly.

3. pss_back.json — backup copy of the previous working configuration.

4. pss_default.json — default settings shipped with the package.

The first file that loads successfully is used. If all four files are missing or damaged, the service starts with empty settings — which contain no account at all. The administrator is then created by hand: stop the service, add an entry to web-server.login in pss.json with the keys id, login and password, and start the service again — an edit made to a running service is overwritten from memory (The API or the settings file).

Two things follow from the existence of pss_last.json. First: deleting pss.json no longer starts the node from a clean slate — the service will come up on pss_last.json and write it back into pss.json. There will be no alert, but it will not go unnoticed either: an entry stays in the log, and a start-up message appears in the web interface. To reset the node for real, pss.json is deleted together with pss_last.json and pss_back.json — the service then comes up on pss_default.json. Nothing else in the settings directory may be touched: without pss.properties the service does not start at all. Second: pss_last.json is only as good as the last clean start is recent. Settings changed through the web interface that have never survived a restart exist in pss.json alone, and a fallback to the last working configuration will not preserve them.

An unacceptable settings file. If pss.json could not be read, the service moves it into the /opt/pss/config/bad/ archive under the name pss_YYYYMMDD_HHMMSS.json; the date and time in the name are the moment of archiving in UTC, the same reckoning the log uses by default. After that the service carries on loading in the usual order and re-saves the working configuration into pss.json from whichever file did load. The details (the key name, the description of the error, the name of the file in the archive) are written to the operation log, and the alert about the failed load names the archive path outright as well.

Loading stops on: a JSON syntax error, a null value, a wrong shape of value (an object where a single value is expected and the other way round), a number or some other word instead of true and false, an over-long string, a missing or duplicated identifier of an array entry, a repeat of a value declared unique. An unknown key does not discard the file: it is ignored, a warning naming the section and the key is written to the log, and at the next save the key disappears from the file. The full account of what the service accepts when reading the file and what it refuses is in What the service does when it reads the file.

Only the main pss.json ends up in the archive. The pss_last.json, pss_back.json and pss_default.json files are not archived when corrupted — the log entries are sufficient for diagnostics, and the files themselves remain in place and can be corrected manually.

If /opt/pss/config/bad/ already holds a file with the same timestamp (two failed starts within one and the same second, for instance), the new one is given a numeric suffix — pss_YYYYMMDD_HHMMSS_2.json and onwards; the copy saved earlier is not lost in the process. The directory cannot grow out of hand: the appearance of a new copy leaves the twenty files with the highest names in it and the rest are deleted. For the archives the service names by time, those are exactly the twenty most recent; foreign files left in the directory count too and take up those places, so it is best not to keep anything superfluous in bad/. One failed edit — one copy; a restart on its own creates no new copies, because the rejected file has already been moved and a working one has been written in its place.

Numeric values outside the allowed range. If a numeric value in the settings file is less than the minimum allowed or greater than the maximum allowed for that parameter, the service does not discard the whole file. Instead, a warning is written to the log stating the parameter name, the value read, and the applied bound, and the value itself is clamped to the nearest allowed range boundary (the minimum or the maximum). After loading completes, the service automatically re-saves pss.json with the corrected values, so on the next startup these warnings no longer appear.

Besides the log, the correction is announced by the start-up notification of the service in the web interface: it names the number of values clamped to a limit and refers to the log for the details. Read it after an update that has narrowed some range: the correction is silent, and on a retention parameter it means that the data beyond the new limit will be deleted by the next cleanup pass.

This behavior applies only during the initial loading of the settings file. When settings are changed through the web interface or the HTTP API (Managing the node over the HTTP API), values outside the allowed range are still rejected with an error — without automatic correction.

A refusal, however, does not return the node to its previous state: what the node has managed to read before the invalid value stays applied, and a message about a rejected save does not mean that nothing has changed (How errors arrive).

Editing the file by hand, validating it against the schema and carrying the settings to another node or another version — The pss.json settings file and Editing, checking and carrying the settings.