smc-python

https://smc-python.readthedocs.io/en/latest/
Admin
smc-python is a Python library that provides an interface to the Stonesoft Management Center,...
Tokens:394,599
Snippets:3,691
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install smc-python from tarball

Source: https://smc-python.readthedocs.io/en/latest/pages/installation.html

For offline installations or specific environments, download the tarball, unzip, and run the setup script.

```bash
python setup.py install

```

--------------------------------

### Install License from File - Python

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/system.html

Installs a new license by providing the fully qualified path to the license file. The file must be accessible by the system.

```python
system.license_install(license_file='/path/to/your/license.key')
```

--------------------------------

### Install License

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/system.html

Installs a new license from a specified file path.

```APIDOC
## POST /system/license_install

### Description
Install a new license.

### Method
POST

### Endpoint
/system/license_install

### Parameters
#### Request Body
- **license_file** (file) - Required - Fully qualified path to the license jar file.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message of successful installation.

### Response Example
```json
{
  "message": "License installed successfully"
}
```
```

--------------------------------

### Install smc-python using pip

Source: https://smc-python.readthedocs.io/en/latest/pages/installation.html

Use this command to install the package directly from the GitHub repository using pip.

```bash
pip install git+https://github.com/gabstopper/smc-python.git

```

--------------------------------

### Layer 3 Physical Interface Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/interfaces.html

Example configuration for a Layer 3 physical interface, including comment, interface ID, and network node details.

```python
interface = {
            'comment': u'Regular interface',
            'interface_id': u'67',
            'interfaces': [{'nodes': [{'address': u'5.5.5.2',
                                       'network_value': u'5.5.5.0/24',
                                       'nodeid': 1},

```

--------------------------------

### Creating Interfaces

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/collection.html

Provides examples for creating new interfaces, both through helper methods and manually.

```APIDOC
## Creating Interfaces

### Description
Create new interfaces using helper methods or by manually constructing interface objects.

### Example

Creating a layer 3 interface for a virtual engine using a helper method:
```python
engine.virtual_physical_interface.add_layer3_interface(
    interface_id=1,
    address='14.14.14.119',
    network_value='14.14.14.0/24',
    comment='my comment',
    zone_ref='myzone')
```

Manually creating a VirtualPhysicalInterface:
```python
payload = {'comment': 'comment on this interface',
            'interfaces': [{'nodes': [{'address': '13.13.13.13', 'network_value': '13.13.13.0/24'}]}]}

vinterface = VirtualPhysicalInterface(interface_id=1, **payload)
```
```

--------------------------------

### Run Task Immediately

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/scheduled_tasks.html

Execute a created task immediately by calling the `start` method on the task object.

```python
task = RefreshPolicyTask('mytask')
    task.start()
```

--------------------------------

### Create and Manage AS Path Access List

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/bgp_access_list.html

Demonstrates creating an AS Path Access List with initial entries, adding new entries, updating the list, removing entries, and iterating through the entries.

```python
aspath = ASPathAccessList.create(name='aspath', entries=[
    {'expression': '123-456', 'action': 'permit'},
    {'expression': '1234-567', 'action': 'deny'}])
aspath

```

```python
aspath.add_entry(expression='897', action='permit')
aspath.update()

```

```python
aspath.remove_entry(expression='123-456')
aspath.update()

```

```python
for entry in aspath:
  entry

```

--------------------------------

### Get Installed Policy Name

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engine.html

Returns the name of the policy currently installed on the engine. Returns None if no policy is installed.

```python
@property
def installed_policy(self):
    """
    Return the name of the policy installed on this engine. If
    no policy, None will be returned.
    
    :rtype: str or None
    """
    for node in self.nodes:
        return node.health.installed_policy
```

--------------------------------

### Bind license and initiate contact for nodes

Source: https://smc-python.readthedocs.io/en/latest/pages/engine.html

Perform node-specific setup operations including binding a license and initiating contact with the engine. This is typically done for each node within an engine.

```python
>>> for node in engine.nodes:
...   node.initial_contact(filename='/Users/davidlepage/engine.cfg')
...   node.bind_license()
```

--------------------------------

### Get start and end times as datetime objects

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/calendar.html

Properties to retrieve the start and end times from the TimeFormat instance as datetime objects. Returns 0 if the time is not specified.

```python
    @property
    def start_time(self):
        """
        Return the start time in datetime format. Will return
        0 if start time is not specified.
        
        :rtype: datetime
        """
        return datetime_from_ms(self.data.get('start_ms')) if \
            self.data.get('start_ms') != 0 else 0
    
    @property
    def end_time(self):
        """
        Return the end time in datetime format. Will return
        0 if end time is not specified.
        
        :rtype: datetime
        """
        return datetime_from_ms(self.data.get('end_ms')) if \
            self.data.get('start_ms') != 0 else 0
```

--------------------------------

### Set up a query with a time format

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/calendar.html

Demonstrates how to initialize a LogQuery and set a timezone and a time range for the last five minutes.

```python
query = LogQuery(fetch_size=50)
query.format.timezone('Europe/Helsinki')
query.time_range.last_five_minutes()
```

--------------------------------

### Get Element Categories

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/model.html

Retrieves a list of categories assigned to this element. Example usage shows fetching categories for a Host element.

