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