Administration

Standard Red Notes provides two administration surfaces:

• Settings → Admin in the web client; and
• srn-admin inside the server container.

Both call server-authorized operations. The client hiding a tab is not the security boundary.

flowchart LR
  A[Admin session or srn-admin] --> B[Server authorization]
  B --> C[User and RBAC services]
  B --> D[Persisted runtime settings]
  B --> E[Service control]
  C --> F[Audit trail]
  D --> F
  E --> F

Access model

The built-in administrator role is ADMIN_USER. After a role change, sign out and back in if the current session does not yet carry the new claims. The web console surfaces a specific warning when the client expects admin access but the server returns 403.

Protect admin accounts with MFA, narrow network access, short session lifetime, and independent recovery material. Do not use a daily note-taking account for unattended administration.

Web console tabs

Some controls depend on the deployed server profile. The UI should show a feature as unavailable when the backing endpoint or lifecycle mechanism is not present.

User operations

Start with lookup and effective-state review:

docker compose exec server srn-admin user person@example.test
docker compose exec server srn-admin audit --user person@example.test --limit 50

Administrative states are distinct:

• Ban is an abuse response and can be permanent, temporary, or shadow.
• Suspend is a reversible administrative hold that signs the user out and blocks sign-in.
• Delete permanently removes the user across services.
• Feature flags change one capability without disabling the account.

Use the least disruptive state that meets the requirement.

The CLI requires delete-user <user> --confirm <email> and protects the last administrator unless --force is supplied.

Roles, permissions, and groups

A user’s effective authority is the union of direct roles and roles conferred by groups. Before changing a role:

1. inspect the permission catalog;
2. use the effective-permissions simulator or user lookup;
3. make the smallest direct or group change;
4. refresh the user session if necessary;
5. verify effective permissions again; and
6. inspect the audit event.

Prefer groups for stable job functions and direct roles for exceptional, time-bounded access. Review groups when a person changes responsibility.

Registration

Registration has more than an on/off switch. The server supports:

• a persisted runtime registration gate layered over environment defaults;
• a default role for new users;
• allowed or blocked email-domain policy;
• email-confirmation requirements and sign-in gating;
• invite-only links with role and expiry/use limits;
• an approval queue;
• account caps; and
• a UTC signup window.

Test policy changes with a non-admin account. Keep at least one known-good admin session open until the new registration and sign-in behavior is confirmed.

Feature gates

Privacy-sensitive or resource-intensive features often have two gates:

1. an operator master switch; and
2. a per-user setting.

This applies to server OCR, workflows, scheduled backups, and CalDAV. A visible client setting does not override a disabled server master switch.

Persisted admin overrides can take precedence over environment baselines. The Admin Server tab and srn-admin config, ocr, and workflows commands show effective values and their source. Note whether a change is live, requires a page load, or requires a gateway restart.

The Workflows gates control discovery of a separately authenticated n8n link. They do not provision, disable, or sign a user out of n8n. Manage actual n8n access in n8n; see Workflows with n8n.

Email delivery

Use Settings → Admin → Server → Email delivery to manage outgoing account messages, email backups, and published reminders. The Redis-backed, multi-service deployment supports up to 20 prioritized relay profiles:

• SMTP with STARTTLS, implicit TLS, or a deliberately trusted private insecure relay;
• SendGrid;
• Mailgun’s US or EU API; and
• AWS SES, using explicit credentials or the runtime’s default AWS credential chain.

Lower priority numbers are tried first. Fallback to next enabled relay moves a transient transport or provider failure through the remaining profiles; permanent recipient, policy, suppression, and mailbox rejections always stop. No fallback stops after the selected profile. Each profile also has an independent max messages per window rate limit (max = 0 disables that profile’s limit). Changes are live: the worker re-evaluates the saved configuration and its readiness marker at most five seconds later. An enabled relay must be valid before the queue accepts new mail.

Credentials are write-only. Partial saves preserve an existing credential unless the administrator explicitly replaces or clears it. Relay settings and queued message payloads are encrypted at rest with purpose-specific keys derived from the existing AUTH_SERVER_ENCRYPTION_SERVER_KEY; email delivery needs no additional encryption secret. Do not rotate that server key while jobs remain in the queue. Use this exact order for an intentional rotation:

1. Stop new mail-producing work, drain the ready, leased, and dead queue states, and verify the protected database, redis-data, server-data, uploads, and environment backups as one recovery set.
2. Export the operator-known relay values. Credentials remain write-only and therefore must come from the operator’s secret manager, not the admin API.
3. While the old key is still active, save an empty relay list. Verify that relayConfigurationEncrypted is absent and relayConfigurationManaged is true in the protected server settings file, then wait for the worker readiness marker to expire. The non-secret managed marker prevents legacy environment SMTP from silently reappearing after this explicit disable.
4. Rotate the key, recreate the containers without deleting volumes, restore the relay profiles from the secret manager, and send a test message.
5. Keep the old key and matching settings/Redis backup until queue processing and test delivery both pass with the new key.

Clearing every profile is an explicit disabled state and does not expose legacy environment SMTP. The UI cannot overwrite an envelope that the current key cannot authenticate; simply re-entering credentials after an uncoordinated rotation is not a recovery procedure.

