.. index:: daemon,

.. _#ug-daemon:

19. Running AMPS as a Linux Service
====================================

AMPS is designed to be able to easily integrate into your existing
infrastructure. AMPS includes all of the dependencies it needs to run
and is configured easily with a single configuration file. Some
deployments integrate AMPS into a third-party service management
infrastructure. For those deployments, the needs of that infrastructure
determine how to install AMPS.

More typically, AMPS runs as a Linux service. This chapter describes how
to install AMPS as a service.

Installing the Service
----------------------

AMPS includes a shell script that installs the service. The shell script
is included in the ``bin`` directory of your AMPS installation. Run the
script with root permission, as follows:

.. code::

    $ sudo ./install-amps-daemon.sh

This script does the following installation work:

-  Installs the AMPS distribution into ``/opt/amps``.

-  Creates the ``/opt/etc/amps`` directory if it does not already exist.
   By default, the daemon uses an AMPS configuration file at
   ``/opt/etc/amps/config.xml``.

-  Installs the service management scripts. Depending on the init system
   the script detects on your system, this will either be a System V
   style script located at ``/etc/init.d/amps`` or a SystemD service
   definition file named ``amps.service`` installed under
   ``/usr/lib/systemd/``.

-  Updates the service management infrastructure to register AMPS as a
   service and configure the service to start on startup. The exact
   steps that the script takes to do this depend on the init system
   detected.

In addition, you must copy the AMPS configuration file for the instance
to: ``/opt/etc/amps/config.xml``.

You can only run one instance of AMPS as a service on a system at a
given time using this script. AMPS does not enforce any restriction on
how many instances can be run on the system at the same time through
other means, but this script is designed to manage a single instance
running as a service.

Configuring the Service
------------------------

When running as a service, the following considerations apply to the
configuration file:

AMPS Logging
^^^^^^^^^^^^

60East recommends logging the most important AMPS messages to syslog
when running as a service. For example, the following configuration file
snippet logs messages of warning level and above to the system log:

.. code-block:: xml

    <Logging>
        <Target>
            <Protocol>syslog</Protocol>
            <Level>warning</Level>
            <Ident>amps</Ident>
            <Options>LOG_CONS,LOG_NDELAY,LOG_PID</Options>
            <Facility>LOG_USER</Facility>
        </Target>
    </Logging>

60East does not recommend logging a level lower than warning to syslog,
since an active AMPS instance can produce a large volume of messages.

File Paths
^^^^^^^^^^

When running as a service, file paths in the configuration file also
require attention. In particular:

-  For simplicity, use absolute paths for all file paths in the
   configuration file.

-  Consider startup order, and ensure that any devices that AMPS uses
   are mounted before AMPS starts.

-  As with any other AMPS installation, it's also important to estimate
   the amount of storage space AMPS requires and ensure that the device
   where AMPS stores files has the needed capacity.

Configuration File Location
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The AMPS service scripts require the configuration file to be located at:
``/opt/etc/amps/config.xml``.

Managing the Service
---------------------

The scripts that AMPS installs provide management functions for the AMPS
service. The scripts are used in the same way scripts for other Linux
services are used.

Starting the AMPS Service
^^^^^^^^^^^^^^^^^^^^^^^^^^

To start the AMPS service, use the following command if your system uses
System V init scripts:

.. code-block:: bash

    sudo /etc/init.d/amps start

Many systems that use System V init scripts also provide convenience
commands (such as ``service``) to locate and run commands for working
with daemons. Check your distribution's documentation for details.

If your system uses SystemD, you can use a command like:

.. code-block:: bash

    sudo systemctl start amps

Stopping the AMPS Service
^^^^^^^^^^^^^^^^^^^^^^^^^

To stop the AMPS service, use the following command if your system uses
System V init scripts:

.. code-block:: bash

    sudo /etc/init.d/amps stop

Many distributions that use System V init scripts also provide
convenience commands (such as the ``service`` program) for working with
daemons. Check your distribution's documentation for details.

If your system uses SystemD, you can use a command like:

.. code-block:: bash

    sudo systemctl stop amps

Restarting the AMPS Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To restart the AMPS service, use the following command if your system
uses System V init scripts:

.. code-block:: bash

    sudo /etc/init.d/amps restart

Many distributions that use System V init scripts also provide
convenience commands (such as the ``service`` program) for working with
daemons. Check your distribution's documentation for details.

If your distribution uses SystemD, you can use a command like:

.. code-block:: bash

    sudo systemctl restart amps

View Status for the AMPS Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To see the status of the AMPS service, use the following command if your
system uses System V init scripts:

.. code-block:: bash

    sudo /etc/init.d/amps status

Many distributions that use System V init scripts also provide
convenience commands (such as the ``service`` program) for working with
daemons. Check your distribution's documentation for details.

If your distribution uses SystemD, you can use a command like:

.. code-block:: bash

    sudo systemctl status amps

Uninstalling the Service
------------------------

AMPS includes a script that uninstalls AMPS as a service. The script
reverses the changes that the install script makes to your system. Run
the script with root permission, as follows:

.. code-block:: bash

    $ sudo ./uninstall-amps-daemon.sh

The uninstall script does not remove the configuration file or any files
or data that AMPS creates at runtime.

Upgrading the Service
---------------------

To upgrade the service to a new version of AMPS, follow these steps:

1. Stop the service.

2. Uninstall the previous version of the service using the uninstall
   script included with that version.

3. If necessary, upgrade any data files or configuration files that you
   want to retain. Note that data files, such as AMPS journal files and 
   SOW files, as of version 5.0.0.0, are compatible with later releases 
   and do not need to be upgraded.

4. Install the new version of the service using the install script
   included with the new version. Ensure that the configuration file is
   at the appropriate path for the new installation.

5. Start the service.

For AMPS instances that participate in failover, you must coordinate
your upgrades as you would for a standalone AMPS instance.
