VEN Library Setup in the PCE

You can use your on-premises PCE cluster as a centralized mechanism for distributing, installing, and upgrading VENs in your organization.

About the VEN Library in the PCE

The PCE-based installation feature is:

  • Available for the RPM, Debian, and Windows distributions of the VEN software. Other workload operating systems are not supported.
  • Supported only for PCE and VEN version 18.2 and later.

VEN installation from the PCE does not affect any processes you might already have for installing or upgrading VENs directly on workloads, such as installation or activation with the VEN CTL (illumio-ven-ctl). Those processes can continue until and after you decide to distribute via the PCE.

NOTE: Once you install the PCE software onto a host and you have set up a local VEN repo onto the PCE, migrating the PCE to a new host requires that you also set up the VEN repo for that new host.

VEN Library

Previously, VENs could be deployed from an external VEN repository (the VEN repo) or by manually installing the VEN packages directly onto your workloads.

From the 18.2.0 release onwards, the PCE can act as a repository for distributing, installing, and upgrading the VEN software. The PCE can host multiple VEN versions, allowing you to evaluate and certify new versions of the VEN while continuing to deploy older versions in production.

Using the VEN Library in the PCE to install VENs replaces the external VEN repo, which is no longer supported for VEN 18.2.0 or later. A migration path is available for Illumio Cloud customers and Illumio On-premises customers with VEN repos upgrading VENs to 18.2.0.

Using the VEN Library to install VENs has the following benefits:

  • The VEN software bundle is loaded on the PCE and replicated to all PCE core nodes.
  • You can view VEN releases from the VEN Library page in the PCE web console.
  • You have the ability to download software on workstations.
  • It supports Windows and Linux operating systems.
  • Multiple versions of VEN software can exist on the PCE.
  • You can specify initial VEN versions in Pairing Profiles.
  • You can add and remove VEN releases from the PCE.
  • You have the option to set a default release when multiple VEN releases exist on the PCE.
  • VEN upgrade supports an option for either all or a list of agents.

The VEN Library page is available in the Settings menu after you have loaded a VEN software bundle using the PCE control interface (illumio-pce-ctl). From this page, you can download individual VEN packages and view supported OS versions.

If a system default version has not been designated or an external repository has not been configured, you must set an initial VEN version.


If you use the Illumio REST API to create a pairing profile with a version or the PCE has pairing profiles that do not have versions, and you attempt to pair VENs using one of those profiles, the VEN pairing fails.

Migration to Installation Using VEN Library

Before migrating from the central VEN repo or an on-premises VEN repo to using the VEN Library in the PCE to install VENs, thoroughly plan and time the migration so that it does not impact your current operations. Contact Illumio Customer Support for information and assistance.

Workflow for VEN Library Setup

You do not have change or update your configuration or other settings to set up the VEN Library in the PCE. Loading the VEN bundle into the VEN Library on the PCE enables the feature. See also Set Default Version in VEN Library.

The following steps describe the high-level process for setting up and using the VEN Library on the PCE:

  1. Download the version of the VEN software bundle to distribute.
  2. Load the VEN deployment into one of the PCE core node's VEN Library. From this node, the VEN software bundle is automatically copied to the other nodes.
  3. Install or upgrade VENs:
    1. To install the VEN software on workloads, with the PCE web console, generate a pairing script.
    2. To upgrade all VEN workloads or selective workloads, use the PCE command interface.

Location for Downloaded VEN Software

Decide on a system where you want to download the VEN software bundle. Download it to one of the PCE core nodes or to a system that is accessible from a PCE core node via HTTP, SFTP, or SCP.

Selection of VEN Software Bundle

Determine which VEN software versions to distribute.

The VEN software for VEN installation using the VEN Library is a tarball (tar file) of a version of VEN software for all supported workload platforms. This tarball is known as a VEN software bundle.

Download VEN Software Bundles

Download the VEN software bundles from the Illumio Support portal for all VEN versions you require to load into the PCE.

  1. In your browser, navigate to Illumio's software download page.
  2. Select the your version of the Illumio Core.
  3. Download all the VEN software bundles you need to distribute to a convenient directory on your PCE core node or to any system that your PCE can reach with HTTP, SFTP, or SCP.

    You do not need to unpack the VEN software bundle.

  4. Repeat this step for all versions of the VEN you want to distribute.

In addition, when Illumio releases new versions of the VEN software, plan on repeating these steps when you are ready to deploy that version.

Load VEN Software Bundle into PCE

Loading the VEN software bundle consists of running illumio-pce-ctl on the PCE command interface to load the VEN software bundle into the PCE's VEN Library. The VEN Library is then replicated to the other core nodes.

Loading the VEN software bundle into the PCE's VEN Library is what configures the PCE as the VEN installation method.

  1. Copy the downloaded VEN software bundles to a convenient location on your PCE core node or to any system that the PCE can access via HTTP, SFTP, or SCP.
  2. To load the VEN software bundle, run the following command on the core node's command line.

    sudo -u ilo-pce illumio-pce-ctl ven-software-install protocolAndFqdnOfVenBundleHost/nameOfVenSoftwareBundleFile.tar.bz2


    • protocolAndFqdnOfVenBundleHost/nameOfVenSoftwareBundleFile.tar.bz2 is any of the following locations:
      • The absolute or relative path to a directory on the PCE where you downloaded the VEN software bundle
      • An HTTP URL to a host and file where you stored the downloaded VEN software bundle
      • An SFTP URL to a host and file where you stored the downloaded VEN software bundle
      • An SCP URL to a host where you stored the downloaded VEN software bundle
    • nameOfVenSoftwareBundleFile.tar.bz2 follows this pattern:


      Where someVersionStamp is the version and build number of the Illumio Core release.


The following example assumes you have copied the VEN software bundle into /var/tmp on you PCE:

# sudo -u ilo-pce
# illumio-pce-ctl ven-software-install /var/tmp/illumio-ven-bundle-someVersionStamp.tar.bz2
Reading /opt/pce_config/etc/runtime_env.yml.
Validating VEN release tarball file contents:
Deploying VEN release tarball to 'PCE's IP address' .

Committing tarball manifest information to database.
Are you sure you want to continue? [yes/no]: yes
Release version_of_bundle Successful.

HTTP and SCP Examples

These examples show HTTP and SCP URLs on the illumio-pce-ctl ven-soft-install command:

  • HTTP:

    sudo -u ilo-pce illumio-pce-ctl ven-software-install
  • SCP:

    sudo -u ilo-pce illumio-pce-ctl ven-software-install scp://

View Loaded VEN Library

The VEN loading process with illumio-pce-ctl ven-software-install prints its success or failure when it completes. You can also verify the successful loading in the following ways.

  • In the PCE web console, look at the VEN library. Navigate to Settings > VEN Library to see that the bundle has been loaded.
  • On the PCE command line, run the following command:

    sudo -u ilo-pce illumio-pce-ctl ven-software-releases-list

Set Default Version in VEN Library

There are two ways to set a default version of the VEN software in the VEN Library: either for all workloads or for selected pairing profiles. These two methods can be used simultaneously. For example:

  • Set a default VEN version for all workloads when you are ready to roll out that specific version.
  • Create a separate pairing profile with a specific VEN version for test, evaluation, and certification before general rollout.

Set Default VEN Version for All Workloads

To define the default VEN version for all workloads, run this command on the PCE:

sudo -u ilo-pce illumio-pce-ctl ven-software-release-set-default ven_release_id 


  • ven_release_id is the release ID displayed by the illumio-pce-ctl ven-software-releases-list command.

You can also to set the default release when you install a new VEN bundle by using the --default option with illumio-pce-ctl ven-software-install:

sudo -u ilo-pce illumio-pce-ctl ven-software-install /var/tmp/illumio-ven-bundle-someVersionStamp.tar.bz2 --default

Set VEN Version for Specific Pairing Profile

You can selectively set a VEN version for specific pairing profiles. The profiles that have a defined VEN version create pairing profiles that install that specific VEN version on the workload. Other pairing profiles that have no VEN version set are unaffected.

To set a pairing profile's VEN version, see Configure a Pairing Profile.

For information about pairing scripts, see prepare Scripts.

PCE Runtime Parameters for Installation Using VEN Library

After you have migrated from any external VEN repo you might have, remove the following parameters from the PCE runtime_env.yml file:

  • ven_repo_url
  • ven_repo_ips

These parameters are not needed when installing the VEN by using the VEN Library in the PCE. They are deprecated and should no longer be used.

PCE Maintenance for VEN Installation

You should plan for the following PCE maintenance tasks when choosing to use the VEN Library in the PCE for VEN installation.

About PCE Backups

Be sure that your PCE backup includes the VEN Library and does not occur before the point when you loaded the VEN software bundles into the VEN Library. If you restore from an earlier backup, you need to either reload the VEN Library or redeploy from an existing core node.

Addition, Deletion, or Failure of PCE Nodes

If you need to add or replace one of the core nodes to your PCE cluster, you need to redeploy the VEN Library to the new core node.

After adding or replacing a node, redeploy each VEN version by using the ven-software-install command.

About Complete PCE failure

In case of a catastrophic failure of the PCE cluster, after rebuilding or reinstalling the cluster, reload the VEN software bundles into a PCE core node's VEN Library.

VEN-related Maintenance Commands on PCE

The illumio-pce-ctl control interface has options for VEN maintenance, such as add new VEN software bundle, remove VEN version, and delete VEN version. See the illumio-pce-ctl --help details.

Some of the options for distributing VENs from the PCE show org-id, org-list, and other organization-related arguments. None of the organization-related options or arguments are needed for distributing VENs from your on-premises PCE and do not need to be specified.