Tenodera Documentation

1Overview

Tenodera is a self-hosted Linux server administration panel. It provides a real-time web interface for managing local and remote Linux servers — terminal access, service control, user management, package management, networking, storage, containers, logs, and more.

Browser ──WSS──> Gateway (:9090) <──WS── tenodera-agent (remote host)
                                 <──WS── tenodera-agent (localhost)

Key design principles

• No inbound ports on managed hosts — agents connect outbound to the gateway via WebSocket
• No extra daemon required — the agent is a single binary managed by systemd
• PAM authentication — uses existing system accounts (local, LDAP, SSSD, FreeIPA)
• Role-based access — admin vs. read-only, based on sudo group membership

2Requirements

Panel host

Managed hosts (agent only)

3Installation

3.1 Panel (gateway + UI)

Run on the host that will serve the web interface:

Copycurl -sSfL https://raw.githubusercontent.com/tenodera-io/tenodera/main/tenodera.sh | sudo bash

After install, log in at http://<host>:9090 with any PAM system user.

3.2 Agent (managed hosts)

Run on each host you want to manage:

Copycurl -sSfL https://raw.githubusercontent.com/tenodera-io/tenodera/main/tenodera-agent.sh \
  | sudo bash -s -- --gateway http://<panel-host>:9090

The host enters pending state — approve it in Hosts → Pending.

For unattended installs, generate a bootstrap token in Hosts → Tokens:

Copycurl -sSfL https://raw.githubusercontent.com/tenodera-io/tenodera/main/tenodera-agent.sh \
  | sudo bash -s -- --gateway http://<panel-host>:9090 --token <bootstrap-token>

3.3 Build from source

Copygit clone https://github.com/tenodera-io/tenodera
cd Tenodera
cd panel && sudo make all   # panel host
cd agent && sudo make all   # managed hosts

4Panel Configuration

4.1 Gateway config reference

Edit /etc/tenodera/tenodera.cnf, then restart the service:

# ── Network ──────────────────────────────────────────────
TENODERA_BIND_ADDR=0.0.0.0        # Listen address
TENODERA_BIND_PORT=9090            # Listen port

# ── External URL (reverse proxy / public hostname) ───────
# TENODERA_EXTERNAL_URL=https://panel.example.com

# ── TLS ──────────────────────────────────────────────────
TENODERA_TLS_CERT=/etc/tenodera/tls/cert.pem
TENODERA_TLS_KEY=/etc/tenodera/tls/key.pem
# TENODERA_ALLOW_UNENCRYPTED=1   # dev only!

# ── Security ─────────────────────────────────────────────
TENODERA_IDLE_TIMEOUT=900          # Session idle timeout (seconds)
TENODERA_MAX_STARTUPS=20           # Max failed logins per IP per 5 min

# ── Logging ──────────────────────────────────────────────
RUST_LOG=tenodera_gateway=info

4.2 TLS setup

Self-signed (dev / testing)

cd panel && sudo make tls-selfsigned

Let's Encrypt

Copysudo certbot certonly --standalone -d panel.example.com

# Then in tenodera.cnf:
TENODERA_TLS_CERT=/etc/letsencrypt/live/panel.example.com/fullchain.pem
TENODERA_TLS_KEY=/etc/letsencrypt/live/panel.example.com/privkey.pem

# Restart on renewal:
echo 'systemctl restart tenodera' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/tenodera.sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/tenodera.sh

4.3 Reverse proxy

Set TENODERA_EXTERNAL_URL in tenodera.cnf. nginx example:

location / {
    proxy_pass http://127.0.0.1:9090;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 3600s;
}

5Agent Configuration

Edit /etc/tenodera/agent.cnf on each managed host, then restart the agent:

# Gateway WebSocket endpoint
# http://  → plain WebSocket
# https:// → encrypted WebSocket
TENODERA_GATEWAY_URL=http://<panel-host>:9090

# Bootstrap token — skip pending approval on first connect
# TENODERA_BOOTSTRAP_TOKEN=<token>

# Skip TLS cert verification (self-signed certs only)
# TENODERA_AGENT_ACCEPT_INSECURE=1

# Host roles (grouping label)
# role=web

6Authentication & Access Control

Tenodera uses PAM authentication — the same credentials as the system. No separate user database.

Role is determined at login via sudo -l -U <user>. LDAP/SSSD/FreeIPA users work transparently if PAM is configured for them.

