| 1 |
.\" |
| 2 |
.\"@(#)nfsidmap(8) - The NFS idmapper upcall program |
| 3 |
.\" |
| 4 |
.\" Copyright (C) 2010 Bryan Schumaker <[email protected]> |
| 5 |
.TH nfsidmap 8 "1 October 2010" |
| 6 |
.SH NAME |
| 7 |
nfsidmap \- The NFS idmapper upcall program |
| 8 |
.SH SYNOPSIS |
| 9 |
.B "nfsidmap [-v] [-t timeout] key desc" |
| 10 |
.br |
| 11 |
.B "nfsidmap [-v] [-c]" |
| 12 |
.br |
| 13 |
.B "nfsidmap [-v] [-u|-g|-r user]" |
| 14 |
.br |
| 15 |
.B "nfsidmap -d" |
| 16 |
.br |
| 17 |
.B "nfsidmap -l" |
| 18 |
.br |
| 19 |
.B "nfsidmap -h" |
| 20 |
.SH DESCRIPTION |
| 21 |
The NFSv4 protocol represents the local system's UID and GID values |
| 22 |
on the wire as strings of the form |
| 23 |
.IR user@domain . |
| 24 |
The process of translating from UID to string and string to UID is |
| 25 |
referred to as "ID mapping." |
| 26 |
.PP |
| 27 |
The system derives the |
| 28 |
.I user |
| 29 |
part of the string by performing a password or group lookup. |
| 30 |
The lookup mechanism is configured in |
| 31 |
.IR /etc/idmapd.conf . |
| 32 |
.PP |
| 33 |
By default, the |
| 34 |
.I domain |
| 35 |
part of the string is the system's DNS domain name. |
| 36 |
It can also be specified in |
| 37 |
.I /etc/idmapd.conf |
| 38 |
if the system is multi-homed, |
| 39 |
or if the system's DNS domain name does |
| 40 |
not match the name of the system's Kerberos realm. |
| 41 |
.PP |
| 42 |
When the domain is not specified in |
| 43 |
.I /etc/idmapd.conf |
| 44 |
the local DNS server will be queried for the |
| 45 |
.I _nfsv4idmapdomain |
| 46 |
text record. If the record exists |
| 47 |
that will be used as the domain. When the record |
| 48 |
does not exist, the domain part of the DNS domain |
| 49 |
will used. |
| 50 |
.PP |
| 51 |
The |
| 52 |
.I /usr/sbin/nfsidmap |
| 53 |
program performs translations on behalf of the kernel. |
| 54 |
The kernel uses the request-key mechanism to perform |
| 55 |
an upcall. |
| 56 |
.I /usr/sbin/nfsidmap |
| 57 |
is invoked by /sbin/request-key, performs the translation, |
| 58 |
and initializes a key with the resulting information. |
| 59 |
The kernel then caches the translation results in the key. |
| 60 |
.PP |
| 61 |
.I nfsidmap |
| 62 |
can also clear cached ID map results in the kernel, |
| 63 |
or revoke one particular key. |
| 64 |
An incorrect cached key can result in file and directory ownership |
| 65 |
reverting to "nobody" on NFSv4 mount points. |
| 66 |
.PP |
| 67 |
In addition, the |
| 68 |
.B -d |
| 69 |
and |
| 70 |
.B -l |
| 71 |
options are available to help diagnose misconfigurations. |
| 72 |
They have no effect on the keyring containing ID mapping results. |
| 73 |
.SH OPTIONS |
| 74 |
.TP |
| 75 |
.B -c |
| 76 |
Clear the keyring of all the keys. |
| 77 |
.TP |
| 78 |
.B -d |
| 79 |
Display the system's effective NFSv4 domain name on |
| 80 |
.IR stdout . |
| 81 |
.TP |
| 82 |
.B -g user |
| 83 |
Revoke the gid key of the given user. |
| 84 |
.TP |
| 85 |
.B -h |
| 86 |
Display usage message. |
| 87 |
.TP |
| 88 |
.B -l |
| 89 |
Display on |
| 90 |
.I stdout |
| 91 |
all keys currently in the keyring used to cache ID mapping results. |
| 92 |
These keys are visible only to the superuser. |
| 93 |
.TP |
| 94 |
.B -r user |
| 95 |
Revoke both the uid and gid key of the given user. |
| 96 |
.TP |
| 97 |
.B -t timeout |
| 98 |
Set the expiration timer, in seconds, on the key. |
| 99 |
The default is 600 seconds (10 mins). |
| 100 |
.TP |
| 101 |
.B -u user |
| 102 |
Revoke the uid key of the given user. |
| 103 |
.TP |
| 104 |
.B -v |
| 105 |
Increases the verbosity of the output to syslog |
| 106 |
(can be specified multiple times). |
| 107 |
.SH CONFIGURING |
| 108 |
The file |
| 109 |
.I /etc/request-key.conf |
| 110 |
will need to be modified so |
| 111 |
.I /sbin/request-key |
| 112 |
can properly direct the upcall. The following line should be added before a call |
| 113 |
to keyctl negate: |
| 114 |
.PP |
| 115 |
create id_resolver * * /usr/sbin/nfsidmap -t 600 %k %d |
| 116 |
.PP |
| 117 |
This will direct all id_resolver requests to the program |
| 118 |
.I /usr/sbin/nfsidmap. |
| 119 |
The |
| 120 |
.B -t 600 |
| 121 |
defines how many seconds into the future the key will |
| 122 |
expire. This is an optional parameter for |
| 123 |
.I /usr/sbin/nfsidmap |
| 124 |
and will default to 600 seconds when not specified. |
| 125 |
.PP |
| 126 |
The idmapper system uses four key descriptions: |
| 127 |
.PP |
| 128 |
uid: Find the UID for the given user |
| 129 |
.br |
| 130 |
gid: Find the GID for the given group |
| 131 |
.br |
| 132 |
user: Find the user name for the given UID |
| 133 |
.br |
| 134 |
group: Find the group name for the given GID |
| 135 |
.PP |
| 136 |
You can choose to handle any of these individually, rather than using the |
| 137 |
generic upcall program. If you would like to use your own program for a uid |
| 138 |
lookup then you would edit your request-key.conf so it looks similar to this: |
| 139 |
.PP |
| 140 |
create id_resolver uid:* * /some/other/program %k %d |
| 141 |
.br |
| 142 |
create id_resolver * * /usr/sbin/nfsidmap %k %d |
| 143 |
.PP |
| 144 |
Notice that the new line was added above the line for the generic program. |
| 145 |
request-key will find the first matching line and run the corresponding program. |
| 146 |
In this case, /some/other/program will handle all uid lookups, and |
| 147 |
/usr/sbin/nfsidmap will handle gid, user, and group lookups. |
| 148 |
.SH FILES |
| 149 |
.TP |
| 150 |
.I /etc/idmapd.conf |
| 151 |
ID mapping configuration file |
| 152 |
.TP |
| 153 |
.I /etc/request-key.conf |
| 154 |
Request key configuration file |
| 155 |
.SH "SEE ALSO" |
| 156 |
.BR idmapd.conf (5), |
| 157 |
.BR request-key (8) |
| 158 |
.SH AUTHOR |
| 159 |
Bryan Schumaker, <[email protected]> |