VEN Activate Command Reference

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

About the Command Options

You use the activate command options in these ways:

  • When pairing a VEN with a pairing script and activating 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"
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 visibility-level Arguments.
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.
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 Enforced or Illuminated policy state, 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.

Called High Detail in the PCE web console. 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 during the build and test policy states.

flow_drops

Valid only in enforced state

Called Less Detail in the PCE web console.

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

Called No Detail in the PCE web console.

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.

The following values have special names in the PCE web console:

  • Illuminated, --visibility-level flow_summary: Build and Test

  • Enforced

    • --visibility-level flow_off: No detail in enforced mode
    • --visibility-level flow_summary: High detail in enforced mode
    • --visibility-level flow_drops: Low detail in enforced mode