```python
    @property
    def categories(self):
        """
        Search categories assigned to this element
        ::

            >>> from smc.elements.network import Host
            >>> Host('kali').categories
            [Category(name=foo), Category(name=foocategory)]

        :rtype: list(Category)
        """
        return [Element.from_meta(**tag)
                for tag in self.make_request(
                    resource='search_category_tags_from_element')]
```

--------------------------------

### Create External Gateway and VPN Site

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/vpn/elements.html

Demonstrates the step-by-step creation of a network element, an external gateway, an external endpoint, and a VPN site.

```python
Network.create(name='mynetwork', ipv4_network='172.18.1.0/24')
gw = ExternalGateway.create(name='mygw')
gw.external_endpoint.create(name='myendpoint', address='10.10.10.10')
gw.vpn_site.create(name='mysite', site_element=[Network('mynetwork')])
```

--------------------------------

### Retrieve elements by entry point

Source: https://smc-python.readthedocs.io/en/latest/pages/collections.html

Use `entry_point()` with a specific element type string to retrieve all elements of that type. For example, to get all VPNs, use 'vpn'.

```python
>>> list(Search.objects.entry_point('vpn'))
[PolicyVPN(name=Amazon AWS), PolicyVPN(name=sg_vm_vpn), PolicyVPN(name=TRITON AP-WEB Cloud VPN)]
```

--------------------------------

### Example Service Definitions

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Illustrates how to define services for firewall rules, accepting various formats including service objects, element hrefs, or a combination of both.

```python
services=[TCPService('myservice'),
          'http://1.1.1.1/8082/elements/tcp_service/mytcpservice',
          'http://1.1.1.1/8082/elements/udp_server/myudpservice'], etc
```

--------------------------------

### Internal Gateway Configuration Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engine.html

Demonstrates viewing and updating internal gateway settings for VPN clients, including firewall, antivirus, and VPN client mode.

```python
engine = Engine('dingo')
>>> vpn = engine.vpn
>>> vpn.name
            u'dingo Primary'
            >>> vpn.vpn_client.firewall
            False
            >>> vpn.vpn_client.antivirus
            False
            >>> vpn.vpn_client.vpn_client_mode
            u'ipsec'
        
        Enable client AV and windows FW::
        
            engine.vpn.vpn_client.update(
                firewall=True, antivirus=True)
```

--------------------------------

### SubElementCollection Usage Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/collection.html

Illustrates the usage of SubElementCollection for fetching and filtering engine upgrade information from a System object. It shows how to get elements by index, by name containment, and retrieve all matching elements.

```python
from smc.administration.system import System
system = System()
upgrades = system.engine_upgrade()
upgrades
list(upgrades)
upgrades.get(5)
upgrades.get_contains('6.2')
upgrades.get_all_contains('6.2')
```

--------------------------------

### Configure Log Options for a Rule

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule_elements.html

Example of how to obtain a rule reference and configure logging options for it. This includes setting accounting information, log level, and application/user logging.

```python
policy = FirewallPolicy('smcpython')
for rule in policy.fw_ipv4_access_rules.all():
    if rule.name == 'foo':
        rule.options.log_accounting_info_mode = True
        rule.options.log_level = 'stored'
        rule.options.application_logging = 'enforced'
        rule.options.user_logging = 'enforced'
        rule.save()
```

--------------------------------

### Installed Policy

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engine.html

Returns the name of the policy currently installed on the engine. Returns None if no policy is installed.

```APIDOC
## Installed Policy

### Description
Return the name of the policy installed on this engine. If no policy, None will be returned.

### Property
`installed_policy`

### Returns
- `str` or `None`: The name of the installed policy or None.
```

--------------------------------

### Get current time in milliseconds

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/calendar.html

A lambda function to get the current time in milliseconds since the epoch.

```python
current_millis = lambda: int(round(time.time() * 1000))
```

--------------------------------

### Create Master Engine and Add Interfaces

Source: https://smc-python.readthedocs.io/en/latest/pages/engine.html

Creates a Master Engine for managing virtual engines. This example initializes a master engine with specific management details and DNS servers, then adds physical interfaces for virtual engine allocation.

```python
>>> from smc.core.engines import MasterEngine
>>> engine = MasterEngine.create(name='api-master',
...                              mgmt_ip='1.1.1.1',
...                              mgmt_network='1.1.1.0/24',
...                              master_type='firewall',
...                              domain_server_address=['8.8.4.4', '7.7.7.7'])
>>> print(engine)
>>> MasterEngine(name=api-master)
>>> engine.physical_interface.add(1)    # add intefaces
>>> engine.physical_interface.add(2)
>>> for intf in engine.interface.all():
...   print(intf)
... 
PhysicalInterface(name=Interface 1)
PhysicalInterface(name=Interface 0)
PhysicalInterface(name=Interface 2)
```

--------------------------------

### Create Firewall Engine with Additional Interfaces

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engines.html

This example demonstrates creating a firewall engine with additional interfaces beyond the primary management interface. It shows how to define multiple interfaces, including CVI+NDI and NDI-only configurations, with specific node and network settings for each.

