release/src/router/libnfsidmap/README

   1 Library to help mapping id's, mainly for NFSv4.
   2
   3 When NFSv4 is using AUTH_GSS (which currently only supports Kerberos v5), the
   4 NFSv4 server mapping functions MUST use secure communications.
   5
   6 We provide several mapping functions, configured using /etc/idmapd.conf
   7
   8 As of the 0.21 version of this library, mapping methods are separate
   9 dynamically-loaded libaries.  This allows the separation of any
  10 LDAP requirements from the main libnfsidmap library.  The main library
  11 now basically loads and calls the functions in the method-specific
  12 libaries.  The method libraries are expected to be named
  13 "libnfsidmap_<method>.so", for example, "libnfsidmap_nsswitch.so".
  14
  15 Several methods may be specified in the /etc/idmapd.conf configuration
  16 file.  Each method is called until a mapping is found.
  17
  18 The following translation methods are delivered in the default distribution:
  19
  20 nsswitch
  21 --------
  22
  23 The default method is called nsswitch. This method uses the get password
  24 file entry functions getpwname(), getpwid(), and the get group file entry
  25 functions getgrnam(), getgrgid(). The nsswitch method can therefore be
  26 configured by the /etc/nss_switch.conf passwd data base stanza. If secure
  27 communications are required (AUTH_GSS), the passwd data base stanza can contain
  28 the 'file' entry because the rpc.idmapd and rpc.svcgssd run as root, and/or the
  29 'ldap' entry if the ldap service is configured to use SASL in /etc/ldap.conf.
  30 The 'nis' entry is NOT recommended, it does not have a secure communications
  31 mode.
  32
  33
  34 static
  35 ------
  36
  37 This method works only for translating GSS authenticated names to local
  38 names.  It uses a static mapping setup defined in the [Static] section
  39 of the idmapd.conf file.  The form of the entries are:
  40   <GSS-Authenticated name> = <localuser>
  41
  42 For example:
  43   nfs/host.domain.org@DOMAIN.ORG = root
  44
  45 It is recommended that this module be used in combination with another
  46 module (e.g. the nsswitch module).
  47
  48 umich_ldap
  49 ----------
  50 An experimental method, umich_ldap uses an LDAP schema and ldap functions
  51 to perform translations.  This method is designed to service remote users,
  52 allowing remote users to set and get ACLs as well as map GSS principals
  53 to id's.  The functions are LDAP based, and the ldap search filters look
  54 for attribute names set by idmapd.conf [UMICH_SCHEMA]
  55 NFSv4_name_attr, NFSv4_group_attr, and GSS_principal_attr.
  56
  57 It is assumed that the LDAP server will index these attributes, and that these
  58 attributes will be associated with the nss.schema posixAccount uidNumber and
  59 gidNumber.  We expect that the uidNumber and gidNumber attribute will be
  60 configurable via the idmapd.conf file soon.
  61
  62 NFSv4_name_attr holds an NFSv4 name of the form user@domain, where the domain
  63 portion of the name is a valid NFSv4 domain name. There is a one-to-one
  64 mapping between the NFSv4_name_attr name and a UID.
  65
  66 NFSv4_group_attr holds an NFSv4 name of the form group@domain, where the domain
  67 portion of the name is a valid NFSv4 domain name. There is a one-to-one
  68 mapping between the NFSv4_group_attr name and a GID.
  69
  70 GSS_principal_attr holds a GSS security mechanism specific context principal
  71 name. For Kerberos v5, it is a Kerberos principal <service/>principal@REALM.
  72 For SPKM3, it is a PKI DN such as (line is split):`
  73 "/C=US/ST=Michigan/O=University of Michigan/OU=UMICH Kerberos
  74  Certification Authority/CN=andros/USERID=andros/Email=andros@UMICH.EDU".
  75 There is a many-to-one relationship between the GSS_principal_attr
  76 name and a UID plus GID.
  77
  78 We have defined LDAP object classes for our experimental NFSv4 id mapping.
  79 We made the attribute names configurable so that other sites could still use
  80 the TR_UMICH_LDAP translation functions with different LDAP attribute names.
  81
  82 We use the same attribute name, NFSv4Name for the NFSv4_name_attr and the
  83 NFSv4_group_attr. For local users and remote users that we wish to give
  84 a local machine account, we add the NFSv4Name attribute and the GSSAuthName
  85 attribute to the existing inetorgPerson and posixAccount schema.
  86 For remote users that we do not wish to give a local machine account,
  87 we use the NFSv4RemotePerson object to contain the NFSv4Name, uidNumber,
  88 gidNumber, and GSSAuthName.
  89
  90 nfsv4.schema
  91 ------------
  92 attributetype ( 1.3.6.1.4.1.250.1.61
  93         NAME ( 'NFSv4Name')
  94         DESC 'NFS version 4 Name'
  95         EQUALITY caseIgnoreIA5Match
  96         SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
  97         SINGLE-VALUE)
  98
  99 attributetype ( 1.3.6.1.4.1.250.1.62
 100         NAME ( 'GSSAuthName')
 101         DESC 'RPCSEC GSS authenticated user name'
 102         EQUALITY caseIgnoreIA5Match
 103         SYNTAX 1.3.6.1.4.1.1466.115.121.1.26)
 104
 105 #
 106 # minimal information for NFSv4 access. used when local filesystem
 107 # access is not permitted (nsswitch ldap calls fail), or when
 108 # inetorgPerson is too much info.
 109 #
 110 objectclass ( 1.3.6.1.4.1.250.1.60 NAME 'NFSv4RemotePerson'
 111         DESC 'NFS version4 person from remote NFSv4 Domain'
 112         SUP top STRUCTURAL
 113         MUST ( uidNumber $ gidNumber $ NFSv4Name )
 114         MAY ( cn $ GSSAuthName $ description) )
 115
 116 #
 117 # minimal information for NFSv4 access. used when local filesystem
 118 # access is not permitted (nsswitch ldap calls fail), or when
 119 # inetorgPerson is too much info.
 120 #
 121 objectclass ( 1.3.6.1.4.1.250.1.63 NAME 'NFSv4RemoteGroup'
 122         DESC 'NFS version4 group from remote NFSv4 Domain'
 123         SUP top STRUCTURAL
 124         MUST ( gidNumber $ NFSv4Name )
 125         MAY ( cn $ memberUid $ description) )
 126