Configuring user authentication for PAM and default clients

Follow these steps to configure authentication for PAM and default clients by using an authentication plug-in.

Before you begin

  1. Stop the cluster:
    # egoshutdown.sh
  2. On all management hosts, create a plug-in configuration file (pamauth.conf) under the $EGO_CONFDIR directory. For an example of a pamauth.conf file, refer to the following steps. If you have used the PAM plug-in previously, this file might exist.
    Note: If $EGO_CONFDIR is on a shared directory, you need to perform this step only once.
  3. Optional: Complete one of the following steps:
    • Ensure a PAM service file (the default PAM service is sshd) exists under the /etc/pam.d/ directory. As root, assign 644 permissions to the PAM service file.
    • Configure the EGO plug-in to use another (existing) PAM policy file (for example, sshd). The PAM configuration file controls the authentication policy and can be modified by the system administrator.

Procedure

  1. Edit the PAM configuration file ($EGO_CONFDIR/pamauth.conf) to set the values of mandatory and optional parameters:
    Table 1. PAM configuration parameters
    Parameter Mandatory or optional Description
    PAM_SERVICE Mandatory Specifies the PAM policy file that is located under the /etc/pam.d/ directory.
    KEYFILE Optional Specifies the path to the key file.

    You can also specify a custom key in the key file, which is used to create credentials. Specify a value for the KEY parameter within the KEYFILE parameter. Specify up to 64 ASCII alphanumeric characters and special characters. For example, KEY="myKey12345@#$%^*ABC".

    PAM_CACHEEXPIRYTIME Optional Specifies the interval at which the user cache is updated, enabling new users and user groups to be imported from PAM and registered to the system. By default, the user cache is updated every day. In environments where adding and removing users are frequent operations, set this parameter at an interval that suits your requirements.
    • To specify an interval in days, enter a positive integer or a positive integer followed by d or D for days. For example, 2 or 2d means the user cache is set to refresh every 2 days. The default is 1d.
    • To specify a duration in minutes or hours, enter a positive integer followed by m or M for minutes or h or H for hours. For example, 2m means the user cache is set to refresh every 2 minutes; 2h means the user cache is set to refresh every 2 hours.

      Configuring a short refresh interval might degrade cluster performance. Ensure that you choose a value that balances cache refresh requirements and cluster performance. Take note that setting the value to 0 disables the user cache and retrieves user data from PAM all the time.
    INCLUDED_USERGROUP

    -or-

    EXCLUDED_USERGROUP

    		 Optional When users are automatically loaded to the cluster, users and user groups are retrieved through the glibc API, which returns the same results as the Linux® getent passwd and getent group commands. As a result, many users and user groups that are not used in the cluster are added to the cluster, impacting performance.

    Limit users added to the cluster to either include only user groups configured in the INCLUDED_USERGROUP parameter or exclude user groups configured in the EXCLUDED_USERGROUPparameter.

    • To add users only from certain user groups, specify the user groups to be added in INCLUDED_USERGROUP, in the format groupname1,groupname2,.... Only users belonging to the specified user groups are loaded; if the group contains subgroups, the subgroups and users in the subgroups are not loaded. For example:
      INCLUDED_USERGROUP=testGroup,testGroup2
    • To exclude users from certain user groups, specify the user groups from which users must not be loaded in EXCLUDED_USERGROUP, in the format groupname1,groupname2,.... For example:
      EXCLUDED_USERGROUP=notforcluster1,notforcluster2
    Ensure that you define only one of the parameters. If both parameters are configured, neither parameter takes effect.
    FOLLOW_GETENT_GROUP Optional If either INCLUDED_USERGROUP or EXCLUDED_USERGROUP is configured, specify whether to strictly follow the output of the getent group groupname command to identify members of a user group.
    • To include only users of a group who show with the getent group groupname command, specify Y.
    • To include all users who show as members of a group with the getent group groupname command and users who have this user group as their primary group, specify N.
    If the getent group groupname command in your environment returns all users that should be considered as belonging to the user group, define FOLLOW_GETENT_GROUP to Y:
    FOLLOW_GETENT_GROUP=Y
    With this setting, only users that can be shown as members of a group with the getent group groupname command are considered as belonging to the user groups defined in the INCLUDED_USERGROUP or EXCLUDED_USERGROUP parameter.
    SEC_PAM_BYPASS Optional Specifies whether to bypass PAM authentication. If you enable this parameter, all user authentication requests from PAM clients succeed.
    For example, the pamauth.conf file can include the following parameters: 
    # Optional parameters
