path: root/source4/ldap_server/devdocs/rfc2307.txt

Network Working Group                                          L. Howard
Request for Comments: 2307                        Independent Consultant
Category: Experimental                                        March 1998


      An Approach for Using LDAP as a Network Information Service

Status of this Memo

   This memo defines an Experimental Protocol for the Internet
   community.  It does not specify an Internet standard of any kind.
   Discussion and suggestions for improvement are requested.
   Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

Abstract

   This document describes an experimental mechanism for mapping
   entities related to TCP/IP and the UNIX system into X.500 [X500]
   entries so that they may be resolved with the Lightweight Directory
   Access Protocol [RFC2251]. A set of attribute types and object
   classes are proposed, along with specific guidelines for interpreting
   them.

   The intention is to assist the deployment of LDAP as an
   organizational nameservice. No proposed solutions are intended as
   standards for the Internet. Rather, it is hoped that a general
   consensus will emerge as to the appropriate solution to such
   problems, leading eventually to the adoption of standards. The
   proposed mechanism has already been implemented with some success.

1. Background and Motivation

   The UNIX (R) operating system, and its derivatives (specifically,
   those which support TCP/IP and conform to the X/Open Single UNIX
   specification [XOPEN]) require a means of looking up entities, by
   matching them against search criteria or by enumeration. (Other
   operating systems that support TCP/IP may provide some means of
   resolving some of these entities. This schema is applicable to those
   environments also.)

   These entities include users, groups, IP services (which map names to
   IP ports and protocols, and vice versa), IP protocols (which map
   names to IP protocol numbers and vice versa), RPCs (which map names
   to ONC Remote Procedure Call [RFC1057] numbers and vice versa), NIS



Howard                        Experimental                      [Page 1]

RFC 2307      Using LDAP as a Network Information Service     March 1998


   netgroups, booting information (boot parameters and MAC address
   mappings), filesystem mounts, IP hosts and networks, and RFC822 mail
   aliases.

   Resolution requests are made through a set of C functions, provided
   in the UNIX system's C library. For example, the UNIX system utility
   "ls", which enumerates the contents of a filesystem directory, uses
   the C library function getpwuid() in order to map user IDs to login
   names. Once the request is made, it is resolved using a "nameservice"
   which is supported by the client library. The nameservice may be, at
   its simplest, a collection of files in the local filesystem which are
   opened and searched by the C library. Other common nameservices
   include the Network Information Service (NIS) and the Domain Name
   System (DNS). (The latter is typically used for resolving hosts,
   services and networks.) Both these nameservices have the advantage of
   being distributed and thus permitting a common set of entities to be
   shared amongst many clients.

   LDAP is a distributed, hierarchical directory service access protocol
   which is used to access repositories of users and other network-
   related entities. Because LDAP is often not tightly integrated with
   the host operating system, information such as users may need to be
   kept both in LDAP and in an operating system supported nameservice
   such as NIS. By using LDAP as the the primary means of resolving
   these entities, these redundancy issues are minimized and the
   scalability of LDAP can be exploited. (By comparison, NIS services
   based on flat files do not have the scalability or extensibility of
   LDAP or X.500.)

   The object classes and attributes defined below are suitable for
   representing the aforementioned entities in a form compatible with
   LDAP and X.500 directory services.

2. General Issues

2.1. Terminology

   The key words "MUST", "SHOULD", and "MAY" used in this document are
   to be interpreted as described in [RFC2119].

   For the purposes of this document, the term "nameservice" refers to a
   service, such as NIS or flat files, that is used by the operating
   system to resolve entities within a single, local naming context.
   Contrast this with a "directory service" such as LDAP, which supports
   extensible schema and multiple naming contexts.






Howard                        Experimental                      [Page 2]

