Configuration

A self-hosted inSCADA is configured through environment variables. Two things are worth knowing before you edit anything: there is a master key the application will not start without, and there is a right way to hand secrets to the process.

The master key — INS_MASTER_KEY

This is the one secret you supply by hand. Left blank, the application does not start.

Every other key — the interface session key, the attribute key that reads the encrypted columns in the database, the cluster key, the code-integrity key and the electronic-signature key — is generated on first start and kept encrypted. You neither choose nor record those. The encrypted bundle lives in Redis, with a copy at ${ins.data.path}/secrets.json, and what opens it is derived from INS_MASTER_KEY (PBKDF2).

The master key is not in the backup — record it on the day you install

A backup carries the encrypted bundle and not the key that opens it. The master key is held in nothing the product persists: not the database, not Redis, not that file.

What follows in practice: whoever restores a backup must already know INS_MASTER_KEY. On the day the installation is created, record it somewhere outside the product — a password manager, or a sealed envelope in the plant safe. Lose it and the encrypted columns and signature records cannot be recovered.

The key is chosen once per installation; there is no rotation path.

Secrets do not go on the command line

Every setting whose value is a secret is given to the process as an environment variable — never as a -D on the java command line, and never as a program argument.

This is not a matter of style: a process’s arguments are public. Any account with a login on the machine can read the command line of a running process; no privilege is required. An environment variable is not like that — only the process’s owner can read it.

# WRONG — every user on this box can read the master key
java -Dins.master.key=... -jar inscada.jar

# RIGHT
export INS_MASTER_KEY=...
java -jar inscada.jar

The application says so at startup: for each sensitive setting that arrived on the command line it writes one warning line naming the setting, never the value. It does not refuse to start, because taking a plant down over a value that is correct would be the wrong trade. Check the startup log after a deployment; a clean start prints none of these lines.

The same applies to whatever wraps the process. A systemd unit reads secrets with EnvironmentFile= — the file readable only by the service account — rather than putting them in ExecStart=; a container uses --env-file or a secret mount. If you run it under a Windows service wrapper, load the environment the same way: from a permission-restricted environment file, not the command line.

Core settings

Anything whose default is blank is something you are expected to supply.

Variable	Default	Description
INS_MASTER_KEY	—	Required. See above
DB_URL	jdbc:postgresql://localhost:5432/inscada	PostgreSQL address
DB_USERNAME · DB_PASSWORD	blank	Database credentials
REDIS_HOST · REDIS_PORT	localhost · 6379	Redis
INFLUX_URL · INFLUX_DB	http://localhost:8086 · inscada	The historian
SSL_KEYSTORE · SSL_KEYSTORE_PASSWORD	blank	TLS keystore
APP_TRUSTSTORE · APP_TRUSTSTORE_PASSWORD	blank	Truststore for outbound connections
LOG_FILE	./logs/inscada.log	The log file

Directories

Setting	Default	What is in it
ins.data.path	./data	The encrypted secret bundle’s copy, and working data
ins.filesystem.path	./fs	Uploaded files

Both are relative to the working directory. When you back up the installation directory, make sure the two are covered.

Several installations sharing one Redis

Everything an installation keeps in Redis — the secret bundle, the cluster’s leadership record, live values, sessions — sits in a single logical database, 0 when unset. A second installation pointed at the same Redis, a test instance beside production or a second plant, must use a different database number; otherwise the two share one space.

Ports and origins

Port	What
8082	The application and the API
8083	The sandbox

The sandbox is a separate origin by design: Custom HTML pages and animation scripts run in an isolated frame, and that separation is the isolation boundary.

Because cookies are host-only, the sandbox origin must be on the same host as the application. On different hosts the cookies never reach the frame, and the fix is to bring the sandbox back to the same host — usually with a proxy on that machine fronting :8083 — rather than widening the cookie’s domain.

Bind settings and advertised settings

Four settings decide the topology. Two are bind settings — where the server listens — and two are advertised — the origin the client is told to use. They are separate on purpose: behind a proxy, the port the server binds and the origin the client sees legitimately differ.

Setting	Layer	Default	Meaning
INS_SANDBOX_ADDRESS	bind	blank → all interfaces	The address the sandbox listens on. Set 127.0.0.1 when a proxy on the same machine owns the public port
server.sandbox.port	bind	8083	The sandbox port
INS_SANDBOX_URL	advertised	https://localhost:8083	The full sandbox origin the client sees
INS_APP_URL	advertised	https://localhost:8082	The backend / API origin

The advertised origins form an exact-match allowlist with no wildcard. A wrong value breaks only your own installation — a frame will not render, or an origin will not be trusted.

Three topologies

Topology	INS_SANDBOX_ADDRESS	Advertised sandbox	Advertised app
Single box, no proxy	blank	https://<host>:8083	https://<host>:8082
Proxy on the same machine	127.0.0.1	The proxy’s public origin	The backend origin
Separate-machine DMZ	the internal interface’s address	The public origin	The DMZ origin

With a proxy on the same machine, bind the public port in the proxy to the machine’s real address and forward it to 127.0.0.1:8083; a bare :8083 block binds all interfaces and collides with the loopback listener (“address already in use”).

In a DMZ topology, declare the proxy’s address

INS_HTTP_TRUSTED_PROXIES defaults to 127.0.0.1,::1, which covers a proxy on the same machine. When the proxy is on a separate machine, add its address to that list. Without it the product reads every client as the proxy, and the IP allowlist, the login block, the rate limiter and the audit trail all see a single address.

When both local and remote access are needed

The interface builds the sandbox origin at request time: /api/config reports only the sandbox port, and the frame origin is derived from the address the browser is currently on (protocol + host) together with that port. The frame therefore always lands on the host the operator used, and host-only cookies reach it. Access from the local network and from an external address work at the same time; no proxy that rewrites the advertised sandbox host is needed.

The one thing left to complete is the browser-side permission. The CSP frame-src and frame-ancestors directives have to be a static list of origins — the parent origin is not known when a sandbox response is generated. That list is built from the advertised addresses (INS_APP_URL, INS_SANDBOX_URL) plus ins.iframe.allowed-hosts. So the sandbox origin of every additional access path must be listed in ins.iframe.allowed-hosts, or the browser blocks the frame.

Each access path also needs: 8082 and 8083 reachable over it, and, with a self-signed certificate, the certificate accepted once per origin — the sandbox is a separate origin, so its certificate is accepted separately.

INS_SANDBOX_URL is now only the backward-compatibility value used when talking to an older version that does not report a port; it still feeds the CSP list.

For the step-by-step setup, an example configuration and troubleshooting: Custom HTML and iframe Access.

Post-installation checklist

• /actuator/health — the proxy indicator reports the intended mode and nothing is DOWN. On a clustered node, health-check a load balancer against /actuator/health/readiness rather than raw /actuator/health.
• The startup log carries no proxy warning and no line reporting that a secret arrived on the command line.
• Behind a reverse proxy, 8082 and 8083 are not reachable from outside it, and the proxy sends X-Forwarded-Proto: https.
• A Custom HTML page or an animation opens in the browser — this exercises the sandbox origin and the cookie flow end to end.
• INS_MASTER_KEY has been recorded somewhere outside the product.

Related

• Backup
• Redundancy