systeroid/README.md

systeroid — A more powerful alternative to sysctl.

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/	-

Table of Contents

• Usage
  • Options
  • Examples
    • Listing parameters
    • Filtering by section
    • Displaying values
    • Setting values
    • Loading values from a file
    • Loading values from the system directories
    • Searching parameters
    • Showing information about parameters
• TUI
  • Usage
  • Key Bindings
  • Examples
• Resources
  • References
  • Logo
  • Social Links
  • Funding
• Contributing
• License
• Copyright

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
-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

To load it:

systeroid --load sysctl.conf

If no file is given, values are loaded from /etc/sysctl.conf as default:

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

Then the parsed data is cached in $HOME/.cache/systeroid-core and used from there as long as the documentation is not updated.

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
• 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

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
-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
-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
/, s	search
enter	select / set parameter value
c	copy to clipboard
r, f5	refresh
esc	cancel / exit
ctrl-c/ctrl-d	exit

Examples

TBA

Resources

References

• sysctl - source code
• sysctl - Wikipedia
• sysctl - ArchWiki

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

Check out his store for a fine piece of similar art. Kudos!

Social Links

• 
• 
  • 
  • 

Funding

If you find systeroid and/or other projects on my GitHub profile useful, consider 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, Orhun Parmaksız