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

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