Linux: Install and Upgrade with CLI and VEN CTL

This section discusses installing and upgrading the VEN for Linux by using packaging technology commands and the VEN CTL.

  • Installing the VEN on Linux relies native package management commands:

    • For Debian and Ubuntu (referred to as “Debian”): dpkg

    • For Red Hat and CentOS (referred to as “Red Hat”): rpm

  • Root access on the workload is required for installation of the Linux VEN.
  • Some of the optional installation features in the RPM are not available with the Debian package. These cases are marked in section titles below with “RPM only.”

About iptables Versions for Red Hat and CentOS

Red Hat Version 6 VENs

If the iptables version already on the workload is older than iptables version 1.4.7-16 or ipsets is older than version 6.11-4, the VEN installation process installs more recent versions of iptables and ipset, including libmnl. These unmodified distribution files (RPMs) are packaged with the VEN itself and installed in /opt/illumio_ven/etc/extras.

About Red Hat 8 Support and nftables

In 18.2.x, the VEN supported iptables. In 19.3.0 and later releases, the VEN supports nftables, which is the default host-based firewall used by Red Hat 8. Supporting nftables, which is used by Red Hat 8, simplifies rule writing and allows developers to write fewer rules and do so much more efficiently. The new support for nftables does not change VEN functionality or the VEN feature set because the underlying net filter capabilities are the same. Support for nftables provides the following usability enhancements for the VEN:

  • Simpler syntax: Uses a simpler syntax, which is very similar to TCP dump.
  • Combined rules: Rather than write 2 rules for every enforcement point, you can combine them into a single rule; such as combining multiple ports into a single rule, and IPv4 and IPv6 into a single rule.
  • Multiple actions: A single rule can have multiple actions, such as LOG and DROP.
  • Built in tracing: Includes built-in support for named sets. To use lists or sets with iptables, you need to install ipset.nftables has integrated set support and can be used more naturally within the configuration.

Notes:

  • Native support for nftables in Red Hat 8 does not change the VEN installation or upgrade process; if you've written installation scripts, they don't require updates.
  • nftables does not impact Firewall Coexistence and it is still supported.
  • Using the nftrace tool on Illumio created tables is not supported because it requires specific filtering rules.
  • nftables support does not impact the PCE; viewing a workload that is running Red Hat 8 in the PCE web console does not change. You can view all the workload details. Creating policy for workloads running Red Hat 8 does not change.
IMPORTANT:

In 19.3.0 and later releases, the VEN continues to support earlier versions of Red Hat with no changes. For the complete list of Red Hat versions supported by the VEN by release, see OS Support and Package Dependencies on the Illumio Support portal.

Linux Default Installation Directories

The Linux VEN is installed into two directories by default:

  • /opt/illumio_ven
  • /opt/illumio_ven_data

Directory Ownership Pre- and Post-activation

  • All directories are created with mode 0750.
  • Post-activation user/group ilo-ven:ilo-ven allows processes running as that user to write to the VEN installation directory and VEN data directory.
  • At installation, you can set various environment variable to override default settings. See Linux Installation with Environment Variables.

VEN Package Format

Path

Default Pre-Activation Owner

Default Post-Activation Owner

RPM

 /opt/illumio_ven root:ilo-ven root:ilo-ven

 

 /opt/illumio_ven_data ilo-ven:ilo-ven ilo-ven:ilo-ven

DPKG

 /opt/illumio_ven root:ilo-ven root:ilo-ven

 

 /opt/illumio_ven_data root:ilo-ven ilo-ven:ilo-ven

Dependency Check for Certificates

If your PCE-to-VEN SSL certificate was signed by a private CA and the signing CA's credentials have already been added to the workload's trusted certificate store, the ca-certificates package is not needed. To install the VEN without the dependency check, follow these examples:

  • Red Hat: rpm -vh -nodeps illumio-ven-<ven_version>.<os_platform>.rpm
  • Debian: dpkg --ignore-depends=illumio-ven-<ven_version>.<os_platform>.deb

RPM Only: Installation in Non-Default Directory

If you want to change the installation directory during installation or upgrade, you can use environment variable or use the --prefix option on the RPM command line.

# rpm -ivh <illumio-ven-pkg>.rpm --prefix=/opt/foo/bar
CAUTION:

The Linux VEN does not support installing the VEN in a directory where the directory is a symbolic link.

Linux Installation with Environment Variables

The following table lists VEN environment variables that you can set for the package installation on Linux.

NOTE:
Before installation, set any of the following environment variables.

Variable

Description
VEN_ACTIVATION_CODE

The activation code; see Example: Linux Environment Variables and About the Command Options.
VEN_DATA_DIR

Directory where the illumio_ven_data directory is created.

This option can also be used when you are upgrading a VEN with RPM or Debian.
VEN_DISABLE_MONITOR_RESTART

Disable the VEN agent monitor process. See Disable Agent Monitor cronjob .
VEN_INSTALL_ACTION

Activate or prepare the VEN during installation. Valid values:

  • activate: Requires an activation code on the illumio-ven-ctl control script or set in the VEN_ACTIVATION_CODE environment variable.
  • prepare: Used to defer activation until after installation. For example, see Prepare Golden Image for Workload Installation.
VEN_KERBEROS_WORKLOAD_SPN

See Kerberos for Linux VEN-to-PCE Authentication.
VEN_KERBEROS_MANAGEMENT_SERVER_SPN

See Kerberos for Linux VEN-to-PCE Authentication.
VEN_KERBEROS_LIBRARY_PATH

See Kerberos for Linux VEN-to-PCE Authentication.
VEN_MANAGEMENT_SERVER

The FQDN of the PCE server and its port.
VEN_NONPRIV_UID

If VEN_NONPRIV_USER is not set, create the ilo-ven user with the specified UID.
VEN_NONPRIV_GID

If VEN_NONPRIV_USER is not set, create the ilo-ven group with the specified GID.
VEN_NONPRIV_USER

Existing username to override the default username ilo-ven. The group name of the specified user is the primary existing group name of the specified user.

  • If VEN_NONPRIV_USER is set, any values for VEN_NONPRIV_UID and VEN_NONPRIV_GID are ignored.
  • Conversely, if VEN_NONPRIV_USER is not set, any values for VEN_NONPRIV_UID and VEN_NONPRIV_GID take effect.
ILLUMIO_RUNTIME_ENV If ILLUMIO_RUNTIME_ENV is set, read the runtime_env.yml from this file path. This environment variable is unique because it is relevant during and after installation.

Kerberos for Linux VEN-to-PCE Authentication

The illumio-ven-ctl command does not have any options for Kerberos, but when you activate the VEN with illumio-ven-ctl, at installation it honors the Kerberos values that have been set in environment variables.

Before installing the Linux VEN, set the following environment variables.

Environment variable

Value

Notes
VEN_KERBEROS_WORKLOAD_SPN

(Optional) See notes.

The default host principal set in the Kerberos keytab file.

The SPN of the server for renewing Ticket Granting Tickets (TGT) for Linux workloads.

Format:

host/fqdn_of_ven@REALM

Where:

  • The literal host/ is required.
  • fqdn_of_ven is the FQDN of the workload where the VEN is installed.
  • @REALM is optional. If not specified, the default realm is used.

A workload might have more than one host principal in its keytab file, one of them the principal needed for PCE authentication. In this case VEN_KERBEROS_WORKLOAD_SPN must be set so that the VEN software knows which principal to use to acquire a TGT.

The VEN relies on the default Kerberos keytab file, typically /etc/krb5.keytab. Therefore, the host SPN for PCE authentication must be added to the default keytab file.

Before deploying Kerberos authentication, you can use kinit to verify that a TGT for the workload's SPN can be acquired:

kinit -k

If the command is successful, use klist to verify the TGT has been acquired for the correct host SPN.

