Setup & Configuration¶

Last update: October 19, 2026

This page is the reference of every setting of Tolk for Cisco UC. The whole configuration is done from the Admin Web UI: one chapter per page, one section per tab, and for each setting its key, its description and its default value.

Editing Settings¶

The settings pages (Global settings, Products) group the parameters of each tab in cards. Each row shows the key, its current value and a ? icon with a contextual help text.

Edit: hover a value and click the pencil icon. The edit page shows the current value, checks the new one (type, range, consistency) and offers Reset to default when the value differs from the default.
Staged changes: a saved value is not applied immediately. The row turns orange and a banner shows the number of staged changes.
Apply: open System & reload → Apply / Restart. The page lists every change (before / after, author), runs pre-restart checks (integrity, TLS certificates, active clients, active admin sessions) and lets you undo one change or all of them. Restart now applies the configuration (the MCP server and admin sessions are briefly interrupted).
Snapshots: a timestamped snapshot of the configuration is kept before each change (see BACKUP_ADMIN_UI_ENV_BACKUP_RETENTION).
New settings: after an upgrade, the settings added by the new release are highlighted in blue until they are edited, marked as seen (Mark as seen) or for 7 days.
Greyed settings: a setting made irrelevant by another one is greyed out (e.g. every BACKUP_* setting when BACKUP_ENABLED is 0).
Filters: the tab bar offers a search box and a Hide parameters left at their default value toggle.
Files and trust stores: settings that point to a file (keys, certificates, known_hosts…) or to a CA trust store are not edited inline: a View / Edit link opens a dedicated page (metadata, content, generation, import…).

Access rights

Editing requires the read-write (RW) access level on the page, granted by the administrator profile (see Administrators).

Global Settings¶

Menu Global settings. The page has eight tabs.

Server¶

Identity¶

Key	Description	Default
`MCP_SERVER_NAME`	Display name of the MCP server.	`Tolk for Cisco UC`
`MCP_SERVER_INSTRUCTIONS`	Instructions advertised to connecting AI agents (the built-in text asks them to call `infra_init_session` first).	(built-in text)
`HOST_FQDN`	FQDN of the Docker host (output of `hostname -f`), not of the container. Used as the container hostname and for license binding: must match the license.	(to be set)

Docker container¶

Key	Description	Default
`UID`	Numeric user ID the container runs as (output of `id -u` for the service account). Must own the bind-mounted directories. `0` (root) is refused.	`1000`
`GID`	Numeric group ID the container runs as (output of `id -g` for the service account). Must match the group of the bind-mounted directories. `0` (root) is refused.	`1000`

Applied by Docker Compose

UID / GID are read by Docker Compose when the container is created: after a change, run docker compose up -d on the host — Apply & restart is not enough. Change the owner of the bind-mounted directories accordingly (sudo chown -R <uid>:<gid> ~/tolk) before re-creating the container.

Persistent Data (Bind-Mount Volumes)¶

The configuration and all runtime data are persisted on the host, in the installation directory, via bind-mount volumes:

Host Path	Container Path	Purpose
`./secrets/`	`/app/secrets/`	RSA keys, TLS certificates, license, admin accounts
`./clients/`	`/app/clients/`	Client data, reports
`./profiles/clients/_live`	`/app/profiles/clients/_live`	Client RBAC profiles (working copies)
`./profiles/webadmin/_live`	`/app/profiles/webadmin/_live`	Admin Web UI RBAC profiles (working copies)
`./logs/`	`/app/logs/`	Application & audit logs
`./backups/`	`/app/backups/`	Encrypted backups
`./servers-data/`	`/app/servers-data/`	AXL/RIS schemas, CA trust stores, custom prompts

Reverse proxy¶

Key	Description	Default
`MCP_SERVER_PUBLIC_URL`	Public base URL used by clients through a reverse proxy / VIP (`https://host[:port]`, no path). Automatically allowed in `MCP_SERVER_SECURITY_ALLOWED_HOSTS` / `MCP_SERVER_SECURITY_ALLOWED_ORIGINS`, advertised instead of `AUTH_ISSUER` (OAuth discovery, `/status`, client connection URL) and added as a secondary SAN. Empty = no proxy.	(empty)
`TRUSTED_PROXY_IPS`	Reverse proxies (comma-separated IPs / CIDR) in front of the MCP server and the admin UI. Only from these sources is `X-Forwarded-For` used to identify the real client (logs, blacklist, statistics, `ADMIN_UI_TRUSTED_IPS`); they are never blacklisted. Empty = no proxy.	(empty)

Transport¶

Key	Description	Default
`MCP_SERVER_HOST`	Bind address inside the container. Must stay `0.0.0.0` for Docker port mapping.	`0.0.0.0`
`MCP_SERVER_PORT`	TCP port the MCP server listens on (HTTPS, default 8443).	`8443`
`MCP_SERVER_TRANSPORT`	MCP transport protocol. `streamable-http` is the only supported transport.	`streamable-http`
`MCP_SERVER_SECURITY_TRANSPORT_ENABLED`	DNS-rebinding protection on the transport (1 = on, 0 = off).	`1`
`MCP_SERVER_URL_PATH`	URL path the MCP endpoint is served under.	`/mcp`
`MCP_SERVER_SECURITY_ALLOWED_HOSTS`	Allowed `Host` header values (comma-separated, port wildcard supported), e.g. `tolk.domain.com:*`. Loopback hosts and the `MCP_SERVER_PUBLIC_URL` host are implicit. Non-loopback entries are added as SANs of the self-signed certificate and of the CSR.	(to be set)
`MCP_SERVER_SECURITY_ALLOWED_ORIGINS`	Allowed `Origin` header values (comma-separated, `https://`), e.g. `https://tolk.domain.com:8443`. Loopback origins and the `MCP_SERVER_PUBLIC_URL` origin are implicit.	(to be set)

DNS rebinding protection

Setting MCP_SERVER_SECURITY_TRANSPORT_ENABLED to 0 disables Host / Origin header validation. Only disable it in fully isolated networks where DNS rebinding attacks are not a concern. These checks apply to the MCP port only, not to the admin UI.

Maintenance mode¶

Key	Description	Default
`MAINTENANCE_IDLE_TIMEOUT_SECONDS`	While maintenance mode is on (System & reload page), a client idle for longer than this many seconds has its MCP requests refused ("retry later"). Active clients continue; new sessions are always refused.	`300`
`MAINTENANCE_MAX_DRAIN_SECONDS`	Optional maximum drain duration, in seconds, after maintenance mode is enabled: once elapsed, every MCP request is refused, active client or not. 0 = no limit.	`0`

Maintenance mode itself is switched on and off from the System & reload page.

Other¶

Key	Description	Default
`SERVER_HEALTHCHECK_STATUS_RESPONSE`	Body returned by the health-check endpoint when the server is healthy.	`ok`
`INTEGRITY_CHECK_INTERVAL_HOURS`	Interval, in hours, of the file-integrity watchdog check.	`24`

