Try to make it clear that when match_group_by_gid is enabled, groups

in sudoers are looked up by group name instead of group ID.  This
doesn't usually cause problems, but if there are conflicting group
entries (for example, from a local /etc/group file and an LDAP or
AD group database), whether the group is resolved by name or ID can
be used to work around conflicts.

diff --git a/doc/sudoers.cat b/doc/sudoers.cat
index 5b77e438e89cf2375f4ce79617c8c0641f950143..daae58f29f6dd10b69249365bb98e18e018cc6de 100644 (file)
--- a/doc/sudoers.cat
+++ b/doc/sudoers.cat
@@ -1194,24 +1194,39 @@ S\bSU\bUD\bDO\bOE\bER\bRS\bS O\bOP\bPT\bTI\bIO\bON\bNS\bS
                        _\bo_\bn by default.
 
      match_group_by_gid
-                       By default, when matching groups, s\bsu\bud\bdo\boe\ber\brs\bs will first
-                       resolve all the user's group IDs to group names and
-                       then compare those group names to any group names
-                       listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file.  This works well on systems
-                       where the number of groups listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file
-                       is larger than the number of groups a typical user
-                       belongs to.  On systems where group lookups are slow,
-                       where users may belong to a large number of groups, and
-                       where the number of groups listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file
-                       is relatively small, it may be prohibitively expensive
-                       and running commands via s\bsu\bud\bdo\bo may take longer than
-                       normal.  On such systems it may be faster to use the
+                       By default, s\bsu\bud\bdo\boe\ber\brs\bs will look up each group the user is
+                       a member of by group ID to determine the group name
+                       (this is only done once).  The resulting list of the
+                       user's group names is used when matching groups listed
+                       in the _\bs_\bu_\bd_\bo_\be_\br_\bs file.  This works well on systems where
+                       the number of groups listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file is
+                       larger than the number of groups a typical user belongs
+                       to.  On systems where group lookups are slow, where
+                       users may belong to a large number of groups, and where
+                       the number of groups listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file is
+                       relatively small, it may be prohibitively expensive and
+                       running commands via s\bsu\bud\bdo\bo may take longer than normal.
+                       On such systems it may be faster to use the
                        _\bm_\ba_\bt_\bc_\bh_\b__\bg_\br_\bo_\bu_\bp_\b__\bb_\by_\b__\bg_\bi_\bd flag to avoid resolving the user's
-                       group IDs to group names and instead resolve all group
-                       names listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file, matching by group ID
-                       instead of by group name.  The _\bm_\ba_\bt_\bc_\bh_\b__\bg_\br_\bo_\bu_\bp_\b__\bb_\by_\b__\bg_\bi_\bd flag
-                       has no effect when _\bs_\bu_\bd_\bo_\be_\br_\bs data is stored in LDAP.
-                       This flag is _\bo_\bf_\bf by default.
+                       group IDs to group names.  In this case, s\bsu\bud\bdo\boe\ber\brs\bs must
+                       look up any group name listed in the _\bs_\bu_\bd_\bo_\be_\br_\bs file and
+                       use the group ID instead of the group name when
+                       determining whether the user is a member of the group.
+
+                       Note that if _\bm_\ba_\bt_\bc_\bh_\b__\bg_\br_\bo_\bu_\bp_\b__\bb_\by_\b__\bg_\bi_\bd is enabled, group
+                       database lookups performed by s\bsu\bud\bdo\boe\ber\brs\bs will be keyed by
+                       group name as opposed to group ID.  On systems where
+                       there are multiple sources for the group database, it
+                       is possible to have conflicting group names or group
+                       IDs in the local _\b/_\be_\bt_\bc_\b/_\bg_\br_\bo_\bu_\bp file and the remote group
+                       database.  On such systems, enabling or disabling
+                       _\bm_\ba_\bt_\bc_\bh_\b__\bg_\br_\bo_\bu_\bp_\b__\bb_\by_\b__\bg_\bi_\bd can be used to choose whether group
+                       database queries are performed by name (enabled) or ID
+                       (disabled), which may aid in working around group entry
+                       conflicts.
+
+                       The _\bm_\ba_\bt_\bc_\bh_\b__\bg_\br_\bo_\bu_\bp_\b__\bb_\by_\b__\bg_\bi_\bd flag has no effect when _\bs_\bu_\bd_\bo_\be_\br_\bs
+                       data is stored in LDAP.  This flag is _\bo_\bf_\bf by default.
 
                        This setting is only supported by version 1.8.18 or
                        higher.
