VEN Operations

Overview of VEN Suspension

The VEN Update API (PUT [api-version][ven-href]) allows you to mark a VEN as either suspended or unsuspended in the PCE. It does not, however, actually suspend or unsuspend the VEN.

To suspend a VEN, use the illumio-ven-ctl command-line tool, which isolates a VEN on a workload so that you can troubleshoot issues and determine if the VEN is the cause of any anomalous behavior.

When you suspend a VEN, the VEN informs the PCE that it is in suspended mode.

However, if the PCE does not receive this notification, you must mark the VEN as "Suspended" in the PCE web console (select the VEN and click Edit), or you can use this API to mark the VEN as suspended.

When you don't mark the VEN as suspended in the PCE, after one hour, the PCE assumes that the workload is offline and removes it from the policy. When you mark the VEN as suspended, that VEN’s workload is still included in the policy of other workloads.

When a VEN is suspended:

  • The VEN still appears in the PCE in the VEN list page.
  • The VEN's host cannot be unpaired.
  • An organization event (server_suspended) is logged. This event is exportable to CEF/LEEF and has the severity of WARNING.

  • Heartbeats or other communications are not expected, but when received, all communications are logged by the PCE.

  • If the PCE is rebooted, the VEN remains suspended.

  • Any custom iptables rules are removed, and you need to reconfigure them manually.

When a VEN is unsuspended:

  • The PCE is informed that the VEN is no longer suspended and is able to receive policy from the PCE. If existing rules affect the unsuspended workload, the PCE reprograms those rules.
  • An organization event (server_unsuspended) is logged. This event is exportable to CEF/LEEF and has the severity of WARNING.
  • The workload reverts to the policy state it had before it was suspended.
  • Custom iptables rules are configured back into the iptables.

VEN upgrade APIs allow you to specify an array of VEN hrefs to upgrade to a specific version instead of a list of agent ID's.

Rules when validating with the VEN upgrade APIs are as follows:

  • No downgrades are allowed
  • Users cannot upgrade to a VEN version higher than the PCE version
  • No AIX, Solaris, or C-VEN are allowed
  • Users can only upgrade VENs paired to the same region
  • Only workload managers can upgrade VENs, and they can only upgrade VENs within their scope.

VEN API Methods

In addition to the page in the PCE web console that lists all VENs and shows the details of a single VEN, there is a Public Experimental API for getting VEN collections and VEN instances. Other new APIs support VEN filtering in the PCE web console, and update and unpair VENs.

VEN Methods HTTP URI
Get the collection of all VENs GET

[api_version][org_href]/vens/

Get details on a VEN instance GET [api_version][org_href]/vens/ven_id
Use to get the default release
without iterating through the
whole collection.		 GET [api_version[org_href]/software/vens/default
Support VEN filtering in the
PCE web console		 GET [api_version][org_href]/vens/autocomplete

[api_version][org_href]/vens/facets

To set the target_pce_fqdn
on a VEN

 PUT [api_version][org_href]/vens/ven_id
Update a VEN PUT

[api_version][org_href]/vens/update

Upgrade a VEN. This API
accepts a list
of hrefs instead of agent_ids.

The upgrade endpoint falls under the
/vens/resource
instead of the /software/resource.

 PUT [api_version][org_href]vens/upgrade
List VEN releases GET [api_version]/software/ven/releases

Unpair a VEN: trigger the unpairing
of one or more VENs.

NOTE: This endpoint replaces /workloads/unpair, which is deprecated.

 PUT

[api_version][org_href]/vens/unpair

Provided so that users can set the
default version for VEN pairing.		 PUT [api_version][org_href]/software/vens/default

Parameters

Parameter Description Type Required
org_id (GET, PUT, DELETE) Organization Integer Yes
ven_id (GET) VEN ID String Yes
activation_type (GET) The method in which the VEN was activated. Options are:
"pairing_key", "kerberos", "certificate"		 String No
active_pce_fqdn (GET) FQDN of the PCE String No
condition (GET) A specific error condition to filter by String No
disconnected_before (GET) Return VENs that have been disconnected since the given time date/time  
container_clusters ( GET) Array of container cluster URIs, encoded as a JSON string String No
health (GET) The overall health (condition) of the VEN String  
ip_address GET) IP address of VEN(s) to return. Supports partial matches String  
labels

(GET) Labels assigned to the host managed by the VEN.

 String  
name (GET) Friendly name for the VEN String  
last_goodbye_at (GET) The time (rfc3339 timestamp) of the last goodbye from the VEN. There are two parameters:
last_goodbye_at[gte]: Greater than or equal to value for last goodbye at timestamp
last_goodbye_at[lte]: Less than or equal to value for last goodbye at timestamp
 Bollean  
