IPsec Tunnel Configuration Object

Table of Contents

1. Overview
2. Core Methods
3. IPsec Tunnel Model Attributes
4. Auto Key Configuration
5. Exceptions
6. Basic Configuration
7. Usage Examples
   • Creating IPsec Tunnels
   • Retrieving IPsec Tunnels
   • Updating IPsec Tunnels
   • Listing IPsec Tunnels
   • Filtering Responses
   • Controlling Pagination with max_limit
   • Deleting IPsec Tunnels
8. Managing Configuration Changes
   • Performing Commits
   • Monitoring Jobs
9. Error Handling
10. Best Practices
11. Related Models

Overview

The IPsecTunnel class manages IPsec tunnel objects in Palo Alto Networks' Strata Cloud Manager. It extends from BaseObject and offers methods to create, retrieve, update, list, fetch, and delete IPsec tunnels. IPsec tunnels provide encrypted connectivity between sites and complete the VPN stack alongside the existing IKE Gateway and IPsec Crypto Profile services. Each tunnel requires an auto_key configuration that references one or more IKE gateways and an IPsec crypto profile.

Core Methods

Method	Description	Parameters	Return Type
create()	Creates a new IPsec tunnel	data: Dict[str, Any]	IPsecTunnelResponseModel
get()	Retrieves an IPsec tunnel by its unique ID	object_id: str	IPsecTunnelResponseModel
update()	Updates an existing IPsec tunnel	tunnel: IPsecTunnelUpdateModel	IPsecTunnelResponseModel
list()	Lists IPsec tunnels with optional filtering	folder: Optional[str], snippet: Optional[str], device: Optional[str], exact_match: bool = False, plus additional filters	List[IPsecTunnelResponseModel]
fetch()	Fetches a single IPsec tunnel by name within a container	name: str, folder: Optional[str], snippet: Optional[str], device: Optional[str]	IPsecTunnelResponseModel
delete()	Deletes an IPsec tunnel by its ID	object_id: str	None

IPsec Tunnel Model Attributes

Attribute	Type	Required	Default	Description
name	str	Yes	None	Tunnel name. Max 63 chars
id	UUID	Yes*	None	Unique identifier (*response/update only)
auto_key	AutoKey	Yes	None	Auto key configuration (IKE gateway + crypto profile)
anti_replay	bool	No	None	Enable anti-replay protection
copy_tos	bool	No	False	Copy TOS header
enable_gre_encapsulation	bool	No	False	Enable GRE encapsulation
tunnel_monitor	TunnelMonitor	No	None	Tunnel monitor configuration
folder	str	No**	None	Folder location. Max 64 chars
snippet	str	No**	None	Snippet location. Max 64 chars
device	str	No**	None	Device location. Max 64 chars

* Only required for update and response models ** Exactly one container (folder/snippet/device) must be provided for create operations

Auto Key Configuration

The auto_key attribute is required for all IPsec tunnels and contains the IKE gateway references and crypto profile settings.

AutoKey

Attribute	Type	Required	Description
ike_gateway	List[IkeGatewayRef]	Yes	List of IKE gateway references
ipsec_crypto_profile	str	Yes	IPsec crypto profile name
proxy_id	List[ProxyId]	No	List of proxy IDs
proxy_id_v6	List[ProxyId]	No	List of IPv6 proxy IDs

IkeGatewayRef

Attribute	Type	Required	Description
name	str	Yes	The name of the IKE gateway

ProxyId

Attribute	Type	Required	Description
name	str	Yes	The name of the proxy ID
local	str	No	Local address or subnet
remote	str	No	Remote address or subnet
protocol	ProxyIdProtocol	No	Protocol configuration

TunnelMonitor

Attribute	Type	Required	Default	Description
enable	bool	No	True	Enable tunnel monitoring
destination_ip	str	Yes	None	Destination IP for tunnel monitoring
proxy_id	str	No	None	Proxy ID for tunnel monitoring

Exceptions

