rcpanel 0.3.4
OpenBSD administration in the terminal

rcpanel brings a function-organized system map, service controls, package
management, kernel settings, configuration files, and your usual editor into
one terminal application. It uses Python's standard library and the system's
native tools. There is no web server, remote API, or resident panel daemon.

The system map has 12 top-level categories. It includes 47 fixed read-only
reports and links to services, files, manuals, forms, installed programs, and
package management. The configuration catalog contains 47 default paths.
Broad coverage comes from native documentation and
explicit command review; this release does not provide a custom form for every
program or command-line flag.

PROJECT PRINCIPLES

Our guiding reflection comes from the dua of gratitude: Alhamdulillah, Allah
in His mercy gave us sweet water to drink instead of making it bitter because
of our sins. Purity of purpose should guide development toward software worth
publishing as open source and worth using.

In practice, make useful work understandable, leave the administrator in
control, and care for what already works. That means readable code, honest
native results, visible configuration files, and deliberate changes. When time
is short, reduce the feature list and preserve the quality of what remains.

SECURITY MAINTENANCE

Version 0.3.1 hardens privileged command and editor launch, configuration
approval and validation, repository-plan freshness, hostile catalog parsing,
installation trust, and crash durability. Existing features remain available.
docs/SECURITY-REVIEW.txt records the findings, fixes, threat model, and limits.
Portable tests pass; native OpenBSD acceptance is still pending.

QUICK START

Target system: OpenBSD 7.8. Python 3.10 or newer with curses is required.
Use a terminal of at least 60 columns by 16 rows. Live mode is refused on
other operating systems. The isolated demo and portable tests also run on Linux.

If Python is not installed:

    doas pkg_add python

Choose a Python 3 branch of version 3.10 or newer if pkg_add offers a choice.
Use its installed executable, for example python3.12. Replace python3 below
when necessary; the installed launcher needs no unversioned python3 symlink.

From the extracted source directory:

    python3 ./rcpanel --demo
    python3 ./rcpanel --demo --map network
    python3 ./rcpanel --demo --programs
    python3 ./rcpanel --demo --packages
    python3 ./rcpanel --demo --status

Demo services, package data, kernel values, and reports are simulated. Its
configuration files are temporary and its program inventory is illustrative.
No native administration commands run. Opening $EDITOR still runs your actual
chosen editor on a temporary draft. Demo changes disappear on exit.

INSTALLING

On OpenBSD, using your actual Python executable:

    doas /usr/local/bin/python3.12 ./install.py --prefix /usr/local

The installer records that interpreter and installs:

    /usr/local/sbin/rcpanel
    /usr/local/libexec/rcpanel/0.3.4/
    /usr/local/man/man8/rcpanel.8
    /usr/local/share/doc/rcpanel/

The launcher is replaced after the complete version directory is installed.
It records the actual interpreter used by install.py and uses Python's -I
isolated import mode. The installer writes application code, documentation,
the manual, and the launcher. It does not change service configurations,
enable or start services, reload daemons, or install Python for you.

Launch with the full path:

    /usr/local/sbin/rcpanel
    doas /usr/local/sbin/rcpanel

An ordinary account uses its native permissions; explicitly invoked programs
can perform writes those permissions allow. Service changes, configuration
installation, kernel changes, and package previews and changes require root.
The panel does not alter doas policy or elevate itself.
The installer does not register a native OpenBSD package; retain the Python
interpreter recorded in the launcher when managing installed packages.

UPGRADING AN EXISTING INSTALLATION

Exit running panel instances. Keep the old version directory and your current
service configurations. From the directory containing the new release archive:

    tar -xzf rcpanel-0.3.4.tar.gz
    cd rcpanel-0.3.4

Inspect the first line of your installed launcher to identify its interpreter:

    head -n 1 /usr/local/sbin/rcpanel

For example, #!/usr/local/bin/python3.12 -I means the interpreter is
/usr/local/bin/python3.12. Use the actual installed Python 3.10-or-newer path
shown on your machine; do not assume python3 is an available command. If that
interpreter has been removed, install a supported Python package first and
use its actual executable. The installer prints the interpreter it records.