RFC 2307      Using LDAP as a Network Information Service     March 1998


   The term "NIS-related entities" broadly refers to entities which are
   typically resolved using the Network Information Service. (NIS was
   previously known as YP.) Deploying LDAP for resolving these entities
   does not imply that NIS be used, as a gateway or otherwise. In
   particular, the host and network classes are generically applicable,
   and may be implemented on any system that wishes to use LDAP or X.500
   for host and network resolution.

   The "DUA" (directory user agent) refers to the LDAP client querying
   these entities, such as an LDAP to NIS gateway or the C library.  The
   "client" refers to the application which ultimately makes use of the
   information returned by the resolution. It is irrelevant whether the
   DUA and the client reside within the same address space. The act of
   the DUA making this information to the client is termed
   "republishing".

   To avoid confusion, the term "login name" refers to the user's login
   name (being the value of the uid attribute) and the term "user ID"
   refers to he user's integer identification number (being the value of
   the uidNumber attribute).

   The phrases "resolving an entity" and "resolution of entities" refer
   respectively to enumerating NIS-related entities of a given type, and
   matching them against a given search criterion. One or more entities
   are returned as a result of successful "resolutions" (a "match"
   operation will only return one entity).

   The use of the term UNIX does not confer upon this schema the
   endorsement of owners of the UNIX trademark. Where necessary, the
   term "TCP/IP entity" is used to refer to protocols, services, hosts,
   and networks, and the term "UNIX entity" to its complement. (The
   former category does not mandate the host operating system supporting
   the interfaces required for resolving UNIX entities.)

   The OIDs defined below are derived from iso(1) org(3) dod(6)
   internet(1) directory(1) nisSchema(1).

2.2. Attributes

   The attributes and classes defined in this document are summarized
   below.

   The following attributes are defined in this document:

           uidNumber
           gidNumber
           gecos
           homeDirectory



Howard                        Experimental                      [Page 3]

RFC 2307      Using LDAP as a Network Information Service     March 1998


           loginShell
           shadowLastChange
           shadowMin
           shadowMax
           shadowWarning
           shadowInactive
           shadowExpire
           shadowFlag
           memberUid
           memberNisNetgroup
           nisNetgroupTriple
           ipServicePort
           ipServiceProtocol
           ipProtocolNumber
           oncRpcNumber
           ipHostNumber
           ipNetworkNumber
           ipNetmaskNumber
           macAddress
           bootParameter
           bootFile
           nisMapName
           nisMapEntry

   Additionally, some of the attributes defined in [RFC2256] are
   required.

2.3. Object classes

   The following object classes are defined in this document:

           posixAccount
           shadowAccount
           posixGroup
           ipService
           ipProtocol
           oncRpc
           ipHost
           ipNetwork
           nisNetgroup
           nisMap
           nisObject
           ieee802Device
           bootableDevice

   Additionally, some of the classes defined in [RFC2256] are required.





Howard                        Experimental                      [Page 4]

RFC 2307      Using LDAP as a Network Information Service     March 1998


2.4. Syntax definitions

   The following syntax definitions [RFC2252] are used by this schema.
   The nisNetgroupTripleSyntax represents NIS netgroup triples:

           ( nisSchema.0.0 NAME 'nisNetgroupTripleSyntax'
             DESC 'NIS netgroup triple' )

   Values in this syntax are represented by the following:

        nisnetgrouptriple = "(" hostname "," username "," domainname ")"
        hostname          = "" / "-" / keystring
        username          = "" / "-" / keystring
        domainname        = "" / "-" / keystring

   X.500 servers may use the following representation of the above
   syntax:

        nisNetgroupTripleSyntax ::= SEQUENCE {
         hostname  [0] IA5String OPTIONAL,
         username  [1] IA5String OPTIONAL,
         domainname  [2] IA5String OPTIONAL
        }

   The bootParameterSyntax syntax represents boot parameters:

           ( nisSchema.0.1 NAME 'bootParameterSyntax'
             DESC 'Boot parameter' )

   where:

        bootparameter     = key "=" server ":" path
        key               = keystring
        server            = keystring
        path              = keystring

   X.500 servers may use the following representation of the above
   syntax:

        bootParameterSyntax ::= SEQUENCE {
         key     IA5String,
         server  IA5String,
         path    IA5String
        }

   Values adhering to these syntaxes are encoded as strings by LDAP
   servers.




Howard                        Experimental                      [Page 5]

RFC 2307      Using LDAP as a Network Information Service     March 1998


