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"}'

REST APIs for 22.2