With the example interpreter and the default existing prefix:

    doas /usr/local/bin/python3.12 ./install.py --prefix /usr/local
    /usr/local/sbin/rcpanel --version

The last command should print rcpanel 0.3.4. If your existing installation uses
a different prefix, use that same prefix and its sbin/rcpanel path throughout.
Do not extract a new release over an old source tree or copy individual
modules into the installed application. Use the new archive's install.py.

The same launcher now selects /usr/local/libexec/rcpanel/0.3.4/. Earlier
version directories, including 0.3.3, are retained; they are not merged or deleted.
The installer leaves service configurations, service state, and panel state
files alone. A normal upgrade from a customized earlier release can therefore
install 0.3.4 beside it without overwriting the older application code.

Reinstalling a version requires every installed Python module to match that
version's source bytes and pass the ownership and permission checks. Identical
code can be reinstalled. If an installed 0.3.4 module was edited, or a different
build also calls itself 0.3.4, installation is refused before the launcher is
replaced. Inspect the difference. For an intentional custom build, give it a
new unique version in rcpanel_lib/__init__.py and run its installer. Do not
delete an active version directory to bypass the comparison. Documentation
can be refreshed by reinstalling when the application modules still match.

TEXT OUTPUT

These mutually exclusive options print information without opening curses:

    --status             Service boot and runtime status.
    --map [QUERY]        Static system map, optionally filtered by search.
    --programs [QUERY]   Installed executable paths, optionally filtered.
    --packages           Installed package names and comments.
    --settings           Saved preferences and the effective user's file path.

Each may be combined with --demo. --version and --help are also available.
Quotes group a multiword QUERY using your invoking shell's ordinary rules.
These text-output modes do not display the interactive startup notice.

STARTUP NOTICE

Every interactive launch displays the project's BLOODGUILT CURSE notice and
credits before opening the panel. An ordinary key continues. A terminal resize
does not dismiss it. Ctrl+C exits; Ctrl+Z suspends the panel, and fg in the
launching shell resumes it. The startup notice cannot be disabled in preferences.

NAVIGATING THE MAP

The categories are System, Services, Network, Security, Storage, Users and
access, Software, Servers, Hardware, Files and schedules, Programs, and
Panel. Selection and scroll position are remembered separately for each menu
during the session when that preference is enabled. The interface uses normal
terminal colors and reverse video for selection; no function keys are required.

    8 / 2                 Move up / down (also arrows or k / j).
    5 / 6                 Open the selection (also Enter or Right).
    4                     Return to the parent (also Escape or Left).
    0                     Return to the top-level map.
    /                     Search the static map from a map menu.
    :                     Enter a static map path, for example 3*1*1#.
    f                     Open Favorites; on an endpoint, toggle its favorite.
    r                     Open Recent pages from a map menu.

The final # in a path is optional. A path only navigates to an entry; it never
executes the entry's action. Endpoint pages explain the action before offering
it. Numeric keys are ordinary text in input fields. In text viewers, Left and
Right scroll long lines horizontally; Escape or 4 returns. Home/End and
Page Up/Down help with long lists. Returning to the map discards an uninstalled
draft. Screen hints distinguish menu controls from field editing.
In viewers, Page Down or Space advances a screen and Page Up goes back.
The status line shows the visible range and marks End when the last row of
output is visible. Use / to find text and n/N for the next/previous search
match. The w key toggles wrapping for the current viewer; the saved wrap
preference supplies the initial mode for a new viewer.

Input prompts wrap their help to the available width and keep the entry field
below it. If help exceeds the terminal height, Page Up/Page Down scroll the
help while preserving the field's text and cursor. Resizing reflows the help.

CANCELLING WORK AND GOING BACK

While Working is displayed, Escape cancels reads, reports, searches, package
downloads/previews, program discovery, and standalone configuration checks.
It returns to the previous screen without waiting for the command's normal
completion or showing its abandoned result. The usual 4/q Back keys also
cancel; 0 cancels and returns to the main map. The panel stops the read's
child and finishes cleanup before returning, preserving staged files and locks.

