'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH YPSERV 5 "Dec 2, 2023"
.SH NAME
ypserv \- configuration file for NIS to LDAP transition daemons
.SH SYNOPSIS
.nf
\fB/etc/default/ypserv\fR
.fi

.SH DESCRIPTION
The \fBypserv\fR file specifies configuration information for the
\fBypserv\fR(8) daemon. Configuration information can come from LDAP or be
specified in the \fBypserv\fR file.
.sp
.LP
You can create a simple \fBypserv\fR file by running \fBinityp2l\fR(8). The
\fBypserv\fR file can then be customized as required.
.sp
.LP
A related \fBNISLDAPmapping\fR file contains mapping information that converts
NIS entries into LDAP entries. See the \fBNISLDAPmapping\fR(5) man page for an
overview of the setup that is needed to map NIS data to or from LDAP.
.SH EXTENDED DESCRIPTION
The \fBypserv\fR(8) server recognizes the attributes that follow. Values
specified for these attributes in the \fBypserv\fR file, including any empty
values, override values that are obtained from LDAP. However, the
\fBnisLDAPconfig*\fR values are read from the \fBypserv\fR file only
.SS "Attributes"
The following are attributes that are used for initial configuration.
.sp
.ne 2
.na
\fB\fBnisLDAPconfigDN\fR\fR
.ad
.sp .6
.RS 4n
The \fBDN\fR for configuration information. If \fBnisLDAPconfigDN\fR is empty,
all other \fBnisLDAPConfig*\fR values are ignored.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigPreferredServerList\fR\fR
.ad
.sp .6
.RS 4n
The list of servers to use for the configuration phase. There is no default
value. The following is an example of a value for
\fBnisLDAPconfigPreferredServerList\fR:
.sp
.in +2
.nf
nisLDAPconfigPreferredServerList=127.0.0.1:389
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigAuthenticationMethod\fR\fR
.ad
.sp .6
.RS 4n
The authentication method used to obtain the configuration information. The
recognized values for \fBnisLDAPconfigAuthenticationMethod\fR are:
.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 19n
No authentication attempted
.RE

.sp
.ne 2
.na
\fB\fBsimple\fR\fR
.ad
.RS 19n
Password of proxy user sent in the clear to the LDAP server
.RE

.sp
.ne 2
.na
\fB\fBsasl/cram-md5\fR\fR
.ad
.RS 19n
Use \fBSASL/CRAM-MD5\fR authentication. This authentication method may not be
supported by all LDAP servers. A password must be supplied.
.RE

.sp
.ne 2
.na
\fB\fBsasl/digest-md5\fR\fR
.ad
.RS 19n
Use SASL/DIGEST-MD5 authentication. The \fBSASL/CRAM-MD5\fRauthentication
method may not be supported by all LDAP servers. A password must be supplied.
.RE

\fBnisLDAPconfigAuthenticationMethod\fR has no default value. The following is
an example of a value for \fBnisLDAPconfigAuthenticationMethod\fR:
.sp
.in +2
.nf
nisLDAPconfigAuthenticationMethod=simple
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigTLS\fR\fR
.ad
.sp .6
.RS 4n
The transport layer security used for the connection to the server. The
recognized values are:
.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 8n
No encryption of transport layer data. The default value is \fBnone\fR.
.RE

.sp
.ne 2
.na
\fB\fBssl\fR\fR
.ad
.RS 8n
\fBSSL\fR encryption of transport layer data. A certificate is required.
.RE

Export and import control restrictions might limit the availability of
transport layer security.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigTLSCertificateDBPath\fR\fR
.ad
.sp .6
.RS 4n
The name of the directory that contains the certificate database. The default
path is \fB/var/yp\fR.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigProxyUser\fR\fR
.ad
.sp .6
.RS 4n
The proxy user used to obtain configuration information.
\fBnisLDAPconfigProxyUser\fR has no default value. If the value ends with a
comma, the value of the \fBnisLDAPconfigDN\fR attribute is appended. For
example:
.sp
.in +2
.nf
nisLDAPconfigProxyUser=cn=nisAdmin,ou=People,
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPconfigProxyPassword\fR\fR
.ad
.sp .6
.RS 4n
The password that should be supplied to LDAP for the proxy user when the
authentication method requires one. To avoid exposing this password publicly on
the machine, the password should only appear in the configuration file, and the
file should have an appropriate owner, group, and file mode.
\fBnisLDAPconfigProxyPassword\fR has no default value.
.RE

