Configuration
vpsAdminOS uses Nix configuration language. It reuses a number of NixOS modules
for system configuration and also adds some of its own. Explore os/modules/
to see its capabilities.
Default and example configs are included in os/configs/ directory.
make qemuusesqemu.nixmake iso-imageusesiso.nix
The simplest way to start with vpsAdminOS is to clone its repository and
put your configuration in os/configs/local.nix, which you can base on
os/configs/local.nix.sample. local.nix is imported with make qemu automatically
if it exists.
Another option is to put path to your config to environment variable
VPSADMINOS_CONFIG, e.g.:
export VPSADMINOS_CONFIG=/where/is/your/config.nix
make qemu
Kernel runtime parameters (sysctl)
Declare kernel runtime settings with boot.kernel.sysctl:
boot.kernel.sysctl = {
"vm.swappiness" = 60;
};
The settings are written to /etc/sysctl.d/60-nixos.conf. Boot stage 1 applies
sysctl files after loading kernel modules and before setting up networking.
The sysctl runit service applies them again when the default or rescue
runlevel starts. This second application is intentional. Single and custom
runlevels do not include this service automatically.
On a live configuration switch or test, the service runs when managed
sysctl files change. Its inputs include enabled environment.etc entries whose
effective target is sysctl.conf or a direct sysctl.d/*.conf file, including
the generated 60-nixos.conf. Content changes, additions, removals and target
renames trigger an application. An otherwise unchanged configuration switch
does not rerun the service, so a manual runtime override remains in place.
Editing an unmanaged file alone does not trigger the service.
The service uses procps sysctl -w --system. Directory priority is
/etc/sysctl.d, /run/sysctl.d, /usr/local/lib/sysctl.d, /usr/lib/sysctl.d,
then /lib/sysctl.d. A file with the same name in a higher-priority directory
replaces the lower-priority copy. Files are applied in filename order, and
/etc/sysctl.conf is read last. The command reads the full system configuration,
including unmanaged files, whenever the service runs. Settings applied later
can override earlier ones.
Each start makes one application attempt. A failure can leave some values
changed; the service does not roll them back or retry automatically. Diagnostics
are in /var/log/sysctl/current. Successful application publishes
/run/service/sysctl/applied for the current managed inputs, which the custom
completion check validates:
/service/sysctl/check
sysctl -n vm.swappiness
A successful switch exit does not prove sysctl application succeeded. The
switcher retains its existing service-error handling, and a newly introduced
service starts asynchronously. sv status and sv check alone are also
insufficient: a completed one-shot service is normally down, and sv check
can skip its custom check in that state. Use the direct completion check after
observing the attempt finish, inspect its logs, and read back relevant values.
The success stamp records an application, not continuous equality with runtime
settings.
Retrying an application
First stop the service and invalidate earlier completion markers:
sv stop sysctl
rm -f /run/service/sysctl/applied /run/service/sysctl/done
tail -n 0 -F /var/log/sysctl/current
Confirm that sv stop succeeded before proceeding. Leave the log follower
running, then start one attempt from another terminal:
sv once sysctl
Observe fresh application output and its success or failure diagnostic. After that attempt finishes, stop following the log and check:
sv status sysctl
/service/sysctl/check
sysctl -n vm.swappiness
An initial down state immediately after sv once can precede execution; it
does not establish completion. Do not reuse an old success marker or infer
latest-attempt success from the start command returning. A failed completed
attempt leaves no valid application stamp. Correct the reported configuration
error before retrying. A retry reads current unmanaged files too.
Whenever the service runs, it reapplies configured values and can overwrite
manual runtime changes. Setting a declaration to null or removing a key/file
does not reset its live value. Removing the service or rolling back to an OS
without it does not apply old values automatically. Check and explicitly
restore required values during a rollback, or boot an appropriate configuration.
The boot action alone only prepares boot configuration; dry-activate reports
planned service actions without applying sysctls.
Declarative containers
It is possible to built the os with images for containers to be imported and
started on boot by osctld. For examples see configs/containers directory.
This functionality is experimental and mostly used for testing.
Explicit configuration and dependencies
Most of the make targets are wrappers for nix build using the repository
flake. The following example demonstrates how to build the os directly
without make.
cd os
nix build --out-link result/qemu ..#qemu
To use a custom configuration, set VPSADMINOS_CONFIG to an absolute path and
build with --impure, e.g.:
cd os
VPSADMINOS_CONFIG=/where/is/your/config.nix nix build --impure --out-link result/qemu ..#qemu