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.
Windows VEN Installation Directories
By default, the Windows VEN is installed in the following directories:
- Installation:
C:\Program Files\Illumio
- Data:
C:\ProgramData\Illumio
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
The installation file is an executable usedto install the Windows VEN.
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-<ven_version>-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
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"
INSTALLFOLDER
|
|
DATAFOLDER
|
|
MANAGEMENT_SERVER
|
|
ACTIVATION_CODE
|
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
When you use the CLI to install a Windows VEN on a workload, you cannot include colons in the values for command options. Including a colon in a option value causes VEN activation to fail. For example, including the following values in the -role
option, causes VEN activation to fail:
-role "R: UNKNOWN" -app "A:UNKNOWN" -env "E: UNKNOWN"
Activation fails because Windows uses the colon as a special character and cannot interpret the value even when you include quotation marks around the value.
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 Labels and Label Groups in 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 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 Xpress policy and activates the Windows firewall.