1SUDO.CONF(5) BSD File Formats Manual SUDO.CONF(5)
2
4 sudo.conf — configuration for sudo front end
5
7 The sudo.conf file is used to configure the sudo front end. It specifies
8 the security policy and I/O logging plugins, debug flags as well as
9 plugin-agnostic path names and settings.
10 The sudo.conf file supports the following directives, described in detail
12 below.
13 Plugin a security policy or I/O logging plugin
15 Path a plugin-agnostic path
17 Set a front end setting, such as disable_coredump or group_source
19 Debug debug flags to aid in debugging sudo, sudoreplay, visudo, and
21 the sudoers plugin.
22 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 Long lines can be continued with a backslash (‘\’) as the last character
27 on the line. Note that leading white space is removed from the beginning
28 of lines even when the continuation character is used.
29 Non-comment lines that don't begin with Plugin, Path, Debug, or Set are
31 silently ignored.
32 The sudo.conf file is always parsed in the “C” locale.
34 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 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 approval_plugin, audit_plugin, io_plugin,
44 or policy_plugin struct contained in the plugin. If a plugin implements
45 multiple plugin types, there must be a Plugin line for each unique symbol
46 name. The path may be fully qualified or relative. If not fully quali‐
47 fied, it is relative to the directory specified by the plugin_dir Path
48 setting, which defaults to /usr/libexec/sudo. In other words:
49 Plugin sudoers_policy sudoers.so
51 is equivalent to:
53 Plugin sudoers_policy /usr/libexec/sudo/sudoers.so
55 If the plugin was compiled statically into the sudo binary instead of be‐
57 ing installed as a dynamic shared object, the path should be specified
58 without a leading directory, as it does not actually exist in the file
59 system. For example:
60 Plugin sudoers_policy sudoers.so
62 Starting with sudo 1.8.5, any additional parameters after the path are
64 passed as arguments to the plugin's open function. For example, to over‐
65 ride the compile-time default sudoers file mode:
66 Plugin sudoers_policy sudoers.so sudoers_mode=0440
68 See the sudoers(5) manual for a list of supported arguments.
70 The same dynamic shared object may contain multiple plugins, each with a
72 different symbol name. The file must be owned by uid 0 and only writable
73 by its owner. Because of ambiguities that arise from composite policies,
74 only a single policy plugin may be specified. This limitation does not
75 apply to I/O plugins.
76 If no sudo.conf file is present, or if it contains no Plugin lines, the
78 sudoers plugin will be used as the default security policy, for I/O log‐
79 ging (if enabled by the policy) and for auditing. This is equivalent to
80 the following:
81 Plugin sudoers_policy sudoers.so
83 Plugin sudoers_io sudoers.so
84 Plugin sudoers_audit sudoers.so
85 Starting with sudo version 1.9.1, some of the logging functionality of
87 the sudoers plugin has been moved from the policy plugin to an audit
88 plugin. To maintain compatibility with sudo.conf files from older sudo
89 versions, if sudoers is configured as the security policy, it will be
90 used as an audit plugin as well. This guarantees that the logging behav‐
91 ior will be consistnet with that of sudo versions 1.9.0 and below.
92 For more information on the sudo plugin architecture, see the
94 sudo_plugin(5) manual.
95 Path settings
97 A Path line consists of the Path keyword, followed by the name of the
98 path to set and its value. For example:
99 Path intercept disabled
101 Path noexec /usr/libexec/sudo/sudo_noexec.so
102 Path askpass /usr/X11R6/bin/ssh-askpass
103 If no path name is specified, features relying on the specified setting
105 will be disabled. Disabling Path settings is only supported in sudo ver‐
106 sion 1.8.16 and higher.
107 The following plugin-agnostic paths may be set in the /etc/sudo.conf
109 file:
110 askpass The fully qualified path to a helper program used to read the
112 user's password when no terminal is available. This may be the
113 case when sudo is executed from a graphical (as opposed to
114 text-based) application. The program specified by askpass
115 should display the argument passed to it as the prompt and
116 write the user's password to the standard output. The value of
117 askpass may be overridden by the SUDO_ASKPASS environment vari‐
118 able.
119 devsearch
121 An ordered, colon-separated search path of directories to look
122 in for device nodes. This is used when mapping the process's
123 tty device number to a device name on systems that do not pro‐
124 vide such a mechanism. Sudo will not recurse into sub-directo‐
125 ries. If terminal devices may be located in a sub-directory of
126 /dev, that path must be explicitly listed in devsearch. The
127 default value is
128 /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev
129 This option is ignored on systems that support either the
131 devname() or _ttyname_dev() functions, for example BSD, macOS
132 and Solaris.
133 intercept
135 The fully-qualified path to a shared library containing a wrap‐
136 pers for the execl(), execle(), execlp(), execv(), execve(),
137 execvp(), and execvpe() library functions that intercepts at‐
138 tempts to run further commands and performs a policy check be‐
139 fore allowing them to be executed. This is used to implement
140 the intercept functionality on systems that support LD_PRELOAD
141 or its equivalent. The default value is disabled.
142 noexec The fully-qualified path to a shared library containing wrap‐
144 pers for the execl(), execle(), execlp(), exect(), execv(),
145 execve(), execveat(), execvP(), execvp(), execvpe(), fexecve(),
146 popen(), posix_spawn(), posix_spawnp(), system(), and wordexp()
147 library functions that prevent the execution of further com‐
148 mands. This is used to implement the noexec functionality on
149 systems that support LD_PRELOAD or its equivalent. The default
150 value is /usr/libexec/sudo/sudo_noexec.so.
151 plugin_dir
153 The default directory to use when searching for plugins that
154 are specified without a fully qualified path name. The default
155 value is /usr/libexec/sudo.
156 sesh The fully-qualified path to the sesh binary. This setting is
158 only used when sudo is built with SELinux support. The default
159 value is /usr/libexec/sudo/sesh.
160 Other settings
162 The sudo.conf file also supports the following front end settings:
163 disable_coredump
165 Core dumps of sudo itself are disabled by default to prevent
166 the disclosure of potentially sensitive information. To aid in
167 debugging sudo crashes, you may wish to re-enable core dumps by
168 setting “disable_coredump” to false in sudo.conf as follows:
169 Set disable_coredump false
171 All modern operating systems place restrictions on core dumps
173 from set-user-ID processes like sudo so this option can be en‐
174 abled without compromising security. To actually get a sudo
175 core file you will likely need to enable core dumps for set-
176 user-ID processes. On BSD and Linux systems this is accom‐
177 plished in the sysctl(8) command. On Solaris, the coreadm(1m)
178 command is used to configure core dump behavior.
179 This setting is only available in sudo version 1.8.4 and
181 higher.
182 developer_mode
184 By default sudo refuses to load plugins which can be modified
185 by other than the root user. The plugin should be owned by
186 root and write access permissions should be disabled for
187 “group” and “other”. To make development of a plugin easier,
188 you can disable that by setting “developer_mode” option to true
189 in sudo.conf as follows:
190 Set developer_mode true
192 Please note that this creates a security risk, so it is not
194 recommended on critical systems such as a desktop machine for
195 daily use, but is intended to be used in development environ‐
196 ments (VM, container, etc). Before enabling developer mode,
197 ensure you understand the implications.
198 This setting is only available in sudo version 1.9.0 and
200 higher.
201 group_source
203 sudo passes the invoking user's group list to the policy and
204 I/O plugins. On most systems, there is an upper limit to the
205 number of groups that a user may belong to simultaneously (typ‐
206 ically 16 for compatibility with NFS). On systems with the
207 getconf(1) utility, running:
208 getconf NGROUPS_MAX
209 will return the maximum number of groups.
210 However, it is still possible to be a member of a larger number
212 of groups--they simply won't be included in the group list re‐
213 turned by the kernel for the user. Starting with sudo version
214 1.8.7, if the user's kernel group list has the maximum number
215 of entries, sudo will consult the group database directly to
216 determine the group list. This makes it possible for the secu‐
217 rity policy to perform matching by group name even when the
218 user is a member of more than the maximum number of groups.
219 The group_source setting allows the administrator to change
221 this default behavior. Supported values for group_source are:
222 static Use the static group list that the kernel returns.
224 Retrieving the group list this way is very fast but
225 it is subject to an upper limit as described above.
226 It is “static” in that it does not reflect changes to
227 the group database made after the user logs in. This
228 was the default behavior prior to sudo 1.8.7.
229 dynamic Always query the group database directly. It is
231 “dynamic” in that changes made to the group database
232 after the user logs in will be reflected in the group
233 list. On some systems, querying the group database
234 for all of a user's groups can be time consuming when
235 querying a network-based group database. Most oper‐
236 ating systems provide an efficient method of perform‐
237 ing such queries. Currently, sudo supports efficient
238 group queries on AIX, BSD, HP-UX, Linux, macOS and
239 Solaris. This is the default behavior on macOS in
240 sudo 1.9.6 and higher.
241 adaptive Only query the group database if the static group
243 list returned by the kernel has the maximum number of
244 entries. This is the default behavior on systems
245 other than macOS in sudo 1.8.7 and higher.
246 For example, to cause sudo to only use the kernel's static list
248 of groups for the user:
249 Set group_source static
251 This setting is only available in sudo version 1.8.7 and
253 higher.
254 max_groups
256 The maximum number of user groups to retrieve from the group
257 database. Values less than one or larger than 1024 will be ig‐
258 nored. This setting is only used when querying the group data‐
259 base directly. It is intended to be used on systems where it
260 is not possible to detect when the array to be populated with
261 group entries is not sufficiently large. By default, sudo will
262 allocate four times the system's maximum number of groups (see
263 above) and retry with double that number if the group database
264 query fails.
265 This setting is only available in sudo version 1.8.7 and
267 higher. It should not be required in sudo versions 1.8.24 and
268 higher and may be removed in a later release.
269 probe_interfaces
271 By default, sudo will probe the system's network interfaces and
272 pass the IP address of each enabled interface to the policy
273 plugin. This makes it possible for the plugin to match rules
274 based on the IP address without having to query DNS. On Linux
275 systems with a large number of virtual interfaces, this may
276 take a non-negligible amount of time. If IP-based matching is
277 not required, network interface probing can be disabled as fol‐
278 lows:
279 Set probe_interfaces false
281 This setting is only available in sudo version 1.8.10 and
283 higher.
284 Debug settings
286 sudo versions 1.8.4 and higher support a flexible debugging framework
287 that can log what sudo is doing internally if there is a problem.
288 A Debug line consists of the Debug keyword, followed by the name of the
290 program, plugin or shared object to debug, the debug file name and a
291 comma-separated list of debug flags. The debug flag syntax used by sudo,
292 the sudoers plugin and its associated programs and shared objects is
293 subsystem@priority but a third-party plugin is free to use a different
294 format so long as it does not include a comma (‘,’).
295 Examples:
297 Debug sudo /var/log/sudo_debug all@warn,plugin@info
299 would log all debugging statements at the warn level and higher in addi‐
301 tion to those at the info level for the plugin subsystem.
302 Debug sudo_intercept.so /var/log/intercept_debug all@debug
304 would log all debugging statements, regardless of level, for the
306 sudo_intercept.so shared object that implements sudo's intercept func‐
307 tionality.
308 As of sudo 1.8.12, multiple Debug entries may be specified per program.
310 Older versions of sudo only support a single Debug entry per program.
311 Plugin-specific Debug entries are also supported starting with sudo
312 1.8.12 and are matched by either the base name of the plugin that was
313 loaded (for example sudoers.so) or by the plugin's fully-qualified path
314 name. Previously, the sudoers plugin shared the same Debug entry as the
315 sudo front end and could not be configured separately.
316 The following priorities are supported, in order of decreasing severity:
318 crit, err, warn, notice, diag, info, trace and debug. Each priority,
319 when specified, also includes all priorities higher than it. For exam‐
320 ple, a priority of notice would include debug messages logged at notice
321 and higher.
322 The priorities trace and debug also include function call tracing which
324 logs when a function is entered and when it returns. For example, the
325 following trace is for the get_user_groups() function located in
326 src/sudo.c:
327 sudo[123] -> get_user_groups @ src/sudo.c:385
329 sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5
330 When the function is entered, indicated by a right arrow ‘->’, the pro‐
332 gram, process ID, function, source file and line number are logged. When
333 the function returns, indicated by a left arrow ‘<-’, the same informa‐
334 tion is logged along with the return value. In this case, the return
335 value is a string.
336 The following subsystems are used by the sudo front-end:
338 all matches every subsystem
340 args command line argument processing
342 conv user conversation
344 edit sudoedit
346 event event subsystem
348 exec command execution
350 main sudo main function
352 netif network interface handling
354 pcomm communication with the plugin
356 plugin plugin configuration
358 pty pseudo-terminal related code
360 selinux SELinux-specific handling
362 util utility functions
364 utmp utmp handling
366 The sudoers(5) plugin includes support for additional subsystems.
368
370 /etc/sudo.conf sudo front end configuration
371
373 #
374 # Default /etc/sudo.conf file
375 #
376 # Sudo plugins:
377 # Plugin plugin_name plugin_path plugin_options ...
378 #
379 # The plugin_path is relative to /usr/libexec/sudo unless
380 # fully qualified.
381 # The plugin_name corresponds to a global symbol in the plugin
382 # that contains the plugin interface structure.
383 # The plugin_options are optional.
384 #
385 # The sudoers plugin is used by default if no Plugin lines are present.
386 #Plugin sudoers_policy sudoers.so
387 #Plugin sudoers_io sudoers.so
388 #Plugin sudoers_audit sudoers.so
389 #
391 # Sudo askpass:
392 # Path askpass /path/to/askpass
393 #
394 # An askpass helper program may be specified to provide a graphical
395 # password prompt for "sudo -A" support. Sudo does not ship with its
396 # own askpass program but can use the OpenSSH askpass.
397 #
398 # Use the OpenSSH askpass
399 #Path askpass /usr/X11R6/bin/ssh-askpass
400 #
401 # Use the Gnome OpenSSH askpass
402 #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
403 #
405 # Sudo device search path:
406 # Path devsearch /dev/path1:/dev/path2:/dev
407 #
408 # A colon-separated list of paths to check when searching for a user's
409 # terminal device.
410 #
411 #Path devsearch /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev
412 #
414 # Sudo command interception:
415 # Path intercept /path/to/sudo_intercept.so
416 #
417 # Path to a shared library containing replacements for the execv()
418 # and execve() library functions that perform a policy check to verify
419 # the command is allowed and simply return an error if not. This is
420 # used to implement the "intercept" functionality on systems that
421 # support LD_PRELOAD or its equivalent.
422 #
423 # The compiled-in value is usually sufficient and should only be changed
424 # if you rename or move the sudo_intercept.so file.
425 #
426 #Path intercept /usr/libexec/sudo/sudo_intercept.so
427 #
429 # Sudo noexec:
430 # Path noexec /path/to/sudo_noexec.so
431 #
432 # Path to a shared library containing replacements for the execv()
433 # family of library functions that just return an error. This is
434 # used to implement the "noexec" functionality on systems that support
435 # LD_PRELOAD or its equivalent.
436 #
437 # The compiled-in value is usually sufficient and should only be changed
438 # if you rename or move the sudo_noexec.so file.
439 #
440 #Path noexec /usr/libexec/sudo/sudo_noexec.so
441 #
443 # Sudo plugin directory:
444 # Path plugin_dir /path/to/plugins
445 #
446 # The default directory to use when searching for plugins that are
447 # specified without a fully qualified path name.
448 #
449 #Path plugin_dir /usr/libexec/sudo
450 #
452 # Sudo developer mode:
453 # Set developer_mode true|false
454 #
455 # Allow loading of plugins that are owned by non-root or are writable
456 # by "group" or "other". Should only be used during plugin development.
457 #Set developer_mode true
458 #
460 # Core dumps:
461 # Set disable_coredump true|false
462 #
463 # By default, sudo disables core dumps while it is executing (they
464 # are re-enabled for the command that is run).
465 # To aid in debugging sudo problems, you may wish to enable core
466 # dumps by setting "disable_coredump" to false.
467 #
468 #Set disable_coredump false
469 #
471 # User groups:
472 # Set group_source static|dynamic|adaptive
473 #
474 # Sudo passes the user's group list to the policy plugin.
475 # If the user is a member of the maximum number of groups (usually 16),
476 # sudo will query the group database directly to be sure to include
477 # the full list of groups.
478 #
479 # On some systems, this can be expensive so the behavior is configurable.
480 # The "group_source" setting has three possible values:
481 # static - use the user's list of groups returned by the kernel.
482 # dynamic - query the group database to find the list of groups.
483 # adaptive - if user is in less than the maximum number of groups.
484 # use the kernel list, else query the group database.
485 #
486 #Set group_source static
487 #
489 # Sudo interface probing:
490 # Set probe_interfaces true|false
491 #
492 # By default, sudo will probe the system's network interfaces and
493 # pass the IP address of each enabled interface to the policy plugin.
494 # On systems with a large number of virtual interfaces this may take
495 # a noticeable amount of time.
496 #
497 #Set probe_interfaces false
498 #
500 # Sudo debug files:
501 # Debug program /path/to/debug_log subsystem@priority[,subsyste@priority]
502 #
503 # Sudo and related programs support logging debug information to a file.
504 # The program is typically sudo, sudoers.so, sudoreplay or visudo.
505 #
506 # Subsystems vary based on the program; "all" matches all subsystems.
507 # Priority may be crit, err, warn, notice, diag, info, trace or debug.
508 # Multiple subsystem@priority may be specified, separated by a comma.
509 #
510 #Debug sudo /var/log/sudo_debug all@debug
511 #Debug sudoers.so /var/log/sudoers_debug all@debug
512
514 sudo_plugin(5), sudoers(5), sudo(8)
515
517 See the HISTORY file in the sudo distribution (https://www.sudo.ws/his‐
518 tory.html) for a brief history of sudo.
519
521 Many people have worked on sudo over the years; this version consists of
522 code written primarily by:
523 Todd C. Miller
525 See the CONTRIBUTORS file in the sudo distribution
527 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
528 who have contributed to sudo.
529
531 If you feel you have found a bug in sudo, please submit a bug report at
532 https://bugzilla.sudo.ws/
533
535 Limited free support is available via the sudo-users mailing list, see
536 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
537 the archives.
538
540 sudo is provided “AS IS” and any express or implied warranties, includ‐
541 ing, but not limited to, the implied warranties of merchantability and
542 fitness for a particular purpose are disclaimed. See the LICENSE file
543 distributed with sudo or https://www.sudo.ws/license.html for complete
544 details.
545Sudo 1.9.8p2 September 7, 2021 Sudo 1.9.8p2