diff --git a/lib/libutil/login.conf.5 b/lib/libutil/login.conf.5 index cd1f65e79bd0..0ccfafd6b4af 100644 --- a/lib/libutil/login.conf.5 +++ b/lib/libutil/login.conf.5 @@ -1,372 +1,376 @@ .\" Copyright (c) 1996 David Nugent .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, is permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice immediately at the beginning of the file, without modification, .\" this list of conditions, and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. This work was done expressly for inclusion into FreeBSD. Other use .\" is permitted provided this notation is included. .\" 4. Absolutely no warranty of function or purpose is made by the author .\" David Nugent. .\" 5. Modifications may be freely made to this file providing the above .\" conditions are met. .\" .\" $FreeBSD$ .\" .Dd November 22, 1996 .Dt LOGIN.CONF 5 .Os FreeBSD .Sh NAME .Nm login.conf .Nd login class capability database .Sh SYNOPSIS .Pa /etc/login.conf , .Pa ~/.login_conf .Sh DESCRIPTION .Nm login.conf contains various attributes and capabilities of login classes. A login class (an optional annotation against each record in the user account database, .Pa /etc/master.passwd ) determines session accounting, resource limits and user environment settings. It is used by various programs in the system to set up a user's login environment and to enforce policy, accounting and administrative restrictions. It also provides the means by which users are able to be authenticated to the system and the types of authentication available. .Pp A special record "default" in the system user class capability database .Pa /etc/login.conf is used automatically for any non-root user without a valid login class in .Pa /etc/master.passwd . A user with a uid of 0 without a valid login class will use the record "root" if it exists, or "default" if not. .Pp In FreeBSD, users may individually create a file called .Pa .login_conf in their home directory using the same format, consisting of a single entry with a record id of "me". If present, this file is used by .Xr login 1 to set user-defined environment settings which override those specified in the system login capabilities database. Only a subset of login capabilities may be overridden, typically those which do not involve authentication, resource limits and accounting. .Pp Records in a class capabilities database consist of a number of colon-separated fields. The first entry for each record gives one or more names that a record is to be known by, each separated by a '|' character. The first name is the most common abbreviation. The last name given should be a long name that is more descriptive of the capability entry, and all others are synonyms. All names but the last should be in lower case and contain no blanks; the last name may contain upper case characters and blanks for readability. .Pp See .Xr getcap 3 for a more in-depth description of the format of a capability database. .Sh CAPABILITIES Fields within each record in the database follow the .Xr getcap 3 conventions for boolean, type string .Ql \&= and type numeric .Ql \&# , although type numeric is depreciated in favour of the string format and either form is accepted for a numeric datum. Values fall into the following categories: .Bl -tag -width "program" .It file Path name to a data file .It program Path name to an executable file .It list A list of values (or pairs of values) separated by commas or spaces .It path A space or comma separated list of path names, following the usual csh conventions (leading tilde with and without username being expanded to home directories etc.) .It number A numeric value, either decimal (default), hexadecimal (with leading 0x), or octal (with a leading 0). With a numeric type, only one numeric value is allowed. Numeric types may also be specified in string format (ie. the capability tag being delimited from the value by '=' instead of '#'). Whichever method is used, then all records in the database must use the same method to allow values to be correctly overridden in interpolated records. .It size A number which expresses a size. The default interpretation of a value is the number of bytes, but a suffix may specify alternate units: .Bl -tag -offset indent -compact -width xxxx .It b explicitly selects 512-byte blocks .It k selects kilobytes (1024 bytes) .It m specifies a multiplier of 1 megabyte (1048576 bytes), .It g specifies units of gigabytes, and .It t represents terabytes. .El A size value is a numeric quantity and case of the suffix is not significant. Concatenated values are added together. .It time A period of time, by default in seconds. A prefix may specify a different unit: .Bl -tag -offset indent -compact -width xxxx .It y indicates the number of 365 day years, .It w indicates the number of weeks, .It d the number of days, .It h the number of hours, .It m the number of minutes, and .It s the number of seconds. .El Concatenated values are added together. For example, 2 hours and 40 minutes may be written either as 9600s, 160m or 2h40m. .El .Pp The usual convention to interpolate capability entries using the special .Em tc=value notation may be used. .Pp .Sh RESOURCE LIMITS .Bl -column coredumpsize indent indent .Sy Name Type Notes Description .It cputime time CPU usage limit. .It filesize size Maximum file size limit. .It datasize size Maximum data size limit. .It stacksize size Maximum stack size limit. .It coredumpsize size Maximum coredump size limit. .It memoryuse size Maximum of core memory use size limit. .It memorylocked size Maximum locked in core memory size limit. .It maxproc number Maximum number of processes. .It openfiles number Maximum number of open files per process. .It sbsize size Maximum permitted socketbuffer size. .El .Pp These resource limit entries actually specify both the maximum and current limits (see .Xr getrlimit 2 ). The current (soft) limit is the one normally used, although the user is permitted to increase the current limit to the maximum (hard) limit. The maximum and current limits may be specified individually by appending a -max or -cur to the capability name. .Pp .Sh ENVIRONMENT .Bl -column ignorenologin indent xbinxxusrxbin .Sy Name Type Notes Description .It charset string Set $MM_CHARSET environment variable to the specified value. .It hushlogin bool false Same as having a ~/.hushlogin file. .It ignorenologin bool false Login not prevented by nologin. .It lang string Set $LANG environment variable to the specified value. .It manpath path Default search path for manpages. .It nologin file If the file exists it will be displayed and the login session will be terminated. .It path path /bin /usr/bin Default search path. .It priority number Initial priority (nice) level. .It requirehome bool false Require a valid home directory to login. .It setenv list A comma-separated list of environment variables and values to which they are to be set. .It shell prog Session shell to execute rather than the shell specified in the passwd file. The SHELL environment variable will contain the shell specified in the password file. .It term string Default terminal type if not able to determine from other means. .It timezone string Default value of $TZ environment variable. .It umask number 022 Initial umask. Should always have a leading 0 to ensure octal interpretation. .It welcome file /etc/motd File containing welcome message. .El .Pp .Sh AUTHENTICATION .Bl -column minpasswordlen indent indent .Sy Name Type Notes Description .It minpasswordlen number 6 The minimum length a local password may be. +.It passwd_format string md5 The encryption format that new or +changed passwords will use. +Valid values include "md5" and "des". +NIS clients using a non-FreeBSD NIS server should probably use "des". .\" .It approve program Program to approve login. .It mixpasswordcase bool true Whether .Xr passwd 1 will warn the user if an all lower case password is entered. .It copyright file File containing additional copyright information .\".It widepasswords bool false Use the wide password format. The wide password .\" format allows up to 128 significant characters in the password. .It host.allow list List of remote host wildcards from which users in the class may access. .It host.deny list List of remote host wildcards from which users in the class may not access. .It times.allow list List of time periods during which logins are allowed. .It times.deny list List of time periods during which logins are disallowed. .It ttys.allow list List of ttys and ttygroups which users in the class may use for access. .It ttys.deny list List of ttys and ttygroups which users in the class may not use for access. .El .Pp These fields are intended to be used by .Xr passwd 1 and other programs in the login authentication system. .Pp Capabilities that set environment variables are scanned for both .Ql \&~ and .Ql \&$ characters, which are substituted for a user's home directory and name respectively. To pass these characters literally into the environment variable, escape the character by preceding it with a backslash '\\'. .Pp The .Em host.allow and .Em host.deny entries are comma separated lists used for checking remote access to the system, and consist of a list of hostnames and/or IP addresses against which remote network logins are checked. Items in these lists may contain wildcards in the form used by shell programs for wildcard matching (See .Xr fnmatch 3 for details on the implementation). The check on hosts is made against both the remote system's Internet address and hostname (if available). If both lists are empty or not specified, then logins from any remote host are allowed. If host.allow contains one or more hosts, then only remote systems matching any of the items in that list are allowed to log in. If host.deny contains one or more hosts, then a login from any matching hosts will be disallowed. .Pp The .Em times.allow and .Em times.deny entries consist of a comma-separated list of time periods during which the users in a class are allowed to be logged in. These are expressed as one or more day codes followed by a start and end times expressed in 24 hour format, separated by a hyphen or dash. For example, MoThSa0200-1300 translates to Monday, Thursday and Saturday between the hours of 2 am and 1 p.m.. If both of these time lists are empty, users in the class are allowed access at any time. If .Em times.allow is specified, then logins are only allowed during the periods given. If .Em times.deny is specified, then logins are denied during the periods given, regardless of whether one of the periods specified in .Em times.allow applies. .Pp Note that .Xr login 1 enforces only that the actual login falls within periods allowed by these entries. Further enforcement over the life of a session requires a separate daemon to monitor transitions from an allowed period to a non-allowed one. .Pp The .Em ttys.allow and .Em ttys.deny entries contain a comma-separated list of tty devices (without the /dev/ prefix) that a user in a class may use to access the system, and/or a list of ttygroups (See .Xr getttyent 3 and .Xr ttys 5 for information on ttygroups). If neither entry exists, then the choice of login device used by the user is unrestricted. If only .Em ttys.allow is specified, then the user is restricted only to ttys in the given group or device list. If only .Em ttys.deny is specified, then the user is prevented from using the specified devices or devices in the group. If both lists are given and are non-empty, the user is restricted to those devices allowed by ttys.allow that are not available by ttys.deny. .Sh ACCOUNTING LIMITS .Bl -column host.accounted indent indent .Sy Name Type Notes Description .It accounted bool false Enable session time accounting for all users in this class. .It autodelete time Time after expiry when account is auto-deleted. .It bootfull bool false Enable 'boot only if ttygroup is full' strategy when terminating sessions. .It daytime time Maximum login time per day. .It expireperiod time Time for expiry allocation. .It graceexpire time Grace days for expired account. .It gracetime time Additional grace login time allowed. .It host.accounted list List of remote host wildcards from which login sessions will be accounted. .It host.exempt list List of remote host wildcards from which login session accounting is exempted. .It idletime time Maximum idle time before logout. .It monthtime time Maximum login time per month. .It passwordtime time Used by .Xr passwd 1 to set next password expiry date. .It refreshtime time New time allowed on account refresh. .It refreshperiod str How often account time is refreshed. .It sessiontime time Maximum login time per session. .It sessionlimit number Maximum number of concurrent login sessions on ttys in any group. .It ttys.accounted list List of ttys and ttygroups for which login accounting is active. .It ttys.exempt list List of ttys and ttygroups for which login accounting is exempt. .It warnexpire time Advance notice for pending account expiry. .It warnpassword time Advance notice for pending password expiry. .It warntime time Advance notice for pending out-of-time. .It weektime time Maximum login time per week. .El .Pp These fields are used by the time accounting system, which regulates, controls and records user login access. .Pp The .Em ttys.accounted and .Em ttys.exempt fields operate in a similar manner to .Em ttys.allow and .Em ttys.deny as explained above. Similarly with the .Em host.accounted and .Em host.exempt lists. .Sh SEE ALSO .Xr cap_mkdb 1 , .Xr login 1 , .Xr getcap 3 , .Xr getttyent 3 , .Xr login_cap 3 , .Xr login_class 3 , .Xr passwd 5 , .Xr ttys 5 diff --git a/share/man/man4/yp.4 b/share/man/man4/yp.4 index 3ceab06412e1..045884006520 100644 --- a/share/man/man4/yp.4 +++ b/share/man/man4/yp.4 @@ -1,529 +1,537 @@ .\" Copyright (c) 1992/3 Theo de Raadt .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 .\" $FreeBSD$ .\" .Dd April 5, 1993 .Dt YP 4 .Os BSD 4.2 .Sh NAME .Nm yp .Nd description of the YP/NIS system .Sh SYNOPSIS .Nm yp .Sh DESCRIPTION The .Nm YP subsystem allows network management of passwd, group, netgroup, hosts, services, rpc, bootparams and ethers file entries through the functions .Xr getpwent 3 , .Xr getgrent 3 , .Xr getnetgrent 3 , .Xr gethostent 3 , .Xr getnetent 3 , .Xr getrpcent 3 , and .Xr ethers 3 . The .Xr bootparamd 8 daemon makes direct .Tn NIS library calls since there are no functions in the standard C library for reading bootparams. .Tn NIS support is enabled in .Xr nsswitch.conf . .Pp The .Nm YP subsystem is started automatically in .Pa /etc/rc if it has been initialized in .Pa /etc/rc.conf and if the directory .Pa /var/yp exists (which it does in the default distribution). The default .Tn NIS domain must also be set with the .Xr domainname 1 command, which will happen automatically at system startup if it is specified in .Pa /etc/rc.conf . .Pp .Tn NIS is an .Tn RPC Ns -based client/server system that allows a group of machines within an .Tn NIS domain to share a common set of configuration files. This permits a system administrator to set up .Tn NIS client systems with only minimal configuration data and add, remove or modify configuration data from a single location. .Pp The canonical copies of all .Tn NIS information are stored on a single machine called the .Em Tn NIS master server . The databases used to store the information are called .Em Tn NIS maps . In .Bx Free , these maps are stored in .Pa /var/yp/[domainname] where .Pa [domainname] is the name of the .Tn NIS domain being served. A single .Tn NIS server can support several domains at once, therefore it is possible to have several such directories, one for each supported domain. Each domain will have its own independent set of maps. .Pp In .Bx Free , the .Tn NIS maps are Berkeley DB hashed database files (the same format used for the .Xr passwd 5 database files). Other operating systems that support .Tn NIS use old-style ndbm databases instead (largely because Sun Microsystems originally based their .Tn NIS implementation on ndbm, and other vendors have simply licensed Sun's code rather than design their own implementation with a different database format). On these systems, the databases are generally split into .Em .dir and .Em .pag files which the ndbm code uses to hold separate parts of the hash database. The Berkeley DB hash method instead uses a single file for both pieces of information. This means that while you may have .Pa passwd.byname.dir and .Pa passwd.byname.pag files on other operating systems (both of which are really parts of the same map), .Bx Free will have only one file called .Pa passwd.byname . The difference in format is not significant: only the .Tn NIS server, .Xr ypserv 8 , and related tools need to know the database format of the .Tn NIS maps. Client .Tn NIS systems receive all .Tn NIS data in .Tn ASCII form. .Pp There are three main types of .Tn NIS systems: .Bl -enum -offset indent .It .Pa Tn NIS clients , which query .Tn NIS servers for information. .It .Pa Tn NIS master servers , which maintain the canonical copies of all .Tn NIS maps. .It .Pa Tn NIS slave servers , which maintain backup copies of .Tn NIS maps that are periodically updated by the master. .El .Pp An .Tn NIS client establishes what is called a .Em binding to a particular .Tn NIS server using the .Xr ypbind 8 daemon. .Xr Ypbind 8 checks the system's default domain (as set by the .Xr domainname 1 command) and begins broadcasting .Tn RPC requests on the local network. These requests specify the name of the domain for which .Xr ypbind 8 is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to .Xr ypbind 8 , which will record the server's address. If there are several servers available (a master and several slaves, for example), .Xr ypbind 8 will use the address of the first one to respond. From that point on, the client system will direct all of its .Tn NIS requests to that server. .Xr Ypbind 8 will occasionally ``ping'' the server to make sure it's still up and running. If it fails to receive a reply to one of its pings within a reasonable amount of time, .Xr ypbind 8 will mark the domain as unbound and begin broadcasting again in the hopes of locating another server. .Pp .Tn NIS master and slave servers handle all .Tn NIS requests with the .Xr ypserv 8 daemon. .Xr Ypserv 8 is responsible for receiving incoming requests from .Tn NIS clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database back to the client. There is a specific set of requests that .Xr ypserv 8 is designed to handle, most of which are implemented as functions within the standard C library: .Bl -bullet -offset indent .It .Fn yp_order -- check the creation date of a particular map .It .Fn yp_master -- obtain the name of the .Tn NIS master server for a given map/domain .It .Fn yp_match -- lookup the data corresponding to a given in key in a particular map/domain .It .Fn yp_first -- obtain the first key/data pair in a particular map/domain .It .Fn yp_next -- pass .Xr ypserv 8 a key in a particular map/domain and have it return the key/data pair immediately following it (the functions .Fn yp_first and .Fn yp_next can be used to do a sequential search of an .Tn NIS map) .It .Fn yp_all -- retrieve the entire contents of a map .El .Pp There are a few other requests which .Xr ypserv 8 is capable of handling (i.e. acknowledge whether or not you can handle a particular domain (YPPROC_DOMAIN), or acknowledge only if you can handle the domain and be silent otherwise (YPPROC_DOMAIN_NONACK)) but these requests are usually generated only by .Xr ypbind 8 and are not meant to be used by standard utilities. .Pp On networks with a large number of hosts, it is often a good idea to use a master server and several slaves rather than just a single master server. A slave server provides the exact same information as a master server: whenever the maps on the master server are updated, the new data should be propagated to the slave systems using the .Xr yppush 8 command. The .Tn NIS Makefile .Pf ( Pa /var/yp/Makefile ) will do this automatically if the administrator comments out the line which says .Em NOPUSH=true (NOPUSH is set to true by default because the default configuration is for a small network with only one .Tn NIS server). The .Xr yppush 8 command will initiate a transaction between the master and slave during which the slave will transfer the specified maps from the master server using .Xr ypxfr 8 . (The slave server calls .Xr ypxfr 8 automatically from within .Xr ypserv 8 ; therefore it is not usually necessary for the administrator to use it directly. It can be run manually if desired, however.) Maintaining slave servers helps improve .Tn NIS performance on large networks by: .Pp .Bl -bullet -offset indent .It Providing backup services in the event that the .Tn NIS master crashes or becomes unreachable .It Spreading the client load out over several machines instead of causing the master to become overloaded .It Allowing a single .Tn NIS domain to extend beyond a local network (the .Xr ypbind 8 daemon might not be able to locate a server automatically if it resides on a network outside the reach of its broadcasts. It is possible to force .Xr ypbind 8 to bind to a particular server with .Xr ypset 8 but this is sometimes inconvenient. This problem can be avoided simply by placing a slave server on the local network.) .El .Pp The .Bx Free .Xr ypserv 8 is specially designed to provided enhanced security (compared to other .Tn NIS implementations) when used exclusively with .Bx Free client systems. The .Bx Free password database system (which is derived directly from .Bx 4.4 ) includes support for .Em "shadow passwords" . The standard password database does not contain users' encrypted passwords: these are instead stored (along with other information) is a separate database which is accessible only by the super-user. If the encrypted password database were made available as an .Tn NIS map, this security feature would be totally disabled, since any user is allowed to retrieve .Tn NIS data. .Pp To help prevent this, .Bx Free Ns 's .Tn NIS server handles the shadow password maps .Pf ( Pa master.passwd.byname and .Pa master.passwd.byuid ) in a special way: the server will only provide access to these maps in response to requests that originate on privileged ports. Since only the super-user is allowed to bind to a privileged port, the server assumes that all such requests come from privileged users. All other requests are denied: requests from non-privileged ports will receive only an error code from the server. Additionally, .Bx Free Ns 's .Xr ypserv 8 includes support for Wietse Venema's tcp wrapper package; with tcp wrapper support enabled, the administrator can configure .Xr ypserv 8 to respond only to selected client machines. .Pp While these enhancements provide better security than stock .Tn NIS Ns , they are by no means 100% effective. It is still possible for someone with access to your network to spoof the server into disclosing the shadow password maps. .Pp On the client side, .Bx Free Ns 's .Fn getpwent 3 functions will automatically search for the .Pa master.passwd maps and use them if they exist. If they do, they will be used, and all fields in these special maps (class, password age and account expiration) will be decoded. If they aren't found, the standard .Pa passwd maps will be used instead. .Sh COMPATIBILITY +When using a non-FreeBSD NIS server for +.Xr passwd 5 +files, it is unlikely that the default MD5-based format that FreeBSD +uses for passwords will be accepted by it. +If this is the case, the value of the "passwd_format" setting in +.Xr login.conf 5 +should be changed to "des" for compatibility. +.Pp Some systems, such as SunOS 4.x, need .Tn NIS to be running in order for their hostname resolution functions ( .Fn gethostbyname , .Fn gethostbyaddr , etc) to work properly. On these systems, .Xr ypserv 8 performs .Tn DNS lookups when asked to return information about a host that doesn't exist in its .Pa hosts.byname or .Pa hosts.byaddr maps. .Bx Free Ns 's resolver uses .Tn DNS by default (it can be made to use .Tn NIS Ns , if desired), therefore its .Tn NIS server doesn't do .Tn DNS lookups by default. However, .Xr ypserv 8 can be made to perform .Tn DNS lookups if it is started with a special flag. It can also be made to register itself as an .Tn NIS v1 server in order to placate certain systems that insist on the presence of a v1 server .Pf ( Bx Free uses only .Tn NIS v2, but many other systems, including .Tn SunOS 4.x, search for both a v1 and v2 server when binding). .Bx Free Ns 's .Xr ypserv 8 does not actually handle .Tn NIS v1 requests, but this ``kludge mode'' is useful for silencing stubborn systems that search for both a v1 and v2 server. .Pp (Please see the .Xr ypserv 8 manual page for a detailed description of these special features and flags.) .Sh BUGS While .Bx Free now has both .Tn NIS client and server capabilities, it does not yet have support for .Xr ypupdated 8 or the .Fn yp_update function. Both of these require secure .Tn RPC Ns , which .Bx Free doesn't support yet either. .Pp The .Xr getservent 3 and .Xr getprotoent 3 functions do not yet have .Tn NIS support. Fortunately, these files don't need to be updated that often. .Pp Many more manual pages should be written, especially .Xr ypclnt 3 . For the time being, seek out a local Sun machine and read the manuals for there. .Pp Neither Sun nor this author have found a clean way to handle the problems that occur when ypbind cannot find its server upon bootup. .Sh HISTORY The .Nm YP subsystem was written from the ground up by .An Theo de Raadt to be compatible to Sun's implementation. Bug fixes, improvements and .Tn NIS server support were later added by .An Bill Paul Ns . The server-side code was originally written by .An Peter Eriksson and .An Tobias Reber and is subject to the GNU Public License. No Sun code was referenced. diff --git a/share/man/man8/yp.8 b/share/man/man8/yp.8 index 3ceab06412e1..045884006520 100644 --- a/share/man/man8/yp.8 +++ b/share/man/man8/yp.8 @@ -1,529 +1,537 @@ .\" Copyright (c) 1992/3 Theo de Raadt .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 .\" $FreeBSD$ .\" .Dd April 5, 1993 .Dt YP 4 .Os BSD 4.2 .Sh NAME .Nm yp .Nd description of the YP/NIS system .Sh SYNOPSIS .Nm yp .Sh DESCRIPTION The .Nm YP subsystem allows network management of passwd, group, netgroup, hosts, services, rpc, bootparams and ethers file entries through the functions .Xr getpwent 3 , .Xr getgrent 3 , .Xr getnetgrent 3 , .Xr gethostent 3 , .Xr getnetent 3 , .Xr getrpcent 3 , and .Xr ethers 3 . The .Xr bootparamd 8 daemon makes direct .Tn NIS library calls since there are no functions in the standard C library for reading bootparams. .Tn NIS support is enabled in .Xr nsswitch.conf . .Pp The .Nm YP subsystem is started automatically in .Pa /etc/rc if it has been initialized in .Pa /etc/rc.conf and if the directory .Pa /var/yp exists (which it does in the default distribution). The default .Tn NIS domain must also be set with the .Xr domainname 1 command, which will happen automatically at system startup if it is specified in .Pa /etc/rc.conf . .Pp .Tn NIS is an .Tn RPC Ns -based client/server system that allows a group of machines within an .Tn NIS domain to share a common set of configuration files. This permits a system administrator to set up .Tn NIS client systems with only minimal configuration data and add, remove or modify configuration data from a single location. .Pp The canonical copies of all .Tn NIS information are stored on a single machine called the .Em Tn NIS master server . The databases used to store the information are called .Em Tn NIS maps . In .Bx Free , these maps are stored in .Pa /var/yp/[domainname] where .Pa [domainname] is the name of the .Tn NIS domain being served. A single .Tn NIS server can support several domains at once, therefore it is possible to have several such directories, one for each supported domain. Each domain will have its own independent set of maps. .Pp In .Bx Free , the .Tn NIS maps are Berkeley DB hashed database files (the same format used for the .Xr passwd 5 database files). Other operating systems that support .Tn NIS use old-style ndbm databases instead (largely because Sun Microsystems originally based their .Tn NIS implementation on ndbm, and other vendors have simply licensed Sun's code rather than design their own implementation with a different database format). On these systems, the databases are generally split into .Em .dir and .Em .pag files which the ndbm code uses to hold separate parts of the hash database. The Berkeley DB hash method instead uses a single file for both pieces of information. This means that while you may have .Pa passwd.byname.dir and .Pa passwd.byname.pag files on other operating systems (both of which are really parts of the same map), .Bx Free will have only one file called .Pa passwd.byname . The difference in format is not significant: only the .Tn NIS server, .Xr ypserv 8 , and related tools need to know the database format of the .Tn NIS maps. Client .Tn NIS systems receive all .Tn NIS data in .Tn ASCII form. .Pp There are three main types of .Tn NIS systems: .Bl -enum -offset indent .It .Pa Tn NIS clients , which query .Tn NIS servers for information. .It .Pa Tn NIS master servers , which maintain the canonical copies of all .Tn NIS maps. .It .Pa Tn NIS slave servers , which maintain backup copies of .Tn NIS maps that are periodically updated by the master. .El .Pp An .Tn NIS client establishes what is called a .Em binding to a particular .Tn NIS server using the .Xr ypbind 8 daemon. .Xr Ypbind 8 checks the system's default domain (as set by the .Xr domainname 1 command) and begins broadcasting .Tn RPC requests on the local network. These requests specify the name of the domain for which .Xr ypbind 8 is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to .Xr ypbind 8 , which will record the server's address. If there are several servers available (a master and several slaves, for example), .Xr ypbind 8 will use the address of the first one to respond. From that point on, the client system will direct all of its .Tn NIS requests to that server. .Xr Ypbind 8 will occasionally ``ping'' the server to make sure it's still up and running. If it fails to receive a reply to one of its pings within a reasonable amount of time, .Xr ypbind 8 will mark the domain as unbound and begin broadcasting again in the hopes of locating another server. .Pp .Tn NIS master and slave servers handle all .Tn NIS requests with the .Xr ypserv 8 daemon. .Xr Ypserv 8 is responsible for receiving incoming requests from .Tn NIS clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database back to the client. There is a specific set of requests that .Xr ypserv 8 is designed to handle, most of which are implemented as functions within the standard C library: .Bl -bullet -offset indent .It .Fn yp_order -- check the creation date of a particular map .It .Fn yp_master -- obtain the name of the .Tn NIS master server for a given map/domain .It .Fn yp_match -- lookup the data corresponding to a given in key in a particular map/domain .It .Fn yp_first -- obtain the first key/data pair in a particular map/domain .It .Fn yp_next -- pass .Xr ypserv 8 a key in a particular map/domain and have it return the key/data pair immediately following it (the functions .Fn yp_first and .Fn yp_next can be used to do a sequential search of an .Tn NIS map) .It .Fn yp_all -- retrieve the entire contents of a map .El .Pp There are a few other requests which .Xr ypserv 8 is capable of handling (i.e. acknowledge whether or not you can handle a particular domain (YPPROC_DOMAIN), or acknowledge only if you can handle the domain and be silent otherwise (YPPROC_DOMAIN_NONACK)) but these requests are usually generated only by .Xr ypbind 8 and are not meant to be used by standard utilities. .Pp On networks with a large number of hosts, it is often a good idea to use a master server and several slaves rather than just a single master server. A slave server provides the exact same information as a master server: whenever the maps on the master server are updated, the new data should be propagated to the slave systems using the .Xr yppush 8 command. The .Tn NIS Makefile .Pf ( Pa /var/yp/Makefile ) will do this automatically if the administrator comments out the line which says .Em NOPUSH=true (NOPUSH is set to true by default because the default configuration is for a small network with only one .Tn NIS server). The .Xr yppush 8 command will initiate a transaction between the master and slave during which the slave will transfer the specified maps from the master server using .Xr ypxfr 8 . (The slave server calls .Xr ypxfr 8 automatically from within .Xr ypserv 8 ; therefore it is not usually necessary for the administrator to use it directly. It can be run manually if desired, however.) Maintaining slave servers helps improve .Tn NIS performance on large networks by: .Pp .Bl -bullet -offset indent .It Providing backup services in the event that the .Tn NIS master crashes or becomes unreachable .It Spreading the client load out over several machines instead of causing the master to become overloaded .It Allowing a single .Tn NIS domain to extend beyond a local network (the .Xr ypbind 8 daemon might not be able to locate a server automatically if it resides on a network outside the reach of its broadcasts. It is possible to force .Xr ypbind 8 to bind to a particular server with .Xr ypset 8 but this is sometimes inconvenient. This problem can be avoided simply by placing a slave server on the local network.) .El .Pp The .Bx Free .Xr ypserv 8 is specially designed to provided enhanced security (compared to other .Tn NIS implementations) when used exclusively with .Bx Free client systems. The .Bx Free password database system (which is derived directly from .Bx 4.4 ) includes support for .Em "shadow passwords" . The standard password database does not contain users' encrypted passwords: these are instead stored (along with other information) is a separate database which is accessible only by the super-user. If the encrypted password database were made available as an .Tn NIS map, this security feature would be totally disabled, since any user is allowed to retrieve .Tn NIS data. .Pp To help prevent this, .Bx Free Ns 's .Tn NIS server handles the shadow password maps .Pf ( Pa master.passwd.byname and .Pa master.passwd.byuid ) in a special way: the server will only provide access to these maps in response to requests that originate on privileged ports. Since only the super-user is allowed to bind to a privileged port, the server assumes that all such requests come from privileged users. All other requests are denied: requests from non-privileged ports will receive only an error code from the server. Additionally, .Bx Free Ns 's .Xr ypserv 8 includes support for Wietse Venema's tcp wrapper package; with tcp wrapper support enabled, the administrator can configure .Xr ypserv 8 to respond only to selected client machines. .Pp While these enhancements provide better security than stock .Tn NIS Ns , they are by no means 100% effective. It is still possible for someone with access to your network to spoof the server into disclosing the shadow password maps. .Pp On the client side, .Bx Free Ns 's .Fn getpwent 3 functions will automatically search for the .Pa master.passwd maps and use them if they exist. If they do, they will be used, and all fields in these special maps (class, password age and account expiration) will be decoded. If they aren't found, the standard .Pa passwd maps will be used instead. .Sh COMPATIBILITY +When using a non-FreeBSD NIS server for +.Xr passwd 5 +files, it is unlikely that the default MD5-based format that FreeBSD +uses for passwords will be accepted by it. +If this is the case, the value of the "passwd_format" setting in +.Xr login.conf 5 +should be changed to "des" for compatibility. +.Pp Some systems, such as SunOS 4.x, need .Tn NIS to be running in order for their hostname resolution functions ( .Fn gethostbyname , .Fn gethostbyaddr , etc) to work properly. On these systems, .Xr ypserv 8 performs .Tn DNS lookups when asked to return information about a host that doesn't exist in its .Pa hosts.byname or .Pa hosts.byaddr maps. .Bx Free Ns 's resolver uses .Tn DNS by default (it can be made to use .Tn NIS Ns , if desired), therefore its .Tn NIS server doesn't do .Tn DNS lookups by default. However, .Xr ypserv 8 can be made to perform .Tn DNS lookups if it is started with a special flag. It can also be made to register itself as an .Tn NIS v1 server in order to placate certain systems that insist on the presence of a v1 server .Pf ( Bx Free uses only .Tn NIS v2, but many other systems, including .Tn SunOS 4.x, search for both a v1 and v2 server when binding). .Bx Free Ns 's .Xr ypserv 8 does not actually handle .Tn NIS v1 requests, but this ``kludge mode'' is useful for silencing stubborn systems that search for both a v1 and v2 server. .Pp (Please see the .Xr ypserv 8 manual page for a detailed description of these special features and flags.) .Sh BUGS While .Bx Free now has both .Tn NIS client and server capabilities, it does not yet have support for .Xr ypupdated 8 or the .Fn yp_update function. Both of these require secure .Tn RPC Ns , which .Bx Free doesn't support yet either. .Pp The .Xr getservent 3 and .Xr getprotoent 3 functions do not yet have .Tn NIS support. Fortunately, these files don't need to be updated that often. .Pp Many more manual pages should be written, especially .Xr ypclnt 3 . For the time being, seek out a local Sun machine and read the manuals for there. .Pp Neither Sun nor this author have found a clean way to handle the problems that occur when ypbind cannot find its server upon bootup. .Sh HISTORY The .Nm YP subsystem was written from the ground up by .An Theo de Raadt to be compatible to Sun's implementation. Bug fixes, improvements and .Tn NIS server support were later added by .An Bill Paul Ns . The server-side code was originally written by .An Peter Eriksson and .An Tobias Reber and is subject to the GNU Public License. No Sun code was referenced.