Use Send test after saving. Refresh queue lists ready, leased, and dead jobs; eligible jobs can be retried or discarded. Refresh logs lists bounded attempt metadata and can filter by relay and outcome. The queue and log views never expose a recipient, subject, body, attachment, credential, or raw provider response. Administrative audit records likewise contain only the action, administrator, and outcome. Discarding a currently leased job is refused so that an in-flight delivery cannot be raced from the UI.

The default worker runs every 5 seconds in batches of 25, makes at most 5 delivery attempts for bounded jobs, backs off from 30 seconds to 6 hours, and holds a 2-minute lease that it renews while provider work is in progress. Bounded ready and dead jobs and delivery logs are retained for 30 days; logs are additionally capped at 10,000 entries. Dead-man-switch mail deliberately retries indefinitely and remains queued until it is delivered or an administrator discards it. The encrypted queue accepts at most 25 MiB per job and 64 MiB total by default. These bounds and retention periods are operator-configurable through the documented EMAIL_QUEUE_* and EMAIL_DELIVERY_* environment values.

Published-reminder jobs carry their own queue source. Turning the operator REMINDER_DELIVERY_ENABLED switch off causes those jobs to be terminally settled before any relay or rate-limit call, while the separate auth email-reminder feature remains unaffected. Account opt-out persists a cancellation tombstone for every pending published-reminder job and erases delivered and pending plaintext history plus the stored destination. It refuses an actively leased send; if a provider has already accepted an occurrence, cleanup still completes but the API reports alreadyDispatched: true because accepted mail cannot be recalled. Editing, unpublishing, or changing delivery configuration instead returns a conflict in that state so a replacement cannot create a duplicate.

Changing a queue safety limit preserves the existing encrypted Redis namespace: jobs keep their enqueue-time retry/expiry policy and remain visible. During a rolling change, producers refuse new jobs until the worker readiness marker matches the exact new policy; update auth and gateway together, then confirm readiness. Reducing byte limits can temporarily reject new work until existing jobs bring usage below the new bound.

Redis uses AOF everysec, and every newly accepted job additionally requires a successful local WAITAOF persistence acknowledgement. Deterministic delivery identifiers make a producer retry idempotent while that job exists. Provider delivery is still at least once: if a provider accepted a message but its response was lost or timed out, a later attempt can produce a duplicate. Choose provider-side suppression where available and make security-sensitive email content safe to receive more than once.

The single/home in-memory topology retains the compatible direct SMTP settings and test action, but does not expose the advanced relay, queue, or log surfaces; those endpoints return 501. Redis Cluster also deliberately falls back to legacy direct SMTP because a node-local AOF acknowledgement cannot be proven safely. On the supported Redis-backed topology, 501 means the capability is not wired in that topology; 503 means the advanced service is present but temporarily unavailable.

Service health and lifecycle

The Server tab reports per-service health and response time. Depending on the deployment, it can start, stop, or restart allowlisted services or Compose containers.

The API gateway is special because restarting it interrupts the request that issued the action. Self-interrupting actions require explicit confirmation, and stopping the gateway is forbidden through the control service.

After any lifecycle action:

1. wait for readiness, not merely process startup;
2. verify authentication, sync, files, revisions, and WebSockets;
3. inspect bounded logs; and
4. confirm background workers are processing events.

Runtime log level

The Server tab’s Log level control is live. A persisted logging.level wins over that process’s LOG_LEVEL environment baseline; if neither is valid, the safe baseline is info. Changes are polled and reach all deployed loggers within about 30 seconds without restarting the stack.

In the standard multi-service image this includes the API gateway, auth server and worker, syncing server and worker, files server and worker, and revisions server and worker. The realtime gateway runs inside the API gateway, so it uses the gateway logger. In the all-in-one image one poll updates the named auth, syncing, files, revisions, API gateway, and home-server loggers.

Every process must read the same SERVER_SETTINGS_PATH. The supplied Compose files default that file inside the persistent server-data or single-data volume and the entrypoints propagate the exact path to every package. If you override the path, use an in-container path and mount it persistently yourself. Removing, corrupting, or setting an unknown level in the overlay makes the reader fall back to the environment baseline; it never disables logging or crashes a service.

Security and anti-abuse

IP allow entries bypass rate limits. Use an exact address or the smallest possible CIDR, record the reason and expiry, and remove it when no longer needed. Ensure TRUST_PROXY and any dedicated client-IP header are configured only for a trusted reverse proxy; otherwise audit and rate-limit decisions can use attacker-controlled headers.

Unlocking an account addresses rate-limit lockout. It does not lift a ban or suspension, and it does not reset MFA.

Audit practice

Query audit events after changes to:

• users, roles, groups, and permissions;
• registration and invite policy;
• bans, suspensions, IP lists, and lockouts;
• feature flags, limits, and provider configuration; and
• services and runtime settings.

Changing the Workflows master switch or per-user flag is an SRN administration event. n8n logins, role changes, credentials, and executions belong to n8n’s independent audit and retention controls.

For command details, see Command-Line Tools. For incident procedures, see Monitoring and Troubleshooting.