Rules can allow communication between multiple applications or entities in different scopes or the same scope. To write a rule, you need to define three things: A service, a provider of the service, and a consumer of the service. You also need to select the type of rule: 

About Rules

Illumio supports the delegation of rule writing using role-based access control (RBAC). Application administrators can only edit rules where the scope of the ruleset matches the scopes where they have administrator privileges. They cannot create or manage rulesets if the scope includes “All.”

Rule types allow the application administrator to write rules that allow other applications to communicate with the applications that they manage without requiring global administrator privileges. This feature allows users to group rules required for inter-application and intra-application communication for a specific application into one ruleset.

You can combine multiple types of rules (intra-scope, extra-scope, and custom iptables) in a single ruleset. They can be used to either Create a Ruleset or Create a Ruleset with Multiple Scopes.

From 18.2.0 version on, you can use multiple services or ports and protocols in a rule. This approach helps reduce the number of rules in your PCEs, which helps improve the PCE performance.


You cannot provision drop actions from the PCE in a NAT table for custom IP tables. Doing so results in a firewall generation failure.

Intra-scope Rules

Intra-scope rules allow authorized users to write rules that allow communication between providers and consumers within a specific scope. This rule type is typically used to allow communication between workloads that belong to the same application. For intra-scope rules, the labels used in the scope must match the labels used for both the provider and the consumer. If you don't specify a Label, “All” is used by default.


In this example, all Database workloads with the labels HRM | US | Dev can accept MySQL connections from all Web workloads with the labels HRM | US | Dev.

Extra-scope Rules

Extra-scope rules allow authorized users to write rules that allow communication between applications. Specifically, you can write rules that allow providers within a scope to be accessed by consumers that can be in or outside the specified scope. For extra-scope rules, the labels used in the scope must match the labels used by the provider. If you don't specify a label, “All” is used by default.


In this example, all Database workloads with the labels HRM | US | Dev can accept connections on MySQL from all workloads with the label Web, irrespective of other labels.

The MySQL might not belong to the application HRM (for example, the consumers are “Global” and are not restricted by the labels in the scope).


If the RBAC user's scope coverage type is “Providers and Consumers,” the user cannot select an IP list as the consumer. To select an IP list as a consumer in a rule, the scope coverage type must be “Providers Only.” For more information, see IP Lists and Role-based Access Control in the PCE Administration Guide.

Custom iptables Rules

You might have configured iptables directly on your Linux workloads as needed for your application workloads as part of your host configuration. However, when you pair a workload and put a policy into the build, test, or enforced policy state, the VEN assumes control of the iptables to enact the policy and does not apply any pre-programmed iptables to the policy.

Custom iptables rules in Illumio Core provide the ability for you to program the custom iptables rules needed for your applications as part of the rules managed by the PCE. Custom iptables rules help preserve any configured iptables from native Linux host configurations by allowing you to include them with the rules for your policy.

To clarify: 

  • iptables refer to a Linux host configuration before the VEN is installed
  • Rules refer to statements written by the PCE to determine permitted traffic, typically by assuming control of iptables and programming the new rules
  • iptables rules refer to iptables that are inserted as rules onto the VENs and managed by the PCE

Custom iptables rules consist of a list of iptables statements and the entities that receive the rules. Each rule can consist of a list of iptables rules, which allows users to group a sequence of rules for a specific function. The custom iptables rules are programmed after the Illumio PCE generates the iptables rules, but prior to the last default rule.

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

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

  • The error is reported to the PCE and is logged in the organization events
  • The error is displayed in the VEN policy sync 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 the chain where it 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 Support
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

If the RBAC user's scope coverage type is “Providers and Consumers,” the user cannot manage custom iptables rules. To allow access to custom iptables rules, the scope coverage type must be “Providers Only.” For more information, see Role-based Access Control in the PCE Administration Guide

Permitted Rule Writing Combinations

The following table explains the valid rule combinations between providers and consumers.

