Creating a consumer

Begin to build your tree by first creating consumers.

1. From the cluster management console, select Resources > Consumers.

   A list of existing first-level consumers in your tree displays.

2. Locate and click on the tree level for which you would like to add a consumer.
3. From Global Actions, select Create a Consumer.

   The Create a Consumer page displays.

   You can create a consumer at any level of your existing tree, except where a consumer already has something registered to it; in this case, no other sub-consumers can be created.

4. Fill in the consumer properties.

   Some of these properties may be already filled out or disabled depending on which tree level to which you are adding a consumer.

   1. Specify a name for your new consumer. The consumer name must adhere to the following naming rules:
      • The consumer name must be unique, and can be the name of a department or project in your structure.
      • The consumer name must start with a letter.
      • The consumer name can only contain the following characters: 0 to 9, lowercase letters, uppercase letters, hyphens (-), or underscores (_). It cannot contain these characters: \ / : * ? \ " < > | '
      • The consumer name can be a maximum of 128 characters.
   2. In the section Specify users for this consumer, select a user.

      User View permission is required to see the list of user accounts that are relative to this consumer.

      Specified administrators automatically become administrators for any other consumers created on this branch.

   3. In the Roles column, select a role for this user. Role View permission is required to see the list of roles.

      Depending on the permissions that are associated with the roles, a user may modify any property, assign resources, and control hosts.

   4. Specify the allowed execution user list for the consumer. This is a comma-separated list of OS or LDAP users or groups that are allowed to be execution users. Keep either Any user can be the OS execution user selected, or deselect this option and specify the allowed users or user groups.

      For example: User list: userA, userB, userC

      Group list: groupA, groupB, groupC

      Note:

      • When you create a first-level consumer, Any user can be the OS execution user is automatically selected. In this case, any user can be the OS user account for this consumer.
      • When you create a child consumer, the values are copied automatically from the parent consumer and either the cluster or consumer administrator can edit a subset of the list.

        The allowed execution user list of the child consumer must either be a subset of the parent consumer's allowed execution user list or the allowed execution group list. The allowed execution group list of the child consumer must be a subset of the parent consumer's allowed execution group list.

        For users and groups configured in the allowed execution user list or execution group list, the PAM, Active Directory (AD), and default security plug-ins validate if the specified users and groups exist when creating and modifying consumers or starting EGO activities. For the default plug-in, you must enable validation by configuring the ENABLE_BI_AUTH parameter (supported only on Linux) in the $EGO_CONFDIR/ego.conf configuration file. For example:

        EGO_SEC_PLUGIN=sec_ego_default 
        EGO_SEC_CONF=/opt/ego/kernel/conf,time-to-live_duration,ENABLE_BI_AUTH

        Note that you can optionally specify a time-to-live duration, in minutes, to be used for the authentication token sent from client to server. If not specified, the system uses the default time-to-live duration of 600 minutes, which is 10 hours. To use the default time-to-live duration, do not provide a value, but keep the commas (and no extra spaces), to separate the configuration options, as such:

        EGO_SEC_PLUGIN=sec_ego_default 
        EGO_SEC_CONF=/opt/ego/kernel/conf,,ENABLE_BI_AUTH

      • The cluster or consumer administrator is also able to edit the allowed execution user list after the consumer has been created.
   5. Specify the workload execution user account (the OS account under which workload runs). All workload for the consumer runs under the same account, no matter which user submitted workload units.
      On Linux® hosts, the $SOAM_HOME/deploy directory's group access permissions is set to 7 (rwx). All execution (OS) users of consumers must belong to the deploy directory owner group. The deploy directory is created and owned by the cluster administrator OS user account (by default, egoadmin). Additionally, ensure that you include all consumer OS user accounts under the same group as the cluster administrator OS user account; otherwise, you may encounter issues with writable permissions to SOAM work directories, such as these:

      • $SOAM_HOME/datamanager
      • $SOAM_HOME/history
      • $SOAM_HOME/jouraling
      • $SOAM_HOME/paging

      Note: As of IBM® Spectrum Symphony 7.2.1, you can allow SSM to use the same cluster administrator permissions that SD uses by setting a cluster-wide environment variable (SD_SSM_RUN_AS_CLUSTER_ADMIN) to TRUE in the service definition file (sd.xml). This way, SSM processes run as the cluster administrator, rather than as the execution user. For details about SD_SSM_RUN_AS_CLUSTER_ADMIN, see Session director environment variables.

      If the consumer runs workload units on a Windows host, include the domain name as shown: domain_name\user_name. If the consumer runs workload units on a Linux host, EGO can automatically strip the domain name from the user name. For example, if you configure the account as mydomain\user2, it is interpreted as mydomain\user2 on Windows but as user2 on Linux.

      If you specify a Windows user account that has not already been configured, you have to log on to EGO as the cluster administrator and then run egosh ego execpasswd before the execution user can run an activity without exiting. The egoadmin account is already configured.

      Any activity started through egosh uses the same execution account as configured for the leaf consumer it runs on. The file ConsumerTrees.xml contains execution user account information for each registered consumer.

      Note: Once an execution user account has been configured for a consumer, it cannot be changed. If the user account is not correct, you must delete the consumer and create a new one. Before deleting a consumer, unregister all applications associated with it.

      Note: To retrieve session and task history from the command line and the cluster management console, ensure the user account running the session director (cluster administrator), and the user account running the session manager for the application (OS execution account assigned to the consumer) have access to the directory configured to store historical files for sessions and tasks.
   6. Specify one or more resource groups (a collection of hosts) that this consumer must have access to.

      Only the resource groups specified by this consumer's parent are available for selection. You can create resource groups based on similar qualities or by machine names. If you have not modified your resource groups, you can keep the default resource group selections.

   7. Specify a reclaim grace period.

      Reclaim applies to consumers that are borrowing resources. If a client is running workload units on a borrowed resource, you can impose a delay (grace period) so that these units can run uninterrupted before the resource gets returned (reclaimed). To enable your workload to finish before the resource is reclaimed, set the reclaim grace period higher than the length of time to complete your workload. To terminate all running workload and reclaim the resource almost immediately, set the reclaim grace period to 0. When a grace period is not specified or configured, it defaults to 0 seconds.

   8. (Optional) Check the Rebalance when resource plan changes or time interval changes box.

      If you want EGO to rebalance or reset the ownership when a new time interval occurs with a change in ownership of resources, check this box. Similarly, when resources are reclaimed (or passed back to their original owners), you can evoke a re-balancing in accordance with the resource plan.

      Before EGO re-balances according to the resource plan, a consumer’s grace period is honored to help ensure workload is completed before being killed.

5. Click Create.