Annotation of src/usr.bin/sudo/visudo.pod, Revision 1.3
1.1 millert 1: =cut
2: Copyright (c) 1996,1998-2003 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: 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.3 ! millert 21: $Sudo: visudo.pod,v 1.38.2.8 2007/07/29 23:09:47 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>
47: flag or the I<env_editor> C<Default> variable is set in I<sudoers>,
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:
70: =over 4
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:
81: =item -f
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
92: the B<-c> flag.
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:
111: The following environment variables are used only if B<visudo>
112: was configured with the I<--with-env-editor> option:
113:
114: VISUAL Invoked by visudo as the editor to use
115: EDITOR Used by visudo if VISUAL is not set
116:
117: =head1 FILES
118:
1.3 ! millert 119: =over 4
! 120:
! 121: =item F<@sysconfdir@/sudoers>C< >List of who can run what
! 122:
! 123: =item F<@sysconfdir@/sudoers.tmp>C< >Lock file for visudo
! 124:
! 125: =back 4
1.1 millert 126:
127: =head1 DIAGNOSTICS
128:
129: =over 4
130:
131: =item sudoers file busy, try again later.
132:
133: Someone else is currently editing the I<sudoers> file.
134:
135: =item @sysconfdir@/sudoers.tmp: Permission denied
136:
137: You didn't run B<visudo> as root.
138:
139: =item Can't find you in the passwd database
140:
141: Your userid does not appear in the system passwd file.
142:
143: =item Warning: undeclared Alias referenced near ...
144:
145: Either you are using a {User,Runas,Host,Cmnd}_Alias before
146: defining it or you have a user or hostname listed that
147: consists solely of uppercase letters, digits, and the
148: underscore ('_') character. If the latter, you can ignore
149: the warnings (B<sudo> will not complain). In B<-s> (strict)
150: mode these are errors, not warnings.
151:
152: =item Warning: runas_default set after old value is in use ...
153:
154: You have a I<runas_default> Defaults setting listed in the I<sudoers>
155: file after its value has already been used. This means that entries
156: prior to the I<runas_default> setting will match based on the default
157: value of I<runas_default> (C<@runas_default@>) whereas entries
158: B<after> the I<runas_default> setting will match based on the new
159: value. This is usually unintentional and in most cases the
160: <runas_default> setting should be placed before any C<Runas_Alias>
161: or User specifications. In B<-s> (strict) mode this is an error,
162: not a warning.
163:
164: =back
165:
166: =head1 SEE ALSO
167:
168: L<vi(1)>, L<sudoers(5)>, L<sudo(8)>, L<vipw(8)>
169:
170: =head1 AUTHOR
171:
172: Many people have worked on I<sudo> over the years; this version of
173: B<visudo> was written by:
174:
175: Todd Miller
176:
177: See the HISTORY file in the sudo distribution or visit
178: http://www.sudo.ws/sudo/history.html for more details.
179:
180: =head1 CAVEATS
181:
182: There is no easy way to prevent a user from gaining a root shell if
183: the editor used by B<visudo> allows shell escapes.
184:
185: =head1 BUGS
186:
187: If you feel you have found a bug in B<visudo>, please submit a bug report
188: at http://www.sudo.ws/sudo/bugs/
189:
190: =head1 SUPPORT
191:
192: Limited free support is available via the sudo-users mailing list,
193: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
194: search the archives.
195:
196: =head1 DISCLAIMER
197:
198: B<visudo> is provided ``AS IS'' and any express or implied warranties,
199: including, but not limited to, the implied warranties of merchantability
200: and fitness for a particular purpose are disclaimed. See the LICENSE
201: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
202: for complete details.