Correct default passwd file suffix ECFLOW-2056

Author: marcosbento

docs/client_api/api/reloadcustompasswdfile.rst

@@ -22,32 +22,52 @@ The following help text is generated by :code:`ecflow_client --help=reloadcustom
    reloadcustompasswdfile
    ----------------------
    
-   Reload the server custom password file. For those user's who don't use login name
-   This should be used when most users use the machine login name, but a few users specify their own user name,
-   in this case these user must provide a password.
-   Although the password file can be reloaded(i.e to add/remove users), its location can't be changed
-   The password file is located by the ECF_CUSTOM_PASSWD environment variable, both for the client and server
-   On the server the default file name is <host>.<port>.ecf.custom_passwd
-   On the client the default file name is ecf.custom_passwd
+   Reload the server custom password file.
+   
+   The custom password file (authentication) is used by the server to authenticate a 'user' by
+   verifying if the password provided by the user matches the one held by the server. This
+   particular file is used for authentication of users that explicitly specify the user name
+   (either via the environment variable ECF_USER or the --user option).
+   
+   This mechanism should be used when most users use the machine login name, but a few users
+   specify their own user name, in which case the password must also be explicitly provided.
+   
+   The file path is specified as the ECF_CUSTOM_PASSWD environment variable, both for the
+   client and server, and is loaded only by the server on *startup*. This means that the file
+   contents can be updated (i.e., add/remove users), but the file location cannot change during
+   the server execution.
+   
+   The server automatically loads the password file content as part of the startup procedure.
+   
+   The ECF_CUSTOM_PASSWD environment variable is used to specify the password file location,
+   considering that
+    - On the server the default file name is <host>.<port>.ecf.custom_passwd
+    - On the client the default file name is ecf.custom_passwd
+   
    The format of the file is same for client and server:
    
+   
    4.5.0
    # comment
    <user> <host> <port> <passwd> # comment
    
-   i.e
+   The following is an example
+   
    4.5.0 # the version
    fred machine1 3142 xxyyyd
    fred machine2 3133 xxyyyd # comment
    bill machine2 3133 xxyggyyd
    
-   The same user may appear multiple times. i.e with different host/port. This allows the password file
-   to be used for multiple servers
-   For the password authentication to work. It must be:
-     - Defined for the client and server
-     - Creating an empty password file,(i.e with just the version) will mean, no client can reload it.
-       Hence at least the server administrator needs to be added to the file
-     - The password file permission's must be set for reading by the user only
+   Notice that the same user may appear multiple times (associated with different host/port).
+   This allows the client to use the same password file to contact multiple servers.
+   
+   For the password authentication to work, ensure the following:
+    - The password is defined for the client and server
+    - On the server, add at least the server administrator to the password file
+      Note: If an empty password file (i.e., containing just the version) is used,
+            no user is allowed access.
+    - On the client, the password file should be readable only by the 'user' itself
+   
    Usage:
     --reloadcustompasswdfile
    

docs/client_api/api/reloadpasswdfile.rst

@@ -22,30 +22,52 @@ The following help text is generated by :code:`ecflow_client --help=reloadpasswd
    reloadpasswdfile
    ----------------
    
-   Reload the server password file. To be used when ALL users have a password
-   Although the password file can be reloaded(i.e to add/remove users), its location can't be changed
-   The password file is located by the ECF_PASSWD environment variable, both for the client and server
-   On the server the default file name is <host>.<port>.ecf.passwd
-   On the client the default file name is ecf.passwd
+   Reload the server password file.
+   
+   The password file (authentication) is used by the server to authenticate a 'user' by
+   verifying if the password provided by the user matches the one held by the server.
+   The password file is also used on the client to automatically load the password for the
+   'user' when connecting to the server.
+   
+   When the server is configured to use a password file, then ALL users must have a password.
+   
+   The file path is specified as the ECF_PASSWD environment variable, both for the client and
+   server, and is loaded only by the server on *startup*. This means that the file contents
+   can be updated (i.e., add/remove users), but the file location cannot change during the
+   server execution.
+   
+   The server automatically loads the password file content as part of the startup procedure.
+   
+   The ECF_PASSWD environment variable is used to specify the password file location,
+   considering that
+    - On the server, the default file name is <host>.<port>.ecf.passwd
+    - On the client, the default file name is ecf.passwd
+   
    The format of the file is same for client and server:
    