Account presence on managed hosts

Tenodera authenticates you against the panel host — managed hosts are separate machines and may not have your account. The panel checks via getent passwd (NSS-aware: local, SSSD, FreeIPA, LDAP). If your account is absent on a host:

• A warning banner appears at the top of the UI when that host is active
• A no account badge appears on the host card in Management → Enrolled
• Read-only features (Dashboard, Storage, Networking, Logs) still work — the agent collects data independently
• Operations requiring sudo (service restart, package install, firewall changes) will fail
• The Terminal is non-functional — PTY session requires a valid system account

7Multi-Host Management

Each managed host runs tenodera-agent which connects outbound to the gateway. The host selector (top-left) switches context — all pages instantly show data from the selected host.

• Hosts enter pending state on first connect — approve in Hosts → Pending
• Use bootstrap tokens for unattended enrollment — Hosts → Tokens
• Agents reconnect automatically with exponential backoff on disconnect
• Host roles: set in agent.cnf or via the Management UI (no restart required)

8Feature Reference

This section describes every page and sub-tab in the Tenodera UI. Write operations (Admin) require membership in sudo, wheel, admin, or admins group. Many write operations also require entering the superuser password — stored encrypted in browser sessionStorage for the session duration.

8.1 Dashboard

Live overview of the selected host's system state. All metrics streamed over WebSocket — no page refresh needed.

System information panel: hostname, OS (name/version/ID), uptime, boot time, timezone, CPU model, core/thread count, frequency (MHz), architecture, kernel version, CPU temperatures (per sensor, with critical threshold).

Real-time charts — 90-point rolling history:

Disk partitions: device, mount point, filesystem type, total size, used, free, use%.

Network interfaces: name, state (up/down), MAC, speed (Mbps), IPv4/IPv6, RX/TX bytes and packets, error counts.

Top processes: PID, name, CPU%, memory%, user, state — sorted by CPU descending.

8.2 Terminal Admin

Full PTY running in the browser, powered by xterm.js. Visible only to admin users.

• Opens a shell as the authenticated user — agent drops to user's UID/GID (no root shell exposed)
• 10 000-line scrollback buffer
• Font: JetBrains Mono → Fira Code → Cascadia Code → monospace, 14 px
• Auto-copy: selecting text copies to clipboard (requires HTTPS or localhost)
• Auto-resize with browser window (xterm.js FitAddon)
• Connection is a WebSocket channel multiplexed through the gateway — no direct SSH

8.3 Services

Manage systemd units on the selected host.

Services tab

Lists all loaded systemd units with:

Filter by unit name. Sort by Active or State. Color coding: green = active/running, red = failed. Admin actions: Start, Stop, Restart, Enable, Disable.

Timers tab

Lists all systemd timer units: unit name, description, active/sub state, next run, last run, enabled state, triggered unit.

8.4 Users & Groups

Manage system users and groups on the selected host.

Users tab

Lists all users visible through NSS (local /etc/passwd, LDAP, SSSD, FreeIPA):

Admin actions: Lock account, Unlock account, Delete user, Change password.

Groups tab

Lists all NSS groups: group name, GID, member list, system group flag.

Create Account tab Admin

Create a new local user: username, password, full name, home directory, login shell, initial group memberships.

8.5 Packages

Manage software packages. Backend auto-detected: apt (Debian/Ubuntu), dnf (RHEL/Fedora), pacman (Arch).

• Installed tab — lists all installed packages: name, version, repository source; filter by name
• Search tab Admin — search available packages; install from results
• Updates tab Admin — lists available updates; Update all runs full system upgrade; live output streamed to UI
• Repositories tab Admin — view and manage configured repositories; enable/disable repos

8.6 Storage

Monitor block devices and disk I/O on the selected host.

Block device tree — hierarchical lsblk-style tree: device name, size, type (disk/part/lvm/raid), mount points, used/free/use% for mounted devices.

Disk I/O chart — real-time read/write KB/s. Configurable interval: 1 s, 5 s, 10 s, 30 s, 1 min, 5 min, 10 min, 30 min. 90-point rolling history. Interval saved in localStorage.

8.7 Networking

Monitor and manage network configuration.