.sp
.LP
The following are attributes used for data retrieval. The object class name
used for these attributes is \fBnisLDAPconfig\fR.
.sp
.ne 2
.na
\fB\fBpreferredServerList\fR\fR
.ad
.sp .6
.RS 4n
The list of servers to use to read or to write mapped NIS data from or to LDAP.
\fBpreferredServerList\fR has no default value. For example:
.sp
.in +2
.nf
preferredServerList=127.0.0.1:389
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBauthenticationMethod\fR\fR
.ad
.sp .6
.RS 4n
The authentication method to use to read or to write mapped NIS data from or to
LDAP. For recognized values, see the \fBLDAPconfigAuthenticationMethod
attribute\fR. \fBauthenticationMethod\fR has no default value. For example:
.sp
.in +2
.nf
authenticationMethod=simple
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPTLS\fR\fR
.ad
.sp .6
.RS 4n
The transport layer security to use to read or to write NIS data from or to
LDAP. For recognized values, see the \fBnisLDAPconfigTLS\fR attribute. The
default value is none. Export and import control restrictions might limit the
availability of transport layer security.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPTLSCertificateDBPath\fR\fR
.ad
.sp .6
.RS 4n
The name of the directory that contains the certificate \fBDB\fR. For
recognized and default values for \fBnisLDAPTLSCertificateDBPath\fR, see the
\fBnisLDAPconfigTLSCertificateDBPath\fR attribute.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPproxyUser\fR\fR
.ad
.sp .6
.RS 4n
Proxy user used by \fBypserv\fR(8), \fBypxfrd\fR(8) and \fByppasswdd\fR(8)
to read or to write from or to LDAP. Assumed to have the appropriate permission
to read and modify LDAP data. There is no default value. If the value ends in a
comma, the value of the context for the current domain, as defined by a
\fBnisLDAPdomainContext\fR attribute, is appended. See \fBNISLDAPmapping\fR(5).
For example:
.sp
.in +2
.nf
nisLDAPproxyUser=cn=nisAdmin,ou=People,
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPproxyPassword\fR\fR
.ad
.sp .6
.RS 4n
The password that should be supplied to LDAP for the proxy user when the
authentication method so requires. To avoid exposing this password publicly on
the machine, the password should only appear in the configuration file, and the
file must have an appropriate owner, group, and file mode.
\fBnisLDAPproxyPassword\fR has no default value.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPsearchTimeout\fR\fR
.ad
.sp .6
.RS 4n
Establishes the timeout for the LDAP search operation. The default value for
\fBnisLDAPsearchTimeout\fR is 180 seconds.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPbindTimeout\fR\fR
.ad
.br
.na
\fB\fBnisLDAPmodifyTimeout\fR\fR
.ad
.br
.na
\fB\fBnisLDAPaddTimeout\fR\fR
.ad
.br
.na
\fB\fBnisLDAPdeleteTimeout\fR\fR
.ad
.sp .6
.RS 4n
Establish timeouts for LDAP bind, modify, add, and delete operations,
respectively. The default value is 15 seconds for each attribute. Decimal
values are allowed.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPsearchTimeLimit\fR\fR
.ad
.sp .6
.RS 4n
Establish a value for the \fBLDAP_OPT_TIMELIMIT\fR option, which suggests a
time limit for the search operation on the LDAP server. The server may impose
its own constraints on possible values. See your LDAP server documentation. The
default is the \fBnisLDAPsearchTimeout\fR value. Only integer values are
allowed.
.sp
Since the \fBnisLDAPsearchTimeout\fR limits the amount of time the client
\fBypserv\fR will wait for completion of a search operation, do not set the
value of \fBnisLDAPsearchTimeLimit\fR larger than the value of
\fBnisLDAPsearchTimeout\fR.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPsearchSizeLimit\fR\fR
.ad
.sp .6
.RS 4n
Establish a value for the \fBLDAP_OPT_SIZELIMIT\fR option, which suggests a
size limit, in bytes, for the search results on the LDAP server. The server may
impose its own constraints on possible values. See your LDAP server
documentation. The default value for \fBnisLDAPsearchSizeLimit\fR is zero,
which means the size limit is unlimited. Only integer values are allowed.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPfollowReferral\fR\fR
.ad
.sp .6
.RS 4n
Determines if the \fBypserv\fR should follow referrals or not. Recognized
values for \fBnisLDAPfollowReferral\fR are \fByes\fR and \fBno\fR. The default
value for \fBnisLDAPfollowReferral\fR is \fBno\fR.
.RE

