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:
- Configuring the Engine Host machine(s)
- Configuring the Client
- Miscellaneous
- 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 theesd.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.
- 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:
Thepam_unix.so.1
module is no longer supported under Solaris 10. See ORACLE document: System Administration Guide: Security Services Chapter 17 Using PAM: Thepam_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.
- 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.)
Theset_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
- 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 thepid+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 theccm_start_daemons
command.
In CMSynergy 6.3, theccm_stop_daemons
will stop all ESD daemons registered with the router service.
For more information regarding theccm_esd
command, refer to pages 77 and 84 of the Administration Guide
CM Synergy Administration Guide for UNIX - 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 theesd.adr
. For example if you enter the IP address as the engine host, this must be an alias in theesd.adr
.
Check also your$CCM_HOME/log/ccm_esd_<engine_host>.log
.
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.
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 preferences3. Miscellaneous
Historical Number
KB5986;TB235
Was this topic helpful?
Document Information
Modified date:
22 December 2020
UID
swg21325284