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 <_static/uid-register.xml>`__
and
`unregister <_static/uid-unregister.xml>`__
messages manage tag to IP mappings (``registered-ip`` objects):

.. literalinclude:: _static/uid-register.xml
   :language: xml
   :linenos:

.. literalinclude:: _static/uid-unregister.xml
   :language: xml
   :linenos:

``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 <_static/uid-register2.xml>`__
 and
 `unregister <_static/uid-unregister2.xml>`__
 messages for IPv4 range, network and host objects:

 .. literalinclude:: _static/uid-register2.xml
    :language: xml
    :linenos:

 .. literalinclude:: _static/uid-unregister2.xml
    :language: xml
    :linenos:

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:

 #. single quote
 #. double quote
 #. 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 <_static/uid-unregister-register.xml>`_
can be combined in a single XML document:

.. literalinclude:: _static/uid-unregister-register.xml
   :language: xml
   :linenos:

.. 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 <_static/uid-clear-registered-ip.xml>`_
message removes all IP tag mappings.
This is equivalent to the CLI command
``debug object registered-ip clear all``.

.. literalinclude:: _static/uid-clear-registered-ip.xml
   :language: xml
   :linenos:

.. 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
------

#. Use **panxapi.py** to perform a *register* request.

#. Verify ``registered-ip`` mappings using the CLI.

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

#. Verify mappings using **panxapi.py** **-o**.

#. View dynamic address group members for group ``group2`` using the CLI.

#. View *iptag* logs using the CLI.

#. 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**.

.. admonition:: Solution
   :class: toggle

   ::

     $ 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