Central service settings

The central service’s own settings cover what it needs before it can reach its database: the database, the web address and certificate, console sign-in and how secrets are protected. Everything else is in the database and changed in the console (see Console settings).

Where settings come from

Later sources override earlier ones:

1. appsettings.json next to the program, in a "Central" section.
2. The registry, HKLM\SOFTWARE\Routes\Central (Windows; written by the installer). One string value per setting.
3. Environment variables, Routes__Central__<Setting>, such as Routes__Central__Port=5080.
4. The command line, --Central:<Setting>=<value>.

Restart the service after changing them. Lists (groups, claims) are separated by ;.

Database

Setting	Installer property	Default	What it does
DatabaseProvider	DATABASEPROVIDER	SqlServer	SqlServer or PostgreSql.
SqlServer	SQLSERVER	localhost	The SQL Server instance, such as sqlprod01\INST1 (PostgreSQL: the host), when there is no connection string.
Database	SQLDATABASE	Routes	The database name. It is created on first start if the account may.
SqlValidateCertificate		false	SQL Server without a connection string: check the server’s certificate instead of trusting any (it needs one the operating system trusts, issued to the server’s name). The connection is encrypted either way.
ConnectionString	CONNECTIONSTRING (or PGHOST, PGPORT, PGUSER, PGPASSWORD)	Windows authentication as the service account	A full connection string; overrides the two above. Needed for PostgreSQL and SQL authentication.

See The database.

Web address and HTTPS

Setting	Installer property	Default	What it does
Port	HTTPPORT	5080	The port of the console and the node API, on every address.
Urls			Addresses to listen on instead, ; separated, such as https://*:443.
CertificateThumbprint	CERTTHUMBPRINT		A certificate in LocalMachine\My to serve HTTPS with.
CertificatePath			The certificate as a file instead: PKCS#12 (.pfx, .p12) or PEM.
CertificateKeyPath			The PEM private key, when it is not in the certificate file.
CertificatePassword			The PKCS#12 file’s password, or the encrypted PEM key’s.
HttpsMode	HTTPSMODE	SelfSigned	Without a certificate: SelfSigned (a certificate this server makes and renews itself), or Http (plain HTTP, only behind a proxy that adds TLS). Plain HTTP on addresses only the machine itself can reach is always allowed.
CertificateExportPath			Where to write the self-signed certificate’s public part (PEM), for nodes to trust it from a shared folder.

See HTTPS and certificates.

Console sign-in

Setting	Installer property	Default	What it does
Authentication	AUTHENTICATION	Windows on Windows, Local elsewhere	Windows, OpenIdConnect or Local.
AdminGroups	ADMINGROUPS	BUILTIN\Administrators	Who may change the configuration and act on nodes: Windows groups or DOMAIN\Name, or identity provider group or role values.
ViewerGroups	VIEWERGROUPS	administrators only	Who may view the console.
OperatorGroups	OPERATORGROUPS	administrators only	Who may operate without changing the configuration: drain and resume nodes, retry, skip and resend, work dead letters, quarantine and reconciliation (with HistoryGroups where those show patients). They may view the console too.
HistoryGroups	HISTORYGROUPS	administrators only	Who may search the history, which holds patient names and IDs.
OidcAuthority	OIDCAUTHORITY		The identity provider’s issuer URL, such as https://login.microsoftonline.com/<tenant>/v2.0.
OidcClientId	OIDCCLIENTID		This application’s client ID at the provider.
OidcClientSecret	OIDCCLIENTSECRET		The client secret. Empty = a public client, with PKCE only.
OidcScopes			Scopes asked for besides openid profile email.
OidcNameClaim		preferred_username	The claim that names the user (then email, upn, name, sub).
OidcRoleClaims	OIDCROLECLAIMS	groups;roles	The claims matched against the group settings above.
OidcSessionHours		8	How long a sign-in lasts without use (identity provider and local accounts).
SessionMaxHours		12	How long a sign-in lasts at most, even in constant use; then the user signs in again.
DisableChangeApproval		false	Turns two-person approval of changes off on this server, whatever the configuration says: the way back in when no second administrator can approve. Remove it once the setting is off.
TrustedProxies		none	Reverse proxies or load balancers in front of the central service, as addresses or ranges (10.0.0.5;10.1.0.0/24), whose X-Forwarded-For and X-Forwarded-Proto headers are believed: sign-in limits and the audit log then see the user’s address. Headers from anyone else are ignored.

With local accounts, the first administrator’s password is in initial-admin-password.txt in the data folder. See Console sign-in.

Secrets, nodes and enrollment

Setting	Installer property	Default	What it does
SecretProtection	SECRETPROTECTION	Machine	How stored secrets are encrypted: Machine (this computer), Account (the service account, for several central servers running as one domain account), Certificate (the default off Windows), HashiCorpVault or AzureKeyVault (a key in a vault), or a DPAPI-NG protection descriptor such as SID=S-1-5-21-….
SecretProtectionCertificatePath		secret-protection.pfx in the data folder	The certificate for Certificate. Several central servers need the same one.
SecretProtectionCertificatePassword			Its password.
VaultAddress, VaultTransitMount, VaultTransitKey, VaultNamespace, VaultRoleId, VaultSecretId, VaultAppRoleMount, VaultKubernetesRole, VaultKubernetesMount, VaultToken			HashiCorpVault: the vault, its key and how to sign in. See Secrets in a vault.
AzureKeyVaultKey, AzureTenantId, AzureClientId, AzureClientSecret, AzureAuthorityHost			AzureKeyVault: the key and how to sign in. See Secrets in a vault.
InitialEnrollmentKey		random	The enrollment key a new database starts with (at least 24 characters), for containers set up together. Ignored once the database has one.
NodeOfflineSeconds		15	A node is shown as offline after this long without a heartbeat.
InstanceName	INSTANCENAME	the computer name	This server’s name in the console.
UpdateFeedUrl		Routes’ public releases	Where the daily check for a newer release asks: a GitHub “latest release” API address, or a mirror that answers the same way. See Upgrades.

See Several central servers.

Folders and logging

Setting	Installer property	Default	What it does
DataDirectory		%ProgramData%\Routes\Central\Data, /var/lib/routes/central	Certificates and the first administrator’s password. See Data folders.
LogDirectory	LOGDIR	%ProgramData%\Routes\Central\Logs, /var/log/routes/central	A file a day, central-<yyyymmdd>.log, 30 kept.
LogLevel		Information	Verbose, Debug, Information, Warning or Error.

The event log and syslog are set in the console, for every server at once.

Development only

DevelopmentUser signs every request in as that administrator, and only when ASPNETCORE_ENVIRONMENT is Development. It is ignored otherwise. Never use it on a server that holds real data.