Upgrade 3.18

en | ru

Version: 3.18

Version required: 3.10 and above

A few words from the author - version features

• A lot of work has been done and especially we have tried to emphasise on fine-tuning all sorts of little things. Please read the list of changes thoughtfully.

• Please take a look at the "Hot keys" page.

• Version 3.18 declares obsolete sections:
  • "Application for connection". In version 3.19, the section will be removed. Use the "API" section to organise receiving applications and creating tasks
  • "General commutation scheme". In version 3.19, the section will be removed. Use the "Commutation schemes" section in your work

• Upgrade. Recommended to have two instances of the system. A separate running one and a separate test one. On the test one you can periodically update the database from the live system and perform updates to make sure everything is working, familiarise yourself with innovations or identify things that have stopped working for you.

• Our group in Telegram for mutual communication between clients: https://t.me/usersideeu and a channel for news: https://t.me/userside

Features of the upgrade

When upgrading in a Docker environment, refer to instructions in the Docker bundle repository.

• If you are upgrading from version 3.10 - check out the page: Upgrade 3.11

• If you are upgrading from version 3.11 and earlier - check out the page: Upgrade 3.12

• If you are upgrading from version 3.12 and earlier - check out the page: Upgrade 3.13

• If you are upgrading from version 3.13 and earlier - check out the page: Upgrade 3.14

• If you are upgrading from version 3.14 and earlier - check out the page: Upgrade 3.15

• If you are upgrading from version 3.15 and earlier - check out the page: Upgrade 3.16

• If you are upgrading from version 3.16 and earlier - check out the page: Upgrade 3.17

• Version 3.18 requires PHP version 8.1. You can install all the necessary packages in addition to your existing different PHP version. If you are using LDAP, also install php8.1-ldap. If you are using TurboSMS, install php8.1-soap.

sudo apt install -y php8.1-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

• If php8.1 is not in your repository, use an alternative repository such as deb.sury.org by adding it to your system as follows and then repeating the PHP8.1 installation command above:

sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

• Change the PHP configuration as follows and restart the php-fpm service.

Note that if your time zone is Europe/Kiev, then instead of $(cat /etc/timezone) You must write Europe/Kyiv. Debian 11 has not yet made the time zone renaming changes, while PHP 8.1 has already made the changes.

sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_input_time.*@max_input_time = 300@" /etc/php/8.1/fpm/php.ini
 
sudo systemctl restart php8.1-fpm

• In NGINX, change the PHP version used for the updated copy of USERSIDE. If you followed the system installation instructions, in /etc/nginx/conf.d/default.conf or userside.conf or whatever you used to configure userside, change the line:

fastcgi_pass  unix:/run/php/php7.4-fpm.sock;

per line

fastcgi_pass  unix:/run/php/php8.1-fpm.sock;

and reread the nginx configuration:

sudo nginx -s reload

• Note that when the command is invoked php from the command line, php8.1 will now be called, since it is the latest version installed. If you're still using php7.4 anywhere, you'll need to change the php call in those places or change the alternate php command to run the version you need.

• USERSIDE 3.18 requires Python3 of any currently supported version. The status of versions can be viewed here:"Status of Python versions". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to install additionally a more recent version of Python.

• Stop the supervisor and all services under its control:

sudo systemctl stop supervisor

• The console script that runs various commands from the command line is now named run instead of userside. You need to change the launch command everywhere from php /var/www/userside/userside to php /var/www/userside/run.
  • In the file /etc/cron.d/userside you need to replace the line:

* * * * *   www-data   /usr/bin/php /var/www/userside/userside cron > /dev/null

per line:

* * * * *   www-data   /usr/bin/php /var/www/userside/run cron > /dev/null

• • In the file /etc/supervisor/conf.d/us-core-worker.conf you need to replace the line:

command=/usr/bin/php /var/www/userside/userside queue/listen

per line:

command=/usr/bin/php /var/www/userside/run queue/listen

• The RabbitMQ user used by USERSIDE needs to be given monitoring privileges so that USERSIDE can monitor the operation of the server. To do this, execute (assuming your user name is userside):

sudo rabbitmqctl set_user_tags "userside" "monitoring"

If you are using a vhost other than the root (default), you should also add the appropriate option, e.g. for vhost copy:

sudo rabbitmqctl --vhost copy set_user_tags "userside" "monitoring"

• Remove rudimentary queues:

sudo rabbitmqctl delete_queue userside.core
sudo rabbitmqctl delete_queue userside.microservice.poller

• Use the automatic installer to perform an upgrade:

sudo -u www-data php userside_install.phar install

• The following action only needs to be performed if you updated Python. If you haven't updated, you don't need to do it:

sudo rm -rf /var/www/userside/microservice/poller/venv
sudo python3.11 -m venv /var/www/userside/microservice/poller/venv

• It is necessary to update (install) the dependencies for poller:

cd /var/www/userside/microservice/poller
sudo venv/bin/pip3 install --upgrade pip
sudo venv/bin/pip3 install -U -r requirements.txt

• Note that as of version 3.18, background services do much of the work of interacting with network hardware. Start the supervisor:

sudo systemctl start supervisor

And make sure that all services start and run correctly (RUNNING):

sudo supervisorctl status

You should see 5 instances of the us-poller service and 10 instances of the us-core-worker service, or the number you have specified yourself in the supervisor configuration files.

• As of version 3.18, instead of satellite modules (usm_satellite) installed on remote nodes to proxy hardware communication commands, the exact same pollers are now used as in the system kernel, but with the mandatory "setellite" identifier in the settings. Be sure to review the steps required to switch from usm_satellite to usm_poller in the appropriate section.

• In version 3.18, we've reworked the database structure a lot. Both the basic schema and the names of all tables, almost all fields and, often, the types of these fields have changed. Firstly, updating can take a long time, and secondly, if you used direct reading from the database - all this needs to be reworked.

• Reworked low-level hardware polling (FDB, ARP, interface polling, etc). All of this is now done by kernel pollers. After the update, check if FDB tables and other polling works.

• Customers' labels are combined with common labels in the system. Accordingly, in the configuration files of billing interaction modules (or in the API) it is required to change the IDs of labels to new ones (if you use it). For example, for the usm_utm5 module this is the $markMerge variable

• Removed JABBER interaction. Use the "Custom HTTP request" notification service or Messenger (Telegram).

• If you have not yet reconfigured the to the new system - do so. In version 3.18, $zapikey is removed and the API key will stop working for those who have not reconfigured.

• If in version 3.17 you still haven't configured WebSTOMP, you need to do so or parts of the system will stop working

• Don't forget to update all modules to their latest versions

• In the poller (usm_poller), which is now used to interact with the hardware, one community is used for authentication in SNMP v1 and v2. But in the USERSIDE user interface, two fields (ro and rw) are left for now for backward compatibility. Which of the values will be used is described below in the algorithm for selecting a single SNMP-community. To simplify this for you, you can use the same community for the two fields. For example, if you want to give Userside read-only access, then enter the read-only community in both fields (ro and rw). If you want to grant full access, then also enter the same community with full permissions in both fields. It is also worth considering that the blank field will be filled in from the global Userside settings.

List of Changes: view

Performing the upgrade: instruction