Back uses the menu snapshot already displayed. Closing service settings,
package details, a kernel value, or a file does not reload the parent list.
Configuration directory browsing retains ancestor listings while descending.
Refresh explicitly reads current data. After a change, old service/package/
kernel snapshots are marked as needing refresh; normal pre-write membership,
permission, and freshness checks still run before another change.

A confirmed service action, package application, configuration installation,
or kernel assignment is protected once applying. Its footer says cancellation
is disabled. These operations finish under their existing controls so Back
cannot interrupt a package script or close a transaction during installation.

PREFERENCES, FAVORITES, AND SAVED COMMANDS

Panel > Panel preferences edits a draft. Save installs and applies the draft;
Back or Discard leaves the saved preferences unchanged. Options include
keyboard hints, remembering menu positions, viewer wrapping, page overlap
(0-10 rows), startup map code, an editor override, an existing absolute native
working directory, and recent-page limit (0-50; zero disables recording).
The startup code opens a page on the next launch and never runs its action.
Menu positions themselves remain session state; the preference controls whether
they are remembered while the panel is open.
Reload saved preferences reads and applies the current file without writing;
if the draft was changed, discarding it requires confirmation. Use Reload after
another panel has changed the saved file instead of overwriting its changes.

Preferences belong to the effective user. Root and ordinary accounts have
separate files, and demo state lives in its temporary directory. The default
directory is .config/rcpanel beneath the effective account's home from the
password database; inherited HOME does not redirect it. Preferences and
favorites use preferences.json, saved commands use commands.json, and the
downloaded list uses available-packages.json. To display the
exact preference path and saved values for an administrative session:

    doas /usr/local/sbin/rcpanel --settings

An invalid preference file is reported and left unchanged while the interactive
panel uses defaults for that session. Ordinary Save does not silently replace
it. Restore and save defaults requires confirmation and clears saved favorites;
it retains saved native commands and the downloaded package catalog.
Action confirmations and the startup notice are always enabled.
Defaults enable hints and remembered positions, disable wrapping, use one row
of page overlap, open map 0, inherit EDITOR, use / as the native directory,
start with no favorites, and retain up to 12 recent pages for the session.

Favorites persist with preferences. Recent pages are bounded session history
and are not saved between launches. Both reopen map pages without executing
their actions. Existing static map codes retain their meanings when new entries
are added.

A native program page can save a named command containing its executable,
arguments, and working directory. Panel > Saved native commands reopens those
choices on the program page. Loading a saved command never launches it: inspect
the arguments and confirm a fresh invocation. The executable must still be
available and pass the normal launch checks. Saved commands are plain private
state, so avoid placing secrets in command-line arguments.

PROGRAMS AND NATIVE MANUALS

System > Manuals contains native OpenBSD documentation. Configuration file
manuals offers references including httpd.conf(5), smtpd.conf(5), pf.conf(5),
sshd_config(5), and rc.conf(8). Administration manuals covers services, kernel
settings, system updates, and packages. The collection also includes man(1),
afterboot(8), hier(7), and the native apropos keyword-search tool.
Manual labels begin with the actual page name and section.

intro(5) is intentionally only a short description of manual section 5.
It is labeled as a brief overview; use the individual file's manual for
configuration syntax and examples. Pages are read from the installed system
with /usr/bin/man -c, which sends the page to the panel's viewer without
starting a separate pager. The -c option does not select a shortened synopsis.

Panel contains the application's own settings, help, credits, and saved pages
and commands. Its former manual codes 12*3, 12*4, and 12*5 still open the same
manuals at their new System locations. Existing saved startup choices and
favorites resolve there on load; the saved file changes only on an explicit
Save. Topic-specific manual shortcuts also remain beside their related tools.

Programs discovers executable files in ten groups:

    /bin                 /sbin                 /usr/bin
    /usr/sbin            /usr/libexec          /usr/games
    /usr/X11R6/bin        /usr/local/bin        /usr/local/sbin
    /usr/local/libexec