```python
Engine.create(name='fw2', cluster_virtual='10.0.0.1', network_value='10.0.0.0/24', macaddress='02:02:02:02:02:02', interface_id='eth0', nodes=[{'address':'10.0.0.2', 'network_value':'10.0.0.0/24', 'nodeid':1}], interfaces=[{'interface_id': 1, 'macaddress': '02:02:02:02:02:03', 'interfaces': [{'cluster_virtual': '2.2.2.1', 'network_value': '2.2.2.0/24', 'nodes':[{'address': '2.2.2.2', 'network_value': '2.2.2.0/24', 'nodeid': 1}, {'address': '2.2.2.3', 'network_value': '2.2.2.0/24', 'nodeid': 2}]}]}, {'interface_id': 2, 'interfaces': [{'nodes':[{'address': '3.3.3.2', 'network_value': '3.3.3.0/24', 'nodeid': 1}, {'address': '3.3.3.3', 'network_value': '3.3.3.0/24', 'nodeid': 2}]}]}])
```

--------------------------------

### Create IPList with Initial Content

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/elements/network.html

Create an IPList and populate it with initial IP addresses or networks. The 'iplist' parameter takes a list of strings.

```python
IPList.create(name='mylist', iplist=['1.1.1.1','1.1.1.2', '1.2.3.4'])

```

--------------------------------

### Example of NOT filter usage to ignore traffic

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/filters.html

A NOT filter can suppress auditing for specific criteria. This example shows how to ignore DNS traffic.

```python
query = LogQuery(fetch_size=50)
query.add_not_filter(
    [InFilter(FieldValue(LogField.SERVICE), [ServiceValue('UDP/53')])])
```

--------------------------------

### BlacklistQuery Initialization and Basic Usage

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/monitors/blacklist.html

Demonstrates how to initialize a BlacklistQuery for a specific target and set timezone preferences. It also shows how to fetch results in a default table format.

```APIDOC
## BlacklistQuery Initialization

### Description
Initializes a query to retrieve blacklist entries for a given target (engine or cluster) and optionally sets a timezone for timestamp resolution.

### Class
`BlacklistQuery`

### Parameters
- **target** (str) - Required - The name of the engine or cluster to query.
- **timezone** (str) - Optional - The timezone for resolving timestamps (e.g., 'US/Eastern', 'PST').

### Example
```python
from smc_monitoring.monitors.blacklist import BlacklistQuery

query = BlacklistQuery('sg_vm')
query.format.timezone('CST')

# Fetch results in default table format
for entry in query.fetch_batch():
    print(entry)
```
```

--------------------------------

### Get DNS Relay Settings

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engine.html

Enables, disables, or gets status for the DNS Relay Service. Requires a layer 3 engine and version >= v6.2.

```python
if 'dns_relay_interface' in self.data:
            return DNSRelay(self)
        raise UnsupportedEngineFeature(
            'DNS Relay requires a layer 3 engine and version >= v6.2.')
```

--------------------------------

### Download and Activate Update Package

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/updates.html

Shows how to retrieve update packages, find a specific dynamic update package by ID, download it, and then activate it. The `wait_for_finish=True` ensures the download completes before activation.

```python
system = System()
packages = system.update_package()
dynup = packages.get_contains('1007')

poller = dynup.download(wait_for_finish=True)
while not poller.done():
    print(poller.result(3))
print("Finished download: %s" % poller.result())
package.activate()
```

--------------------------------

### Login and Logout with Session

Source: https://smc-python.readthedocs.io/en/latest/pages/session.html

Basic example of logging in to establish a session and logging out when finished. Ensure to call logout() to remove the active session.

```python
from smc import session

session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx')
....do stuff....
session.logout()
```

--------------------------------

### Example of OR filter usage

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/filters.html

Use an OR filter to match records if any of the combined filters are true. This example fetches records matching a specific IP or service.

```python
query = LogQuery(fetch_size=50)
query.add_or_filter([
    InFilter(FieldValue(LogField.SRC), [IPValue('192.168.4.84')]),
    InFilter(FieldValue(LogField.SERVICE), [ServiceValue('TCP/80')])])
```

--------------------------------

### Get Management Server Reference

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/elements/servers.html

Retrieve the first Management Server element from the collection. This is the standard way to get a reference to the management server for configuration tasks.

```python
>>> ManagementServer.objects.first()
ManagementServer(name=Management Server)
```

--------------------------------

### Create RouteMap and Rule with Match Conditions

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/route_map.html

Demonstrates creating a RouteMap and adding a rule with match conditions specified as keyword arguments. Ensure necessary classes are imported.

```python
from smc.routing.route_map import RouteMap
from smc.routing.access_list import IPAccessList
from smc.routing.bgp import ExternalBGPPeer

rm = RouteMap.create(name='myroutemap')
rm
rm.route_map_rules.create(name='rule1', action='permit',
        next_hop=IPAccessList('myacl'), peer_address=ExternalBGPPeer('bgppeer'),
        metric=20)
...
```

--------------------------------

### Start Task Polling Loop

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/tasks.html

The internal method to start the polling loop for a task. It updates task status, decrements remaining tries, and handles exceptions.

```python
def _start(self):
        while not self.finished():
            try:
                time.sleep(self._timeout)
                self._task = self._task.update_status()
                self._max_tries -= 1
            except Exception as e:
                self._exception = e
                break

        self._done.set()
        for call in self.callbacks:
            call(self.task)
```

--------------------------------