If the default SPN is not what you want for PCE authentication, use the following command to verify that you can reach the desired SPN:

kinit -k host/fqdn_of_ven@REALM

If the command is successful, set VEN_KERBEROS_WORKLOAD_SPN to host/fqdn_of_ven@REALM.
VEN_KERBEROS_MANAGEMENT_SERVER_SPN

SPN for the PCE

Example: illumio-device-auth/pce.example.com

GSSAPI Authentication
VEN_KERBEROS_LIBRARY_PATH

Absolute path to libgssapi_krb5.so

Example: /usr/lib/libgssapi_krb5.so

The exact path can vary by type of Linux OS.

If libgssapi_krb5.so does not exist on your system, create a symlink of the same name to point to the libgssapi_krb5.so.n file, where n is the number on the actual installed shared object library on your workload, like libgssapi_krb5.so.2

Activation with Kerberos

On the illumio-ven-ctl --activate or in the pairing script, do not use any option that sets a label. That is, do not use the --env, --loc, --role, or --app options. Labels should be set in the PCE web console. See Labels and Label Groups in the Security Policy Guide for information.

After installation with the command-line variable, when you activate the VEN, a message similar to the following is displayed:

# illumio-ven-ctl activate

      Activating Illumio
... 
Enabling Kerberos Authentication .....
...

Example: Linux Environment Variables

To activate the VEN during installation, set the following environment variables before running the installation command.

  • VEN_MANAGEMENT_SERVER
  • VEN_ACTIVATION_CODE
  • VEN_INSTALL_ACTION

For example, to activate a VEN during installation of a VEN package:

# VEN_MANAGEMENT_SERVER=pce.example.com:8443 VEN_INSTALL_ACTION=activate VEN_ACTIVATION_CODE=<activation_code> rpm -ivh illumio-ven-<ven_version>.<os_platform>.rpm

Or

# VEN_MANAGEMENT_SERVER=pce.example.com:8443 VEN_INSTALL_ACTION=activate VEN_ACTIVATION_CODE=<activation_code> dpkg -i illumio-ven-<ven_version>.<os_platform>.deb

Change Default Name of User at Installation

The default username for the VEN installation is ilo-ven. With the package installation, you can specify an environment variable to set a different, existing username to override this default. The group name is the specified user's primary group and does not need to be specified.

# VEN_NONPRIV_USER=desired_existing_username rpm -ivh illumio-ven-<ven_version>.<os_platform>.rpm

Or

# VEN_NONPRIV_USER=desired_existing_username dpkg -i illumio-ven-<ven_version>.<os_platform>.deb

Disable Agent Monitor cronjob

You can disable the agent monitor cronjob before or after VEN installation. When failing to hook into existing init systems like systemd, upstart, or SysV, the Linux VEN installation creates a cronjob to check the VEN agent monitor process and restart it if necessary. This cronjob runs every 10 minutes.

Some organizations prefer to rely on their own VEN agent monitoring processes. The Illumio-supplied VEN-checking cronjob might create logs whose size you consider excessive or whose frequency is not right for your needs.

To disable the Linux VEN monitoring cronjob before installation:

Set the following environment variable:

export VEN_DISABLE_MONITOR_RESTART=true

Any value other than true does not have any effect.

To modify or disable the Linux VEN monitoring cronjob after installation:

You have several options:

  • Edit your crontab to decrease the cronjob's frequency.
  • In your crontab, completely comment out the VEN agent monitoring cronjob.

To substitute your own VEN agent monitor checking process, consider the following points:

  • Rely on your own organization's standard mechanisms for monitoring processes.
  • Make sure your monitoring restarts the VEN if necessary.

    • Do not restart only the VEN agent monitoring process. Restart the entire VEN:

      # illumio-ven-ctl restart
    • Be sure that your monitoring process has sufficient permissions to restart the VEN.

Linux VEN Activation After Installation

To activate the VEN after installation, use the illumio-ven-ctl control script with the activate argument to activate the workload and pair the VEN with the PCE.

