Settings in the Web UI

Overview

PatchMon 2.0 moves most day-to-day tuning out of the container's .env and into the Settings area of the web UI. From here you manage users and roles, host groups, agent update cadence, server-level toggles, branding, integrations, and authentication providers. Settings are stored in the database and the server re-reads them on every request (with a brief in-memory cache for hot paths), so most changes take effect without restarting the container.

Env vars beat DB values. When the same setting is present both as an environment variable and as a Settings UI value, the environment variable wins. The Environment page shows a yellow ".env" source badge on those variables, marks them Set in .env, and does not let you edit them there, because a database value would be ignored. See PatchMon Environment Variables Reference for the full priority model.

This page is the map of the Settings area: what each page does, which permission unlocks it, and which deeper chapter to read if you need more detail.

How to reach Settings

Click the cog icon in the top navigation bar, or go directly to /settings. You land on whatever your highest-priority settings page is (users, for people with can_view_users; branding, for everyone else with settings permissions).

The left sidebar groups settings into four sections:

1. User Management: users, roles, your own profile, and social/SSO authentication
2. Hosts Management: host groups and agent update behaviour
3. Integrations: API integrations (auto-enrolment tokens) and AI Terminal
4. Server: server URL, environment variables, branding, server version, and metrics

Some items only appear depending on your deployment or your edition. For example, Server URL and Metrics are only shown on the self-hosted version, and features like Roles (custom RBAC), Branding, and AI Terminal are gated by the corresponding capability modules on paid tiers.

Settings Pages: Quick Reference

Notifications, alert channels, alert settings, and patch management policies live outside the Settings area in 2.0, see Where alerts and patch policies live below.

User Management

Users

Path: /settings/users

Central directory of all PatchMon accounts. From here you can:

