NAME

director-spec — Director specification for configuration files

CONFIGURATION

SPECIFICATION

options

Options that will be used by all services.

type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.

services

This dictionary contains the services to be created and started. Each key is the name of the service that must be valid with the following regular expression: “^[a-zA-Z0-9._-]+$”. The name of the service is not the same as the name of the jail.

type: Dictionary.

services.service.priority

Once the director-spec(5) file has been processed, the services will be sorted using this number. Lower integers have higher priority, so those services will be processed first.

type: Integer
default: 99

services.service.name

Jail name. If not specified, a random hexadecimal string will be used.

type: String

services.service.makejail

appjail-makejail(5) to be executed.

type: String
default: Makejail

services.service.runtime-makejail

Like makejail, but uses appjail-apply(5) to apply an appjail-makejail(5) to an existing jail, which in this case occurs after director(1) starts the jail (if the appjail-makejail(5) specified in makejail doesn't do so). This appjail-makejail(5) is applied every time the up command is run, so some logic should be added depending on the task performed to avoid unwanted behavior. Useful for updating an existing file and/or hot reloading. See post-start in scripts, which has a similar purpose but does not use Makejails.

If this appjail-makejail(5) fails, director(1) will not set the service as failed because, if it did, the service would be recreated on the next execution, which is not desirable in this context.

Please note that you must explicitly specify the apply stage in the appjail-makejail(5) specified by this parameter in order to execute the code.

type: String

services.service.reset_options

The global options will be added to the local options. These options only take into account the local options per service.

type: Boolean

services.service.ignore_mtime

Do not recreate the service when the appjail-makejail(5) modification time changes.

type: Boolean

services.service.options

It has the same effect as the global options, but only for the services in which it appears.

services.service.arguments

Arguments to pass to the appjail-makejail(5) to be executed.

type: Array of dictionaries. Each dictionary (key and value) is a string.

services.service.runtime-arguments

Arguments to pass to the appjail-makejail(5) specified in runtime-makejail.

type: Array of dictionaries. Each dictionary (key and value) is a string.

services.service.runtime-environment

Environment variables valid only in the apply stage.

type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.

services.service.environment

Environment variables valid only in the build stage.

type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.

services.service.start-environment

Environment variables valid only in the start stage.

type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.

services.service.oci

Settings used by OCI-related commands.

type: Dictionary

services.service.oci.user

Execute the process specified by the OCI image as another user.

type: String

services.service.oci.workdir

Execute the process specified by the OCI image in this working directory.

type: String

services.service.oci.environment

Environment variables used by the process specified by the OCI image.

type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.

services.service.volumes

The key of each dictionary is used to obtain the volume options specified by the global volumes.

type: Array of dictionaries. Each dictionary (key and value) is a string.

services.service.scripts

Scripts that will be executed once the jail is created and started.

type: Array of dictionaries.

services.service.scripts.[].shell

Shell used to execute the script.

type: String
default: /bin/sh -c

services.service.scripts.[].type

In which environment the script will be executed: jexec (inside the jail), local (in the host), or chroot (inside the chroot environment).

See also appjail-cmd(1) for details.

type: String
default: jexec

services.service.scripts.[].text

Script to be executed.

type: String

services.service.scripts.[].post-start

By default, director(1) executes the script before checking the status of the jail, which means that the jail may or may not be started. When this parameter is set to true, the script runs after this check, and this occurs every time the project runs, so you must add logic to your script to prevent unwanted changes. This is especially useful when you need to update a configuration file and/or perform a hot reload.

type: Boolean
default: false

services.service.start

Arguments to be passed to the start stage.

type: Array of dictionaries. Each dictionary (key and value) is a string.

services.service.serial

director(1) detects changes to rerun the appjail-makejail(5), this item forces the execution of the appjail-makejail(5).

type: String

default_volume_type

Default volume type when type is not defined in volumes.volume.

volumes

Describe the volume options used by the services.

type: Dictionary

volumes.volume.device

Device to be mounted.

type: String

volumes.volume.type

Type of the file system. When using nullfs, <pseudofs> or <volumefs>, device is treated as a directory (when it doesn't exist) and after getting the absolute path it will be used as the actual device.

type: String
default: <pseudofs>

volumes.volume.options

Mount point options associated with the file system.

type: String
default: rw

volumes.volume.dump

Whether dump(8) command should be used for those file systems that need to be dumped.

type: Integer
default: 0

volumes.volume.pass

Used by fsck(8) and quotacheck(8) commands to determine the order in which file system and quota checks are done at reboot time.

type: Integer
default: 0

volumes.volume.umask

Valid only for nullfs, <pseudofs> and <volumefs> file systems. When defined, the umask is set before the creation of the directory (aka device) and is restored after the directory is created.

type: Integer

volumes.volume.mode

Valid only for nullfs, <pseudofs> and <volumefs> file systems. Change the access permissions of the directory (aka device) after its creation.

type: Integer

volumes.volume.owner

Valid only for nullfs, <pseudofs> and <volumefs> file systems. When defined, the directory owner is set after the creation of the directory (aka device). Note that if you use a string instead of an integer, it will be resolved from your local user database.

volumes.volume.group

It has the same effect as owner, but for the device group.

SEE ALSO

appjail(1) director(1)

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>