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