.sp
.LP
The following attributes specify the action to be taken when some event occurs.
The values are all of the form \fBevent=action\fR. The default action is the
first one listed for each event.
.sp
.ne 2
.na
\fB\fBnisLDAPretrieveErrorAction\fR\fR
.ad
.sp .6
.RS 4n
If an error occurs while trying to retrieve an entry from LDAP, one of the
following actions can be selected:
.sp
.ne 2
.na
\fB\fBuse_cached\fR\fR
.ad
.RS 14n
Retry the retrieval the number of time specified by
\fBnisLDAPretrieveErrorAttempts\fR, with the \fBnisLDAPretrieveErrorTimeout\fR
value controlling the wait between each attempt.
.sp
If all attempts fail, then a warning is logged and the value currently in the
cache is returned to the client.
.RE

.sp
.ne 2
.na
\fB\fBfail\fR\fR
.ad
.RS 14n
Proceed as for \fBuse_cached\fR, but if all attempts fail, a \fBYPERR_YPERR\fR
error is returned to the client.
.RE

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPretrieveErrorAttempts\fR\fR
.ad
.sp .6
.RS 4n
The number of times a failed retrieval should be retried. The default value for
\fBnisLDAPretrieveErrorAttempts\fR is unlimited. While retries are made the
\fBypserv\fR daemon will be prevented from servicing further
requests .\fBnisLDAPretrieveErrorAttempts\fR values other than \fB1\fR should be used
with caution.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPretrieveErrorTimeout\fR\fR
.ad
.sp .6
.RS 4n
The timeout in seconds between each new attempt to retrieve LDAP data. The
default value for \fBnisLDAPretrieveErrorTimeout\fR is 15 seconds.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPstoreErrorAction\fR\fR
.ad
.sp .6
.RS 4n
An error occurred while trying to store data to the LDAP repository.
.sp
.ne 2
.na
\fB\fBretry\fR\fR
.ad
.RS 9n
Retry operation \fBnisLDAPstoreErrorAttempts\fR times with
\fBnisLDAPstoreErrorTimeout\fR seconds between each attempt. While retries are
made, the NIS daemon will be prevented from servicing further requests. Use
with caution.
.RE

.sp
.ne 2
.na
\fB\fBfail\fR\fR
.ad
.RS 9n
Return \fBYPERR_YPERR\fR error to the client.
.RE

.RE

.sp
.ne 2
.na
\fB\fBnisLDAPstoreErrorAttempts\fR\fR
.ad
.sp .6
.RS 4n
The number of times a failed attempt to store should be retried. The default
value for \fBnisLDAPstoreErrorAttempts\fR is unlimited. The value for
\fBnisLDAPstoreErrorAttempts\fR is ignored unless
\fBnisLDAPstoreErrorAction=retry\fR.
.RE

.sp
.ne 2
.na
\fB\fBnisLDAPstoreErrortimeout\fR\fR
.ad
.sp .6
.RS 4n
The timeout, in seconds, between each new attempt to store LDAP data. The
default value for \fBnisLDAPstoreErrortimeout\fR is 15 seconds. The
\fBnisLDAPstoreErrortimeout\fR value is ignored unless
\fBnisLDAPstoreErrorAction=retry\fR.
.RE

