Skip to main content

Management API and console

info

The management API and console are available from Genesis Server 8.15.34, and LDAP login from 8.15.37.

The Resource Daemon can serve two management surfaces, for operators who can't get a shell on the host:

  • a JSON API under /mgmt
  • a browser console

Both let an authorized user change a process's log level, start, stop or restart a process, and capture heap and thread dumps. They act only on processes on the node that serves them. Starting, stopping and restarting processes and changing log levels work only on Linux.

Enabling the API and the console​

Both surfaces are off by default, and each has its own switch. The daemon reads these when it starts. You must also name the processes that can be managed:

genesis-system-definition.kts
systemDefinition {
global {
...
item(name = "DaemonMgmtApiEnabled", value = "true")
item(name = "DaemonMgmtApiAuthMode", value = "OIDC")
item(name = "DaemonMgmtOidcIssuer", value = "https://idp.example.com/")
item(name = "DaemonMgmtOidcJwksUri", value = "https://idp.example.com/.well-known/jwks.json")
item(name = "DaemonMgmtOidcAudience", value = "genesis-daemon")

item(name = "DaemonMgmtUiEnabled", value = "true")
item(name = "DaemonMgmtUiLoginMode", value = "USER_PASSWORD")
item(name = "DaemonMgmtPasswordSalt", value = "<the passwordSalt from auth-preferences.kts>")

item(name = "DaemonManagedProcesses", value = "POSITION_EVENT_HANDLER,POSITION_DATASERVER")
...
}
}

The API and the console are served on the daemon's HTTP port, DaemonServerPort (4568 in the default system definition). The daemon itself serves plain HTTP. To use the console, put it behind a proxy that terminates TLS, because its session cookie is marked Secure by default.

Settings​

ItemDescriptionDefault
DaemonMgmtApiEnabledServe the /mgmt APIfalse
DaemonMgmtUiEnabledServe the browser consolefalse
DaemonManagedProcessesComma-separated list of the processes that can be managed, case-insensitive. * or ALL means every process on the node. If this is not set, every action is rejected
DaemonDiagnosticsDirWhere heap and thread dumps are written$GENESIS_HOME/runtime/diagnostics
DaemonMgmtApiAuthModeHow API callers are authenticated: IAP, OIDC or TRUSTED_PROXY. See API authentication. Required when the API is enabled
DaemonMgmtIapAudienceExpected audience of the token. Required for IAP
DaemonMgmtOidcIssuerExpected issuer of the token. Required for OIDC
DaemonMgmtOidcJwksUriURI of the JSON Web Key Set that verifies the token. Required for OIDC
DaemonMgmtOidcAudienceExpected audience of the token. Required for OIDC
DaemonMgmtOidcUsernameClaimThe token claim that holds the usernamesub
DaemonMgmtOidcClockSkewSecondsClock skew allowed when validating a token, for IAP and OIDC, in seconds60
DaemonMgmtApiDefaultUserThe user that requests are attributed to under TRUSTED_PROXYLOCAL
DaemonMgmtUiLoginModeComma-separated list of login providers, in the order to try them. DISABLED or an empty value turns off loginUSER_PASSWORD
DaemonMgmtPasswordSaltThe salt for USER_PASSWORD login. It must match passwordSalt in auth-preferences.kts
DaemonMgmtSessionTtlMinutesHow long a console session can be idle, in minutes30
DaemonMgmtSessionMaxMinutesThe maximum length of a console session, in minutes480
DaemonMgmtSessionCookieNameThe name of the console's session cookieGENESIS_DAEMON_SESSION
DaemonMgmtCookieSecureMark the session cookie as Secure. Set to false only for local development over HTTPtrue
DaemonMgmtDiagnosticsDownloadEnabledAllow dumps to be downloaded from the console. When this is false, dumps are still written to disktrue

Rights​

Each action needs its own right, and neither surface creates or ships these rights. Add the ones you need and assign them to user profiles, so that they appear in RIGHT_SUMMARY:

RightActionAPI endpoint
MGMT_LOG_LEVELChange a log levelPOST /mgmt/processes/{name}/loglevel
MGMT_THREAD_DUMPCapture a thread dumpPOST /mgmt/processes/{name}/threaddump
MGMT_HEAP_DUMPCapture a heap dumpPOST /mgmt/processes/{name}/heapdump
MGMT_RESTARTRestart a processPOST /mgmt/processes/{name}/restart
MGMT_STARTStart a processPOST /mgmt/processes/{name}/start
MGMT_STOPStop a processPOST /mgmt/processes/{name}/stop

A user needs at least one of these rights to log in to the console, and sees only the actions they hold rights for. Rights changes made through the auth event handlers take effect straight away. If you load profile data directly into the database, run ConsolidateRights. If a console user loses all MGMT_* rights, their session ends on their next request.

API authentication​

DaemonMgmtApiAuthMode has no default. While the API is enabled and this is unset or not valid, every request gets a 503.