# KEYFILE=<keyfile-location>
# Absolute path to the location of the key file.
KEYFILE=/tmp/seckey.conf
# SEC_PAM_BYPASS=<y-or-n>
# Bypass PAM authentication: Y or N.
SEC_PAM_BYPASS=N
# PAM_CACHEEXPIRYTIME=<a-positive-integer-followed-by-d-or-D-or-h-or-H-or-m-or-M>
# Duration for which the VEMKD must cache the user list obtained from LDAP,
# beyond which time the user list cache expires.
# To specify a duration in days, enter a positive integer or a positive integer followed by d or D.
# For example, PAM_CACHEEXPIRYTIME=2 or PAM_CACHEEXPIRYTIME=2d means the user cache is set to refresh
# every 2 days. To specify a duration in minutes or hours, enter a positive integer followed by m or M
# for minutes (for example, 2m) or h or H for hours (for example, 2h).
# If not specified, the default value of 1 day is used.
# NOTE: Configuring a short refresh interval might downgrade cluster performance. Choose a
# value to balance requirements for cache refreshes and cluster performance.
PAM_CACHEEXPIRYTIME=2h
# INCLUDED_USERGROUP=<pam-user-group-name1,pam-user-group-name2>
# Name of the user group whose users must be included.
# Use a comma (,) to separate multiple user groups.
# Use either INCLUDED_USERGROUP or EXCLUDED_USERGROUP; do not define both parameters.
# EXCLUDED_USERGROUP=<pam-user-group-nameA,pam-user-group-nameB>
# Name of the user group whose users must be excluded.
# Use a comma (,) to separate multiple user groups.
# Use either INCLUDED_USERGROUP or EXCLUDED_USERGROUP; do not define both parameters.
# FOLLOW_GETENT_GROUP=<y-or-n>
# Whether to strictly follow the output of the getent group groupname command to identify members of a
# user group: Y or N.
# Specify Y to include only users of a group who show with the getent group groupname command. Specify N to
# include all users who show as members of a group with the getent group groupname command and users who have
# this user group as their primary group.
# Mandatory parameters
# PAM_SERVICE=<pam-service-name>
# PAM service file (at /etc/pam.d) which defines the
# PAM policy to be used for EGO.
# Default is "sshd"
PAM_SERVICE=sshd
  2. Optional: If you configured the KEYFILE parameter in pamauth.conf, configure a custom key by using the KEY parameter within KEYFILE.
    For example, the pamauth.conf file contains the KEYFILE parameter set to a value of /tmp/seckey.conf:
    KEYFILE=/tmp/seckey.conf
    For example, you can set the KEY parameter with a value of myKey12345@#$%^*ABC, defined within the KEYFILE value: 
    KEY="myKey12345@#$%^*ABC"
  3. On all management hosts, edit ego.conf to modify the value of the EGO_SEC_PLUGIN and EGO_SEC_CONF parameters as follows:
    Table 2. Management host configuration parameters
    Parameter Value Description
    EGO_SEC_PLUGIN sec_ego_pam_default Specifies PAM+default authentication on management hosts.
    EGO_SEC_CONF $EGO_CONFDIR,0,INFO,$EGO_TOP/kernel/log Specifies if log messages are required from the server-side plug-in. All server-side messages are logged to ego_ext_plugin_server.log in the plug-in log-directory.

    Use this format: <plugin-configurationdirectory, created-ttl, plugin-log-level, pluginlog-directory>
  4. On all compute hosts, edit ego.conf to modify the value of the EGO_SEC_PLUGIN and (optionally) the EGO_SEC_CONF parameter:
    Table 3. Compute host configuration parameters
    Parameter Value Description
    EGO_SEC_PLUGIN sec_ego_pam_default Specifies PAM+default authentication.
    EGO_SEC_CONF (optional) $EGO_TOP/kernel/conf,0,DEBUG,$EGO_TOP/kernel/log Specifies whether log messages are required from the client-side plug-in. All client-side messages are logged to ego_ext_plugin_client.log in the plug-in log-directory.

    Use this format: <plugin-configurationdirectory, created-ttl, plugin-log-level, pluginlog-directory>
  5. Start the IBM® Spectrum Conductor cluster:
    1. Log on to the primary host as the cluster administrator.
    2. Run the following commands to start the cluster:
      • For bash: 
        # . $EGO_TOP/profile.platform
# egosh ego start all
      • For csh:
        # source $EGO_TOP/cshrc.platform
# egosh ego start all
  6. Complete this step only if the authentication server is required to authenticate a PAM client by using the default authentication method or the PAM authentication method.

    Log on to EGO as the cluster administrator called Admin, then run the egosh user add command to map the PAM user to the EGO account.

  7. From the cluster management console, edit the instance group configuration to enable the Spark drivers and executors to run as the OS user.
    1. From the cluster management console, click Workload > Instance Groups.
    2. Select the instance group to modify and click Configure.
      If the instance group is running workload, stop the instance group and all associated notebooks before you change its configuration.
    3. In the Basic Settings tab, select Enable authentication and authorization for the submission user.
    4. Click Modify Instance Group.