Windows: Install and Upgrade with CLI and VEN CTL

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

With the Windows VEN MSI, you have the option of activating (pairing) the VEN either during installation or after installation.

Windows VEN Installation Directories

By default, the Windows VEN is installed in the following directories:

  • Installation: C:\Program Files\Illumio
  • Data: C:\ProgramData\Illumio

VEN Package Format Changes

Starting with the Illumio Core 21.2.1 release, the Windows VEN installer switched from MSI to EXE package format. This package format change primarily affects Illumio Core On-Premises customers running older MSI-based Windows VENs.

For information about using the VEN Library in the PCE to install Windows VENs on workloads, see Pair a Windows Workload.

Run PowerShell as Administrator

Use Windows PowerShell to run the VEN installation program.

Run PowerShell as Administrator with Execution Policy, because the installation affects the operating system.

Right-click the PowerShell icon and select Run as Administrator.

In addition, the VEN control scripts require the proper execution permissions on Windows. In PowerShell, run the following command before installation:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Install the Windows VEN Using EXE Package

Starting with the version 21.2.1, the Windows VEN installer format changed from an MSI package to an EXE bundle. The installation file is now executable and msiexec.exe is no longer used to install the Windows VEN in Illumio Core 21.2.1 and later releases.

Command Line Interface

The Windows VEN installer supports following command line options:

  • /install
  • /uninstall

  • /quiet

    Disables the interactive installer so that you don't respond to installation prompts.

  • /passive

    Still displays a minimal user interface but does not provide installation prompts.

  • /norestart

    Suppresses any attempts at restart.

  • /log

    Logs installation information to a specific file.

The following installation command lines show how to install the VEN EXE bundle and activate the VEN after installation. See Windows VEN Activation After Installation.

Quiet VEN Installation

Start-Process -FilePath "<directory_path>\illumio-ven-<ven_version>.<os_platform>.exe" -ArgumentList "/install","/quiet","/norestart","/log" "<directory_path>\VENInstaller.log" -Wait -PassThru

For example:

Start-Process -FilePath "$env:WinDir\temp\illumio-ven-21.5.0-xxxx.win.x64.exe" -ArgumentList "/install","/quiet","/norestart","/log","$env:WinDir\temp\VENInstaller.log" -Wait -PassThru

Quiet VEN Installation with Custom Directories

Start-Process -FilePath "$env:WinDir\temp\illumio-ven-<version>-<build>.win.x64.exe" -ArgumentList "/install","/quiet","/norestart","/log","$env:WinDir\temp\VENInstaller.log" INSTALLFOLDER="c:\illumio\ven" DATAFOLDER="c:\illumio\ven_data" -Wait -PassThru
CAUTION:

The VEN EXE installer supports custom installation directories; however, you should only specify the INSTALLFOLDER and DATAFOLDER parameters when installing the Windows VEN the first time. Do not specify these parameters when upgrading the Windows VEN using the EXE installer or the upgrade will fail.

Interactive VEN Installation

Start-Process -FilePath "<directory_path>\illumio-ven-<ven_version>.<os_platform>.exe" -ArgumentList "/install","/log" "<directory_path>\VENInstaller.log"

Windows VEN Activation After Installation

Be sure that you have the proper administrative permissions. See Run PowerShell as Administrator .

To activate the Windows VEN after installation, run the following command:

PS C:\Program Files\Illumio> .\illumio-ven-ctl.ps1 activate -activation-code <activation_code> -management-server <pce_fqdn:pce_portnumber> <activation_options>

Windows VEN Activation Options

You have several activation options you can set while pairing. You can set the workload policy state and apply labels at the time of activation.

This example shows how to activate a Windows workload with the following options:

  • Set the VEN policy state to illuminated with no traffic logging: -log_traffic false
  • Set the role as Web service: -role Web
  • Set the application to HRM: -app HRM
  • Set the environment to development: -env Dev
  • Set the location of the VEN to New York City: -loc NYC
PS C:\Program Files\Illumio> .\illumio-ven-ctl.ps1 activate -management-server yourPCE.example.com.8443 -activation-code <activation_code> -visibility_level flow_summary -log_traffic false -role Web -app HRM -env Dev -loc NYC

Kerberos for Windows VEN-to-PCE Authentication

To enable Kerberos authentication at installation, set the command-line variable KERBEROS_PCE_SPN on the installation program. Use the following value for this variable:

illumio-device-auth/<fqdn_of_your_pce>

Where:

  • The literal illumio-device-auth/ is required.
  • fqdn_of_your_pce is the fully qualified domain name (FQDN) of your PCE.

Example:

C:\> msiexec.exe /i illumio-ven-<ven_version>.<os_platform>.msi KERBEROS_PCE_SPN=illumio-device-auth/pce.example.com

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 the Security Policy Guidefor 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 .....
...

Windows VEN Upgrade for the MSI Package Format

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.

To upgrade the VEN, run this command:

PS C:\> msiexec /i illumio-ven-<ven_version>.<os_platform>.msi /qn

Windows VEN Uninstallation Using CLI

To uninstall the Windows VEN by using the VEN CTL, see Deactivate and Unpair VENs in the VEN Administration Guide.

Offline VEN During Unpairing

If the workload you are unpairing is offline, the workload might still appear in the workloads list in the PCE web console, even though the workload has been unpaired. The unpaired workload is removed from the PCE web console within 30-35 minutes.

Alternative: Remove Windows VEN Using Control Panel

You can also use the Windows Control Panel Programs and Features utility to remove the VEN. When you remove the Windows VEN with the Windows Control Panel, the VEN unpairs the workload with the Unpair and remove Illumio policy option. This method removes any current Illumio policy and activates the Windows firewall.