@@ -2796,4 +2811,4 @@ D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
      file distributed with s\bsu\bud\bdo\bo or https://www.sudo.ws/license.html for
      complete details.
 
-Sudo 1.8.20                     March 27, 2017                     Sudo 1.8.20
+Sudo 1.8.20                     April 11, 2017                     Sudo 1.8.20

diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in
index 0716489a6646368b56a78b9bd8320134f250c34c..2031a719f8611be53b771965d44be8c115b6dfc8 100644 (file)
--- a/doc/sudoers.man.in
+++ b/doc/sudoers.man.in
@@ -21,7 +21,7 @@
 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
 .\"
-.TH "SUDOERS" "5" "March 27, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDOERS" "5" "April 11, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -2526,10 +2526,12 @@ This flag is
 by default.
 .TP 18n
 match_group_by_gid
-By default, when matching groups,
+By default,
 \fBsudoers\fR
-will first resolve all the user's group IDs to group names and then
-compare those group names to any group names listed in the
+will look up each group the user is a member of by group ID to
+determine the group name (this is only done once).
+The resulting list of the user's group names is used when matching
+groups listed in the
 \fIsudoers\fR
 file.
 This works well on systems where the number of groups listed in the
@@ -2545,10 +2547,29 @@ running commands via
 may take longer than normal.
 On such systems it may be faster to use the
 \fImatch_group_by_gid\fR
-flag to avoid resolving the user's group IDs to group names and
-instead resolve all group names listed in the
+flag to avoid resolving the user's group IDs to group names.
+In this case,
+\fBsudoers\fR
+must look up any group name listed in the
 \fIsudoers\fR
-file, matching by group ID instead of by group name.
+file and use the group ID instead of the group name when determining
+whether the user is a member of the group.
+.sp
+Note that if
+\fImatch_group_by_gid\fR
+is enabled, group database lookups performed by
+\fBsudoers\fR
+will be keyed by group name as opposed to group ID.
+On systems where there are multiple sources for the group database,
+it is possible to have conflicting group names or group IDs in the local
+\fI/etc/group\fR
+file and the remote group database.
+On such systems, enabling or disabling
+\fImatch_group_by_gid\fR
+can be used to choose whether group database queries are performed
+by name (enabled) or ID (disabled), which may aid in working around
+group entry conflicts.
+.sp
 The
 \fImatch_group_by_gid\fR
 flag has no effect when

diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in
index c7748c3118f678b1314978d7278c0e3e28e5a908..433871557c5d3f0f3a69779b6fd40e7fd63c3598 100644 (file)
--- a/doc/sudoers.mdoc.in
+++ b/doc/sudoers.mdoc.in
@@ -19,7 +19,7 @@
 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
 .\"
-.Dd March 27, 2017
+.Dd April 11, 2017
 .Dt SUDOERS @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -2368,10 +2368,12 @@ This flag is
 .Em @mail_no_user@
 by default.
 .It match_group_by_gid
-By default, when matching groups,
+By default,
 .Nm
-will first resolve all the user's group IDs to group names and then
-compare those group names to any group names listed in the
+will look up each group the user is a member of by group ID to
+determine the group name (this is only done once).
+The resulting list of the user's group names is used when matching
+groups listed in the
 .Em sudoers
 file.
 This works well on systems where the number of groups listed in the
@@ -2387,10 +2389,29 @@ running commands via
 may take longer than normal.
 On such systems it may be faster to use the
 .Em match_group_by_gid
-flag to avoid resolving the user's group IDs to group names and
-instead resolve all group names listed in the
+flag to avoid resolving the user's group IDs to group names.
+In this case,
+.Nm
+must look up any group name listed in the
 .Em sudoers
-file, matching by group ID instead of by group name.
+file and use the group ID instead of the group name when determining
+whether the user is a member of the group.
+.Pp
+Note that if
+.Em match_group_by_gid
+is enabled, group database lookups performed by
+.Nm
+will be keyed by group name as opposed to group ID.
+On systems where there are multiple sources for the group database,
+it is possible to have conflicting group names or group IDs in the local
+.Pa /etc/group
+file and the remote group database.
+On such systems, enabling or disabling
+.Em match_group_by_gid
+can be used to choose whether group database queries are performed
+by name (enabled) or ID (disabled), which may aid in working around
+group entry conflicts.
+.Pp
 The
 .Em match_group_by_gid
 flag has no effect when