Usm satellite EN

en | ru

Description

The usm_satellite external module is a proxy for making network requests to equipment on networks where nodes cannot be accessed directly from USERSIDE or are significantly difficult to access. usm_satellite also solves the problem of high latency for time-hungry requests such as icmp-ping.

The usm_satellite front-end communicates with the USERSIDE system via the http (https) protocol. That is, from the USERSIDE interface side it represents WEB-API. USERSIDE accesses the module via the http protocol, passes commands to it and receives the results of these commands. The usm_satellite module, having received a command via http from the USERSIDE system, executes it by communicating with the network equipment via icmp, snmp protocols, either by directly accessing the equipment or by executing console commands such as ping, arp, telnet.

Requirements

• USERSIDE 3.13+
• PHP 7.0+
• PHP-extensions: mbstring, json, snmp

Manual installation on the server

This section describes how to install the module on the server operating system. If you prefer to run the module as a Docker container, please refer to the corresponding section below.

Any server on any operating system that runs a WEB server and a PHP interpreter together will be suitable for running the module. It can be Apache + PHP or Nginx + PHP-FPM or any other web server with PHP. The server only requires WEB-server, RNR interpreter version not lower than 7.0 and RNR-extensions: php-mbstring, php-snmp, php-json. The module can be placed either in a separate virtual host, or simply in a subdirectory of an existing host (site) hosted on this server.

Download the archive with usm_satellite module from your personal cabinet, copy it to the server and unzip it. As a result you will get a catalogue with files. This directory should be moved to a convenient location on your web server.

It is also strongly recommended to restrict access to this catalogue via http only from the IP address from which USERSIDE will connect to it. Another important condition is to configure the WEB server in such a way that it is impossible to view the contents of directories and files via http.

If this is your first installation, go to the config directory and make a copy of the config-example.php file named config.php. Now open the config.php file with any convenient editor, think up (or better yet, generate) a long complex access key for this satellite and write it into the 'key' variable of this file. The key should be at least 8 characters, among which should be both letters and numbers. It is better if it is a randomly generated hash of at least 32 characters. There you can also change the path to the log files, if necessary.

To generate the access key, you can use any of the following methods, or whatever you prefer. Don't forget to change the passphrase in the commands below:

echo "my complex passphrase" | sha256sum
echo "my complex passphrase" | sha1sum
pwgen -s 32 1

Functionality check

Now simply open the URL that accesses usm_satellite in your browser. You should see an authentication error that looks like this:

{
  "code": 401,
  "name": "Unauthorized",
  "message": "Invalid authentication. Access keys do not match."
}

If you see this error message, then everything is configured correctly. You should see the same error message in the log file (by default, if you have not changed its location, it is located in the log directory).

2021-10-15 15:10:08|1.1|ERROR  |401| SatelliteException[Unauthorized]: Invalid authentication. Access keys do not match.

Startup using Docker

Instead of installing and configuring the WEB server, PHP, extensions and everything else, you can use a ready-made Docker image.

Installation

If you haven't installed Docker yet, you can do so in the following way:

sudo curl -fsSL get.docker.com -o get-docker.sh && sh get-docker.sh

The following steps create a docker group and add the current system user to it (so that the current user has full access to Docker). You can skip these steps if you don't need to, but then you will have to run all commands as superuser (via sudo):

sudo groupadd docker
sudo gpasswd -a $USER docker
newgrp docker

Next, you need to create a directory for the module logs:

sudo mkdir -p /var/log/usm_satellite && sudo chmod 777 /var/log/usm_satellite

Now start the container as follows (instead of access_key_here, specify your desired module access key):

docker run -d --name usm_satellite \
    --restart always \
    -e API_KEY=access_key_here \
    -p 8080:8080 \
    -v /var/log/usm_satellite:/app/log \
    -v /etc/localtime:/etc/localtime:ro \
    -v /etc/timezone:/etc/timezone:ro \
    erpuserside/usm_satellite

This configuration will use port 8080 on the server for translation to the container. If you need a different port, such as the default port 80, then change the parameter as follows (port 8080 on the right should remain the same):

-p 80:8080 \

If you would like usm_satellite to be available only on a specific interface, specify its IP address as follows:

-p 203.0.113.12:80:8080 \

If there should be several such interfaces - add another parameter -p

-p 203.0.113.12:80:8080 \
-p 192.168.1.10:80:8080 \

• The \ characters at the end are service characters and are needed to indicate that the command continues on the next line rather than terminating.

You can use nginx as ssl frontend if you need to provide https access.

The container will be automatically started when the server starts, and restarted if there is any internal failure.

Maintenance

The module logs are written to the directory that is connected to the container. In the example above, this is the directory /var/log/usm_satellite. A module log file named usm_satellite.log is created there. The logs are rotated automatically once a week and the last 4 files are saved.

When debugging, you may need to write debugging information to the module log. To do this, stop the container:

docker stop usm_satellite

And then run it again by adding another environment variable to the command parameters above:

-e LOG_SERENITY=debug \

When debugging is complete, it is advisable to restart the container without this parameter, because otherwise too much information will be written to the log.

In addition to the module log, there are also logs of the container's system processes (nginx, fpm, supervisor, etc.) - they are output to the standard container output (stdout + stderr) as required. Since the above command runs the container in the background, these logs can be viewed with the command:

docker logs usm_satellite

Or, if you need to monitor logs, then:

docker logs usm_satellite -f

If you run the container out of the background, system logs will be output to the console.

Upgrading the module version

To upgrade, run the following commands:

docker stop usm_satellite
docker rm usm_satellite
docker pull erpuserside/usm_satellite

Then start the container again as shown above.

Deleting a container

If you need to delete a container and its associated image, then execute:

docker stop usm_satellite
docker rm usm_satellite
docker rmi erpuserside/usm_satellite

Setup in USERSIDE

See: Satellites