• Impex
  • Documentation
  • Installation instructions for the Impex family

Installation basics

Installation media can be downloaded from https://portal.sysctl.se as an ISO-file for every installation type or an Azure image for the ICC server. The installation supports only installation from ISO and not any kind of images with the exception for Azure image. Only the ICC server can be installed on Azure cloud infrastructures Azure.

Getting the installation media

All Impex products can be installed from ISO, the example below is for the ICC ISO but the procedure is the same for all products.

Download the ICC ISO from https://portal.sysctl.se and verify the SHA256 checksum

sha256sum sysctl-icc-5.0.0.iso

or on Windows system using powershell:

Get-FileHASH sysctl-icc-5.0.0.iso

Most common is to install the servers in a virtualization environment, but it is also possible to install the software on physical hardware. The USB Protect is always installed on physical hardware.

Use the Linux command dd to add the iso to a USB-device, this is most common for the USB Protect installation

dd if=sysctl-usbprotect-5.0.0.iso of=/dev/sdX bs=4096

Note: replace sdX above with the actual device. Probably it is sda but please verify since using the incorrect device here could lead to irreparable harm to your computer.

It may also be possible to burn it with tools like rufus, but ensure the tool uses dd-mode.

Installation from the installation media

All installations are unattended and require only the root password to be configured with exception for USB Protect which does not have any static root password.

Installation in virtual environments

The software and installation media requires EFI enabled virtual hardware to boot. This must be configured before the installation starts.

USB Protect installation instructions

Before you begin, contact SYSCTL to obtain the UEFI password for your USB Protect hardware.

  1. Press “F12” to access the boot menu and select the option to boot from the USB.
  2. Enter the UEFI password when prompted.
  3. The installation will proceed automatically without further input.

If a USB Protect upgrade is necessary, follow the same procedure outlined above. The installation will preserve the current configuration and apply it after the new installation. If you need to erase the old configuration as well, interrupt the installation process and restart it. This works because, after collecting the old settings from the hard drive, the system clears the disk. When the installation is restarted, it proceeds with a fresh configuration.

To connect the station to an ICC server, refer to the USB Protect user manual for detailed instructions.

To set the station in offline mode, refer to the USB Protect user manual for detailed instructions.

Installation steps for ICC, Repo and DataLock

Choose the correct ISO for your installation and if needed, create a bootable USB. Boot the system from the installation media.

The installation will start to install after 60 seconds if no option is selected.

Boot menu for an ICC installation

After one of the options has been selected the installation will begin and the harddrive will be wiped. If the ICC or Repo has been selected it will be possible to set the root password during the installation. If it is a USB Protect installation will the system automatically look for a previous installation and copy the configurations from the old installation. If this is not the desired action one can abort the installation after it created a new filesystem and then boot again on the installation USB drive. This time the system disk will have been wiped and no previous configuration files will be found, making this a new clean installation.

Set a password for the root user if this is an ICC, REPO or Datalock installation.

Set root password

After the installation is completed, press enter to reboot.

Finish installation

Azure

Get the installation image

Download the Azure image from https://portal.sysctl.se

Azure configuration

Create a storage account

Create Storage Account

In the storage account, go to Containers

Storage Account Container

Create a new container

Storage Account Create Container

Upload the VHD-file to a Storage account under Data storage - Containers

Storage Account Upload Container

Go to Virtual machines and click on Create and select Azure virtual machine

Virtual machines Create New

The following configuration works with the image

  • Subscription: Your subscription
  • Subscription - Resource group: The resource for the image
  • Virtual machine name: ICC or similar
  • Image: The container image that was uploaded
  • VM architecture: x64
  • Size: 2vcpu 16GiB memory
  • Authentication type: SSH public key or Password
  • Public inbound ports: Depends on the installation architecture
  • OS type: Linux
  • VM generation: Gen 2
  • Storage blob: the uploaded VHD-file
  • Host caching: Read/write
  • License type: Other

Expand the disk

Go to the Virtual machine and select Settings -> Disks and the click on the Disk name

Virtual machines Select Disk

Select Settings -> Size + performance and select a larger disk and save

Virtual machines Select Large Disk

Start the Virtual machine

Virtual machines start

Initial configuration

These steps are only needed for the ICC, Repo and Datalock installations. One needs to configure IP addresses to allow SSH connection for the configuration of the Impex solution.

Log in to the console using the root user and the root password specified during installation.

Once logged in, the follows steps need to be done:

  • Configure IP address
  • Expand the disk
  • Set the hostname
  • Install a certificate

Console logins

IMPEX Configuration tool

Since certificate installation may require more complex configurations this must be a manual process. To create a certificate see the Manual Configuration.

Everything else can be configured with a built-in interactive tool:

/root/configuration.py

The tool is menu-driven. You can configure IP settings, set the hostname, manage upstream ICC server settings, run network tests, and expand LVM partitions. Tests are included to quickly validate connectivity.

Available options vary by server installation