Info¶

These read-only values identify the installation. They are updated automatically by each upgrade.

Key	Description	Default
`PROJECT_CREATOR`	Project author/creator metadata (informational).	`Pierre SOURDEAU`
`PROJECT_NAME`	Project name metadata (informational).	`tolk-for-cisco-uc`
`PROJECT_VERSION`	Project/build version; also used by the integrity manifest.	(installed release)

Authentication¶

Identity¶

Key	Description	Default
`AUTH_AUDIENCE`	Expected JWT `aud` claim, identifying this server as the intended token audience.	`mcp-clients`
`AUTH_ISSUER`	Public HTTPS URL of the server (e.g. `https://tolk.domain.com:8443`): JWT `iss` claim, OAuth 2.1 Authorization Server base URL and CN of the generated certificates.	(to be set)
`AUTH_MODE`	Global authentication mode: `jwt`, `oauth2` or `jwt+oauth2` (see Authentication Modes).	`jwt`
`CLIENTS_DIR`	Directory where per-client data (credentials, reports) is stored.	`./clients/`

MCP clients are not declared here but on the Clients page.

Authentication Modes¶

`AUTH_MODE`	Credentials	Typical use
`jwt`	Long-lived signed JWT token (Bearer), pre-generated for each client	AI agents configured with a static token
`oauth2`	OAuth 2.1: `client_id` / `client_secret`, short-lived access tokens	AI agents (interactive browser login or automatic login), scripts / pipelines
`jwt+oauth2`	Both: each client gets its own mode (`jwt`, `oauth2` or both)	Mixed environments

JWT Mode (Default)¶

A signed RS256 JWT is generated for each client and shown once with View credentials on the Clients page.
Its lifetime is set by AUTH_TOKEN_EXPIRY_DAYS (default: 365 days).
At startup, a token is renewed automatically when it is missing, corrupted, wrongly signed, or when its claims or subject changed.
Reset tokens (Clients page) revokes the current token immediately and generates a new one.

JWT claims:

Claim	Description
`sub`	Client subject
`iss`	Issuer (`AUTH_ISSUER`)
`aud`	Audience (`AUTH_AUDIENCE`)
`iat`	Issued-at timestamp
`exp`	Expiration timestamp
`jti`	Unique token ID (for revocation)
`client_id`	Client name

OAuth 2.1 Mode¶

OAuth 2.1 uses short-lived dynamic tokens, better suited to automated pipelines and to environments with stricter credential hygiene.

client_id = client name, created on the Clients page (no dynamic client registration). The client_secret is shown once with View credentials; only its bcrypt hash is kept.
Access token lifetime: AUTH_OAUTH_TOKEN_EXPIRY_SECONDS (default: 3600 s). No refresh token is issued: on expiry, the agent obtains a new token with the same flow.
Reset tokens (Clients page) rotates the client_secret: the previous secret can no longer obtain tokens.
Endpoints: GET/POST /authorize, POST /token, POST /revoke (RFC 7009), GET /.well-known/oauth-authorization-server (RFC 8414), GET /.well-known/oauth-protected-resource (RFC 9728).

An AI agent obtains its tokens in one of two ways, depending on what it supports:

	Interactive login (browser)	Automatic login (client credentials)
OAuth grant	`authorization_code` + PKCE (RFC 7636)	`client_credentials` (RFC 6749 §4.4)
Agent configuration	Server URL, plus the `client_id` when the agent accepts it	Server URL, `client_id` and `client_secret`
Where the secret is typed	By the user, on the Tolk login page	Nowhere: the agent reads it from its configuration file
Browser	Yes	No
Token expiry	The agent opens the login page again	The agent requests a new token by itself, without user action
Redirect URI allow-list	Applies (see OAuth Redirect URI Allow-List)	Not used
Typical clients	AI IDEs and agents with a browser login (e.g. OpenCode)	Agents supporting the client credentials grant (e.g. Claude Desktop), MCP SDKs, automation platforms, scripts

Interactive login (authorization_code + PKCE):

The agent receives a 401 response and performs the OAuth discovery (/.well-known/...).
It opens the Tolk login page in the browser (GET /authorize), with the client_id pre-filled when its configuration provides it.
The user enters the client_id (if empty) and the client_secret.
The browser is redirected back to the agent (redirect_uri) with an authorization code.
The agent exchanges the code for an access token (POST /token), protected by PKCE.

Note

In this flow, the secret is always typed on the login page: even if the agent configuration also holds a client_secret, Tolk does not use it and the browser still opens. Only an agent using the client credentials grant connects without user action.

Automatic login (client_credentials):

The agent reads the client_id and the client_secret from its configuration.
It sends them to POST /token with grant_type=client_credentials, in the HTTP Basic header (client_secret_basic) or in the form body (client_secret_post).
It calls the MCP server with the returned access token (Authorization: Bearer ...).
When the token expires (expires_in), it requests a new one the same way.

Equivalent request with curl:

curl -sk -X POST https://tolk.domain.com:8443/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

Secret stored in the agent configuration

With the automatic login, the client_secret is stored in clear text in the agent configuration file: restrict its access rights, and create one client per user and agent so that Reset tokens only affects that agent.

Hybrid JWT + OAuth 2.1 Mode¶

With jwt+oauth2, the client form of the Clients page shows an authentication mode field: each client uses jwt, oauth2 or both. Some clients can thus use static JWT tokens while others use OAuth 2.1.

Brute-force protection¶

Key	Description	Default
`AUTH_FAIL_LIMIT`	Authentication failures allowed before the source IP is blacklisted.	`10`
`AUTH_FAIL_WINDOW_SECONDS`	Sliding window, in seconds, over which authentication failures are counted.	`300`
`AUTH_BLACKLIST_DURATION_SECONDS`	How long an IP stays blacklisted after exceeding the auth failure limit, in seconds.	`900`

Token expiry¶

Key	Description	Default
`AUTH_TOKEN_EXPIRY_DAYS`	Lifetime, in days, of static JWT tokens issued in jwt mode.	`365`
`AUTH_OAUTH_TOKEN_EXPIRY_SECONDS`	Lifetime of OAuth2 access tokens, in seconds (used only when `AUTH_MODE` includes oauth2).	`3600`

OAuth2 redirect URIs¶

Key	Description	Default
`AUTH_OAUTH_REDIRECT_URIS`	Per-client JSON allow-list of OAuth 2.1 `redirect_uri` values (see OAuth Redirect URI Allow-List). Empty = no allow-list.	(empty)
`AUTH_OAUTH_REDIRECT_URI_ENFORCEMENT`	`off` (allow-list not enforced, mismatches are only audited) or `strict` (recommended in production: a `redirect_uri` not in the allow-list is rejected).	`off`

OAuth Redirect URI Allow-List¶

