=head1 NAME

aa-status - Show status of services

=head1 SYNOPSIS

B<aa-status> [B<-D>] [B<-O> I<FILE|FD>] [B<-r> I<repodir>] [B<-a>] [B<-f>
I<filter>] [B<-L>] [B<-n>] [B<-l> I<listdir>] [B<-s> I<sort>] [B<-R>] [B<-N>]
[I<service...>]

=head1 OPTIONS

=over

=item B<-a, --all>

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

=item B<-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.

B<Deprecation warning:> Note that this option has been deprecated and will be
removed in the next version; You should use B<--log-file> instead.

=item B<-f, --filter> I<filter>

Only process services matching I<filter>. See L<B<FILTERING>|/FILTERING> below
for more.

=item B<-h, --help>

Show help screen and exit.

=item B<-l, --listdir> I<dir>

Use I<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 I<dir> doesn't start with a slash or dot, it will be prefixed with
I</etc/anopa/listdirs/>

=item B<-L, --list>

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

=item B<-N, --name>

Sort services by name. Default is by time, see B<--sort> for more.

=item B<-n, --dry-list>

Only show service names, one per line.

=item B<-O, --log-file> I<FILE|FD>

Will duplicate all output (everything written to stdout or stderr) to the given
file or file descriptor. I<FILE|FD> can either be a (previously opened for
writing) file descriptor (must be > 2), or a file which will then be opened in
append mode.

=item B<-R, --reverse>

Reverse sort order.

=item B<-r, --repodir> I<dir>

Use I<dir> as repository directory. This is where servicedirs will be looked
for.

=item B<-s, --sort> I<sort>

Sort services according to I<sort>, which can be one of:

- I<name> : to sort by names. Can use B<--name> as an alias.

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

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

=item B<-V, --version>

Show version information and exit.

=back

=head1 DESCRIPTION

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

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

=head1 FILTERING

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

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

=head2 Filter by type

=over

=item I<oneshot>; I<os>

To only process oneshot services.

=item I<longrun>; I<lr>

To only process longrun services.

=item I<all>; I<os+lr+log>

To process all services: oneshots, longruns, and loggers. By default, only
oneshots and longruns are shown.

=item I<log>

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

=item I<logged>; I<lr+log>

To only process longruns and loggers. Note that this also include longruns
without loggers.

=back

=head2 Filter by status

=over

=item I<start>; I<started>; I<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.

=item I<stop>; I<stopped>; I<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.

=item I<fail>; I<failed>; I<error>

To only process services that are in error state.

=back

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 I<stopped> and I<failed>

You can specify more than one B<--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.

=head2 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


=head1 POSSIBLE STATUSES

The different possible statuses are :

=over

=item B<Unknown status>

E.g. if no status file exist. Such services will be filtered as I<stopped>.

=item B<Error>

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

=item B<Starting failed> / B<Stopping failed>

For oneshot services, the script I<start>/I<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.

=item B<Start failed> / B<Stop failed>

(I<one-shot services only.>)

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

=item B<Starting> / B<Stopping>

The script I<start>/I<stop> is currently running; or the command has been sent
to the B<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 I<stopped>.

=item B<Started> / B<Stopped>

(I<one-shot services only.>)

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

=item B<Up> / B<Up; Getting ready...> / B<Up & Ready>

(I<long-run services only.>)

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

In list mode (option B<--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 B<--list>), this information is shown
under "Mode".

I<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').

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

=item B<Down> / B<Down & Ready>

(I<long-run services only.>)

The script I<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 B<s6-supervise> shall be
starting the run script again.

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

=back

=head1 RETURN CODES

Return codes are somewhat unified inside B<anopa>. Return codes are unified for
all commands, and are documented in B<anopa-rc>(1)

=head1 ENVIRONMENT VARIABLES

The following environment variables are used :

=over

=item B<AA_REPODIR>

The full path to the repository directory, unless specified via B<--repodir> If
neither the environment variable nor the option are used, defaults to
I</run/services>

=back