Skip to main content

REST APIs for 24.2.20 and 24.2.10

Policy Update Mode

This Public Experimental API controls when policy updates are applied to workloads.

Overview of Policy Update Mode

The PCE has two policy update options:

  • Adaptive: Apply policy changes as soon as you provision.

  • Static: Apply policy changes later, such as during a scheduled maintenance window.

By default, the PCE policy update mode is set to Adaptive, but you can configure Static policy update mode for specific sets of workloads identified by scopes. Workloads that share the same labels configured for static policy update scope receive policy changes from the PCE. Still, those changes will not be applied until a user or an orchestration system instructs the PCE to apply those changes.

Configuring static policy update mode requires defining a scope that contains one or more environment, application, or location and role labels. If a label type is not defined in the scope, that label type is interpreted as All. For example, if the policy update scope is

Application = Checking, Location = China,

The PCE interprets the scope as

Application = Checking, Location = China, Environment = All.

Methods for policy update

Functionality

HTTP

URI

Get the current policy update mode for your organization.

GET

[api_version][org_href]/sec_policy/draft/ firewall_settings

Change the policy update mode for your organization.

PUT

[api_version][org_href]/sec_policy/draft/ firewall_settings

Get Policy Update Mode

You can use this method to get your organization's current policy update mode settings, which is part of your PCE security settings. This method contains a variable (:pversion) that can be used to return the security settings with active (currently provisioned) or draft state for your organization.

URI To Get Policy Update Mode

GET [api_version][org_href]/sec_policy/draft/firewall_settings
Change Policy Update Mode

The Change Policy Update Mode sets your organization's draft policy update mode, which might include adding or removing a policy scope.

The draft state of your policy update mode can be modified, but not the currently active (provisioned) version. First, change to the draft policy update mode, and then provision those changes.

URI To Change Policy Update Mode

PUT [api_version][org_href]/sec_policy/draft/firewall_settings
Remove all Static Policy Scopes

To remove all static policy scopes, pass an empty JSON array:

PUT [api_version][org_href]/sec_policy/draft/firewall_settings { "static_policy_scopes": [] }

Note

The policy update mode is set to Adaptive when all static policy scopes are removed.

Policy Update Mode Reference

This topic covers properties, parameters, and examples for policy update mode.

Parameters

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy Version

String

Yes

max_results

Maximum number of policy objects to return (per type)

Integer

No

Properties

The current firewall_settings resource specifies a combination of IPsec / IKE authentication method (PSK or certificate) for SecureConnect and Machine Authentication.

Parameter

Description

Type

Required

update_type

Type of update

String

Yes

static_policy_scopes

Scopes that have static policy application mode

Reference to common/rule_set_scopes_get.schema.json

No

max_results

Maximum number of policy objects to return (per type)

Integer

No

ike_authentication_type

IKE authentication type to use for IPsec (SecureConnect and Machine Authentication)

String

No

allow_captive_portal_outbound

Defines whether or not to open the endpoint firewall to all outbound traffic when the VEN discovers a captive portal scenario

Boolean

No

containers_inherit_host_ policy_scopes

A workload that matches the scope will apply the policy it receives to itself and the containers it hosts.

Reference to common/rule_set_scopes_get.schema.json

blocked_connection_ reject_scopes

Scopes whose blocked connection action will be rejected

Reference to common/rule_set_scope_get.schema.json

loopback_interfaces_in_ policy_scopes

Workloads that match the scope will apply policy on loopback interfaces and the loopback interface's IPs will be distributed to peers.

Reference to common/rule_set_scope_get.schema.json

Draft or Active Policy Update Mode

Variable

Description

:pversion

Allows you to get:

  • active: The currently provisioned security settings, including policy update mode

  • draft: The draft state of any changed security settings that have not yet been provisioned, including policy update mode

Examples

Curl Command Get Active Policy Update Mode

This curl example gets the active (currently provisioned) security settings for your organization, which includes the policy update mode settings.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/sec_policy/active/firewall_settings -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

The static_policy_scopes property in the response (in blue ) indicates that two static scopes have been configured for policy update.

Each scope is defined as a JSON array of labels, which includes an Application, Environment, and a Location label. The labels in the scope are identified by their HREFs.

{
    "href": "/orgs/7/sec_policy/active/firewall_settings",
    "created_at": "2015-10-23T22:01:01.151Z",
    "updated_at": "2017-09-02T19:08:55.623Z",
    "deleted_at": null,
    "created_by": { "href": "/users/0"  },
    "updated_by": { "href": "/users/14" },
    "deleted_by": null,    
    "update_type": null,
    "allow_dhcp_client": true,
    "log_dropped_multicast": true,
    "log_dropped_broadcast": false,
    "allow_traceroute": true,
    "allow_ipv6": true,
    "allow_igmp": false,
    "track_flow": true,
    "system_rule_log_flow": false,
    "allow_path_mtu_discovery": true,
    "network_detection_mode": "single_private_brn",
    "static_policy_scopes": [
      [
        { "label": { "href": "/orgs/7/labels/83" } },
        { "label": { "href": "/orgs/7/labels/86" } },
        { "label": { "href": "/orgs/7/labels/94" } }
      ],
      [
        { "label": { "href": "/orgs/7/labels/82"  } },
        { "label": { "href": "/orgs/7/labels/100" } },
        { "label": { "href": "/orgs/7/labels/89"  } },
        { "label": { "href": "/orgs/7/labels/94"  } }
      ]
    ],
      "secure_connect_certs": {
      "default_issuer_name_match": "test",
      "scoped_certificates": []
    }
}

Properties to change the policy update.

Property

Description

Type

Required

static_policy_scopes

A set of up to four labels, one or more of the type Application, Environment, Role, and Location.

Each label in the policy scope is identified by its HREF, nested in a JSON array.

Before updating the organization policy update mode, make sure you have the exact set of labels you want to use and their HREFs.

JSON

array of strings

Yes

Request Body

This example shows the request body for two policy update scopes. The first has a single label scope, and the second scope has a set of three labels.

{ 
  "static_policy_scopes": [
    [ 
      { "label": { "href": "/orgs/1/labels/8" } }
    ],
    [
      { "label": { "href": "/orgs/1/labels/2"  } },
      { "label": { "href": "/orgs/1/labels/8"  } },
      { "label": { "href": "/orgs/1/labels/11" } }
    ]
  ]
}

Curl Command to Update Policy Update Mode

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/firewall_settings -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"static_policy_scopes":[[{"label":{"href":"/orgs/1/labels/8"}}],[{"label":{"href":"/orgs/1/labels/2"}},{"label":{"href":"/orgs/1/labels/8"}},{"label":{"href":"/orgs/1/labels/11"}}]]}'

Response

The response for a successful change to your policy update mode is an HTTP 204 No Content Operation. No data is returned.

Curl Command to Remove Static Policy Scopes

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/firewall_settings -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"static_policy_scopes":[]}'
See also: