A more powerful alternative to sysctl(8) with a terminal user interface
A more powerful alternative to sysctl(8) with a terminal user interface
systeroid — A more powerful alternative to sysctl(8).sysctl(8) is a utility on Unix-like operating systems that is used to read and modify the attributes of the kernel such as its version number, maximum limits, and security settings*. systeroid is "sysctl on steroids". It can do everything that sysctl does and even more. It provides a safer, more performant, and user-friendly CLI/TUI for managing the kernel parameters at runtime.
systeroid is implemented using procfs which is the virtual file system that is typically mapped to a mount point named /proc at boot time. This means checking the value of some kernel parameter requires opening a file in this virtual filesystem, reading its contents, parsing them, and closing the file. In Linux, these dynamically configurable kernel options are available under /proc/sys which contains directories representing the sections of the kernel and readable/writable virtual files. For example, to enable/disable IP forwarding, 1 or 0 could be written in /proc/sys/net/ipv4/ip_forward or systeroid ip_forward=1 command can be used to change the value of the parameter.
Although systeroid does not need the parameter section to be specified explicitly, it is important to know the sections and their areas of impact. Here are the available kernel sections according to the Linux kernel documentation:
| Section | Path | Description |
|---|---|---|
| abi | /proc/sys/abi/ |
execution domains & personalities |
| fs | /proc/sys/fs/ |
filesystem settings |
| kernel | /proc/sys/kernel/ |
global kernel information / miscellaneous settings |
| net | /proc/sys/net/ |
networking settings |
| sunrpc | /proc/sys/sunrpc/ |
SUN Remote Procedure Call settings |
| user | /proc/sys/user/ |
user namespace limits |
| vm | /proc/sys/vm/ |
memory management tuning buffer and cache management settings |
| dev | /proc/sys/dev/ |
device specific information |
| debug | /proc/sys/debug/ |
- |
Rust (>=1.64.0) (see building from source)libxcb (for clipboard support)linux-documentation (for viewing the documentation)To install the runtime dependencies:
pacman -S libxcb libxkbcommon linux-docsapt-get install libx11-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev linux-docdnf install libX11-devel kernel-docsysteroid is available on crates.io:
cargo install systeroid
cargo install systeroid-tui
systeroid can be installed from the community repository using pacman:
pacman -S systeroid
systeroid is available for Alpine Edge. It can be installed via apk after enabling the community repository.
apk add systeroid
See available releases that are automated by Continuous Deployment workflow.
# clone the repository
git clone https://github.com/orhun/systeroid && cd systeroid/
# binaries will be located at:
# - target/release/systeroid
# - target/release/systeroid-tui
CARGO_TARGET_DIR=target cargo build --release
Also see requirements.
Docker builds are automated and images are available in the following registries:
The following command can be used to interactively view the documentation of selected parameters:
docker run --rm -it "orhunp/systeroid:${TAG:-latest}" --tui
Docker containers share the host system's kernel and its settings thus access to /proc and /sys are restricted for security. That is why it is not possible (and not recommended) to tweak the kernel parameters within a container. *
Custom Docker images can be built from the Dockerfile:
docker build -t systeroid .
systeroid [options] [variable[=value] ...] --load[=<file>]
…
Most of the arguments/flags are inherited from sysctl so they have the same functionality.
# list all parameters
systeroid -A
# list parameters in a tree-like format
systeroid -T
# list parameters in JSON format
systeroid -J
To disable colors, set the NO_COLOR environment variable.
# only list parameters in the "kernel" section
systeroid kernel
# only list parameters in the "vm" and "user" sections
systeroid vm user
# print the name and value of a parameter (in "name=value" format)
systeroid kernel.hostname
# print only the value of a parameter
systeroid -n kernel.hostname
# print the name and values of the multiple parameters
systeroid kernel.hostname user.max_user_namespaces
# set the value of a parameter
systeroid kernel.domainname="example.com"
# set the values of multiple parameters and ignore errors
systeroid -e kernel.dmesg_restrict=0 vm.panic_on_oom=1 unknown_param="test"
# set the values of multiple parameters and enforce the "name=value" format
systeroid -w fs.dir-notify-enable=1 net.mptcp.enabled=1 vm.oom_kill_allocating_task
Parameter values can be set from an INI file.
sysctl.conf:
# Use kernel.sysrq = 1 to allow all keys.
# See https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html for a list
# of values and keys.
kernel.sysrq = 16
# Append the PID to the core filename
kernel.core_uses_pid = 1
; Enable hard and soft link protection
; (If a line begins with a single '-', any attempts to set the value that fail will be ignored.)
-fs.protected_hardlinks = 1
fs.protected_symlinks = 1
To load it:
systeroid --load sysctl.conf
If no file is given, values are loaded from /etc/sysctl.conf as default:
systeroid --load
Specifying "-" as file name means reading data from standard input:
systeroid --load -
The list of default system directories are the following:
/etc/sysctl.d/run/sysctl.d/usr/local/lib/sysctl.d/usr/lib/sysctl.d/lib/sysctl.d/etc/sysctl.confUse --system flag to load the files with ".conf" extension in these directories:
systeroid --system
# search parameters using regex patterns
systeroid -r 'net.ipv4.conf.(eth|wlan)0.arp'
systeroid -r '^net.ipv6'
Example output of combining search with listing:
$ systeroid --names --pattern 'kernel.*_max$' --tree
kernel
├── ngroups_max
├── pid_max
└── sched_util_clamp_max
systeroid can dump the parameter information from the kernel documentation. This is useful if you don't know what a parameter is used for.
# show information about a parameter
systeroid --explain oom_dump_tasks
Kernel documentation should be present in one of the following paths for parsing upon first launch:
/usr/share/doc/linux/usr/share/doc/linux-doc/usr/share/doc/linux-docs/usr/share/doc/kernel-doc-*/DocumentationThen the parsed data is cached in $HOME/.cache/systeroid-core and used from there as long as the documentation is not updated. The caching mechanism can be disabled via setting the NO_CACHE environment variable.
This is a design choice due to the fact that different versions of kernels might be installed on different systems so the documentation might be too new or old if systeroid was to be shipped with a fixed set of parameter descriptions bundled in. With the parsing approach, documentation is always kept up-to-date.
However, this
No open issues yet, or sync has not completed.