Custom Iptables Rules

This Public Stable API allows you to leverage preexisting iptables rules on Linux workloads and add them as rules to rulesets.

You can use the rules API to create custom iptables rules in situations where your Linux workloads have preexisting iptables rules configured that you would like to keep in addition to the rules you create using Illumio Core.

If you configured iptables on Linux workloads before using Illumio Core, when you pair a workload, the VEN assumes control of the iptables to enact policy and disables any pre-programmed iptables. To solve this, you can use the Rules API to leverage your own iptables rule configurations in a ruleset.

Custom Iptables Rules

These terms clarify the relationship between your iptables rules and Illumio Core rules:

iptables: Linux host configuration before the VEN is installed
Rules: Configurations in the PCE that define the allowed communication between two or more workloads or other entities (IP lists, labels representing multiple workloads, and label groups)
Custom iptables rules: PCE rules that leverage your iptables rule configurations that get programmed on your workloads by the VEN and managed by the PCE

How Custom iptables Rules Work

Custom iptables rules in the PCE consist of a list of predefined iptables statements and the entities that receive the rule definitions. Each rule can have a list of iptables configurations, which allows you to group a sequence of rules for a specific function. Custom iptables rules are programmed after the Illumio PCE generates the iptables rules and are provisioned.

Before custom iptables rules are sent to the VEN, they are checked for any unsupported tokens (such as names of firewall chains already in use by Illumio, matching against IP sets, and semicolons). The rule cannot be saved or provisioned if an unsupported token is included.

If the VEN fails to apply a custom iptables rule because of a missing package or an incorrectly formatted rule:

Error is reported to the PCE and is logged as two audit events:
“Firewall config failure” (fw_config_failure) and
“Failed to apply policy changes” (policy_deploy_failed).
The error is displayed in the VEN health status.
The new policy is not used, and the last known successful policy is used instead.

For policy distribution and enforcement, the VEN creates a custom chain that contains the rules for each table or chain in the iptables. Each custom chain is appended to the end of its corresponding chain in the correct table. When the VEN requests the policy, the iptables command is sent, including where the chain should be placed.

For security reasons, custom iptables rules only support rules in the mangle, nat, and filter tables.

The following table describes the permitted actions for each iptables type:

Table Name	Chain Names	Custom Rules
`raw`	prerouting, output	No
`mangle`	prerouting, input, output, forward, postrouting	Yes
`nat`	prerouting, output, postrouting	Yes
`filter`	input, output, forward	Yes
`security`	input, output, forward	No

Create a Custom iptables Rule.

This method allows you to create a rule that can contain custom iptables.

Create a Custom iptables Rule.

