Systemd for Lua.

This library is for working with systemd from scripts and daemons written in Lua.

Where necessary, the low level libsystemd functions have been bound in C. Higher level functions with more idiomatic lua semantics are written in Lua on top of these C primitives.

Compatible with Lua 5.1, 5.2 and 5.3 (thanks compat-5.3).

Status

Waiting for API to stabilise before making an initial release.

Todo

• Notify - Notify service manager about start-up completion and other daemon status changes
• ID128 - APIs for processing 128-bit IDs
• Journal
  • Journal Writing
  • Journal Reading
  • Journal Change Notification
• Login
  • PID/Peer Information
  • User State
  • Session Information
  • Seat Information
  • Login Monitoring - Monitor login sessions, seats, users and virtual machines/containers
• Unit Control - Requires use of dbus API

Installation

lua-systemd is on luarocks: https://luarocks.org/modules/daurnimator/systemd

Install via luarocks: luarocks install --server=http://luarocks.org/manifests/daurnimator systemd

Usage

Bound from C

All functions return nil, error_message [, errno] in case of error.

Misc extras

systemd.daemon.notifyt(tbl) and systemd.daemon.pid_notifyt(tbl)

Like notify, but takes a lua table instead of a newline delimited list. Numbers will be coerced to strings.

notifyt { READY = 1, STATUS = "Server now accepting connections", WATCHDOG = 1 }

interval = systemd.daemon.watchdog_enabled()

Returns the watchdog interval (in seconds) if there is one set otherwise returns false.

You should call kick_dog or notify("WATCHDOG=1") every half of this interval.

Similar functionality to sd_watchdog_enabled()

systemd.daemon.kick_dog()

Tells systemd to update the watchdog timestamp. This should be called on an interval.

systemd.journal.LOG

Table containing the syslog(3) priority constants: EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG

Useful as the second argument to systemd.journal.streamfd()

systemd.journal.print(priority, fmt_string, ...)

Same argument signature as C, but written in lua on top of sendv() and string.format()

systemd.journal.sendt(tbl)

Log a message to the journal with the key/value pairs from tbl

systemd.journal.sendt {
	SYSLOG_IDENTIFIER = "identifier" ;
	SYSLOG_FACILITY = "facility" ;
	PRIORITY = systemd.journal.LOG.ERR ;
	MESSAGE = "something happended!" ;
	MY_CUSTOM_FIELD = "extra detail.";
}

value = my_journal:get(field)

Returns the given field from the current journal entry (which may be nil)

Throws a lua error on failure.

my_journal:each_data()

A valid lua iterator that enumerates through field, value pairs.

for field, value in my_journal:each_data() do
	print(field, value)
end

Throws a lua error on failure.

my_journal:each_unique(field_name)

A valid lua iterator that enumerates through unique field values.

-- Print each different `_SYSTEMD_UNIT`
for value in my_journal:each_unique("_SYSTEMD_UNIT") do
	print(value)
end

Throws a lua error on failure.

t = my_journal:to_table()

Converts the current journal entry to a lua table.

Includes Address Fields:

• __CURSOR
• __REALTIME_TIMESTAMP
• __MONOTONIC_TIMESTAMP

text = my_journal:get_catalog()

Looks up the current journal entry's MESSAGE_ID in the message catalog. Substitutes the templated fields (between @ symbols) with values from this journal entry.

Returns:

• the filled out catalogue entry as a string
• false if MESSAGE_ID is not set, or does not exist in the catalogue
• nil, err_msg, errno in case of failure.

Same functionality as sd_journal_get_catalog().

systemd.messages

A table of well-known message ids as id128 objects.

Taken from sd-messages.h