This document contains information about the ElectricAccelerator integration with Kerberos. Topics include: Overview 2.

Transcription

1 Electric Cloud ElectricAccelerator version 6.2 Technical Notes Kerberos Integration December 2012 This document contains information about the ElectricAccelerator integration with Kerberos. Topics include: Overview 2 Prerequisites 2 Using the emake Client 2 Using the Agent 3 Addressing Error and Warning Messages 4 Troubleshooting and Getting Help 7 1

2 Overview Overview You can configure ElectricAccelerator to use the Kerberos security protocol to authenticate initial connections from emake client programs to agent services. To assist with auditing, you can also configure agents to log these authentication events and the build steps that were run. In authenticated mode, UNIX/Linux build steps run as the authenticated user only. For example, if an emake client authenticates with Kerberos principal then build steps run as user even if the emake client runs as a different user on its machine. In order for emake to authenticate itself under UNIX/Linux, you must first run kinit. Agents require keytab access to the relevant Kerberos host principal. Windows authentication is based on domain users. The emake client must be run by a domain user, and you must configure agents to run as domain users. Windows agents do not impersonate emake client users but will log authentication events and build steps if desired. In order to highlight security gaps caused by misconfiguration, you must either enable authentication throughout the cluster, or prohibit it throughout the cluster. Agents and the emake client will refuse to fall back to unauthenticated mode, because doing so hides gaps in security. Instead, mismatches between emake client and agent security configurations will fail builds until corrected. When you configure an agent to require authentication, you authorize a specific Kerberos domain to use that agent. Principals in other Kerberos domains remain unauthorized. Note: Kerberos integration supports x86 and SPARC Solaris 10 (Update 9 is required). Prerequisites Kerberos implementation of GSSAPI For Linux systems, you must install a Kerberos implementation of GSSAPI on the agent and emake client machines. The package names may start with krb5-libs on Red Hat systems, or krb5-user on Ubuntu systems. For 64-bit emake systems, Electric Cloud recommends installing both 32-bit and 64-bit variants, so that both 32- bit and 64-bit emake can use the library. On Linux, ElectricAccelerator supports the MIT Kerberos 5 implementation of GSSAPI. Other implementations of GSSAPI are not supported/tested by Electric Cloud. Using the emake Client Logging in On Windows systems, you must log in with a domain account. For UNIX/Linux systems, you must run kinit to log in to your Kerberos domain. Enabling authentication Authentication is both enabled and required by this command line option: --emake-agent-security=auth Alternatively, you can add that command line option to $EMAKEFLAGS or set EMAKE_AGENT_SECURITY=auth in your environment. For security debug logging, use --emake-debug=y 2

3 Using the Agent Using the Agent erunner service Do not install the erunner service; it is not secure. Without the erunner service, single point cluster upgrades are not supported. Agent users On Windows systems, agent users must be domain accounts named ECloudInternalUser1, ECloudInternalUser2,... You must explicitly override the default choice, which is to use local accounts with those names. Enabling authentication and security tracing Enable authentication and security tracing by running: On UNIX/Linux: On Windows: ecconfig -emakesecurity "auth DOMAIN.COM" -trace security ecconfig -args "-emakesecurity \"auth DOMAIN.COM\" -trace security" Replace DOMAIN.COM with the uppercase Kerberos domain that is authorized to use the agent. For verbose security details, replace -trace security with -trace securitydetails. Restart the agents after making this change. Note: As a side effect of enabling authentication, the agent console port will be disabled. Rerun ecconfig after upgrading After upgrading ElectricAccelerator, you must rerun the ecconfig command to re-enable Kerberos authentication and security tracing. Restart agents after running ecconfig. Kerberos host principals that include fully qualified domain names On UNIX/Linux, if the Kerberos host principal for an agent host includes the host s fully qualified domain name (instead of its host name only), then add the corresponding text (depending on your ElectricAccelerator version) to <installdir>/<arch>/bin/runagent.local on that agent host: For ElectricAccelerator 6.0.x or 5.5, add set ::args(-myhost) [info hostname]-[expr {$args(-efsid) + 1}] For ElectricAccelerator 6.1 or later, add set args(-myhost) [hostname -fqdn] If the runagent.local file does not yet exist, then create it. Whether or not the file previously existed, restart the agents after making this change. MIT Kerberos 5 keytab location On Linux systems, if you want the agents to use an MIT Kerberos 5 keytab that is not in the default location, then use ecconfig to instruct the agent where to find it; for example: ecconfig -keytab /etc/ecagent.keytab Restart the agents after making this change. 3