Exception	HTTP Code	Description
InvalidObjectError	400	Thrown when provided data or parameters are invalid
MissingQueryParameterError	400	Thrown when required query parameters (e.g., name or folder) are missing
NameNotUniqueError	409	Tunnel name already exists
ObjectNotPresentError	404	Tunnel not found
ReferenceNotZeroError	409	Tunnel still referenced
AuthenticationError	401	Authentication failed
ServerError	500	Internal server error

Basic Configuration

The IPsec Tunnel service can be accessed using either the unified client interface (recommended) or the traditional service instantiation.

Unified Client Interface (Recommended)

from scm.client import ScmClient

# Initialize client
client = ScmClient(
   client_id="your_client_id",
   client_secret="your_client_secret",
   tsg_id="your_tsg_id"
)

# Access the IPsec Tunnel service directly through the client
ipsec_tunnels = client.ipsec_tunnel

Traditional Service Instantiation (Legacy)

from scm.client import Scm
from scm.config.network import IPsecTunnel

# Initialize client
client = Scm(
   client_id="your_client_id",
   client_secret="your_client_secret",
   tsg_id="your_tsg_id"
)

# Initialize IPsecTunnel object explicitly
ipsec_tunnels = IPsecTunnel(client)

Note

While both approaches work, the unified client interface is recommended for new development as it provides a more streamlined developer experience and ensures proper token refresh handling across all services.

Usage Examples

Creating IPsec Tunnels

from scm.client import ScmClient

# Initialize client
client = ScmClient(
   client_id="your_client_id",
   client_secret="your_client_secret",
   tsg_id="your_tsg_id"
)

# Create a basic IPsec tunnel
tunnel_data = {
   "name": "site-a-to-site-b",
   "auto_key": {
      "ike_gateway": [
         {"name": "gw-site-b"}
      ],
      "ipsec_crypto_profile": "aes256-sha256"
   },
   "anti_replay": True,
   "folder": "Texas"
}

new_tunnel = client.ipsec_tunnel.create(tunnel_data)
print(f"Created IPsec tunnel with ID: {new_tunnel.id}")

# Create an IPsec tunnel with proxy IDs and tunnel monitoring
advanced_tunnel_data = {
   "name": "hq-to-branch",
   "auto_key": {
      "ike_gateway": [
         {"name": "gw-branch-office"}
      ],
      "ipsec_crypto_profile": "suite-b-gcm-256",
      "proxy_id": [
         {
            "name": "proxy-1",
            "local": "10.0.0.0/24",
            "remote": "192.168.1.0/24",
            "protocol": {
               "number": 0
            }
         }
      ]
   },
   "anti_replay": True,
   "copy_tos": True,
   "tunnel_monitor": {
      "enable": True,
      "destination_ip": "192.168.1.1"
   },
   "folder": "Texas"
}

advanced_tunnel = client.ipsec_tunnel.create(advanced_tunnel_data)
print(f"Created advanced IPsec tunnel with ID: {advanced_tunnel.id}")

# Create an IPsec tunnel with GRE encapsulation
gre_tunnel_data = {
   "name": "gre-over-ipsec",
   "auto_key": {
      "ike_gateway": [
         {"name": "gw-remote"}
      ],
      "ipsec_crypto_profile": "aes128-sha1"
   },
   "enable_gre_encapsulation": True,
   "folder": "Texas"
}

gre_tunnel = client.ipsec_tunnel.create(gre_tunnel_data)
print(f"Created GRE-over-IPsec tunnel with ID: {gre_tunnel.id}")

Retrieving IPsec Tunnels

# Fetch by name and folder
tunnel = client.ipsec_tunnel.fetch(
   name="site-a-to-site-b",
   folder="Texas"
)
print(f"Found tunnel: {tunnel.name}")
print(f"  IKE Gateway: {tunnel.auto_key.ike_gateway[0].name}")
print(f"  Crypto Profile: {tunnel.auto_key.ipsec_crypto_profile}")

# Get by ID
tunnel_by_id = client.ipsec_tunnel.get(tunnel.id)
print(f"Retrieved tunnel: {tunnel_by_id.name}")

