From 4897093455a2bf08f3db3a1132cc2f6f5484d77c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 08:03:02 +0200 Subject: Adding upstream version 1:2.6.4. Signed-off-by: Daniel Baumann --- utils/nfsidmap/nfsidmap.man | 159 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 utils/nfsidmap/nfsidmap.man (limited to 'utils/nfsidmap/nfsidmap.man') diff --git a/utils/nfsidmap/nfsidmap.man b/utils/nfsidmap/nfsidmap.man new file mode 100644 index 0000000..1911c41 --- /dev/null +++ b/utils/nfsidmap/nfsidmap.man @@ -0,0 +1,159 @@ +.\" +.\"@(#)nfsidmap(8) - The NFS idmapper upcall program +.\" +.\" Copyright (C) 2010 Bryan Schumaker +.TH nfsidmap 8 "1 October 2010" +.SH NAME +nfsidmap \- The NFS idmapper upcall program +.SH SYNOPSIS +.B "nfsidmap [-v] [-t timeout] key desc" +.br +.B "nfsidmap [-v] [-c]" +.br +.B "nfsidmap [-v] [-u|-g|-r user]" +.br +.B "nfsidmap -d" +.br +.B "nfsidmap -l" +.br +.B "nfsidmap -h" +.SH DESCRIPTION +The NFSv4 protocol represents the local system's UID and GID values +on the wire as strings of the form +.IR user@domain . +The process of translating from UID to string and string to UID is +referred to as "ID mapping." +.PP +The system derives the +.I user +part of the string by performing a password or group lookup. +The lookup mechanism is configured in +.IR /etc/idmapd.conf . +.PP +By default, the +.I domain +part of the string is the system's DNS domain name. +It can also be specified in +.I /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. +.PP +When the domain is not specified in +.I /etc/idmapd.conf +the local DNS server will be queried for the +.I _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. +.PP +The +.I /usr/sbin/nfsidmap +program performs translations on behalf of the kernel. +The kernel uses the request-key mechanism to perform +an upcall. +.I /usr/sbin/nfsidmap +is invoked by /sbin/request-key, performs the translation, +and initializes a key with the resulting information. +The kernel then caches the translation results in the key. +.PP +.I 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. +.PP +In addition, the +.B -d +and +.B -l +options are available to help diagnose misconfigurations. +They have no effect on the keyring containing ID mapping results. +.SH OPTIONS +.TP +.B -c +Clear the keyring of all the keys. +.TP +.B -d +Display the system's effective NFSv4 domain name on +.IR stdout . +.TP +.B -g user +Revoke the gid key of the given user. +.TP +.B -h +Display usage message. +.TP +.B -l +Display on +.I stdout +all keys currently in the keyring used to cache ID mapping results. +These keys are visible only to the superuser. +.TP +.B -r user +Revoke both the uid and gid key of the given user. +.TP +.B -t timeout +Set the expiration timer, in seconds, on the key. +The default is 600 seconds (10 mins). +.TP +.B -u user +Revoke the uid key of the given user. +.TP +.B -v +Increases the verbosity of the output to syslog +(can be specified multiple times). +.SH CONFIGURING +The file +.I /etc/request-key.conf +will need to be modified so +.I /sbin/request-key +can properly direct the upcall. The following line should be added before a call +to keyctl negate: +.PP +create id_resolver * * /usr/sbin/nfsidmap -t 600 %k %d +.PP +This will direct all id_resolver requests to the program +.I /usr/sbin/nfsidmap. +The +.B -t 600 +defines how many seconds into the future the key will +expire. This is an optional parameter for +.I /usr/sbin/nfsidmap +and will default to 600 seconds when not specified. +.PP +The idmapper system uses four key descriptions: +.PP + uid: Find the UID for the given user +.br + gid: Find the GID for the given group +.br + user: Find the user name for the given UID +.br + group: Find the group name for the given GID +.PP +You can choose to handle any of these individually, rather than using the +generic upcall program. 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: +.PP +create id_resolver uid:* * /some/other/program %k %d +.br +create id_resolver * * /usr/sbin/nfsidmap %k %d +.PP +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. +.SH FILES +.TP +.I /etc/idmapd.conf +ID mapping configuration file +.TP +.I /etc/request-key.conf +Request key configuration file +.SH "SEE ALSO" +.BR idmapd.conf (5), +.BR request-key (8) +.SH AUTHOR +Bryan Schumaker, -- cgit v1.2.3