4 Addressing Error and Warning Messages Customizing the agent and/or host names the agent reports to the Cluster Manager You want to change the agent name, host name, or both names that the agent reports to the Cluster Manager. Changing the host name By default, the host name reported to the Cluster Manager is the name of the host on which the agent runs, without any domain name qualification. Adding: set args(-myhost) somehostname to runagent.local overrides the default name, where "somehostname" is a host name of your choice, and may be qualified if desired. If you need to send the fully qualified form of the hostname: set args(-myhost) [hostname -fqdn] Changing the agent name By default, the agent name reported to the Cluster Manager is the same as the host name that is reported to the Cluster Manager (as specified by -myhost, above, or defaulted), but followed by a minus sign and the agent number. The agent name uniquely identifies the agent process, as opposed to the agent host machine. Generally, you would need to change the agent name only if the default is not suitable, which may be the case if -myhost was set to an unusual value. Adding: set args(-myname) somehostname-$::gagentnumber to runagent.local overrides the default, where "somehostname" is a host name of your choice. Electric Cloud recommends ending the agent name with a minus sign followed by the agent number. The code in runagent.local can access the agent number through the Tcl global variable named ::gagentnumber. Addressing Error and Warning Messages This section details error and warning messages associated with Kerberos usage in ElectricAccelerator. EC1171: [agent]: [agentprincipal]: Security Error:... Emake failed in its preparations to authenticate itself to the agent, or the agent failed mutual authentication. (This error is detected on the emake side.) There are any number of reasons that this sort of failure might occur. The most common example is that, under UNIX/Linux, the user may have neglected to run Kerberos kinit. Check the error text for clues as to which stage of authentication failed. On UNIX/Linux, the portion of the message after the GSSAPI Minor Status code but before the text \naborting build. was generated by the GSSAPI library. Similarly, on Windows, the portion of the message after the SSPI Error code but before the \naborting build. was generated by the Windows SSPI library. EC1172: Unknown security mode for agent communications: "[option]" The argument to --emake-agent-security= is invalid. Check the text of the error message for a list of available modes, and choose one. 4

5 Addressing Error and Warning Messages EC1173:... Emake failed to initialize needed security facilities. Check the text of the error message to determine what failed. Check for the following messages in particular: Failed to load GSSAPI message In this case, there was a problem loading the UNIX/Linux GSSAPI shared object library provided by Kerberos. On Linux systems, first verify that Kerberos is installed. See "Prerequisites" on page 2 for suggested package name prefixes. On 64-bit systems, verify that 64-bit and 32-bit GSSAPI shared object libraries are installed. On UNIX/Linux, if Kerberos has been installed, then add the directory containing its GSSAPI shared object library to the LD_LIBRARY_PATH environment variable. Alternatively, if you do not wish to modify LD_LIBRARY_PATH, or such modification does not solve the problem, then instead set the ECLOUD_GSSAPI_LIBRARY environment variable to the filename of the Kerberos GSSAPI shared object library that is to be used. Use only the filename; if that does not work, use an absolute path. (See man dlopen for more details concerning library search.) You can even set ECLOUD_GSSAPI_LIBRARY to a space-separated list of candidate shared object library names. Emake ignores ECLOUD_GSSAPI_LIBRARY on Windows. WARNING: Unable to start session: Failed to load GSSAPI:... On UNIX/Linux systems, if you see this message in an agent log, then you may need to instruct ecagent where to find a Kerberos implementation of GSSAPI. The underlying issue is the same as for the emake client EC1173: Failed to load GSSAPI message. The response, however, is slightly different in the agent context. Linux Kerberos installation is the same as for "EC1173:..." on page 5 above. If Kerberos is installed and the agent still cannot find GSSAPI, then specify the filename of the GSSAPI shared object library with: ecconfig -gssapi "libgssapi-a.so /some/directory/libgssapi-b.so" The argument to -gssapi has the same form and meaning as does the value of ECLOUD_GSSAPI_LIBRARY; see "EC1173:..." on page 5 above. Restart the agents after making this change. EC2128: agent reports: [Security Error: authentication rejected]; aborting build The agent has rejected an attempt by the emake client to authenticate itself. Various causes are possible. Check the agent logs for details for security reasons, the agent intentionally withholds those details from the emake client. Security Error: gss_accept_sec_context: GSSAPI Minor Status 0x2: No such file or directory In particular, if on Linux you see this error message in the agent log, then you may need to install a keytab or instruct the agent where to find it; see "MIT Kerberos 5 keytab location" on page 3 for details. On UNIX/Linux, if the agent log message mentions a GSSAPI Minor Status code, then the rest of the message was generated by the GSSAPI library. Similarly, on Windows, if the agent log message mentions an SSPI Error code, then the rest of the message was generated by the Windows SSPI library. EC2129: agent reports: [Security Error: authentication required]; aborting build The agent requires authentication for this emake client connection. Enable authentication on the emake client. 5

