LSL standard library: processes and system administration
os, process, system, luxos, config/configure and sandbox. Basic process
built-ins (run, capture, system()) are in builtins.md.
os — run programs (never a shell)
load os. Programs are started by direct PATH lookup and execve with an argv list – never
/bin/sh -c, so there are no pipes, redirections or expansions, and arguments with spaces,
quotes or special characters are safe. A command is either a String (tokenized without a shell)
or an argv List.
| Function | Description |
|---|---|
os.run(command) |
run, inherit stdio, return the exit status |
os.system(command) |
alias of os.run (also the built-in system(command)) |
os.capture(command) |
return stdout as String (status/stderr via capture_status(), capture_stderr()) |
os.capture_result(command) |
return {stdout, stderr, status, ok} |
os.check(command) |
return stdout; non-zero status raises OSCommandError |
os.run_argv(program, arguments) |
explicit two-argument variant of run |
os.capture_argv(program, arguments) |
explicit two-argument variant of capture (os.capture_argv_clean also exists) |
os.which(name) |
path of an executable in PATH, or None (os.which_trusted(name) searches only trusted system directories) |
os.executable(name) |
checked path to an executable |
Errors: OSCommandError (non-zero status in check), OSError (invalid arguments).
load os
status = os.run("ls -al")
result = os.capture_result(["echo", "hello"])
print result["stdout"].strip(), result["status"], result["ok"] # hello 0 True
if os.which("python3") != None:
print "python3 found"
end
try:
text = os.check(["cat", "missing.txt"])
else:
print "cannot read:", last_error()
end
For a real shell use the optional registry package shell (lsl install shell), which runs
/bin/sh -c explicitly and returns a structured result.
process — structured process API
load process. Status codes as for built-ins (exit code, 128 + signal, 126 fork/wait
failure, 127 exec failure).
| Function | Description |
|---|---|
process.capture_result(program, arguments) |
run, return {stdout, stderr, status, ok} |
process.capture_input_result(program, arguments, input_text) |
same with stdin input |
process.capture_input_stream_result(program, arguments, input_text, callback) |
send stdin, stream stdout to the callback, return the structured result |
process.check(program, arguments) |
return stdout; non-zero status raises ProcessError |
process.check_input(program, arguments, input_text) |
check with stdin input |
process.check_input_stream(program, arguments, input_text, callback) |
check_input that also streams stdout to the callback |
load process
result = process.capture_input_result("/usr/bin/sort", [], "c\na\nb\n")
print result["stdout"]
system — imperative LuxOS/Debian administration
load system. Functions really change the machine and need the corresponding privileges.
Every command is argv, never a shell. Package names are validated against [A-Za-z0-9._+-].
Errors: SystemError (invalid input, missing tool, failed command), PackageError.
| Function | Description |
|---|---|
system.install(package) / update(package) / remove(package) |
detect the package manager (lux, fallback apt) and run the action; return the backend used |
system.refresh() |
refresh package lists (apt update) |
system.detected_lux() / detected_apt() |
path to the tool or None |
system.required_tool(name) |
path to a tool or SystemError |
system.enable_service(name) / disable_service(name) / restart_service(name) |
systemd service control |
system.service_active(name) |
True if the service runs |
system.set_hostname(name) / set_timezone(zone) / set_locale(locale) |
identity ("Europe/Prague", "C.UTF-8") |
system.ensure_group(name) / remove_group(name) |
idempotent group management |
system.ensure_user(name, shell, groups) / remove_user(name) |
idempotent user management |
system.write_file(path, content, mode) |
atomic write with permissions |
system.write_owned_file(path, content, mode, owner, group) |
atomic write with owner |
system.ensure_directory(path, mode) |
create a directory with permissions |
system.remove_file(path) |
delete a file |
system.ensure_mount(device, target, fs, options) / unmount(target) |
mounts |
system.check_system(config_path) / apply_system(config_path) / dry_run_system(config_path) |
run lux check -c / lux apply on a declarative configuration |
system.lux_status() / generations() / rollback(generation) / rollback_dry(generation) |
status, generations and rollback through lux |
system.validate_package(p), validate_name(v, label), validate_account_name(v, label), validate_account_list(vs, label) |
input validation |
Every function also has a _with variant that takes explicit tool paths, e.g.
system.install_with(p, lux, apt), system.enable_service_with(n, systemctl),
system.ensure_user_with(n, shell, groups, id, useradd, usermod),
system.write_file_with(p, content, mode, owner, group, tool),
system.rollback_with(g, dry_run, lux).
On LuxOS: system.install("git") runs lux install git (the LuxOS package manager),
which asks for confirmation and administrator rights like any lux call.
system.update(package) runs lux update PACKAGE, and LuxOS lux update always updates the
whole system (it ignores a package name). The declarative
functions (check_system, apply_system, lux_status, generations, rollback) call
lux check/lux apply/... subcommands from the LSL world; the LuxOS lux package manager
(0.9.x) has no such subcommands, so do not rely on them on LuxOS.
load system
backend = system.install("git") # "lux" or "apt"
call system.enable_service("nginx.service")
call system.ensure_directory("/etc/myapp", "0750")
call system.write_file("/etc/myapp/config", "port=8080\n", "0640")
luxos — declarative system configuration
load luxos. Applies a manifest (hostname, motd, packages, users) to the running system and
records generations for rollback.
| Function | Description |
|---|---|
luxos.defaults() |
{"hostname": "luxos", "locale": "C", "timezone": "UTC", "keymap": "us", "motd": None, "packages": [], "users": []} |
luxos.apply(config) |
validate and apply; with LUXOS_DRY_RUN only print planned changes; returns the list of changes and records a generation |
luxos.apply_manifest() |
apply the manifest from LUXOS_MANIFEST (current config.lconf + configuration) |
luxos.previous_manifest() / luxos.latest_generation() |
manifest of the previous generation / last generation |
luxos.record_generation(config) |
record an evaluated configuration as a new generation |
luxos.validate_config(config) / luxos.field(config, name, fallback) |
validation / field access |
Errors: ValueError for an invalid manifest. This engine belongs to the LSL project; LuxOS
(Arch-based, 0.9.x) does not use it for its own configuration.
config and lsl config
load config declares options for configuration modules evaluated by lsl config ENTRY, which
prints the merged configuration (JSON). Evaluation runs with time and resource limits and is
pure: env and other impure functions are not allowed.
| Function | Description |
|---|---|
config.option(type, default, description) |
option with a type ("Int", "Float", "String", "Bool", "List", "Dictionary", "None", "Any" or unions like "Int\|None"), default and description |
config.required(type, description) |
required option without default |
config.mkOverride(priority, value) |
value with an explicit merge priority |
config.mkDefault(value) |
default value (priority 100, can be overridden) |
config.mkForce(value) |
forced value (priority 1000, overrides everything) |
config.lazy(thunk) |
defer evaluation of a zero-argument function |
config.mkIf(condition, value) |
omit the value when the condition is False (also in lists) |
Lists and dictionaries with the same priority are merged. Errors: ConfigError,
ConfigCycleError. configure.collect(path, seen, active, order) (internal) collects modules
in post-order for the native evaluator generated by lsl-configure.
sandbox — capability isolation
load sandbox; the engine behind lsl sandbox. The program sees an empty tmpfs root, minimal
/proc and /dev, its own read-only executable and only paths bound into /input/N or
/output/N. Network namespaces, a systemd cgroup, prlimit and a timeout are set before start.
Requires the system sandbox tools and a systemd user session (Linux x86-64).
| Function | Description |
|---|---|
sandbox.run(executable, args, policy) |
run in the namespace/cgroup sandbox, return the status (max 4096 args) |
sandbox.command(executable, args, policy) |
build the sandbox argv |
sandbox.available() |
True if the host tools are present |
sandbox.is_active() |
True inside lsl sandbox |
sandbox.profile() |
"strict", "server" or None |
sandbox.input_path(n) / sandbox.output_path(n) |
/input/N / /output/N |
Policy: {"profile": "strict" | "server", "timeout": 1..3600 (default 30), "memory": 64 MiB..8 GiB,
"read": [paths], "write": [paths]}. Errors: SandboxError.
lsl sandbox --profile strict --timeout 10 --memory 268435456 --read data.txt app.lsl
lsl sandbox refuses to compile unsafe source. This is unrelated to the LuxOS system sandbox
(luxos-sandbox, see the LuxOS sandbox page).