# 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:

    $ 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:

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

    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:

    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:

    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:

    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:

    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:

    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:

    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:

    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:

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