Use the number keys to select actions. Press CTRL+C during any step to safely abort and return to the current menu.

What it can do

  • Configure static IPv4/IPv6
  • Show configuration status
  • Set system hostname
  • Configure upstream ICC server and optional proxy
  • Run network tests
  • Expand LVM partitions interactively

Main menu

Configure IP (sub-menu)

  • Set persistent IPv4/IPv6 on the default (or chosen) interface:
    • Validates IPs/prefix/gateways
    • Writes the configuration to the system and apply the configuration

Status (sub-menu)

  • Status: shows hostname, default IPv4/IPv6, gateway, DNS, DNF proxy, ICC, and any icc lines in /etc/hosts
  • Advanced Status: prints hostnamectl; ip -4/6 addr & route; keyfile summaries; ICC/proxy; /etc/hosts

Set system hostname

  • Sets the hostname, After success, if either of these:
    • Repo Installation you’ll be asked whether to regenerate IMPEX certificates: Removes all files in /opt/sysctl/impex-server/etc/apache/certs/ and restarts the service
    • ICC Installation you’ll be asked whether to regenerate IMPEX certificates: Removes all files in /opt/sysctl/impex-server/etc/apache/certs/ and restarts the service

Expand partitions (sub-menu)

  • A guided flow for LVM expansion: Prints PV free space from pvs (in GB)
  • Lists all LVs (lvs) with VG/LV/path/size
  • You choose the LV and enter how many GB to add

Configure Upstream ICC server

  • Writes the upstream ICC server configuration
  • Optional ask for proxy configuration
  • Optional ask for hosts mapping for ICC server

Repo in standalone mode

  • Configure the Repo server to be in standalone mode

Tests (sub-menu)

  • ICC connectivity (ignore TLS warnings)
  • ICC connectivity (verify TLS)
  • Default gateway reachability
  • ICC DNS resolution

Forget ICC configuration

  • Forget the current upstream ICC server configuration

Manual Configuration

Configure IP address

Configure the IP address in the file “/etc/NetworkManager/system-connections/enp1s0.nmconnection” with the VI text editor. The interface name “enp1s0” can be another name depending on the hardware.

Edit the ipv4 and ipv6 sections:

[ipv4]

method=manual

address=1.2.3.4/24

gateway=1.2.3.1

dns=8.8.8.8;8.8.4.4;

[ipv6]

method=disabled

IP configuration

After completing the configuration, restart the network service with the following command:

systemctl restart NetworkManager

Verify that the server is reachable with SSH.

Expand the disk

The default partition layout may vary depending on the installation type and how the system is used.

To see the current partition table use the command df -h

Depending on the usage, expand the root partition and the var partition. The following example will expand the partitions with 100Gb and will work for the most common installations

/usr/sbin/lvextend -r -L+100G /dev/mapper/root_vg-lv_root

/usr/sbin/lvextend -r -L+100G /dev/mapper/root_vg-lv_var

Set the hostname

The server needs to have a fully qualified domain name (FQDN) configured. The FQDN should reflect the subject alt name (SAN) in the certificate for the ICC and Repo server installation.

To configure hostname use the following command

/usr/bin/hostnamectl set-hostname servername.domain.tld

When the hostname has been configured, the ICC service impex-icc must be restarted by executing the following command

systemctl restart impex-icc

Install a Certificate

A trusted certificate is only needed for the ICC and Repo server. To create a certificate signing request, run the script

/opt/sysctl/impex-server/tools/cert.sh

In the examples below EPOCH and FQDN are variables that will differ in your setup. EPOCH is the number of unix seconds since 1970 and FQDN should be replaced with the full hostname and domain of your server. For example icc.internal.example.com.

The script will create a private key and a certificate signing request (CSR) file located in /root/pki/EPOCH/fqdn.{key,crt}

Copy the CSR and let the issuing CA sign the request.

Copy the /root/pki/EPOCH/FQDN.key to /opt/sysctl/impex-server/etc/apache/certs/FQDN.key

Add the signed certificate to /opt/sysctl/impex-server/etc/apache/certs/FQDN.crt. This file must also include intermediate CA certificates, sorted from leaf to root. This starts with the leaf and then the issuing CA certificate of the server certificate and must range up to the root CA certificate. The file must include the concatenation of the various PEM-encoded CA Certificate files, in certificate chain order.

The file must have the certificates in the following order:

  1. Leaf certificate (server certificate).
  2. Issuing certificates
  3. Root certificate

Ensure the /opt/sysctl/impex-server/etc/apache/conf.d/cert.d/cert.conf match the correct path to the certificates and private key.

SSLCertificateFile /opt/sysctl/impex-server/etc/apache/certs/FQDN.crt
SSLCertificateKeyFile /opt/sysctl/impex-server/etc/apache/certs/FQDN.key

Once the new certificate is installed, restart the web service with the following command

systemctl restart impex-server

Add Certificate Trust in ICC

The ICC server needs to trust the certificate authority used in the Repo server. To trust the certificate copy the root CA certificate to

/etc/pki/ca-trust/source/anchors/repo_ca.crt

then update the trust store with the command

update-ca-trust

Verify with curl that the Repo server is trusted by executing the command curl https://servername.domain.tld

Running Repo in Standalone Mode

The Repo server can be operate in standalone mode when upstream updates need to be downloaded and forward to isolated environments.

To enable standalone mode, run the following script on the Repo server:

/opt/sysctl/impex-repo/scripts/standalone.py

During execution, the script will prompt for:

  • Upstream repo username (required)
  • Upstream repo password (required)
  • Proxy (optional)

Once the script has completed, the Repo server will be running in standalone mode.

Connect a Datalock to the ICC

The DataLock server must be connected to a ICC server. By editing the file

/etc/dnf/dnf.conf

and adding the setting icc_server=https://hostname.domain.tld, according to the Subhect Alt Name in the certificate. The DataLock will connect to the ICC with TOFU (Trust On First Use) and store the root-certificate in the trust store. The DataLock will only do TOFU during the first initial connection to the ICC.

Configure the appliance

All other configurations must be done from the graphical web interface (https://fqdn). To login to the interface use the default user name admin and the pregenerated passsword which is saved in the file /root/icc_admin. Once logged in, the password can be changed and configuration can be made according to the ICC manual.

ICC backup and restore

Creating a backup

Select the “Backup” view on the left pane in the ICC.

Backup view

Click “Create backup” and then after a while, depending on how much data needs to be archived, the following view should appear.

Successful backup

Download the file, which will be called icc_backup.zip on disk when downloaded. This file contains ICC secrets so make sure that no one not authorized can access it.

Restoring a backup

Go to the “Backup” view, select the previously downloaded file in the “Restore” card and click “Restore”.

The file will then be uploaded and unpacked and verified by the ICC. If all is ok it will then continue to restart the ICC services. Since the database was replaced your login session will be cleared and you will need to login again with the password the account had during the time of the backup.

Successful restore

Migrating ICC to new server

A new machine needs to be installed from the ICC ISO and then a backup from the old ICC can be restored on the new ICC installation.

The steps are:

  1. Create a backup on the old ICC server
  2. Download the backup from the old ICC server. The archive contains secrets and must be well protected.
  3. Shutdown the old ICC
  4. Install the new ICC server, according to the installation guide.
  5. Update the IP configuration and hostname on the new ICC so it is identical to the old ICC
  6. Reboot the new ICC
  7. Login to the admin GUI on the new ICC server and go to backup view
  8. Select the previously backed up file in the Restore card and click “Restore”
  9. Verify that all the stations are still connected by checking the “Last seen” field on the station card. If not, contact SYSCTL support

The backup includes the database, ICC signify keys, logs, quarantined files, ssh keys, yara rules and TLS certificates.

If the migration is from a 4.x.x installation to a 5.x.x installation the repository configuration must be reconfigured, ensure to get the old username and password and potential proxy configuration stored in /etc/yum.conf

Note: The ICC server uses HSTS, this will deny users from accessing the web application on the newly installed ICC server until it has a trusted certificate. The trusted certificate will be restored from the backup which requires access to the web application. To circumvent this issue it is possible to use the browser’s privacy mode (called incongnito, inPrivate or private mode depending on the browser of your choice).

Doing a backup and downloading it

Select the “Backup” view on the left pane in the ICC.

Backup view

Click “Create backup” and then after a while, depending on how much data needs to be archived, the following view should appear.

Successful backup

Download the file, which will be called icc_backup.zip on disk when downloaded. This file contains ICC secrets so make sure that no one not authorized can access it.

Install a new ICC and restore the backup archive on it

Download the ICC iso from https://portal.sysctl.se, boot on it and install a new ICC. Ensure that the disk is large enough.

After the ICC is installed, go to the “Backup” view, select the downloaded file in the “Restore” card and click “Restore”.

The file will then be uploaded and unpacked and verified by the ICC. If all is ok it will then continue to restart the ICC services. Since the database was replaced your login session will be cleared and you will need to login again.

Successful restore

To verify all went well you can for example check that the Station cards have appeared in the Stations view.

Do the swap

If any error messages showed up in the backup or restore logs on the Backup view, contact SYSCTL support, do not proceed with the swap until you have cleared it with SYSCTL support.

Now that the data from the old ICC has been migrated to the new it is time to shut down the old ICC. After it has been shut down, change the IP address and hostname on the new ICC to finish the takeover. Reboot the new ICC and verify that the stations are able to communicate with the new ICC by checking the “Last seen” field on the station cards.

Troubleshooting

If you see “To access ICC you need to use a hostname, FQDN or ip configured in ALLOWED_HOSTS” message in your web browser when surfing to the new ICC you have not configured the IP or/and the hostname correctly. Doublecheck hosts files, IP configuration and hostname. To set a new hostname:

# hostnamectl set-hostname somename.example.org
# systemctl restart impex-icc