Updating IPsec Tunnels

# Fetch existing tunnel
existing_tunnel = client.ipsec_tunnel.fetch(
   name="site-a-to-site-b",
   folder="Texas"
)

# Enable anti-replay and tunnel monitoring
existing_tunnel.anti_replay = True
existing_tunnel.tunnel_monitor = {
   "enable": True,
   "destination_ip": "10.1.1.1"
}

# Update crypto profile
existing_tunnel.auto_key.ipsec_crypto_profile = "suite-b-gcm-256"

# Perform update
updated_tunnel = client.ipsec_tunnel.update(existing_tunnel)

Listing IPsec Tunnels

# List all IPsec tunnels in a folder
tunnels = client.ipsec_tunnel.list(
   folder="Texas"
)

# Process results
for tunnel in tunnels:
   print(f"Name: {tunnel.name}")
   print(f"  IKE Gateway(s): {', '.join(gw.name for gw in tunnel.auto_key.ike_gateway)}")
   print(f"  Crypto Profile: {tunnel.auto_key.ipsec_crypto_profile}")
   print(f"  Anti-Replay: {tunnel.anti_replay}")
   if tunnel.tunnel_monitor:
      print(f"  Tunnel Monitor: {tunnel.tunnel_monitor.destination_ip}")

# List with crypto profile filter
filtered_tunnels = client.ipsec_tunnel.list(
   folder="Texas",
   ipsec_crypto_profile=["aes256-sha256", "suite-b-gcm-256"]
)

for tunnel in filtered_tunnels:
   print(f"Filtered tunnel: {tunnel.name} ({tunnel.auto_key.ipsec_crypto_profile})")

Filtering Responses

The list() method supports additional parameters to refine your query results even further. Alongside basic filters, you can leverage the exact_match, exclude_folders, exclude_snippets, and exclude_devices parameters to control which objects are included or excluded after the initial API response is fetched.

Parameters:

• exact_match (bool): When True, only objects defined exactly in the specified container (folder, snippet, or device) are returned. Inherited or propagated objects are filtered out.
• exclude_folders (List[str]): Provide a list of folder names that you do not want included in the results.
• exclude_snippets (List[str]): Provide a list of snippet values to exclude from the results.
• exclude_devices (List[str]): Provide a list of device values to exclude from the results.

Examples:

# Only return tunnels defined exactly in 'Texas'
exact_tunnels = client.ipsec_tunnel.list(
   folder='Texas',
   exact_match=True
)

for tunnel in exact_tunnels:
   print(f"Exact match: {tunnel.name} in {tunnel.folder}")

# Exclude all tunnels from the 'All' folder
no_all_tunnels = client.ipsec_tunnel.list(
   folder='Texas',
   exclude_folders=['All']
)

for tunnel in no_all_tunnels:
   assert tunnel.folder != 'All'
   print(f"Filtered out 'All': {tunnel.name}")

Controlling Pagination with max_limit

The SDK supports pagination through the max_limit parameter, which defines how many objects are retrieved per API call. By default, max_limit is set to 2500. The API itself imposes a maximum allowed value of 5000. If you set max_limit higher than 5000, it will be capped to the API's maximum. The list() method will continue to iterate through all objects until all results have been retrieved. Adjusting max_limit can help manage retrieval performance and memory usage when working with large datasets.

Example:

from scm.client import ScmClient

# Initialize client
client = ScmClient(
   client_id="your_client_id",
   client_secret="your_client_secret",
   tsg_id="your_tsg_id"
)

# Configure max_limit using the property setter
client.ipsec_tunnel.max_limit = 4000

# List all tunnels - auto-paginates through results
all_tunnels = client.ipsec_tunnel.list(folder='Texas')

Deleting IPsec Tunnels

# Delete by ID
tunnel_id = "123e4567-e89b-12d3-a456-426655440000"
client.ipsec_tunnel.delete(tunnel_id)

Managing Configuration Changes

Performing Commits

