Login and Logout
================

`login <_static/uid-login.xml>`_
and
`logout <_static/uid-logout.xml>`_
messages manage user to IP mappings:

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

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

Login Timeout
-------------

 *timeout* is optional and the unit is minutes; a ``"0"``
 timeout specifies no timeout (``Never``).

 If not specified the timeout is determined according to the *User
 Identification Timeout* configuration on the firewall; the default
 settings are::

   set user-id-collector setting enable-mapping-timeout yes
   set user-id-collector setting ip-user-mapping-timeout 45

 When ``enable-mapping-timeout`` is ``yes`` the default timeout
 is ``ip-user-mapping-timeout``; when it is ``no`` the default
 is ``Never``.

Logout name
-----------

 The logout ``name`` attribute is optional.  When not specified the
 single user to IP mapping for the ``ip`` specified is deleted.

 .. Note:: A user can have multiple IPs and an IP can have
       one user.

`login and logout <_static/uid-login-logout.xml>`_
can be combined in a single XML document:

.. literalinclude:: _static/uid-login-logout.xml
   :language: xml
   :linenos:

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

Example: Add User to IP Mappings (login)
----------------------------------------
::

  $ cat uid-login.xml
  <uid-message>
    <type>update</type>
    <payload>
      <login>
        <entry name="user1" ip="10.0.0.1"/>
        <entry name="domain\user2" ip="10.0.0.2" timeout="60"/>
      </login>
    </payload>
  </uid-message>

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

  admin@PA-VM> show user ip-user-mapping all

  IP              Vsys   From    User                             IdleTimeout(s) MaxTimeout(s)
  --------------- ------ ------- -------------------------------- -------------- -------------
  10.0.0.2        vsys1  XMLAPI  domain\user2                     3597           3597
  10.0.0.1        vsys1  XMLAPI  user1                            2697           2697
  Total: 2 users

.. tip:: The CLI operational command ``clear user-cache all``
         removes all IP user mappings.


Lab 13
------

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

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

#. Use **panxapi.py** to perform *login* and *logout* requests in a
   single message.

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

#. View *userid* logs 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-login.xml
     dynamic-update: success
     
     admin@PA-VM> show user ip-user-mapping all

     IP              Vsys   From    User                             IdleTimeout(s) MaxTimeout(s)
     --------------- ------ ------- -------------------------------- -------------- -------------
     10.0.0.2        vsys1  XMLAPI  domain\user2                     3594           3594
     10.0.0.1        vsys1  XMLAPI  user1                            2694           2694
     Total: 2 users

     $ panxapi.py -U uid-login-logout.xml
     dynamic-update: success
     
     $ panxapi.py -Xro 'show user ip-user-mapping all'
     op: success
     <entry><ip>10.0.0.3</ip><vsys>vsys1</vsys><type>XMLAPI</type><user>user3</user><idle_timeout>2690</idle_timeout><timeout>2690</timeout></entry>
     <entry><ip>10.0.0.1</ip><vsys>vsys1</vsys><type>XMLAPI</type><user>user1</user><idle_timeout>2672</idle_timeout><timeout>2672</timeout></entry>
     <count>2</count>
     
     admin@PA-VM> show log userid receive_time in last-hour
     Domain,Receive Time,Serial #,Sequence Number,Action Flags,Type,Threat/Content Type,Config Version,Generate Time,dg_hier_level_1,dg_hier_level_2,dg_hier_level_3,dg_hier_level_4,Virtual System Name,Device Name,Virtual System ID,Virtual System,Source IP,User,Data Source Name,Event ID,Repeat Count,timeout,beginport,endport,Data Source,Data Source Type,Padding,cpadding,Factor Type,Factor Completion Time,Factor Number
     1,2017/05/15 09:59:02,015351000001428,36,0x0,USERID,login,6,2017/05/15 09:59:02,0,0,0,0,,PA-VM,1,vsys1,10.0.0.1,user1,XMLAPI,0,1,2700,0,0,xml-api,,0,0,,2017/05/15 09:59:02,1
     1,2017/05/15 09:59:02,015351000001428,37,0x0,USERID,login,6,2017/05/15 09:59:02,0,0,0,0,,PA-VM,1,vsys1,10.0.0.2,domain\user2,XMLAPI,0,1,3600,0,0,xml-api,,0,0,,2017/05/15 09:59:02,1
     1,2017/05/15 09:59:19,015351000001428,38,0x0,USERID,login,6,2017/05/15 09:59:19,0,0,0,0,,PA-VM,1,vsys1,10.0.0.3,user3,XMLAPI,0,1,2700,0,0,xml-api,,0,0,,2017/05/15 09:59:20,1
     1,2017/05/15 09:59:19,015351000001428,39,0x0,USERID,logout,6,2017/05/15 09:59:19,0,0,0,0,,PA-VM,1,vsys1,10.0.0.2,domain\user2,XMLAPI,0,1,0,0,0,xml-api,,0,0,,2017/05/15 09:59:20,1