This is the reference for every option, flag and environment variable of the programs, and for running them by hand or on systems other than Debian. For a first installation follow the Quick start; for securing an installation see Hardening; for what the deb packages install and how systemd runs them see Installing with dpkg/apt.
- What runs where
- Host names ending in .local
- MongoDB and Mosquitto
- janeserver
- addjaneuser
- tarzan
- jp
- All environment variables
| Program | Runs on | Talks to |
|---|---|---|
| janeserver | the Jane host | MongoDB, the MQTT broker, trust agents (tarzan, ratsd) |
| addjaneuser | wherever it can reach Jane's MongoDB | MongoDB |
| jp_extract | wherever it can reach Jane's MongoDB, best on the Jane host (it checks Jane's ports there); see jp_extract | MongoDB |
| tarzan | each element (machine being attested), as root | answers janeserver |
| jp | each element | janeserver's REST API; the local TPM |
Installed from the deb packages, the programs are in /opt/jane and their configuration in /etc/opt/jane. Built from source (see Compiling) they can live anywhere.
janeserver, tarzan and jp are built without cgo (pure Go, so that every architecture builds on one machine). They therefore use Go's own name resolver, which reads /etc/hosts and asks the DNS servers in /etc/resolv.conf, but not avahi's nss-mdns, which resolves <name>.local for programs using glibc (#127).
Since 1.5.6b, janeserver and jp resolve .local names themselves with multicast DNS, in pure Go (package localnames): every name is looked up as before, and only if that fails and the name ends in .local is it asked for by multicast DNS (up to 3 s). DNS, /etc/hosts and IP addresses behave exactly as before. This covers all their HTTP requests: jp to Jane (attestationserver:), Jane to trust agents (element endpoints, e.g. http://pi.local:8530), the EK certificate issuerurl, and the standard intents and objects downloads. It does not cover the MongoDB and MQTT broker addresses in config.yaml; give those as IP addresses or names in /etc/hosts or DNS (the shipped 127.0.0.1 is fine).
Multicast DNS needs multicast on the local network: it works on most home and office LANs, not across routers, in clouds or in Kubernetes overlay networks. Anyone on the LAN can answer a multicast DNS query, as with avahi; where that matters use IP addresses, /etc/hosts, DNS, or HTTPS with a verified certificate. jp and janeserver open UDP port 5353 for the queries when they first need one; avahi keeps working alongside.
janeserver needs both before it starts, and panics (and, under systemd, restarts) until it can reach them.
| Jane setting | Meaning |
|---|---|
database: connection |
MongoDB connection string, e.g. mongodb://127.0.0.1:27017; options such as tls=true or authSource may be added |
database: name |
the database Jane uses; created on first use |
messaging: broker, port |
MQTT broker address and port for janeserver (plain TCP; TLS is not supported yet, #87) |
messaging: portws |
the broker's WebSocket port, used by the browser for the Web UI's Live page |
messaging: clientid |
MQTT client ID; must be unique per Jane instance |
Setting them up without accounts is in the Quick start (steps 1 and 2); with accounts, and with TLS for the Live page, in Hardening (steps 7 and 8). Accounts are given to Jane through environment variables, never in config.yaml.
| Flag | Default | Meaning |
|---|---|---|
--config=FILE |
./config.yaml |
the configuration file |
--startREST=false |
true | don't start the REST API |
--startWebUI=false |
true | don't start the Web UI |
--startx3270=false |
true | don't start the x3270 (tn3270) interface |
The packaged /etc/opt/jane/config.yaml lists every option with comments; a commented example for running from the source tree is janeserver/config.yaml.
| Section | Keys | Notes |
|---|---|---|
system |
name |
a name for this Jane instance, shown in the UIs and logs |
database |
connection, name |
see above |
messaging |
broker, port, portws, clientid |
see above |
rest |
port (8520), listenon, usehttp, crt, key |
REST API. listenon: address to bind, 0.0.0.0 or empty for all, 127.0.0.1 for this machine only. usehttp: true serves plain HTTP; otherwise HTTPS with crt/key |
web |
port (8540), listenon, usehttp, crt, key |
Web UI, as for rest |
x3270 |
port (3270), listenon |
tn3270 terminal interface; never encrypted |
logging |
logfilelocation, sessionupdatelogging |
Jane's log file (CSV, one entry per line), and whether to log every claim and result added to a session |
signing (optional) |
keyfile |
PEM private key for claim, result and session footers; without it an ephemeral key is made at each start. See Signing |
sessions (optional) |
longsession (60), refresh (2) |
sessions open longer than longsession seconds (minimum 30) are flagged LONG SESSION; while a profile run is going its session pages reload every refresh seconds, 0 switches it off. See Sessions |
auth (optional) |
web, rest, x3270, sessiontimeout (30m) |
logins per interface; without the section nothing asks for a login. See Authentication |
Restart Jane after changing the file.
| Variable | Meaning | Unset or empty |
|---|---|---|
JANE_MONGODB_USERNAME |
MongoDB account | no account (or whatever the connection string says) |
JANE_MONGODB_PASSWORD |
its password | empty |
JANE_MONGODB_AUTHSOURCE |
database the account is defined in | admin, or the connection string's authSource |
JANE_MQTT_USERNAME |
MQTT broker account | anonymous |
JANE_MQTT_PASSWORD |
its password | none |
JANE_X3270_DEBUG |
any value: log the x3270 data stream (debugging) | off |
An account in the environment replaces a username in the connection string. Jane reads the variables once, at start.
By hand (from the source tree, or for testing):
export JANE_MONGODB_USERNAME=jane JANE_MONGODB_PASSWORD='...' # only if MongoDB needs an account
./janeserver --config=config.yamlDeb install (systemd): systemctl start|stop|restart|status jane; the variables come from /etc/opt/jane/jane.env. See Installing with dpkg/apt.
Windows: run janeserver.exe as a service (e.g. with the Service Control Manager or a service wrapper) and set the variables in the service's environment.
HashiCorp Vault: either let Vault Agent render jane.env and restart Jane when it changes, or run janeserver under Vault Agent's process supervisor mode with env_template entries for the variables. See Hardening.
JANE: Configuration file location: /etc/opt/jane/config.yaml
JANE: initialising database MONGO connection
JANE: MongoDB authentication: none
JANE: Database infrastructure MONGO is running
JANE: Initialising message infrastructure MQTT connection
JANE: MQTT authentication: none
JANE: MQTT connected
JANE: Message infrastructure MQTT is running
JANE: Authentication: web false, rest false, x3270 false, session timeout 30m0s
...
The authentication lines show the accounts used (user jane), never passwords. Jane warns if a login is required but there are no users, or if no signing key is configured. It creates the indexes on sessions (itemid, parent) at each start (1.6); if that fails it warns (could not create the indexes on sessions) and runs without them, only slower. Under systemd: journalctl -u jane.
Every operation is logged three ways: to the log collection in MongoDB, to MQTT topic AS/<channel>, and to logging: logfilelocation as CSV. The file is created with mode 640 and opened for each entry, so log rotation works. If MongoDB does not answer within 5 seconds the entry is reported on standard error (the journal) instead.
Adds a Jane user, sets a new password for an existing one, or makes or revokes a user's REST API key. Passwords are stored as Argon2id hashes, API keys as SHA-256. Installed as /opt/jane/addjaneuser; in the source tree etc/addjaneuser/addjaneuser. Needs Python 3 with argon2-cffi and pymongo (apt install python3-argon2 python3-pymongo).
addjaneuser [--apikey | --revokeapikey] [--dbuser NAME --dbpass PASSWORD] USERNAME MONGODB_URL DATABASE
MONGODB_URL and DATABASE are Jane's database: connection and database: name (asvr in the packaged configuration).
sudo /opt/jane/addjaneuser ian mongodb://127.0.0.1:27017 asvr # asks for the password twice
echo 'secret' | /opt/jane/addjaneuser ian mongodb://127.0.0.1:27017 asvr # from a script
KEY=$(/opt/jane/addjaneuser --apikey cluster-a mongodb://127.0.0.1:27017 asvr) # new REST API key, printed once
/opt/jane/addjaneuser --revokeapikey cluster-a mongodb://127.0.0.1:27017 asvr # remove itIf MongoDB requires an account, addjaneuser reads JANE_MONGODB_USERNAME, JANE_MONGODB_PASSWORD and JANE_MONGODB_AUTHSOURCE, like Jane. On a deb install, as root:
set -a; . /etc/opt/jane/jane.env; set +a
/opt/jane/addjaneuser ian mongodb://127.0.0.1:27017 asvr--dbuser and --dbpass (both together) override the variables. A password on the command line is visible to other users and kept in shell history; the variables are the safer way.
Users are removed in mongosh: db.users.deleteOne({username: "ian"}). Jane needs no restart after users change. See Authentication.
tarzan is the reference trust agent: it answers Jane over HTTP (protocol A10HTTPRESTv2) with TPM 2.0 quotes and other evidence, event logs and system information. It runs as root (the TPM device, /sys/kernel/security).
At least one API must be enabled.
| Flag | Meaning |
|---|---|
-sys |
system information (OS, architecture, hostname, machine ID, ...) |
-tpm2 |
TPM 2.0: PCRs, quotes, gettime, capabilities, credential activation |
-uefi |
UEFI event log and UEFI variables |
-ima |
Linux IMA measurement log |
-txt |
Intel TXT log (not implemented yet) |
-port=N |
listen on port N (default 8530) |
-unsafe |
never use: lets callers ask for any file instead of the standard log locations, i.e. read any file as root, and use a tcp:// TPM simulator, i.e. make tarzan connect to any address |
Flags may be written with one or two dashes (-tpm2 or --tpm2).
| Variable | Meaning |
|---|---|
JANE_TPM_ENDORSEMENT_PASSWORD |
the TPM's endorsement hierarchy password, only if one has been set (tpm2_changeauth -c e). Unset means the empty password. Used by credential activation; tpm2/gettime cannot use it and fails while a password is set |
By hand:
sudo ./tarzan -sys -tpm2 -uefi -imaDeb install (systemd): the packaged unit starts -sys -tpm2 -uefi -ima and reads /etc/opt/jane/tarzan.env; see Installing with dpkg/apt.
OpenBSD (rc.d): save as /etc/rc.d/tarzan and enable with rcctl enable tarzan. On the BSDs and macOS tarzan cannot read UEFI variables (uefi/efivars answers "not supported"); the other APIs work as on Linux.
#!/bin/ksh
#
# $OpenBSD: tarzan
daemon="/opt/jane/tarzan"
daemon_flags="-sys -tpm2"
. /etc/rc.d/rc.subr
rc_bg=YES
rc_cmd $1Windows (from 1.5.6, #122; best effort): run tarzan.exe (e.g. tarzan.exe -sys -tpm2 -uefi) as Administrator or SYSTEM; starting it as a service or scheduled task, and the firewall rule for its port, are up to the administrator. tarzan opens the TPM through TPM Base Services (the element's tpm2.device is ignored). Windows controls the TPM itself: it only passes commands on its own allow list and keeps the owner authorisation, so some functions (and jp's create/update, which make keys persistent) may be refused — that is Windows' decision. uefi/eventlog comes from TBS (Tbsi_Get_TCG_Log_Ex, Windows 10 1803 and later); ima/asciilog answers "not supported on Windows"; sys/info reports the MachineGuid as the machine ID, as jp does.
jp registers this machine with Jane, provisions its TPM keys, records its expected values, and attests it. Its modes, flags, when to use each, the provisioning file and exit codes are described in jp, the provisioner.
jp [-h] [--reprovisiontpm] [--recreate] [--apikeyfile PATH] create|update|attest PROVISIONINGFILE
jp remoteattest [PROVISIONINGFILE] [PROFILE] [--server URL] [--parent SID]
[--followlimit N | --nofollow] [--parallel] [--apikeyfile PATH]
In short: create (first registration) and update (after firmware or OS updates) need root and change the TPM keys only with --reprovisiontpm; attest needs no root and never touches the TPM; remoteattest (1.6) asks Jane to run the element's stored attestation profile, following related elements, and needs neither root nor a TPM. jp never asks questions, so it can run unattended. Its environment variables are JANE_SERVER (remoteattest), JANE_API_KEY, JANE_TPM_ENDORSEMENT_PASSWORD, JANE_TPM_OWNER_PASSWORD and SSL_CERT_FILE (see the table below); use sudo -E to keep them.
| Variable | Program | Meaning | Unset or empty |
|---|---|---|---|
JANE_MONGODB_USERNAME |
janeserver, addjaneuser | MongoDB account | no account |
JANE_MONGODB_PASSWORD |
janeserver, addjaneuser | its password | empty |
JANE_MONGODB_AUTHSOURCE |
janeserver, addjaneuser | database the account is defined in | admin / connection string |
JANE_MQTT_USERNAME |
janeserver | MQTT account | anonymous |
JANE_MQTT_PASSWORD |
janeserver | its password | none |
JANE_X3270_DEBUG |
janeserver | log the x3270 data stream | off |
JANE_SERVER |
jp | Jane's REST API for remoteattest, e.g. http://jane:8520; --server overrides it |
the provisioning file's attestationserver |
JANE_API_KEY |
jp | Jane REST API key (jane_...); --apikeyfile overrides it |
no key sent |
JANE_TPM_ENDORSEMENT_PASSWORD |
tarzan, jp | TPM endorsement hierarchy password | empty password |
JANE_TPM_OWNER_PASSWORD |
jp | TPM owner hierarchy password (persisting and evicting the EK/AK) | empty password |
SSL_CERT_FILE |
jp (Go) | extra trusted certificates for HTTPS | system store |