traffic#

The following methods allow for interaction with the ZIA Traffic Management API endpoints.

Methods are accessible via zia.traffic

class TrafficForwardingAPI#

Bases: object

add_gre_tunnel(source_ip, primary_dest_vip_id=None, secondary_dest_vip_id=None, **kwargs)#

Add a new GRE tunnel.

Note: If the primary_dest_vip_id and secondary_dest_vip_id aren’t specified then the closest recommended VIPs will be automatically chosen.

Parameters:

  • source_ip (str) – The source IP address of the GRE tunnel. This is typically a static IP address in the organisation or SD-WAN.

  • primary_dest_vip_id (str) – The unique identifier for the primary destination virtual IP address (VIP) of the GRE tunnel. Defaults to the closest recommended VIP.

  • secondary_dest_vip_id (str) – The unique identifier for the secondary destination virtual IP address (VIP) of the GRE tunnel. Defaults to the closest recommended VIP that isn’t in the same city as the primary VIP.

Keyword Arguments:

  • **comment (str) – Additional information about this GRE tunnel

  • **ip_unnumbered (bool) – This is required to support the automated SD-WAN provisioning of GRE tunnels, when set to true gre_tun_ip and gre_tun_id are set to null

  • **internal_ip_range (str) – The start of the internal IP address in /29 CIDR range.

  • **within_country (bool) – Restrict the data center virtual IP addresses (VIPs) only to those within the same country as the source IP address.

Returns:

The resource record for the newly created GRE tunnel.

Return type:

Box

Examples

Add a GRE tunnel with closest recommended VIPs:

>>> zia.traffic.add_gre_tunnel('203.0.113.10')

Add a GRE tunnel with explicit VIPs:

>>> zia.traffic.add_gre_tunnel('203.0.113.11',
...    primary_dest_vip_id='88088',
...    secondary_dest_vip_id='54590',
...    comment='GRE Tunnel for Manufacturing Plant')
add_static_ip(ip_address, **kwargs)#

Adds a new static IP.

Parameters:

ip_address (str) – The static IP address

Keyword Arguments:

  • **comment (str) – Additional information about this static IP address.

  • **geo_override (bool) – If not set, geographic coordinates and city are automatically determined from the IP address. Otherwise, the latitude and longitude coordinates must be provided.

  • **routable_ip (bool) – Indicates whether a non-RFC 1918 IP address is publicly routable. This attribute is ignored if there is no ZIA Private Service Edge associated to the organization.

  • **latitude (float) – Required only if the geoOverride attribute is set. Latitude with 7 digit precision after decimal point, ranges between -90 and 90 degrees.

  • **longitude (float) – Required only if the geoOverride attribute is set. Longitude with 7 digit precision after decimal point, ranges between -180 and 180 degrees.

Returns:

The resource record for the newly created static IP.

Return type:

Box

Examples

Add a new static IP address:

>>> zia.traffic.add_static_ip(ip_address='203.0.113.10',
...    comment="Los Angeles Branch Office")
add_vpn_credential(authentication_type, pre_shared_key=None, **kwargs)#

Add new VPN credentials.

If a pre_shared_key is not provided, one will be randomly generated.

Parameters:

  • authentication_type (str) –

    VPN authentication type (i.e., how the VPN credential is sent to the server). It is not modifiable after VpnCredential is created.

    Only IP and UFQDN supported via API.

  • pre_shared_key (str, optional) – This field is required for UFQDN and IP auth type. If not provided a random one will be generated.

Keyword Arguments:

  • ip_address (str) – The static IP address associated with these VPN credentials.

  • fqdn (str) – Fully Qualified Domain Name. Applicable only to UFQDN auth type. This must be provided in the format userid@fqdn, where the fqdn is an authorised domain for your tenancy.

  • comments (str) – Additional information about this VPN credential.

  • location_id (str) – Associate the VPN credential with an existing location.

Returns:

The newly created VPN credential resource record.

Return type:

Box

bulk_delete_vpn_credentials(credential_ids)#

