Pairing Profiles and Scripts

A pairing profile contains the configuration for workloads so that you can apply certain properties to workloads as they pair with the PCE, such as applying labels, setting workload policy state, and more.

When you configure a pairing profile, the pairing script contains a unique pairing key at the end of the script (an activation code) that identifies the VEN securely so it can authenticate with the PCE. The pairing key can be set to be used one time or several times, and you can configure its time and use limit.

In the PCE web console, you create a pairing profile with the characteristics to create a script called a pairing script to run on workloads. The pairing script installs the VEN software, activates it, and gets the workloads ready to accept security policy from the PCE. “Pairing” is also known as “installation and activation.”

Workflow for Using Pairing Profiles

Creating and using pairing profiles follows this general workflow:

Create a pairing profile.
Generate a pairing script.
Copy the script to the workload and run it.

The following conditions apply when installing VENs by using pairing profiles:

An activation code/pairing key is required. In the PCE web console, you can specify either a single, one-time activation code or an unlimited, multi-use activation code.
The pairing script is not absolutely required. It is an alternative to installing VEN software installation and activation with the VEN CTL (illumio-ven-ctl).

Which VEN Version is Installed

A particular version of the VEN is only installed on a workload when it is activated.

In the PCE web console if you have set a Current Default VEN version for all workloads, that default version gets installed on all workloads.
If you set a specific VEN version for a pairing profile in the PCE web console, that specific VEN version gets installed on the workload regardless of the Current Default.

The Default Pairing Profile

Item	Description
Name	Default
Labels	Role=<Blank> Application=<Blank> Environment=Production Location=<Blank>
Workload State	Illuminated, Locked
Uses per Key	Unlimited
Maximum Key Age	Unlimited
Command Line Overrides	Unlocked (CLI can override anything)

Filter the Pairing Profiles List

You can filter the pairing profiles list using the properties filter at the top of the list. You can filter the list by entering a label type to show only those pairing profiles that use the selected labels. You can further filter the list by selecting specific properties of the pairing profiles. For example, you can filter the list by a pairing profile's name.

Click the Reports button and select JSON or CSV format to generate the pairing profiles report. Once generated, you can either click the download icon next to Reports to download the generated report or select Reports > All Export Reports to view the report details.

Configure a Pairing Profile

You can configure a pairing profile to set the initial workload policy state at the time of pairing. For example, you might want to pair workloads in the Build or Test state so you can view network traffic to build policies before enforcing them.

On the other hand, if you are configuring an auto-scale policy and want to pair workloads automatically based on application demands, you can choose to have workloads paired in Enforcement state.

To configure a pairing profile:

From the PCE web console menu, choose Policy Objects > Pairing Profiles.
Click Add.

The Pairing Profile page appears.
Enter a name and description (optional) for the pairing profile.
Select the Initial VEN Version. This is the VEN version that will be installed initially. You can later edit the pairing profile and select another VEN version.
Configure the following options for the pairing profile and click Save.

Set Policy States

You can choose one of the policy states for workloads when you pair them:

Idle: A state in which the VEN does not take control of the workload’s iptables (Linux) or WFP (Windows), but uses workload network analysis to provides the PCE relevant details about the workload, such as the workload’s IP address, operating system, and traffic flows. This snapshot is taken every ten minutes.

NOTE:
SecureConnect is not supported on workloads in the Idle policy state. If you activate SecureConnect for a rule that applies to workloads that are in both Idle and non-Idle policy states, it could impact the traffic between these workloads.
Build: A state in which the VEN inspects all open ports on a workload and reports the flow of traffic between it and other workloads to the PCE. In this state, the PCE displays the flow of traffic to and from the workload, providing insight into the data center and the applications running in it. No traffic is blocked in this state.
Test: A state which allows you to apply all rules in your ruleset and visualize all of the traffic that would be blocked if you placed the workloads into the Enforced policy state. No traffic is blocked in this state.
Enforced: A state of a workload in which all rules in the ruleset are enforced and all traffic flows that are not allowed by the rules are blocked.

You can choose one of three modes for the Enforced policy state:

High Detail: The VEN collects traffic connection details (source IP address, destination IP address, protocol, and source and destination port) for both allowed and blocked connections. This option creates traffic flow links in the Illumination workflow and is typically used during the building and testing phase of your application security policy.
Low Detail: The VEN only collects traffic connection details (source IP address, destination IP address, protocol, and source and destination port) for blocked connections. This option provides less detail for Illumination but utilizes fewer system resources from a workload and is typically used for policy enforcement.
No Detail: The VEN does not collect any details about traffic connections. This option provides no Illumination detail and utilizes the least amount of resources from workloads. This state is useful when you are satisfied with the rules that have been created and do not need additional overhead from observing workload communication.

Assign Workload Labels

You can specify in the pairing profile which labels you want the to assign to workloads when they are paired. Labels group workloads into logical categories for use in rulesets.

The PCE provides four types of labels:

Role: The role or function of a workload. In a simple two-tier application consisting of a web server and a database server, there are two roles: Web and Database.
Application: The type of application the workload is supporting (for example, HRM, SAP, Finance, Storefront).
Environment: The stage in the development of the application (for example, production, QA, development, staging).
Location: The physical, geographic location of the workload (for example, Germany, US, Europe, Asia).

For information on creating labels, Labels and Label Groups in the Security Policy Guide.

Configure Pairing Key Usage and Lifespan

You can control the usage and lifespan of the pairing key in the pairing profile.

Uses Per Key: Choose if you want the key generated from this pairing profile to be used an unlimited number of times or only once.
Key lifespan: Specify how long you want the pairing key to be valid, either unlimited (forever) or for a specified time frame.

You can choose from these options to define how you want the pairing profile to be used:

Unlimited: This option provides a pairing script that can be used to pair as many workloads in the organization as you want. Each user in an organization is given the pairing script from this profile regardless of the workload, the application the workload is a part of, the location of the workload (data center or country), or the environment (development, testing, QA, production). Unlimited use pairing profiles can present a security risk because they never change; however, if a pairing script is stolen, a workload could be paired into your environment by an untrusted user.

IMPORTANT:
Illumio recommends against configuring unlimited usage of pairing profiles from a security perspective. Instead, determine the appropriate lifespan for the pairing profile to minimize any security risk.
Custom Time Range: If you do not want an unlimited use pairing profile, you can specify that the pairing profile can only be used to pair a workload one time, after which the pairing key cannot be used to pair more workloads.

Choose Command Line Overrides

For each of these Workload states, you can choose to either allow or block modifications to these settings when the pairing script is executed from the command line:

Workload Policy State

Lock Workload policy state assignment: The policy state of the workloads being paired cannot be changed when the pairing script is run.
Allow Workload policy state assignment: The policy state of the workloads being paired can be changed when the pairing script is run.

Label Assignment

Lock Label assignment: This option prevents a user running the pairing script from assigning labels to workloads during pairing except for what is configured with the pairing profile.
Allow custom Labels: This option permits the user running the pairing script to assign labels to the workloads during pairing using this pairing profile. Selecting this option selects all the Label checkboxes. You can deselect any before saving.

Start/Stop Pairing

To enable or disable the pairing profile, click the pairing profile. The pairing profile details page opens and you can click Stop Pairing or Start Pairing .

Generate Key

Click Generate Key at the top of the page to create a unique pairing key that can be used with the pairing script. The key will not be accessible once you close the Pairing Profile details panel.

Every key that is generated under a pairing profile inherits the properties set in the pairing profile. The script can be used to pair Workloads, according to the parameters and time limits set in the pairing profile.

Pairing Script

Regardless of how you choose to install VENs on workload (either by using the VEN Library or by using the packaging CLI and VEN CTL), you create the pairing profile in the PCE web console and run the pairing script on workloads.

Add Options to the Pairing Script

You can add additional pairing options to the pairing profile, such as assign labels to the workload, set the workload policy state, and set logging levels for VEN traffic.

For the complete list of options to use with the pairing script, see VEN Activate Command Reference.

Linux Pairing Script for VEN Library Installation

For example, if you want to add an Environment label to the workload, such as --env Production, include the option at the end of the pairing script as shown below.

rm -fr /opt/illumio_ven_data/tmp && umask 026 && mkdir -p /opt/illumio_ven_data/tmp && curl "https://example.com:8443/api/v18/software/ven/image?pair_script=pair.sh&profile_id=<pairing_profile_id>" -o /opt/illumio_ven_data/tmp/pair.sh && chmod +x /opt/illumio_ven_data/tmp/pair.sh && /opt/illumio_ven_data/tmp/pair.sh --management-server example.com:8443 --activation-code <code> --env Production

Windows VEN Installation without the VEN Library

Set-ExecutionPolicy -Scope process remotesigned -Force; Start-Sleep -s 3; (New-Object System.Net.WebClient).DownloadFile("https://repo.illum.io/Z3JldGVsbHVuZHl0aGF0Y2hlcjg1dGgK/pair.ps1", "$pwd\Pair.ps1"); .\Pair.ps1 -repo-host repo.illum.io -repo-dir Z3JldGVsbHVuZHl0aGF0Y2hlcjg1dGgK/ -repo-https-port 443 ` -management-server pce.example.com:8443 -activation-code <code> –env Production; Set-ExecutionPolicy -Scope process undefined -Force;

Delete a Pairing Profile Key

If you want to completely disable the pairing keys generated with a pairing profile, delete the pairing profile.

To delete a pairing profile and its pairing keys:

From the PCE web console menu, choose Policy Objects > Pairing Profiles.
Select the checkbox of the pairing profiles you want to delete.
Click Remove.

All pairing keys that were associated with this pairing profile are no longer be valid for pairing workloads.

The same process applies if you are instantiating new VMs in vSphere or Microsoft Azure. You can use the modified Illumio PCE pairing script for preparing your new VMs for auto scaling.