In the authorization_code flow, the browser is redirected to the redirect_uri supplied by the AI agent. The allow-list restricts these URIs, per client:

{"alice": ["http://127.0.0.1:19876/mcp/oauth/callback"], "*": ["http://127.0.0.1:19876/mcp/oauth/*"]}

Key = client name (client_id). The "*" key holds the URIs allowed for every client; they are added to each client's own list.
Match: exact, or by prefix when the entry ends with *. Keep the scheme, host, port and path in a prefix (http://127.0.0.1/* does not match http://127.0.0.1:19876/...).
Several agents: create one client per user and agent, and list all its URIs; a client can have several (e.g. OpenCode and another tool).
Unknown URI: in strict mode with an empty list, nothing is blocked and the received redirect_uri is logged as a warning in the application log. Add it to the list, then apply.

Agent	Default `redirect_uri`
OpenCode	`http://127.0.0.1:19876/mcp/oauth/callback` (can be pinned per server with `"oauth": {"redirectUri": "..."}` in `opencode.json`)

Production

Set AUTH_OAUTH_REDIRECT_URI_ENFORCEMENT to strict with exact URIs. The allow-list is used only when AUTH_MODE is oauth2 or jwt+oauth2.

RSA keys¶

Key	Description	Default
`AUTH_RSA_KEY_SIZE`	Size in bits of the RSA server keypair (`2048`, `3072` or `4096`), used when the keypair is (re)generated.	`4096`
`AUTH_RSA_PRIVATE_KEY_FILE`	RSA private key: signs JWT tokens and decrypts backups.	`./secrets/rsa_private.pem`
`AUTH_RSA_PUBLIC_KEY_FILE`	RSA public key: verifies JWT tokens and encrypts backups.	`./secrets/rsa_public.pem`

The RSA server keypair signs the JWT tokens and encrypts the backups. The Regenerate keypair button of this card runs a full rotation: full-system backup, archive of the current keypair, generation of a new keypair and re-issue of every client token. Afterwards, communicate the new tokens with View credentials on the Clients page, then apply the staged restart.

Impact of a regeneration

All existing client tokens become invalid, and backups encrypted with the previous key can only be decrypted with the archived key: export it offline. See RSA Key Rotation.

TLS / Crypto¶

MCP server certificate¶

Key	Description	Default
`MCP_TLS_CSR_FILE`	Certificate signing request of the MCP server certificate (Generate CSR…).	`./secrets/server.csr`
`MCP_TLS_KEY_FILE`	Private key of the MCP server certificate (self-signed or CA-signed); also signs the CSR.	`./secrets/server.key`
`MCP_TLS_CERT_FILE`	MCP server certificate, self-signed or CA-signed (see TLS Certificates).	`./secrets/server.crt`
`MCP_TLS_SELFSIGNED_VALIDITY_DAYS`	Validity, in days, of the auto-generated self-signed server certificate (default 365).	`365`

Certificate infos¶

These values fill the subject of the CSRs; the CN is always the AUTH_ISSUER host.

Key	Description	Default
`CERT_COUNTRY`	Country (C) field for the generated CSR / certificate subject.	`FR`
`CERT_STATE`	State/Province (ST) field for the generated CSR / certificate subject.	`STATE`
`CERT_LOCATION`	Location / Locality (L) field for the generated CSR / certificate subject.	`LOCATION`
`CERT_ORG`	Organization (O) field for the generated CSR / certificate subject.	`ORG`
`CERT_OU`	Organizational Unit (OU) field for the generated CSR / certificate subject.	`OU`
`CERT_KEY_SIZE`	RSA key size in bits used when generating a new certificate private key.	`4096`

Crypto¶

Key	Description	Default
`CRYPTO_SALT_FILE`	Path to the server-side salt file used for cryptographic derivations.	`.salt`
`CRYPTO_SECRETS_DIR`	Directory holding server cryptographic secrets (keys, certificates, salt).	`./secrets/`

TLS Certificates¶

Each listener uses a single certificate / key pair, self-signed or CA-signed:

Listener	Certificate / key settings
MCP server	`MCP_TLS_CERT_FILE` / `MCP_TLS_KEY_FILE`
Admin Web UI	`ADMIN_UI_TLS_CERT_FILE` / `ADMIN_UI_TLS_KEY_FILE` (only when `ADMIN_UI_TLS_REUSE_MCP_CERT` is `0`; see Admin UI → TLS)

The type is detected from the certificate itself (issuer = subject → self-signed, otherwise CA-signed).

Self-Signed Certificate (Default)¶

At startup, when the pair is missing (or only one of the two files exists), Tolk generates a self-signed certificate:

CN = host of AUTH_ISSUER;
SANs = the CN + every non-loopback host of MCP_SERVER_SECURITY_ALLOWED_HOSTS (admin UI: ADMIN_UI_TLS_ALLOWED_HOSTS, or the MCP list when empty) + the host of MCP_SERVER_PUBLIC_URL. localhost / 127.0.0.1 are never included.

An existing self-signed certificate is regenerated at startup when more than 50% of its lifetime has elapsed, when its CN/SANs no longer match the configuration, or when it no longer matches its private key.

Regeneration only at restart

A self-signed certificate is never renewed while the server is running. Once it has passed 50% of its lifetime, the header shows TLS certificate: RESTART REQUIRED, the restart banner appears on every page and the Apply & restart page lists the certificate as a pending change (author System). Restart the server to regenerate it.

Without a restart, the current certificate is still served until it expires; AI agents then reject the TLS connection. The next restart regenerates it. A regenerated certificate is a new certificate: agents that explicitly trust the previous one must trust the new one.

CA-Signed Certificate¶

Click View / Edit on MCP_TLS_CSR_FILE, then Generate CSR…: a preview shows the subject and the SANs, which can be removed or added for this request only.
Have the CSR signed by your CA.
Import the signed certificate on the MCP_TLS_CERT_FILE page. It replaces the self-signed certificate (the private key is preserved), and the spent CSR is removed.
Apply & restart.

A CA-signed certificate is never overwritten nor renewed by Tolk. At startup, an expired CA-signed certificate is fatal for the MCP server (the admin UI listener is disabled instead). To go back to a self-signed certificate, use Delete certificate + key: a new self-signed pair is generated at the next restart.

Recommended for production

A CA-signed certificate removes the TLS trust warnings on AI agents and is strongly recommended for any production deployment.

Certificate Status¶

The dashboard (Security zone), the System & reload page and the header use the same rule, for both certificates and both types:

OK — less than 50% of the lifetime has elapsed;
Renewal recommended — more than 50% elapsed (self-signed: restart required, the restart regenerates it; CA-signed: generate a new CSR and install the re-signed certificate);
Expired.

Admin UI¶

General¶

Key	Description	Default
`ADMIN_UI_ENABLED`	Master switch for the whole admin web UI (0 = the dedicated HTTPS port is not opened).	`1`
`ADMIN_UI_DEFAULT_LANGUAGE`	UI language shown before sign-in: en or fr.	`en`

Disabling the admin UI

With ADMIN_UI_ENABLED set to 0, the admin port is closed after the restart and the Web UI is no longer reachable.

Transport¶

Key	Description	Default
`ADMIN_UI_HOST`	Bind address of the admin UI listener inside the container. Must stay `0.0.0.0` for Docker port mapping (with `127.0.0.1` or a host IP, the admin UI is unreachable from outside the container); restrict access with the host firewall and `ADMIN_UI_TRUSTED_IPS`.	`0.0.0.0`
`ADMIN_UI_PORT`	Dedicated HTTPS port for the admin UI (must differ from `MCP_SERVER_PORT`).	`9443`
`ADMIN_UI_TRUSTED_IPS`	Access allow-list (comma-separated CIDR) evaluated against the client IP (TCP socket IP, or X-Forwarded-For behind a proxy listed in `TRUSTED_PROXY_IPS`). Empty = deny all.	`10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`

Loopback always allowed

127.0.0.1/32 is always trusted, even when it is not listed in ADMIN_UI_TRUSTED_IPS (container health check and local recovery).

Brute-force protection¶

Key	Description	Default
`ADMIN_UI_LOGIN_LOCKOUT_MINUTES`	How long a client is locked out after too many failed admin logins, in minutes.	`15`
`ADMIN_UI_LOGIN_MAX_ATTEMPTS`	Failed admin login attempts allowed before a temporary lockout.	`5`
`ADMIN_UI_LOGIN_WINDOW_SECONDS`	Sliding window, in seconds, over which failed admin logins are counted.	`300`

Password policy¶

Key	Description	Default
`ADMIN_UI_PWD_MIN_LENGTH`	Minimum length required for admin passwords (12 recommended minimum).	`12`
`ADMIN_UI_PWD_REQUIRE_COMPLEXITY`	Require mixed character types in admin passwords (1 = on, 0 = off).	`1`
`ADMIN_UI_PWD_BCRYPT_COST`	bcrypt work factor (log2 rounds) of the admin account passwords, applied when a password is set (change, account creation, reset, `admin_set_password.py`). Each +1 doubles the hashing time, at every login too (≈ 0.2 s at 12, 0.8 s at 14). Existing passwords keep their cost until they are changed. Range 4-16. Does not apply to OAuth client secrets.	`12`

Session¶

Key	Description	Default
`ADMIN_UI_SESSION_IDLE_MINUTES`	Idle timeout, in minutes, before an admin session expires automatically.	`15`
`ADMIN_UI_SESSION_REMEMBER_DAYS`	Lifetime, in days, of a persistent session when 'Keep me signed in' is checked.	`7`
`ADMIN_UI_SESSION_TTL_MINUTES`	Maximum lifetime of an admin session, in minutes.	`30`
`ADMIN_UI_SESSION_SECRET_FILE`	Path to the cookie-signing secret for admin sessions (auto-created if missing).	`./secrets/admins/sessions.key`

TLS¶

Key	Description	Default
`ADMIN_UI_TLS_REUSE_MCP_CERT`	Reuse the MCP TLS certificate on the admin port (1) or serve a dedicated certificate (0).	`1`
`ADMIN_UI_TLS_CSR_FILE`	CSR path for obtaining a CA-signed admin UI certificate. Generated from the admin UI and signed with the admin UI private key (the key is preserved).	`./secrets/admins/admin-ui.csr`
`ADMIN_UI_TLS_KEY_FILE`	Private key for the dedicated admin certificate (used only when reuse=0).	`./secrets/admins/admin-ui.key`
`ADMIN_UI_TLS_CERT_FILE`	Dedicated admin UI certificate, self-signed or CA-signed (used only when `ADMIN_UI_TLS_REUSE_MCP_CERT` is `0`).	`./secrets/admins/admin-ui.crt`
`ADMIN_UI_TLS_ALLOWED_HOSTS`	Extra SANs of the dedicated admin UI certificate (comma-separated `host[:port]`). Empty = reuse `MCP_SERVER_SECURITY_ALLOWED_HOSTS`.	(empty)
`ADMIN_UI_TLS_SELFSIGNED_VALIDITY_DAYS`	Validity, in days, of the auto-generated self-signed admin certificate.	`365`

By default the admin UI reuses the MCP server certificate. With ADMIN_UI_TLS_REUSE_MCP_CERT set to 0, it serves its own certificate, managed like the MCP one (see TLS Certificates).

Other¶

Key	Description	Default
`ADMIN_UI_HELP_LINK`	URL opened by the help (?) icon of the sign-in page and of the sidebar (`http://` or `https://`). Point it to an internal documentation mirror on air-gapped sites.	`https://tolk.sourdeau.com`
`ADMIN_UI_PROMPTS_EDITOR_ENABLED`	Custom prompts editor: `1` = editable from the Web UI, `0` = read-only.	`1`
`ADMIN_UI_SEASONAL_EFFECTS`	Decorative animation of the sign-in page: `off`, `auto` (seasonal theme by date) or a forced theme (`snow`, `christmas`, `spring`, `summer`, `autumn`).	`auto`

Client Credentials Reveal Template¶

The Client credentials reveal template card defines the text shown by View credentials on the Clients page (connection details to send to a client). Placeholders: {server_name}, {server_url}, {client_id}, {jwt_token}, {oauth_client_secret}.

Logging¶

General¶

Key	Description	Default
`LOGGING_LEVEL`	Minimum log verbosity: debug, info, warning, error or critical.	`info`
`LOGGING_DIR`	Directory where application log files are written.	`./logs/`
`LOGGING_ENCODING_FORMAT`	Character encoding for log files (e.g. utf-8).	`utf-8`

Debug level

debug is very verbose and is flagged by a warning icon in the Web UI. Use it only for troubleshooting.

Application logs rotation¶

Key	Description	Default
`LOGGING_ROTATE_FILES`	Number of rotated application-log archives to keep.	`3`
`LOGGING_ROTATE_SIZE`	Size threshold (bytes) that triggers application log rotation.	`5_000_000`

Audit logs rotation¶

Key	Description	Default
`LOGGING_AUDIT_ROTATE_FILES`	Number of rotated audit-log archives to keep.	`10`
`LOGGING_AUDIT_ROTATE_SIZE`	Size threshold (bytes) that triggers audit log rotation.	`10_000_000`

Console logging¶

Key	Description	Default
`LOGGING_CONSOLE_ENABLED`	Enable console log output (1 = on, 0 = off).	`0`
`LOGGING_COLORED_CRITICAL`	ANSI color used for CRITICAL log lines in console output.	`bold_red`
`LOGGING_COLORED_DEBUG`	ANSI color used for DEBUG log lines in console output.	`cyan`
`LOGGING_COLORED_ERROR`	ANSI color used for ERROR log lines in console output.	`red`
`LOGGING_COLORED_INFO`	ANSI color used for INFO log lines in console output.	`green`
`LOGGING_COLORED_WARNING`	ANSI color used for WARNING log lines in console output.	`yellow`

Other¶

Key	Description	Default
`LOGGING_SHOW_TECH_BACKUP_RETENTION`	Retention of show-tech bundles, in days (`0` = never purge).	`30`

Backup¶

Backups are encrypted (AES-256-GCM + RSA OAEP) and can also be triggered and restored from the Backup / Restore page. See Backup & Restore for the encryption model and the restore procedure.

General¶

Key	Description	Default
`BACKUP_ENABLED`	Enable automatic periodic backups (1 = on, 0 = off).	`1`
`BACKUP_DIR`	Local directory where backup archives are stored.	`./backups/`
`BACKUP_INTERVAL_HOURS`	Interval between automatic backups, in hours.	`168`
`BACKUP_RETENTION`	Number of local backup archives to keep.	`4`
`BACKUP_EXCLUDE_DIRS`	Comma-separated directories (relative to project root) excluded from backups.	`./backups/,./.git/,./__pycache__/,./.venv/,./dist/,./build/`

Backup SFTP export¶

After each local backup, the archive can be pushed to a remote SFTP server.

One remote directory per Tolk server

When several Tolk servers export to the same SFTP server, each one must use its own directory or sub-directory in BACKUP_SFTP_REMOTE_PATH (e.g. /backups/tolk-1/, /backups/tolk-2/). Never share a remote directory between two Tolk servers.

Key	Description	Default
`BACKUP_SFTP_HOST`	Hostname of the SFTP server for off-site backup export (empty = SFTP export disabled).	(empty)
`BACKUP_SFTP_PORT`	TCP port of the SFTP server (default 22).	`22`
`BACKUP_SFTP_AUTH`	SFTP authentication method for remote export: key or password.	`key`
`BACKUP_SFTP_USER`	Username for the SFTP export connection.	(empty)
`BACKUP_SFTP_PASSWORD_ENC`	SFTP password (when `BACKUP_SFTP_AUTH` is `password`), stored encrypted. Set it with the Set password link.	(empty)
`BACKUP_SFTP_KEY_FILE`	SSH private key used for the SFTP export (when `BACKUP_SFTP_AUTH` is `key`).	`./secrets/backup_ssh_key`
`BACKUP_SFTP_REMOTE_PATH`	Destination directory on the SFTP server, dedicated to this Tolk server.	`/backups/tolk/`
`BACKUP_SFTP_RETENTION`	Number of backup archives to keep on the SFTP server.	`52`
`BACKUP_SFTP_KNOWN_HOSTS`	OpenSSH `known_hosts` file pinning the SFTP server host key (mandatory before the first transfer).	`./secrets/sftp_known_hosts`

Trust the SFTP server host key first

Without an entry for the server in BACKUP_SFTP_KNOWN_HOSTS, no transfer ever happens: the transfer aborts before any credential is sent (anti-MITM). Click View / Edit on BACKUP_SFTP_KNOWN_HOSTS, then Get server keys: the host keys of BACKUP_SFTP_HOST / BACKUP_SFTP_PORT are retrieved (without authentication) with their SHA-256 fingerprints. Verify the fingerprints out-of-band with the SFTP administrator, then click Save.

SSH Key AuthenticationPassword Authentication

Set BACKUP_SFTP_AUTH to key. Click View / Edit on BACKUP_SFTP_KEY_FILE to generate the key (Regenerate key) or replace it, then authorize the matching public key on the SFTP server.

Set BACKUP_SFTP_AUTH to password, then click Set password on the BACKUP_SFTP_PASSWORD_ENC row. The password is encrypted with the server key; it is never stored in clear.

Other backups¶

Snapshots taken automatically by the Web UI before a change.

Key	Description	Default
`BACKUP_ADMIN_UI_ENV_BACKUP_RETENTION`	Maximum number of configuration snapshots kept (one is taken before each change).	`16`
`BACKUP_ADMIN_UI_CERT_BACKUP_RETENTION`	Maximum number of certificate, key and CSR snapshots kept per file under the backups/certificates directory.	`16`
`BACKUP_ADMIN_UI_RSA_BACKUP_RETENTION`	Maximum number of `AUTH_RSA` server keypair snapshots kept per key file under the backups/rsa_keys directory.	`16`

Rate limiting¶

On top of the per-client limits set in each client profile, an optional global limit (all clients combined) protects each Cisco node. It is counted per destination host and per service, after the per-client check. The per-product caps are on the Products page.

General¶

Key	Description	Default
`RATELIMIT_GLOBAL_ENABLED`	Master switch for the global (all-clients) rate limiter.	`true`
`RATELIMIT_WINDOW_SECONDS`	Length of the global rate-limit window, in seconds (default 60).	`60`

Common¶

Key	Description	Default
`RATELIMIT_GLOBAL_COMMON_REPORT`	Global cap (requests per window, all clients combined) for report writes.	`120`

Per-destination semantics

Each cap applies per destination host: every Cisco node gets its own budget. 0 disables the global cap for that service. A global rejection emits a RATE_LIMITED_GLOBAL audit line and increments mcp_global_rate_limit_hits_total.

SSH pool¶

SSH sessions to the Cisco nodes are pooled and reused.

Key	Description	Default
`SSH_POOL_MAX_SESSIONS_PER_HOST`	Hard cap on concurrent SSH sessions the pool opens per destination node. Commands beyond this queue until a session frees up (default: 3).	`3`
`SSH_POOL_ACQUIRE_TIMEOUT`	Max seconds a queued command waits for a free SSH session before failing with a pool timeout (default: 120).	`120`
`SSH_POOL_IDLE_TTL`	Seconds an idle SSH session is kept in the pool before the reaper closes it (default: 300).	`300`
`SSH_POOL_HEALTH_CHECK_TIMEOUT`	Seconds to probe a reused SSH session for the admin prompt before declaring it unhealthy (default: 5).	`5`

Reports¶

Charts¶

Key	Description	Default
`REPORT_CHARTS_COLORS`	Comma-separated color palette used for charts in generated reports.	`PASS=#78F5AE,WARN=#FFBE54,FAIL=#FF6F61,INFO=#69C2FF,N/A=#BACCCC`

Size limits¶

Key	Description	Default
`REPORT_MAX_CHUNK_BYTES`	Maximum content size per write_report call; larger content is truncated.	`204800`
`REPORT_MAX_FILE_SIZE_BYTES`	Maximum size of a report file before it auto-splits into a new part.	`2097152`
`REPORT_RESUME_TAIL_BYTES`	Number of trailing bytes returned when resuming a report write.	`8192`
`REPORT_RETENTION_DAYS`	Days to keep generated client reports before automatic purge (0 disables purging).	`30`

Products¶

Menu Products. One tab per product enabled by the license (unlicensed products are greyed out). These settings apply to every node of the product.

Cisco UC servers and credentials

The Cisco UC nodes and their credentials are not configured on this page: they are stored encrypted per MCP client, through the *_store_credentials tools called by the AI agent (see Reference).

CUCM¶

AXL (SOAP)¶

Key	Description	Default
`SERVER_CUCM_AXL_PORT`	TCP port of the CUCM AXL SOAP API (typically 8443).	`8443`
`SERVER_CUCM_AXL_SCHEMAS_DIR`	Local directory holding CUCM AXL WSDL/XSD schema files.	`./servers-data/cucm/axl-schemas/`
`SERVER_CUCM_AXL_WSDL_TIMEOUT`	HTTP timeout for downloading the CUCM AXL WSDL, in seconds.	`10`

RIS (RisPort)¶

Key	Description	Default
`SERVER_CUCM_RIS_MAX_DEVICE_NAMES`	Maximum number of device names accepted per cucm_risport_query call, all resolved in a single RisPort request; larger lists must be split into batches.	`1000`
`SERVER_CUCM_RIS_PORT`	TCP port of the CUCM RisPort (real-time info) API.	`8443`
`SERVER_CUCM_RIS_SCHEMAS_DIR`	Local directory holding CUCM RisPort WSDL/XSD schema files.	`./servers-data/cucm/ris-schemas/`
`SERVER_CUCM_RIS_WSDL_TIMEOUT`	HTTP timeout for downloading the CUCM RisPort WSDL, in seconds.	`15`

IP Phones¶

Key	Description	Default
`SERVER_CUCM_PHONES_ENABLED`	Load the CUCM IP Phones sub-module (cucm_phone_* tools and the phone procedure prompt): 1 = loaded (default), 0 = not loaded. Applied at restart.	`1`
`SERVER_CUCM_PHONES_SSL_CA_BUNDLE`	CA trust store used for IP phones when `SERVER_CUCM_PHONES_SSL_VERIFY` is `True` (e.g. CAPF / LSC issuing CA).	`./servers-data/cucm/certs-trust-store-phones/`
`SERVER_CUCM_PHONES_SSL_VERIFY`	Verify the HTTPS certificate chain of IP phones against the phones trust store (hostname not checked: phones are reached by IP).	`False`
`SERVER_CUCM_PHONE_CAMPAIGN_RETENTION_DAYS`	Days to keep the journals of closed or never-started IP phone upgrade campaigns before the nightly purge (03:15). Running or suspended campaigns are never purged. `0` = never purge.	`30`
`SERVER_CUCM_PHONE_MESSAGE_CONCURRENCY`	Maximum number of terminals messaged in parallel within one cucm_phone_send_message call.	`10`
`SERVER_CUCM_PHONE_MESSAGE_MAX_TARGETS`	Maximum number of terminals accepted per cucm_phone_send_message call; larger lists must be split into batches.	`50`
`SERVER_CUCM_PHONE_MESSAGE_TIMEOUT`	HTTP timeout for pushing a text message to one Cisco 88xx/98xx IP phone, in seconds.	`10`
`SERVER_CUCM_PHONE_SCREENSHOT_TIMEOUT`	HTTP timeout for capturing a CUCM phone screenshot, in seconds.	`10`
`SERVER_CUCM_PHONE_WEB_BATCH_TIMEOUT`	Time budget of one cucm_phone_web_info call with ip_phones, in seconds: the phones and pages not started within it are reported as not read.	`120`
`SERVER_CUCM_PHONE_WEB_CONCURRENCY`	Maximum number of phones read in parallel within one cucm_phone_web_info call with ip_phones (the pages of one phone are always read sequentially).	`5`
`SERVER_CUCM_PHONE_WEB_MAX_TARGETS`	Maximum number of phones accepted per cucm_phone_web_info call with ip_phones; larger lists must be split into batches.	`20`
`SERVER_CUCM_PHONE_WEB_TIMEOUT`	HTTP timeout for reading one Cisco 88xx/98xx IP phone web information page (cucm_phone_web_info), in seconds.	`10`

RoomOS codecs¶

Key	Description	Default
`SERVER_CUCM_ROOMOS_CAMPAIGN_RETENTION_DAYS`	Days to keep the journals of closed or never-started RoomOS upgrade campaigns before the nightly purge (03:15). Running or suspended campaigns are never purged. `0` = never purge.	`30`
`SERVER_CUCM_ROOMOS_ENABLED`	Load the CUCM RoomOS sub-module (cucm_roomos_* tools, RoomOS procedure prompt and xAPI reference): 1 = loaded (default), 0 = not loaded. Applied at restart.	`1`
`SERVER_CUCM_ROOMOS_MESSAGE_CONCURRENCY`	Maximum number of codecs messaged in parallel within one cucm_roomos_send_message call.	`10`
`SERVER_CUCM_ROOMOS_MESSAGE_MAX_TARGETS`	Maximum number of codecs accepted per cucm_roomos_send_message call; larger lists must be split into batches.	`50`
`SERVER_CUCM_ROOMOS_SSL_CA_BUNDLE`	CA trust store used for RoomOS codecs when `SERVER_CUCM_ROOMOS_SSL_VERIFY` is `True` (e.g. CAPF / LSC issuing CA).	`./servers-data/cucm/certs-trust-store-roomos/`
`SERVER_CUCM_ROOMOS_SSL_VERIFY`	Verify the HTTPS certificate chain of RoomOS codecs against the RoomOS trust store (hostname not checked: codecs are reached by IP).	`False`
`SERVER_CUCM_ROOMOS_TIMEOUT`	HTTP timeout for one xAPI request (getxml/putxml) to a RoomOS codec, in seconds.	`10`

CUCM sub-modules

IP phones and RoomOS codecs are two optional CUCM sub-modules. A disabled sub-module (SERVER_CUCM_PHONES_ENABLED / SERVER_CUCM_ROOMOS_ENABLED = 0) loads none of its tools, prompts or resources, and its settings are greyed out. A change requires a restart.

Terminal certificate verification

Certificate verification is disabled by default for phones and codecs: they are reached by IP address and usually present a manufacturer (MIC) or self-signed certificate. When *_SSL_VERIFY is True, the certificate chain is verified against the sub-module trust store (not the hostname). Add the issuing CAs (CAPF / LSC issuer, enterprise CA) with View / Edit on SERVER_CUCM_PHONES_SSL_CA_BUNDLE / SERVER_CUCM_ROOMOS_SSL_CA_BUNDLE. Security also relies on the terminal VLAN isolation, the HTTP credentials and the terminal IP being obtained from CUCM (RIS/AXL).

SSH / CLI¶

Key	Description	Default
`SERVER_CUCM_SSH_PORT`	TCP port for CUCM SSH (OS admin CLI), typically 22.	`22`
`SERVER_CUCM_SSH_TERM`	Terminal type advertised for CUCM SSH sessions.	`dumb`
`SERVER_CUCM_SSH_TERM_HEIGHT`	Pseudo-terminal height (rows) for CUCM SSH sessions.	`50`
`SERVER_CUCM_SSH_TERM_WIDTH`	Pseudo-terminal width (columns) for CUCM SSH sessions.	`220`
`SERVER_CUCM_SSH_TIMEOUT`	Timeout for CUCM SSH commands, in seconds.	`120`

SSH timeout

The SSH timeout defaults to 120 seconds on every product: some commands (e.g. cluster state on CUCM) take a while to return.

TLS / certificates¶

Key	Description	Default
`SERVER_CUCM_SSL_CA_BUNDLE`	CA trust store used to verify the CUCM certificate (private CA or product certificates).	`./servers-data/cucm/certs-trust-store/`
`SERVER_CUCM_SSL_VERIFY`	Verify the CUCM TLS certificate. True recommended; False (lab only) exposes traffic to MITM and logs a CRITICAL event.	`True`

Private CA for Cisco UC connections

To trust an internal CA (or the product certificates) for AXL / RIS / CUPI connections, click View / Edit on SERVER_<PRODUCT>_SSL_CA_BUNDLE and paste the PEM certificates. Setting SERVER_<PRODUCT>_SSL_VERIFY to False is for labs only (exposure to MITM, CRITICAL event logged).

SOAP (Zeep)¶

Key	Description	Default
`SERVER_CUCM_ZEEP_TIMEOUT`	Zeep SOAP transport timeout for CUCM AXL/RisPort, in seconds.	`30`

Rate limiting¶

Global caps per CUCM node, all clients combined (see Rate limiting).

Key	Description	Default
`RATELIMIT_GLOBAL_CUCM_AXL`	Global cap (all clients combined) for CUCM AXL calls per destination host.	`500`
`RATELIMIT_GLOBAL_CUCM_PHONE`	Global cap for CUCM phone calls (screenshot, web info, message) per CUCM host.	`500`
`RATELIMIT_GLOBAL_CUCM_RIS`	Global cap for CUCM RisPort calls per destination host.	`300`
`RATELIMIT_GLOBAL_CUCM_ROOMOS`	Global cap for RoomOS xAPI calls per CUCM host (all its codecs).	`500`
`RATELIMIT_GLOBAL_CUCM_SSH`	Global cap for CUCM SSH requests per destination host.	`60`

IMP¶

AXL (SOAP)¶

Key	Description	Default
`SERVER_IMP_AXL_PORT`	TCP port of the IM&P AXL SOAP API.	`8443`
`SERVER_IMP_AXL_SCHEMAS_DIR`	Local directory holding IM&P AXL WSDL/XSD schema files.	`./servers-data/imp/axl-schemas/`
`SERVER_IMP_AXL_WSDL_TIMEOUT`	HTTP timeout for downloading the IM&P AXL WSDL, in seconds.	`10`

SSH / CLI¶

Key	Description	Default
`SERVER_IMP_SSH_PORT`	TCP port for IM&P SSH (OS admin CLI), typically 22.	`22`
`SERVER_IMP_SSH_TERM`	Terminal type advertised for IM&P SSH sessions.	`dumb`
`SERVER_IMP_SSH_TERM_HEIGHT`	Pseudo-terminal height (rows) for IM&P SSH sessions.	`50`
`SERVER_IMP_SSH_TERM_WIDTH`	Pseudo-terminal width (columns) for IM&P SSH sessions.	`220`
`SERVER_IMP_SSH_TIMEOUT`	Timeout for IM&P SSH commands, in seconds.	`120`

TLS / certificates¶

Key	Description	Default
`SERVER_IMP_SSL_CA_BUNDLE`	CA trust store used to verify the IM&P certificate (private CA or product certificates).	`./servers-data/imp/certs-trust-store/`
`SERVER_IMP_SSL_VERIFY`	Verify the IM&P TLS certificate. True recommended; False (lab only) exposes traffic to MITM and logs a CRITICAL event.	`True`

SOAP (Zeep)¶

Key	Description	Default
`SERVER_IMP_ZEEP_TIMEOUT`	Zeep SOAP transport timeout for IM&P AXL, in seconds.	`30`

Rate limiting¶

Key	Description	Default
`RATELIMIT_GLOBAL_IMP_AXL`	Global cap for IM&P AXL calls per destination host.	`300`
`RATELIMIT_GLOBAL_IMP_SSH`	Global cap for IM&P SSH requests per destination host.	`60`

CUC¶

CUPI (voicemail)¶

Key	Description	Default
`SERVER_CUC_CUPI_PORT`	TCP port of the CUC CUPI REST API (Unity provisioning).	`8443`
`SERVER_CUC_CUPI_TIMEOUT`	HTTP timeout for CUC CUPI REST calls, in seconds.	`30`

SSH / CLI¶

Key	Description	Default
`SERVER_CUC_SSH_PORT`	TCP port for CUC SSH (OS admin CLI), typically 22.	`22`
`SERVER_CUC_SSH_TERM`	Terminal type advertised for CUC SSH sessions.	`dumb`
`SERVER_CUC_SSH_TERM_HEIGHT`	Pseudo-terminal height (rows) for CUC SSH sessions.	`50`
`SERVER_CUC_SSH_TERM_WIDTH`	Pseudo-terminal width (columns) for CUC SSH sessions.	`220`
`SERVER_CUC_SSH_TIMEOUT`	Timeout for CUC SSH commands, in seconds.	`120`

TLS / certificates¶

Key	Description	Default
`SERVER_CUC_SSL_CA_BUNDLE`	CA trust store used to verify the CUC certificate (private CA or product certificates).	`./servers-data/cuc/certs-trust-store/`
`SERVER_CUC_SSL_VERIFY`	Verify the CUC TLS certificate. True recommended; False for lab/dev only.	`True`

Rate limiting¶

Key	Description	Default
`RATELIMIT_GLOBAL_CUC_CUPI`	Global cap for CUC CUPI calls per destination host.	`300`
`RATELIMIT_GLOBAL_CUC_SSH`	Global cap for CUC SSH requests per destination host.	`60`

Custom Prompts¶

Menu Custom prompts. One tab per licensed product (CUCM, IMP, CUC). Each prompt is a reusable instruction published to the AI agents as an MCP prompt.

Field	Description
Name	Unique identifier: lowercase letters, digits, underscores
Title	Optional display title
Description	Text shown to the MCP clients
Tags	Optional, comma-separated (e.g. `audit, security`)
Prompt body	Instruction text
Enabled	Published or not
Append the common end-of-workflow summary	Adds the shared customer summary at the end of the prompt (see below)

Add a custom prompt, edit, enable / disable or delete a prompt from the list.
Load a custom prompt definition file: import prompts from a .json file (or pasted content) and tick the ones to add; existing prompts are skipped.
End-of-workflow summary: when ticked ("summary": true in the .json file), a common template is appended to the prompt. The AI agent then ends the workflow — success, failure, interruption or nothing to do — with a short customer summary: operation, reference / dates, overall result (✅ / ⚠️ / ❌ / ⏸️ / ➖), key figures, changes, attention points, remaining actions, rollback. A short form (operation, result, changes, rollback) is used for single-object operations. Put the workflow-specific content (what goes in each line, where the summary is placed) in a ## Summary specifics section of the prompt body. A Summary tag marks these prompts in the list.
Changes apply after a restart.
With ADMIN_UI_PROMPTS_EDITOR_ENABLED set to 0 (Admin UI tab), the prompts are read-only.

Administrators¶

Menu Administrators: accounts and access rights of the Admin Web UI. Changes take effect immediately.

Accounts¶

Field	Description
Login	Account name
Password	Subject to the password policy (`ADMIN_UI_PWD_*`)
Profile	Administrator profile (see the Profiles tab)
Locked	A locked account cannot sign in
Change password at next login	Forces a new password at the next sign-in

Add account, edit, lock or delete an account; Reset password sets a temporary password that must be changed at the next login.
You cannot lock or delete your own account, nor remove the last superadmin account.
The first superadmin password is set from the command line at installation (see Getting Started).

Profiles¶

A profile sets an access level for every page of the Web UI: no access, read-only (RO) or read-write (RW).

superadmin is built-in, has RW on every page and cannot be edited.
Add profile creates a new profile; a profile still assigned to an account cannot be deleted.

Clients¶

Menu Clients: MCP clients (AI agents, scripts) and their RBAC profiles. Client changes are staged and apply after Apply & restart.

Accounts¶

Client Fields¶

Field	Rules
Name	Unique identifier, used as `client_id` and as the client directory name. Letters, digits and hyphens.
Subject	JWT `sub` claim. Recommended format: `sub-<name>-YYYYMMDD`.
Profile	Client RBAC profile (see the Profiles tab).
Authentication mode	`jwt`, `oauth2` or `jwt+oauth2`. Shown only when `AUTH_MODE` is `jwt+oauth2`; otherwise the client uses the global mode.

Subject immutability

The subject is embedded in every issued JWT token. Changing it invalidates all the tokens already distributed. Choose it carefully before distributing tokens.

Credentials¶

After the restart that creates a client (or after Reset tokens), a View credentials button shows the connection details once: server URL, client_id, JWT token and/or OAuth client_secret, formatted with the reveal template. Copy them and send them securely to the client.
Reset tokens revokes the current JWT token immediately and generates a new one. OAuth access tokens already issued expire on their own.

Client Lifecycle¶

At every startup, the server synchronizes the client directories with the declared clients:

Condition	Action
New client	Directory created, credentials generated
Existing client, valid token	No action
Existing client, invalid token (expired, bad signature, claims changed)	Token renewed automatically
Deleted client	Directory purged

Automatic purge

Deleting a client and restarting permanently deletes its directory, including its reports and credentials. Export any needed data first.

Profiles¶

A client profile defines which products, operations and commands a client may use, and its per-client rate limits.

Predefined Profiles¶

Profile	Product Scope	AXL Operations	SSH Access	RIS Access	Phone	RoomOS xAPI	CUPI Access (CUC)	Rate Limits (req/min)
`admin`	All	All prefixes + SQL Update	All commands	All device classes	Screenshot, web info, message	Status, Configuration (read/write), all Commands	All verbs (`GET`/`POST`/`PUT`/`DELETE`)	60 / 5 / 20 / 100 / 60 / 60
`operator`	cucm, imp, cuc	get, list + phone write + SQLQuery	`show` only	Phone only	Screenshot, web info, message	Status, Configuration (read), Phonebook, Message, Standby	`GET` + targeted `PUT` (users, callhandlers)	30 / 5 / 20 / 100 / 30 / 30
`auditor`	cucm, imp, cuc	get, list + SQLQuery	`show` + audit utils	All device classes	Screenshot, web info	Status, Configuration (read), Phonebook Search	`GET /vmrest/` only (read-only)	30 / 5 / 20 / 100 / 30 / 30

Rate limit columns

Rate limit columns represent: AXL / SSH / RIS / Phone / RoomOS / Common (report) requests per minute, per client.

CUCM feature service restart (serviceability)

Only admin grants cucm_restart_feature_service (restart prefix). Feature services (Cisco Tftp, Cisco CallManager…) cannot be restarted from the VOS CLI; network / platform services are restarted from the CLI with utils service restart <service> (SSH permission).

RoomOS sensitive operations

Sensitive RoomOS operations (factory reset, software upgrade, option keys, macros, HttpClient, user management, security, provisioning, and the matching set Configuration branches) appear as red tiles in the RoomOS list of every profile. They are blocked by default, even for admin: an operation under a sensitive prefix is allowed only when that prefix (or a finer one) is granted explicitly — tick its tile to allow it.

Default profiles

The predefined profiles are installed at the first startup and are never overwritten afterwards: your changes are kept across upgrades.

Editing a Profile¶

Add profile creates a profile from a template (a predefined profile or an existing one).
In the editor, each permission is a tile: green = allowed, red = denied; click a tile to toggle it. A field below each list adds custom prefixes (comma- or newline-separated). Each service has its own rate limit (requests per minute).
Compare shows the selected profiles side by side.
Saved changes are applied without restart. A profile still assigned to a client cannot be deleted.

Matching Rules¶

Scope	Rule	Example
AXL prefix	Any operation starting with the prefix is allowed	`list` → allows `listPhone`, `listLine`, `listUser`, …
AXL exact	Exact operation name match only	`executeSQLQuery` → allows only that exact call
SSH prefix	Command must equal the prefix or start with `<prefix>` (space-separated)	`show` → allows `show version`, `show interface`, …
RIS filters	Device classes and statuses are optional; if absent, no filter is applied	`Phone` → restricts to phone device registrations
CUPI prefix	Allowed CUPI calls — full `<METHOD> <path>` prefix match (CUC only)	`GET /vmrest/` → allows any GET under `/vmrest/`
RoomOS prefix	xAPI operation `get Status <path>` / `get Configuration <path>` / `set Configuration <path>` / `Command <path>`, matched node by node; sensitive prefixes (factory reset, macros, security…) need an explicit entry	`Command Phonebook` → allows `Command Phonebook Search`, `Command Phonebook Contact Add`, …
Serviceability prefix	CUCM feature service operation `restart <service name>`, case-insensitive, word by word	`restart` → every feature service; `restart Cisco Tftp` → Cisco Tftp only

No SSH section

If a profile grants no SSH permission for a product, SSH access is denied for that product.