Bulk delete VPN credentials.

Parameters:

credential_ids (list) – List of credential IDs that will be deleted.

Returns:

Response code for operation.

Return type:

int

Examples

>>> zia.traffic.bulk_delete_vpn_credentials(['94963984', '97679232'])
check_static_ip(ip_address)#

Validates if a static IP object is correct.

Parameters:

ip_address (str) – The static IP address

Returns:

True if the static IP provided is valid, False otherwise.

Return type:

bool

Examples

>>> zia.traffic.check_static_ip(ip_address='203.0.113.11')
delete_gre_tunnel(tunnel_id)#

Delete the specified static IP.

Parameters:

static_ip_id (str) – The unique identifier for the static IP.

Returns:

The response code for the operation.

Return type:

int

Examples

>>> zia.traffic.delete_gre_tunnel('972494')
delete_static_ip(static_ip_id)#

Delete the specified static IP.

Parameters:

static_ip_id (str) – The unique identifier for the static IP.

Returns:

The response code for the operation.

Return type:

int

Examples

>>> zia.traffic.delete_static_ip('972494')
delete_vpn_credential(credential_id)#

Delete VPN credentials for the specified ID.

Parameters:

credential_id (str) – The unique identifier for the VPN credentials that will be deleted.

Returns:

Response code for the operation.

Return type:

int

Examples

>>> zia.traffic.delete_vpn_credential('97679391')
get_closest_diverse_vip_ids(ip_address)#

Returns the closest diverse Zscaler destination VIPs for a given IP address.

Parameters:

ip_address (str) – The IP address used for locating the closest diverse VIPs.

Returns:

Tuple containing the preferred and secondary VIP IDs.

Return type:

tuple

Examples

>>> closest_vips = zia.traffic.get_closest_diverse_vip_ids('203.0.113.20')
get_gre_tunnel(tunnel_id)#

Returns information for the specified GRE tunnel.

Parameters:

tunnel_id (str) – The unique identifier for the GRE tunnel.

Returns:

The GRE tunnel resource record.

Return type:

Box

Examples

>>> gre_tunnel = zia.traffic.get_gre_tunnel('967134')
get_static_ip(static_ip_id)#

Returns information for the specified static IP.

Parameters:

static_ip_id (str) – The unique identifier for the static IP.

Returns:

The resource record for the static IP

Return type:

dict

Examples

>>> static_ip = zia.traffic.get_static_ip('967134')
get_vpn_credential(credential_id=None, fqdn=None)#

Get VPN credentials for the specified ID or fqdn.

Parameters:

  • credential_id (str, optional) – The unique identifier for the VPN credentials.

  • fqdn (str, optional) – The unique FQDN for the VPN credentials.

Returns:

The resource record for the requested VPN credentials.

Return type:

Box

Examples

>>> pprint(zia.traffic.get_vpn_credential('97679391'))

>>> pprint(zia.traffic.get_vpn_credential(fqdn='userid@fqdn'))
list_gre_ranges(**kwargs)#

Returns a list of available GRE tunnel ranges.

Keyword Arguments:

  • **internal_ip_range (str, optional) – Internal IP range information.

  • **static_ip (str, optional) – Static IP information.

  • **limit (int, optional) – The maximum number of GRE tunnel IP ranges that can be added. Defaults to 10.

Returns:

A list of available GRE tunnel ranges.

Return type:

BoxList

Examples

>>> gre_tunnel_ranges = zia.traffic.list_gre_ranges()
list_gre_tunnels(**kwargs)#

Returns the list of all configured GRE tunnels.

Keyword Arguments:

  • **max_items (int, optional) – The maximum number of items to request before stopping iteration.

  • **max_pages (int, optional) – The maximum number of pages to request before stopping iteration.

  • **page_size (int, optional) – Specifies the page size. The default size is 100, but the maximum size is 1000.

Returns:

A list of GRE tunnels configured in ZIA.

Return type:

BoxList

Examples

List GRE tunnels with default settings:

>>> for tunnel in zia.traffic.list_gre_tunnels():
...    print(tunnel)

List GRE tunnels, limiting to a maximum of 10 items:

>>> for tunnel in zia.traffic.list_gre_tunnels(max_items=10):
...    print(tunnel)

List GRE tunnels, returning 200 items per page for a maximum of 2 pages:

>>> for tunnel in zia.traffic.list_gre_tunnels(page_size=200, max_pages=2):
...    print(tunnel)
list_static_ips(**kwargs)#

Returns the list of all configured static IPs.

Keyword Arguments:

  • **available_for_gre_tunnel (bool, optional) – Only return the static IP addresses that are not yet associated with a GRE tunnel if True. Defaults to False.

  • **ip_address (str, optional) – Filter based on IP address.

  • **max_items (int, optional) – The maximum number of items to request before stopping iteration.

  • **max_pages (int, optional) – The maximum number of pages to request before stopping iteration.

  • **page_size (int, optional) – Specifies the page size. The default size is 100, but the maximum size is 1000.

Returns:

A list of the configured static IPs

Return type:

BoxList

Examples

List static IPs using default settings:

>>> for ip_address in zia.traffic.list_static_ips():
...    print(ip_address)

List static IPs, limiting to a maximum of 10 items:

>>> for ip_address in zia.traffic.list_static_ips(max_items=10):
...    print(ip_address)

List static IPs, returning 200 items per page for a maximum of 2 pages:

>>> for ip_address in zia.traffic.list_static_ips(page_size=200, max_pages=2):
...    print(ip_address)
list_vip_group_by_dc(source_ip, **kwargs)#

Returns a list of recommended GRE tunnel (VIPs) grouped by data center.

Parameters:

  • source_ip (str) – The source IP address.

  • **kwargs – Optional keywords args.

Keyword Arguments:

  • routable_ip (bool) – The routable IP address. Default: True.

  • within_country_only (bool) – Search within country only. Default: False.

  • include_private_service_edge (bool) – Include ZIA Private Service Edge VIPs. Default: True.

  • include_current_vips (bool) – Include currently assigned VIPs. Default: True.

  • latitude (str) – Latitude coordinate of GRE tunnel source.

  • longitude (str) – Longitude coordinate of GRE tunnel source.

  • geo_override (bool) – Override the geographic coordinates. Default: False.

Returns:

List of VIP resource records.

Return type:

BoxList

Examples

Return recommended VIPs for a given source IP:

>>> for vip in zia.vips.list_vip_group_by_dc(source_ip='203.0.113.30'):
...    pprint(vip)
list_vips(**kwargs)#

Returns a list of virtual IP addresses (VIPs) available in the Zscaler cloud.

Keyword Arguments:

  • **dc (str, optional) – Filter based on data center.

  • **include (str, optional) – Include all, private, or public VIPs in the list. Available choices are all, private, public. Defaults to public.

  • **max_items (int, optional) – The maximum number of items to request before stopping iteration.

  • **max_pages (int, optional) – The maximum number of pages to request before stopping iteration.

  • **page_size (int, optional) – Specifies the page size. The default size is 100, but the maximum size is 1000.

  • **region (str, optional) – Filter based on region.

Returns:

List of VIP resource records.

Return type:

BoxList

Examples

List VIPs using default settings:

>>> for vip in zia.vips.list_vips():
...    pprint(vip)

List VIPs, limiting to a maximum of 10 items:

>>> for vip in zia.vips.list_vips(max_items=10):
...    print(vip)

List VIPs, returning 200 items per page for a maximum of 2 pages:

>>> for vip in zia.traffic.list_vips(page_size=200, max_pages=2):
...    print(vip)

Returns a list of recommended virtual IP addresses (VIPs) based on parameters.

Parameters:

  • source_ip (str) – The source IP address.

  • **kwargs – Optional keywords args.

