arc/hesabixAPI/docs/SERVICE_LOGS_ADMIN_API.md

Service logs admin API (/api/v1/admin/system-services)

The UI path Profile → System settings → Service logs calls these endpoints. They run journalctl and systemctl on the same host as the API process.

When it works

• Linux with systemd.
• journalctl and systemctl are on PATH for the API process.
• Journald on that host actually contains logs for the allowed units (hesabix-api, hesabix-rq-worker, hesabix-notification-moderation).

When it returns 503

• API runs on Windows or macOS (no host journald for those units).
• API runs in a container without access to the host journal.
• journalctl fails (permission, missing unit on that host, etc.). The API may include a short preview under error.details.journalctl_preview for debugging.

Optional sudo fallback for journalctl

If the API user cannot read journald directly, you can allow a tightly-scoped non-interactive sudo fallback.

1. Set:

HESABIX_ALLOW_SUDO_JOURNALCTL=1

2. Add a restricted sudoers rule for the API runtime user (example):

hesabix ALL=(root) NOPASSWD: /usr/bin/journalctl

The API uses sudo -n journalctl ... only when direct journalctl fails with a permission-style error (or when the env is enabled explicitly).

Docker: give the API container host journal access

Mount the host journal socket (preferred on most distros):

services:
  hesabix-api:
    volumes:
      - /run/systemd/journal/socket:/run/systemd/journal/socket

If your distro layout differs, alternatives people use include read-only mounts of journal data paths (e.g. /var/log/journal); keep host and image journald versions compatible and prefer the socket pattern when available.

The user inside the container should be allowed to read the journal (often: add the runtime user to group systemd-journal on the host numeric GID mapped into the container, or run with a user that already has journal access—policy depends on your image).

Restart (POST .../restart)

systemctl restart usually requires elevated privileges. Typical patterns:

• Run the API service on the host under systemd with a sudoers rule allowing only systemctl restart for the allowlisted units, or
• Use a small root sidecar / helper that only exposes restart, or
• Avoid restart from the panel in container-only setups and restart via your orchestrator.

Security

These routes are protected by the system_settings app permission. They can leak operational detail and can disrupt services; restrict who has that permission and harden the host as above.

API logging diagnostics (GET .../logging-diagnostics)

Returns the effective log configuration for the current API worker process (root level, uvicorn.access, SQLAlchemy, etc.) and lists valid LOG_LEVEL names. Changing LOG_LEVEL in the service environment requires a process restart to apply everywhere (especially with multiple Uvicorn workers).

See also

• Worker deployment and moderation service (includes the same REST examples): NOTIFICATION_MODERATION_WORKER_DEPLOYMENT.md
• RQ worker systemd and journalctl usage: PHASE4_BACKGROUND_JOBS.md