ModeHow a caller is authenticated
IAPValidates the Google Cloud Identity-Aware Proxy JWT in the x-goog-iap-jwt-assertion header. The username is the email claim
OIDCValidates the JWT in the Authorization: Bearer header against the configured issuer, JWKS URI and audience. The username comes from DaemonMgmtOidcUsernameClaim
TRUSTED_PROXYNo credential check. Every request is attributed to DaemonMgmtApiDefaultUser, so rights are the only check

The username from the token must match USER_NAME in the USER table exactly, including case. Otherwise every request gets a 403.

warning

With TRUSTED_PROXY, make sure that the daemon's port can be reached only through the trusted proxy.

Calling the API​

Each endpoint takes a JSON body with a mandatory reason:

curl -X POST http://localhost:4568/mgmt/processes/POSITION_EVENT_HANDLER/loglevel \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"level": "DEBUG", "expirySeconds": 900, "reason": "Investigating rejected trades"}'

The loglevel endpoint also accepts these fields:

FieldDescription
levelTRACE, DEBUG, INFO, WARN or ERROR. Required unless reset is true
expirySecondsHow long the change lasts, in seconds, from 0 to 14400. If you leave it out, it is 3600. 0 makes the change permanent
resetSet to true to return the process to its default level

The response has the fields action, processName, outcome and detail. For a thread or heap dump, detail gives the path of the file. The daemon must run on a JDK, not a JRE, to capture dumps.

StatusMeaning
400The body or a field is not valid, reason is missing, the process name is not valid, or the process is not in DaemonManagedProcesses
401The caller could not be authenticated
403The user doesn't have the right for this action
409Another operation is in progress on this process
500The operation failed, for example a dump could not be captured, or a start, stop or restart was not confirmed within 30 seconds
503The API is misconfigured, or authentication is unavailable, for example because the JWKS can't be reached

Console login providers​

The console is at /login. List one or more of these providers in DaemonMgmtUiLoginMode:

ProviderHow a user logs in
USER_PASSWORDUsername and password, checked against the USER table. The account's STATUS must be ENABLED
LDAPUsername and password, checked against an LDAP directory. The user must also have a USER row with STATUS of ENABLED
JWT_HEADERUses the token that a proxy sends with the request, so the user doesn't enter a password. Needs DaemonMgmtApiAuthMode to be IAP or OIDC, and is not enabled otherwise. The API itself doesn't need to be enabled

Providers that use a username and password are tried in the listed order. The next one is tried only if the current one rejects the credentials or is unavailable, so with LDAP,USER_PASSWORD, a local account still works if the directory is unreachable. If a provider accepts the user but the user holds no MGMT_* right, login is refused and the next provider is not tried. After five failed logins in a row for the same username and IP address, that combination is locked out for a minute.

The console's auto-revert field works differently from the API's expirySeconds: leaving it blank makes a log level change permanent.

LDAP settings​

The LDAP provider needs LdapUrl, and either LdapSearchBases or LdapUserDnTemplate. If the configuration is not valid, the provider is not registered, the daemon logs an error, and any other listed provider still works.

ItemDescriptionDefault
LdapUrlThe directory's hostname, without a scheme
LdapPortThe directory's port636 if LdapUseTLS is true, otherwise 389
LdapUseTLSConnect with LDAPS. Without it, passwords are sent in clear textfalse
LdapVerifyHostnameCheck the certificate's hostnametrue
LdapTrustSourceWhere trusted certificates come from: SYSTEM, CERTIFICATE (with LdapTrustCaBundlePath) or TRUSTSTORE (with LdapTrustStorePath, LdapTrustStoreType and LdapTrustStorePassword)SYSTEM
LdapSearchBasesSemicolon-separated DNs to search for the user
LdapUserDnTemplateA template to bind with directly instead of searching, using {0} or %s for the username, for example CN={0},OU=People,DC=example,DC=com. If you also set LdapUserGroups, the template must produce a valid DN
LdapBindDn, LdapBindPasswordThe service account for searches. If these aren't set, searches are anonymous
LdapUserIdTypeComma-separated attributes to search oncn
LdapCanonicalIdAttributeThe attribute whose value is matched to USER_NAMEthe first entry in LdapUserIdType
LdapUserGroupsSemicolon-separated DNs of the groups a user must belong to. If this isn't set, any user who can bind is accepted
LdapNestedGroupSearchInclude nested group membershipfalse
LdapStripDomainPrefixTreat DOMAIN\username as usernametrue
LdapUserPrefixA prefix added to the value that is searched for
LdapConnectTimeoutMs, LdapResponseTimeoutMsConnection and response timeouts5000, 10000

Audit log​

The daemon writes every API and console action, and every console login, logout and ended session, including denied attempts, to its log under the MGMT_AUDIT logger. Each entry is a JSON line with the action, process, user, reason, outcome, detail and host.