3. Attribute definitions

   This section contains attribute definitions to be implemented by DUAs
   supporting this schema.

        ( nisSchema.1.0 NAME 'uidNumber'
          DESC 'An integer uniquely identifying a user in an
                administrative domain'
          EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.1 NAME 'gidNumber'
          DESC 'An integer uniquely identifying a group in an
                administrative domain'
          EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.2 NAME 'gecos'
          DESC 'The GECOS field; the common name'
          EQUALITY caseIgnoreIA5Match
          SUBSTRINGS caseIgnoreIA5SubstringsMatch
          SYNTAX 'IA5String' SINGLE-VALUE )

        ( nisSchema.1.3 NAME 'homeDirectory'
          DESC 'The absolute path to the home directory'
          EQUALITY caseExactIA5Match
          SYNTAX 'IA5String' SINGLE-VALUE )

        ( nisSchema.1.4 NAME 'loginShell'
          DESC 'The path to the login shell'
          EQUALITY caseExactIA5Match
          SYNTAX 'IA5String' SINGLE-VALUE )

        ( nisSchema.1.5 NAME 'shadowLastChange'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.6 NAME 'shadowMin'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.7 NAME 'shadowMax'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.8 NAME 'shadowWarning'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.9 NAME 'shadowInactive'



Howard                        Experimental                      [Page 6]

RFC 2307      Using LDAP as a Network Information Service     March 1998


          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.10 NAME 'shadowExpire'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.11 NAME 'shadowFlag'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.12 NAME 'memberUid'
          EQUALITY caseExactIA5Match
          SUBSTRINGS caseExactIA5SubstringsMatch
          SYNTAX 'IA5String' )

        ( nisSchema.1.13 NAME 'memberNisNetgroup'
          EQUALITY caseExactIA5Match
          SUBSTRINGS caseExactIA5SubstringsMatch
          SYNTAX 'IA5String' )

        ( nisSchema.1.14 NAME 'nisNetgroupTriple'
          DESC 'Netgroup triple'
          SYNTAX 'nisNetgroupTripleSyntax' )

        ( nisSchema.1.15 NAME 'ipServicePort'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.16 NAME 'ipServiceProtocol'
          SUP name )

        ( nisSchema.1.17 NAME 'ipProtocolNumber'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.18 NAME 'oncRpcNumber'
          EQUALITY integerMatch
          SYNTAX 'INTEGER' SINGLE-VALUE )

        ( nisSchema.1.19 NAME 'ipHostNumber'
          DESC 'IP address as a dotted decimal, eg. 192.168.1.1,
                omitting leading zeros'
          EQUALITY caseIgnoreIA5Match
          SYNTAX 'IA5String{128}' )

        ( nisSchema.1.20 NAME 'ipNetworkNumber'
          DESC 'IP network as a dotted decimal, eg. 192.168,



Howard                        Experimental                      [Page 7]

RFC 2307      Using LDAP as a Network Information Service     March 1998


                omitting leading zeros'
          EQUALITY caseIgnoreIA5Match
          SYNTAX 'IA5String{128}' SINGLE-VALUE )

        ( nisSchema.1.21 NAME 'ipNetmaskNumber'
          DESC 'IP netmask as a dotted decimal, eg. 255.255.255.0,
                omitting leading zeros'
          EQUALITY caseIgnoreIA5Match
          SYNTAX 'IA5String{128}' SINGLE-VALUE )

        ( nisSchema.1.22 NAME 'macAddress'
          DESC 'MAC address in maximal, colon separated hex
                notation, eg. 00:00:92:90:ee:e2'
          EQUALITY caseIgnoreIA5Match
          SYNTAX 'IA5String{128}' )

        ( nisSchema.1.23 NAME 'bootParameter'
          DESC 'rpc.bootparamd parameter'
          SYNTAX 'bootParameterSyntax' )

        ( nisSchema.1.24 NAME 'bootFile'
          DESC 'Boot image name'
          EQUALITY caseExactIA5Match
          SYNTAX 'IA5String' )

        ( nisSchema.1.26 NAME 'nisMapName'
          SUP name )

        ( nisSchema.1.27 NAME 'nisMapEntry'
          EQUALITY caseExactIA5Match
          SUBSTRINGS caseExactIA5SubstringsMatch
          SYNTAX 'IA5String{1024}' SINGLE-VALUE )