POST [api_version/[rule_set_href]/sec_rules

Custom Iptables Rules Reference

This topic covers parameters, properties, and examples for iptable rules.

Query Parameters

Parameter	Description	Type	Required
`name`	Ruleset name (must be unique)	String	Yes
`scopes`	Scope for the ruleset, which consists of a list of labels, with each list having at least one application, environment, and/or location label	Array	Yes
`external_data_set`	External data set identifier.	String	No
`external_data_reference`	External data reference identifier	String	No
`enabled`	Whether the ruleset is enabled or not	Boolean	Yes
`rules`	Standard (non-iptables) rules	String	Yes
`iptables_rules`	Rules that use iptables (see the following table for properties)	String	Yes

Custom iptables_rules Properties

Property	Description	Type	Required
`enabled`	Whether the rule is currently enabled	Enum	Yes
`ip_version`	Whether IPv4 or IPv6 is used	String	Yes
`description`	Description of ruleset	String	No
`actors`	Entities that receive the ruleset.	String	Yes
`statements`	Rules for iptables (table, chain name, and parameters), which consist of the following elements: `table_name`: Name of iptables table, which is `nat`, `mangle`, or `filter` `chain_name`: Name of iptables chain, which is `prerouting`, `input`, `output`, `forward`, or `postrouting` `parameters`: Remaining iptables rules (excluding table name and chain name)	String	Yes

Examples

Request Body

In this example, a ruleset named test_ipt_rs contains two iptables rules.

Note

Each iptables rule can contain multiple statements.

{
    "name": "test_ipt_rs",
    "enabled": true,
      "scopes": [
    [
      { "label": { "href": "/orgs/1/labels/24" } },
      { "label": { "href": "/orgs/1/labels/27" } },
      { "label": { "href": "/orgs/1/labels/21" } }
    ],
  ],
    "ip_tables_rules": [
        {
            "enabled": true,
            "actors": [{"label": { "href": "/orgs/1/labels/11" }}],
            "statements": [
                {
                    "table_name": "mangle",
                    "chain_name": "PREROUTING",
                    "parameters": "-i eth0 -p tcp --dport 2222 -j MARK --set-mark 2222"
                },
                {
                    "table_name": "nat",
                    "chain_name": "PREROUTING",
                    "parameters": "-i eth0 -p tcp -m mark --mark 2222 -j REDIRECT --to-port 3333"
                },
                {
                    "table_name": "filter",
                    "chain_name": "INPUT",
                    "parameters": "-i eth0 -p tcp -m mark --mark 2222 -j ACCEPT"
                }
            ],
            "ip_version": "4"
        },
        {
            "enabled": true,
            "actors": [{ "actors": "ams" }],
            "statements": [
                {
                    "table_name": "nat",
                    "chain_name": "POSTROUTING",
                    "parameters": "-o eth1 -s 192.0.2.10! -d 198.51.100.0/24 -j MASQUERADE"
                }
            ],
            "ip_version": "4"
        }   
    ]
}

Create Custom iptables Rule.

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/rule_sets -H "Content-Type:application/json" -u $KEY:$TOKEN-d '{"name":"test_ipt_rs","enabled":true,"scopes":[{[],[]}],"ip_tables_rules":[{"enabled":true,"actors":[{"label":{"href":"/orgs/1/labels/11"}}],"statements": [{"table_name":"mangle","chain_name":"PREROUTING","parameters":"-i eth0 -p tcp --dport 2222 -j MARK --set-mark 2222"},{"table_name":"nat","chain_name":"PREROUTING","parameters":"-i eth0 -p tcp -m mark --mark 2222 -j REDIRECT --to-port 3333"},{"table_name":"filter","chain_name":"INPUT","parameters":"-i eth0 -p tcp -m mark --mark 2222 -j ACCEPT"}], "ip_version":"4"},{"enabled":true,"actors":[{"actors":"ams"}],"statements":[{"table_name":"nat", "chain_name":"POSTROUTING","parameters":"-o eth1 -s 10.0.0.2 ! -d 172.17.0.0/16 -j MASQUERADE"}], "ip_version":"4"}]}'

Response Body

Property	Description	Type
`href`	Identifier for the resource	String

Response

{
  "href": "/orgs/1/sec_policy/draft/rule_sets/17",
  "created_at": "2023-02-24T23:19:01.020Z",
  "updated_at": "2023-02-24T23:19:01.020Z",
  "deleted_at": null,
  "created_by": {
    "href": "/users/1"
  },
  "updated_by": {
    "href": "/users/1"
  },
  "deleted_by": null,
  "name": "test_ipt_rs",
  "description": null,
  "enabled": true,
  "scopes": [
    [
      { "label": { "href": "/orgs/1/labels/24" } },
      { "label": { "href": "/orgs/1/labels/27" } },
      { "label": { "href": "/orgs/1/labels/21" } }
    ],
    [ 
      { "label": { "href": "/orgs/1/labels/15" } },
      { "label": { "href": "/orgs/1/labels/16" } },
      { "label": { "href": "/orgs/1/labels/17" } }
    ]
   ],
  ],
  "rules": [],
  "ip_tables_rules": [
    {
      "href": "/orgs/1/sec_policy/draft/rule_sets/17/ip_tables_rules/20",
      "created_at": "2023-02-24T23:19:01.280Z",
      "updated_at": "2023-02-24T23:19:01.280Z",
      "deleted_at": null,
      "created_by": {
        "href": "/users/1"
      },
      "updated_by": {
        "href": "/users/1"
      },
      "deleted_by": null,
      "description": null,
      "enabled": true,
      "actors": [
        {
          "actors": "ams"
        }
      ],
      "ip_version": "4",
      "statements": [
        {
          "table_name": "nat",
          "chain_name": "POSTROUTING",
          "parameters": "-o eth1 -s 192.0.2.0 ! -d 198.51.100.0/24 -j MASQUERADE"
        }
      ]
    },
    {
      "href": "/orgs/1/sec_policy/draft/rule_sets/17/ip_tables_rules/18",
      "created_at": "2023-02-24T23:19:01.229Z",
      "updated_at": "2023-02-24T23:19:01.229Z",
      "deleted_at": null,
      "created_by": {
        "href": "/users/1"
      },
      "updated_by": {
        "href": "/users/1"
      },
      "deleted_by": null,
      "description": null,
      "enabled": true,
      "actors": [
        {
          "label": {
            "href": "/orgs/1/labels/11",
            "key": "loc",
            "value": "test"
          }
        }
      ],
      "ip_version": "4",
      "statements": [
        {
          "table_name": "filter",
          "chain_name": "INPUT",
          "parameters": "-i eth0 -p tcp -m mark --mark 2222 -j ACCEPT"
        },
        {
          "table_name": "nat",
          "chain_name": "PREROUTING",
          "parameters": "-i eth0 -p tcp -m mark --mark 2222 -j REDIRECT --to-port 3333"
        },
        {
          "table_name": "mangle",
          "chain_name": "PREROUTING",
          "parameters": "-i eth0 -p tcp --dport 2222 -j MARK --set-mark 2222"
        }
      ]
    }
  ]
}

REST APIs 25.2.10

Custom Iptables Rules

Custom Iptables Rules

How Custom iptables Rules Work

Create a Custom iptables Rule.

Custom Iptables Rules Reference

Query Parameters

Custom iptables_rules Properties

Examples

Note

Search results