1SUDO.CONF(5)                BSD File Formats Manual               SUDO.CONF(5)
2

NAME

4     sudo.conf — configuration for sudo front-end
5

DESCRIPTION

7     The sudo.conf file is used to configure the sudo front-end.  It is used
8     to configure sudo plugins, plugin-agnostic path names, debug flags, and
9     other settings.
10
11     The sudo.conf file supports the following directives, described in detail
12     below.
13
14     Plugin    an approval, audit, I/O logging, or security policy plugin
15
16     Path      a plugin-agnostic path
17
18     Set       a front-end setting, such as disable_coredump or group_source
19
20     Debug     debug flags to aid in debugging sudo, sudoreplay, visudo, and
21               the sudoers plugin.
22
23     The pound sign (‘#’) is used to indicate a comment.  Both the comment
24     character and any text after it, up to the end of the line, are ignored.
25
26     Long lines can be continued with a backslash (‘\’) as the last character
27     on the line.  Leading white space is removed from the beginning of lines
28     even when a continuation character is used.
29
30     Non-comment lines that don't begin with Plugin, Path, Debug, or Set are
31     silently ignored.
32
33     The sudo.conf file is always parsed in the ‘C’ locale.
34
35   Plugin configuration
36     sudo supports a plugin architecture for security policies and input/out‐
37     put logging.  Third parties can develop and distribute their own policy
38     and I/O logging plugins to work seamlessly with the sudo front-end.
39     Plugins are dynamically loaded based on the contents of sudo.conf.
40
41     A Plugin line consists of the Plugin keyword, followed by the symbol_name
42     and the path to the dynamic shared object that contains the plugin.  The
43     symbol_name is the name of the struct approval_plugin, struct
44     audit_plugin, struct io_plugin, or struct policy_plugin defined by the
45     plugin.  If a plugin implements multiple plugin types, there must be a
46     Plugin line for each unique symbol name.  The path may be fully qualified
47     or relative.  If not fully qualified, it is relative to the directory
48     specified by the plugin_dir Path setting, which defaults to
49     /usr/libexec/sudo.  In other words:
50
51         Plugin sudoers_policy sudoers.so
52
53     is equivalent to:
54
55         Plugin sudoers_policy /usr/libexec/sudo/sudoers.so
56
57     If the plugin was compiled statically into the sudo binary instead of be‐
58     ing installed as a dynamic shared object, the path should be specified
59     without a leading directory, as it does not actually exist in the file
60     system.  For example:
61
62         Plugin sudoers_policy sudoers.so
63
64     Starting with sudo 1.8.5, any additional parameters after the path are
65     passed as arguments to the plugin's open function.  For example, to over‐
66     ride the compile-time default sudoers file mode:
67
68         Plugin sudoers_policy sudoers.so sudoers_mode=0440
69
70     See the sudoers(5) manual for a list of supported arguments.
71
72     The same dynamic shared object may contain multiple plugins, each with a
73     different symbol name.  The file must be owned by user-ID 0 and only
74     writable by its owner.  Because of ambiguities that arise from composite
75     policies, only a single policy plugin may be specified.  This limitation
76     does not apply to I/O plugins.
77
78     If no sudo.conf file is present, or if it contains no Plugin lines, the
79     sudoers plugin will be used as the default security policy, for I/O log‐
80     ging (if enabled by the policy), and for auditing.  This is equivalent to
81     the following:
82
83         Plugin sudoers_policy sudoers.so
84         Plugin sudoers_io sudoers.so
85         Plugin sudoers_audit sudoers.so
86
87     Starting with sudo version 1.9.1, some of the logging functionality of
88     the sudoers plugin has been moved from the policy plugin to an audit
89     plugin.  To maintain compatibility with sudo.conf files from older sudo
90     versions, if sudoers is configured as the security policy, it will be
91     used as an audit plugin as well.  This guarantees that the logging behav‐
92     ior will be consistnet with that of sudo versions 1.9.0 and below.
93
94     For more information on the sudo plugin architecture, see the
95     sudo_plugin(5) manual.
96
97   Path settings
98     A Path line consists of the Path keyword, followed by the name of the
99     path to set and its value.  For example:
100
101         Path intercept disabled
102         Path noexec /usr/libexec/sudo/sudo_noexec.so
103         Path askpass /usr/X11R6/bin/ssh-askpass
104
105     If no path name is specified, features relying on the specified setting
106     will be disabled.  Disabling Path settings is only supported in sudo ver‐
107     sion 1.8.16 and higher.
108
109     The following plugin-agnostic paths may be set in the /etc/sudo.conf
110     file:
111
112     askpass   The fully qualified path to a helper program used to read the
113               user's password when no terminal is available.  This may be the
114               case when sudo is executed from a graphical (as opposed to
115               text-based) application.  The program specified by askpass
116               should display the argument passed to it as the prompt and
117               write the user's password to the standard output.  The value of
118               askpass may be overridden by the SUDO_ASKPASS environment vari‐
119               able.
120
121     devsearch
122               An ordered, colon-separated search path of directories to look
123               in for device nodes.  This is used when mapping the process's
124               tty device number to a device name on systems that do not pro‐
125               vide such a mechanism.  Sudo will not recurse into sub-directo‐
126               ries.  If terminal devices may be located in a sub-directory of
127               /dev, that path must be explicitly listed in devsearch.  The
128               default value is
129               /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev
130
131               This option is ignored on systems that support either the
132               devname() or _ttyname_dev() functions, for example BSD, macOS
133               and Solaris.
134
135     intercept
136               The fully-qualified path to a shared library containing a wrap‐
137               pers for the execve(2), execl(3), execle(3), execlp(3),
138               execv(3), execvp(3), execvpe(3), and system(3) library func‐
139               tions that intercepts attempts to run further commands and per‐
140               forms a policy check before allowing them to be executed.  This
141               is used to implement the intercept functionality on systems
142               that support LD_PRELOAD or its equivalent.  The default value
143               is disabled.
144
145     noexec    The fully-qualified path to a shared library containing wrap‐
146               pers for the execve(2), execl(3), execle(3), execlp(3),
147               exect(3), execv(3), execveat(3), execvP(3), execvp(3),
148               execvpe(3), fexecve(3), popen(3), posix_spawn(3),
149               posix_spawnp(3), system(3), and wordexp(3) library functions
150               that prevent the execution of further commands.  This is used
151               to implement the noexec functionality on systems that support
152               LD_PRELOAD or its equivalent.  The default value is
153               /usr/libexec/sudo/sudo_noexec.so.
154
155     plugin_dir
156               The default directory to use when searching for plugins that
157               are specified without a fully qualified path name.  The default
158               value is /usr/libexec/sudo.
159
160     sesh      The fully-qualified path to the sesh binary.  This setting is
161               only used when sudo is built with SELinux support.  The default
162               value is /usr/libexec/sudo/sesh.
163
164   Other settings
165     The sudo.conf file also supports the following front-end settings:
166
167     disable_coredump
168               Core dumps of sudo itself are disabled by default to prevent
169               the disclosure of potentially sensitive information.  To aid in
170               debugging sudo crashes, you may wish to re-enable core dumps by
171               setting “disable_coredump” to false in sudo.conf as follows:
172
173                   Set disable_coredump false
174
175               All modern operating systems place restrictions on core dumps
176               from set-user-ID processes like sudo so this option can be en‐
177               abled without compromising security.  To actually get a sudo
178               core file you will likely need to enable core dumps for set-
179               user-ID processes.  On BSD and Linux systems this is accom‐
180               plished in the sysctl(8) command.  On Solaris, the coreadm(1m)
181               command is used to configure core dump behavior.
182
183               This setting is only available in sudo version 1.8.4 and
184               higher.
185
186     developer_mode
187               By default sudo refuses to load plugins which can be modified
188               by other than the root user.  The plugin should be owned by
189               root and write access permissions should be disabled for
190               “group” and “other”.  To make development of a plugin easier,
191               you can disable that by setting “developer_mode” option to true
192               in sudo.conf as follows:
193
194                   Set developer_mode true
195
196               This creates a security risk and is not recommended for produc‐
197               tion systems, it is intended to be used in a development envi‐
198               ronment (VM, container, etc).  Before enabling developer mode,
199               be sure that you understand the implications.
200
201               This setting is only available in sudo version 1.9.0 and
202               higher.
203
204     group_source
205               sudo passes the invoking user's group list to the policy and
206               I/O plugins.  On most systems, there is an upper limit to the
207               number of groups that a user may belong to simultaneously (typ‐
208               ically 16 for compatibility with NFS).  On systems with the
209               getconf(1) utility, running:
210                     getconf NGROUPS_MAX
211               will return the maximum number of groups.
212
213               However, it is still possible to be a member of a larger number
214               of groups--they simply won't be included in the group list re‐
215               turned by the kernel for the user.  Starting with sudo version
216               1.8.7, if the user's kernel group list has the maximum number
217               of entries, sudo will consult the group database directly to
218               determine the group list.  This makes it possible for the secu‐
219               rity policy to perform matching by group name even when the
220               user is a member of more than the maximum number of groups.
221
222               The group_source setting allows the administrator to change
223               this default behavior.  Supported values for group_source are:
224
225               static    Use the static group list that the kernel returns.
226                         Retrieving the group list this way is very fast but
227                         it is subject to an upper limit as described above.
228                         It is “static” in that it does not reflect changes to
229                         the group database made after the user logs in.  This
230                         was the default behavior prior to sudo 1.8.7.
231
232               dynamic   Always query the group database directly.  It is
233                         “dynamic” in that changes made to the group database
234                         after the user logs in will be reflected in the group
235                         list.  On some systems, querying the group database
236                         for all of a user's groups can be time consuming when
237                         querying a network-based group database.  Most oper‐
238                         ating systems provide an efficient method of perform‐
239                         ing such queries.  Currently, sudo supports efficient
240                         group queries on AIX, BSD, HP-UX, Linux, macOS, and
241                         Solaris.  This is the default behavior on macOS in
242                         sudo 1.9.6 and higher.
243
244               adaptive  Only query the group database if the static group
245                         list returned by the kernel has the maximum number of
246                         entries.  This is the default behavior on systems
247                         other than macOS in sudo 1.8.7 and higher.
248
249               For example, to cause sudo to only use the kernel's static list
250               of groups for the user:
251
252                   Set group_source static
253
254               This setting is only available in sudo version 1.8.7 and
255               higher.
256
257     max_groups
258               The maximum number of user groups to retrieve from the group
259               database.  Values less than one or larger than 1024 will be ig‐
260               nored.  This setting is only used when querying the group data‐
261               base directly.  It is intended to be used on systems where it
262               is not possible to detect when the array to be populated with
263               group entries is not sufficiently large.  By default, sudo will
264               allocate four times the system's maximum number of groups (see
265               above) and retry with double that number if the group database
266               query fails.
267
268               This setting is only available in sudo version 1.8.7 and
269               higher.  It should not be required in sudo versions 1.8.24 and
270               higher and may be removed in a later release.
271
272     probe_interfaces
273               By default, sudo will probe the system's network interfaces and
274               pass the IP address of each enabled interface to the policy
275               plugin.  This makes it possible for the plugin to match rules
276               based on the IP address without having to query DNS.  On Linux
277               systems with a large number of virtual interfaces, this may
278               take a non-negligible amount of time.  If IP-based matching is
279               not required, network interface probing can be disabled as fol‐
280               lows:
281
282                   Set probe_interfaces false
283
284               This setting is only available in sudo version 1.8.10 and
285               higher.
286
287   Debug settings
288     sudo versions 1.8.4 and higher support a flexible debugging framework
289     that can log what sudo is doing internally if there is a problem.
290
291     A Debug line consists of the Debug keyword, followed by the name of the
292     program, plugin, or shared object to debug, the debug file name, and a
293     comma-separated list of debug flags.  The debug flag syntax used by sudo,
294     the sudoers plugin along with its associated programs and shared objects
295     is subsystem@priority but a third-party plugin is free to use a different
296     format so long as it does not include a comma (‘,’).
297
298     Examples:
299
300         Debug sudo /var/log/sudo_debug all@warn,plugin@info
301
302     would log all debugging statements at the warn level and higher in addi‐
303     tion to those at the info level for the plugin subsystem.
304
305         Debug sudo_intercept.so /var/log/intercept_debug all@debug
306
307     would log all debugging statements, regardless of level, for the
308     sudo_intercept.so shared library that implements sudo's intercept func‐
309     tionality on some systems.
310
311     As of sudo 1.8.12, multiple Debug entries may be specified per program.
312     Older versions of sudo only support a single Debug entry per program.
313     Plugin-specific Debug entries are also supported starting with sudo
314     1.8.12 and are matched by either the base name of the plugin that was
315     loaded (for example sudoers.so) or by the plugin's fully-qualified path
316     name.  Previously, the sudoers plugin shared the same Debug entry as the
317     sudo front-end and could not be configured separately.
318
319     The following priorities are supported, in order of decreasing severity:
320     crit, err, warn, notice, diag, info, trace, and debug.  Each priority,
321     when specified, also includes all priorities higher than it.  For exam‐
322     ple, a priority of notice would include debug messages logged at notice
323     and higher.
324
325     The priorities trace and debug also include function call tracing which
326     logs when a function is entered and when it returns.  For example, the
327     following trace is for the get_user_groups() function located in
328     src/sudo.c:
329
330         sudo[123] -> get_user_groups @ src/sudo.c:385
331         sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5
332
333     When the function is entered, indicated by a right arrow ‘->’, the pro‐
334     gram, process ID, function, source file, and line number are logged.
335     When the function returns, indicated by a left arrow ‘<-’, the same in‐
336     formation is logged along with the return value.  In this case, the re‐
337     turn value is a string.
338
339     The following subsystems are used by the sudo front-end:
340
341     all         matches every subsystem
342
343     args        command line argument processing
344
345     conv        user conversation
346
347     edit        sudoedit
348
349     event       event subsystem
350
351     exec        command execution
352
353     main        sudo main function
354
355     netif       network interface handling
356
357     pcomm       communication with the plugin
358
359     plugin      plugin configuration
360
361     pty         pseudo-terminal related code
362
363     selinux     SELinux-specific handling
364
365     util        utility functions
366
367     utmp        utmp handling
368
369     The sudoers(5) plugin includes support for additional subsystems.
370

