Register and Unregister - DAG Objects

Dynamic Address Groups (DAGs) are an alternative to Static Address Groups. An Address Groups object with type Dynamic is created containing match criteria to define the members in the address group using the and and or operators to match registered-ip object tags and populate the DAG, which can be used in the source and destination address of a security policy.

register and unregister messages manage tag to IP mappings (registered-ip objects):

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <register>
 5      <entry ip="10.0.0.1">
 6        <tag>
 7          <member>tag01</member>
 8          <member timeout="0">tag02</member>
 9          <member timeout="3600">tag03</member>
10        </tag>
11      </entry>
12      <entry ip="10.0.0.2" persistent="0">
13        <tag>
14          <member>tag01</member>
15        </tag>
16      </entry>
17    </register>
18  </payload>
19</uid-message>

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <unregister>
 5      <entry ip="10.0.0.1">
 6        <tag>
 7          <member>tag01</member>
 8        </tag>
 9      </entry>
10    </unregister>
11  </payload>
12</uid-message>

registered-ip Objects

A registered-ip object can be the following:

  • IPv4 host address (/32)

  • IPv6 host address (/128)

Starting with PAN-OS 10.0, additional objects are allowed:

  • IPv4 ranges (ip-start - ip-end: 10.0.0.1-10.0.0.9)

  • IPv4 networks (network/prefix: 10.0.0.0/24)

register and unregister messages for IPv4 range, network and host objects:

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <register>
 5      <entry ip="10.1.1.10-10.1.1.19">
 6        <tag>
 7          <member>tag01</member>
 8        </tag>
 9      </entry>
10      <entry ip="10.1.1.0/24">
11        <tag>
12          <member>tag02</member>
13        </tag>
14      </entry>
15      <entry ip="10.1.1.1/32">
16        <tag>
17          <member>tag03</member>
18        </tag>
19      </entry>
20    </register>
21  </payload>
22</uid-message>

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <unregister>
 5      <entry ip="10.1.1.10-10.1.1.19">
 6        <tag>
 7          <member>tag01</member>
 8        </tag>
 9      </entry>
10      <entry ip="10.1.1.0/24">
11        <tag>
12          <member>tag02</member>
13        </tag>
14      </entry>
15    </unregister>
16  </payload>
17</uid-message>

Object Tag Inheritance

registered-ip objects inherit tags from other objects they are contained within. For the previous register message, the tags and inherited tags are as follows:

Object

Tags

Inherited Tags

Inherited From

10.1.1.10-10.1.1.19

tag01

tag02

10.1.1.0/24

10.1.1.0/24

tag02

10.1.1.1/32

tag03

tag02

10.1.1.0/24

Tags

Up to 32 tags can be specified for each registered-ip object.

The maximum length of a tag is 127.

The tag name cannot contain the following:

  1. single quote

  2. double quote

  3. greater than one consecutive space

And cannot be the case insensitive words:

  • and, or, not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent. Persistent means the mapping is preserved across device reboots.

The persistent attribute is optional and can be "0" (non-persistent) or "1" (persistent); the default is persistent.

Note

When an existing registered-ip mapping is updated, the persistence is updated according to the persistent attribute in the update.

Timeout Attribute

Starting with PAN-OS 9.0 a tag can contain an optional timeout attribute in the <member> element. Unrecognized attributes are ignored, so timeout can be specified in documents used on prior PAN-OS versions.

The default is "0" (never expires) or a timeout value in seconds for the tag. The maximum timeout is 2592000 (30 days).

register and unregister can be combined in a single XML document:

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <unregister>
 5      <entry ip="10.0.0.1">
 6        <tag>
 7          <member>tag02</member>
 8          <member>tag03</member>
 9        </tag>
10      </entry>
11    </unregister>
12    <register>
13      <entry ip="10.0.0.2">
14        <tag>
15          <member>tag02</member>
16        </tag>
17      </entry>
18      <entry ip="10.0.0.3">
19        <tag>
20          <member>tag01</member>
21          <member>tag02</member>
22        </tag>
23      </entry>
24    </register>
25  </payload>
26</uid-message>

Note

When register and unregister are combined in a single document, the entries are processed in the order: unregister, register; only a single <register/> and <unregister/> section should be specified.

A clear registered-ip message removes all IP tag mappings. This is equivalent to the CLI command debug object registered-ip clear all.

 1<uid-message>
 2  <type>update</type>
 3  <payload>
 4    <clear>
 5      <registered-ip>
 6        <all/>
 7      </registered-ip>
 8    </clear>
 9  </payload>
10</uid-message>

Note

The dynamic address group group2 exists in the lab config with match criteria: "tag01" or "tag02".

Example: Add Tag to IP Mappings (register)

$ cat uid-register.xml
<uid-message>
  <type>update</type>
  <payload>
    <register>
      <entry ip="10.0.0.1">
        <tag>
          <member>tag01</member>
          <member timeout="0">tag02</member>
          <member timeout="3600">tag03</member>
        </tag>
      </entry>
      <entry ip="10.0.0.2" persistent="0">
        <tag>
          <member>tag01</member>
        </tag>
      </entry>
    </register>
  </payload>
</uid-message>

