git.gag.com Git - debian/sudo/blob - doc/visudo.mdoc.in

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