Getting started with WombatOAM

Prerequisites

Before installing WombatOAM, ensure that the machine meets the prerequisites:

A UNIX operating system (WombatOAM has been tested on Linux, OS X)
The Erlang run-time system, ERTS (R15B03 or later)
OpenSSL and libcrypto (already present on Mac OS X)

WombatOAM needs a license key to work. The license key can be changed any time by replacing the license key file and restarting WombatOAM. The license file contains how many nodes can be managed by WombatOAM and it includes an expiry date. Once WombatOAM is installed, you can check the details of the license by clicking on "Help" on the WombatOAM Dashboard.

Installing WombatOAM

The fastest way to install WombatOAM on your computer is from a package. Execute the following commands:

Extract the WombatOAM package:

tar xfz wombat-[VERSION].tar.gz

cd wombat-[VERSION]

Copy your license key into the WombatOAM root directory:
```
cp .../my.lic_key .
```
Install WombatOAM:
```
./wombat install
```

!INCLUDE "parts/upgrade-howto.md"

The WombatOAM web dashboard

To access the web dashboard, go to http://localhost:8080 in your browser. Log in with the following details:

Name: admin
Password: admin

See the Configuration page for further information about configuring the web interface (for example to enable SSL).

Running WombatOAM

You can start and stop WombatOAM with the following commands:

1 2	`./wombat start # start WombatOAM ./wombat stop # stop WombatOAM`

You can also use the script bin/wombat, located in the _build/default/rel/wombat/bin/wombat folder. This script provides additional options for interacting with WombatOAM but you will have to configure Wombat through environment variables. Please refer to the ./wombat script or use it through ./wombat start_script. You can find more information in the Configuring WombatOAM for servers and containers chapter.

To check whether WombatOAM is already running, navigate your browser to the WombatOAM web dashboard on http://localhost:8080.

Using WombatOAM

To see how WombatOAM handles nodes, you can install the WombatOAM node itself into WombatOAM:

Select the Topology tab and click Add Node.
Enter the following:
- Node name: wombat@127.0.0.1
- Cookie: wombat
Click the Add node button. The WombatOAM node should come up in a few seconds. If it doesn't, check the following log file for details: _build/default/rel/wombat/log/wombat.log

Click the Metrics tab, select the node, and then select a metric. For example, click Memory → Total memory. You should see the measurements made on that node. For more information about the different metrics, see the section "Metrics".

Installing WombatOAM in multi-server environment

After you tested WombatOAM locally, you want to install it in a multi-server environment (monitoring test or production servers). The steps are very similar to what is described in Installing WombatOAM above but before starting Wombat make sure to set the WombatOAM node name to match the server's host name or IP address. This will switch WombatOAM to run in Distributed security mode (as opposed to Local-only security mode) which requires some further configuration changes to the default config. See the sections on Node name and Security modes in the Configuration chapter for details.

The default naming and structure for nodes and families can also be customized. For further information see the section Custom topology.

Configuring WombatOAM for servers and containers

It is possible to configure WombatOAM through environment variables. The available options are the following:

WOMBAT_NODENAME, the erlang node name of the node, by default it is wombat@127.0.0.1. Inside containers it is recommended to configure this to a static value because mnesia relies on the node's name being always the same.
WOMBAT_COOKIE, the cookie of the node, by default it is wombat.
HEART, enable automatic restart of Wombat in case of failure using Heart, by default it is false. It is not useful to use this option inside containers because when Wombat stops in case of error the container will stop as well.

It is recommended to use a separate (virtual) network for Wombat and its managed nodes.

Mounting volumes in containers

It is necessary to provide persistent storage for WombatOAM if you want to keep historical data. The following directories can be mounted in the provided docker image:

/wombat/data -- The data directory of Wombat
/wombat/log -- The logs generated by Wombat
/wombat/wombat.lic_key -- Wombat will look for the license in its root directory, it is advised to mount it if you are using containers.
_build/default/rel/wombat/files/wombat.config -- Wombat config file. Place your changes to the default config into this file.

Using Wombat in Amazon AWS

We build AMIs from Wombat. Please get in touch at wombat@erlang-solutions.com if you have no access to them.

For configuring the AMI please check the 'Using the official AMI containing WombatOAM' section.

Configuring networking in containerised environments

Wombat will only be able to connect to containers where it can resolve the hostname to an IP and that IP is accessible. It is necessary to place every monitored container into a network which is available for Wombat.

If you are using docker-compose then all containers in the same file will be in the same network by default, this is not true for containers started by the docker run command. If you started the containers with docker run then it's necessary to create a network and attach the containers using docker network. If you are using docker stack then an overlay network is needed to be configured.

In case you are using Amazon ECS it is possible to start the containers in the same network by configuring awsvpc.

Installing WombatOAM on Windows

Currently on Windows only running it inside Docker is supported. Please get in touch with us if you need Windows support.

Troubleshooting

Cannot connect to WombatOAM remotely

WombatOAM is configured in Local-only mode

Please configure WombatOAM to run in 'Distributed' security mode. Follow the instructions in WombatOAM Manual (chapter Configuration, section Security modes) to switch to Distributed security mode.

WombatOAM is configured in Distributed mode

Please make sure that if there's firewall configured on the host where WombatOAM is running, the HTTP and HTTPS ports (by default TCP 8080 and TCP 8443, configurable by the wo_rest, http_port and wo_rest, https_port settings) are not blocked. In particular, the default CentOS 7 installation contains a firewall configuration that blocks incoming connection to these ports. Please check the documentation of your operating system on how to enable access to these ports.

WombatOAM is not started after running the start script

It is possible that WombatOAM does not start if the path to the application or the erlang system library contains spaces or other special characters. A solution to this issue is to remove the spaces or special characters from the paths or use the provided Docker container to run Wombat.