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

When installing and activating a VEN using a pairing script generated by a pairing profile:

If you set a specific VEN version in the PCE web console for the pairing profile used to generate the pairing script, that specific VEN version is installed on the workload.
Otherwise, if you have set a default VEN version for all workloads, that VEN version is installed on the workload. The PCE web console shows the current default VEN version in the "Initial VEN Version" dropdown. If no default VEN version is specified, the PCE uses the latest VEN version available in the VEN library.

The Default Pairing Profile

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

Last Pairing Key Generated and Last VEN Paired

The following information appears on the pairing profile details page:

The last time a pairing key was generated using this pairing profile.

The last time a VEN was paired using this pairing profile.

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 Visibility 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 Full enforcement state.

To configure a pairing profile:

From the PCE web console menu, go to Policy Objects > Pairing Profiles.
Click Add.
Enter a name and description (optional) for the pairing profile.
Configure the following options for the pairing profile:
Enforcement Mode for Policy
You can choose one of the enforcement modes 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 four hours.
  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.
- Visibility: In the Visibility Only state, 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 datacenter and the applications running in it. No traffic is blocked in this state. This state is useful when firewall policies are not yet known. This state can be used for discovering the application traffic flows in the organization and then generating a security policy that governs required communication.
- Selective: Segmentation rules are enforced only for selected inbound services when a workload is within the scope of a Selective Enforcement Rule.
- Full: Segmentation Rules are enforced for all inbound and outbound services. Traffic that is not allowed by a Segmentation Rule is blocked.
For information about how these enforcement modes impact workload security policy, see the "Enforcement States" and "Enforcement States for Rules" topics in the Security Policy Guide.
You can choose one of three modes for the traffic visibility for workloads:
- Off (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.
- Blocked: The VEN only collects the blocked connection details (source IP, destination IP, protocol and source port and destination port), including all packets that were dropped. This option provides less Illumination detail but also demands fewer system resources from a workload than high detail.
- Blocked + Allowed: The VEN collects connection details (source IP, destination IP, protocol and source port and destination port). This applies to both allowed and blocked connections. This option provides rich Illumination detail but requires some system resources from a workload.
Enforcement Node Type
The Enforcement Node Type setting allows you to specify the type of VEN that the pairing profile will activate:
- Server VEN: Select to activate a Server VEN with the pairing keys that this pairing profile will generate. When selected, only Server VENs can be activated with this pairing profile.
- Endpoint VEN: Select to activate a Endpoint VEN with the pairing keys that this pairing profile will generate. When selected, only Endpoint VENs can be activated with this pairing profile.
- Specified during VEN activation (deprecated legacy option): When Illumio initially released the Endpoint solution, it wasn't yet possible to specify the Endpoint Enforcement Node Type in the PCE UI. Instead, after copying the pairing script from the PCE it was necessary to paste the script into a text editor and enter -endpoint true in an appropriate place in the script and then run the script. This option is for that use case.
Initial VEN Version
This is the VEN version that will be installed initially. You can edit the pairing profile later and select a different VEN version. If you don't select an initial VEN version, the pairing script installs the default VEN version. When using the default VEN version, VENs paired using the pairing line may have different versions depending on the default VEN version at pairing time. If you don't specify a default VEN version, VENs paired using the pairing line will use the latest compatible VEN version.
Assign Workload Labels
You can specify in the pairing profile which labels you want the PCE 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, see 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.
Key Usage Requirements
The certification Key Usage requirements have changed to CERT_DIGITAL_SIGNATURE_KEY_USAGE, CERT_KEY_ENCIPHERMENT_KEY_USAGE, and CERT_DATA_ENCIPHERMENT_KEY_USAGE, so that the endpoint certificates can be set in the x.509 Windows environment.
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.
Click Save.
The PCE saves the pairing profile and the page refreshes with the values you specified.

Working with a Pairing Profile

Open a pairing profile to display options to perform the following tasks.

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.

Delete a Pairing Profile

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 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.

Pairing Script

When you choose to install VENs on workloads by using the VEN Library, you create the pairing profile in the PCE web console and run the pairing script on workloads. (The CLI VEN installation method bypasses the pairing script altogether. In that method, you use the native tools of the operating system to install the package, followed by the VEN CLI to activate the VEN. See VEN Installation & Upgrade with VEN CTL.)

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 Pairing and Activation 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;

Running RHEL 5 Pairing Script with cURL

When using a cURL command to run a pairing script for a RHEL 5 VEN, first perform the following additional configuration.

Downgrade the Transport Layer Security (TLS) version that the PCE uses for VEN-to-PCE communications. In RHEL 5, the normal default minimum version, TLS 1.2, can not be used. Set the default minimum version to TLS 1.0 by setting the parameter min_tls_version to tls1_0 in the PCE configuration file runtime_env.yml. For details, see TLS Versions for Communications.

Update the CA certificate file on the RHEL 5 machine. Download the latest cacert.pem and append it to the ca-bundle.crt file. Use the following steps:

Download the latest cacert.pem to your RHEL 5 machine from https://curl.se/docs/caextract.html. If the download fails because the certificate is expired, perform the download again on a different machine with a valid certificate and then copy the certificate to the initial machine.

Append the certificate using the following command:

sudo cat /tmp/cacert.pem >> /etc/pki/tls/certs/ca-bundle.cr

After changing the TLS version and the CA certificate, pair the VEN using a cURL command as described earlier in this section.

Illumio Core 23.2 Install, Configure, Upgrade