manual/sudo/original/man8/visudo.8

   1 .\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
   2 .\" IT IS GENERATED AUTOMATICALLY FROM visudo.mdoc.in
   3 .\"
   4 .\" Copyright (c) 1996,1998-2005, 2007-2015
   5 .\"     Todd C. Miller <Todd.Miller@courtesan.com>
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  19 .\"
  20 .\" Sponsored in part by the Defense Advanced Research Projects
  21 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
  22 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
  23 .\"
  24 .TH "VISUDO" "8" "November 20, 2015" "Sudo 1.8.17" "System Manager's Manual"
  25 .nh
  26 .if n .ad l
  27 .SH "NAME"
  28 \fBvisudo\fR
  29 \- edit the sudoers file
  30 .SH "SYNOPSIS"
  31 .HP 7n
  32 \fBvisudo\fR
  33 [\fB\-chqsV\fR]
  34 [\fB\-f\fR\ \fIsudoers\fR]
  35 [\fB\-x\fR\ \fIoutput_file\fR]
  36 .SH "DESCRIPTION"
  37 \fBvisudo\fR
  38 edits the
  39 \fIsudoers\fR
  40 file in a safe fashion, analogous to
  41 vipw(8).
  42 \fBvisudo\fR
  43 locks the
  44 \fIsudoers\fR
  45 file against multiple simultaneous edits, provides basic sanity checks,
  46 and checks for parse errors.
  47 If the
  48 \fIsudoers\fR
  49 file is currently being edited you will receive a message to try again later.
  50 .PP
  51 There is a hard-coded list of one or more editors that
  52 \fBvisudo\fR
  53 will use set at compile-time that may be overridden via the
  54 \fIeditor\fR
  55 \fIsudoers\fR
  56 \fRDefault\fR
  57 variable.
  58 This list defaults to
  59 \fRvi\fR.
  60 Normally,
  61 \fBvisudo\fR
  62 does not honor the
  63 \fRVISUAL\fR
  64 or
  65 \fREDITOR\fR
  66 environment variables unless they contain an editor in the aforementioned
  67 editors list.
  68 However, if
  69 \fBvisudo\fR
  70 is configured with the
  71 \fR--with-env-editor\fR
  72 option or the
  73 \fIenv_editor\fR
  74 \fRDefault\fR
  75 variable is set in
  76 \fIsudoers\fR,
  77 \fBvisudo\fR
  78 will use any the editor defines by
  79 \fRVISUAL\fR
  80 or
  81 \fREDITOR\fR.
  82 Note that this can be a security hole since it allows the user to
  83 execute any program they wish simply by setting
  84 \fRVISUAL\fR
  85 or
  86 \fREDITOR\fR.
  87 .PP
  88 \fBvisudo\fR
  89 parses the
  90 \fIsudoers\fR
  91 file after the edit and will
  92 not save the changes if there is a syntax error.
  93 Upon finding an error,
  94 \fBvisudo\fR
  95 will print a message stating the line number(s)
  96 where the error occurred and the user will receive the
  97 \(LqWhat now?\(Rq
  98 prompt.
  99 At this point the user may enter
 100 \(oqe\(cq
 101 to re-edit the
 102 \fIsudoers\fR
 103 file,
 104 \(oqx\(cq
 105 to exit without saving the changes, or
 106 \(oqQ\(cq
 107 to quit and save changes.
 108 The
 109 \(oqQ\(cq
 110 option should be used with extreme care because if
 111 \fBvisudo\fR
 112 believes there to be a parse error, so will
 113 \fBsudo\fR
 114 and no one
 115 will be able to run
 116 \fBsudo\fR
 117 again until the error is fixed.
 118 If
 119 \(oqe\(cq
 120 is typed to edit the
 121 \fIsudoers\fR
 122 file after a parse error has been detected, the cursor will be placed on
 123 the line where the error occurred (if the editor supports this feature).
 124 .PP
 125 The options are as follows:
 126 .TP 12n
 127 \fB\-c\fR, \fB\--check\fR
 128 Enable
 129 \fIcheck-only\fR
 130 mode.
 131 The existing
 132 \fIsudoers\fR
 133 file will be
 134 checked for syntax errors, owner and mode.
 135 A message will be printed to the standard output describing the status of
 136 \fIsudoers\fR
 137 unless the
 138 \fB\-q\fR
 139 option was specified.
 140 If the check completes successfully,
 141 \fBvisudo\fR
 142 will exit with a value of 0.
 143 If an error is encountered,
 144 \fBvisudo\fR
 145 will exit with a value of 1.
 146 .TP 12n
 147 \fB\-f\fR \fIsudoers\fR, \fB\--file\fR=\fIsudoers\fR
 148 Specify an alternate
 149 \fIsudoers\fR
 150 file location.
 151 With this option,
 152 \fBvisudo\fR
 153 will edit (or check) the
 154 \fIsudoers\fR
 155 file of your choice,
 156 instead of the default,
 157 \fI/etc/sudoers\fR.
 158 The lock file used is the specified
 159 \fIsudoers\fR
 160 file with
 161 \(Lq\.tmp\(Rq
 162 appended to it.
 163 In
 164 \fIcheck-only\fR
 165 mode only, the argument to
 166 \fB\-f\fR
 167 may be
 168 \(oq-\(cq,
 169 indicating that
 170 \fIsudoers\fR
 171 will be read from the standard input.
 172 .TP 12n
 173 \fB\-h\fR, \fB\--help\fR
 174 Display a short help message to the standard output and exit.
 175 .TP 12n
 176 \fB\-q\fR, \fB\--quiet\fR
 177 Enable
 178 \fIquiet\fR
 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 \fB\-c\fR
 184 option.
 185 .TP 12n
 186 \fB\-s\fR, \fB\--strict\fR
 187 Enable
 188 \fIstrict\fR
 189 checking of the
 190 \fIsudoers\fR
 191 file.
 192 If an alias is used before it is defined,
 193 \fBvisudo\fR
 194 will consider this a parse error.
 195 Note that it is not possible to differentiate between an
 196 alias and a host name or user name that consists solely of uppercase
 197 letters, digits, and the underscore
 198 (\(oq_\(cq)
 199 character.
 200 .TP 12n
 201 \fB\-V\fR, \fB\--version\fR
 202 Print the
 203 \fBvisudo\fR
 204 and
 205 \fIsudoers\fR
 206 grammar versions and exit.
 207 .TP 12n
 208 \fB\-x\fR \fIoutput_file\fR, \fB\--export\fR=\fIoutput_file\fR
 209 Export a
 210 \fIsudoers\fR
 211 in JSON format and write it to
 212 \fIoutput_file\fR.
 213 If
 214 \fIoutput_file\fR
 215 is
 216 \(oq-\(cq,
 217 the exported
 218 \fIsudoers\fR
 219 policy will be written to the standard output.
 220 By default,
 221 \fI/etc/sudoers\fR
 222 (and any files it includes) will be exported.
 223 The
 224 \fB\-f\fR
 225 option can be used to specify a different
 226 \fIsudoers\fR
 227 file to export.
 228 The exported format is intended to be easier for third-party
 229 applications to parse than the traditional
 230 \fIsudoers\fR
 231 format.
 232 The various values have explicit types which removes much of the
 233 ambiguity of the
 234 \fIsudoers\fR
 235 format.
 236 .SS "Debugging and sudoers plugin arguments"
 237 \fBvisudo\fR
 238 versions 1.8.4 and higher support a flexible debugging framework
 239 that is configured via
 240 \fRDebug\fR
 241 lines in the
 242 sudo.conf(5)
 243 file.
 244 .PP
 245 Starting with
 246 \fBsudo\fR
 247 1.8.12,
 248 \fBvisudo\fR
 249 will also parse the arguments to the
 250 \fIsudoers\fR
 251 plugin to override the default
 252 \fIsudoers\fR
 253 path name, UID, GID and file mode.
 254 These arguments, if present, should be listed after the path to the plugin
 255 (i.e.\& after
 256 \fIsudoers.so\fR).
 257 Multiple arguments may be specified, separated by white space.
 258 For example:
 259 .nf
 260 .sp
 261 .RS 6n
 262 Plugin sudoers_policy sudoers.so sudoers_mode=0400
 263 .RE
 264 .fi
 265 .PP
 266 The following arguments are supported:
 267 .TP 10n
 268 sudoers_file=pathname
 269 The
 270 \fIsudoers_file\fR
 271 argument can be used to override the default path to the
 272 \fIsudoers\fR
 273 file.
 274 .TP 10n
 275 sudoers_uid=uid
 276 The
 277 \fIsudoers_uid\fR
 278 argument can be used to override the default owner of the sudoers file.
 279 It should be specified as a numeric user ID.
 280 .TP 10n
 281 sudoers_gid=gid
 282 The
 283 \fIsudoers_gid\fR
 284 argument can be used to override the default group of the sudoers file.
 285 It must be specified as a numeric group ID (not a group name).
 286 .TP 10n
 287 sudoers_mode=mode
 288 The
 289 \fIsudoers_mode\fR
 290 argument can be used to override the default file mode for the sudoers file.
 291 It should be specified as an octal value.
 292 .PP
 293 For more information on configuring
 294 sudo.conf(5),
 295 please refer to its manual.
 296 .SH "ENVIRONMENT"
 297 The following environment variables may be consulted depending on
 298 the value of the
 299 \fIeditor\fR
 300 and
 301 \fIenv_editor\fR
 302 \fIsudoers\fR
 303 settings:
 304 .TP 17n
 305 \fRVISUAL\fR
 306 Invoked by
 307 \fBvisudo\fR
 308 as the editor to use
 309 .TP 17n
 310 \fREDITOR\fR
 311 Used by
 312 \fBvisudo\fR
 313 if
 314 \fRVISUAL\fR
 315 is not set
 316 .SH "FILES"
 317 .TP 26n
 318 \fI/etc/sudo.conf\fR
 319 Sudo front end configuration
 320 .TP 26n
 321 \fI/etc/sudoers\fR
 322 List of who can run what
 323 .TP 26n
 324 \fI/etc/sudoers.tmp\fR
 325 Lock file for visudo
 326 .SH "DIAGNOSTICS"
 327 .TP 6n
 328 \fRsudoers file busy, try again later.\fR
 329 Someone else is currently editing the
 330 \fIsudoers\fR
 331 file.
 332 .TP 6n
 333 \fR/etc/sudoers.tmp: Permission denied\fR
 334 You didn't run
 335 \fBvisudo\fR
 336 as root.
 337 .TP 6n
 338 \fRCan't find you in the passwd database\fR
 339 Your user ID does not appear in the system passwd file.
 340 .TP 6n
 341 \fRWarning: {User,Runas,Host,Cmnd}_Alias referenced but not defined\fR
 342 Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias
 343 or you have a user or host name listed that consists solely of
 344 uppercase letters, digits, and the underscore
 345 (\(oq_\(cq)
 346 character.
 347 In the latter case, you can ignore the warnings
 348 (\fBsudo\fR
 349 will not complain)
 350 \&.
 351 In
 352 \fB\-s\fR
 353 (strict) mode these are errors, not warnings.
 354 .TP 6n
 355 \fRWarning: unused {User,Runas,Host,Cmnd}_Alias\fR
 356 The specified {User,Runas,Host,Cmnd}_Alias was defined but never
 357 used.
 358 You may wish to comment out or remove the unused alias.
 359 .TP 6n
 360 \fRWarning: cycle in {User,Runas,Host,Cmnd}_Alias\fR
 361 The specified {User,Runas,Host,Cmnd}_Alias includes a reference to
 362 itself, either directly or through an alias it includes.
 363 This is only a warning by default as
 364 \fBsudo\fR
 365 will ignore cycles when parsing
 366 the
 367 \fIsudoers\fR
 368 file.
 369 .TP 6n
 370 \fRvisudo: /etc/sudoers: input and output files must be different\fR
 371 The
 372 \fB\-x\fR
 373 flag was used and the specified
 374 \fIoutput_file\fR
 375 has the same path name as the
 376 \fIsudoers\fR
 377 file to export.
 378 .SH "SEE ALSO"
 379 vi(1),
 380 sudo.conf(5),
 381 sudoers(5),
 382 sudo(8),
 383 vipw(8)
 384 .SH "AUTHORS"
 385 Many people have worked on
 386 \fBsudo\fR
 387 over the years; this version consists of code written primarily by:
 388 .sp
 389 .RS 6n
 390 Todd C. Miller
 391 .RE
 392 .PP
 393 See the CONTRIBUTORS file in the
 394 \fBsudo\fR
 395 distribution (https://www.sudo.ws/contributors.html) for an
 396 exhaustive list of people who have contributed to
 397 \fBsudo\fR.
 398 .SH "CAVEATS"
 399 There is no easy way to prevent a user from gaining a root shell if
 400 the editor used by
 401 \fBvisudo\fR
 402 allows shell escapes.
 403 .SH "BUGS"
 404 If you feel you have found a bug in
 405 \fBvisudo\fR,
 406 please submit a bug report at https://bugzilla.sudo.ws/
 407 .SH "SUPPORT"
 408 Limited free support is available via the sudo-users mailing list,
 409 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 410 search the archives.
 411 .SH "DISCLAIMER"
 412 \fBvisudo\fR
 413 is provided
 414 \(LqAS IS\(Rq
 415 and any express or implied warranties, including, but not limited
 416 to, the implied warranties of merchantability and fitness for a
 417 particular purpose are disclaimed.
 418 See the LICENSE file distributed with
 419 \fBsudo\fR
 420 or https://www.sudo.ws/license.html for complete details.