move stuff about implementing modules/services into Developer manual
This commit is contained in:
Daniel Barlow
@@ -112,7 +112,7 @@ check" command at regular intervals. When the health check fails,
|
||||
indicating that the wrapped service is not working, it is terminated and
|
||||
allowed to restart.
|
||||
|
||||
==== Runtime secrets (external vault)
|
||||
=== Runtime secrets (external vault)
|
||||
|
||||
Secrets (such as wifi passphrases, PPP username/password, SSH keys, etc)
|
||||
that you provide as literal values in `+configuration.nix+` are
|
||||
@@ -221,250 +221,3 @@ directly on the device. (That latter approach may pose a chicken/egg
|
||||
problem if the device needs secrets to boot up and run the services you
|
||||
are relying on in order to login).
|
||||
|
||||
==== Writing services
|
||||
|
||||
For the most part, for common use cases, hopefully the services you need
|
||||
will be defined by modules and you will only have to pass the right
|
||||
parameters to `+build+`.
|
||||
|
||||
Should you need to create a custom service of your own devising, use the
|
||||
[.title-ref]#oneshot# or [.title-ref]#longrun# functions:
|
||||
|
||||
* a "longrun" service is the "normal" service concept: it has a `+run+`
|
||||
action which describes the process to start, and it watches that process
|
||||
to restart it if it exits. The process should not attempt to daemonize
|
||||
or "background" itself, otherwise s6-rc will think it died. Whatever it
|
||||
prints to standard output/standard error will be logged.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
config.services.cowsayd = pkgs.liminix.services.longrun {
|
||||
name = "cowsayd";
|
||||
run = "${pkgs.cowsayd}/bin/cowsayd --port 3001 --breed hereford";
|
||||
# don't start this until the lan interface is ready
|
||||
dependencies = [ config.services.lan ];
|
||||
}
|
||||
----
|
||||
|
||||
* a "oneshot" service doesn't have a process attached. It consists of
|
||||
`+up+` and `+down+` actions which are bits of shell script that are run
|
||||
at the appropriate points in the service lifecycle
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
config.services.greenled = pkgs.liminix.services.oneshot {
|
||||
name = "greenled";
|
||||
up = ''
|
||||
echo 17 > /sys/class/gpio/export
|
||||
echo out > /sys/class/gpio/gpio17/direction
|
||||
echo 0 > /sys/class/gpio/gpio17/value
|
||||
'';
|
||||
down = ''
|
||||
echo 0 > /sys/class/gpio/gpio17/value
|
||||
'';
|
||||
}
|
||||
----
|
||||
|
||||
Services may have dependencies: as you see above in the `+cowsayd+`
|
||||
example, it depends on some service called `+config.services.lan+`,
|
||||
meaning that it won't be started until that other service is up.
|
||||
|
||||
==== Service outputs
|
||||
|
||||
Outputs are a mechanism by which a service can provide data which may be
|
||||
required by other services. For example:
|
||||
|
||||
* the DHCP client service can expect to receive nameserver address
|
||||
information as one of the fields in the response from the DHCP server:
|
||||
we provide that as an output which a dependent service for a stub name
|
||||
resolver can use to configure its upstream servers.
|
||||
* a service that creates a new network interface (e.g. ppp) will provide
|
||||
the name of the interface (`+ppp0+`, or `+ppp1+` or `+ppp7+`) as an
|
||||
output so that a dependent service can reference it to set up a route,
|
||||
or to configure firewall rules.
|
||||
|
||||
A service `+myservice+` should write its outputs as files in
|
||||
`+/run/services/outputs/myservice+`: you can look around this directory
|
||||
on a running Liminix system to see how it's used currently. Usually we
|
||||
use the `+in_outputs+` shell function in the `+up+` or `+run+`
|
||||
attributes of the service:
|
||||
|
||||
[source,shell]
|
||||
----
|
||||
(in_outputs ${name}
|
||||
for i in lease mask ip router siaddr dns serverid subnet opt53 interface ; do
|
||||
(printenv $i || true) > $i
|
||||
done)
|
||||
----
|
||||
|
||||
The outputs are just files, so technically you can read them using
|
||||
anything that can read a file. Liminix has two "preferred" mechanisms,
|
||||
though:
|
||||
|
||||
===== One-off lookups
|
||||
|
||||
In any context that ends up being evaluated by the shell, use `+output+`
|
||||
to print the value of an output
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
services.defaultroute4 = svc.network.route.build {
|
||||
via = "$(output ${services.wan} address)";
|
||||
target = "default";
|
||||
dependencies = [ services.wan ];
|
||||
};
|
||||
----
|
||||
|
||||
===== Continuous updates
|
||||
|
||||
The downside of using shell functions in downstream service startup
|
||||
scripts is that they only run when the service starts up: if a service
|
||||
output _changes_, the downstream service would have to be restarted to
|
||||
notice the change. Sometimes this is OK but other times the downstream
|
||||
has no other need to restart, if it can only get its new data.
|
||||
|
||||
For this case, there is the `+anoia.svc+` Fennel library, which allows
|
||||
you to write a simple loop which is iterated over whenever a service's
|
||||
outputs change. This code is from
|
||||
`+modules/dhcp6c/acquire-wan-address.fnl+`
|
||||
|
||||
[source,fennel]
|
||||
----
|
||||
(fn update-addresses [wan-device addresses new-addresses exec]
|
||||
;; run some appropriate "ip address [add|remove]" commands
|
||||
)
|
||||
|
||||
(fn run []
|
||||
(let [[state-directory wan-device] arg
|
||||
dir (svc.open state-directory)]
|
||||
(accumulate [addresses []
|
||||
v (dir:events)]
|
||||
(update-addresses wan-device addresses
|
||||
(or (v:output "address") []) system))))
|
||||
----
|
||||
|
||||
The `+output+` method seen here accepts a filename (relative to the
|
||||
service's output directory), or a directory name. It returns the first
|
||||
line of that file, or for directories it returns a table (Lua's
|
||||
key/value datastructure, similar to a hash/dictionary) of the outputs in
|
||||
that directory.
|
||||
|
||||
===== Output design considerations
|
||||
|
||||
For preference, outputs should be short and simple, and not require
|
||||
downstream services to do complicated parsing in order to use them.
|
||||
Shell commands in Liminix are run using the Busybox shell which doesn't
|
||||
have the niceties of an advanced shell like Bash let alone those of a
|
||||
real programming language.
|
||||
|
||||
Note also that the Lua `+svc+` library only reads the first line of each
|
||||
output.
|
||||
|
||||
=== Module implementation
|
||||
|
||||
Modules in Liminix conventionally live in
|
||||
`+modules/somename/default.nix+`. If you want or need to write your own,
|
||||
you may wish to refer to the examples there in conjunction with reading
|
||||
this section.
|
||||
|
||||
A module is a function that accepts `+{lib, pkgs, config, ... }+` and
|
||||
returns an attrset with keys `+imports, options config+`.
|
||||
|
||||
* `+imports+` is a list of paths to the other modules required by this
|
||||
one
|
||||
* `+options+` is a nested set of option declarations
|
||||
* `+config+` is a nested set of option definitions
|
||||
|
||||
The NixOS manual section
|
||||
https://nixos.org/manual/nixos/stable/#sec-writing-modules[Writing NixOS
|
||||
Modules] is a quite comprehensive reference to writing NixOS modules,
|
||||
which is also mostly applicable to Liminix except that it doesn't cover
|
||||
service templates.
|
||||
|
||||
==== Service templates
|
||||
|
||||
To expose a service template in a module, it needs the following:
|
||||
|
||||
* an option declaration for `+system.service.myservicename+` with the
|
||||
type of `+liminix.lib.types.serviceDefn+`
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
options = {
|
||||
system.service.cowsay = mkOption {
|
||||
type = liminix.lib.types.serviceDefn;
|
||||
};
|
||||
};
|
||||
----
|
||||
|
||||
* an option definition for the same key, which specifies where to import
|
||||
the service template from (often `+./service.nix+`) and the types of its
|
||||
parameters.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
config.system.service.cowsay = config.system.callService ./service.nix {
|
||||
address = mkOption {
|
||||
type = types.str;
|
||||
default = "0.0.0.0";
|
||||
description = "Listen on specified address";
|
||||
example = "127.0.0.1";
|
||||
};
|
||||
port = mkOption {
|
||||
type = types.port;
|
||||
default = 22;
|
||||
description = "Listen on specified TCP port";
|
||||
};
|
||||
breed = mkOption {
|
||||
type = types.str;
|
||||
default = "British Friesian"
|
||||
description = "Breed of the cow";
|
||||
};
|
||||
};
|
||||
----
|
||||
|
||||
Then you need to provide the service template itself, probably in
|
||||
`+./service.nix+`:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
# any nixpkgs package can be named here
|
||||
liminix
|
||||
, cowsayd
|
||||
, serviceFns
|
||||
, lib
|
||||
}:
|
||||
# these are the parameters declared in the callService invocation
|
||||
{ address, port, breed} :
|
||||
let
|
||||
inherit (liminix.services) longrun;
|
||||
inherit (lib.strings) escapeShellArg;
|
||||
in longrun {
|
||||
name = "cowsayd";
|
||||
run = "${cowsayd}/bin/cowsayd --address ${address} --port ${builtins.toString port} --breed ${escapeShellArg breed}";
|
||||
}
|
||||
----
|
||||
|
||||
[TIP]
|
||||
====
|
||||
Not relevant to module-based services specifically, but a common gotcha
|
||||
when specifiying services is forgetting to transform "rich" parameter
|
||||
values into text when composing a command for the shell to execute. Note
|
||||
here that the port number, an integer, is stringified with `+toString+`,
|
||||
and the name of the breed, which may contain spaces, is escaped with
|
||||
`+escapeShellArg+`
|
||||
====
|
||||
|
||||
==== Types
|
||||
|
||||
All of the NixOS module types are available in Liminix. These
|
||||
Liminix-specific types also exist in `+pkgs.liminix.lib.types+`:
|
||||
|
||||
* `+service+`: an s6-rc service
|
||||
* `+interface+`: an s6-rc service which specifies a network interface
|
||||
* `+serviceDefn+`: a service "template" definition
|
||||
|
||||
In the future it is likely that we will extend this to include other
|
||||
useful types in the networking domain: for example; IP address, network
|
||||
prefix or netmask, protocol family and others as we find them.
|
||||
|
||||
Reference in New Issue
Block a user