Annotation of embedaddon/sudo/doc/sudo.conf.man.in, revision 1.1.1.2
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: .\"
4: .\" Copyright (c) 2010-2013 Todd C. Miller <Todd.Miller@courtesan.com>
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.2 ! misho 19: .TH "SUDO" "5" "August 13, 2013" "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
60: (`#')
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
66: (`\e')
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
82: ``\fRC\fR''
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
103: to the shared object containing the plugin.
104: The
105: \fIsymbol_name\fR
106: is the name of the
107: \fRstruct policy_plugin\fR
108: or
109: \fRstruct io_plugin\fR
110: in the plugin shared object.
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
136: Starting with
137: \fBsudo\fR
138: 1.8.5, any additional parameters after the
139: \fIpath\fR
140: are passed as arguments to the plugin's
141: \fIopen\fR
142: function.
143: For example, to override the compile-time default sudoers file mode:
144: .nf
145: .sp
146: .RS 6n
147: Plugin sudoers_policy sudoers.so sudoers_mode=0440
148: .RE
149: .fi
150: .PP
151: The same shared object may contain multiple plugins, each with a
152: different symbol name.
153: The shared object file must be owned by uid 0 and only writable by its owner.
154: Because of ambiguities that arise from composite policies, only a single
155: policy plugin may be specified.
156: This limitation does not apply to I/O plugins.
157: .PP
158: If no
159: \fBsudo.conf\fR
160: file is present, or if it contains no
161: \fRPlugin\fR
162: lines, the
163: \fBsudoers\fR
164: plugin will be used as the default security policy and for I/O logging
165: (if enabled by the policy).
166: This is equivalent to the following:
167: .nf
168: .sp
169: .RS 6n
170: Plugin sudoers_policy sudoers.so
171: Plugin sudoers_io sudoers.so
172: .RE
173: .fi
174: .PP
175: For more information on the
176: \fBsudo\fR
177: plugin architecture, see the
178: sudo_plugin(@mansectsu@)
179: manual.
180: .SS "Path settings"
181: A
182: \fRPath\fR
183: line consists of the
184: \fRPath\fR
185: keyword, followed by the name of the path to set and its value.
186: For example:
187: .nf
188: .sp
189: .RS 6n
190: Path noexec @noexec_file@
191: Path askpass /usr/X11R6/bin/ssh-askpass
192: .RE
193: .fi
194: .PP
195: The following plugin-agnostic paths may be set in the
196: \fI@sysconfdir@/sudo.conf\fR
197: file:
198: .TP 10n
199: askpass
200: The fully qualified path to a helper program used to read the user's
201: password when no terminal is available.
202: This may be the case when
203: \fBsudo\fR
204: is executed from a graphical (as opposed to text-based) application.
205: The program specified by
206: \fIaskpass\fR
207: should display the argument passed to it as the prompt and write
208: the user's password to the standard output.
209: The value of
210: \fIaskpass\fR
211: may be overridden by the
212: \fRSUDO_ASKPASS\fR
213: environment variable.
214: .TP 10n
215: noexec
216: The fully-qualified path to a shared library containing dummy
217: versions of the
218: \fBexecv\fR(),
219: \fBexecve\fR()
220: and
221: \fBfexecve\fR()
222: library functions that just return an error.
223: This is used to implement the
224: \fInoexec\fR
225: functionality on systems that support
226: \fRLD_PRELOAD\fR
227: or its equivalent.
228: The default value is:
229: \fI@noexec_file@\fR.
230: .TP 10n
1.1.1.2 ! misho 231: plugin_dir
! 232: The default directory to use when searching for plugins
! 233: that are specified without a fully qualified path name.
! 234: The default value is
! 235: \fI@PLUGINDIR@\fR.
! 236: .TP 10n
1.1 misho 237: sesh
238: The fully-qualified path to the
239: \fBsesh\fR
240: binary.
241: This setting is only used when
242: \fBsudo\fR
243: is built with SELinux support.
244: The default value is
245: \fI@sesh_file@\fR.
246: .SS "Other settings"
247: The
248: \fBsudo.conf\fR
249: file also supports the following front end settings:
250: .TP 10n
251: disable_coredump
252: Core dumps of
253: \fBsudo\fR
254: itself are disabled by default.
255: To aid in debugging
256: \fBsudo\fR
257: crashes, you may wish to re-enable core dumps by setting
258: ``disable_coredump''
259: to false in
260: \fBsudo.conf\fR
261: as follows:
262: .RS
263: .nf
264: .sp
265: .RS 6n
266: Set disable_coredump false
267: .RE
268: .fi
269: .sp
270: Note that most operating systems disable core dumps from setuid programs,
271: including
272: \fBsudo\fR.
273: To actually get a
274: \fBsudo\fR
275: core file you will likely need to enable core dumps for setuid processes.
276: On BSD and Linux systems this is accomplished in the
277: sysctl
278: command.
279: On Solaris, the
280: coreadm
281: command is used to configure core dump behavior.
282: .sp
283: This setting is only available in
284: \fBsudo\fR
285: version 1.8.4 and higher.
286: .PP
287: .RE
288: .PD 0
289: .TP 10n
290: group_source
291: \fBsudo\fR
292: passes the invoking user's group list to the policy and I/O plugins.
293: On most systems, there is an upper limit to the number of groups that
294: a user may belong to simultaneously (typically 16 for compatibility
295: with NFS).
296: On systems with the
297: getconf(1)
298: utility, running:
299: .RS 6n
300: getconf NGROUPS_MAX
301: .RE
302: will return the maximum number of groups.
303: .sp
304: However, it is still possible to be a member of a larger number of
305: groups--they simply won't be included in the group list returned
306: by the kernel for the user.
307: Starting with
308: \fBsudo\fR
309: version 1.8.7, if the user's kernel group list has the maximum number
310: of entries,
311: \fBsudo\fR
312: will consult the group database directly to determine the group list.
313: This makes it possible for the security policy to perform matching by group
314: name even when the user is a member of more than the maximum number of groups.
315: .sp
316: The
317: \fIgroup_source\fR
318: setting allows the administrator to change this default behavior.
319: Supported values for
320: \fIgroup_source\fR
321: are:
322: .RS
323: .PD
324: .TP 10n
325: static
326: Use the static group list that the kernel returns.
327: Retrieving the group list this way is very fast but it is subject
328: to an upper limit as described above.
329: It is
330: ``static''
331: in that it does not reflect changes to the group database made
332: after the user logs in.
333: This was the default behavior prior to
334: \fBsudo\fR
335: 1.8.7.
336: .TP 10n
337: dynamic
338: Always query the group database directly.
339: It is
340: ``dynamic''
341: in that changes made to the group database after the user logs in
342: will be reflected in the group list.
343: On some systems, querying the group database for all of a user's
344: groups can be time consuming when querying a network-based group
345: database.
346: Most operating systems provide an efficient method of performing
347: such queries.
348: Currently,
349: \fBsudo\fR
350: supports efficient group queries on AIX, BSD, HP-UX, Linux and
351: Solaris.
352: .TP 10n
353: adaptive
354: Only query the group database if the static group list returned
355: by the kernel has the maximum number of entries.
356: This is the default behavior in
357: \fBsudo\fR
358: 1.8.7 and higher.
359: .PP
360: For example, to cause
361: \fBsudo\fR
362: to only use the kernel's static list of groups for the user:
363: .nf
364: .sp
365: .RS 6n
366: Set group_source static
367: .RE
368: .fi
369: .sp
370: This setting is only available in
371: \fBsudo\fR
372: version 1.8.7 and higher.
373: .PP
374: .RE
375: .PD 0
376: .TP 10n
377: max_groups
378: The maximum number of user groups to retrieve from the group database.
1.1.1.2 ! misho 379: Values less than one will be ignored.
1.1 misho 380: This setting is only used when querying the group database directly.
381: It is intended to be used on systems where it is not possible to detect
382: when the array to be populated with group entries is not sufficiently large.
383: By default,
384: \fBsudo\fR
385: will allocate four times the system's maximum number of groups (see above)
386: and retry with double that number if the group database query fails.
387: However, some systems just return as many entries as will fit and
388: do not indicate an error when there is a lack of space.
389: .sp
390: This setting is only available in
391: \fBsudo\fR
392: version 1.8.7 and higher.
393: .PD
394: .SS "Debug flags"
395: \fBsudo\fR
396: versions 1.8.4 and higher support a flexible debugging framework
397: that can help track down what
398: \fBsudo\fR
399: is doing internally if there is a problem.
400: .PP
401: A
402: \fRDebug\fR
403: line consists of the
404: \fRDebug\fR
405: keyword, followed by the name of the program (or plugin) to debug
406: (\fBsudo\fR, \fBvisudo\fR, \fBsudoreplay\fR, \fBsudoers\fR),
407: the debug file name and a comma-separated list of debug flags. The
408: debug flag syntax used by
409: \fBsudo\fR
410: and the
411: \fBsudoers\fR
412: plugin is
413: \fIsubsystem\fR@\fIpriority\fR
414: but a plugin is free to use a different format so long as it does
415: not include a comma
416: (`\&,').
417: .PP
418: For example:
419: .nf
420: .sp
421: .RS 6n
422: Debug sudo /var/log/sudo_debug all@warn,plugin@info
423: .RE
424: .fi
425: .PP
426: would log all debugging statements at the
427: \fIwarn\fR
428: level and higher in addition to those at the
429: \fIinfo\fR
430: level for the plugin subsystem.
431: .PP
432: Currently, only one
433: \fRDebug\fR
434: entry per program is supported. The
435: \fBsudo\fR
436: \fRDebug\fR
437: entry is shared by the
438: \fBsudo\fR
439: front end,
440: \fBsudoedit\fR
441: and the plugins. A future release may add support for per-plugin
442: \fRDebug\fR
443: lines and/or support for multiple debugging files for a single
444: program.
445: .PP
446: The priorities used by the
447: \fBsudo\fR
448: front end, in order of decreasing severity, are:
449: \fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR
450: and
451: \fIdebug\fR.
452: Each priority, when specified, also includes all priorities higher
453: than it. For example, a priority of
454: \fInotice\fR
455: would include debug messages logged at
456: \fInotice\fR
457: and higher.
458: .PP
459: The following subsystems are used by the
460: \fBsudo\fR
461: front-end:
462: .TP 12n
463: \fIall\fR
464: matches every subsystem
465: .TP 12n
466: \fIargs\fR
467: command line argument processing
468: .TP 12n
469: \fIconv\fR
470: user conversation
471: .TP 12n
472: \fIedit\fR
473: sudoedit
474: .TP 12n
475: \fIexec\fR
476: command execution
477: .TP 12n
478: \fImain\fR
479: \fBsudo\fR
480: main function
481: .TP 12n
482: \fInetif\fR
483: network interface handling
484: .TP 12n
485: \fIpcomm\fR
486: communication with the plugin
487: .TP 12n
488: \fIplugin\fR
489: plugin configuration
490: .TP 12n
491: \fIpty\fR
492: pseudo-tty related code
493: .TP 12n
494: \fIselinux\fR
495: SELinux-specific handling
496: .TP 12n
497: \fIutil\fR
498: utility functions
499: .TP 12n
500: \fIutmp\fR
501: utmp handling
502: .PP
503: The
504: sudoers(@mansectform@)
505: plugin includes support for additional subsystems.
506: .SH "FILES"
507: .TP 26n
508: \fI@sysconfdir@/sudo.conf\fR
509: \fBsudo\fR
510: front end configuration
511: .SH "EXAMPLES"
512: .nf
513: .RS 0n
514: #
515: # Default @sysconfdir@/sudo.conf file
516: #
517: # Format:
518: # Plugin plugin_name plugin_path plugin_options ...
519: # Path askpass /path/to/askpass
520: # Path noexec /path/to/sudo_noexec.so
521: # Debug sudo /var/log/sudo_debug all@warn
522: # Set disable_coredump true
523: #
524: # The plugin_path is relative to @PLUGINDIR@ unless
525: # fully qualified.
526: # The plugin_name corresponds to a global symbol in the plugin
527: # that contains the plugin interface structure.
528: # The plugin_options are optional.
529: #
530: # The sudoers plugin is used by default if no Plugin lines are
531: # present.
532: Plugin sudoers_policy sudoers.so
533: Plugin sudoers_io sudoers.so
534:
535: #
536: # Sudo askpass:
537: #
538: # An askpass helper program may be specified to provide a graphical
539: # password prompt for "sudo -A" support. Sudo does not ship with
540: # its own askpass program but can use the OpenSSH askpass.
541: #
542: # Use the OpenSSH askpass
543: #Path askpass /usr/X11R6/bin/ssh-askpass
544: #
545: # Use the Gnome OpenSSH askpass
546: #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
547:
548: #
549: # Sudo noexec:
550: #
551: # Path to a shared library containing dummy versions of the execv(),
552: # execve() and fexecve() library functions that just return an error.
553: # This is used to implement the "noexec" functionality on systems that
554: # support C<LD_PRELOAD> or its equivalent.
555: # The compiled-in value is usually sufficient and should only be
556: # changed if you rename or move the sudo_noexec.so file.
557: #
558: #Path noexec @noexec_file@
559:
560: #
561: # Core dumps:
562: #
563: # By default, sudo disables core dumps while it is executing
564: # (they are re-enabled for the command that is run).
565: # To aid in debugging sudo problems, you may wish to enable core
566: # dumps by setting "disable_coredump" to false.
567: #
568: #Set disable_coredump false
569:
570: #
571: # User groups:
572: #
573: # Sudo passes the user's group list to the policy plugin.
574: # If the user is a member of the maximum number of groups (usually 16),
575: # sudo will query the group database directly to be sure to include
576: # the full list of groups.
577: #
578: # On some systems, this can be expensive so the behavior is configurable.
579: # The "group_source" setting has three possible values:
580: # static - use the user's list of groups returned by the kernel.
581: # dynamic - query the group database to find the list of groups.
582: # adaptive - if user is in less than the maximum number of groups.
583: # use the kernel list, else query the group database.
584: #
585: #Set group_source static
586: .RE
587: .fi
588: .SH "SEE ALSO"
589: sudoers(@mansectform@),
590: sudo(@mansectsu@),
591: sudo_plugin(@mansectsu@)
592: .SH "HISTORY"
593: See the HISTORY file in the
594: \fBsudo\fR
595: distribution (http://www.sudo.ws/sudo/history.html) for a brief
596: history of sudo.
597: .SH "AUTHORS"
598: Many people have worked on
599: \fBsudo\fR
600: over the years; this version consists of code written primarily by:
601: .sp
602: .RS 6n
603: Todd C. Miller
604: .RE
605: .PP
606: See the CONTRIBUTORS file in the
607: \fBsudo\fR
608: distribution (http://www.sudo.ws/sudo/contributors.html) for an
609: exhaustive list of people who have contributed to
610: \fBsudo\fR.
611: .SH "BUGS"
612: If you feel you have found a bug in
613: \fBsudo\fR,
614: please submit a bug report at http://www.sudo.ws/sudo/bugs/
615: .SH "SUPPORT"
616: Limited free support is available via the sudo-users mailing list,
617: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
618: search the archives.
619: .SH "DISCLAIMER"
620: \fBsudo\fR
621: is provided
622: ``AS IS''
623: and any express or implied warranties, including, but not limited
624: to, the implied warranties of merchantability and fitness for a
625: particular purpose are disclaimed.
626: See the LICENSE file distributed with
627: \fBsudo\fR
628: or http://www.sudo.ws/sudo/license.html for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>