=head1 NAME

aa-stop - Stop services

=head1 SYNOPSIS

B<aa-stop> [B<-D>] [B<-O> I<FILE|FD>] [B<-r> I<repodir>] [B<-l> I<listdir>]
[B<-a>] [B<-k> I<service>] [B<-t> I<timeout>] [B<-n>] [B<-v>] [I<service...>]

=head1 OPTIONS

=over

=item B<-a, --all>

Stops all running/started services.

Specify this option twice to enable "stop-all" mode, intended to bring down the
entire supervised tree (i.e. be used during stage 3, after B<s6-svscan> has been
brought down).
When used, you shouldn't specify any service on the command line.

Also see below as well as B<--timeout> for more implications.

=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<-h, --help>

Show help screen and exit.

=item B<-k, --skip> I<service>

If I<service> was asked to be stopped, silently ignore it. This is intended for
use alongside B<--all --all> to keep the catch-all logger service running as
long as possible. Its B<s6-supervise> will only be sent an 'x' command, so
stopping the service next will automatically have its supervisor exit as well.

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

Use I<dir> to list services to start. 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<-n, --dry-list>

Only print the name of the services, but do not stop anything.

=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, --repodir> I<dir>

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

=item B<-t, --timeout> I<timeout>

Set default timeout to I<timeout> seconds. You can use 0 for no timeout.
Timeout can also be set in service in a file I<timeout> in its servicedir.

If the "stop-all" mode is enabled (i.e. option B<--all> used twice), the default
timeout (whether or not set on command line) will also be used as a maximum
value.

=item B<-V, --version>

Show version information and exit.

=item B<-v, --verbose>

Print auto-added dependencies (from "needs").  Note that dependencies are
"reversed" here, i.e. if foo needs bar, B<aa-stop>(1) will print "bar needs foo"
as to indicate that stopping bar needs to (first) stop foo.

Also note that this will always print dependencies for all started services,
whether or not they'll apply to the requested operation.

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

=back

=head1 DESCRIPTION

B<aa-stop>(1) allows to stop one or more services. It works in similar fashion
to B<aa-start>(1) but processing order and dependencies "in reverse" so to
speak.

That is to say if service A was to be started after service B, then it will be
stopped before B. And if A had a dependency (I<needs>) on C, then stopping C
will also cause for A to be stopped.

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

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

B<aa-stop>(1) works in a very similar manner as B<aa-start>(1), with the
following differences :

=head1 STOPPING A LONG-RUN SERVICE

B<aa-stop>(1) will check if the service is running, and if not simply announce
it as not up.

If the "stop-all" mode is enabled (i.e. option B<--all> used twice), failing
dependencies will not cause not to stop services.  That is, is A needs B,
stopping B would depend on stopping A first, and if that failed B wouldn't be
stopped (Stopping failed: Failed dependency: A).  However with this mode B
would be stopped, as if A had been successfully stopped.

Additionally, B<aa-stop>(1) will send command 'x' to B<s6-supervise> of all down
services, while it will send commands 'dx' (instead of 'd') to the up services'
B<s6-supervise>, so that after bringing their services down they exit as well.
This is obviously all intended to bring the supervised tree all down, as is
expected, and shouldn't be used if B<s6-svscan> is still running (as it would
bring the B<s6-supervise> back up).

=head2 Service not up

When you call B<aa-stop>(1) it will first create a list of all services to be
stopped. Any service specified that isn't up will simply be ignored with a "Not
up" message shown.

It should be noted that, for long-run services, it is possible that a service
was up then, but will be down by the time B<aa-stop>(1) wants to stop it. E.g.
because other services stopped first caused it to stop/crash.

In such a case, the message "Stopping service..." will be shown, and
B<aa-stop>(1) will send the command as usual; But it won't check for errors
(nor wait for the 'd' event) and simply report the service as "Not up" instead.

This should ensure that e.g. s6 doesn't restart the service, or stops it if that
was already (being) done.

=head1 STOPPING A ONE-SHOT SERVICE

Obviously, the script used is I<stop> and not I<start>. Other than that, the
process is much the same, so you can refer to B<aa-start>(1) for more.

=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