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, the PCE assumes that the workload is offline and removes it from the policy after one hour. 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 on 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 can 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 (The `href` property in each interface in the VEN interfaces array is dropped from the response.)	`GET`	`[api_version][org_href]/vens/`
Get details on a VEN instance (The `href` property in each interface in the VEN interfaces array is dropped from the response)	`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 `/vens/resource` instead of the `/software/resource`.	`PUT`	`[api_version][org_href]vens/upgrade`
Lists the VEN releases available to the org, one per VEN version, along with metadata such as whether it is the default version, whether that release supports servers and/or endpoints, and so on. The list of images is longer than the list of releases, and multiple images belong to the same release version.	`GET`	`[api_version]/software/ven/releases`
Shows the full list of VEN images. There is one image for each Linux distribution we support (such as RHEL, Ubuntu), plus images for Windows and macOS.	`GET`	`[api_version]/software/ven/releases-images`
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`

VEN Parameters

Parameter	Description	Type	Required
`org_id`	Organization ID	Integer	Yes
`activation_type`	The method by which the VEN was activated	String	No
`active_pce_fqdn`	FQDN of the PCE	String	No
`activation_recovery`	Return VENs in or not in authentication recovery	Boolean	No
`condition`	A specific error condition to filter by	String	No
`container_clusters`	An array of container cluster URIs, encoded as a JSON string	Object	No
`disconnected_before`	Return VENs that have been disconnected since the given time.	date/time	No
`health`	The overall health (condition) of the VEN	String	No
`hostname`	The hostname of VEN(s) to return. Supports partial matches.	String	No
`ip_addressl`	IP address of VEN(s) to return. Supports partial matches	Sring	No
`last_goodbye_at`	The time (rfc3339 timestamp) of the last goodbye from the VEN.	String, Null
`os_platform`	OS platform of the host managed by the VEN	String, Null
`version`	Software version of the VEN.	String
`status`	The current status of the VEN. Options are: "active", "suspended", "uninstalled"	String
`activation_type`	The method in which the VEN was activated. Options are: "pairing_key", "kerberos", "certificate"	String, Null	No
`active_pce_fqdn`	The FQDN of the PCE that the VEN last connected to	String, Null	No
`target_pce_fqdn`	cluster FQDN for target PCE	String, Null
`labels`	Labels assigned to the host managed by the VEN.	Array
`interfaces`	Network interfaces of the host managed by the VEN.	Array
`workloads`	The only required property is `HREF`, the others are optional: `name`, `managed`, `hostname`, `os_id`, `os_detail`, `labels`, `interfaces`, etc.	Array
`description`	Description of VEN(s) to return. Supports partial matches	String, Null
`last_heartbeat_at`	The last time (rfc3339 timestamp) a heartbeat was received from this VEN.	String, Null
`status`	VEN Status: "active" "suspended"	String
`ven_type`	The `ven_type` property is introduced through the reference to a common schema `ven_type.schema.json`:	String	No

Properties

