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