### Create a Firewall Rule with Logging

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Demonstrates creating a firewall rule with specific logging options. The rule is configured to 'continue' processing and logs accounting information with a 'stored' level. Requires importing FirewallPolicy, LogOptions, and other necessary elements.

```python
from smc.policy.layer3 import FirewallPolicy
from smc.policy.rule_elements import LogOptions
from smc.policy.rule_elements import Action
from smc.elements.other import Alias

options = LogOptions()
options.log_accounting_info_mode=True
options.log_level='stored'

policy = FirewallPolicy('AWS_Default')
policy.fw_ipv4_access_rules.create(name='mylogrule',services='any',sources='any',destinations='any',actions='continue',log_options=options)
```

--------------------------------

### Example of Defined filter to check for field presence

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/filters.html

Use a Defined filter to match records only if a specified field has a value. This example shows how to find records with a defined Action.

```python
query = LogQuery(fetch_size=50)
query.add_defined_filter(FieldValue(LogField.ACTION))
```

--------------------------------

### ClusterPhysicalInterface Example with VLAN, CVI, and NDI

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/interfaces.html

Defines a ClusterPhysicalInterface with VLAN, CVI, and NDI configurations. This example shows how to specify VLAN ID, zone reference, and comments for nested interfaces.

```python
interface = {
    'interface_id': '24',
    'cvi_mode': 'packetdispatch',
    'macaddress': '02:02:08:08:08:06',
    'interfaces': [{'cluster_virtual': '242.242.242.250',
                    'network_value': '242.242.242.0/24',
                    'nodes': [{'address': '242.242.242.2', 'network_value': '242.242.242.0/24', 'nodeid': 1},
                              {'address': '242.242.242.3', 'network_value': '242.242.242.0/24', 'nodeid': 2}],
                    'vlan_id': 24,
                    'zone_ref': 'vlanzone',
                    'comment': 'comment on vlan'}],
    'zone_ref': zone_helper('myzone'),
    'comment': 'top level interface'}
    
```

--------------------------------

### Check Engine Upgrades and Download

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/administration/updates.html

Demonstrates how to check for engine upgrades, find a specific upgrade by version, download it, and then activate it. The `wait_for_finish=True` ensures the download completes before proceeding.

```python
system = System()
upgrades = system.engine_upgrade()
package = upgrades.get_contains('6.2')

poller = package.download(wait_for_finish=True)
while not poller.done():
    print(poller.result(3))
print("Finished download: %s" % poller.result())
package.activate()
```

--------------------------------

### List Interface Template Policies

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/interface.html

Demonstrates how to list all available Interface Template Policies. This is useful for understanding existing configurations or selecting a template for a new policy.

```python
print(list(InterfaceTemplatePolicy.objects.all()))

```

--------------------------------

### Get or Create Element

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/model.html

A convenience method to retrieve an Element or create it if it does not exist. If the element class does not have a `create` method, it defaults to using `get`. Keyword arguments are used for creation if the element is not found.

```python
@classmethod
    def get_or_create(cls, filter_key=None, with_status=False, **kwargs):
        """
        Convenience method to retrieve an Element or create if it does not
        exist. If an element does not have a `create` classmethod, then it
        is considered read-only and the request will be redirected to :meth:`~get`.
        Any keyword arguments passed except the optional filter_key
        will be used in a create() call. If filter_key is provided, this
        should define an attribute and value to use for an exact match on
        the element. Valid attributes are ones required on the elements
        ``create`` method or can be viewed by the elements class docs.
        If no filter_key is provided, the name field will be used to
        find the element.
        ::

            >>> Network.get_or_create(
                    filter_key={'ipv4_network': '123.123.123.0/24'},
                    name='mynetwork',
                    ipv4_network='123.123.123.0/24')
            Network(name=mynetwork)

        The kwargs should be used to satisfy the elements ``create``
        classmethod parameters to create in the event it cannot be found.

        :param dict filter_key: filter key represents the data attribute and
            value to use to find the element. If none is provided, the name

```

--------------------------------

### Tunnel Interface Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/interfaces.html

Defines a tunnel interface, typically used for route-based VPN traffic. This example shows the structure for a tunnel interface on a cluster firewall, including nested interface details.

```python
cluster_tunnel_interface = {
            'comment': u'My Tunnel on cluster',
            'interface_id': u'1000',
            'interfaces': [{'cluster_virtual': u'77.77.77.70',
                            'network_value': u'77.77.77.0/24',
                            'nodes': [{'address': u'5.5.5.2',
                                       'network_value': u'5.5.5.0/24',
                                        'nodeid': 1},

```

--------------------------------

### Login and Logout Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/api/session.html

Demonstrates a typical workflow of logging into the SMC API and then logging out. Ensure logout is called to release session resources on the SMC server.

```python
from smc import session
session.login(url='http://1.1.1.1:8082', api_key='SomeSMCG3ener@t3dPwd')
.....do stuff.....
session.logout()
```

--------------------------------

### Layer 2 Firewall Interface Configuration Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/interfaces.html

Example configuration for a Layer 2 Firewall interface, specifying inline IPS settings. This includes interface IDs, failure mode, and VLAN inspection settings.

```python
inline_ips = {
    'interface_id': '10',
    'second_interface_id': '11',
    'interface': 'inline_ips_interface',
    'logical_interface_ref': 'interfaceref',
    'inspect_unspecified_vlans': True,
    'failure_mode': 'bypass',
    'interfaces': [{'logical_interface_ref': 'logical',
                    'vlan_id': 15,
                    'zone_ref': 'vlan15 side a',
```

