vpsvip 0.4.0 - small VPS and SSH operation

SCOPE

These notes apply to an OpenBSD guest you administer, including a guest hosted
by an IRCNow community such as NaStYcOdE. IRCNow lists independently operated
servers and identifies NastyCode as a VPS provider [1]. Its VMM instructions
distinguish the provider's host from your guest: normal administration connects
to the guest, while serial-console access goes through the host [2].

Use the guest address, console instructions, and resource allocation supplied
for your account. A shared shell account is not authority to administer the
provider's host. vpsvip's initial native target remains OpenBSD 7.8; demo and
portable tests run elsewhere without invoking native administration tools.

WORK REDUCED SINCE VERSION 0.3.5

1. Single-service status freshly checks rcctl membership, then reads the boot
   state and checks only the selected daemon. It avoids the all-daemon runtime
   probes used by rcctl ls started. Boot-only settings and ordinary-account
   inspection do not issue a daemon check. The whole service list still makes
   an all-service snapshot on entry or explicit Refresh [3].

2. After the kernel browser's inventory, reading a scalar uses one exact
   sysctl name query. It no longer runs sysctl -a before and after that read.
   Only inventoried scalar names are accepted; a bare subtree is a different
   native operation. Assignments still require a fresh membership check [4].

3. A downloaded-package browser entry reads and validates one saved catalog
   for both its status and its names. Filtering and Back stay local. Selecting
   a package still requires a fresh native preview and normal installation
   checks. There is no decoded catalog cache that bypasses later validation.

4. The text viewer keeps original escaped lines. Normal viewing needs no
   per-line row index. Wrapping uses compact offsets, and only visible row
   slices are created. Searches and resize anchors still refer to original
   lines. Large output remains bounded by the command reader; this is not a
   streaming viewer for an arbitrary-size file.

These changes need no preference switch. Idle menus wait for input; they do
not poll services or kernels. Escape cancels reads and completes cleanup before
returning. Confirmed writes retain their protected completion behavior.

A USEFUL SSH SESSION

For an intermittent connection, start or reattach a named tmux session on the
guest, then launch the panel inside it [5]:

    /usr/bin/tmux new-session -A -s vpsvip
    doas /usr/local/sbin/vpsvip

The first command opens the session; enter the second command in its shell.
Use the unprivileged panel when only inspection is needed. With tmux's default
bindings, Ctrl+b followed by d detaches. Reconnect to the same guest/account
and repeat the first command to return to the session. tmux preserves the
session when its SSH client disconnects; it does not turn a partially completed
native change into a transaction. Inspect the result when you reattach [5].

Optional SSH-client settings can detect a dead connection. Add a host-specific
entry on your own client machine, replacing the placeholders [6]:

    Host my-openbsd-vps
        HostName YOUR_GUEST_ADDRESS
        User YOUR_LOGIN
        ServerAliveInterval 30
        ServerAliveCountMax 3

This example sends an encrypted keepalive after 30 seconds without server
data and allows three unanswered probes. It detects a failed connection; it
does not retain the terminal session by itself. Keep this entry specific to
the intended guest. It requires no sshd_config change [6].

FIND THE BOTTLENECK BEFORE CHANGING LIMITS

Useful existing map paths are below. Enter a path with : in a map menu, or
save its endpoint as a Favorite. Opening a path only navigates; choose Run
on a report page when you want a new observation.

    1*2*1#  Process snapshot: native ps aux.
    1*2*2#  Memory and CPU snapshot: native vmstat.
    1*2*4#  Interactive process display: the installed top program.
    5*1*1#  Free space and inodes: native df -hi.
    5*3*1#  Swap usage: native swapctl -lk.
    2*1#    Service browser, including installed package daemons.
    7*1#    Package manager and saved available-package catalog.

For a short series of CPU/memory samples, Programs can find /usr/bin/vmstat.
Set arguments to -w 1 -c 5, review, and run, or enter this directly in a shell:

    /usr/bin/vmstat -w 1 -c 5

The first display covers time since boot. Subsequent displays cover the period
since the preceding display; use those intervals when comparing active load.
This command stops after five displays. It can also be saved as a native
command for later review and invocation [7].

Record the guest's RAM, CPU allocation, workload, disk use, and which process
is consuming resources before choosing a change. Compare under the same IRC,
bouncer, web, or mail workload. Resource limits in login.conf belong to login
classes and sessions [8]; increasing them globally is not a capacity estimate.
Inspect the actual daemon, account, native documentation, and active config
before adjusting a limit. The panel has no measured basis for choosing a
site-specific connection count, buffer size, mail concurrency, or kernel limit.

For startup changes, distinguish Enable/Disable from Start/Stop. Use the
selected service's Refresh to verify its state without probing unrelated
daemons. Keep console access available when deliberately changing remote
access or routing. The provider's host address is not a guessed guest gateway.

LOCAL PERFORMANCE PROBE

tools/benchmark_vps.py uses a simulated terminal and in-memory package catalog.
It does not contact a mirror or run native administration commands. From a
source checkout, run each case in a fresh Linux Python process:

    python3 tools/benchmark_vps.py viewer --kind short
    python3 tools/benchmark_vps.py viewer --kind short --wrap
    python3 tools/benchmark_vps.py viewer --kind ordinary
    python3 tools/benchmark_vps.py viewer --kind long --wrap
    python3 tools/benchmark_vps.py catalog

For an earlier extracted version, pass --source /path/to/rcpanel-0.3.4.
Repeat serially and compare medians. Peak RSS includes the interpreter and
fixture setup; CPU time covers the requested viewer/browser entry. The short
case is deliberately stressful: a 1 MiB report with 524,288 short lines.
It is not a claim about the usual size of a server's status output.

docs/TEST-RESULTS.txt records the local results and test environment. Native
OpenBSD resource use, actual provider hardware, SSH latency, daemon behavior,
and package transactions still require the acceptance work recorded in
docs/OPENBSD-CHECKLIST.txt. Synthetic Linux results are not VPS capacity figures.

UPGRADING

Follow README.txt's UPGRADING AN EXISTING INSTALLATION section using a fresh
0.4.0 extraction, your installed Python interpreter, and the same prefix.
The complete application version must be installed together; do not copy only
the optimized modules over an older installation.

PRIMARY REFERENCES

[1] https://wiki.ircnow.org/index.php?n=Ircnow.Servers
[2] https://wiki.ircnow.org/index.php?n=Vmm.Install
[3] https://man.openbsd.org/OpenBSD-7.8/rcctl.8
    https://man.openbsd.org/OpenBSD-7.8/rc.d.8
[4] https://man.openbsd.org/OpenBSD-7.8/sysctl.8
[5] https://man.openbsd.org/OpenBSD-7.8/tmux.1
[6] https://man.openbsd.org/OpenBSD-7.8/ssh_config.5
[7] https://man.openbsd.org/OpenBSD-7.8/vmstat.8
[8] https://man.openbsd.org/OpenBSD-7.8/login.conf.5
