utils/nfsidmap/nfsidmap.man

   1 .\"
   2 .\"@(#)nfsidmap(8) - The NFS idmapper upcall program
   3 .\"
   4 .\" Copyright (C) 2010 Bryan Schumaker <bjschuma@netapp.com>
   5 .TH nfsidmap 5 "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 .SH DESCRIPTION
  13 The file
  14 .I /usr/sbin/nfsidmap
  15 is used by the NFS idmapper to translate user and group ids into names, and to
  16 translate user and group names into ids. Idmapper uses request-key to perform
  17 the upcall and cache the result.
  18 .I /usr/sbin/nfsidmap
  19 is called by /sbin/request-key, and will perform the translation and
  20 initialize a key with the resulting information.
  21 .PP
  22 .I nfsidmap
  23 can also used to clear the keyring of all the keys.
  24 This is useful when all the mappings have failed to due to an DNS outage
  25 or some other error resulting in all the cached uid/gid to be invalid.
  26 .SH OPTIONS
  27 .TP
  28 .B -c
  29 Clear the keyring of all the keys.
  30 .TP
  31 .B -t timeout
  32 Set the expiration timer, in seconds, on the key.
  33 The default is 600 seconds (10 mins).
  34 .TP
  35 .B -v
  36 Increases the verbosity of the output to syslog
  37 (can be specified multiple times).
  38 .SH CONFIGURING
  39 The file
  40 .I /etc/request-key.conf
  41 will need to be modified so
  42 .I /sbin/request-key
  43 can properly direct the upcall. The following line should be added before a call
  44 to keyctl negate:
  45 .PP
  46 create  id_resolver     *       *       /usr/sbin/nfsidmap -t 600 %k %d
  47 .PP
  48 This will direct all id_resolver requests to the program
  49 .I /usr/sbin/nfsidmap.
  50 The
  51 .B -t 600
  52 defines how many seconds into the future the key will
  53 expire.  This is an optional parameter for
  54 .I /usr/sbin/nfsidmap
  55 and will default to 600 seconds when not specified.
  56 .PP
  57 The idmapper system uses four key descriptions:
  58 .PP
  59           uid: Find the UID for the given user
  60 .br
  61           gid: Find the GID for the given group
  62 .br
  63          user: Find the user name for the given UID
  64 .br
  65         group: Find the group name for the given GID
  66 .PP
  67 You can choose to handle any of these individually, rather than using the
  68 generic upcall program.  If you would like to use your own program for a uid
  69 lookup then you would edit your request-key.conf so it looks similar to this:
  70 .PP
  71 create  id_resolver     uid:*   *       /some/other/program %k %d
  72 .br
  73 create  id_resolver     *               *       /usr/sbin/nfsidmap %k %d
  74 .PP
  75 Notice that the new line was added above the line for the generic program.
  76 request-key will find the first matching line and run the corresponding program.
  77 In this case, /some/other/program will handle all uid lookups, and
  78 /usr/sbin/nfsidmap will handle gid, user, and group lookups.
  79 .SH AUTHOR
  80 Bryan Schumaker, <bjschuma@netapp.com>