man > nfsidmap(8)

nfsidmap(8)                            System Manager's Manual                           nfsidmap(8)

NAME
       nfsidmap - The NFS idmapper upcall program

SYNOPSIS
       nfsidmap [-v] [-t timeout] key desc
       nfsidmap [-v] [-c]
       nfsidmap [-v] [-u|-g|-r user]
       nfsidmap -d
       nfsidmap -l
       nfsidmap -h

DESCRIPTION
       The NFSv4 protocol represents the local system's UID and GID values on the wire as strings of
       the form user@domain.  The process of translating from UID to string and string to UID is re‐
       ferred to as "ID mapping."

       The system derives the user part of the string by performing a password or group lookup.  The
       lookup mechanism is configured in /etc/idmapd.conf.

       By  default,  the  domain part of the string is the system's DNS domain name.  It can also be
       specified in /etc/idmapd.conf if the system is multi-homed, or if  the  system's  DNS  domain
       name does not match the name of the system's Kerberos realm.

       When the domain is not specified in /etc/idmapd.conf the local DNS server will be queried for
       the _nfsv4idmapdomain text record. If the record exists that will be used as the domain. When
       the record does not exist, the domain part of the DNS domain will used.

       The  /usr/sbin/nfsidmap  program  performs  translations on behalf of the kernel.  The kernel
       uses the request-key mechanism to  perform  an  upcall.   /usr/sbin/nfsidmap  is  invoked  by
       /sbin/request-key,  performs the translation, and initializes a key with the resulting infor‐
       mation.  The kernel then caches the translation results in the key.

       nfsidmap can also clear cached ID map results in the kernel, or revoke  one  particular  key.
       An  incorrect  cached key can result in file and directory ownership reverting to "nobody" on
       NFSv4 mount points.

       In addition, the -d and -l options are available to help  diagnose  misconfigurations.   They
       have no effect on the keyring containing ID mapping results.

OPTIONS
       -c     Clear the keyring of all the keys.

       -d     Display the system's effective NFSv4 domain name on stdout.

       -g user
              Revoke the gid key of the given user.

       -h     Display usage message.

       -l     Display  on stdout all keys currently in the keyring used to cache ID mapping results.
              These keys are visible only to the superuser.

       -r user
              Revoke both the uid and gid key of the given user.

       -t timeout
              Set the expiration timer, in seconds, on the key.  The  default  is  600  seconds  (10
              mins).

       -u user
              Revoke the uid key of the given user.

       -v     Increases the verbosity of the output to syslog (can be specified multiple times).

CONFIGURING
       The file /etc/request-key.conf will need to be modified so /sbin/request-key can properly di‐
       rect the upcall. The following line should be added before a call to keyctl negate:

       create    id_resolver    *    *    /usr/sbin/nfsidmap -t 600 %k %d

       This  will direct all id_resolver requests to the program /usr/sbin/nfsidmap.  The -t 600 de‐
       fines how many seconds into the future the key will expire.  This is  an  optional  parameter
       for /usr/sbin/nfsidmap and will default to 600 seconds when not specified.

       The idmapper system uses four key descriptions:

              uid: Find the UID for the given user
              gid: Find the GID for the given group
             user: Find the user name for the given UID
            group: Find the group name for the given GID

       You can choose to handle any of these individually, rather than using the generic upcall pro‐
       gram.   If  you  would like to use your own program for a uid lookup then you would edit your
       request-key.conf so it looks similar to this:

       create    id_resolver    uid:*     *    /some/other/program %k %d
       create    id_resolver    *         *    /usr/sbin/nfsidmap %k %d

       Notice that the new line was added above the line for the generic program.  request-key  will
       find   the   first   matching  line  and  run  the  corresponding  program.   In  this  case,
       /some/other/program will handle all uid lookups,  and  /usr/sbin/nfsidmap  will  handle  gid,
       user, and group lookups.

FILES
       /etc/idmapd.conf
              ID mapping configuration file

       /etc/request-key.conf
              Request key configuration file

SEE ALSO
       idmapd.conf(5), request-key(8)

AUTHOR
       Bryan Schumaker, <bjschuma AT netapp.com>

                                           1 October 2010                                nfsidmap(8)