4. Class definitions

   This section contains class definitions to be implemented by DUAs
   supporting the schema.

   The rfc822MailGroup object class MAY be used to represent a mail
   group for the purpose of alias expansion. Several alternative schemes
   for mail routing and delivery using LDAP directories, which are
   outside the scope of this document.

        ( nisSchema.2.0 NAME 'posixAccount' SUP top AUXILIARY
          DESC 'Abstraction of an account with POSIX attributes'
          MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
          MAY ( userPassword $ loginShell $ gecos $ description ) )




Howard                        Experimental                      [Page 8]

RFC 2307      Using LDAP as a Network Information Service     March 1998


        ( nisSchema.2.1 NAME 'shadowAccount' SUP top AUXILIARY
          DESC 'Additional attributes for shadow passwords'
          MUST uid
          MAY ( userPassword $ shadowLastChange $ shadowMin
                shadowMax $ shadowWarning $ shadowInactive $
                shadowExpire $ shadowFlag $ description ) )

        ( nisSchema.2.2 NAME 'posixGroup' SUP top STRUCTURAL
          DESC 'Abstraction of a group of accounts'
          MUST ( cn $ gidNumber )
          MAY ( userPassword $ memberUid $ description ) )

        ( nisSchema.2.3 NAME 'ipService' SUP top STRUCTURAL
          DESC 'Abstraction an Internet Protocol service.
                Maps an IP port and protocol (such as tcp or udp)
                to one or more names; the distinguished value of
                the cn attribute denotes the service's canonical
                name'
          MUST ( cn $ ipServicePort $ ipServiceProtocol )
          MAY ( description ) )

        ( nisSchema.2.4 NAME 'ipProtocol' SUP top STRUCTURAL
          DESC 'Abstraction of an IP protocol. Maps a protocol number
                to one or more names. The distinguished value of the cn
                attribute denotes the protocol's canonical name'
          MUST ( cn $ ipProtocolNumber $ description )
          MAY description )

        ( nisSchema.2.5 NAME 'oncRpc' SUP top STRUCTURAL
          DESC 'Abstraction of an Open Network Computing (ONC)
               [RFC1057] Remote Procedure Call (RPC) binding.
               This class maps an ONC RPC number to a name.
               The distinguished value of the cn attribute denotes
               the RPC service's canonical name'
          MUST ( cn $ oncRpcNumber $ description )
          MAY description )

        ( nisSchema.2.6 NAME 'ipHost' SUP top AUXILIARY

          DESC 'Abstraction of a host, an IP device. The distinguished
                value of the cn attribute denotes the host's canonical
                name. Device SHOULD be used as a structural class'
          MUST ( cn $ ipHostNumber )
          MAY ( l $ description $ manager ) )

        ( nisSchema.2.7 NAME 'ipNetwork' SUP top STRUCTURAL
          DESC 'Abstraction of a network. The distinguished value of
                the cn attribute denotes the network's canonical name'



Howard                        Experimental                      [Page 9]

RFC 2307      Using LDAP as a Network Information Service     March 1998


          MUST ( cn $ ipNetworkNumber )
          MAY ( ipNetmaskNumber $ l $ description $ manager ) )

        ( nisSchema.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL
          DESC 'Abstraction of a netgroup. May refer to other netgroups'
          MUST cn
          MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) )

        ( nisSchema.2.09 NAME 'nisMap' SUP top STRUCTURAL
          DESC 'A generic abstraction of a NIS map'
          MUST nisMapName
          MAY description )

        ( nisSchema.2.10 NAME 'nisObject' SUP top STRUCTURAL
          DESC 'An entry in a NIS map'
          MUST ( cn $ nisMapEntry $ nisMapName )
          MAY description )

        ( nisSchema.2.11 NAME 'ieee802Device' SUP top AUXILIARY
          DESC 'A device with a MAC address; device SHOULD be
                used as a structural class'
          MAY macAddress )

        ( nisSchema.2.12 NAME 'bootableDevice' SUP top AUXILIARY
          DESC 'A device with boot parameters; device SHOULD be
                used as a structural class'
          MAY ( bootFile $ bootParameter ) )

5. Implementation details

5.1. Suggested resolution methods

   The preferred means of directing a client application (one using the
   shared services of the C library) to use LDAP as its information
   source for the functions listed in 5.2 is to modify the source code
   to directly query LDAP. As the source