This is documentation for MapR Version 5.0. You can also refer to MapR documentation for the latest release.

Skip to end of metadata
Go to start of metadata

Logging into a Cluster with maprlogin

The /opt/mapr/bin/maprlogin command line tool enables users to log into a secure MapR cluster. Users authenticate themselves to the cluster with a maprticket that can be generated in the following ways:

  • Run maprlogin password to authenticate with username and password.
  • Run maprlogin generateticket to request a service ticket for use by an external application or user account (based on the current user's ticket).
  • Run maprlogin kerberos after generating a Kerberos ticket with the kinit command.

For more details about different ways to generate tickets, see Tickets and Certificates.

Command Syntax

Argument or Option

Description

Default

password

The user's UNIX password

N/A

kerberos

Indicates the presence of a Kerberos ticket

N/A

generateticketGenerates a service ticket for another user or application. The user who runs the maprlogin command with this option must already have a user ticket and must have fc (full control) ACL authorization on the cluster. (See acl set.)N/A
-type

Required ticket type for the generateticket command; must be service or crosscluster:

  • service is used to generate service tickets for regular cluster operations.
  • crosscluster is used to generate tickets for inter-cluster operations, such as remote mirroring. The crosscluster option only works with the mapr user.
No default; -type must be set in the maprlogin generateticket command.

print

Prints user ticket information

N/A

authtest

Simulates runtime behavior during authentication

N/A

renew

Renews the ticket, given a duration that does not cause the ticket to exceed its maximum lifetime. The original -renewal value for the ticket determines its maximum lifetime.

N/A

-cluster

Name of the cluster to log into

First cluster name in the /opt/mapr/conf/mapr-clusters.conf file

-user

UNIX user name on the MapR cluster.

For crosscluster tickets, the user must be mapr.

root

-out

A safe directory location where the ticket will be stored.

You must specify a location when generating service tickets. (This requirement ensures that other tickets are not overwritten.)

/tmp/maprticket_<uid>

(default applies to non-service tickets only)

-duration

Length of time before the ticket expires, specified in one of the following formats:

-duration [Days:]Hours:Minutes

-duration Seconds

Password-generated tickets are bounded by the CLDB duration and renewal properties that are set for the cluster:

  • cldb.security.user.ticket.duration.seconds (default=1209600)
  • cldb.security.user.ticket.renew.duration.seconds (default=2592000)

See config.

However, service tickets may have a very long lifetime; their duration is not bounded by these properties.

If -duration is not set in the maprlogin command, the CLDB duration property is set by default.

1209600 seconds (14 days)

-renewal

Total lifetime of the ticket, specified in one of the following formats:

-renewal [Days:]Hours:Minutes 

-renewal Seconds

If -renewal is not set in the maprlogin command, the CLDB renewal property is set by default (cldb.security.user.ticket.renew.duration.seconds).

For example, assume that the maprlogin command passes the following options for a service ticket:

-duration 30:0:0 -renewal 90:0:0

The ticket will expire after 30 days unless it is renewed. If a maprlogin renew command is submitted for the ticket before the initial 30 days pass, the ticket's lifetime may be extended up to a total maximum lifetime of 90 days. Tickets do not renew automatically; administrators must renew them with the maprlogin renew command, specifying a valid renewal period, and they must do this before the duration period ends. The renewal period must be less than or equal to the remaining amount of time allowed on the ticket.

Using the same example, if you renew a ticket on the 29th day of its life, you can renew it for up to 61 days. You can renew a ticket incrementally, for some number of days at a time, as long as you do not exceed the original renewal value.

2592000 seconds (30 days)

 

Displaying User Ticket Information

To display the contents of all user tickets, run maprlogin print. Sample output is shown below. Note that the uid (user id) has been converted to a 10-digit number.

Running an Authentication Test

  • authtest: This troubleshooting option simulates the behavior of the runtime during authentication, going through the authentication flow. Options:
    [ -cluster ] Specifies the name of the cluster.

Ending a Session Before the Ticket Expires

  • end or logout: Destroys tickets and logs out. Options:
    [ -cluster ] Specifies the name of the cluster. By default, deletes all tickets for all clusters.

Renewing a Ticket Before it Expires

  • renew: Renews an existing ticket for a specified time period. Options:
    [ -cluster ] Specifies the name of the cluster.
    [ -duration ] Specifies the ticket duration.

The duration you specify must be valid for the ticket in question, given the original -renewal value for the ticket and the life of the ticket when the renew command is run:

  • You cannot renew a ticket that has already expired.
  • You can renew the same ticket multiple times.
  • The renewal period (or periods) cannot exceed the available time left for the ticket. 

For example, assume that a ticket is created with a duration of 10 days and a renewal of 30 days:

  • On the 11th day, the ticket expires and cannot be renewed at all.
  • On the 9th day, you can renew the ticket for any number of days up to a maximum of 21. 
  • On the 23rd day, you can renew the ticket for any number of days up to a maximum of 7.

When a User Tries to Access a Cluster without a Ticket

Any user who wants to access a secure cluster must have a MapR user ticket. If a user tries to log in without a ticket, an error message appears similar to these:

Troubleshooting maprlogin Failures

While the root causes of most failure cases with maprlogin can be quickly diagnosed, the following cases can prove challenging:

  • When security is enabled for a cluster, the cluster's CLDB listens for connections on port 7443. If security for the cluster is disabled, the maprlogin utility is unable to reach the CLDB.
  • The utility's connection uses HTTPS, which requires the file conf/ssl_truststore to exist on the client. If the file is not present, a secure connection cannot be negotiated.

Detailed error logs for maprlogin connection attempts are kept at logs/maprlogin-<USERID>-nnnn.log.

MapR Tickets and the PAM Authenticator

The MapR distribution for Hadoop supports Pluggable Authentication Modules (PAM) in the UNIX authentication stack. MapR provides a PAM Authenticator module that generates MapR tickets in conjunction with the maprlogin utility. After you install the MapR distribution for Hadoop, the PAM Authenticator module is located at $INSTALL_DIR/lib/libmapr_pam.so. Configuration files for PAM are located in the /etc/pam.d directory, and each UNIX operation, such as sulogin, or ssh, has a specific PAM configuration file in that directory.

Configuring the PAM Authenticator on Ubuntu or SUSE

To configure the MapR PAM Authenticator, apend the following line to the end of the /etc/pam.d/common-auth file:

auth     optional     /opt/mapr/lib/libmapr_pam.so    # MapR PAM module

Icon

An absolute path to the location of the libmapr_pam.so file is required. By default, this location is $MAPR_HOME/lib/libmapr_pam.so.

Configuring the PAM Authenticator on Red Hat or CentOS

  1. Insert the following line in the /etc/pam.d/system-auth file immediately before the first module that uses the auth     sufficient configuration:
    auth     optional     libmapr_pam.so    # MapR PAM module
  2. Append the string try_first_pass to the end of the module that uses auth     sufficient, as in this example:

Before modification:

auth     required     pam_env.so
auth     sufficient   pam_unix.so nullok
auth     requisite    pam_succeed_if.so uid >= 500 quiet
auth     required     pam_deny.so

After modification, changes in bold:

auth     required     pam_env.so
auth     optional     libmapr_pam.so     # MapR PAM module
auth     sufficient   pam_unix.so nullok try_first_pass
auth     requisite    pam_succeed_if.so uid >= 500 quiet
auth     required     pam_deny.so

Configuring Debugging for PAM

To enable debugging for the client traffic used by the maprlogin utility, update the /opt/mapr/conf/log4j.properties file with the following line:

log4j.logger.com.mapr.login=DEBUG

After updating the log4j.properties file, trace the com.mapr.login package at the DEBUG level.

Be sure to update the correct instance of the log4j.properties file. Traffic specific to MapR, such as maprlogin and MapR Control System (MCS) traffic, uses the instance in the /opt/mapr/conf directory. Traffic used by the JobTracker, TaskTracker, and the hadoop command use the instance in the /opt/mapr/hadoop/hadoop-<version>/conf directory.

To perform the same tracing activity on the server side, modify the appropriate instance of the log4j.properties file on the server, or specify the page com.mapr.login in the MCS UI's tracing/logger settings. To trace PAM activity from the server, add the following line to the server's log4j.properties instance:

log4j.logger.net.sf.jpam=DEBUG

After modifying this setting, the server log will contain a message similar to the following:

2013-07-23 16:05:25,200 DEBUG Pam [1068409264@qtp-874242484-3]: Debug mode active.

Detailed information about PAM activity is written to the /opt/mapr/logs/pam.log file.

Other Packages

The following packages are not directly related to PAM, but can provide useful insights for subtler errors.

  • org.apache.hadoop.security - This package contains Apache security code, including MapR enhancements. Tracing this package can provide information about what login configuration is in use.
  • com.mapr.fs.cldb.http.login - This package contains code that the CLDB uses to validate maprlogin calls.

Common Issues  

The Linux Documentation Project's HOWTO on LDAP Implementation has a section on PAM and NSS that may prove helpful. 

If a user's credentials appear valid, for example in a case where the su and ssh commands work normally, but PAM does not correctly authenticate, the issue may relate specifically to MapR's use of PAM as a normal user, compared to the usual case where PAM consumers run as the root user, causing permissions issues. The two most common issues relating to this condition are:

  • The /etc/shadow directory is not readable to the mapr user. This directory is made readable to the mapr user during install, but some secure environments and configuration management tools undo these changes.

  • A Kerberos PAM module is attempting to create and change the ownership of a kerberos ticket file. This attempt fails, since these changes require root privileges. Different Kerberos PAM modules can report errors differently, leading to difficulty tracking down root causes of errors. To address permissions problems with Kerberos PAM modules, configure the Kerberos PAM module to skip creating a ticket file, using the KDC only to validate the password. PAM configuration information is located in the /etc/pam.d directory. MapR can use a custom PAM configuration specified in the web.conf file. 

  • No labels