• Create new users (local username/password or OIDC-matched)
• Assign a role (superadmin, admin, host_manager, user, readonly, or any custom role you've created)
• Reset a user's password (admin-initiated reset, not self-serve)
• Enable, disable, or delete an account
• See when each user last logged in

Users also get a one-click button to create an auto-enrolment-style API token scoped to themselves, useful for integrations that need to act on behalf of a specific human operator.

Roles

Path: /settings/roles Requires: rbac_custom module (Plus tier)

The Roles editor is where custom roles are authored. A role is a named bundle of permission flags:

• can_view_dashboard, can_view_hosts, can_view_users, can_view_packages, can_view_reports, can_view_notification_logs
• can_manage_hosts, can_manage_users, can_manage_settings, can_manage_alerts, can_manage_notifications, can_manage_compliance, can_manage_patching, can_manage_automation, can_manage_docker
• can_use_remote_access (SSH terminal and RDP)

The superadmin, admin and user roles cannot be edited. The other two built-in roles, host_manager and readonly, can be edited like custom roles but cannot be deleted. The editor lets you create and edit additional roles alongside them and assign users to them, within the limits described under role escalation protection below.

My Profile

Path: /settings/profile

Your own account settings. Every authenticated user has access. Covers:

• First name, last name, email
• Password change (rate-limited; by default 5 attempts per 15-minute window)
• Two-Factor Authentication: enable or disable TOTP, regenerate backup codes
• Trusted Devices: list and revoke "remember this device" exemptions from MFA challenges
• Dashboard preferences: light/dark mode, card layout, default landing tab

Password policy rules are live: you cannot save a password that fails the server's policy. Spaces at the start or end of a password are ignored, both when it is set and when you sign in, and the policy is checked on the password without them. See PatchMon Environment Variables Reference: Password Policy.

Discord Auth

Path: /settings/discord-auth

Configure a Discord application as a sign-in provider. Each user can link their Discord identity from their profile page; once linked, they can sign in via the Discord button on the login page instead of typing a password.

Discord Auth is intentionally less feature-rich than OIDC SSO. There is no group-to-role mapping, no enforced-SSO mode, and no user auto-provisioning. Use it for communities and small teams; use OIDC SSO for everything else.

When Disable local auth is on in OIDC / SSO, Discord sign-in is turned off as well, so SSO is the only way in. The Discord button is hidden, and Discord logins are refused before any account is created. Users can still link a Discord identity to their profile, but cannot sign in with it until local authentication is enabled again.

OIDC / SSO

Path: /settings/oidc-auth

Full OpenID Connect configuration: issuer URL, client ID and secret, redirect URI, scopes, button text, auto-provisioning, group-to-role mapping, and enforced-SSO toggle. A dedicated Import from environment button pulls existing OIDC_* values from .env into the database so you can migrate from file-based config without retyping anything.

The toggles at the top of the page that control password sign-in:

• Disable local auth: once SSO is fully configured, the login page shows only the SSO button and the server refuses password sign-in and self-service signup.
• Superadmin password login if SSO is down: only matters while Disable local auth is on. Off by default. When on, superadmins who have two-factor authentication set up can sign in with their PatchMon password while your identity provider cannot be reached (a network failure, or the provider returning a server error). Nobody else can. Each such sign-in raises a sso_fallback_login event. Changing this setting needs the Manage Superusers permission. Anyone who can cut PatchMon off from your provider and holds a superadmin's password and second factor can get in this way, so only enable it if that risk is acceptable. See Password Login When the SSO Provider Is Unreachable in the operator guide.

For a step-by-step walk-through (Authentik, Keycloak, Entra ID, Okta), see Setting up OIDC SSO.

Hosts Management

Host Groups

Path: /settings/host-groups

Groups are the primary way to organise hosts for patching policies, alert routing, and dashboard filtering. Each host can belong to many groups; groups are purely organisational (no hierarchy, no nesting) and are referenced by name from policies, scheduled reports, and notification routes.

Agent Updates

Path: /settings/agent-config

Controls how and when PatchMon agents talk to the server and update themselves:

• Update interval: how often agents perform a check-in (default: 60 minutes); hosts with the WebSocket channel open pick up interval changes live. From v2.0.3 each tick is a hash-gated check-in: the agent ships content hashes per section, and the server only requests full content for sections whose hash has changed. Steady-state cycles are a few KB instead of a few MB.
• Auto-update behaviour: global on/off for automatic agent binary updates. Per-host overrides live on the host detail page.
• Disable apt download retries: on by default. On apt-based hosts (Debian, Ubuntu and derivatives) running agent 2.1.8 or later, PatchMon patch runs call apt-get upgrade and apt-get --only-upgrade install with -o Acquire::Retries=0, so apt does not retry a failed or redirected download. This protects patch runs against CVE-2026-109518; you still need to update apt itself. Turn it off only if your mirrors are unreliable: with retries off, a transient download failure fails the patch run instead of being retried. Connected agents receive a change straight away and every agent picks up the current value when it starts, replacing any per-host apt.disable_retries in config.yml. apt-get update, dry runs and manual or unattended-upgrades runs are not affected. The compliance scanner install always runs with retries off, whatever this setting says. On Univention Corporate Server, Patch all runs univention-upgrade, which this setting does not cover; patching selected packages is covered.
• Signup enabled: whether the first-time setup wizard still serves the initial-admin endpoint.

Agent Version

Path: /settings/agent-version

Inspect the bundled agent binary versions (one per OS/architecture), check for newer releases upstream, and force a fresh download of the bundled binaries. Useful after you upgrade the server. Agents pick up the new binaries via the auto-update flow. No manual distribution required.

From agent 2.1.4, each host's page also shows a Config Version next to the agent version. An upgraded agent updates its config.yml to the new release when it restarts, so the two match once the host has reported after the upgrade. See Host Info.

See Managing the PatchMon Agent for how agents consume this information.

Integrations

API integrations

Path: /settings/integrations

Auto-enrolment tokens and per-integration API credentials:

• Auto-enrolment tokens: one-shot or long-lived tokens that let enrolment scripts register new hosts without a human in the loop. Each token can be scoped to specific host groups and flagged for integrations like Proxmox LXC or getHomepage.
• Integration-type tokens: the scoped token model used by the integration /api/* routes, including gethomepage for the dashboard widget.

AI Terminal

Path: /settings/ai-terminal Requires: ai module (Max tier)

Configure the AI provider used by the in-browser SSH terminal's assist feature. Supported providers: OpenAI, Anthropic, Google Gemini, OpenRouter. Credentials are encrypted at rest using AI_ENCRYPTION_KEY (see Environment Variables Reference). The page includes a "Test connection" button so you can confirm the key works before saving.

Server

Server URL

Path: /settings/server-url Hidden on: PatchMon Cloud

Three fields (protocol, host, port) that together define the base URL agents use to reach the server. This is the same URL the first-time setup wizard asked you to confirm, persisted in the database so the UI can generate correct install commands for every new host you add.

If you change the URL later, existing agents keep using whatever URL they were installed with; only new agents pick up the change. Rerun the install command on any host you want to retarget.

Environment

Path: /settings/environment Requires: can_manage_settings

New in 2.0: every tunable environment variable that can be safely changed at runtime is listed here with its effective value, source (env / database / default), default, and a one-line description. Editable variables have an Edit button; sensitive or bootstrap-only variables (like DATABASE_URL, JWT_SECRET, REDIS_PASSWORD, AI_ENCRYPTION_KEY, SESSION_SECRET) show Configure via .env and must still be changed in .env.

A variable that would normally be editable but already has a value in .env (or the container environment) shows Set in .env instead of an Edit button. The .env value takes priority, so anything saved here would be ignored. To change it, edit or remove it in .env and restart the server. If the database also holds a value for it, the row says the database value is ignored and a Misconfiguration detected banner appears at the top of the page. The stock Docker env.example sets CORS_ORIGIN, so on a default Docker install that variable is managed in .env.

Variables are grouped by category: Database, Server, Logging, Authentication, Password policy, Server performance, Rate limits, Redis, Encryption, Deployment.

When you save a value, the UI writes it to the database, reloads the table so it shows the value the server resolved, and shows the server's confirmation. Most settings take effect straight away and the confirmation says "Saved. The new value is in effect." Settings that are wired in at startup (CORS_ORIGIN, ENABLE_LOGGING, LOG_LEVEL, ENABLE_HSTS, DB_TRANSACTION_LONG_TIMEOUT) say "Saved. Restart the application for this change to take effect." instead; for those, run docker compose restart server.

Tip: If you've been managing PatchMon from .env files for a long time and want to move configuration into the database, clear a variable from .env first, then change it here. Otherwise the env value keeps winning.

Full reference: PatchMon Environment Variables Reference.

Branding

Path: /settings/branding Requires: custom_branding module (Plus tier)

Upload a custom logo and favicon. The assets are stored in the database and served via GET /api/v1/settings/logos/{type}, so they live through container restarts without a persistent volume. Both dark-mode and light-mode variants can be uploaded separately. The read path is public (so the login page can show your branding before the user authenticates) but upload/reset are gated behind the custom_branding module.

Logos can be PNG, JPEG or SVG, up to 5 MB. SVG files are cleaned on upload: scripts, event handlers, embedded HTML, animation elements, external links and editor metadata (for example Inkscape or Illustrator data) are removed, and an SVG that is not well-formed XML is rejected with "Invalid SVG file". If your logo looks different after uploading, export it again as a plain SVG.

Server Version

Path: /settings/server-version Hidden on: PatchMon Cloud

Shows the running PatchMon server version, the latest upstream version (checked daily by the version-update-check automation job, see Background jobs and automation), and a manual "Check for updates" button. It does not perform the upgrade. To upgrade, PatchMon is a container-image swap (see Installing PatchMon Server on Docker).

Metrics

Path: /settings/metrics Hidden on: PatchMon Cloud

Opt-in anonymous telemetry. PatchMon sends a small heartbeat (server version, number of hosts, rough OS distribution) to the upstream metrics endpoint once a day. You can turn this off, regenerate your anonymous instance ID, or send a one-off payload immediately. See Metrics and telemetry for exactly what is sent.

Where Alerts and Patch Policies Live

In 1.4.x these lived inside Settings. In 2.0 they've moved to more natural homes:

• Alerts (Open alerts, History): /reporting → Alerts tab
• Alert Lifecycle /reporting → Alert Lifecycle tab (retention, auto-resolve, cleanup jobs) → Alert Lifecycle tab (requires alerts_advanced module, Plus tier)
• Destinations (SMTP, webhook, ntfy): /reporting → Destinations tab
• Event Rules (routing alerts to destinations): /reporting → Event Rules tab
• Delivery Log: /reporting → Delivery Log tab
• Scheduled Reports: /reporting → Scheduled Reports tab
• Patch Policies (scheduling, approval rules, exclusions): /patching?tab=policies

The Settings sidebar doesn't list them because the pages where you actually use them (Reporting and Patching) are the right home for them. The permissions are unchanged: can_manage_notifications, can_manage_alerts, can_manage_patching still control who sees each area.

Troubleshooting

"I changed a setting but nothing happened"

Check the Environment page for the variable you changed. If its row says Set in .env, the value comes from .env or the container spec and overrides the database, which is why the page does not let you edit it. Change it in .env, or remove it from .env and restart the server so the database value takes over.

"I saved a setting and the UI says 'Restart to take effect'"

Some settings (startup-only values like PORT, DATABASE_URL, pool sizes) are read once at boot and cached for the life of the process. Restart the server container:

docker compose restart server

Most Environment page settings (rate limits, password policy, lockout and session timeouts, body limits) are re-resolved on every request and don't require a restart. The confirmation shown after saving tells you which case you are in.

"Branding / AI Terminal / Roles is greyed out"

These are paid-tier features. Self-hosted users on the free tier see them in the sidebar but can't click through; clicking redirects to an upgrade page. If you're on a paid tier and still see them as locked, click Settings → My Profile → Subscription to confirm the module is listed under your enabled modules.

See Also

• First-time admin setup
• PatchMon Environment Variables Reference
• Managing the PatchMon Agent
• Setting up OIDC SSO
• Background jobs and automation