py-freebsd_sysctl

Native Python wrapper for FreeBSD sysctls using libc.

This Python 3 interface for FreeBSD sysctl has no third party dependency and does not require a compile step to install. It is meant for performant (read) access to sysctls, their type, value and description.

>>> from freebsd_sysctl import Sysctl
>>> Sysctl("security.jail.enforce_statfs").value
2
>>> Sysctl("security.jail.enforce_statfs").ctl_type
<class 'freebsd_sysctl.types.INT'>
>>> Sysctl("security.jail.enforce_statfs").description
'Processes in jail cannot see all mounted file systems (deprecated)'

>>> free_count = Sysctl("vm.stats.vm.v_free_count")
>>> free_count.value
180054
>>> free_count.value
180054
>>> b = bytearray(100*1024*1024)
>>> b = None
>>> free_count.value
176879

With either a sysctl name or oid the other properties resolve lazily. Name, OID, type, size and description are memoized, while the value is read from the kernel on each access.

Properties

Read/Write

Property Name	Description
name	String identifier of the sysctl.
oid	List of Integer values identifying the sysctl.

Read-Only

Read Property Name	Description
value	Value of a sysctl. sysctl <name> Each call fetches a new value.
ctl_type	sysctl type class. sysctl -t <name>
description	Text description of the sysctl. sysctl -d <name>

---

This project is heavily inspired by johalun/sysctl-rs. Kudos to @fabianfreyer for untiring support and debugging.

It is developed and maintained by Stefan Grönke (@gronke) and published under BSD 2-Clause License.

Development

Unit Tests

The test suite runs on FreeBSD and compares the library against sysctl(8).

pip install -e ".[test]"
pytest

On other operating systems the suite runs inside a FreeBSD virtual machine. See tests/vm/README.md for the QEMU harness that also drives continuous integration:

tests/vm/run.sh --release 14.4

Static Code Analysis

ruff and mypy verify code style and typing on every change:

ruff check .
mypy freebsd_sysctl

Releases

We try to manually keep a Changelog, following the style on changelog.md. New releases are tagged according to Semver, released on PyPI, and packaged in the FreeBSD ports tree as devel/py-freebsd-sysctl.