Initial configuration

Once the monitor is installed and running, the next step is configuration. The first task is to create an administrator. This must be done before any other operations are performed as adding monitored resources, creating alerts, user management etc., can only be performed by a user with the administrator privilege. Configuration is done via the hamonitor command line utility, located in the docker image as /usr/bin/hamonitor.

Check progress by watching the log file

The log file records all actions taken by the monitor when configuration is undertaken and during the monitoring process itself (recording lost and regained connections, alerts sent, etc.). It is therefore useful to monitoring the contents of the log file during any configuration to assist in debugging.

The log file is held in the shared volume specified by the --volume argument when the monitor is started. The log file name is hamonitor.log, therefore in the docker container the full path is /tmp/hamonitor/hamonitor.log.

The log file can also be accessed from the docker host using the host directory path supplied to the volume argument, by appending hamonitor.log to the end of the path.

Create an administrator

Start a shell connected to the docker container:

docker exec -it hamonitor bash

Issue the user create command:

hamonitor user create

When prompted fill in the details for the administrator:

Enter username: admin
Enter password: [hidden]
Verify password: [hidden]
Enter real name [None]: admin
Enter email address [None]: someone@some.domain
Available roles: 0 (view-only), 1 (operator), 2 (admin)
Enter role [0]: 2

Initial admin user successfully created.

The API will restart now to enforce security.
User creation is now limited to admin roles.
Please log in as the new user

From now on you will need to login to the monitor to perform any operations:

hamonitor login
Enter URL [https://localhost:13514 if empty]:
Enter Username: admin
Enter Password: ******

Welcome admin

Once the administrator has been created the next step is to add resources to be monitored.

Add a monitored resource

From a shell connected to the docker container issue the resource add command:
```
hamonitor resource add
```

Fill in the resource details:

Enter protocol [NFS, SMB, iSCSI, LDAP]: NFS
IP address of NFS server: 2001:efca:56e4::70e7:fd8:999
Path of the NFS share: /tank
Mount options [return for None]:
User name [return for None]:
Password [return for None]:

Resource created, ID is 1

This creates a monitored NFS resource and assigned it the unique ID 1 within the monitor framework. The ID is then used by the hamonitor to refer to this resource for all operations (such as adding or removing an alert).

To view configured resources use the resource list command:

hamonitor resource list
[{
    "path": “/tank”,
    "ip": "[2001:efca:56e4::70e7:fd8:999]",
    "protocol": “nfs",
    "enabled": true,
    "creationDate": "2020-08-26T09:48:08+00:00",
    "notifications": {
    "slack": false,
    "teams": false,
    "email": false,
    "snmp": false
    },
    “resourceid”: 1
}]

In the above listing all alert notifications are set false (as this is a newly configured resource). The next step is to configure and enable an alert for this resource.

Create an alert

Once a resource has been configured, alerts can then be associated with it. In this step an email alert is added and associated with the resource created previously. Note that the resource ID (in this case 1) is used to link the alert to the resource being monitored.

From a shell connected to the docker container issue the following command:
```
hamonitor alert email create -id 1
```

Fill in the alert details from the prompts: This alert method only supports authenticated email delivery over TLS.

Enter SMTP server address (MX:PORT): mx1.yourcompany.com:587
Enter SMTP server user password: [hidden]
Verify password: [hidden]
Enter email FROM address: alerts_sender_alias@yourcompany.com
Enter email TO address: alerts_manager_alias@yourcompany.com

201:created

From now on any changes in the availability of this resource will generate an email alert. Other alert types can be added as required.

Specifying a port for SNMP Alerts

As of v2.3.1, the SNMP management station port number can optionally be included in the SNMP management station address. To do this, append the port to the ip address separated by a comma. For example to send alerts to address 10.254.254.110 on port 1234:

hamonitor alert snmp create --id 1
Enter SNMP manager address: 10.254.254.110,1234
201: Created

If no port is specified, the default port 162 will be used.