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