Keyword Arguments:

  • routable_ip (bool) – The routable IP address. Default: True.

  • within_country_only (bool) – Search within country only. Default: False.

  • include_private_service_edge (bool) – Include ZIA Private Service Edge VIPs. Default: True.

  • include_current_vips (bool) – Include currently assigned VIPs. Default: True.

  • latitude (str) – Latitude coordinate of GRE tunnel source.

  • longitude (str) – Longitude coordinate of GRE tunnel source.

  • geo_override (bool) – Override the geographic coordinates. Default: False.

Returns:

List of VIP resource records.

Return type:

BoxList

Examples

Return recommended VIPs for a given source IP:

>>> for vip in zia.traffic.list_vips_recommende(source_ip='203.0.113.30'):
...    pprint(vip)
list_vpn_credentials(**kwargs)#

Returns the list of all configured VPN credentials with optional filtering.

Parameters:

**kwargs – Optional keyword search filters.

Keyword Arguments:

  • search (str, optional) – The search string used to match against a VPN credential’s attributes.

  • type (str, optional) – Only gets VPN credentials for the specified type (CN, IP, UFQDN, XAUTH).

  • include_only_without_location (bool, optional) – Include VPN credential only if not associated to any location.

  • location_id (int, optional) – Gets the VPN credentials for the specified location ID.

  • managedBy (int, optional) – Gets the VPN credentials managed by the given partner.

  • max_items (int, optional) – The maximum number of items to request before stopping iteration.

  • max_pages (int, optional) – The maximum number of pages to request before stopping iteration.

  • page_size (int, optional) – Specifies the page size. The default size is 100, but the maximum size is 1000.

Returns:

List containing the VPN credential resource records.

Return type:

BoxList

Examples

List VPN credentials using default settings:

>>> for credential in zia.traffic.list_vpn_credentials:
...    pprint(credential)

List VPN credentials, limiting to a maximum of 10 items:

>>> for credential in zia.traffic.list_vpn_credentials(max_items=10):
...    print(credential)

List VPN credentials, returning 200 items per page for a maximum of 2 pages:

>>> for credential in zia.traffic.list_vpn_credentials(page_size=200, max_pages=2):
...    print(credential)
update_gre_tunnel(tunnel_id, source_ip=None, primary_dest_vip_id=None, secondary_dest_vip_id=None, **kwargs)#

Update an existing GRE tunnel.

update_static_ip(static_ip_id, **kwargs)#

Updates information relating to the specified static IP.

Parameters:

  • static_ip_id (str) – The unique identifier for the static IP

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • **comment (str) – Additional information about this static IP address.

  • **geo_override (bool) – If not set, geographic coordinates and city are automatically determined from the IP address. Otherwise, the latitude and longitude coordinates must be provided.

  • **routable_ip (bool) – Indicates whether a non-RFC 1918 IP address is publicly routable. This attribute is ignored if there is no ZIA Private Service Edge associated to the organization.

  • **latitude (float) – Required only if the geoOverride attribute is set. Latitude with 7 digit precision after decimal point, ranges between -90 and 90 degrees.

  • **longitude (float) – Required only if the geoOverride attribute is set. Longitude with 7 digit precision after decimal point, ranges between -180 and 180 degrees.

Returns:

The updated static IP resource record.

Return type:

Box

Examples

>>> zia.traffic.update_static_ip('972494', comment='NY Branch Office')
update_vpn_credential(credential_id, **kwargs)#

Update VPN credentials with the specified ID.

Parameters:

credential_id (str) – The unique identifier for the credential that will be updated.

Keyword Arguments:

  • pre_shared_key (str) – Pre-shared key. This is a required field for UFQDN and IP auth type.

  • comments (str) – Additional information about this VPN credential.

  • location_id (str) – The unique identifier for an existing location.

Returns:

The newly updated VPN credential resource record.

Return type:

Box

Examples

Add a comment:

>>> zia.traffic.update_vpn_credential('94963984',
...    comments='Adding a comment')

Update the pre-shared key:

>>> zia.traffic.update_vpn_credential('94963984',
...    pre_shared_key='MyNewInsecureKey',
...    comments='Pre-shared key rotated on 21 JUL 21')