vpsmgr/docs/configuration.md

Configuration

The config file is at /etc/vpsmgr/config.yaml (auto-generated at install, root-only read/write). The VPSMGR_CONFIG env var points the vps binary at another path; the shell install/uninstall scripts always use /etc/vpsmgr/config.yaml.

The installer is intended for a fresh, dedicated host unless existing services, ports, bridges, UFW, and firewall rules have been checked. For a host that must keep other public services and only needs IPv6 inbound access, install with ./install.sh --disable-v4forward; this requires an explicit confirmation, skips vpsmgr's reserved-port check, writes net.v4_forward=false, and leaves HAProxy installed but stopped.

Editing config.yaml by hand is discouraged. The sanctioned interface is vps config list / vps config set / vps config help, which validate every change and refuse immutable fields. A raw YAML edit still works but is not checked — get the rules from vps config help.

Field matrix (kind + how a change applies)

Every field is classified exactly one way — there is no ambiguity about who may change it or when the change takes effect. vps config help prints the same table; vps config list shows the live values with this annotation.

Key	Kind	Change applies	Notes
panel.listen	operator	systemctl restart vps	a FRESH install picks a random free port in 2000-9999
panel.cert	operator	restart panel	TLS certificate path
panel.key	operator	restart panel	TLS private key path
panel.db	operator	re-run vps install	SQLite database path
panel.public_ip	operator	re-run vps install	NIC IPv4 used by firewall/routing; cert is regenerated
panel.display_ip	operator	restart panel	address shown to users (panel URL / SSH hints); any string without spaces (IP or domain), or empty = fall back to public_ip
panel.title	operator	restart panel	name on the login page and in the panel header; empty = VPS Manager
panel.session_days	operator	restart panel	login session lifetime (days)
panel.url_path	fixed at install	—	secret prefix of the user panel; settable only while empty (re-enable)
panel.admin_url_path	operator	restart panel	secret prefix of the admin panel; an empty value disables the admin panel (shown as disabled)
panel.show_footer	operator	restart panel	user panel footer with project link and installed/build version; false hides the entire footer
panel.web_ssh	operator	restart panel	browser terminal in the user panel; default true. When false the Web SSH button is not rendered and the panel refuses the terminal page and connection outright
panel.bandwidth_reset_day	operator	restart panel — discards stored state	day of month the monthly bandwidth quota resets, 1-28 (28 keeps February safe); default 1. Changing it wipes every user's accumulated traffic totals — see below
panel.admin_pass_hash	managed elsewhere	—	bcrypt hash of the admin password; stored in the DB, set via vps admin-passwd / web UI
net.subnet	fixed at install	—	container subnet 10.<n>.0.0/24; changing breaks existing containers
net.gateway	fixed at install	—	bridge gateway (derived from subnet)
net.user_ports	operator	next vps add / reinstall	user-port ranges a new container's 100-port block is drawn from; comma-separated inclusive ranges (e.g. 10000-29999 = 200 containers, or 10000-20000, 25000-30000); auto-aligned to whole hundreds; affects new containers only — existing ones keep their ports
net.v4_forward	runtime policy	applied immediately	true = direct IPv4 SSH/port DNAT; false = IPv4 inbound fully off; web-only = public IPv4 and optional HAProxy 80/443 domains, with direct IPv4 ports off; NAT4 outbound always remains
net.haproxy	runtime toggle	applied immediately	false = stop and disable HAProxy; existing domains are retained, but new domains cannot be added. Renamed from net.traefik — same values; an old key is read and rewritten under the new name
net.ext_if	operator	re-run vps install	external NIC (auto-detected from default route)
net.ipv6_subnet	operator	re-run vps install	global IPv6 prefix for pass-through, e.g. 2602:fada:6::/64; empty = disabled (does not remove IPv6 state already applied, see note below)
net.ipv6_mode	fixed at install	—	IPv6 allocation mode: none / prefix (/112 blocks) / pool (per-container address)
net.ipv6_pool	operator	vps config set needs --apply; admin-panel changes apply immediately	pool-mode address list (bare global addresses or /128); editable via the admin panel's IPv6 Pool page
net.ipv6_extra_prefix	operator	applied immediately (rewires host IPv6 + restarts the panel); admin-panel changes apply immediately too	optional extra prefix (prefix mode alongside /112, or IPv4-only none mode as standalone routed /64) that a container can be given a whole /64 out of, e.g. 2001:1c00:b1b:7f0::/60; empty = feature off (the default, including on every upgrade). Accepted as-is — the /64 this host itself uses is never handed out
net.ipv6_pin_gateway	operator	applied immediately (host IPv6 rewired; no panel restart)	pin the host's upstream link-local default gateway as a permanent neighbour, working around a provider router that answers neighbour solicitations unreliably (the host's default route otherwise drops to INCOMPLETE and every container loses IPv6 with it). Off by default: a permanent entry is never re-resolved, so a gateway that moves to another MAC is then missed
incus.image	operator	next vps add / reinstall	container image alias
incus.image_fallback	operator	next vps add / reinstall	fallback remote image
incus.pool	fixed at install	—	storage pool (backend selected at install via VPSMGR_STORAGE=zfs|btrfs|dir)
incus.bridge	fixed at install	—	managed bridge
incus.socket	operator	restart panel	Incus daemon Unix socket
incus.swap_ratio	operator	applied immediately	swap granted to each container as a multiple of its memory limit (limits.memory.swap = limits.memory × ratio); 0 disables container swap. Setting it re-applies the allowance to all existing containers (no restart)
snapshots.limit	operator	restart panel	max checkpoints a user may keep per container (0 = disable new snapshots). Restoring to an older checkpoint auto-deletes the ones created after it (see below)
snapshots.share	operator	applied immediately	allow users to share a checkpoint behind a code and install from it. Off by default; CLI-only: vps config set snapshots.share true. Stored codes survive while it is off

