Configuration

There is no configuration file. Each setting is a flag, and each flag has a related environment variable. A flag wins over the environment variable, and the environment variable wins over the default. monolock -h prints the same table as below.

Flags

Flag	Environment variable	Default	Meaning
-listen	MONOLOCK_LISTEN_ADDRESS	0.0.0.0:7070	address to listen on
-ops-listen	MONOLOCK_OPS_LISTEN_ADDRESS	(empty)	address of the ops HTTP server: /metrics, /healthz, /readyz; empty disables it
-admin-listen	MONOLOCK_ADMIN_LISTEN_ADDRESS	(empty)	address of the admin HTTP API; empty disables it
-tls-cert	MONOLOCK_TLS_CERT	(empty)	PEM server certificate; with -tls-key enables TLS on the protocol port
-tls-key	MONOLOCK_TLS_KEY	(empty)	PEM private key for -tls-cert
-tls-client-ca	MONOLOCK_TLS_CLIENT_CA	(empty)	PEM certificate-authority (CA) pool for client certificates; enables mutual TLS (mTLS)
-acl-file	MONOLOCK_ACL_FILE	(empty)	JSON file with identity → lock name glob rules; requires -tls-client-ca, empty disables authorization
-audit-log	MONOLOCK_AUDIT_LOG	(empty)	audit log destination: a file path or - for stdout; empty disables audit
-io-timeout	MONOLOCK_IO_TIMEOUT	5s	deadline for a single read or write on a connection
-log-level	MONOLOCK_LOG_LEVEL	info	debug, info, warn or error
-log-format	MONOLOCK_LOG_FORMAT	text	text or json

Durations are Go duration strings, for example 5s or 250ms.

What is deliberately absent

There is no lease setting and no heartbeat setting. Each client selects its own lease in ACQUIRE. The client calculates its heartbeat schedule from this lease (see How it works). The only I/O policy of the server is -io-timeout, the deadline for a single read or a single write. This deadline limits the time that one blocked socket can occupy the server.

There is also no connection limit and no queue limit. See Capacity & limits for the resources that limit the server instead.

SIGHUP: reload external files

SIGHUP is the single signal that makes the server read its external files again. The server reads these files again:

• the TLS certificate, the key, and the client CA, so that certificates rotate without a restart
• the ACL (access-control list) file

The server also opens the audit log again, for logrotate.

With the example configuration below, SIGHUP touches these files:

• Directoryetc/monolock/

  • server.crt reread — certificate rotation
  • server.key reread — certificate rotation
  • clients-ca.crt reread — certificate rotation
  • acl.json reread — ACL reload
• Directoryvar/log/monolock/

  • audit.jsonl reopened — for logrotate

A failed reload keeps the previous state. An unsatisfactory certificate rotation causes stale certificates, not a stop. A broken ACL file keeps the old rules. If the audit log does not open again, the server continues to write to the old file, which possibly has a new name. The server writes the failure to the log. The server never replaces a satisfactory configuration with a broken configuration.

Example

The same configuration in the two forms. The environment variables are useful for containers:

Flags

monolock \
  -listen 0.0.0.0:7070 \
  -ops-listen 0.0.0.0:9090 \
  -admin-listen 127.0.0.1:7071 \
  -tls-cert /etc/monolock/server.crt \
  -tls-key /etc/monolock/server.key \
  -tls-client-ca /etc/monolock/clients-ca.crt \
  -acl-file /etc/monolock/acl.json \
  -audit-log /var/log/monolock/audit.jsonl \
  -log-format json

Environment variables

MONOLOCK_LISTEN_ADDRESS=0.0.0.0:7070 \
MONOLOCK_OPS_LISTEN_ADDRESS=0.0.0.0:9090 \
MONOLOCK_ADMIN_LISTEN_ADDRESS=127.0.0.1:7071 \
MONOLOCK_TLS_CERT=/etc/monolock/server.crt \
MONOLOCK_TLS_KEY=/etc/monolock/server.key \
MONOLOCK_TLS_CLIENT_CA=/etc/monolock/clients-ca.crt \
MONOLOCK_ACL_FILE=/etc/monolock/acl.json \
MONOLOCK_AUDIT_LOG=/var/log/monolock/audit.jsonl \
MONOLOCK_LOG_FORMAT=json \
monolock