The MapR POSIX Client is implemented by the mapr-loopbacknfs service included in the MapR distribution. The POSIX client allows app servers, web servers, and other client nodes and apps to read and write data directly and securely to a MapR cluster, with transmitted data compressed in both directions.

Starting with the 4.0.2 release, MapR provides single-user mapr-loopbacknfs licenses that give access to one or more clusters.

The table below summarizes the differences between the basic Linux OS NFS client and the MapR POSIX client:



Linux OS Client

MapR POSIX Client

Client OS

  • Supported Linux distributions and desktop systems (Mac OS X and Windows)

  • Supported Linux distributions only

  • No version for Mac OS X

Installs On Node Type

  • Client node - not part of MapR cluster

  • No mapr-fileserver or other Hadoop services

  • Same

Access to Cluster

  • Only needs network connection to the node running the mapr-nfs service

  • Same

Supported Interfaces

  • Apache HDFS and MapR-FS


Connection to File System

  • Point to point

  • Via an NFS gateway

  • Single point of failure

  • Proxied on host to regular MapR client traffic

  • Direct, no NFS gateway

  • No single point of failure


  • Link to NFS gateway is insecure

  • Fully secured

The Linux OS NFS client must go through an NFS gateway, the link to the gateway is not secured, and transmitted data is not compressed.

The following diagram illustrates how the MapR POSIX client (mapr-loopbacknfs) works, in comparison with the Linux OS NFS client (left).

The instructions on this page are for the MapR POSIX client. For instructions on setting up NFS on a MapR cluster, see Setting Up MapR NFS.

The table below summarizes the differences in the MapR POSIX client deployment behavior when installed with a MapR cluster where security is disabled or enabled:



Cluster Security Disabled

Cluster Security Enabled

Client Node

  • MapR cluster looks exactly like network attached storage (NAS) 

  • POSIX permissions are enforced

  • Single-user authentication

  • Write access is supported only for applications with uid matching authenticated user

Cluster Node

  • MapR cluster looks exactly like NAS

  • POSIX permissions are enforced

  • Secure cluster access is key

  • Best Practice: Use ticket from mapr user


Installing a mapr-loopbacknfs Package on Your Machine

The MapR POSIX client can be installed on any client node, even your laptop, if you have Linux installed. The feature requires a mapr-loopbacknfs license, which is limited to a single user

Perform all steps from your client node, except where noted.

A client node must have a supported Linux OS distribution and must be outside the MapR cluster, not running mapr-fileserver or other Hadoop services. You cannot install the MapR POSIX client on a Windows or Mac OS X machine.

To install mapr-loopbacknfs on your machine, perform the steps below for your version of Linux, as the root user or as sudo. The package is installed to the /usr/local/mapr-loopbacknfs directory.

For CentOS or Red Hat

[root@ip-<ip_address> ~] # yum install mapr-loopbacknfs

For Suse

# zypper install mapr-compat-suse
# zypper install mapr-loopbacknfs

For Ubuntu

# sudo apt-get install mapr-loopbacknfs

Specifying Environment Variables

A subset of the environment variables defined on the servers for the MapR cluster must be defined, with the same values, on the client. You can add environment variables directly to the startup script, or create a local file in /usr/local/mapr-loopbacknfs/conf. You cannot simply copy the file from a server node in the cluster because the MAPR_HOME setting would be different.

  1. On a server node in the MapR cluster, locate the file in the /opt/mapr/conf directory.
  2. Retrieve the MAPR_SUBNETS and JAVA_HOME settings from the server file and clone them to /usr/local/mapr-loopbacknfs/conf/ on the client node.
  3. Change the JAVA_HOME setting to point to the location where Java is installed on the client.
  4. Add these lines to the client node file:

    export MAPR_HOME=/usr/local/mapr-loopbacknfs
    export MAPR_TICKETFILE_LOCATION= /usr/local/mapr-loopbacknfs/initscripts/mapr-loopbacknfs/longlived_ticket
  5. Save and close the file.

Copying Configuration Files from a Server Node

Settings in the nfsserver.conf and mapr-clusters.conf files on server nodes in the MapR cluster are also needed by the POSIX client.

  1. On a server node in the MapR cluster, locate the nfsserver.conf and mapr-clusters.conf files in the /opt/mapr/conf/ directory.

  2. Copy both of those files to the /usr/local/mapr-loopbacknfs/conf/ directory on the client machine.

Starting the mapr-loopbacknfs Service to Access a Cluster

The following instructions explain how to start the mapr-loopbacknfs service so you can access either a secure or a non-secure cluster.

If you need to access multiple clusters, make sure the first cluster that you configure is a MapR 4.0.2 or later cluster, with available POSIX client licenses.

Prerequisites for accessing a secure cluster

  • Enable security for the cluster. See Enabling and Disabling Security Features on Your Cluster.
  • Generate a user ticket. See Generating a MapR User Ticket for instructions. If you do not already have a MapR user ticket, with full control ACL authorization on the cluster, you will have to have a cluster administrator do this for you.
    • Go to a server node in the MapR cluster to which you want to connect.

    • Be sure to run maprlogin password to log in first. The user that logs in must be a privileged user, such as the mapr superuser.

    • Then run maprlogin generateticket -type service -user <user> -duration 365:0:0 -out <file> to generate the user ticket. The <user> for whom the ticket is generated can be any user.

  • Copy the user ticket file from the cluster server node where you generated it to the /usr/local/mapr-loopbacknfs/conf directory on the client machine where the MapR POSIX client will run.

Since the NFS server runs based on a single user's ticket, it can act on behalf of only one user. Therefore, the UID or GID associated with the ticket must match the UID or GID of any user who accesses the NFS server via MapR POSIX Client.