• Overview tab — real-time traffic charts per interface: RX and TX lines (up to 8 interfaces, color-coded), configurable interval, 90-point rolling history
• Firewall tab Admin — all detected backends (ufw, firewalld, nftables): active state, rules; add/remove rules; supports mixed environments
• Interfaces tab Admin — state, MAC, MTU, flags, IPv4/IPv6; bring interface up/down; VPN connections listed separately
• Logs tab — network-related log entries from the system journal

8.8 Containers

Manage Docker and Podman containers on the selected host.

Containers tab

Lists all containers from both user namespace (rootless) and root namespace:

Sorted: running first, then user before root. Admin: Start, Stop, Remove.

Images tab Admin

Repository, tags, size, creation date, owner. Remove image (fails gracefully if in use).

8.9 Files

File manager: browse, view, edit, create, and delete files.

Access modes

Restriction enforced at the agent level. Symlink targets are resolved (canonicalized) before applying the home-directory restriction.

Features: navigation breadcrumb, path autocomplete (Administrative mode), sorted listing (dirs first), 200-line paginated viewer, inline editor, new file creation, delete with confirmation.

8.10 Logs (Journal)

Query the systemd journal on the selected host.

• Unit filter — filter by unit name (debounced 400 ms)
• Line count — configurable (default: 100)
• Each entry: timestamp, unit name, priority, message text
• Superuser password enables access to protected journal entries

8.11 Log Files

Browse and search plain-text log files in /var/log.

File list: all files in /var/log recursively; filename, path, size, last-modified. Root-owned non-world-readable files require superuser password.

Tail view — last N lines (default: 100, configurable).

Search view — full-text search with Before/After context lines, max results, date/time range. When date/time range is set without a keyword, all lines within the window are returned.

Tenodera audit log

Events: login attempt (username, IP, success/failure), logout (duration), privilege escalation (superuser password activation).

Log rotation (/etc/logrotate.d/tenodera): daily, keep 3, max 1 GB, gzip (delaycompress), copytruncate — no service restart required.

8.12 Cron Jobs

