lua-sysctl aim provide a simple and complete interface to FreeBSD's sysctl(3) C function for the Lua scripting language. It allow both reading and writing sysctl values (see limitations).

Although the project has been started to display system informations inside the Awesome window manager it has been designed as a general purpose interface, allowing it to be embedded into bigger project, used as library by system administration scripts etc.

Most of the implementation is based on FreeBSD's sysctl(8) command line tool. For more informations about sysctl see:

• http://www.freebsd.org/doc/handbook/configtuning-sysctl.html
• http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=8
• http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=3

• Supported Lua versions: 5.2, 5.3, and 5.4
• Supported FreeBSD versions: 12.x

Note that lua-sysctl might work fine with other version(s), I just don't have the time to test more than what is listed above.

Thanks to garga@FreeBSD and @uzsolt, lua-sysctl is in the FreeBSD ports tree under devel/lua-sysctl.

Thanks to @kraileth, lua-sysctl is in Ravenports.

Example build, usage, and installation with Lua 5.4 (simply replace LUA_VER and lua54 by your Lua version).

Compiling:

% make LUA_VER=5.4
install -m 755 -d build
cc -O2 -pipe -Wall -Wextra -fPIC `pkg-config --cflags lua-5.4` -o build/sysctl.so  -shared -Wl,-soname,lua_sysctl src/lua_sysctl.c

require from the local build/ directory:

% sysctl -Na | LUA_CPATH="${PWD}/build/?.so;;" lua54 ./misc/test-all.lua
…

Installing:

# make LUA_VER=5.4 DESTDIR=/usr/local/lib/lua/5.4 install
install -m 755 -d /usr/local/lib/lua/5.4
install -m 755 build/sysctl.so /usr/local/lib/lua/5.4

Now we can require from the standard Lua path:

% sysctl -Na | lua54 ./misc/test-all.lua
…

Reading:

> sysctl = require('sysctl')
> val, type = sysctl.get('kern.ostype') -- reading a string
> print(val)
FreeBSD
> print(type)
A
> val, type = sysctl.get('kern.maxvnodes') -- reading a integer value
> print(val)
111376
> print(type)
I
> table, type = sysctl.get('vm.vmtotal') -- reading a special type value (which will be a table in Lua)
> print(table)
table: 0x801415800
> print(type)
S,vmtotal
> for k,v in pairs(table) do print(k,v) end
sl  20
rm  81264
avmshr  6884
dw  0
free    1601444
pw  0
armshr  6252
vmshr   22048
rmshr   7204
arm 35104
rq  1
vm  1074232888
avm 420396

Writting:

> sysctl = require('sysctl')
> sysctl.set('security.bsd.see_other_uids', 0)

NOTE: Both sysctl.get() and sysctl.set() raise an error if any problem occur. If you don't control the key you're passing to these function you might want to use protected calls.

Returns two values: The first returned value is the sysctl(3) value, the second value is the format.

From format value to C types:

• I int
• UI unsigned int
• IK int, in (kelv * 10) (used to get temperature)
• L long
• UL unsigned long
• A char *
• S,clockinfo struct clockinfo
• S,loadavg struct loadavg
• S,timeval struct timeval
• S,vmtotal struct vmtotal

In Lua land, it means that:

• I, UI, IK, L, UL, are numbers.
• A is a string.
• S,clockinfo is a table of integers { hz, tick, profhz, stathz }
• S,loadavg is an array of numbers { 1, 2, 3 }
• S,timeval is a table of integers { sec, sec }
• S,vmtotal is a table of integers { rq, dw, pw, sl, vm, avm, rm, arm, vmshr, avmshr, rmshr, armshr, free }

Set the sysctl's key to newval. Return nothing and throw Lua error if any problem occur. Note that some sysctl's key are read only or read only tunable and can not be set at runtime.

Convert a sysctl's IK value into Celsius and return it.

Convert a sysctl's IK value into Fahrenheit and return it.

• Some sysctl variables cannot be changed while the system is running (they're "read-only tunable").
• You need root privilege to change sysctl variables
• Some variables cannot be changed from inside a jail (and might depend of the securelevel too).

Theses limitations are not due to the implementation of lua-sysctl but rather to sysctl(3) and how FreeBSD work. Note that most (if not all) theses limitations are desirables.

• lua-sysctl is unable to handle values for all existing types. More precisely, it can handle about the same subset supported by the sysctl(8) command line utility. It should not be an issue since most sysctl key have "simple" values (i.e. numeric or string).