1: .\"
2: .\" Copyright (c) 2010-2014 Todd C. Miller <Todd.Miller@courtesan.com>
3: .\"
4: .\" Permission to use, copy, modify, and distribute this software for any
5: .\" purpose with or without fee is hereby granted, provided that the above
6: .\" copyright notice and this permission notice appear in all copies.
7: .\"
8: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
16: .\"
17: .Dd January 22, 2014
18: .Dt SUDO @mansectform@
19: .Os Sudo @PACKAGE_VERSION@
20: .Sh NAME
21: .Nm sudo.conf
22: .Nd configuration for sudo front end
23: .Sh DESCRIPTION
24: The
25: .Nm sudo.conf
26: file is used to configure the
27: .Nm sudo
28: front end.
29: It specifies the security policy and I/O logging plugins, debug flags
30: as well as plugin-agnostic path names and settings.
31: .Pp
32: The
33: .Nm sudo.conf
34: file supports the following directives, described in detail below.
35: .Bl -tag -width 8n
36: .It Plugin
37: a security policy or I/O logging plugin
38: .It Path
39: a plugin-agnostic path
40: .It Set
41: a front end setting, such as
42: .Em disable_coredump
43: or
44: .Em group_source
45: .It Debug
46: debug flags to aid in debugging
47: .Nm sudo ,
48: .Nm sudoreplay ,
49: .Nm visudo ,
50: and the
51: .Nm sudoers
52: plugin.
53: .El
54: .Pp
55: The pound sign
56: .Pq Ql #
57: is used to indicate a comment.
58: Both the comment character and any text after it, up to the end of
59: the line, are ignored.
60: .Pp
61: Long lines can be continued with a backslash
62: .Pq Ql \e
63: as the last character on the line.
64: Note that leading white space is removed from the beginning of lines
65: even when the continuation character is used.
66: .Pp
67: Non-comment lines that don't begin with
68: .Li Plugin ,
69: .Li Path ,
70: .Li Debug ,
71: or
72: .Li Set
73: are silently ignored.
74: .Pp
75: The
76: .Nm sudo.conf
77: file is always parsed in the
78: .Dq Li C
79: locale.
80: .Ss Plugin configuration
81: .Nm sudo
82: supports a plugin architecture for security policies and input/output
83: logging.
84: Third parties can develop and distribute their own policy and I/O
85: logging plugins to work seamlessly with the
86: .Nm sudo
87: front end.
88: Plugins are dynamically loaded based on the contents of
89: .Nm sudo.conf .
90: .Pp
91: A
92: .Li Plugin
93: line consists of the
94: .Li Plugin
95: keyword, followed by the
96: .Em symbol_name
97: and the
98: .Em path
99: to the dynamic shared object that contains the plugin.
100: The
101: .Em symbol_name
102: is the name of the
103: .Li struct policy_plugin
104: or
105: .Li struct io_plugin
106: symbol contained in the plugin.
107: The
108: .Em path
109: may be fully qualified or relative.
110: If not fully qualified, it is relative to the directory
111: specified by the
112: .Em plugin_dir
113: .Li Path
114: setting, which defaults to
115: .Pa @PLUGINDIR@ .
116: In other words:
117: .Bd -literal -offset indent
118: Plugin sudoers_policy sudoers.so
119: .Ed
120: .Pp
121: is equivalent to:
122: .Bd -literal -offset indent
123: Plugin sudoers_policy @PLUGINDIR@/sudoers.so
124: .Ed
125: .Pp
126: If the plugin was compiled statically into the
127: .Nm sudo
128: binary instead of being installed as a dynamic shared object, the
129: .Em path
130: should be specified without a leading directory,
131: as it does not actually exist in the file system.
132: For example:
133: .Bd -literal -offset indent
134: Plugin sudoers_policy sudoers.so
135: .Ed
136: .Pp
137: Starting with
138: .Nm sudo
139: 1.8.5, any additional parameters after the
140: .Em path
141: are passed as arguments to the plugin's
142: .Em open
143: function.
144: For example, to override the compile-time default sudoers file mode:
145: .Bd -literal -offset indent
146: Plugin sudoers_policy sudoers.so sudoers_mode=0440
147: .Ed
148: .Pp
149: The same dynamic shared object may contain multiple plugins,
150: each with a different symbol name.
151: The file must be owned by uid 0 and only writable by its owner.
152: Because of ambiguities that arise from composite policies, only a single
153: policy plugin may be specified.
154: This limitation does not apply to I/O plugins.
155: .Pp
156: If no
157: .Nm sudo.conf
158: file is present, or if it contains no
159: .Li Plugin
160: lines, the
161: .Nm sudoers
162: plugin will be used as the default security policy and for I/O logging
163: (if enabled by the policy).
164: This is equivalent to the following:
165: .Bd -literal -offset indent
166: Plugin sudoers_policy sudoers.so
167: Plugin sudoers_io sudoers.so
168: .Ed
169: .Pp
170: For more information on the
171: .Nm sudo
172: plugin architecture, see the
173: .Xr sudo_plugin @mansectsu@
174: manual.
175: .Ss Path settings
176: A
177: .Li Path
178: line consists of the
179: .Li Path
180: keyword, followed by the name of the path to set and its value.
181: For example:
182: .Bd -literal -offset indent
183: Path noexec @noexec_file@
184: Path askpass /usr/X11R6/bin/ssh-askpass
185: .Ed
186: .Pp
187: The following plugin-agnostic paths may be set in the
188: .Pa @sysconfdir@/sudo.conf
189: file:
190: .Bl -tag -width 8n
191: .It askpass
192: The fully qualified path to a helper program used to read the user's
193: password when no terminal is available.
194: This may be the case when
195: .Nm sudo
196: is executed from a graphical (as opposed to text-based) application.
197: The program specified by
198: .Em askpass
199: should display the argument passed to it as the prompt and write
200: the user's password to the standard output.
201: The value of
202: .Em askpass
203: may be overridden by the
204: .Ev SUDO_ASKPASS
205: environment variable.
206: .It noexec
207: The fully-qualified path to a shared library containing dummy
208: versions of the
209: .Fn execv ,
210: .Fn execve
211: and
212: .Fn fexecve
213: library functions that just return an error.
214: This is used to implement the
215: .Em noexec
216: functionality on systems that support
217: .Ev LD_PRELOAD
218: or its equivalent.
219: The default value is:
220: .Pa @noexec_file@ .
221: .It plugin_dir
222: The default directory to use when searching for plugins
223: that are specified without a fully qualified path name.
224: The default value is
225: .Pa @PLUGINDIR@ .
226: .It sesh
227: The fully-qualified path to the
228: .Nm sesh
229: binary.
230: This setting is only used when
231: .Nm sudo
232: is built with SELinux support.
233: The default value is
234: .Pa @sesh_file@ .
235: .El
236: .Ss Other settings
237: The
238: .Nm sudo.conf
239: file also supports the following front end settings:
240: .Bl -tag -width 8n
241: .It disable_coredump
242: Core dumps of
243: .Nm sudo
244: itself are disabled by default.
245: To aid in debugging
246: .Nm sudo
247: crashes, you may wish to re-enable core dumps by setting
248: .Dq disable_coredump
249: to false in
250: .Nm sudo.conf
251: as follows:
252: .Bd -literal -offset indent
253: Set disable_coredump false
254: .Ed
255: .Pp
256: Note that most operating systems disable core dumps from setuid programs,
257: including
258: .Nm sudo .
259: To actually get a
260: .Nm sudo
261: core file you will likely need to enable core dumps for setuid processes.
262: On BSD and Linux systems this is accomplished in the
263: .Xr sysctl
264: command.
265: On Solaris, the
266: .Xr coreadm
267: command is used to configure core dump behavior.
268: .Pp
269: This setting is only available in
270: .Nm sudo
271: version 1.8.4 and higher.
272: .It group_source
273: .Nm sudo
274: passes the invoking user's group list to the policy and I/O plugins.
275: On most systems, there is an upper limit to the number of groups that
276: a user may belong to simultaneously (typically 16 for compatibility
277: with NFS).
278: On systems with the
279: .Xr getconf 1
280: utility, running:
281: .Dl getconf NGROUPS_MAX
282: will return the maximum number of groups.
283: .Pp
284: However, it is still possible to be a member of a larger number of
285: groups--they simply won't be included in the group list returned
286: by the kernel for the user.
287: Starting with
288: .Nm sudo
289: version 1.8.7, if the user's kernel group list has the maximum number
290: of entries,
291: .Nm sudo
292: will consult the group database directly to determine the group list.
293: This makes it possible for the security policy to perform matching by group
294: name even when the user is a member of more than the maximum number of groups.
295: .Pp
296: The
297: .Em group_source
298: setting allows the administrator to change this default behavior.
299: Supported values for
300: .Em group_source
301: are:
302: .Bl -tag -width 8n
303: .It static
304: Use the static group list that the kernel returns.
305: Retrieving the group list this way is very fast but it is subject
306: to an upper limit as described above.
307: It is
308: .Dq static
309: in that it does not reflect changes to the group database made
310: after the user logs in.
311: This was the default behavior prior to
312: .Nm sudo
313: 1.8.7.
314: .It dynamic
315: Always query the group database directly.
316: It is
317: .Dq dynamic
318: in that changes made to the group database after the user logs in
319: will be reflected in the group list.
320: On some systems, querying the group database for all of a user's
321: groups can be time consuming when querying a network-based group
322: database.
323: Most operating systems provide an efficient method of performing
324: such queries.
325: Currently,
326: .Nm sudo
327: supports efficient group queries on AIX, BSD, HP-UX, Linux and
328: Solaris.
329: .It adaptive
330: Only query the group database if the static group list returned
331: by the kernel has the maximum number of entries.
332: This is the default behavior in
333: .Nm sudo
334: 1.8.7 and higher.
335: .El
336: .Pp
337: For example, to cause
338: .Nm sudo
339: to only use the kernel's static list of groups for the user:
340: .Bd -literal -offset indent
341: Set group_source static
342: .Ed
343: .Pp
344: This setting is only available in
345: .Nm sudo
346: version 1.8.7 and higher.
347: .It max_groups
348: The maximum number of user groups to retrieve from the group database.
349: Values less than one will be ignored.
350: This setting is only used when querying the group database directly.
351: It is intended to be used on systems where it is not possible to detect
352: when the array to be populated with group entries is not sufficiently large.
353: By default,
354: .Nm sudo
355: will allocate four times the system's maximum number of groups (see above)
356: and retry with double that number if the group database query fails.
357: However, some systems just return as many entries as will fit and
358: do not indicate an error when there is a lack of space.
359: .Pp
360: This setting is only available in
361: .Nm sudo
362: version 1.8.7 and higher.
363: .It probe_interfaces
364: By default,
365: .Nm sudo
366: will probe the system's network interfaces and pass the IP address
367: of each enabled interface to the policy plugin. This makes it
368: possible for the plugin to match rules based on the IP address
369: without having to query DNS. On Linux systems with a large number
370: of virtual interfaces, this may take a non-negligible amount of time.
371: If IP-based matching is not required, network interface probing
372: can be disabled as follows:
373: .Bd -literal -offset indent
374: Set probe_interfaces false
375: .Ed
376: .Pp
377: This setting is only available in
378: .Nm sudo
379: version 1.8.10 and higher.
380: .El
381: .Ss Debug flags
382: .Nm sudo
383: versions 1.8.4 and higher support a flexible debugging framework
384: that can help track down what
385: .Nm sudo
386: is doing internally if there is a problem.
387: .Pp
388: A
389: .Li Debug
390: line consists of the
391: .Li Debug
392: keyword, followed by the name of the program (or plugin) to debug
393: .Pq Nm sudo , Nm visudo , Nm sudoreplay , Nm sudoers ,
394: the debug file name and a comma-separated list of debug flags. The
395: debug flag syntax used by
396: .Nm sudo
397: and the
398: .Nm sudoers
399: plugin is
400: .Em subsystem Ns @ Ns Em priority
401: but a plugin is free to use a different format so long as it does
402: not include a comma
403: .Pq Ql \&, .
404: .Pp
405: For example:
406: .Bd -literal -offset indent
407: Debug sudo /var/log/sudo_debug all@warn,plugin@info
408: .Ed
409: .Pp
410: would log all debugging statements at the
411: .Em warn
412: level and higher in addition to those at the
413: .Em info
414: level for the plugin subsystem.
415: .Pp
416: Currently, only one
417: .Li Debug
418: entry per program is supported. The
419: .Nm sudo
420: .Li Debug
421: entry is shared by the
422: .Nm sudo
423: front end,
424: .Nm sudoedit
425: and the plugins. A future release may add support for per-plugin
426: .Li Debug
427: lines and/or support for multiple debugging files for a single
428: program.
429: .Pp
430: The priorities used by the
431: .Nm sudo
432: front end, in order of decreasing severity, are:
433: .Em crit , err , warn , notice , diag , info , trace
434: and
435: .Em debug .
436: Each priority, when specified, also includes all priorities higher
437: than it. For example, a priority of
438: .Em notice
439: would include debug messages logged at
440: .Em notice
441: and higher.
442: .Pp
443: The following subsystems are used by the
444: .Nm sudo
445: front-end:
446: .Bl -tag -width Fl
447: .It Em all
448: matches every subsystem
449: .It Em args
450: command line argument processing
451: .It Em conv
452: user conversation
453: .It Em edit
454: sudoedit
455: .It Em event
456: event subsystem
457: .It Em exec
458: command execution
459: .It Em main
460: .Nm sudo
461: main function
462: .It Em netif
463: network interface handling
464: .It Em pcomm
465: communication with the plugin
466: .It Em plugin
467: plugin configuration
468: .It Em pty
469: pseudo-tty related code
470: .It Em selinux
471: SELinux-specific handling
472: .It Em util
473: utility functions
474: .It Em utmp
475: utmp handling
476: .El
477: .Pp
478: The
479: .Xr sudoers @mansectform@
480: plugin includes support for additional subsystems.
481: .Sh FILES
482: .Bl -tag -width 24n
483: .It Pa @sysconfdir@/sudo.conf
484: .Nm sudo
485: front end configuration
486: .El
487: .Sh EXAMPLES
488: .Bd -literal
489: #
490: # Default @sysconfdir@/sudo.conf file
491: #
492: # Format:
493: # Plugin plugin_name plugin_path plugin_options ...
494: # Path askpass /path/to/askpass
495: # Path noexec /path/to/sudo_noexec.so
496: # Debug sudo /var/log/sudo_debug all@warn
497: # Set disable_coredump true
498: #
499: # The plugin_path is relative to @PLUGINDIR@ unless
500: # fully qualified.
501: # The plugin_name corresponds to a global symbol in the plugin
502: # that contains the plugin interface structure.
503: # The plugin_options are optional.
504: #
505: # The sudoers plugin is used by default if no Plugin lines are
506: # present.
507: Plugin sudoers_policy sudoers.so
508: Plugin sudoers_io sudoers.so
509:
510: #
511: # Sudo askpass:
512: #
513: # An askpass helper program may be specified to provide a graphical
514: # password prompt for "sudo -A" support. Sudo does not ship with
515: # its own askpass program but can use the OpenSSH askpass.
516: #
517: # Use the OpenSSH askpass
518: #Path askpass /usr/X11R6/bin/ssh-askpass
519: #
520: # Use the Gnome OpenSSH askpass
521: #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
522:
523: #
524: # Sudo noexec:
525: #
526: # Path to a shared library containing dummy versions of the execv(),
527: # execve() and fexecve() library functions that just return an error.
528: # This is used to implement the "noexec" functionality on systems that
529: # support C<LD_PRELOAD> or its equivalent.
530: # The compiled-in value is usually sufficient and should only be
531: # changed if you rename or move the sudo_noexec.so file.
532: #
533: #Path noexec @noexec_file@
534:
535: #
536: # Core dumps:
537: #
538: # By default, sudo disables core dumps while it is executing
539: # (they are re-enabled for the command that is run).
540: # To aid in debugging sudo problems, you may wish to enable core
541: # dumps by setting "disable_coredump" to false.
542: #
543: #Set disable_coredump false
544:
545: #
546: # User groups:
547: #
548: # Sudo passes the user's group list to the policy plugin.
549: # If the user is a member of the maximum number of groups (usually 16),
550: # sudo will query the group database directly to be sure to include
551: # the full list of groups.
552: #
553: # On some systems, this can be expensive so the behavior is configurable.
554: # The "group_source" setting has three possible values:
555: # static - use the user's list of groups returned by the kernel.
556: # dynamic - query the group database to find the list of groups.
557: # adaptive - if user is in less than the maximum number of groups.
558: # use the kernel list, else query the group database.
559: #
560: #Set group_source static
561: .Ed
562: .Sh SEE ALSO
563: .Xr sudoers @mansectform@ ,
564: .Xr sudo @mansectsu@ ,
565: .Xr sudo_plugin @mansectsu@
566: .Sh HISTORY
567: See the HISTORY file in the
568: .Nm sudo
569: distribution (http://www.sudo.ws/sudo/history.html) for a brief
570: history of sudo.
571: .Sh AUTHORS
572: Many people have worked on
573: .Nm sudo
574: over the years; this version consists of code written primarily by:
575: .Bd -ragged -offset indent
576: Todd C. Miller
577: .Ed
578: .Pp
579: See the CONTRIBUTORS file in the
580: .Nm sudo
581: distribution (http://www.sudo.ws/sudo/contributors.html) for an
582: exhaustive list of people who have contributed to
583: .Nm sudo .
584: .Sh BUGS
585: If you feel you have found a bug in
586: .Nm sudo ,
587: please submit a bug report at http://www.sudo.ws/sudo/bugs/
588: .Sh SUPPORT
589: Limited free support is available via the sudo-users mailing list,
590: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
591: search the archives.
592: .Sh DISCLAIMER
593: .Nm sudo
594: is provided
595: .Dq AS IS
596: and any express or implied warranties, including, but not limited
597: to, the implied warranties of merchantability and fitness for a
598: particular purpose are disclaimed.
599: See the LICENSE file distributed with
600: .Nm sudo
601: or http://www.sudo.ws/sudo/license.html for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>