xref: /freebsd/usr.sbin/mountd/netgroup.5 (revision d6b92ffa) 
1.\" Copyright (c) 1992, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)netgroup.5	8.2 (Berkeley) 12/11/93
29.\" $FreeBSD$
30.\"
31.Dd December 11, 1993
32.Dt NETGROUP 5
33.Os
34.Sh NAME
35.Nm netgroup
36.Nd defines network groups
37.Sh SYNOPSIS
38.Nm
39.Sh DESCRIPTION
40The
41.Nm
42file
43specifies ``netgroups'', which are sets of
44.Sy (host, user, domain)
45tuples that are to be given similar network access.
46.Pp
47Each line in the file
48consists of a netgroup name followed by a list of the members of the
49netgroup.
50Each member can be either the name of another netgroup or a specification
51of a tuple as follows:
52.Bd -literal -offset indent
53(host, user, domain)
54.Ed
55.Pp
56where the
57.Sy host ,
58.Sy user ,
59and
60.Sy domain
61are character string names for the corresponding component.
62Any of the comma separated fields may be empty to specify a ``wildcard'' value
63or may consist of the string ``-'' to specify ``no valid value''.
64The members of the list may be separated by whitespace and/or commas;
65the ``\e'' character may be used at the end of a line to specify
66line continuation.
67Lines are limited to 1024 characters.
68The functions specified in
69.Xr getnetgrent 3
70should normally be used to access the
71.Nm
72database.
73.Pp
74Lines that begin with a # are treated as comments.
75.Sh NIS/YP INTERACTION
76On most other platforms,
77.Nm Ns s
78are only used in conjunction with
79.Tn NIS
80and local
81.Pa /etc/netgroup
82files are ignored.
83With
84.Fx ,
85.Nm Ns s
86can be used with either
87.Tn NIS
88or local files, but there are certain
89caveats to consider.
90The existing
91.Nm
92system is extremely inefficient where
93.Fn innetgr 3
94lookups are concerned since
95.Nm
96memberships are computed on the fly.
97By contrast, the
98.Tn NIS
99.Nm
100database consists of three separate maps (netgroup, netgroup.byuser
101and netgroup.byhost) that are keyed to allow
102.Fn innetgr 3
103lookups to be done quickly.
104The
105.Fx
106.Nm
107system can interact with the
108.Tn NIS
109.Nm
110maps in the following ways:
111.Bl -bullet -offset indent
112.It
113If the
114.Pa /etc/netgroup
115file does not exist, or it exists and is empty, or
116it exists and contains only a
117.Sq + ,
118and
119.Tn NIS
120is running,
121.Nm
122lookups will be done exclusively through
123.Tn NIS ,
124with
125.Fn innetgr 3
126taking advantage of the netgroup.byuser and
127netgroup.byhost maps to speed up searches.
128(This
129is more or less compatible with the behavior of SunOS and
130similar platforms.)
131.It
132If the
133.Pa /etc/netgroup
134exists and contains only local
135.Nm
136information (with no
137.Tn NIS
138.Sq +
139token), then only the local
140.Nm
141information will be processed (and
142.Tn NIS
143will be ignored).
144.It
145If
146.Pa /etc/netgroup
147exists and contains both local netgroup data
148.Pa and
149the
150.Tn NIS
151.Sq +
152token, the local data and the
153.Tn NIS
154netgroup
155map will be processed as a single combined
156.Nm
157database.
158While this configuration is the most flexible, it
159is also the least efficient: in particular,
160.Fn innetgr 3
161lookups will be especially slow if the
162database is large.
163.El
164.Sh FILES
165.Bl -tag -width /etc/netgroup -compact
166.It Pa /etc/netgroup
167the netgroup database
168.El
169.Sh COMPATIBILITY
170The file format is compatible with that of various vendors, however it
171appears that not all vendors use an identical format.
172.Sh SEE ALSO
173.Xr getnetgrent 3 ,
174.Xr exports 5
175.Sh BUGS
176The interpretation of access restrictions based on the member tuples of a
177netgroup is left up to the various network applications.
178Also, it is not obvious how the domain specification
179applies to the
180.Bx
181environment.
182.Pp
183The
184.Nm
185database should be stored in the form of a
186hashed
187.Xr db 3
188database just like the
189.Xr passwd 5
190database to speed up reverse lookups.
191