At a minimum, to activate the VEN using the VEN control script, you need the hostname or IP address of the PCE, an activation code (called a pairing key in the PCE web console) generated from a pairing profile, and any other required options, such as the workload policy state, label assignment, and workload name. For example, the following command shows how to activate the VEN that places the workload into the Illumination policy state (--mode).

# /opt/illumio_ven/illumio-ven-ctl activate --management-server pce.example.com:8443 --activation-code <activation_code>

Upgrade Linux VEN Using CLI

IMPORTANT:

Illumio strongly recommends that you upgrade VENs only during maintenance windows.

NOTE:
If the VEN was activated prior to the upgrade, it does not need to be activated again after the upgrade completes.

Custom Username, Installation Directory, VEN Data Directory

If you installed the VEN with your own username, for upgrade you need to specify that same username with the VEN_NONPRIV_USER environment variable.

If you previously installed the VEN to non-default installation (RPM only) and data directories with environment variables, specify the same values before upgrade.

See Linux Installation with Environment Variables.

RPM Upgrade

# rpm -Uvh illumio-ven-<ven_version>.<os_platform>.rpm
IMPORTANT:
If the VEN_DATA_DIR environment variable and the --prefix option are not specified during the RPM installation, then the illumio_ven and illumio_ven_data directories are created in the /opt directory.

This information is important because if you previously installed the VEN to non-default installation and data directories, and if you upgrade without specifying those non-default directories, the VEN will not upgrade to your custom directories.

Therefore, if you specified non-default installation (RPM only) and data directories when you installed the VEN, you need to specify those same directories in the upgrade command.

This example also includes a custom username that was used during VEN installation.

For example, if you installed the VEN with this type of command:


# VEN_NONPRIV_USER=ven_install_username VEN_DATA_DIR=/opt/my_data_dir rpm -ivh <orig-illumio-ven-pkg>.rpm --prefix=/opt/my_ven_dir

Then, upgrade the VEN with the following command:


# VEN_NONPRIV_USER=ven_install_username VEN_DATA_DIR=/opt/my_data_dir rpm -Uvh <new-illumio-ven-pkg>.rpm --prefix=/opt/my_ven_dir

Debian Upgrade

# dpkg -i illumio-ven-<ven_version>.<os_platform>.deb
IMPORTANT:
If the VEN_DATA_DIR environment variable is not specified during VEN installation, then the illumio_ven_data directory is created in the /opt directory.

This information is important, because if you specified a custom data directory during installation, and if you upgrade the VEN without specifying the custom data directory, the VEN will not upgrade using your custom data directory.

Therefore, if you specified a non-default data directory when you installed, you need to specify the same non-default data directory during upgrade.

This example also includes a custom username that was used during VEN installation.

NOTE:
Using --prefix=/opt/my_ven_dir to specify a custom installation directory is not supported with Debian.

For example, if you installed the VEN with this type of command:


# VEN_NONPRIV_USER=ven_install_username VEN_DATA_DIR=/opt/my_data_dir dpkg -i <orig-illumio-ven-pkg>.deb 

Then, upgrade the VEN with the following command:


# VEN_NONPRIV_USER=ven_install_username VEN_DATA_DIR=/opt/my_data_dir dpkg -i <new-illumio-ven-pkg>.deb

Uninstall Linux VEN Using CLI

Unpair a Linux VEN before uninstalling it. See Deactivate and Unpair VENs in the VEN Administration Guide.

SUSE Linux: If a SUSE workload is unpaired in the Full enforcement policy state, the uninstallation might not complete when the workload does not have rules that allow it to connect to SUSE repositories. To avoid this issue, change the policy state to Visibility before unpairing the VEN. For more information see Workload Policy States in the VEN Administration Guide.

Uninstall the VEN

Security Implications: Production applications on this workload could break because after uninstalling the VEN this workload will no longer allow any connections to it other than SSH on port 22.

To uninstall the VEN, see Deactivate and Unpair VENs in the VEN Administration Guide.