+   
    4.5.0
    # comment
    <user> <host> <port> <passwd> # comment
    
-   i.e
+   The following is an example
+   
    4.5.0 # the version
    fred machine1 3142 xxyyyd
    fred machine2 3133 xxyyyd # comment
    bill machine2 3133 xxyggyyd
    
-   The same user may appear multiple times. i.e with different host/port. This allows the password file
-   to be used for multiple servers
-   For the password authentication to work. It must be:
-     - Defined for the client and server
-     - Creating an empty password file,(i.e with just the version) will mean, no client can reload it.
-       Hence at least the server administrator needs to be added to the file
-     - The password file permission's must be set for reading by the user only
+   
+   Notice that the same user may appear multiple times (associated with different host/port).
+   This allows the client to use the same password file to contact multiple servers.
+   
+   For the password authentication to work, ensure the following:
+    - The password is defined for the client and server
+    - On the server, add at least the server administrator to the password file
+      Note: If an empty password file (i.e., containing just the version) is used,
+            no user is allowed access.
+    - On the client, the password file should be readable only by the 'user' itself
+   
    Usage:
     --reloadpasswdfile
    

docs/client_api/api/reloadwsfile.rst

@@ -23,32 +23,47 @@ The following help text is generated by :code:`ecflow_client --help=reloadwsfile
    ------------
    
    Reload the white list file.
-   The white list file is used to authenticate 'user' commands.
-   File path is specified by ECF_LISTS environment, read by the server on *startup*.
-   Hence the contents of the file can be changed but not the location
-   If ECF_LISTS is not specified, or is specified and is 'ecf.lists' then by default
-   it will open <host>.<port>.ecf.lists.If a path like /var/tmp/ecf.lists was specified
-   for ECF_LISTS, then this is the path used for reloading the white list file
-   On startup, if the file is not present or is present but is empty (i.e just contains the version number)
-   then all users have read/write access
-   However on reload it will raises an error if file does not exist, or fails to parse
+   
+   The white list file (authorisation) is used to verify if a 'user' is allowed to perform a
+   specific command.
+   
+   The file path is specified as the ECF_LISTS variable, and loaded only once by the server
+   (on *startup*). This means that the file contents can be updated, but the file location
+   cannot change during the server execution.
+   
+   The ECF_LISTS variable can be used as follows:
+     - if ECF_LISTS is not specified, or if it is specified with value `ecf.lists`,
+       then the server will use the value `<host>.<port>.ecf.lists`
+     - if ECF_LISTS is specified to be a path, such as /var/tmp/ecf.lists,
+       then the server will use this path to reload the white list file
+   
+   The server automatically loads the white list file content as part of the startup procedure,
+   considering that if the file is not present or is empty (i.e., just contains the version
+   number) then all users have read/write access.
+   
+   The reload operation will fail if file does not exist or if the content is invalid.
+   
    Expected format for this file is:
    
-   # comment
-   4.4.14  # version number, this must be present, even if no users specified
    
+   # all characters after the first # in a line are considered comments and are discarded
+   # empty lines are also discarded
+   
+   4.4.14  # the version number is mandatory, even if no users are specified
    # Users with read/write access
-   user1   # comment
+   user1
    user2   # comment
-   
    *       # use this form if you want all users to have read/write access
    
    # Users with read  access, must have - before user name
    -user3  # comment
    -user4
-   
    -*      # use this form if you want all users to have read access
    
+   
+   Usage:
+    --reloadwsfile
+   
    The client considers, for both user and child commands, the following environment variables:
    
      ECF_HOST <string> [mandatory*]

docs/client_api/index.rst

@@ -231,11 +231,11 @@ The list of commands, amongst other details, can be displayed by using the optio
 
     * - :ref:`reloadcustompasswdfile_cli` 
       - :term:`user command`
-      - Reload the server custom password file. For those user's who don't use login name
+      - Reload the server custom password file.
 
     * - :ref:`reloadpasswdfile_cli` 
       - :term:`user command`
-      - Reload the server password file. To be used when ALL users have a password
+      - Reload the server password file.
 
     * - :ref:`reloadwsfile_cli` 
       - :term:`user command`