Annotation of src/usr.bin/sudo/visudo.mdoc.in, Revision 1.2
1.1 millert 1: .\"
2: .\" Copyright (c) 1996,1998-2005, 2007-2012
3: .\" Todd C. Miller <Todd.Miller@courtesan.com>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17: .\"
18: .\" Sponsored in part by the Defense Advanced Research Projects
19: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
20: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
21: .\"
1.2 ! millert 22: .Dd $Mdocdate: August 17 2012 $
1.1 millert 23: .Dt VISUDO @mansectsu@
24: .Os
25: .Sh NAME
26: .Nm visudo
27: .Nd edit the sudoers file
28: .Sh SYNOPSIS
29: .Nm visudo
30: .Op Fl cqsV
31: .Op Fl f Ar sudoers
32: .Sh DESCRIPTION
33: .Nm visudo
34: edits the
35: .Em sudoers
36: file in a safe fashion, analogous to
37: .Xr vipw @mansectsu@ .
38: .Nm visudo
39: locks the
40: .Em sudoers
41: file against multiple simultaneous edits, provides basic sanity checks,
42: and checks for parse errors.
43: If the
44: .Em sudoers
45: file is currently being edited you will receive a message to try again later.
46: .Pp
47: There is a hard-coded list of one or more editors that
48: .Nm visudo
49: will use set at compile-time that may be overridden via the
50: .Em editor
51: .Em sudoers
52: .Li Default
53: variable.
54: This list defaults to
55: .Li "@editor@" .
56: Normally,
57: .Nm visudo
58: does not honor the
59: .Ev VISUAL
60: or
61: .Ev EDITOR
62: environment variables unless they contain an editor in the aforementioned
63: editors list.
64: However, if
65: .Nm visudo
66: is configured with the
67: .Li --with-env-editor
68: option or the
69: .Em env_editor
70: .Li Default
71: variable is set in
72: .Em sudoers ,
73: .Nm visudo
74: will use any the editor defines by
75: .Ev VISUAL
76: or
77: .Ev EDITOR .
78: Note that this can be a security hole since it allows the user to
79: execute any program they wish simply by setting
80: .Ev VISUAL
81: or
82: .Ev EDITOR .
83: .Pp
84: .Nm visudo
85: parses the
86: .Em sudoers
87: file after the edit and will
88: not save the changes if there is a syntax error.
89: Upon finding an error,
90: .Nm visudo
91: will print a message stating the line number(s)
92: where the error occurred and the user will receive the
93: .Dq What now?
94: prompt.
95: At this point the user may enter
96: .Ql e
97: to re-edit the
98: .Em sudoers
99: file,
100: .Ql x
101: to exit without saving the changes, or
102: .Ql Q
103: to quit and save changes.
104: The
105: .Ql Q
106: option should be used with extreme care because if
107: .Nm visudo
108: believes there to be a parse error, so will
109: .Nm sudo
110: and no one
111: will be able to
112: .Nm sudo
113: again until the error is fixed.
114: If
115: .Ql e
116: is typed to edit the
117: .Em sudoers
118: file after a parse error has been detected, the cursor will be placed on
119: the line where the error occurred (if the editor supports this feature).
120: .Pp
121: The options are as follows:
122: .Bl -tag -width Fl
123: .It Fl c
124: Enable
125: .Em check-only
126: mode.
127: The existing
128: .Em sudoers
129: file will be
130: checked for syntax errors, owner and mode.
131: A message will be printed to the standard output describing the status of
132: .Em sudoers
133: unless the
134: .Fl q
135: option was specified.
136: If the check completes successfully,
137: .Nm visudo
138: will exit with a value of 0.
139: If an error is encountered,
140: .Nm visudo
141: will exit with a value of 1.
142: .It Fl f Ar sudoers
143: Specify and alternate
144: .Em sudoers
145: file location.
146: With this option
147: .Nm visudo
148: will edit (or check) the
149: .Em sudoers
150: file of your choice,
151: instead of the default,
152: .Pa @sysconfdir@/sudoers .
153: The lock file used is the specified
154: .Em sudoers
155: file with
156: .Dq \.tmp
157: appended to it.
158: In
159: .Em check-only
160: mode only, the argument to
161: .Fl f
162: may be
163: .Ql - ,
164: indicating that
165: .Em sudoers
166: will be read from the standard input.
167: .It Fl q
168: Enable
169: .Em quiet
170: mode.
171: In this mode details about syntax errors are not printed.
172: This option is only useful when combined with
173: the
174: .Fl c
175: option.
176: .It Fl s
177: Enable
178: .Em strict
179: checking of the
180: .Em sudoers
181: file.
182: If an alias is used before it is defined,
183: .Nm visudo
184: will consider this a parse error.
185: Note that it is not possible to differentiate between an
186: alias and a host name or user name that consists solely of uppercase
187: letters, digits, and the underscore
188: .Pq Ql _
189: character.
190: .It Fl V
191: The
192: .Fl V ( Em version Ns No )
193: option causes
194: .Nm visudo
195: to print its version number
196: and exit.
197: .El
198: .Sh ENVIRONMENT
199: The following environment variables may be consulted depending on
200: the value of the
201: .Em editor
202: and
203: .Em env_editor
204: .Em sudoers
205: settings:
206: .Bl -tag -width 15n
207: .It Ev VISUAL
208: Invoked by
209: .Nm visudo
210: as the editor to use
211: .It Ev EDITOR
212: Used by
213: .Nm visudo
214: if
215: .Ev VISUAL
216: is not set
217: .El
218: .Sh FILES
219: .Bl -tag -width 24n
220: .It Pa @sysconfdir@/sudoers
221: List of who can run what
222: .It Pa @sysconfdir@/sudoers.tmp
223: Lock file for visudo
224: .El
225: .Sh DIAGNOSTICS
226: .Bl -tag -width 4n
227: .It Li sudoers file busy, try again later.
228: Someone else is currently editing the
229: .Em sudoers
230: file.
231: .It Li @sysconfdir@/sudoers.tmp: Permission denied
232: You didn't run
233: .Nm visudo
234: as root.
235: .It Li Can't find you in the passwd database
236: Your user ID does not appear in the system passwd file.
237: .It Li Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined
238: Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias
239: or you have a user or host name listed that consists solely of
240: uppercase letters, digits, and the underscore
241: .Pq Ql _
242: character.
243: In the latter case, you can ignore the warnings
244: .Po
245: .Nm sudo
246: will not complain
247: .Pc .
248: In
249: .Fl s
250: (strict) mode these are errors, not warnings.
251: .It Li Warning: unused {User,Runas,Host,Cmnd}_Alias
252: The specified {User,Runas,Host,Cmnd}_Alias was defined but never
253: used.
254: You may wish to comment out or remove the unused alias.
255: In
256: .Fl s
257: (strict) mode this is an error, not a warning.
258: .It Li Warning: cycle in {User,Runas,Host,Cmnd}_Alias
259: The specified {User,Runas,Host,Cmnd}_Alias includes a reference to
260: itself, either directly or through an alias it includes.
261: This is only a warning by default as
262: .Nm sudo
263: will ignore cycles when parsing
264: the
265: .Em sudoers
266: file.
267: .El
268: .Sh SEE ALSO
269: .Xr vi 1 ,
270: .Xr sudoers @mansectform@ ,
271: .Xr sudo @mansectsu@ ,
272: .Xr vipw @mansectsu@
273: .Sh AUTHORS
274: Many people have worked on
275: .Nm sudo
276: over the years; this version consists of code written primarily by:
277: .Bd -ragged -offset indent
278: Todd C. Miller
279: .Ed
280: .Pp
281: See the CONTRIBUTORS file in the
282: .Nm sudo
283: distribution (http://www.sudo.ws/sudo/contributors.html) for an
284: exhaustive list of people who have contributed to
285: .Nm sudo .
286: .Sh CAVEATS
287: There is no easy way to prevent a user from gaining a root shell if
288: the editor used by
289: .Nm visudo
290: allows shell escapes.
291: .Sh BUGS
292: If you feel you have found a bug in
293: .Nm visudo ,
294: please submit a bug report at http://www.sudo.ws/sudo/bugs/
295: .Sh SUPPORT
296: Limited free support is available via the sudo-users mailing list,
297: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
298: search the archives.
299: .Sh DISCLAIMER
300: .Nm visudo
301: is provided
302: .Dq AS IS
303: and any express or implied warranties, including, but not limited
304: to, the implied warranties of merchantability and fitness for a
305: particular purpose are disclaimed.
306: See the LICENSE file distributed with
307: .Nm sudo
308: or http://www.sudo.ws/sudo/license.html for complete details.