last_heartbeat_at (GET) The last time (rfc3339 timestamp) a heartbeat was received from this VEN. There are two parameters:
last_heartbeat_at[gte]: Greater than or equal to value for last heartbeat timestamp
last_heartbeat_at[lte]: Less than or equal to value for last heartbeat timestamp
 Boolean  
os (GET) Operating System of VEN(s) to return. Supports partial matches. String  
status (GET) The current status of the VEN. Options are:
"active", "suspended", "uninstalled"		 String  
version (GET) Software version of the VEN. Two parameters are used:
version[gte]: Greater than or equal to value for version
version[lte]: Less than or equal to value for version		 String  
hostname (GET) Hostname of VEN(s) to return. Supports partial matches. String No
release (PUT) The software release to set as the default for this org.
(GET, DELETE) Release identifier
 String Yes
ven_id (GET, PUT) VEN ID String  
description Description of VEN(s) to return. Supports partial matches    
upgrade_pending (GET) Only return VENs with/without a pending upgrade Boolean No
vens (PUT) VENs to unpair
Required property: href
 Array Yes
firewall_restore

(PUT) The strategy to use to restore the firewall state after the VEN is uninstalled.

The strategy to use to restore the firewall state after the VEN is uninstalled:

Options are: saved, default, and disable. The default is: default.

 String  

Response Properties

Property Description Type
secure_connect

Property: matching_issuer_name.
Issuer name match criteria for certificate used during establishing secure connections.

matching_issuer_name: Issuer name match criteria for certificate used while establishing secure connections.

Object

 

String
active_pce_fqdn The FQDN of the PCE that the VEN last connected to String
target_pce_fqdn The FQDN of the PCE that the VEN uses for future connections String
interfaces Network interfaces of the host managed by the VEN. Array
security_policy_applied_at Last reported time when policy was applied to the workload (UTC),
only present in expanded representations.		 date-time
security_policy_received_at Last reported time when policy was received by the workload (UTC),
only present in expanded representations.		 date-time
enforcement_mode

Policy enforcement mode, only present in expanded representations.

Options are: "idle", "visibility_only", "full", "selective"

 String
visibility_level

The amount of data the VEN collects and reports to the PCE from a
workload in the enforced mode (policy state), so you can control
resource demands on workloads.

The higher levels of detail are useful for visualizing traffic flows in
the Illumination map inside the PCE web console.
If this parameter is not set, then VEN visibility level is set to flow_summary.

  • flow_summary: (“High Detail” in the PCE web console)
    The VEN collects traffic connection details (source IP, destination IP,
    protocol, and source and destination port) for both allowed and blocked connections. This option creates traffic links in the Illumination map
    and is typically used during the building and testing phase of your
    security policy.
  • flow_drops: (“Less Detail” in the PCE web console.)
    The VEN only collects traffic connection details (source IP,
    destination IP, protocol, and source and destination port) for
    blocked connections. This option provides less detail for Illumination
    but demands fewer system resources from a workload and is typically
    used for policy enforcement.
  • flow_off: (“No Detail” in the PCE web console.)
    The VEN does not collect any details about traffic connections.
    This option provides no Illumination detail and demands the least
    amount of resources from workloads. This mode is useful when you
    are satisfied with the rules that have been created and do not need additional overhead from observing workload communication.
 String
os_id OS identifier of the host managed by the VEN String
os_detail Additional OS details from the host managed by the VEN Sring
os_platform OS platform of the host managed by the VEN String

GET VENs

To get a collection of VENs that have a specific label applied to them, take a label string that was returned when you got a collection of VENs, and then add a query parameter to GET all VENs with that specific label.

Curl Command to Get VENs with a Specific Label

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/vens?labels="[[/orgs/2/labels/1642]]" -H "Accept: application/json" -u $KEY:$TOKEN

To restrict the type of VENs you want returned and set a limit on how many results you want returned, use the relevant query parameters. For example, you might want to get a collection of no more than 50 VENs running CentOS 6.3 that have an active status.

Curl Command to Get VENs using other Query Parameters

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/vens?os_id=centos-x86_64-6.3&max_results=50&status=active -H "Accept: application/json"-u $KEY:$TOKEN

Unpairing and Suspending VENs

Instead of unpairing and suspending workloads, use the new VEN APIs to unpair and suspend VENs.

NOTE:

The endpoint workloads/unpair is DEPRECATED. Use /vens/unpair instead.

Curl Command for Unpairing VENs

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/vens/unpair -H "Content -Type:application/json" -u $KEY:$TOKEN -d '{"vens": [{"href": "/orgs/7/vens/xxxxxxxx-9611-44aa-ae06-fXXX8903db65"}, {"href": "/orgs/7/vens/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}], "firewall_restore": "default"}'

Curl Command to Mark VEN as Suspended

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/vens/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71 -H "Content-Type:application/json" -u $KEY:$TOKEN -d'{"status":"suspended"}'