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 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
372 /etc/sudo.conf sudo front-end configuration
373
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
516 sudo_plugin(5), sudoers(5), sudo(8)
517
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
529 If you believe you have found a bug in sudo, you can submit a bug report
530 at https://bugzilla.sudo.ws/
531
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
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