Settings that are NOT in this file

The dynamic CPU limit rule is edited on the admin overview and stored in the DB: it has no config.yaml key and no vps config key, because it is tuned repeatedly and must apply immediately. Saving applies it on the spot (turning it off restores every capped container), and vps install never resets it.

How "fixed at install" is enforced

Fields marked fixed at install (net.subnet, net.gateway, incus.pool, incus.bridge, panel.url_path, net.ipv6_mode) are snapshotted into the DB settings table on the first vps install. Every later vps install and vps serve compares the live config against that snapshot and refuses to run if any of them drifted — vps config set also refuses them up front. The user panel path (panel.url_path) is immutable on purpose: moving it strands every user who bookmarked it. The admin path is NOT immutable — it can be rotated and emptied to disable the admin panel.

Managed files

Files generated by the panel carry a Managed by vpsmgr — generated, do not edit by hand banner and are overwritten on the next write:

File	Written by
/etc/vpsmgr/nftables.conf	vps install
/etc/vpsmgr/nftables.d/user-<name>.nft	vps add / quota / firewall updates
/etc/haproxy/haproxy.cfg	install (from configs/haproxy/haproxy.cfg); static entry config, never rewritten by the panel
/etc/haproxy/releases/<gen>/{domains.cfg,maps/*.map,manifest}	domain add/update/delete (a new immutable generation)
/etc/haproxy/current	domain add/update/delete (symlink to the generation in service)
/etc/ndppd.conf	IPv6 pass-through updates
/etc/sysctl.d/99-vpsmgr.conf	vps install
systemd units (vps/vps-nft/vps-ipv6, haproxy)	vps install

Example

panel:
  listen: ":5231"              # panel listen address — a FRESH install picks a random free port in 2000-9999
  cert: /etc/vpsmgr/panel.crt  # HTTPS certificate
  key: /etc/vpsmgr/panel.key   # private key
  db: /etc/vpsmgr/vpsmgr.db    # SQLite database
  public_ip: AUTO              # NIC IPv4 used by the firewall / routing; on NAT-ing clouds (AWS/Alibaba) this is a private address
  display_ip: AUTO             # address shown to users (panel URL, SSH hints); any string without spaces (IP or domain); auto-fetched from ipv4.ip.sb when public_ip is private; empty = fall back to public_ip
  session_days: 3              # login session lifetime (days)
  bandwidth_reset_day: 1       # day of month the monthly bandwidth quota resets (1-28).
                               # CHANGING IT WIPES every user's accumulated traffic totals.
                               # `vps config set` asks for confirmation.
  url_path: AUTO               # random secret path, the only panel entrance; do not change after first install
  admin_url_path: AUTO         # random secret path of the admin panel; do not change after first install
  admin_pass_hash: AUTO        # bcrypt hash of the admin password — stored in the DB, not in this file

net:
  subnet: "10.115.0.0/24"      # container subnet 10.<n>.0.0/24 — only the second octet is settable, at install
  gateway: "10.115.0.1"
  v4_forward: true             # true = direct IPv4 SSH/ports; false = fully off; web-only = 80/443 domains only
  haproxy: true                # domain reverse proxy (false = stopped and not enabled at boot);
                               # renamed from `traefik` — a pre-rename key is adopted as-is
  ext_if: AUTO                 # external NIC, auto-detected from the default route
  ipv6_mode: ""                # IPv6 allocation mode: none / prefix / pool (fixed at install)
  ipv6_subnet: ""              # optional: global prefix for IPv6 pass-through, e.g. "2602:fada:6::/64"
                               # (/64 or shorter uses the first /64; provider /80 slices like
                               # "2406:da14:1dd2:a807:753a::/80"); empty = disabled (default),
                               # but does not remove IPv6 state already applied
  ipv6_pool: []                # optional (pool mode): the /128 addresses containers are
                               # assigned from, e.g. "2001:db8:1::9c4" (bare global
                               # addresses, no prefix length)
  ipv6_extra_prefix: ""        # optional: an extra prefix a container can be given
                               # a whole /64 out of, e.g. "2001:1c00:b1b:7f0::/60"
                               # (/48, /56, /60 ...). Works in prefix mode or IPv4-only
                               # (none) mode. Empty = off (the default). The /64 this host
                               # uses itself is never handed out. See docs/ipv6.md
  ipv6_pin_gateway: false      # optional: pin the host's upstream link-local default
                               # gateway as a PERMANENT neighbour, working around a
                               # provider router that answers NDP unreliably. Off by
                               # default — a permanent entry is never re-resolved.
                               # See docs/ipv6.md

incus:
  image: "vpsmgr/debian-sshd"
  image_fallback: "images:debian/13"
  pool: vpsmgr
  bridge: incusbr0
  socket: "/var/lib/incus/unix.socket"   # Incus daemon Unix socket (REST API)
  swap_ratio: 0.5                        # swap per container as a multiple of its
                                         # memory limit (0 = no swap; 0.5 = a 1 GiB
                                         # container may use 512 MiB host swap);
                                         # applied to all containers immediately on set

snapshots:
  limit: 1                                # 0 disables new snapshots
  share: false                            # allow checkpoint share codes (opt-in:
                                          # install from someone's checkpoint)

Port scheme

The port layout per container is fixed at install and not individually tunable, but the span new containers may use follows net.user_ports:

• Panel port: random free port in 2000-9999, chosen on a fresh install and stored in panel.listen. Change it in the config only if you know why.
• SSH port: each container gets one random port in 30000-31999 (TCP, DNAT to container :22). Independent of the user-port ranges. Not reserved at install — each port is probed at vps add time, and a candidate already listened on by another process is skipped for another. Shown as ssh -p <port>.
• User ports: each container owns a whole-hundred block of 100 ports, drawn at create time from the configured net.user_ports ranges, DNAT to the container (TCP and UDP). Displayed compactly as e.g. 107xx.

User-port ranges (net.user_ports)

net.user_ports names the port ranges a new container's 100-port block may be drawn from, e.g. 10000-29999 (full) or 10000-20000, 25000-30000 (leave a gap for the host). Set it at install (00-ip-ask.sh asks right after the subnet octet) or change it later:

vps config set net.user_ports 10000-20000, 25000-30000

Rules:

• Comma-separated inclusive ranges A-B (integers, A <= B). Ends may extend outside 10000-29999 — only the overlap with the usable domain counts, and a fully-outside range contributes nothing.
• Values are auto-aligned to whole hundreds: the low end rounds up to a block start and the high end rounds down to a block end (...99 <= B), so the effective range always ends in ...99, never ...00, and never spills past the requested upper bound. For example 10001-29998 becomes 10100-29899, and 10000-15000 becomes 10000-14999.
• At least one whole 100-port block must remain (the value is rejected otherwise) — a range that cannot host even one container is an error.
• Capacity follows the ranges: 10000-29999 allows 200 containers; 10000-20000, 25000-30000 allows 150; and so on. The interactive prompt echoes the computed capacity for confirmation.
• A narrowed set reserves far fewer host user ports, so an install's port-occupancy check scans only the configured ranges — not the whole 10000-29999. 80/443 is reserved regardless; SSH ports (30000-31999) are not checked at install — each is probed at vps add time and the allocator reassigns on conflict (a live listener on the candidate is skipped).
• It affects new containers only: editing the ranges never renumbers or removes an existing container (one whose block falls outside the current ranges keeps it). The admin panel's capacity readout reflects the ranges.

Legacy: configs written before net.user_ports used net.slot_range (a range of v4 last octets, e.g. 2-201). On upgrade the installer converts it once to the equivalent user_ports value and writes the new key; the old key stays in the file but is ignored and is no longer an editable config key.

IPv4 inbound policy (v4_forward)

net.v4_forward controls the IPv4 inbound policy. It is enabled by default and accepts three values:

• true (default): containers get direct SSH and user-port-block DNAT, and HAProxy domains are available when net.haproxy=true.
• web-only: direct IPv4 SSH/port DNAT is removed, but the public IPv4 remains visible in the user panel and HAProxy can forward domains on host ports 80/443 when net.haproxy=true. Domain add/update/delete remains available. The user panel still shows IPv4 SSH as unsupported.
• false: IPv4 inbound is fully off. HAProxy is stopped (domains are kept but not served), the public IPv4 is hidden, and adding a domain is rejected. Containers still reach IPv4 outbound through the NAT4 masquerade.

Change it at runtime with vps config set net.v4_forward true|false|web-only. Direct DNAT files are refreshed immediately; HAProxy boot autostart follows the effective policy. Stored SSH/user ports remain in SQLite, so changing back to true restores the same allocations.

web-only is a vpsmgr application policy: it removes vpsmgr's per-user direct DNAT while continuing to use HAProxy for 80/443. Kernel IPv4 forwarding, the Incus bridge, NAT4 masquerade, and Docker compatibility rules are unchanged; this setting does not install a host-wide packet allowlist.

Domain proxy (net.haproxy)

net.haproxy independently controls the HAProxy domain reverse proxy. It is enabled by default. Set it with vps config set net.haproxy false to stop HAProxy and disable its boot autostart. Existing domain records and the published configuration are kept, but users cannot add new domains while it is disabled. Re-enabling the setting starts HAProxy, restores autostart, and republishes the configuration from the database.

Upgrading from a Traefik-era install. This key used to be called net.traefik. The values are identical (true = running and enabled at boot, false = stopped and disabled), and the rename is handled automatically:

• a config.yaml carrying traefik: is read as net.haproxy (the new key wins if both are somehow present), and the next save rewrites only the new key;
• the DB runtime mirror (settings.traefik) is moved to settings.haproxy by schema migration v18, keeping the stored value;
• the installer still honors VPSMGR_TRAEFIK as a fallback for VPSMGR_HAPROXY (an older checkout exports the old name);
• install.sh removes the Traefik program, unit and service account and republishes the domains onto HAProxy, keeping only /etc/traefik/traefik.yaml (inert).

There is no rollback to Traefik: HAProxy is the only proxy the panel knows.

Install-time auto-off: if port 80 or 443 is already bound by a non-vpsmgr process during install.sh, the installer does not fail. Instead it proceeds with HAProxy installed but net.haproxy: false (not started, no boot autostart), so a host that already serves 80/443 stays usable. The 00-check.sh port-occupancy scan reports it and installs the proxy disabled; re-enable later with vps config set net.haproxy true.

HAProxy layout and version

The proxy itself is HAProxy 3.4 LTS, installed from the official HAProxy performance packages (haproxy-awslc) for the host's distribution. The panel pins the branch (3.4), not the patch: install.sh and upgrade-haproxy.sh keep the newest patch of that branch, and install.sh --update moves the panel and the proxy together. A branch change is a deliberate migration — update HAPROXY_BRANCH / HAPROXY_REPO_SLUG / HAPROXY_BRANCH_RE in scripts/30-haproxy.sh and upgrade-haproxy.sh, plus cfg.HaproxyBranch, then re-run install.sh.

Path	Written by
/etc/haproxy/haproxy.cfg	install (static entry config; the unit loads it first and current/domains.cfg second)
/etc/haproxy/current	panel — symlink to the generation in service
/etc/haproxy/releases/<gen>/	panel — one immutable generation (three kept)
/etc/haproxy/generation	panel — counter of the last published generation
/etc/systemd/system/haproxy.service	install (overrides the distribution's unit)

Monthly bandwidth reset day (panel.bandwidth_reset_day)

The quota period runs from the configured day of one month to that day of the next (default 1 = calendar months). The user panel shows which reset applies to the period in force, including which month it falls in — with the reset day set to the 22nd and today the 16th, the period ends on the 22nd of this month, because it started on the 22nd of the previous one.

Changing this setting discards every user's accumulated bandwidth totals. The accumulated counters are keyed by an accounting period derived from this day, so moving the day moves the period key, and the next sampler pass sees "a new period" and starts from zero. Any over-quota throttle is lifted as a side effect, and past totals are not recoverable — setting the day back does not bring them back.

This is why the key is classified as destructive: vps config set panel.bandwidth_reset_day <n> asks for an explicit confirmation describing the loss (and repeats it when the change is saved with --no-apply, since then it lands at the next panel restart instead). To reset ONE user's traffic on purpose, use the admin panel's "重置流量统计" button instead — that is the supported, per-user operation.

Port 25 (SMTP) is always blocked

The host nftables ruleset drops port 25 for all forwarded traffic, both directions, TCP and UDP (containers ⇄ internet, container ⇄ container). This is a permanent anti-spam measure: there is no user toggle, and the rule only goes away when the panel is uninstalled.

Field notes

• panel.listen, panel.public_ip, net.ext_if only affect display/on how the panel listens.
• url_path, net.subnet, incus.pool etc. are bound to existing data — do not change them after first install.
• net.ipv6_subnet must be a global (non-ULA) IPv6 CIDR with an explicit prefix length — a bare address is rejected, never silently assumed /64. The validator accepts a global prefix of /80 or shorter; /48../80 are the documented operational range (see ipv6.md).
• net.ipv6_mode is fixed at install and immutable (like net.subnet): none (pure IPv4), prefix (classic /112 blocks), pool (per-container address from net.ipv6_pool). Switching modes would renumber containers.
• net.ipv6_extra_prefix is optional and off by default — an upgraded host keeps running exactly as before until an operator fills it in, and nothing in the installer or the panel prompts for it. It works in prefix mode (alongside the /112) and in none mode (a standalone routed /64), is accepted as the operator enters it (no ownership check: they assert the prefix is theirs), and never renumbers an existing container. Changing it takes effect immediately: host IPv6 plumbing (forwarding, proxy_ndp, NDP rules, block routes) is rewired, the boot unit is refreshed and the panel is restarted so the create form updates. A value that holds no whole /64 (a /64 or longer) simply leaves the feature inert.
• net.ipv6_pin_gateway is optional and off by default. It makes the host's own upstream default gateway — only when that gateway is a link-local address — a permanent neighbour entry, so the kernel stops probing it. That works around providers whose router answers neighbour solicitations unreliably: the host's default nexthop otherwise falls to INCOMPLETE, and every forwarded packet, every container's IPv6 included, is answered with address unreachable until it recovers. It is re-applied by vps ipv6-reapply and vps install, touches only that one gateway, and does nothing while the gateway is unresolved. Turning the key off drops the permanent entry again. The trade-off is why the default is off: a permanent entry is never re-resolved, so a gateway that later moves to a different MAC is not picked up.
• Clearing net.ipv6_subnet (empty) only stops vpsmgr from applying IPv6 on the next vps install; it does not remove IPv6 already in place (bridge address, ndppd, routes). Full IPv6 cleanup happens in uninstall.sh.