1nfsidmap(5)                   File Formats Manual                  nfsidmap(5)
2
3
4

NAME

6       nfsidmap - The NFS idmapper upcall program
7

SYNOPSIS

9       nfsidmap [-v] [-t timeout] key desc
10       nfsidmap [-v] [-c]
11       nfsidmap [-v] [-u|-g|-r user]
12       nfsidmap -d
13       nfsidmap -l
14       nfsidmap -h
15

DESCRIPTION

17       The  NFSv4 protocol represents the local system's UID and GID values on
18       the wire as strings of the form user@domain.  The process of  translat‐
19       ing  from  UID  to  string and string to UID is referred to as "ID map‐
20       ping."
21
22       The system derives the user part of the string by performing a password
23       or   group   lookup.    The   lookup   mechanism   is   configured   in
24       /etc/idmapd.conf.
25
26       By default, the domain part of the string is the  system's  DNS  domain
27       name.   It  can  also be specified in /etc/idmapd.conf if the system is
28       multi-homed, or if the system's DNS domain name does not match the name
29       of the system's Kerberos realm.
30
31       When  the  domain  is  not  specified in /etc/idmapd.conf the local DNS
32       server will be queried for the _nfsv4idmapdomain text  record.  If  the
33       record exists that will be used as the domain. When the record does not
34       exist, the domain part of the DNS domain will used.
35
36       The /usr/sbin/nfsidmap program performs translations on behalf  of  the
37       kernel.   The  kernel  uses  the  request-key  mechanism  to perform an
38       upcall.  /usr/sbin/nfsidmap is invoked by  /sbin/request-key,  performs
39       the  translation, and initializes a key with the resulting information.
40       The kernel then caches the translation results in the key.
41
42       nfsidmap can also clear cached ID map results in the kernel, or  revoke
43       one  particular  key.   An  incorrect cached key can result in file and
44       directory ownership reverting to "nobody" on NFSv4 mount points.
45
46       In addition, the -d and -l options are available to help diagnose  mis‐
47       configurations.   They have no effect on the keyring containing ID map‐
48       ping results.
49

OPTIONS

51       -c     Clear the keyring of all the keys.
52
53       -d     Display the system's effective NFSv4 domain name on stdout.
54
55       -g user
56              Revoke the gid key of the given user.
57
58       -h     Display usage message.
59
60       -l     Display on stdout all keys currently  in  the  keyring  used  to
61              cache  ID  mapping  results.  These keys are visible only to the
62              superuser.
63
64       -r user
65              Revoke both the uid and gid key of the given user.
66
67       -t timeout
68              Set the expiration timer, in seconds, on the key.   The  default
69              is 600 seconds (10 mins).
70
71       -u user
72              Revoke the uid key of the given user.
73
74       -v     Increases  the  verbosity of the output to syslog (can be speci‐
75              fied multiple times).
76

CONFIGURING

78       The  file  /etc/request-key.conf  will   need   to   be   modified   so
79       /sbin/request-key  can  properly  direct the upcall. The following line
80       should be added before a call to keyctl negate:
81
82       create    id_resolver    *    *    /usr/sbin/nfsidmap -t 600 %k %d
83
84       This  will   direct   all   id_resolver   requests   to   the   program
85       /usr/sbin/nfsidmap.   The  -t  600  defines  how  many seconds into the
86       future the  key  will  expire.   This  is  an  optional  parameter  for
87       /usr/sbin/nfsidmap and will default to 600 seconds when not specified.
88
89       The idmapper system uses four key descriptions:
90
91              uid: Find the UID for the given user
92              gid: Find the GID for the given group
93             user: Find the user name for the given UID
94            group: Find the group name for the given GID
95
96       You  can  choose to handle any of these individually, rather than using
97       the generic upcall program.  If you would like to use your own  program
98       for  a uid lookup then you would edit your request-key.conf so it looks
99       similar to this:
100
101       create    id_resolver    uid:*     *    /some/other/program %k %d
102       create    id_resolver    *         *    /usr/sbin/nfsidmap %k %d
103
104       Notice that the new line was added above the line for the generic  pro‐
105       gram.  request-key will find the first matching line and run the corre‐
106       sponding program.  In this case, /some/other/program  will  handle  all
107       uid  lookups,  and  /usr/sbin/nfsidmap will handle gid, user, and group
108       lookups.
109

FILES

111       /etc/idmapd.conf
112              ID mapping configuration file
113
114       /etc/request-key.conf
115              Request key configuration file
116

SEE ALSO

118       idmapd.conf(5), request-key(8)
119

AUTHOR

121       Bryan Schumaker, <bjschuma@netapp.com>
122
123
124
125                                1 October 2010                     nfsidmap(5)
Impressum