.SS "Storing Configuration Attributes in LDAP"
Most attributes described on this man page, as well as those described on
\fBNISLDAPmapping\fR(5), can be stored in LDAP. In order to do so, you will
need to add the following definitions to your LDAP server, which are described
here in \fBLDIF\fR format suitable for use by \fBldapadd\fR(1). The attribute
and objectclass OIDs are examples only.
.sp
.in +2
.nf
dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( 1.3.6.1.4.1.11.1.3.1.1.2 NAME 'preferredServerList' \e
          DESC 'Preferred LDAP server host addresses used by DUA' \e
          EQUALITY caseIgnoreMatch \
          SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
attributetypes: ( 1.3.6.1.4.1.11.1.3.1.1.6 NAME 'authenticationMethod' \e
          DESC 'Authentication method used to contact the DSA' \e
          EQUALITY caseIgnoreMatch \
          SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )

dn: cn=schema
     changetype: modify
     add: attributetypes
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.0 \e
               NAME 'nisLDAPTLS' \e
               DESC 'Transport Layer Security' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.1 \e
               NAME 'nisLDAPTLSCertificateDBPath' \e
               DESC 'Certificate file' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.2 \e
               NAME 'nisLDAPproxyUser' \e
               DESC 'Proxy user for data store/retrieval' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.3 \e
               NAME 'nisLDAPproxyPassword' \e
               DESC 'Password/key/shared secret for proxy user' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.6 \e
               NAME 'nisLDAPretrieveErrorAction' \e
               DESC 'Action following an LDAP search error' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.7 \e
               NAME 'nisLDAPretrieveErrorAttempts' \e
               DESC 'Number of times to retry an LDAP search' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.8 \e
               NAME 'nisLDAPretrieveErrorTimeout' \e
               DESC 'Timeout between each search attempt' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.9 \e
               NAME 'nisLDAPstoreErrorAction' \e
               DESC 'Action following an LDAP store error' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.10 \e
               NAME 'nisLDAPstoreErrorAttempts' \e
               DESC 'Number of times to retry an LDAP store' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.11 \e
               NAME 'nisLDAPstoreErrorTimeout' \e
               DESC 'Timeout between each store attempt' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.12 \e
               NAME 'nisLDAPdomainContext' \e
               DESC 'Context for a single domain' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.13 \e
               NAME 'nisLDAPyppasswddDomains' \e
               DESC 'List of domains for which password changes are made' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.14 \e
               NAME 'nisLDAPdatabaseIdMapping' \e
               DESC 'Defines a database id for a NIS object' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.15 \e
               NAME 'nisLDAPentryTtl' \e
               DESC 'TTL for cached objects derived from LDAP' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.16 \e
               NAME 'nisLDAPobjectDN' \e
               DESC 'Location in LDAP tree where NIS data is stored' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.17 ) \e
               NAME 'nisLDAPnameFields' \e
               DESC 'Rules for breaking NIS entries into fields' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.18 ) \e
               NAME 'nisLDAPsplitFields' \e
               DESC 'Rules for breaking fields into sub fields' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.19 \e
               NAME 'nisLDAPattributeFromField' \e
               DESC 'Rules for mapping fields to LDAP attributes' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.20 \e
               NAME 'nisLDAPfieldFromAttribute' \e
               DESC 'Rules for mapping fields to LDAP attributes' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.21 \e
               NAME 'nisLDAPrepeatedFieldSeparators' \e
               DESC 'Rules for mapping fields to LDAP attributes' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.22 \e
               NAME 'nisLDAPcommentChar' \e
               DESC 'Rules for mapping fields to LDAP attributes' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     attributetypes: ( 1.3.6.1.4.1.42.2.27.5.42.43.1.23 \e
               NAME 'nisLDAPmapFlags' \e
               DESC 'Rules for mapping fields to LDAP attributes' \e
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

     dn: cn=schema
     changetype: modify
     add: objectclasses
     objectclasses:  ( 1.3.6.1.4.1.42.2.27.5.42.43.1.0 NAME 'nisLDAPconfig' \e
               DESC 'NIS/LDAP mapping configuration' \e
               SUP top STRUCTURAL \e
               MAY ( cn $ preferredServerList $
                 authenticationMethod $ nisLDAPTLS $
                 nisLDAPTLSCertificateDBPath $
                 nisLDAPproxyUser $ nisLDAPproxyPassword $
                 nisLDAPretrieveErrorAction $
                 nisLDAPretrieveErrorAttempts $
                 nisLDAPretrieveErrorTimeout $
                 nisLDAPstoreErrorAction $
                 nisLDAPstoreErrorAttempts $
                 nisLDAPstoreErrorTimeout $
                 nisLDAPdomainContext $
                 nisLDAPyppasswddDomains $
                 nisLDAPdatabaseIdMapping $
                 nisLDAPentryTtl $
                 nisLDAPobjectDN $
                 nisLDAPnameFields $
                 nisLDAPsplitFields $
                 nisLDAPattributeFromField $
                 nisLDAPfieldFromAttribute $
                 nisLDAPrepeatedFieldSeparators $
                 nisLDAPcommentChar $
                 nisLDAPmapFlags ) )
.fi
.in -2

.sp
.LP
Create a file containing the following LDIF data. Substitute your actual
\fBnisLDAPconfigDN\fR for \fBconfigDN\fR:
.sp
.in +2
.nf
dn: configDN
objectClass: top
objectClass: nisLDAPconfig
.fi
.in -2

.sp
.LP
Use this file as input to the \fBldapadd\fR(1) command in order to create the
NIS to LDAP configuration entry. Initially, the entry is empty. You can use the
\fBldapmodify\fR(1) command to add configuration attributes.
.SH EXAMPLES
\fBExample 1 \fRCreating a NIS to LDAP Configuration Entry
.sp
.LP
To set the server list to port 389 on 127.0.0.1, create the following file and
use it as input to \fBldapmodify\fR(1):

.sp
.in +2
.nf
dn: configDN
preferredServerList: 127.0.0.1:389
.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Obsolete
.TE

.SH SEE ALSO
.BR ldapadd (1),
.BR ldapmodify (1),
.BR NISLDAPmapping (5),
.BR attributes (7),
.BR inityp2l (8),
.BR yppasswdd (8),
.BR ypserv (8),
.BR ypxfrd (8)
.sp
.LP
\fISystem Administration Guide: Naming and Directory Services (DNS, NIS, and
LDAP)\fR