share/man/man5/group.5

   1 .\" Copyright (c) 1980, 1991, 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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)group.5       8.3 (Berkeley) 4/19/94
  33 .\" $FreeBSD: src/share/man/man5/group.5,v 1.15.2.4 2002/02/01 15:51:18 ru Exp $
  34 .\"
  35 .Dd September 29, 1994
  36 .Dt GROUP 5
  37 .Os
  38 .Sh NAME
  39 .Nm group
  40 .Nd format of the group permissions file
  41 .Sh DESCRIPTION
  42 The file
  43 .Aq Pa /etc/group
  44 consists of newline separated
  45 .Tn ASCII
  46 records, one per group, containing four colon
  47 .Ql \&:
  48 separated fields.
  49 These fields are as follows:
  50 .Bl -tag -width password -offset indent -compact
  51 .It group
  52 Name of the group.
  53 .It passwd
  54 Group's
  55 .Em encrypted
  56 password.
  57 .It gid
  58 The group's decimal ID.
  59 .It member
  60 Group members.
  61 .El
  62 .Pp
  63 Lines whose first non-whitespace character is a pound-sign (#)
  64 are comments, and are ignored.
  65 Blank lines that consist
  66 only of spaces, tabs or newlines are also ignored.
  67 .Pp
  68 The
  69 .Ar group
  70 field is the group name used for granting file access to users
  71 who are members of the group.
  72 The
  73 .Ar gid
  74 field is the number associated with the group name.
  75 They should both be unique across the system (and often
  76 across a group of systems) since they control file access.
  77 The
  78 .Ar passwd
  79 field
  80 is an optional
  81 .Em encrypted
  82 password.
  83 This field is rarely used
  84 and an asterisk is normally placed in it rather than leaving it blank.
  85 The
  86 .Ar member
  87 field contains the names of users granted the privileges of
  88 .Ar group .
  89 The member names are separated by commas without spaces or newlines.
  90 A user is automatically in a group if that group was specified
  91 in their
  92 .Pa /etc/passwd
  93 entry and does not need to be added to that group in the
  94 .Pa /etc/group file.
  95 .\" .Pp
  96 .\" When the system reads the file
  97 .\" .Pa /etc/group
  98 .\" the fields are read into the structure
  99 .\" .Fa group
 100 .\" declared in
 101 .\" .Aq Pa grp.h :
 102 .\" .Bd -literal -offset indent
 103 .\" struct group {
 104 .\"     char    *gr_name;        /* group name */
 105 .\"     char    *gr_passwd;      /* group password */
 106 .\"     int     gr_gid;          /* group id */
 107 .\"     char    **gr_mem;        /* group members */
 108 .\" };
 109 .\" .Ed
 110 .Sh YP/NIS INTERACTION
 111 The
 112 .Pa /etc/group
 113 file can be configured to enable the YP/NIS group database.
 114 An entry whose
 115 .Ar name
 116 field consists of a plus sign (`+') followed by a group name, will be
 117 replaced internally to the C library with the YP/NIS group entry for the
 118 named group.  An entry whose
 119 .Ar name
 120 field consists of a single plus sign with no group name following,
 121 will be replaced with the entire YP/NIS
 122 .Dq Li group.byname
 123 map.
 124 .Pp
 125 If the YP/NIS group database is enabled for any reason, all reverse
 126 lookups (i.e.,
 127 .Fn getgrgid )
 128 will use the entire database, even if only a few groups are enabled.
 129 Thus, the group name returned by
 130 .Fn getgrgid
 131 is not guaranteed to have a valid forward mapping.
 132 .Sh LIMITS
 133 There are various limitations which are explained in
 134 the function where they occur; see section
 135 .Sx SEE ALSO .
 136 .Pp
 137 In older implementations,
 138 a group cannot have more than 200 members.
 139 The maximum line length of
 140 .Pa /etc/group
 141 is 1024 characters.
 142 Longer lines will be skipped.
 143 This limitation disappeared in
 144 .Fx 3.0 .
 145 Older binaries that are statically linked, depend on old
 146 shared libraries, or
 147 .No non- Ns Fx
 148 binaries in compatibility mode
 149 may still have this limits.
 150 .Sh FILES
 151 .Bl -tag -width /etc/group -compact
 152 .It Pa /etc/group
 153 .El
 154 .Sh SEE ALSO
 155 .Xr passwd 1 ,
 156 .Xr setgroups 2 ,
 157 .Xr crypt 3 ,
 158 .Xr getgrent 3 ,
 159 .Xr initgroups 3 ,
 160 .Xr passwd 5 ,
 161 .Xr yp 8
 162 .Sh BUGS
 163 The
 164 .Xr passwd 1
 165 command does not change the
 166 .Nm
 167 passwords.
 168 .Sh HISTORY
 169 A
 170 .Nm
 171 file format appeared in
 172 .At v6 .
 173 The YP/NIS functionality is modeled after
 174 .Tn SunOS
 175 and first appeared in
 176 .Fx 1.1 .
 177 Support for comments first appeared in
 178 .Fx 3.0 .