IBM Support

Configuring ESD in Rational Synergy

Troubleshooting


Problem

How to confugure the Engine Startup Daemon(ESD) in IBM Rational Synergy.

Cause

The Engine Startup Daemon(ESD) was initially introduced with CMSynergy 6.2 Service Pack 1 to allow users to use Pluggable Authentication Modules (PAM) authentication rather than be constrained to the use of the Berkeley r* commands. This document is valid for the following versions: CMSynergy 6.2 Service Pack 1 up to and including release 7.1. Release 7.2 uses Web Mode clients exclusively so the ESD daemon is no longer required.

Environment

ESD is only relevant where you have a UNIX/Linux server.

You will have to configure any Windows clients which need to connect to these servers.

Diagnosing The Problem

By default Rational Synergy clients use the The Berkeley r* commands to start and run client sessions. These commands are considered insecure in some environments and are not available by default on some operating systems. In environments where firewalls are configured you will not be able to use the Berkeley r* commands.

Resolving The Problem

To configure Rational Synergy to use EDS you have to look at the following:

    1. Configuring the Engine Host machine(s)
    2. Configuring the Client
    3. Miscellaneous

    1. Configure the Engine Host machine(s)
    The ESD daemon needs to run on each machine you will run an engine on. This requires setting up the esd.adr and configuring PAM.


    1. Configure the engine hosts for ESD:
      Configure the engine hosts for ESD in the $CCM_HOME/etc/esd.adr file.

      Format: hostname:port alias1 alias 2 alias3 ...

      Where you can have multiple lines for multiple engine hosts. For example to allow engines to run on 'lucy' and 'martha', with users accessing these machines via shortname, fully qualified domain name or ip address, enter the following in the esd.adr:
      lucy:8830 lucy.example.com 123.123.123.1
      martha:8830 martha.example.com 123.123.123.2


      Then start the ESD daemon on lucy and martha by running the command 'ccm_esd' as user ccm_root on lucy and martha.


    2. Configure Pluggable Authentication Modules (PAM)
      On Solaris, HP-UX, and Linux systems, ESD uses PAM to authenticate users. The PAM service name is "]cmsynergy[". To enable the ESD to authenticate users, the PAM configuration must be updated to specify the authentication methods to use for the "cmsynergy" service, unless a reasonable default already exists.

      • Solaris 9 and earlier:
        Sample additions to Solaris
        /etc/pam.conf file:
        cmsynergy auth required /usr/lib/security/$ISA/pam_unix.so.1
        cmsynergy account required /usr/lib/security/$ISA/pam_unix.so.1

      • Solaris 10:
        The pam_unix.so.1 module is no longer supported under Solaris 10. See ORACLE document: System Administration Guide: Security Services Chapter 17 Using PAM: The pam_unix module has been removed and replaced by a set of service modules of equivalent or greater functionality. So, the followingpam.conf settings should be used:

        cmsynergy        auth     requisite        pam_authtok_get.so.1
        cmsynergy        auth     required         pam_dhkeys.so.1
        cmsynergy        auth     required         pam_unix_cred.so.1
        cmsynergy        auth     required         pam_unix_auth.so.1
        cmsynergy        account required         pam_unix_account.so.1

         
      • HP-UX:Sample additions to /etc/pam.conf file:
        cmsynergy auth required /usr/lib/security/libpam_unix.1
        cmsynergy account required /usr/lib/security/libpam_unix.1

      • Linux:Sample additions to /etc/pam.d/cmsynergy file:
        auth required /lib/security/pam_stack.so service=system-auth
        auth required /lib/security/pam_nologin.so
        account required /lib/security/pam_stack.so service=system-auth

      • AIX:
        AIX uses its own configuration scheme instead of using PAM. AIX authentication is through its base operating system. For additional information about how to configure PAM, refer to the documentation for your system or contact your system administrator.


          
      • Note that IBM Rational can not guarantee these settings will work for all customer environments. IBM Rational's official recommendation is that if you wish to setup ESD to utilize OS authentication you should copy the lines from the "login" or "rlogin" section of the PAM configuration for their system to create the lines for the new "cmsynergy" section.


         
    2. Setting up the ESD Client
    You must configure the client to connect to ESD rather than using the normal engine startup procedure. This is done by editing the ccm.ini file to specify how the engine is started. You must add the following line to the [Options] section of the ccm.ini file:
    engine_daemon = TRUE

    You can change either the $CCM_HOME/etc/ccm.ini file, or your personal ccm.ini file, which takes precedence. For further information on the ccm.ini file see Technote 1325190: How to customize Rational Synergy Classic client preferences


    3. Miscellaneous

    1. The .netrc/.ccmrc file.

      ESD requires a .netrc[</code>] file for 'nogui' sessions and if you do not wish to manually enter your password at startup. This file is required for local and remote sessions. In CMSynergy 6.2, the user must create this file manually and set the permissions to 600. The format of this file is:
      machine <ipaddress> login <login name> password <password>

      CMSynergy 6.3 has a wrapper command to assist with the creation of the .ccmrc file (The .ccmrc file is equivalent to the .netrc file.)

      The set_password command enables you to set the password required for starting engines when using ESD. This command creates the password in the .ccmrc file in the user's home directory. The password can be set for all hosts or for a specific host. The default password for all hosts is used if you have not specified a password for a specific host. After the password is set, the user is no longer prompted for a password.

      For Example: Set the password for the host named matisse
      % ccm set_password matisse

    2. Stopping ESD

      In CMSynergy 6.2SP1 without patch 6.2-032 installed, attempting to stop the engine startup daemon by using the command % kill pid will be unsuccessful, even when the correct process id is used. In most cases, using the pid+1 will stop the engine.
      For example, if the process id is 7288, use the command % kill 7289 to stop the ESD.

      Patch 6.2-032 correctly registers the ESD process so the kill command will work correctly when the correct process id is used. However, the process is still not stopped or started by the ccm_start_daemons command.

      In CMSynergy 6.3, the ccm_stop_daemons will stop all ESD daemons registered with the router service.

      For more information regarding the ccm_esd command, refer to pages 77 and 84 of the Administration Guide
      CM Synergy Administration Guide for UNIX

    3. Troubleshooting


      The most common error seen is:
      Warning: UISSYS engine daemon not registered with router at host <client name>

      Check the 'Engine host' entered in the Startup Dialog. An ESD daemon must be running on this host. If the engine host is not the shortname, make sure it is entered as an alias in the esd.adr. For example if you enter the IP address as the engine host, this must be an alias in the esd.adr.

      Check also your $CCM_HOME/log/ccm_esd_<engine_host>.log.

[{"Product":{"code":"SSC6Q5","label":"Rational Synergy"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"General Information","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"}],"Version":"6.3;6.4;6.5;6.5a;6.6a;7.0;7.1;7.1a","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Historical Number

KB5986;TB235

Document Information

Modified date:
22 December 2020

UID

swg21325284