Only the two libexec trees are searched recursively, to three levels below
their roots. A scan examines at most 50,000 directory entries and returns at
most 20,000 programs; omissions and access failures are reported. A minimal
installation may have no X11, games, or local-package directory.

A discovered program's identity is its full executable path. Dynamic inventory
entries do not receive invented static map numbers. Open an entry to read its
native synopsis or manual, supply arguments and an absolute working directory,
and review the exact command before running it. Arguments use shell-like
quoting without panel evaluation of pipes, substitutions, or wildcard expansion.
The program then owns the terminal and keeps its native prompts and controls.

This invocation can change the system according to the selected program and
arguments, with the panel's current privileges. It is distinct from the 47
fixed read-only reports. Discovery does not execute programs to probe their
flags, and a missing manual or executable is reported as such.

SERVICES

Services shows independent Boot and Now columns. Enable and disable change
startup configuration; start, stop, restart, and reload affect the current
daemon. Boot-only settings without an rc.d script have no daemon actions.
The panel shows unavailable or failed status queries as unknown. Runtime
classification follows rcctl's own checks; it does not independently diagnose
why an individual service script's check did not report a running daemon.

Actions require confirmation and show their command, exit status, and output.
The panel does not use rcctl -f to force disabled daemons to start. Status and
check queries have time limits. Service changes and rcctl settings have no
panel kill timer; native rc.d scripts and their daemon_timeout govern completion.
A slow or custom script can therefore keep a job open. Output capture remains
bounded. A failed change can leave partial work: refresh actual state before
another action. There is no silent retry or rollback.

If a command exits while a background process retains its output pipe, the
panel ends capture after a short tail drain and reports incomplete output.
It preserves the command's exit status and does not kill that background
process group. Custom service scripts must redirect daemon output; writing to
a capture pipe after it closes can still fail. Standard rc.d output handling
already redirects daemon output when debugging is disabled.

Service pages include rcctl settings and relevant configuration shortcuts.
Catalog paths are defaults. If daemon flags select an alternate file, inspect
those flags and open that file explicitly in an allowed configuration tree.

KERNEL SETTINGS

The kernel browser builds a searchable hierarchy from current sysctl names.
Read a value or explicitly confirm one runtime assignment. Presence in the
list does not mean that a value is writable; native read-only, invalid-value,
and permission failures are displayed without claiming success.

A runtime change does not edit /etc/sysctl.conf. That file has a separate
staged editor for persistent startup settings. Saving it does not apply the
assignments to the running kernel. Choose runtime and persistent changes
separately and review both when persistence is intended.

PACKAGES AND THE DOWNLOADED CATALOG

The package browser lists installed names and comments and shows an installed
package's description, files, dependents, and messages. Download available
packages explicitly obtains the repository's full available-name list from
its directory indexes and saves a local catalog. The catalog shows its source,
download time, and status. Browse and filter the saved not-installed list
without repeatedly querying the repository; Refresh explicitly downloads a
replacement. Installed membership is still checked locally by full package name.

The catalog is a convenience list, not a frozen or signed installation plan.
Names can disappear from a mirror after download. An invalid or incompatible
catalog cannot authorize installation. A download or parsing failure retains
the previous cache and reports the failure. If replacement completes but its
directory cannot be synced, the message identifies that the new file was saved;
inspect its status before another operation. Native fragment search remains
available when you want a current pkg_info query. It accepts a plain
package-name fragment, not URLs, local archives, or options.

Catalog sources come from /etc/installurl and the system's native release and
package architecture. A release combines its normal package index with an
available packages-stable index; beta/current systems use the snapshots index.
Only names are downloaded here, not package archives or full descriptions.

Supported changes are install, update one package, remove, upgrade all, and
remove unused dependencies. Install selects an exact catalog/search result;
remove and update select an exact installed name. Selecting a cached name
still requires a fresh native preview before installation.

Every change first runs a native noninteractive dry run. Review its output and
the exact command, then confirm. Failed or truncated previews cannot be applied.
The plan records installed names/comments and manual-install tags and checks
them again before applying. Search results and repository-dependent plans also
bind to the current /etc/installurl contents. A changed repository configuration
requires a new search or preview. Plans are one-use; changed inventory requires
a new preview. A private advisory lock serializes panel package operations.

A dry run is advisory: it does not freeze the repository or every package DB
record. Native dependency checks and package locking remain authoritative when
other package clients operate. Package tools use the system's /etc/installurl
configuration with a fixed clean environment and working directory /; ambient
PKG_PATH and PKG_DBDIR overrides are not inherited. The panel adds no force or
unsigned-package flags.

Progress is displayed while a package change runs. Package mutations have no
automatic kill timer, so a slow operation is not killed while writing the
package database. Capture remains bounded and truncation is identified. Native
exit status and ordinary package/script output are retained. Failure may leave
partial changes; the panel neither retries nor rolls back automatically.

CONFIGURATION EDITS AND FORMS

The catalog, file browser, and custom path support files below /etc,
/var/unbound/etc, and /var/nsd/etc. Editing opens a private staged copy in
the selected editor. Configuration lists show the real filename first, such as
smtpd.conf - Mail server, with the full path on the file page. Saving in the
editor leaves the live file unchanged. Back in the panel,
review the diff, validate where supported, and explicitly install. Approval is
bound to the displayed candidate's bytes and identity. A changed draft requires
a new review. Validators receive a separate private copy; installation checks
its identity and contents again after validation and backup work. Installation
rechecks the live file, backs it up if present, and atomically replaces that one
file while retaining its ownership and permission bits.

Fourteen catalogued default files have registered native syntax checkers:
httpd, smtpd, ntpd, sshd, pfctl, doas, iked, unwind, relayd, dhcpd, bgpd, ospfd,
unbound-checkconf, and nsd-checkconf. Other files state that no checker is
registered. Checking pf.conf does not load rules. The panel does not execute
rc.conf.local to validate it. Includes and referenced files are outside the
one-file transaction; syntax acceptance does not prove working runtime behavior.

Installing a file does not issue an automatic service reload, restart, enable,
or start. Its reader determines when the new bytes take effect. In particular,
cron automatically reloads /etc/crontab, so installing it can activate scheduled
commands within a minute. Programs may read doas.conf, hosts, or resolver
settings on their next use. Review the file's effect before confirming.

Writes require regular, single-linked files owned by the invoking user and
trusted parent directories. The panel refuses symbolic links, group/other
writable paths, filesystem flags, invalid UTF-8, NUL bytes, and text over 4 MiB.
Daemon-owned files or directories can therefore be outside the editor's
supported ownership policy even when their paths are catalogued.

The HTTP form describes one server name, listener, port, document root, and
directory-listing toggle. Defaults are 127.0.0.1:8080, /htdocs inside the explicit
/var/www chroot, and listing off. Supply site content separately. The mail form
provides mbox or Maildir delivery for local clients, a lo0 listener, and optional
direct outbound delivery, off by default. Existing aliases and .forward files
still need review. There are no forms for public-mail deployment, IMAP, TLS,
certificates, DNS records, or multiple HTTP virtual hosts.

Forms reopen only files matching their complete generated format. An unfamiliar
or manually changed file opens in the editor, or can be explicitly replaced
from form defaults with a complete diff and typed target-filename confirmation.
No approximate parser silently removes unrelated configuration.

EDITOR AND TERMINAL HANDLING

doas normally builds a new environment. To carry your selection through an
allowed administrative command:

    doas /usr/bin/env EDITOR="$EDITOR" /usr/local/sbin/rcpanel

The saved editor preference takes precedence over EDITOR. Leave that preference
empty to use the environment; an empty EDITOR then uses /usr/bin/vi.
Arguments and quoted paths are accepted without shell evaluation or expansion.
Bare editor names use the panel's fixed system PATH; a custom editor needs an
absolute path. Relative executable paths are refused. When running as root,
the executable and its resolution path must be root-owned and not writable by
other accounts. A user-owned editor must be installed in a trusted location
before it can edit administrative drafts through a root panel.

