AA-ENABLE(1)

NAME
aa-enable - Enable services, i.e. copy servicedirs to repodir

SYNOPSIS
aa-enable [-D] [-r REPODIR] [-c CRASH] [-f FINISH] [-k SERVICE] [-S SOURCEDIR] [-s SOURCEDIR] [-l LISTDIR] [-N] [-W] [-u] [-a] [--no-supervise] [-q] [SERVICE...]

OPTIONS

-a, --alarm-s6
    Alarms s6-svscan as last step; This obviously assumes there is a running instance of s6-svscan running on REPODIR/.scandir; Also note that it will do it regardless of whether longruns where added or not.

    "Alarm" means s6-svscan will immediately perform a scan of its scandir to check for (new) services. This is equivalent to manually running "s6-svscan -a REPODIR/.scandir" afterwards.

-c, --set-crash CRASH
    Create a symlink REPODIR/.scandir/.s6-svscan/crash that points to CRASH. This is what s6-svscan will exec into if it crashes.

-D, --double-output
    Enable double-output mode. Instead of using stdout for regular output, and stderr for warnings and errors, everything is sent both to stdout and stderr. This is intended to redirect stderr to a log file, so full output can be both shown on console and logged.

-f, --set-finish FINISH
    Create a symlink REPODIR/.scandir/.s6-svscan/finish that points to FINISH. This is what s6-svscan will exec into when it's done. This would usually point to aa-stage3(1).

-h, --help
    Show help screen and exit.

-k, --skip-down SERVICE
    When (if) enabling SERVICE do not create a file down even it there's none and it is a longrun service. This is intended to be used during stage 1, for the catch-all logger service, which needs to be started automatically by s6-svscan (to unblock & trigger stage 2).

-l, --listdir LISTDIR
    Use LISTDIR to list services to enable. Only one can be set, if specified more than once the last one will be used.

    The directory will be read, and names of files/directories within be used as service name to enable. For directories, their content will be merged/copied into the servicedir; See below for more.

    If LISTDIR doesn't start with a slash or dot, it will be prefixed with /etc/anopa/listdirs/

-N, --no-needs
    Don't auto-enable any services listed under directory needs of a service being (auto-)enabled.

-q, --quiet
    Don't print enabled service names.

-r, --repodir REPODIR
    Use REPODIR as repository directory. This is where all servicedirs will be created/copied to.

-S, --reset-source SOURCEDIR
    Reset the list of source directories to SOURCEDIR. You can add more with --source. This is useful to unset the defaults.

-s, --source SOURCEDIR
    Add SOURCEDIR as new source. Can be specified multiple times; Source directories will be processed in the order they were added.

-u, --upgrade
    Upgrade servicedirs instead of creating them. See below for implications.

--no-supervise
    Disable creation of supervise folders for longrun services. By default, aa-enable(1) will create a folder supervise with permissions 0711 for every longrun service (including loggers).

    This is meant to ensure one can read the s6 status file (which is world-readable by default) without the need to be root. This allows for example to use aa-status(1) as a user properly.

    If you were to disable this, the supervise folders would likely be created by s6-supervise with 0700 permissions, and when trying to read s6 status as a user a "Permission denied" error would occur.

-V, --version
    Show version information and exit.

-W, --no-wants
    Don't auto-enable any services listed under directory wants of a service being (auto-)enabled.

DESCRIPTION
With anopa, you usually create your service repository early on boot (during stage 1) into tmpfs (/run/services). This ensures that no previous state/files from an earlier boot will interfere with the current one, leaving your main filesystem untouched (it could even be read-only).

By default the repository directory used is /run/services and source directories are, in order, /etc/anopa/services and /usr/lib/services

Also note that by default aa-enable(1) will auto-enable any service whose name was found in a directory need or wants of a created servicedir. This can be turned off via --no-needs and/or --no-wants if needed.

You can use - as service name to read actual service names from stdin, where there must be one name per line.

  Enabling a service / Creating a servicedir
Instead of simply creating the repository ahead of time, and copying it all on boot, the copying process is done through aa-enable(1) which works as such:

- The given LISTDIR is read. It contains either empty regular files, or directories, whose name is the name of a service to enable.

- Source directories are tried, in order, to find the corresponding servicedir, which is then copied over to the runtime repository (REPODIR). During this copy, aa-enable(1) notes whether or not a file run exists, i.e. whether this is a long-run or one-shot service.

