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