AA-STATUS(1)

NAME
aa-status - Show status of services

SYNOPSIS
aa-status [-D] [-r repodir] [-a] [-f filter] [-L] [-n] [-l listdir] [-s sort] [-R] [-N] [service...]

OPTIONS

-a, --all
    Show status of all (enabled) services. This will list all folders (servicedirs) in the repository and show their status.

-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, --filter filter
    Only process services matching filter. See FILTERING below for more.

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

-l, --listdir dir
    Use dir to list services to show status of. 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/

-L, --list
    Show statuses as a list, with one service per line, elipsizing service name and/or status if needed.

-N, --name
    Sort services by name. Default is by time, see --sort for more.

-n, --dry-list
    Only show service names, one per line.

-R, --reverse
    Reverse sort order.

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

-s, --sort sort
    Sort services according to sort, which can be one of:

    - name : to sort by names. Can use --name as an alias.

    - time : to sort by times, i.e. the timestamp of the last event for the
      service; This can be e.g. when it was started, failed to, or got ready. This
      is the default sort order.

    - none : do not sort services. Order will be the one in which they were
      processed.

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

DESCRIPTION
aa-status(1) will show the status of one or more services. It does so by reading the status.anopa file created by either aa-start(1) or aa-stop(1) as well as the status file from s6 for long-run services, using whichever one has more recent information.

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

FILTERING
You can use --filter to filter which services to process amongst those provided (meaning to filter all enabled services you need to combine it with --all).

There are two kinds of filters available, by type and by status.

  Filter by type

oneshot; os
    To only process oneshot services.

longrun; lr
    To only process longrun services.

all; os+lr+log
    To process all services: oneshots, longruns, and loggers. By default, only oneshots and longruns are shown.

log To only process loggers (i.e. */log services)

logged; lr+log
    To only process longruns and loggers. Note that this also include longruns without loggers.

  Filter by status

start; started; up
    To only process services that are up/started. Note that this includes services that might be in error state, e.g. that failed to be stopped.

stop; stopped; down
    To only process services that are down/stopped. Note that this includes services that might be in error state, e.g. that failed to be started.

fail; failed; error
    To only process services that are in error state.

As noted below, a given service can match more than one filter, e.g. a service that failed to be started will show up both under stopped and failed

You can specify more than one --filter option, though it only make sense to combine filters of different kinds. If more than one filter of the same kind is given, only the last one is used.

  Examples
To list all oneshot services in error state:

    aa-status --list --all --filter oneshot --filter error

The same could be done using e.g:

    aa-status -Laf fail -f os

To show statues of all longrun services currently up:

    aa-status -a -f longrun -f started

This will list all oneshot services (only the last filter is used since they're both of the same kind) :

    aa-status -Laf longrun --filter os

To list all services, including loggers, that are up:

    aa-status -Laf all -f up

POSSIBLE STATUSES
The different possible statuses are :

Unknown status
    E.g. if no status file exist. Such services will be filtered as stopped.

Error
    An error occured while processing the service, e.g. a dependency failed. An additionnal message will be present.

Starting failed / Stopping failed
    For oneshot services, the script start/stop could not be started; E.g. a permission error prevented its execution; For longrun services, it can occur if e.g. anopa failed to communicate with s6

    An additionnal message might be present.

Start failed / Stop failed
    (one-shot services only.)

    The script start/stop did not return zero on exit. It will say either which value was returned, or which signal killed it.

Starting / Stopping
    The script start/stop is currently running; or the command has been sent to the s6-supervise of the service.

    Such services will be filtered according to their current state, e.g. a service that is starting will be matched via stopped.

Started / Stopped
    (one-shot services only.)

    This script start/stop succesfully ran (i.e. and returned 0).

Up / Up; Getting ready... / Up & Ready
    (long-run services only.)

    The script run is currently running; Its PID will be specified.

    In list mode (option --list), the word "Once" might appear next to the PID. This is done when the service is running in mode once, i.e. will not be automatically restarted when it goes down.

    In standard output (i.e. without option --list), this information is shown under "Mode".

    Up; Getting ready... is shown when a service is up, supports readiness, but isn't yet ready (i.e. event 'u' occured, but not 'U').

    Up & Ready means that the service indicated readiness (or it was set via e.g. aa-setready(1)). Both times for up ('u') and readiness ('U') are shown, though in list mode only the later in shown.

Down / Down & Ready
    (long-run services only.)

    The script run isn't running anymore. Its exitcode or which signal killed it will be specified.

    It can be followed by "To be restarted" when the service is expected to be restarted soon by its supervisor, e.g. the service just went down or its finish script is running, but within a few seconds its s6-supervise shall be starting the run script again.

    Down & Ready means that the finish script (if any) also ended its execution (or was killed by s6-supervise). Both times for down ('d') and end-of-finish ('D') are shown, though in list mode (option --list) only the later in shown.

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>