On this page

Install the Webserver-Front (DMZ)

The Webserver-Front is a read-only replica of the Webserver (ADMIN) designed to be exposed in a DMZ. It is fed exclusively by a one-way, mutually-authenticated (mTLS) push from ADMIN: the Front never opens a connection back to ADMIN or to any internal component. This page covers the full deployment: generating the PKI, laying out the pki/ folder, configuring each side’s configuration file (webserver.json on ADMIN, webserver_front.json on FRONT), and verifying the replication feed.

Throughout this page, ADMIN is the normal (licensed, internal) Webserver and FRONT is the front-tagged replica. For the architecture and trust model behind FRONT, see Webserver-Front (DMZ Replica); for day-to-day operation, see Operating Webserver-Front.

Security recap

  • ADMIN → FRONT only. ADMIN pushes incremental deltas continuously and a full snapshot every FrontReconcileMins minutes to FRONT’s replication receiver (mTLS, on FRONT’s PortAPI).
  • Three independent protections wrap every push: mTLS client-certificate authentication, a short-lived revocable RS256 token (dedicated replication keypair), and AES-256-GCM payload encryption with the shared ReplKey.
  • Secrets never leave ADMIN. Only a whitelist of buckets is replicated, and sensitive fields (tokens, passwords, internal IPs/ports/endpoints) are stripped before leaving ADMIN.
  • No license needed on FRONT. It is a replica of the licensed ADMIN and runs without a license_MNS.dat file.

Step 1 — Generate the PKI

Generate all key material on a secure machine (ideally the ADMIN host or an offline workstation), then distribute only the files each side needs.

1.1 Replication CA and certificates



# Root CA - keep the CA key offline after issuance

openssl genrsa -out repl_ca.key 4096
openssl req -x509 -new -nodes -key repl_ca.key -sha256 -days 3650 -subj "/CN=mugnsoft-repl-ca" -out repl_ca.crt

# ADMIN client certificate (presented by ADMIN when it POSTs to the Front)

openssl genrsa -out admin_client.key 4096
openssl req -new -key admin_client.key -subj "/CN=webserver-admin" -out admin_client.csr
printf "extendedKeyUsage=clientAuth\n" > admin_ext.cnf
openssl x509 -req -in admin_client.csr -CA repl_ca.crt -CAkey repl_ca.key -CAcreateserial \
 -out admin_client.crt -days 825 -sha256 -extfile admin_ext.cnf

# FRONT server certificate: signed by the SAME CA.
# The SAN list must cover EVERY name ADMIN will dial in FrontEndpoint:
# add a DNS: entry per hostname and an IP: entry per IP address.

openssl genrsa -out front_server.key 4096
openssl req -new -key front_server.key -subj "/CN=front.example.com" -out front_server.csr
cat > front_ext.cnf <<EOF
subjectAltName=DNS:front.example.com,IP:203.0.113.10
extendedKeyUsage=serverAuth
EOF
openssl x509 -req -in front_server.csr -CA repl_ca.crt -CAkey repl_ca.key -CAcreateserial \
 -out front_server.crt -days 825 -sha256 -extfile front_ext.cnf

# verify the SANs before deploying
openssl x509 -in front_server.crt -noout -ext subjectAltName

SAN must match FrontEndpoint

Go’s TLS client performs strict SAN verification. If ADMIN’s FrontEndpoint is set to an IP address (e.g. 203.0.113.10:8050), the certificate must contain a matching IP: SAN — a DNS-only certificate fails with x509: cannot validate certificate for <IP> because it doesn't contain any IP SANs. If FrontEndpoint uses a hostname, that exact hostname must appear as a DNS: SAN (the CN alone is not enough). When in doubt, include both.

Note:

On Git Bash for Windows, prefix the -subj value with a double slash (-subj "//CN=...") to prevent MSYS path mangling.

1.2 Shared payload encryption key

The ReplKey is a 64-character hex string (32 bytes = AES-256). The same value must be configured on ADMIN and on the Front.