--------------------------------

### ConnectionQuery Initialization and Basic Usage

Source: https://smc-python.readthedocs.io/en/latest/pages/extensions.html

Demonstrates how to initialize a ConnectionQuery for a specific engine and set a timezone.

```APIDOC
## ConnectionQuery Initialization and Basic Usage

### Description
Initialize a query to obtain all connections for a given engine and optionally set a timezone for timestamp formatting.

### Method
```python
query = ConnectionQuery('sg_vm')
query.format.timezone('CST')
```

### Parameters
- `target` (str): The name of the target engine or cluster.
- `timezone` (str, optional): The timezone to use for formatting timestamps. Example: 'CST'.
```

--------------------------------

### Example of Defined filter within an AND filter

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc_monitoring/models/filters.html

Shows how to combine a Defined filter with other filters, like an InFilter, to create more specific queries. This example fetches records for a specific source IP that also have an application defined.

```python
query = LogQuery(fetch_size=50)
query.add_and_filter([
    DefinedFilter(FieldValue(LogField.IPSAPPID)),
    InFilter(FieldValue(LogField.SRC), [IPValue('192.168.4.84')])])
```

--------------------------------

### Get Categories

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/model.html

Retrieves the categories assigned to this element.

```APIDOC
## categories

### Description
Search categories assigned to this element

### Method
property

### Parameters
None

### Request Example
```python
from smc.elements.network import Host
Host('kali').categories
```

### Response
#### Success Response (200)
- **categories** (list(Category)) - A list of Category objects assigned to the element.

#### Response Example
```python
[Category(name=foo), Category(name=foocategory)]
```
```

--------------------------------

### Create and Use MatchExpression in Firewall Policy

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule_elements.html

Demonstrates creating a MatchExpression with a host and zone, then using it as a source in a new firewall rule. Shows how to retrieve and inspect the rule's sources.

```python
from smc.elements.network import Host, Zone
from smc.policy.rule_elements import MatchExpression
from smc.policy.layer3 import FirewallPolicy

match = MatchExpression.create(name='mymatch', network_element=Host('kali'), zone=Zone('Mail'))
policy = FirewallPolicy('smcpython')
policy.fw_ipv4_access_rules.create(name='myrule', sources=[match], destinations='any', services='any')
'http://172.18.1.150:8082/6.2/elements/fw_policy/261/fw_ipv4_access_rule/2099740'
rule = policy.search_rule('myrule')

for source in rule[0].sources.all():
  print(source, source.values())

```

--------------------------------

### initial_contact

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/node.html

Allows saving the initial contact configuration for a specified node. This method can enable SSH, set time zone and keyboard layout, and optionally install the configuration on the SMC Install server. It can also return the configuration as a base64 encoded string.

```APIDOC
## initial_contact

### Description
Allows to save the initial contact for for the specified node.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
POST (implied by make_request with method='create')

### Endpoint
/initial_contact

### Parameters
- **enable_ssh** (bool) - Optional - flag to know if we allow the ssh daemon on the specified node
- **time_zone** (str) - Optional - optional time zone to set on the specified node
- **keyboard** (str) - Optional - optional keyboard to set on the specified node
- **install_on_server** (bool) - Optional - optional flag to know if the generated configuration needs to be installed on SMC Install server (POS is needed)
- **filename** (str) - Optional - filename to save initial_contact to
- **as_base64** (bool) - Optional - return the initial config in base 64 format. Useful for cloud based engine deployments as userdata

### Request Example
```python
node.initial_contact(enable_ssh=True, time_zone='UTC', filename='initial_config.txt', as_base64=False)
```

### Response
#### Success Response (200)
- **content** (str) - initial contact text information

#### Response Example
```json
{
  "content": "initial_contact_data"
}
```

### Error Handling
- **NodeCommandFailed**: IOError handling initial configuration data
```

--------------------------------

### Configure Connection Tracking Options

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule_elements.html

Configure connection tracking settings on a per-rule basis, including MSS enforcement and state tracking. This example enables MSS enforcement and sets the state to 'normal'.

```python
for rule in policy.fw_ipv4_access_rules.all():
    rule.action.connection_tracking_options.mss_enforced = True
    rule.action.connection_tracking_options.state = 'normal'
    rule.action.connection_tracking_options.mss_enforced_min_max = (1400, 1450)
    rule.action.connection_tracking_options.sync_connections = True
    rule.save()
```

--------------------------------

### Create OSPF Area with Virtual Link Endpoints

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/ospf.html

This example demonstrates creating an OSPF Area and configuring virtual link endpoints. It shows how to specify router IDs for endpoints A and B.

```python
OSPFArea.create(
            name='ospf', 
            interface_settings_ref=intf, 
            area_id=3,
            ospfv2_virtual_links_endpoints_container=[
                {'interface_settings_ref': 
                    'http://172.18.1.150:8082/6.1/elements/ospfv2_interface_settings/8',
                  'router_id_endpoint_A': '192.168.1.1',
                  'router_id_endpoint_B': '192.168.1.254'},
                 {'router_id_endpoint_A': '172.18.1.254',
                  'router_id_endpoint_B': '172.18.1.200'}])
```