View and manage cron jobs. Sources: /etc/crontab, /etc/cron.d/*, per-user crontabs.

Each entry: source, schedule (raw + human-readable description), user, command, comment.

Admin: click a source to open in editor; save writes back to the file.

8.13 Kernel Dump (kdump)

Monitor kernel crash dump configuration.

Status panel

Crash dumps browser: lists directories (typically /var/crash) with name, type, size, vmcore/dmesg presence, timestamp. Expand to see files. View dmesg inline.

8.14 DNS

Manage DNS configuration.

• Resolver tab Admin — display and edit /etc/resolv.conf: nameservers, search domains
• /etc/hosts tab Admin — display and edit /etc/hosts
• Lookup tab — interactive dig lookup: hostname or IP, query type (A, AAAA, MX, NS, TXT, CNAME, PTR, SOA, SRV)
• systemd-resolved tab Admin — shows systemd-resolved status, configuration, allows service restart

8.15 Certificates

Manage TLS certificates on the selected host.

Certificates tab

Scans common certificate locations:

Admin: Import certificate (paste PEM cert + key; validated before saving); Remove certificate (requires superuser password).

Trust Store tab Admin

List trusted CA certificates; add/remove trusted CAs.

Let's Encrypt tab

Lists Certbot-managed certificates: domain, covered domains, expiry, days remaining, cert and key paths.

Self-Signed tab Admin

Generate a self-signed TLS certificate: Common Name, validity period. Cert and key saved to specified paths.

8.16 Management Admin

Admin-only panel for managing all connected agents. Three tabs: Enrolled, Pending, and Tokens.

Enrolled tab

All hosts that have completed the TOFU handshake:

Badges: local (green) = panel host; active (blue) = currently selected; no account (yellow) = your account absent on this host. Distro name shown in card corner.

Actions: Switch (make active), Role (tag-style input), Restart (sends restart to agent service), Remove (host re-enters pending on next connect).

Pending tab

Agents connected but not yet approved. Refreshes every 5 s. Shows hostname, fingerprint (SHA-256), IP, waiting time. Approve: optionally enter display name; gateway saves key and sends HelloAck. Entries time out after 24 h if not approved.

Tokens tab

Bootstrap tokens for unattended enrollment. Options: TTL (1 h–30 days; default 24 h), single-use, hostname binding, re-enroll (key rotation). After creation, ready-to-use install command generated. Revoke: immediately invalidate a token.

9Service Management

Copy# Panel host
sudo systemctl status tenodera
sudo systemctl restart tenodera
journalctl -u tenodera -f

# Agent (all hosts)
sudo systemctl status tenodera-agent
sudo systemctl restart tenodera-agent
journalctl -u tenodera-agent -f

Installed files

10Health & Monitoring

GET /api/health        # → { status, sessions, uptime_secs, version }
GET /api/health/ready  # → 200 OK | 503 (readiness probe)

GET /api/health

Returns a JSON object:

{
  "status": "ok",
  "sessions": 2,
  "uptime_secs": 3600,
  "version": "0.1.0"
}

GET /api/health/ready

Returns 200 OK when the agent binary exists and is executable, 503 Service Unavailable otherwise. Use as a readiness probe in load balancers or container orchestration (e.g. Kubernetes).

11Architecture

                  [ Browser ]
                       |
                       | HTTPS / WSS  (channel-multiplexed JSON)
                       |
                  [ Gateway ]   Axum HTTP/WS · PAM auth · session management
                 /      |      \
   outbound WS  /       |       \  outbound WS
               /        |        \
        [ Agent ]  [ Agent ]  [ Agent ]   ...
          host-1      host-2     localhost

• Gateway — Rust, Axum 0.8. Serves React UI, authenticates via PAM subprocess, routes WebSocket channels. Starts as root, drops to tenodera-gw user after binding.
• Agent — Rust, Tokio. ~20 MB. 39 operation types. Setuid root, drops to user UID/GID for terminal.
• Protocol — Shared Rust library. JSON messages with type field. Protocol version 2.

Wire protocol

Messages are JSON objects with a type field:

Current protocol version: 2

Project structure

panel/                   Central server (gateway + UI)
  crates/gateway/        Axum HTTP/WS gateway, PAM auth, agent registry
  ui/                    React 19 + TypeScript SPA (Vite 6)
  Makefile               Build & install
  systemd/               tenodera.service

agent/                   Agent binary (deployed to managed hosts)
  src/handlers/          28 handler modules (39 registered handlers)
  Makefile               Build & install
  systemd/               tenodera-agent.service

protocol/                Shared message types (Rust library crate)

packaging/               RPM spec files (tenodera.spec, tenodera-agent.spec)

12Security

See SECURITY.md on GitHub for the full security model.

• PAM auth via isolated tenodera-pam-helper subprocess — gateway never handles PAM directly
• Ed25519 TOFU agent authentication — 32-byte challenge-response; SECURITY ALERT on key mismatch
• TLS required by default; HSTS (max-age=63072000; includeSubDomains)
• WebSocket Origin validation, CSRF protection on all mutating HTTP requests
• Full HTTP security headers: CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
• Gateway injects _user/_role into every channel message — agent never trusts client-supplied identity
• Core dumps disabled; systemd hardening: NoNewPrivileges, PrivateTmp, ProtectSystem=strict
• Audit log: all logins, logouts, privilege escalations → /var/log/tenodera_audit.log

13Docker / Containerization

Tenodera cannot run correctly inside a standard Docker container. This is a fundamental architectural constraint — three independent mechanisms each break when containerized.

Why containerization fails

1. PAM authentication requires the host user database

Tenodera authenticates every login through the Linux PAM stack (/etc/pam.d/tenodera). PAM resolves users against NSS — /etc/passwd, /etc/shadow, and optionally SSSD, FreeIPA, or LDAP via their sockets and shared libraries. Inside a Docker container, PAM sees the container's own minimal user database, not the host's.

Even if you bind-mount /etc/passwd and /etc/shadow from the host, the following issues remain:

• SSSD / FreeIPA / LDAP authenticate via Unix sockets (/var/run/sssd/public/sss_cli) and shared libraries (pam_sss.so, pam_winbind.so). Mounting only the user files is not enough — you also need the live sockets, PAM modules, and matching library versions.
• PAM modules (pam_unix.so, pam_sss.so) are shared libraries linked against specific glibc versions. A container built on a different base image will have the wrong library versions, causing pam_authenticate() to segfault or silently fail.
• /etc/pam.d/tenodera is installed on the host by the Tenodera installer. Inside the container this file does not exist unless explicitly mounted.

2. Setuid root subprocess conflicts with Docker's security model

PAM authentication and PTY user-switching run through tenodera-pam-helper, a binary that must be setuid root. The gateway spawns it as the unprivileged tenodera-gw user. Docker prevents this in two ways:

• User namespace remapping — when Docker remaps UIDs (default in rootless Docker), the setuid bit is ignored because the file is owned by a remapped UID, not real root.
• no-new-privileges — Docker's default seccomp profile and most Kubernetes pod security policies set PR_SET_NO_NEW_PRIVS, which is inherited by all child processes and prevents setuid binaries from gaining elevated privileges.

3. The panel's purpose requires unrestricted host access

Tenodera manages the OS it runs on. Full feature set requires access to:

Granting all of this requires --privileged. A --privileged container has the same kernel access as a root process on the host — container isolation is entirely removed.

Why --privileged is not a solution

Even with --privileged: PAM still sees the wrong user database unless /etc is fully bind-mounted; SSSD / FreeIPA sockets are still unavailable; library version mismatches persist. The result is a --privileged container that is harder to debug, slower to start, and less reliable than the binary running natively — with no isolation benefit.

What Docker can be used for: build environments

Docker is appropriate as a build environment — for CI/CD pipelines, cross-compilation, and release artifacts. The resulting binaries are deployed and run directly on the host, not inside Docker.

FROM rust:1.82-bookworm
RUN apt-get update && apt-get install -y libpam0g-dev nodejs npm
WORKDIR /build
COPY panel/ ./panel/
COPY protocol/ ./protocol/
RUN cd panel && cargo build --release
# docker cp <container>:/build/panel/target/release/tenodera-gateway ./

Recommended production setup

Install directly on the host using the one-line installer. For TLS, either configure the gateway directly (§4.2) or place nginx/Caddy in front of it (§4.3).

Host OS (bare metal or VM)
├── tenodera-gateway    (systemd, drops to tenodera-gw after bind)
├── tenodera-pam-helper (setuid root, spawned by gateway for auth)
├── tenodera-agent      (systemd, connects outbound to gateway)
└── nginx / Caddy       (optional reverse proxy for TLS termination)

14Uninstall

Copy# Panel host (removes everything)
curl -sSfL https://raw.githubusercontent.com/tenodera-io/tenodera/main/tenodera.sh \
  | sudo bash -s -- --uninstall

# Managed hosts (agent only)
curl -sSfL https://raw.githubusercontent.com/tenodera-io/tenodera/main/tenodera-agent.sh \
  | sudo bash -s -- --uninstall

15Troubleshooting

Panel not starting

journalctl -u tenodera -e

• TLS certificate not found — set TENODERA_ALLOW_UNENCRYPTED=1 or run cd panel && sudo make tls-selfsigned
• Port 9090 in use — change TENODERA_BIND_PORT in tenodera.cnf

Agent not connecting to gateway

journalctl -u tenodera-agent -e

• Wrong gateway URL — check TENODERA_GATEWAY_URL in /etc/tenodera/agent.cnf
• Firewall blocking — managed host must reach panel on TCP 9090 (outbound only)
• TLS cert failing — set TENODERA_AGENT_ACCEPT_INSECURE=1 for self-signed certs

Agent not in Hosts → Pending

• Verify TENODERA_GATEWAY_URL
• Bootstrap token invalid or expired — check Hosts → Tokens
• Pending limit reached (max 100)

Agent challenge rejected

Gateway logs show challenge verification failed. The agent's key store at /var/lib/tenodera/ may be corrupted or the key was rotated manually.

Fix: delete the agent's key store and restart:

Copysudo systemctl stop tenodera-agent
sudo rm -rf /var/lib/tenodera/
sudo systemctl start tenodera-agent

Then approve the host again in Hosts → Pending. If previously enrolled, remove it first via Hosts → Enrolled → Remove so the new key is accepted.

Host not appearing in UI

• Check agent is running: sudo systemctl status tenodera-agent
• Check agent logs: journalctl -u tenodera-agent -f
• Look for Hello handshake in the logs — if it's there, the gateway is connected
• Verify TENODERA_GATEWAY_URL points to the correct panel host

Enable debug logging

# In /etc/tenodera/tenodera.cnf:
RUST_LOG=tenodera_gateway=debug
sudo systemctl restart tenodera
journalctl -u tenodera -f

Login fails

• Verify the user exists on the panel host (not the managed host)
• Verify PAM: pamtester tenodera <username> authenticate
• Check audit log: sudo tail -f /var/log/tenodera_audit.log