26 KiB
![](/system/systeroid/media/commit/70818db7503c5ae83772fe6ca9d8d153714d8b11/assets/systeroid-logo.jpg)
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.
![](/system/systeroid/media/commit/70818db7503c5ae83772fe6ca9d8d153714d8b11/assets/systeroid-demo.gif)
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/ |
- |
Table of Contents
Requirements
Rust
(>=1.56.1
) (see building from source)libxcb
(for clipboard support)linux-documentation
(for viewing the documentation)
To install the runtime dependencies:
- on Arch Linux:
pacman -S libxcb libxkbcommon linux-docs
- on Debian/Ubuntu:
apt-get install libx11-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev linux-doc
- on Fedora:
dnf install libX11-devel kernel-doc
Installation
Cargo
systeroid is available on crates.io:
cargo install systeroid
cargo install systeroid-tui
Arch Linux
systeroid can be installed from the community repository using pacman:
pacman -S systeroid
Binary releases
See available releases that are automated by Continuous Deployment workflow.
Building from source
# 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
Images
Docker builds are automated and images are available in the following registries:
Usage
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. *
Building
Custom Docker images can be built from the Dockerfile:
docker build -t systeroid .
Usage
systeroid [options] [variable[=value] ...] --load[=<file>]
Options
-a, --all display all variables (-A,-X)
-T, --tree display the variables in a tree-like format
-J, --json display the variables in JSON format
--deprecated include deprecated variables while listing
-e, --ignore ignore unknown variable errors
-N, --names print only variable names
-n, --values print only variable values
-b, --binary print only variable values without new line
-p, --load read values from file (-f)
-S, --system read values from all system directories
-r, --pattern <expr>
use a regex for matching variable names
-q, --quiet do not print variable after the value is set
-w, --write only enable writing a value to variable
-E, --explain provide a detailed explanation for variable
-D, --docs <path> set the path of the kernel documentation
-P, --no-pager do not pipe output into a pager
-v, --verbose enable verbose logging
--tui show terminal user interface
-c, --config <path> set the path of the configuration file
-h, --help display this help and exit (-d)
-V, --version output version information and exit
Most of the arguments/flags are inherited from sysctl
so they have the same functionality.
Examples
Listing parameters
# 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.
Filtering by section
# only list parameters in the "kernel" section
systeroid kernel
# only list parameters in the "vm" and "user" sections
systeroid vm user
Displaying values
# 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
Setting values
# 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
Loading values from a file
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 -
Loading values from the system directories
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.conf
Use --system
flag to load the files with ".conf" extension in these directories:
systeroid --system
Searching parameters
# 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
Showing information about parameters
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-*/Documentation
Then 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 means you need to:
- either install the kernel documentation package (based on your distribution)
- on Arch Linux:
pacman -S linux-docs
- on Debian/Ubuntu:
apt-get install linux-doc
- on Fedora:
dnf install kernel-doc
- on Arch Linux:
- or explicitly specify the path of the kernel documentation.
# specify the kernel documentation path explicitly
# (not needed if you have the kernel documentation installed as a package)
systeroid -E user.max_user_namespaces --docs /usr/share/doc/linux
To change the default pager (less(1)
), you can use the PAGER
environment variable. Also, you can simply use --no-pager
flag to disable it.
systeroid -E kernel.ctrl-alt-del --no-pager
It is also possible to retrieve information about multiple parameters:
systeroid -E --pattern '.*ipv4.*' --no-pager
TUI
Usage
systeroid-tui [options]
-t, --tick-rate <ms>
set the tick rate of the terminal [default: 250]
-D, --docs <path> set the path of the kernel documentation
--save-path <path>
set the path for saving the changed parameters
-s, --section <section>
set the section to filter
-q, --query <query> set the query to search
--bg-color <color>
set the background color [default: black]
--fg-color <color>
set the foreground color [default: white]
-n, --no-docs do not show the kernel documentation
--deprecated include deprecated variables while listing
-c, --config <path> set the path of the configuration file
-h, --help display this help and exit
-V, --version output version information and exit
Key Bindings
Key | Action |
---|---|
?, f1 | show help |
up/down, k/j, pgup/pgdown | scroll list |
t/b | scroll to top/bottom |
left/right, h/l | scroll documentation |
tab, ` | next/previous section |
: | command |
/ | search |
enter | select / set parameter value |
s | save parameter value |
c | copy to clipboard |
r, f5 | refresh |
esc | cancel / exit |
q, ctrl-c/ctrl-d | exit |
Examples
Launching
Simply run systeroid-tui
to launch the terminal user interface. Alternatively, you can use systeroid --tui
command (which runs systeroid-tui
under the hood if it is found in PATH
).
Showing help
Help menu and key bindings can be shown via pressing ?:
Scrolling
Use up/down keys to scroll the parameter list. Alternatively, use t/b to scroll to the top/bottom.
Use left/right to scroll the parameter documentation.
Toggling the kernel section
Press tab or ` to toggle the kernel section for filtering entries in the parameter list.
Order of the sections is all
-abi
-fs
-kernel
-net
-sunrpc
-user
-vm
.
--section
argument can be used to start systeroid-tui with the specified section for filtering.
systeroid-tui --section kernel
Searching
Press / and type in your query to search for parameters.
Alternatively, you can start systeroid-tui with a pre-defined search query by using --query
argument.
systeroid-tui --query "fs.quota"
Setting values
Press enter to select a parameter and set its value via command prompt.
You can press r to refresh the values in the parameter list.
Saving values
Press s to set a parameter value via command prompt and save its value to a file specified via --save-path
.
Default save path is /etc/sysctl.conf
and the values can be loaded via systeroid --load
.
$ systeroid-tui --save-path /etc/sysctl.d/custom.conf
$ systeroid --system
Running commands
Press : to open the command prompt for running a command. Available commands are:
Command | Description |
---|---|
:help |
Show help |
:search |
Enable search |
:select |
Select the current parameter in the list |
:set <name> <value> |
Set parameter value |
:save <name> <value> |
Save parameter value to file |
:scroll [area] [direction] <amount> |
Scroll the list or text - areas: list , docs , section - directions: up , down , top , bottom , right , left |
:copy |
Copy to clipboard |
:refresh |
Refresh values |
:quit , :q |
Quit |
Copying to clipboard
Press c to show the options menu for copying the name, value, or documentation of the selected parameter.
* systeroid-tui should be built with clipboard
feature for enabling the clipboard support.
Changing the colors
Use --bg-color
and --fg-color
arguments to customize the colors of the terminal user interface.
# use a color name for setting the foreground color
systeroid-tui --fg-color blue
# use hexadecimal values for setting foreground/background colors
systeroid-tui --bg-color ffff99 --fg-color 003366
Viewing the parameter documentation
To view the documentation as parameters are being selected on the list, kernel documentation should be parsed as explained in the "Showing information about parameters" section. A specific path for kernel documentation can be given via --docs
argument or KERNEL_DOCS
environment variable if it is not found in one of the locations that are checked as default.
To disable this feature altogether, use --no-docs
flag.
Setting the refresh rate
It is possible to specify a value in milliseconds via --tick-rate
argument for tweaking the refresh rate of the terminal which might be necessary in some cases where better performance is desired.
systeroid-tui --tick-rate 500
Configuration
systeroid can be configured with a configuration file that uses the INI format. It can be specified via --config
or SYSTEROID_CONFIG
environment variable. It can also be placed in one of the following global locations:
$HOME/.config/systeroid/systeroid.conf
$HOME/.systeroid/systeroid.conf
# set the config path via argument
systeroid --config config/systeroid.conf
# set the config path via env
SYSTEROID_CONFIG=config/systeroid.conf systeroid
# use a global path
mkdir -p "$HOME/.config/systeroid"
cp config/systeroid.conf "$HOME/.config/systeroid"
systeroid
See the example systeroid.conf for the configuration options.
Resources
References
Logo
systeroid logo was originally painted by Ryan Tippery as a part of the Compositions art collection and it is put together by me using the Filled Spots font. Shout out to Ryan for letting me use his painting for the logo! <3 Kudos!
Social Links
Funding
If you find systeroid and/or other projects on my GitHub profile useful, consider supporting me on GitHub Sponsors or becoming a patron!
Contributing
See our Contribution Guide and please follow the Code of Conduct in all your interactions with the project.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache 2.0 License, shall be dual licensed as above, without any additional terms or conditions.
License
Licensed under either of Apache License Version 2.0 or The MIT License at your option.
Copyright
Copyright © 2022-2023, Orhun Parmaksız