Document match_group_by_gid

NEWS

@@ -46,6 +46,11 @@ What's new in Sudo 1.8.18
    was runnable even when denied by sudoers when using the LDAP or
    SSSD backends.
 
+ * The match_group_by_gid Defaults option has been added to allow
+   sites where group name resolution is slow and where sudoers only
+   contains a small number of groups to match groups by group ID
+   instead of by group name.
+
 What's new in Sudo 1.8.17p1
 
  * Fixed a bug introduced in 1.8.17 where the user's groups were

doc/sudoers.cat

@@ -1133,6 +1133,24 @@ SSUUDDOOEERRSS OOPPTTIIOONNSS
                        invoking user is not in the _s_u_d_o_e_r_s file.  This flag is
                        _o_n by default.
 
+     match_group_by_gid
+                       By default, when matching groups, ssuuddooeerrss 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 _s_u_d_o_e_r_s file.  This works well on systems
+                       where the number of groups listed in the _s_u_d_o_e_r_s 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 _s_u_d_o_e_r_s file
+                       is relatively small, it may be prohibitively expensive
+                       and running commands via ssuuddoo may take longer than
+                       normal.  On such systems it may be faster to use the
+                       _m_a_t_c_h___g_r_o_u_p___b_y___g_i_d flag to avoid resolving the user's
+                       group IDs to group names and instead resolve all group
+                       names listed in the _s_u_d_o_e_r_s file, matching by group ID
+                       instead of by group name.  This flag is _o_f_f by default.
+
      netgroup_tuple    If set, netgroup lookups will be performed using the
                        full netgroup tuple: host name, user name and domain
                        (if one is set).  Historically, ssuuddoo only matched the
@@ -2569,4 +2587,4 @@ DDIISSCCLLAAIIMMEERR
      file distributed with ssuuddoo or https://www.sudo.ws/license.html for
      complete details.
 
-Sudo 1.8.18                     August 17, 2016                    Sudo 1.8.18
+Sudo 1.8.18                     August 30, 2016                    Sudo 1.8.18

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" "August 17, 2016" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDOERS" "5" "August 30, 2016" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -2412,6 +2412,34 @@ This flag is
 \fI@mail_no_user@\fR
 by default.
 .TP 18n
+match_group_by_gid
+By default, when matching groups,
+\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
+\fIsudoers\fR
+file.
+This works well on systems where the number of groups listed in the
+\fIsudoers\fR
+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
+\fIsudoers\fR
+file is relatively small, it may be prohibitively expensive and
+running commands via
+\fBsudo\fR
+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
+\fIsudoers\fR
+file, matching by group ID instead of by group name.
+This flag is
+\fIoff\fR
+by default.
+.TP 18n
 netgroup_tuple
 If set, netgroup lookups will be performed using the full netgroup
 tuple: host name, user name and domain (if one is set).

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 August 17, 2016
+.Dd August 30, 2016
 .Dt SUDOERS @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -2258,6 +2258,33 @@ file.
 This flag is
 .Em @mail_no_user@
 by default.
+.It match_group_by_gid
+By default, when matching groups,
+.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
+.Em sudoers
+file.
+This works well on systems where the number of groups listed in the
+.Em sudoers
+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
+.Em sudoers
+file is relatively small, it may be prohibitively expensive and
+running commands via
+.Nm sudo
+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
+.Em sudoers
+file, matching by group ID instead of by group name.
+This flag is
+.Em off
+by default.
 .It netgroup_tuple
 If set, netgroup lookups will be performed using the full netgroup
 tuple: host name, user name and domain (if one is set).