Securing the cluster so that only one user can have secure access provides tight control over cluster access, but it also means that any user on the client who is able to read the generated ticket will have read access to all data in the cluster.

Start the mapr-loopbacknfs service and mount the volume

Perform the following steps from your client node, except where noted.

If cluster security is enabled, the ticket you generated above must be available or the NFS server will not start.

  1. Start the mapr-loopbacknfs service from the command line.

    # service mapr-loopbacknfs start
  2. Create a mount point at /mapr and mount the client node to it.

    # mkdir /mapr
    # mount localhost:/mapr /mapr
  3. You can also automate the mounting of the volume with every launch of the mapr-loopbacknfs service. On the POSIX client node, create /usr/local/mapr-loopbacknfs/conf/mapr_fstab and add the following line:

    localhost:/mapr /mapr hard,nolock

    Securing the Mountpoint

    POSIX permissions are the only limitation on read access by the MapR POSIX client, whether the cluster connected to has security enabled or disabled.

    By securing the mountpoint, you can limit access to a single user

  1. On the client system, create /mapr/<clustername>:

    mkdir -p /mapr/<clustername>
  2. Set ownership and permissions

    chown user1:<posix_user> /mapr 
    chmod 700 /mapr
  3. Mount the cluster:

     mount localhost:/mapr/<clustername>  /mapr/<clustername>

Now only <posix_user> can access the cluster with the POSIX client.

Registering a POSIX Client with Additional Clusters

The first time you start the loopbacknfs service, you edit the mapr-loopbacknfs init script by defining the CLUSTER_NAME and CLDB_IPS variables, then run the script. These actions update the /usr/local/mapr-loopbacknfs/conf/mapr-clusters.conf file. 

However, when you want to register a client with a new cluster or an additional cluster, you must add entries directly to the /usr/local/mapr-loopbacknfs/conf/mapr-clusters.conf file. Editing the mapr-loopbacknfs script and restarting the loopbacknfs service does not update the mapr-clusters.conf file.

Configuring the MapR POSIX Client

The default RPC requests configuration can negatively impact performance and memory. To avoid performance and memory issues, configure the number of outstanding RPC requests to the cluster to be 128.

Perform the following steps as the root user on each POSIX client machine:

  1. Issue the following commands to create the sunrpc.conf file under /etc/modprobe.d with the recommended configuration:

    echo "options sunrpc tcp_slot_table_entries=128" >> /etc/modprobe.d/sunrpc.conf 
    echo "options sunrpc tcp_max_slot_table_entries=128" >> /etc/modprobe.d/sunrpc.conf
  2. Issue the following echo commands:

    echo 128 > /proc/sys/sunrpc/tcp_slot_table_entries 
    echo 128 > /proc/sys/sunrpc/tcp_max_slot_table_entries

    This will enable the configuration to take effect after you remount the POSIX client to the MapR cluster.

  3. Remount the POSIX client to the Mapr cluster. 
    For example, the following commands unmount and mount the NFS assuming that the cluster is mounted at /mapr: 

    # umount /mapr 
    # mount -o hard,nolock /mapr

Failure to configure this property may result in the following error in /usr/local/mapr-loopbacknfs/log:
ERROR nfsserver[38960] fs/nfsd/[0] cannot allocate more OncRpcContexts: [numDropped=2556001] dropping connection from nfsc=

CentOS Troubleshooting Tip

After the reboot of the node, if the /proc/sys/sunrpc directory not available or if rpcidmapd is not running, start the rpcidmapd service using the following command: service rpcidmapd start

Verifying MapR POSIX Client Licenses

You can check how many MapR POSIX Client licenses are available by clicking on System Settings > Manage Licenses in the navigation pane of the MCS. When the License Management dialog box displays, look under Additional Features to find the number of POSIX Client nodes that can consume a MapR POSIX Client license.

Managing the mapr-loopbacknfs Service

To manually start or stop the service:

service mapr-loopbacknfs [start|stop]

To have the service start automatically when the OS starts up:

chkconfig -add mapr-loopbacknfs
chkconfig -list mapr-loopbacknfs     # confirm settings

To monitor the service:

service mapr-loopbacknfs status
showmount -e localhost

The showmount command displays:

  • Export list for <host>

  • /mapr     

  • /mapr/<clustername>

Troubleshooting mapr-loopbacknfs Service Issues

To debug authentication issues, follow these steps:

  1. If you receive a standard error (stderr):
    • Make sure rpcinfo/portmap is installed and/or run service portmap start.
    • Run service rpcbind restart.
  2. Examine the log files for error messages:


    Error messages in loopbacknfs.log file:

    Error Message


    Refresh User tickets failed as security layer could not be initialized with user ticket /tmp/maprticket_0

    Unset MAPR_TICKETFILE_LOCATION in initscripts/mapr-loopbacknfs.

    exiting: license only allows 10 NFS/mfs server(s), currently alive=10

    If you have multiple clusters listed in the mapr-clusters.conf file on the client, make sure the first one listed is a MapR 4.0.2 or later cluster.

    If that is not the problem, you will probably need to purchase additional licenses, or reduce number of installations of the mapr-loopbacknfs service.

  3. Verify that settings in configuration files are correct.
    • For all clusters:
    • For secure clusters:
  4. Check for “stale” mounts.incremental save for major revision for Bug 17049
    • The script is not very intelligent, and the initscript wrapper does force unmounts of the mounted file systems.

    • Always check for stale mounts after stopping the service:

      • df -k should return instantly.

      • Use umount –f <mount_point> to force the unmount.

      • Use ps –ef | grep mount_local to confirm that the script is not stuck.