---
obj: application
repo: https://github.com/orhun/systeroid
rev: 2025-02-07
---

# systeroid
`sysctl` 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.

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](https://www.kernel.org/doc/html/latest/admin-guide/sysctl/index.html):

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


## Usage
```
systeroid [options] [variable[=value] ...] --load[=<file>]
```

### Options
| Option                 | Description                                  |
| ---------------------- | -------------------------------------------- |
| `-a, --all`            | display all variables                        |
| `-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                        |
| `-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       |

Most of the arguments/flags are inherited from `sysctl` so they have the same functionality.

### Examples

#### Listing parameters

```sh
# list all parameters
systeroid -A

# list parameters in a tree-like format
systeroid -T

# list parameters in JSON format
systeroid -J
```

#### Filtering by section

```sh
# only list parameters in the "kernel" section
systeroid kernel

# only list parameters in the "vm" and "user" sections
systeroid vm user
```

#### Displaying values

```sh
# 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

```sh
# 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](https://en.wikipedia.org/wiki/INI_file).

`sysctl.conf`:

```ini
# 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:

```sh
systeroid --load sysctl.conf
```

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

```sh
systeroid --load
```

Specifying "-" as file name means reading data from standard input:

```sh
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:

```sh
systeroid --system
```

#### Searching parameters

```sh
# 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:

```sh
$ 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.

```sh
# 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`
- or explicitly specify the path of the [kernel documentation](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/admin-guide).

```sh
# 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.

```sh
systeroid -E kernel.ctrl-alt-del --no-pager
```

It is also possible to retrieve information about multiple parameters:

```sh
systeroid -E --pattern '.*ipv4.*' --no-pager
```

#### Verbose logging

`--verbose` flag can be used to enable verbose logging:

```sh
systeroid --verbose
```

Also, `RUST_LOG` environment variable can be set accordingly to filter based on different log levels.

```sh
RUST_LOG=trace systeroid
```

## TUI

### Usage

```
systeroid-tui [options]
```

### Key Bindings

| Key                                                        | Action                       |
| ---------------------------------------------------------- | ---------------------------- |
| <kbd>?</kbd>, <kbd>f1</kbd>                                | show help                    |
| <kbd>up/down</kbd>, <kbd>k/j</kbd>, <kbd>pgup/pgdown</kbd> | scroll list                  |
| <kbd>t/b</kbd>                                             | scroll to top/bottom         |
| <kbd>left/right</kbd>, <kbd>h/l</kbd>                      | scroll documentation         |
| <kbd>tab</kbd>, <kbd>`</kbd>                               | next/previous section        |
| <kbd>:</kbd>                                               | command                      |
| <kbd>/</kbd>                                               | search                       |
| <kbd>enter</kbd>                                           | select / set parameter value |
| <kbd>s</kbd>                                               | save parameter value         |
| <kbd>c</kbd>                                               | copy to clipboard            |
| <kbd>ctrl-l</kbd>, <kbd>f2</kbd>                           | show logs                    |
| <kbd>r</kbd>, <kbd>f5</kbd>                                | refresh                      |
| <kbd>esc</kbd>                                             | cancel / exit                |
| <kbd>q</kbd>, <kbd>ctrl-c/ctrl-d</kbd>                     | exit                         |

## Configuration
**systeroid** can be configured with a configuration file that uses the [INI format](https://en.wikipedia.org/wiki/INI_file). 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`

```sh
# 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:

```ini
; systeroid ~ configuration file
; https://github.com/orhun/systeroid
;
; Each line either contains a comment or a command line argument grouped under a section.
; Run "systeroid --help" or "systeroid-tui --help" to get a list of all possible configuration options.

[general]
; display the deprecated parameters such as base_reachable_time and retrans_time while listing
; See https://bugzilla.redhat.com/show_bug.cgi?id=152435
display_deprecated = false
; path of the Linux kernel documentation
; this is distro dependent, systeroid checks the following locations as default:
; - /usr/share/doc/linux/
; - /usr/share/doc/linux-doc/
; - /usr/share/doc/linux-docs/
; - /usr/share/doc/kernel-doc-*/Documentation/
kernel_docs = "/usr/share/doc/linux"

[cli]
; ignore unknown variable errors
ignore_errors = true
; do not print variable after the value is set
quiet = false
; do not pipe output into a pager
; note that the default pager is less(1) and you can change it by using `PAGER` environment variable
no_pager = false
; display type for the parameter, available options are:
; - default: print the parameter name along with its value
; - name: print only the name of the parameter
; - value: print only the value of the parameter
; - binary: print only the value of the parameter without new line
display_type = "default"
; output type for the list, available options are:
; - default: print the output as is
; - tree: print the output in a tree-like format
; - json: print the output in JSON format
output_type = "default"

[cli.colors]
; available colors are defined in https://docs.rs/owo-colors/latest/owo_colors/colored/enum.Color.html
; default color for the symbols
default_color = "bright black"
; section colors
section_abi = "red"
section_fs = "green"
section_kernel = "magenta"
section_net = "blue"
section_sunrpc = "yellow"
section_user = "cyan"
section_vm = "bright red"
section_unknown = "white"

[tui]
; tick rate of the terminal
tick_rate = 250
; disable showing the parameter documentation
no_docs = true
; path for saving the changed kernel parameters
save_path = "/etc/sysctl.conf"
; file to save the logs
;log_file = "systeroid.log"

[tui.colors]
; available colors are defined in https://docs.rs/tui/latest/tui/style/enum.Color.html
; terminal foreground color
fg_color = "white"
; terminal background color
bg_color = "black"
```
