Expand description
§kcheck
A library for checking system configurations.
§Motivation
When writing low-level software applications there can be contraints placed on a developer based on system configuration options. These options could be kernel configuration or runtime sysctl settings.
Full desktop kernel distributions will often come with a ton of settings already ready to go. However, minimal config systems such as custom embedded Linux kernels or some server configs may not have a required feature enabled.
In these unknown system configurations, it would be helpful to both developers and users to know why an application may not be working properly. The goal of this software is to develop a library that is capable of parsing both build time and runtime system configuration information to help determine where a system may be misconfigured.
§Installation
Add kcheck to your Cargo.toml
[dependencies]
kcheck = "0.2"Optionally, install the command line tool.
cargo install kcheck-cli§Features
- Parse Kconfig files and fragments from a build system (does not need to be on the target system) and compare it to a provided configuration file
- Parse a running Linux kernel config (if one exists on the system) and compare it to a provided configuration file
-
Optionally, utilize the
kchecklibrary to develop app defined configuration checks - Parse a desired kernel config from config fragments located in a specific location
-
Parse kernel runtime parameters via
sysctl - Compare a desired configuration to the running Linux kernel config at boot
§Configuration File Format
kcheck configuration files can be written in either JSON or TOML, but TOML files
are probably easier to read. Each config file can contain one or more fragments and each fragment
has a name and a reason. These are mostly to help with printing helpful messages if a configuration
fails. name is required, reason is optional.
After the initial fragment definition, the file can contain kernel configuration fragments which
require a name and a state. The name is the name of the variable as it shows up in the Kconfig
output. The state is an expansion of the Kconfig tri-state system. An application might not care
if the setting is On or a Module, only that it is Enabled. Alternatively, a security conscious
application may want to ensure that no modules have been configured.
[[fragment]]
name = "usb-serial"
reason = "Serial USB support"
[[fragment.kernel]]
name = "CONFIG_USB_ACM"
state = "On"
[[fragment.kernel]]
name = "CONFIG_USB_SERIAL"
state = "Module"§Usage
Once a configuration file is defined, it can then be used as input into kcheck to check against a
system configuration. For example, the kcheck-cli command can be used to check the example serial
configuration fragment against a running kernel:
kcheck-cli -c ./kcheck-serial.toml
+-------------------+---------------+--------------+--------+
| Config Option | Desired State | Kernel State | Result |
+-------------------+---------------+--------------+--------+
| CONFIG_USB_ACM | On | Module | Fail |
+-------------------+---------------+--------------+--------+
| CONFIG_USB_SERIAL | Module | Module | Pass |
+-------------------+---------------+--------------+--------+It can also be used to check a specific non-running kernel config:
kcheck-cli -k /boot/config-5.15.0-143-generic -c ./kcheck-serial.toml
+-------------------+---------------+--------------+--------+
| Config Option | Desired State | Kernel State | Result |
+-------------------+---------------+--------------+--------+
| CONFIG_USB_ACM | On | Module | Fail |
+-------------------+---------------+--------------+--------+
| CONFIG_USB_SERIAL | Module | Module | Pass |
+-------------------+---------------+--------------+--------+See the examples folder for additional examples of how to use the
kcheck library in an application directly.
§License
Licensed under the Mozilla Public License Version 2.0.
Re-exports§
pub use error::KcheckError;pub use error::KcheckResult;
Modules§
Structs§
- Kcheck
- Kcheck
Builder - Build a new
Kcheckinstance. - Kcheck
Config Result