VEN Activate Command Reference

The following topic describes the commands for activating the VENs either during or after installation, and the ways that you can configure the VEN during activation.

About the Command Options

You use the activate options in these ways:

  • When pairing a VEN with a pairing script and you activate the VEN during installation:
    • pair.sh (Linux)
    • pair.ps1 (Windows)
  • When activating a VEN (all supported operating systems) after VEN installation by using the illumio-ven-ctl control script

If you are activating with a PCE that has a pairing profile configured to block changes to policy state (the illumio-ven-ctl option --mode) or label assignment (the illumio-ven-ctl options --env, --loc, --role, --app), you must not use these options on these blocked configurations or the activation will fail.

WARNING:

When you use the VEN CTL or a pairing script to install a Windows VEN on a workload, you cannot include colons in the values for the options. Including a colon in a command 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.

Description of the activate Command Options

The options and arguments are the same for Windows and Unix (Linux, Solaris, and Solaris), except the options with two dashes on Unix should be replaced with a single dash on Windows (for example, --loc on Linux should be replaced with -loc on Windows).

NOTE:

The following options are optional unless noted in the description.

Option Arguments Description
activation-code | -a <activation_code>

REQUIRED: Inputs the activation code of the VEN into the pairing script. This code is auto-generated by the pairing profile.

Activation code: one-time use or unlimited use

In the PCE web console, you can specify that an activation code is for one-time use or for unlimited uses. Be sure you have generated the correct type for your needs. Do not use a single one-time use activation code for more than one workload.

Example: --activation-code 1234567890abcdef
management-server | -m <PCE_FQDN:port> | <IPaddress:port>

REQUIRED: Sets the domain name or IP address and port of the host where the VEN can retrieve master configuration information.

Example: --management-server mypce.example.com:8443
name | -n <server_friendly _name>

Sets a friendly name that will be used for this workload when it appears in the PCE web console.

Example: --name "Web Server 1"
env <environment_label>

Assigns an Environment label for this workload.

Example: --env Production
loc

<location_label>

Assigns a Location label for this workload.

Example: --loc "US"
role <role_label>

Assigns a Role label for this workload.

Example: --role "Dev Group"
app

<application_label>

Assigns an Application label for this workload.

Example: --app "Web Service"
proxy_server <proxy-string>

[Linux, Solaris, AIX only]

You only need to specify this option when configuring a proxy server for a Linux, Solaris, or AIX workload. Windows automatically detects a proxy server; therefore, you do not need to specify this option when installing a VEN on a Windows workload.

For information about configuring a proxy server, see VEN Proxy Support.
log-traffic

true | false

Enables or disables traffic logging. If not specified, logging is set to true by default.

Default: true

Interacts with the visibility-level option. See Allowable Combinations of log-traffic and visibility-level.
mode illuminated | enforced | idle

Sets the policy state for the workload. For an explanation of the various states, see "Workload Policy States" in the VEN Administration Guide.
enforcement_mode full | visibility_only | selective | idle

Default: visibility_only

Enables the new selective mode for the VEN.

 
visbility-level

flow_summary | flow_drops | flow_off

Default: flow_summary

Defines the extent of the data the VEN collects and reports to the PCE from a workload in the Full enforcement or Visibility policy states, so you can control resource demands on workloads. The higher levels of detail are useful for visualizing traffic flows in greater detail in the Illumination map inside the PCE web console.

Interacts with the --log-traffic option. See Allowable Combinations of log-traffic and visibility-level.

visibility-level Arguments

Argument Value in Policy States Notes
flow_summary

Included in all policy states

Default.

The VEN collects traffic connection details for both allowed and blocked connections: source and destination IP address and port and protocol.

This argument creates traffic links in the Illumination map and is typically used initially after installing the VEN to determine the full scope of potential policy impact on the workload.

flow_drops

Valid only in full policy state

The VEN collects connection details only for blocked traffic: source and destination IP address and port and protocol.

This argument produces less detail for Illumination but demands fewer workload system resources than flow_summary.
flow_off

Valid in all policy states

The VEN does not collect any details about traffic connections.

This option produces no details for the Illumination map but requires the fewest number of workload resources. Useful when you are satisfied with policy rules and do not need additional detail.

Allowable Combinations of log-traffic and visibility-level

The following rules apply to using the log-traffic and visibility-level options together with the activate command:

  • The visibility-level argument takes precedence over the log-traffic argument.
  • visibility-level flow_off and --log-traffic true is an invalid combination.
  • visibility-level flow_drops is invalid in Illuminated policy state.

VEN Modes in Illumio Core 20.2.0 and later

In Illumio Core 20.2.0, Illumio introduced a new feature called Selective Enforcement. For an explanation of how this feature changed policy functionality in the release, see Selective Enforcement in What's New in This Release, 20.2.0.

NOTE:

This change to the VEN modes affects the VEN in Illumio Core 20.2.0 and later releases.

In particular, the feature changed the workload policy states. To further understand how the policy state changed between releases, see these topics:

The changes to policy states in 20.2.0 impacted the VEN mode option that you specify with the activate command in the following ways.

CAUTION:

Do not use both the mode and enforcement_mode options together on the command line because you could specify contradictory options. Specify one or the other. To specify the new Selective Enforcement option, enter the enforcement_mode selective option and argument.

  • Adds a new option for the activate command: enforcement full|visibility_only|selective|idle
  • Retains the mode option from the previous release for backward compatibility
  • The arguments for the mode option map to those for the enforcement_mode option in this way:
    • illuminated maps to visibility_only
    • enforced maps to full
    • idle is the same in both options

    • enforcement_mode option adds the selective argument

      Use the selective argument to set the VEN mode as Selective Enforcement state. For information about using Selective Enforcement in policy, see Enforcement Modes for Rules in the Security Policy Guide.

  • The visibility-level option and argument are unchanged in Illumio Core 20.2.0 and later releases; however, the Selective Enforcement feature separated the workload policy visibility state from the policy enforcement state; in particular, the PCE web console has separate drop-down menus (Enforcement and Visibility) in the Workloads page for these two options.

    The arguments for the visibility-level option map to the new visibility states in 20.2.0 and later releases in this way:

    • flow_off maps to Off
    • flow_drops maps to Blocked
    • flow_summary maps to Blocked + Allowed