Upgrading to the next version

Before starting the upgrade, it is recommended to create a backup: either a snapshot of the virtual machine (if NAICE is deployed in a virtualization environment) or an archive of the NAICE installation directory (default: /etc/docker-naice).

Updating within the same version is described in the instruction: v1.1_3.7.1 Updating within the same version.

General update principle

In general, upgrading to the next version requires rerunning the installation using the Ansible playbook of the target version according to the installation instructions over the existing installation.

If any variables in group_vars/all.yml have been modified, the variable values from the old all.yml file must be transferred to the new one before installation.

NAICE installation directory — change the value if a different installation directory was previously used:

naice_docker_path: /etc/docker-naice


Specify the current NAICE operating time zone:

time_zone: "Etc/UTC"


If periodic computer password rotation is used for interaction with Active Directory, specify the previously configured variable values:

ursus_netlogon_change_pass_cron: '-'
ursus_netlogon_change_pass_cron_node1: '-'
ursus_netlogon_change_pass_cron_node2: '-'
ursus_netlogon_change_pass_length: 12


If an Offline ELM server is used, specify the previously configured server address and proxy server values (if a proxy server connection is used):

elm_server_url: https://elm.eltex-co.ru:8099
elm_proxy_host: ""
elm_proxy_port: ""
elm_proxy_login: ""
elm_proxy_password: ""


If a custom certificate was previously added for EAP-PEAP authentication, add the certificates and key, and configure the variables according to the instruction Replacing default certificates for EAP-PEAP operation.

If a custom certificate was previously added for EAP-TLS authentication, add the certificates and key, and configure the variables according to the instruction Adding certificates for EAP-TLS operation.


If the configuration of container subnets was previously modified manually to use specific subnets, this part of the configuration must be copied from the docker-compose.yml container configuration file and transferred to the template file used by the Ansible playbooks during installation: ansible/roles/docker/templates/docker-compose.yml.j2. Specify the required subnets at the end of this file:

ansible/roles/docker/templates/docker-compose.yml.j2
networks:
  unmasked:
    name: naice-network-unmasked
    driver: bridge
    driver_opts:
      com.docker.network.bridge.enable_ip_masquerade: "false"
    ipam:
      config:
         - subnet: "172.22.0.0/20"
          ip_range: "172.22.8.0/21"
          gateway: "172.22.0.1" 

  external:
    driver: "bridge"
    driver_opts:
      com.docker.network.bridge.name: "external"
    enable_ipv6: false
    external: false
    internal: false
    ipam:
      driver: "default"
      config:
        - subnet: "172.20.0.0/20"
          ip_range: "172.20.8.0/21"
          gateway: "172.20.0.1"
    name: "external"

  internal:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: "internal"
    enable_ipv6: false
    external: false
    internal: true
    ipam:
      driver: "default"
      config:
        - subnet: "172.21.0.0/20"
          ip_range: "172.21.8.0/21"
          gateway: "172.21.0.1"
    name: "internal"



To update across multiple versions, perform the updates sequentially to each latest intermediate version before the target version.

Specifics of updating from version 1.1 to version 1.1.1

Perform the update preparation according to the instruction General update principle.

Stand-alone installation

Perform the installation according to the instruction: v1.1_3.2 Installation using Ansible playbooks (stand-alone).

After the update, execute the following command:

sudo docker exec -it naice-postgres psql -U postgres -c "ALTER DATABASE aquila REFRESH COLLATION VERSION;ALTER DATABASE bubo REFRESH COLLATION VERSION;ALTER DATABASE lemmus REFRESH COLLATION VERSION;ALTER DATABASE lepus REFRESH COLLATION VERSION;ALTER DATABASE mustela REFRESH COLLATION VERSION;ALTER DATABASE ovis REFRESH COLLATION VERSION;ALTER DATABASE phoca REFRESH COLLATION VERSION;ALTER DATABASE postgres REFRESH COLLATION VERSION;ALTER DATABASE repmgr REFRESH COLLATION VERSION;ALTER DATABASE template1 REFRESH COLLATION VERSION;ALTER DATABASE ursus REFRESH COLLATION VERSION;"

High-availability installation

Perform the installation according to the instruction: v1.1_3.3 High-availability installation (using VRRP) or v1.1_3.4 High-availability installation (without using VRRP).

As part of this patch, it is necessary to execute the PostgreSQL database installation playbooks first and then the NAICE installation playbooks sequentially, since a new database version has been released.

Ensure that the first PostgreSQL cluster node is the primary node and execute the following command:

sudo docker exec -it naice-postgres-1 psql -U postgres -c "ALTER DATABASE aquila REFRESH COLLATION VERSION;ALTER DATABASE bubo REFRESH COLLATION VERSION;ALTER DATABASE lemmus REFRESH COLLATION VERSION;ALTER DATABASE lepus REFRESH COLLATION VERSION;ALTER DATABASE mustela REFRESH COLLATION VERSION;ALTER DATABASE ovis REFRESH COLLATION VERSION;ALTER DATABASE phoca REFRESH COLLATION VERSION;ALTER DATABASE postgres REFRESH COLLATION VERSION;ALTER DATABASE repmgr REFRESH COLLATION VERSION;ALTER DATABASE template1 REFRESH COLLATION VERSION;ALTER DATABASE ursus REFRESH COLLATION VERSION;"

General actions after the update

Reinstall the security certificates (if custom certificates were previously installed).

Specifics of updating to version 1.1

Updating from version 0.9 requires a sequential update through version 1.0.

Before updating to version 1.1, all containers must be stopped and all Docker networks previously created during the NAICE deployment must be removed.

Stand-alone installation

For a stand-alone installation, open the installation directory (default: /etc/docker-naice) and execute the following commands:

# Stop the containers
sudo docker compose down

# Ensure that no containers are running
sudo docker compose ps -a
NAME                COMMAND             SERVICE             STATUS              PORTS

# Remove all created Docker networks
sudo docker network prune
WARNING! This will remove all custom networks not used by at least one container.
Are you sure you want to continue? [y/N] y
Deleted Networks:
naice-network

Perform the installation according to the instruction: v1.1_3.2 Installation using Ansible playbooks (stand-alone).

High-availability installation

For a high-availability installation, it is necessary to stop the containers running the NAICE services and the PostgreSQL database.

First, stop the NAICE services. To do this, open the installation directory (default: /etc/docker-naice) on each NAICE node and execute the following:

# Stop the containers
sudo docker compose down

# Ensure that no containers are running
sudo docker compose ps -a
NAME                COMMAND             SERVICE             STATUS              PORTS

Then stop the PostgreSQL database cluster on each node. To do this, open the installation directory (default: /etc/docker-naice) on each database node and execute:

# Stop the database container
sudo docker compose -f docker-compose.repmgr.yml down

# Ensure that the container is not running
sudo docker compose -f docker-compose.repmgr.yml ps -a
NAME      IMAGE     COMMAND   SERVICE   CREATED   STATUS    PORTS

Execute the following command on all nodes where the NAICE services and the PostgreSQL database cluster are deployed:

# Remove all created Docker networks
sudo docker network prune
WARNING! This will remove all custom networks not used by at least one container.
Are you sure you want to continue? [y/N] y
Deleted Networks:
naice-network

Otherwise, the following error may occur:

[ems@naice docker-naice]$ docker compose up -d
[+] up 2/2
 ✔ Network internal Created                                                                                     0.0s
 ✘ Network external Error Error response from daemon: cannot create network 91dd2efc95b3a15915a979379f5bc9...   0.0s
failed to create network external: Error response from daemon: cannot create network 91dd2efc95... (external): conflicts with network ba1d160c56... (br-ba1d160c5655): networks have overlapping IPv4

Perform the installation according to the instruction: v1.1_3.3 High-availability installation (using VRRP) or v1.1_3.4 High-availability installation (without using VRRP).

Actions after the update

Security certificates (if custom certificates were previously installed)

If third-party security certificates had previously been installed for the user interfaces (web interface, portal), they must be restored after the update according to the instruction: v1.1_3.6 Using security certificates

Configuration manager

Version 1.1 introduced a new service called Phoca (configuration manager), which allows configuring certain system parameters through the web interface that were previously configured using environment variables. The configurations are now stored in the database.

During the update from version 1.0 to 1.1, the values of some variables will be transferred to the corresponding database. These variables include:

  • SYSTEM_LOCALE
  • RADIUS_AUTH_PORT
  • OVIS_SESSION_TO_DELETE_HOURS
  • AQUILA_TACACS_PORT
  • AQUILA_SESSION_TO_DELETE_DAYS, AQUILA_ACCOUNTING_TO_DELETE_DAYS
  • MUSTELA_EVENTS_TO_DELETE_DAYS
  • ELM_SERVER_URL, ELM_PROXY_HOST, ELM_PROXY_PORT, ELM_PROXY_LOGIN, ELM_PROXY_PASSWORD
  • URSUS_ADMIN_PASSWORD_LENGTH

To preserve custom values, these variables were not removed from the version 1.1 installation scripts. They will be removed in version 1.2.

The <service_name>_LOGGING_LEVEL variables were replaced with a common logging level setting for all services: SERVER_LOGGING_LEVEL.

Configuration of the corresponding system parameters is now performed in: v1.1_5.2 System settings.

User authorization by group from an external source using the CUSTOM scheme

In version 1.1, the mechanism for retrieving groups from an external source was changed. Previously, groups were searched using the attribute specified in Group name attribute. Now group processing is performed using the DN (Distinguished Name) attribute to eliminate cases where multiple groups with the same name are retrieved from different branches of the directory tree.

If groups had previously been imported from an external source, they must be deleted and imported again after the update using the new format. New group import format: the group DN without the part matching the source Group search base.

If groups from the source were used in authorization policy conditions, they must first be removed from the logical conditions before deleting the groups.

During editing, it is recommended to switch the policies to the “Condition check” mode and return them to “Enabled” only after all changes to conditions and groups have been completed.

Captive Portal and SMS gateway

Version 1.1 introduced integration with a mail server. As a result, the ${phoneNumber} variable name was changed. This variable is used in the portal settings (Guest portals → Portal management → Portal builder) on configuration page 3 in the Login via SMS setting. During the update to version 1.1, this variable will be updated automatically from ${phoneNumber} to ${target}.

If an SMS gateway integration is configured in the section Notification Gateways → Gateway Management, it is necessary to manually replace the ${phoneNumber} variable with ${target} after the update to preserve compatibility with the portal settings.

PostgreSQL database cluster (high-availability deployment)

v1.1_3.7.2 Updating pg_hba.conf in version 1.1

  • Нет меток