`prepare` Scripts

The prepare script is used for creating golden images to activate the VEN the first time the image is booted.

NOTE: After the PCE software has been installed onto a host and a local VEN repo has been set up on the PCE, migrating the PCE to a new host requires that you set up the VEN repo for that new host.

Prepare Golden Image for Workload Installation

Many organizations use “golden images” for faster deployment. When using a golden image to install a VEN, you have two options for pairing with the PCE:

Use a modified version of the Illumio Core pairing script called prepare to ensure these golden images have the VEN pre-installed.
Use the illumio-ven-ctl control script.

IMPORTANT:

You should enable your images with the prepare script as the last step in building the image. The prepare script takes effect at the next system boot, which means the VEN might be activated prematurely on the image itself. If you have other software to install on the image and the image requires reboot, the VEN is activated at once, which is probably not desirable.
In the PCE web console, the pairing profile has two types of activation codes: one-time use or unlimited use. Be sure to specify the correct type for your needs. For more information, see Configure Pairing Key Usage and Lifespan.

Prepare Using the Pairing Profile/Pairing Script

This option relies on the pair script displayed in the PCE web console.

In the PCE web console, create a pairing profile or select an existing pairing profile. For information, see Pairing Profiles and Scripts
Copy the pairing script.
In the copy of the script, change all occurrences of pair to prepare.
Run the modified script on the image.

The prepare script installs the VEN on the image. When the prepare scripts finishes, the VEN is stopped. The script configures the VEN to start the next time the workload is booted.

Prepare the Workload with `illumio-ven-ctl`

Instead of the prepare script, you have several options:

Use illumio-ven-ctl to set the image into “prepare” mode:

# /opt/illumio_ven/illumio-ven-ctl prepare –management-server <pce_fqdn:port> --activation-code <activation_key>

Use an activation file that contains the activation code and management server name and port. The configuration file is read when the VEN is started when the image is booted.
- On Windows, by default, the file is C:\ProgramData\Illumio\etc\agent_activation.cfg
- On Linux, by default, the file is /opt/illumio_ven_data/etc/agent_activation.cfg
Contents of agent_activation.cfg:
```
activation_code: <your_activation_code>
masterconfig_server: <your_pce_fqdn:your_port>
```

Example activation configuration file:

activation_code: 11bbbe89962159ffe7f0b7e71a532910aa47171f97bc0ad3a0219a780f559006a320587bba966a854 masterconfig_server: pce.example.com:8443

Auto Scaling Linux Workloads

The process for enabling Illumio Core to enable auto scaling for Linux workloads follows this general process:

Select an existing VM instance that you want to create a new instance for.
Inside the PCE web console, create a pairing profile (or select an existing pairing profile).

Copy and edit the Linux pairing script:

rm -fr /opt/illumio_ven_data/tmp && umask 026 && mkdir -p /opt/illumio_ven_data/tmp && curl --tlsv1 "https://pce.example.com:8443/api/v18/software/ven/image?pair_script=pair.sh&profile_id=1" -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 pce.example.com:8443 --activation-code 11a12969c511197eb7ae1e175b9b49382fe1bc011b2a2228c8a184cc6c9f75663325146e5d5ac7c5d

Change all occurrences of the script where pair.sh is used and replace with prepare.sh.

So that the script looks like this:

rm -fr /opt/illumio_ven_data/tmp && umask 026 && mkdir -p /opt/illumio_ven_data/tmp && curl --tlsv1 "https://pce.example.com:8443/api/v18/software/ven/image?pair_script=prepare.sh&profile_id=1" -o /opt/illumio_ven_data/tmp/prepare.sh && chmod +x /opt/illumio_ven_data/tmp/prepare.sh && /opt/illumio_ven_data/tmp/prepare.sh --management-server pce.example.com:8443 --activation-code 11a12969c511197eb7ae1e175b9b49382fe1bc011b2a2228c8a184cc6c9f75663325146e5d5ac7c5d

The prepare.sh script installs the VEN on the new workload and configures it so the VEN will start running as soon as the new workload is instantiated.

Run the modified script on the Linux instance.
Configure your auto scaling policy to use an image that contains the prepare script.

Auto Scaling for Windows Workloads

The process for enabling Illumio Core to enable auto scaling on Windows workloads follows this general process:

Select an existing VM instance that you want to create a new instance for.
In the PCE web console, create a pairing profile (or use an existing pairing profile).

Copy and edit the Windows pairing script:

PowerShell -Command "& {Set-ExecutionPolicy -Scope process remotesigned -Force; Start-Sleep -s 3; Set-Variable -Name ErrorActionPreference -Value SilentlyContinue; [System.Net.ServicePointManager]::SecurityProtocol=[Enum]::ToObject([System.Net.SecurityProtocolType], 3072); Set-Variable -Name ErrorActionPreference -Value Continue; (New-Object System.Net.WebClient).DownloadFile('https://pce.example.com:8443/api/v18/software/ven/image?pair_script=pair.ps1&profile_id=1', (echo $env:windir\temp\pair.ps1)); & $env:windir\temp\pair.ps1 -management-server pce.example.com:8443 -activation-code 11a12969c511197eb7ae1e175b9b49382fe1bc011b2a2228c8a184cc6c9f75663325146e5d5ac7c5d;}"

Change all occurrences of the script where pair.ps1 is used and replace with prepare.ps1.