Annotation of src/usr.bin/sudo/visudo.mdoc.in, Revision 1.3
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.3 ! schwarze 22: .Dd $Mdocdate: February 15 2014 $
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
1.3 ! schwarze 192: .Fl V
! 193: .Pq Em version
1.1 millert 194: option causes
195: .Nm visudo
196: to print its version number
197: and exit.
198: .El
199: .Sh ENVIRONMENT
200: The following environment variables may be consulted depending on
201: the value of the
202: .Em editor
203: and
204: .Em env_editor
205: .Em sudoers
206: settings:
207: .Bl -tag -width 15n
208: .It Ev VISUAL
209: Invoked by
210: .Nm visudo
211: as the editor to use
212: .It Ev EDITOR
213: Used by
214: .Nm visudo
215: if
216: .Ev VISUAL
217: is not set
218: .El
219: .Sh FILES
220: .Bl -tag -width 24n
221: .It Pa @sysconfdir@/sudoers
222: List of who can run what
223: .It Pa @sysconfdir@/sudoers.tmp
224: Lock file for visudo
225: .El
226: .Sh DIAGNOSTICS
227: .Bl -tag -width 4n
228: .It Li sudoers file busy, try again later.
229: Someone else is currently editing the
230: .Em sudoers
231: file.
232: .It Li @sysconfdir@/sudoers.tmp: Permission denied
233: You didn't run
234: .Nm visudo
235: as root.
236: .It Li Can't find you in the passwd database
237: Your user ID does not appear in the system passwd file.
238: .It Li Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined
239: Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias
240: or you have a user or host name listed that consists solely of
241: uppercase letters, digits, and the underscore
242: .Pq Ql _
243: character.
244: In the latter case, you can ignore the warnings
245: .Po
246: .Nm sudo
247: will not complain
248: .Pc .
249: In
250: .Fl s
251: (strict) mode these are errors, not warnings.
252: .It Li Warning: unused {User,Runas,Host,Cmnd}_Alias
253: The specified {User,Runas,Host,Cmnd}_Alias was defined but never
254: used.
255: You may wish to comment out or remove the unused alias.
256: In
257: .Fl s
258: (strict) mode this is an error, not a warning.
259: .It Li Warning: cycle in {User,Runas,Host,Cmnd}_Alias
260: The specified {User,Runas,Host,Cmnd}_Alias includes a reference to
261: itself, either directly or through an alias it includes.
262: This is only a warning by default as
263: .Nm sudo
264: will ignore cycles when parsing
265: the
266: .Em sudoers
267: file.
268: .El
269: .Sh SEE ALSO
270: .Xr vi 1 ,
271: .Xr sudoers @mansectform@ ,
272: .Xr sudo @mansectsu@ ,
273: .Xr vipw @mansectsu@
274: .Sh AUTHORS
275: Many people have worked on
276: .Nm sudo
277: over the years; this version consists of code written primarily by:
278: .Bd -ragged -offset indent
1.3 ! schwarze 279: .An Todd C. Miller
1.1 millert 280: .Ed
281: .Pp
282: See the CONTRIBUTORS file in the
283: .Nm sudo
284: distribution (http://www.sudo.ws/sudo/contributors.html) for an
285: exhaustive list of people who have contributed to
286: .Nm sudo .
287: .Sh CAVEATS
288: There is no easy way to prevent a user from gaining a root shell if
289: the editor used by
290: .Nm visudo
291: allows shell escapes.
292: .Sh BUGS
293: If you feel you have found a bug in
294: .Nm visudo ,
295: please submit a bug report at http://www.sudo.ws/sudo/bugs/
296: .Sh SUPPORT
297: Limited free support is available via the sudo-users mailing list,
298: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
299: search the archives.
300: .Sh DISCLAIMER
301: .Nm visudo
302: is provided
303: .Dq AS IS
304: and any express or implied warranties, including, but not limited
305: to, the implied warranties of merchantability and fitness for a
306: particular purpose are disclaimed.
307: See the LICENSE file distributed with
308: .Nm sudo
309: or http://www.sudo.ws/sudo/license.html for complete details.