--------------------------------

### Get Parent Policy

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the parent policy of this rule.

```APIDOC
## parent_policy

### Description
Read-only name of the parent policy

### Method Signature
`parent_policy(self) -> Element`

### Returns
* `:class:`smc.base.model.Element` of type policy` - The parent policy element.
```

--------------------------------

### Create IPAccessList

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/access_list.html

Demonstrates creating an IPAccessList with initial entries and subsequently adding and removing entries. Use this to define IP-based route filtering rules.

```python
ip = IPAccessList.create(name='mylist', entries=[
    {'subnet': '1.1.1.0/24', 'action': 'permit'}, {'subnet': '2.2.2.0/24', 'action': 'deny'}]
)
>>> ip.add_entry(subnet='3.3.3.0/24', action='permit')
>>> ip.remove_entry(subnet='1.1.1.0/24')
>>> ip.update()
'https://172.18.1.151:8082/6.4/elements/ip_access_list/13'
>>> for entry in ip:
...   entry
... 
AccessListEntry(subnet=u'2.2.2.0/24', action=u'deny', comment=None)
AccessListEntry(subnet=u'3.3.3.0/24', action=u'permit', comment=None)
...
>>> ip.delete()
```

--------------------------------

### Get Services

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the service elements assigned to this rule.

```APIDOC
## services

### Description
Services assigned to this rule

### Method Signature
`services(self) -> Service`

### Returns
* `Service` - The service object for the rule.
```

--------------------------------

### Get Destinations

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the destination elements assigned to this rule.

```APIDOC
## destinations

### Description
Destinations for this rule

### Method Signature
`destinations(self) -> Destination`

### Returns
* `Destination` - The destination object for the rule.
```

--------------------------------

### ElementCollection Initialization and Filtering

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/collection.html

Demonstrates how to initialize an ElementCollection with parameters and how filters are chained, returning new query objects without affecting the original. Shows the internal state of parameters and exact match settings after filtering.

```python
class ElementCollection(object):
    """
    ElementCollection is generated dynamically from the CollectionManager
    and provides methods to obtain data from the SMC. Filters can be chained
    together to generate more complex queries. Each time a filter is added,
    a clone is returned to preserve the parent query parameters.
    
    Chaining filters do not affect the parent iterator::
    
        >>> iterator = Host.objects.iterator()    <-- Obtain iterator from CollectionManager
        >>> query1 = iterator.filter('10.10.10.1')
        >>> query1._params, query1._iexact
        ({'filter': '10.10.10.1', 'exact_match': False, 'filter_context': 'router'}, None)
        >>> query2 = query1.limit(2)
        >>> query2._params, query2._iexact
        ({'filter': '10.10.10.1', 'exact_match': False, 'filter_context': 'router', 'limit': 2}, None)
        >>> query3 = query2.filter(address='10.10.10.1')
        >>> query3._params, query3._iexact
        ({'filter': '10.10.10.1', 'exact_match': False, 'filter_context': 'router', 'limit': 2}, {'address': '10.10.10.1'})
        
    
    Searcb operations can access a collection directly through chained syntax::
    
        >>> for router in Router.objects.filter('192.168'):
        ...   print(router)
        ... 
        Router(name=router-192.168.19.241)
        Router(name=router-192.168.21.241)
        Router(name=router-192.168.5.241)
        Router(name=router-192.168.15.241)
        
    Adding additional filtering via kwargs::
    
        >>> print(list(Router.objects.filter(address='10.10.10.1')))
        [Router(name=Router-10.10.10.1)]

    Checking if items from the query exist before accessing::
    
        >>> query1 = iterator.filter('10.10.10.1')
        >>> if query1.exists():
        ...   list(query1.all())
        ... 
        [Router(name=Router-110.10.10.10), Router(name=Router-10.10.10.10), Router(name=Router-10.10.10.1)]
    
    Helper methods ``first``, ``last`` and ``exists`` are provided to simplify retrieving a
    result from the collection::
    
        >>> query1 = iterator.filter('10.10.10.1')
        >>> list(query1)
        [Router(name=Router-110.10.10.10), Router(name=Router-10.10.10.10), Router(name=Router-10.10.10.1)]
        >>> query1.first()
        Router(name=Router-110.10.10.10)
        >>> query1.last()
        Router(name=Router-10.10.10.1)
        >>> query1.count()
        3
        >>> query2 = query1.filter(address='10.10.10.1')  # change filter to kwarg
        >>> list(query2)
        [Router(name=Router-10.10.10.1)]

    .. note:: ``exists`` does not perform filtering when using ``filter_key``.
        Results on filter(kwargs) are only done by retrieving the list of
        results or iterating.
    """
    def __init__(self, **params):
        self._params = params
        self._iexact = params.pop('iexact', None)

    def __iter__(self):

```

--------------------------------

### Get Sources

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the source elements assigned to this rule.

```APIDOC
## sources

### Description
Sources assigned to this rule

### Method Signature
`sources(self) -> Source`

### Returns
* `Source` - The source object for the rule.
```

--------------------------------

### Instantiate and Access Engine

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engine.html

Demonstrates how to instantiate an Engine object by its name and access its href. This is useful for directly referencing an existing engine.