openssl rand -hex 32

# example output: 3addba52d5bb500caad74d211d8832f595b08842e846ae1db2aa080538a4d326

1.3 Replication token signing keypair

This RSA keypair signs the short-lived tokens that authenticate each push. It is deliberately separate from the user-login JWT keypair (config/sec/): the Front only ever holds the public half, so a compromised Front can forge neither replication pushes nor ADMIN user sessions.


openssl genrsa -out repl_sign.key 2048
openssl rsa -in repl_sign.key -pubout -out repl_sign.pub

1.4 Distribute the files

Create a pki/ folder next to each executable and copy only the files listed below. The CA private key (repl_ca.key) stays offline.

File ADMIN pki/ FRONT pki/ Purpose
repl_ca.crt yes yes CA that each side uses to verify the other’s certificate
admin_client.crt yes no ADMIN’s mTLS client certificate
admin_client.key yes no ADMIN’s mTLS client key
repl_sign.key yes no RSA private key signing replication tokens
repl_sign.pub no yes RSA public key verifying replication tokens
repl_ca.key no no CA key - keep offline

The Front’s server certificate does not go in pki/; it goes in the standard TLS location of the Front install directory:



# on the FRONT host

cp front_server.crt <front-install-dir>/config/ssl/certificates/webserver.pem
cp front_server.key <front-install-dir>/config/ssl/private/webserver.key

Step 2 — Deploy the Front

Copy the webserver-front package to the DMZ host. The expected folder layout:


webserver-front/
webserver_front.exe # front build of the webserver (webserver_front on Linux)
webserver_front.json # service + replication configuration (see below)
web-front/ # web UI assets, served from disk (not embedded)
pki/
repl_ca.crt
repl_sign.pub
config/
ssl/
certificates/webserver.pem # front_server.crt
private/webserver.key # front_server.key

Note:

No license_MNS.dat is required on the Front. The remaining folders (dbs/, data/, log/, …) are created automatically at first start.

Front webserver_front.json

The configuration file is named after the executable (<executable-name>.json): webserver_front.exe reads webserver_front.json.


{
"HTTPS": "true",
"PortAPI": "8050",
"PortWEB": "9090",
"RunUser": "",

"ReplKey": "3addba52d5bb500caad74d211d8832f595b08842e846ae1db2aa080538a4d326",
"ReplCACert": "pki/repl_ca.crt",
"ReplPubKey": "pki/repl_sign.pub"
}
Field Read by Description
PortAPI FRONT Port of the mTLS replication receiver — the only endpoint ADMIN pushes to. Must match the port in ADMIN’s FrontEndpoint
PortWEB FRONT Port of the read-only web UI exposed to end users
ReplKey both Shared AES-256 key (64 hex chars) decrypting every replication payload. Must be identical on ADMIN and FRONT
ReplCACert both CA certificate. The Front uses it to require and verify ADMIN’s client certificate at the TLS layer
ReplPubKey FRONT Public half of the replication signing keypair; verifies the RS256 token carried by each push

Install and start the service



# Windows (elevated prompt)

webserver_front.exe install && webserver_front.exe start

# Linux

./webserver_front install && ./webserver_front start

Step 3 — Configure ADMIN

Add the replication and Front fields to ADMIN’s webserver.json, then restart the ADMIN service. ADMIN needs exactly the files marked “ADMIN pki/” in the table of step 1.4 — in particular it does not need repl_sign.pub (ReplPubKey is a FRONT-only field):


{
"HTTPS": "true",
"PortAPI": "8050",
"PortWEB": "9090",
"RunUser": "",

"ReplKey": "3addba52d5bb500caad74d211d8832f595b08842e846ae1db2aa080538a4d326",
"ReplCACert": "pki/repl_ca.crt",
"ReplClientCert": "pki/admin_client.crt",
"ReplClientKey": "pki/admin_client.key",
"ReplSignKey": "pki/repl_sign.key",

"FrontEnabled": "true",
"FrontEndpoint": "front.example.com:8050",
"FrontReconcileMins": "5",
"FrontGracePeriodMins": "0"
}