- If the service name came from a directory in LISTDIR, its content is then merged/copied over into the servicedir. This allows to specify service-specific configuration, or could possibly be used to overwrite an actual script. See below for how to remove/append to files.

- If the service is a long-run, an empty regular file down is created (unless it already existed, or the service was specified to --skip-down) to ensure the service won't be auto-started by s6-svscan, and a symlink is added to the servicedir into the .scandir sub-directory of REPODIR (even if the service was specified to --skip-down). And, unless option --no-supervise was specified, a folder supervise is created with 0711 permissions.

- As last step, aa-enable(1) will check if a regular file log/run-args exists in the newly created servicedir, and if so its content will be appended to log/run

  Special case: Instances
Service names cannot start nor end with a @ character, but can contain one. servicedirs in source directories shall not contain a @ character, unless it is the last character in their name.

The idea is to use the notion of "instances." Imagine a service that starts a getty on a tty. Instead of needing to write as many servicedirs as you want gettys on ttys, you simply write one, named getty@

Then, you can enable getty@tty1 and getty@tty2. For the service name getty@tty1, we say the service used in getty for instance tty1. The way it works in aa-enable(1) is that it will look for a servicedir getty@ in source directories, but will copy it as getty@tty1 into the repository.

Then, in your run/finish/start/stop script(s), you can e.g. use aa-service(1) to get the service & instance names and use them as needed.

Additionally, whenever copying content of the directories needs, wants, after and before, aa-enable(1) will automatically rename any file whose name ends with a @ to append the current instance name.

Therefore, if servicedir getty@ contained a file named set-numlock@ into one of those, it would be copied as e.g. set-numock@tty1 into the created servicedir getty@tty1.

  Special case: service logger
Long-run services are likely to be logged, and to do so you need to provide a servicedir log inside the servicedir of the service.

To simplify things, if a regular file or directory log is found in a servicedir (in a source directory), aa-enable(1) will copy the servicedir log, taken from source directories as usual, into the servicedir of the service. And in case of a directory, its content will then be merged/copied over.

This allows you to use the service/servicedir log as logger for a service by simply putting an empty regular file log into the original servicedir (in a source directory); Or use a directory to simply specify/add configuration files.

Note that you can also still provide files from the configuration directory in listdir, since it is copied last (and that this always includes providing a new run file).

The servicedir of the logger is treated as such, meaning dependencies ("needs" and "wants") will be auto-enabled as needed, you can remove/append to files from the configuration directory as described below, and a file down will be created, as well as a folder supervise (unless --no-supervise was specified).

Lastly, aa-enable(1)'s last step when creating a servicedir is to check for a regular file log/run-args in the newly created servicedir, and if found to append its content to log/run

The idea is to allow to easily use the default logger, and yet be able to add e.g. directives to s6-log's loggin script. This could be particularly useful e.g. if the default logger does connect its stdout to a fifo, allowing you to select lines to write there (or to the logger's stderr).

Note that since you can remove or append to files from configuration (directory in LISTDIR; See below), you can either remove, rewrite or append to log/run-args as needed before it is processed.

  Removing/appending to files
When copying files from the "configuration directory" (directory in LISTDIR) regular files starting with either a dash ( - ) or plus sign ( + ) are processed in a special manner:

- A file -foobar will have aa-enable(1) remove file foobar from the destination servicedir, if it exists.

- A file +foobar will have its content be appended to foobar in the destination servicedir.

  Upgrading servicedirs
You can upgrade servicedirs using the --upgrade option. This is meant to apply changes (from source directories and/or configuration) into existing servicedirs.

When used, aa-enable(1) will behave as usual with the following changes:

- The repodir (and the contained scandir) must already exist;

- Each servicedir must already exist as well. Before copying anything, all its
  content will be recursively removed except for regular file status.anopa,
  regular file down, folder supervise and folder event (and their
  content);

- For longruns, no down file will be created, nor will a symlink be added
  into the scandir or supervise folder be created;

- If used, options --set-finish and --set-crash are ignored.

Services auto-added from needs or wants will also be processed differently that those specified:

- If servicedir already exists in repodir, nothing is done

- Else, they are enabled as usual (i.e. as if without the --upgrade option)

BUGS
They're probably crawling somewhere in there... if you happen to catch one, (or more) report it and I'll do my best to squash it.

REPOSITORY
You can find the latest source code of anopa as well as report bugs and/or suggest features on its GitHub repository, available at <https://github.com/jjk-jacky/anopa>; or visit its official website at <https://jjacky.com/anopa>

AUTHOR

Olivier Brunel <jjk@jjacky.com>