```python
>>> from smc.core.engine import Engine
>>> engine = Engine('testfw')
>>> print(engine.href)
http://1.1.1.1:8082/6.1/elements/single_fw/39550
```

--------------------------------

### Get Rule Action

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the action associated with this rule.

```APIDOC
## action

### Description
Action for this rule.

### Method Signature
`action(self) -> Action`

### Returns
* `Action` - The action object for the rule.
```

--------------------------------

### Iterate and Control Engine Nodes

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/node.html

Example of loading an engine and performing node-level actions. Ensure the Engine is loaded before accessing its nodes.

```python
engine = Engine('myfw')
for node in engine.nodes:
    node.reboot()
    node.bind_license()
    node.go_online()
    node.go_offline()
```

--------------------------------

### Get Rule Services

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the services assigned to this rule.

```python
return Service(self)
```

--------------------------------

### Configuration File Login (Script)

Source: https://smc-python.readthedocs.io/en/latest/pages/session.html

Example of calling session.login() after configuring connection details in a file like ~/.smcrc. The session is then managed with session.logout().

```python
session.login()
session.logout()
```

--------------------------------

### Get Rule Destinations

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the destinations assigned to this rule.

```python
return Destination(self)
```

--------------------------------

### Get Rule Sources

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the sources assigned to this rule.

```python
return Source(self)
```

--------------------------------

### Engine Context Blacklist Example

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/elements/other.html

Demonstrates how to create an engine context blacklist with extended parameters for source and destination ports, and protocols.

```APIDOC
## Engine Context Blacklist

### Description
Allows blacklisting of network traffic based on IP addresses, ports, protocols, and duration. This function is used to define specific network conditions for blacklisting.

### Method
`engine.blacklist(ip_address1, ip_address2, **kw)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **ip_address1** (str) - The first IP address or network to blacklist.
- **ip_address2** (str) - The second IP address or network to blacklist.
- **duration** (int) - Optional. Length of time to apply the blacklist in seconds.
- **src_port1** (int) - Optional. Start source port to limit the blacklist.
- **src_port2** (int) - Optional. End source port to limit the blacklist. If not provided, defaults to `src_port1`.
- **src_proto** (str) - Optional. Source protocol. Either 'predefined_tcp' or 'predefined_udp'. Defaults to 'predefined_tcp'.
- **dst_port1** (int) - Optional. Start destination port to limit the blacklist.
- **dst_port2** (int) - Optional. End destination port to limit the blacklist. If not provided, defaults to `dst_port1`.
- **dst_proto** (str) - Optional. Destination protocol. Either 'predefined_tcp' or 'predefined_udp'. Defaults to 'predefined_tcp'.

### Request Example
```python
engine.blacklist('1.1.1.1/32', '2.2.2.2/32', duration=3600,
    src_port1=1000, src_port2=1500, src_proto='predefined_udp',
    dst_port1=3, dst_port2=3000, dst_proto='predefined_udp')
```

### Response
#### Success Response (200)
Returns a JSON object representing the blacklist configuration.
- **end_point1** (dict) - Configuration for the first endpoint (source).
  - **address_mode** (str) - Mode of address (e.g., 'any', 'address').
  - **ip_network** (str) - IP network address if `address_mode` is 'address'.
  - **port1** (int) - Start port.
  - **port2** (int) - End port.
  - **port_mode** (str) - Port mode (protocol).
- **end_point2** (dict) - Configuration for the second endpoint (destination).
  - **address_mode** (str) - Mode of address (e.g., 'any', 'address').
  - **ip_network** (str) - IP network address if `address_mode` is 'address'.
  - **port1** (int) - Start port.
  - **port2** (int) - End port.
  - **port_mode** (str) - Port mode (protocol).
- **duration** (int) - Duration of the blacklist in seconds.

#### Response Example
```json
{
  "end_point1": {
    "address_mode": "address",
    "ip_network": "1.1.1.1/32",
    "port1": 1000,
    "port2": 1500,
    "port_mode": "predefined_udp"
  },
  "end_point2": {
    "address_mode": "address",
    "ip_network": "2.2.2.2/32",
    "port1": 3,
    "port2": 3000,
    "port_mode": "predefined_udp"
  },
  "duration": 3600
}
```
```

--------------------------------

### Get Rule Action

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the action associated with this rule.

```python
return Action(self)
```

--------------------------------

### Create Layer3 Interface on Virtual Engine

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/collection.html

Example of creating a Layer3 interface on a virtual engine using a helper method.

```python
engine.virtual_physical_interface.add_layer3_interface(
    interface_id=1,
    address='14.14.14.119',
    network_value='14.14.14.0/24',
    comment='my comment',
    zone_ref='myzone')
```

--------------------------------

### comment

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/route_map.html

Get and set the comment for a route map rule.

```APIDOC
## comment

### Description
Allows retrieval and modification of the comment associated with a route map rule.

### Method
- GET: Retrieves the current comment string.
- SET: Sets a new comment string for the rule.

### Parameters
- **value** (str) - Required (for setter) - The string comment to set for the rule.

### Return Value
- **str**: The current comment string of the rule (for GET).

