Annotation of src/usr.bin/sudo/visudo.pod, Revision 1.1
1.1 ! millert 1: =cut
! 2: Copyright (c) 1996,1998-2003 Todd C. Miller <Todd.Miller@courtesan.com>
! 3:
! 4: Permission to use, copy, modify, and distribute this software for any
! 5: purpose with or without fee is hereby granted, provided that the above
! 6: copyright notice and this permission notice appear in all copies.
! 7:
! 8: THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 9: WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 10: MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 11: ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 12: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 13: ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 14: OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 15: ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 16:
! 17: Sponsored in part by the Defense Advanced Research Projects
! 18: Agency (DARPA) and Air Force Research Laboratory, Air Force
! 19: Materiel Command, USAF, under agreement number F39502-99-1-0512.
! 20:
! 21: $Sudo: visudo.pod,v 1.38.2.6 2007/07/26 14:04:54 millert Exp $
! 22: =pod
! 23:
! 24: =head1 NAME
! 25:
! 26: visudo - edit the sudoers file
! 27:
! 28: =head1 SYNOPSIS
! 29:
! 30: B<visudo> [B<-c>] [B<-q>] [B<-s>] [B<-V>] [B<-f> I<sudoers>]
! 31:
! 32: =head1 DESCRIPTION
! 33:
! 34: B<visudo> edits the I<sudoers> file in a safe fashion, analogous to
! 35: L<vipw(8)>. B<visudo> locks the I<sudoers> file against multiple
! 36: simultaneous edits, provides basic sanity checks, and checks
! 37: for parse errors. If the I<sudoers> file is currently being
! 38: edited you will receive a message to try again later.
! 39:
! 40: There is a hard-coded list of editors that B<visudo> will use set
! 41: at compile-time that may be overridden via the I<editor> I<sudoers>
! 42: C<Default> variable. This list defaults to the path to L<vi(1)> on
! 43: your system, as determined by the I<configure> script. Normally,
! 44: B<visudo> does not honor the C<VISUAL> or C<EDITOR> environment
! 45: variables unless they contain an editor in the aforementioned editors
! 46: list. However, if B<visudo> is configured with the I<--with-enveditor>
! 47: flag or the I<env_editor> C<Default> variable is set in I<sudoers>,
! 48: B<visudo> will use any the editor defines by C<VISUAL> or C<EDITOR>.
! 49: Note that this can be a security hole since it allows the user to
! 50: execute any program they wish simply by setting C<VISUAL> or C<EDITOR>.
! 51:
! 52: B<visudo> parses the I<sudoers> file after the edit and will
! 53: not save the changes if there is a syntax error. Upon finding
! 54: an error, B<visudo> will print a message stating the line number(s)
! 55: where the error occurred and the user will receive the
! 56: "What now?" prompt. At this point the user may enter "e"
! 57: to re-edit the I<sudoers> file, "x" to exit without
! 58: saving the changes, or "Q" to quit and save changes. The
! 59: "Q" option should be used with extreme care because if B<visudo>
! 60: believes there to be a parse error, so will B<sudo> and no one
! 61: will be able to B<sudo> again until the error is fixed.
! 62: If "e" is typed to edit the I<sudoers> file after a parse error
! 63: has been detected, the cursor will be placed on the line where the
! 64: error occurred (if the editor supports this feature).
! 65:
! 66: =head1 OPTIONS
! 67:
! 68: B<visudo> accepts the following command line options:
! 69:
! 70: =over 4
! 71:
! 72: =item -c
! 73:
! 74: Enable B<check-only> mode. The existing I<sudoers> file will be
! 75: checked for syntax and a message will be printed to the
! 76: standard output detailing the status of I<sudoers>.
! 77: If the syntax check completes successfully, B<visudo> will
! 78: exit with a value of 0. If a syntax error is encountered,
! 79: B<visudo> will exit with a value of 1.
! 80:
! 81: =item -f
! 82:
! 83: Specify and alternate I<sudoers> file location. With this option
! 84: B<visudo> will edit (or check) the I<sudoers> file of your choice,
! 85: instead of the default, F<@sysconfdir@/sudoers>. The lock file used
! 86: is the specified I<sudoers> file with ".tmp" appended to it.
! 87:
! 88: =item -q
! 89:
! 90: Enable B<quiet> mode. In this mode details about syntax errors
! 91: are not printed. This option is only useful when combined with
! 92: the B<-c> flag.
! 93:
! 94: =item -s
! 95:
! 96: Enable B<strict> checking of the I<sudoers> file. If an alias is
! 97: used before it is defined, B<visudo> will consider this a parse
! 98: error. Note that it is not possible to differentiate between an
! 99: alias and a hostname or username that consists solely of uppercase
! 100: letters, digits, and the underscore ('_') character.
! 101:
! 102: =item -V
! 103:
! 104: The B<-V> (version) option causes B<visudo> to print its version number
! 105: and exit.
! 106:
! 107: =back
! 108:
! 109: =head1 ENVIRONMENT
! 110:
! 111: The following environment variables are used only if B<visudo>
! 112: was configured with the I<--with-env-editor> option:
! 113:
! 114: VISUAL Invoked by visudo as the editor to use
! 115: EDITOR Used by visudo if VISUAL is not set
! 116:
! 117: =head1 FILES
! 118:
! 119: @sysconfdir@/sudoers List of who can run what
! 120: @sysconfdir@/sudoers.tmp Lock file for visudo
! 121:
! 122: =head1 DIAGNOSTICS
! 123:
! 124: =over 4
! 125:
! 126: =item sudoers file busy, try again later.
! 127:
! 128: Someone else is currently editing the I<sudoers> file.
! 129:
! 130: =item @sysconfdir@/sudoers.tmp: Permission denied
! 131:
! 132: You didn't run B<visudo> as root.
! 133:
! 134: =item Can't find you in the passwd database
! 135:
! 136: Your userid does not appear in the system passwd file.
! 137:
! 138: =item Warning: undeclared Alias referenced near ...
! 139:
! 140: Either you are using a {User,Runas,Host,Cmnd}_Alias before
! 141: defining it or you have a user or hostname listed that
! 142: consists solely of uppercase letters, digits, and the
! 143: underscore ('_') character. If the latter, you can ignore
! 144: the warnings (B<sudo> will not complain). In B<-s> (strict)
! 145: mode these are errors, not warnings.
! 146:
! 147: =item Warning: runas_default set after old value is in use ...
! 148:
! 149: You have a I<runas_default> Defaults setting listed in the I<sudoers>
! 150: file after its value has already been used. This means that entries
! 151: prior to the I<runas_default> setting will match based on the default
! 152: value of I<runas_default> (C<@runas_default@>) whereas entries
! 153: B<after> the I<runas_default> setting will match based on the new
! 154: value. This is usually unintentional and in most cases the
! 155: <runas_default> setting should be placed before any C<Runas_Alias>
! 156: or User specifications. In B<-s> (strict) mode this is an error,
! 157: not a warning.
! 158:
! 159: =back
! 160:
! 161: =head1 SEE ALSO
! 162:
! 163: L<vi(1)>, L<sudoers(5)>, L<sudo(8)>, L<vipw(8)>
! 164:
! 165: =head1 AUTHOR
! 166:
! 167: Many people have worked on I<sudo> over the years; this version of
! 168: B<visudo> was written by:
! 169:
! 170: Todd Miller
! 171:
! 172: See the HISTORY file in the sudo distribution or visit
! 173: http://www.sudo.ws/sudo/history.html for more details.
! 174:
! 175: =head1 CAVEATS
! 176:
! 177: There is no easy way to prevent a user from gaining a root shell if
! 178: the editor used by B<visudo> allows shell escapes.
! 179:
! 180: =head1 BUGS
! 181:
! 182: If you feel you have found a bug in B<visudo>, please submit a bug report
! 183: at http://www.sudo.ws/sudo/bugs/
! 184:
! 185: =head1 SUPPORT
! 186:
! 187: Limited free support is available via the sudo-users mailing list,
! 188: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
! 189: search the archives.
! 190:
! 191: =head1 DISCLAIMER
! 192:
! 193: B<visudo> is provided ``AS IS'' and any express or implied warranties,
! 194: including, but not limited to, the implied warranties of merchantability
! 195: and fitness for a particular purpose are disclaimed. See the LICENSE
! 196: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
! 197: for complete details.