Add documentation about entropy, binding and mapping

source/index.rst

@@ -21,6 +21,7 @@ Contents:
    pdp/index
    pep/index
    monitoring/index
+   operations/index
    quick_start/index
    misc/examples
    misc/service_reference_card

source/operations/bind_localhost.rst

@@ -0,0 +1,100 @@
+.. _argus_bind_localhost:
+
+Bind services to localhost
+==========================
+
+Argus services can be deployed all on the same machine.
+
+The service that is mandatory to expose outside the machine is
+only the PEP service.
+So to avoid to expose PAP and PDP services,
+these daemon can configured to listen on loopback interface.
+
+To achieve this kind of deployment, change the configuration as
+described below.
+
+.. warning::
+   To bind the services on the loopback interface,
+   ensure that the host certificate includes ``localhost`` and
+   ``127.0.0.1`` in the Subject Alternative Name.
+
+PAP
+^^^
+
+Argus PAP service listen on all interfaces, by design.
+So, it cannot be binded only to loopback interface.
+
+
+PDP
+^^^
+
+Edit ``/etc/argus/pdp/pdp.ini`` specifying ``localhost`` as hostname::
+
+  hostname = localhost
+  port = 8152
+
+Update the ``paps`` option with the endpoint of the local PAP::
+
+  [POLICY]
+  paps = https://localhost:8150/pap/services/ProvisioningService
+
+PEP
+^^^
+
+Edit ``/etc/argus/pepd/pepd.ini`` with the local PDP endpoint::
+  
+  [PDP]
+  pdps = https://localhost:8152/authz
+
+
+Validation
+^^^^^^^^^^
+
+Restart the services; on EL7 platforms::
+
+  $ systemctl restart argus-pap argus-pdp argus-pepd
+
+On EL6 platforms::
+
+  $ for svc in pap pdp pepd; do service argus-$svc restart; done
+
+Check the ports::
+
+  $ ss -tnpl sport ge :8150 and sport le :8155 | column -t
+  State   Recv-Q  Send-Q  Local                   Address:Port  Peer                             Address:Port
+  LISTEN  0       50      :::8150                 :::*          users:(("java",pid=8030,fd=63))
+  LISTEN  0       50      ::ffff:127.0.0.1:8151   :::*          users:(("java",pid=8030,fd=58))
+  LISTEN  0       50      ::ffff:127.0.0.1:8152   :::*          users:(("java",pid=7963,fd=67))
+  LISTEN  0       50      ::ffff:127.0.0.1:8153   :::*          users:(("java",pid=7963,fd=62))
+  LISTEN  0       50      ::ffff:10.0.0.173:8154  :::*          users:(("java",pid=7979,fd=66))
+  LISTEN  0       50      ::ffff:127.0.0.1:8155   :::*          users:(("java",pid=7979,fd=60))
+
+From another host, scan the Argus ports::
+
+  $ nmap -p8150-8155 argus.cnaf.test
+
+  Starting Nmap 7.60 ( https://nmap.org ) at 2017-12-04 15:07 CET
+  Nmap scan report for argus.cnaf.test (10.0.0.173)
+  Host is up (0.00015s latency).
+  rDNS record for 10.0.0.173: argus
+
+  PORT     STATE  SERVICE
+  8150/tcp open   unknown
+  8151/tcp closed unknown
+  8152/tcp closed unknown
+  8153/tcp closed quantastor
+  8154/tcp open   unknown
+  8155/tcp closed unknown
+
+  Nmap done: 1 IP address (1 host up) scanned in 0.03 seconds
+
+
+See also
+--------
+
+:ref:`Firewall setup <argus_firewall>`
+
+References
+----------
+
+`GGUS ticket <https://ggus.eu/index.php?mode=ticket_info&ticket_id=131284>`_

source/operations/entropy.rst

@@ -0,0 +1,68 @@
+.. _argus_entropy:
+
+Entropy related problems
+========================
+
+In headless servers, sometimes Java processes hangs waiting on a thread that's
+continuously in wait status, trying to generate random numbers, because entropy
+is too low to generate enough random numbers.
+
+Check the entropy level with the following command::
+
+  $ cat /proc/sys/kernel/random/entropy_avail
+
+If the obtained value is less than 1000, entropy is too low. This problem can be
+solved in two different way:
+
+- Running ``haveged`` daemon;
+- Configure Argus daemons to use ``/dev/urandom`` as random device.
+
+
+Run Haveged
+-----------
+
+Install EPEL repository and ``haveged`` package::
+
+  $ sudo yum install -y epel-release
+  $ sudo yum install -y haveged
+
+Enable and run the daemon. On EL7 platforms::
+
+  $ sudo systemctl enable haveged
+  $ sudo systemctl start haveged
+
+On EL6 platforms::
+
+  $ sudo chkconfig haveged on
+  $ sudo service haveged start
+
+
+Change random device
+--------------------
+
+Edit the Argus services environment files, adding the option
+``-Djava.security.egd=file:/dev/urandom`` to the Java options.
+
+For the PAP service, edit the ``PAP_JAVA_OPTS`` variable in
+``/etc/sysconfig/argus-pap`` file. Example::
+
+  PAP_JAVA_OPTS="-Djava.security.egd=file:/dev/urandom"
+
+For the PDP service, edit the ``PDP_JOPTS`` variable in
+``/etc/sysconfig/argus-pdp`` file. Example::
+  
+  PDP_JOPTS="-Xmx256M -Djdk.tls.trustNameService=true -Djava.security.egd=file:/dev/urandom"
+
+For the PEP daemon, edit the ``PEPD_JOPTS`` variable in
+``/etc/sysconfig/argus-pepd`` file. Example:: 
+
+  PEPD_JOPTS="-Xmx256M -Djdk.tls.trustNameService=true -Djava.security.egd=file:/dev/urandom"
+
+Then restart the services. On EL7 platforms::
+
+  $ sudo systemctl restart argus-pap argus-pdp argus-pepd
+
+On EL6 platforms::
+
+  $ for svc in pap pdp pepd; do sudo service argus-$svc restart; done
+

source/operations/firewall.rst

@@ -0,0 +1,55 @@
+.. _argus_firewall:
+
+Firewall setup
+==============
+
+You can use a firewall to restrict access to Argus services.
+
+A simple setup is to open only the Argus PEP port.
+
+Edit the iptables configuration file ``/etc/sysconfig/iptables``
+to open the PEP port 8154 in the ``INPUT`` chain and
+drop network traffic on all other ports (except SSH)::
+ 
+  *filter
+  :INPUT DROP [0:0]
+  :FORWARD DROP [0:0]
+  :OUTPUT ACCEPT [0:0]
+  -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
+  -A INPUT -p icmp -j ACCEPT
+  -A INPUT -i lo -j ACCEPT
+  -A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT
+  -A INPUT -p tcp -m state --state NEW -m tcp --dport 8154 -j ACCEPT
+  COMMIT
+
+Save the changes and restart iptables. On EL7 platforms::
+
+  $ systemctl restart iptables
+
+On EL6 platforms::
+
+  $ service iptables restart
+
+
+Validation
+^^^^^^^^^^
+
+From another host, scan the Argus ports::
+
+  $ nmap -Pn -p8150-8155 argus.cnaf.test
+
+  Starting Nmap 7.60 ( https://nmap.org ) at 2017-12-04 15:07 CET
+  Nmap scan report for argus.cnaf.test (10.0.0.173)
+  Host is up (0.00015s latency).
+  rDNS record for 10.0.0.173: argus
+
+  PORT     STATE    SERVICE
+  8150/tcp filtered unknown
+  8151/tcp filtered unknown
+  8152/tcp filtered unknown
+  8153/tcp filtered quantastor
+  8154/tcp open     unknown
+  8155/tcp filtered unknown
+
+  Nmap done: 1 IP address (1 host up) scanned in 2.14 seconds
+

source/operations/index.rst

@@ -0,0 +1,12 @@
+.. _argus_operations_index:
+
+Argus Operations
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   entropy
+   bind_localhost
+   firewall
+   mapping

source/operations/mapping.rst

@@ -0,0 +1,69 @@
+.. _argus_mapping:
+
+Mapping details
+===============
+
+.. attention::
+   | New behavior from Argus 1.7.0
+
+Argus 1.7.0 fixes an incorrect behavior in groups mapping, in particular
+in the handling of secondary group names, as described in issues `pep-7`_ and `pep-11`_.
+
+This changes have an impact in the creation of hard links in the ``/etc/grid-security/gridmapdir``
+directory, links used to map Grid users to a local pool account.
+
+Since version 1.7.0, these link are created with the following pattern::
+
+   <dn>:<primary group>:<secondary group>
+
+If needed, to keep compatibility with the LCMAPS ``-do_not_use_secondary_gids``
+option used by the CREAM YAIM module, in Argus 1.7 you would need to add::
+
+   useSecondaryGroupNamesForMapping = false
+
+in the ``[ACCOUNTMAP_OH]`` section of the ``/etc/argus/pepd/pepd.ini``
+and restart the service.
+
+
+Example
+^^^^^^^
+
+With the default settings, Argus PEP server use secondary groups for mapping.
+Performing a request with ``pepcli``, for example::
+
+   $ pepcli --capath /etc/grid-security/certificates/ --cert .globus/usercert.pem --key .globus/userkey.pem -k /tmp/x509up_u0 -p https://argus.cnaf.test:8154/authz -a "ANY" -r "resource-2"
+   Resource: resource-2
+   Decision: Permit
+   Obligation: http://glite.org/xacml/obligation/local-environment-map/posix (caller should resolve POSIX account mapping)
+   Username: tst13
+   Group: testvo
+   Secondary Groups: testvo testvo
+
+Into ``/etc/grid-security/gridmapdir`` we'll found the mapping::
+
+   $ ll -hrt /etc/grid-security/gridmapdir/
+   ...
+   -rw-r--r--. 2 root root 0 Jan 25 14:17 tst13
+   -rw-r--r--. 2 root root 0 Jan 25 14:17 %2fc%3dit%2fo%3digi%2fcn%3dtest0:testvo:testvo
+
+To disable the usage of secondary groups, edit ``/etc/argus/pepd/pepd.ini`` setting::
+
+   [ACCOUNTMAP_OH]
+   parserClass = org.glite.authz.pep.obligation.dfpmap.DFPMObligationHandlerConfigurationParser
+   accountMapFile = /etc/grid-security/grid-mapfile
+   groupMapFile = /etc/grid-security/groupmapfile
+   gridMapDir = /etc/grid-security/gridmapdir
+   
+   useSecondaryGroupNamesForMapping = false
+   
+Restart the PEP server. Now, repeating the same request with ``pepcli``
+the mapping obtained will be::
+
+   $ ll -hrt /etc/grid-security/gridmapdir/
+   ...
+   -rw-r--r--. 2 root root 0 Jan 25 14:08 tst06
+   -rw-r--r--. 2 root root 0 Jan 25 14:08 %2fc%3dit%2fo%3digi%2fcn%3dtest0:testvo
+
+
+.. _pep-7: https://github.com/argus-authz/argus-pep-server/issues/7
+.. _pep-11: https://github.com/argus-authz/argus-pep-server/issues/11

source/release_notes/v_1_7_0.rst

@@ -46,7 +46,7 @@ Changes in the mapping logic behaviour (`pep-7`_ , `pep-11`_), and in
 particular in the handling of secondary group names, could produce different
 mappings for user jobs, so it's safer to drain the site before upgrading the
 Argus services to version 1.7.0 if you want to avoid potential job failures
-due to the upgrade.
+due to the upgrade. More details can be found :ref:`here <argus_mapping>`.
 
 Main fixes
 ~~~~~~~~~~