FILES

372     /etc/sudo.conf            sudo front-end configuration
373

EXAMPLES

375     #
376     # Default /etc/sudo.conf file
377     #
378     # Sudo plugins:
379     #   Plugin plugin_name plugin_path plugin_options ...
380     #
381     # The plugin_path is relative to /usr/libexec/sudo unless
382     #   fully qualified.
383     # The plugin_name corresponds to a global symbol in the plugin
384     #   that contains the plugin interface structure.
385     # The plugin_options are optional.
386     #
387     # The sudoers plugin is used by default if no Plugin lines are present.
388     #Plugin sudoers_policy sudoers.so
389     #Plugin sudoers_io sudoers.so
390     #Plugin sudoers_audit sudoers.so
391
392     #
393     # Sudo askpass:
394     #   Path askpass /path/to/askpass
395     #
396     # An askpass helper program may be specified to provide a graphical
397     # password prompt for "sudo -A" support.  Sudo does not ship with its
398     # own askpass program but can use the OpenSSH askpass.
399     #
400     # Use the OpenSSH askpass
401     #Path askpass /usr/X11R6/bin/ssh-askpass
402     #
403     # Use the Gnome OpenSSH askpass
404     #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
405
406     #
407     # Sudo device search path:
408     #   Path devsearch /dev/path1:/dev/path2:/dev
409     #
410     # A colon-separated list of paths to check when searching for a user's
411     # terminal device.
412     #
413     #Path devsearch /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev
414
415     #
416     # Sudo command interception:
417     #   Path intercept /path/to/sudo_intercept.so
418     #
419     # Path to a shared library containing replacements for the execv()
420     # and execve() library functions that perform a policy check to verify
421     # the command is allowed and simply return an error if not.  This is
422     # used to implement the "intercept" functionality on systems that
423     # support LD_PRELOAD or its equivalent.
424     #
425     # The compiled-in value is usually sufficient and should only be changed
426     # if you rename or move the sudo_intercept.so file.
427     #
428     #Path intercept /usr/libexec/sudo/sudo_intercept.so
429
430     #
431     # Sudo noexec:
432     #   Path noexec /path/to/sudo_noexec.so
433     #
434     # Path to a shared library containing replacements for the execv()
435     # family of library functions that just return an error.  This is
436     # used to implement the "noexec" functionality on systems that support
437     # LD_PRELOAD or its equivalent.
438     #
439     # The compiled-in value is usually sufficient and should only be changed
440     # if you rename or move the sudo_noexec.so file.
441     #
442     #Path noexec /usr/libexec/sudo/sudo_noexec.so
443
444     #
445     # Sudo plugin directory:
446     #   Path plugin_dir /path/to/plugins
447     #
448     # The default directory to use when searching for plugins that are
449     # specified without a fully qualified path name.
450     #
451     #Path plugin_dir /usr/libexec/sudo
452
453     #
454     # Sudo developer mode:
455     #   Set developer_mode true|false
456     #
457     # Allow loading of plugins that are owned by non-root or are writable
458     # by "group" or "other".  Should only be used during plugin development.
459     #Set developer_mode true
460
461     #
462     # Core dumps:
463     #   Set disable_coredump true|false
464     #
465     # By default, sudo disables core dumps while it is executing (they
466     # are re-enabled for the command that is run).
467     # To aid in debugging sudo problems, you may wish to enable core
468     # dumps by setting "disable_coredump" to false.
469     #
470     #Set disable_coredump false
471
472     #
473     # User groups:
474     #   Set group_source static|dynamic|adaptive
475     #
476     # Sudo passes the user's group list to the policy plugin.
477     # If the user is a member of the maximum number of groups (usually 16),
478     # sudo will query the group database directly to be sure to include
479     # the full list of groups.
480     #
481     # On some systems, this can be expensive so the behavior is configurable.
482     # The "group_source" setting has three possible values:
483     #   static   - use the user's list of groups returned by the kernel.
484     #   dynamic  - query the group database to find the list of groups.
485     #   adaptive - if user is in less than the maximum number of groups.
486     #              use the kernel list, else query the group database.
487     #
488     #Set group_source static
489
490     #
491     # Sudo interface probing:
492     #   Set probe_interfaces true|false
493     #
494     # By default, sudo will probe the system's network interfaces and
495     # pass the IP address of each enabled interface to the policy plugin.
496     # On systems with a large number of virtual interfaces this may take
497     # a noticeable amount of time.
498     #
499     #Set probe_interfaces false
500
501     #
502     # Sudo debug files:
503     #   Debug program /path/to/debug_log subsystem@priority[,subsyste@priority]
504     #
505     # Sudo and related programs support logging debug information to a file.
506     # The program is typically sudo, sudoers.so, sudoreplay, or visudo.
507     #
508     # Subsystems vary based on the program; "all" matches all subsystems.
509     # Priority may be crit, err, warn, notice, diag, info, trace, or debug.
510     # Multiple subsystem@priority may be specified, separated by a comma.
511     #
512     #Debug sudo /var/log/sudo_debug all@debug
513     #Debug sudoers.so /var/log/sudoers_debug all@debug
514

SEE ALSO

516     sudo_plugin(5), sudoers(5), sudo(8)
517

AUTHORS

519     Many people have worked on sudo over the years; this version consists of
520     code written primarily by:
521
522           Todd C. Miller
523
524     See the CONTRIBUTORS.md file in the sudo distribution
525     (https://www.sudo.ws/about/contributors/) for an exhaustive list of peo‐
526     ple who have contributed to sudo.
527

BUGS

529     If you believe you have found a bug in sudo, you can submit a bug report
530     at https://bugzilla.sudo.ws/
531

SUPPORT

533     Limited free support is available via the sudo-users mailing list, see
534     https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
535     the archives.
536

DISCLAIMER

538     sudo is provided “AS IS” and any express or implied warranties, includ‐
539     ing, but not limited to, the implied warranties of merchantability and
540     fitness for a particular purpose are disclaimed.  See the LICENSE.md file
541     distributed with sudo or https://www.sudo.ws/about/license/ for complete
542     details.
543
544Sudo 1.9.12p2                    May 31, 2022                    Sudo 1.9.12p2
Impressum