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