6 Addressing Error and Warning Messages EC2130: agent reports: [Security Error: authentication not offered]; aborting build An agent does not offer authentication for emake client connections. Enable authentication on all agents. EC2132: (from [agent]) Security Warning: unavailable user XXX; instead setting user AAA and groups BBB,CCC The UNIX/Linux user ID available to the emake client is not allowed for the authenticated user on an agent machine involved in the build. First, check that the principal used in authentication (typically the argument to kinit) matches the UNIX/Linux user account that is running emake. If it does not match, then rerun kinit (or similar) with a principal that does match the UNIX/Linux user account (or switch to a different UNIX/Linux user account and rerun kinit). If the principal and user match, then log in as that user on both the emake client machine and the agent machine, run id in both accounts, and compare the results to see if they match. If they do not match, then change the user ID on one of the machines to match the other and reconcile the groups as well in order to avoid EC2133 and EC2134. Be sure that all agent machines match each other, too, or you will get the same error with a different agent machine. You can also check to see if there is some type of setuid/sudo wrapper around emake. EC2133 Security Warning: unavailable primary group YYY; instead setting user AAA and groups BBB,CCC This is similar to EC2132, except that in this case the user ID matches, but the primary group ID requested by emake is not available to that user on an agent machine. Either grant membership in the group on all agent machines, or change to a different primary group on the emake client. In the latter case, if you keep the original primary group in the supplementary group list, then you may encounter EC2134. EC2134 Security Warning: unavailable supplementary groups YYY,ZZZ; instead setting user AAA and groups BBB,CCC This is similar to EC2132, except that in this case the user ID matches, and the primary group ID requested by emake is available to that user, but one or more supplementary group IDs requested by emake is not available to that user on an agent machine. See also EC2133, which is for an unavailable primary group ID. Either grant membership in the group on all agent machines, or deny membership on the emake client. "Unknown code krb5..." appearing in security error messages This type of message appears to result from a bug in the 64-bit MIT Kerberos 5 implementation of GSSAPI, not from any flaw in Electric Cloud products. (The bug appears to be that an unsigned 32-bit GSSAPI minor status is zero-padded to create a 64-bit MIT Kerberos 5 error code, instead of being sign-extended as MIT Kerberos 5 expects, and therefore certain codes are not found in the error string table, thus leading to generic error strings.) To work around this bug, either run in 32-bit mode or look up the MIT Kerberos 5 error numbers on the web. In the latter case, you may find it easiest to use the full code just after GSSAPI Minor Status. Also refer to the following Red Hat bug report about this issue: 6

7 Troubleshooting and Getting Help Troubleshooting and Getting Help Contacting Technical Support: Before you contact our technical support staff, please have the following information available. Your name, title, company name, phone number, fax number, and address Operating system and version number Product name and release version Problem description Hours: 8AM - 5PM PST (Monday-Friday, except Holidays) Phone: , Option #2 support@electric-cloud.com Copyright Electric Cloud, Inc. All rights reserved. Electric Cloud believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. ELECTRIC CLOUD, INC. MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any Electric Cloud software described in this publication requires an applicable software license. Trademarks Electric Cloud, ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are registered trademarks or trademarks of Electric Cloud, Incorporated. Electric Cloud products ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are commonly referred to by their short names Accelerator, Commander, Insight, and emake throughout various types of Electric Cloud product-specific documentation. All other trademarks used herein are the property of their respective owners. 7