If Provider is And Service is Consumer can be
Workload, All workloads, label, label group Any service Workload , IP list (including Any ( and ::/0), label, label group, user groups, All workloads
IP list Any service Workload, label, label group, user groups, All workloads

Uses virtual services

Not applicable (the service is derived from the virtual service) Workload, label, label group, IP lists, All workloads, uses virtual service, uses virtual services and workloads
Uses virtual services and workloads Any service

Workload, label, label group, IP lists, All workloads, uses virtual service, uses virtual services and workloads

Workload, All workloads, label, or label groups Any service

User groups and one or more of the following: workload, All workloads, label, label groups

Stateless Rules

By default, all rules you write in the PCE are stateful, which means that the host's firewall keeps track of a connection for the entire duration of the session.

For Linux workloads, you can specify stateless packet filtering for a rule (“stateless”: true). This means that the VEN instructs the host's firewall to not maintain persistent connections for all sessions. You can create this type of a stateless rule for datacenter core services, such as DNS and NTP.

If you add a stateless rule to a policy that has both Windows and Linux workloads in its scope, then that rule is configured as a stateful rule on the Windows workload.


In a stateless rule, you can add the following policy objects as consumers:

  • An individual workload
  • A label (one each of a specific type, up to four total)
  • Any IP list plus All workloads

If you attempt to add any other consumers, you receive an error.

The Illumio Core limits the number of stateless rules to 100, to ensure that both stateful and stateless rules coexist on the host in a way that optimizes system and network performance. If you need more than 100 stateless rules in your Illumio policy, contact your Illumio Professional Services Representative for more information.


Existing active connections on workloads allowed by a stateless rule (for example, an SSH session) are terminated when workloads receive new rules from the PCE. Those connections need to be reestablished by the clients. For this reason, Illumio recommends that you use stateless rules for services that use high-frequency short-lived connections, such as DNS and SNMP.

View and Download Computed Rules

You can download the computed rules, which are all the rules that apply to a workload, in JSON format. When your organization has less than 1000 rules, you can download them immediately by clicking Export.

When your organization has more than 1000 rules, the PCE does not display any rules and you have the option to generate the rules asynchronously on the PCE.

The amount of time required to generate the rules is proportional to the number of rules. When the rules have been generated on the PCE, you can download them or view them in the browser.


  • You cannot navigate away from the page while the computed rules are being generated. When you navigate away from the page before downloading the rules, you must re-generate the rules.
  • If the request takes longer than 30 minutes to complete due to the large number of computed rules, the request will time out and the rules will not be generated.
  • For large and complex organizations or rulesets, this feature might not be supported.

Rule Search

If you had a large number of rules organized in rulesets, you can't easily search for rules across rulesets. For example, when you want to know how many rules there are for SNMP (UDP 161) and you have around 200,000 rules organized across 700 rulesets, it is time-consuming to narrow down that search.

Rule Search makes it simple to search for specific rules. You can search for and analyze rules that allow communication over a specific port and protocol.

  • Rule Search allows you to quickly find rules that apply to a set of providers and consumers.
  • Providers and consumers can be represented by a workload, an IP address, or a set of labels.
  • It helps you identify rules that are getting applied to your workloads due to unnecessarily broadly applicable rulesets or human errors.

To search for rules:

  1. From the PCE web console menu, choose Rule Search.
  2. Search for Active or Draft rules.
  3. Perform a Basic or Advanced search of your rules:
    • Basic: Searches all attributes
    • Advanced: Searches by provider, consumer, or both.
  4. Click the Column drop-down list to select the attributes you want to be displayed in the search results.

  5. Choose to either have the exact match of the selected search filters to be displayed or a match to any of the selected filters (all results).
  6. Filter options to further narrow your search.
  7. Click Go after you have selected your options.


    When you perform an advanced search by workload name, the search results do not display the IP list rules when the iplist contains workload IP addresses because the Illumio Core does not resolve CIDRs and ranges within an IP list.

  8. Under the Ruleset column, select a ruleset and make changes to the rules.
  9. Click Download to download the results of your search.

    You can download up to 500 rules in the CSV format.

Policy Check

The Policy Check feature allows you to determine if a rule allowing communication between workloads or a workload and another IP address already exists.

For example, you have created several rulesets for your workloads and applications and you want to know whether your organization has an existing rule for that traffic before you start writing new rules that duplicate those existing rules.


You can do a policy check between two workloads, or a single workload and single IP address.

To perform a policy check:

  1. From the PCE web console menu, choose Troubleshooting > Policy Check.
  2. On the Policy Check page, select two workloads or IP addresses to determine if a rule exists to allow communication between them.
  3. In the Provider field, type or select a workload or IP address.
  4. In the Port and Protocol field, enter a port and protocol when the connection is running over TCP or UDP, or just a protocol when the connection is running over GRE or IPIP.
  5. In the Consumer field, type or select a workload or IP address.
  6. Click Check Rules.

    If a connection is allowed between the selected two workloads or IP addresses, the page will display at least one rule that allows the connection.

  7. NOTE:

    The status column does not display any values. For more information, you can do a detailed search using the Rule Search feature.

    When a rule does not exists, the page displays “No Rules exist to allow that connection.”