### Example
```python
# Get comment
current_comment = rule.comment

# Set comment
rule.comment = "This rule permits traffic from internal network."
rule.update() # Assuming an update method exists to save changes
```
```

--------------------------------

### Layer3VirtualEngine Create Method

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/engines.html

Creates a Layer3Virtual engine, mapping it to a master engine. Configuration includes interface details, NAT settings, and OSPF options.

```python
engine = Layer3VirtualEngine.create(
                                name='myips',
                                master_engine='mymaster_engine',
                                virtual_engine='ve-3',
                                interfaces=[{'interface_id': 0,
                                             'address': '5.5.5.5',
                                             'network_value': '5.5.5.5/30',
                                             'zone_ref': ''}]
```

--------------------------------

### Get Element Comment

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/model.html

Retrieves the comment associated with the element.

```python
@property
    def comment(self):
        """
        Comment for element
        """
        return self.data.get('comment', None)
```

--------------------------------

### Create and Manage Community Access List (Standard)

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/bgp_access_list.html

Shows how to create a standard Community Access List with initial entries, add more entries, and iterate through the list. The 'type' parameter is set to 'standard'.

```python
from smc.routing.community_list import CommunityAccessList
comm = CommunityAccessList.create(name='commacl',
        entries=[{'community': 123, 'action': 'permit'},{'community': 456, 'action': 'deny'}],
        type='standard')
comm

```

```python
comm.add_entry(community=789, action='permit')
comm.update()

```

```python
for entries in comm:
  entries

```

--------------------------------

### Get All Elements

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/base/collection.html

Returns an iterator for all elements managed by this collection.

```python
def all(self):
        return self.iterator()

    all.__doc__ = ElementCollection.all.__doc__
```

--------------------------------

### Create and Configure VPN Policy

Source: https://smc-python.readthedocs.io/en/latest/pages/vpn.html

Creates a VPN policy, applying internal and external gateways, and then opens, modifies, saves, and closes the policy.

```APIDOC
## Create and Configure VPN Policy

### Description
Creates a `PolicyVPN` object, sets its name and NAT status, opens it for modification, adds central and satellite gateways, saves the changes, and then closes the policy.

### Method
`PolicyVPN.create(name: str, nat: bool)`
`vpn.open()`
`vpn.add_central_gateway(gateway_href: str)`
`vpn.add_satellite_gateway(gateway_href: str)`
`vpn.save()`
`vpn.close()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
>>> vpn = PolicyVPN.create(name='myVPN', nat=True)
>>> print(vpn.name, vpn.vpn_profile)
(u'myVPN', u'http://172.18.1.150:8082/6.1/elements/vpn_profile/2')
...
>>> vpn.open()
>>> vpn.add_central_gateway(engine.internal_gateway.href)
>>> vpn.add_satellite_gateway(external_gateway.href)
>>> vpn.save()
>>> vpn.close()
```

### Response
This operation modifies the VPN policy in place. Success is indicated by the absence of errors during execution. The `save()` and `close()` methods finalize the changes.
```

--------------------------------

### Get Rule Tag

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the read-only tag associated with this rule.

```APIDOC
## tag

### Description
Value of rule tag. Read only.

### Method Signature
`tag(self) -> str`

### Returns
* `str` - The rule tag.
```

--------------------------------

### Add Cluster Virtual Interface (CVI) and Node Dependent Interfaces (NDI)

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/core/collection.html

This example demonstrates adding both a Cluster Virtual Interface (CVI) and Node Dependent Interfaces (NDI) for a clustered engine. It includes configuration for the CVI and details for each node's interface.

```python
engine.physical_interface.add_cluster_virtual_interface(
    cluster_virtual='5.5.5.1',
    network_value='5.5.5.0/24',
    macaddress='02:03:03:03:03:03',
    nodes=[{'address':'5.5.5.2', 'network_value':'5.5.5.0/24', 'nodeid':1},

```

--------------------------------

### Create a new VPN Policy

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/vpn/policy.html

Instantiates a new VPN Policy. VPN Profile is required and defaults to 'VPN-A Suite' if not specified.

```python
PolicyVPN.create(name='myvpn')
PolicyVPN('myvpn')
```

--------------------------------

### Get Log Options

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the logging options configured for this rule.

```APIDOC
## options

### Description
Rule based options for logging. Enabling and disabled specific log settings.

### Method Signature
`options(self) -> LogOptions`

### Returns
* `LogOptions` - The log options object for the rule.
```

--------------------------------

### Get Authentication Options

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/policy/rule.html

Retrieves the read-only authentication options for this rule.

```python
return AuthenticationOptions(self)
```

--------------------------------

### LogicalInterface.create

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/elements/other.html

Create the logical interface.

```APIDOC
## LogicalInterface.create

### Description
Create the logical interface

### Parameters
#### Path Parameters
- **name** (str) - Required - name of logical interface
- **comment** (str) - Optional - optional comment

### Raises
- CreateElementFailed: failed creating element with reason

### Returns
- instance with meta (LogicalInterface)
```

--------------------------------

### Get BGP status

Source: https://smc-python.readthedocs.io/en/latest/_modules/smc/routing/bgp.html

Retrieves the BGP status (enabled/disabled) for an engine.

```APIDOC
## Get BGP status

### Description
Checks if BGP is enabled on the engine.

### Method
engine.dynamic_routing.bgp.status

### Parameters
None

### Response
#### Success Response (200)
- **status** (bool) - True if BGP is enabled, False otherwise.
```
Tokens:
Raw