Parameter	Description	Type	Required
`ven_type`	The type of the release marked as default: "server", "endpoint"	String	No
`default_release_ven_types`	The type of the release marked as default	String
`name`	Friendly name for the VEN	String, Null
`hostname`	The hostname of the host managed by the VEN	String, Null	Yes
`uid`	The unique ID of the host managed by the VEN	String, Null
`os_id`	OS identifier of the host managed by the VEN	String, Null
`os_detail`	Additional OS details from the host managed by the VEN	Sring, Null
`os_platform`	OS platform of the host managed by the VEN	String, Null
`version`	Software version of the VEN.	String
`status`	The current status of the VEN. Options are: "active", "suspended", "uninstalled"	String
`activation_type`	The method in which the VEN was activated. Options are: "pairing_key", "kerberos", "certificate"	String, Null	No
`active_pce_fqdn`	The FQDN of the PCE that the VEN last connected to	String, Null	No
`target_pce_fqdn`	cluster FQDN for target PCE	String, Null
`labels`	Labels assigned to the host managed by the VEN.	Array
`interfaces`	Network interfaces of the host managed by the VEN.	Array
`workloads`	The only required property is `HREF`, the others are optional: `name`, `managed`, `hostname`, `os_id`, `os_detail`, `labels`, `interfaces`, etc. `managed`: `True` if the workload is managed, else `false`.	Array
`container_clusters`	Array of container cluster URIs, encoded as a JSON string	Object	No
`secure_connect`	Issuer name match criteria for certificate used during establishing secure connections	Object, Null
`last_heartbeat_at`	The last time (rfc3339 timestamp) a heartbeat was received from this VEN.	String, Null
`last_goodbye_at`	The time (rfc3339 timestamp) of the last goodbye from the VEN.	String, Null
`status`	VEN Status: "active" "suspended"	String
`disconnected_before`	Return VENs that have been disconnected since the given time	date/time
`health`	The overall health (condition) of the VEN	String
`ip_address`	IP address of VEN(s) to return. Supports partial matches	String
`firewall_restore`	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`. Works with `vens_unpair_put`.	String
`ven_id`	VEN ID (works with `GET /api/v2/orgs/{org_id}/vens/{ven_id}`)	String
`vens`	VENs to unpair (works with `PUT /api/v2/orgs/{org_id}/vens/unpair`) Required property: `href`	Array	Yes
`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
`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` Null
`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
`upgrade_pending`	Only return VENs with/without a pending upgrade	Boolean	No
`ven_type`	The `ven_type` property is introduced through the reference to a common schema `ven_type.schema.json`:	String	No
`upgrade_expires_at`	The time (rfc3339 timestamp) at which the PCE stops attempting VEN upgrade	String. Null	No
`upgrade_target_version`	The software release to upgrade to	String, Null	No
`upgrade_timeout_seconds`	Number of seconds during which the PCE tries to trigger the agent upgrade: "minimum": 900, "maximum": 15552000	Integer

Software VEN Releases

release_ven_types

{
	"$schema": "hp://json-schema.org/draft-04/schema#",
	"description": "Supported ven types in this release",
	"type": "array",
	"items": {
		"type": "string",
			"enum": ["server", "endpoint"]
		}
}

The new common schema release_ven_types is introduced to show ven_types for each release and to filter releases by ven_type.

Previously, the ven_type was not stored for the release, and database records looked as follows:

Release	Distributiion
22.5.1	CentOS
22.5.1	MacOS
22.5.1	Windows

With the property ven_type added, the database records are expanded with an additional ven_types column:

Release	Distributiion	ven_types
22.5.1	CentOS	server + endpoint
22.5.1	MacOS	server + endpoint
22.5.1	Windows	server + endpoint

Note that in release 22.5.1 the code supports the type "server+endpont". However, Centos (Linux) supports a server-only VEN image, MasOS supports endpoint-only image, and Windows supports both server and endpoint:

Release	Distributiion	ven_types
22.5.1	CentOS	server
22.5.1	MacOS	endpoint
22.5.1	Windows	server + endpoint

When a user opens the list of release images via UI and looks for the type server + endpoint, only the Windows image will show up as a complete match.

To fix this issue, the ven_type is now based on release and distribution:

All releases before 21.2.2 were just server (there was no endpoint)
Any release with 22.3.x was endpoint (there was no server)
Any other releases were server + endpoint , but instead of setting it to all the images (database records), the ven_types are set in a way that is specific for the Os.

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

Network Enforcement Nodes (NEN) APIs

Network Enforcement Node Reassignment

`network_enforcement_nodes_put`

This API is used to change the target PCE FQDN of an agent.

It updates the target_pce_fqdn property so that the NEN can be managed by a different PCE in a Supercluster.

Change Target PCE

When you have the NEN HREF, you can update the target PCE with the PCE FQDN the NEN will use. In your JSON request body, pass the following data:

	"target_pce_fqdn": "new-pce-fqdn.example.com"
}

The URI for this operation is:

PUT [api_version][nen_href]/update

This curl example shows how you can pass the target_pce_fqdn property containing the FQDN of the new PCE:

curl -u api_xxxxxxx64fcee809:'xxxxxxx5048a6a85ce846a706e134ef1d4bf2ac1f253b84c1bf8df6b83c70d95' -H "Accept: application/json" -H "Content-Type:application/json" -X PUT -d '{"target_pce_fqdn":"new-pce-fqdn.example.com"}' https://my.pce.supercluster:443/api/v1/orgs/3/network_enforcement_nodes/f67d35d5-ea71-42da-b40d-8dcc3b1420c2/update

Authorization and Exposure Changes

Some of the existing Experimental APIs have been changed in release 23.5.0 to facilitate creation of fully scripted integrations of endpoint management systems with the PCE using the Network Enforcement Nodes (NEN) Switch integration capabilities.

Exposure Changes

Exposure of the listed NEN APIs was changed in release 23.5.0 from Public Experimental to Public Stable.

Authorization Changes

Authorization of some NEN APIs was changed in release 23.5.0 from the default ( "Global Administrator" and "Global Organization Owner") to authorize additional users as listed in the table.

API	Exposure Change	New Authorization Change
`network_device_config`	YES	NO
`network_device_get`	YES	NO
`network_device_network_endpoint_get`	YES	NO
`network_devices_enforcement _instructions_applied_post`	YES	"Global Policy Object Provisioner" and " Ruleset Provisioner"
`network_devices_enforcement _instructions_request_post`	YES	"Global Policy Object Provisioner" and " Ruleset Provisioner"
`network_devices_get`	YES	"Global Policy Object Provisioner", "Global Read Only", "Limited Ruleset Manager", "Ruleset Provisioner", "Ruleset Viewer", "Workload Manager"
`network_devices_multi_enforcement _instructions_applied_post`	YES	"Global Policy Object Provisioner" and " Ruleset Provisioner"
`network_devices_multi_enforcement _instructions_request_post`	YES	"Global Policy Object Provisioner" and " Ruleset Provisioner"
`network_devices_network_endpoints_get`	YES	NO
`network_devices_network_endpoints_post`	YES	"Workload Manager"
`network_devices_network_endpoints_put`	YES	"Workload Manager"
`network_devices_put`	YES	"Workload Manager"
`network_endpoint_config`	YES	NO
`network_enforcement_node_get`	YES	NO
`network_enforcement_nodes_get`	YES	"Full Ruleset Manager", "Global Policy Object Provisioner", "Global Read Only", "Limited Ruleset Manager", "Ruleset Provisioner", "Ruleset Viewer", "Workload Manager"
`network_enforcement_nodes_network_devices_post`	YES	"Workload Manager"
`network_enforcement_nodes_put`	YES	NO

REST APIs for 23.5