Replication field reference

PKI / cryptographic fields (Repl*)

These fields are provisioned out-of-band in webserver.json on both hosts. They never travel over the replication channel and are never editable from the Settings UI.

Field Side Description
ReplKey ADMIN + FRONT Shared hex AES-256 key (64 hex characters, generate with openssl rand -hex 32). Every replication batch is AES-GCM encrypted with it, so the data stays confidential and tamper-evident end-to-end — even if TLS is terminated by a reverse proxy in between. The value must be identical on both sides
ReplCACert ADMIN + FRONT Path to the CA certificate verifying the peer. On the FRONT it validates ADMIN’s client certificate (RequireAndVerifyClientCert: a peer without a CA-signed client cert never reaches the handler). On ADMIN it validates the Front’s server certificate
ReplClientCert ADMIN Path to the TLS client certificate ADMIN presents when it POSTs to the Front
ReplClientKey ADMIN Path to the private key of ReplClientCert
ReplSignKey ADMIN Path to the PEM RSA private key signing the short-lived RS256 token attached to every /replicate push. Dedicated keypair, separate from the user-login JWT keys
ReplPubKey FRONT Path to the PEM RSA public key verifying those tokens. The Front holds only this public half: a Front compromise can forge neither replication pushes nor ADMIN user sessions

Front operational fields (Front*)

These fields live on ADMIN and control the push. They can be set in webserver.json or overridden at runtime from the ADMIN Settings UI.

Field Default Description
FrontEnabled "false" Set to "true" to activate the replication pump on ADMIN
FrontEndpoint — host:port of the Front’s mTLS replication receiver. The port is the Front’s PortAPI (e.g. front.example.com:8050)
FrontReconcileMins "5" Cadence in minutes of the full snapshot push (incremental deltas flow continuously in between). The value is stamped on every push, and the Front flags its feed as stale — with a UI banner — when no valid push arrives within 3x this interval
FrontGracePeriodMins "0" (off) Grace period in minutes before a non-OK application status becomes visible on the Front. When an application leaves OK for a degraded state, external viewers on the Front keep seeing the last-known-good status for this window — operations teams often resolve short incidents before outside users ever notice. ADMIN’s own real-time views, status history, SLA and alerting are unaffected. Planned DOWNTIME is propagated immediately

Step 4 — Verify

From the ADMIN host, test the mTLS channel with the client certificate:


curl --cacert pki/repl_ca.crt --cert pki/admin_client.crt --key pki/admin_client.key \
 https://front.example.com:8050/uptime

# expected response: ok

Then check:

  • ADMIN log (log/webserver.log): the pump reports pushed batches; certificate or key errors appear here.
  • FRONT log: replicateHandler - applied N/N items (snapshot=true) at debug level; token or payload rejections are logged as warnings.
  • FRONT UI: open https://front.example.com:9090/ — monitors, applications and discovery data appear after the first reconcile (up to FrontReconcileMins minutes). A red banner indicates a stale feed.

Troubleshooting:

  • token rejected on the FRONT: ReplPubKey on the Front does not match ADMIN’s ReplSignKey, or the clocks differ too much.
  • payload rejected on the FRONT: ReplKey differs between the two hosts.
  • TLS handshake errors: certificate not signed by ReplCACert, or the FrontEndpoint hostname does not match the SAN of the Front’s server certificate.
  • x509: cannot validate certificate for <IP> because it doesn't contain any IP SANs: FrontEndpoint dials the Front by IP address but the server certificate only carries DNS: SANs. Re-issue it with a matching IP: entry (see step 1.1), or switch FrontEndpoint to a hostname listed in the certificate’s DNS: SANs.
  • apply failed ... cannot find the path specified: the Front’s dbs/ folder is missing — fixed automatically at first start on current builds; on older builds create the dbs/ folder manually.

See also

Translations

Folder structure