Annotation of src/usr.bin/sudo/visudo.pod, Revision 1.7
1.6 millert 1: Copyright (c) 1996,1998-2005, 2007-2008
2: Todd C. Miller <Todd.Miller@courtesan.com>
1.1 millert 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: Sponsored in part by the Defense Advanced Research Projects
18: Agency (DARPA) and Air Force Research Laboratory, Air Force
19: Materiel Command, USAF, under agreement number F39502-99-1-0512.
20:
1.7 ! millert 21: $Sudo: visudo.pod,v 1.55 2008/11/15 18:34:01 millert Exp $
1.1 millert 22: =pod
23:
24: =head1 NAME
25:
26: visudo - edit the sudoers file
27:
28: =head1 SYNOPSIS
29:
30: B<visudo> [B<-c>] [B<-q>] [B<-s>] [B<-V>] [B<-f> I<sudoers>]
31:
32: =head1 DESCRIPTION
33:
34: B<visudo> edits the I<sudoers> file in a safe fashion, analogous to
35: L<vipw(8)>. B<visudo> locks the I<sudoers> file against multiple
36: simultaneous edits, provides basic sanity checks, and checks
37: for parse errors. If the I<sudoers> file is currently being
38: edited you will receive a message to try again later.
39:
40: There is a hard-coded list of editors that B<visudo> will use set
41: at compile-time that may be overridden via the I<editor> I<sudoers>
42: C<Default> variable. This list defaults to the path to L<vi(1)> on
43: your system, as determined by the I<configure> script. Normally,
44: B<visudo> does not honor the C<VISUAL> or C<EDITOR> environment
45: variables unless they contain an editor in the aforementioned editors
46: list. However, if B<visudo> is configured with the I<--with-enveditor>
1.7 ! millert 47: option or the I<env_editor> C<Default> variable is set in I<sudoers>,
1.1 millert 48: B<visudo> will use any the editor defines by C<VISUAL> or C<EDITOR>.
49: Note that this can be a security hole since it allows the user to
50: execute any program they wish simply by setting C<VISUAL> or C<EDITOR>.
51:
52: B<visudo> parses the I<sudoers> file after the edit and will
53: not save the changes if there is a syntax error. Upon finding
54: an error, B<visudo> will print a message stating the line number(s)
55: where the error occurred and the user will receive the
56: "What now?" prompt. At this point the user may enter "e"
57: to re-edit the I<sudoers> file, "x" to exit without
58: saving the changes, or "Q" to quit and save changes. The
59: "Q" option should be used with extreme care because if B<visudo>
60: believes there to be a parse error, so will B<sudo> and no one
61: will be able to B<sudo> again until the error is fixed.
62: If "e" is typed to edit the I<sudoers> file after a parse error
63: has been detected, the cursor will be placed on the line where the
64: error occurred (if the editor supports this feature).
65:
66: =head1 OPTIONS
67:
68: B<visudo> accepts the following command line options:
69:
1.6 millert 70: =over 12
1.1 millert 71:
72: =item -c
73:
74: Enable B<check-only> mode. The existing I<sudoers> file will be
75: checked for syntax and a message will be printed to the
76: standard output detailing the status of I<sudoers>.
77: If the syntax check completes successfully, B<visudo> will
78: exit with a value of 0. If a syntax error is encountered,
79: B<visudo> will exit with a value of 1.
80:
1.6 millert 81: =item -f I<sudoers>
1.1 millert 82:
83: Specify and alternate I<sudoers> file location. With this option
84: B<visudo> will edit (or check) the I<sudoers> file of your choice,
85: instead of the default, F<@sysconfdir@/sudoers>. The lock file used
86: is the specified I<sudoers> file with ".tmp" appended to it.
87:
88: =item -q
89:
90: Enable B<quiet> mode. In this mode details about syntax errors
91: are not printed. This option is only useful when combined with
1.7 ! millert 92: the B<-c> option.
1.1 millert 93:
94: =item -s
95:
96: Enable B<strict> checking of the I<sudoers> file. If an alias is
97: used before it is defined, B<visudo> will consider this a parse
98: error. Note that it is not possible to differentiate between an
99: alias and a hostname or username that consists solely of uppercase
100: letters, digits, and the underscore ('_') character.
101:
102: =item -V
103:
104: The B<-V> (version) option causes B<visudo> to print its version number
105: and exit.
106:
107: =back
108:
109: =head1 ENVIRONMENT
110:
1.6 millert 111: The following environment variables may be consulted depending on
112: the value of the I<editor> and I<env_editor> I<sudoers> variables:
1.1 millert 113:
1.4 millert 114: =over 16
115:
116: =item C<VISUAL>
117:
118: Invoked by visudo as the editor to use
119:
120: =item C<EDITOR>
121:
122: Used by visudo if VISUAL is not set
123:
124: =back
1.1 millert 125:
126: =head1 FILES
127:
1.5 millert 128: =over 24
129:
130: =item F<@sysconfdir@/sudoers>
131:
132: List of who can run what
1.3 millert 133:
1.5 millert 134: =item F<@sysconfdir@/sudoers.tmp>
1.3 millert 135:
1.5 millert 136: Lock file for visudo
1.3 millert 137:
1.4 millert 138: =back
1.1 millert 139:
140: =head1 DIAGNOSTICS
141:
142: =over 4
143:
144: =item sudoers file busy, try again later.
145:
146: Someone else is currently editing the I<sudoers> file.
147:
148: =item @sysconfdir@/sudoers.tmp: Permission denied
149:
150: You didn't run B<visudo> as root.
151:
152: =item Can't find you in the passwd database
153:
154: Your userid does not appear in the system passwd file.
155:
1.6 millert 156: =item Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined
1.1 millert 157:
1.6 millert 158: Either you are trying to use an undeclare {User,Runas,Host,Cmnd}_Alias
159: or you have a user or hostname listed that consists solely of
160: uppercase letters, digits, and the underscore ('_') character. In
161: the latter case, you can ignore the warnings (B<sudo> will not
162: complain). In B<-s> (strict) mode these are errors, not warnings.
163:
164: =item Warning: unused {User,Runas,Host,Cmnd}_Alias
165:
166: The specified {User,Runas,Host,Cmnd}_Alias was defined but never
167: used. You may wish to comment out or remove the unused alias. In
168: B<-s> (strict) mode this is an error, not a warning.
1.1 millert 169:
170: =back
171:
172: =head1 SEE ALSO
173:
174: L<vi(1)>, L<sudoers(5)>, L<sudo(8)>, L<vipw(8)>
175:
176: =head1 AUTHOR
177:
178: Many people have worked on I<sudo> over the years; this version of
179: B<visudo> was written by:
180:
181: Todd Miller
182:
183: See the HISTORY file in the sudo distribution or visit
184: http://www.sudo.ws/sudo/history.html for more details.
185:
186: =head1 CAVEATS
187:
188: There is no easy way to prevent a user from gaining a root shell if
189: the editor used by B<visudo> allows shell escapes.
190:
191: =head1 BUGS
192:
193: If you feel you have found a bug in B<visudo>, please submit a bug report
194: at http://www.sudo.ws/sudo/bugs/
195:
196: =head1 SUPPORT
197:
198: Limited free support is available via the sudo-users mailing list,
199: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
200: search the archives.
201:
202: =head1 DISCLAIMER
203:
204: B<visudo> is provided ``AS IS'' and any express or implied warranties,
205: including, but not limited to, the implied warranties of merchantability
206: and fitness for a particular purpose are disclaimed. See the LICENSE
207: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
208: for complete details.