AA-START(1)

NAME
aa-start - Start services

SYNOPSIS
aa-start [-D] [-r repodir] [-l listdir] [-W] [-t timeout] [-n] [-v] [service...]

OPTIONS

-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.

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

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

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

-n, --dry-list
    Only print the name of the services, but do not start anything.

    Specify a second time to list services that need to be up instead of those that would be started, i.e. include those already up.

-r, --repodir dir
    Use dir as repository directory. This is where servicedirs will be looked for.

-t, --timeout timeout
    Set default timeout to timeout seconds. You can use 0 for no timeout. Timeout can also be set in service in a file timeout in its servicedir.

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

-v, --verbose
    Print auto-added dependencies (from "needs" and "wants"). Note that due to recursion they'll be printed in reverse order, e.g. "B needs C" then "A needs B" when starting A.

    This will be printed on stdout unless --dry-list was used, then it goes to stderr.

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

DESCRIPTION
aa-start(1) allows to start one or more services. By default, any services found in directories needs or wants are also auto-started, though it is possible not to auto-start the ones from wants via --no-wants.

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

Refer to anopa(1) for descriptions of servicedirs and service dependencies.

TIMEOUTS
When starting a service, a timestamp is collected. If the service fails to be started/ready before the number of seconds specified either in a file timeout in its servicedir or using the default value (300 (5 min) by default, unless set via --timeout), the service is considered to have timed out.

For long-run services, aa-start(1) will simply stop waiting for event and mark the service as timed out.

For one-shot services, signal TERM will be sent to the process, which is then given up to 2 seconds to react. If it exits during that time, it will be processed as usual, with the exception that if SIGTERM is the cause the service will then be marked as timed out (i.e. it could exit with a specified exit code, and be then marked failed, or even return 0 and be successfully started).

If the process hasn't ended after those 2 seconds, signal KILL is sent to the process and the service marked as timed out.

Note that using a value of 0 as time out (either via timeout file or --timeout option) means it never times out, and aa-start(1) will wait for it forever; Use with caution.

  Which services are we waiting for?
When waiting for a service, and if there is no other activity (i.e. no services being started or showing messages, etc) then aa-start(1) will show an indication of the service being waited for, including how much time has elapsed since it was started and its timeout, e.g:

    [23s/5m] foobar

Indicates that service foobar is being waited for, it was started 23 seconds ago and will timeout when reaching 5 minutes. In case more than one service is being waited for, the "index" of the service and the number of services being waited for will be prefixed, and it will go through all services, e.g:

    [1/2; 23s/5m] foo

for a couple of seconds, then:

    [2/2; 42s/2m30] bar

Looping through them again until some activity occurs. The service whose name is currently being shown is called the "active" service.

  Manual trigger of time out
When the name of the "active" service is shown, if aa-start(1) receives signal INT (e.g. you pressed Ctrl+C) it will then reset the service's timeout to 1 second, effectively causing it to be processed as timed out immediately.

This could be useful if you know a service won't work and eventually time out, and do not wish to wait until it actually gets there. This also works for services with an infinite timeout (i.e. set to 0).

STARTING A LONG-RUN SERVICE
When starting a long-run service, aa-start(1) first connects to the event fifodir of the service, then checks (with s6) if the service is already up or not. If so, it disconnects and the service is announced as already up and process continues as expected.

If not, aa-start(1) then checks whether there's a file gets-ready in the servicedir, and if not whether there is a file notification-fd containing a number. It then sends the command to bring it up and removes the down file (if present).

If there was no gets-ready/valid notification-fd file, it waits for event 'u' to be triggered, then (disconnects from the fifodir and) announce the service as started. If there was one, it will then wait for event 'U' to be triggered instead, announcing the service as ready instead. (A message will be shown on event 'u' as information only. Note that should event 'd' occur, a message will also be shown, but aa-start(1) will still keep waiting for event 'U'.)

STARTING A ONE-SHOT SERVICE
When starting a one-shot service, if no file start exists the service is simply announced as started right away. Else, aa-start(1) forks and the child goes into the servicedir (making it its current working directory) then executes into start.

Pipes are set up, so the script's stdin (fd 0) is a pipe connected to aa-start(1), as are its stdout & stderr (fd 1 & 2), and lastly another pipe is set up on file descriptor 3.

Any and all lines written on fd 1 and 2 will be printed on console by aa-start(1), prefixed with the service name.

This last fd can be used by the service for special cases.

  Showing progress bars
A service might want to show the user a progress bar as they perform long operations. This can be done simply by writing LF-terminated lines to fd 3 made of the following space-separated fields :

1. Step number
    In case more than one steps will be performed, each having its own progress bar. If only one progress bar will be used, use 0.

2. Current value
    The current value. This is an integer representing the current value of the operation, from 0 to the maximum value (next field).

3. Maximum value
    The maximum value. Note that when the current value and the maximum value are the same, a progress bar filled to 100% will be shown; It is only removed from the screen once the process execution is over (or when the fd is closed).

4. Description
    This last field can include spaces, as it goes until the LF. It is an optional (small) description to be added alongside the progress bar, e.g. to indicate what is being performed.

The knowledgeable reader will have noticed that this format correspond to that used by fsck(8) and its -C option; This is no coincidence. To have progress bars shown for a service performing an fsck, simply run it with `-C3` as option.

  Asking user for a password
A service might need to ask the user to input a password, e.g. to open an encrypted device. This can also be done with a little help from our friend, in file descriptor 3.

First, the service needs to write an LF-terminated line to its fd 3, the message asking the user, prefixed with "< " (less than sign and a space). For example, write "< Please enter passphrase to open /dev/sda2" (ending with a LF).

Then, simply read on stdin (fd 0) what the user inputed. aa-start(1) takes care of showing the message to the user (prefixed with the service name) and disabling echoing input on the terminal.

It is possible to ask again for another input (e.g. if password failed) by simply doing the same again.

Note that it is not possible to show a progress bar while asking for user input, not that there should be a need for it anyways.

Also note that once aa-start(1) received a demand of password input, it will disable the service's timeout, restoring it once it has been processed (e.g. user input has been written to the service's stdin) and resetting its timer.

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>