# Prepare commit parameters
commit_params = {
   "folders": ["Texas"],
   "description": "Updated IPsec tunnel configurations",
   "sync": True,
   "timeout": 300  # 5 minute timeout
}

# Commit the changes directly on the client
result = client.commit(**commit_params)

print(f"Commit job ID: {result.job_id}")

Monitoring Jobs

# Get status of specific job directly from the client
job_status = client.get_job_status(result.job_id)
print(f"Job status: {job_status.data[0].status_str}")

# List recent jobs directly from the client
recent_jobs = client.list_jobs(limit=10)
for job in recent_jobs.data:
   print(f"Job {job.id}: {job.type_str} - {job.status_str}")

Error Handling

from scm.client import ScmClient
from scm.exceptions import (
   InvalidObjectError,
   MissingQueryParameterError,
   NameNotUniqueError,
   ObjectNotPresentError,
   ReferenceNotZeroError
)

# Initialize client
client = ScmClient(
   client_id="your_client_id",
   client_secret="your_client_secret",
   tsg_id="your_tsg_id"
)

try:
   # Create IPsec tunnel configuration
   tunnel_config = {
      "name": "test-tunnel",
      "auto_key": {
         "ike_gateway": [
            {"name": "test-gateway"}
         ],
         "ipsec_crypto_profile": "aes256-sha256"
      },
      "anti_replay": True,
      "folder": "Texas"
   }

   # Create the tunnel using the unified client interface
   new_tunnel = client.ipsec_tunnel.create(tunnel_config)

   # Commit changes directly from the client
   result = client.commit(
      folders=["Texas"],
      description="Added test IPsec tunnel",
      sync=True
   )

   # Check job status directly from the client
   status = client.get_job_status(result.job_id)

except InvalidObjectError as e:
   print(f"Invalid tunnel data: {e.message}")
except NameNotUniqueError as e:
   print(f"Tunnel name already exists: {e.message}")
except ObjectNotPresentError as e:
   print(f"Tunnel not found: {e.message}")
except ReferenceNotZeroError as e:
   print(f"Tunnel still in use: {e.message}")
except MissingQueryParameterError as e:
   print(f"Missing parameter: {e.message}")

Best Practices

1. Client Usage
2. Use the unified client interface (client.ipsec_tunnel) for streamlined code
3. Create a single client instance and reuse it across your application

4. Perform commit operations directly on the client object (client.commit())

5. VPN Stack Configuration

6. Create IKE crypto profiles and IPsec crypto profiles before creating tunnels
7. Configure IKE gateways before referencing them in IPsec tunnels
8. Use descriptive tunnel names that identify the connection endpoints

9. Follow the VPN configuration order: IKE Crypto Profile -> IPsec Crypto Profile -> IKE Gateway -> IPsec Tunnel

10. Tunnel Configuration

11. Always enable anti_replay for security against replay attacks
12. Use tunnel monitoring to detect and recover from tunnel failures
13. Configure proxy IDs when connecting to third-party VPN devices
14. Use GRE encapsulation only when routing protocols need to run over the tunnel

15. Set copy_tos when QoS preservation across the tunnel is required

16. Container Management

17. Always specify exactly one container (folder, snippet, or device)
18. Use consistent container names across operations

19. Validate container existence before operations

20. Error Handling

21. Implement comprehensive error handling for all operations
22. Check job status after commits
23. Handle specific exceptions before generic ones

24. Log error details for troubleshooting

25. Performance

26. Use appropriate pagination for list operations
27. Cache frequently accessed tunnel configurations

28. Implement proper retry mechanisms

29. Security

30. Use strong crypto profiles (AES-256, SHA-256 or better)
31. Regularly rotate IKE and IPsec keys
32. Monitor tunnel status for unexpected disconnections
33. Review and audit tunnel configurations periodically

Related Models

• IPsecTunnelBaseModel
• IPsecTunnelCreateModel
• IPsecTunnelUpdateModel
• IPsecTunnelResponseModel
• AutoKey
• IkeGatewayRef
• ProxyId
• TunnelMonitor