Editors run from / with a small environment containing the effective account's
HOME/USER/LOGNAME, a checked TERM, and the panel's PATH and C locale. Inherited
startup commands such as EXINIT/VIMINIT, shell hooks, Python/loader overrides,
and arbitrary GUI environment settings are not passed through. The editor
child uses umask 077 for newly created private files. The selected editor is
still trusted code with the panel's privileges and must remain in the foreground
until editing finishes; use its wait option when
needed. A malformed command, launch failure, or nonzero editor exit is reported
without installing the draft.

Ctrl+C exits an ordinary panel menu and works normally in the foreground
editor. Ctrl+Z suspends an idle panel, with terminal restoration on suspend and
resume. During a cancellable read, Ctrl+C cancels and returns like Escape.
SIGHUP and SIGTERM cancel reads and close the panel after cleanup. During an
applying change, Ctrl+C does not interrupt it; SIGHUP and SIGTERM wait for its
completion before closing. Ctrl+Z waits for an active job before suspending.
Service and package changes have no panel deadline. A completed change remains
installed if the terminal disconnects before displaying its result; inspect
current state when reconnecting.
Editors and explicitly launched native programs use ordinary terminal job
control, including suspension of their foreground process group.

BACKUPS AND RECOVERY

Existing files are backed up beside the target in .rcpanel-backups. Directories
are private (0700), backup files are private (0600), and installation reports
the exact path. Backups are not expired automatically. A previously absent
file has no prior contents to back up. To restore, use the target's restore
action and enter its exact backup path; restoration is another reviewed and
validated installation with a fresh backup and the same file-reader effects.

Enable, disable, and flag changes back up an existing rc.conf.local before
rcctl runs. A failed rcctl result is shown without pretending this external
command was an atomic file transaction.

The configuration advisory lock coordinates panel instances, including edits
in the two DNS configuration trees. Other root programs need not honor it.
Observed conflicts stop installation, but another root process can still race
the final replacement. Backups do not snapshot runtime state or included files.
After a crash, private .rcpanel-stage-* directories may need inspection and
cleanup; do not remove one while another panel is editing it.

DEVELOPMENT AND NATIVE ACCEPTANCE

    python3 -m unittest discover -s tests -v

Tests use temporary files, simulated backends, and harmless child processes.
They cover transaction failures, argument handling, streaming, package-plan
freshness, forms, and navigation. Native OpenBSD behavior remains unverified
until the supplied docs/OPENBSD-CHECKLIST.txt is completed on a disposable test
machine. Portable test success is not native acceptance.

See docs/DESIGN.txt for boundaries, docs/SYSTEM-MAP.txt for the static map index, and
docs/rcpanel.8 for the command manual. Current test results are supplied in
docs/TEST-RESULTS.txt; the 0.3.1 security pass is in docs/SECURITY-REVIEW.txt.

Primary OpenBSD 7.8 references:

https://man.openbsd.org/OpenBSD-7.8/rcctl.8
https://man.openbsd.org/OpenBSD-7.8/sysctl.8
https://man.openbsd.org/OpenBSD-7.8/sysctl.conf.5
https://man.openbsd.org/OpenBSD-7.8/pkg_info.1
https://man.openbsd.org/OpenBSD-7.8/pkg_add.1
https://man.openbsd.org/OpenBSD-7.8/pkg_delete.1
https://man.openbsd.org/OpenBSD-7.8/installurl.5
https://man.openbsd.org/OpenBSD-7.8/arch.1
https://man.openbsd.org/OpenBSD-7.8/ftp.1
https://man.openbsd.org/OpenBSD-7.8/httpd.conf.5
https://man.openbsd.org/OpenBSD-7.8/smtpd.conf.5
https://man.openbsd.org/OpenBSD-7.8/cron.8
https://man.openbsd.org/OpenBSD-7.8/crontab.5
https://man.openbsd.org/OpenBSD-7.8/doas.1

Design by remfan1994. Published by ThatIAm.vip.
