The looseleaf server accepts a JSON configuration file with a very strictly-defined
format. The configuration file is a JSON object with the following properties:
The %schema property must be present and set to the value
"https://www.io7m.com/software/looseleaf/looseleaf-config-1.json".
The addresses property specifies an array of addresses to which the server will
bind. An address is a JSON object with a mandatory string-typed host and mandatory
integer-typed port property. For example, for a server that listens on
172.17.0.1
port
20000
and
fe80::42:31ff:fe0a:119a
port 20001, the following definitions would be used:
The
looseleaf server does not support
TLS
and it is expected that the server will be configured to listen on
localhost
behind a reverse proxy that provides TLS such as
nginx.
The databaseFile property specifies the path of the database that the server
will use to store key/value data. The file will be created if it does not already exist.
The
roles property is an array-typed property that defines a set of
roles.
The following example defines a role read-xy that allows any user that
has the role to read keys that begin with /x/y/:
Similarly, the following write-xy definition allows any user that
has the write-xy role to create, update, and/or delete keys that begin with
/x/y/:
The
users property is an array-typed property that defines a set of
users. Each element of the array is a JSON object
that specifies a user name, a
hashed password, and a set of
role names that reference roles declared in the
roles property.
A
hashed password declares an
algorithm identifier,
an uppercase hex-encoded
salt value and an uppercase hex-encoded
hash value. Currently, the only supported
algorithm identifier is
PBKDF2WithHmacSHA256:n:256, which states that passwords are hashed
with
PBKDF2 using a
SHA-256 HMAC, with
n rounds of hashing, using a
256 bit key.
The
create-password command can be used
to hash a password suitable for use in a configuration file.
The following example defines a hashed password for a user:
The following example defines a user called someone, with a hashed
password and a set of roles:
The
telemetry property is an optional object-typed property that
configures
telemetry. It expects three
optional properties
metrics,
traces,
and
logs, that each specify an
endpoint and
protocol for telemetry.
If any of the three properties are absent, data will not be sent for that class of telemetry. The
telemetry property also requires a property named
logicalServiceName property which, unsurprisingly, configures
the logical service name to be included in telemetry; this is used to distinguish between multiple
running instances of the
looseleaf server in telemetry. The protocol
name may either be
HTTP or
GRPC.
In order to test that your
monitoring system
is working correctly, it can be desirable to be able to inject faults into the server in order to verify
that the monitoring system picks them up. The
faultInjection property is
an optional object-typed property that specifies the probability that various types of faults will be
injected. If the property is not present, no fault injection will occur. All probabilities are in the
range
[0, 1] where
1 indicates that faults
will occur on every operation unconditionally.
Currently, the only supported property is databaseCrashProbability, which
specifies the probability that database accesses will raise exceptions.
A full configuration file example is as follows:
The configuration defines two roles read-xy and
write-xy
which allow reading of keys
/x/y/*
and writing of keys /x/y/*, respectively. The configuration defines a single user
named someone with both roles assigned. The configuration specifies that the local
database will be created a /looseleaf/etc/data.db, and that the server will listen
on http://localhost:20000.
The
JSON schema that defines the configuration
file format is as follows: