Sensor Management Docker Deployment

This article provides the installation requirements and procedures necessary to deploy a Cisco Crosswork Assurance Sensor Management Docker container.

Ubuntu Operating System

Procedure Requirements

Before beginning the installation, ensure your host system meets the following specifications:

A. Operating System & Hardware

• OS: Ubuntu 24.04.4 LTS
• CPU/RAM: refer to Sensor Management Docker Deployment Profile Configuration for usage planning
• Disk Space:
  • Docker Images (default /var/lib/docker): Minimum 30 GB of free space
  • Temporary Files (default /tmp): Minimum 15 GB of free space
  • Refer to Sensor Management Docker Disk Configuration for details on usage planning

B. Software Dependencies

• Docker: Minimum version 29.4.2
  • Verification: docker --version
  • Note: Using the Ubuntu Docker snap offered as an option during the Ubuntu installation is not supported. See Install Docker Engine on Ubuntu for the installation procedure.
• Docker Compose: Standalone version (docker-compose CLI), minimum version 5.1.2. See here for the installation procedure.
  • Verification: docker-compose --version
  • Important: The Docker Compose plugin (docker compose CLI) is not supported

C. System Configuration

• Privileges: Sudo or root access is required on the host.
• SSH: OpenSSH server must be installed and running. The Docker host must approve SSH connections using password authentication.
  • Verification: systemctl status sshd
• Multipath: The multipath-tools package must be installed and enabled.
  • Verification: systemctl status multipathd
• Security: Disable Secure Boot on the system.
  • Verification: mokutil --sb-state
• Drivers: Enable the overlay storage driver.
  • Verification: Run lsmod | grep overlay to confirm the module is loaded
• Hostname resolution: Configure the /etc/hosts file to include the Docker host's hostname mapped.
  • Example: "127.0.1.1 <the Docker host hostname>"
  • Note: The IP 127.0.1.1 can be substituted with a different server IP if required by your network policy
  • Find the hostname: Run the hostname command to identify the current system name

Reference Versions

The components listed below constitute the reference environment used for the development and validation during the development process. While other versions may be compatible, the versions specified here have been strictly verified for product functionality.

Note: Utilizing versions outside of those specified in the table above may result in functional inconsistencies. If you are operating in a different environment and encountering issues, contact the technical support team for further assistance.

Preinstallation Procedure

This procedure provides the necessary setup for Docker hosts running Docker version 29.4.2+ to disable containerd image store on Docker Engine before installing Sensor Management Docker.

1. Add the min-api-version flag to the Docker service configuration file /etc/docker/daemon.json:

{
  "features": {
    "containerd-snapshotter": false
  }
}

Note: If the daemon.json file already exists, ensure to merge this entry correctly with any existing configurations.

2. Reload the Docker daemon to apply the changes:

sudo systemctl daemon-reload

3. Restart the Docker service:

sudo systemctl restart docker

Procedure Steps

Follow the steps below to install Sensor Management Docker on a Docker host.

To install Cisco Crosswork Assurance Sensor Management on Docker host:

1. Using an SSH client, log in to your Docker host and execute the installation package on a host operating system (OS), where < version > in the name of the installation package is the version of Sensor Management Docker to be installed:

sudo sh docker-dist-<version>.sh

2. Confirm to proceed by typing y or Y as anything else will abort the installation.

3. When asked for the temporary installation folder, type Enter to use the /tmp folder or type the location of another temporary folder. A temporary subfolder, so_install, will be created during the installation and will be removed at the end of the installation.

4. When asked for Installing Cisco Crosswork Assurance Sensor Management with Hot Standby Redundancy (HA feature default: true)?

   1. Type y to install the Cisco Crosswork Assurance Sensor Management with Hot Standby Redundancy
   2. Type N to install the Cisco Crosswork Assurance Sensor Management with Non-Hot Standby Redundancy

5. The installation will create the user skylight and the group skylight on the host, if these do not already exist.

Notes:

• If the user is created during the installation, you will be asked to set up its password.
• The installation will create the home folder for the user skylight in /home/skylight.
• During the installation, Docker images are loaded from the installation package. The main user of these images (visionems or mysql, depending on the image) is reset to the host user 'skylight' UID and GID. This ensures that the user in containers has full access to the /home/skylight/so folders on the host, via mapped Docker volumes.
• A Docker network, "so-network", is also created, with a random subnet assigned by Docker daemon. The subnet can be changed later via Sensor Management Docker client.
• For the management of Sensor Management Docker, a climanager service is installed on the host: sm.climgr

Folder Structure

The installation will create the home folder for the user skylight in /home/skylight.

├── bin
├── config
│ ├── cib
│ ├── climgr
│ │ ├── greetings.txt
│ │ └── hostkey.ser
│ ├── deployment
│ │ └── deployment-user-config.properties
│ ├── domain
│ │ ├── admin-keyfile
│ │ └── keystore.jks
│ ├── gfclient
│ │ └── pass
│ ├── ha
│ │ ├── cib
│ │ ├── drbd-proxy.license
│ │ ├── generated
│ │ └── hamonitorconfig.properties
│ ├── snmp
│ │ └── storesnmpconfig.properties
│ └── ssh
│ │ └── known_hosts
├── data
├── docker
│ ├── core.compose.yaml
│ ├── ha.compose.yaml
│ └── so.env
├── lib
│ └── jdk -> /home/skylight/lib/jdk-17
├── logs
└── mysql
└── mysql-ha

The installation will also create the following Docker volumes that will point, by default, to the home folders of the skylight user:

• so-config → /home/skylight/so/config
• so-data → /home/skylight/so/data
• so-logs → /home/skylight/so/logs
• so-mysql → /home/skylight/so/mysql

Several files are persisted on the host:

• /home/skylight/<so_version>/bin = scripts for managing Sensor Management containers
• /home/skylight/<so_version>/docker = the docker-compose file, the environment file
• /home/skylight/<so_version>/config = the Sensor Management keystore, admin-keyfile and the ssh configuration for the Sensor Management application
• /home/skylight/<so_version>/logs = the logs of Sensor Management services
• /home/skylight/<so_version>/data = data used by Sensor Management (except the main database)
• /home/skylight/<so_version>/mysql = the main database
• /home/skylight/<so_version>/mysql-ha = where the main database is stored while the High Availability feature is enabled
• /home/skylight/so = symlink to the latest installed /home/skylight/<so_version>
• /home/skylight/<so_version>/bin/logs = the log of the CLI manager

IPv6 Connectivity

For Cisco Crosswork Assurance Sensor Management to be able to connect to devices on IPv6 networks, you must:

1. Add the following flags in the configuration of the Docker service on the host, in the file /etc/docker/daemon.json:

{
"ip6tables":true,
"experimental": true
}

2. To enable the change, reload and restart the Docker daemon:

sudo systemctl daemon-reload
sudo systemctl restart docker

3. Assign an IPv6 subnet to Sensor Management Docker containers. Open the Sensor Management client:

smcli.sh

4. Configure the subnet using the command config edit network subnet and specify an IPv6 subnet with the IPv6 option.

Example:

config set network subnet ipv4 <network/subnet mask> ipv6 <network/prefix>

Disabling IPv6 on the Docker Host

(OPTIONAL) If you must disable IPv6 on the Docker host, follow this procedure to avoid disrupting container functionality and ensure that Sensor Management continues to operate as intended.

Note: This method disables IPv6 at the sysctl level only. The IPv6 stack remains loaded, but no IPv6 addresses are assigned.

1. Access the Docker host via SSH on port 22.

2. Create a new sysctl configuration file by entering the following command:

sudo vim /etc/sysctl.d/90-disable-ipv6.conf

3. Add the following two lines to the file:

net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1

4. Apply the changes by entering:

sudo sysctl -p /etc/sysctl.d/90-disable-ipv6.conf

5. Reboot the Docker host:

sudo reboot

Changing the Greeting Message

The greeting message, displayed when opening the Sensor Management client (smcli.sh), can be changed by replacing the content of the file:

/home/skylight/so/config/climgr/greetings.txt

This file resides on the host and can be edited using sudo, or by opening a shell as user skylight. Ensure to not change the permissions of the file as this has to be readable by the user skylight (original file permissions are 770).

After the change, restart the Sensor Management client manager:

sudo systemctl restart sm.climgr.service

Changing Timezone Configuration

If operating in a Hot Standby configuration, stop the redundancy feature:

1. Open an SSH terminal session to the Sensor Management CLI on Site-A using port 2200.
2. Log in as the skylight user.
3. Stop the redundancy feature process by entering:

redundancy control stop

4. Configure the preferred site to last active site by entering:

redundancy config preferred {site-a | site-b}

To configure the timezone for Sensor Management in Docker Host:

Note: Perform this step at both sites when using the Hot Standby configuration.

1. Open an SSH terminal session to the Sensor Management on port 22.
2. Log in as a user with sudo privileges or as root.
3. Use timedatectl to configure the timezone:

sudo timedatectl set-timezone <timezone_value>

4. Update the timezone value in the /etc/timezone file.
5. Reboot the Docker host.

sudo reboot

If operating with the Hot Standby configuration, start the redundancy feature:

1. Open an SSH terminal session to the Sensor Management CLI on Site-A using port 2200.
2. Log in as the skylight user.
3. Start the redundancy feature process by entering:

redundancy control start

Red Hat Operating System

Procedure Requirements

Before beginning the installation, ensure your host system meets the following specifications:

A. Operating System & Hardware

• OS: Red Hat 9.6
• CPU/RAM: refer to Sensor Management Docker Deployment Profile Configuration for usage planning
• Disk Space:
  • Docker Images (default /var/lib/docker): Minimum 30 GB of free space
  • Temporary Files (default /tmp): Minimum 15 GB of free space
  • Refer to Sensor Management Docker Disk Configuration for details on usage planning

B. Software Dependencies

• Docker: Minimum version 29.4.2
  • Verification: docker --version
• Docker Compose: Standalone version (docker-compose CLI), minimum version 5.1.2. See here for the installation procedure.
  • Verification: docker-compose --version
  • Important: The Docker Compose plugin (docker compose CLI) is not supported

C. System Configuration

• Privileges: Sudo or root access is required on the host.
• Firewall: firewalld must be installed and running.
  • Verification: sudo dnf install firewalld -y
• SSH: OpenSSH server must be installed and running. The Docker host must approve SSH connections using password authentication.
  • Verification: systemctl status sshd
• Multipath: The device-mapper-multipath package must be installed and enabled.
  • Verification: systemctl status multipathd
• Additional packages: kernel-devel, json_pp utility (perl-JSON-PP) must be installed.
  • Verification: rpm -qa |grep kernel-devel
  • Verification: rpm -qa |grep JSON-PP
• Security: Disable Secure Boot on the system.
  • Verification: mokutil --sb-state
• Drivers: Enable the overlay storage driver.
  • Verification: Run lsmod | grep overlay to confirm the module is loaded
• Hostname resolution: Configure the /etc/hosts file to include the Docker host's hostname mapped.
  • Example: "127.0.1.1 < the Docker host hostname >"
  • Note: The IP 127.0.1.1 can be substituted with a different server IP if required by your network policy
  • Find the hostname: Run the hostname command to identify the current system name

Reference Versions

The components listed below constitute the reference environment used for the development and validation during the development process. While other versions may be compatible, the versions specified here have been strictly verified for product functionality.

Note: Utilizing versions outside of those specified in the table above may result in functional inconsistencies. If you are operating in a different environment and encountering issues, contact the technical support team for further assistance.

Preinstallation Procedure

This procedure provides the necessary setup for Docker hosts running Docker version 29.4.2+ to disable containerd image store on Docker Engine before installing Sensor Management Docker.

1. Add the min-api-version flag to the Docker service configuration file /etc/docker/daemon.json:

{
  "features": {
    "containerd-snapshotter": false
  }
}

Note: If the daemon.json file already exists, ensure to merge this entry correctly with any existing configurations.

2. Reload the Docker daemon to apply the changes:

sudo systemctl daemon-reload

3. Restart the Docker service:

sudo systemctl restart docker

Procedure Steps

Follow the steps below to install Sensor Management on a Docker host.

To install Sensor Management on Docker host:

1. Using an SSH client, log in to your docker host and execute the installation package on a host operating system (OS), where < version > in the name of the installation package is the version of Sensor Management to be installed:

sudo sh docker-dist-<version>.sh

2. Confirm to proceed by typing y or Y as anything else will abort the installation.

3. When asked for the temporary installation folder, type Enter to use the /tmp folder or type the location of another temporary folder. A temporary subfolder, so_install, will be created during the installation and will be removed at the end of the installation.

4. When asked for Installing Cisco Crosswork Assurance Sensor Management with Hot Standby Redundancy (HA feature default: true)?

   1. Type y to install the Cisco Crosswork Assurance Sensor Management with Hot Standby Redundancy
   2. Type N to install the Cisco Crosswork Assurance Sensor Management with Non-Hot Standby Redundancy

5. The installation will create the user skylight and the group skylight on the host, if these do not already exist.

Notes:

• If the user is created during the installation, you will be asked to set up its password.
• The installation will create the home folder for the user skylight in /home/skylight.
• During the installation, Docker images are loaded from the installation package. The main user of these images (visionems or mysql, depending on the image) is reset to the host user 'skylight' UID and GID. This ensures that the user in containers has full access to the /home/skylight/so folders on the host, via mapped Docker volumes.
• A Docker network "so-network" is also created, with a random subnet assigned by Docker daemon. The subnet can be changed later via Sensor Management client.
• For the management of Sensor Management, a climanager service is installed on the host: sm.climgr.service

Folder Structure

The installation will create the home folder for the user skylight in /home/skylight.

├── bin
├── config
│ ├── cib
│ ├── climgr
│ │ ├── greetings.txt
│ │ └── hostkey.ser
│ ├── deployment
│ │ └── deployment-user-config.properties
│ ├── domain
│ │ ├── admin-keyfile
│ │ └── keystore.jks
│ ├── gfclient
│ │ └── pass
│ ├── ha
│ │ ├── cib
│ │ ├── drbd-proxy.license
│ │ ├── generated
│ │ └── hamonitorconfig.properties
│ ├── snmp
│ │ └── storesnmpconfig.properties
│ └── ssh
│ │ └── known_hosts
├── data
├── docker
│ ├── core.compose.yaml
│ ├── ha.compose.yaml
│ └── so.env
├── lib
│ └── jdk -> /home/skylight/lib/jdk-17
├── logs
└── mysql
└── mysql-ha

The installation will also create the following Docker volumes that will point, by default, to the home folders of the skylight user:

• so-config → /home/skylight/so/config
• so-data → /home/skylight/so/data
• so-logs → /home/skylight/so/logs
• so-mysql → /home/skylight/so/mysql

Several files are persisted on the host:

• /home/skylight/<so_version>/bin = scripts for managing Cisco Crosswork Assurance Sensor Management containers
• /home/skylight/<so_version>/docker = the docker-compose file, the environment file
• /home/skylight/<so_version>/config = the Cisco Crosswork Assurance Sensor Management keystore, admin-keyfile and the ssh configuration for the Cisco Crosswork Assurance Sensor Management application
• /home/skylight/<so_version>/logs = the logs of Cisco Crosswork Assurance Sensor Management services
• /home/skylight/<so_version>/data = data used by Cisco Crosswork Assurance Sensor Management (except the main database)
• /home/skylight/<so_version>/mysql = the main database
• /home/skylight/<so_version>/mysql-ha = where the main database is stored while High Availability feature is enabled
• /home/skylight/so = symlink to the latest installed /home/skylight/<so_version>
• /home/skylight/<so_version>/bin/logs = the log of the CLI manager

IPv6 Connectivity

For Sensor Management to be able to connect to devices on IPv6 networks, you must:

1. Add the following flags in the configuration of the Docker service on the host, in the file /etc/docker/daemon.json.

{
"ip6tables":true,
"experimental": true
}

2. To enable the change, reload and restart the Docker daemon:

sudo systemctl daemon-reload
sudo systemctl restart docker

3. Assign an IPv6 subnet to Sensor Management Docker containers. Open the Sensor Management client:

smcli.sh

4. Configure the subnet using the command config edit network subnet and specify an IPv6 subnet with the IPv6 option.

Example:

config set network subnet ipv4 <network/subnet mask> ipv6 <network/prefix>

Disabling IPv6 on the Docker Host

(OPTIONAL) If you must disable IPv6 on the Docker host, follow this procedure to avoid disrupting container functionality and ensure that Sensor Management continues to operate as intended.

Note: This method disables IPv6 at the sysctl level only. The IPv6 stack remains loaded, but no IPv6 addresses are assigned.

1. Access the Docker host via SSH on port 22.

2. Create a new sysctl configuration file by entering the following command:

sudo vim /etc/sysctl.d/90-disable-ipv6.conf

3. Add the following two lines to the file:

net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1

4. Apply the changes by entering:

sudo sysctl -p /etc/sysctl.d/90-disable-ipv6.conf

5. Reboot the Docker host:

sudo reboot

Changing the Greeting Message

The greeting message, displayed when opening the Sensor Management client (smcli.sh), can be changed by replacing the content of the file:

/home/skylight/so/config/climgr/greetings.txt

This file resides on the host and can be edited using sudo, or by opening a shell as user skylight. Ensure to not change the permissions of the file as this has to be readable by the user skylight (original file permissions are 770).

After the change, restart the Sensor Management client manager:

sudo systemctl restart sm.climgr

Changing Timezone Configuration

If operating in a Hot Standby configuration, stop the redundancy feature:

1. Open an SSH terminal session to the Sensor Management CLI on Site-A using port 2200.
2. Log in as the skylight user.
3. Stop the redundancy feature process by entering:

redundancy control stop

4. Configure the preferred site to last active site by entering:

redundancy config preferred {site-a | site-b}

To configure the timezone for Sensor Management in Docker Host:

Note: Perform this step at both sites when using the Hot Standby configuration.

1. Open an SSH terminal session to the Sensor Management on port 22.
2. Log in as a user with sudo privileges or as root.
3. Use timedatectl to configure the timezone:

sudo timedatectl set-timezone <timezone_value>

4. Update the timezone value in the /etc/timezone file.
5. Reboot the Docker host.

sudo reboot

If operating with the Hot Standby configuration, start the redundancy feature:

1. Open an SSH terminal session to the Sensor Management CLI on Site-A using port 2200.
2. Log in as the skylight user.
3. Start the redundancy feature process by entering:

redundancy control start

Related Documentation

Migration Guides

Full Migration

• Migrate from Hot Standby Docker to Sensor Management Docker
• Migrate from Non-Hot Standby Docker to Sensor Management Docker
• Migrate from Hot Standby VM to Sensor Management Docker
• Migrate from Non-Hot Standby VM to Sensor Management Docker

Configuration Only

• Simplified Configuration-Only Migration from Hot Standby Docker to Docker
• Simplified Configuration-Only Migration from Non-Hot Standby Docker to Docker
• Simplified Configuration-Only Migration from a Hot Standby Virtual Machine to Docker
• Simplified Configuration-Only Migration from a Non-Hot Standby Virtual Machine to Docker

Additional Resources

• Configure User Authentication on Docker
• Sensor Management Docker CLI Reference