[v7r0] Docs.ConfigurationSystem: move explanations from rst to code, add some doc for options

ConfigurationSystem/Agent/Bdii2CSAgent.py

@@ -1,8 +1,8 @@
 """ The Bdii2CSAgent performs checking BDII for availability of CE and SE
-    resources for a given or any configured VO. It detects resources not yet
-    present in the CS and notifies the administrators.
-    For the CEs and SEs already present in the CS, the agent is updating
-    if necessary settings which were changed in the BDII recently
+resources for a given or any configured VO. It detects resources not yet
+present in the CS and notifies the administrators.
+For the CEs and SEs already present in the CS, the agent is updating
+if necessary settings which were changed in the BDII recently
 
 The following options can be set for the Bdii2CSAgent.
 

ConfigurationSystem/Agent/VOMS2CSAgent.py

@@ -1,8 +1,17 @@
 """
-VOMS2CSAgent performs the following operations:
+The VOMS2CSAgent extracts VO user information from VOMS servers.
 
-- Adds new users for the given VO taking into account the VO VOMS information
-- Updates the data in the CS for existing users including DIRAC group membership
+It performs the following operations:
+
+- Extracts user info from the VOMS server using its REST interface
+- Finds user DN's not yet registered in the DIRAC Registry
+- For each new DN it constructs a DIRAC login name by a best guess or using the nickname VOMS attribute
+- Registers new users to the DIRAC Registry including group membership
+- Updates information for already registered users, including group membership
+- Sends report for performed operation to the VO administrator
+
+The agent is performing its operations with credentials of the VO administrator as defined
+in the ``/Registry/VO/<VO_name>`` configuration section. See also :ref:`registry_vo`.
 
 The following options can be set for the VOMS2CSAgent.
 
@@ -12,6 +21,9 @@
   :dedent: 2
   :caption: VOMS2CSAgent options
 
+.. note:: The options *AutoAddUsers*, *AutoModifyUsers*, *AutoDeleteUsers* can be overridden by the
+  corresponding options defined in the ``/Registry/VO/<VO_name>`` configuration section.
+
 """
 
 from __future__ import absolute_import

ConfigurationSystem/ConfigTemplate.cfg

@@ -1,18 +1,25 @@
 Services
 {
+  ##BEGIN Server
   Server
   {
     HandlerPath = DIRAC/ConfigurationSystem/Service/ConfigurationHandler.py
     Port = 9135
+    # Subsection to configure authorization over the service
     Authorization
     {
+      # Default authorization
       Default = authenticated
+      #Define who can commit new configuration
       commitNewData = CSAdministrator
+      # Define who can roll back the configuration to a previous version
       rollbackToVersion = CSAdministrator
+      # Define who can get version contents
       getVersionContents = ServiceAdministrator
       getVersionContents += CSAdministrator
     }
   }
+  ##END
 }
 Agents
 {
@@ -23,15 +30,19 @@ Agents
     PollingTime = 14400
     BannedCEs =
     BannedSEs =
+    # Only treat these sites
     SelectedSites =
+    # Process Computing Elements
     ProcessCEs = yes
+    # Process Storage Elements
     ProcessSEs = no
     # Mail Notifications options
     MailTo =
     MailFrom =
     VirtualOrganization =
     # Flag to turn to False if you want this agent to write in the CS
     DryRun = True
+    # Host to query, must include port
     Host = lcg-bdii.cern.ch:2170
     # URLs for Glue2, if filled and GLUE2Only is False, the agent will look under theses URLs for Glue2 information
     GLUE2URLs =
@@ -45,12 +56,19 @@ Agents
     #Time between cycles in seconds
     PollingTime = 14400
     MailFrom = noreply@dirac.system
+    # If users will be added automatically
     AutoAddUsers = True
+    # If users will be modified automatically
     AutoModifyUsers = True
+    # Users no longer registered in VOMS are automatically deleted from DIRAC
     AutoDeleteUsers = True
+    # If suspended status is lifted, if lifted in VOMS
     AutoLiftSuspendedStatus = True
+    # Detailed report on users per group send to the VO administrator
     DetailedReport = True
+    # Automatically create user home directory in the File Catalog
     MakeHomeDirectory = False
+    # List of VO names
     VO = Any
     # Flag to turn to False if you want this agent to write in the CS (more granularity within other options)
     DryRun = True
@@ -63,6 +81,8 @@ Agents
     PollingTime = 14400
     # Flag to turn to False if you want this agent to write in the CS
     DryRun = True
+    # if False, disable the updating of perfSONAR endpoints from GOCDB
+    UpdatePerfSONARS = True
   }
   ##END
 }

ConfigurationSystem/Service/ConfigurationHandler.py

@@ -1,4 +1,14 @@
 """ The CS! (Configuration Service)
+
+
+The following options can be set for the Configuration Service.
+
+.. literalinclude:: ../ConfigTemplate.cfg
+  :start-after: ##BEGIN Server
+  :end-before: ##END
+  :dedent: 2
+  :caption: Service options
+
 """
 
 __RCSID__ = "$Id$"

ConfigurationSystem/test/Test_agentOptions.py

@@ -10,7 +10,8 @@
                                                                            'BufferTimeout']}),
           ('DIRAC.ConfigurationSystem.Agent.Bdii2CSAgent', {'IgnoreOptions': ['BannedCEs', 'BannedSEs', 'DryRun',
                                                                               'AlternativeBDIIs', 'VO']}),
-          ('DIRAC.ConfigurationSystem.Agent.GOCDB2CSAgent', {'IgnoreOptions': ['Cycles', 'DryRun']}),
+          ('DIRAC.ConfigurationSystem.Agent.GOCDB2CSAgent', {'IgnoreOptions': ['Cycles', 'DryRun',
+                                                                               'UpdatePerfSONARS']}),
           ('DIRAC.ConfigurationSystem.Agent.VOMS2CSAgent', {'IgnoreOptions': ['VO']}),
           ('DIRAC.DataManagementSystem.Agent.FTS3Agent', {}),
           ('DIRAC.FrameworkSystem.Agent.CAUpdateAgent', {}),

docs/source/AdministratorGuide/Configuration/ConfReference/Registry/VO/index.rst

@@ -1,3 +1,5 @@
+.. _registry_vo:
+
 Registry / VO - Subsections
 ==============================