User Groups (Optional)
======================

`groups <_static/uid-groups.xml>`_
messages manage user to group mappings:

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

Groups Updates
--------------

 Group members must be updated in their entirety; it is not possible
 to add or delete individual members.

 .. note:: :ref:`dug_objects`
	   is the preferred method to perform user to group mappings
	   when using PAN-OS 9.1 or greater; Dynamic User Groups can
	   be updated incrementally.

 To
 `delete (clear) <_static/uid-groups-clear.xml>`_
 a group,
 perform an update with an empty ``<members/>``
 element node:

 .. literalinclude:: _static/uid-groups-clear.xml
   :language: xml
   :linenos:

Example: Add User to Group Mappings (groups)
--------------------------------------------
::

  $ cat uid-groups.xml
  <uid-message>
    <type>update</type>
    <payload>
      <groups>
        <entry name="group1">
          <members>
            <entry name="user1"/>
            <entry name="domain\user2"/>
          </members>
        </entry>
        <entry name="group2">
          <members>
            <entry name="user3"/>
          </members>
        </entry>
      </groups>
    </payload>
  </uid-message>

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

  admin@PA-VM> show user group list

  group1
  group2

  Total: 2
  * : Custom Group

  admin@PA-VM> show user group name group1


  source type: xmlapi

  [1     ] user1
  [2     ] domain\user2

  admin@PA-VM> show user group name group2


  source type: xmlapi

  [1     ] user3

.. tip:: The CLI commands
	 ``debug user-id clear group all``
	 and
	 ``debug user-id clear group <group>``
         can be used to remove all user group mappings and
	 a specific group's mappings.

Lab 14
------

#. Use **panxapi.py** to perform a *groups* request to create group members.

#. Verify ``group`` membership using the CLI.

#. Verify ``group`` membership using **panxapi.py** **-o**.

#. Use **panxapi.py** to perform a *groups* request to remove a group.

#. Verify ``group`` membership using the CLI.

.. 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-groups.xml
     dynamic-update: success

     admin@PA-VM> show user group name group1


     source type: xmlapi

     [1     ] user1
     [2     ] domain\user2

     $ panxapi.py -Xro 'show user group name "group2"'
     op: success
     source type: xmlapi

     [1     ] user3

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

     admin@PA-VM> show user group name group2

     admin@PA-VM>