$ panxapi.py -xU uid-register.xml
dynamic-update: success
<response status="success"><result><uid-response>
  <version>2.0</version>
  <payload>
    <register>
    </register>
  </payload>
</uid-response>
</result></response>

admin@PA-VM> show object registered-ip all

registered IP                             Tags
----------------------------------------  -----------------

10.0.0.1 #
                                         "tag01 (never expire)"
                                         "tag02 (never expire)"
                                         "tag03 (expire in 3592 seconds)"

10.0.0.2
                                         "tag01 (never expire)"

Total: 2 registered addresses
*: received from user-id agent  #: persistent

$ panxapi.py -Xro 'show object registered-ip all'
op: success
<entry from_agent="0" ip="10.0.0.1" persistent="1">
<tag>
<member>tag01</member>
<member>tag02</member>
<member>tag03</member>
</tag>
</entry>
<entry from_agent="0" ip="10.0.0.2" persistent="0">
<tag>
<member>tag01</member>
</tag>
</entry>
<count>2</count>

admin@PA-VM> show object dynamic-address-group name group2


Dynamic address groups in vsys vsys1:
----------------------------------------------------

----------------defined in vsys --------------------
        group2
                filter: "tag01" or "tag02"

                        10.0.0.1 (R)
                        10.0.0.2 (R)
                members: total 2
O: address object; R: registered ip; D: dynamic group; S: static group

Lab 16

  1. Use panxapi.py to perform a register request.

  2. Verify registered-ip mappings using the CLI.

  3. Use panxapi.py to perform unregister and register requests in a single message.

  4. Verify mappings using panxapi.py -o.

  5. View dynamic address group members for group group2 using the CLI.

  6. View iptag logs using the CLI.

  7. Use panxapi.py to perform a clear request to remove all IP tag mappings.

Hint

The links to the <uid-message/> XML documents above can be retrieved using curl or wget.

Solution

$ panxapi.py -U uid-register.xml
dynamic-update: success

admin@PA-VM> show object registered-ip all

registered IP                             Tags
----------------------------------------  -----------------

10.0.0.1 #
                                         "tag01"
                                         "tag02"
                                         "tag03"

10.0.0.2
                                         "tag01"

Total: 2 registered addresses
*: received from user-id agent  #: persistent

$ panxapi.py -U uid-unregister-register.xml
dynamic-update: success

$ panxapi.py -Xro 'show object registered-ip all'
op: success
<entry from_agent="0" ip="10.0.0.1" persistent="1">
<tag>
<member>tag01</member>
</tag>
</entry>
<entry from_agent="0" ip="10.0.0.2" persistent="1">
<tag>
<member>tag01</member>
<member>tag02</member>
</tag>
</entry>
<entry from_agent="0" ip="10.0.0.3" persistent="1">
<tag>
<member>tag01</member>
<member>tag02</member>
</tag>
</entry>
<count>3</count>

admin@PA-VM> show object dynamic-address-group name group2


Dynamic address groups in vsys vsys1:
----------------------------------------------------

----------------defined in vsys --------------------
        group2
                filter: "tag01" or "tag02"
                members: total 3
                        10.0.0.1 (R)
                        10.0.0.2 (R)
                        10.0.0.3 (R)

O: address object; R: registered ip; D: dynamic group; S: static group

admin@PA-VM> show log iptag receive_time in last-15-minutes
Domain,Receive Time,Serial #,Sequence Number,Action Flags,Type,Threat/Content Type,Config Version,Generate Time,Virtual System,Source IP,tag_name,event_id,Repeat Count,timeout,Data Source Name,datasource_type,datasource_subtype,dg_hier_level_1,dg_hier_level_2,dg_hier_level_3,dg_hier_level_4,Virtual System Name,Device Name
1,2017/05/15 11:13:06,015351000001428,38,0x0,IPTAG,0,6,2017/05/15 11:13:06,vsys1,10.0.0.1,tag01,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:13:06,015351000001428,39,0x0,IPTAG,0,6,2017/05/15 11:13:06,vsys1,10.0.0.1,tag02,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:13:06,015351000001428,40,0x0,IPTAG,0,6,2017/05/15 11:13:06,vsys1,10.0.0.1,tag03,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:13:06,015351000001428,41,0x0,IPTAG,0,6,2017/05/15 11:13:06,vsys1,10.0.0.2,tag01,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:14:12,015351000001428,42,0x0,IPTAG,0,6,2017/05/15 11:14:12,vsys1,10.0.0.1,tag02,unregister,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:14:12,015351000001428,43,0x0,IPTAG,0,6,2017/05/15 11:14:12,vsys1,10.0.0.1,tag03,unregister,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:14:12,015351000001428,44,0x0,IPTAG,0,6,2017/05/15 11:14:12,vsys1,10.0.0.2,tag02,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:14:12,015351000001428,45,0x0,IPTAG,0,6,2017/05/15 11:14:12,vsys1,10.0.0.3,tag01,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM
1,2017/05/15 11:14:12,015351000001428,46,0x0,IPTAG,0,6,2017/05/15 11:14:12,vsys1,10.0.0.3,tag02,register,1,0,XMLAPI,xml-api,unknown,0,0,0,0,,PA-VM

$ panxapi.py -U uid-clear-registered-ip.xml
dynamic-update: success