granicus.if.org Git - sudo/blob - doc/visudo.man.in

   1 .\" Automatically generated from an mdoc input file.  Do not edit.
   2 .\"
   3 .\" SPDX-License-Identifier: ISC
   4 .\"
   5 .\" Copyright (c) 1996,1998-2005, 2007-2018
   6 .\"     Todd C. Miller <Todd.Miller@sudo.ws>
   7 .\"
   8 .\" Permission to use, copy, modify, and distribute this software for any
   9 .\" purpose with or without fee is hereby granted, provided that the above
  10 .\" copyright notice and this permission notice appear in all copies.
  11 .\"
  12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  18 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  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" "@mansectsu@" "December 24, 2018" "Sudo @PACKAGE_VERSION@" "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 .SH "DESCRIPTION"
  36 \fBvisudo\fR
  37 edits the
  38 \fIsudoers\fR
  39 file in a safe fashion, analogous to
  40 vipw(@mansectsu@).
  41 \fBvisudo\fR
  42 locks the
  43 \fIsudoers\fR
  44 file against multiple simultaneous edits, provides basic sanity checks,
  45 and checks for parse errors.
  46 If the
  47 \fIsudoers\fR
  48 file is currently being edited you will receive a message to try again later.
  49 .PP
  50 \fBvisudo\fR
  51 parses the
  52 \fIsudoers\fR
  53 file after editing and will not save the changes if there is a syntax error.
  54 Upon finding an error,
  55 \fBvisudo\fR
  56 will print a message stating the line number(s)
  57 where the error occurred and the user will receive the
  58 \(lqWhat now?\(rq
  59 prompt.
  60 At this point the user may enter
  61 \(oqe\(cq
  62 to re-edit the
  63 \fIsudoers\fR
  64 file,
  65 \(oqx\(cq
  66 to exit without saving the changes, or
  67 \(oqQ\(cq
  68 to quit and save changes.
  69 The
  70 \(oqQ\(cq
  71 option should be used with extreme caution because if
  72 \fBvisudo\fR
  73 believes there to be a parse error, so will
  74 \fBsudo\fR
  75 and no one
  76 will be able to run
  77 \fBsudo\fR
  78 again until the error is fixed.
  79 If
  80 \(oqe\(cq
  81 is typed to edit the
  82 \fIsudoers\fR
  83 file after a parse error has been detected, the cursor will be placed on
  84 the line where the error occurred (if the editor supports this feature).
  85 .PP
  86 There are two
  87 \fIsudoers\fR
  88 settings that determine which editor
  89 \fBvisudo\fR
  90 will run.
  91 .TP 10n
  92 editor
  93 A colon
  94 (\(oq:\&\(cq)
  95 separated list of editors allowed to be used with
  96 \fBvisudo\fR.
  97 \fBvisudo\fR
  98 will choose the editor that matches the user's
  99 \fRSUDO_EDITOR\fR,
 100 \fRVISUAL\fR
 101 or
 102 \fREDITOR\fR
 103 environment variable if possible, or the first editor in the
 104 list that exists and is executable.
 105 Note that the
 106 \fRSUDO_EDITOR\fR,
 107 \fRVISUAL\fR
 108 and
 109 \fREDITOR\fR
 110 environment variables are not preserved by default when the
 111 \fIenv_reset\fR
 112 \fIsudoers\fR
 113 option is enabled.
 114 The default editor path is
 115 \fI@editor@\fR
 116 which can be set at compile time via the
 117 \fR--with-editor\fR
 118 configure option.
 119 .TP 10n
 120 env_editor
 121 If set,
 122 \fBvisudo\fR
 123 will use the value of the
 124 \fRSUDO_EDITOR\fR,
 125 \fRVISUAL\fR
 126 or
 127 \fREDITOR\fR
 128 environment variables before falling back on the default editor list.
 129 Note that this may create a security hole as it allows the user to
 130 run any arbitrary command as root without logging.
 131 A safer alternative is to place a colon-separated list of editors
 132 in the
 133 \fIeditor\fR
 134 variable.
 135 \fBvisudo\fR
 136 will then only use
 137 \fRSUDO_EDITOR\fR,
 138 \fRVISUAL\fR
 139 or
 140 \fREDITOR\fR
 141 if they match a value specified in
 142 \fIeditor\fR.
 143 If the
 144 \fIenv_reset\fR
 145 flag is enabled, the
 146 \fRSUDO_EDITOR\fR,
 147 \fRVISUAL\fR
 148 and/or
 149 \fREDITOR\fR
 150 environment variables must be present in the
 151 \fIenv_keep\fR
 152 list for the
 153 \fIenv_editor\fR
 154 flag to function when
 155 \fBvisudo\fR
 156 is invoked via
 157 \fBsudo\fR.
 158 The default value is
 159 \fI@env_editor@\fR,
 160 which can be set at compile time via the
 161 \fR--with-env-editor\fR
 162 configure option.
 163 .PP
 164 The options are as follows:
 165 .TP 12n
 166 \fB\-c\fR, \fB\--check\fR
 167 Enable
 168 \fIcheck-only\fR
 169 mode.
 170 The existing
 171 \fIsudoers\fR
 172 file (and any other files it includes) will be
 173 checked for syntax errors.
 174 If the path to the
 175 \fIsudoers\fR
 176 file was not specified,
 177 \fBvisudo\fR
 178 will also check the file owner and mode.
 179 A message will be printed to the standard output describing the status of
 180 \fIsudoers\fR
 181 unless the
 182 \fB\-q\fR
 183 option was specified.
 184 If the check completes successfully,
 185 \fBvisudo\fR
 186 will exit with a value of 0.
 187 If an error is encountered,
 188 \fBvisudo\fR
 189 will exit with a value of 1.
 190 .TP 12n
 191 \fB\-f\fR \fIsudoers\fR, \fB\--file\fR=\fIsudoers\fR
 192 Specify an alternate
 193 \fIsudoers\fR
 194 file location, see below.
 195 As of version 1.8.27, the
 196 \fIsudoers\fR
 197 path can be specified without using the
 198 \fB\-f\fR
 199 option.
 200 .TP 12n
 201 \fB\-h\fR, \fB\--help\fR
 202 Display a short help message to the standard output and exit.
 203 .TP 12n
 204 \fB\-q\fR, \fB\--quiet\fR
 205 Enable
 206 \fIquiet\fR
 207 mode.
 208 In this mode details about syntax errors are not printed.
 209 This option is only useful when combined with
 210 the
 211 \fB\-c\fR
 212 option.
 213 .TP 12n
 214 \fB\-s\fR, \fB\--strict\fR
 215 Enable
 216 \fIstrict\fR
 217 checking of the
 218 \fIsudoers\fR
 219 file.
 220 If an alias is referenced but not actually defined
 221 or if there is a cycle in an alias,
 222 \fBvisudo\fR
 223 will consider this a parse error.
 224 Note that it is not possible to differentiate between an
 225 alias and a host name or user name that consists solely of uppercase
 226 letters, digits, and the underscore
 227 (\(oq_\(cq)
 228 character.
 229 .TP 12n
 230 \fB\-V\fR, \fB\--version\fR
 231 Print the
 232 \fBvisudo\fR
 233 and
 234 \fIsudoers\fR
 235 grammar versions and exit.
 236 .PP
 237 A
 238 \fIsudoers\fR
 239 file may be specified instead of the default,
 240 \fI@sysconfdir@/sudoers\fR.
 241 The lock file used is the specified
 242 \fIsudoers\fR
 243 file with
 244 \(lq\.tmp\(rq
 245 appended to it.
 246 In
 247 \fIcheck-only\fR
 248 mode only,
 249 \(oq-\(cq
 250 may be used to indicate that
 251 \fIsudoers\fR
 252 will be read from the standard input.
 253 Because the policy is evaluated in its entirety, it is not sufficient
 254 to check an individual
 255 \fIsudoers\fR
 256 include file for syntax errors.
 257 .SS "Debugging and sudoers plugin arguments"
 258 \fBvisudo\fR
 259 versions 1.8.4 and higher support a flexible debugging framework
 260 that is configured via
 261 \fRDebug\fR
 262 lines in the
 263 sudo.conf(@mansectform@)
 264 file.
 265 .PP
 266 Starting with
 267 \fBsudo\fR
 268 1.8.12,
 269 \fBvisudo\fR
 270 will also parse the arguments to the
 271 \fIsudoers\fR
 272 plugin to override the default
 273 \fIsudoers\fR
 274 path name, UID, GID and file mode.
 275 These arguments, if present, should be listed after the path to the plugin
 276 (i.e., after
 277 \fIsudoers.so\fR).
 278 Multiple arguments may be specified, separated by white space.
 279 For example:
 280 .nf
 281 .sp
 282 .RS 6n
 283 Plugin sudoers_policy sudoers.so sudoers_mode=0400
 284 .RE
 285 .fi
 286 .PP
 287 The following arguments are supported:
 288 .TP 10n
 289 sudoers_file=pathname
 290 The
 291 \fIsudoers_file\fR
 292 argument can be used to override the default path to the
 293 \fIsudoers\fR
 294 file.
 295 .TP 10n
 296 sudoers_uid=uid
 297 The
 298 \fIsudoers_uid\fR
 299 argument can be used to override the default owner of the sudoers file.
 300 It should be specified as a numeric user ID.
 301 .TP 10n
 302 sudoers_gid=gid
 303 The
 304 \fIsudoers_gid\fR
 305 argument can be used to override the default group of the sudoers file.
 306 It must be specified as a numeric group ID (not a group name).
 307 .TP 10n
 308 sudoers_mode=mode
 309 The
 310 \fIsudoers_mode\fR
 311 argument can be used to override the default file mode for the sudoers file.
 312 It should be specified as an octal value.
 313 .PP
 314 For more information on configuring
 315 sudo.conf(@mansectform@),
 316 please refer to its manual.
 317 .SH "ENVIRONMENT"
 318 The following environment variables may be consulted depending on
 319 the value of the
 320 \fIeditor\fR
 321 and
 322 \fIenv_editor\fR
 323 \fIsudoers\fR
 324 settings:
 325 .TP 17n
 326 \fRSUDO_EDITOR\fR
 327 Invoked by
 328 \fBvisudo\fR
 329 as the editor to use
 330 .TP 17n
 331 \fRVISUAL\fR
 332 Used by
 333 \fBvisudo\fR
 334 if
 335 \fRSUDO_EDITOR\fR
 336 is not set
 337 .TP 17n
 338 \fREDITOR\fR
 339 Used by
 340 \fBvisudo\fR
 341 if neither
 342 \fRSUDO_EDITOR\fR
 343 nor
 344 \fRVISUAL\fR
 345 is set
 346 .SH "FILES"
 347 .TP 26n
 348 \fI@sysconfdir@/sudo.conf\fR
 349 Sudo front end configuration
 350 .TP 26n
 351 \fI@sysconfdir@/sudoers\fR
 352 List of who can run what
 353 .TP 26n
 354 \fI@sysconfdir@/sudoers.tmp\fR
 355 Lock file for visudo
 356 .SH "DIAGNOSTICS"
 357 In addition to reporting
 358 \fIsudoers\fR
 359 parse errors,
 360 \fBvisudo\fR
 361 may produce the following messages:
 362 .TP 6n
 363 \fRsudoers file busy, try again later.\fR
 364 Someone else is currently editing the
 365 \fIsudoers\fR
 366 file.
 367 .TP 6n
 368 \fR@sysconfdir@/sudoers.tmp: Permission denied\fR
 369 You didn't run
 370 \fBvisudo\fR
 371 as root.
 372 .TP 6n
 373 \fRyou do not exist in the passwd database\fR
 374 Your user ID does not appear in the system passwd database.
 375 .TP 6n
 376 \fRWarning: {User,Runas,Host,Cmnd}_Alias referenced but not defined\fR
 377 Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias
 378 or you have a user or host name listed that consists solely of
 379 uppercase letters, digits, and the underscore
 380 (\(oq_\(cq)
 381 character.
 382 In the latter case, you can ignore the warnings
 383 (\fBsudo\fR
 384 will not complain)
 385 \&.
 386 The message is prefixed with the path name of the
 387 \fIsudoers\fR
 388 file and the line number where the undefined alias was used.
 389 In
 390 \fB\-s\fR
 391 (strict) mode these are errors, not warnings.
 392 .TP 6n
 393 \fRWarning: unused {User,Runas,Host,Cmnd}_Alias\fR
 394 The specified {User,Runas,Host,Cmnd}_Alias was defined but never
 395 used.
 396 The message is prefixed with the path name of the
 397 \fIsudoers\fR
 398 file and the line number where the unused alias was defined.
 399 You may wish to comment out or remove the unused alias.
 400 .TP 6n
 401 \fRWarning: cycle in {User,Runas,Host,Cmnd}_Alias\fR
 402 The specified {User,Runas,Host,Cmnd}_Alias includes a reference to
 403 itself, either directly or through an alias it includes.
 404 The message is prefixed with the path name of the
 405 \fIsudoers\fR
 406 file and the line number where the cycle was detected.
 407 This is only a warning unless
 408 \fBvisudo\fR
 409 is run in
 410 \fB\-s\fR
 411 (strict) mode as
 412 \fBsudo\fR
 413 will ignore cycles when parsing
 414 the
 415 \fIsudoers\fR
 416 file.
 417 .TP 6n
 418 \fRunknown defaults entry \&"name\&"\fR
 419 The
 420 \fIsudoers\fR
 421 file contains a
 422 \fRDefaults\fR
 423 setting not recognized by
 424 \fBvisudo\fR.
 425 .SH "SEE ALSO"
 426 vi(1),
 427 sudo.conf(@mansectform@),
 428 sudoers(@mansectform@),
 429 sudo(@mansectsu@),
 430 vipw(@mansectsu@)
 431 .SH "AUTHORS"
 432 Many people have worked on
 433 \fBsudo\fR
 434 over the years; this version consists of code written primarily by:
 435 .sp
 436 .RS 6n
 437 Todd C. Miller
 438 .RE
 439 .PP
 440 See the CONTRIBUTORS file in the
 441 \fBsudo\fR
 442 distribution (https://www.sudo.ws/contributors.html) for an
 443 exhaustive list of people who have contributed to
 444 \fBsudo\fR.
 445 .SH "CAVEATS"
 446 There is no easy way to prevent a user from gaining a root shell if
 447 the editor used by
 448 \fBvisudo\fR
 449 allows shell escapes.
 450 .SH "BUGS"
 451 If you feel you have found a bug in
 452 \fBvisudo\fR,
 453 please submit a bug report at https://bugzilla.sudo.ws/
 454 .SH "SUPPORT"
 455 Limited free support is available via the sudo-users mailing list,
 456 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 457 search the archives.
 458 .SH "DISCLAIMER"
 459 \fBvisudo\fR
 460 is provided
 461 \(lqAS IS\(rq
 462 and any express or implied warranties, including, but not limited
 463 to, the implied warranties of merchantability and fitness for a
 464 particular purpose are disclaimed.
 465 See the LICENSE file distributed with
 466 \fBsudo\fR
 467 or https://www.sudo.ws/license.html for complete details.