diff options
Diffstat (limited to 'doc')
41 files changed, 37858 insertions, 0 deletions
diff --git a/doc/CONTRIBUTORS b/doc/CONTRIBUTORS new file mode 100644 index 0000000..487322b --- /dev/null +++ b/doc/CONTRIBUTORS @@ -0,0 +1,230 @@ +The following list of people, sorted by last name, have contributed +code or patches to this implementation of sudo since I began +maintaining it in 1993. This list is known to be incomplete--if +you believe you should be listed, please send a note to sudo@sudo.ws. + + Ackeret, Matt + Adler, Mark + Allbery, Russ + Anderson, Jamie + Andrew, Nick + Andric, Dimitry + Barron, Danny + Bates, Tom + Behan, Zdeněk + Bellis, Ray + Benali, Elias + Beverly, Jamie + Boardman, Spider + Bostley, P.J. + Bowes, Keith + Boyce, Keith Garry + Brantley, Michael + Braun, Rob + Březina, Pavel + Brooks, Piete + Brown, Jerry + Burr, Michael E + Burton, Ross + Bussjaeger, Andreas + Calvin, Gary + Campbell, Aaron + Chazelas, Stephane + Cheloha, Scott + Čížek, Vítězslav + Coleman, Chris + Corzine, Deven T. + Cusack, Frank + Dai, Wei + Dill, David + Earickson, Jeff + Eckhardt, Drew + Edgington, Ben + Esipovich, Marc + Espie, Marc + Faigon, Ariel + Farrell, Brian + Fobes, Steve + Frysinger, Mike + G., Daniel Richard + Gailly, Jean-loup + Gelman, Stephen + Gerraty, Simon J. + Graber, Stephane + Guillory, B. + Hayman, Randy M. + Henke, Joachim + Hideaki, Yoshifuji + Hieb, Dave + Holloway, Nick + Hoover, Adam + Hunter, Michael T. + Hutchings, Ben + Irrgang, Eric + Jackson, Brian + Jackson, John R. + Jackson, Richard L., Jr. + Janssen, Mark + Jepeway, Chris + Jorge, Joel Peláe + Jover, Guillem + Juhani, Timo + Kikuchi, Ayamura + Kadow, Kevin + Kasal, Stepan + Kienenberger, Mike + King, Dale + King, Michael + Klyachkin, Andrey + Knoble, Jim + Knox, Tim + Komarnitsky, Alek O. + Kondrashov, Nikolai + Kopeček, Daniel + Kranenburg, Paul + Krause, David + Lakin, Eric + Larsen, Case + Levin, Dmitry V. + Libby, Kendall + Lobbes, Phillip E. + McIntyre, Jason + MacKenzie, David J. + McLaughlin, Tom + Makey, Jeff + Marchionna, Michael D. + Markham, Paul + Martinian, Emin + Meskes, Michael + Michael, David + Miller, Todd C. + Minier, Loïc + Moffat, Darren + Moldung, Jan Thomas + Morris, Charles + Mueller, Andreas + Müller, Dworkin + Nieusma, Jeff + Nikitser, Peter A. + Nussel, Ludwig + Ouellet, Jean-Philippe + Paquet, Eric + Paradis, Chantal + Pasteleurs, Frederic + Percival, Ted + Perera, Andres + Peron, Christian S.J. + Peschel, Aaron + Peslyak, Alexander + Peterson, Toby + Pettenò, Diego Elio + Pickett, Joel + Plotnick, Alex + de Raadt, Theo + Rasch, Gudleik + Reid, Steve + Richards, Matt + Rossum, Guido van + Rouillard, John P. + Rowe, William A., Jr. + Roy, Alain + Ruusamäe, Elan + Ryabinkin, Eygene + Sato, Yuichi + Sánchez, Wilfredo + Sanders, Miguel + Sasaki, Kan + Saucier, Jean-Francois + Schoenfeld, Patrick + Schuring, Arno + Schwarze, Ingo + Scott, Dougal + Sieger, Nick + Simon, Thor Lancelot + Slemko, Marc + Smith, Andy + Sobrado, Igor + Soulen, Steven + Spangler, Aaron + Spradling, Cloyce D. + Stier, Matthew + Stoeckmann, Tobias + Street, Russell + Stritzky, Tilo + Stroucken, Michael + Tarrall, Robert + Thomas, Matthew + Todd, Giles + Toft, Martin + Torek, Chris + Tucker, Darren + Uhl, Robert + Uzel, Petr + Valery, Reznic + Van Dinter, Theo + Venckus, Martynas + de Vries, Maarten + Wagner, Klaus + Walsh, Dan + Warburton, John + Webb, Kirk + Wetzel, Timm + Wieringen, Marco van + Wilk, Jakub + Winiger, Gary + Wood, David + Zacarias, Gustavo + Zolnowsky, John + +The following people have worked to translate sudo into +other languages as part of the Translation Project, see +https://translationproject.org for more details. + + Albuquerque, Pedro + Blättermann, Mario + Bogusz, Jakub + Buo-ren, Lin + Casagrande, Milo + Castro, Felipe + Cho, Seong-ho + Chornoivan, Yuri + Diéguez, Francisco + Fontenelle, Rafael + García-Fontes, Walter + Gezer, Volkan + Hamasaki, Takeshi + Hamming, Peter + Hansen, Joe + Hantrais, Frédéric + Hein, Jochen + Hufthammer, Karl Ove + Jerovšek, Damir + Karvonen, Jorma + Kazik, Dušan + Kelemen, Gábor + Keçeci, Mehmet + Košir, Klemen + Kozlov, Yuri + Kramer, Jakob + Krznar, Tomislav + Marchal, Frédéric + Margevičius, Algimantas + Maryanov, Pavel + Nikolić, Miroslav + Nylander, Daniel + Písař, Petr + Puente, Enol + Putanec, Božidar + Quân, Trần Ngọc + Rasmussen, Sebastian + Regueiro, Leandro + Sarıer, Özgür + Sendón, Abel + Sikrom, Åka + Spingos, Dimitris + Taniguchi, Yasuaki + Tomat, Fábio + Úr, Balázs + Uranga, Mikel Olasagasti + Vorotnikov, Artem + Wang, Wylmer diff --git a/doc/HISTORY b/doc/HISTORY new file mode 100644 index 0000000..0ad9512 --- /dev/null +++ b/doc/HISTORY @@ -0,0 +1,76 @@ +A Brief History of Sudo: + +The Early Years + +Sudo was first conceived and implemented by Bob Coggeshall and Cliff Spencer +around 1980 at the Department of Computer Science at SUNY/Buffalo. It ran on +a VAX-11/750 running 4.1BSD. An updated version, credited to Phil Betchel, +Cliff Spencer, Gretchen Phillips, John LoVerso and Don Gworek, was posted to +the net.sources Usenet newsgroup in December of 1985. + +Sudo at CU-Boulder + +In the Summer of 1986, Garth Snyder released an enhanced version of sudo. +For the next 5 years, sudo was fed and watered by a handful of folks at +CU-Boulder, including Bob Coggeshall, Bob Manchek, and Trent Hein. + +Root Group Sudo + +In 1991, Dave Hieb and Jeff Nieusma wrote a new version of sudo with an +enhanced sudoers format under contract to a consulting firm called "The Root +Group". This version was later released under the GNU public license. + +CU Sudo + +In 1994, after maintaining sudo informally within CU-Boulder for some time, +Todd C. Miller made a public release of "CU sudo" (version 1.3) with bug +fixes and support for more operating systems. The "CU" was added to +differentiate it from the "official" version from "The Root Group". + +In 1995, a new parser for the sudoers file was contributed by Chris Jepeway. +The new parser was a proper grammar (unlike the old one) and could work with +both sudo and visudo (previously they had slightly different parsers). + +In 1996, Todd, who had been maintaining sudo for several years in his spare +time, moved distribution of sudo from a CU-Boulder ftp site to his domain, +courtesan.com. + +Just Plain Sudo + +In 1999, the "CU" prefix was dropped from the name since there had been no +formal release of sudo from "The Root Group" since 1991 (the original +authors now work elsewhere). As of version 1.6, Sudo no longer contains any +of the original "Root Group" code and is available under an ISC-style +license. + +In 2001, the sudo web site, ftp site and mailing lists were moved from +courtesan.com to the sudo.ws domain (sudo.org was already taken). + +LDAP Integration + +In 2003, Nationwide Mutual Insurance Company contributed code written by +Aaron Spangler to store the sudoers data in LDAP. These changes were +incorporated into Sudo 1.6.8. + +New Parser + +In 2005, Todd rewrote the sudoers parser to better support the features that +had been added in the past ten years. This new parser removes some +limitations of the previous one, removes ordering constraints and adds +support for including multiple sudoers files. + +Quest Sponsorship + +In 2010, Quest Software began sponsoring Sudo development by hiring +Todd to work on Sudo as part of his full-time job. This enabled +the addition of I/O logging, the plugin interface, additional +regression tests, support for binary packages and more regular +releases. + +Present Day + +Sudo, in its current form, is maintained by: + + Todd C. Miller <Todd.Miller@sudo.ws> + +Todd continues to enhance sudo and fix bugs. diff --git a/doc/LICENSE b/doc/LICENSE new file mode 100644 index 0000000..46dd8f2 --- /dev/null +++ b/doc/LICENSE @@ -0,0 +1,236 @@ +Sudo is distributed under the following license: + + Copyright (c) 1994-1996, 1998-2019 + Todd C. Miller <Todd.Miller@sudo.ws> + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + Sponsored in part by the Defense Advanced Research Projects + Agency (DARPA) and Air Force Research Laboratory, Air Force + Materiel Command, USAF, under agreement number F39502-99-1-0512. + +The file redblack.c bears the following license: + + Copyright (c) 2001 Emin Martinian + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that neither the name of Emin + Martinian nor the names of any contributors are be used to endorse or + promote products derived from this software without specific prior + written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +The file reallocarray.c bears the following license: + + Copyright (c) 2008 Otto Moerbeek <otto@drijf.net> + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +The files getcwd.c, glob.c, glob.h, snprintf.c and sudo_queue.h bear the +following license: + + Copyright (c) 1989, 1990, 1991, 1993 + The Regents of the University of California. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + +The file fnmatch.c bears the following license: + + Copyright (c) 2011, VMware, Inc. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of the VMware, Inc. nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +The file getopt_long.c bears the following license: + + Copyright (c) 2000 The NetBSD Foundation, Inc. + All rights reserved. + + This code is derived from software contributed to The NetBSD Foundation + by Dieter Baron and Thomas Klausner. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS + ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +The file inet_pton.c bears the following license: + + Copyright (c) 1996 by Internet Software Consortium. + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS + ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE + CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS + ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + +The file arc4random.c bears the following license: + + Copyright (c) 1996, David Mazieres <dm@uun.org> + Copyright (c) 2008, Damien Miller <djm@openbsd.org> + Copyright (c) 2013, Markus Friedl <markus@openbsd.org> + Copyright (c) 2014, Theo de Raadt <deraadt@openbsd.org> + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +The file arc4random_uniform.c bears the following license: + + Copyright (c) 2008, Damien Miller <djm@openbsd.org> + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +The file getentropy.c bears the following license: + + Copyright (c) 2014 Theo de Raadt <deraadt@openbsd.org> + Copyright (c) 2014 Bob Beck <beck@obtuse.com> + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +The embedded copy of zlib bears the following license: + + Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. + + Jean-loup Gailly Mark Adler + jloup@gzip.org madler@alumni.caltech.edu diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..e8d2605 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,395 @@ +# +# Copyright (c) 2010-2015, 2017-2018 Todd C. Miller <Todd.Miller@sudo.ws> +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# +# @configure_input@ +# + +#### Start of system configuration section. #### + +srcdir = @srcdir@ +docdir = @docdir@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ + +# Tools to use +SED = @SED@ +IGOR = igor +MANDOC = @MANDOCPROG@ +MANCOMPRESS = @MANCOMPRESS@ +MANCOMPRESSEXT = @MANCOMPRESSEXT@ +TR = @TRPROG@ + +# Our install program supports extra flags... +INSTALL = $(SHELL) $(top_srcdir)/install-sh -c +INSTALL_OWNER = -o $(install_uid) -g $(install_gid) + +# Where to install things... +prefix = @prefix@ +exec_prefix = @exec_prefix@ +bindir = @bindir@ +sbindir = @sbindir@ +sysconfdir = @sysconfdir@ +libexecdir = @libexecdir@ +datarootdir = @datarootdir@ +localstatedir = @localstatedir@ +mandir = @mandir@ + +# Directory to copy man pages from +mansrcdir = @mansrcdir@ + +# Directory in which to install the man page +mantype = @MANTYPE@ +mansectsu = @mansectsu@ +mansectform = @mansectform@ +mandirexe = $(mandir)/@MANDIRTYPE@1 +mandirsu = $(mandir)/@MANDIRTYPE@$(mansectsu) +mandirform = $(mandir)/@MANDIRTYPE@$(mansectform) + +# User and group ids the installed files should be "owned" by +install_uid = 0 +install_gid = 0 + +# Set to non-empty for development mode +DEVEL = @DEVEL@ + +#### End of system configuration section. #### + +SHELL = @SHELL@ + +DOCS = $(mansrcdir)/cvtsudoers.$(mantype) $(mansrcdir)/sudo.$(mantype) \ + $(mansrcdir)/sudo.conf.$(mantype) $(mansrcdir)/sudo_plugin.$(mantype) \ + $(mansrcdir)/sudoers.$(mantype) $(mansrcdir)/sudoers.ldap.$(mantype) \ + $(mansrcdir)/sudoers_timestamp.$(mantype) \ + $(mansrcdir)/sudoreplay.$(mantype) $(mansrcdir)/visudo.$(mantype) + +DEVDOCS = $(srcdir)/cvtsudoers.man.in $(srcdir)/cvtsudoers.cat \ + $(srcdir)/sudo.conf.man.in $(srcdir)/sudo.conf.cat \ + $(srcdir)/sudo.man.in $(srcdir)/sudo.cat \ + $(srcdir)/sudo_plugin.man.in $(srcdir)/sudo_plugin.cat \ + $(srcdir)/sudoers.ldap.man.in $(srcdir)/sudoers.ldap.cat \ + $(srcdir)/sudoers.man.in $(srcdir)/sudoers.cat \ + $(srcdir)/sudoers_timestamp.man.in $(srcdir)/sudoers_timestamp.cat \ + $(srcdir)/sudoreplay.man.in $(srcdir)/sudoreplay.cat \ + $(srcdir)/visudo.man.in $(srcdir)/visudo.cat + +OTHER_DOCS = $(top_srcdir)/ChangeLog $(top_srcdir)/README \ + $(top_srcdir)/NEWS $(srcdir)/HISTORY $(srcdir)/CONTRIBUTORS \ + $(srcdir)/LICENSE $(srcdir)/TROUBLESHOOTING $(srcdir)/UPGRADE + +OTHER_DOCS_LDAP = $(top_srcdir)/README.LDAP $(srcdir)/schema.* + +VERSION = @PACKAGE_VERSION@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ + +all: $(DEVDOCS) $(DOCS) + +igor: all + @if [ "$(mantype)" != "mdoc" ]; then \ + echo "make igor only supported for mdoc manuals" 1>&2; \ + exit 1; \ + else \ + rval=0; \ + for m in $(DOCS); do \ + echo $(IGOR) -D $$m; \ + $(IGOR) -D $$m || rval=`expr $$rval + $$?`; \ + done; \ + exit $$rval; \ + fi + +lint: all + @if [ "$(mantype)" != "mdoc" ]; then \ + echo "make lint only supported for mdoc manuals" 1>&2; \ + exit 1; \ + else \ + rval=0; \ + for m in $(DOCS); do \ + echo $(MANDOC) -Tlint -Wstyle $$m; \ + $(MANDOC) -Tlint -Wstyle $$m || rval=`expr $$rval + $$?`; \ + done; \ + exit $$rval; \ + fi + +Makefile: $(srcdir)/Makefile.in + cd $(top_builddir) && ./config.status --file doc/Makefile + +.SUFFIXES: .man + +varsub: $(top_srcdir)/configure.ac + @if [ -n "$(DEVEL)" ]; then \ + printf 's#@%s@#1#\ns#@%s@#1#\ns#@%s@#1#\ns#@%s@#1#\ns#@%s@#/etc#g\ns#@%s@#/usr/local#g\ns#@%s@#5#g\ns#@%s@#8#g\ns#@%s@#%s#\n' SEMAN BAMAN LCMAN PSMAN sysconfdir prefix mansectform mansectsu PACKAGE_VERSION $(VERSION) > $@; \ + $(SED) -n '/Begin initial values for man page substitution/,/End initial values for man page substitution/{;p;}' $(top_srcdir)/configure.ac | $(SED) -e '/^#/d' -e 's/^/s#@/' -e 's/=[\\"]*/@#/' -e 's/[\\"]*$$/#g/' >> $@; \ + fi + +$(srcdir)/sudo.man.in: $(srcdir)/sudo.mdoc.in $(srcdir)/sudo.man.in.sed + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e 's/^\(\.nr [A-Z][A-Z]\) .[A-Z][A-Z]MAN./\1 1/' -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudo.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDO" \)"8"\(.*\)/\1"'$$mansectsu'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" -f $(srcdir)/sudo.man.in.sed > $@; \ + fi + +fixman.sed: $(srcdir)/fixman.sh + $(SHELL) $(srcdir)/fixman.sh $@ + +$(mansrcdir)/sudo.man: $(top_builddir)/config.status $(srcdir)/sudo.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudo.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudo.mdoc: $(top_builddir)/config.status $(srcdir)/sudo.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudo.cat: varsub $(srcdir)/sudo.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudo.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/visudo.man.in: $(srcdir)/visudo.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/visudo.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "VISUDO" \)"8"\(.*\)/\1"'$$mansectsu'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/visudo.man: $(top_builddir)/config.status $(srcdir)/visudo.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/visudo.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/visudo.mdoc: $(top_builddir)/config.status $(srcdir)/visudo.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/visudo.cat: varsub $(srcdir)/visudo.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/visudo.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudo.conf.man.in: $(srcdir)/sudo.conf.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudo.conf.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDO.CONF" \)"5"\(.*\)/\1"'$$mansectform'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/sudo.conf.man: $(top_builddir)/config.status $(srcdir)/sudo.conf.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudo.conf.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudo.conf.mdoc: $(top_builddir)/config.status $(srcdir)/sudo.conf.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudo.conf.cat: varsub $(srcdir)/sudo.conf.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudo.conf.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudoers.man.in: $(srcdir)/sudoers.mdoc.in $(srcdir)/sudoers.man.in.sed + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e 's/^\(\.nr [A-Z][A-Z]\) .[A-Z][A-Z]MAN./\1 1/' -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoers.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOERS" \)"5"\(.*\)/\1"'$$mansectform'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" -f $(srcdir)/sudoers.man.in.sed> $@; \ + fi + +$(mansrcdir)/sudoers.man: $(top_builddir)/config.status $(srcdir)/sudoers.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudoers.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudoers.mdoc: $(top_builddir)/config.status $(srcdir)/sudoers.mdoc.in $(srcdir)/fixmdoc.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudoers.mdoc.in | $(SED) -f $(srcdir)/fixmdoc.sed > $@ + +$(srcdir)/sudoers.cat: varsub $(srcdir)/sudoers.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudoers.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudoers.ldap.man.in: $(srcdir)/sudoers.ldap.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoers.ldap.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOERS.LDAP" \)"5"\(.*\)/\1"'$$mansectform'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/sudoers.ldap.man: $(top_builddir)/config.status $(srcdir)/sudoers.ldap.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudoers.ldap.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudoers.ldap.mdoc: $(top_builddir)/config.status $(srcdir)/sudoers.ldap.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudoers.ldap.cat: varsub $(srcdir)/sudoers.ldap.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudoers.ldap.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudoers_timestamp.man.in: $(srcdir)/sudoers_timestamp.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoers_timestamp.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOERS_TIMESTAMP" \)"5"\(.*\)/\1"'$$mansectform'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/sudoers_timestamp.man: $(top_builddir)/config.status $(srcdir)/sudoers_timestamp.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudoers_timestamp.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudoers_timestamp.mdoc: $(top_builddir)/config.status $(srcdir)/sudoers_timestamp.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudoers_timestamp.cat: varsub $(srcdir)/sudoers_timestamp.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudoers_timestamp.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/cvtsudoers.man.in: $(srcdir)/cvtsudoers.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/cvtsudoers.mdoc.in | $(MANDOC) -Tman | $(SED) -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/cvtsudoers.man: $(top_builddir)/config.status $(srcdir)/cvtsudoers.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/cvtsudoers.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/cvtsudoers.mdoc: $(top_builddir)/config.status $(srcdir)/cvtsudoers.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/cvtsudoers.cat: varsub $(srcdir)/cvtsudoers.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/cvtsudoers.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudoreplay.man.in: $(srcdir)/sudoreplay.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoreplay.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOREPLAY" \)"8"\(.*\)/\1"'$$mansectsu'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/sudoreplay.man: $(top_builddir)/config.status $(srcdir)/sudoreplay.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudoreplay.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudoreplay.mdoc: $(top_builddir)/config.status $(srcdir)/sudoreplay.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudoreplay.cat: varsub $(srcdir)/sudoreplay.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudoreplay.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +$(srcdir)/sudo_plugin.man.in: $(srcdir)/sudo_plugin.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \ + mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \ + $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudo_plugin.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDO_PLUGIN" \)"8"\(.*\)/\1"'$$mansectsu'"\2/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" > $@; \ + fi + +$(mansrcdir)/sudo_plugin.man: $(top_builddir)/config.status $(srcdir)/sudo_plugin.man.in fixman.sed + (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/sudo_plugin.man.in | $(SED) -f fixman.sed > $@ + +$(mansrcdir)/sudo_plugin.mdoc: $(top_builddir)/config.status $(srcdir)/sudo_plugin.mdoc.in + cd $(top_builddir) && $(SHELL) config.status --file=doc/$@ + +$(srcdir)/sudo_plugin.cat: varsub $(srcdir)/sudo_plugin.mdoc.in + @if [ -n "$(DEVEL)" ]; then \ + echo "Generating $@"; \ + $(SED) -f varsub $(srcdir)/sudo_plugin.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \ + fi + +pre-install: + +install: install-doc + +install-dirs: + $(SHELL) $(top_srcdir)/mkinstalldirs $(DESTDIR)$(docdir) \ + $(DESTDIR)$(mandirexe) $(DESTDIR)$(mandirform) $(DESTDIR)$(mandirsu) + +install-binaries: + +install-includes: + +install-doc: install-dirs + for f in $(OTHER_DOCS); do $(INSTALL) $(INSTALL_OWNER) -m 0644 $$f $(DESTDIR)$(docdir); done + @LDAP@for f in $(OTHER_DOCS_LDAP); do $(INSTALL) $(INSTALL_OWNER) -m 0644 $$f $(DESTDIR)$(docdir); done + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/cvtsudoers.$(mantype) $(DESTDIR)$(mandirexe)/cvtsudoers.1 + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudo.$(mantype) $(DESTDIR)$(mandirsu)/sudo.$(mansectsu) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudo_plugin.$(mantype) $(DESTDIR)$(mandirsu)/sudo_plugin.$(mansectsu) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoreplay.$(mantype) $(DESTDIR)$(mandirsu)/sudoreplay.$(mansectsu) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/visudo.$(mantype) $(DESTDIR)$(mandirsu)/visudo.$(mansectsu) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudo.conf.$(mantype) $(DESTDIR)$(mandirform)/sudo.conf.$(mansectform) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers.$(mantype) $(DESTDIR)$(mandirform)/sudoers.$(mansectform) + $(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers_timestamp.$(mantype) $(DESTDIR)$(mandirform)/sudoers_timestamp.$(mansectform) + @LDAP@$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers.ldap.$(mantype) $(DESTDIR)$(mandirform)/sudoers.ldap.$(mansectform) + @if test -n "$(MANCOMPRESS)"; then \ + for f in $(mandirexe)/cvtsudoers.1 $(mandirsu)/sudo.$(mansectsu) $(mandirsu)/sudo_plugin.$(mansectsu) $(mandirsu)/sudoreplay.$(mansectsu) $(mandirsu)/visudo.$(mansectsu) $(mandirform)/sudo.conf.$(mansectform) $(mandirform)/sudoers.$(mansectform) $(mandirform)/sudoers_timestamp.$(mansectform) $(mandirform)/sudoers.ldap.$(mansectform); do \ + if test -f $(DESTDIR)$$f; then \ + echo $(MANCOMPRESS) -f $(DESTDIR)$$f; \ + $(MANCOMPRESS) -f $(DESTDIR)$$f; \ + fi; \ + done; \ + rm -f $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu)$(MANCOMPRESSEXT); \ + echo ln -s sudo.$(mansectsu)$(MANCOMPRESSEXT) $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu)$(MANCOMPRESSEXT); \ + ln -s sudo.$(mansectsu)$(MANCOMPRESSEXT) $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu)$(MANCOMPRESSEXT); \ + else \ + rm -f $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu); \ + echo ln -s sudo.$(mansectsu) $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu); \ + ln -s sudo.$(mansectsu) $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu); \ + fi + +install-plugin: + +uninstall: + -rm -rf $(DESTDIR)$(docdir) + -rm -f $(DESTDIR)$(mandirexe)/cvtsudoers.1 \ + $(DESTDIR)$(mandirsu)/sudo.$(mansectsu) \ + $(DESTDIR)$(mandirsu)/sudoedit.$(mansectsu) \ + $(DESTDIR)$(mandirsu)/sudo_plugin.$(mansectsu) \ + $(DESTDIR)$(mandirsu)/sudoreplay.$(mansectsu) \ + $(DESTDIR)$(mandirsu)/visudo.$(mansectsu) \ + $(DESTDIR)$(mandirform)/sudo.conf.$(mansectform) \ + $(DESTDIR)$(mandirform)/sudoers.$(mansectform) \ + $(DESTDIR)$(mandirform)/sudoers_timestamp.$(mansectform) + $(DESTDIR)$(mandirform)/sudoers.ldap.$(mansectform) + +splint: + +cppcheck: + +pvs-log-files: + +pvs-studio: + +check: + +clean: + -rm -f varsub fixman.sed + +mostlyclean: clean + +distclean: clean + -rm -rf Makefile config.log *.man *.mdoc + +clobber: distclean + +realclean: distclean + +cleandir: distclean diff --git a/doc/TROUBLESHOOTING b/doc/TROUBLESHOOTING new file mode 100644 index 0000000..3bb6f14 --- /dev/null +++ b/doc/TROUBLESHOOTING @@ -0,0 +1,282 @@ +Troubleshooting tips and FAQ for Sudo +===================================== + +Q) When I run configure, it says "C compiler cannot create executables". +A) This usually means you either don't have a working compiler. This + could be due to the lack of a license or that some component of the + compiler suite could not be found. Check config.log for clues as + to why this is happening. On many systems, compiler components live + in /usr/ccs/bin which may not be in your PATH environment variable. + +Q) When I run configure, it says "sudo requires the 'ar' utility to build". +A) As part of the build process, sudo creates a temporary library containing + objects that are shared amongst the different sudo executables. + On Unix systems, the "ar" utility is used to do this. This error + indicates that "ar" is missing on your system. On Solaris systems, + you may need to install the SUNWbtool package. On other systems + "ar" may be included in the GNU binutils package. + +Q) Sudo compiles and installs OK but when I try to run it I get: + /usr/local/bin/sudo must be owned by uid 0 and have the setuid bit set +A) Sudo must be setuid root to do its work. Either /usr/local/bin/sudo + is not owned by uid 0 or the setuid bit is not set. This should have + been done for you by "make install" but you can fix it manually by + running the following as root: + # chown root /usr/local/bin/sudo; chmod 4755 /usr/local/bin/sudo + +Q) Sudo compiles and installs OK but when I try to run it I get: + effective uid is not 0, is /usr/local/bin/sudo on a file system with the + 'nosuid' option set or an NFS file system without root privileges? +A) The owner and permissions on the sudo binary appear to be OK but when + sudo ran, the setuid bit did not have an effect. There are two common + causes for this. The first is that the file system the sudo binary + is located on is mounted with the 'nosuid' mount option, which disables + setuid binaries. The output of the "mount" command should tell you if + the file system is mounted with the 'nosuid' option. The other possible + cause is that sudo is installed on an NFS-mounted file system that is + exported without root privileges. By default, NFS file systems are + exported with uid 0 mapped to a non-privileged uid (usually -2). You + should be able to determine whether sudo is located on an NFS-mounted + filesystem by running "df `which sudo'". + +Q) Sudo never gives me a chance to enter a password using PAM, it just + says 'Sorry, try again.' three times and exits. +A) You didn't setup PAM to work with sudo. On RedHat Linux or Fedora + Core this generally means installing the sample pam.conf file as + /etc/pam.d/sudo. See the example pam.conf file for hints on what + to use for other Linux systems. + +Q) Sudo says 'Account expired or PAM config lacks an "account" + section for sudo, contact your system administrator' and exits + but I know my account has not expired. +A) Your PAM config lacks an "account" specification. On Linux this + usually means you are missing a line like: + account required pam_unix.so + in /etc/pam.d/sudo. + +Q) Sudo is setup to log via syslog(3) but I'm not getting any log + messages. +A) Make sure you have an entry in your syslog.conf file to save + the sudo messages (see the example syslog.conf file). The default + log facility is authpriv (changeable via configure or in sudoers). + Don't forget to send a SIGHUP to your syslogd so that it re-reads + its conf file. Also, remember that syslogd does *not* create + log files, you need to create the file before syslogd will log + to it (ie: touch /var/log/sudo). + Note: the facility (e.g. "auth.debug") must be separated from the + destination (e.g. "/var/log/auth" or "@loghost") by + tabs, *not* spaces. This is a common error. + +Q) When sudo asks me for my password it never accepts what I enter even + though I know I entered my password correctly. +A) If you are not using pam and your system uses shadow passwords, + it is possible that sudo didn't properly detect that shadow + passwords are in use. Take a look at the generated config.h + file and verify that the C function used for shadow password + look ups was detected. For instance, for SVR4-style shadow + passwords, HAVE_GETSPNAM should be defined (you can search for + the string "shadow passwords" in config.h with your editor). + Note that there is no define for 4.4BSD-based shadow passwords + since that just uses the standard getpw* routines. + +Q) Can sudo use the ssh agent for authentication instead of asking + for the user's Unix password? +A) Not directly, but you can use a PAM module like pam_ssh_agent_auth + or pam_ssh for this purpose. + +Q) I don't want the sudoers file in /etc, how can I specify where it + should go? +A) Use the --sysconfdir option to configure. Ie: + configure --sysconfdir=/dir/you/want/sudoers/in + +Q) Can I put the sudoers file in NIS/NIS+ or do I have to have a + copy on each machine? +A) There is no support for making an NIS/NIS+ map/table out of + the sudoers file at this time. You can distribute the sudoers + file via rsync or rdist. It is also possible to NFS-mount the + sudoers file. If you use LDAP at your site you may be interested + in sudo's LDAP sudoers support, see the README.LDAP file and the + sudoers.ldap manual. + +Q) I don't run sendmail on my machine. Does this mean that I cannot + use sudo? +A) No, you just need to disable mailing with a line like: + Defaults !mailerpath + in your sudoers file or run configure with the --without-sendmail + option. + +Q) When I run visudo it uses vi as the editor and I hate vi. How + can I make it use another editor? +A) You can specify the editor to use in visudo in the sudoers file. + See the "editor" and "env_editor" entries in the sudoers manual. + The defaults can also be set at configure time using the + --with-editor and --with-env-editor configure options. + +Q) Sudo appears to be removing some variables from my environment, why? +A) By default, sudo runs commands with new, minimal environment. + It is possible to control what environment variables are copied + from the invoking user's environment using the "env_keep" setting + in sudoers. Another, less secure, option is to disable the + "env_reset" setting to copy all variables from the invoking + user's environment that are not considered "dangerous". See the + "Command Environment" section of the sudoers manual for more + information. + +Q) How can I keep sudo from asking for a password? +A) To specify this on a per-user (and per-command) basis, use the + 'NOPASSWD' tag right before the command list in sudoers. See + the sudoers man page and examples/sudoers for details. To disable + passwords completely, add !authenticate" to the Defaults line + in /etc/sudoers. You can also turn off authentication on a + per-user or per-host basis using a user or host-specific Defaults + entry in sudoers. To hard-code the global default, you can + configure with the --without-passwd option. + +Q) When I run configure, it dies with the following error: + "no acceptable cc found in $PATH". +A) /usr/ucb/cc was the only C compiler that configure could find. + You need to tell configure the path to the "real" C compiler + via the --with-CC option. On Solaris, the path is probably + something like "/opt/SUNWspro/SC4.0/bin/cc". If you have gcc + that will also work. + +Q) When I run configure, it dies with the following error: + Fatal Error: config.cache exists from another platform! + Please remove it and re-run configure. +A) configure caches the results of its tests in a file called + config.cache to make re-running configure speedy. However, + if you are building sudo for a different platform the results + in config.cache will be wrong so you need to remove config.cache. + You can do this by "rm config.cache" or "make realclean". + Note that "make realclean" will also remove any object files + and configure temp files that are laying around as well. + +Q) I built sudo on a Solaris 11 (or higher) machine but the resulting + binary doesn't work older Solaris versions. Why? +A) Starting with Solaris 11, asprintf(3) is included in the standard + C library. To build a version of sudo on a Solaris 11 machine that + will run on an older Solaris release, edit config.h and comment out + the lines: + #define HAVE_ASPRINTF 1 + #define HAVE_VASPRINTF 1 + and run make. + +Q) When I run "visudo" it says "sudoers file busy, try again later." + and doesn't do anything. +A) Someone else is currently editing the sudoers file with visudo. + +Q) When I try to use "cd" with sudo it says "cd: command not found". +A) "cd" is a shell built-in command, you can't run it as a command + since a child process (sudo) cannot affect the current working + directory of the parent (your shell). + +Q) When I try to use "cd" with sudo the command completes without + errors but nothing happens. +A) Even though "cd" is a shell built-in command, some operating systems + include a /usr/bin/cd command for some reason. A standalone + "cd" command is totally useless since a child process (cd) cannot + affect the current working directory of the parent (your shell). + Thus, "sudo cd /foo" will start a child process, change the + directory and immediately exit without doing anything useful. + +Q) When I run sudo it says I am not allowed to run the command as root + but I don't want to run it as root, I want to run it as another user. + My sudoers file entry looks like: + bob ALL=(oracle) ALL +A) The default user sudo tries to run things as is always root, even if + the invoking user can only run commands as a single, specific user. + This may change in the future but at the present time you have to + work around this using the 'runas_default' option in sudoers. + For example: + Defaults:bob runas_default=oracle + would achieve the desired result for the preceding sudoers fragment. + +Q) When I try to run sudo via ssh, I get the error: + sudo: no tty present and no askpass program specified +A) ssh does not allocate a tty by default when running a remote command. + Without a tty, sudo cannot disable echo when prompting for a password. + You can use ssh's "-t" option to force it to allocate a tty. + Alternately, if you do not mind your password being echoed to the + screen, you can use the "visiblepw" sudoers option to allow this. + +Q) When I try to use SSL-enabled LDAP with sudo I get an error: + unable to initialize SSL cert and key db: security library: bad database. + you must set TLS_CERT in /etc/ldap.conf to use SSL +A) On systems that use a Mozilla-derived LDAP SDK there must be a + certificate database in place to use SSL-encrypted LDAP connections. + This file is usually /var/ldap/cert8.db or /etc/ldap/cert8.db. + The actual number after "cert" will vary, depending on the version + of the LDAP SDK that is being used. If you do not have a certificate + database you can either copy one from a mozilla-derived browser, such + as firefox, or create one using the "certutil" command. You can run + "certutil" as follows and press the <return> (or <enter>) key at the + password prompt: + # certutil -N -d /var/ldap + Enter a password which will be used to encrypt your keys. + The password should be at least 8 characters long, + and should contain at least one non-alphabetic character. + + Enter new password: <return> + Re-enter password: <return> + +Q) On Solaris, when I run command via sudo it displays information + about the last login for every command. How can I fix this? +A) This output comes from /usr/lib/security/pam_unix_session.so.1. + To suppress it, first create /etc/pam.d/sudo if it doesn't exist: + cp /etc/pam.d/other /etc/pam.d/sudo + Then add "nowarn" to the end of the pam_unix_session.so.1 line: + session required pam_unix_session.so.1 nowarm + +Q) On HP-UX, when I run command via sudo it displays information + about the last successful login and last authentication failure + for every command. How can I fix this? +A) This output comes from /usr/lib/security/libpam_hpsec.so.1. + To suppress it, add a line like the following to /etc/pam.conf: + sudo session required libpam_hpsec.so.1 bypass_umask bypass_last_login + +Q) On HP-UX, the umask setting in sudoers has no effect. +A) If your /etc/pam.conf file has the libpam_hpsec.so.1 session module + enabled, you may need to a add line like the following to pam.conf: + sudo session required libpam_hpsec.so.1 bypass_umask + +Q) When I run "sudo -i shell_alias" I get "command not found" even + though the alias is defined in my shell startup files. +A) Commands run via "sudo -i" are executed by the shell in + non-interactive mode. The bash shell will ony parse aliases in + interactive mode unless the "expand_aliases" shell option is + set. If you add "shopt -s expand_aliases" to your .bash_profile + (or .profile if using that instead) the aliases should now be + available to "sudo -i". + +Q) When I run sudo on AIX I get the following error: + setuidx(ID_EFFECTIVE|ID_REAL|ID_SAVED, ROOT_UID): Operation not permitted. +A) AIX's Enhanced RBAC is preventing sudo from running. To fix + this, add the following entry to /etc/security/privcmds (adjust + the path to sudo as needed) and run the setkst command as root: + + /usr/local/bin/sudo: + accessauths = ALLOW_ALL + innateprivs = PV_DAC_GID,PV_DAC_R,PV_DAC_UID,PV_DAC_X,PV_FS_CHOWN,PV_PROC_PRIO,PV_NET_PORT,PV_NET_CNTL,PV_SU_UID + secflags = FSF_EPS + +Q) Sudo configures and builds without error but when I run it I get + a Segmentation fault. +A) If you are on a Linux system, the first thing to try is to run + configure with the --disable-pie option, then "make clean" and + "make". If that fixes the problem then your operating system + does not properly support position independent executables. + Please send a message to sudo@sudo.ws with system details such + as the Linux distro, kernel version and CPU architecture. + +Q) When I run configure I get the following error: + dlopen present but libtool doesn't appear to support your platform. +A) Libtool doesn't know how to support dynamic linking on the operating + system you are building for. If you are cross-compiling, you need to + specify the operating system, not just the CPU type. For example: + --host powerpc-unknown-linux + instead of just: + --host powerpc + +Q) How do you pronounce `sudo'? +A) The official pronunciation is soo-doo (for su "do"). However, an + alternate pronunciation, a homophone of "pseudo", is also common. diff --git a/doc/UPGRADE b/doc/UPGRADE new file mode 100644 index 0000000..1b787c1 --- /dev/null +++ b/doc/UPGRADE @@ -0,0 +1,463 @@ +Notes on upgrading from an older release +======================================== + +o Upgrading from a version prior to 1.8.26: + + Starting with version 1.8.26, sudo no long sets the USERNAME + environment variable when running commands. This is a non-standard + environment variable that was set on some older Linux systems. + Sudo still sets the LOGNAME, USER and, on AIX systems, LOGIN + environment variables. + + Handling of the LOGNAME, USER (and on AIX, LOGIN) environment + variables has changed slightly in version 1.8.26. Sudo now + treats those variables as a single unit. This means that if + one variable is preserved or removed from the environment using + env_keep, env_check or env_delete, the others are too. + +o Upgrading from a version prior to 1.8.23: + + In sudo 1.8.23 the "sudoers2ldif" script and the "visudo -x" + functionality has been superseded by the "cvtsudoers" utility. + The cvtsudoers utility is intended to be a drop-in replacement + for "sudoers2ldif". Because it uses the same parser as sudo + and visudo, cvtsudoers can perform a more accurate conversion + than sudoers2ldif could. + + To convert a sudoers file to JSON, the format option must be + specified. For example, instead of: + + visudo -f sudoers_file -x output_file + + one would use: + + cvtsudoers -f json -o output_file sudoers_file + + Note that unlike "visudo -x", "cvtsudoers" reads from the + standard input by default. Also, the base DN may be specified + on the command line, if desired, using the -b option. + +o Upgrading from a version prior to 1.8.20: + + Prior to version 1.8.20, when log_input, log_output or use_pty + were enabled, if any of the standard input, output or error + were not connected to a terminal, sudo would use a pipe. The + pipe allows sudo to interpose itself between the old standard + input, output or error and log the contents. Beginning with + version 1.8.20, a pipe is only used when I/O logging is enabled. + If use_pty is set without log_input or log_output, no pipe will + be used. Additionally, if log_input is set without log_output, + a pipe is only used for the standard input. Likewise, if + log_output is set without log_input, a pipe is only used for + the standard output and standard error. This results in a + noticeable change in behavior if the use_pty flag is set and no + terminal is present when running commands such as scripts that + execute other commands asynchronously (in the background). + Previously, sudo would exit immediately, causing background + commands to terminate with a broken pipe if they attempt to + write to the standard output or standard error. As of version + 1.8.20, a pipe will not be used in this case so the command + will no longer be terminated. + +o Upgrading from a version prior to 1.8.16: + + When editing files with sudoedit, files in a directory that is + writable by the invoking user may no longer be edited by default. + Also, sudoedit will refuse to follow a symbolic link in the + path to be edited if that directory containing the link is + writable by the user. This behavior can be disabled by negating + the sudoedit_checkdir sudoers option, which is now enabled by + default. + +o Upgrading from a version prior to 1.8.15: + + Prior to version 1.8.15, when env_reset was enabled (the default) + and the -s option was not used, the SHELL environment variable + was set to the shell of the invoking user. In 1.8.15 and above, + when env_reset is enabled and the -s option is not used, SHELL + is set based on the target user. + + When editing files with sudoedit, symbolic links will no longer + be followed by default. The old behavior can be restored by + enabling the sudoedit_follow option in sudoers or on a per-command + basis with the FOLLOW and NOFOLLOW tags. + + Prior to version 1.8.15, groups listed in sudoers that were not + found in the system group database were passed to the group + plugin, if any. Starting with 1.8.15, only groups of the form + %:group are resolved via the group plugin by default. The old + behavior can be restored by using the always_query_group_plugin + sudoers option. + + Locking of the time stamp file has changed in sudo 1.8.15. + Previously, the user's entire time stamp file was locked while + retrieving and updating a time stamp record. Now, only a single + record, specific to the tty or parent process ID, is locked. + This lock is held while the user enters their password. If + sudo is suspended at the password prompt (or run in the + background), the lock is dropped until sudo is resumed, at which + point it will be reacquired. This allows sudo to be used in a + pipeline even when a password is required--only one instance + of sudo will prompt for a password. + +o Upgrading from a version prior to 1.8.14: + + On HP-UX, sudo will no longer check for "plugin.sl" if "plugin.so" + is specified but does not exist. This was a temporary hack for + backwards compatibility with Sudo 1.8.6 and below when the + plugin path name was not listed in sudo.conf. A plugin path + name that explicitly ends in ".sl" will still work as expected. + +o Upgrading from a version prior to 1.8.12: + + On Solaris, sudo is now able to determine the NIS domain name. + As a result, if you had previously been using netgroups that + do not include the domain, you will need to either set the + domain in the entry or leave the domain part of the tuple blank. + + For example, the following will no longer work: + my-hosts (foo,-,-) (bar,-,-) (baz,-,-) + and should be changed to: + my-hosts (foo,-,) (bar,-,) (baz,-,) + +o Upgrading from a version prior to 1.8.10: + + The time stamp file format has changed in sudo 1.8.10. There + is now a single time stamp file for each user, even when tty-based + time stamps are used. Each time stamp file may contain multiple + records to support tty-based time stamps as well as multiple + authentication users. On systems that support it, monotonic + time is stored instead of wall clock time. As a result, it is + important that the time stamp files not persist when the system + reboots. For this reason, the default location for the time + stamp files has changed back to a directory located in /var/run. + Systems that do not have /var/run (e.g. AIX) or that do not clear + it on boot (e.g. HP-UX) will need to clear the time stamp + directory via a start up script. Such a script is installed by + default on AIX and HP-UX systems. + + Because there is now a single time stamp file per user, the -K + option will remove all of the user's time stamps, not just the + time stamp for the current terminal. + + Lecture status is now stored separately from the time stamps + in a separate directory: /var/db/sudo/lectured, /var/lib/sudo/lectured + or /var/adm/sudo/lectured depending on what is present on the + system. + + LDAP-based sudoers now uses a default search filter of + (objectClass=sudoRole) for more efficient queries. It is + possible to disable the default search filter by specifying + SUDOERS_SEARCH_FILTER in ldap.conf but omitting a value. + +o Upgrading from a version prior to 1.8.7: + + Sudo now stores its libexec files in a "sudo" sub-directory + instead of in libexec itself. For backwards compatibility, if + the plugin is not found in the default plugin directory, sudo + will check the parent directory default directory ends in "/sudo". + + The default sudo plugins now all use the .so extension, regardless + of the extension used by native shared libraries. For backwards + compatibility, sudo on HP-UX will also search for a plugin with + an .sl extension if the .so version is not found. + + Handling of users belonging to a large number of groups has + changed. Previously, sudo would only use the group list from + the kernel unless the system_group plugin was enabled in sudoers. + Now, sudo will query the groups database if the user belongs + to the maximum number of groups supported by the kernel. See + the group_source and max_groups settings in the sudo.conf manual + for details. + +o Upgrading from a version prior to 1.8.2: + + When matching Unix groups in the sudoers file, sudo will now + match based on the name of the group as it appears in sudoers + instead of the group ID. This can substantially reduce the + number of group lookups for sudoers files that contain a large + number of groups. There are a few side effects of this change. + + 1) Unix groups with different names but the same group ID are + can no longer be used interchangeably. Sudo will look up all + of a user's groups by group ID and use the resulting group + names when matching sudoers entries. If there are multiple + groups with the same ID, the group name returned by the + system getgrgid() library function is the name that will be + used when matching sudoers entries. + + 2) Unix group names specified in the sudoers file that are + longer than the system maximum will no longer match. For + instance, if there is a Unix group "fireflie" on a system + where group names are limited to eight characters, "%fireflies" + in sudoers will no longer match "fireflie". Previously, a + lookup by name of the group "fireflies" would have matched + the "fireflie" group on most systems. + + The legacy group matching behavior may be restored by enabling + the match_group_by_gid Defaults option in sudoers available + in sudo 1.8.18 and higher. + +o Upgrading from a version prior to 1.8.1: + + Changes in the sudoers parser could result in parse errors for + existing sudoers file. These changes cause certain erroneous + entries to be flagged as errors where before they allowed. + Changes include: + + Combining multiple Defaults entries with a backslash. E.g. + + Defaults set_path \ + Defaults syslog + + which should be: + + Defaults set_path + Defaults syslog + + Also, double-quoted strings with a missing end-quote are now + detected and result in an error. Previously, text starting a + double quote and ending with a newline was ignored. E.g. + + Defaults set_path"foo + + In previous versions of sudo, the `"foo' portion would have + been ignored. + + To avoid problems, sudo 1.8.1's "make install" will not install + a new sudo binary if the existing sudoers file has errors. + + In Sudo 1.8.1 the "noexec" functionality has moved out of the + sudoers policy plugin and into the sudo front-end. As a result, + the path to the noexec file is now specified in the sudo.conf + file instead of the sudoers file. If you have a sudoers file + that uses the "noexec_file" option, you will need to move the + definition to the sudo.conf file instead. + + Old style in /etc/sudoers: + Defaults noexec_file=/usr/local/libexec/sudo_noexec.so + + New style in /etc/sudo.conf: + Path noexec /usr/local/libexec/sudo_noexec.so + +o Upgrading from a version prior to 1.8.0: + + Starting with version 1.8.0, sudo uses a modular framework to + support policy and I/O logging plugins. The default policy + plugin is "sudoers" which provides the traditional sudoers + evaluation and I/O logging. Plugins are typically located in + /usr/libexec or /usr/local/libexec, though this is system-dependent. + The sudoers plugin is named "sudoers.so" on most systems. + + The sudo.conf file, usually stored in /etc, is used to configure + plugins. This file is optional--if no plugins are specified + in sudo.conf, the "sudoers" plugin is used. See the example + sudo.conf file in the doc directory or refer to the updated + sudo manual to see how to configure sudo.conf. + + The "askpass" setting has moved from the sudoers file to the + sudo.conf file. If you have a sudoers file that uses the + "askpass" option, you will need to move the definition to the + sudo.conf file. + + Old style in /etc/sudoers: + Defaults askpass=/usr/X11R6/bin/ssh-askpass + + New style in /etc/sudo.conf: + Path askpass /usr/X11R6/bin/ssh-askpass + +o Upgrading from a version prior to 1.7.5: + + Sudo 1.7.5 includes an updated LDAP schema with support for + the sudoNotBefore, sudoNotAfter and sudoOrder attributes. + + The sudoNotBefore and sudoNotAfter attribute support is only + used when the SUDOERS_TIMED setting is enabled in ldap.conf. + If enabled, those attributes are used directly when constructing + an LDAP filter. As a result, your LDAP server must have the + updated schema if you want to use sudoNotBefore and sudoNotAfter. + + The sudoOrder support does not affect the LDAP filter sudo + constructs and so there is no need to explicitly enable it in + ldap.conf. If the sudoOrder attribute is not present in an + entry, a value of 0 is used. If no entries contain sudoOrder + attributes, the results are in whatever order the LDAP server + returns them, as in past versions of sudo. + + Older versions of sudo will simply ignore the new attributes + if they are present in an entry. There are no compatibility + problems using the updated schema with older versions of sudo. + +o Upgrading from a version prior to 1.7.4: + + Starting with sudo 1.7.4, the time stamp files have moved from + /var/run/sudo to either /var/db/sudo, /var/lib/sudo or /var/adm/sudo. + The directories are checked for existence in that order. This + prevents users from receiving the sudo lecture every time the + system reboots. Time stamp files older than the boot time are + ignored on systems where it is possible to determine this. + + Additionally, the tty_tickets sudoers option is now enabled by + default. To restore the old behavior (single time stamp per user), + add a line like: + Defaults !tty_tickets + to sudoers or use the --without-tty-tickets configure option. + + The HOME and MAIL environment variables are now reset based on the + target user's password database entry when the env_reset sudoers option + is enabled (which is the case in the default configuration). Users + wishing to preserve the original values should use a sudoers entry like: + Defaults env_keep += HOME + to preserve the old value of HOME and + Defaults env_keep += MAIL + to preserve the old value of MAIL. + + NOTE: preserving HOME has security implications since many programs + use it when searching for configuration files. Adding HOME to env_keep + may enable a user to run unrestricted commands via sudo. + + The default syslog facility has changed from "local2" to "authpriv" + (or "auth" if the operating system doesn't have "authpriv"). + The --with-logfac configure option can be used to change this + or it can be changed in the sudoers file. + +o Upgrading from a version prior to 1.7.0: + + Starting with sudo 1.7.0, comments in the sudoers file must not + have a digit or minus sign immediately after the comment character + ('#'). Otherwise, the comment may be interpreted as a user or + group ID. + + When sudo is build with LDAP support the /etc/nsswitch.conf file is + now used to determine the sudoers sea ch order. sudo will default to + only using /etc/sudoers unless /etc/nsswitch.conf says otherwise. + This can be changed with an nsswitch.conf line, e.g.: + sudoers: ldap files + Would case LDAP to be searched first, then the sudoers file. + To restore the pre-1.7.0 behavior, run configure with the + --with-nsswitch=no flag. + + Sudo now ignores user .ldaprc files as well as system LDAP defaults. + All LDAP configuration is now in /etc/ldap.conf (or whichever file + was specified by configure's --with-ldap-conf-file option). + If you are using TLS, you may now need to specify: + tls_checkpeer no + in sudo's ldap.conf unless ldap.conf references a valid certificate + authority file(s). + + Please also see the NEWS file for a list of new features in + sudo 1.7.0. + +o Upgrading from a version prior to 1.6.9: + + Starting with sudo 1.6.9, if an OS supports a modular authentication + method such as PAM, it will be used by default by configure. + + Environment variable handling has changed significantly in sudo + 1.6.9. Prior to version 1.6.9, sudo would preserve the user's + environment, pruning out potentially dangerous variables. + Beginning with sudo 1.6.9, the environment is reset to a default + set of values with only a small number of "safe" variables + preserved. To preserve specific environment variables, add + them to the "env_keep" list in sudoers. E.g. + + Defaults env_keep += "EDITOR" + + The old behavior can be restored by negating the "env_reset" + option in sudoers. E.g. + + Defaults !env_reset + + There have also been changes to how the "env_keep" and + "env_check" options behave. + + Prior to sudo 1.6.9, the TERM and PATH environment variables + would always be preserved even if the env_keep option was + redefined. That is no longer the case. Consequently, if + env_keep is set with "=" and not simply appended to (i.e. using + "+="), PATH and TERM must be explicitly included in the list + of environment variables to keep. The LOGNAME, SHELL, USER, + and USERNAME environment variables are still always set. + + Additionally, the env_check setting previously had no effect + when env_reset was set (which is now on by default). Starting + with sudo 1.6.9, environment variables listed in env_check are + also preserved in the env_reset case, provided that they do not + contain a '/' or '%' character. Note that it is not necessary + to also list a variable in env_keep--having it in env_check is + sufficient. + + The default lists of variables to be preserved and/or checked + are displayed when sudo is run by root with the -V flag. + +o Upgrading from a version prior to 1.6.8: + + Prior to sudo 1.6.8, if /var/run did not exist, sudo would put + the time stamp files in /tmp/.odus. As of sudo 1.6.8, the + time stamp files will be placed in /var/adm/sudo or /usr/adm/sudo + if there is no /var/run directory. This directory will be + created if it does not already exist. + + Previously, a sudoers entry that explicitly prohibited running + a command as a certain user did not override a previous entry + allowing the same command. This has been fixed in sudo 1.6.8 + such that the last match is now used (as it is documented). + Hopefully no one was depending on the previous (buggy) behavior. + +o Upgrading from a version prior to 1.6: + + As of sudo 1.6, parsing of runas entries and the NOPASSWD tag + has changed. Prior to 1.6, a runas specifier applied only to + a single command directly following it. Likewise, the NOPASSWD + tag only allowed the command directly following it to be run + without a password. Starting with sudo 1.6, both the runas + specifier and the NOPASSWD tag are "sticky" for an entire + command list. So, given the following line in sudo < 1.6 + + millert ALL=(daemon) NOPASSWD:/usr/bin/whoami,/bin/ls + + millert would be able to run /usr/bin/whoami as user daemon + without a password and /bin/ls as root with a password. + + As of sudo 1.6, the same line now means that millert is able + to run run both /usr/bin/whoami and /bin/ls as user daemon + without a password. To expand on this, take the following + example: + + millert ALL=(daemon) NOPASSWD:/usr/bin/whoami, (root) /bin/ls, \ + /sbin/dump + + millert can run /usr/bin/whoami as daemon and /bin/ls and + /sbin/dump as root. No password need be given for either + command. In other words, the "(root)" sets the default runas + user to root for the rest of the list. If we wanted to require + a password for /bin/ls and /sbin/dump the line could be written + as: + + millert ALL=(daemon) NOPASSWD:/usr/bin/whoami, \ + (root) PASSWD:/bin/ls, /sbin/dump + + Additionally, sudo now uses a per-user time stamp directory + instead of a time stamp file. This allows tty time stamps to + simply be files within the user's time stamp dir. For the + default, non-tty case, the time stamp on the directory itself + is used. + + Also, the temporary file used by visudo is now /etc/sudoers.tmp + since some versions of vipw on systems with shadow passwords use + /etc/stmp for the temporary shadow file. + +o Upgrading from a version prior to 1.5: + + By default, sudo expects the sudoers file to be mode 0440 and + to be owned by user and group 0. This differs from version 1.4 + and below which expected the sudoers file to be mode 0400 and + to be owned by root. Doing a `make install' will set the sudoers + file to the new mode and group. If sudo encounters a sudoers + file with the old permissions it will attempt to update it to + the new scheme. You cannot, however, use a sudoers file with + the new permissions with an old sudo binary. It is suggested + that if have a means of distributing sudo you distribute the + new binaries first, then the new sudoers file (or you can leave + sudoers as is and sudo will fix the permissions itself as long + as sudoers is on a local file system). diff --git a/doc/cvtsudoers.cat b/doc/cvtsudoers.cat new file mode 100644 index 0000000..d6fcbe3 --- /dev/null +++ b/doc/cvtsudoers.cat @@ -0,0 +1,282 @@ +CVTSUDOERS(1) General Commands Manual CVTSUDOERS(1) + +NNAAMMEE + ccvvttssuuddooeerrss - convert between sudoers file formats + +SSYYNNOOPPSSIISS + ccvvttssuuddooeerrss [--eehhMMppVV] [--bb _d_n] [--cc _c_o_n_f___f_i_l_e] [--dd _d_e_f_t_y_p_e_s] + [--ff _o_u_t_p_u_t___f_o_r_m_a_t] [--ii _i_n_p_u_t___f_o_r_m_a_t] [--II _i_n_c_r_e_m_e_n_t] + [--mm _f_i_l_t_e_r] [--oo _o_u_t_p_u_t___f_i_l_e] [--OO _s_t_a_r_t___p_o_i_n_t] [--PP _p_a_d_d_i_n_g] + [--ss _s_e_c_t_i_o_n_s] [_i_n_p_u_t___f_i_l_e] + +DDEESSCCRRIIPPTTIIOONN + ccvvttssuuddooeerrss can be used to convert between _s_u_d_o_e_r_s security policy file + formats. The default input format is sudoers. The default output format + is LDIF. It is only possible to convert a _s_u_d_o_e_r_s file that is + syntactically correct. + + If no _i_n_p_u_t___f_i_l_e is specified, or if it is `-', the policy is read from + the standard input. By default, the result is written to the standard + output. + + The options are as follows: + + --bb _d_n, ----bbaassee=_d_n + The base DN (distinguished name) that will be used when + performing LDAP queries. Typically this is of the form + ou=SUDOers,dc=my-domain,dc=com for the domain my-domain.com. + If this option is not specified, the value of the + SUDOERS_BASE environment variable will be used instead. Only + necessary when converting to LDIF format. + + --cc _c_o_n_f___f_i_l_e, ----ccoonnffiigg=_c_o_n_f___f_i_l_e + Specify the path to the configuration file. Defaults to + _/_e_t_c_/_c_v_t_s_u_d_o_e_r_s_._c_o_n_f. + + --dd _d_e_f_t_y_p_e_s, ----ddeeffaauullttss=_d_e_f_t_y_p_e_s + Only convert Defaults entries of the specified types. One or + more Defaults types may be specified, separated by a comma + (`,'). The supported types are: + + all All Defaults entries. + + global Global Defaults entries that are applied regardless + of user, runas, host or command. + + user Per-user Defaults entries. + + runas Per-runas user Defaults entries. + + host Per-host Defaults entries. + + command Per-command Defaults entries. + + See the DDeeffaauullttss section in sudoers(4) for more information. + + If the --dd option is not specified, all Defaults entries will + be converted. + + --ee, ----eexxppaanndd--aalliiaasseess + Expand aliases in _i_n_p_u_t___f_i_l_e. Aliases are preserved by + default when the output _f_o_r_m_a_t is JSON or sudoers. + + --ff _o_u_t_p_u_t___f_o_r_m_a_t, ----oouuttppuutt--ffoorrmmaatt=_o_u_t_p_u_t___f_o_r_m_a_t + Specify the output format (case-insensitive). The following + formats are supported: + + JSON JSON (JavaScript Object Notation) files are usually + easier for third-party applications to consume than + the traditional _s_u_d_o_e_r_s format. The various values + have explicit types which removes much of the + ambiguity of the _s_u_d_o_e_r_s format. + + LDIF LDIF (LDAP Data Interchange Format) files can be + imported into an LDAP server for use with + sudoers.ldap(4). + + Conversion to LDIF has the following limitations: + + ++oo Command, host, runas and user-specific Defaults + lines cannot be translated as they don't have an + equivalent in the sudoers LDAP schema. + + ++oo Command, host, runas and user aliases are not + supported by the sudoers LDAP schema so they are + expanded during the conversion. + + sudoers Traditional sudoers format. A new sudoers file + will be reconstructed from the parsed input file. + Comments are not preserved and data from any + include files will be output inline. + + --hh, ----hheellpp Display a short help message to the standard output and exit. + + --ii _i_n_p_u_t___f_o_r_m_a_t, ----iinnppuutt--ffoorrmmaatt=_i_n_p_u_t___f_o_r_m_a_t + Specify the input format. The following formats are + supported: + + LDIF LDIF (LDAP Data Interchange Format) files can be + exported from an LDAP server to convert security + policies used by sudoers.ldap(4). If a base DN + (distinguished name) is specified, only sudoRole + objects that match the base DN will be processed. + Not all sudoOptions specified in a sudoRole can be + translated from LDIF to sudoers format. + + sudoers Traditional sudoers format. This is the default + input format. + + --II _i_n_c_r_e_m_e_n_t, ----iinnccrreemmeenntt=_i_n_c_r_e_m_e_n_t + When generating LDIF output, increment each sudoOrder + attribute by the specified number. Defaults to an increment + of 1. + + --mm _f_i_l_t_e_r, ----mmaattcchh=_f_i_l_t_e_r + Only output rules that match the specified _f_i_l_t_e_r. A _f_i_l_t_e_r + expression is made up of one or more kkeeyy == _v_a_l_u_e pairs, + separated by a comma (`,'). The kkeeyy may be "user", "group" + or "host". For example, uusseerr = _o_p_e_r_a_t_o_r or hhoosstt = _w_w_w. An + upper-case User_Alias or Host_Alias may be specified as the + "user" or "host". + + A matching _s_u_d_o_e_r_s rule may also include users, groups and + hosts that are not part of the _f_i_l_t_e_r. This can happen when + a rule includes multiple users, groups or hosts. To prune + out any non-matching user, group or host from the rules, the + --pp option may be used. + + By default, the password and group databases are not + consulted when matching against the filter so the users and + groups do not need to be present on the local system (see the + --MM option). Only aliases that are referenced by the filtered + policy rules will be displayed. + + --MM, ----mmaattcchh--llooccaall + When the --mm option is also specified, use password and group + database information when matching users and groups in the + filter. Only users and groups in the filter that exist on + the local system will match, and a user's groups will + automatically be added to the filter. If the --MM is _n_o_t + specified, users and groups in the filter do not need to + exist on the local system, but all groups used for matching + must be explicitly listed in the filter. + + --oo _o_u_t_p_u_t___f_i_l_e, ----oouuttppuutt=_o_u_t_p_u_t___f_i_l_e + Write the converted output to _o_u_t_p_u_t___f_i_l_e. If no _o_u_t_p_u_t___f_i_l_e + is specified, or if it is `-', the converted _s_u_d_o_e_r_s policy + will be written to the standard output. + + --OO _s_t_a_r_t___p_o_i_n_t, ----oorrddeerr--ssttaarrtt=_s_t_a_r_t___p_o_i_n_t + When generating LDIF output, use the number specified by + _s_t_a_r_t___p_o_i_n_t in the sudoOrder attribute of the first sudoRole + object. Subsequent sudoRole object use a sudoOrder value + generated by adding an _i_n_c_r_e_m_e_n_t, see the --II option for + details. Defaults to a starting point of 1. A starting + point of 0 will disable the generation of sudoOrder + attributes in the resulting LDIF file. + + --pp, ----pprruunnee--mmaattcchheess + When the --mm option is also specified, ccvvttssuuddooeerrss will prune + out non-matching users, groups and hosts from matching + entries. + + --PP _p_a_d_d_i_n_g, ----ppaaddddiinngg=_p_a_d_d_i_n_g + When generating LDIF output, construct the initial sudoOrder + value by concatenating _o_r_d_e_r___s_t_a_r_t and _i_n_c_r_e_m_e_n_t, padding the + _i_n_c_r_e_m_e_n_t with zeros until it consists of _p_a_d_d_i_n_g digits. + For example, if _o_r_d_e_r___s_t_a_r_t is 1027, _p_a_d_d_i_n_g is 3, and + _i_n_c_r_e_m_e_n_t is 1, the value of sudoOrder for the first entry + will be 1027000, followed by 1027001, 1027002, etc. If the + number of sudoRole entries is larger than the padding would + allow, ccvvttssuuddooeerrss will exit with an error. By default, no + padding is performed. + + --ss _s_e_c_t_i_o_n_s, ----ssuupppprreessss=_s_e_c_t_i_o_n_s + Suppress the output of specific _s_e_c_t_i_o_n_s of the security + policy. One or more section names may be specified, + separated by a comma (`,'). The supported section name are: + ddeeffaauullttss, aalliiaasseess and pprriivviilleeggeess (which may be shortened to + pprriivvss). + + --VV, ----vveerrssiioonn + Print the ccvvttssuuddooeerrss and _s_u_d_o_e_r_s grammar versions and exit. + + Options in the form "keyword = value" may also be specified in a + configuration file, _/_e_t_c_/_c_v_t_s_u_d_o_e_r_s_._c_o_n_f by default. The following + keywords are recognized: + + ddeeffaauullttss == _d_e_f_t_y_p_e_s + See the description of the --dd command line option. + + eexxppaanndd__aalliiaasseess == _y_e_s | _n_o + See the description of the --ee command line option. + + iinnppuutt__ffoorrmmaatt == _l_d_i_f | _s_u_d_o_e_r_s + See the description of the --ii command line option. + + mmaattcchh == _f_i_l_t_e_r + See the description of the --mm command line option. + + oorrddeerr__iinnccrreemmeenntt == _i_n_c_r_e_m_e_n_t + See the description of the --II command line option. + + oorrddeerr__ssttaarrtt == _s_t_a_r_t___p_o_i_n_t + See the description of the --OO command line option. + + oouuttppuutt__ffoorrmmaatt == _j_s_o_n | _l_d_i_f | _s_u_d_o_e_r_s + See the description of the --ff command line option. + + ppaaddddiinngg == _p_a_d_d_i_n_g + See the description of the --PP command line option. + + pprruunnee__mmaattcchheess == _y_e_s | _n_o + See the description of the --pp command line option. + + ssuuddooeerrss__bbaassee == _d_n + See the description of the --bb command line option. + + ssuupppprreessss == _s_e_c_t_i_o_n_s + See the description of the --ss command line option. + + Options on the command line will override values from the configuration + file. + +FFIILLEESS + _/_e_t_c_/_c_v_t_s_u_d_o_e_r_s_._c_o_n_f default configuration for cvtsudoers + +EEXXAAMMPPLLEESS + Convert _/_e_t_c_/_s_u_d_o_e_r_s to LDIF (LDAP Data Interchange Format) where the + _l_d_a_p_._c_o_n_f file uses a _s_u_d_o_e_r_s___b_a_s_e of my-domain,dc=com, storing the + result in _s_u_d_o_e_r_s_._l_d_i_f: + + $ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \ + /etc/sudoers + + Convert _/_e_t_c_/_s_u_d_o_e_r_s to JSON format, storing the result in _s_u_d_o_e_r_s_._j_s_o_n: + + $ cvtsudoers -f json -o sudoers.json /etc/sudoers + + Parse _/_e_t_c_/_s_u_d_o_e_r_s and display only rules that match user _a_m_b_r_o_s_e on host + _h_a_s_t_u_r: + + $ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers + + Same as above, but expand aliases and prune out any non-matching users + and hosts from the expanded entries. + + $ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers + + Convert _s_u_d_o_e_r_s_._l_d_i_f from LDIF to traditional _s_u_d_o_e_r_s format: + + $ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif + +SSEEEE AALLSSOO + sudoers(4), sudoers.ldap(4), sudo(1m) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +BBUUGGSS + If you feel you have found a bug in ccvvttssuuddooeerrss, please submit a bug + report at https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ccvvttssuuddooeerrss is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 December 11, 2018 Sudo 1.8.26 diff --git a/doc/cvtsudoers.man.in b/doc/cvtsudoers.man.in new file mode 100644 index 0000000..41929ea --- /dev/null +++ b/doc/cvtsudoers.man.in @@ -0,0 +1,511 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "CVTSUDOERS" "1" "December 11, 2018" "Sudo @PACKAGE_VERSION@" "General Commands Manual" +.nh +.if n .ad l +.SH "NAME" +\fBcvtsudoers\fR +\- convert between sudoers file formats +.SH "SYNOPSIS" +.HP 11n +\fBcvtsudoers\fR +[\fB\-ehMpV\fR] +[\fB\-b\fR\ \fIdn\fR] +[\fB\-c\fR\ \fIconf_file\fR] +[\fB\-d\fR\ \fIdeftypes\fR] +[\fB\-f\fR\ \fIoutput_format\fR] +[\fB\-i\fR\ \fIinput_format\fR] +[\fB\-I\fR\ \fIincrement\fR] +[\fB\-m\fR\ \fIfilter\fR] +[\fB\-o\fR\ \fIoutput_file\fR] +[\fB\-O\fR\ \fIstart_point\fR] +[\fB\-P\fR\ \fIpadding\fR] +[\fB\-s\fR\ \fIsections\fR] +[\fIinput_file\fR] +.SH "DESCRIPTION" +\fBcvtsudoers\fR +can be used to convert between +\fIsudoers\fR +security policy file formats. +The default input format is sudoers. +The default output format is LDIF. +It is only possible to convert a +\fIsudoers\fR +file that is syntactically correct. +.PP +If no +\fIinput_file\fR +is specified, or if it is +\(oq-\(cq, +the policy is read from the standard input. +By default, the result is written to the standard output. +.PP +The options are as follows: +.TP 12n +\fB\-b\fR \fIdn\fR, \fB\--base\fR=\fIdn\fR +The base DN (distinguished name) that will be used when performing +LDAP queries. +Typically this is of the form +\fRou=SUDOers,dc=my-domain,dc=com\fR +for the domain +\fRmy-domain.com\fR. +If this option is not specified, the value of the +\fRSUDOERS_BASE\fR +environment variable will be used instead. +Only necessary when converting to LDIF format. +.TP 12n +\fB\-c\fR \fIconf_file\fR, \fB\--config\fR=\fIconf_file\fR +Specify the path to the configuration file. +Defaults to +\fI@sysconfdir@/cvtsudoers.conf\fR. +.TP 12n +\fB\-d\fR \fIdeftypes\fR, \fB\--defaults\fR=\fIdeftypes\fR +Only convert +\fRDefaults\fR +entries of the specified types. +One or more +\fRDefaults\fR +types may be specified, separated by a comma +(\(oq\&,\(cq). +The supported types are: +.PP +.RS 12n +.PD 0 +.TP 10n +all +All Defaults entries. +.PD +.TP 10n +global +Global Defaults entries that are applied regardless of +user, runas, host or command. +.TP 10n +user +Per-user Defaults entries. +.TP 10n +runas +Per-runas user Defaults entries. +.TP 10n +host +Per-host Defaults entries. +.TP 10n +command +Per-command Defaults entries. +.PP +See the +\fBDefaults\fR +section in +sudoers(@mansectform@) +for more information. +.sp +If the +\fB\-d\fR +option is not specified, all +\fRDefaults\fR +entries will be converted. +.RE +.TP 12n +\fB\-e\fR, \fB\--expand-aliases\fR +Expand aliases in +\fIinput_file\fR. +Aliases are preserved by default when the output +\fIformat\fR +is JSON or sudoers. +.TP 12n +\fB\-f\fR \fIoutput_format\fR, \fB\--output-format\fR=\fIoutput_format\fR +Specify the output format (case-insensitive). +The following formats are supported: +.PP +.RS 12n +.PD 0 +.TP 10n +JSON +JSON (JavaScript Object Notation) files are usually easier for +third-party applications to consume than the traditional +\fIsudoers\fR +format. +The various values have explicit types which removes much of the +ambiguity of the +\fIsudoers\fR +format. +.PD +.TP 10n +LDIF +LDIF (LDAP Data Interchange Format) files can be imported into an LDAP +server for use with +sudoers.ldap(@mansectform@). +.sp +Conversion to LDIF has the following limitations: +.PP +.RS 10n +.PD 0 +.TP 3n +\fB\(bu\fR +Command, host, runas and user-specific Defaults lines cannot be +translated as they don't have an equivalent in the sudoers LDAP schema. +.PD +.TP 3n +\fB\(bu\fR +Command, host, runas and user aliases are not supported by the +sudoers LDAP schema so they are expanded during the conversion. +.PD 0 +.PP +.RE +.PD +.TP 10n +sudoers +Traditional sudoers format. +A new sudoers file will be reconstructed from the parsed input file. +Comments are not preserved and data from any include files will be +output inline. +.PD 0 +.PP +.RE +.PD +.TP 12n +\fB\-h\fR, \fB\--help\fR +Display a short help message to the standard output and exit. +.TP 12n +\fB\-i\fR \fIinput_format\fR, \fB\--input-format\fR=\fIinput_format\fR +Specify the input format. +The following formats are supported: +.PP +.RS 12n +.PD 0 +.TP 10n +LDIF +LDIF (LDAP Data Interchange Format) files can be exported from an LDAP +server to convert security policies used by +sudoers.ldap(@mansectform@). +If a base DN (distinguished name) is specified, only sudoRole objects +that match the base DN will be processed. +Not all sudoOptions specified in a sudoRole can be translated from +LDIF to sudoers format. +.PD +.TP 10n +sudoers +Traditional sudoers format. +This is the default input format. +.PD 0 +.PP +.RE +.PD +.TP 12n +\fB\-I\fR \fIincrement\fR, \fB\--increment\fR=\fIincrement\fR +When generating LDIF output, increment each sudoOrder attribute by +the specified number. +Defaults to an increment of 1. +.TP 12n +\fB\-m\fR \fIfilter\fR, \fB\--match\fR=\fIfilter\fR +Only output rules that match the specified +\fIfilter\fR. +A +\fIfilter\fR +expression is made up of one or more +\fBkey =\fR \fIvalue\fR +pairs, separated by a comma +(\(oq\&,\(cq). +The +\fBkey\fR +may be +\(lquser\(rq, +\(lqgroup\(rq +or +\(lqhost\(rq. +For example, +\fBuser\fR = \fIoperator\fR +or +\fBhost\fR = \fIwww\fR. +An upper-case User_Alias or Host_Alias may be specified as the +\(lquser\(rq +or +\(lqhost\(rq. +.sp +A matching +\fIsudoers\fR +rule may also include users, groups and hosts that are not part of the +\fIfilter\fR. +This can happen when a rule includes multiple users, groups or hosts. +To prune out any non-matching user, group or host from the rules, the +\fB\-p\fR +option may be used. +.sp +By default, the password and group databases are not consulted when matching +against the filter so the users and groups do not need to be present +on the local system (see the +\fB\-M\fR +option). +Only aliases that are referenced by the filtered policy rules will +be displayed. +.TP 12n +\fB\-M\fR, \fB\--match-local\fR +When the +\fB\-m\fR +option is also specified, use password and group database information +when matching users and groups in the filter. +Only users and groups in the filter that exist on the local system will match, +and a user's groups will automatically be added to the filter. +If the +\fB\-M\fR +is +\fInot\fR +specified, users and groups in the filter do not need to exist on the +local system, but all groups used for matching must be explicitly listed +in the filter. +.TP 12n +\fB\-o\fR \fIoutput_file\fR, \fB\--output\fR=\fIoutput_file\fR +Write the converted output to +\fIoutput_file\fR. +If no +\fIoutput_file\fR +is specified, or if it is +\(oq-\(cq, +the converted +\fIsudoers\fR +policy will be written to the standard output. +.TP 12n +\fB\-O\fR \fIstart_point\fR, \fB\--order-start\fR=\fIstart_point\fR +When generating LDIF output, use the number specified by +\fIstart_point\fR +in the sudoOrder attribute of the first sudoRole object. +Subsequent sudoRole object use a sudoOrder value generated by adding an +\fIincrement\fR, +see the +\fB\-I\fR +option for details. +Defaults to a starting point of 1. +A starting point of 0 will disable the generation of sudoOrder +attributes in the resulting LDIF file. +.TP 12n +\fB\-p\fR, \fB\--prune-matches\fR +When the +\fB\-m\fR +option is also specified, +\fBcvtsudoers\fR +will prune out non-matching users, groups and hosts from +matching entries. +.TP 12n +\fB\-P\fR \fIpadding\fR, \fB\--padding\fR=\fIpadding\fR +When generating LDIF output, construct the initial sudoOrder value by +concatenating +\fIorder_start\fR +and +\fIincrement\fR, +padding the +\fIincrement\fR +with zeros until it consists of +\fIpadding\fR +digits. +For example, if +\fIorder_start\fR +is 1027, +\fIpadding\fR +is 3, and +\fIincrement\fR +is 1, the value of sudoOrder for the first entry will be 1027000, +followed by 1027001, 1027002, etc. +If the number of sudoRole entries is larger than the padding would allow, +\fBcvtsudoers\fR +will exit with an error. +By default, no padding is performed. +.TP 12n +\fB\-s\fR \fIsections\fR, \fB\--suppress\fR=\fIsections\fR +Suppress the output of specific +\fIsections\fR +of the security policy. +One or more section names may be specified, separated by a comma +(\(oq\&,\(cq). +The supported section name are: +\fBdefaults\fR, +\fBaliases\fR +and +\fBprivileges\fR +(which may be shortened to +\fBprivs\fR). +.TP 12n +\fB\-V\fR, \fB\--version\fR +Print the +\fBcvtsudoers\fR +and +\fIsudoers\fR +grammar versions and exit. +.PP +Options in the form +\(lqkeyword = value\(rq +may also be specified in a configuration file, +\fI@sysconfdir@/cvtsudoers.conf\fR +by default. +The following keywords are recognized: +.TP 6n +\fBdefaults =\fR \fIdeftypes\fR +See the description of the +\fB\-d\fR +command line option. +.TP 6n +\fBexpand_aliases =\fR \fIyes\fR | \fIno\fR +See the description of the +\fB\-e\fR +command line option. +.TP 6n +\fBinput_format =\fR \fIldif\fR | \fIsudoers\fR +See the description of the +\fB\-i\fR +command line option. +.TP 6n +\fBmatch =\fR \fIfilter\fR +See the description of the +\fB\-m\fR +command line option. +.TP 6n +\fBorder_increment =\fR \fIincrement\fR +See the description of the +\fB\-I\fR +command line option. +.TP 6n +\fBorder_start =\fR \fIstart_point\fR +See the description of the +\fB\-O\fR +command line option. +.TP 6n +\fBoutput_format =\fR \fIjson\fR | \fIldif\fR | \fIsudoers\fR +See the description of the +\fB\-f\fR +command line option. +.TP 6n +\fBpadding =\fR \fIpadding\fR +See the description of the +\fB\-P\fR +command line option. +.TP 6n +\fBprune_matches =\fR \fIyes\fR | \fIno\fR +See the description of the +\fB\-p\fR +command line option. +.TP 6n +\fBsudoers_base =\fR \fIdn\fR +See the description of the +\fB\-b\fR +command line option. +.TP 6n +\fBsuppress =\fR \fIsections\fR +See the description of the +\fB\-s\fR +command line option. +.PP +Options on the command line will override values from the +configuration file. +.SH "FILES" +.TP 26n +\fI@sysconfdir@/cvtsudoers.conf\fR +default configuration for cvtsudoers +.SH "EXAMPLES" +Convert +\fI/etc/sudoers\fR +to LDIF (LDAP Data Interchange Format) where the +\fIldap.conf\fR +file uses a +\fIsudoers_base\fR +of my-domain,dc=com, storing the result in +\fIsudoers.ldif\fR: +.nf +.sp +.RS 6n +$ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \e + /etc/sudoers +.RE +.fi +.PP +Convert +\fI/etc/sudoers\fR +to JSON format, storing the result in +\fIsudoers.json\fR: +.nf +.sp +.RS 6n +$ cvtsudoers -f json -o sudoers.json /etc/sudoers +.RE +.fi +.PP +Parse +\fI/etc/sudoers\fR +and display only rules that match user +\fIambrose\fR +on host +\fIhastur\fR: +.nf +.sp +.RS 6n +$ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers +.RE +.fi +.PP +Same as above, but expand aliases and prune out any non-matching +users and hosts from the expanded entries. +.nf +.sp +.RS 6n +$ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers +.RE +.fi +.PP +Convert +\fIsudoers.ldif\fR +from LDIF to traditional +\fIsudoers\fR +format: +.nf +.sp +.RS 6n +$ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif +.RE +.fi +.SH "SEE ALSO" +sudoers(@mansectform@), +sudoers.ldap(@mansectform@), +sudo(@mansectsu@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBcvtsudoers\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBcvtsudoers\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/cvtsudoers.mdoc.in b/doc/cvtsudoers.mdoc.in new file mode 100644 index 0000000..ce5d4c3 --- /dev/null +++ b/doc/cvtsudoers.mdoc.in @@ -0,0 +1,437 @@ +.\" +.\" Copyright (c) 2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 11, 2018 +.Dt CVTSUDOERS 1 +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm cvtsudoers +.Nd convert between sudoers file formats +.Sh SYNOPSIS +.Nm cvtsudoers +.Op Fl ehMpV +.Op Fl b Ar dn +.Op Fl c Ar conf_file +.Op Fl d Ar deftypes +.Op Fl f Ar output_format +.Op Fl i Ar input_format +.Op Fl I Ar increment +.Op Fl m Ar filter +.Op Fl o Ar output_file +.Op Fl O Ar start_point +.Op Fl P Ar padding +.Op Fl s Ar sections +.Op Ar input_file +.Sh DESCRIPTION +.Nm +can be used to convert between +.Em sudoers +security policy file formats. +The default input format is sudoers. +The default output format is LDIF. +It is only possible to convert a +.Em sudoers +file that is syntactically correct. +.Pp +If no +.Ar input_file +is specified, or if it is +.Ql - , +the policy is read from the standard input. +By default, the result is written to the standard output. +.Pp +The options are as follows: +.Bl -tag -width Fl +.It Fl b Ar dn , Fl -base Ns = Ns Ar dn +The base DN (distinguished name) that will be used when performing +LDAP queries. +Typically this is of the form +.Li ou=SUDOers,dc=my-domain,dc=com +for the domain +.Li my-domain.com . +If this option is not specified, the value of the +.Ev SUDOERS_BASE +environment variable will be used instead. +Only necessary when converting to LDIF format. +.It Fl c Ar conf_file , Fl -config Ns = Ns Ar conf_file +Specify the path to the configuration file. +Defaults to +.Pa @sysconfdir@/cvtsudoers.conf . +.It Fl d Ar deftypes , Fl -defaults Ns = Ns Ar deftypes +Only convert +.Li Defaults +entries of the specified types. +One or more +.Li Defaults +types may be specified, separated by a comma +.Pq Ql \&, . +The supported types are: +.Bl -tag -width 8n +.It all +All Defaults entries. +.It global +Global Defaults entries that are applied regardless of +user, runas, host or command. +.It user +Per-user Defaults entries. +.It runas +Per-runas user Defaults entries. +.It host +Per-host Defaults entries. +.It command +Per-command Defaults entries. +.El +.Pp +See the +.Sy Defaults +section in +.Xr sudoers @mansectform@ +for more information. +.Pp +If the +.Fl d +option is not specified, all +.Li Defaults +entries will be converted. +.It Fl e , Fl -expand-aliases +Expand aliases in +.Ar input_file . +Aliases are preserved by default when the output +.Ar format +is JSON or sudoers. +.It Fl f Ar output_format , Fl -output-format Ns = Ns Ar output_format +Specify the output format (case-insensitive). +The following formats are supported: +.Bl -tag -width 8n +.It JSON +JSON (JavaScript Object Notation) files are usually easier for +third-party applications to consume than the traditional +.Em sudoers +format. +The various values have explicit types which removes much of the +ambiguity of the +.Em sudoers +format. +.It LDIF +LDIF (LDAP Data Interchange Format) files can be imported into an LDAP +server for use with +.Xr sudoers.ldap @mansectform@ . +.Pp +Conversion to LDIF has the following limitations: +.Bl -bullet -width 1n +.It +Command, host, runas and user-specific Defaults lines cannot be +translated as they don't have an equivalent in the sudoers LDAP schema. +.It +Command, host, runas and user aliases are not supported by the +sudoers LDAP schema so they are expanded during the conversion. +.El +.It sudoers +Traditional sudoers format. +A new sudoers file will be reconstructed from the parsed input file. +Comments are not preserved and data from any include files will be +output inline. +.El +.It Fl h , Fl -help +Display a short help message to the standard output and exit. +.It Fl i Ar input_format , Fl -input-format Ns = Ns Ar input_format +Specify the input format. +The following formats are supported: +.Bl -tag -width 8n +.It LDIF +LDIF (LDAP Data Interchange Format) files can be exported from an LDAP +server to convert security policies used by +.Xr sudoers.ldap @mansectform@ . +If a base DN (distinguished name) is specified, only sudoRole objects +that match the base DN will be processed. +Not all sudoOptions specified in a sudoRole can be translated from +LDIF to sudoers format. +.It sudoers +Traditional sudoers format. +This is the default input format. +.El +.It Fl I Ar increment , Fl -increment Ns = Ns Ar increment +When generating LDIF output, increment each sudoOrder attribute by +the specified number. +Defaults to an increment of 1. +.It Fl m Ar filter , Fl -match Ns = Ns Ar filter +Only output rules that match the specified +.Ar filter . +A +.Ar filter +expression is made up of one or more +.Sy key = Ar value +pairs, separated by a comma +.Pq Ql \&, . +The +.Sy key +may be +.Dq user , +.Dq group +or +.Dq host . +For example, +.Sy user No = Ar operator +or +.Sy host No = Ar www . +An upper-case User_Alias or Host_Alias may be specified as the +.Dq user +or +.Dq host . +.Pp +A matching +.Em sudoers +rule may also include users, groups and hosts that are not part of the +.Ar filter . +This can happen when a rule includes multiple users, groups or hosts. +To prune out any non-matching user, group or host from the rules, the +.Fl p +option may be used. +.Pp +By default, the password and group databases are not consulted when matching +against the filter so the users and groups do not need to be present +on the local system (see the +.Fl M +option). +Only aliases that are referenced by the filtered policy rules will +be displayed. +.It Fl M , Fl -match-local +When the +.Fl m +option is also specified, use password and group database information +when matching users and groups in the filter. +Only users and groups in the filter that exist on the local system will match, +and a user's groups will automatically be added to the filter. +If the +.Fl M +is +.Em not +specified, users and groups in the filter do not need to exist on the +local system, but all groups used for matching must be explicitly listed +in the filter. +.It Fl o Ar output_file , Fl -output Ns = Ns Ar output_file +Write the converted output to +.Ar output_file . +If no +.Ar output_file +is specified, or if it is +.Ql - , +the converted +.Em sudoers +policy will be written to the standard output. +.It Fl O Ar start_point , Fl -order-start Ns = Ns Ar start_point +When generating LDIF output, use the number specified by +.Ar start_point +in the sudoOrder attribute of the first sudoRole object. +Subsequent sudoRole object use a sudoOrder value generated by adding an +.Ar increment , +see the +.Fl I +option for details. +Defaults to a starting point of 1. +A starting point of 0 will disable the generation of sudoOrder +attributes in the resulting LDIF file. +.It Fl p , Fl -prune-matches +When the +.Fl m +option is also specified, +.Nm +will prune out non-matching users, groups and hosts from +matching entries. +.It Fl P Ar padding , Fl -padding Ns = Ns Ar padding +When generating LDIF output, construct the initial sudoOrder value by +concatenating +.Ar order_start +and +.Ar increment , +padding the +.Ar increment +with zeros until it consists of +.Ar padding +digits. +For example, if +.Ar order_start +is 1027, +.Ar padding +is 3, and +.Ar increment +is 1, the value of sudoOrder for the first entry will be 1027000, +followed by 1027001, 1027002, etc. +If the number of sudoRole entries is larger than the padding would allow, +.Nm +will exit with an error. +By default, no padding is performed. +.It Fl s Ar sections , Fl -suppress Ns = Ns Ar sections +Suppress the output of specific +.Ar sections +of the security policy. +One or more section names may be specified, separated by a comma +.Pq Ql \&, . +The supported section name are: +.Sy defaults , +.Sy aliases +and +.Sy privileges +(which may be shortened to +.Sy privs ) . +.It Fl V , -version +Print the +.Nm +and +.Em sudoers +grammar versions and exit. +.El +.Pp +Options in the form +.Dq keyword = value +may also be specified in a configuration file, +.Pa @sysconfdir@/cvtsudoers.conf +by default. +The following keywords are recognized: +.Bl -tag -width 4n +.It Sy defaults = Ar deftypes +See the description of the +.Fl d +command line option. +.It Sy expand_aliases = Ar yes | no +See the description of the +.Fl e +command line option. +.It Sy input_format = Ar ldif | sudoers +See the description of the +.Fl i +command line option. +.It Sy match = Ar filter +See the description of the +.Fl m +command line option. +.It Sy order_increment = Ar increment +See the description of the +.Fl I +command line option. +.It Sy order_start = Ar start_point +See the description of the +.Fl O +command line option. +.It Sy output_format = Ar json | ldif | sudoers +See the description of the +.Fl f +command line option. +.It Sy padding = Ar padding +See the description of the +.Fl P +command line option. +.It Sy prune_matches = Ar yes | no +See the description of the +.Fl p +command line option. +.It Sy sudoers_base = Ar dn +See the description of the +.Fl b +command line option. +.It Sy suppress = Ar sections +See the description of the +.Fl s +command line option. +.El +.Pp +Options on the command line will override values from the +configuration file. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/cvtsudoers.conf +default configuration for cvtsudoers +.El +.Sh EXAMPLES +Convert +.Pa /etc/sudoers +to LDIF (LDAP Data Interchange Format) where the +.Pa ldap.conf +file uses a +.Em sudoers_base +of my-domain,dc=com, storing the result in +.Pa sudoers.ldif : +.Bd -literal -offset indent +$ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \e + /etc/sudoers +.Ed +.Pp +Convert +.Pa /etc/sudoers +to JSON format, storing the result in +.Pa sudoers.json : +.Bd -literal -offset indent +$ cvtsudoers -f json -o sudoers.json /etc/sudoers +.Ed +.Pp +Parse +.Pa /etc/sudoers +and display only rules that match user +.Em ambrose +on host +.Em hastur : +.Bd -literal -offset indent +$ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers +.Ed +.Pp +Same as above, but expand aliases and prune out any non-matching +users and hosts from the expanded entries. +.Bd -literal -offset indent +$ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers +.Ed +.Pp +Convert +.Pa sudoers.ldif +from LDIF to traditional +.Em sudoers +format: +.Bd -literal -offset indent +$ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif +.Ed +.Sh SEE ALSO +.Xr sudoers @mansectform@ , +.Xr sudoers.ldap @mansectform@ , +.Xr sudo @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/fixman.sh b/doc/fixman.sh new file mode 100755 index 0000000..f7ed1a8 --- /dev/null +++ b/doc/fixman.sh @@ -0,0 +1,37 @@ +#!/bin/sh +# +# Copyright (c) 2012-2014, 2017 Todd C. Miller <Todd.Miller@sudo.ws> +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# + +OUTFILE="$1" +rm -f "$OUTFILE" +> "$OUTFILE" + +# HP-UX friendly header/footer for all man pages +if [ X"`uname 2>&1`" = X"HP-UX" ]; then + cat >>"$OUTFILE" <<-'EOF' + s/^\.TH \("[^"]*"\) \("[^"]*"\) "\([^"]*\)" "\([^"]*\)" \("[^"]*"\)/.TH \1 \2\ + .ds )H \4\ + .ds ]W \3/ +EOF +fi + +# Replace "0 minutes" with "unlimited" +cat >>"$OUTFILE" <<-'EOF' + /^\\fR0\\fR$/ { + N + s/^\\fR0\\fR\nminutes\.$/unlimited./ + } +EOF diff --git a/doc/fixmdoc.sed b/doc/fixmdoc.sed new file mode 100644 index 0000000..3d57216 --- /dev/null +++ b/doc/fixmdoc.sed @@ -0,0 +1,5 @@ +# Replace "0 minutes" with "unlimited" +/^\.Li 0$/ { + N + s/^\.Li 0\nminutes\.$/unlimited./ +} diff --git a/doc/schema.ActiveDirectory b/doc/schema.ActiveDirectory new file mode 100644 index 0000000..f488eef --- /dev/null +++ b/doc/schema.ActiveDirectory @@ -0,0 +1,255 @@ +#
+# Active Directory Schema for sudo configuration (sudoers)
+#
+# To extend your Active Directory schema, run one of the following command
+# on your Windows DC (default port - Active Directory):
+#
+# ldifde -i -f schema.ActiveDirectory -c "CN=Schema,CN=Configuration,DC=X" #schemaNamingContext
+#
+# or on your Windows DC if using another port (with Active Directory LightWeight Directory Services / ADAM-Active Directory Application Mode)
+# Port 50000 by example (or any other port specified when defining the ADLDS/ADAM instance
+#
+# ldifde -i -f schema.ActiveDirectory -t 50000 -c "CN=Schema,CN=Configuration,DC=X" #schemaNamingContext
+#
+# or
+#
+# ldifde -i -f schema.ActiveDirectory -s server:port -c "CN=Schema,CN=Configuration,DC=X" #schemaNamingContext
+#
+# Can add username domain and password
+#
+# -b username domain password
+#
+# Can create Log file in current or any directory
+#
+# -j .
+#
+
+dn: CN=sudoUser,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoUser
+distinguishedName: CN=sudoUser,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.1
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoUser
+adminDescription: User(s) who may run sudo
+oMSyntax: 22
+searchFlags: 1
+lDAPDisplayName: sudoUser
+name: sudoUser
+schemaIDGUID:: JrGcaKpnoU+0s+HgeFjAbg==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoHost,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoHost
+distinguishedName: CN=sudoHost,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.2
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoHost
+adminDescription: Host(s) who may run sudo
+oMSyntax: 22
+lDAPDisplayName: sudoHost
+name: sudoHost
+schemaIDGUID:: d0TTjg+Y6U28g/Y+ns2k4w==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoCommand,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoCommand
+distinguishedName: CN=sudoCommand,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.3
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoCommand
+adminDescription: Command(s) to be executed by sudo
+oMSyntax: 22
+lDAPDisplayName: sudoCommand
+name: sudoCommand
+schemaIDGUID:: D6QR4P5UyUen3RGYJCHCPg==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoRunAs,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoRunAs
+distinguishedName: CN=sudoRunAs,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.4
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoRunAs
+adminDescription: User(s) impersonated by sudo (deprecated)
+oMSyntax: 22
+lDAPDisplayName: sudoRunAs
+name: sudoRunAs
+schemaIDGUID:: CP98mCQTyUKKxGrQeM80hQ==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoOption,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoOption
+distinguishedName: CN=sudoOption,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.5
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoOption
+adminDescription: Option(s) followed by sudo
+oMSyntax: 22
+lDAPDisplayName: sudoOption
+name: sudoOption
+schemaIDGUID:: ojaPzBBlAEmsvrHxQctLnA==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoRunAsUser,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoRunAsUser
+distinguishedName: CN=sudoRunAsUser,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.6
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoRunAsUser
+adminDescription: User(s) impersonated by sudo
+oMSyntax: 22
+lDAPDisplayName: sudoRunAsUser
+name: sudoRunAsUser
+schemaIDGUID:: 9C52yPYd3RG3jMR2VtiVkw==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoRunAsGroup,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoRunAsGroup
+distinguishedName: CN=sudoRunAsGroup,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.7
+attributeSyntax: 2.5.5.5
+isSingleValued: FALSE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoRunAsGroup
+adminDescription: Groups(s) impersonated by sudo
+oMSyntax: 22
+lDAPDisplayName: sudoRunAsGroup
+name: sudoRunAsGroup
+schemaIDGUID:: xJhSt/Yd3RGJPTB1VtiVkw==
+objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+
+dn: CN=sudoNotBefore,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoNotBefore
+distinguishedName: CN=sudoNotBefore,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.8
+attributeSyntax: 2.5.5.11
+isSingleValued: TRUE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoNotBefore
+adminDescription: Start of time interval for which the entry is valid
+oMSyntax: 24
+lDAPDisplayName: sudoNotBefore
+name: sudoNotBefore
+schemaIDGUID:: dm1HnRfY4RGf4gopYYhwmw== +objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+ +dn: CN=sudoNotAfter,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoNotAfter
+distinguishedName: CN=sudoNotAfter,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.9
+attributeSyntax: 2.5.5.11
+isSingleValued: TRUE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoNotAfter
+adminDescription: End of time interval for which the entry is valid
+oMSyntax: 24
+lDAPDisplayName: sudoNotAfter
+name: sudoNotAfter
+schemaIDGUID:: OAr/pBfY4RG9dBIpYYhwmw== +objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+ +dn: CN=sudoOrder,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: attributeSchema
+cn: sudoOrder
+distinguishedName: CN=sudoOrder,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+attributeID: 1.3.6.1.4.1.15953.9.1.10
+attributeSyntax: 2.5.5.9
+isSingleValued: TRUE
+showInAdvancedViewOnly: TRUE
+adminDisplayName: sudoOrder
+adminDescription: an integer to order the sudoRole entries
+oMSyntax: 2
+lDAPDisplayName: sudoOrder
+name: sudoOrder
+schemaIDGUID:: 0J8yrRfY4RGIYBUpYYhwmw== +objectCategory: CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=X
+ +dn:
+changetype: modify
+add: schemaUpdateNow
+schemaUpdateNow: 1
+-
+
+dn: CN=sudoRole,CN=Schema,CN=Configuration,DC=X
+changetype: add
+objectClass: top
+objectClass: classSchema
+cn: sudoRole
+distinguishedName: CN=sudoRole,CN=Schema,CN=Configuration,DC=X
+instanceType: 4
+possSuperiors: container
+possSuperiors: top
+subClassOf: top
+governsID: 1.3.6.1.4.1.15953.9.2.1
+mayContain: sudoCommand
+mayContain: sudoHost
+mayContain: sudoOption
+mayContain: sudoRunAs
+mayContain: sudoRunAsUser
+mayContain: sudoRunAsGroup
+mayContain: sudoUser
+mayContain: sudoNotBefore
+mayContain: sudoNotAfter
+mayContain: sudoOrder
+rDNAttID: cn
+showInAdvancedViewOnly: FALSE
+adminDisplayName: sudoRole
+adminDescription: Sudoer Entries
+objectClassCategory: 1
+lDAPDisplayName: sudoRole
+name: sudoRole
+schemaIDGUID:: SQn432lnZ0+ukbdh3+gN3w==
+systemOnly: FALSE
+objectCategory: CN=Class-Schema,CN=Schema,CN=Configuration,DC=X
+defaultObjectCategory: CN=sudoRole,CN=Schema,CN=Configuration,DC=X
diff --git a/doc/schema.OpenLDAP b/doc/schema.OpenLDAP new file mode 100644 index 0000000..e1d525f --- /dev/null +++ b/doc/schema.OpenLDAP @@ -0,0 +1,78 @@ +# +# OpenLDAP schema file for Sudo +# Save as /etc/openldap/schema/sudo.schema and restart slapd. +# For a version that uses online configuration, see schema.olcSudo. +# + +attributetype ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo (deprecated)' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + +objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ + sudoRunAsGroup $ sudoOption $ sudoOrder $ sudoNotBefore $ + sudoNotAfter $ description ) + ) diff --git a/doc/schema.iPlanet b/doc/schema.iPlanet new file mode 100644 index 0000000..e512864 --- /dev/null +++ b/doc/schema.iPlanet @@ -0,0 +1,12 @@ +dn: cn=schema +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.1 NAME 'sudoUser' DESC 'User(s) who may run sudo' EQUALITY caseExactIA5Match SUBSTR caseExactIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.2 NAME 'sudoHost' DESC 'Host(s) who may run sudo' EQUALITY caseExactIA5Match SUBSTR caseExactIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.3 NAME 'sudoCommand' DESC 'Command(s) to be executed by sudo' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.4 NAME 'sudoRunAs' DESC 'User(s) impersonated by sudo (deprecated)' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.5 NAME 'sudoOption' DESC 'Options(s) followed by sudo' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.6 NAME 'sudoRunAsUser' DESC 'User(s) impersonated by sudo' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.7 NAME 'sudoRunAsGroup' DESC 'Group(s) impersonated by sudo' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'SUDO' ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.8 NAME 'sudoNotBefore' DESC 'Start of time interval for which the entry is valid' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.9 NAME 'sudoNotAfter' DESC 'End of time interval for which the entry is valid' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) +attributeTypes: ( 1.3.6.1.4.1.15953.9.1.10 NAME 'sudoOrder' DESC 'an integer to order the sudoRole entries' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) +objectClasses: ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL DESC 'Sudoer Entries' MUST ( cn ) MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ sudoRunAsGroup $ sudoOption $ sudoOrder $ sudoNotBefore $ sudoNotAfter $ description ) X-ORIGIN 'SUDO' ) diff --git a/doc/schema.olcSudo b/doc/schema.olcSudo new file mode 100644 index 0000000..8748dfc --- /dev/null +++ b/doc/schema.olcSudo @@ -0,0 +1,79 @@ +dn: cn=sudoschema,cn=schema,cn=config +objectClass: olcSchemaConfig +cn: sudoschema +# +# OpenLDAP schema file for Sudo in on-line configuration (OLC) format. +# Import using ldapadd or another suitable LDAP browser. +# Converted to OLC format by Frederic Pasteleurs <frederic@askarel.be> +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo (deprecated)' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) +# +olcattributetypes: ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) +# +olcattributeTypes: ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) +# +olcobjectclasses: ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ sudoRunAsGroup $ sudoOption $ sudoOrder $ sudoNotBefore $ sudoNotAfter $ + description ) + ) diff --git a/doc/sudo.cat b/doc/sudo.cat new file mode 100644 index 0000000..6d7671b --- /dev/null +++ b/doc/sudo.cat @@ -0,0 +1,741 @@ +SUDO(1m) System Manager's Manual SUDO(1m) + +NNAAMMEE + ssuuddoo, ssuuddooeeddiitt - execute a command as another user + +SSYYNNOOPPSSIISS + ssuuddoo --hh | --KK | --kk | --VV + ssuuddoo --vv [--AAkknnSS] [--aa _t_y_p_e] [--gg _g_r_o_u_p] [--hh _h_o_s_t] [--pp _p_r_o_m_p_t] [--uu _u_s_e_r] + ssuuddoo --ll [--AAkknnSS] [--aa _t_y_p_e] [--gg _g_r_o_u_p] [--hh _h_o_s_t] [--pp _p_r_o_m_p_t] [--UU _u_s_e_r] + [--uu _u_s_e_r] [_c_o_m_m_a_n_d] + ssuuddoo [--AAbbEEHHnnPPSS] [--aa _t_y_p_e] [--CC _n_u_m] [--cc _c_l_a_s_s] [--gg _g_r_o_u_p] [--hh _h_o_s_t] + [--pp _p_r_o_m_p_t] [--rr _r_o_l_e] [--tt _t_y_p_e] [--TT _t_i_m_e_o_u_t] [--uu _u_s_e_r] [_V_A_R=_v_a_l_u_e] + [--ii | --ss] [_c_o_m_m_a_n_d] + ssuuddooeeddiitt [--AAkknnSS] [--aa _t_y_p_e] [--CC _n_u_m] [--cc _c_l_a_s_s] [--gg _g_r_o_u_p] [--hh _h_o_s_t] + [--pp _p_r_o_m_p_t] [--TT _t_i_m_e_o_u_t] [--uu _u_s_e_r] _f_i_l_e _._._. + +DDEESSCCRRIIPPTTIIOONN + ssuuddoo allows a permitted user to execute a _c_o_m_m_a_n_d as the superuser or + another user, as specified by the security policy. The invoking user's + real (_n_o_t effective) user ID is used to determine the user name with + which to query the security policy. + + ssuuddoo supports a plugin architecture for security policies and + input/output logging. Third parties can develop and distribute their own + policy and I/O logging plugins to work seamlessly with the ssuuddoo front + end. The default security policy is _s_u_d_o_e_r_s, which is configured via the + file _/_e_t_c_/_s_u_d_o_e_r_s, or via LDAP. See the _P_l_u_g_i_n_s section for more + information. + + The security policy determines what privileges, if any, a user has to run + ssuuddoo. The policy may require that users authenticate themselves with a + password or another authentication mechanism. If authentication is + required, ssuuddoo will exit if the user's password is not entered within a + configurable time limit. This limit is policy-specific; the default + password prompt timeout for the _s_u_d_o_e_r_s security policy is 5 minutes. + + Security policies may support credential caching to allow the user to run + ssuuddoo again for a period of time without requiring authentication. The + _s_u_d_o_e_r_s policy caches credentials for 5 minutes, unless overridden in + sudoers(4). By running ssuuddoo with the --vv option, a user can update the + cached credentials without running a _c_o_m_m_a_n_d. + + When invoked as ssuuddooeeddiitt, the --ee option (described below), is implied. + + Security policies may log successful and failed attempts to use ssuuddoo. If + an I/O plugin is configured, the running command's input and output may + be logged as well. + + The options are as follows: + + --AA, ----aasskkppaassss + Normally, if ssuuddoo requires a password, it will read it from + the user's terminal. If the --AA (_a_s_k_p_a_s_s) option is + specified, a (possibly graphical) helper program is executed + to read the user's password and output the password to the + standard output. If the SUDO_ASKPASS environment variable is + set, it specifies the path to the helper program. Otherwise, + if sudo.conf(4) contains a line specifying the askpass + program, that value will be used. For example: + + # Path to askpass helper program + Path askpass /usr/X11R6/bin/ssh-askpass + + If no askpass program is available, ssuuddoo will exit with an + error. + + --aa _t_y_p_e, ----aauutthh--ttyyppee=_t_y_p_e + Use the specified BSD authentication _t_y_p_e when validating the + user, if allowed by _/_e_t_c_/_l_o_g_i_n_._c_o_n_f. The system + administrator may specify a list of sudo-specific + authentication methods by adding an "auth-sudo" entry in + _/_e_t_c_/_l_o_g_i_n_._c_o_n_f. This option is only available on systems + that support BSD authentication. + + --bb, ----bbaacckkggrroouunndd + Run the given command in the background. Note that it is not + possible to use shell job control to manipulate background + processes started by ssuuddoo. Most interactive commands will + fail to work properly in background mode. + + --CC _n_u_m, ----cclloossee--ffrroomm=_n_u_m + Close all file descriptors greater than or equal to _n_u_m + before executing a command. Values less than three are not + permitted. By default, ssuuddoo will close all open file + descriptors other than standard input, standard output and + standard error when executing a command. The security policy + may restrict the user's ability to use this option. The + _s_u_d_o_e_r_s policy only permits use of the --CC option when the + administrator has enabled the _c_l_o_s_e_f_r_o_m___o_v_e_r_r_i_d_e option. + + --cc _c_l_a_s_s, ----llooggiinn--ccllaassss=_c_l_a_s_s + Run the command with resource limits and scheduling priority + of the specified login _c_l_a_s_s. The _c_l_a_s_s argument can be + either a class name as defined in _/_e_t_c_/_l_o_g_i_n_._c_o_n_f, or a + single `-' character. If _c_l_a_s_s is --, the default login class + of the target user will be used. Otherwise, the command must + be run as the superuser (user ID 0), or ssuuddoo must be run from + a shell that is already running as the superuser. If the + command is being run as a login shell, additional + _/_e_t_c_/_l_o_g_i_n_._c_o_n_f settings, such as the umask and environment + variables, will be applied, if present. This option is only + available on systems with BSD login classes. + + --EE, ----pprreesseerrvvee--eennvv + Indicates to the security policy that the user wishes to + preserve their existing environment variables. The security + policy may return an error if the user does not have + permission to preserve the environment. + + ----pprreesseerrvvee--eennvv==lliisstt + Indicates to the security policy that the user wishes to add + the comma-separated list of environment variables to those + preserved from the user's environment. The security policy + may return an error if the user does not have permission to + preserve the environment. + + --ee, ----eeddiitt Edit one or more files instead of running a command. In lieu + of a path name, the string "sudoedit" is used when consulting + the security policy. If the user is authorized by the + policy, the following steps are taken: + + 1. Temporary copies are made of the files to be edited + with the owner set to the invoking user. + + 2. The editor specified by the policy is run to edit the + temporary files. The _s_u_d_o_e_r_s policy uses the + SUDO_EDITOR, VISUAL and EDITOR environment variables + (in that order). If none of SUDO_EDITOR, VISUAL or + EDITOR are set, the first program listed in the _e_d_i_t_o_r + sudoers(4) option is used. + + 3. If they have been modified, the temporary files are + copied back to their original location and the + temporary versions are removed. + + To help prevent the editing of unauthorized files, the + following restrictions are enforced unless explicitly allowed + by the security policy: + + ++oo Symbolic links may not be edited (version 1.8.15 and + higher). + + ++oo Symbolic links along the path to be edited are not + followed when the parent directory is writable by the + invoking user unless that user is root (version 1.8.16 + and higher). + + ++oo Files located in a directory that is writable by the + invoking user may not be edited unless that user is root + (version 1.8.16 and higher). + + Users are never allowed to edit device special files. + + If the specified file does not exist, it will be created. + Note that unlike most commands run by _s_u_d_o, the editor is run + with the invoking user's environment unmodified. If, for + some reason, ssuuddoo is unable to update a file with its edited + version, the user will receive a warning and the edited copy + will remain in a temporary file. + + --gg _g_r_o_u_p, ----ggrroouupp=_g_r_o_u_p + Run the command with the primary group set to _g_r_o_u_p instead + of the primary group specified by the target user's password + database entry. The _g_r_o_u_p may be either a group name or a + numeric group ID (GID) prefixed with the `#' character (e.g., + #0 for GID 0). When running a command as a GID, many shells + require that the `#' be escaped with a backslash (`\'). If + no --uu option is specified, the command will be run as the + invoking user. In either case, the primary group will be set + to _g_r_o_u_p. The _s_u_d_o_e_r_s policy permits any of the target + user's groups to be specified via the --gg option as long as + the --PP option is not in use. + + --HH, ----sseett--hhoommee + Request that the security policy set the HOME environment + variable to the home directory specified by the target user's + password database entry. Depending on the policy, this may + be the default behavior. + + --hh, ----hheellpp Display a short help message to the standard output and exit. + + --hh _h_o_s_t, ----hhoosstt=_h_o_s_t + Run the command on the specified _h_o_s_t if the security policy + plugin supports remote commands. Note that the _s_u_d_o_e_r_s + plugin does not currently support running remote commands. + This may also be used in conjunction with the --ll option to + list a user's privileges for the remote host. + + --ii, ----llooggiinn + Run the shell specified by the target user's password + database entry as a login shell. This means that login- + specific resource files such as _._p_r_o_f_i_l_e, _._b_a_s_h___p_r_o_f_i_l_e or + _._l_o_g_i_n will be read by the shell. If a command is specified, + it is passed to the shell for execution via the shell's --cc + option. If no command is specified, an interactive shell is + executed. ssuuddoo attempts to change to that user's home + directory before running the shell. The command is run with + an environment similar to the one a user would receive at log + in. Note that most shells behave differently when a command + is specified as compared to an interactive session; consult + the shell's manual for details. The _C_o_m_m_a_n_d _e_n_v_i_r_o_n_m_e_n_t + section in the sudoers(4) manual documents how the --ii option + affects the environment in which a command is run when the + _s_u_d_o_e_r_s policy is in use. + + --KK, ----rreemmoovvee--ttiimmeessttaammpp + Similar to the --kk option, except that it removes the user's + cached credentials entirely and may not be used in + conjunction with a command or other option. This option does + not require a password. Not all security policies support + credential caching. + + --kk, ----rreesseett--ttiimmeessttaammpp + When used without a command, invalidates the user's cached + credentials. In other words, the next time ssuuddoo is run a + password will be required. This option does not require a + password and was added to allow a user to revoke ssuuddoo + permissions from a _._l_o_g_o_u_t file. + + When used in conjunction with a command or an option that may + require a password, this option will cause ssuuddoo to ignore the + user's cached credentials. As a result, ssuuddoo will prompt for + a password (if one is required by the security policy) and + will not update the user's cached credentials. + + Not all security policies support credential caching. + + --ll, ----lliisstt If no _c_o_m_m_a_n_d is specified, list the allowed (and forbidden) + commands for the invoking user (or the user specified by the + --UU option) on the current host. A longer list format is used + if this option is specified multiple times and the security + policy supports a verbose output format. + + If a _c_o_m_m_a_n_d is specified and is permitted by the security + policy, the fully-qualified path to the command is displayed + along with any command line arguments. If a _c_o_m_m_a_n_d is + specified but not allowed by the policy, ssuuddoo will exit with + a status value of 1. + + --nn, ----nnoonn--iinntteerraaccttiivvee + Avoid prompting the user for input of any kind. If a + password is required for the command to run, ssuuddoo will + display an error message and exit. + + --PP, ----pprreesseerrvvee--ggrroouuppss + Preserve the invoking user's group vector unaltered. By + default, the _s_u_d_o_e_r_s policy will initialize the group vector + to the list of groups the target user is a member of. The + real and effective group IDs, however, are still set to match + the target user. + + --pp _p_r_o_m_p_t, ----pprroommpptt=_p_r_o_m_p_t + Use a custom password prompt with optional escape sequences. + The following percent (`%') escape sequences are supported by + the _s_u_d_o_e_r_s policy: + + %H expanded to the host name including the domain name (on + if the machine's host name is fully qualified or the _f_q_d_n + option is set in sudoers(4)) + + %h expanded to the local host name without the domain name + + %p expanded to the name of the user whose password is being + requested (respects the _r_o_o_t_p_w, _t_a_r_g_e_t_p_w, and _r_u_n_a_s_p_w + flags in sudoers(4)) + + %U expanded to the login name of the user the command will + be run as (defaults to root unless the --uu option is also + specified) + + %u expanded to the invoking user's login name + + %% two consecutive `%' characters are collapsed into a + single `%' character + + The custom prompt will override the default prompt specified + by either the security policy or the SUDO_PROMPT environment + variable. On systems that use PAM, the custom prompt will + also override the prompt specified by a PAM module unless the + _p_a_s_s_p_r_o_m_p_t___o_v_e_r_r_i_d_e flag is disabled in _s_u_d_o_e_r_s. + + --rr _r_o_l_e, ----rroollee=_r_o_l_e + Run the command with an SELinux security context that + includes the specified _r_o_l_e. + + --SS, ----ssttddiinn + Write the prompt to the standard error and read the password + from the standard input instead of using the terminal device. + + --ss, ----sshheellll + Run the shell specified by the SHELL environment variable if + it is set or the shell specified by the invoking user's + password database entry. If a command is specified, it is + passed to the shell for execution via the shell's --cc option. + If no command is specified, an interactive shell is executed. + Note that most shells behave differently when a command is + specified as compared to an interactive session; consult the + shell's manual for details. + + --tt _t_y_p_e, ----ttyyppee=_t_y_p_e + Run the command with an SELinux security context that + includes the specified _t_y_p_e. If no _t_y_p_e is specified, the + default type is derived from the role. + + --UU _u_s_e_r, ----ootthheerr--uusseerr=_u_s_e_r + Used in conjunction with the --ll option to list the privileges + for _u_s_e_r instead of for the invoking user. The security + policy may restrict listing other users' privileges. The + _s_u_d_o_e_r_s policy only allows root or a user with the ALL + privilege on the current host to use this option. + + --TT _t_i_m_e_o_u_t, ----ccoommmmaanndd--ttiimmeeoouutt=_t_i_m_e_o_u_t + Used to set a timeout for the command. If the timeout + expires before the command has exited, the command will be + terminated. The security policy may restrict the ability to + set command timeouts. The _s_u_d_o_e_r_s policy requires that user- + specified timeouts be explicitly enabled. + + --uu _u_s_e_r, ----uusseerr=_u_s_e_r + Run the command as a user other than the default target user + (usually _r_o_o_t). The _u_s_e_r may be either a user name or a + numeric user ID (UID) prefixed with the `#' character (e.g., + #0 for UID 0). When running commands as a UID, many shells + require that the `#' be escaped with a backslash (`\'). Some + security policies may restrict UIDs to those listed in the + password database. The _s_u_d_o_e_r_s policy allows UIDs that are + not in the password database as long as the _t_a_r_g_e_t_p_w option + is not set. Other security policies may not support this. + + --VV, ----vveerrssiioonn + Print the ssuuddoo version string as well as the version string + of the security policy plugin and any I/O plugins. If the + invoking user is already root the --VV option will display the + arguments passed to configure when ssuuddoo was built and plugins + may display more verbose information such as default options. + + --vv, ----vvaalliiddaattee + Update the user's cached credentials, authenticating the user + if necessary. For the _s_u_d_o_e_r_s plugin, this extends the ssuuddoo + timeout for another 5 minutes by default, but does not run a + command. Not all security policies support cached + credentials. + + ---- The ---- option indicates that ssuuddoo should stop processing + command line arguments. + + Environment variables to be set for the command may also be passed on the + command line in the form of _V_A_R=_v_a_l_u_e, e.g., + LD_LIBRARY_PATH=_/_u_s_r_/_l_o_c_a_l_/_p_k_g_/_l_i_b. Variables passed on the command line + are subject to restrictions imposed by the security policy plugin. The + _s_u_d_o_e_r_s policy subjects variables passed on the command line to the same + restrictions as normal environment variables with one important + exception. If the _s_e_t_e_n_v option is set in _s_u_d_o_e_r_s, the command to be run + has the SETENV tag set or the command matched is ALL, the user may set + variables that would otherwise be forbidden. See sudoers(4) for more + information. + +CCOOMMMMAANNDD EEXXEECCUUTTIIOONN + When ssuuddoo executes a command, the security policy specifies the execution + environment for the command. Typically, the real and effective user and + group and IDs are set to match those of the target user, as specified in + the password database, and the group vector is initialized based on the + group database (unless the --PP option was specified). + + The following parameters may be specified by security policy: + + ++oo real and effective user ID + + ++oo real and effective group ID + + ++oo supplementary group IDs + + ++oo the environment list + + ++oo current working directory + + ++oo file creation mode mask (umask) + + ++oo SELinux role and type + + ++oo Solaris project + + ++oo Solaris privileges + + ++oo BSD login class + + ++oo scheduling priority (aka nice value) + + PPrroocceessss mmooddeell + There are two distinct ways ssuuddoo can run a command. + + If an I/O logging plugin is configured or if the security policy + explicitly requests it, a new pseudo-terminal ("pty") is allocated and + fork(2) is used to create a second ssuuddoo process, referred to as the + _m_o_n_i_t_o_r. The _m_o_n_i_t_o_r creates a new terminal session with itself as the + leader and the pty as its controlling terminal, calls fork(2), sets up + the execution environment as described above, and then uses the execve(2) + system call to run the command in the child process. The _m_o_n_i_t_o_r exists + to relay job control signals between the user's existing terminal and the + pty the command is being run in. This makes it possible to suspend and + resume the command. Without the monitor, the command would be in what + POSIX terms an "orphaned process group" and it would not receive any job + control signals from the kernel. When the command exits or is terminated + by a signal, the _m_o_n_i_t_o_r passes the command's exit status to the main + ssuuddoo process and exits. After receiving the command's exit status, the + main ssuuddoo passes the command's exit status to the security policy's close + function and exits. + + If no pty is used, ssuuddoo calls fork(2), sets up the execution environment + as described above, and uses the execve(2) system call to run the command + in the child process. The main ssuuddoo process waits until the command has + completed, then passes the command's exit status to the security policy's + close function and exits. As a special case, if the policy plugin does + not define a close function, ssuuddoo will execute the command directly + instead of calling fork(2) first. The _s_u_d_o_e_r_s policy plugin will only + define a close function when I/O logging is enabled, a pty is required, + or the _p_a_m___s_e_s_s_i_o_n or _p_a_m___s_e_t_c_r_e_d options are enabled. Note that + _p_a_m___s_e_s_s_i_o_n and _p_a_m___s_e_t_c_r_e_d are enabled by default on systems using PAM. + + SSiiggnnaall hhaannddlliinngg + When the command is run as a child of the ssuuddoo process, ssuuddoo will relay + signals it receives to the command. The SIGINT and SIGQUIT signals are + only relayed when the command is being run in a new pty or when the + signal was sent by a user process, not the kernel. This prevents the + command from receiving SIGINT twice each time the user enters control-C. + Some signals, such as SIGSTOP and SIGKILL, cannot be caught and thus will + not be relayed to the command. As a general rule, SIGTSTP should be used + instead of SIGSTOP when you wish to suspend a command being run by ssuuddoo. + + As a special case, ssuuddoo will not relay signals that were sent by the + command it is running. This prevents the command from accidentally + killing itself. On some systems, the reboot(1m) command sends SIGTERM to + all non-system processes other than itself before rebooting the system. + This prevents ssuuddoo from relaying the SIGTERM signal it received back to + reboot(1m), which might then exit before the system was actually rebooted, + leaving it in a half-dead state similar to single user mode. Note, + however, that this check only applies to the command run by ssuuddoo and not + any other processes that the command may create. As a result, running a + script that calls reboot(1m) or shutdown(1m) via ssuuddoo may cause the system + to end up in this undefined state unless the reboot(1m) or shutdown(1m) are + run using the eexxeecc() family of functions instead of ssyysstteemm() (which + interposes a shell between the command and the calling process). + + If no I/O logging plugins are loaded and the policy plugin has not + defined a cclloossee() function, set a command timeout or required that the + command be run in a new pty, ssuuddoo may execute the command directly + instead of running it as a child process. + + PPlluuggiinnss + Plugins may be specified via Plugin directives in the sudo.conf(4) file. + They may be loaded as dynamic shared objects (on systems that support + them), or compiled directly into the ssuuddoo binary. If no sudo.conf(4) + file is present, or it contains no Plugin lines, ssuuddoo will use the + traditional _s_u_d_o_e_r_s security policy and I/O logging. See the + sudo.conf(4) manual for details of the _/_e_t_c_/_s_u_d_o_._c_o_n_f file and the + sudo_plugin(4) manual for more information about the ssuuddoo plugin + architecture. + +EEXXIITT VVAALLUUEE + Upon successful execution of a command, the exit status from ssuuddoo will be + the exit status of the program that was executed. If the command + terminated due to receipt of a signal, ssuuddoo will send itself the same + signal that terminated the command. + + If the --ll option was specified without a command, ssuuddoo will exit with a + value of 0 if the user is allowed to run ssuuddoo and they authenticated + successfully (as required by the security policy). If a command is + specified with the --ll option, the exit value will only be 0 if the + command is permitted by the security policy, otherwise it will be 1. + + If there is an authentication failure, a configuration/permission problem + or if the given command cannot be executed, ssuuddoo exits with a value of 1. + In the latter case, the error string is printed to the standard error. + If ssuuddoo cannot stat(2) one or more entries in the user's PATH, an error + is printed to the standard error. (If the directory does not exist or if + it is not really a directory, the entry is ignored and no error is + printed.) This should not happen under normal circumstances. The most + common reason for stat(2) to return "permission denied" is if you are + running an automounter and one of the directories in your PATH is on a + machine that is currently unreachable. + +SSEECCUURRIITTYY NNOOTTEESS + ssuuddoo tries to be safe when executing external commands. + + To prevent command spoofing, ssuuddoo checks "." and "" (both denoting + current directory) last when searching for a command in the user's PATH + (if one or both are in the PATH). Note, however, that the actual PATH + environment variable is _n_o_t modified and is passed unchanged to the + program that ssuuddoo executes. + + Users should _n_e_v_e_r be granted ssuuddoo privileges to execute files that are + writable by the user or that reside in a directory that is writable by + the user. If the user can modify or replace the command there is no way + to limit what additional commands they can run. + + Please note that ssuuddoo will normally only log the command it explicitly + runs. If a user runs a command such as sudo su or sudo sh, subsequent + commands run from that shell are not subject to ssuuddoo's security policy. + The same is true for commands that offer shell escapes (including most + editors). If I/O logging is enabled, subsequent commands will have their + input and/or output logged, but there will not be traditional logs for + those commands. Because of this, care must be taken when giving users + access to commands via ssuuddoo to verify that the command does not + inadvertently give the user an effective root shell. For more + information, please see the _P_r_e_v_e_n_t_i_n_g _s_h_e_l_l _e_s_c_a_p_e_s section in + sudoers(4). + + To prevent the disclosure of potentially sensitive information, ssuuddoo + disables core dumps by default while it is executing (they are re-enabled + for the command that is run). This historical practice dates from a time + when most operating systems allowed setuid processes to dump core by + default. To aid in debugging ssuuddoo crashes, you may wish to re-enable + core dumps by setting "disable_coredump" to false in the sudo.conf(4) + file as follows: + + Set disable_coredump false + + See the sudo.conf(4) manual for more information. + +EENNVVIIRROONNMMEENNTT + ssuuddoo utilizes the following environment variables. The security policy + has control over the actual content of the command's environment. + + EDITOR Default editor to use in --ee (sudoedit) mode if neither + SUDO_EDITOR nor VISUAL is set. + + MAIL Set to the mail spool of the target user when the --ii + option is specified or when _e_n_v___r_e_s_e_t is enabled in + _s_u_d_o_e_r_s (unless MAIL is present in the _e_n_v___k_e_e_p list). + + HOME Set to the home directory of the target user when the --ii + or --HH options are specified, when the --ss option is + specified and _s_e_t___h_o_m_e is set in _s_u_d_o_e_r_s, when + _a_l_w_a_y_s___s_e_t___h_o_m_e is enabled in _s_u_d_o_e_r_s, or when _e_n_v___r_e_s_e_t + is enabled in _s_u_d_o_e_r_s and _H_O_M_E is not present in the + _e_n_v___k_e_e_p list. + + LOGNAME Set to the login name of the target user when the --ii + option is specified, when the _s_e_t___l_o_g_n_a_m_e option is + enabled in _s_u_d_o_e_r_s or when the _e_n_v___r_e_s_e_t option is + enabled in _s_u_d_o_e_r_s (unless LOGNAME is present in the + _e_n_v___k_e_e_p list). + + PATH May be overridden by the security policy. + + SHELL Used to determine shell to run with --ss option. + + SUDO_ASKPASS Specifies the path to a helper program used to read the + password if no terminal is available or if the --AA option + is specified. + + SUDO_COMMAND Set to the command run by sudo. + + SUDO_EDITOR Default editor to use in --ee (sudoedit) mode. + + SUDO_GID Set to the group ID of the user who invoked sudo. + + SUDO_PROMPT Used as the default password prompt unless the --pp option + was specified. + + SUDO_PS1 If set, PS1 will be set to its value for the program + being run. + + SUDO_UID Set to the user ID of the user who invoked sudo. + + SUDO_USER Set to the login name of the user who invoked sudo. + + USER Set to the same value as LOGNAME, described above. + + VISUAL Default editor to use in --ee (sudoedit) mode if + SUDO_EDITOR is not set. + +FFIILLEESS + _/_e_t_c_/_s_u_d_o_._c_o_n_f ssuuddoo front end configuration + +EEXXAAMMPPLLEESS + Note: the following examples assume a properly configured security + policy. + + To get a file listing of an unreadable directory: + + $ sudo ls /usr/local/protected + + To list the home directory of user yaz on a machine where the file system + holding ~yaz is not exported as root: + + $ sudo -u yaz ls ~yaz + + To edit the _i_n_d_e_x_._h_t_m_l file as user www: + + $ sudoedit -u www ~www/htdocs/index.html + + To view system logs only accessible to root and users in the adm group: + + $ sudo -g adm more /var/log/syslog + + To run an editor as jim with a different primary group: + + $ sudoedit -u jim -g audio ~jim/sound.txt + + To shut down a machine: + + $ sudo shutdown -r +15 "quick reboot" + + To make a usage listing of the directories in the /home partition. Note + that this runs the commands in a sub-shell to make the cd and file + redirection work. + + $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE" + +DDIIAAGGNNOOSSTTIICCSS + Error messages produced by ssuuddoo include: + + editing files in a writable directory is not permitted + By default, ssuuddooeeddiitt does not permit editing a file when any of the + parent directories are writable by the invoking user. This avoids + a race condition that could allow the user to overwrite an + arbitrary file. See the _s_u_d_o_e_d_i_t___c_h_e_c_k_d_i_r option in sudoers(4) for + more information. + + editing symbolic links is not permitted + By default, ssuuddooeeddiitt does not follow symbolic links when opening + files. See the _s_u_d_o_e_d_i_t___f_o_l_l_o_w option in sudoers(4) for more + information. + + effective uid is not 0, is sudo installed setuid root? + ssuuddoo was not run with root privileges. The ssuuddoo binary must be + owned by the root user and have the Set-user-ID bit set. Also, it + must not be located on a file system mounted with the `nosuid' + option or on an NFS file system that maps uid 0 to an unprivileged + uid. + + effective uid is not 0, is sudo on a file system with the 'nosuid' option + set or an NFS file system without root privileges? + ssuuddoo was not run with root privileges. The ssuuddoo binary has the + proper owner and permissions but it still did not run with root + privileges. The most common reason for this is that the file + system the ssuuddoo binary is located on is mounted with the `nosuid' + option or it is an NFS file system that maps uid 0 to an + unprivileged uid. + + fatal error, unable to load plugins + An error occurred while loading or initializing the plugins + specified in sudo.conf(4). + + invalid environment variable name + One or more environment variable names specified via the --EE option + contained an equal sign (`='). The arguments to the --EE option + should be environment variable names without an associated value. + + no password was provided + When ssuuddoo tried to read the password, it did not receive any + characters. This may happen if no terminal is available (or the --SS + option is specified) and the standard input has been redirected + from _/_d_e_v_/_n_u_l_l. + + no tty present and no askpass program specified + ssuuddoo needs to read the password but there is no mechanism available + to do so. A terminal is not present to read the password from, + ssuuddoo has not been configured to read from the standard input, and + no askpass program has been specified either via the --AA option or + the SUDO_ASKPASS environment variable. + + no writable temporary directory found + ssuuddooeeddiitt was unable to find a usable temporary directory in which + to store its intermediate files. + + sudo must be owned by uid 0 and have the setuid bit set + ssuuddoo was not run with root privileges. The ssuuddoo binary does not + have the correct owner or permissions. It must be owned by the + root user and have the Set-user-ID bit set. + + sudoedit is not supported on this platform + It is only possible to run ssuuddooeeddiitt on systems that support setting + the effective user-ID. + + timed out reading password + The user did not enter a password before the password timeout (5 + minutes by default) expired. + + you do not exist in the passwd database + Your user ID does not appear in the system passwd database. + + you may not specify environment variables in edit mode + It is only possible to specify environment variables when running a + command. When editing a file, the editor is run with the user's + environment unmodified. + +SSEEEE AALLSSOO + su(1), stat(2), login_cap(3), passwd(4), sudo.conf(4), sudo_plugin(4), + sudoers(4), sudoreplay(1m), visudo(1m) + +HHIISSTTOORRYY + See the HISTORY file in the ssuuddoo distribution + (https://www.sudo.ws/history.html) for a brief history of sudo. + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +CCAAVVEEAATTSS + There is no easy way to prevent a user from gaining a root shell if that + user is allowed to run arbitrary commands via ssuuddoo. Also, many programs + (such as editors) allow the user to run commands via shell escapes, thus + avoiding ssuuddoo's checks. However, on most systems it is possible to + prevent shell escapes with the sudoers(4) plugin's _n_o_e_x_e_c functionality. + + It is not meaningful to run the cd command directly via sudo, e.g., + + $ sudo cd /usr/local/protected + + since when the command exits the parent process (your shell) will still + be the same. Please see the _E_X_A_M_P_L_E_S section for more information. + + Running shell scripts via ssuuddoo can expose the same kernel bugs that make + setuid shell scripts unsafe on some operating systems (if your OS has a + /dev/fd/ directory, setuid shell scripts are generally safe). + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 November 25, 2018 Sudo 1.8.26 diff --git a/doc/sudo.conf.cat b/doc/sudo.conf.cat new file mode 100644 index 0000000..b43217b --- /dev/null +++ b/doc/sudo.conf.cat @@ -0,0 +1,434 @@ +SUDO.CONF(4) File Formats Manual SUDO.CONF(4) + +NNAAMMEE + ssuuddoo..ccoonnff - configuration for sudo front end + +DDEESSCCRRIIPPTTIIOONN + The ssuuddoo..ccoonnff file is used to configure the ssuuddoo front end. It specifies + the security policy and I/O logging plugins, debug flags as well as + plugin-agnostic path names and settings. + + The ssuuddoo..ccoonnff file supports the following directives, described in detail + below. + + Plugin a security policy or I/O logging plugin + + Path a plugin-agnostic path + + Set a front end setting, such as _d_i_s_a_b_l_e___c_o_r_e_d_u_m_p or _g_r_o_u_p___s_o_u_r_c_e + + Debug debug flags to aid in debugging ssuuddoo, ssuuddoorreeppllaayy, vviissuuddoo, and + the ssuuddooeerrss plugin. + + The pound sign (`#') is used to indicate a comment. Both the comment + character and any text after it, up to the end of the line, are ignored. + + Long lines can be continued with a backslash (`\') as the last character + on the line. Note that leading white space is removed from the beginning + of lines even when the continuation character is used. + + Non-comment lines that don't begin with Plugin, Path, Debug, or Set are + silently ignored. + + The ssuuddoo..ccoonnff file is always parsed in the "C" locale. + + PPlluuggiinn ccoonnffiigguurraattiioonn + ssuuddoo supports a plugin architecture for security policies and + input/output logging. Third parties can develop and distribute their own + policy and I/O logging plugins to work seamlessly with the ssuuddoo front + end. Plugins are dynamically loaded based on the contents of ssuuddoo..ccoonnff. + + A Plugin line consists of the Plugin keyword, followed by the _s_y_m_b_o_l___n_a_m_e + and the _p_a_t_h to the dynamic shared object that contains the plugin. The + _s_y_m_b_o_l___n_a_m_e is the name of the struct policy_plugin or struct io_plugin + symbol contained in the plugin. The _p_a_t_h may be fully qualified or + relative. If not fully qualified, it is relative to the directory + specified by the _p_l_u_g_i_n___d_i_r Path setting, which defaults to + _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o. In other words: + + Plugin sudoers_policy sudoers.so + + is equivalent to: + + Plugin sudoers_policy /usr/local/libexec/sudo/sudoers.so + + If the plugin was compiled statically into the ssuuddoo binary instead of + being installed as a dynamic shared object, the _p_a_t_h should be specified + without a leading directory, as it does not actually exist in the file + system. For example: + + Plugin sudoers_policy sudoers.so + + Starting with ssuuddoo 1.8.5, any additional parameters after the _p_a_t_h are + passed as arguments to the plugin's _o_p_e_n function. For example, to + override the compile-time default sudoers file mode: + + Plugin sudoers_policy sudoers.so sudoers_mode=0440 + + See the sudoers(4) manual for a list of supported arguments. + + The same dynamic shared object may contain multiple plugins, each with a + different symbol name. The file must be owned by uid 0 and only writable + by its owner. Because of ambiguities that arise from composite policies, + only a single policy plugin may be specified. This limitation does not + apply to I/O plugins. + + If no ssuuddoo..ccoonnff file is present, or if it contains no Plugin lines, the + ssuuddooeerrss plugin will be used as the default security policy and for I/O + logging (if enabled by the policy). This is equivalent to the following: + + Plugin sudoers_policy sudoers.so + Plugin sudoers_io sudoers.so + + For more information on the ssuuddoo plugin architecture, see the + sudo_plugin(4) manual. + + PPaatthh sseettttiinnggss + A Path line consists of the Path keyword, followed by the name of the + path to set and its value. For example: + + Path noexec /usr/local/libexec/sudo/sudo_noexec.so + Path askpass /usr/X11R6/bin/ssh-askpass + + If no path name is specified, features relying on the specified setting + will be disabled. Disabling Path settings is only supported in ssuuddoo + version 1.8.16 and higher. + + The following plugin-agnostic paths may be set in the _/_e_t_c_/_s_u_d_o_._c_o_n_f + file: + + askpass The fully qualified path to a helper program used to read the + user's password when no terminal is available. This may be the + case when ssuuddoo is executed from a graphical (as opposed to + text-based) application. The program specified by _a_s_k_p_a_s_s + should display the argument passed to it as the prompt and + write the user's password to the standard output. The value of + _a_s_k_p_a_s_s may be overridden by the SUDO_ASKPASS environment + variable. + + devsearch + An ordered, colon-separated search path of directories to look + in for device nodes. This is used when mapping the process's + tty device number to a device name on systems that do not + provide such a mechanism. Sudo will _n_o_t recurse into sub- + directories. If terminal devices may be located in a sub- + directory of _/_d_e_v, that path must be explicitly listed in + _d_e_v_s_e_a_r_c_h. The default value is: + /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev + + This option is ignored on systems that support either the + ddeevvnnaammee() or __ttttyynnaammee__ddeevv() functions, for example BSD, macOS + and Solaris. + + noexec The fully-qualified path to a shared library containing + wrappers for the eexxeeccll(), eexxeeccllee(), eexxeeccllpp(), eexxeecctt(), eexxeeccvv(), + eexxeeccvvee(), eexxeeccvvPP(), eexxeeccvvpp(), eexxeeccvvppee(), ffeexxeeccvvee(), ppooppeenn(), + ppoossiixx__ssppaawwnn(), ppoossiixx__ssppaawwnnpp(), ssyysstteemm(), and wwoorrddeexxpp() library + functions that prevent the execution of further commands. This + is used to implement the _n_o_e_x_e_c functionality on systems that + support LD_PRELOAD or its equivalent. The default value is: + _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o_/_s_u_d_o___n_o_e_x_e_c_._s_o. + + plugin_dir + The default directory to use when searching for plugins that + are specified without a fully qualified path name. The default + value is _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o. + + sesh The fully-qualified path to the sseesshh binary. This setting is + only used when ssuuddoo is built with SELinux support. The default + value is _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o_/_s_e_s_h. + + OOtthheerr sseettttiinnggss + The ssuuddoo..ccoonnff file also supports the following front end settings: + + disable_coredump + Core dumps of ssuuddoo itself are disabled by default to prevent + the disclosure of potentially sensitive information. To aid in + debugging ssuuddoo crashes, you may wish to re-enable core dumps by + setting "disable_coredump" to false in ssuuddoo..ccoonnff as follows: + + Set disable_coredump false + + All modern operating systems place restrictions on core dumps + from setuid processes like ssuuddoo so this option can be enabled + without compromising security. To actually get a ssuuddoo core + file you will likely need to enable core dumps for setuid + processes. On BSD and Linux systems this is accomplished in + the sysctl(1m) command. On Solaris, the coreadm(1m) command is + used to configure core dump behavior. + + This setting is only available in ssuuddoo version 1.8.4 and + higher. + + group_source + ssuuddoo passes the invoking user's group list to the policy and + I/O plugins. On most systems, there is an upper limit to the + number of groups that a user may belong to simultaneously + (typically 16 for compatibility with NFS). On systems with the + getconf(1) utility, running: + getconf NGROUPS_MAX + will return the maximum number of groups. + + However, it is still possible to be a member of a larger number + of groups--they simply won't be included in the group list + returned by the kernel for the user. Starting with ssuuddoo + version 1.8.7, if the user's kernel group list has the maximum + number of entries, ssuuddoo will consult the group database + directly to determine the group list. This makes it possible + for the security policy to perform matching by group name even + when the user is a member of more than the maximum number of + groups. + + The _g_r_o_u_p___s_o_u_r_c_e setting allows the administrator to change + this default behavior. Supported values for _g_r_o_u_p___s_o_u_r_c_e are: + + static Use the static group list that the kernel returns. + Retrieving the group list this way is very fast but + it is subject to an upper limit as described above. + It is "static" in that it does not reflect changes to + the group database made after the user logs in. This + was the default behavior prior to ssuuddoo 1.8.7. + + dynamic Always query the group database directly. It is + "dynamic" in that changes made to the group database + after the user logs in will be reflected in the group + list. On some systems, querying the group database + for all of a user's groups can be time consuming when + querying a network-based group database. Most + operating systems provide an efficient method of + performing such queries. Currently, ssuuddoo supports + efficient group queries on AIX, BSD, HP-UX, Linux and + Solaris. + + adaptive Only query the group database if the static group + list returned by the kernel has the maximum number of + entries. This is the default behavior in ssuuddoo 1.8.7 + and higher. + + For example, to cause ssuuddoo to only use the kernel's static list + of groups for the user: + + Set group_source static + + This setting is only available in ssuuddoo version 1.8.7 and + higher. + + max_groups + The maximum number of user groups to retrieve from the group + database. Values less than one will be ignored. This setting + is only used when querying the group database directly. It is + intended to be used on systems where it is not possible to + detect when the array to be populated with group entries is not + sufficiently large. By default, ssuuddoo will allocate four times + the system's maximum number of groups (see above) and retry + with double that number if the group database query fails. + + This setting is only available in ssuuddoo version 1.8.7 and + higher. It should not be required in ssuuddoo versions 1.8.24 and + higher and may be removed in a later release. + + probe_interfaces + By default, ssuuddoo will probe the system's network interfaces and + pass the IP address of each enabled interface to the policy + plugin. This makes it possible for the plugin to match rules + based on the IP address without having to query DNS. On Linux + systems with a large number of virtual interfaces, this may + take a non-negligible amount of time. If IP-based matching is + not required, network interface probing can be disabled as + follows: + + Set probe_interfaces false + + This setting is only available in ssuuddoo version 1.8.10 and + higher. + + DDeebbuugg ffllaaggss + ssuuddoo versions 1.8.4 and higher support a flexible debugging framework + that can help track down what ssuuddoo is doing internally if there is a + problem. + + A Debug line consists of the Debug keyword, followed by the name of the + program (or plugin) to debug (ssuuddoo, vviissuuddoo, ssuuddoorreeppllaayy, ssuuddooeerrss), the + debug file name and a comma-separated list of debug flags. The debug + flag syntax used by ssuuddoo and the ssuuddooeerrss plugin is _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y but + a plugin is free to use a different format so long as it does not include + a comma (`,'). + + For example: + + Debug sudo /var/log/sudo_debug all@warn,plugin@info + + would log all debugging statements at the _w_a_r_n level and higher in + addition to those at the _i_n_f_o level for the plugin subsystem. + + As of ssuuddoo 1.8.12, multiple Debug entries may be specified per program. + Older versions of ssuuddoo only support a single Debug entry per program. + Plugin-specific Debug entries are also supported starting with ssuuddoo + 1.8.12 and are matched by either the base name of the plugin that was + loaded (for example sudoers.so) or by the plugin's fully-qualified path + name. Previously, the ssuuddooeerrss plugin shared the same Debug entry as the + ssuuddoo front end and could not be configured separately. + + The following priorities are supported, in order of decreasing severity: + _c_r_i_t, _e_r_r, _w_a_r_n, _n_o_t_i_c_e, _d_i_a_g, _i_n_f_o, _t_r_a_c_e and _d_e_b_u_g. Each priority, + when specified, also includes all priorities higher than it. For + example, a priority of _n_o_t_i_c_e would include debug messages logged at + _n_o_t_i_c_e and higher. + + The priorities _t_r_a_c_e and _d_e_b_u_g also include function call tracing which + logs when a function is entered and when it returns. For example, the + following trace is for the ggeett__uusseerr__ggrroouuppss() function located in + src/sudo.c: + + sudo[123] -> get_user_groups @ src/sudo.c:385 + sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 + + When the function is entered, indicated by a right arrow `->', the + program, process ID, function, source file and line number are logged. + When the function returns, indicated by a left arrow `<-', the same + information is logged along with the return value. In this case, the + return value is a string. + + The following subsystems are used by the ssuuddoo front-end: + + _a_l_l matches every subsystem + + _a_r_g_s command line argument processing + + _c_o_n_v user conversation + + _e_d_i_t sudoedit + + _e_v_e_n_t event subsystem + + _e_x_e_c command execution + + _m_a_i_n ssuuddoo main function + + _n_e_t_i_f network interface handling + + _p_c_o_m_m communication with the plugin + + _p_l_u_g_i_n plugin configuration + + _p_t_y pseudo-tty related code + + _s_e_l_i_n_u_x SELinux-specific handling + + _u_t_i_l utility functions + + _u_t_m_p utmp handling + + The sudoers(4) plugin includes support for additional subsystems. + +FFIILLEESS + _/_e_t_c_/_s_u_d_o_._c_o_n_f ssuuddoo front end configuration + +EEXXAAMMPPLLEESS + # + # Default /etc/sudo.conf file + # + # Format: + # Plugin plugin_name plugin_path plugin_options ... + # Path askpass /path/to/askpass + # Path noexec /path/to/sudo_noexec.so + # Debug sudo /var/log/sudo_debug all@warn + # Set disable_coredump true + # + # The plugin_path is relative to /usr/local/libexec/sudo unless + # fully qualified. + # The plugin_name corresponds to a global symbol in the plugin + # that contains the plugin interface structure. + # The plugin_options are optional. + # + # The sudoers plugin is used by default if no Plugin lines are + # present. + Plugin sudoers_policy sudoers.so + Plugin sudoers_io sudoers.so + + # + # Sudo askpass: + # + # An askpass helper program may be specified to provide a graphical + # password prompt for "sudo -A" support. Sudo does not ship with + # its own askpass program but can use the OpenSSH askpass. + # + # Use the OpenSSH askpass + #Path askpass /usr/X11R6/bin/ssh-askpass + # + # Use the Gnome OpenSSH askpass + #Path askpass /usr/libexec/openssh/gnome-ssh-askpass + + # + # Sudo noexec: + # + # Path to a shared library containing dummy versions of the execv(), + # execve() and fexecve() library functions that just return an error. + # This is used to implement the "noexec" functionality on systems that + # support C<LD_PRELOAD> or its equivalent. + # The compiled-in value is usually sufficient and should only be + # changed if you rename or move the sudo_noexec.so file. + # + #Path noexec /usr/local/libexec/sudo/sudo_noexec.so + + # + # Core dumps: + # + # By default, sudo disables core dumps while it is executing + # (they are re-enabled for the command that is run). + # To aid in debugging sudo problems, you may wish to enable core + # dumps by setting "disable_coredump" to false. + # + #Set disable_coredump false + + # + # User groups: + # + # Sudo passes the user's group list to the policy plugin. + # If the user is a member of the maximum number of groups (usually 16), + # sudo will query the group database directly to be sure to include + # the full list of groups. + # + # On some systems, this can be expensive so the behavior is configurable. + # The "group_source" setting has three possible values: + # static - use the user's list of groups returned by the kernel. + # dynamic - query the group database to find the list of groups. + # adaptive - if user is in less than the maximum number of groups. + # use the kernel list, else query the group database. + # + #Set group_source static + +SSEEEE AALLSSOO + sudo_plugin(4), sudoers(4), sudo(1m) + +HHIISSTTOORRYY + See the HISTORY file in the ssuuddoo distribution + (https://www.sudo.ws/history.html) for a brief history of sudo. + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 October 7, 2018 Sudo 1.8.26 diff --git a/doc/sudo.conf.man.in b/doc/sudo.conf.man.in new file mode 100644 index 0000000..8a8a311 --- /dev/null +++ b/doc/sudo.conf.man.in @@ -0,0 +1,752 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2010-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "SUDO.CONF" "@mansectform@" "October 7, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudo.conf\fR +\- configuration for sudo front end +.SH "DESCRIPTION" +The +\fBsudo.conf\fR +file is used to configure the +\fBsudo\fR +front end. +It specifies the security policy and I/O logging plugins, debug flags +as well as plugin-agnostic path names and settings. +.PP +The +\fBsudo.conf\fR +file supports the following directives, described in detail below. +.TP 10n +Plugin +a security policy or I/O logging plugin +.TP 10n +Path +a plugin-agnostic path +.TP 10n +Set +a front end setting, such as +\fIdisable_coredump\fR +or +\fIgroup_source\fR +.TP 10n +Debug +debug flags to aid in debugging +\fBsudo\fR, +\fBsudoreplay\fR, +\fBvisudo\fR, +and the +\fBsudoers\fR +plugin. +.PP +The pound sign +(\(oq#\(cq) +is used to indicate a comment. +Both the comment character and any text after it, up to the end of +the line, are ignored. +.PP +Long lines can be continued with a backslash +(\(oq\e\(cq) +as the last character on the line. +Note that leading white space is removed from the beginning of lines +even when the continuation character is used. +.PP +Non-comment lines that don't begin with +\fRPlugin\fR, +\fRPath\fR, +\fRDebug\fR, +or +\fRSet\fR +are silently ignored. +.PP +The +\fBsudo.conf\fR +file is always parsed in the +\(lq\fRC\fR\(rq +locale. +.SS "Plugin configuration" +\fBsudo\fR +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging plugins to work seamlessly with the +\fBsudo\fR +front end. +Plugins are dynamically loaded based on the contents of +\fBsudo.conf\fR. +.PP +A +\fRPlugin\fR +line consists of the +\fRPlugin\fR +keyword, followed by the +\fIsymbol_name\fR +and the +\fIpath\fR +to the dynamic shared object that contains the plugin. +The +\fIsymbol_name\fR +is the name of the +\fRstruct policy_plugin\fR +or +\fRstruct io_plugin\fR +symbol contained in the plugin. +The +\fIpath\fR +may be fully qualified or relative. +If not fully qualified, it is relative to the directory +specified by the +\fIplugin_dir\fR +\fRPath\fR +setting, which defaults to +\fI@PLUGINDIR@\fR. +In other words: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so +.RE +.fi +.PP +is equivalent to: +.nf +.sp +.RS 6n +Plugin sudoers_policy @PLUGINDIR@/sudoers.so +.RE +.fi +.PP +If the plugin was compiled statically into the +\fBsudo\fR +binary instead of being installed as a dynamic shared object, the +\fIpath\fR +should be specified without a leading directory, +as it does not actually exist in the file system. +For example: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so +.RE +.fi +.PP +Starting with +\fBsudo\fR +1.8.5, any additional parameters after the +\fIpath\fR +are passed as arguments to the plugin's +\fIopen\fR +function. +For example, to override the compile-time default sudoers file mode: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so sudoers_mode=0440 +.RE +.fi +.PP +See the +sudoers(@mansectform@) +manual for a list of supported arguments. +.PP +The same dynamic shared object may contain multiple plugins, +each with a different symbol name. +The file must be owned by uid 0 and only writable by its owner. +Because of ambiguities that arise from composite policies, only a single +policy plugin may be specified. +This limitation does not apply to I/O plugins. +.PP +If no +\fBsudo.conf\fR +file is present, or if it contains no +\fRPlugin\fR +lines, the +\fBsudoers\fR +plugin will be used as the default security policy and for I/O logging +(if enabled by the policy). +This is equivalent to the following: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.RE +.fi +.PP +For more information on the +\fBsudo\fR +plugin architecture, see the +sudo_plugin(@mansectform@) +manual. +.SS "Path settings" +A +\fRPath\fR +line consists of the +\fRPath\fR +keyword, followed by the name of the path to set and its value. +For example: +.nf +.sp +.RS 6n +Path noexec @noexec_file@ +Path askpass /usr/X11R6/bin/ssh-askpass +.RE +.fi +.PP +If no path name is specified, features relying on the specified +setting will be disabled. +Disabling +\fRPath\fR +settings is only supported in +\fBsudo\fR +version 1.8.16 and higher. +.PP +The following plugin-agnostic paths may be set in the +\fI@sysconfdir@/sudo.conf\fR +file: +.TP 10n +askpass +The fully qualified path to a helper program used to read the user's +password when no terminal is available. +This may be the case when +\fBsudo\fR +is executed from a graphical (as opposed to text-based) application. +The program specified by +\fIaskpass\fR +should display the argument passed to it as the prompt and write +the user's password to the standard output. +The value of +\fIaskpass\fR +may be overridden by the +\fRSUDO_ASKPASS\fR +environment variable. +.TP 10n +devsearch +.br +An ordered, colon-separated search path of directories to look in for +device nodes. +This is used when mapping the process's tty device number to a device name +on systems that do not provide such a mechanism. +Sudo will +\fInot\fR +recurse into sub-directories. +If terminal devices may be located in a sub-directory of +\fI/dev\fR, +that path must be explicitly listed in +\fIdevsearch\fR. +The default value is: +\fR/dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev\fR +.sp +This option is ignored on systems that support either the +\fBdevname\fR() +or +\fB_ttyname_dev\fR() +functions, for example +BSD, +macOS and Solaris. +.TP 10n +noexec +The fully-qualified path to a shared library containing wrappers +for the +\fBexecl\fR(), +\fBexecle\fR(), +\fBexeclp\fR(), +\fBexect\fR(), +\fBexecv\fR(), +\fBexecve\fR(), +\fBexecvP\fR(), +\fBexecvp\fR(), +\fBexecvpe\fR(), +\fBfexecve\fR(), +\fBpopen\fR(), +\fBposix_spawn\fR(), +\fBposix_spawnp\fR(), +\fBsystem\fR(), +and +\fBwordexp\fR() +library functions that prevent the execution of further commands. +This is used to implement the +\fInoexec\fR +functionality on systems that support +\fRLD_PRELOAD\fR +or its equivalent. +The default value is: +\fI@noexec_file@\fR. +.TP 10n +plugin_dir +The default directory to use when searching for plugins +that are specified without a fully qualified path name. +The default value is +\fI@PLUGINDIR@\fR. +.TP 10n +sesh +The fully-qualified path to the +\fBsesh\fR +binary. +This setting is only used when +\fBsudo\fR +is built with SELinux support. +The default value is +\fI@sesh_file@\fR. +.SS "Other settings" +The +\fBsudo.conf\fR +file also supports the following front end settings: +.TP 10n +disable_coredump +Core dumps of +\fBsudo\fR +itself are disabled by default to prevent the disclosure of potentially +sensitive information. +To aid in debugging +\fBsudo\fR +crashes, you may wish to re-enable core dumps by setting +\(lqdisable_coredump\(rq +to false in +\fBsudo.conf\fR +as follows: +.nf +.sp +.RS 16n +Set disable_coredump false +.RE +.fi +.RS 10n +.sp +All modern operating systems place restrictions on core dumps +from setuid processes like +\fBsudo\fR +so this option can be enabled without compromising security. +To actually get a +\fBsudo\fR +core file you will likely need to enable core dumps for setuid processes. +On +BSD +and Linux systems this is accomplished in the +sysctl(@mansectsu@) +command. +On Solaris, the +coreadm(1m) +command is used to configure core dump behavior. +.sp +This setting is only available in +\fBsudo\fR +version 1.8.4 and higher. +.RE +.TP 10n +group_source +\fBsudo\fR +passes the invoking user's group list to the policy and I/O plugins. +On most systems, there is an upper limit to the number of groups that +a user may belong to simultaneously (typically 16 for compatibility +with NFS). +On systems with the +getconf(1) +utility, running: +.RS 16n +getconf NGROUPS_MAX +.RE +.RS 10n +will return the maximum number of groups. +.sp +However, it is still possible to be a member of a larger number of +groups--they simply won't be included in the group list returned +by the kernel for the user. +Starting with +\fBsudo\fR +version 1.8.7, if the user's kernel group list has the maximum number +of entries, +\fBsudo\fR +will consult the group database directly to determine the group list. +This makes it possible for the security policy to perform matching by group +name even when the user is a member of more than the maximum number of groups. +.sp +The +\fIgroup_source\fR +setting allows the administrator to change this default behavior. +Supported values for +\fIgroup_source\fR +are: +.TP 10n +static +Use the static group list that the kernel returns. +Retrieving the group list this way is very fast but it is subject +to an upper limit as described above. +It is +\(lqstatic\(rq +in that it does not reflect changes to the group database made +after the user logs in. +This was the default behavior prior to +\fBsudo\fR +1.8.7. +.TP 10n +dynamic +Always query the group database directly. +It is +\(lqdynamic\(rq +in that changes made to the group database after the user logs in +will be reflected in the group list. +On some systems, querying the group database for all of a user's +groups can be time consuming when querying a network-based group +database. +Most operating systems provide an efficient method of performing +such queries. +Currently, +\fBsudo\fR +supports efficient group queries on AIX, +BSD, +HP-UX, Linux and Solaris. +.TP 10n +adaptive +Only query the group database if the static group list returned +by the kernel has the maximum number of entries. +This is the default behavior in +\fBsudo\fR +1.8.7 and higher. +.PP +For example, to cause +\fBsudo\fR +to only use the kernel's static list of groups for the user: +.nf +.sp +.RS 16n +Set group_source static +.RE +.fi +.sp +This setting is only available in +\fBsudo\fR +version 1.8.7 and higher. +.RE +.TP 10n +max_groups +The maximum number of user groups to retrieve from the group database. +Values less than one will be ignored. +This setting is only used when querying the group database directly. +It is intended to be used on systems where it is not possible to detect +when the array to be populated with group entries is not sufficiently large. +By default, +\fBsudo\fR +will allocate four times the system's maximum number of groups (see above) +and retry with double that number if the group database query fails. +.sp +This setting is only available in +\fBsudo\fR +version 1.8.7 and higher. +It should not be required in +\fBsudo\fR +versions 1.8.24 and higher and may be removed in a later release. +.TP 10n +probe_interfaces +By default, +\fBsudo\fR +will probe the system's network interfaces and pass the IP address +of each enabled interface to the policy plugin. +This makes it possible for the plugin to match rules based on the IP address +without having to query DNS. +On Linux systems with a large number of virtual interfaces, this may +take a non-negligible amount of time. +If IP-based matching is not required, network interface probing +can be disabled as follows: +.nf +.sp +.RS 16n +Set probe_interfaces false +.RE +.fi +.RS 10n +.sp +This setting is only available in +\fBsudo\fR +version 1.8.10 and higher. +.RE +.SS "Debug flags" +\fBsudo\fR +versions 1.8.4 and higher support a flexible debugging framework +that can help track down what +\fBsudo\fR +is doing internally if there is a problem. +.PP +A +\fRDebug\fR +line consists of the +\fRDebug\fR +keyword, followed by the name of the program (or plugin) to debug +(\fBsudo\fR, \fBvisudo\fR, \fBsudoreplay\fR, \fBsudoers\fR), +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by +\fBsudo\fR +and the +\fBsudoers\fR +plugin is +\fIsubsystem\fR@\fIpriority\fR +but a plugin is free to use a different format so long as it does +not include a comma +(\(oq\&,\(cq). +.PP +For example: +.nf +.sp +.RS 6n +Debug sudo /var/log/sudo_debug all@warn,plugin@info +.RE +.fi +.PP +would log all debugging statements at the +\fIwarn\fR +level and higher in addition to those at the +\fIinfo\fR +level for the plugin subsystem. +.PP +As of +\fBsudo\fR +1.8.12, multiple +\fRDebug\fR +entries may be specified per program. +Older versions of +\fBsudo\fR +only support a single +\fRDebug\fR +entry per program. +Plugin-specific +\fRDebug\fR +entries are also supported starting with +\fBsudo\fR +1.8.12 and are matched by either the base name of the plugin that was loaded +(for example +\fRsudoers.so\fR) +or by the plugin's fully-qualified path name. +Previously, the +\fBsudoers\fR +plugin shared the same +\fRDebug\fR +entry as the +\fBsudo\fR +front end and could not be configured separately. +.PP +The following priorities are supported, in order of decreasing severity: +\fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR +and +\fIdebug\fR. +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +\fInotice\fR +would include debug messages logged at +\fInotice\fR +and higher. +.PP +The priorities +\fItrace\fR +and +\fIdebug\fR +also include function call tracing which logs when a function is +entered and when it returns. +For example, the following trace is for the +\fBget_user_groups\fR() +function located in src/sudo.c: +.nf +.sp +.RS 6n +sudo[123] -> get_user_groups @ src/sudo.c:385 +sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 +.RE +.fi +.PP +When the function is entered, indicated by a right arrow +\(oq->\(cq, +the program, process ID, function, source file and line number +are logged. +When the function returns, indicated by a left arrow +\(oq<-\(cq, +the same information is logged along with the return value. +In this case, the return value is a string. +.PP +The following subsystems are used by the +\fBsudo\fR +front-end: +.TP 12n +\fIall\fR +matches every subsystem +.TP 12n +\fIargs\fR +command line argument processing +.TP 12n +\fIconv\fR +user conversation +.TP 12n +\fIedit\fR +sudoedit +.TP 12n +\fIevent\fR +event subsystem +.TP 12n +\fIexec\fR +command execution +.TP 12n +\fImain\fR +\fBsudo\fR +main function +.TP 12n +\fInetif\fR +network interface handling +.TP 12n +\fIpcomm\fR +communication with the plugin +.TP 12n +\fIplugin\fR +plugin configuration +.TP 12n +\fIpty\fR +pseudo-tty related code +.TP 12n +\fIselinux\fR +SELinux-specific handling +.TP 12n +\fIutil\fR +utility functions +.TP 12n +\fIutmp\fR +utmp handling +.PP +The +sudoers(@mansectform@) +plugin includes support for additional subsystems. +.SH "FILES" +.TP 26n +\fI@sysconfdir@/sudo.conf\fR +\fBsudo\fR +front end configuration +.SH "EXAMPLES" +.nf +.RS 0n +# +# Default @sysconfdir@/sudo.conf file +# +# Format: +# Plugin plugin_name plugin_path plugin_options ... +# Path askpass /path/to/askpass +# Path noexec /path/to/sudo_noexec.so +# Debug sudo /var/log/sudo_debug all@warn +# Set disable_coredump true +# +# The plugin_path is relative to @PLUGINDIR@ unless +# fully qualified. +# The plugin_name corresponds to a global symbol in the plugin +# that contains the plugin interface structure. +# The plugin_options are optional. +# +# The sudoers plugin is used by default if no Plugin lines are +# present. +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so + +# +# Sudo askpass: +# +# An askpass helper program may be specified to provide a graphical +# password prompt for "sudo -A" support. Sudo does not ship with +# its own askpass program but can use the OpenSSH askpass. +# +# Use the OpenSSH askpass +#Path askpass /usr/X11R6/bin/ssh-askpass +# +# Use the Gnome OpenSSH askpass +#Path askpass /usr/libexec/openssh/gnome-ssh-askpass + +# +# Sudo noexec: +# +# Path to a shared library containing dummy versions of the execv(), +# execve() and fexecve() library functions that just return an error. +# This is used to implement the "noexec" functionality on systems that +# support C<LD_PRELOAD> or its equivalent. +# The compiled-in value is usually sufficient and should only be +# changed if you rename or move the sudo_noexec.so file. +# +#Path noexec @noexec_file@ + +# +# Core dumps: +# +# By default, sudo disables core dumps while it is executing +# (they are re-enabled for the command that is run). +# To aid in debugging sudo problems, you may wish to enable core +# dumps by setting "disable_coredump" to false. +# +#Set disable_coredump false + +# +# User groups: +# +# Sudo passes the user's group list to the policy plugin. +# If the user is a member of the maximum number of groups (usually 16), +# sudo will query the group database directly to be sure to include +# the full list of groups. +# +# On some systems, this can be expensive so the behavior is configurable. +# The "group_source" setting has three possible values: +# static - use the user's list of groups returned by the kernel. +# dynamic - query the group database to find the list of groups. +# adaptive - if user is in less than the maximum number of groups. +# use the kernel list, else query the group database. +# +#Set group_source static +.RE +.fi +.SH "SEE ALSO" +sudo_plugin(@mansectform@), +sudoers(@mansectform@), +sudo(@mansectsu@) +.SH "HISTORY" +See the HISTORY file in the +\fBsudo\fR +distribution (https://www.sudo.ws/history.html) for a brief +history of sudo. +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudo.conf.mdoc.in b/doc/sudo.conf.mdoc.in new file mode 100644 index 0000000..4823a0b --- /dev/null +++ b/doc/sudo.conf.mdoc.in @@ -0,0 +1,687 @@ +.\" +.\" Copyright (c) 2010-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 7, 2018 +.Dt SUDO.CONF @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudo.conf +.Nd configuration for sudo front end +.Sh DESCRIPTION +The +.Nm sudo.conf +file is used to configure the +.Nm sudo +front end. +It specifies the security policy and I/O logging plugins, debug flags +as well as plugin-agnostic path names and settings. +.Pp +The +.Nm +file supports the following directives, described in detail below. +.Bl -tag -width 8n +.It Plugin +a security policy or I/O logging plugin +.It Path +a plugin-agnostic path +.It Set +a front end setting, such as +.Em disable_coredump +or +.Em group_source +.It Debug +debug flags to aid in debugging +.Nm sudo , +.Nm sudoreplay , +.Nm visudo , +and the +.Nm sudoers +plugin. +.El +.Pp +The pound sign +.Pq Ql # +is used to indicate a comment. +Both the comment character and any text after it, up to the end of +the line, are ignored. +.Pp +Long lines can be continued with a backslash +.Pq Ql \e +as the last character on the line. +Note that leading white space is removed from the beginning of lines +even when the continuation character is used. +.Pp +Non-comment lines that don't begin with +.Li Plugin , +.Li Path , +.Li Debug , +or +.Li Set +are silently ignored. +.Pp +The +.Nm +file is always parsed in the +.Dq Li C +locale. +.Ss Plugin configuration +.Nm sudo +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging plugins to work seamlessly with the +.Nm sudo +front end. +Plugins are dynamically loaded based on the contents of +.Nm . +.Pp +A +.Li Plugin +line consists of the +.Li Plugin +keyword, followed by the +.Em symbol_name +and the +.Em path +to the dynamic shared object that contains the plugin. +The +.Em symbol_name +is the name of the +.Li struct policy_plugin +or +.Li struct io_plugin +symbol contained in the plugin. +The +.Em path +may be fully qualified or relative. +If not fully qualified, it is relative to the directory +specified by the +.Em plugin_dir +.Li Path +setting, which defaults to +.Pa @PLUGINDIR@ . +In other words: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +.Ed +.Pp +is equivalent to: +.Bd -literal -offset indent +Plugin sudoers_policy @PLUGINDIR@/sudoers.so +.Ed +.Pp +If the plugin was compiled statically into the +.Nm sudo +binary instead of being installed as a dynamic shared object, the +.Em path +should be specified without a leading directory, +as it does not actually exist in the file system. +For example: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +.Ed +.Pp +Starting with +.Nm sudo +1.8.5, any additional parameters after the +.Em path +are passed as arguments to the plugin's +.Em open +function. +For example, to override the compile-time default sudoers file mode: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so sudoers_mode=0440 +.Ed +.Pp +See the +.Xr sudoers @mansectform@ +manual for a list of supported arguments. +.Pp +The same dynamic shared object may contain multiple plugins, +each with a different symbol name. +The file must be owned by uid 0 and only writable by its owner. +Because of ambiguities that arise from composite policies, only a single +policy plugin may be specified. +This limitation does not apply to I/O plugins. +.Pp +If no +.Nm +file is present, or if it contains no +.Li Plugin +lines, the +.Nm sudoers +plugin will be used as the default security policy and for I/O logging +(if enabled by the policy). +This is equivalent to the following: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.Ed +.Pp +For more information on the +.Nm sudo +plugin architecture, see the +.Xr sudo_plugin @mansectform@ +manual. +.Ss Path settings +A +.Li Path +line consists of the +.Li Path +keyword, followed by the name of the path to set and its value. +For example: +.Bd -literal -offset indent +Path noexec @noexec_file@ +Path askpass /usr/X11R6/bin/ssh-askpass +.Ed +.Pp +If no path name is specified, features relying on the specified +setting will be disabled. +Disabling +.Li Path +settings is only supported in +.Nm sudo +version 1.8.16 and higher. +.Pp +The following plugin-agnostic paths may be set in the +.Pa @sysconfdir@/sudo.conf +file: +.Bl -tag -width 8n +.It askpass +The fully qualified path to a helper program used to read the user's +password when no terminal is available. +This may be the case when +.Nm sudo +is executed from a graphical (as opposed to text-based) application. +The program specified by +.Em askpass +should display the argument passed to it as the prompt and write +the user's password to the standard output. +The value of +.Em askpass +may be overridden by the +.Ev SUDO_ASKPASS +environment variable. +.It devsearch +An ordered, colon-separated search path of directories to look in for +device nodes. +This is used when mapping the process's tty device number to a device name +on systems that do not provide such a mechanism. +Sudo will +.Em not +recurse into sub-directories. +If terminal devices may be located in a sub-directory of +.Pa /dev , +that path must be explicitly listed in +.Em devsearch . +The default value is: +.Li /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev +.Pp +This option is ignored on systems that support either the +.Fn devname +or +.Fn _ttyname_dev +functions, for example +.Bx , +macOS and Solaris. +.It noexec +The fully-qualified path to a shared library containing wrappers +for the +.Fn execl , +.Fn execle , +.Fn execlp , +.Fn exect , +.Fn execv , +.Fn execve , +.Fn execvP , +.Fn execvp , +.Fn execvpe , +.Fn fexecve , +.Fn popen , +.Fn posix_spawn , +.Fn posix_spawnp , +.Fn system , +and +.Fn wordexp +library functions that prevent the execution of further commands. +This is used to implement the +.Em noexec +functionality on systems that support +.Ev LD_PRELOAD +or its equivalent. +The default value is: +.Pa @noexec_file@ . +.It plugin_dir +The default directory to use when searching for plugins +that are specified without a fully qualified path name. +The default value is +.Pa @PLUGINDIR@ . +.It sesh +The fully-qualified path to the +.Nm sesh +binary. +This setting is only used when +.Nm sudo +is built with SELinux support. +The default value is +.Pa @sesh_file@ . +.El +.Ss Other settings +The +.Nm +file also supports the following front end settings: +.Bl -tag -width 8n +.It disable_coredump +Core dumps of +.Nm sudo +itself are disabled by default to prevent the disclosure of potentially +sensitive information. +To aid in debugging +.Nm sudo +crashes, you may wish to re-enable core dumps by setting +.Dq disable_coredump +to false in +.Nm +as follows: +.Bd -literal -offset indent +Set disable_coredump false +.Ed +.Pp +All modern operating systems place restrictions on core dumps +from setuid processes like +.Nm sudo +so this option can be enabled without compromising security. +To actually get a +.Nm sudo +core file you will likely need to enable core dumps for setuid processes. +On +.Bx +and Linux systems this is accomplished in the +.Xr sysctl 8 +command. +On Solaris, the +.Xr coreadm 1m +command is used to configure core dump behavior. +.Pp +This setting is only available in +.Nm sudo +version 1.8.4 and higher. +.It group_source +.Nm sudo +passes the invoking user's group list to the policy and I/O plugins. +On most systems, there is an upper limit to the number of groups that +a user may belong to simultaneously (typically 16 for compatibility +with NFS). +On systems with the +.Xr getconf 1 +utility, running: +.Dl getconf NGROUPS_MAX +will return the maximum number of groups. +.Pp +However, it is still possible to be a member of a larger number of +groups--they simply won't be included in the group list returned +by the kernel for the user. +Starting with +.Nm sudo +version 1.8.7, if the user's kernel group list has the maximum number +of entries, +.Nm sudo +will consult the group database directly to determine the group list. +This makes it possible for the security policy to perform matching by group +name even when the user is a member of more than the maximum number of groups. +.Pp +The +.Em group_source +setting allows the administrator to change this default behavior. +Supported values for +.Em group_source +are: +.Bl -tag -width 8n +.It static +Use the static group list that the kernel returns. +Retrieving the group list this way is very fast but it is subject +to an upper limit as described above. +It is +.Dq static +in that it does not reflect changes to the group database made +after the user logs in. +This was the default behavior prior to +.Nm sudo +1.8.7. +.It dynamic +Always query the group database directly. +It is +.Dq dynamic +in that changes made to the group database after the user logs in +will be reflected in the group list. +On some systems, querying the group database for all of a user's +groups can be time consuming when querying a network-based group +database. +Most operating systems provide an efficient method of performing +such queries. +Currently, +.Nm sudo +supports efficient group queries on AIX, +.Bx , +HP-UX, Linux and Solaris. +.It adaptive +Only query the group database if the static group list returned +by the kernel has the maximum number of entries. +This is the default behavior in +.Nm sudo +1.8.7 and higher. +.El +.Pp +For example, to cause +.Nm sudo +to only use the kernel's static list of groups for the user: +.Bd -literal -offset indent +Set group_source static +.Ed +.Pp +This setting is only available in +.Nm sudo +version 1.8.7 and higher. +.It max_groups +The maximum number of user groups to retrieve from the group database. +Values less than one will be ignored. +This setting is only used when querying the group database directly. +It is intended to be used on systems where it is not possible to detect +when the array to be populated with group entries is not sufficiently large. +By default, +.Nm sudo +will allocate four times the system's maximum number of groups (see above) +and retry with double that number if the group database query fails. +.Pp +This setting is only available in +.Nm sudo +version 1.8.7 and higher. +It should not be required in +.Nm sudo +versions 1.8.24 and higher and may be removed in a later release. +.It probe_interfaces +By default, +.Nm sudo +will probe the system's network interfaces and pass the IP address +of each enabled interface to the policy plugin. +This makes it possible for the plugin to match rules based on the IP address +without having to query DNS. +On Linux systems with a large number of virtual interfaces, this may +take a non-negligible amount of time. +If IP-based matching is not required, network interface probing +can be disabled as follows: +.Bd -literal -offset indent +Set probe_interfaces false +.Ed +.Pp +This setting is only available in +.Nm sudo +version 1.8.10 and higher. +.El +.Ss Debug flags +.Nm sudo +versions 1.8.4 and higher support a flexible debugging framework +that can help track down what +.Nm sudo +is doing internally if there is a problem. +.Pp +A +.Li Debug +line consists of the +.Li Debug +keyword, followed by the name of the program (or plugin) to debug +.Pq Nm sudo , Nm visudo , Nm sudoreplay , Nm sudoers , +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by +.Nm sudo +and the +.Nm sudoers +plugin is +.Em subsystem Ns @ Ns Em priority +but a plugin is free to use a different format so long as it does +not include a comma +.Pq Ql \&, . +.Pp +For example: +.Bd -literal -offset indent +Debug sudo /var/log/sudo_debug all@warn,plugin@info +.Ed +.Pp +would log all debugging statements at the +.Em warn +level and higher in addition to those at the +.Em info +level for the plugin subsystem. +.Pp +As of +.Nm sudo +1.8.12, multiple +.Li Debug +entries may be specified per program. +Older versions of +.Nm sudo +only support a single +.Li Debug +entry per program. +Plugin-specific +.Li Debug +entries are also supported starting with +.Nm sudo +1.8.12 and are matched by either the base name of the plugin that was loaded +(for example +.Li sudoers.so ) +or by the plugin's fully-qualified path name. +Previously, the +.Nm sudoers +plugin shared the same +.Li Debug +entry as the +.Nm sudo +front end and could not be configured separately. +.Pp +The following priorities are supported, in order of decreasing severity: +.Em crit , err , warn , notice , diag , info , trace +and +.Em debug . +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +.Em notice +would include debug messages logged at +.Em notice +and higher. +.Pp +The priorities +.Em trace +and +.Em debug +also include function call tracing which logs when a function is +entered and when it returns. +For example, the following trace is for the +.Fn get_user_groups +function located in src/sudo.c: +.Bd -literal -offset indent +sudo[123] -> get_user_groups @ src/sudo.c:385 +sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 +.Ed +.Pp +When the function is entered, indicated by a right arrow +.Ql -> , +the program, process ID, function, source file and line number +are logged. +When the function returns, indicated by a left arrow +.Ql <- , +the same information is logged along with the return value. +In this case, the return value is a string. +.Pp +The following subsystems are used by the +.Nm sudo +front-end: +.Bl -tag -width Fl +.It Em all +matches every subsystem +.It Em args +command line argument processing +.It Em conv +user conversation +.It Em edit +sudoedit +.It Em event +event subsystem +.It Em exec +command execution +.It Em main +.Nm sudo +main function +.It Em netif +network interface handling +.It Em pcomm +communication with the plugin +.It Em plugin +plugin configuration +.It Em pty +pseudo-tty related code +.It Em selinux +SELinux-specific handling +.It Em util +utility functions +.It Em utmp +utmp handling +.El +.Pp +The +.Xr sudoers @mansectform@ +plugin includes support for additional subsystems. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +.Nm sudo +front end configuration +.El +.Sh EXAMPLES +.Bd -literal +# +# Default @sysconfdir@/sudo.conf file +# +# Format: +# Plugin plugin_name plugin_path plugin_options ... +# Path askpass /path/to/askpass +# Path noexec /path/to/sudo_noexec.so +# Debug sudo /var/log/sudo_debug all@warn +# Set disable_coredump true +# +# The plugin_path is relative to @PLUGINDIR@ unless +# fully qualified. +# The plugin_name corresponds to a global symbol in the plugin +# that contains the plugin interface structure. +# The plugin_options are optional. +# +# The sudoers plugin is used by default if no Plugin lines are +# present. +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so + +# +# Sudo askpass: +# +# An askpass helper program may be specified to provide a graphical +# password prompt for "sudo -A" support. Sudo does not ship with +# its own askpass program but can use the OpenSSH askpass. +# +# Use the OpenSSH askpass +#Path askpass /usr/X11R6/bin/ssh-askpass +# +# Use the Gnome OpenSSH askpass +#Path askpass /usr/libexec/openssh/gnome-ssh-askpass + +# +# Sudo noexec: +# +# Path to a shared library containing dummy versions of the execv(), +# execve() and fexecve() library functions that just return an error. +# This is used to implement the "noexec" functionality on systems that +# support C<LD_PRELOAD> or its equivalent. +# The compiled-in value is usually sufficient and should only be +# changed if you rename or move the sudo_noexec.so file. +# +#Path noexec @noexec_file@ + +# +# Core dumps: +# +# By default, sudo disables core dumps while it is executing +# (they are re-enabled for the command that is run). +# To aid in debugging sudo problems, you may wish to enable core +# dumps by setting "disable_coredump" to false. +# +#Set disable_coredump false + +# +# User groups: +# +# Sudo passes the user's group list to the policy plugin. +# If the user is a member of the maximum number of groups (usually 16), +# sudo will query the group database directly to be sure to include +# the full list of groups. +# +# On some systems, this can be expensive so the behavior is configurable. +# The "group_source" setting has three possible values: +# static - use the user's list of groups returned by the kernel. +# dynamic - query the group database to find the list of groups. +# adaptive - if user is in less than the maximum number of groups. +# use the kernel list, else query the group database. +# +#Set group_source static +.Ed +.Sh SEE ALSO +.Xr sudo_plugin @mansectform@ , +.Xr sudoers @mansectform@ , +.Xr sudo @mansectsu@ +.Sh HISTORY +See the HISTORY file in the +.Nm sudo +distribution (https://www.sudo.ws/history.html) for a brief +history of sudo. +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudo.man.in b/doc/sudo.man.in new file mode 100644 index 0000000..ffcd468 --- /dev/null +++ b/doc/sudo.man.in @@ -0,0 +1,1431 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.nr SL @SEMAN@ +.nr BA @BAMAN@ +.nr LC @LCMAN@ +.nr PS @PSMAN@ +.TH "SUDO" "@mansectsu@" "November 25, 2018" "Sudo @PACKAGE_VERSION@" "System Manager's Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudo\fR, +\fBsudoedit\fR +\- execute a command as another user +.SH "SYNOPSIS" +.HP 5n +\fBsudo\fR +\fB\-h\fR\ |\ \fB\-K\fR\ |\ \fB\-k\fR\ |\ \fB\-V\fR +.br +.PD 0 +.HP 5n +\fBsudo\fR +\fB\-v\fR +[\fB\-AknS\fR] +.if \n(BA [\fB\-a\fR\ \fItype\fR] +[\fB\-g\fR\ \fIgroup\fR] +[\fB\-h\fR\ \fIhost\fR] +[\fB\-p\fR\ \fIprompt\fR] +[\fB\-u\fR\ \fIuser\fR] +.br +.HP 5n +\fBsudo\fR +\fB\-l\fR +[\fB\-AknS\fR] +.if \n(BA [\fB\-a\fR\ \fItype\fR] +[\fB\-g\fR\ \fIgroup\fR] +[\fB\-h\fR\ \fIhost\fR] +[\fB\-p\fR\ \fIprompt\fR] +[\fB\-U\fR\ \fIuser\fR] +[\fB\-u\fR\ \fIuser\fR] +[\fIcommand\fR] +.br +.HP 5n +\fBsudo\fR +[\fB\-AbEHnPS\fR] +.if \n(BA [\fB\-a\fR\ \fItype\fR] +[\fB\-C\fR\ \fInum\fR] +.if \n(LC [\fB\-c\fR\ \fIclass\fR] +[\fB\-g\fR\ \fIgroup\fR] +[\fB\-h\fR\ \fIhost\fR] +[\fB\-p\fR\ \fIprompt\fR] +.if \n(SL [\fB\-r\fR\ \fIrole\fR] +.if \n(SL [\fB\-t\fR\ \fItype\fR] +[\fB\-T\fR\ \fItimeout\fR] +[\fB\-u\fR\ \fIuser\fR] +[\fIVAR\fR=\fIvalue\fR] +[\fB\-i\fR\ |\ \fB\-s\fR] +[\fIcommand\fR] +.br +.HP 9n +\fBsudoedit\fR +[\fB\-AknS\fR] +.if \n(BA [\fB\-a\fR\ \fItype\fR] +[\fB\-C\fR\ \fInum\fR] +.if \n(LC [\fB\-c\fR\ \fIclass\fR] +[\fB\-g\fR\ \fIgroup\fR] +[\fB\-h\fR\ \fIhost\fR] +[\fB\-p\fR\ \fIprompt\fR] +[\fB\-T\fR\ \fItimeout\fR] +[\fB\-u\fR\ \fIuser\fR] +\fIfile\ ...\fR +.PD +.SH "DESCRIPTION" +\fBsudo\fR +allows a permitted user to execute a +\fIcommand\fR +as the superuser or another user, as specified by the security +policy. +The invoking user's real +(\fInot\fR effective) +user ID is used to determine the user name with which +to query the security policy. +.PP +\fBsudo\fR +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging plugins to work seamlessly with the +\fBsudo\fR +front end. +The default security policy is +\fIsudoers\fR, +which is configured via the file +\fI@sysconfdir@/sudoers\fR, +or via LDAP. +See the +\fIPlugins\fR +section for more information. +.PP +The security policy determines what privileges, if any, a user has +to run +\fBsudo\fR. +The policy may require that users authenticate themselves with a +password or another authentication mechanism. +If authentication is required, +\fBsudo\fR +will exit if the user's password is not entered within a configurable +time limit. +This limit is policy-specific; the default password prompt timeout +for the +\fIsudoers\fR +security policy is +\fR@password_timeout@\fR +minutes. +.PP +Security policies may support credential caching to allow the user +to run +\fBsudo\fR +again for a period of time without requiring authentication. +The +\fIsudoers\fR +policy caches credentials for +\fR@timeout@\fR +minutes, unless overridden in +sudoers(@mansectform@). +By running +\fBsudo\fR +with the +\fB\-v\fR +option, a user can update the cached credentials without running a +\fIcommand\fR. +.PP +When invoked as +\fBsudoedit\fR, +the +\fB\-e\fR +option (described below), is implied. +.PP +Security policies may log successful and failed attempts to use +\fBsudo\fR. +If an I/O plugin is configured, the running command's input and +output may be logged as well. +.PP +The options are as follows: +.TP 12n +\fB\-A\fR, \fB\--askpass\fR +Normally, if +\fBsudo\fR +requires a password, it will read it from the user's terminal. +If the +\fB\-A\fR (\fIaskpass\fR) +option is specified, a (possibly graphical) helper program is +executed to read the user's password and output the password to the +standard output. +If the +\fRSUDO_ASKPASS\fR +environment variable is set, it specifies the path to the helper +program. +Otherwise, if +sudo.conf(@mansectform@) +contains a line specifying the askpass program, that value will be +used. +For example: +.nf +.sp +.RS 16n +# Path to askpass helper program +Path askpass /usr/X11R6/bin/ssh-askpass +.RE +.fi +.RS 12n +.sp +If no askpass program is available, +\fBsudo\fR +will exit with an error. +.RE +.if \n(BA \{\ +.TP 12n +\fB\-a\fR \fItype\fR, \fB\--auth-type\fR=\fItype\fR +Use the specified +BSD +authentication +\fItype\fR +when validating the user, if allowed by +\fI/etc/login.conf\fR. +The system administrator may specify a list of sudo-specific +authentication methods by adding an +\(lqauth-sudo\(rq +entry in +\fI/etc/login.conf\fR. +This option is only available on systems that support +BSD +authentication. +.\} +.TP 12n +\fB\-b\fR, \fB\--background\fR +Run the given command in the background. +Note that it is not possible to use shell job control to manipulate +background processes started by +\fBsudo\fR. +Most interactive commands will fail to work properly in background +mode. +.TP 12n +\fB\-C\fR \fInum\fR, \fB\--close-from\fR=\fInum\fR +Close all file descriptors greater than or equal to +\fInum\fR +before executing a command. +Values less than three are not permitted. +By default, +\fBsudo\fR +will close all open file descriptors other than standard input, +standard output and standard error when executing a command. +The security policy may restrict the user's ability to use this option. +The +\fIsudoers\fR +policy only permits use of the +\fB\-C\fR +option when the administrator has enabled the +\fIclosefrom_override\fR +option. +.if \n(LC \{\ +.TP 12n +\fB\-c\fR \fIclass\fR, \fB\--login-class\fR=\fIclass\fR +Run the command with resource limits and scheduling priority of +the specified login +\fIclass\fR. +The +\fIclass\fR +argument can be either a class name as defined in +\fI/etc/login.conf\fR, +or a single +\(oq\-\(cq +character. +If +\fIclass\fR +is +\fB-\fR, +the default login class of the target user will be used. +Otherwise, the command must be run as the superuser (user ID 0), or +\fBsudo\fR +must be run from a shell that is already running as the superuser. +If the command is being run as a login shell, additional +\fI/etc/login.conf\fR +settings, such as the umask and environment variables, will +be applied, if present. +This option is only available on systems with +BSD +login classes. +.\} +.TP 12n +\fB\-E\fR, \fB\--preserve-env\fR +Indicates to the security policy that the user wishes to +preserve their existing environment variables. +The security policy may return an error if the user does not have +permission to preserve the environment. +.TP 12n +\fB\--preserve-env=list\fR +Indicates to the security policy that the user wishes to add the +comma-separated list of environment variables to those preserved +from the user's environment. +The security policy may return an error if the user does not have +permission to preserve the environment. +.TP 12n +\fB\-e\fR, \fB\--edit\fR +Edit one or more files instead of running a command. +In lieu of a path name, the string "sudoedit" is used when consulting +the security policy. +If the user is authorized by the policy, the following steps are +taken: +.RS 16n +.TP 5n +1.\& +Temporary copies are made of the files to be edited with the owner +set to the invoking user. +.TP 5n +2.\& +The editor specified by the policy is run to edit the temporary +files. +The +\fIsudoers\fR +policy uses the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +and +\fREDITOR\fR +environment variables (in that order). +If none of +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +are set, the first program listed in the +\fIeditor\fR +sudoers(@mansectform@) +option is used. +.TP 5n +3.\& +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. +.RE +.RS 12n +.sp +To help prevent the editing of unauthorized files, the following +restrictions are enforced unless explicitly allowed by the security policy: +.RS 16n +.TP 3n +\fB\(bu\fR +Symbolic links may not be edited (version 1.8.15 and higher). +.TP 3n +\fB\(bu\fR +Symbolic links along the path to be edited are not followed when the +parent directory is writable by the invoking user unless that user +is root (version 1.8.16 and higher). +.TP 3n +\fB\(bu\fR +Files located in a directory that is writable by the invoking user may +not be edited unless that user is root (version 1.8.16 and higher). +.RE +.sp +Users are never allowed to edit device special files. +.sp +If the specified file does not exist, it will be created. +Note that unlike most commands run by +\fIsudo\fR, +the editor is run with the invoking user's environment unmodified. +If, for some reason, +\fBsudo\fR +is unable to update a file with its edited version, the user will +receive a warning and the edited copy will remain in a temporary +file. +.RE +.TP 12n +\fB\-g\fR \fIgroup\fR, \fB\--group\fR=\fIgroup\fR +Run the command with the primary group set to +\fIgroup\fR +instead of the primary group specified by the target +user's password database entry. +The +\fIgroup\fR +may be either a group name or a numeric group ID +(GID) +prefixed with the +\(oq#\(cq +character (e.g., +\fR#0\fR +for GID 0). +When running a command as a GID, many shells require that the +\(oq#\(cq +be escaped with a backslash +(\(oq\e\(cq). +If no +\fB\-u\fR +option is specified, the command will be run as the invoking user. +In either case, the primary group will be set to +\fIgroup\fR. +The +\fIsudoers\fR +policy permits any of the target user's groups to be specified via +the +\fB\-g\fR +option as long as the +\fB\-P\fR +option is not in use. +.TP 12n +\fB\-H\fR, \fB\--set-home\fR +Request that the security policy set the +\fRHOME\fR +environment variable to the home directory specified by the target +user's password database entry. +Depending on the policy, this may be the default behavior. +.TP 12n +\fB\-h\fR, \fB\--help\fR +Display a short help message to the standard output and exit. +.TP 12n +\fB\-h\fR \fIhost\fR, \fB\--host\fR=\fIhost\fR +Run the command on the specified +\fIhost\fR +if the security policy plugin supports remote commands. +Note that the +\fIsudoers\fR +plugin does not currently support running remote commands. +This may also be used in conjunction with the +\fB\-l\fR +option to list a user's privileges for the remote host. +.TP 12n +\fB\-i\fR, \fB\--login\fR +Run the shell specified by the target user's password database entry +as a login shell. +This means that login-specific resource files such as +\fI.profile\fR, +\fI.bash_profile\fR +or +\fI.login\fR +will be read by the shell. +If a command is specified, it is passed to the shell for execution +via the shell's +\fB\-c\fR +option. +If no command is specified, an interactive shell is executed. +\fBsudo\fR +attempts to change to that user's home directory before running the +shell. +The command is run with an environment similar to the one +a user would receive at log in. +Note that most shells behave differently when a command is specified +as compared to an interactive session; consult the shell's manual +for details. +The +\fICommand environment\fR +section in the +sudoers(@mansectform@) +manual documents how the +\fB\-i\fR +option affects the environment in which a command is run when the +\fIsudoers\fR +policy is in use. +.TP 12n +\fB\-K\fR, \fB\--remove-timestamp\fR +Similar to the +\fB\-k\fR +option, except that it removes the user's cached credentials entirely +and may not be used in conjunction with a command or other option. +This option does not require a password. +Not all security policies support credential caching. +.TP 12n +\fB\-k\fR, \fB\--reset-timestamp\fR +When used without a command, invalidates the user's cached credentials. +In other words, the next time +\fBsudo\fR +is run a password will be required. +This option does not require a password and was added to allow a +user to revoke +\fBsudo\fR +permissions from a +\fI.logout\fR +file. +.sp +When used in conjunction with a command or an option that may require +a password, this option will cause +\fBsudo\fR +to ignore the user's cached credentials. +As a result, +\fBsudo\fR +will prompt for a password (if one is required by the security +policy) and will not update the user's cached credentials. +.sp +Not all security policies support credential caching. +.TP 12n +\fB\-l\fR, \fB\--list\fR +If no +\fIcommand\fR +is specified, +list the allowed (and forbidden) commands for the +invoking user (or the user specified by the +\fB\-U\fR +option) on the current host. +A longer list format is used if this option is specified multiple times +and the security policy supports a verbose output format. +.sp +If a +\fIcommand\fR +is specified and is permitted by the security policy, the fully-qualified +path to the command is displayed along with any command line +arguments. +If a +\fIcommand\fR +is specified but not allowed by the policy, +\fBsudo\fR +will exit with a status value of 1. +.TP 12n +\fB\-n\fR, \fB\--non-interactive\fR +Avoid prompting the user for input of any kind. +If a password is required for the command to run, +\fBsudo\fR +will display an error message and exit. +.TP 12n +\fB\-P\fR, \fB\--preserve-groups\fR +Preserve the invoking user's group vector unaltered. +By default, the +\fIsudoers\fR +policy will initialize the group vector to the list of groups the +target user is a member of. +The real and effective group IDs, however, are still set to match +the target user. +.TP 12n +\fB\-p\fR \fIprompt\fR, \fB\--prompt\fR=\fIprompt\fR +Use a custom password prompt with optional escape sequences. +The following percent +(\(oq%\(cq) +escape sequences are supported by the +\fIsudoers\fR +policy: +.PP +.RS 12n +.PD 0 +.TP 4n +\fR%H\fR +expanded to the host name including the domain name (on if the +machine's host name is fully qualified or the +\fIfqdn\fR +option is set in +sudoers(@mansectform@)) +.PD +.TP 4n +\fR%h\fR +expanded to the local host name without the domain name +.TP 4n +\fR%p\fR +expanded to the name of the user whose password is being requested +(respects the +\fIrootpw\fR, +\fItargetpw\fR, +and +\fIrunaspw\fR +flags in +sudoers(@mansectform@)) +.TP 4n +\fR\&%U\fR +expanded to the login name of the user the command will be run as +(defaults to root unless the +\fB\-u\fR +option is also specified) +.TP 4n +\fR%u\fR +expanded to the invoking user's login name +.TP 4n +\fR%%\fR +two consecutive +\(oq%\(cq +characters are collapsed into a single +\(oq%\(cq +character +.PP +The custom prompt will override the default prompt specified by either +the security policy or the +\fRSUDO_PROMPT\fR +environment variable. +On systems that use PAM, the custom prompt will also override the prompt +specified by a PAM module unless the +\fIpassprompt_override\fR +flag is disabled in +\fIsudoers\fR. +.RE +.if \n(SL \{\ +.TP 12n +\fB\-r\fR \fIrole\fR, \fB\--role\fR=\fIrole\fR +Run the command with an SELinux security context that includes +the specified +\fIrole\fR. +.\} +.TP 12n +\fB\-S\fR, \fB\--stdin\fR +Write the prompt to the standard error and read the password from the +standard input instead of using the terminal device. +.TP 12n +\fB\-s\fR, \fB\--shell\fR +Run the shell specified by the +\fRSHELL\fR +environment variable if it is set or the shell specified by the +invoking user's password database entry. +If a command is specified, it is passed to the shell for execution +via the shell's +\fB\-c\fR +option. +If no command is specified, an interactive shell is executed. +Note that most shells behave differently when a command is specified +as compared to an interactive session; consult the shell's manual +for details. +.if \n(SL \{\ +.TP 12n +\fB\-t\fR \fItype\fR, \fB\--type\fR=\fItype\fR +Run the command with an SELinux security context that includes +the specified +\fItype\fR. +If no +\fItype\fR +is specified, the default type is derived from the role. +.\} +.TP 12n +\fB\-U\fR \fIuser\fR, \fB\--other-user\fR=\fIuser\fR +Used in conjunction with the +\fB\-l\fR +option to list the privileges for +\fIuser\fR +instead of for the invoking user. +The security policy may restrict listing other users' privileges. +The +\fIsudoers\fR +policy only allows root or a user with the +\fRALL\fR +privilege on the current host to use this option. +.TP 12n +\fB\-T\fR \fItimeout\fR, \fB\--command-timeout\fR=\fItimeout\fR +Used to set a timeout for the command. +If the timeout expires before the command has exited, the +command will be terminated. +The security policy may restrict the ability to set command timeouts. +The +\fIsudoers\fR +policy requires that user-specified timeouts be explicitly enabled. +.TP 12n +\fB\-u\fR \fIuser\fR, \fB\--user\fR=\fIuser\fR +Run the command as a user other than the default target user +(usually +\fIroot\fR). +The +\fIuser\fR +may be either a user name or a numeric user ID +(UID) +prefixed with the +\(oq#\(cq +character (e.g., +\fR#0\fR +for UID 0). +When running commands as a UID, many shells require that the +\(oq#\(cq +be escaped with a backslash +(\(oq\e\(cq). +Some security policies may restrict UIDs +to those listed in the password database. +The +\fIsudoers\fR +policy allows UIDs that are not in the password database as long as the +\fItargetpw\fR +option is not set. +Other security policies may not support this. +.TP 12n +\fB\-V\fR, \fB\--version\fR +Print the +\fBsudo\fR +version string as well as the version string of the security +policy plugin and any I/O plugins. +If the invoking user is already root the +\fB\-V\fR +option will display the arguments passed to configure when +\fBsudo\fR +was built and plugins may display more verbose information such as +default options. +.TP 12n +\fB\-v\fR, \fB\--validate\fR +Update the user's cached credentials, authenticating the user +if necessary. +For the +\fIsudoers\fR +plugin, this extends the +\fBsudo\fR +timeout for another +\fR@timeout@\fR +minutes by default, but does not run a command. +Not all security policies support cached credentials. +.TP 12n +\fB\--\fR +The +\fB\--\fR +option indicates that +\fBsudo\fR +should stop processing command line arguments. +.PP +Environment variables to be set for the command may also be passed +on the command line in the form of +\fIVAR\fR=\fIvalue\fR, +e.g., +\fRLD_LIBRARY_PATH\fR=\fI/usr/local/pkg/lib\fR. +Variables passed on the command line are subject to restrictions +imposed by the security policy plugin. +The +\fIsudoers\fR +policy subjects variables passed on the command line to the same +restrictions as normal environment variables with one important +exception. +If the +\fIsetenv\fR +option is set in +\fIsudoers\fR, +the command to be run has the +\fRSETENV\fR +tag set or the command matched is +\fRALL\fR, +the user may set variables that would otherwise be forbidden. +See +sudoers(@mansectform@) +for more information. +.SH "COMMAND EXECUTION" +When +\fBsudo\fR +executes a command, the security policy specifies the execution +environment for the command. +Typically, the real and effective user and group and IDs are set to +match those of the target user, as specified in the password database, +and the group vector is initialized based on the group database +(unless the +\fB\-P\fR +option was specified). +.PP +The following parameters may be specified by security policy: +.TP 3n +\fB\(bu\fR +real and effective user ID +.TP 3n +\fB\(bu\fR +real and effective group ID +.TP 3n +\fB\(bu\fR +supplementary group IDs +.TP 3n +\fB\(bu\fR +the environment list +.TP 3n +\fB\(bu\fR +current working directory +.TP 3n +\fB\(bu\fR +file creation mode mask (umask) +.if \n(SL \{\ +.TP 3n +\fB\(bu\fR +SELinux role and type +.\} +.if \n(PS \{\ +.TP 3n +\fB\(bu\fR +Solaris project +.\} +.if \n(PS \{\ +.TP 3n +\fB\(bu\fR +Solaris privileges +.\} +.if \n(LC \{\ +.TP 3n +\fB\(bu\fR +BSD +login class +.\} +.TP 3n +\fB\(bu\fR +scheduling priority (aka nice value) +.SS "Process model" +There are two distinct ways +\fBsudo\fR +can run a command. +.PP +If an I/O logging plugin is configured or if the security policy +explicitly requests it, a new pseudo-terminal +(\(lqpty\(rq) +is allocated and +fork(2) +is used to create a second +\fBsudo\fR +process, referred to as the +\fImonitor\fR. +The +\fImonitor\fR +creates a new terminal session with itself as the leader and the pty as its +controlling terminal, calls +fork(2), +sets up the execution environment as described above, and then uses the +execve(2) +system call to run the command in the child process. +The +\fImonitor\fR +exists to relay job control signals between the user's +existing terminal and the pty the command is being run in. +This makes it possible to suspend and resume the command. +Without the monitor, the command would be in what POSIX terms an +\(lqorphaned process group\(rq +and it would not receive any job control signals from the kernel. +When the command exits or is terminated by a signal, the +\fImonitor\fR +passes the command's exit status to the main +\fBsudo\fR +process and exits. +After receiving the command's exit status, the main +\fBsudo\fR +passes the command's exit status to the security policy's close function +and exits. +.PP +If no pty is used, +\fBsudo\fR +calls +fork(2), +sets up the execution environment as described above, and uses the +execve(2) +system call to run the command in the child process. +The main +\fBsudo\fR +process waits until the command has completed, then passes the +command's exit status to the security policy's close function and exits. +As a special case, if the policy plugin does not define a close +function, +\fBsudo\fR +will execute the command directly instead of calling +fork(2) +first. +The +\fIsudoers\fR +policy plugin will only define a close function when I/O logging +is enabled, a pty is required, or the +\fIpam_session\fR +or +\fIpam_setcred\fR +options are enabled. +Note that +\fIpam_session\fR +and +\fIpam_setcred\fR +are enabled by default on systems using PAM. +.SS "Signal handling" +When the command is run as a child of the +\fBsudo\fR +process, +\fBsudo\fR +will relay signals it receives to the command. +The +\fRSIGINT\fR +and +\fRSIGQUIT\fR +signals are only relayed when the command is being run in a new pty +or when the signal was sent by a user process, not the kernel. +This prevents the command from receiving +\fRSIGINT\fR +twice each time the user enters control-C. +Some signals, such as +\fRSIGSTOP\fR +and +\fRSIGKILL\fR, +cannot be caught and thus will not be relayed to the command. +As a general rule, +\fRSIGTSTP\fR +should be used instead of +\fRSIGSTOP\fR +when you wish to suspend a command being run by +\fBsudo\fR. +.PP +As a special case, +\fBsudo\fR +will not relay signals that were sent by the command it is running. +This prevents the command from accidentally killing itself. +On some systems, the +reboot(@mansectsu@) +command sends +\fRSIGTERM\fR +to all non-system processes other than itself before rebooting +the system. +This prevents +\fBsudo\fR +from relaying the +\fRSIGTERM\fR +signal it received back to +reboot(@mansectsu@), +which might then exit before the system was actually rebooted, +leaving it in a half-dead state similar to single user mode. +Note, however, that this check only applies to the command run by +\fBsudo\fR +and not any other processes that the command may create. +As a result, running a script that calls +reboot(@mansectsu@) +or +shutdown(@mansectsu@) +via +\fBsudo\fR +may cause the system to end up in this undefined state unless the +reboot(@mansectsu@) +or +shutdown(@mansectsu@) +are run using the +\fBexec\fR() +family of functions instead of +\fBsystem\fR() +(which interposes a shell between the command and the calling process). +.PP +If no I/O logging plugins are loaded and the policy plugin has not +defined a +\fBclose\fR() +function, set a command timeout or required that the command be +run in a new pty, +\fBsudo\fR +may execute the command directly instead of running it as a child process. +.SS "Plugins" +Plugins may be specified via +\fRPlugin\fR +directives in the +sudo.conf(@mansectform@) +file. +They may be loaded as dynamic shared objects (on systems that support them), +or compiled directly into the +\fBsudo\fR +binary. +If no +sudo.conf(@mansectform@) +file is present, or it contains no +\fRPlugin\fR +lines, +\fBsudo\fR +will use the traditional +\fIsudoers\fR +security policy and I/O logging. +See the +sudo.conf(@mansectform@) +manual for details of the +\fI@sysconfdir@/sudo.conf\fR +file and the +sudo_plugin(@mansectform@) +manual for more information about the +\fBsudo\fR +plugin architecture. +.SH "EXIT VALUE" +Upon successful execution of a command, the exit status from +\fBsudo\fR +will be the exit status of the program that was executed. +If the command terminated due to receipt of a signal, +\fBsudo\fR +will send itself the same signal that terminated the command. +.PP +If the +\fB\-l\fR +option was specified without a command, +\fBsudo\fR +will exit with a value of 0 if the user is allowed to run +\fBsudo\fR +and they authenticated successfully (as required by the security policy). +If a command is specified with the +\fB\-l\fR +option, the exit value will only be 0 if the command is permitted by the +security policy, otherwise it will be 1. +.PP +If there is an authentication failure, a configuration/permission +problem or if the given command cannot be executed, +\fBsudo\fR +exits with a value of 1. +In the latter case, the error string is printed to the standard error. +If +\fBsudo\fR +cannot +stat(2) +one or more entries in the user's +\fRPATH\fR, +an error is printed to the standard error. +(If the directory does not exist or if it is not really a directory, +the entry is ignored and no error is printed.) +This should not happen under normal circumstances. +The most common reason for +stat(2) +to return +\(lqpermission denied\(rq +is if you are running an automounter and one of the directories in +your +\fRPATH\fR +is on a machine that is currently unreachable. +.SH "SECURITY NOTES" +\fBsudo\fR +tries to be safe when executing external commands. +.PP +To prevent command spoofing, +\fBsudo\fR +checks "." and "" (both denoting current directory) last when +searching for a command in the user's +\fRPATH\fR +(if one or both are in the +\fRPATH\fR). +Note, however, that the actual +\fRPATH\fR +environment variable is +\fInot\fR +modified and is passed unchanged to the program that +\fBsudo\fR +executes. +.PP +Users should +\fInever\fR +be granted +\fBsudo\fR +privileges to execute files that are writable by the user or +that reside in a directory that is writable by the user. +If the user can modify or replace the command there is no way +to limit what additional commands they can run. +.PP +Please note that +\fBsudo\fR +will normally only log the command it explicitly runs. +If a user runs a command such as +\fRsudo su\fR +or +\fRsudo sh\fR, +subsequent commands run from that shell are not subject to +\fBsudo\fR's +security policy. +The same is true for commands that offer shell escapes (including +most editors). +If I/O logging is enabled, subsequent commands will have their input and/or +output logged, but there will not be traditional logs for those commands. +Because of this, care must be taken when giving users access to commands via +\fBsudo\fR +to verify that the command does not inadvertently give the user an +effective root shell. +For more information, please see the +\fIPreventing shell escapes\fR +section in +sudoers(@mansectform@). +.PP +To prevent the disclosure of potentially sensitive information, +\fBsudo\fR +disables core dumps by default while it is executing (they are +re-enabled for the command that is run). +This historical practice dates from a time when most operating +systems allowed setuid processes to dump core by default. +To aid in debugging +\fBsudo\fR +crashes, you may wish to re-enable core dumps by setting +\(lqdisable_coredump\(rq +to false in the +sudo.conf(@mansectform@) +file as follows: +.nf +.sp +.RS 6n +Set disable_coredump false +.RE +.fi +.PP +See the +sudo.conf(@mansectform@) +manual for more information. +.SH "ENVIRONMENT" +\fBsudo\fR +utilizes the following environment variables. +The security policy has control over the actual content of the command's +environment. +.TP 17n +\fREDITOR\fR +Default editor to use in +\fB\-e\fR +(sudoedit) mode if neither +\fRSUDO_EDITOR\fR +nor +\fRVISUAL\fR +is set. +.TP 17n +\fRMAIL\fR +Set to the mail spool of the target user when the +\fB\-i\fR +option is specified or when +\fIenv_reset\fR +is enabled in +\fIsudoers\fR +(unless +\fRMAIL\fR +is present in the +\fIenv_keep\fR +list). +.TP 17n +\fRHOME\fR +Set to the home directory of the target user when the +\fB\-i\fR +or +\fB\-H\fR +options are specified, when the +\fB\-s\fR +option is specified and +\fIset_home\fR +is set in +\fIsudoers\fR, +when +\fIalways_set_home\fR +is enabled in +\fIsudoers\fR, +or when +\fIenv_reset\fR +is enabled in +\fIsudoers\fR +and +\fIHOME\fR +is not present in the +\fIenv_keep\fR +list. +.TP 17n +\fRLOGNAME\fR +Set to the login name of the target user when the +\fB\-i\fR +option is specified, when the +\fIset_logname\fR +option is enabled in +\fIsudoers\fR +or when the +\fIenv_reset\fR +option is enabled in +\fIsudoers\fR +(unless +\fRLOGNAME\fR +is present in the +\fIenv_keep\fR +list). +.TP 17n +\fRPATH\fR +May be overridden by the security policy. +.TP 17n +\fRSHELL\fR +Used to determine shell to run with +\fB\-s\fR +option. +.TP 17n +\fRSUDO_ASKPASS\fR +Specifies the path to a helper program used to read the password +if no terminal is available or if the +\fB\-A\fR +option is specified. +.TP 17n +\fRSUDO_COMMAND\fR +Set to the command run by sudo. +.TP 17n +\fRSUDO_EDITOR\fR +Default editor to use in +\fB\-e\fR +(sudoedit) mode. +.TP 17n +\fRSUDO_GID\fR +Set to the group ID of the user who invoked sudo. +.TP 17n +\fRSUDO_PROMPT\fR +Used as the default password prompt unless +the +\fB\-p\fR +option was specified. +.TP 17n +\fRSUDO_PS1\fR +If set, +\fRPS1\fR +will be set to its value for the program being run. +.TP 17n +\fRSUDO_UID\fR +Set to the user ID of the user who invoked sudo. +.TP 17n +\fRSUDO_USER\fR +Set to the login name of the user who invoked sudo. +.TP 17n +\fRUSER\fR +Set to the same value as +\fRLOGNAME\fR, +described above. +.TP 17n +\fRVISUAL\fR +Default editor to use in +\fB\-e\fR +(sudoedit) mode if +\fRSUDO_EDITOR\fR +is not set. +.SH "FILES" +.TP 26n +\fI@sysconfdir@/sudo.conf\fR +\fBsudo\fR +front end configuration +.SH "EXAMPLES" +Note: the following examples assume a properly configured security +policy. +.PP +To get a file listing of an unreadable directory: +.nf +.sp +.RS 6n +$ sudo ls /usr/local/protected +.RE +.fi +.PP +To list the home directory of user yaz on a machine where the file +system holding ~yaz is not exported as root: +.nf +.sp +.RS 6n +$ sudo -u yaz ls ~yaz +.RE +.fi +.PP +To edit the +\fIindex.html\fR +file as user www: +.nf +.sp +.RS 6n +$ sudoedit -u www ~www/htdocs/index.html +.RE +.fi +.PP +To view system logs only accessible to root and users in the adm +group: +.nf +.sp +.RS 6n +$ sudo -g adm more /var/log/syslog +.RE +.fi +.PP +To run an editor as jim with a different primary group: +.nf +.sp +.RS 6n +$ sudoedit -u jim -g audio ~jim/sound.txt +.RE +.fi +.PP +To shut down a machine: +.nf +.sp +.RS 6n +$ sudo shutdown -r +15 "quick reboot" +.RE +.fi +.PP +To make a usage listing of the directories in the /home partition. +Note that this runs the commands in a sub-shell to make the +\fRcd\fR +and file redirection work. +.nf +.sp +.RS 6n +$ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE" +.RE +.fi +.SH "DIAGNOSTICS" +Error messages produced by +\fBsudo\fR +include: +.TP 6n +\fRediting files in a writable directory is not permitted\fR +By default, +\fBsudoedit\fR +does not permit editing a file when any of the parent directories are writable +by the invoking user. +This avoids a race condition that could allow the user to overwrite +an arbitrary file. +See the +\fIsudoedit_checkdir\fR +option in +sudoers(@mansectform@) +for more information. +.TP 6n +\fRediting symbolic links is not permitted\fR +By default, +\fBsudoedit\fR +does not follow symbolic links when opening files. +See the +\fIsudoedit_follow\fR +option in +sudoers(@mansectform@) +for more information. +.TP 6n +\fReffective uid is not 0, is sudo installed setuid root?\fR +\fBsudo\fR +was not run with root privileges. +The +\fBsudo\fR +binary must be owned by the root user and have the Set-user-ID bit set. +Also, it must not be located on a file system mounted with the +\(oqnosuid\(cq +option or on an NFS file system that maps uid 0 to an unprivileged uid. +.TP 6n +\fReffective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?\fR +\fBsudo\fR +was not run with root privileges. +The +\fBsudo\fR +binary has the proper owner and permissions but it still did not run +with root privileges. +The most common reason for this is that the file system the +\fBsudo\fR +binary is located on is mounted with the +\(oqnosuid\(cq +option or it is an NFS file system that maps uid 0 to an unprivileged uid. +.TP 6n +\fRfatal error, unable to load plugins\fR +An error occurred while loading or initializing the plugins specified in +sudo.conf(@mansectform@). +.TP 6n +\fRinvalid environment variable name\fR +One or more environment variable names specified via the +\fB\-E\fR +option contained an equal sign +(\(oq=\(cq). +The arguments to the +\fB\-E\fR +option should be environment variable names without an associated value. +.TP 6n +\fRno password was provided\fR +When +\fBsudo\fR +tried to read the password, it did not receive any characters. +This may happen if no terminal is available (or the +\fB\-S\fR +option is specified) and the standard input has been redirected from +\fI/dev/null\fR. +.TP 6n +\fRno tty present and no askpass program specified\fR +\fBsudo\fR +needs to read the password but there is no mechanism available to do so. +A terminal is not present to read the password from, +\fBsudo\fR +has not been configured to read from the standard input, +and no askpass program has been specified either via the +\fB\-A\fR +option or the +\fRSUDO_ASKPASS\fR +environment variable. +.TP 6n +\fRno writable temporary directory found\fR +\fBsudoedit\fR +was unable to find a usable temporary directory in which to store its +intermediate files. +.TP 6n +\fRsudo must be owned by uid 0 and have the setuid bit set\fR +\fBsudo\fR +was not run with root privileges. +The +\fBsudo\fR +binary does not have the correct owner or permissions. +It must be owned by the root user and have the Set-user-ID bit set. +.TP 6n +\fRsudoedit is not supported on this platform\fR +It is only possible to run +\fBsudoedit\fR +on systems that support setting the effective user-ID. +.TP 6n +\fRtimed out reading password\fR +The user did not enter a password before the password timeout +(5 minutes by default) expired. +.TP 6n +\fRyou do not exist in the passwd database\fR +Your user ID does not appear in the system passwd database. +.TP 6n +\fRyou may not specify environment variables in edit mode\fR +It is only possible to specify environment variables when running +a command. +When editing a file, the editor is run with the user's environment unmodified. +.SH "SEE ALSO" +su(1), +stat(2), +login_cap(3), +passwd(@mansectform@), +sudo.conf(@mansectform@), +sudo_plugin(@mansectform@), +sudoers(@mansectform@), +sudoreplay(@mansectsu@), +visudo(@mansectsu@) +.SH "HISTORY" +See the HISTORY file in the +\fBsudo\fR +distribution (https://www.sudo.ws/history.html) for a brief +history of sudo. +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "CAVEATS" +There is no easy way to prevent a user from gaining a root shell +if that user is allowed to run arbitrary commands via +\fBsudo\fR. +Also, many programs (such as editors) allow the user to run commands +via shell escapes, thus avoiding +\fBsudo\fR's +checks. +However, on most systems it is possible to prevent shell escapes with the +sudoers(@mansectform@) +plugin's +\fInoexec\fR +functionality. +.PP +It is not meaningful to run the +\fRcd\fR +command directly via sudo, e.g., +.nf +.sp +.RS 6n +$ sudo cd /usr/local/protected +.RE +.fi +.PP +since when the command exits the parent process (your shell) will +still be the same. +Please see the +\fIEXAMPLES\fR +section for more information. +.PP +Running shell scripts via +\fBsudo\fR +can expose the same kernel bugs that make setuid shell scripts +unsafe on some operating systems (if your OS has a /dev/fd/ directory, +setuid shell scripts are generally safe). +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudo.man.in.sed b/doc/sudo.man.in.sed new file mode 100644 index 0000000..432dd74 --- /dev/null +++ b/doc/sudo.man.in.sed @@ -0,0 +1,76 @@ +s/^\(.TH .*\)/.nr SL @SEMAN@\ +.nr BA @BAMAN@\ +.nr LC @LCMAN@\ +.nr PS @PSMAN@\ +\1/ + +s/^\(\[\\fB\\-a\\fR.*\\fItype\\fR\]\) *$/.if \\n(BA \1/ +s/^\(\[\\fB\\-c\\fR.*\\fIclass\\fR\]\) *$/.if \\n(LC \1/ +s/^\(\[\\fB\\-r\\fR.*\\fIrole\\fR\]\) *$/.if \\n(SL \1/ +s/^\(\[\\fB\\-t\\fR.*\\fItype\\fR\]\) *$/.if \\n(SL \1/ + +/^\.TP 12n$/ { + N + /^\.TP 12n\n\\fB\\-a\\fR.*\\fItype\\fR$/,/^\.TP 12n/ { + /^\.TP 12n/ { + /^\.TP 12n\n\\fB\\-a\\fR.*\\fItype\\fR$/i\ +.if \\n(BA \\{\\ + /^\.TP 12n\n\\fB\\-a\\fR.*\\fItype\\fR$/!i\ +.\\} + } + } + /^\.TP 12n\n\\fB\\-c\\fR.*\\fIclass\\fR$/,/^\.TP 12n/ { + /^\.TP 12n/ { + /^\.TP 12n\n\\fB\\-c\\fR.*\\fIclass\\fR$/i\ +.if \\n(LC \\{\\ + /^\.TP 12n\n\\fB\\-c\\fR.*\\fIclass\\fR$/!i\ +.\\} + } + } + /^\.TP 12n\n\\fB\\-r\\fR.*\\fIrole\\fR$/,/^\.TP 12n/ { + /^\.TP 12n/ { + /^\.TP 12n\n\\fB\\-r\\fR.*\\fIrole\\fR$/i\ +.if \\n(SL \\{\\ + /^\.TP 12n\n\\fB\\-r\\fR.*\\fIrole\\fR$/!i\ +.\\} + } + } + /^\.TP 12n\n\\fB\\-t\\fR.*\\fItype\\fR$/,/^\.TP 12n/ { + /^\.TP 12n/ { + /^\.TP 12n\n\\fB\\-t\\fR.*\\fItype\\fR$/i\ +.if \\n(SL \\{\\ + /^\.TP 12n\n\\fB\\-t\\fR.*\\fItype\\fR$/!i\ +.\\} + } + } +} + +/^\.TP 3n$/ { + N + N + /^.TP 3n\n\\fB\\(bu\\fR\nSELinux role and type$/ { + i\ +.if \\n(SL \\{\\ + a\ +.\\} + } + /^.TP 3n\n\\fB\\(bu\\fR\nSolaris project$/ { + i\ +.if \\n(PS \\{\\ + a\ +.\\} + } + /^.TP 3n\n\\fB\\(bu\\fR\nSolaris privileges$/ { + i\ +.if \\n(PS \\{\\ + a\ +.\\} + } + /^.TP 3n\n\\fB\\(bu\\fR\nBSD$/ { + N + i\ +.if \\n(LC \\{\\ + a\ +.\\} + } +} diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in new file mode 100644 index 0000000..c9b928e --- /dev/null +++ b/doc/sudo.mdoc.in @@ -0,0 +1,1320 @@ +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.nr SL @SEMAN@ +.nr BA @BAMAN@ +.nr LC @LCMAN@ +.nr PS @PSMAN@ +.Dd November 25, 2018 +.Dt SUDO @mansectsu@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudo , +.Nm sudoedit +.Nd execute a command as another user +.Sh SYNOPSIS +.Nm sudo +.Fl h | K | k | V +.Nm sudo +.Fl v +.Op Fl AknS +.if \n(BA \{\ +.Op Fl a Ar type +.\} +.Op Fl g Ar group +.Op Fl h Ar host +.Op Fl p Ar prompt +.Op Fl u Ar user +.Nm sudo +.Fl l +.Op Fl AknS +.if \n(BA \{\ +.Op Fl a Ar type +.\} +.Op Fl g Ar group +.Op Fl h Ar host +.Op Fl p Ar prompt +.Op Fl U Ar user +.Op Fl u Ar user +.Op Ar command +.Nm sudo +.Op Fl AbEHnPS +.if \n(BA \{\ +.Op Fl a Ar type +.\} +.Op Fl C Ar num +.if \n(LC \{\ +.Op Fl c Ar class +.\} +.Op Fl g Ar group +.Op Fl h Ar host +.Op Fl p Ar prompt +.if \n(SL \{\ +.Op Fl r Ar role +.Op Fl t Ar type +.\} +.Op Fl T Ar timeout +.Op Fl u Ar user +.Op Ar VAR Ns = Ns Ar value +.Op Fl i | s +.Op Ar command +.Nm sudoedit +.Op Fl AknS +.if \n(BA \{\ +.Op Fl a Ar type +.\} +.Op Fl C Ar num +.if \n(LC \{\ +.Op Fl c Ar class +.\} +.Op Fl g Ar group +.Op Fl h Ar host +.Op Fl p Ar prompt +.Op Fl T Ar timeout +.Op Fl u Ar user +.Ar +.Sh DESCRIPTION +.Nm +allows a permitted user to execute a +.Ar command +as the superuser or another user, as specified by the security +policy. +The invoking user's real +.Pq Em not No effective +user ID is used to determine the user name with which +to query the security policy. +.Pp +.Nm +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging plugins to work seamlessly with the +.Nm +front end. +The default security policy is +.Em sudoers , +which is configured via the file +.Pa @sysconfdir@/sudoers , +or via LDAP. +See the +.Sx Plugins +section for more information. +.Pp +The security policy determines what privileges, if any, a user has +to run +.Nm . +The policy may require that users authenticate themselves with a +password or another authentication mechanism. +If authentication is required, +.Nm +will exit if the user's password is not entered within a configurable +time limit. +This limit is policy-specific; the default password prompt timeout +for the +.Em sudoers +security policy is +.Li @password_timeout@ +minutes. +.Pp +Security policies may support credential caching to allow the user +to run +.Nm +again for a period of time without requiring authentication. +The +.Em sudoers +policy caches credentials for +.Li @timeout@ +minutes, unless overridden in +.Xr sudoers @mansectform@ . +By running +.Nm +with the +.Fl v +option, a user can update the cached credentials without running a +.Ar command . +.Pp +When invoked as +.Nm sudoedit , +the +.Fl e +option (described below), is implied. +.Pp +Security policies may log successful and failed attempts to use +.Nm . +If an I/O plugin is configured, the running command's input and +output may be logged as well. +.Pp +The options are as follows: +.Bl -tag -width Fl +.It Fl A , -askpass +Normally, if +.Nm +requires a password, it will read it from the user's terminal. +If the +.Fl A Pq Em askpass +option is specified, a (possibly graphical) helper program is +executed to read the user's password and output the password to the +standard output. +If the +.Ev SUDO_ASKPASS +environment variable is set, it specifies the path to the helper +program. +Otherwise, if +.Xr sudo.conf @mansectform@ +contains a line specifying the askpass program, that value will be +used. +For example: +.Bd -literal -offset 4n +# Path to askpass helper program +Path askpass /usr/X11R6/bin/ssh-askpass +.Ed +.Pp +If no askpass program is available, +.Nm +will exit with an error. +.if \n(BA \{\ +.It Fl a Ar type , Fl -auth-type Ns = Ns Ar type +Use the specified +.Bx +authentication +.Ar type +when validating the user, if allowed by +.Pa /etc/login.conf . +The system administrator may specify a list of sudo-specific +authentication methods by adding an +.Dq auth-sudo +entry in +.Pa /etc/login.conf . +This option is only available on systems that support +.Bx +authentication. +.\} +.It Fl b , -background +Run the given command in the background. +Note that it is not possible to use shell job control to manipulate +background processes started by +.Nm . +Most interactive commands will fail to work properly in background +mode. +.It Fl C Ar num , Fl -close-from Ns = Ns Ar num +Close all file descriptors greater than or equal to +.Ar num +before executing a command. +Values less than three are not permitted. +By default, +.Nm +will close all open file descriptors other than standard input, +standard output and standard error when executing a command. +The security policy may restrict the user's ability to use this option. +The +.Em sudoers +policy only permits use of the +.Fl C +option when the administrator has enabled the +.Em closefrom_override +option. +.if \n(LC \{\ +.It Fl c Ar class , Fl -login-class Ns = Ns Ar class +Run the command with resource limits and scheduling priority of +the specified login +.Ar class . +The +.Ar class +argument can be either a class name as defined in +.Pa /etc/login.conf , +or a single +.Ql \- +character. +If +.Ar class +is +.Cm - , +the default login class of the target user will be used. +Otherwise, the command must be run as the superuser (user ID 0), or +.Nm +must be run from a shell that is already running as the superuser. +If the command is being run as a login shell, additional +.Pa /etc/login.conf +settings, such as the umask and environment variables, will +be applied, if present. +This option is only available on systems with +.Bx +login classes. +.\} +.It Fl E , -preserve-env +Indicates to the security policy that the user wishes to +preserve their existing environment variables. +The security policy may return an error if the user does not have +permission to preserve the environment. +.It Fl -preserve-env=list +Indicates to the security policy that the user wishes to add the +comma-separated list of environment variables to those preserved +from the user's environment. +The security policy may return an error if the user does not have +permission to preserve the environment. +.It Fl e , -edit +Edit one or more files instead of running a command. +In lieu of a path name, the string "sudoedit" is used when consulting +the security policy. +If the user is authorized by the policy, the following steps are +taken: +.Bl -enum -offset 4 +.It +Temporary copies are made of the files to be edited with the owner +set to the invoking user. +.It +The editor specified by the policy is run to edit the temporary +files. +The +.Em sudoers +policy uses the +.Ev SUDO_EDITOR , +.Ev VISUAL +and +.Ev EDITOR +environment variables (in that order). +If none of +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +are set, the first program listed in the +.Em editor +.Xr sudoers @mansectform@ +option is used. +.It +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. +.El +.Pp +To help prevent the editing of unauthorized files, the following +restrictions are enforced unless explicitly allowed by the security policy: +.Bl -bullet -offset 4 -width 1n +.It +Symbolic links may not be edited (version 1.8.15 and higher). +.It +Symbolic links along the path to be edited are not followed when the +parent directory is writable by the invoking user unless that user +is root (version 1.8.16 and higher). +.It +Files located in a directory that is writable by the invoking user may +not be edited unless that user is root (version 1.8.16 and higher). +.El +.Pp +Users are never allowed to edit device special files. +.Pp +If the specified file does not exist, it will be created. +Note that unlike most commands run by +.Em sudo , +the editor is run with the invoking user's environment unmodified. +If, for some reason, +.Nm +is unable to update a file with its edited version, the user will +receive a warning and the edited copy will remain in a temporary +file. +.It Fl g Ar group , Fl -group Ns = Ns Ar group +Run the command with the primary group set to +.Ar group +instead of the primary group specified by the target +user's password database entry. +The +.Ar group +may be either a group name or a numeric group ID +.Pq GID +prefixed with the +.Ql # +character (e.g., +.Li #0 +for GID 0). +When running a command as a GID, many shells require that the +.Ql # +be escaped with a backslash +.Pq Ql \e . +If no +.Fl u +option is specified, the command will be run as the invoking user. +In either case, the primary group will be set to +.Ar group . +The +.Em sudoers +policy permits any of the target user's groups to be specified via +the +.Fl g +option as long as the +.Fl P +option is not in use. +.It Fl H , -set-home +Request that the security policy set the +.Ev HOME +environment variable to the home directory specified by the target +user's password database entry. +Depending on the policy, this may be the default behavior. +.It Fl h , -help +Display a short help message to the standard output and exit. +.It Fl h Ar host , Fl -host Ns = Ns Ar host +Run the command on the specified +.Ar host +if the security policy plugin supports remote commands. +Note that the +.Em sudoers +plugin does not currently support running remote commands. +This may also be used in conjunction with the +.Fl l +option to list a user's privileges for the remote host. +.It Fl i , -login +Run the shell specified by the target user's password database entry +as a login shell. +This means that login-specific resource files such as +.Pa .profile , +.Pa .bash_profile +or +.Pa .login +will be read by the shell. +If a command is specified, it is passed to the shell for execution +via the shell's +.Fl c +option. +If no command is specified, an interactive shell is executed. +.Nm +attempts to change to that user's home directory before running the +shell. +The command is run with an environment similar to the one +a user would receive at log in. +Note that most shells behave differently when a command is specified +as compared to an interactive session; consult the shell's manual +for details. +The +.Em Command environment +section in the +.Xr sudoers @mansectform@ +manual documents how the +.Fl i +option affects the environment in which a command is run when the +.Em sudoers +policy is in use. +.It Fl K , -remove-timestamp +Similar to the +.Fl k +option, except that it removes the user's cached credentials entirely +and may not be used in conjunction with a command or other option. +This option does not require a password. +Not all security policies support credential caching. +.It Fl k , -reset-timestamp +When used without a command, invalidates the user's cached credentials. +In other words, the next time +.Nm +is run a password will be required. +This option does not require a password and was added to allow a +user to revoke +.Nm +permissions from a +.Pa .logout +file. +.Pp +When used in conjunction with a command or an option that may require +a password, this option will cause +.Nm +to ignore the user's cached credentials. +As a result, +.Nm +will prompt for a password (if one is required by the security +policy) and will not update the user's cached credentials. +.Pp +Not all security policies support credential caching. +.It Fl l , Fl -list +If no +.Ar command +is specified, +list the allowed (and forbidden) commands for the +invoking user (or the user specified by the +.Fl U +option) on the current host. +A longer list format is used if this option is specified multiple times +and the security policy supports a verbose output format. +.Pp +If a +.Ar command +is specified and is permitted by the security policy, the fully-qualified +path to the command is displayed along with any command line +arguments. +If a +.Ar command +is specified but not allowed by the policy, +.Nm +will exit with a status value of 1. +.It Fl n , -non-interactive +Avoid prompting the user for input of any kind. +If a password is required for the command to run, +.Nm +will display an error message and exit. +.It Fl P , -preserve-groups +Preserve the invoking user's group vector unaltered. +By default, the +.Em sudoers +policy will initialize the group vector to the list of groups the +target user is a member of. +The real and effective group IDs, however, are still set to match +the target user. +.It Fl p Ar prompt , Fl -prompt Ns = Ns Ar prompt +Use a custom password prompt with optional escape sequences. +The following percent +.Pq Ql % +escape sequences are supported by the +.Em sudoers +policy: +.Bl -tag -width 2n +.It Li %H +expanded to the host name including the domain name (on if the +machine's host name is fully qualified or the +.Em fqdn +option is set in +.Xr sudoers @mansectform@ ) +.It Li %h +expanded to the local host name without the domain name +.It Li %p +expanded to the name of the user whose password is being requested +(respects the +.Em rootpw , +.Em targetpw , +and +.Em runaspw +flags in +.Xr sudoers @mansectform@ ) +.It Li \&%U +expanded to the login name of the user the command will be run as +(defaults to root unless the +.Fl u +option is also specified) +.It Li %u +expanded to the invoking user's login name +.It Li %% +two consecutive +.Ql % +characters are collapsed into a single +.Ql % +character +.El +.Pp +The custom prompt will override the default prompt specified by either +the security policy or the +.Ev SUDO_PROMPT +environment variable. +On systems that use PAM, the custom prompt will also override the prompt +specified by a PAM module unless the +.Em passprompt_override +flag is disabled in +.Em sudoers . +.if \n(SL \{\ +.It Fl r Ar role , Fl -role Ns = Ns Ar role +Run the command with an SELinux security context that includes +the specified +.Ar role . +.\} +.It Fl S , -stdin +Write the prompt to the standard error and read the password from the +standard input instead of using the terminal device. +.It Fl s , -shell +Run the shell specified by the +.Ev SHELL +environment variable if it is set or the shell specified by the +invoking user's password database entry. +If a command is specified, it is passed to the shell for execution +via the shell's +.Fl c +option. +If no command is specified, an interactive shell is executed. +Note that most shells behave differently when a command is specified +as compared to an interactive session; consult the shell's manual +for details. +.if \n(SL \{\ +.It Fl t Ar type , Fl -type Ns = Ns Ar type +Run the command with an SELinux security context that includes +the specified +.Ar type . +If no +.Ar type +is specified, the default type is derived from the role. +.\} +.It Fl U Ar user , Fl -other-user Ns = Ns Ar user +Used in conjunction with the +.Fl l +option to list the privileges for +.Ar user +instead of for the invoking user. +The security policy may restrict listing other users' privileges. +The +.Em sudoers +policy only allows root or a user with the +.Li ALL +privilege on the current host to use this option. +.It Fl T Ar timeout , Fl -command-timeout Ns = Ns Ar timeout +Used to set a timeout for the command. +If the timeout expires before the command has exited, the +command will be terminated. +The security policy may restrict the ability to set command timeouts. +The +.Em sudoers +policy requires that user-specified timeouts be explicitly enabled. +.It Fl u Ar user , Fl -user Ns = Ns Ar user +Run the command as a user other than the default target user +(usually +.Em root ) . +The +.Ar user +may be either a user name or a numeric user ID +.Pq UID +prefixed with the +.Ql # +character (e.g., +.Li #0 +for UID 0). +When running commands as a UID, many shells require that the +.Ql # +be escaped with a backslash +.Pq Ql \e . +Some security policies may restrict UIDs +to those listed in the password database. +The +.Em sudoers +policy allows UIDs that are not in the password database as long as the +.Em targetpw +option is not set. +Other security policies may not support this. +.It Fl V , -version +Print the +.Nm +version string as well as the version string of the security +policy plugin and any I/O plugins. +If the invoking user is already root the +.Fl V +option will display the arguments passed to configure when +.Nm +was built and plugins may display more verbose information such as +default options. +.It Fl v , -validate +Update the user's cached credentials, authenticating the user +if necessary. +For the +.Em sudoers +plugin, this extends the +.Nm +timeout for another +.Li @timeout@ +minutes by default, but does not run a command. +Not all security policies support cached credentials. +.It Fl - +The +.Fl - +option indicates that +.Nm +should stop processing command line arguments. +.El +.Pp +Environment variables to be set for the command may also be passed +on the command line in the form of +.Ar VAR Ns = Ns Ar value , +e.g., +.Ev LD_LIBRARY_PATH Ns = Ns Pa /usr/local/pkg/lib . +Variables passed on the command line are subject to restrictions +imposed by the security policy plugin. +The +.Em sudoers +policy subjects variables passed on the command line to the same +restrictions as normal environment variables with one important +exception. +If the +.Em setenv +option is set in +.Em sudoers , +the command to be run has the +.Li SETENV +tag set or the command matched is +.Li ALL , +the user may set variables that would otherwise be forbidden. +See +.Xr sudoers @mansectform@ +for more information. +.Sh COMMAND EXECUTION +When +.Nm +executes a command, the security policy specifies the execution +environment for the command. +Typically, the real and effective user and group and IDs are set to +match those of the target user, as specified in the password database, +and the group vector is initialized based on the group database +(unless the +.Fl P +option was specified). +.Pp +The following parameters may be specified by security policy: +.Bl -bullet -width 1n +.It +real and effective user ID +.It +real and effective group ID +.It +supplementary group IDs +.It +the environment list +.It +current working directory +.It +file creation mode mask (umask) +.if \n(SL \{\ +.It +SELinux role and type +.\} +.if \n(PS \{\ +.It +Solaris project +.It +Solaris privileges +.\} +.if \n(LC \{\ +.It +.Bx +login class +.\} +.It +scheduling priority (aka nice value) +.El +.Ss Process model +There are two distinct ways +.Nm +can run a command. +.Pp +If an I/O logging plugin is configured or if the security policy +explicitly requests it, a new pseudo-terminal +.Pq Dq pty +is allocated and +.Xr fork 2 +is used to create a second +.Nm +process, referred to as the +.Em monitor . +The +.Em monitor +creates a new terminal session with itself as the leader and the pty as its +controlling terminal, calls +.Xr fork 2 , +sets up the execution environment as described above, and then uses the +.Xr execve 2 +system call to run the command in the child process. +The +.Em monitor +exists to relay job control signals between the user's +existing terminal and the pty the command is being run in. +This makes it possible to suspend and resume the command. +Without the monitor, the command would be in what POSIX terms an +.Dq orphaned process group +and it would not receive any job control signals from the kernel. +When the command exits or is terminated by a signal, the +.Em monitor +passes the command's exit status to the main +.Nm +process and exits. +After receiving the command's exit status, the main +.Nm +passes the command's exit status to the security policy's close function +and exits. +.Pp +If no pty is used, +.Nm +calls +.Xr fork 2 , +sets up the execution environment as described above, and uses the +.Xr execve 2 +system call to run the command in the child process. +The main +.Nm +process waits until the command has completed, then passes the +command's exit status to the security policy's close function and exits. +As a special case, if the policy plugin does not define a close +function, +.Nm +will execute the command directly instead of calling +.Xr fork 2 +first. +The +.Em sudoers +policy plugin will only define a close function when I/O logging +is enabled, a pty is required, or the +.Em pam_session +or +.Em pam_setcred +options are enabled. +Note that +.Em pam_session +and +.Em pam_setcred +are enabled by default on systems using PAM. +.Ss Signal handling +When the command is run as a child of the +.Nm +process, +.Nm +will relay signals it receives to the command. +The +.Dv SIGINT +and +.Dv SIGQUIT +signals are only relayed when the command is being run in a new pty +or when the signal was sent by a user process, not the kernel. +This prevents the command from receiving +.Dv SIGINT +twice each time the user enters control-C. +Some signals, such as +.Dv SIGSTOP +and +.Dv SIGKILL , +cannot be caught and thus will not be relayed to the command. +As a general rule, +.Dv SIGTSTP +should be used instead of +.Dv SIGSTOP +when you wish to suspend a command being run by +.Nm . +.Pp +As a special case, +.Nm +will not relay signals that were sent by the command it is running. +This prevents the command from accidentally killing itself. +On some systems, the +.Xr reboot @mansectsu@ +command sends +.Dv SIGTERM +to all non-system processes other than itself before rebooting +the system. +This prevents +.Nm +from relaying the +.Dv SIGTERM +signal it received back to +.Xr reboot @mansectsu@ , +which might then exit before the system was actually rebooted, +leaving it in a half-dead state similar to single user mode. +Note, however, that this check only applies to the command run by +.Nm +and not any other processes that the command may create. +As a result, running a script that calls +.Xr reboot @mansectsu@ +or +.Xr shutdown @mansectsu@ +via +.Nm +may cause the system to end up in this undefined state unless the +.Xr reboot @mansectsu@ +or +.Xr shutdown @mansectsu@ +are run using the +.Fn exec +family of functions instead of +.Fn system +(which interposes a shell between the command and the calling process). +.Pp +If no I/O logging plugins are loaded and the policy plugin has not +defined a +.Fn close +function, set a command timeout or required that the command be +run in a new pty, +.Nm +may execute the command directly instead of running it as a child process. +.Ss Plugins +Plugins may be specified via +.Li Plugin +directives in the +.Xr sudo.conf @mansectform@ +file. +They may be loaded as dynamic shared objects (on systems that support them), +or compiled directly into the +.Nm +binary. +If no +.Xr sudo.conf @mansectform@ +file is present, or it contains no +.Li Plugin +lines, +.Nm +will use the traditional +.Em sudoers +security policy and I/O logging. +See the +.Xr sudo.conf @mansectform@ +manual for details of the +.Pa @sysconfdir@/sudo.conf +file and the +.Xr sudo_plugin @mansectform@ +manual for more information about the +.Nm +plugin architecture. +.Sh EXIT VALUE +Upon successful execution of a command, the exit status from +.Nm +will be the exit status of the program that was executed. +If the command terminated due to receipt of a signal, +.Nm +will send itself the same signal that terminated the command. +.Pp +If the +.Fl l +option was specified without a command, +.Nm +will exit with a value of 0 if the user is allowed to run +.Nm +and they authenticated successfully (as required by the security policy). +If a command is specified with the +.Fl l +option, the exit value will only be 0 if the command is permitted by the +security policy, otherwise it will be 1. +.Pp +If there is an authentication failure, a configuration/permission +problem or if the given command cannot be executed, +.Nm +exits with a value of 1. +In the latter case, the error string is printed to the standard error. +If +.Nm +cannot +.Xr stat 2 +one or more entries in the user's +.Ev PATH , +an error is printed to the standard error. +(If the directory does not exist or if it is not really a directory, +the entry is ignored and no error is printed.) +This should not happen under normal circumstances. +The most common reason for +.Xr stat 2 +to return +.Dq permission denied +is if you are running an automounter and one of the directories in +your +.Ev PATH +is on a machine that is currently unreachable. +.Sh SECURITY NOTES +.Nm +tries to be safe when executing external commands. +.Pp +To prevent command spoofing, +.Nm +checks "." and "" (both denoting current directory) last when +searching for a command in the user's +.Ev PATH +(if one or both are in the +.Ev PATH ) . +Note, however, that the actual +.Ev PATH +environment variable is +.Em not +modified and is passed unchanged to the program that +.Nm +executes. +.Pp +Users should +.Em never +be granted +.Nm +privileges to execute files that are writable by the user or +that reside in a directory that is writable by the user. +If the user can modify or replace the command there is no way +to limit what additional commands they can run. +.Pp +Please note that +.Nm +will normally only log the command it explicitly runs. +If a user runs a command such as +.Li sudo su +or +.Li sudo sh , +subsequent commands run from that shell are not subject to +.Nm sudo Ns 's +security policy. +The same is true for commands that offer shell escapes (including +most editors). +If I/O logging is enabled, subsequent commands will have their input and/or +output logged, but there will not be traditional logs for those commands. +Because of this, care must be taken when giving users access to commands via +.Nm +to verify that the command does not inadvertently give the user an +effective root shell. +For more information, please see the +.Em Preventing shell escapes +section in +.Xr sudoers @mansectform@ . +.Pp +To prevent the disclosure of potentially sensitive information, +.Nm +disables core dumps by default while it is executing (they are +re-enabled for the command that is run). +This historical practice dates from a time when most operating +systems allowed setuid processes to dump core by default. +To aid in debugging +.Nm +crashes, you may wish to re-enable core dumps by setting +.Dq disable_coredump +to false in the +.Xr sudo.conf @mansectform@ +file as follows: +.Bd -literal -offset indent +Set disable_coredump false +.Ed +.Pp +See the +.Xr sudo.conf @mansectform@ +manual for more information. +.Sh ENVIRONMENT +.Nm +utilizes the following environment variables. +The security policy has control over the actual content of the command's +environment. +.Bl -tag -width 15n +.It Ev EDITOR +Default editor to use in +.Fl e +(sudoedit) mode if neither +.Ev SUDO_EDITOR +nor +.Ev VISUAL +is set. +.It Ev MAIL +Set to the mail spool of the target user when the +.Fl i +option is specified or when +.Em env_reset +is enabled in +.Em sudoers +(unless +.Ev MAIL +is present in the +.Em env_keep +list). +.It Ev HOME +Set to the home directory of the target user when the +.Fl i +or +.Fl H +options are specified, when the +.Fl s +option is specified and +.Em set_home +is set in +.Em sudoers , +when +.Em always_set_home +is enabled in +.Em sudoers , +or when +.Em env_reset +is enabled in +.Em sudoers +and +.Em HOME +is not present in the +.Em env_keep +list. +.It Ev LOGNAME +Set to the login name of the target user when the +.Fl i +option is specified, when the +.Em set_logname +option is enabled in +.Em sudoers +or when the +.Em env_reset +option is enabled in +.Em sudoers +(unless +.Ev LOGNAME +is present in the +.Em env_keep +list). +.It Ev PATH +May be overridden by the security policy. +.It Ev SHELL +Used to determine shell to run with +.Fl s +option. +.It Ev SUDO_ASKPASS +Specifies the path to a helper program used to read the password +if no terminal is available or if the +.Fl A +option is specified. +.It Ev SUDO_COMMAND +Set to the command run by sudo. +.It Ev SUDO_EDITOR +Default editor to use in +.Fl e +(sudoedit) mode. +.It Ev SUDO_GID +Set to the group ID of the user who invoked sudo. +.It Ev SUDO_PROMPT +Used as the default password prompt unless +the +.Fl p +option was specified. +.It Ev SUDO_PS1 +If set, +.Ev PS1 +will be set to its value for the program being run. +.It Ev SUDO_UID +Set to the user ID of the user who invoked sudo. +.It Ev SUDO_USER +Set to the login name of the user who invoked sudo. +.It Ev USER +Set to the same value as +.Ev LOGNAME , +described above. +.It Ev VISUAL +Default editor to use in +.Fl e +(sudoedit) mode if +.Ev SUDO_EDITOR +is not set. +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +.Nm +front end configuration +.El +.Sh EXAMPLES +Note: the following examples assume a properly configured security +policy. +.Pp +To get a file listing of an unreadable directory: +.Bd -literal -offset indent +$ sudo ls /usr/local/protected +.Ed +.Pp +To list the home directory of user yaz on a machine where the file +system holding ~yaz is not exported as root: +.Bd -literal -offset indent +$ sudo -u yaz ls ~yaz +.Ed +.Pp +To edit the +.Pa index.html +file as user www: +.Bd -literal -offset indent +$ sudoedit -u www ~www/htdocs/index.html +.Ed +.Pp +To view system logs only accessible to root and users in the adm +group: +.Bd -literal -offset indent +$ sudo -g adm more /var/log/syslog +.Ed +.Pp +To run an editor as jim with a different primary group: +.Bd -literal -offset indent +$ sudoedit -u jim -g audio ~jim/sound.txt +.Ed +.Pp +To shut down a machine: +.Bd -literal -offset indent +$ sudo shutdown -r +15 "quick reboot" +.Ed +.Pp +To make a usage listing of the directories in the /home partition. +Note that this runs the commands in a sub-shell to make the +.Li cd +and file redirection work. +.Bd -literal -offset indent +$ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE" +.Ed +.Sh DIAGNOSTICS +Error messages produced by +.Nm +include: +.Bl -tag -width 4n +.It Li editing files in a writable directory is not permitted +By default, +.Nm sudoedit +does not permit editing a file when any of the parent directories are writable +by the invoking user. +This avoids a race condition that could allow the user to overwrite +an arbitrary file. +See the +.Em sudoedit_checkdir +option in +.Xr sudoers @mansectform@ +for more information. +.It Li editing symbolic links is not permitted +By default, +.Nm sudoedit +does not follow symbolic links when opening files. +See the +.Em sudoedit_follow +option in +.Xr sudoers @mansectform@ +for more information. +.It Li effective uid is not 0, is sudo installed setuid root? +.Nm +was not run with root privileges. +The +.Nm +binary must be owned by the root user and have the Set-user-ID bit set. +Also, it must not be located on a file system mounted with the +.Sq nosuid +option or on an NFS file system that maps uid 0 to an unprivileged uid. +.It Li effective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges? +.Nm +was not run with root privileges. +The +.Nm +binary has the proper owner and permissions but it still did not run +with root privileges. +The most common reason for this is that the file system the +.Nm +binary is located on is mounted with the +.Sq nosuid +option or it is an NFS file system that maps uid 0 to an unprivileged uid. +.It Li fatal error, unable to load plugins +An error occurred while loading or initializing the plugins specified in +.Xr sudo.conf @mansectform@ . +.It Li invalid environment variable name +One or more environment variable names specified via the +.Fl E +option contained an equal sign +.Pq Ql = . +The arguments to the +.Fl E +option should be environment variable names without an associated value. +.It Li no password was provided +When +.Nm +tried to read the password, it did not receive any characters. +This may happen if no terminal is available (or the +.Fl S +option is specified) and the standard input has been redirected from +.Pa /dev/null . +.It Li no tty present and no askpass program specified +.Nm +needs to read the password but there is no mechanism available to do so. +A terminal is not present to read the password from, +.Nm +has not been configured to read from the standard input, +and no askpass program has been specified either via the +.Fl A +option or the +.Ev SUDO_ASKPASS +environment variable. +.It Li no writable temporary directory found +.Nm sudoedit +was unable to find a usable temporary directory in which to store its +intermediate files. +.It Li sudo must be owned by uid 0 and have the setuid bit set +.Nm +was not run with root privileges. +The +.Nm +binary does not have the correct owner or permissions. +It must be owned by the root user and have the Set-user-ID bit set. +.It Li sudoedit is not supported on this platform +It is only possible to run +.Nm sudoedit +on systems that support setting the effective user-ID. +.It Li timed out reading password +The user did not enter a password before the password timeout +(5 minutes by default) expired. +.It Li you do not exist in the passwd database +Your user ID does not appear in the system passwd database. +.It Li you may not specify environment variables in edit mode +It is only possible to specify environment variables when running +a command. +When editing a file, the editor is run with the user's environment unmodified. +.El +.Sh SEE ALSO +.Xr su 1 , +.Xr stat 2 , +.Xr login_cap 3 , +.Xr passwd @mansectform@ , +.Xr sudo.conf @mansectform@ , +.Xr sudo_plugin @mansectform@ , +.Xr sudoers @mansectform@ , +.Xr sudoreplay @mansectsu@ , +.Xr visudo @mansectsu@ +.Sh HISTORY +See the HISTORY file in the +.Nm +distribution (https://www.sudo.ws/history.html) for a brief +history of sudo. +.Sh AUTHORS +Many people have worked on +.Nm +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm . +.Sh CAVEATS +There is no easy way to prevent a user from gaining a root shell +if that user is allowed to run arbitrary commands via +.Nm . +Also, many programs (such as editors) allow the user to run commands +via shell escapes, thus avoiding +.Nm sudo Ns 's +checks. +However, on most systems it is possible to prevent shell escapes with the +.Xr sudoers @mansectform@ +plugin's +.Em noexec +functionality. +.Pp +It is not meaningful to run the +.Li cd +command directly via sudo, e.g., +.Bd -literal -offset indent +$ sudo cd /usr/local/protected +.Ed +.Pp +since when the command exits the parent process (your shell) will +still be the same. +Please see the +.Sx EXAMPLES +section for more information. +.Pp +Running shell scripts via +.Nm +can expose the same kernel bugs that make setuid shell scripts +unsafe on some operating systems (if your OS has a /dev/fd/ directory, +setuid shell scripts are generally safe). +.Sh BUGS +If you feel you have found a bug in +.Nm , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat new file mode 100644 index 0000000..eda4ceb --- /dev/null +++ b/doc/sudo_plugin.cat @@ -0,0 +1,1683 @@ +SUDO_PLUGIN(4) File Formats Manual SUDO_PLUGIN(4) + +NNAAMMEE + ssuuddoo__pplluuggiinn - Sudo Plugin API + +DDEESSCCRRIIPPTTIIOONN + Starting with version 1.8, ssuuddoo supports a plugin API for policy and + session logging. Plugins may be compiled as dynamic shared objects (the + default on systems that support them) or compiled statically into the + ssuuddoo binary itself. By default, the ssuuddooeerrss policy plugin and an + associated I/O logging plugin are used. Via the plugin API, ssuuddoo can be + configured to use alternate policy and/or I/O logging plugins provided by + third parties. The plugins to be used are specified in the sudo.conf(4) + file. + + The API is versioned with a major and minor number. The minor version + number is incremented when additions are made. The major number is + incremented when incompatible changes are made. A plugin should be check + the version passed to it and make sure that the major version matches. + + The plugin API is defined by the sudo_plugin.h header file. + + PPoolliiccyy pplluuggiinn AAPPII + A policy plugin must declare and populate a policy_plugin struct in the + global scope. This structure contains pointers to the functions that + implement the ssuuddoo policy checks. The name of the symbol should be + specified in sudo.conf(4) along with a path to the plugin so that ssuuddoo + can load it. + + struct policy_plugin { + #define SUDO_POLICY_PLUGIN 1 + unsigned int type; /* always SUDO_POLICY_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); + int (*show_version)(int verbose); + int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + int (*list)(int argc, char * const argv[], int verbose, + const char *list_user); + int (*validate)(void); + void (*invalidate)(int remove); + int (*init_session)(struct passwd *pwd, char **user_env[]); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); + }; + + The policy_plugin struct has the following fields: + + type The type field should always be set to SUDO_POLICY_PLUGIN. + + version + The version field should be set to SUDO_API_VERSION. + + This allows ssuuddoo to determine the API version the plugin was built + against. + + open + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); + + Returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error. In the latter case, ssuuddoo will + print a usage message before it exits. If an error occurs, the + plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + The function arguments are as follows: + + version + The version passed in by ssuuddoo allows the plugin to determine + the major and minor version number of the plugin API + supported by ssuuddoo. + + conversation + A pointer to the ccoonnvveerrssaattiioonn() function that can be used by + the plugin to interact with the user (see below). Returns 0 + on success and -1 on failure. + + plugin_printf + A pointer to a pprriinnttff()-style function that may be used to + display informational or error messages (see below). Returns + the number of characters printed on success and -1 on + failure. + + settings + A vector of user-supplied ssuuddoo settings in the form of + "name=value" strings. The vector is terminated by a NULL + pointer. These settings correspond to flags the user + specified when running ssuuddoo. As such, they will only be + present when the corresponding flag has been specified on the + command line. + + When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + bsdauth_type=string + Authentication type, if specified by the --aa flag, to + use on systems where BSD authentication is supported. + + closefrom=number + If specified, the user has requested via the --CC flag + that ssuuddoo close all files descriptors with a value of + _n_u_m_b_e_r or higher. The plugin may optionally pass this, + or another value, back in the _c_o_m_m_a_n_d___i_n_f_o list. + + debug_flags=string + A debug file path name followed by a space and a comma- + separated list of debug flags that correspond to the + plugin's Debug entry in sudo.conf(4), if there is one. + The flags are passed to the plugin exactly as they + appear in sudo.conf(4). The syntax used by ssuuddoo and + the ssuuddooeerrss plugin is _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y but a plugin + is free to use a different format so long as it does + not include a comma (`,'). Prior to ssuuddoo 1.8.12, there + was no way to specify plugin-specific _d_e_b_u_g___f_l_a_g_s so + the value was always the same as that used by the ssuuddoo + front end and did not include a path name, only the + flags themselves. As of version 1.7 of the plugin + interface, ssuuddoo will only pass _d_e_b_u_g___f_l_a_g_s if + sudo.conf(4) contains a plugin-specific Debug entry. + + debug_level=number + This setting has been deprecated in favor of + _d_e_b_u_g___f_l_a_g_s. + + ignore_ticket=bool + Set to true if the user specified the --kk flag along + with a command, indicating that the user wishes to + ignore any cached authentication credentials. + _i_m_p_l_i_e_d___s_h_e_l_l to true. This allows ssuuddoo with no + arguments to be used similarly to su(1). If the plugin + does not to support this usage, it may return a value + of -2 from the cchheecckk__ppoolliiccyy() function, which will + cause ssuuddoo to print a usage message and exit. + + implied_shell=bool + If the user does not specify a program on the command + line, ssuuddoo will pass the plugin the path to the user's + shell and set + + login_class=string + BSD login class to use when setting resource limits and + nice value, if specified by the --cc flag. + + login_shell=bool + Set to true if the user specified the --ii flag, + indicating that the user wishes to run a login shell. + + max_groups=int + The maximum number of groups a user may belong to. + This will only be present if there is a corresponding + setting in sudo.conf(4). + + network_addrs=list + A space-separated list of IP network addresses and + netmasks in the form "addr/netmask", e.g., + "192.168.1.2/255.255.255.0". The address and netmask + pairs may be either IPv4 or IPv6, depending on what the + operating system supports. If the address contains a + colon (`:'), it is an IPv6 address, else it is IPv4. + + noninteractive=bool + Set to true if the user specified the --nn flag, + indicating that ssuuddoo should operate in non-interactive + mode. The plugin may reject a command run in non- + interactive mode if user interaction is required. + + plugin_dir=string + The default plugin directory used by the ssuuddoo front + end. This is the default directory set at compile time + and may not correspond to the directory the running + plugin was loaded from. It may be used by a plugin to + locate support files. + + plugin_path=string + The path name of plugin loaded by the ssuuddoo front end. + The path name will be a fully-qualified unless the + plugin was statically compiled into ssuuddoo. + + preserve_environment=bool + Set to true if the user specified the --EE flag, + indicating that the user wishes to preserve the + environment. + + preserve_groups=bool + Set to true if the user specified the --PP flag, + indicating that the user wishes to preserve the group + vector instead of setting it based on the runas user. + + progname=string + The command name that sudo was run as, typically "sudo" + or "sudoedit". + + prompt=string + The prompt to use when requesting a password, if + specified via the --pp flag. + + remote_host=string + The name of the remote host to run the command on, if + specified via the --hh option. Support for running the + command on a remote host is meant to be implemented via + a helper program that is executed in place of the user- + specified command. The ssuuddoo front end is only capable + of executing commands on the local host. Only + available starting with API version 1.4. + + run_shell=bool + Set to true if the user specified the --ss flag, + indicating that the user wishes to run a shell. + + runas_group=string + The group name or gid to run the command as, if + specified via the --gg flag. + + runas_user=string + The user name or uid to run the command as, if + specified via the --uu flag. + + selinux_role=string + SELinux role to use when executing the command, if + specified by the --rr flag. + + selinux_type=string + SELinux type to use when executing the command, if + specified by the --tt flag. + + set_home=bool + Set to true if the user specified the --HH flag. If + true, set the HOME environment variable to the target + user's home directory. + + sudoedit=bool + Set to true when the --ee flag is specified or if invoked + as ssuuddooeeddiitt. The plugin shall substitute an editor + into _a_r_g_v in the cchheecckk__ppoolliiccyy() function or return -2 + with a usage error if the plugin does not support + _s_u_d_o_e_d_i_t. For more information, see the _c_h_e_c_k___p_o_l_i_c_y + section. + + timeout=string + User-specified command timeout. Not all plugins + support command timeouts and the ability for the user + to set a timeout may be restricted by policy. The + format of the timeout string is plugin-specific. + + Additional settings may be added in the future so the plugin + should silently ignore settings that it does not recognize. + + user_info + A vector of information about the user running the command in + the form of "name=value" strings. The vector is terminated + by a NULL pointer. + + When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + cols=int + The number of columns the user's terminal supports. If + there is no terminal device available, a default value + of 80 is used. + + cwd=string + The user's current working directory. + + egid=gid_t + The effective group ID of the user invoking ssuuddoo. + + euid=uid_t + The effective user ID of the user invoking ssuuddoo. + + gid=gid_t + The real group ID of the user invoking ssuuddoo. + + groups=list + The user's supplementary group list formatted as a + string of comma-separated group IDs. + + host=string + The local machine's hostname as returned by the + gethostname(2) system call. + + lines=int + The number of lines the user's terminal supports. If + there is no terminal device available, a default value + of 24 is used. + + pgid=int + The ID of the process group that the running ssuuddoo + process is a member of. Only available starting with + API version 1.2. + + pid=int + The process ID of the running ssuuddoo process. Only + available starting with API version 1.2. + + plugin_options + Any (non-comment) strings immediately after the plugin + path are passed as arguments to the plugin. These + arguments are split on a white space boundary and are + passed to the plugin in the form of a NULL-terminated + array of strings. If no arguments were specified, + _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL pointer. + + NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available + starting with API version 1.2. A plugin mmuusstt check the + API version specified by the ssuuddoo front end before + using _p_l_u_g_i_n___o_p_t_i_o_n_s. Failure to do so may result in a + crash. + + ppid=int + The parent process ID of the running ssuuddoo process. + Only available starting with API version 1.2. + + sid=int + The session ID of the running ssuuddoo process or 0 if ssuuddoo + is not part of a POSIX job control session. Only + available starting with API version 1.2. + + tcpgid=int + The ID of the foreground process group associated with + the terminal device associated with the ssuuddoo process or + -1 if there is no terminal present. Only available + starting with API version 1.2. + + tty=string + The path to the user's terminal device. If the user + has no terminal device associated with the session, the + value will be empty, as in "tty=". + + uid=uid_t + The real user ID of the user invoking ssuuddoo. + + umask=octal + The invoking user's file creation mask. Only available + starting with API version 1.10. + + user=string + The name of the user invoking ssuuddoo. + + user_env + The user's environment in the form of a NULL-terminated + vector of "name=value" strings. + + When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + close + void (*close)(int exit_status, int error); + + The cclloossee() function is called when the command being run by ssuuddoo + finishes. + + The function arguments are as follows: + + exit_status + The command's exit status, as returned by the wait(2) system + call. The value of exit_status is undefined if error is non- + zero. + + error + If the command could not be executed, this is set to the + value of errno set by the execve(2) system call. The plugin + is responsible for displaying error information via the + ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function. If the command + was successfully executed, the value of error is 0. + + If no cclloossee() function is defined, no I/O logging plugins are + loaded, and neither the _t_i_m_e_o_u_t not _u_s_e___p_t_y options are set in the + command_info list, the ssuuddoo front end may execute the command + directly instead of running it as a child process. + + show_version + int (*show_version)(int verbose); + + The sshhooww__vveerrssiioonn() function is called by ssuuddoo when the user + specifies the --VV option. The plugin may display its version + information to the user via the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function using SUDO_CONV_INFO_MSG. If the user requests detailed + version information, the verbose flag will be set. + + Returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error, although the return value is + currently ignored. + + check_policy + int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + + The cchheecckk__ppoolliiccyy() function is called by ssuuddoo to determine whether + the user is allowed to run the specified commands. + + If the _s_u_d_o_e_d_i_t option was enabled in the _s_e_t_t_i_n_g_s array passed to + the ooppeenn() function, the user has requested _s_u_d_o_e_d_i_t mode. + _s_u_d_o_e_d_i_t is a mechanism for editing one or more files where an + editor is run with the user's credentials instead of with elevated + privileges. ssuuddoo achieves this by creating user-writable temporary + copies of the files to be edited and then overwriting the originals + with the temporary copies after editing is complete. If the plugin + supports _s_u_d_o_e_d_i_t, it should choose the editor to be used, + potentially from a variable in the user's environment, such as + EDITOR, and include it in _a_r_g_v___o_u_t (note that environment variables + may include command line flags). The files to be edited should be + copied from _a_r_g_v into _a_r_g_v___o_u_t, separated from the editor and its + arguments by a "--" element. The "--" will be removed by ssuuddoo + before the editor is executed. The plugin should also set + _s_u_d_o_e_d_i_t_=_t_r_u_e in the _c_o_m_m_a_n_d___i_n_f_o list. + + The cchheecckk__ppoolliiccyy() function returns 1 if the command is allowed, 0 + if not allowed, -1 for a general error, or -2 for a usage error or + if _s_u_d_o_e_d_i_t was specified but is unsupported by the plugin. In the + latter case, ssuuddoo will print a usage message before it exits. If + an error occurs, the plugin may optionally call the ccoonnvveerrssaattiioonn() + or pplluuggiinn__pprriinnttff() function with SUDO_CONF_ERROR_MSG to present + additional error information to the user. + + The function arguments are as follows: + + argc The number of elements in _a_r_g_v, not counting the final NULL + pointer. + + argv The argument vector describing the command the user wishes to + run, in the same form as what would be passed to the + execve(2) system call. The vector is terminated by a NULL + pointer. + + env_add + Additional environment variables specified by the user on the + command line in the form of a NULL-terminated vector of + "name=value" strings. The plugin may reject the command if + one or more variables are not allowed to be set, or it may + silently ignore such variables. + + When parsing _e_n_v___a_d_d, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + command_info + Information about the command being run in the form of + "name=value" strings. These values are used by ssuuddoo to set + the execution environment when running a command. The plugin + is responsible for creating and populating the vector, which + must be terminated with a NULL pointer. The following values + are recognized by ssuuddoo: + + chroot=string + The root directory to use when running the command. + + closefrom=number + If specified, ssuuddoo will close all files descriptors + with a value of _n_u_m_b_e_r or higher. + + command=string + Fully qualified path to the command to be executed. + + cwd=string + The current working directory to change to when + executing the command. + + exec_background=bool + By default, ssuuddoo runs a command as the foreground + process as long as ssuuddoo itself is running in the + foreground. When _e_x_e_c___b_a_c_k_g_r_o_u_n_d is enabled and the + command is being run in a pty (due to I/O logging or + the _u_s_e___p_t_y setting), the command will be run as a + background process. Attempts to read from the + controlling terminal (or to change terminal settings) + will result in the command being suspended with the + SIGTTIN signal (or SIGTTOU in the case of terminal + settings). If this happens when ssuuddoo is a foreground + process, the command will be granted the controlling + terminal and resumed in the foreground with no user + intervention required. The advantage of initially + running the command in the background is that ssuuddoo need + not read from the terminal unless the command + explicitly requests it. Otherwise, any terminal input + must be passed to the command, whether it has required + it or not (the kernel buffers terminals so it is not + possible to tell whether the command really wants the + input). This is different from historic _s_u_d_o behavior + or when the command is not being run in a pty. + + For this to work seamlessly, the operating system must + support the automatic restarting of system calls. + Unfortunately, not all operating systems do this by + default, and even those that do may have bugs. For + example, macOS fails to restart the ttccggeettaattttrr() and + ttccsseettaattttrr() system calls (this is a bug in macOS). + Furthermore, because this behavior depends on the + command stopping with the SIGTTIN or SIGTTOU signals, + programs that catch these signals and suspend + themselves with a different signal (usually SIGTOP) + will not be automatically foregrounded. Some versions + of the linux su(1) command behave this way. Because of + this, a plugin should not set _e_x_e_c___b_a_c_k_g_r_o_u_n_d unless it + is explicitly enabled by the administrator and there + should be a way to enabled or disable it on a per- + command basis. + + This setting has no effect unless I/O logging is + enabled or _u_s_e___p_t_y is enabled. + + execfd=number + If specified, ssuuddoo will use the fexecve(2) system call + to execute the command instead of execve(2). The + specified _n_u_m_b_e_r must refer to an open file descriptor. + + iolog_compress=bool + Set to true if the I/O logging plugins, if any, should + compress the log data. This is a hint to the I/O + logging plugin which may choose to ignore it. + + iolog_group=string + The group that will own newly created I/O log files and + directories. This is a hint to the I/O logging plugin + which may choose to ignore it. + + iolog_mode=octal + The file permission mode to use when creating I/O log + files and directories. This is a hint to the I/O + logging plugin which may choose to ignore it. + + iolog_user=string + The user that will own newly created I/O log files and + directories. This is a hint to the I/O logging plugin + which may choose to ignore it. + + iolog_path=string + Fully qualified path to the file or directory in which + I/O log is to be stored. This is a hint to the I/O + logging plugin which may choose to ignore it. If no + I/O logging plugin is loaded, this setting has no + effect. + + iolog_stdin=bool + Set to true if the I/O logging plugins, if any, should + log the standard input if it is not connected to a + terminal device. This is a hint to the I/O logging + plugin which may choose to ignore it. + + iolog_stdout=bool + Set to true if the I/O logging plugins, if any, should + log the standard output if it is not connected to a + terminal device. This is a hint to the I/O logging + plugin which may choose to ignore it. + + iolog_stderr=bool + Set to true if the I/O logging plugins, if any, should + log the standard error if it is not connected to a + terminal device. This is a hint to the I/O logging + plugin which may choose to ignore it. + + iolog_ttyin=bool + Set to true if the I/O logging plugins, if any, should + log all terminal input. This only includes input typed + by the user and not from a pipe or redirected from a + file. This is a hint to the I/O logging plugin which + may choose to ignore it. + + iolog_ttyout=bool + Set to true if the I/O logging plugins, if any, should + log all terminal output. This only includes output to + the screen, not output to a pipe or file. This is a + hint to the I/O logging plugin which may choose to + ignore it. + + login_class=string + BSD login class to use when setting resource limits and + nice value (optional). This option is only set on + systems that support login classes. + + nice=int + Nice value (priority) to use when executing the + command. The nice value, if specified, overrides the + priority associated with the _l_o_g_i_n___c_l_a_s_s on BSD + systems. + + noexec=bool + If set, prevent the command from executing other + programs. + + preserve_fds=list + A comma-separated list of file descriptors that should + be preserved, regardless of the value of the _c_l_o_s_e_f_r_o_m + setting. Only available starting with API version 1.5. + + preserve_groups=bool + If set, ssuuddoo will preserve the user's group vector + instead of initializing the group vector based on + runas_user. + + runas_egid=gid + Effective group ID to run the command as. If not + specified, the value of _r_u_n_a_s___g_i_d is used. + + runas_euid=uid + Effective user ID to run the command as. If not + specified, the value of _r_u_n_a_s___u_i_d is used. + + runas_gid=gid + Group ID to run the command as. + + runas_groups=list + The supplementary group vector to use for the command + in the form of a comma-separated list of group IDs. If + _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, this option is ignored. + + runas_uid=uid + User ID to run the command as. + + selinux_role=string + SELinux role to use when executing the command. + + selinux_type=string + SELinux type to use when executing the command. + + set_utmp=bool + Create a utmp (or utmpx) entry when a pseudo-tty is + allocated. By default, the new entry will be a copy of + the user's existing utmp entry (if any), with the tty, + time, type and pid fields updated. + + sudoedit=bool + Set to true when in _s_u_d_o_e_d_i_t mode. The plugin may + enable _s_u_d_o_e_d_i_t mode even if ssuuddoo was not invoked as + ssuuddooeeddiitt. This allows the plugin to perform command + substitution and transparently enable _s_u_d_o_e_d_i_t when the + user attempts to run an editor. + + sudoedit_checkdir=bool + Set to false to disable directory writability checks in + ssuuddooeeddiitt. By default, ssuuddooeeddiitt 1.8.16 and higher will + check all directory components of the path to be edited + for writability by the invoking user. Symbolic links + will not be followed in writable directories and + ssuuddooeeddiitt will refuse to edit a file located in a + writable directory. These restrictions are not + enforced when ssuuddooeeddiitt is run by root. The + _s_u_d_o_e_d_i_t___f_o_l_l_o_w option can be set to false to disable + this check. Only available starting with API version + 1.8. + + sudoedit_follow=bool + Set to true to allow ssuuddooeeddiitt to edit files that are + symbolic links. By default, ssuuddooeeddiitt 1.8.15 and higher + will refuse to open a symbolic link. The + _s_u_d_o_e_d_i_t___f_o_l_l_o_w option can be used to restore the older + behavior and allow ssuuddooeeddiitt to open symbolic links. + Only available starting with API version 1.8. + + timeout=int + Command timeout. If non-zero then when the timeout + expires the command will be killed. + + umask=octal + The file creation mask to use when executing the + command. + + use_pty=bool + Allocate a pseudo-tty to run the command in, regardless + of whether or not I/O logging is in use. By default, + ssuuddoo will only run the command in a pty when an I/O log + plugin is loaded. + + utmp_user=string + User name to use when constructing a new utmp (or + utmpx) entry when _s_e_t___u_t_m_p is enabled. This option can + be used to set the user field in the utmp entry to the + user the command runs as rather than the invoking user. + If not set, ssuuddoo will base the new entry on the + invoking user's existing entry. + + Unsupported values will be ignored. + + argv_out + The NULL-terminated argument vector to pass to the execve(2) + system call when executing the command. The plugin is + responsible for allocating and populating the vector. + + user_env_out + The NULL-terminated environment vector to use when executing + the command. The plugin is responsible for allocating and + populating the vector. + + list + int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); + + List available privileges for the invoking user. Returns 1 on + success, 0 on failure and -1 on error. On error, the plugin may + optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function with + SUDO_CONF_ERROR_MSG to present additional error information to the + user. + + Privileges should be output via the ccoonnvveerrssaattiioonn() or + pplluuggiinn__pprriinnttff() function using SUDO_CONV_INFO_MSG, + + verbose + Flag indicating whether to list in verbose mode or not. + + list_user + The name of a different user to list privileges for if the + policy allows it. If NULL, the plugin should list the + privileges of the invoking user. + + argc The number of elements in _a_r_g_v, not counting the final NULL + pointer. + + argv If non-NULL, an argument vector describing a command the user + wishes to check against the policy in the same form as what + would be passed to the execve(2) system call. If the command + is permitted by the policy, the fully-qualified path to the + command should be displayed along with any command line + arguments. + + validate + int (*validate)(void); + + The vvaalliiddaattee() function is called when ssuuddoo is run with the --vv + flag. For policy plugins such as ssuuddooeerrss that cache authentication + credentials, this function will validate and cache the credentials. + + The vvaalliiddaattee() function should be NULL if the plugin does not + support credential caching. + + Returns 1 on success, 0 on failure and -1 on error. On error, the + plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + invalidate + void (*invalidate)(int remove); + + The iinnvvaalliiddaattee() function is called when ssuuddoo is called with the --kk + or --KK flag. For policy plugins such as ssuuddooeerrss that cache + authentication credentials, this function will invalidate the + credentials. If the _r_e_m_o_v_e flag is set, the plugin may remove the + credentials instead of simply invalidating them. + + The iinnvvaalliiddaattee() function should be NULL if the plugin does not + support credential caching. + + init_session + int (*init_session)(struct passwd *pwd, char **user_envp[); + + The iinniitt__sseessssiioonn() function is called before ssuuddoo sets up the + execution environment for the command. It is run in the parent + ssuuddoo process and before any uid or gid changes. This can be used + to perform session setup that is not supported by _c_o_m_m_a_n_d___i_n_f_o, + such as opening the PAM session. The cclloossee() function can be used + to tear down the session that was opened by init_session. + + The _p_w_d argument points to a passwd struct for the user the command + will be run as if the uid the command will run as was found in the + password database, otherwise it will be NULL. + + The _u_s_e_r___e_n_v argument points to the environment the command will + run in, in the form of a NULL-terminated vector of "name=value" + strings. This is the same string passed back to the front end via + the Policy Plugin's _u_s_e_r___e_n_v___o_u_t parameter. If the iinniitt__sseessssiioonn() + function needs to modify the user environment, it should update the + pointer stored in _u_s_e_r___e_n_v. The expected use case is to merge the + contents of the PAM environment (if any) with the contents of + _u_s_e_r___e_n_v. NOTE: the _u_s_e_r___e_n_v parameter is only available starting + with API version 1.2. A plugin mmuusstt check the API version + specified by the ssuuddoo front end before using _u_s_e_r___e_n_v. Failure to + do so may result in a crash. + + Returns 1 on success, 0 on failure and -1 on error. On error, the + plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + register_hooks + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + + The rreeggiisstteerr__hhooookkss() function is called by the sudo front end to + register any hooks the plugin needs. If the plugin does not + support hooks, register_hooks should be set to the NULL pointer. + + The _v_e_r_s_i_o_n argument describes the version of the hooks API + supported by the ssuuddoo front end. + + The rreeggiisstteerr__hhooookk() function should be used to register any + supported hooks the plugin needs. It returns 0 on success, 1 if + the hook type is not supported and -1 if the major version in + struct hook does not match the front end's major hook API version. + + See the _H_o_o_k _f_u_n_c_t_i_o_n _A_P_I section below for more information about + hooks. + + NOTE: the rreeggiisstteerr__hhooookkss() function is only available starting with + API version 1.2. If the ssuuddoo front end doesn't support API version + 1.2 or higher, register_hooks will not be called. + + deregister_hooks + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); + + The ddeerreeggiisstteerr__hhooookkss() function is called by the sudo front end to + deregister any hooks the plugin has registered. If the plugin does + not support hooks, deregister_hooks should be set to the NULL + pointer. + + The _v_e_r_s_i_o_n argument describes the version of the hooks API + supported by the ssuuddoo front end. + + The ddeerreeggiisstteerr__hhooookk() function should be used to deregister any + hooks that were put in place by the rreeggiisstteerr__hhooookk() function. If + the plugin tries to deregister a hook that the front end does not + support, deregister_hook will return an error. + + See the _H_o_o_k _f_u_n_c_t_i_o_n _A_P_I section below for more information about + hooks. + + NOTE: the ddeerreeggiisstteerr__hhooookkss() function is only available starting + with API version 1.2. If the ssuuddoo front end doesn't support API + version 1.2 or higher, deregister_hooks will not be called. + + _P_o_l_i_c_y _P_l_u_g_i_n _V_e_r_s_i_o_n _M_a_c_r_o_s + + /* Plugin API version major/minor. */ + #define SUDO_API_VERSION_MAJOR 1 + #define SUDO_API_VERSION_MINOR 13 + #define SUDO_API_MKVERSION(x, y) ((x << 16) | y) + #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\ + SUDO_API_VERSION_MINOR) + + /* Getters and setters for API version */ + #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) + #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) + #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \ + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \ + } while(0) + #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \ + *(vp) = (*(vp) & 0xffff0000) | (n); \ + } while(0) + + II//OO pplluuggiinn AAPPII + struct io_plugin { + #define SUDO_IO_PLUGIN 2 + unsigned int type; /* always SUDO_IO_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); /* wait status or error */ + int (*show_version)(int verbose); + int (*log_ttyin)(const char *buf, unsigned int len); + int (*log_ttyout)(const char *buf, unsigned int len); + int (*log_stdin)(const char *buf, unsigned int len); + int (*log_stdout)(const char *buf, unsigned int len); + int (*log_stderr)(const char *buf, unsigned int len); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); + int (*change_winsize)(unsigned int lines, unsigned int cols); + int (*log_suspend)(int signo); + }; + + When an I/O plugin is loaded, ssuuddoo runs the command in a pseudo-tty. + This makes it possible to log the input and output from the user's + session. If any of the standard input, standard output or standard error + do not correspond to a tty, ssuuddoo will open a pipe to capture the I/O for + logging before passing it on. + + The log_ttyin function receives the raw user input from the terminal + device (note that this will include input even when echo is disabled, + such as when a password is read). The log_ttyout function receives + output from the pseudo-tty that is suitable for replaying the user's + session at a later time. The lloogg__ssttddiinn(), lloogg__ssttddoouutt() and lloogg__ssttddeerrrr() + functions are only called if the standard input, standard output or + standard error respectively correspond to something other than a tty. + + Any of the logging functions may be set to the NULL pointer if no logging + is to be performed. If the open function returns 0, no I/O will be sent + to the plugin. + + If a logging function returns an error (-1), the running command will be + terminated and all of the plugin's logging functions will be disabled. + Other I/O logging plugins will still receive any remaining input or + output that has not yet been processed. + + If an input logging function rejects the data by returning 0, the command + will be terminated and the data will not be passed to the command, though + it will still be sent to any other I/O logging plugins. If an output + logging function rejects the data by returning 0, the command will be + terminated and the data will not be written to the terminal, though it + will still be sent to any other I/O logging plugins. + + The io_plugin struct has the following fields: + + type The type field should always be set to SUDO_IO_PLUGIN. + + version + The version field should be set to SUDO_API_VERSION. + + This allows ssuuddoo to determine the API version the plugin was built + against. + + open + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); + + The ooppeenn() function is run before the lloogg__ttttyyiinn(), lloogg__ttttyyoouutt(), + lloogg__ssttddiinn(), lloogg__ssttddoouutt(), lloogg__ssttddeerrrr(), lloogg__ssuussppeenndd(), + cchhaannggee__wwiinnssiizzee(), or sshhooww__vveerrssiioonn() functions are called. It is + only called if the version is being requested or if the policy + plugin's cchheecckk__ppoolliiccyy() function has returned successfully. It + returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error. In the latter case, ssuuddoo will + print a usage message before it exits. If an error occurs, the + plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + The function arguments are as follows: + + version + The version passed in by ssuuddoo allows the plugin to determine + the major and minor version number of the plugin API + supported by ssuuddoo. + + conversation + A pointer to the ccoonnvveerrssaattiioonn() function that may be used by + the sshhooww__vveerrssiioonn() function to display version information + (see sshhooww__vveerrssiioonn() below). The ccoonnvveerrssaattiioonn() function may + also be used to display additional error message to the user. + The ccoonnvveerrssaattiioonn() function returns 0 on success and -1 on + failure. + + plugin_printf + A pointer to a pprriinnttff()-style function that may be used by + the sshhooww__vveerrssiioonn() function to display version information + (see show_version below). The pplluuggiinn__pprriinnttff() function may + also be used to display additional error message to the user. + The pplluuggiinn__pprriinnttff() function returns number of characters + printed on success and -1 on failure. + + settings + A vector of user-supplied ssuuddoo settings in the form of + "name=value" strings. The vector is terminated by a NULL + pointer. These settings correspond to flags the user + specified when running ssuuddoo. As such, they will only be + present when the corresponding flag has been specified on the + command line. + + When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a list of all possible + settings. + + user_info + A vector of information about the user running the command in + the form of "name=value" strings. The vector is terminated + by a NULL pointer. + + When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a list of all possible + strings. + + argc The number of elements in _a_r_g_v, not counting the final NULL + pointer. It can be zero, when ssuuddoo is called with --VV. + + argv If non-NULL, an argument vector describing a command the user + wishes to run in the same form as what would be passed to the + execve(2) system call. + + user_env + The user's environment in the form of a NULL-terminated + vector of "name=value" strings. + + When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt + equal sign (`=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + + plugin_options + Any (non-comment) strings immediately after the plugin path + are treated as arguments to the plugin. These arguments are + split on a white space boundary and are passed to the plugin + in the form of a NULL-terminated array of strings. If no + arguments were specified, _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL + pointer. + + NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available starting + with API version 1.2. A plugin mmuusstt check the API version + specified by the ssuuddoo front end before using _p_l_u_g_i_n___o_p_t_i_o_n_s. + Failure to do so may result in a crash. + + close + void (*close)(int exit_status, int error); + + The cclloossee() function is called when the command being run by ssuuddoo + finishes. + + The function arguments are as follows: + + exit_status + The command's exit status, as returned by the wait(2) system + call. The value of exit_status is undefined if error is non- + zero. + + error + If the command could not be executed, this is set to the + value of errno set by the execve(2) system call. If the + command was successfully executed, the value of error is 0. + + show_version + int (*show_version)(int verbose); + + The sshhooww__vveerrssiioonn() function is called by ssuuddoo when the user + specifies the --VV option. The plugin may display its version + information to the user via the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function using SUDO_CONV_INFO_MSG. If the user requests detailed + version information, the verbose flag will be set. + + Returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error, although the return value is + currently ignored. + + log_ttyin + int (*log_ttyin)(const char *buf, unsigned int len); + + The lloogg__ttttyyiinn() function is called whenever data can be read from + the user but before it is passed to the running command. This + allows the plugin to reject data if it chooses to (for instance if + the input contains banned content). Returns 1 if the data should + be passed to the command, 0 if the data is rejected (which will + terminate the running command) or -1 if an error occurred. + + The function arguments are as follows: + + buf The buffer containing user input. + + len The length of _b_u_f in bytes. + + log_ttyout + int (*log_ttyout)(const char *buf, unsigned int len); + + The lloogg__ttttyyoouutt() function is called whenever data can be read from + the command but before it is written to the user's terminal. This + allows the plugin to reject data if it chooses to (for instance if + the output contains banned content). Returns 1 if the data should + be passed to the user, 0 if the data is rejected (which will + terminate the running command) or -1 if an error occurred. + + The function arguments are as follows: + + buf The buffer containing command output. + + len The length of _b_u_f in bytes. + + log_stdin + int (*log_stdin)(const char *buf, unsigned int len); + + The lloogg__ssttddiinn() function is only used if the standard input does + not correspond to a tty device. It is called whenever data can be + read from the standard input but before it is passed to the running + command. This allows the plugin to reject data if it chooses to + (for instance if the input contains banned content). Returns 1 if + the data should be passed to the command, 0 if the data is rejected + (which will terminate the running command) or -1 if an error + occurred. + + The function arguments are as follows: + + buf The buffer containing user input. + + len The length of _b_u_f in bytes. + + log_stdout + int (*log_stdout)(const char *buf, unsigned int len); + + The lloogg__ssttddoouutt() function is only used if the standard output does + not correspond to a tty device. It is called whenever data can be + read from the command but before it is written to the standard + output. This allows the plugin to reject data if it chooses to + (for instance if the output contains banned content). Returns 1 if + the data should be passed to the user, 0 if the data is rejected + (which will terminate the running command) or -1 if an error + occurred. + + The function arguments are as follows: + + buf The buffer containing command output. + + len The length of _b_u_f in bytes. + + log_stderr + int (*log_stderr)(const char *buf, unsigned int len); + + The lloogg__ssttddeerrrr() function is only used if the standard error does + not correspond to a tty device. It is called whenever data can be + read from the command but before it is written to the standard + error. This allows the plugin to reject data if it chooses to (for + instance if the output contains banned content). Returns 1 if the + data should be passed to the user, 0 if the data is rejected (which + will terminate the running command) or -1 if an error occurred. + + The function arguments are as follows: + + buf The buffer containing command output. + + len The length of _b_u_f in bytes. + + register_hooks + See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a description of + register_hooks. + + deregister_hooks + See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a description of + deregister_hooks. + + change_winsize + int (*change_winsize)(unsigned int lines, unsigned int cols); + + The cchhaannggee__wwiinnssiizzee() function is called whenever the window size of + the terminal changes from the initial values specified in the + user_info list. Returns -1 if an error occurred, in which case no + further calls to cchhaannggee__wwiinnssiizzee() will be made, + + log_suspend + int (*log_suspend)(int signo); + + The lloogg__ssuussppeenndd() function is called whenever a command is + suspended or resumed. The _s_i_g_n_o argument is either the signal that + caused the command to be suspended or SIGCONT if the command was + resumed. Logging this information makes it possible to skip the + period of time when the command was suspended during playback of a + session. Returns -1 if an error occurred, in which case no further + calls to lloogg__ssuussppeenndd() will be made, + + _I_/_O _P_l_u_g_i_n _V_e_r_s_i_o_n _M_a_c_r_o_s + + Same as for the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I. + + SSiiggnnaall hhaannddlleerrss + The ssuuddoo front end installs default signal handlers to trap common + signals while the plugin functions are run. The following signals are + trapped by default before the command is executed: + + ++oo SIGALRM + ++oo SIGHUP + ++oo SIGINT + ++oo SIGPIPE + ++oo SIGQUIT + ++oo SIGTERM + ++oo SIGTSTP + ++oo SIGUSR1 + ++oo SIGUSR2 + + If a fatal signal is received before the command is executed, ssuuddoo will + call the plugin's cclloossee() function with an exit status of 128 plus the + value of the signal that was received. This allows for consistent + logging of commands killed by a signal for plugins that log such + information in their cclloossee() function. An exception to this is SIGPIPE, + which is ignored until the command is executed. + + A plugin may temporarily install its own signal handlers but must restore + the original handler before the plugin function returns. + + HHooookk ffuunnccttiioonn AAPPII + Beginning with plugin API version 1.2, it is possible to install hooks + for certain functions called by the ssuuddoo front end. + + Currently, the only supported hooks relate to the handling of environment + variables. Hooks can be used to intercept attempts to get, set, or + remove environment variables so that these changes can be reflected in + the version of the environment that is used to execute a command. A + future version of the API will support hooking internal ssuuddoo front end + functions as well. + + _H_o_o_k _s_t_r_u_c_t_u_r_e + + Hooks in ssuuddoo are described by the following structure: + + typedef int (*sudo_hook_fn_t)(); + + struct sudo_hook { + unsigned int hook_version; + unsigned int hook_type; + sudo_hook_fn_t hook_fn; + void *closure; + }; + + The sudo_hook structure has the following fields: + + hook_version + The hook_version field should be set to SUDO_HOOK_VERSION. + + hook_type + The hook_type field may be one of the following supported hook + types: + + SUDO_HOOK_SETENV + The C library setenv(3) function. Any registered hooks will + run before the C library implementation. The hook_fn field + should be a function that matches the following typedef: + + typedef int (*sudo_hook_fn_setenv_t)(const char *name, + const char *value, int overwrite, void *closure); + + If the registered hook does not match the typedef the results + are unspecified. + + SUDO_HOOK_UNSETENV + The C library unsetenv(3) function. Any registered hooks + will run before the C library implementation. The hook_fn + field should be a function that matches the following + typedef: + + typedef int (*sudo_hook_fn_unsetenv_t)(const char *name, + void *closure); + + SUDO_HOOK_GETENV + The C library getenv(3) function. Any registered hooks will + run before the C library implementation. The hook_fn field + should be a function that matches the following typedef: + + typedef int (*sudo_hook_fn_getenv_t)(const char *name, + char **value, void *closure); + + If the registered hook does not match the typedef the results + are unspecified. + + SUDO_HOOK_PUTENV + The C library putenv(3) function. Any registered hooks will + run before the C library implementation. The hook_fn field + should be a function that matches the following typedef: + + typedef int (*sudo_hook_fn_putenv_t)(char *string, + void *closure); + + If the registered hook does not match the typedef the results + are unspecified. + + hook_fn + sudo_hook_fn_t hook_fn; + + The hook_fn field should be set to the plugin's hook + implementation. The actual function arguments will vary depending + on the hook_type (see hook_type above). In all cases, the closure + field of struct sudo_hook is passed as the last function parameter. + This can be used to pass arbitrary data to the plugin's hook + implementation. + + The function return value may be one of the following: + + SUDO_HOOK_RET_ERROR + The hook function encountered an error. + + SUDO_HOOK_RET_NEXT + The hook completed without error, go on to the next hook + (including the native implementation if applicable). For + example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if + the specified variable was not found in the private copy of + the environment. + + SUDO_HOOK_RET_STOP + The hook completed without error, stop processing hooks for + this invocation. This can be used to replace the native + implementation. For example, a setenv hook that operates on + a private copy of the environment but leaves environ + unchanged. + + Note that it is very easy to create an infinite loop when hooking C + library functions. For example, a getenv(3) hook that calls the + snprintf(3) function may create a loop if the snprintf(3) implementation + calls getenv(3) to check the locale. To prevent this, you may wish to + use a static variable in the hook function to guard against nested calls. + For example: + + static int in_progress = 0; /* avoid recursion */ + if (in_progress) + return SUDO_HOOK_RET_NEXT; + in_progress = 1; + ... + in_progress = 0; + return SUDO_HOOK_RET_STOP; + + _H_o_o_k _A_P_I _V_e_r_s_i_o_n _M_a_c_r_o_s + + /* Hook API version major/minor */ + #define SUDO_HOOK_VERSION_MAJOR 1 + #define SUDO_HOOK_VERSION_MINOR 0 + #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\ + SUDO_HOOK_VERSION_MINOR) + + For getters and setters see the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I. + + RReemmoottee ccoommmmaanndd eexxeeccuuttiioonn + The ssuuddoo front end does not have native support for running remote + commands. However, starting with ssuuddoo 1.8.8, the --hh option may be used + to specify a remote host that is passed to the policy plugin. A plugin + may also accept a _r_u_n_a_s___u_s_e_r in the form of "user@hostname" which will + work with older versions of ssuuddoo. It is anticipated that remote commands + will be supported by executing a "helper" program. The policy plugin + should setup the execution environment such that the ssuuddoo front end will + run the helper which, in turn, will connect to the remote host and run + the command. + + For example, the policy plugin could utilize sssshh to perform remote + command execution. The helper program would be responsible for running + sssshh with the proper options to use a private key or certificate that the + remote host will accept and run a program on the remote host that would + setup the execution environment accordingly. + + Note that remote ssuuddooeeddiitt functionality must be handled by the policy + plugin, not ssuuddoo itself as the front end has no knowledge that a remote + command is being executed. This may be addressed in a future revision of + the plugin API. + + CCoonnvveerrssaattiioonn AAPPII + If the plugin needs to interact with the user, it may do so via the + ccoonnvveerrssaattiioonn() function. A plugin should not attempt to read directly + from the standard input or the user's tty (neither of which are + guaranteed to exist). The caller must include a trailing newline in msg + if one is to be printed. + + A pprriinnttff()-style function is also available that can be used to display + informational or error messages to the user, which is usually more + convenient for simple messages where no use input is required. + + _C_o_n_v_e_r_s_a_t_i_o_n _f_u_n_c_t_i_o_n _s_t_r_u_c_t_u_r_e_s + + The conversation function takes as arguments pointers to the following + structures: + + struct sudo_conv_message { + #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ + #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ + #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ + #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ + #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ + #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ + #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */ + int msg_type; + int timeout; + const char *msg; + }; + + #define SUDO_CONV_REPL_MAX 255 + + struct sudo_conv_reply { + char *reply; + }; + + typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure); + struct sudo_conv_callback { + unsigned int version; + void *closure; + sudo_conv_callback_fn_t on_suspend; + sudo_conv_callback_fn_t on_resume; + }; + + Pointers to the ccoonnvveerrssaattiioonn() and pprriinnttff()-style functions are passed in + to the plugin's ooppeenn() function when the plugin is initialized. The + following type definitions can be used in the declaration of the ooppeenn() + function: + + typedef int (*sudo_conv_t)(int num_msgs, + const struct sudo_conv_message msgs[], + struct sudo_conv_reply replies[], + struct sudo_conv_callback *callback); + + typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); + + To use the ccoonnvveerrssaattiioonn() function, the plugin must pass an array of + sudo_conv_message and sudo_conv_reply structures. There must be a struct + sudo_conv_message and struct sudo_conv_reply for each message in the + conversation, that is, both arrays must have the same number of elements. + Each struct sudo_conv_reply must have its _r_e_p_l_y member initialized to + NULL. The struct sudo_conv_callback pointer, if not NULL, should contain + function pointers to be called when the ssuuddoo process is suspended and/or + resumed during conversation input. The _o_n___s_u_s_p_e_n_d and _o_n___r_e_s_u_m_e + functions are called with the signal that caused ssuuddoo to be suspended and + the _c_l_o_s_u_r_e pointer from the struct sudo_conv_callback. These functions + should return 0 on success and -1 on error. On error, the conversation + will end and the conversation function will return a value of -1. The + intended use is to allow the plugin to release resources, such as locks, + that should not be held indefinitely while suspended and then reacquire + them when the process is resumed. Note that the functions are not + actually invoked from within a signal handler. + + The _m_s_g___t_y_p_e must be set to one of the following values: + + SUDO_CONV_PROMPT_ECHO_OFF + Prompt the user for input with echo disabled; this is generally + used for passwords. The reply will be stored in the _r_e_p_l_i_e_s array, + and it will never be NULL. + + SUDO_CONV_PROMPT_ECHO_ON + Prompt the user for input with echo enabled. The reply will be + stored in the _r_e_p_l_i_e_s array, and it will never be NULL. + + SUDO_CONV_ERROR_MSG + Display an error message. The message is written to the standard + error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it + is written to the user's terminal if possible. + + SUDO_CONV_INFO_MSG + Display a message. The message is written to the standard output + unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is + written to the user's terminal if possible. + + SUDO_CONV_PROMPT_MASK + Prompt the user for input but echo an asterisk character for each + character read. The reply will be stored in the _r_e_p_l_i_e_s array, and + it will never be NULL. This can be used to provide visual feedback + to the user while reading sensitive information that should not be + displayed. + + In addition to the above values, the following flag bits may also be set: + + SUDO_CONV_PROMPT_ECHO_OK + Allow input to be read when echo cannot be disabled when the + message type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK. + By default, ssuuddoo will refuse to read input if the echo cannot be + disabled for those message types. + + SUDO_CONV_PREFER_TTY + When displaying a message via SUDO_CONV_ERROR_MSG or + SUDO_CONV_INFO_MSG, try to write the message to the user's + terminal. If the terminal is unavailable, the standard error or + standard output will be used, depending upon whether The user's + terminal is always used when possible for input, this flag is only + used for output. SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was + used. + + The _t_i_m_e_o_u_t in seconds until the prompt will wait for no more input. A + zero value implies an infinite timeout. + + The plugin is responsible for freeing the reply buffer located in each + struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents + the maximum length of the reply buffer (not including the trailing NUL + character). In practical terms, this is the longest password ssuuddoo will + support. It is also useful as a maximum value for the mmeemmsseett__ss() + function when clearing passwords filled in by the conversation function. + + The pprriinnttff()-style function uses the same underlying mechanism as the + ccoonnvveerrssaattiioonn() function but only supports SUDO_CONV_INFO_MSG and + SUDO_CONV_ERROR_MSG for the _m_s_g___t_y_p_e parameter. It can be more + convenient than using the ccoonnvveerrssaattiioonn() function if no user reply is + needed and supports standard pprriinnttff() escape sequences. + + See the sample plugin for an example of the ccoonnvveerrssaattiioonn() function + usage. + + SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII + The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix + group lookups. This can be used to query a group source other than the + standard Unix group database. Two sample group plugins are bundled with + ssuuddoo, _g_r_o_u_p___f_i_l_e and _s_y_s_t_e_m___g_r_o_u_p, are detailed in sudoers(4). Third + party group plugins include a QAS AD plugin available from Quest + Software. + + A group plugin must declare and populate a sudoers_group_plugin struct in + the global scope. This structure contains pointers to the functions that + implement plugin initialization, cleanup and group lookup. + + struct sudoers_group_plugin { + unsigned int version; + int (*init)(int version, sudo_printf_t sudo_printf, + char *const argv[]); + void (*cleanup)(void); + int (*query)(const char *user, const char *group, + const struct passwd *pwd); + }; + + The sudoers_group_plugin struct has the following fields: + + version + The version field should be set to GROUP_API_VERSION. + + This allows ssuuddooeerrss to determine the API version the group plugin + was built against. + + init + int (*init)(int version, sudo_printf_t plugin_printf, + char *const argv[]); + + The iinniitt() function is called after _s_u_d_o_e_r_s has been parsed but + before any policy checks. It returns 1 on success, 0 on failure + (or if the plugin is not configured), and -1 if a error occurred. + If an error occurs, the plugin may call the pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + The function arguments are as follows: + + version + The version passed in by ssuuddooeerrss allows the plugin to + determine the major and minor version number of the group + plugin API supported by ssuuddooeerrss. + + plugin_printf + A pointer to a pprriinnttff()-style function that may be used to + display informational or error message to the user. Returns + the number of characters printed on success and -1 on + failure. + + argv A NULL-terminated array of arguments generated from the + _g_r_o_u_p___p_l_u_g_i_n option in _s_u_d_o_e_r_s. If no arguments were given, + _a_r_g_v will be NULL. + + cleanup + void (*cleanup)(); + + The cclleeaannuupp() function is called when ssuuddooeerrss has finished its + group checks. The plugin should free any memory it has allocated + and close open file handles. + + query + int (*query)(const char *user, const char *group, + const struct passwd *pwd); + + The qquueerryy() function is used to ask the group plugin whether _u_s_e_r + is a member of _g_r_o_u_p. + + The function arguments are as follows: + + user The name of the user being looked up in the external group + database. + + group + The name of the group being queried. + + pwd The password database entry for _u_s_e_r, if any. If _u_s_e_r is not + present in the password database, _p_w_d will be NULL. + + _G_r_o_u_p _A_P_I _V_e_r_s_i_o_n _M_a_c_r_o_s + + /* Sudoers group plugin version major/minor */ + #define GROUP_API_VERSION_MAJOR 1 + #define GROUP_API_VERSION_MINOR 0 + #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \ + GROUP_API_VERSION_MINOR) + For getters and setters see the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I. + +PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG + The following revisions have been made to the Sudo Plugin API. + + Version 1.0 + Initial API version. + + Version 1.1 (sudo 1.8.0) + The I/O logging plugin's ooppeenn() function was modified to take the + command_info list as an argument. + + Version 1.2 (sudo 1.8.5) + The Policy and I/O logging plugins' ooppeenn() functions are now passed + a list of plugin parameters if any are specified in sudo.conf(4). + + A simple hooks API has been introduced to allow plugins to hook in + to the system's environment handling functions. + + The init_session Policy plugin function is now passed a pointer to + the user environment which can be updated as needed. This can be + used to merge in environment variables stored in the PAM handle + before a command is run. + + Version 1.3 (sudo 1.8.7) + Support for the _e_x_e_c___b_a_c_k_g_r_o_u_n_d entry has been added to the + command_info list. + + The _m_a_x___g_r_o_u_p_s and _p_l_u_g_i_n___d_i_r entries were added to the settings + list. + + The vveerrssiioonn() and cclloossee() functions are now optional. Previously, + a missing vveerrssiioonn() or cclloossee() function would result in a crash. + If no policy plugin cclloossee() function is defined, a default cclloossee() + function will be provided by the ssuuddoo front end that displays a + warning if the command could not be executed. + + The ssuuddoo front end now installs default signal handlers to trap + common signals while the plugin functions are run. + + Version 1.4 (sudo 1.8.8) + The _r_e_m_o_t_e___h_o_s_t entry was added to the settings list. + + Version 1.5 (sudo 1.8.9) + The _p_r_e_s_e_r_v_e___f_d_s entry was added to the command_info list. + + Version 1.6 (sudo 1.8.11) + The behavior when an I/O logging plugin returns an error (-1) has + changed. Previously, the ssuuddoo front end took no action when the + lloogg__ttttyyiinn(), lloogg__ttttyyoouutt(), lloogg__ssttddiinn(), lloogg__ssttddoouutt(), or + lloogg__ssttddeerrrr() function returned an error. + + The behavior when an I/O logging plugin returns 0 has changed. + Previously, output from the command would be displayed to the + terminal even if an output logging function returned 0. + + Version 1.7 (sudo 1.8.12) + The _p_l_u_g_i_n___p_a_t_h entry was added to the settings list. + + The _d_e_b_u_g___f_l_a_g_s entry now starts with a debug file path name and + may occur multiple times if there are multiple plugin-specific + Debug lines in the sudo.conf(4) file. + + Version 1.8 (sudo 1.8.15) + The _s_u_d_o_e_d_i_t___c_h_e_c_k_d_i_r and _s_u_d_o_e_d_i_t___f_o_l_l_o_w entries were added to the + command_info list. The default value of _s_u_d_o_e_d_i_t___c_h_e_c_k_d_i_r was + changed to true in sudo 1.8.16. + + The sudo _c_o_n_v_e_r_s_a_t_i_o_n function now takes a pointer to a struct + sudo_conv_callback as its fourth argument. The sudo_conv_t + definition has been updated to match. The plugin must specify that + it supports plugin API version 1.8 or higher to receive a + conversation function pointer that supports this argument. + + Version 1.9 (sudo 1.8.16) + The _e_x_e_c_f_d entry was added to the command_info list. + + Version 1.10 (sudo 1.8.19) + The _u_m_a_s_k entry was added to the user_info list. The _i_o_l_o_g___g_r_o_u_p, + _i_o_l_o_g___m_o_d_e, and _i_o_l_o_g___u_s_e_r entries were added to the command_info + list. + + Version 1.11 (sudo 1.8.20) + The _t_i_m_e_o_u_t entry was added to the settings list. + + Version 1.12 (sudo 1.8.21) + The change_winsize field was added to the io_plugin struct. + + Version 1.13 (sudo 1.8.26) + The log_suspend field was added to the io_plugin struct. + +SSEEEE AALLSSOO + sudo.conf(4), sudoers(4), sudo(1m) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 October 24, 2018 Sudo 1.8.26 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in new file mode 100644 index 0000000..c336033 --- /dev/null +++ b/doc/sudo_plugin.man.in @@ -0,0 +1,2986 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2009-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "SUDO_PLUGIN" "5" "October 24, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudo_plugin\fR +\- Sudo Plugin API +.SH "DESCRIPTION" +Starting with version 1.8, +\fBsudo\fR +supports a plugin API +for policy and session logging. +Plugins may be compiled as dynamic shared objects (the default on +systems that support them) or compiled statically into the +\fBsudo\fR +binary itself. +By default, the +\fBsudoers\fR +policy plugin and an associated I/O logging plugin are used. +Via the plugin API, +\fBsudo\fR +can be configured to use alternate policy and/or I/O logging plugins +provided by third parties. +The plugins to be used are specified in the +sudo.conf(@mansectform@) +file. +.PP +The API is versioned with a major and minor number. +The minor version number is incremented when additions are made. +The major number is incremented when incompatible changes are made. +A plugin should be check the version passed to it and make sure that the +major version matches. +.PP +The plugin API is defined by the +\fRsudo_plugin.h\fR +header file. +.SS "Policy plugin API" +A policy plugin must declare and populate a +\fRpolicy_plugin\fR +struct in the global scope. +This structure contains pointers to the functions that implement the +\fBsudo\fR +policy checks. +The name of the symbol should be specified in +sudo.conf(@mansectform@) +along with a path to the plugin so that +\fBsudo\fR +can load it. +.nf +.sp +.RS 0n +struct policy_plugin { +#define SUDO_POLICY_PLUGIN 1 + unsigned int type; /* always SUDO_POLICY_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); + int (*show_version)(int verbose); + int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + int (*list)(int argc, char * const argv[], int verbose, + const char *list_user); + int (*validate)(void); + void (*invalidate)(int remove); + int (*init_session)(struct passwd *pwd, char **user_env[]); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +}; +.RE +.fi +.PP +The policy_plugin struct has the following fields: +.TP 6n +type +The +\fRtype\fR +field should always be set to SUDO_POLICY_PLUGIN. +.TP 6n +version +The +\fRversion\fR +field should be set to +\fRSUDO_API_VERSION\fR. +.sp +This allows +\fBsudo\fR +to determine the API version the plugin was +built against. +.TP 6n +open +.nf +.RS 6n +int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); +.RE +.fi +.RS 6n +.sp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +\fBsudo\fR +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional error information to the user. +.sp +The function arguments are as follows: +.TP 6n +version +The version passed in by +\fBsudo\fR +allows the plugin to determine the +major and minor version number of the plugin API supported by +\fBsudo\fR. +.TP 6n +conversation +A pointer to the +\fBconversation\fR() +function that can be used by the plugin to interact with the user (see below). +Returns 0 on success and \-1 on failure. +.TP 6n +plugin_printf +A pointer to a +\fBprintf\fR()-style +function that may be used to display informational or error messages +(see below). +Returns the number of characters printed on success and \-1 on failure. +.TP 6n +settings +A vector of user-supplied +\fBsudo\fR +settings in the form of +\(lqname=value\(rq +strings. +The vector is terminated by a +\fRNULL\fR +pointer. +These settings correspond to flags the user specified when running +\fBsudo\fR. +As such, they will only be present when the corresponding flag has +been specified on the command line. +.sp +When parsing +\fIsettings\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.PP +.RS 6n +.PD 0 +.TP 6n +bsdauth_type=string +Authentication type, if specified by the +\fB\-a\fR +flag, to use on +systems where +BSD +authentication is supported. +.PD +.TP 6n +closefrom=number +If specified, the user has requested via the +\fB\-C\fR +flag that +\fBsudo\fR +close all files descriptors with a value of +\fInumber\fR +or higher. +The plugin may optionally pass this, or another value, back in the +\fIcommand_info\fR +list. +.TP 6n +debug_flags=string +A debug file path name followed by a space and a comma-separated +list of debug flags that correspond to the plugin's +\fRDebug\fR +entry in +sudo.conf(@mansectform@), +if there is one. +The flags are passed to the plugin exactly as they appear in +sudo.conf(@mansectform@). +The syntax used by +\fBsudo\fR +and the +\fBsudoers\fR +plugin is +\fIsubsystem\fR@\fIpriority\fR +but a plugin is free to use a different +format so long as it does not include a comma +(\(oq,\&\(cq). +Prior to +\fBsudo\fR +1.8.12, there was no way to specify plugin-specific +\fIdebug_flags\fR +so the value was always the same as that used by the +\fBsudo\fR +front end and did not include a path name, only the flags themselves. +As of version 1.7 of the plugin interface, +\fBsudo\fR +will only pass +\fIdebug_flags\fR +if +sudo.conf(@mansectform@) +contains a plugin-specific +\fRDebug\fR +entry. +.TP 6n +debug_level=number +This setting has been deprecated in favor of +\fIdebug_flags\fR. +.TP 6n +ignore_ticket=bool +Set to true if the user specified the +\fB\-k\fR +flag along with a +command, indicating that the user wishes to ignore any cached +authentication credentials. +\fIimplied_shell\fR +to true. +This allows +\fBsudo\fR +with no arguments +to be used similarly to +su(1). +If the plugin does not to support this usage, it may return a value of \-2 +from the +\fBcheck_policy\fR() +function, which will cause +\fBsudo\fR +to print a usage message and +exit. +.TP 6n +implied_shell=bool +If the user does not specify a program on the command line, +\fBsudo\fR +will pass the plugin the path to the user's shell and set +.TP 6n +login_class=string +BSD +login class to use when setting resource limits and nice value, +if specified by the +\fB\-c\fR +flag. +.TP 6n +login_shell=bool +Set to true if the user specified the +\fB\-i\fR +flag, indicating that +the user wishes to run a login shell. +.TP 6n +max_groups=int +The maximum number of groups a user may belong to. +This will only be present if there is a corresponding setting in +sudo.conf(@mansectform@). +.TP 6n +network_addrs=list +A space-separated list of IP network addresses and netmasks in the +form +\(lqaddr/netmask\(rq, +e.g., +\(lq192.168.1.2/255.255.255.0\(rq. +The address and netmask pairs may be either IPv4 or IPv6, depending on +what the operating system supports. +If the address contains a colon +(\(oq:\&\(cq), +it is an IPv6 address, else it is IPv4. +.TP 6n +noninteractive=bool +Set to true if the user specified the +\fB\-n\fR +flag, indicating that +\fBsudo\fR +should operate in non-interactive mode. +The plugin may reject a command run in non-interactive mode if user +interaction is required. +.TP 6n +plugin_dir=string +The default plugin directory used by the +\fBsudo\fR +front end. +This is the default directory set at compile time and may not +correspond to the directory the running plugin was loaded from. +It may be used by a plugin to locate support files. +.TP 6n +plugin_path=string +The path name of plugin loaded by the +\fBsudo\fR +front end. +The path name will be a fully-qualified unless the plugin was +statically compiled into +\fBsudo\fR. +.TP 6n +preserve_environment=bool +Set to true if the user specified the +\fB\-E\fR +flag, indicating that +the user wishes to preserve the environment. +.TP 6n +preserve_groups=bool +Set to true if the user specified the +\fB\-P\fR +flag, indicating that +the user wishes to preserve the group vector instead of setting it +based on the runas user. +.TP 6n +progname=string +The command name that sudo was run as, typically +\(lqsudo\(rq +or +\(lqsudoedit\(rq. +.TP 6n +prompt=string +The prompt to use when requesting a password, if specified via +the +\fB\-p\fR +flag. +.TP 6n +remote_host=string +The name of the remote host to run the command on, if specified via +the +\fB\-h\fR +option. +Support for running the command on a remote host is meant to be implemented +via a helper program that is executed in place of the user-specified command. +The +\fBsudo\fR +front end is only capable of executing commands on the local host. +Only available starting with API version 1.4. +.TP 6n +run_shell=bool +Set to true if the user specified the +\fB\-s\fR +flag, indicating that the user wishes to run a shell. +.TP 6n +runas_group=string +The group name or gid to run the command as, if specified via +the +\fB\-g\fR +flag. +.TP 6n +runas_user=string +The user name or uid to run the command as, if specified via the +\fB\-u\fR +flag. +.TP 6n +selinux_role=string +SELinux role to use when executing the command, if specified by +the +\fB\-r\fR +flag. +.TP 6n +selinux_type=string +SELinux type to use when executing the command, if specified by +the +\fB\-t\fR +flag. +.TP 6n +set_home=bool +Set to true if the user specified the +\fB\-H\fR +flag. +If true, set the +\fRHOME\fR +environment variable to the target user's home directory. +.TP 6n +sudoedit=bool +Set to true when the +\fB\-e\fR +flag is specified or if invoked as +\fBsudoedit\fR. +The plugin shall substitute an editor into +\fIargv\fR +in the +\fBcheck_policy\fR() +function or return \-2 with a usage error +if the plugin does not support +\fIsudoedit\fR. +For more information, see the +\fIcheck_policy\fR +section. +.TP 6n +timeout=string +User-specified command timeout. +Not all plugins support command timeouts and the ability for the +user to set a timeout may be restricted by policy. +The format of the timeout string is plugin-specific. +.PP +Additional settings may be added in the future so the plugin should +silently ignore settings that it does not recognize. +.RE +.TP 6n +user_info +A vector of information about the user running the command in the form of +\(lqname=value\(rq +strings. +The vector is terminated by a +\fRNULL\fR +pointer. +.sp +When parsing +\fIuser_info\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.PP +.RS 6n +.PD 0 +.TP 6n +cols=int +The number of columns the user's terminal supports. +If there is no terminal device available, a default value of 80 is used. +.PD +.TP 6n +cwd=string +The user's current working directory. +.TP 6n +egid=gid_t +The effective group ID of the user invoking +\fBsudo\fR. +.TP 6n +euid=uid_t +The effective user ID of the user invoking +\fBsudo\fR. +.TP 6n +gid=gid_t +The real group ID of the user invoking +\fBsudo\fR. +.TP 6n +groups=list +The user's supplementary group list formatted as a string of +comma-separated group IDs. +.TP 6n +host=string +The local machine's hostname as returned by the +gethostname(2) +system call. +.TP 6n +lines=int +The number of lines the user's terminal supports. +If there is +no terminal device available, a default value of 24 is used. +.TP 6n +pgid=int +The ID of the process group that the running +\fBsudo\fR +process is a member of. +Only available starting with API version 1.2. +.TP 6n +pid=int +The process ID of the running +\fBsudo\fR +process. +Only available starting with API version 1.2. +.TP 6n +plugin_options +Any (non-comment) strings immediately after the plugin path are +passed as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +\fRNULL\fR-terminated +array of strings. +If no arguments were +specified, +\fIplugin_options\fR +will be the +\fRNULL\fR +pointer. +.sp +NOTE: the +\fIplugin_options\fR +parameter is only available starting with +API version 1.2. +A plugin +\fBmust\fR +check the API version specified +by the +\fBsudo\fR +front end before using +\fIplugin_options\fR. +Failure to do so may result in a crash. +.TP 6n +ppid=int +The parent process ID of the running +\fBsudo\fR +process. +Only available starting with API version 1.2. +.TP 6n +sid=int +The session ID of the running +\fBsudo\fR +process or 0 if +\fBsudo\fR +is not part of a POSIX job control session. +Only available starting with API version 1.2. +.TP 6n +tcpgid=int +The ID of the foreground process group associated with the terminal +device associated with the +\fBsudo\fR +process or \-1 if there is no +terminal present. +Only available starting with API version 1.2. +.TP 6n +tty=string +The path to the user's terminal device. +If the user has no terminal device associated with the session, +the value will be empty, as in +\(lq\fRtty=\fR\(rq. +.TP 6n +uid=uid_t +The real user ID of the user invoking +\fBsudo\fR. +.TP 6n +umask=octal +The invoking user's file creation mask. +Only available starting with API version 1.10. +.TP 6n +user=string +The name of the user invoking +\fBsudo\fR. +.PD 0 +.PP +.RE +.PD +.TP 6n +user_env +The user's environment in the form of a +\fRNULL\fR-terminated vector of +\(lqname=value\(rq +strings. +.sp +When parsing +\fIuser_env\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.PD 0 +.PP +.RE +.PD +.TP 6n +close +.br +.nf +.RS 6n +void (*close)(int exit_status, int error); +.RE +.fi +.RS 6n +.sp +The +\fBclose\fR() +function is called when the command being run by +\fBsudo\fR +finishes. +.sp +The function arguments are as follows: +.TP 6n +exit_status +The command's exit status, as returned by the +wait(2) +system call. +The value of +\fRexit_status\fR +is undefined if +\fRerror\fR +is non-zero. +.TP 6n +error +.br +If the command could not be executed, this is set to the value of +\fRerrno\fR +set by the +execve(2) +system call. +The plugin is responsible for displaying error information via the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function. +If the command was successfully executed, the value of +\fRerror\fR +is 0. +.PP +If no +\fBclose\fR() +function is defined, no I/O logging plugins are loaded, +and neither the +\fItimeout\fR +not +\fIuse_pty\fR +options are set in the +\fRcommand_info\fR +list, the +\fBsudo\fR +front end may execute the command directly instead of running +it as a child process. +.RE +.TP 6n +show_version +.nf +.RS 6n +int (*show_version)(int verbose); +.RE +.fi +.RS 6n +.sp +The +\fBshow_version\fR() +function is called by +\fBsudo\fR +when the user specifies +the +\fB\-V\fR +option. +The plugin may display its version information to the user via the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function using +\fRSUDO_CONV_INFO_MSG\fR. +If the user requests detailed version information, the verbose flag will be set. +.sp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. +.RE +.TP 6n +check_policy +.nf +.RS 6n +int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); +.RE +.fi +.RS 6n +.sp +The +\fBcheck_policy\fR() +function is called by +\fBsudo\fR +to determine +whether the user is allowed to run the specified commands. +.sp +If the +\fIsudoedit\fR +option was enabled in the +\fIsettings\fR +array +passed to the +\fBopen\fR() +function, the user has requested +\fIsudoedit\fR +mode. +\fIsudoedit\fR +is a mechanism for editing one or more files +where an editor is run with the user's credentials instead of with +elevated privileges. +\fBsudo\fR +achieves this by creating user-writable +temporary copies of the files to be edited and then overwriting the +originals with the temporary copies after editing is complete. +If the plugin supports +\fIsudoedit\fR, +it should choose the editor to be used, potentially from a variable +in the user's environment, such as +\fREDITOR\fR, +and include it in +\fIargv_out\fR +(note that environment +variables may include command line flags). +The files to be edited should be copied from +\fIargv\fR +into +\fIargv_out\fR, +separated from the +editor and its arguments by a +\(lq\fR--\fR\(rq +element. +The +\(lq\fR--\fR\(rq +will +be removed by +\fBsudo\fR +before the editor is executed. +The plugin should also set +\fIsudoedit=true\fR +in the +\fIcommand_info\fR +list. +.sp +The +\fBcheck_policy\fR() +function returns 1 if the command is allowed, +0 if not allowed, \-1 for a general error, or \-2 for a usage error +or if +\fIsudoedit\fR +was specified but is unsupported by the plugin. +In the latter case, +\fBsudo\fR +will print a usage message before it +exits. +If an error occurs, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional error information to the user. +.sp +The function arguments are as follows: +.TP 6n +argc +The number of elements in +\fIargv\fR, +not counting the final +\fRNULL\fR +pointer. +.TP 6n +argv +The argument vector describing the command the user wishes to run, +in the same form as what would be passed to the +execve(2) +system call. +The vector is terminated by a +\fRNULL\fR +pointer. +.TP 6n +env_add +Additional environment variables specified by the user on the command +line in the form of a +\fRNULL\fR-terminated +vector of +\(lqname=value\(rq +strings. +The plugin may reject the command if one or more variables +are not allowed to be set, or it may silently ignore such variables. +.sp +When parsing +\fIenv_add\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.TP 6n +command_info +Information about the command being run in the form of +\(lqname=value\(rq +strings. +These values are used by +\fBsudo\fR +to set the execution +environment when running a command. +The plugin is responsible for creating and populating the vector, +which must be terminated with a +\fRNULL\fR +pointer. +The following values are recognized by +\fBsudo\fR: +.PP +.RS 6n +.PD 0 +.TP 6n +chroot=string +The root directory to use when running the command. +.PD +.TP 6n +closefrom=number +If specified, +\fBsudo\fR +will close all files descriptors with a value +of +\fInumber\fR +or higher. +.TP 6n +command=string +Fully qualified path to the command to be executed. +.TP 6n +cwd=string +The current working directory to change to when executing the command. +.TP 6n +exec_background=bool +By default, +\fBsudo\fR +runs a command as the foreground process as long as +\fBsudo\fR +itself is running in the foreground. +When +\fIexec_background\fR +is enabled and the command is being run in a pty (due to I/O logging +or the +\fIuse_pty\fR +setting), the command will be run as a background process. +Attempts to read from the controlling terminal (or to change terminal +settings) will result in the command being suspended with the +\fRSIGTTIN\fR +signal (or +\fRSIGTTOU\fR +in the case of terminal settings). +If this happens when +\fBsudo\fR +is a foreground process, the command will be granted the controlling terminal +and resumed in the foreground with no user intervention required. +The advantage of initially running the command in the background is that +\fBsudo\fR +need not read from the terminal unless the command explicitly requests it. +Otherwise, any terminal input must be passed to the command, whether it +has required it or not (the kernel buffers terminals so it is not possible +to tell whether the command really wants the input). +This is different from historic +\fIsudo\fR +behavior or when the command is not being run in a pty. +.sp +For this to work seamlessly, the operating system must support the +automatic restarting of system calls. +Unfortunately, not all operating systems do this by default, +and even those that do may have bugs. +For example, macOS fails to restart the +\fBtcgetattr\fR() +and +\fBtcsetattr\fR() +system calls (this is a bug in macOS). +Furthermore, because this behavior depends on the command stopping with the +\fRSIGTTIN\fR +or +\fRSIGTTOU\fR +signals, programs that catch these signals and suspend themselves +with a different signal (usually +\fRSIGTOP\fR) +will not be automatically foregrounded. +Some versions of the linux +su(1) +command behave this way. +Because of this, a plugin should not set +\fIexec_background\fR +unless it is explicitly enabled by the administrator and there should +be a way to enabled or disable it on a per-command basis. +.sp +This setting has no effect unless I/O logging is enabled or +\fIuse_pty\fR +is enabled. +.TP 6n +execfd=number +If specified, +\fBsudo\fR +will use the +fexecve(2) +system call to execute the command instead of +execve(2). +The specified +\fInumber\fR +must refer to an open file descriptor. +.TP 6n +iolog_compress=bool +Set to true if the I/O logging plugins, if any, should compress the +log data. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_group=string +The group that will own newly created I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_mode=octal +The file permission mode to use when creating I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_user=string +The user that will own newly created I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_path=string +Fully qualified path to the file or directory in which I/O log is +to be stored. +This is a hint to the I/O logging plugin which may choose to ignore it. +If no I/O logging plugin is loaded, this setting has no effect. +.TP 6n +iolog_stdin=bool +Set to true if the I/O logging plugins, if any, should log the +standard input if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_stdout=bool +Set to true if the I/O logging plugins, if any, should log the +standard output if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_stderr=bool +Set to true if the I/O logging plugins, if any, should log the +standard error if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_ttyin=bool +Set to true if the I/O logging plugins, if any, should log all +terminal input. +This only includes input typed by the user and not from a pipe or +redirected from a file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +iolog_ttyout=bool +Set to true if the I/O logging plugins, if any, should log all +terminal output. +This only includes output to the screen, not output to a pipe or file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.TP 6n +login_class=string +BSD +login class to use when setting resource limits and nice value (optional). +This option is only set on systems that support login classes. +.TP 6n +nice=int +Nice value (priority) to use when executing the command. +The nice value, if specified, overrides the priority associated with the +\fIlogin_class\fR +on +BSD +systems. +.TP 6n +noexec=bool +If set, prevent the command from executing other programs. +.TP 6n +preserve_fds=list +A comma-separated list of file descriptors that should be +preserved, regardless of the value of the +\fIclosefrom\fR +setting. +Only available starting with API version 1.5. +.TP 6n +preserve_groups=bool +If set, +\fBsudo\fR +will preserve the user's group vector instead of +initializing the group vector based on +\fRrunas_user\fR. +.TP 6n +runas_egid=gid +Effective group ID to run the command as. +If not specified, the value of +\fIrunas_gid\fR +is used. +.TP 6n +runas_euid=uid +Effective user ID to run the command as. +If not specified, the value of +\fIrunas_uid\fR +is used. +.TP 6n +runas_gid=gid +Group ID to run the command as. +.TP 6n +runas_groups=list +The supplementary group vector to use for the command in the form +of a comma-separated list of group IDs. +If +\fIpreserve_groups\fR +is set, this option is ignored. +.TP 6n +runas_uid=uid +User ID to run the command as. +.TP 6n +selinux_role=string +SELinux role to use when executing the command. +.TP 6n +selinux_type=string +SELinux type to use when executing the command. +.TP 6n +set_utmp=bool +Create a utmp (or utmpx) entry when a pseudo-tty is allocated. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +.TP 6n +sudoedit=bool +Set to true when in +\fIsudoedit\fR +mode. +The plugin may enable +\fIsudoedit\fR +mode even if +\fBsudo\fR +was not invoked as +\fBsudoedit\fR. +This allows the plugin to perform command substitution and transparently +enable +\fIsudoedit\fR +when the user attempts to run an editor. +.TP 6n +sudoedit_checkdir=bool +Set to false to disable directory writability checks in +\fBsudoedit\fR. +By default, +\fBsudoedit\fR +1.8.16 and higher will check all directory components of the path to be +edited for writability by the invoking user. +Symbolic links will not be followed in writable directories and +\fBsudoedit\fR +will refuse to edit a file located in a writable directory. +These restrictions are not enforced when +\fBsudoedit\fR +is run by root. +The +\fIsudoedit_follow\fR +option can be set to false to disable this check. +Only available starting with API version 1.8. +.TP 6n +sudoedit_follow=bool +Set to true to allow +\fBsudoedit\fR +to edit files that are symbolic links. +By default, +\fBsudoedit\fR +1.8.15 and higher will refuse to open a symbolic link. +The +\fIsudoedit_follow\fR +option can be used to restore the older behavior and allow +\fBsudoedit\fR +to open symbolic links. +Only available starting with API version 1.8. +.TP 6n +timeout=int +Command timeout. +If non-zero then when the timeout expires the command will be killed. +.TP 6n +umask=octal +The file creation mask to use when executing the command. +.TP 6n +use_pty=bool +Allocate a pseudo-tty to run the command in, regardless of whether +or not I/O logging is in use. +By default, +\fBsudo\fR +will only run +the command in a pty when an I/O log plugin is loaded. +.TP 6n +utmp_user=string +User name to use when constructing a new utmp (or utmpx) entry when +\fIset_utmp\fR +is enabled. +This option can be used to set the user field in the utmp entry to +the user the command runs as rather than the invoking user. +If not set, +\fBsudo\fR +will base the new entry on +the invoking user's existing entry. +.PP +Unsupported values will be ignored. +.RE +.TP 6n +argv_out +The +\fRNULL\fR-terminated +argument vector to pass to the +execve(2) +system call when executing the command. +The plugin is responsible for allocating and populating the vector. +.TP 6n +user_env_out +The +\fRNULL\fR-terminated +environment vector to use when executing the command. +The plugin is responsible for allocating and populating the vector. +.PD 0 +.PP +.RE +.PD +.TP 6n +list +.nf +.RS 6n +int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); +.RE +.fi +.RS 6n +.sp +List available privileges for the invoking user. +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional error information to +the user. +.sp +Privileges should be output via the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function using +\fRSUDO_CONV_INFO_MSG\fR, +.TP 6n +verbose +Flag indicating whether to list in verbose mode or not. +.TP 6n +list_user +The name of a different user to list privileges for if the policy +allows it. +If +\fRNULL\fR, +the plugin should list the privileges of the invoking user. +.TP 6n +argc +The number of elements in +\fIargv\fR, +not counting the final +\fRNULL\fR +pointer. +.TP 6n +argv +If +non-\fRNULL\fR, +an argument vector describing a command the user +wishes to check against the policy in the same form as what would +be passed to the +execve(2) +system call. +If the command is permitted by the policy, the fully-qualified path +to the command should be displayed along with any command line arguments. +.PD 0 +.PP +.RE +.PD +.TP 6n +validate +.nf +.RS 6n +int (*validate)(void); +.RE +.fi +.RS 6n +.sp +The +\fBvalidate\fR() +function is called when +\fBsudo\fR +is run with the +\fB\-v\fR +flag. +For policy plugins such as +\fBsudoers\fR +that cache +authentication credentials, this function will validate and cache +the credentials. +.sp +The +\fBvalidate\fR() +function should be +\fRNULL\fR +if the plugin does not support credential caching. +.sp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional +error information to the user. +.RE +.TP 6n +invalidate +.nf +.RS 6n +void (*invalidate)(int remove); +.RE +.fi +.RS 6n +.sp +The +\fBinvalidate\fR() +function is called when +\fBsudo\fR +is called with +the +\fB\-k\fR +or +\fB\-K\fR +flag. +For policy plugins such as +\fBsudoers\fR +that +cache authentication credentials, this function will invalidate the +credentials. +If the +\fIremove\fR +flag is set, the plugin may remove +the credentials instead of simply invalidating them. +.sp +The +\fBinvalidate\fR() +function should be +\fRNULL\fR +if the plugin does not support credential caching. +.RE +.TP 6n +init_session +.nf +.RS 6n +int (*init_session)(struct passwd *pwd, char **user_envp[); +.RE +.fi +.RS 6n +.sp +The +\fBinit_session\fR() +function is called before +\fBsudo\fR +sets up the +execution environment for the command. +It is run in the parent +\fBsudo\fR +process and before any uid or gid changes. +This can be used to perform session setup that is not supported by +\fIcommand_info\fR, +such as opening the PAM session. +The +\fBclose\fR() +function can be +used to tear down the session that was opened by +\fRinit_session\fR. +.sp +The +\fIpwd\fR +argument points to a passwd struct for the user the +command will be run as if the uid the command will run as was found +in the password database, otherwise it will be +\fRNULL\fR. +.sp +The +\fIuser_env\fR +argument points to the environment the command will +run in, in the form of a +\fRNULL\fR-terminated +vector of +\(lqname=value\(rq +strings. +This is the same string passed back to the front end via +the Policy Plugin's +\fIuser_env_out\fR +parameter. +If the +\fBinit_session\fR() +function needs to modify the user environment, it should update the +pointer stored in +\fIuser_env\fR. +The expected use case is to merge the contents of the PAM environment +(if any) with the contents of +\fIuser_env\fR. +NOTE: the +\fIuser_env\fR +parameter is only available +starting with API version 1.2. +A plugin +\fBmust\fR +check the API +version specified by the +\fBsudo\fR +front end before using +\fIuser_env\fR. +Failure to do so may result in a crash. +.sp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional +error information to the user. +.RE +.TP 6n +register_hooks +.nf +.RS 6n +void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); +.RE +.fi +.RS 6n +.sp +The +\fBregister_hooks\fR() +function is called by the sudo front end to +register any hooks the plugin needs. +If the plugin does not support hooks, +\fRregister_hooks\fR +should be set to the +\fRNULL\fR +pointer. +.sp +The +\fIversion\fR +argument describes the version of the hooks API +supported by the +\fBsudo\fR +front end. +.sp +The +\fBregister_hook\fR() +function should be used to register any supported +hooks the plugin needs. +It returns 0 on success, 1 if the hook type is not supported and \-1 +if the major version in +\fRstruct hook\fR +does not match the front end's major hook API version. +.sp +See the +\fIHook function API\fR +section below for more information +about hooks. +.sp +NOTE: the +\fBregister_hooks\fR() +function is only available starting +with API version 1.2. +If the +\fBsudo\fR +front end doesn't support API +version 1.2 or higher, +\fRregister_hooks\fR +will not be called. +.RE +.TP 6n +deregister_hooks +.nf +.RS 6n +void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +.RE +.fi +.RS 6n +.sp +The +\fBderegister_hooks\fR() +function is called by the sudo front end +to deregister any hooks the plugin has registered. +If the plugin does not support hooks, +\fRderegister_hooks\fR +should be set to the +\fRNULL\fR +pointer. +.sp +The +\fIversion\fR +argument describes the version of the hooks API +supported by the +\fBsudo\fR +front end. +.sp +The +\fBderegister_hook\fR() +function should be used to deregister any +hooks that were put in place by the +\fBregister_hook\fR() +function. +If the plugin tries to deregister a hook that the front end does not support, +\fRderegister_hook\fR +will return an error. +.sp +See the +\fIHook function API\fR +section below for more information +about hooks. +.sp +NOTE: the +\fBderegister_hooks\fR() +function is only available starting +with API version 1.2. +If the +\fBsudo\fR +front end doesn't support API +version 1.2 or higher, +\fRderegister_hooks\fR +will not be called. +.RE +.PP +\fIPolicy Plugin Version Macros\fR +.nf +.sp +.RS 0n +/* Plugin API version major/minor. */ +#define SUDO_API_VERSION_MAJOR 1 +#define SUDO_API_VERSION_MINOR 13 +#define SUDO_API_MKVERSION(x, y) ((x << 16) | y) +#define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e + SUDO_API_VERSION_MINOR) + +/* Getters and setters for API version */ +#define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) +#define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) +#define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e +} while(0) +#define SUDO_API_VERSION_SET_MINOR(vp, n) do { \e + *(vp) = (*(vp) & 0xffff0000) | (n); \e +} while(0) +.RE +.fi +.SS "I/O plugin API" +.nf +.RS 0n +struct io_plugin { +#define SUDO_IO_PLUGIN 2 + unsigned int type; /* always SUDO_IO_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); /* wait status or error */ + int (*show_version)(int verbose); + int (*log_ttyin)(const char *buf, unsigned int len); + int (*log_ttyout)(const char *buf, unsigned int len); + int (*log_stdin)(const char *buf, unsigned int len); + int (*log_stdout)(const char *buf, unsigned int len); + int (*log_stderr)(const char *buf, unsigned int len); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); + int (*change_winsize)(unsigned int lines, unsigned int cols); + int (*log_suspend)(int signo); +}; +.RE +.fi +.PP +When an I/O plugin is loaded, +\fBsudo\fR +runs the command in a pseudo-tty. +This makes it possible to log the input and output from the user's +session. +If any of the standard input, standard output or standard error do not +correspond to a tty, +\fBsudo\fR +will open a pipe to capture +the I/O for logging before passing it on. +.PP +The log_ttyin function receives the raw user input from the terminal +device (note that this will include input even when echo is disabled, +such as when a password is read). +The log_ttyout function receives output from the pseudo-tty that is +suitable for replaying the user's session at a later time. +The +\fBlog_stdin\fR(), +\fBlog_stdout\fR() +and +\fBlog_stderr\fR() +functions are only called if the standard input, standard output +or standard error respectively correspond to something other than +a tty. +.PP +Any of the logging functions may be set to the +\fRNULL\fR +pointer if no logging is to be performed. +If the open function returns 0, no I/O will be sent to the plugin. +.PP +If a logging function returns an error +(\-1), +the running command will be terminated and all of the plugin's logging +functions will be disabled. +Other I/O logging plugins will still receive any remaining +input or output that has not yet been processed. +.PP +If an input logging function rejects the data by returning 0, the +command will be terminated and the data will not be passed to the +command, though it will still be sent to any other I/O logging plugins. +If an output logging function rejects the data by returning 0, the +command will be terminated and the data will not be written to the +terminal, though it will still be sent to any other I/O logging plugins. +.PP +The io_plugin struct has the following fields: +.TP 6n +type +The +\fRtype\fR +field should always be set to +\fRSUDO_IO_PLUGIN\fR. +.TP 6n +version +The +\fRversion\fR +field should be set to +\fRSUDO_API_VERSION\fR. +.sp +This allows +\fBsudo\fR +to determine the API version the plugin was +built against. +.TP 6n +open +.nf +.RS 6n +int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); +.RE +.fi +.RS 6n +.sp +The +\fBopen\fR() +function is run before the +\fBlog_ttyin\fR(), +\fBlog_ttyout\fR(), +\fBlog_stdin\fR(), +\fBlog_stdout\fR(), +\fBlog_stderr\fR(), +\fBlog_suspend\fR(), +\fBchange_winsize\fR(), +or +\fBshow_version\fR() +functions are called. +It is only called if the version is being requested or if the +policy plugin's +\fBcheck_policy\fR() +function has returned successfully. +It returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +\fBsudo\fR +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present +additional error information to the user. +.sp +The function arguments are as follows: +.TP 6n +version +The version passed in by +\fBsudo\fR +allows the plugin to determine the +major and minor version number of the plugin API supported by +\fBsudo\fR. +.TP 6n +conversation +A pointer to the +\fBconversation\fR() +function that may be used by the +\fBshow_version\fR() +function to display version information (see +\fBshow_version\fR() +below). +The +\fBconversation\fR() +function may also be used to display additional error message to the user. +The +\fBconversation\fR() +function returns 0 on success and \-1 on failure. +.TP 6n +plugin_printf +A pointer to a +\fBprintf\fR()-style +function that may be used by the +\fBshow_version\fR() +function to display version information (see +show_version below). +The +\fBplugin_printf\fR() +function may also be used to display additional error message to the user. +The +\fBplugin_printf\fR() +function returns number of characters printed on success and \-1 on failure. +.TP 6n +settings +A vector of user-supplied +\fBsudo\fR +settings in the form of +\(lqname=value\(rq +strings. +The vector is terminated by a +\fRNULL\fR +pointer. +These settings correspond to flags the user specified when running +\fBsudo\fR. +As such, they will only be present when the corresponding flag has +been specified on the command line. +.sp +When parsing +\fIsettings\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.sp +See the +\fIPolicy plugin API\fR +section for a list of all possible settings. +.TP 6n +user_info +A vector of information about the user running the command in the form of +\(lqname=value\(rq +strings. +The vector is terminated by a +\fRNULL\fR +pointer. +.sp +When parsing +\fIuser_info\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.sp +See the +\fIPolicy plugin API\fR +section for a list of all possible strings. +.TP 6n +argc +The number of elements in +\fIargv\fR, +not counting the final +\fRNULL\fR +pointer. +It can be zero, when +\fBsudo\fR +is called with +\fB\-V\fR. +.TP 6n +argv +If +non-\fRNULL\fR, +an argument vector describing a command the user +wishes to run in the same form as what would be passed to the +execve(2) +system call. +.TP 6n +user_env +The user's environment in the form of a +\fRNULL\fR-terminated +vector of +\(lqname=value\(rq +strings. +.sp +When parsing +\fIuser_env\fR, +the plugin should split on the +\fBfirst\fR +equal sign +(\(oq=\(cq) +since the +\fIname\fR +field will never include one +itself but the +\fIvalue\fR +might. +.TP 6n +plugin_options +Any (non-comment) strings immediately after the plugin path are +treated as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +\fRNULL\fR-terminated +array of strings. +If no arguments were specified, +\fIplugin_options\fR +will be the +\fRNULL\fR +pointer. +.sp +NOTE: the +\fIplugin_options\fR +parameter is only available starting with +API version 1.2. +A plugin +\fBmust\fR +check the API version specified +by the +\fBsudo\fR +front end before using +\fIplugin_options\fR. +Failure to do so may result in a crash. +.PD 0 +.PP +.RE +.PD +.TP 6n +close +.br +.nf +.RS 6n +void (*close)(int exit_status, int error); +.RE +.fi +.RS 6n +.sp +The +\fBclose\fR() +function is called when the command being run by +\fBsudo\fR +finishes. +.sp +The function arguments are as follows: +.TP 6n +exit_status +The command's exit status, as returned by the +wait(2) +system call. +The value of +\fRexit_status\fR +is undefined if +\fRerror\fR +is non-zero. +.TP 6n +error +.br +If the command could not be executed, this is set to the value of +\fRerrno\fR +set by the +execve(2) +system call. +If the command was successfully executed, the value of +\fRerror\fR +is 0. +.PD 0 +.PP +.RE +.PD +.TP 6n +show_version +.nf +.RS 6n +int (*show_version)(int verbose); +.RE +.fi +.RS 6n +.sp +The +\fBshow_version\fR() +function is called by +\fBsudo\fR +when the user specifies +the +\fB\-V\fR +option. +The plugin may display its version information to the user via the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function using +\fRSUDO_CONV_INFO_MSG\fR. +If the user requests detailed version information, the verbose flag will be set. +.sp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. +.RE +.TP 6n +log_ttyin +.nf +.RS 6n +int (*log_ttyin)(const char *buf, unsigned int len); +.RE +.fi +.RS 6n +.sp +The +\fBlog_ttyin\fR() +function is called whenever data can be read from +the user but before it is passed to the running command. +This allows the plugin to reject data if it chooses to (for instance +if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data +is rejected (which will terminate the running command) or \-1 if an +error occurred. +.sp +The function arguments are as follows: +.TP 6n +buf +The buffer containing user input. +.TP 6n +len +The length of +\fIbuf\fR +in bytes. +.PD 0 +.PP +.RE +.PD +.TP 6n +log_ttyout +.nf +.RS 6n +int (*log_ttyout)(const char *buf, unsigned int len); +.RE +.fi +.RS 6n +.sp +The +\fBlog_ttyout\fR() +function is called whenever data can be read from +the command but before it is written to the user's terminal. +This allows the plugin to reject data if it chooses to (for instance +if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is rejected +(which will terminate the running command) or \-1 if an error occurred. +.sp +The function arguments are as follows: +.TP 6n +buf +The buffer containing command output. +.TP 6n +len +The length of +\fIbuf\fR +in bytes. +.PD 0 +.PP +.RE +.PD +.TP 6n +log_stdin +.nf +.RS 6n +int (*log_stdin)(const char *buf, unsigned int len); +.RE +.fi +.RS 6n +.sp +The +\fBlog_stdin\fR() +function is only used if the standard input does +not correspond to a tty device. +It is called whenever data can be read from the standard input but +before it is passed to the running command. +This allows the plugin to reject data if it chooses to +(for instance if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.sp +The function arguments are as follows: +.TP 6n +buf +The buffer containing user input. +.TP 6n +len +The length of +\fIbuf\fR +in bytes. +.PD 0 +.PP +.RE +.PD +.TP 6n +log_stdout +.nf +.RS 6n +int (*log_stdout)(const char *buf, unsigned int len); +.RE +.fi +.RS 6n +.sp +The +\fBlog_stdout\fR() +function is only used if the standard output does not correspond +to a tty device. +It is called whenever data can be read from the command but before +it is written to the standard output. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.sp +The function arguments are as follows: +.TP 6n +buf +The buffer containing command output. +.TP 6n +len +The length of +\fIbuf\fR +in bytes. +.PD 0 +.PP +.RE +.PD +.TP 6n +log_stderr +.nf +.RS 6n +int (*log_stderr)(const char *buf, unsigned int len); +.RE +.fi +.RS 6n +.sp +The +\fBlog_stderr\fR() +function is only used if the standard error does +not correspond to a tty device. +It is called whenever data can be read from the command but before it +is written to the standard error. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.sp +The function arguments are as follows: +.TP 6n +buf +The buffer containing command output. +.TP 6n +len +The length of +\fIbuf\fR +in bytes. +.PD 0 +.PP +.RE +.PD +.TP 6n +register_hooks +See the +\fIPolicy plugin API\fR +section for a description of +\fRregister_hooks\fR. +.TP 6n +deregister_hooks +See the +\fIPolicy plugin API\fR +section for a description of +\fRderegister_hooks\fR. +.TP 6n +change_winsize +.nf +.RS 6n +int (*change_winsize)(unsigned int lines, unsigned int cols); +.RE +.fi +.RS 6n +.sp +The +\fBchange_winsize\fR() +function is called whenever the window size of the terminal changes from +the initial values specified in the +\fRuser_info\fR +list. +Returns \-1 if an error occurred, in which case no further calls to +\fBchange_winsize\fR() +will be made, +.RE +.TP 6n +log_suspend +.nf +.RS 6n +int (*log_suspend)(int signo); +.RE +.fi +.RS 6n +.sp +The +\fBlog_suspend\fR() +function is called whenever a command is suspended or resumed. +The +\fIsigno\fR +argument is either the signal that caused the command to be suspended or +\fRSIGCONT\fR +if the command was resumed. +Logging this information makes it possible to skip the period of time when +the command was suspended during playback of a session. +Returns \-1 if an error occurred, in which case no further calls to +\fBlog_suspend\fR() +will be made, +.RE +.PP +\fII/O Plugin Version Macros\fR +.PP +Same as for the +\fIPolicy plugin API\fR. +.SS "Signal handlers" +The +\fBsudo\fR +front end installs default signal handlers to trap common signals +while the plugin functions are run. +The following signals are trapped by default before the command is +executed: +.TP 3n +\fB\(bu\fR +\fRSIGALRM\fR +.PD 0 +.TP 3n +\fB\(bu\fR +\fRSIGHUP\fR +.TP 3n +\fB\(bu\fR +\fRSIGINT\fR +.TP 3n +\fB\(bu\fR +\fRSIGPIPE\fR +.TP 3n +\fB\(bu\fR +\fRSIGQUIT\fR +.TP 3n +\fB\(bu\fR +\fRSIGTERM\fR +.TP 3n +\fB\(bu\fR +\fRSIGTSTP\fR +.TP 3n +\fB\(bu\fR +\fRSIGUSR1\fR +.TP 3n +\fB\(bu\fR +\fRSIGUSR2\fR +.PD +.PP +If a fatal signal is received before the command is executed, +\fBsudo\fR +will call the plugin's +\fBclose\fR() +function with an exit status of 128 plus the value of the signal +that was received. +This allows for consistent logging of commands killed by a signal +for plugins that log such information in their +\fBclose\fR() +function. +An exception to this is +\fRSIGPIPE\fR, +which is ignored until the command is executed. +.PP +A plugin may temporarily install its own signal handlers but must +restore the original handler before the plugin function returns. +.SS "Hook function API" +Beginning with plugin API version 1.2, it is possible to install +hooks for certain functions called by the +\fBsudo\fR +front end. +.PP +Currently, the only supported hooks relate to the handling of +environment variables. +Hooks can be used to intercept attempts to get, set, or remove +environment variables so that these changes can be reflected in +the version of the environment that is used to execute a command. +A future version of the API will support hooking internal +\fBsudo\fR +front end functions as well. +.PP +\fIHook structure\fR +.PP +Hooks in +\fBsudo\fR +are described by the following structure: +.nf +.sp +.RS 0n +typedef int (*sudo_hook_fn_t)(); + +struct sudo_hook { + unsigned int hook_version; + unsigned int hook_type; + sudo_hook_fn_t hook_fn; + void *closure; +}; +.RE +.fi +.PP +The +\fRsudo_hook\fR +structure has the following fields: +.TP 6n +hook_version +The +\fRhook_version\fR +field should be set to +\fRSUDO_HOOK_VERSION\fR. +.TP 6n +hook_type +The +\fRhook_type\fR +field may be one of the following supported hook types: +.PP +.RS 6n +.PD 0 +.TP 6n +\fRSUDO_HOOK_SETENV\fR +The C library +setenv(3) +function. +Any registered hooks will run before the C library implementation. +The +\fRhook_fn\fR +field should +be a function that matches the following typedef: +.nf +.sp +.RS 6n +typedef int (*sudo_hook_fn_setenv_t)(const char *name, + const char *value, int overwrite, void *closure); +.RE +.fi +.RS 6n +.sp +If the registered hook does not match the typedef the results are +unspecified. +.RE +.PD +.TP 6n +\fRSUDO_HOOK_UNSETENV\fR +The C library +unsetenv(3) +function. +Any registered hooks will run before the C library implementation. +The +\fRhook_fn\fR +field should +be a function that matches the following typedef: +.nf +.sp +.RS 6n +typedef int (*sudo_hook_fn_unsetenv_t)(const char *name, + void *closure); +.RE +.fi +.TP 6n +\fRSUDO_HOOK_GETENV\fR +The C library +getenv(3) +function. +Any registered hooks will run before the C library implementation. +The +\fRhook_fn\fR +field should +be a function that matches the following typedef: +.nf +.sp +.RS 6n +typedef int (*sudo_hook_fn_getenv_t)(const char *name, + char **value, void *closure); +.RE +.fi +.RS 6n +.sp +If the registered hook does not match the typedef the results are +unspecified. +.RE +.TP 6n +\fRSUDO_HOOK_PUTENV\fR +The C library +putenv(3) +function. +Any registered hooks will run before the C library implementation. +The +\fRhook_fn\fR +field should +be a function that matches the following typedef: +.nf +.sp +.RS 6n +typedef int (*sudo_hook_fn_putenv_t)(char *string, + void *closure); +.RE +.fi +.RS 6n +.sp +If the registered hook does not match the typedef the results are +unspecified. +.RE +.PD 0 +.PP +.RE +.PD +.TP 6n +hook_fn +sudo_hook_fn_t hook_fn; +.sp +The +\fRhook_fn\fR +field should be set to the plugin's hook implementation. +The actual function arguments will vary depending on the +\fRhook_type\fR +(see +\fRhook_type\fR +above). +In all cases, the +\fRclosure\fR +field of +\fRstruct sudo_hook\fR +is passed as the last function parameter. +This can be used to pass arbitrary data to the plugin's hook implementation. +.sp +The function return value may be one of the following: +.PP +.RS 6n +.PD 0 +.TP 6n +\fRSUDO_HOOK_RET_ERROR\fR +The hook function encountered an error. +.PD +.TP 6n +\fRSUDO_HOOK_RET_NEXT\fR +The hook completed without error, go on to the next hook (including +the native implementation if applicable). +For example, a +getenv(3) +hook might return +\fRSUDO_HOOK_RET_NEXT\fR +if the specified variable was not found in the private copy of the environment. +.TP 6n +\fRSUDO_HOOK_RET_STOP\fR +The hook completed without error, stop processing hooks for this invocation. +This can be used to replace the native implementation. +For example, a +\fRsetenv\fR +hook that operates on a private copy of +the environment but leaves +\fRenviron\fR +unchanged. +.PD 0 +.PP +.RE +.PD +.PP +Note that it is very easy to create an infinite loop when hooking +C library functions. +For example, a +getenv(3) +hook that calls the +snprintf(3) +function may create a loop if the +snprintf(3) +implementation calls +getenv(3) +to check the locale. +To prevent this, you may wish to use a static variable in the hook +function to guard against nested calls. +For example: +.nf +.sp +.RS 0n +static int in_progress = 0; /* avoid recursion */ +if (in_progress) + return SUDO_HOOK_RET_NEXT; +in_progress = 1; +\&... +in_progress = 0; +return SUDO_HOOK_RET_STOP; +.RE +.fi +.PP +\fIHook API Version Macros\fR +.nf +.sp +.RS 0n +/* Hook API version major/minor */ +#define SUDO_HOOK_VERSION_MAJOR 1 +#define SUDO_HOOK_VERSION_MINOR 0 +#define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e + SUDO_HOOK_VERSION_MINOR) +.RE +.fi +.PP +For getters and setters see the +\fIPolicy plugin API\fR. +.SS "Remote command execution" +The +\fBsudo\fR +front end does not have native support for running remote commands. +However, starting with +\fBsudo\fR +1.8.8, the +\fB\-h\fR +option may be used to specify a remote host that is passed +to the policy plugin. +A plugin may also accept a +\fIrunas_user\fR +in the form of +\(lquser@hostname\(rq +which will work with older versions of +\fBsudo\fR. +It is anticipated that remote commands will be supported by executing a +\(lqhelper\(rq +program. +The policy plugin should setup the execution environment such that the +\fBsudo\fR +front end will run the helper which, in turn, will connect to the +remote host and run the command. +.PP +For example, the policy plugin could utilize +\fBssh\fR +to perform remote command execution. +The helper program would be responsible for running +\fBssh\fR +with the proper options to use a private key or certificate +that the remote host will accept and run a program +on the remote host that would setup the execution environment +accordingly. +.PP +Note that remote +\fBsudoedit\fR +functionality must be handled by the policy plugin, not +\fBsudo\fR +itself as the front end has no knowledge that a remote command is +being executed. +This may be addressed in a future revision of the plugin API. +.SS "Conversation API" +If the plugin needs to interact with the user, it may do so via the +\fBconversation\fR() +function. +A plugin should not attempt to read directly from the standard input +or the user's tty (neither of which are guaranteed to exist). +The caller must include a trailing newline in +\fRmsg\fR +if one is to be printed. +.PP +A +\fBprintf\fR()-style +function is also available that can be used to display informational +or error messages to the user, which is usually more convenient for +simple messages where no use input is required. +.PP +\fIConversation function structures\fR +.PP +The conversation function takes as arguments pointers to the following +structures: +.nf +.sp +.RS 0n +struct sudo_conv_message { +#define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ +#define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ +#define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ +#define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ +#define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ +#define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ +#define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */ + int msg_type; + int timeout; + const char *msg; +}; + +#define SUDO_CONV_REPL_MAX 255 + +struct sudo_conv_reply { + char *reply; +}; + +typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure); +struct sudo_conv_callback { + unsigned int version; + void *closure; + sudo_conv_callback_fn_t on_suspend; + sudo_conv_callback_fn_t on_resume; +}; +.RE +.fi +.PP +Pointers to the +\fBconversation\fR() +and +\fBprintf\fR()-style +functions are passed +in to the plugin's +\fBopen\fR() +function when the plugin is initialized. +The following type definitions can be used in the declaration of the +\fBopen\fR() +function: +.nf +.sp +.RS 0n +typedef int (*sudo_conv_t)(int num_msgs, + const struct sudo_conv_message msgs[], + struct sudo_conv_reply replies[], + struct sudo_conv_callback *callback); + +typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); +.RE +.fi +.PP +To use the +\fBconversation\fR() +function, the plugin must pass an array of +\fRsudo_conv_message\fR +and +\fRsudo_conv_reply\fR +structures. +There must be a +\fRstruct sudo_conv_message\fR +and +\fRstruct sudo_conv_reply\fR +for +each message in the conversation, that is, both arrays must have the same +number of elements. +Each +\fRstruct sudo_conv_reply\fR +must have its +\fIreply\fR +member initialized to +\fRNULL\fR. +The +\fRstruct sudo_conv_callback\fR +pointer, if not +\fRNULL\fR, +should contain function pointers to be called when the +\fBsudo\fR +process is suspended and/or resumed during conversation input. +The +\fIon_suspend\fR +and +\fIon_resume\fR +functions are called with the signal that caused +\fBsudo\fR +to be suspended and the +\fIclosure\fR +pointer from the +\fRstruct sudo_conv_callback\fR. +These functions should return 0 on success and \-1 on error. +On error, the conversation will end and the conversation function +will return a value of \-1. +The intended use is to allow the plugin to release resources, such as locks, +that should not be held indefinitely while suspended and then reacquire them +when the process is resumed. +Note that the functions are not actually invoked from within a signal handler. +.PP +The +\fImsg_type\fR +must be set to one of the following values: +.TP 6n +SUDO_CONV_PROMPT_ECHO_OFF +Prompt the user for input with echo disabled; +this is generally used for passwords. +The reply will be stored in the +\fIreplies\fR +array, and it will never be +\fRNULL\fR. +.TP 6n +SUDO_CONV_PROMPT_ECHO_ON +Prompt the user for input with echo enabled. +The reply will be stored in the +\fIreplies\fR +array, and it will never be +\fRNULL\fR. +.TP 6n +SUDO_CONV_ERROR_MSG +Display an error message. +The message is written to the standard error unless the +\fRSUDO_CONV_PREFER_TTY\fR +flag is set, in which case it is written to the user's terminal if possible. +.TP 6n +SUDO_CONV_INFO_MSG +Display a message. +The message is written to the standard output unless the +\fRSUDO_CONV_PREFER_TTY\fR +flag is set, in which case it is written to the user's terminal if possible. +.TP 6n +SUDO_CONV_PROMPT_MASK +Prompt the user for input but echo an asterisk character for each +character read. +The reply will be stored in the +\fIreplies\fR +array, and it will never be +\fRNULL\fR. +This can be used to provide visual feedback to the user while reading +sensitive information that should not be displayed. +.PP +In addition to the above values, the following flag bits may also be set: +.TP 6n +SUDO_CONV_PROMPT_ECHO_OK +Allow input to be read when echo cannot be disabled +when the message type is +\fRSUDO_CONV_PROMPT_ECHO_OFF\fR +or +\fRSUDO_CONV_PROMPT_MASK\fR. +By default, +\fBsudo\fR +will refuse to read input if the echo cannot be disabled for those +message types. +.TP 6n +SUDO_CONV_PREFER_TTY +When displaying a message via +\fRSUDO_CONV_ERROR_MSG\fR +or +\fRSUDO_CONV_INFO_MSG\fR, +try to write the message to the user's terminal. +If the terminal is unavailable, the standard error or standard output +will be used, depending upon whether +The user's terminal is always used when possible for input, +this flag is only used for output. +\fRSUDO_CONV_ERROR_MSG\fR +or +\fRSUDO_CONV_INFO_MSG\fR +was used. +.PP +The +\fItimeout\fR +in seconds until the prompt will wait for no more input. +A zero value implies an infinite timeout. +.PP +The plugin is responsible for freeing the reply buffer located in each +\fRstruct sudo_conv_reply\fR, +if it is not +\fRNULL\fR. +\fRSUDO_CONV_REPL_MAX\fR +represents the maximum length of the reply buffer (not including +the trailing NUL character). +In practical terms, this is the longest password +\fBsudo\fR +will support. +It is also useful as a maximum value for the +\fBmemset_s\fR() +function when clearing passwords filled in by the conversation function. +.PP +The +\fBprintf\fR()-style +function uses the same underlying mechanism as the +\fBconversation\fR() +function but only supports +\fRSUDO_CONV_INFO_MSG\fR +and +\fRSUDO_CONV_ERROR_MSG\fR +for the +\fImsg_type\fR +parameter. +It can be more convenient than using the +\fBconversation\fR() +function if no user reply is needed and supports standard +\fBprintf\fR() +escape sequences. +.PP +See the sample plugin for an example of the +\fBconversation\fR() +function usage. +.SS "Sudoers group plugin API" +The +\fBsudoers\fR +plugin supports its own plugin interface to allow non-Unix +group lookups. +This can be used to query a group source other than the standard Unix +group database. +Two sample group plugins are bundled with +\fBsudo\fR, +\fIgroup_file\fR +and +\fIsystem_group\fR, +are detailed in +sudoers(@mansectform@). +Third party group plugins include a QAS AD plugin available from Quest Software. +.PP +A group plugin must declare and populate a +\fRsudoers_group_plugin\fR +struct in the global scope. +This structure contains pointers to the functions that implement plugin +initialization, cleanup and group lookup. +.nf +.sp +.RS 0n +struct sudoers_group_plugin { + unsigned int version; + int (*init)(int version, sudo_printf_t sudo_printf, + char *const argv[]); + void (*cleanup)(void); + int (*query)(const char *user, const char *group, + const struct passwd *pwd); +}; +.RE +.fi +.PP +The +\fRsudoers_group_plugin\fR +struct has the following fields: +.TP 6n +version +The +\fRversion\fR +field should be set to GROUP_API_VERSION. +.sp +This allows +\fBsudoers\fR +to determine the API version the group plugin +was built against. +.TP 6n +init +.nf +.RS 6n +int (*init)(int version, sudo_printf_t plugin_printf, + char *const argv[]); +.RE +.fi +.RS 6n +.sp +The +\fBinit\fR() +function is called after +\fIsudoers\fR +has been parsed but +before any policy checks. +It returns 1 on success, 0 on failure (or if the plugin is not configured), +and \-1 if a error occurred. +If an error occurs, the plugin may call the +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional error information +to the user. +.sp +The function arguments are as follows: +.TP 6n +version +The version passed in by +\fBsudoers\fR +allows the plugin to determine the +major and minor version number of the group plugin API supported by +\fBsudoers\fR. +.TP 6n +plugin_printf +A pointer to a +\fBprintf\fR()-style +function that may be used to display informational or error message to the user. +Returns the number of characters printed on success and \-1 on failure. +.TP 6n +argv +A +\fRNULL\fR-terminated +array of arguments generated from the +\fIgroup_plugin\fR +option in +\fIsudoers\fR. +If no arguments were given, +\fIargv\fR +will be +\fRNULL\fR. +.PD 0 +.PP +.RE +.PD +.TP 6n +cleanup +.nf +.RS 6n +void (*cleanup)(); +.RE +.fi +.RS 6n +.sp +The +\fBcleanup\fR() +function is called when +\fBsudoers\fR +has finished its +group checks. +The plugin should free any memory it has allocated and close open file handles. +.RE +.TP 6n +query +.br +.nf +.RS 6n +int (*query)(const char *user, const char *group, + const struct passwd *pwd); +.RE +.fi +.RS 6n +.sp +The +\fBquery\fR() +function is used to ask the group plugin whether +\fIuser\fR +is a member of +\fIgroup\fR. +.sp +The function arguments are as follows: +.TP 6n +user +The name of the user being looked up in the external group database. +.TP 6n +group +.br +The name of the group being queried. +.TP 6n +pwd +The password database entry for +\fIuser\fR, +if any. +If +\fIuser\fR +is not +present in the password database, +\fIpwd\fR +will be +\fRNULL\fR. +.PD 0 +.PP +.RE +.PD +.PP +\fIGroup API Version Macros\fR +.nf +.sp +.RS 0n +/* Sudoers group plugin version major/minor */ +#define GROUP_API_VERSION_MAJOR 1 +#define GROUP_API_VERSION_MINOR 0 +#define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e + GROUP_API_VERSION_MINOR) +.RE +.fi +For getters and setters see the +\fIPolicy plugin API\fR. +.SH "PLUGIN API CHANGELOG" +The following revisions have been made to the Sudo Plugin API. +.TP 6n +Version 1.0 +Initial API version. +.TP 6n +Version 1.1 (sudo 1.8.0) +The I/O logging plugin's +\fBopen\fR() +function was modified to take the +\fRcommand_info\fR +list as an argument. +.TP 6n +Version 1.2 (sudo 1.8.5) +The Policy and I/O logging plugins' +\fBopen\fR() +functions are now passed +a list of plugin parameters if any are specified in +sudo.conf(@mansectform@). +.sp +A simple hooks API has been introduced to allow plugins to hook in to the +system's environment handling functions. +.sp +The +\fRinit_session\fR +Policy plugin function is now passed a pointer +to the user environment which can be updated as needed. +This can be used to merge in environment variables stored in the PAM +handle before a command is run. +.TP 6n +Version 1.3 (sudo 1.8.7) +Support for the +\fIexec_background\fR +entry has been added to the +\fRcommand_info\fR +list. +.sp +The +\fImax_groups\fR +and +\fIplugin_dir\fR +entries were added to the +\fRsettings\fR +list. +.sp +The +\fBversion\fR() +and +\fBclose\fR() +functions are now optional. +Previously, a missing +\fBversion\fR() +or +\fBclose\fR() +function would result in a crash. +If no policy plugin +\fBclose\fR() +function is defined, a default +\fBclose\fR() +function will be provided by the +\fBsudo\fR +front end that displays a warning if the command could not be +executed. +.sp +The +\fBsudo\fR +front end now installs default signal handlers to trap common signals +while the plugin functions are run. +.TP 6n +Version 1.4 (sudo 1.8.8) +The +\fIremote_host\fR +entry was added to the +\fRsettings\fR +list. +.TP 6n +Version 1.5 (sudo 1.8.9) +The +\fIpreserve_fds\fR +entry was added to the +\fRcommand_info\fR +list. +.TP 6n +Version 1.6 (sudo 1.8.11) +The behavior when an I/O logging plugin returns an error +(\-1) +has changed. +Previously, the +\fBsudo\fR +front end took no action when the +\fBlog_ttyin\fR(), +\fBlog_ttyout\fR(), +\fBlog_stdin\fR(), +\fBlog_stdout\fR(), +or +\fBlog_stderr\fR() +function returned an error. +.sp +The behavior when an I/O logging plugin returns 0 has changed. +Previously, output from the command would be displayed to the +terminal even if an output logging function returned 0. +.TP 6n +Version 1.7 (sudo 1.8.12) +The +\fIplugin_path\fR +entry was added to the +\fRsettings\fR +list. +.sp +The +\fIdebug_flags\fR +entry now starts with a debug file path name and may occur multiple +times if there are multiple plugin-specific Debug lines in the +sudo.conf(@mansectform@) file. +.TP 6n +Version 1.8 (sudo 1.8.15) +The +\fIsudoedit_checkdir\fR +and +\fIsudoedit_follow\fR +entries were added to the +\fRcommand_info\fR +list. +The default value of +\fIsudoedit_checkdir\fR +was changed to true in sudo 1.8.16. +.sp +The sudo +\fIconversation\fR +function now takes a pointer to a +\fRstruct sudo_conv_callback\fR +as its fourth argument. +The +\fRsudo_conv_t\fR +definition has been updated to match. +The plugin must specify that it supports plugin API version 1.8 or higher +to receive a conversation function pointer that supports this argument. +.TP 6n +Version 1.9 (sudo 1.8.16) +The +\fIexecfd\fR +entry was added to the +\fRcommand_info\fR +list. +.TP 6n +Version 1.10 (sudo 1.8.19) +The +\fIumask\fR +entry was added to the +\fRuser_info\fR +list. +The +\fIiolog_group\fR, +\fIiolog_mode\fR, +and +\fIiolog_user\fR +entries were added to the +\fRcommand_info\fR +list. +.TP 6n +Version 1.11 (sudo 1.8.20) +The +\fItimeout\fR +entry was added to the +\fRsettings\fR +list. +.TP 6n +Version 1.12 (sudo 1.8.21) +The +\fRchange_winsize\fR +field was added to the io_plugin struct. +.TP 6n +Version 1.13 (sudo 1.8.26) +The +\fRlog_suspend\fR +field was added to the io_plugin struct. +.SH "SEE ALSO" +sudo.conf(@mansectform@), +sudoers(@mansectform@), +sudo(@mansectsu@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in new file mode 100644 index 0000000..a293ee3 --- /dev/null +++ b/doc/sudo_plugin.mdoc.in @@ -0,0 +1,2625 @@ +.\" +.\" Copyright (c) 2009-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 24, 2018 +.Dt SUDO_PLUGIN @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudo_plugin +.Nd Sudo Plugin API +.Sh DESCRIPTION +Starting with version 1.8, +.Nm sudo +supports a plugin API +for policy and session logging. +Plugins may be compiled as dynamic shared objects (the default on +systems that support them) or compiled statically into the +.Nm sudo +binary itself. +By default, the +.Nm sudoers +policy plugin and an associated I/O logging plugin are used. +Via the plugin API, +.Nm sudo +can be configured to use alternate policy and/or I/O logging plugins +provided by third parties. +The plugins to be used are specified in the +.Xr sudo.conf @mansectform@ +file. +.Pp +The API is versioned with a major and minor number. +The minor version number is incremented when additions are made. +The major number is incremented when incompatible changes are made. +A plugin should be check the version passed to it and make sure that the +major version matches. +.Pp +The plugin API is defined by the +.Li sudo_plugin.h +header file. +.Ss Policy plugin API +A policy plugin must declare and populate a +.Li policy_plugin +struct in the global scope. +This structure contains pointers to the functions that implement the +.Nm sudo +policy checks. +The name of the symbol should be specified in +.Xr sudo.conf @mansectform@ +along with a path to the plugin so that +.Nm sudo +can load it. +.Bd -literal +struct policy_plugin { +#define SUDO_POLICY_PLUGIN 1 + unsigned int type; /* always SUDO_POLICY_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); + int (*show_version)(int verbose); + int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + int (*list)(int argc, char * const argv[], int verbose, + const char *list_user); + int (*validate)(void); + void (*invalidate)(int remove); + int (*init_session)(struct passwd *pwd, char **user_env[]); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +}; +.Ed +.Pp +The policy_plugin struct has the following fields: +.Bl -tag -width 4n +.It type +The +.Li type +field should always be set to SUDO_POLICY_PLUGIN. +.It version +The +.Li version +field should be set to +.Dv SUDO_API_VERSION . +.Pp +This allows +.Nm sudo +to determine the API version the plugin was +built against. +.It open +.Bd -literal -compact +int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); +.Ed +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +.Nm sudo +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Nm sudo +allows the plugin to determine the +major and minor version number of the plugin API supported by +.Nm sudo . +.It conversation +A pointer to the +.Fn conversation +function that can be used by the plugin to interact with the user (see below). +Returns 0 on success and \-1 on failure. +.It plugin_printf +A pointer to a +.Fn printf Ns -style +function that may be used to display informational or error messages +(see below). +Returns the number of characters printed on success and \-1 on failure. +.It settings +A vector of user-supplied +.Nm sudo +settings in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +These settings correspond to flags the user specified when running +.Nm sudo . +As such, they will only be present when the corresponding flag has +been specified on the command line. +.Pp +When parsing +.Em settings , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Bl -tag -width 4n +.It bsdauth_type=string +Authentication type, if specified by the +.Fl a +flag, to use on +systems where +.Bx +authentication is supported. +.It closefrom=number +If specified, the user has requested via the +.Fl C +flag that +.Nm sudo +close all files descriptors with a value of +.Em number +or higher. +The plugin may optionally pass this, or another value, back in the +.Em command_info +list. +.It debug_flags=string +A debug file path name followed by a space and a comma-separated +list of debug flags that correspond to the plugin's +.Li Debug +entry in +.Xr sudo.conf @mansectform@ , +if there is one. +The flags are passed to the plugin exactly as they appear in +.Xr sudo.conf @mansectform@ . +The syntax used by +.Nm sudo +and the +.Nm sudoers +plugin is +.Em subsystem Ns @ Ns Em priority +but a plugin is free to use a different +format so long as it does not include a comma +.Pq Ql ,\& . +Prior to +.Nm sudo +1.8.12, there was no way to specify plugin-specific +.Em debug_flags +so the value was always the same as that used by the +.Nm sudo +front end and did not include a path name, only the flags themselves. +As of version 1.7 of the plugin interface, +.Nm sudo +will only pass +.Em debug_flags +if +.Xr sudo.conf @mansectform@ +contains a plugin-specific +.Li Debug +entry. +.It debug_level=number +This setting has been deprecated in favor of +.Em debug_flags . +.It ignore_ticket=bool +Set to true if the user specified the +.Fl k +flag along with a +command, indicating that the user wishes to ignore any cached +authentication credentials. +.Em implied_shell +to true. +This allows +.Nm sudo +with no arguments +to be used similarly to +.Xr su 1 . +If the plugin does not to support this usage, it may return a value of \-2 +from the +.Fn check_policy +function, which will cause +.Nm sudo +to print a usage message and +exit. +.It implied_shell=bool +If the user does not specify a program on the command line, +.Nm sudo +will pass the plugin the path to the user's shell and set +.It login_class=string +.Bx +login class to use when setting resource limits and nice value, +if specified by the +.Fl c +flag. +.It login_shell=bool +Set to true if the user specified the +.Fl i +flag, indicating that +the user wishes to run a login shell. +.It max_groups=int +The maximum number of groups a user may belong to. +This will only be present if there is a corresponding setting in +.Xr sudo.conf @mansectform@ . +.It network_addrs=list +A space-separated list of IP network addresses and netmasks in the +form +.Dq addr/netmask , +e.g., +.Dq 192.168.1.2/255.255.255.0 . +The address and netmask pairs may be either IPv4 or IPv6, depending on +what the operating system supports. +If the address contains a colon +.Pq Ql :\& , +it is an IPv6 address, else it is IPv4. +.It noninteractive=bool +Set to true if the user specified the +.Fl n +flag, indicating that +.Nm sudo +should operate in non-interactive mode. +The plugin may reject a command run in non-interactive mode if user +interaction is required. +.It plugin_dir=string +The default plugin directory used by the +.Nm sudo +front end. +This is the default directory set at compile time and may not +correspond to the directory the running plugin was loaded from. +It may be used by a plugin to locate support files. +.It plugin_path=string +The path name of plugin loaded by the +.Nm sudo +front end. +The path name will be a fully-qualified unless the plugin was +statically compiled into +.Nm sudo . +.It preserve_environment=bool +Set to true if the user specified the +.Fl E +flag, indicating that +the user wishes to preserve the environment. +.It preserve_groups=bool +Set to true if the user specified the +.Fl P +flag, indicating that +the user wishes to preserve the group vector instead of setting it +based on the runas user. +.It progname=string +The command name that sudo was run as, typically +.Dq sudo +or +.Dq sudoedit . +.It prompt=string +The prompt to use when requesting a password, if specified via +the +.Fl p +flag. +.It remote_host=string +The name of the remote host to run the command on, if specified via +the +.Fl h +option. +Support for running the command on a remote host is meant to be implemented +via a helper program that is executed in place of the user-specified command. +The +.Nm sudo +front end is only capable of executing commands on the local host. +Only available starting with API version 1.4. +.It run_shell=bool +Set to true if the user specified the +.Fl s +flag, indicating that the user wishes to run a shell. +.It runas_group=string +The group name or gid to run the command as, if specified via +the +.Fl g +flag. +.It runas_user=string +The user name or uid to run the command as, if specified via the +.Fl u +flag. +.It selinux_role=string +SELinux role to use when executing the command, if specified by +the +.Fl r +flag. +.It selinux_type=string +SELinux type to use when executing the command, if specified by +the +.Fl t +flag. +.It set_home=bool +Set to true if the user specified the +.Fl H +flag. +If true, set the +.Li HOME +environment variable to the target user's home directory. +.It sudoedit=bool +Set to true when the +.Fl e +flag is specified or if invoked as +.Nm sudoedit . +The plugin shall substitute an editor into +.Em argv +in the +.Fn check_policy +function or return \-2 with a usage error +if the plugin does not support +.Em sudoedit . +For more information, see the +.Em check_policy +section. +.It timeout=string +User-specified command timeout. +Not all plugins support command timeouts and the ability for the +user to set a timeout may be restricted by policy. +The format of the timeout string is plugin-specific. +.El +.Pp +Additional settings may be added in the future so the plugin should +silently ignore settings that it does not recognize. +.It user_info +A vector of information about the user running the command in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +.Pp +When parsing +.Em user_info , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Bl -tag -width 4n +.It cols=int +The number of columns the user's terminal supports. +If there is no terminal device available, a default value of 80 is used. +.It cwd=string +The user's current working directory. +.It egid=gid_t +The effective group ID of the user invoking +.Nm sudo . +.It euid=uid_t +The effective user ID of the user invoking +.Nm sudo . +.It gid=gid_t +The real group ID of the user invoking +.Nm sudo . +.It groups=list +The user's supplementary group list formatted as a string of +comma-separated group IDs. +.It host=string +The local machine's hostname as returned by the +.Xr gethostname 2 +system call. +.It lines=int +The number of lines the user's terminal supports. +If there is +no terminal device available, a default value of 24 is used. +.It pgid=int +The ID of the process group that the running +.Nm sudo +process is a member of. +Only available starting with API version 1.2. +.It pid=int +The process ID of the running +.Nm sudo +process. +Only available starting with API version 1.2. +.It plugin_options +Any (non-comment) strings immediately after the plugin path are +passed as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +.Dv NULL Ns -terminated +array of strings. +If no arguments were +specified, +.Em plugin_options +will be the +.Dv NULL +pointer. +.Pp +NOTE: the +.Em plugin_options +parameter is only available starting with +API version 1.2. +A plugin +.Sy must +check the API version specified +by the +.Nm sudo +front end before using +.Em plugin_options . +Failure to do so may result in a crash. +.It ppid=int +The parent process ID of the running +.Nm sudo +process. +Only available starting with API version 1.2. +.It sid=int +The session ID of the running +.Nm sudo +process or 0 if +.Nm sudo +is not part of a POSIX job control session. +Only available starting with API version 1.2. +.It tcpgid=int +The ID of the foreground process group associated with the terminal +device associated with the +.Nm sudo +process or \-1 if there is no +terminal present. +Only available starting with API version 1.2. +.It tty=string +The path to the user's terminal device. +If the user has no terminal device associated with the session, +the value will be empty, as in +.Dq Li tty= . +.It uid=uid_t +The real user ID of the user invoking +.Nm sudo . +.It umask=octal +The invoking user's file creation mask. +Only available starting with API version 1.10. +.It user=string +The name of the user invoking +.Nm sudo . +.El +.It user_env +The user's environment in the form of a +.Dv NULL Ns -terminated vector of +.Dq name=value +strings. +.Pp +When parsing +.Em user_env , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.El +.It close +.Bd -literal -compact +void (*close)(int exit_status, int error); +.Ed +.Pp +The +.Fn close +function is called when the command being run by +.Nm sudo +finishes. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It exit_status +The command's exit status, as returned by the +.Xr wait 2 +system call. +The value of +.Li exit_status +is undefined if +.Li error +is non-zero. +.It error +If the command could not be executed, this is set to the value of +.Li errno +set by the +.Xr execve 2 +system call. +The plugin is responsible for displaying error information via the +.Fn conversation +or +.Fn plugin_printf +function. +If the command was successfully executed, the value of +.Li error +is 0. +.El +.Pp +If no +.Fn close +function is defined, no I/O logging plugins are loaded, +and neither the +.Em timeout +not +.Em use_pty +options are set in the +.Li command_info +list, the +.Nm sudo +front end may execute the command directly instead of running +it as a child process. +.It show_version +.Bd -literal -compact +int (*show_version)(int verbose); +.Ed +.Pp +The +.Fn show_version +function is called by +.Nm sudo +when the user specifies +the +.Fl V +option. +The plugin may display its version information to the user via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG . +If the user requests detailed version information, the verbose flag will be set. +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. +.It check_policy +.Bd -literal -compact +int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); +.Ed +.Pp +The +.Fn check_policy +function is called by +.Nm sudo +to determine +whether the user is allowed to run the specified commands. +.Pp +If the +.Em sudoedit +option was enabled in the +.Em settings +array +passed to the +.Fn open +function, the user has requested +.Em sudoedit +mode. +.Em sudoedit +is a mechanism for editing one or more files +where an editor is run with the user's credentials instead of with +elevated privileges. +.Nm sudo +achieves this by creating user-writable +temporary copies of the files to be edited and then overwriting the +originals with the temporary copies after editing is complete. +If the plugin supports +.Em sudoedit , +it should choose the editor to be used, potentially from a variable +in the user's environment, such as +.Li EDITOR , +and include it in +.Em argv_out +(note that environment +variables may include command line flags). +The files to be edited should be copied from +.Em argv +into +.Em argv_out , +separated from the +editor and its arguments by a +.Dq Li -- +element. +The +.Dq Li -- +will +be removed by +.Nm sudo +before the editor is executed. +The plugin should also set +.Em sudoedit=true +in the +.Em command_info +list. +.Pp +The +.Fn check_policy +function returns 1 if the command is allowed, +0 if not allowed, \-1 for a general error, or \-2 for a usage error +or if +.Em sudoedit +was specified but is unsupported by the plugin. +In the latter case, +.Nm sudo +will print a usage message before it +exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +.It argv +The argument vector describing the command the user wishes to run, +in the same form as what would be passed to the +.Xr execve 2 +system call. +The vector is terminated by a +.Dv NULL +pointer. +.It env_add +Additional environment variables specified by the user on the command +line in the form of a +.Dv NULL Ns -terminated +vector of +.Dq name=value +strings. +The plugin may reject the command if one or more variables +are not allowed to be set, or it may silently ignore such variables. +.Pp +When parsing +.Em env_add , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.It command_info +Information about the command being run in the form of +.Dq name=value +strings. +These values are used by +.Nm sudo +to set the execution +environment when running a command. +The plugin is responsible for creating and populating the vector, +which must be terminated with a +.Dv NULL +pointer. +The following values are recognized by +.Nm sudo : +.Bl -tag -width 4n +.It chroot=string +The root directory to use when running the command. +.It closefrom=number +If specified, +.Nm sudo +will close all files descriptors with a value +of +.Em number +or higher. +.It command=string +Fully qualified path to the command to be executed. +.It cwd=string +The current working directory to change to when executing the command. +.It exec_background=bool +By default, +.Nm sudo +runs a command as the foreground process as long as +.Nm sudo +itself is running in the foreground. +When +.Em exec_background +is enabled and the command is being run in a pty (due to I/O logging +or the +.Em use_pty +setting), the command will be run as a background process. +Attempts to read from the controlling terminal (or to change terminal +settings) will result in the command being suspended with the +.Dv SIGTTIN +signal (or +.Dv SIGTTOU +in the case of terminal settings). +If this happens when +.Nm sudo +is a foreground process, the command will be granted the controlling terminal +and resumed in the foreground with no user intervention required. +The advantage of initially running the command in the background is that +.Nm sudo +need not read from the terminal unless the command explicitly requests it. +Otherwise, any terminal input must be passed to the command, whether it +has required it or not (the kernel buffers terminals so it is not possible +to tell whether the command really wants the input). +This is different from historic +.Em sudo +behavior or when the command is not being run in a pty. +.Pp +For this to work seamlessly, the operating system must support the +automatic restarting of system calls. +Unfortunately, not all operating systems do this by default, +and even those that do may have bugs. +For example, macOS fails to restart the +.Fn tcgetattr +and +.Fn tcsetattr +system calls (this is a bug in macOS). +Furthermore, because this behavior depends on the command stopping with the +.Dv SIGTTIN +or +.Dv SIGTTOU +signals, programs that catch these signals and suspend themselves +with a different signal (usually +.Dv SIGTOP ) +will not be automatically foregrounded. +Some versions of the linux +.Xr su 1 +command behave this way. +Because of this, a plugin should not set +.Em exec_background +unless it is explicitly enabled by the administrator and there should +be a way to enabled or disable it on a per-command basis. +.Pp +This setting has no effect unless I/O logging is enabled or +.Em use_pty +is enabled. +.It execfd=number +If specified, +.Nm sudo +will use the +.Xr fexecve 2 +system call to execute the command instead of +.Xr execve 2 . +The specified +.Em number +must refer to an open file descriptor. +.It iolog_compress=bool +Set to true if the I/O logging plugins, if any, should compress the +log data. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_group=string +The group that will own newly created I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_mode=octal +The file permission mode to use when creating I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_user=string +The user that will own newly created I/O log files and directories. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_path=string +Fully qualified path to the file or directory in which I/O log is +to be stored. +This is a hint to the I/O logging plugin which may choose to ignore it. +If no I/O logging plugin is loaded, this setting has no effect. +.It iolog_stdin=bool +Set to true if the I/O logging plugins, if any, should log the +standard input if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_stdout=bool +Set to true if the I/O logging plugins, if any, should log the +standard output if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_stderr=bool +Set to true if the I/O logging plugins, if any, should log the +standard error if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_ttyin=bool +Set to true if the I/O logging plugins, if any, should log all +terminal input. +This only includes input typed by the user and not from a pipe or +redirected from a file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_ttyout=bool +Set to true if the I/O logging plugins, if any, should log all +terminal output. +This only includes output to the screen, not output to a pipe or file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It login_class=string +.Bx +login class to use when setting resource limits and nice value (optional). +This option is only set on systems that support login classes. +.It nice=int +Nice value (priority) to use when executing the command. +The nice value, if specified, overrides the priority associated with the +.Em login_class +on +.Bx +systems. +.It noexec=bool +If set, prevent the command from executing other programs. +.It preserve_fds=list +A comma-separated list of file descriptors that should be +preserved, regardless of the value of the +.Em closefrom +setting. +Only available starting with API version 1.5. +.It preserve_groups=bool +If set, +.Nm sudo +will preserve the user's group vector instead of +initializing the group vector based on +.Li runas_user . +.It runas_egid=gid +Effective group ID to run the command as. +If not specified, the value of +.Em runas_gid +is used. +.It runas_euid=uid +Effective user ID to run the command as. +If not specified, the value of +.Em runas_uid +is used. +.It runas_gid=gid +Group ID to run the command as. +.It runas_groups=list +The supplementary group vector to use for the command in the form +of a comma-separated list of group IDs. +If +.Em preserve_groups +is set, this option is ignored. +.It runas_uid=uid +User ID to run the command as. +.It selinux_role=string +SELinux role to use when executing the command. +.It selinux_type=string +SELinux type to use when executing the command. +.It set_utmp=bool +Create a utmp (or utmpx) entry when a pseudo-tty is allocated. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +.It sudoedit=bool +Set to true when in +.Em sudoedit +mode. +The plugin may enable +.Em sudoedit +mode even if +.Nm sudo +was not invoked as +.Nm sudoedit . +This allows the plugin to perform command substitution and transparently +enable +.Em sudoedit +when the user attempts to run an editor. +.It sudoedit_checkdir=bool +Set to false to disable directory writability checks in +.Nm sudoedit . +By default, +.Nm sudoedit +1.8.16 and higher will check all directory components of the path to be +edited for writability by the invoking user. +Symbolic links will not be followed in writable directories and +.Nm sudoedit +will refuse to edit a file located in a writable directory. +These restrictions are not enforced when +.Nm sudoedit +is run by root. +The +.Em sudoedit_follow +option can be set to false to disable this check. +Only available starting with API version 1.8. +.It sudoedit_follow=bool +Set to true to allow +.Nm sudoedit +to edit files that are symbolic links. +By default, +.Nm sudoedit +1.8.15 and higher will refuse to open a symbolic link. +The +.Em sudoedit_follow +option can be used to restore the older behavior and allow +.Nm sudoedit +to open symbolic links. +Only available starting with API version 1.8. +.It timeout=int +Command timeout. +If non-zero then when the timeout expires the command will be killed. +.It umask=octal +The file creation mask to use when executing the command. +.It use_pty=bool +Allocate a pseudo-tty to run the command in, regardless of whether +or not I/O logging is in use. +By default, +.Nm sudo +will only run +the command in a pty when an I/O log plugin is loaded. +.It utmp_user=string +User name to use when constructing a new utmp (or utmpx) entry when +.Em set_utmp +is enabled. +This option can be used to set the user field in the utmp entry to +the user the command runs as rather than the invoking user. +If not set, +.Nm sudo +will base the new entry on +the invoking user's existing entry. +.El +.Pp +Unsupported values will be ignored. +.It argv_out +The +.Dv NULL Ns -terminated +argument vector to pass to the +.Xr execve 2 +system call when executing the command. +The plugin is responsible for allocating and populating the vector. +.It user_env_out +The +.Dv NULL Ns -terminated +environment vector to use when executing the command. +The plugin is responsible for allocating and populating the vector. +.El +.It list +.Bd -literal -compact +int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); +.Ed +.Pp +List available privileges for the invoking user. +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to +the user. +.Pp +Privileges should be output via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG , +.Bl -tag -width 4n +.It verbose +Flag indicating whether to list in verbose mode or not. +.It list_user +The name of a different user to list privileges for if the policy +allows it. +If +.Dv NULL , +the plugin should list the privileges of the invoking user. +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +.It argv +If +.No non- Ns Dv NULL , +an argument vector describing a command the user +wishes to check against the policy in the same form as what would +be passed to the +.Xr execve 2 +system call. +If the command is permitted by the policy, the fully-qualified path +to the command should be displayed along with any command line arguments. +.El +.It validate +.Bd -literal -compact +int (*validate)(void); +.Ed +.Pp +The +.Fn validate +function is called when +.Nm sudo +is run with the +.Fl v +flag. +For policy plugins such as +.Nm sudoers +that cache +authentication credentials, this function will validate and cache +the credentials. +.Pp +The +.Fn validate +function should be +.Dv NULL +if the plugin does not support credential caching. +.Pp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional +error information to the user. +.It invalidate +.Bd -literal -compact +void (*invalidate)(int remove); +.Ed +.Pp +The +.Fn invalidate +function is called when +.Nm sudo +is called with +the +.Fl k +or +.Fl K +flag. +For policy plugins such as +.Nm sudoers +that +cache authentication credentials, this function will invalidate the +credentials. +If the +.Em remove +flag is set, the plugin may remove +the credentials instead of simply invalidating them. +.Pp +The +.Fn invalidate +function should be +.Dv NULL +if the plugin does not support credential caching. +.It init_session +.Bd -literal -compact +int (*init_session)(struct passwd *pwd, char **user_envp[); +.Ed +.Pp +The +.Fn init_session +function is called before +.Nm sudo +sets up the +execution environment for the command. +It is run in the parent +.Nm sudo +process and before any uid or gid changes. +This can be used to perform session setup that is not supported by +.Em command_info , +such as opening the PAM session. +The +.Fn close +function can be +used to tear down the session that was opened by +.Li init_session . +.Pp +The +.Em pwd +argument points to a passwd struct for the user the +command will be run as if the uid the command will run as was found +in the password database, otherwise it will be +.Dv NULL . +.Pp +The +.Em user_env +argument points to the environment the command will +run in, in the form of a +.Dv NULL Ns -terminated +vector of +.Dq name=value +strings. +This is the same string passed back to the front end via +the Policy Plugin's +.Em user_env_out +parameter. +If the +.Fn init_session +function needs to modify the user environment, it should update the +pointer stored in +.Em user_env . +The expected use case is to merge the contents of the PAM environment +(if any) with the contents of +.Em user_env . +NOTE: the +.Em user_env +parameter is only available +starting with API version 1.2. +A plugin +.Sy must +check the API +version specified by the +.Nm sudo +front end before using +.Em user_env . +Failure to do so may result in a crash. +.Pp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional +error information to the user. +.It register_hooks +.Bd -literal -compact +void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); +.Ed +.Pp +The +.Fn register_hooks +function is called by the sudo front end to +register any hooks the plugin needs. +If the plugin does not support hooks, +.Li register_hooks +should be set to the +.Dv NULL +pointer. +.Pp +The +.Em version +argument describes the version of the hooks API +supported by the +.Nm sudo +front end. +.Pp +The +.Fn register_hook +function should be used to register any supported +hooks the plugin needs. +It returns 0 on success, 1 if the hook type is not supported and \-1 +if the major version in +.Li struct hook +does not match the front end's major hook API version. +.Pp +See the +.Sx Hook function API +section below for more information +about hooks. +.Pp +NOTE: the +.Fn register_hooks +function is only available starting +with API version 1.2. +If the +.Nm sudo +front end doesn't support API +version 1.2 or higher, +.Li register_hooks +will not be called. +.It deregister_hooks +.Bd -literal -compact +void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +.Ed +.Pp +The +.Fn deregister_hooks +function is called by the sudo front end +to deregister any hooks the plugin has registered. +If the plugin does not support hooks, +.Li deregister_hooks +should be set to the +.Dv NULL +pointer. +.Pp +The +.Em version +argument describes the version of the hooks API +supported by the +.Nm sudo +front end. +.Pp +The +.Fn deregister_hook +function should be used to deregister any +hooks that were put in place by the +.Fn register_hook +function. +If the plugin tries to deregister a hook that the front end does not support, +.Li deregister_hook +will return an error. +.Pp +See the +.Sx Hook function API +section below for more information +about hooks. +.Pp +NOTE: the +.Fn deregister_hooks +function is only available starting +with API version 1.2. +If the +.Nm sudo +front end doesn't support API +version 1.2 or higher, +.Li deregister_hooks +will not be called. +.El +.Pp +.Em Policy Plugin Version Macros +.Bd -literal +/* Plugin API version major/minor. */ +#define SUDO_API_VERSION_MAJOR 1 +#define SUDO_API_VERSION_MINOR 13 +#define SUDO_API_MKVERSION(x, y) ((x << 16) | y) +#define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e + SUDO_API_VERSION_MINOR) + +/* Getters and setters for API version */ +#define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) +#define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) +#define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e +} while(0) +#define SUDO_API_VERSION_SET_MINOR(vp, n) do { \e + *(vp) = (*(vp) & 0xffff0000) | (n); \e +} while(0) +.Ed +.Ss I/O plugin API +.Bd -literal +struct io_plugin { +#define SUDO_IO_PLUGIN 2 + unsigned int type; /* always SUDO_IO_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); /* wait status or error */ + int (*show_version)(int verbose); + int (*log_ttyin)(const char *buf, unsigned int len); + int (*log_ttyout)(const char *buf, unsigned int len); + int (*log_stdin)(const char *buf, unsigned int len); + int (*log_stdout)(const char *buf, unsigned int len); + int (*log_stderr)(const char *buf, unsigned int len); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); + int (*change_winsize)(unsigned int lines, unsigned int cols); + int (*log_suspend)(int signo); +}; +.Ed +.Pp +When an I/O plugin is loaded, +.Nm sudo +runs the command in a pseudo-tty. +This makes it possible to log the input and output from the user's +session. +If any of the standard input, standard output or standard error do not +correspond to a tty, +.Nm sudo +will open a pipe to capture +the I/O for logging before passing it on. +.Pp +The log_ttyin function receives the raw user input from the terminal +device (note that this will include input even when echo is disabled, +such as when a password is read). +The log_ttyout function receives output from the pseudo-tty that is +suitable for replaying the user's session at a later time. +The +.Fn log_stdin , +.Fn log_stdout +and +.Fn log_stderr +functions are only called if the standard input, standard output +or standard error respectively correspond to something other than +a tty. +.Pp +Any of the logging functions may be set to the +.Dv NULL +pointer if no logging is to be performed. +If the open function returns 0, no I/O will be sent to the plugin. +.Pp +If a logging function returns an error +.Pq \-1 , +the running command will be terminated and all of the plugin's logging +functions will be disabled. +Other I/O logging plugins will still receive any remaining +input or output that has not yet been processed. +.Pp +If an input logging function rejects the data by returning 0, the +command will be terminated and the data will not be passed to the +command, though it will still be sent to any other I/O logging plugins. +If an output logging function rejects the data by returning 0, the +command will be terminated and the data will not be written to the +terminal, though it will still be sent to any other I/O logging plugins. +.Pp +The io_plugin struct has the following fields: +.Bl -tag -width 4n +.It type +The +.Li type +field should always be set to +.Dv SUDO_IO_PLUGIN . +.It version +The +.Li version +field should be set to +.Dv SUDO_API_VERSION . +.Pp +This allows +.Nm sudo +to determine the API version the plugin was +built against. +.It open +.Bd -literal -compact +int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); +.Ed +.Pp +The +.Fn open +function is run before the +.Fn log_ttyin , +.Fn log_ttyout , +.Fn log_stdin , +.Fn log_stdout , +.Fn log_stderr , +.Fn log_suspend , +.Fn change_winsize , +or +.Fn show_version +functions are called. +It is only called if the version is being requested or if the +policy plugin's +.Fn check_policy +function has returned successfully. +It returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +.Nm sudo +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present +additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Nm sudo +allows the plugin to determine the +major and minor version number of the plugin API supported by +.Nm sudo . +.It conversation +A pointer to the +.Fn conversation +function that may be used by the +.Fn show_version +function to display version information (see +.Fn show_version +below). +The +.Fn conversation +function may also be used to display additional error message to the user. +The +.Fn conversation +function returns 0 on success and \-1 on failure. +.It plugin_printf +A pointer to a +.Fn printf Ns -style +function that may be used by the +.Fn show_version +function to display version information (see +show_version below). +The +.Fn plugin_printf +function may also be used to display additional error message to the user. +The +.Fn plugin_printf +function returns number of characters printed on success and \-1 on failure. +.It settings +A vector of user-supplied +.Nm sudo +settings in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +These settings correspond to flags the user specified when running +.Nm sudo . +As such, they will only be present when the corresponding flag has +been specified on the command line. +.Pp +When parsing +.Em settings , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Pp +See the +.Sx Policy plugin API +section for a list of all possible settings. +.It user_info +A vector of information about the user running the command in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +.Pp +When parsing +.Em user_info , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Pp +See the +.Sx Policy plugin API +section for a list of all possible strings. +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +It can be zero, when +.Nm sudo +is called with +.Fl V . +.It argv +If +.No non- Ns Dv NULL , +an argument vector describing a command the user +wishes to run in the same form as what would be passed to the +.Xr execve 2 +system call. +.It user_env +The user's environment in the form of a +.Dv NULL Ns -terminated +vector of +.Dq name=value +strings. +.Pp +When parsing +.Em user_env , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.It plugin_options +Any (non-comment) strings immediately after the plugin path are +treated as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +.Dv NULL Ns -terminated +array of strings. +If no arguments were specified, +.Em plugin_options +will be the +.Dv NULL +pointer. +.Pp +NOTE: the +.Em plugin_options +parameter is only available starting with +API version 1.2. +A plugin +.Sy must +check the API version specified +by the +.Nm sudo +front end before using +.Em plugin_options . +Failure to do so may result in a crash. +.El +.It close +.Bd -literal -compact +void (*close)(int exit_status, int error); +.Ed +.Pp +The +.Fn close +function is called when the command being run by +.Nm sudo +finishes. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It exit_status +The command's exit status, as returned by the +.Xr wait 2 +system call. +The value of +.Li exit_status +is undefined if +.Li error +is non-zero. +.It error +If the command could not be executed, this is set to the value of +.Li errno +set by the +.Xr execve 2 +system call. +If the command was successfully executed, the value of +.Li error +is 0. +.El +.It show_version +.Bd -literal -compact +int (*show_version)(int verbose); +.Ed +.Pp +The +.Fn show_version +function is called by +.Nm sudo +when the user specifies +the +.Fl V +option. +The plugin may display its version information to the user via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG . +If the user requests detailed version information, the verbose flag will be set. +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. +.It log_ttyin +.Bd -literal -compact +int (*log_ttyin)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_ttyin +function is called whenever data can be read from +the user but before it is passed to the running command. +This allows the plugin to reject data if it chooses to (for instance +if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data +is rejected (which will terminate the running command) or \-1 if an +error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing user input. +.It len +The length of +.Em buf +in bytes. +.El +.It log_ttyout +.Bd -literal -compact +int (*log_ttyout)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_ttyout +function is called whenever data can be read from +the command but before it is written to the user's terminal. +This allows the plugin to reject data if it chooses to (for instance +if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is rejected +(which will terminate the running command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stdin +.Bd -literal -compact +int (*log_stdin)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stdin +function is only used if the standard input does +not correspond to a tty device. +It is called whenever data can be read from the standard input but +before it is passed to the running command. +This allows the plugin to reject data if it chooses to +(for instance if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing user input. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stdout +.Bd -literal -compact +int (*log_stdout)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stdout +function is only used if the standard output does not correspond +to a tty device. +It is called whenever data can be read from the command but before +it is written to the standard output. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stderr +.Bd -literal -compact +int (*log_stderr)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stderr +function is only used if the standard error does +not correspond to a tty device. +It is called whenever data can be read from the command but before it +is written to the standard error. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the running command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It register_hooks +See the +.Sx Policy plugin API +section for a description of +.Li register_hooks . +.It deregister_hooks +See the +.Sx Policy plugin API +section for a description of +.Li deregister_hooks . +.It change_winsize +.Bd -literal -compact +int (*change_winsize)(unsigned int lines, unsigned int cols); +.Ed +.Pp +The +.Fn change_winsize +function is called whenever the window size of the terminal changes from +the initial values specified in the +.Li user_info +list. +Returns \-1 if an error occurred, in which case no further calls to +.Fn change_winsize +will be made, +.It log_suspend +.Bd -literal -compact +int (*log_suspend)(int signo); +.Ed +.Pp +The +.Fn log_suspend +function is called whenever a command is suspended or resumed. +The +.Fa signo +argument is either the signal that caused the command to be suspended or +.Dv SIGCONT +if the command was resumed. +Logging this information makes it possible to skip the period of time when +the command was suspended during playback of a session. +Returns \-1 if an error occurred, in which case no further calls to +.Fn log_suspend +will be made, +.El +.Pp +.Em I/O Plugin Version Macros +.Pp +Same as for the +.Sx Policy plugin API . +.Ss Signal handlers +The +.Nm sudo +front end installs default signal handlers to trap common signals +while the plugin functions are run. +The following signals are trapped by default before the command is +executed: +.Pp +.Bl -bullet -compact -width 1n +.It +.Dv SIGALRM +.It +.Dv SIGHUP +.It +.Dv SIGINT +.It +.Dv SIGPIPE +.It +.Dv SIGQUIT +.It +.Dv SIGTERM +.It +.Dv SIGTSTP +.It +.Dv SIGUSR1 +.It +.Dv SIGUSR2 +.El +.Pp +If a fatal signal is received before the command is executed, +.Nm sudo +will call the plugin's +.Fn close +function with an exit status of 128 plus the value of the signal +that was received. +This allows for consistent logging of commands killed by a signal +for plugins that log such information in their +.Fn close +function. +An exception to this is +.Ev SIGPIPE , +which is ignored until the command is executed. +.Pp +A plugin may temporarily install its own signal handlers but must +restore the original handler before the plugin function returns. +.Ss Hook function API +Beginning with plugin API version 1.2, it is possible to install +hooks for certain functions called by the +.Nm sudo +front end. +.Pp +Currently, the only supported hooks relate to the handling of +environment variables. +Hooks can be used to intercept attempts to get, set, or remove +environment variables so that these changes can be reflected in +the version of the environment that is used to execute a command. +A future version of the API will support hooking internal +.Nm sudo +front end functions as well. +.Pp +.Em Hook structure +.Pp +Hooks in +.Nm sudo +are described by the following structure: +.Bd -literal +typedef int (*sudo_hook_fn_t)(); + +struct sudo_hook { + unsigned int hook_version; + unsigned int hook_type; + sudo_hook_fn_t hook_fn; + void *closure; +}; +.Ed +.Pp +The +.Li sudo_hook +structure has the following fields: +.Bl -tag -width 4n +.It hook_version +The +.Li hook_version +field should be set to +.Dv SUDO_HOOK_VERSION . +.It hook_type +The +.Li hook_type +field may be one of the following supported hook types: +.Bl -tag -width 4n +.It Dv SUDO_HOOK_SETENV +The C library +.Xr setenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_setenv_t)(const char *name, + const char *value, int overwrite, void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.It Dv SUDO_HOOK_UNSETENV +The C library +.Xr unsetenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_unsetenv_t)(const char *name, + void *closure); +.Ed +.It Dv SUDO_HOOK_GETENV +The C library +.Xr getenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_getenv_t)(const char *name, + char **value, void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.It Dv SUDO_HOOK_PUTENV +The C library +.Xr putenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_putenv_t)(char *string, + void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.El +.It hook_fn +sudo_hook_fn_t hook_fn; +.Pp +The +.Li hook_fn +field should be set to the plugin's hook implementation. +The actual function arguments will vary depending on the +.Li hook_type +(see +.Li hook_type +above). +In all cases, the +.Li closure +field of +.Li struct sudo_hook +is passed as the last function parameter. +This can be used to pass arbitrary data to the plugin's hook implementation. +.Pp +The function return value may be one of the following: +.Bl -tag -width 4n +.It Dv SUDO_HOOK_RET_ERROR +The hook function encountered an error. +.It Dv SUDO_HOOK_RET_NEXT +The hook completed without error, go on to the next hook (including +the native implementation if applicable). +For example, a +.Xr getenv 3 +hook might return +.Dv SUDO_HOOK_RET_NEXT +if the specified variable was not found in the private copy of the environment. +.It Dv SUDO_HOOK_RET_STOP +The hook completed without error, stop processing hooks for this invocation. +This can be used to replace the native implementation. +For example, a +.Li setenv +hook that operates on a private copy of +the environment but leaves +.Li environ +unchanged. +.El +.El +.Pp +Note that it is very easy to create an infinite loop when hooking +C library functions. +For example, a +.Xr getenv 3 +hook that calls the +.Xr snprintf 3 +function may create a loop if the +.Xr snprintf 3 +implementation calls +.Xr getenv 3 +to check the locale. +To prevent this, you may wish to use a static variable in the hook +function to guard against nested calls. +For example: +.Bd -literal +static int in_progress = 0; /* avoid recursion */ +if (in_progress) + return SUDO_HOOK_RET_NEXT; +in_progress = 1; +\&... +in_progress = 0; +return SUDO_HOOK_RET_STOP; +.Ed +.Pp +.Em Hook API Version Macros +.Bd -literal +/* Hook API version major/minor */ +#define SUDO_HOOK_VERSION_MAJOR 1 +#define SUDO_HOOK_VERSION_MINOR 0 +#define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e + SUDO_HOOK_VERSION_MINOR) +.Ed +.Pp +For getters and setters see the +.Sx Policy plugin API . +.Ss Remote command execution +The +.Nm sudo +front end does not have native support for running remote commands. +However, starting with +.Nm sudo +1.8.8, the +.Fl h +option may be used to specify a remote host that is passed +to the policy plugin. +A plugin may also accept a +.Em runas_user +in the form of +.Dq user@hostname +which will work with older versions of +.Nm sudo . +It is anticipated that remote commands will be supported by executing a +.Dq helper +program. +The policy plugin should setup the execution environment such that the +.Nm sudo +front end will run the helper which, in turn, will connect to the +remote host and run the command. +.Pp +For example, the policy plugin could utilize +.Nm ssh +to perform remote command execution. +The helper program would be responsible for running +.Nm ssh +with the proper options to use a private key or certificate +that the remote host will accept and run a program +on the remote host that would setup the execution environment +accordingly. +.Pp +Note that remote +.Nm sudoedit +functionality must be handled by the policy plugin, not +.Nm sudo +itself as the front end has no knowledge that a remote command is +being executed. +This may be addressed in a future revision of the plugin API. +.Ss Conversation API +If the plugin needs to interact with the user, it may do so via the +.Fn conversation +function. +A plugin should not attempt to read directly from the standard input +or the user's tty (neither of which are guaranteed to exist). +The caller must include a trailing newline in +.Li msg +if one is to be printed. +.Pp +A +.Fn printf Ns -style +function is also available that can be used to display informational +or error messages to the user, which is usually more convenient for +simple messages where no use input is required. +.Pp +.Em Conversation function structures +.Pp +The conversation function takes as arguments pointers to the following +structures: +.Bd -literal +struct sudo_conv_message { +#define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ +#define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ +#define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ +#define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ +#define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ +#define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ +#define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */ + int msg_type; + int timeout; + const char *msg; +}; + +#define SUDO_CONV_REPL_MAX 255 + +struct sudo_conv_reply { + char *reply; +}; + +typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure); +struct sudo_conv_callback { + unsigned int version; + void *closure; + sudo_conv_callback_fn_t on_suspend; + sudo_conv_callback_fn_t on_resume; +}; +.Ed +.Pp +Pointers to the +.Fn conversation +and +.Fn printf Ns -style +functions are passed +in to the plugin's +.Fn open +function when the plugin is initialized. +The following type definitions can be used in the declaration of the +.Fn open +function: +.Bd -literal +typedef int (*sudo_conv_t)(int num_msgs, + const struct sudo_conv_message msgs[], + struct sudo_conv_reply replies[], + struct sudo_conv_callback *callback); + +typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); +.Ed +.Pp +To use the +.Fn conversation +function, the plugin must pass an array of +.Li sudo_conv_message +and +.Li sudo_conv_reply +structures. +There must be a +.Li struct sudo_conv_message +and +.Li struct sudo_conv_reply +for +each message in the conversation, that is, both arrays must have the same +number of elements. +Each +.Li struct sudo_conv_reply +must have its +.Em reply +member initialized to +.Dv NULL . +The +.Li struct sudo_conv_callback +pointer, if not +.Dv NULL , +should contain function pointers to be called when the +.Nm sudo +process is suspended and/or resumed during conversation input. +The +.Fa on_suspend +and +.Fa on_resume +functions are called with the signal that caused +.Nm sudo +to be suspended and the +.Fa closure +pointer from the +.Li struct sudo_conv_callback . +These functions should return 0 on success and \-1 on error. +On error, the conversation will end and the conversation function +will return a value of \-1. +The intended use is to allow the plugin to release resources, such as locks, +that should not be held indefinitely while suspended and then reacquire them +when the process is resumed. +Note that the functions are not actually invoked from within a signal handler. +.Pp +The +.Em msg_type +must be set to one of the following values: +.Bl -tag -width 4n +.It SUDO_CONV_PROMPT_ECHO_OFF +Prompt the user for input with echo disabled; +this is generally used for passwords. +The reply will be stored in the +.Em replies +array, and it will never be +.Dv NULL . +.It SUDO_CONV_PROMPT_ECHO_ON +Prompt the user for input with echo enabled. +The reply will be stored in the +.Em replies +array, and it will never be +.Dv NULL . +.It SUDO_CONV_ERROR_MSG +Display an error message. +The message is written to the standard error unless the +.Dv SUDO_CONV_PREFER_TTY +flag is set, in which case it is written to the user's terminal if possible. +.It SUDO_CONV_INFO_MSG +Display a message. +The message is written to the standard output unless the +.Dv SUDO_CONV_PREFER_TTY +flag is set, in which case it is written to the user's terminal if possible. +.It SUDO_CONV_PROMPT_MASK +Prompt the user for input but echo an asterisk character for each +character read. +The reply will be stored in the +.Em replies +array, and it will never be +.Dv NULL . +This can be used to provide visual feedback to the user while reading +sensitive information that should not be displayed. +.El +.Pp +In addition to the above values, the following flag bits may also be set: +.Bl -tag -width 4n +.It SUDO_CONV_PROMPT_ECHO_OK +Allow input to be read when echo cannot be disabled +when the message type is +.Dv SUDO_CONV_PROMPT_ECHO_OFF +or +.Dv SUDO_CONV_PROMPT_MASK . +By default, +.Nm sudo +will refuse to read input if the echo cannot be disabled for those +message types. +.It SUDO_CONV_PREFER_TTY +When displaying a message via +.Dv SUDO_CONV_ERROR_MSG +or +.Dv SUDO_CONV_INFO_MSG , +try to write the message to the user's terminal. +If the terminal is unavailable, the standard error or standard output +will be used, depending upon whether +The user's terminal is always used when possible for input, +this flag is only used for output. +.Dv SUDO_CONV_ERROR_MSG +or +.Dv SUDO_CONV_INFO_MSG +was used. +.El +.Pp +The +.Em timeout +in seconds until the prompt will wait for no more input. +A zero value implies an infinite timeout. +.Pp +The plugin is responsible for freeing the reply buffer located in each +.Li struct sudo_conv_reply , +if it is not +.Dv NULL . +.Dv SUDO_CONV_REPL_MAX +represents the maximum length of the reply buffer (not including +the trailing NUL character). +In practical terms, this is the longest password +.Nm sudo +will support. +It is also useful as a maximum value for the +.Fn memset_s +function when clearing passwords filled in by the conversation function. +.Pp +The +.Fn printf Ns -style +function uses the same underlying mechanism as the +.Fn conversation +function but only supports +.Dv SUDO_CONV_INFO_MSG +and +.Dv SUDO_CONV_ERROR_MSG +for the +.Em msg_type +parameter. +It can be more convenient than using the +.Fn conversation +function if no user reply is needed and supports standard +.Fn printf +escape sequences. +.Pp +See the sample plugin for an example of the +.Fn conversation +function usage. +.Ss Sudoers group plugin API +The +.Nm sudoers +plugin supports its own plugin interface to allow non-Unix +group lookups. +This can be used to query a group source other than the standard Unix +group database. +Two sample group plugins are bundled with +.Nm sudo , +.Em group_file +and +.Em system_group , +are detailed in +.Xr sudoers @mansectform@ . +Third party group plugins include a QAS AD plugin available from Quest Software. +.Pp +A group plugin must declare and populate a +.Li sudoers_group_plugin +struct in the global scope. +This structure contains pointers to the functions that implement plugin +initialization, cleanup and group lookup. +.Bd -literal +struct sudoers_group_plugin { + unsigned int version; + int (*init)(int version, sudo_printf_t sudo_printf, + char *const argv[]); + void (*cleanup)(void); + int (*query)(const char *user, const char *group, + const struct passwd *pwd); +}; +.Ed +.Pp +The +.Li sudoers_group_plugin +struct has the following fields: +.Bl -tag -width 4n +.It version +The +.Li version +field should be set to GROUP_API_VERSION. +.Pp +This allows +.Nm sudoers +to determine the API version the group plugin +was built against. +.It init +.Bd -literal -compact +int (*init)(int version, sudo_printf_t plugin_printf, + char *const argv[]); +.Ed +.Pp +The +.Fn init +function is called after +.Em sudoers +has been parsed but +before any policy checks. +It returns 1 on success, 0 on failure (or if the plugin is not configured), +and \-1 if a error occurred. +If an error occurs, the plugin may call the +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information +to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Nm sudoers +allows the plugin to determine the +major and minor version number of the group plugin API supported by +.Nm sudoers . +.It plugin_printf +A pointer to a +.Fn printf Ns -style +function that may be used to display informational or error message to the user. +Returns the number of characters printed on success and \-1 on failure. +.It argv +A +.Dv NULL Ns -terminated +array of arguments generated from the +.Em group_plugin +option in +.Em sudoers . +If no arguments were given, +.Em argv +will be +.Dv NULL . +.El +.It cleanup +.Bd -literal -compact +void (*cleanup)(); +.Ed +.Pp +The +.Fn cleanup +function is called when +.Nm sudoers +has finished its +group checks. +The plugin should free any memory it has allocated and close open file handles. +.It query +.Bd -literal -compact +int (*query)(const char *user, const char *group, + const struct passwd *pwd); +.Ed +.Pp +The +.Fn query +function is used to ask the group plugin whether +.Em user +is a member of +.Em group . +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It user +The name of the user being looked up in the external group database. +.It group +The name of the group being queried. +.It pwd +The password database entry for +.Em user , +if any. +If +.Em user +is not +present in the password database, +.Em pwd +will be +.Dv NULL . +.El +.El +.Pp +.Em Group API Version Macros +.Bd -literal +/* Sudoers group plugin version major/minor */ +#define GROUP_API_VERSION_MAJOR 1 +#define GROUP_API_VERSION_MINOR 0 +#define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e + GROUP_API_VERSION_MINOR) +.Ed +For getters and setters see the +.Sx Policy plugin API . +.Sh PLUGIN API CHANGELOG +The following revisions have been made to the Sudo Plugin API. +.Bl -tag -width 4n +.It Version 1.0 +Initial API version. +.It Version 1.1 (sudo 1.8.0) +The I/O logging plugin's +.Fn open +function was modified to take the +.Li command_info +list as an argument. +.It Version 1.2 (sudo 1.8.5) +The Policy and I/O logging plugins' +.Fn open +functions are now passed +a list of plugin parameters if any are specified in +.Xr sudo.conf @mansectform@ . +.Pp +A simple hooks API has been introduced to allow plugins to hook in to the +system's environment handling functions. +.Pp +The +.Li init_session +Policy plugin function is now passed a pointer +to the user environment which can be updated as needed. +This can be used to merge in environment variables stored in the PAM +handle before a command is run. +.It Version 1.3 (sudo 1.8.7) +Support for the +.Em exec_background +entry has been added to the +.Li command_info +list. +.Pp +The +.Em max_groups +and +.Em plugin_dir +entries were added to the +.Li settings +list. +.Pp +The +.Fn version +and +.Fn close +functions are now optional. +Previously, a missing +.Fn version +or +.Fn close +function would result in a crash. +If no policy plugin +.Fn close +function is defined, a default +.Fn close +function will be provided by the +.Nm sudo +front end that displays a warning if the command could not be +executed. +.Pp +The +.Nm sudo +front end now installs default signal handlers to trap common signals +while the plugin functions are run. +.It Version 1.4 (sudo 1.8.8) +The +.Em remote_host +entry was added to the +.Li settings +list. +.It Version 1.5 (sudo 1.8.9) +The +.Em preserve_fds +entry was added to the +.Li command_info +list. +.It Version 1.6 (sudo 1.8.11) +The behavior when an I/O logging plugin returns an error +.Pq \-1 +has changed. +Previously, the +.Nm sudo +front end took no action when the +.Fn log_ttyin , +.Fn log_ttyout , +.Fn log_stdin , +.Fn log_stdout , +or +.Fn log_stderr +function returned an error. +.Pp +The behavior when an I/O logging plugin returns 0 has changed. +Previously, output from the command would be displayed to the +terminal even if an output logging function returned 0. +.It Version 1.7 (sudo 1.8.12) +The +.Em plugin_path +entry was added to the +.Li settings +list. +.Pp +The +.Em debug_flags +entry now starts with a debug file path name and may occur multiple +times if there are multiple plugin-specific Debug lines in the +.Xr sudo.conf @mansectform@ file. +.It Version 1.8 (sudo 1.8.15) +The +.Em sudoedit_checkdir +and +.Em sudoedit_follow +entries were added to the +.Li command_info +list. +The default value of +.Em sudoedit_checkdir +was changed to true in sudo 1.8.16. +.Pp +The sudo +.Em conversation +function now takes a pointer to a +.Li struct sudo_conv_callback +as its fourth argument. +The +.Li sudo_conv_t +definition has been updated to match. +The plugin must specify that it supports plugin API version 1.8 or higher +to receive a conversation function pointer that supports this argument. +.It Version 1.9 (sudo 1.8.16) +The +.Em execfd +entry was added to the +.Li command_info +list. +.It Version 1.10 (sudo 1.8.19) +The +.Em umask +entry was added to the +.Li user_info +list. +The +.Em iolog_group , +.Em iolog_mode , +and +.Em iolog_user +entries were added to the +.Li command_info +list. +.It Version 1.11 (sudo 1.8.20) +The +.Em timeout +entry was added to the +.Li settings +list. +.It Version 1.12 (sudo 1.8.21) +The +.Li change_winsize +field was added to the io_plugin struct. +.It Version 1.13 (sudo 1.8.26) +The +.Li log_suspend +field was added to the io_plugin struct. +.El +.Sh SEE ALSO +.Xr sudo.conf @mansectform@ , +.Xr sudoers @mansectform@ , +.Xr sudo @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers.cat b/doc/sudoers.cat new file mode 100644 index 0000000..9cc6a95 --- /dev/null +++ b/doc/sudoers.cat @@ -0,0 +1,2931 @@ +SUDOERS(4) File Formats Manual SUDOERS(4) + +NNAAMMEE + ssuuddooeerrss - default sudo security policy plugin + +DDEESSCCRRIIPPTTIIOONN + The ssuuddooeerrss policy plugin determines a user's ssuuddoo privileges. It is the + default ssuuddoo policy plugin. The policy is driven by the _/_e_t_c_/_s_u_d_o_e_r_s + file or, optionally in LDAP. The policy format is described in detail in + the _S_U_D_O_E_R_S _F_I_L_E _F_O_R_M_A_T section. For information on storing ssuuddooeerrss + policy information in LDAP, please see sudoers.ldap(4). + + CCoonnffiigguurriinngg ssuuddoo..ccoonnff ffoorr ssuuddooeerrss + ssuuddoo consults the sudo.conf(4) file to determine which policy and I/O + logging plugins to load. If no sudo.conf(4) file is present, or if it + contains no Plugin lines, ssuuddooeerrss will be used for policy decisions and + I/O logging. To explicitly configure sudo.conf(4) to use the ssuuddooeerrss + plugin, the following configuration can be used. + + Plugin sudoers_policy sudoers.so + Plugin sudoers_io sudoers.so + + Starting with ssuuddoo 1.8.5, it is possible to specify optional arguments to + the ssuuddooeerrss plugin in the sudo.conf(4) file. These arguments, if + present, should be listed after the path to the plugin (i.e., after + _s_u_d_o_e_r_s_._s_o). Multiple arguments may be specified, separated by white + space. For example: + + Plugin sudoers_policy sudoers.so sudoers_mode=0400 + + The following plugin arguments are supported: + + ldap_conf=pathname + The _l_d_a_p___c_o_n_f argument can be used to override the default path + to the _l_d_a_p_._c_o_n_f file. + + ldap_secret=pathname + The _l_d_a_p___s_e_c_r_e_t argument can be used to override the default + path to the _l_d_a_p_._s_e_c_r_e_t file. + + sudoers_file=pathname + The _s_u_d_o_e_r_s___f_i_l_e argument can be used to override the default + path to the _s_u_d_o_e_r_s file. + + sudoers_uid=uid + The _s_u_d_o_e_r_s___u_i_d argument can be used to override the default + owner of the sudoers file. It should be specified as a numeric + user ID. + + sudoers_gid=gid + The _s_u_d_o_e_r_s___g_i_d argument can be used to override the default + group of the sudoers file. It must be specified as a numeric + group ID (not a group name). + + sudoers_mode=mode + The _s_u_d_o_e_r_s___m_o_d_e argument can be used to override the default + file mode for the sudoers file. It should be specified as an + octal value. + + For more information on configuring sudo.conf(4), please refer to its + manual. + + UUsseerr AAuutthheennttiiccaattiioonn + The ssuuddooeerrss security policy requires that most users authenticate + themselves before they can use ssuuddoo. A password is not required if the + invoking user is root, if the target user is the same as the invoking + user, or if the policy has disabled authentication for the user or + command. Unlike su(1), when ssuuddooeerrss requires authentication, it + validates the invoking user's credentials, not the target user's (or + root's) credentials. This can be changed via the _r_o_o_t_p_w, _t_a_r_g_e_t_p_w and + _r_u_n_a_s_p_w flags, described later. + + If a user who is not listed in the policy tries to run a command via + ssuuddoo, mail is sent to the proper authorities. The address used for such + mail is configurable via the _m_a_i_l_t_o Defaults entry (described later) and + defaults to root. + + Note that no mail will be sent if an unauthorized user tries to run ssuuddoo + with the --ll or --vv option unless there is an authentication error and + either the _m_a_i_l___a_l_w_a_y_s or _m_a_i_l___b_a_d_p_a_s_s flags are enabled. This allows + users to determine for themselves whether or not they are allowed to use + ssuuddoo. All attempts to run ssuuddoo (successful or not) will be logged, + regardless of whether or not mail is sent. + + If ssuuddoo is run by root and the SUDO_USER environment variable is set, the + ssuuddooeerrss policy will use this value to determine who the actual user is. + This can be used by a user to log commands through sudo even when a root + shell has been invoked. It also allows the --ee option to remain useful + even when invoked via a sudo-run script or program. Note, however, that + the _s_u_d_o_e_r_s file lookup is still done for root, not the user specified by + SUDO_USER. + + ssuuddooeerrss uses per-user time stamp files for credential caching. Once a + user has been authenticated, a record is written containing the user ID + that was used to authenticate, the terminal session ID, the start time of + the session leader (or parent process) and a time stamp (using a + monotonic clock if one is available). The user may then use ssuuddoo without + a password for a short period of time (5 minutes unless overridden by the + _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t option). By default, ssuuddooeerrss uses a separate record + for each terminal, which means that a user's login sessions are + authenticated separately. The _t_i_m_e_s_t_a_m_p___t_y_p_e option can be used to + select the type of time stamp record ssuuddooeerrss will use. + + LLooggggiinngg + ssuuddooeerrss can log both successful and unsuccessful attempts (as well as + errors) to syslog(3), a log file, or both. By default, ssuuddooeerrss will log + via syslog(3) but this is changeable via the _s_y_s_l_o_g and _l_o_g_f_i_l_e Defaults + settings. See _L_O_G _F_O_R_M_A_T for a description of the log file format. + + ssuuddooeerrss is also capable of running a command in a pseudo-tty and logging + all input and/or output. The standard input, standard output and + standard error can be logged even when not associated with a terminal. + I/O logging is not on by default but can be enabled using the _l_o_g___i_n_p_u_t + and _l_o_g___o_u_t_p_u_t options as well as the LOG_INPUT and LOG_OUTPUT command + tags. See _I_/_O _L_O_G _F_I_L_E_S for details on how I/O log files are stored. + + CCoommmmaanndd eennvviirroonnmmeenntt + Since environment variables can influence program behavior, ssuuddooeerrss + provides a means to restrict which variables from the user's environment + are inherited by the command to be run. There are two distinct ways + ssuuddooeerrss can deal with environment variables. + + By default, the _e_n_v___r_e_s_e_t option is enabled. This causes commands to be + executed with a new, minimal environment. On AIX (and Linux systems + without PAM), the environment is initialized with the contents of the + _/_e_t_c_/_e_n_v_i_r_o_n_m_e_n_t file. On BSD systems, if the _u_s_e___l_o_g_i_n_c_l_a_s_s option is + enabled, the environment is initialized based on the _p_a_t_h and _s_e_t_e_n_v + settings in _/_e_t_c_/_l_o_g_i_n_._c_o_n_f. The new environment contains the TERM, + PATH, HOME, MAIL, SHELL, LOGNAME, USER and SUDO_* variables in addition + to variables from the invoking process permitted by the _e_n_v___c_h_e_c_k and + _e_n_v___k_e_e_p options. This is effectively a whitelist for environment + variables. The environment variables LOGNAME and USER are treated + specially. If one of them is preserved (or removed) from user's + environment, the other will be as well. If LOGNAME and USER are to be + preserved but only one of them is present in the user's environment, the + other will be set to the same value. This avoids an inconsistent + environment where one of the variables describing the user name is set to + the invoking user and one is set to the target user. () are removed + unless both the name and value parts are matched by _e_n_v___k_e_e_p or + _e_n_v___c_h_e_c_k, as they may be interpreted as functions by the bbaasshh shell. + Prior to version 1.8.11, such variables were always removed. + + If, however, the _e_n_v___r_e_s_e_t option is disabled, any variables not + explicitly denied by the _e_n_v___c_h_e_c_k and _e_n_v___d_e_l_e_t_e options are inherited + from the invoking process. In this case, _e_n_v___c_h_e_c_k and _e_n_v___d_e_l_e_t_e behave + like a blacklist. Prior to version 1.8.21, environment variables with a + value beginning with () were always removed. Beginning with version + 1.8.21, a pattern in _e_n_v___d_e_l_e_t_e is used to match bbaasshh shell functions + instead. Since it is not possible to blacklist all potentially dangerous + environment variables, use of the default _e_n_v___r_e_s_e_t behavior is + encouraged. + + Environment variables specified by _e_n_v___c_h_e_c_k, _e_n_v___d_e_l_e_t_e, or _e_n_v___k_e_e_p may + include one or more `*' characters which will match zero or more + characters. No other wildcard characters are supported. + + By default, environment variables are matched by name. However, if the + pattern includes an equal sign (`='), both the variables name and value + must match. For example, a bbaasshh shell function could be matched as + follows: + + env_keep += "BASH_FUNC_my_func%%=()*" + + Without the "=()*" suffix, this would not match, as bbaasshh shell functions + are not preserved by default. + + The complete list of environment variables that ssuuddoo allows or denies is + contained in the output of "sudo -V" when run as root. Please note that + this list varies based on the operating system ssuuddoo is running on. + + On systems that support PAM where the ppaamm__eennvv module is enabled for ssuuddoo, + variables in the PAM environment may be merged in to the environment. If + a variable in the PAM environment is already present in the user's + environment, the value will only be overridden if the variable was not + preserved by ssuuddooeerrss. When _e_n_v___r_e_s_e_t is enabled, variables preserved + from the invoking user's environment by the _e_n_v___k_e_e_p list take precedence + over those in the PAM environment. When _e_n_v___r_e_s_e_t is disabled, variables + present the invoking user's environment take precedence over those in the + PAM environment unless they match a pattern in the _e_n_v___d_e_l_e_t_e list. + + Note that the dynamic linker on most operating systems will remove + variables that can control dynamic linking from the environment of setuid + executables, including ssuuddoo. Depending on the operating system this may + include _RLD*, DYLD_*, LD_*, LDR_*, LIBPATH, SHLIB_PATH, and others. + These type of variables are removed from the environment before ssuuddoo even + begins execution and, as such, it is not possible for ssuuddoo to preserve + them. + + As a special case, if ssuuddoo's --ii option (initial login) is specified, + ssuuddooeerrss will initialize the environment regardless of the value of + _e_n_v___r_e_s_e_t. The DISPLAY, PATH and TERM variables remain unchanged; HOME, + MAIL, SHELL, USER, and LOGNAME are set based on the target user. On AIX + (and Linux systems without PAM), the contents of _/_e_t_c_/_e_n_v_i_r_o_n_m_e_n_t are + also included. On BSD systems, if the _u_s_e___l_o_g_i_n_c_l_a_s_s flag is enabled, + the _p_a_t_h and _s_e_t_e_n_v variables in _/_e_t_c_/_l_o_g_i_n_._c_o_n_f are also applied. All + other environment variables are removed unless permitted by _e_n_v___k_e_e_p or + _e_n_v___c_h_e_c_k, described above. + + Finally, the _r_e_s_t_r_i_c_t_e_d___e_n_v___f_i_l_e and _e_n_v___f_i_l_e files are applied, if + present. The variables in _r_e_s_t_r_i_c_t_e_d___e_n_v___f_i_l_e are applied first and are + subject to the same restrictions as the invoking user's environment, as + detailed above. The variables in _e_n_v___f_i_l_e are applied last and are not + subject to these restrictions. In both cases, variables present in the + files will only be set to their specified values if they would not + conflict with an existing environment variable. + +SSUUDDOOEERRSS FFIILLEE FFOORRMMAATT + The _s_u_d_o_e_r_s file is composed of two types of entries: aliases (basically + variables) and user specifications (which specify who may run what). + + When multiple entries match for a user, they are applied in order. Where + there are multiple matches, the last match is used (which is not + necessarily the most specific match). + + The _s_u_d_o_e_r_s file grammar will be described below in Extended Backus-Naur + Form (EBNF). Don't despair if you are unfamiliar with EBNF; it is fairly + simple, and the definitions below are annotated. + + QQuuiicckk gguuiiddee ttoo EEBBNNFF + EBNF is a concise and exact way of describing the grammar of a language. + Each EBNF definition is made up of _p_r_o_d_u_c_t_i_o_n _r_u_l_e_s. E.g., + + symbol ::= definition | alternate1 | alternate2 ... + + Each _p_r_o_d_u_c_t_i_o_n _r_u_l_e references others and thus makes up a grammar for + the language. EBNF also contains the following operators, which many + readers will recognize from regular expressions. Do not, however, + confuse them with "wildcard" characters, which have different meanings. + + ? Means that the preceding symbol (or group of symbols) is optional. + That is, it may appear once or not at all. + + * Means that the preceding symbol (or group of symbols) may appear + zero or more times. + + + Means that the preceding symbol (or group of symbols) may appear + one or more times. + + Parentheses may be used to group symbols together. For clarity, we will + use single quotes ('') to designate what is a verbatim character string + (as opposed to a symbol name). + + AAlliiaasseess + There are four kinds of aliases: User_Alias, Runas_Alias, Host_Alias and + Cmnd_Alias. + + Alias ::= 'User_Alias' User_Alias_Spec (':' User_Alias_Spec)* | + 'Runas_Alias' Runas_Alias_Spec (':' Runas_Alias_Spec)* | + 'Host_Alias' Host_Alias_Spec (':' Host_Alias_Spec)* | + 'Cmnd_Alias' Cmnd_Alias_Spec (':' Cmnd_Alias_Spec)* + + User_Alias ::= NAME + + User_Alias_Spec ::= User_Alias '=' User_List + + Runas_Alias ::= NAME + + Runas_Alias_Spec ::= Runas_Alias '=' Runas_List + + Host_Alias ::= NAME + + Host_Alias_Spec ::= Host_Alias '=' Host_List + + Cmnd_Alias ::= NAME + + Cmnd_Alias_Spec ::= Cmnd_Alias '=' Cmnd_List + + NAME ::= [A-Z]([A-Z][0-9]_)* + + Each _a_l_i_a_s definition is of the form + + Alias_Type NAME = item1, item2, ... + + where _A_l_i_a_s___T_y_p_e is one of User_Alias, Runas_Alias, Host_Alias, or + Cmnd_Alias. A NAME is a string of uppercase letters, numbers, and + underscore characters (`_'). A NAME mmuusstt start with an uppercase letter. + It is possible to put several alias definitions of the same type on a + single line, joined by a colon (`:'). E.g., + + Alias_Type NAME = item1, item2, item3 : NAME = item4, item5 + + It is a syntax error to redefine an existing _a_l_i_a_s. It is possible to + use the same name for _a_l_i_a_s_e_s of different types, but this is not + recommended. + + The definitions of what constitutes a valid _a_l_i_a_s member follow. + + User_List ::= User | + User ',' User_List + + User ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* +netgroup | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* User_Alias + + A User_List is made up of one or more user names, user IDs (prefixed with + `#'), system group names and IDs (prefixed with `%' and `%#' + respectively), netgroups (prefixed with `+'), non-Unix group names and + IDs (prefixed with `%:' and `%:#' respectively) and User_Aliases. Each + list item may be prefixed with zero or more `!' operators. An odd number + of `!' operators negate the value of the item; an even number just cancel + each other out. User netgroups are matched using the user and domain + members only; the host member is not used when matching. + + A user name, uid, group, gid, netgroup, nonunix_group or nonunix_gid may + be enclosed in double quotes to avoid the need for escaping special + characters. Alternately, special characters may be specified in escaped + hex mode, e.g., \x20 for space. When using double quotes, any prefix + characters must be included inside the quotes. + + The actual nonunix_group and nonunix_gid syntax depends on the underlying + group provider plugin. For instance, the QAS AD plugin supports the + following formats: + + ++oo Group in the same domain: "%:Group Name" + + ++oo Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" + + ++oo Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" + + See _G_R_O_U_P _P_R_O_V_I_D_E_R _P_L_U_G_I_N_S for more information. + + Note that quotes around group names are optional. Unquoted strings must + use a backslash (`\') to escape spaces and special characters. See _O_t_h_e_r + _s_p_e_c_i_a_l _c_h_a_r_a_c_t_e_r_s _a_n_d _r_e_s_e_r_v_e_d _w_o_r_d_s for a list of characters that need + to be escaped. + + Runas_List ::= Runas_Member | + Runas_Member ',' Runas_List + + Runas_Member ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* +netgroup | + '!'* Runas_Alias + + A Runas_List is similar to a User_List except that instead of + User_Aliases it can contain Runas_Aliases. Note that user names and + groups are matched as strings. In other words, two users (groups) with + the same uid (gid) are considered to be distinct. If you wish to match + all user names with the same uid (e.g., root and toor), you can use a uid + instead (#0 in the example given). + + Host_List ::= Host | + Host ',' Host_List + + Host ::= '!'* host name | + '!'* ip_addr | + '!'* network(/netmask)? | + '!'* +netgroup | + '!'* Host_Alias + + A Host_List is made up of one or more host names, IP addresses, network + numbers, netgroups (prefixed with `+') and other aliases. Again, the + value of an item may be negated with the `!' operator. Host netgroups + are matched using the host (both qualified and unqualified) and domain + members only; the user member is not used when matching. If you specify + a network number without a netmask, ssuuddoo will query each of the local + host's network interfaces and, if the network number corresponds to one + of the hosts's network interfaces, will use the netmask of that + interface. The netmask may be specified either in standard IP address + notation (e.g., 255.255.255.0 or ffff:ffff:ffff:ffff::), or CIDR notation + (number of bits, e.g., 24 or 64). A host name may include shell-style + wildcards (see the _W_i_l_d_c_a_r_d_s section below), but unless the host name + command on your machine returns the fully qualified host name, you'll + need to use the _f_q_d_n option for wildcards to be useful. Note that ssuuddoo + only inspects actual network interfaces; this means that IP address + 127.0.0.1 (localhost) will never match. Also, the host name "localhost" + will only match if that is the actual host name, which is usually only + the case for non-networked systems. + + digest ::= [A-Fa-f0-9]+ | + [[A-Za-z0-9+/=]+ + + Digest_Spec ::= "sha224" ':' digest | + "sha256" ':' digest | + "sha384" ':' digest | + "sha512" ':' digest + + Cmnd_List ::= Cmnd | + Cmnd ',' Cmnd_List + + command name ::= file name | + file name args | + file name '""' + + Cmnd ::= Digest_Spec? '!'* command name | + '!'* directory | + '!'* "sudoedit" | + '!'* Cmnd_Alias + + A Cmnd_List is a list of one or more command names, directories, and + other aliases. A command name is a fully qualified file name which may + include shell-style wildcards (see the _W_i_l_d_c_a_r_d_s section below). A + simple file name allows the user to run the command with any arguments + he/she wishes. However, you may also specify command line arguments + (including wildcards). Alternately, you can specify "" to indicate that + the command may only be run wwiitthhoouutt command line arguments. A directory + is a fully qualified path name ending in a `/'. When you specify a + directory in a Cmnd_List, the user will be able to run any file within + that directory (but not in any sub-directories therein). + + If a Cmnd has associated command line arguments, then the arguments in + the Cmnd must match exactly those given by the user on the command line + (or match the wildcards if there are any). Note that the following + characters must be escaped with a `\' if they are used in command + arguments: `,', `:', `=', `\'. The built-in command "sudoedit" is used + to permit a user to run ssuuddoo with the --ee option (or as ssuuddooeeddiitt). It may + take command line arguments just as a normal command does. Note that + "sudoedit" is a command built into ssuuddoo itself and must be specified in + the _s_u_d_o_e_r_s file without a leading path. + + If a command name is prefixed with a Digest_Spec, the command will only + match successfully if it can be verified using the specified SHA-2 + digest. The following digest formats are supported: sha224, sha256, + sha384 and sha512. The string may be specified in either hex or base64 + format (base64 is more compact). There are several utilities capable of + generating SHA-2 digests in hex format such as openssl, shasum, + sha224sum, sha256sum, sha384sum, sha512sum. + + For example, using openssl: + + $ openssl dgst -sha224 /bin/ls + SHA224(/bin/ls)= 118187da8364d490b4a7debbf483004e8f3e053ec954309de2c41a25 + + It is also possible to use openssl to generate base64 output: + + $ openssl dgst -binary -sha224 /bin/ls | openssl base64 + EYGH2oNk1JC0p9679IMATo8+BT7JVDCd4sQaJQ== + + Warning, if the user has write access to the command itself (directly or + via a ssuuddoo command), it may be possible for the user to replace the + command after the digest check has been performed but before the command + is executed. A similar race condition exists on systems that lack the + fexecve(2) system call when the directory in which the command is located + is writable by the user. See the description of the _f_d_e_x_e_c setting for + more information on how ssuuddoo executes commands that have an associated + digest. + + Command digests are only supported by version 1.8.7 or higher. + + DDeeffaauullttss + Certain configuration options may be changed from their default values at + run-time via one or more Default_Entry lines. These may affect all users + on any host, all users on a specific host, a specific user, a specific + command, or commands being run as a specific user. Note that per-command + entries may not include command line arguments. If you need to specify + arguments, define a Cmnd_Alias and reference that instead. + + Default_Type ::= 'Defaults' | + 'Defaults' '@' Host_List | + 'Defaults' ':' User_List | + 'Defaults' '!' Cmnd_List | + 'Defaults' '>' Runas_List + + Default_Entry ::= Default_Type Parameter_List + + Parameter_List ::= Parameter | + Parameter ',' Parameter_List + + Parameter ::= Parameter '=' Value | + Parameter '+=' Value | + Parameter '-=' Value | + '!'* Parameter + + Parameters may be ffllaaggss, iinntteeggeerr values, ssttrriinnggss, or lliissttss. Flags are + implicitly boolean and can be turned off via the `!' operator. Some + integer, string and list parameters may also be used in a boolean context + to disable them. Values may be enclosed in double quotes ("") when they + contain multiple words. Special characters may be escaped with a + backslash (`\'). + + Lists have two additional assignment operators, += and -=. These + operators are used to add to and delete from a list respectively. It is + not an error to use the -= operator to remove an element that does not + exist in a list. + + Defaults entries are parsed in the following order: generic, host, user + and runas Defaults first, then command defaults. If there are multiple + Defaults settings of the same type, the last matching setting is used. + The following Defaults settings are parsed before all others since they + may affect subsequent entries: _f_q_d_n, _g_r_o_u_p___p_l_u_g_i_n, _r_u_n_a_s___d_e_f_a_u_l_t, + _s_u_d_o_e_r_s___l_o_c_a_l_e. + + See _S_U_D_O_E_R_S _O_P_T_I_O_N_S for a list of supported Defaults parameters. + + UUsseerr ssppeecciiffiiccaattiioonn + User_Spec ::= User_List Host_List '=' Cmnd_Spec_List \ + (':' Host_List '=' Cmnd_Spec_List)* + + Cmnd_Spec_List ::= Cmnd_Spec | + Cmnd_Spec ',' Cmnd_Spec_List + + Cmnd_Spec ::= Runas_Spec? Option_Spec* Tag_Spec* Cmnd + + Runas_Spec ::= '(' Runas_List? (':' Runas_List)? ')' + + Option_Spec ::= (SELinux_Spec | Solaris_Priv_Spec | Date_Spec | Timeout_Spec) + + SELinux_Spec ::= ('ROLE=role' | 'TYPE=type') + + Solaris_Priv_Spec ::= ('PRIVS=privset' | 'LIMITPRIVS=privset') + + Date_Spec ::= ('NOTBEFORE=timestamp' | 'NOTAFTER=timestamp') + + Timeout_Spec ::= 'TIMEOUT=timeout' + + Tag_Spec ::= ('EXEC:' | 'NOEXEC:' | 'FOLLOW:' | 'NOFOLLOW' | + 'LOG_INPUT:' | 'NOLOG_INPUT:' | 'LOG_OUTPUT:' | + 'NOLOG_OUTPUT:' | 'MAIL:' | 'NOMAIL:' | 'PASSWD:' | + 'NOPASSWD:' | 'SETENV:' | 'NOSETENV:') + + A uusseerr ssppeecciiffiiccaattiioonn determines which commands a user may run (and as + what user) on specified hosts. By default, commands are run as rroooott, but + this can be changed on a per-command basis. + + The basic structure of a user specification is "who where = (as_whom) + what". Let's break that down into its constituent parts: + + RRuunnaass__SSppeecc + A Runas_Spec determines the user and/or the group that a command may be + run as. A fully-specified Runas_Spec consists of two Runas_Lists (as + defined above) separated by a colon (`:') and enclosed in a set of + parentheses. The first Runas_List indicates which users the command may + be run as via ssuuddoo's --uu option. The second defines a list of groups that + can be specified via ssuuddoo's --gg option in addition to any of the target + user's groups. If both Runas_Lists are specified, the command may be run + with any combination of users and groups listed in their respective + Runas_Lists. If only the first is specified, the command may be run as + any user in the list but no --gg option may be specified. If the first + Runas_List is empty but the second is specified, the command may be run + as the invoking user with the group set to any listed in the Runas_List. + If both Runas_Lists are empty, the command may only be run as the + invoking user. If no Runas_Spec is specified the command may be run as + rroooott and no group may be specified. + + A Runas_Spec sets the default for the commands that follow it. What this + means is that for the entry: + + dgb boulder = (operator) /bin/ls, /bin/kill, /usr/bin/lprm + + The user ddggbb may run _/_b_i_n_/_l_s, _/_b_i_n_/_k_i_l_l, and _/_u_s_r_/_b_i_n_/_l_p_r_m on the host + boulder--but only as ooppeerraattoorr. E.g., + + $ sudo -u operator /bin/ls + + It is also possible to override a Runas_Spec later on in an entry. If we + modify the entry like so: + + dgb boulder = (operator) /bin/ls, (root) /bin/kill, /usr/bin/lprm + + Then user ddggbb is now allowed to run _/_b_i_n_/_l_s as ooppeerraattoorr, but _/_b_i_n_/_k_i_l_l + and _/_u_s_r_/_b_i_n_/_l_p_r_m as rroooott. + + We can extend this to allow ddggbb to run /bin/ls with either the user or + group set to ooppeerraattoorr: + + dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\ + /usr/bin/lprm + + Note that while the group portion of the Runas_Spec permits the user to + run as command with that group, it does not force the user to do so. If + no group is specified on the command line, the command will run with the + group listed in the target user's password database entry. The following + would all be permitted by the sudoers entry above: + + $ sudo -u operator /bin/ls + $ sudo -u operator -g operator /bin/ls + $ sudo -g operator /bin/ls + + In the following example, user ttccmm may run commands that access a modem + device file with the dialer group. + + tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\ + /usr/local/bin/minicom + + Note that in this example only the group will be set, the command still + runs as user ttccmm. E.g. + + $ sudo -g dialer /usr/bin/cu + + Multiple users and groups may be present in a Runas_Spec, in which case + the user may select any combination of users and groups via the --uu and --gg + options. In this example: + + alan ALL = (root, bin : operator, system) ALL + + user aallaann may run any command as either user root or bin, optionally + setting the group to operator or system. + + OOppttiioonn__SSppeecc + A Cmnd may have zero or more options associated with it. Options may + consist of SELinux roles and/or types, Solaris privileges sets, start + and/or end dates and command timeouts. Once an option is set for a Cmnd, + subsequent Cmnds in the Cmnd_Spec_List, inherit that option unless it is + overridden by another option. + + SSEELLiinnuuxx__SSppeecc + On systems with SELinux support, _s_u_d_o_e_r_s file entries may optionally have + an SELinux role and/or type associated with a command. If a role or type + is specified with the command it will override any default values + specified in _s_u_d_o_e_r_s. A role or type specified on the command line, + however, will supersede the values in _s_u_d_o_e_r_s. + + SSoollaarriiss__PPrriivv__SSppeecc + On Solaris systems, _s_u_d_o_e_r_s file entries may optionally specify Solaris + privilege set and/or limit privilege set associated with a command. If + privileges or limit privileges are specified with the command it will + override any default values specified in _s_u_d_o_e_r_s. + + A privilege set is a comma-separated list of privilege names. The + ppriv(1) command can be used to list all privileges known to the system. + For example: + + $ ppriv -l + + In addition, there are several "special" privilege strings: + + none the empty set + + all the set of all privileges + + zone the set of all privileges available in the current zone + + basic the default set of privileges normal users are granted at login + time + + Privileges can be excluded from a set by prefixing the privilege name + with either an `!' or `-' character. + + DDaattee__SSppeecc + ssuuddooeerrss rules can be specified with a start and end date via the + NOTBEFORE and NOTAFTER settings. The time stamp must be specified in + _G_e_n_e_r_a_l_i_z_e_d _T_i_m_e as defined by RFC 4517. The format is effectively + yyyymmddHHMMSSZ where the minutes and seconds are optional. The `Z' + suffix indicates that the time stamp is in Coordinated Universal Time + (UTC). It is also possible to specify a timezone offset from UTC in + hours and minutes instead of a `Z'. For example, `-0500' would + correspond to Eastern Standard time in the US. As an extension, if no + `Z' or timezone offset is specified, local time will be used. + + The following are all valid time stamps: + + 20170214083000Z + 2017021408Z + 20160315220000-0500 + 20151201235900 + + TTiimmeeoouutt__SSppeecc + A command may have a timeout associated with it. If the timeout expires + before the command has exited, the command will be terminated. The + timeout may be specified in combinations of days, hours, minutes and + seconds with a single-letter case-insensitive suffix that indicates the + unit of time. For example, a timeout of 7 days, 8 hours, 30 minutes and + 10 seconds would be written as 7d8h30m10s. If a number is specified + without a unit, seconds are assumed. Any of the days, minutes, hours or + seconds may be omitted. The order must be from largest to smallest unit + and a unit may not be specified more than once. + + The following are all _v_a_l_i_d timeout values: 7d8h30m10s, 14d, 8h30m, 600s, + 3600. The following are _i_n_v_a_l_i_d timeout values: 12m2w1d, 30s10m4h, + 1d2d3h. + + This option is only supported by version 1.8.20 or higher. + + TTaagg__SSppeecc + A command may have zero or more tags associated with it. The following + tag values are supported: EXEC, NOEXEC, FOLLOW, NOFOLLOW, LOG_INPUT, + NOLOG_INPUT, LOG_OUTPUT, NOLOG_OUTPUT, MAIL, NOMAIL, PASSWD, NOPASSWD, + SETENV, and NOSETENV. Once a tag is set on a Cmnd, subsequent Cmnds in + the Cmnd_Spec_List, inherit the tag unless it is overridden by the + opposite tag (in other words, PASSWD overrides NOPASSWD and NOEXEC + overrides EXEC). + + _E_X_E_C and _N_O_E_X_E_C + + If ssuuddoo has been compiled with _n_o_e_x_e_c support and the underlying + operating system supports it, the NOEXEC tag can be used to prevent a + dynamically-linked executable from running further commands itself. + + In the following example, user aaaarroonn may run _/_u_s_r_/_b_i_n_/_m_o_r_e and + _/_u_s_r_/_b_i_n_/_v_i but shell escapes will be disabled. + + aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi + + See the _P_r_e_v_e_n_t_i_n_g _s_h_e_l_l _e_s_c_a_p_e_s section below for more details on how + NOEXEC works and whether or not it will work on your system. + + _F_O_L_L_O_W and _N_O_F_O_L_L_O_W Starting with version 1.8.15, ssuuddooeeddiitt will not open + a file that is a symbolic link unless the _s_u_d_o_e_d_i_t___f_o_l_l_o_w option is + enabled. The _F_O_L_L_O_W and _N_O_F_O_L_L_O_W tags override the value of + _s_u_d_o_e_d_i_t___f_o_l_l_o_w and can be used to permit (or deny) the editing of + symbolic links on a per-command basis. These tags are only effective + for the _s_u_d_o_e_d_i_t command and are ignored for all other commands. + + _L_O_G___I_N_P_U_T and _N_O_L_O_G___I_N_P_U_T + + These tags override the value of the _l_o_g___i_n_p_u_t option on a per-command + basis. For more information, see the description of _l_o_g___i_n_p_u_t in the + _S_U_D_O_E_R_S _O_P_T_I_O_N_S section below. + + _L_O_G___O_U_T_P_U_T and _N_O_L_O_G___O_U_T_P_U_T + + These tags override the value of the _l_o_g___o_u_t_p_u_t option on a per-command + basis. For more information, see the description of _l_o_g___o_u_t_p_u_t in the + _S_U_D_O_E_R_S _O_P_T_I_O_N_S section below. + + _M_A_I_L and _N_O_M_A_I_L + + These tags provide fine-grained control over whether mail will be sent + when a user runs a command by overriding the value of the + _m_a_i_l___a_l_l___c_m_n_d_s option on a per-command basis. They have no effect when + ssuuddoo is run with the --ll or --vv options. A _N_O_M_A_I_L tag will also override + the _m_a_i_l___a_l_w_a_y_s and _m_a_i_l___n_o___p_e_r_m_s options. For more information, see + the descriptions of _m_a_i_l___a_l_l___c_m_n_d_s, _m_a_i_l___a_l_w_a_y_s, and _m_a_i_l___n_o___p_e_r_m_s in + the _S_U_D_O_E_R_S _O_P_T_I_O_N_S section below. + + _P_A_S_S_W_D and _N_O_P_A_S_S_W_D + + By default, ssuuddoo requires that a user authenticate him or herself + before running a command. This behavior can be modified via the + NOPASSWD tag. Like a Runas_Spec, the NOPASSWD tag sets a default for + the commands that follow it in the Cmnd_Spec_List. Conversely, the + PASSWD tag can be used to reverse things. For example: + + ray rushmore = NOPASSWD: /bin/kill, /bin/ls, /usr/bin/lprm + + would allow the user rraayy to run _/_b_i_n_/_k_i_l_l, _/_b_i_n_/_l_s, and _/_u_s_r_/_b_i_n_/_l_p_r_m + as rroooott on the machine rushmore without authenticating himself. If we + only want rraayy to be able to run _/_b_i_n_/_k_i_l_l without a password the entry + would be: + + ray rushmore = NOPASSWD: /bin/kill, PASSWD: /bin/ls, /usr/bin/lprm + + Note, however, that the PASSWD tag has no effect on users who are in + the group specified by the _e_x_e_m_p_t___g_r_o_u_p option. + + By default, if the NOPASSWD tag is applied to any of the entries for a + user on the current host, he or she will be able to run "sudo -l" + without a password. Additionally, a user may only run "sudo -v" + without a password if the NOPASSWD tag is present for all a user's + entries that pertain to the current host. This behavior may be + overridden via the _v_e_r_i_f_y_p_w and _l_i_s_t_p_w options. + + _S_E_T_E_N_V and _N_O_S_E_T_E_N_V + + These tags override the value of the _s_e_t_e_n_v option on a per-command + basis. Note that if SETENV has been set for a command, the user may + disable the _e_n_v___r_e_s_e_t option from the command line via the --EE option. + Additionally, environment variables set on the command line are not + subject to the restrictions imposed by _e_n_v___c_h_e_c_k, _e_n_v___d_e_l_e_t_e, or + _e_n_v___k_e_e_p. As such, only trusted users should be allowed to set + variables in this manner. If the command matched is AALLLL, the SETENV + tag is implied for that command; this default may be overridden by use + of the NOSETENV tag. + + WWiillddccaarrddss + ssuuddoo allows shell-style _w_i_l_d_c_a_r_d_s (aka meta or glob characters) to be + used in host names, path names and command line arguments in the _s_u_d_o_e_r_s + file. Wildcard matching is done via the glob(3) and fnmatch(3) functions + as specified by IEEE Std 1003.1 ("POSIX.1"). + + * Matches any set of zero or more characters (including white + space). + + ? Matches any single character (including white space). + + [...] Matches any character in the specified range. + + [!...] Matches any character _n_o_t in the specified range. + + \x For any character `x', evaluates to `x'. This is used to + escape special characters such as: `*', `?', `[', and `]'. + + NNoottee tthhaatt tthheessee aarree nnoott rreegguullaarr eexxpprreessssiioonnss.. Unlike a regular expression + there is no way to match one or more characters within a range. + + Character classes may be used if your system's glob(3) and fnmatch(3) + functions support them. However, because the `:' character has special + meaning in _s_u_d_o_e_r_s, it must be escaped. For example: + + /bin/ls [[\:alpha\:]]* + + Would match any file name beginning with a letter. + + Note that a forward slash (`/') will _n_o_t be matched by wildcards used in + the file name portion of the command. This is to make a path like: + + /usr/bin/* + + match _/_u_s_r_/_b_i_n_/_w_h_o but not _/_u_s_r_/_b_i_n_/_X_1_1_/_x_t_e_r_m. + + When matching the command line arguments, however, a slash _d_o_e_s get + matched by wildcards since command line arguments may contain arbitrary + strings and not just path names. + + WWiillddccaarrddss iinn ccoommmmaanndd lliinnee aarrgguummeennttss sshhoouulldd bbee uusseedd wwiitthh ccaarree.. + Command line arguments are matched as a single, concatenated string. + This mean a wildcard character such as `?' or `*' will match across word + boundaries, which may be unexpected. For example, while a sudoers entry + like: + + %operator ALL = /bin/cat /var/log/messages* + + will allow command like: + + $ sudo cat /var/log/messages.1 + + It will also allow: + + $ sudo cat /var/log/messages /etc/shadow + + which is probably not what was intended. In most cases it is better to + do command line processing outside of the _s_u_d_o_e_r_s file in a scripting + language. + + EExxcceeppttiioonnss ttoo wwiillddccaarrdd rruulleess + The following exceptions apply to the above rules: + + "" If the empty string "" is the only command line argument in the + _s_u_d_o_e_r_s file entry it means that command is not allowed to be + run with _a_n_y arguments. + + sudoedit Command line arguments to the _s_u_d_o_e_d_i_t built-in command should + always be path names, so a forward slash (`/') will not be + matched by a wildcard. + + IInncclluuddiinngg ootthheerr ffiilleess ffrroomm wwiitthhiinn ssuuddooeerrss + It is possible to include other _s_u_d_o_e_r_s files from within the _s_u_d_o_e_r_s + file currently being parsed using the #include and #includedir + directives. + + This can be used, for example, to keep a site-wide _s_u_d_o_e_r_s file in + addition to a local, per-machine file. For the sake of this example the + site-wide _s_u_d_o_e_r_s file will be _/_e_t_c_/_s_u_d_o_e_r_s and the per-machine one will + be _/_e_t_c_/_s_u_d_o_e_r_s_._l_o_c_a_l. To include _/_e_t_c_/_s_u_d_o_e_r_s_._l_o_c_a_l from within + _/_e_t_c_/_s_u_d_o_e_r_s we would use the following line in _/_e_t_c_/_s_u_d_o_e_r_s: + + #include /etc/sudoers.local + + When ssuuddoo reaches this line it will suspend processing of the current + file (_/_e_t_c_/_s_u_d_o_e_r_s) and switch to _/_e_t_c_/_s_u_d_o_e_r_s_._l_o_c_a_l. Upon reaching the + end of _/_e_t_c_/_s_u_d_o_e_r_s_._l_o_c_a_l, the rest of _/_e_t_c_/_s_u_d_o_e_r_s will be processed. + Files that are included may themselves include other files. A hard limit + of 128 nested include files is enforced to prevent include file loops. + + If the path to the include file is not fully-qualified (does not begin + with a `/'), it must be located in the same directory as the sudoers file + it was included from. For example, if _/_e_t_c_/_s_u_d_o_e_r_s contains the line: + + #include sudoers.local + + the file that will be included is _/_e_t_c_/_s_u_d_o_e_r_s_._l_o_c_a_l. + + The file name may also include the %h escape, signifying the short form + of the host name. In other words, if the machine's host name is + "xerxes", then + + #include /etc/sudoers.%h + + will cause ssuuddoo to include the file _/_e_t_c_/_s_u_d_o_e_r_s_._x_e_r_x_e_s. + + The #includedir directive can be used to create a _s_u_d_o_e_r_s_._d directory + that the system package manager can drop _s_u_d_o_e_r_s file rules into as part + of package installation. For example, given: + + #includedir /etc/sudoers.d + + ssuuddoo will suspend processing of the current file and read each file in + _/_e_t_c_/_s_u_d_o_e_r_s_._d, skipping file names that end in `~' or contain a `.' + character to avoid causing problems with package manager or editor + temporary/backup files. Files are parsed in sorted lexical order. That + is, _/_e_t_c_/_s_u_d_o_e_r_s_._d_/_0_1___f_i_r_s_t will be parsed before + _/_e_t_c_/_s_u_d_o_e_r_s_._d_/_1_0___s_e_c_o_n_d. Be aware that because the sorting is lexical, + not numeric, _/_e_t_c_/_s_u_d_o_e_r_s_._d_/_1___w_h_o_o_p_s would be loaded _a_f_t_e_r + _/_e_t_c_/_s_u_d_o_e_r_s_._d_/_1_0___s_e_c_o_n_d. Using a consistent number of leading zeroes in + the file names can be used to avoid such problems. After parsing the + files in the directory, control returns to the file that contained the + #includedir directive. + + Note that unlike files included via #include, vviissuuddoo will not edit the + files in a #includedir directory unless one of them contains a syntax + error. It is still possible to run vviissuuddoo with the --ff flag to edit the + files directly, but this will not catch the redefinition of an _a_l_i_a_s that + is also present in a different file. + + OOtthheerr ssppeecciiaall cchhaarraacctteerrss aanndd rreesseerrvveedd wwoorrddss + The pound sign (`#') is used to indicate a comment (unless it is part of + a #include directive or unless it occurs in the context of a user name + and is followed by one or more digits, in which case it is treated as a + uid). Both the comment character and any text after it, up to the end of + the line, are ignored. + + The reserved word AALLLL is a built-in _a_l_i_a_s that always causes a match to + succeed. It can be used wherever one might otherwise use a Cmnd_Alias, + User_Alias, Runas_Alias, or Host_Alias. You should not try to define + your own _a_l_i_a_s called AALLLL as the built-in alias will be used in + preference to your own. Please note that using AALLLL can be dangerous + since in a command context, it allows the user to run _a_n_y command on the + system. + + An exclamation point (`!') can be used as a logical _n_o_t operator in a + list or _a_l_i_a_s as well as in front of a Cmnd. This allows one to exclude + certain values. For the `!' operator to be effective, there must be + something for it to exclude. For example, to match all users except for + root one would use: + + ALL,!root + + If the AALLLL, is omitted, as in: + + !root + + it would explicitly deny root but not match any other users. This is + different from a true "negation" operator. + + Note, however, that using a `!' in conjunction with the built-in AALLLL + alias to allow a user to run "all but a few" commands rarely works as + intended (see _S_E_C_U_R_I_T_Y _N_O_T_E_S below). + + Long lines can be continued with a backslash (`\') as the last character + on the line. + + White space between elements in a list as well as special syntactic + characters in a _U_s_e_r _S_p_e_c_i_f_i_c_a_t_i_o_n (`=', `:', `(', `)') is optional. + + The following characters must be escaped with a backslash (`\') when used + as part of a word (e.g., a user name or host name): `!', `=', `:', `,', + `(', `)', `\'. + +SSUUDDOOEERRSS OOPPTTIIOONNSS + ssuuddoo's behavior can be modified by Default_Entry lines, as explained + earlier. A list of all supported Defaults parameters, grouped by type, + are listed below. + + BBoooolleeaann FFllaaggss: + + always_query_group_plugin + If a _g_r_o_u_p___p_l_u_g_i_n is configured, use it to resolve + groups of the form %group as long as there is not also + a system group of the same name. Normally, only groups + of the form %:group are passed to the _g_r_o_u_p___p_l_u_g_i_n. + This flag is _o_f_f by default. + + always_set_home If enabled, ssuuddoo will set the HOME environment variable + to the home directory of the target user (which is root + unless the --uu option is used). This effectively means + that the --HH option is always implied. Note that by + default, HOME will be set to the home directory of the + target user when the _e_n_v___r_e_s_e_t option is enabled, so + _a_l_w_a_y_s___s_e_t___h_o_m_e only has an effect for configurations + where either _e_n_v___r_e_s_e_t is disabled or HOME is present + in the _e_n_v___k_e_e_p list. This flag is _o_f_f by default. + + authenticate If set, users must authenticate themselves via a + password (or other means of authentication) before they + may run commands. This default may be overridden via + the PASSWD and NOPASSWD tags. This flag is _o_n by + default. + + case_insensitive_group + If enabled, group names in _s_u_d_o_e_r_s will be matched in a + case insensitive manner. This may be necessary when + users are stored in LDAP or AD. This flag is _o_n by + default. + + case_insensitive_user + If enabled, user names in _s_u_d_o_e_r_s will be matched in a + case insensitive manner. This may be necessary when + groups are stored in LDAP or AD. This flag is _o_n by + default. + + closefrom_override + If set, the user may use ssuuddoo's --CC option which + overrides the default starting point at which ssuuddoo + begins closing open file descriptors. This flag is _o_f_f + by default. + + compress_io If set, and ssuuddoo is configured to log a command's input + or output, the I/O logs will be compressed using zzlliibb. + This flag is _o_n by default when ssuuddoo is compiled with + zzlliibb support. + + exec_background By default, ssuuddoo runs a command as the foreground + process as long as ssuuddoo itself is running in the + foreground. When the _e_x_e_c___b_a_c_k_g_r_o_u_n_d flag is enabled + and the command is being run in a pty (due to I/O + logging or the _u_s_e___p_t_y flag), the command will be run + as a background process. Attempts to read from the + controlling terminal (or to change terminal settings) + will result in the command being suspended with the + SIGTTIN signal (or SIGTTOU in the case of terminal + settings). If this happens when ssuuddoo is a foreground + process, the command will be granted the controlling + terminal and resumed in the foreground with no user + intervention required. The advantage of initially + running the command in the background is that ssuuddoo need + not read from the terminal unless the command + explicitly requests it. Otherwise, any terminal input + must be passed to the command, whether it has required + it or not (the kernel buffers terminals so it is not + possible to tell whether the command really wants the + input). This is different from historic _s_u_d_o behavior + or when the command is not being run in a pty. + + For this to work seamlessly, the operating system must + support the automatic restarting of system calls. + Unfortunately, not all operating systems do this by + default, and even those that do may have bugs. For + example, macOS fails to restart the ttccggeettaattttrr() and + ttccsseettaattttrr() system calls (this is a bug in macOS). + Furthermore, because this behavior depends on the + command stopping with the SIGTTIN or SIGTTOU signals, + programs that catch these signals and suspend + themselves with a different signal (usually SIGTOP) + will not be automatically foregrounded. Some versions + of the linux su(1) command behave this way. This flag + is _o_f_f by default. + + This setting is only supported by version 1.8.7 or + higher. It has no effect unless I/O logging is enabled + or the _u_s_e___p_t_y flag is enabled. + + env_editor If set, vviissuuddoo will use the value of the SUDO_EDITOR, + VISUAL or EDITOR environment variables before falling + back on the default editor list. Note that this may + create a security hole as it allows the user to run any + arbitrary command as root without logging. A safer + alternative is to place a colon-separated list of + editors in the _e_d_i_t_o_r variable. vviissuuddoo will then only + use SUDO_EDITOR, VISUAL or EDITOR if they match a value + specified in _e_d_i_t_o_r. If the _e_n_v___r_e_s_e_t flag is enabled, + the SUDO_EDITOR, VISUAL and/or EDITOR environment + variables must be present in the _e_n_v___k_e_e_p list for the + _e_n_v___e_d_i_t_o_r flag to function when vviissuuddoo is invoked via + ssuuddoo. This flag is _o_f_f by default. + + env_reset If set, ssuuddoo will run the command in a minimal + environment containing the TERM, PATH, HOME, MAIL, + SHELL, LOGNAME, USER and SUDO_* variables. Any + variables in the caller's environment or in the file + specified by the _r_e_s_t_r_i_c_t_e_d___e_n_v___f_i_l_e option that match + the env_keep and env_check lists are then added, + followed by any variables present in the file specified + by the _e_n_v___f_i_l_e option (if any). The contents of the + env_keep and env_check lists, as modified by global + Defaults parameters in _s_u_d_o_e_r_s, are displayed when ssuuddoo + is run by root with the --VV option. If the _s_e_c_u_r_e___p_a_t_h + option is set, its value will be used for the PATH + environment variable. This flag is _o_n by default. + + fast_glob Normally, ssuuddoo uses the glob(3) function to do shell- + style globbing when matching path names. However, + since it accesses the file system, glob(3) can take a + long time to complete for some patterns, especially + when the pattern references a network file system that + is mounted on demand (auto mounted). The _f_a_s_t___g_l_o_b + option causes ssuuddoo to use the fnmatch(3) function, + which does not access the file system to do its + matching. The disadvantage of _f_a_s_t___g_l_o_b is that it is + unable to match relative path names such as _._/_l_s or + _._._/_b_i_n_/_l_s. This has security implications when path + names that include globbing characters are used with + the negation operator, `!', as such rules can be + trivially bypassed. As such, this option should not be + used when the _s_u_d_o_e_r_s file contains rules that contain + negated path names which include globbing characters. + This flag is _o_f_f by default. + + fqdn Set this flag if you want to put fully qualified host + names in the _s_u_d_o_e_r_s file when the local host name (as + returned by the hostname command) does not contain the + domain name. In other words, instead of myhost you + would use myhost.mydomain.edu. You may still use the + short form if you wish (and even mix the two). This + option is only effective when the "canonical" host + name, as returned by the ggeettaaddddrriinnffoo() or + ggeetthhoossttbbyynnaammee() function, is a fully-qualified domain + name. This is usually the case when the system is + configured to use DNS for host name resolution. + + If the system is configured to use the _/_e_t_c_/_h_o_s_t_s file + in preference to DNS, the "canonical" host name may not + be fully-qualified. The order that sources are queried + for host name resolution is usually specified in the + _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f, _/_e_t_c_/_n_e_t_s_v_c_._c_o_n_f, _/_e_t_c_/_h_o_s_t_._c_o_n_f, + or, in some cases, _/_e_t_c_/_r_e_s_o_l_v_._c_o_n_f file. In the + _/_e_t_c_/_h_o_s_t_s file, the first host name of the entry is + considered to be the "canonical" name; subsequent names + are aliases that are not used by ssuuddooeerrss. For example, + the following hosts file line for the machine "xyzzy" + has the fully-qualified domain name as the "canonical" + host name, and the short version as an alias. + + 192.168.1.1 xyzzy.sudo.ws xyzzy + + If the machine's hosts file entry is not formatted + properly, the _f_q_d_n option will not be effective if it + is queried before DNS. + + Beware that when using DNS for host name resolution, + turning on _f_q_d_n requires ssuuddooeerrss to make DNS lookups + which renders ssuuddoo unusable if DNS stops working (for + example if the machine is disconnected from the + network). Also note that just like with the hosts + file, you must use the "canonical" name as DNS knows + it. That is, you may not use a host alias (CNAME + entry) due to performance issues and the fact that + there is no way to get all aliases from DNS. + + This flag is _o_f_f by default. + + ignore_audit_errors + Allow commands to be run even if ssuuddooeerrss cannot write + to the audit log. If enabled, an audit log write + failure is not treated as a fatal error. If disabled, + a command may only be run after the audit event is + successfully written. This flag is only effective on + systems for which ssuuddooeerrss supports audit logging, + including FreeBSD, Linux, macOS and Solaris. This flag + is _o_n by default. + + ignore_dot If set, ssuuddoo will ignore "." or "" (both denoting + current directory) in the PATH environment variable; + the PATH itself is not modified. This flag is _o_f_f by + default. + + ignore_iolog_errors + Allow commands to be run even if ssuuddooeerrss cannot write + to the I/O log. If enabled, an I/O log write failure + is not treated as a fatal error. If disabled, the + command will be terminated if the I/O log cannot be + written to. This flag is _o_f_f by default. + + ignore_logfile_errors + Allow commands to be run even if ssuuddooeerrss cannot write + to the log file. If enabled, a log file write failure + is not treated as a fatal error. If disabled, a + command may only be run after the log file entry is + successfully written. This flag only has an effect + when ssuuddooeerrss is configured to use file-based logging + via the _l_o_g_f_i_l_e option. This flag is _o_n by default. + + ignore_local_sudoers + If set via LDAP, parsing of _/_e_t_c_/_s_u_d_o_e_r_s will be + skipped. This is intended for Enterprises that wish to + prevent the usage of local sudoers files so that only + LDAP is used. This thwarts the efforts of rogue + operators who would attempt to add roles to + _/_e_t_c_/_s_u_d_o_e_r_s. When this option is present, + _/_e_t_c_/_s_u_d_o_e_r_s does not even need to exist. Since this + option tells ssuuddoo how to behave when no specific LDAP + entries have been matched, this sudoOption is only + meaningful for the cn=defaults section. This flag is + _o_f_f by default. + + ignore_unknown_defaults + If set, ssuuddoo will not produce a warning if it + encounters an unknown Defaults entry in the _s_u_d_o_e_r_s + file or an unknown sudoOption in LDAP. This flag is + _o_f_f by default. + + insults If set, ssuuddoo will insult users when they enter an + incorrect password. This flag is _o_f_f by default. + + log_host If set, the host name will be logged in the (non- + syslog) ssuuddoo log file. This flag is _o_f_f by default. + + log_input If set, ssuuddoo will run the command in a pseudo-tty and + log all user input. If the standard input is not + connected to the user's tty, due to I/O redirection or + because the command is part of a pipeline, that input + is also captured and stored in a separate log file. + Anything sent to the standard input will be consumed, + regardless of whether or not the command run via ssuuddoo + is actually reading the standard input. This may have + unexpected results when using ssuuddoo in a shell script + that expects to process the standard input. For more + information about I/O logging, see the _I_/_O _L_O_G _F_I_L_E_S + section. This flag is _o_f_f by default. + + log_output If set, ssuuddoo will run the command in a pseudo-tty and + log all output that is sent to the screen, similar to + the script(1) command. For more information about I/O + logging, see the _I_/_O _L_O_G _F_I_L_E_S section. This flag is + _o_f_f by default. + + log_year If set, the four-digit year will be logged in the (non- + syslog) ssuuddoo log file. This flag is _o_f_f by default. + + long_otp_prompt When validating with a One Time Password (OTP) scheme + such as SS//KKeeyy or OOPPIIEE, a two-line prompt is used to + make it easier to cut and paste the challenge to a + local window. It's not as pretty as the default but + some people find it more convenient. This flag is _o_f_f + by default. + + mail_all_cmnds Send mail to the _m_a_i_l_t_o user every time a user attempts + to run a command via ssuuddoo (this includes ssuuddooeeddiitt). No + mail will be sent if the user runs ssuuddoo with the --ll or + --vv option unless there is an authentication error and + the _m_a_i_l___b_a_d_p_a_s_s flag is also set. This flag is _o_f_f by + default. + + mail_always Send mail to the _m_a_i_l_t_o user every time a user runs + ssuuddoo. This flag is _o_f_f by default. + + mail_badpass Send mail to the _m_a_i_l_t_o user if the user running ssuuddoo + does not enter the correct password. If the command + the user is attempting to run is not permitted by + ssuuddooeerrss and one of the _m_a_i_l___a_l_l___c_m_n_d_s, _m_a_i_l___a_l_w_a_y_s, + _m_a_i_l___n_o___h_o_s_t, _m_a_i_l___n_o___p_e_r_m_s or _m_a_i_l___n_o___u_s_e_r flags are + set, this flag will have no effect. This flag is _o_f_f + by default. + + mail_no_host If set, mail will be sent to the _m_a_i_l_t_o user if the + invoking user exists in the _s_u_d_o_e_r_s file, but is not + allowed to run commands on the current host. This flag + is _o_f_f by default. + + mail_no_perms If set, mail will be sent to the _m_a_i_l_t_o user if the + invoking user is allowed to use ssuuddoo but the command + they are trying is not listed in their _s_u_d_o_e_r_s file + entry or is explicitly denied. This flag is _o_f_f by + default. + + mail_no_user If set, mail will be sent to the _m_a_i_l_t_o user if the + invoking user is not in the _s_u_d_o_e_r_s file. This flag is + _o_n by default. + + match_group_by_gid + By default, ssuuddooeerrss will look up each group the user is + a member of by group ID to determine the group name + (this is only done once). The resulting list of the + user's group names is used when matching groups listed + in the _s_u_d_o_e_r_s file. This works well on systems where + the number of groups listed in the _s_u_d_o_e_r_s file is + larger than the number of groups a typical user belongs + to. On systems where group lookups are slow, where + users may belong to a large number of groups, and where + the number of groups listed in the _s_u_d_o_e_r_s file is + relatively small, it may be prohibitively expensive and + running commands via ssuuddoo may take longer than normal. + On such systems it may be faster to use the + _m_a_t_c_h___g_r_o_u_p___b_y___g_i_d flag to avoid resolving the user's + group IDs to group names. In this case, ssuuddooeerrss must + look up any group name listed in the _s_u_d_o_e_r_s file and + use the group ID instead of the group name when + determining whether the user is a member of the group. + + Note that if _m_a_t_c_h___g_r_o_u_p___b_y___g_i_d is enabled, group + database lookups performed by ssuuddooeerrss will be keyed by + group name as opposed to group ID. On systems where + there are multiple sources for the group database, it + is possible to have conflicting group names or group + IDs in the local _/_e_t_c_/_g_r_o_u_p file and the remote group + database. On such systems, enabling or disabling + _m_a_t_c_h___g_r_o_u_p___b_y___g_i_d can be used to choose whether group + database queries are performed by name (enabled) or ID + (disabled), which may aid in working around group entry + conflicts. + + The _m_a_t_c_h___g_r_o_u_p___b_y___g_i_d flag has no effect when _s_u_d_o_e_r_s + data is stored in LDAP. This flag is _o_f_f by default. + + This setting is only supported by version 1.8.18 or + higher. + + netgroup_tuple If set, netgroup lookups will be performed using the + full netgroup tuple: host name, user name and domain + (if one is set). Historically, ssuuddoo only matched the + user name and domain for netgroups used in a User_List + and only matched the host name and domain for netgroups + used in a Host_List. This flag is _o_f_f by default. + + noexec If set, all commands run via ssuuddoo will behave as if the + NOEXEC tag has been set, unless overridden by an EXEC + tag. See the description of _E_X_E_C _a_n_d _N_O_E_X_E_C above as + well as the _P_r_e_v_e_n_t_i_n_g _s_h_e_l_l _e_s_c_a_p_e_s section at the end + of this manual. This flag is _o_f_f by default. + + pam_session On systems that use PAM for authentication, ssuuddoo will + create a new PAM session for the command to be run in. + Disabling _p_a_m___s_e_s_s_i_o_n may be needed on older PAM + implementations or on operating systems where opening a + PAM session changes the utmp or wtmp files. If PAM + session support is disabled, resource limits may not be + updated for the command being run. If _p_a_m___s_e_s_s_i_o_n, + _p_a_m___s_e_t_c_r_e_d, and _u_s_e___p_t_y are disabled and I/O logging + has not been configured, ssuuddoo will execute the command + directly instead of running it as a child process. + This flag is _o_n by default. + + This setting is only supported by version 1.8.7 or + higher. + + pam_setcred On systems that use PAM for authentication, ssuuddoo will + attempt to establish credentials for the target user by + default, if supported by the underlying authentication + system. One example of a credential is a Kerberos + ticket. If _p_a_m___s_e_s_s_i_o_n, _p_a_m___s_e_t_c_r_e_d, and _u_s_e___p_t_y are + disabled and I/O logging has not been configured, ssuuddoo + will execute the command directly instead of running it + as a child process. This flag is _o_n by default. + + This setting is only supported by version 1.8.8 or + higher. + + passprompt_override + If set, the prompt specified by _p_a_s_s_p_r_o_m_p_t or the + SUDO_PROMPT environment variable will always be used + and will replace the prompt provided by a PAM module or + other authentication method. This flag is _o_f_f by + default. + + path_info Normally, ssuuddoo will tell the user when a command could + not be found in their PATH environment variable. Some + sites may wish to disable this as it could be used to + gather information on the location of executables that + the normal user does not have access to. The + disadvantage is that if the executable is simply not in + the user's PATH, ssuuddoo will tell the user that they are + not allowed to run it, which can be confusing. This + flag is _o_n by default. + + preserve_groups By default, ssuuddoo will initialize the group vector to + the list of groups the target user is in. When + _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, the user's existing group + vector is left unaltered. The real and effective group + IDs, however, are still set to match the target user. + This flag is _o_f_f by default. + + pwfeedback By default, ssuuddoo reads the password like most other + Unix programs, by turning off echo until the user hits + the return (or enter) key. Some users become confused + by this as it appears to them that ssuuddoo has hung at + this point. When _p_w_f_e_e_d_b_a_c_k is set, ssuuddoo will provide + visual feedback when the user presses a key. Note that + this does have a security impact as an onlooker may be + able to determine the length of the password being + entered. This flag is _o_f_f by default. + + requiretty If set, ssuuddoo will only run when the user is logged in + to a real tty. When this flag is set, ssuuddoo can only be + run from a login session and not via other means such + as cron(1m) or cgi-bin scripts. This flag is _o_f_f by + default. + + root_sudo If set, root is allowed to run ssuuddoo too. Disabling + this prevents users from "chaining" ssuuddoo commands to + get a root shell by doing something like "sudo sudo + /bin/sh". Note, however, that turning off _r_o_o_t___s_u_d_o + will also prevent root from running ssuuddooeeddiitt. + Disabling _r_o_o_t___s_u_d_o provides no real additional + security; it exists purely for historical reasons. + This flag is _o_n by default. + + rootpw If set, ssuuddoo will prompt for the root password instead + of the password of the invoking user when running a + command or editing a file. This flag is _o_f_f by + default. + + runaspw If set, ssuuddoo will prompt for the password of the user + defined by the _r_u_n_a_s___d_e_f_a_u_l_t option (defaults to root) + instead of the password of the invoking user when + running a command or editing a file. This flag is _o_f_f + by default. + + set_home If enabled and ssuuddoo is invoked with the --ss option the + HOME environment variable will be set to the home + directory of the target user (which is root unless the + --uu option is used). This effectively makes the --ss + option imply --HH. Note that HOME is already set when + the _e_n_v___r_e_s_e_t option is enabled, so _s_e_t___h_o_m_e is only + effective for configurations where either _e_n_v___r_e_s_e_t is + disabled or HOME is present in the _e_n_v___k_e_e_p list. This + flag is _o_f_f by default. + + set_logname Normally, ssuuddoo will set the LOGNAME and USER + environment variables to the name of the target user + (usually root unless the --uu option is given). However, + since some programs (including the RCS revision control + system) use LOGNAME to determine the real identity of + the user, it may be desirable to change this behavior. + This can be done by negating the set_logname option. + Note that _s_e_t___l_o_g_n_a_m_e will have no effect if the + _e_n_v___r_e_s_e_t option has not been disabled and the _e_n_v___k_e_e_p + list contains LOGNAME or USER. This flag is _o_n by + default. + + set_utmp When enabled, ssuuddoo will create an entry in the utmp (or + utmpx) file when a pseudo-tty is allocated. A pseudo- + tty is allocated by ssuuddoo when the _l_o_g___i_n_p_u_t, _l_o_g___o_u_t_p_u_t + or _u_s_e___p_t_y flags are enabled. By default, the new + entry will be a copy of the user's existing utmp entry + (if any), with the tty, time, type and pid fields + updated. This flag is _o_n by default. + + setenv Allow the user to disable the _e_n_v___r_e_s_e_t option from the + command line via the --EE option. Additionally, + environment variables set via the command line are not + subject to the restrictions imposed by _e_n_v___c_h_e_c_k, + _e_n_v___d_e_l_e_t_e, or _e_n_v___k_e_e_p. As such, only trusted users + should be allowed to set variables in this manner. + This flag is _o_f_f by default. + + shell_noargs If set and ssuuddoo is invoked with no arguments it acts as + if the --ss option had been given. That is, it runs a + shell as root (the shell is determined by the SHELL + environment variable if it is set, falling back on the + shell listed in the invoking user's /etc/passwd entry + if not). This flag is _o_f_f by default. + + stay_setuid Normally, when ssuuddoo executes a command the real and + effective UIDs are set to the target user (root by + default). This option changes that behavior such that + the real UID is left as the invoking user's UID. In + other words, this makes ssuuddoo act as a setuid wrapper. + This can be useful on systems that disable some + potentially dangerous functionality when a program is + run setuid. This option is only effective on systems + that support either the setreuid(2) or setresuid(2) + system call. This flag is _o_f_f by default. + + sudoedit_checkdir + If set, ssuuddooeeddiitt will check all directory components of + the path to be edited for writability by the invoking + user. Symbolic links will not be followed in writable + directories and ssuuddooeeddiitt will refuse to edit a file + located in a writable directory. These restrictions + are not enforced when ssuuddooeeddiitt is run by root. On some + systems, if all directory components of the path to be + edited are not readable by the target user, ssuuddooeeddiitt + will be unable to edit the file. This flag is _o_n by + default. + + This setting was first introduced in version 1.8.15 but + initially suffered from a race condition. The check + for symbolic links in writable intermediate directories + was added in version 1.8.16. + + sudoedit_follow By default, ssuuddooeeddiitt will not follow symbolic links + when opening files. The _s_u_d_o_e_d_i_t___f_o_l_l_o_w option can be + enabled to allow ssuuddooeeddiitt to open symbolic links. It + may be overridden on a per-command basis by the _F_O_L_L_O_W + and _N_O_F_O_L_L_O_W tags. This flag is _o_f_f by default. + + This setting is only supported by version 1.8.15 or + higher. + + syslog_pid When logging via syslog(3), include the process ID in + the log entry. This flag is _o_f_f by default. + + This setting is only supported by version 1.8.21 or + higher. + + targetpw If set, ssuuddoo will prompt for the password of the user + specified by the --uu option (defaults to root) instead + of the password of the invoking user when running a + command or editing a file. Note that this flag + precludes the use of a uid not listed in the passwd + database as an argument to the --uu option. This flag is + _o_f_f by default. + + tty_tickets If set, users must authenticate on a per-tty basis. + With this flag enabled, ssuuddoo will use a separate record + in the time stamp file for each terminal. If disabled, + a single record is used for all login sessions. + + This option has been superseded by the _t_i_m_e_s_t_a_m_p___t_y_p_e + option. + + umask_override If set, ssuuddoo will set the umask as specified in the + _s_u_d_o_e_r_s file without modification. This makes it + possible to specify a umask in the _s_u_d_o_e_r_s file that is + more permissive than the user's own umask and matches + historical behavior. If _u_m_a_s_k___o_v_e_r_r_i_d_e is not set, + ssuuddoo will set the umask to be the union of the user's + umask and what is specified in _s_u_d_o_e_r_s. This flag is + _o_f_f by default. + + use_loginclass If set, ssuuddoo will apply the defaults specified for the + target user's login class if one exists. Only + available if ssuuddoo is configured with the + --with-logincap option. This flag is _o_f_f by default. + + use_netgroups If set, netgroups (prefixed with `+'), may be used in + place of a user or host. For LDAP-based sudoers, + netgroup support requires an expensive sub-string match + on the server unless the NNEETTGGRROOUUPP__BBAASSEE directive is + present in the _/_e_t_c_/_l_d_a_p_._c_o_n_f file. If netgroups are + not needed, this option can be disabled to reduce the + load on the LDAP server. This flag is _o_n by default. + + use_pty If set, and ssuuddoo is running in a terminal, the command + will be run in a pseudo-pty (even if no I/O logging is + being done). If the ssuuddoo process is not attached to a + terminal, _u_s_e___p_t_y has no effect. + + A malicious program run under ssuuddoo may be capable of + injecting commands into the user's terminal or running + a background process that retains access to the user's + terminal device even after the main program has + finished executing. By running the command in a + separate pseudo-pty, this attack is no longer possible. + This flag is _o_f_f by default. + + user_command_timeouts + If set, the user may specify a timeout on the command + line. If the timeout expires before the command has + exited, the command will be terminated. If a timeout + is specified both in the _s_u_d_o_e_r_s file and on the + command line, the smaller of the two timeouts will be + used. See the Timeout_Spec section for a description + of the timeout syntax. This flag is _o_f_f by default. + + This setting is only supported by version 1.8.20 or + higher. + + utmp_runas If set, ssuuddoo will store the name of the runas user when + updating the utmp (or utmpx) file. By default, ssuuddoo + stores the name of the invoking user. This flag is _o_f_f + by default. + + visiblepw By default, ssuuddoo will refuse to run if the user must + enter a password but it is not possible to disable echo + on the terminal. If the _v_i_s_i_b_l_e_p_w flag is set, ssuuddoo + will prompt for a password even when it would be + visible on the screen. This makes it possible to run + things like "ssh somehost sudo ls" since by default, + ssh(1) does not allocate a tty when running a command. + This flag is _o_f_f by default. + + IInntteeggeerrss: + + closefrom Before it executes a command, ssuuddoo will close all open + file descriptors other than standard input, standard + output and standard error (ie: file descriptors 0-2). + The _c_l_o_s_e_f_r_o_m option can be used to specify a different + file descriptor at which to start closing. The default + is 3. + + command_timeout The maximum amount of time a command is allowed to run + before it is terminated. See the Timeout_Spec section + for a description of the timeout syntax. + + This setting is only supported by version 1.8.20 or + higher. + + maxseq The maximum sequence number that will be substituted + for the "%{seq}" escape in the I/O log file (see the + _i_o_l_o_g___d_i_r description below for more information). + While the value substituted for "%{seq}" is in base 36, + _m_a_x_s_e_q itself should be expressed in decimal. Values + larger than 2176782336 (which corresponds to the base + 36 sequence number "ZZZZZZ") will be silently truncated + to 2176782336. The default value is 2176782336. + + Once the local sequence number reaches the value of + _m_a_x_s_e_q, it will "roll over" to zero, after which + ssuuddooeerrss will truncate and re-use any existing I/O log + path names. + + This setting is only supported by version 1.8.7 or + higher. + + passwd_tries The number of tries a user gets to enter his/her + password before ssuuddoo logs the failure and exits. The + default is 3. + + syslog_maxlen On many systems, syslog(3) has a relatively small log + buffer. IETF RFC 5424 states that syslog servers must + support messages of at least 480 bytes and should + support messages up to 2048 bytes. By default, ssuuddooeerrss + creates log messages up to 980 bytes which corresponds + to the historic BSD syslog implementation which used a + 1024 byte buffer to store the message, date, hostname + and program name. To prevent syslog messages from + being truncated, ssuuddooeerrss will split up log messages + that are larger than _s_y_s_l_o_g___m_a_x_l_e_n bytes. When a + message is split, additional parts will include the + string "(command continued)" after the user name and + before the continued command line arguments. + + This setting is only supported by version 1.8.19 or + higher. + + IInntteeggeerrss tthhaatt ccaann bbee uusseedd iinn aa bboooolleeaann ccoonntteexxtt: + + loglinelen Number of characters per line for the file log. This + value is used to decide when to wrap lines for nicer + log files. This has no effect on the syslog log file, + only the file log. The default is 80 (use 0 or negate + the option to disable word wrap). + + passwd_timeout Number of minutes before the ssuuddoo password prompt times + out, or 0 for no timeout. The timeout may include a + fractional component if minute granularity is + insufficient, for example 2.5. The default is 5. + + timestamp_timeout + Number of minutes that can elapse before ssuuddoo will ask + for a passwd again. The timeout may include a + fractional component if minute granularity is + insufficient, for example 2.5. The default is 5. Set + this to 0 to always prompt for a password. If set to a + value less than 0 the user's time stamp will not expire + until the system is rebooted. This can be used to + allow users to create or delete their own time stamps + via "sudo -v" and "sudo -k" respectively. + + umask Umask to use when running the command. Negate this + option or set it to 0777 to preserve the user's umask. + The actual umask that is used will be the union of the + user's umask and the value of the _u_m_a_s_k option, which + defaults to 0022. This guarantees that ssuuddoo never + lowers the umask when running a command. Note: on + systems that use PAM, the default PAM configuration may + specify its own umask which will override the value set + in _s_u_d_o_e_r_s. + + SSttrriinnggss: + + authfail_message Message that is displayed after a user fails to + authenticate. The message may include the `%d' escape + which will expand to the number of failed password + attempts. If set, it overrides the default message, %d + incorrect password attempt(s). + + badpass_message Message that is displayed if a user enters an incorrect + password. The default is Sorry, try again. unless + insults are enabled. + + editor A colon (`:') separated list of editors path names used + by ssuuddooeeddiitt and vviissuuddoo. For ssuuddooeeddiitt, this list is + used to find an editor when none of the SUDO_EDITOR, + VISUAL or EDITOR environment variables are set to an + editor that exists and is executable. For vviissuuddoo, it + is used as a white list of allowed editors; vviissuuddoo will + choose the editor that matches the user's SUDO_EDITOR, + VISUAL or EDITOR environment variable if possible, or + the first editor in the list that exists and is + executable if not. Unless invoked as ssuuddooeeddiitt, ssuuddoo + does not preserve the SUDO_EDITOR, VISUAL and EDITOR + environment variables by default, even when the + _e_n_v___r_e_s_e_t option is enabled. The default is _v_i. + + iolog_dir The top-level directory to use when constructing the + path name for the input/output log directory. Only + used if the _l_o_g___i_n_p_u_t or _l_o_g___o_u_t_p_u_t options are enabled + or when the LOG_INPUT or LOG_OUTPUT tags are present + for a command. The session sequence number, if any, is + stored in the directory. The default is + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o. + + The following percent (`%') escape sequences are + supported: + + %{seq} + expanded to a monotonically increasing base-36 + sequence number, such as 0100A5, where every two + digits are used to form a new directory, e.g., + _0_1_/_0_0_/_A_5 + + %{user} + expanded to the invoking user's login name + + %{group} + expanded to the name of the invoking user's real + group ID + + %{runas_user} + expanded to the login name of the user the + command will be run as (e.g., root) + + %{runas_group} + expanded to the group name of the user the + command will be run as (e.g., wheel) + + %{hostname} + expanded to the local host name without the + domain name + + %{command} + expanded to the base name of the command being + run + + In addition, any escape sequences supported by the + system's strftime(3) function will be expanded. + + To include a literal `%' character, the string `%%' + should be used. + + iolog_file The path name, relative to _i_o_l_o_g___d_i_r, in which to store + input/output logs when the _l_o_g___i_n_p_u_t or _l_o_g___o_u_t_p_u_t + options are enabled or when the LOG_INPUT or LOG_OUTPUT + tags are present for a command. Note that _i_o_l_o_g___f_i_l_e + may contain directory components. The default is + "%{seq}". + + See the _i_o_l_o_g___d_i_r option above for a list of supported + percent (`%') escape sequences. + + In addition to the escape sequences, path names that + end in six or more Xs will have the Xs replaced with a + unique combination of digits and letters, similar to + the mktemp(3) function. + + If the path created by concatenating _i_o_l_o_g___d_i_r and + _i_o_l_o_g___f_i_l_e already exists, the existing I/O log file + will be truncated and overwritten unless _i_o_l_o_g___f_i_l_e + ends in six or more Xs. + + iolog_flush If set, ssuuddoo will flush I/O log data to disk after each + write instead of buffering it. This makes it possible + to view the logs in real-time as the program is + executing but may significantly reduce the + effectiveness of I/O log compression. This flag is _o_f_f + by default. + + This setting is only supported by version 1.8.20 or + higher. + + iolog_group The group name to look up when setting the group ID on + new I/O log files and directories. If _i_o_l_o_g___g_r_o_u_p is + not set, the primary group ID of the user specified by + _i_o_l_o_g___u_s_e_r is used. If neither _i_o_l_o_g___g_r_o_u_p nor + _i_o_l_o_g___u_s_e_r are set, I/O log files and directories are + created with group ID 0. + + This setting is only supported by version 1.8.19 or + higher. + + iolog_mode The file mode to use when creating I/O log files. Mode + bits for read and write permissions for owner, group or + other are honored, everything else is ignored. The + file permissions will always include the owner read and + write bits, even if they are not present in the + specified mode. When creating I/O log directories, + search (execute) bits are added to match the read and + write bits specified by _i_o_l_o_g___m_o_d_e. Defaults to 0600 + (read and write by user only). + + This setting is only supported by version 1.8.19 or + higher. + + iolog_user The user name to look up when setting the user and + group IDs on new I/O log files and directories. If + _i_o_l_o_g___g_r_o_u_p is set, it will be used instead of the + user's primary group ID. By default, I/O log files and + directories are created with user and group ID 0. + + This setting can be useful when the I/O logs are stored + on a Network File System (NFS) share. Having a + dedicated user own the I/O log files means that ssuuddooeerrss + does not write to the log files as user ID 0, which is + usually not permitted by NFS. + + This setting is only supported by version 1.8.19 or + higher. + + lecture_status_dir + The directory in which ssuuddoo stores per-user lecture + status files. Once a user has received the lecture, a + zero-length file is created in this directory so that + ssuuddoo will not lecture the user again. This directory + should _n_o_t be cleared when the system reboots. The + default is _/_v_a_r_/_a_d_m_/_s_u_d_o_/_l_e_c_t_u_r_e_d. + + limitprivs The default Solaris limit privileges to use when + constructing a new privilege set for a command. This + bounds all privileges of the executing process. The + default limit privileges may be overridden on a per- + command basis in _s_u_d_o_e_r_s. This option is only + available if ssuuddooeerrss is built on Solaris 10 or higher. + + mailsub Subject of the mail sent to the _m_a_i_l_t_o user. The + escape %h will expand to the host name of the machine. + Default is "*** SECURITY information for %h ***". + + noexec_file As of ssuuddoo version 1.8.1 this option is no longer + supported. The path to the noexec file should now be + set in the sudo.conf(4) file. + + pam_login_service + On systems that use PAM for authentication, this is the + service name used when the --ii option is specified. The + default value is "sudo". See the description of + _p_a_m___s_e_r_v_i_c_e for more information. + + This setting is only supported by version 1.8.8 or + higher. + + pam_service On systems that use PAM for authentication, the service + name specifies the PAM policy to apply. This usually + corresponds to an entry in the _p_a_m_._c_o_n_f file or a file + in the _/_e_t_c_/_p_a_m_._d directory. The default value is + "sudo". + + This setting is only supported by version 1.8.8 or + higher. + + passprompt The default prompt to use when asking for a password; + can be overridden via the --pp option or the SUDO_PROMPT + environment variable. The following percent (`%') + escape sequences are supported: + + %H expanded to the local host name including the + domain name (only if the machine's host name is + fully qualified or the _f_q_d_n option is set) + + %h expanded to the local host name without the + domain name + + %p expanded to the user whose password is being + asked for (respects the _r_o_o_t_p_w, _t_a_r_g_e_t_p_w and + _r_u_n_a_s_p_w flags in _s_u_d_o_e_r_s) + + %U expanded to the login name of the user the + command will be run as (defaults to root) + + %u expanded to the invoking user's login name + + %% two consecutive % characters are collapsed into a + single % character + + On systems that use PAM for authentication, _p_a_s_s_p_r_o_m_p_t + will only be used if the prompt provided by the PAM + module matches the string "Password: " or "username's + Password: ". This ensures that the _p_a_s_s_p_r_o_m_p_t setting + does not interfere with challenge-response style + authentication. The _p_a_s_s_p_r_o_m_p_t___o_v_e_r_r_i_d_e flag can be + used to change this behavior. + + The default value is "Password: ". + + privs The default Solaris privileges to use when constructing + a new privilege set for a command. This is passed to + the executing process via the inherited privilege set, + but is bounded by the limit privileges. If the _p_r_i_v_s + option is specified but the _l_i_m_i_t_p_r_i_v_s option is not, + the limit privileges of the executing process is set to + _p_r_i_v_s. The default privileges may be overridden on a + per-command basis in _s_u_d_o_e_r_s. This option is only + available if ssuuddooeerrss is built on Solaris 10 or higher. + + role The default SELinux role to use when constructing a new + security context to run the command. The default role + may be overridden on a per-command basis in the _s_u_d_o_e_r_s + file or via command line options. This option is only + available when ssuuddoo is built with SELinux support. + + runas_default The default user to run commands as if the --uu option is + not specified on the command line. This defaults to + root. + + sudoers_locale Locale to use when parsing the sudoers file, logging + commands, and sending email. Note that changing the + locale may affect how sudoers is interpreted. Defaults + to "C". + + timestamp_type ssuuddooeerrss uses per-user time stamp files for credential + caching. The _t_i_m_e_s_t_a_m_p___t_y_p_e option can be used to + specify the type of time stamp record used. It has the + following possible values: + + global A single time stamp record is used for all of a + user's login sessions, regardless of the + terminal or parent process ID. An additional + record is used to serialize password prompts + when ssuuddoo is used multiple times in a pipeline, + but this does not affect authentication. + + ppid A single time stamp record is used for all + processes with the same parent process ID + (usually the shell). Commands run from the + same shell (or other common parent process) + will not require a password for + _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t minutes (5 by default). + Commands run via ssuuddoo with a different parent + process ID, for example from a shell script, + will be authenticated separately. + + tty One time stamp record is used for each + terminal, which means that a user's login + sessions are authenticated separately. If no + terminal is present, the behavior is the same + as _p_p_i_d. Commands run from the same terminal + will not require a password for + _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t minutes (5 by default). + + kernel The time stamp is stored in the kernel as an + attribute of the terminal device. If no + terminal is present, the behavior is the same + as _p_p_i_d. Negative _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t values are + not supported and positive values are limited + to a maximum of 60 minutes. This is currently + only supported on OpenBSD. + + The default value is _t_t_y. + + This setting is only supported by version 1.8.21 or + higher. + + timestampdir The directory in which ssuuddoo stores its time stamp + files. This directory should be cleared when the + system reboots. The default is _/_v_a_r_/_r_u_n_/_s_u_d_o_/_t_s. + + timestampowner The owner of the lecture status directory, time stamp + directory and all files stored therein. The default is + root. + + type The default SELinux type to use when constructing a new + security context to run the command. The default type + may be overridden on a per-command basis in the _s_u_d_o_e_r_s + file or via command line options. This option is only + available when ssuuddoo is built with SELinux support. + + SSttrriinnggss tthhaatt ccaann bbee uusseedd iinn aa bboooolleeaann ccoonntteexxtt: + + env_file The _e_n_v___f_i_l_e option specifies the fully qualified path to a + file containing variables to be set in the environment of + the program being run. Entries in this file should either + be of the form "VARIABLE=value" or "export VARIABLE=value". + The value may optionally be surrounded by single or double + quotes. Variables in this file are only added if the + variable does not already exist in the environment. This + file is considered to be part of the security policy, its + contents are not subject to other ssuuddoo environment + restrictions such as _e_n_v___k_e_e_p and _e_n_v___c_h_e_c_k. + + exempt_group Users in this group are exempt from password and PATH + requirements. The group name specified should not include + a % prefix. This is not set by default. + + fdexec Determines whether ssuuddoo will execute a command by its path + or by an open file descriptor. It has the following + possible values: + + always Always execute by file descriptor. + + never Never execute by file descriptor. + + digest_only + Only execute by file descriptor if the command has + an associated digest in the _s_u_d_o_e_r_s file. + + The default value is _d_i_g_e_s_t___o_n_l_y. This avoids a time of + check versus time of use race condition when the command is + located in a directory writable by the invoking user. + + Note that _f_d_e_x_e_c will change the first element of the + argument vector for scripts ($0 in the shell) due to the + way the kernel runs script interpreters. Instead of being + a normal path, it will refer to a file descriptor. For + example, _/_d_e_v_/_f_d_/_4 on Solaris and _/_p_r_o_c_/_s_e_l_f_/_f_d_/_4 on Linux. + A workaround is to use the SUDO_COMMAND environment + variable instead. + + The _f_d_e_x_e_c setting is only used when the command is matched + by path name. It has no effect if the command is matched + by the built-in AALLLL alias. + + This setting is only supported by version 1.8.20 or higher. + If the operating system does not support the fexecve(2) + system call, this setting has no effect. + + group_plugin A string containing a ssuuddooeerrss group plugin with optional + arguments. The string should consist of the plugin path, + either fully-qualified or relative to the + _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o directory, followed by any + configuration arguments the plugin requires. These + arguments (if any) will be passed to the plugin's + initialization function. If arguments are present, the + string must be enclosed in double quotes (""). + + For more information see _G_R_O_U_P _P_R_O_V_I_D_E_R _P_L_U_G_I_N_S. + + lecture This option controls when a short lecture will be printed + along with the password prompt. It has the following + possible values: + + always Always lecture the user. + + never Never lecture the user. + + once Only lecture the user the first time they run ssuuddoo. + + If no value is specified, a value of _o_n_c_e is implied. + Negating the option results in a value of _n_e_v_e_r being used. + The default value is _o_n_c_e. + + lecture_file Path to a file containing an alternate ssuuddoo lecture that + will be used in place of the standard lecture if the named + file exists. By default, ssuuddoo uses a built-in lecture. + + listpw This option controls when a password will be required when + a user runs ssuuddoo with the --ll option. It has the following + possible values: + + all All the user's _s_u_d_o_e_r_s file entries for the + current host must have the NOPASSWD flag set to + avoid entering a password. + + always The user must always enter a password to use the + --ll option. + + any At least one of the user's _s_u_d_o_e_r_s file entries + for the current host must have the NOPASSWD flag + set to avoid entering a password. + + never The user need never enter a password to use the + --ll option. + + If no value is specified, a value of _a_n_y is implied. + Negating the option results in a value of _n_e_v_e_r being used. + The default value is _a_n_y. + + logfile Path to the ssuuddoo log file (not the syslog log file). + Setting a path turns on logging to a file; negating this + option turns it off. By default, ssuuddoo logs via syslog. + + mailerflags Flags to use when invoking mailer. Defaults to --tt. + + mailerpath Path to mail program used to send warning mail. Defaults + to the path to sendmail found at configure time. + + mailfrom Address to use for the "from" address when sending warning + and error mail. The address should be enclosed in double + quotes ("") to protect against ssuuddoo interpreting the @ + sign. Defaults to the name of the user running ssuuddoo. + + mailto Address to send warning and error mail to. The address + should be enclosed in double quotes ("") to protect against + ssuuddoo interpreting the @ sign. Defaults to root. + + restricted_env_file + The _r_e_s_t_r_i_c_t_e_d___e_n_v___f_i_l_e option specifies the fully + qualified path to a file containing variables to be set in + the environment of the program being run. Entries in this + file should either be of the form "VARIABLE=value" or + "export VARIABLE=value". The value may optionally be + surrounded by single or double quotes. Variables in this + file are only added if the variable does not already exist + in the environment. Unlike _e_n_v___f_i_l_e, the file's contents + are not trusted and are processed in a manner similar to + that of the invoking user's environment. If _e_n_v___r_e_s_e_t is + enabled, variables in the file will only be added if they + are matched by either the _e_n_v___c_h_e_c_k or _e_n_v___k_e_e_p list. If + _e_n_v___r_e_s_e_t is disabled, variables in the file are added as + long as they are not matched by the _e_n_v___d_e_l_e_t_e list. In + either case, the contents of _r_e_s_t_r_i_c_t_e_d___e_n_v___f_i_l_e are + processed before the contents of _e_n_v___f_i_l_e. + + secure_path Path used for every command run from ssuuddoo. If you don't + trust the people running ssuuddoo to have a sane PATH + environment variable you may want to use this. Another use + is if you want to have the "root path" be separate from the + "user path". Users in the group specified by the + _e_x_e_m_p_t___g_r_o_u_p option are not affected by _s_e_c_u_r_e___p_a_t_h. This + option is not set by default. + + syslog Syslog facility if syslog is being used for logging (negate + to disable syslog logging). Defaults to auth. + + The following syslog facilities are supported: aauutthhpprriivv (if + your OS supports it), aauutthh, ddaaeemmoonn, uusseerr, llooccaall00, llooccaall11, + llooccaall22, llooccaall33, llooccaall44, llooccaall55, llooccaall66, and llooccaall77. + + syslog_badpri + Syslog priority to use when the user is not allowed to run + a command or when authentication is unsuccessful. Defaults + to alert. + + The following syslog priorities are supported: aalleerrtt, ccrriitt, + ddeebbuugg, eemmeerrgg, eerrrr, iinnffoo, nnoottiiccee, wwaarrnniinngg, and nnoonnee. + Negating the option or setting it to a value of nnoonnee will + disable logging of unsuccessful commands. + + syslog_goodpri + Syslog priority to use when the user is allowed to run a + command and authentication is successful. Defaults to + notice. + + See _s_y_s_l_o_g___b_a_d_p_r_i for the list of supported syslog + priorities. Negating the option or setting it to a value + of nnoonnee will disable logging of successful commands. + + verifypw This option controls when a password will be required when + a user runs ssuuddoo with the --vv option. It has the following + possible values: + + all All the user's _s_u_d_o_e_r_s file entries for the current + host must have the NOPASSWD flag set to avoid + entering a password. + + always The user must always enter a password to use the --vv + option. + + any At least one of the user's _s_u_d_o_e_r_s file entries for + the current host must have the NOPASSWD flag set to + avoid entering a password. + + never The user need never enter a password to use the --vv + option. + + If no value is specified, a value of _a_l_l is implied. + Negating the option results in a value of _n_e_v_e_r being used. + The default value is _a_l_l. + + LLiissttss tthhaatt ccaann bbee uusseedd iinn aa bboooolleeaann ccoonntteexxtt: + + env_check Environment variables to be removed from the user's + environment unless they are considered "safe". For all + variables except TZ, "safe" means that the variable's + value does not contain any `%' or `/' characters. This + can be used to guard against printf-style format + vulnerabilities in poorly-written programs. The TZ + variable is considered unsafe if any of the following + are true: + + ++oo It consists of a fully-qualified path name, + optionally prefixed with a colon (`:'), that does + not match the location of the _z_o_n_e_i_n_f_o directory. + + ++oo It contains a _._. path element. + + ++oo It contains white space or non-printable characters. + + ++oo It is longer than the value of PATH_MAX. + + The argument may be a double-quoted, space-separated + list or a single value without double-quotes. The list + can be replaced, added to, deleted from, or disabled by + using the =, +=, -=, and ! operators respectively. + Regardless of whether the env_reset option is enabled + or disabled, variables specified by env_check will be + preserved in the environment if they pass the + aforementioned check. The global list of environment + variables to check is displayed when ssuuddoo is run by + root with the --VV option. + + env_delete Environment variables to be removed from the user's + environment when the _e_n_v___r_e_s_e_t option is not in effect. + The argument may be a double-quoted, space-separated + list or a single value without double-quotes. The list + can be replaced, added to, deleted from, or disabled by + using the =, +=, -=, and ! operators respectively. The + global list of environment variables to remove is + displayed when ssuuddoo is run by root with the --VV option. + Note that many operating systems will remove + potentially dangerous variables from the environment of + any setuid process (such as ssuuddoo). + + env_keep Environment variables to be preserved in the user's + environment when the _e_n_v___r_e_s_e_t option is in effect. + This allows fine-grained control over the environment + ssuuddoo-spawned processes will receive. The argument may + be a double-quoted, space-separated list or a single + value without double-quotes. The list can be replaced, + added to, deleted from, or disabled by using the =, +=, + -=, and ! operators respectively. The global list of + variables to keep is displayed when ssuuddoo is run by root + with the --VV option. + +GGRROOUUPP PPRROOVVIIDDEERR PPLLUUGGIINNSS + The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix + group lookups which can query a group source other than the standard Unix + group database. This can be used to implement support for the + nonunix_group syntax described earlier. + + Group provider plugins are specified via the _g_r_o_u_p___p_l_u_g_i_n Defaults + setting. The argument to _g_r_o_u_p___p_l_u_g_i_n should consist of the plugin path, + either fully-qualified or relative to the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o + directory, followed by any configuration options the plugin requires. + These options (if specified) will be passed to the plugin's + initialization function. If options are present, the string must be + enclosed in double quotes (""). + + The following group provider plugins are installed by default: + + group_file + The _g_r_o_u_p___f_i_l_e plugin supports an alternate group file that + uses the same syntax as the _/_e_t_c_/_g_r_o_u_p file. The path to the + group file should be specified as an option to the plugin. For + example, if the group file to be used is _/_e_t_c_/_s_u_d_o_-_g_r_o_u_p: + + Defaults group_plugin="group_file.so /etc/sudo-group" + + system_group + The _s_y_s_t_e_m___g_r_o_u_p plugin supports group lookups via the standard + C library functions ggeettggrrnnaamm() and ggeettggrriidd(). This plugin can + be used in instances where the user belongs to groups not + present in the user's supplemental group vector. This plugin + takes no options: + + Defaults group_plugin=system_group.so + + The group provider plugin API is described in detail in sudo_plugin(4). + +LLOOGG FFOORRMMAATT + ssuuddooeerrss can log events using either syslog(3) or a simple log file. The + log format is almost identical in both cases. + + AAcccceepptteedd ccoommmmaanndd lloogg eennttrriieess + Commands that sudo runs are logged using the following format (split into + multiple lines for readability): + + date hostname progname: username : TTY=ttyname ; PWD=cwd ; \ + USER=runasuser ; GROUP=runasgroup ; TSID=logid ; \ + ENV=env_vars COMMAND=command + + Where the fields are as follows: + + date The date the command was run. Typically, this is in the + format "MMM, DD, HH:MM:SS". If logging via syslog(3), the + actual date format is controlled by the syslog daemon. If + logging to a file and the _l_o_g___y_e_a_r option is enabled, the + date will also include the year. + + hostname The name of the host ssuuddoo was run on. This field is only + present when logging via syslog(3). + + progname The name of the program, usually _s_u_d_o or _s_u_d_o_e_d_i_t. This + field is only present when logging via syslog(3). + + username The login name of the user who ran ssuuddoo. + + ttyname The short name of the terminal (e.g., "console", "tty01", + or "pts/0") ssuuddoo was run on, or "unknown" if there was no + terminal present. + + cwd The current working directory that ssuuddoo was run in. + + runasuser The user the command was run as. + + runasgroup The group the command was run as if one was specified on + the command line. + + logid An I/O log identifier that can be used to replay the + command's output. This is only present when the _l_o_g___i_n_p_u_t + or _l_o_g___o_u_t_p_u_t option is enabled. + + env_vars A list of environment variables specified on the command + line, if specified. + + command The actual command that was executed. + + Messages are logged using the locale specified by _s_u_d_o_e_r_s___l_o_c_a_l_e, which + defaults to the "C" locale. + + DDeenniieedd ccoommmmaanndd lloogg eennttrriieess + If the user is not allowed to run the command, the reason for the denial + will follow the user name. Possible reasons include: + + user NOT in sudoers + The user is not listed in the _s_u_d_o_e_r_s file. + + user NOT authorized on host + The user is listed in the _s_u_d_o_e_r_s file but is not allowed to run + commands on the host. + + command not allowed + The user is listed in the _s_u_d_o_e_r_s file for the host but they are not + allowed to run the specified command. + + 3 incorrect password attempts + The user failed to enter their password after 3 tries. The actual + number of tries will vary based on the number of failed attempts and + the value of the _p_a_s_s_w_d___t_r_i_e_s option. + + a password is required + ssuuddoo's --nn option was specified but a password was required. + + sorry, you are not allowed to set the following environment variables + The user specified environment variables on the command line that were + not allowed by _s_u_d_o_e_r_s. + + EErrrroorr lloogg eennttrriieess + If an error occurs, ssuuddooeerrss will log a message and, in most cases, send a + message to the administrator via email. Possible errors include: + + parse error in /etc/sudoers near line N + ssuuddooeerrss encountered an error when parsing the specified file. In some + cases, the actual error may be one line above or below the line number + listed, depending on the type of error. + + problem with defaults entries + The _s_u_d_o_e_r_s file contains one or more unknown Defaults settings. This + does not prevent ssuuddoo from running, but the _s_u_d_o_e_r_s file should be + checked using vviissuuddoo. + + timestamp owner (username): No such user + The time stamp directory owner, as specified by the _t_i_m_e_s_t_a_m_p_o_w_n_e_r + setting, could not be found in the password database. + + unable to open/read /etc/sudoers + The _s_u_d_o_e_r_s file could not be opened for reading. This can happen + when the _s_u_d_o_e_r_s file is located on a remote file system that maps + user ID 0 to a different value. Normally, ssuuddooeerrss tries to open the + _s_u_d_o_e_r_s file using group permissions to avoid this problem. Consider + either changing the ownership of _/_e_t_c_/_s_u_d_o_e_r_s or adding an argument + like "sudoers_uid=N" (where `N' is the user ID that owns the _s_u_d_o_e_r_s + file) to the end of the ssuuddooeerrss Plugin line in the sudo.conf(4) file. + + unable to stat /etc/sudoers + The _/_e_t_c_/_s_u_d_o_e_r_s file is missing. + + /etc/sudoers is not a regular file + The _/_e_t_c_/_s_u_d_o_e_r_s file exists but is not a regular file or symbolic + link. + + /etc/sudoers is owned by uid N, should be 0 + The _s_u_d_o_e_r_s file has the wrong owner. If you wish to change the + _s_u_d_o_e_r_s file owner, please add "sudoers_uid=N" (where `N' is the user + ID that owns the _s_u_d_o_e_r_s file) to the ssuuddooeerrss Plugin line in the + sudo.conf(4) file. + + /etc/sudoers is world writable + The permissions on the _s_u_d_o_e_r_s file allow all users to write to it. + The _s_u_d_o_e_r_s file must not be world-writable, the default file mode is + 0440 (readable by owner and group, writable by none). The default + mode may be changed via the "sudoers_mode" option to the ssuuddooeerrss + Plugin line in the sudo.conf(4) file. + + /etc/sudoers is owned by gid N, should be 1 + The _s_u_d_o_e_r_s file has the wrong group ownership. If you wish to change + the _s_u_d_o_e_r_s file group ownership, please add "sudoers_gid=N" (where + `N' is the group ID that owns the _s_u_d_o_e_r_s file) to the ssuuddooeerrss Plugin + line in the sudo.conf(4) file. + + unable to open /var/run/sudo/ts/username + ssuuddooeerrss was unable to read or create the user's time stamp file. This + can happen when _t_i_m_e_s_t_a_m_p_o_w_n_e_r is set to a user other than root and + the mode on _/_v_a_r_/_r_u_n_/_s_u_d_o is not searchable by group or other. The + default mode for _/_v_a_r_/_r_u_n_/_s_u_d_o is 0711. + + unable to write to /var/run/sudo/ts/username + ssuuddooeerrss was unable to write to the user's time stamp file. + + /var/run/sudo/ts is owned by uid X, should be Y + The time stamp directory is owned by a user other than _t_i_m_e_s_t_a_m_p_o_w_n_e_r. + This can occur when the value of _t_i_m_e_s_t_a_m_p_o_w_n_e_r has been changed. + ssuuddooeerrss will ignore the time stamp directory until the owner is + corrected. + + /var/run/sudo/ts is group writable + The time stamp directory is group-writable; it should be writable only + by _t_i_m_e_s_t_a_m_p_o_w_n_e_r. The default mode for the time stamp directory is + 0700. ssuuddooeerrss will ignore the time stamp directory until the mode is + corrected. + + NNootteess oonn llooggggiinngg vviiaa ssyysslloogg + By default, ssuuddooeerrss logs messages via syslog(3). The _d_a_t_e, _h_o_s_t_n_a_m_e, and + _p_r_o_g_n_a_m_e fields are added by the system's ssyysslloogg() function, not ssuuddooeerrss + itself. As such, they may vary in format on different systems. + + The maximum size of syslog messages varies from system to system. The + _s_y_s_l_o_g___m_a_x_l_e_n setting can be used to change the maximum syslog message + size from the default value of 980 bytes. For more information, see the + description of _s_y_s_l_o_g___m_a_x_l_e_n. + + NNootteess oonn llooggggiinngg ttoo aa ffiillee + If the _l_o_g_f_i_l_e option is set, ssuuddooeerrss will log to a local file, such as + _/_v_a_r_/_l_o_g_/_s_u_d_o. When logging to a file, ssuuddooeerrss uses a format similar to + syslog(3), with a few important differences: + + 1. The _p_r_o_g_n_a_m_e and _h_o_s_t_n_a_m_e fields are not present. + + 2. If the _l_o_g___y_e_a_r option is enabled, the date will also include the + year. + + 3. Lines that are longer than _l_o_g_l_i_n_e_l_e_n characters (80 by default) are + word-wrapped and continued on the next line with a four character + indent. This makes entries easier to read for a human being, but + makes it more difficult to use grep(1) on the log files. If the + _l_o_g_l_i_n_e_l_e_n option is set to 0 (or negated with a `!'), word wrap + will be disabled. + +II//OO LLOOGG FFIILLEESS + When I/O logging is enabled, ssuuddoo will run the command in a pseudo-tty + and log all user input and/or output, depending on which options are + enabled. I/O is logged to the directory specified by the _i_o_l_o_g___d_i_r + option (_/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o by default) using a unique session ID that is + included in the ssuuddoo log line, prefixed with "TSID=". The _i_o_l_o_g___f_i_l_e + option may be used to control the format of the session ID. + + Each I/O log is stored in a separate directory that contains the + following files: + + _l_o_g a text file containing the time the command was run, the name + of the user who ran ssuuddoo, the name of the target user, the name + of the target group (optional), the terminal that ssuuddoo was run + from, the number of rows and columns of the terminal, the + working directory the command was run from and the path name of + the command itself (with arguments if present) + + _t_i_m_i_n_g a log of the amount of time between, and the number of bytes + in, each I/O log entry (used for session playback) + + _t_t_y_i_n input from the user's tty (what the user types) + + _s_t_d_i_n input from a pipe or file + + _t_t_y_o_u_t output from the pseudo-tty (what the command writes to the + screen) + + _s_t_d_o_u_t standard output to a pipe or redirected to a file + + _s_t_d_e_r_r standard error to a pipe or redirected to a file + + All files other than _l_o_g are compressed in gzip format unless the + _c_o_m_p_r_e_s_s___i_o flag has been disabled. Due to buffering, it is not normally + possible to display the I/O logs in real-time as the program is executing + The I/O log data will not be complete until the program run by ssuuddoo has + exited or has been terminated by a signal. The _i_o_l_o_g___f_l_u_s_h flag can be + used to disable buffering, in which case I/O log data is written to disk + as soon as it is available. The output portion of an I/O log file can be + viewed with the sudoreplay(1m) utility, which can also be used to list or + search the available logs. + + Note that user input may contain sensitive information such as passwords + (even if they are not echoed to the screen), which will be stored in the + log file unencrypted. In most cases, logging the command output via + _l_o_g___o_u_t_p_u_t or LOG_OUTPUT is all that is required. + + Since each session's I/O logs are stored in a separate directory, + traditional log rotation utilities cannot be used to limit the number of + I/O logs. The simplest way to limit the number of I/O is by setting the + _m_a_x_s_e_q option to the maximum number of logs you wish to store. Once the + I/O log sequence number reaches _m_a_x_s_e_q, it will be reset to zero and + ssuuddooeerrss will truncate and re-use any existing I/O logs. + +FFIILLEESS + _/_e_t_c_/_s_u_d_o_._c_o_n_f Sudo front end configuration + + _/_e_t_c_/_s_u_d_o_e_r_s List of who can run what + + _/_e_t_c_/_g_r_o_u_p Local groups file + + _/_e_t_c_/_n_e_t_g_r_o_u_p List of network groups + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o I/O log files + + _/_v_a_r_/_r_u_n_/_s_u_d_o_/_t_s Directory containing time stamps for the + ssuuddooeerrss security policy + + _/_v_a_r_/_a_d_m_/_s_u_d_o_/_l_e_c_t_u_r_e_d Directory containing lecture status files for + the ssuuddooeerrss security policy + + _/_e_t_c_/_e_n_v_i_r_o_n_m_e_n_t Initial environment for --ii mode on AIX and + Linux systems + +EEXXAAMMPPLLEESS + Below are example _s_u_d_o_e_r_s file entries. Admittedly, some of these are a + bit contrived. First, we allow a few environment variables to pass and + then define our _a_l_i_a_s_e_s: + + # Run X applications through sudo; HOME is used to find the + # .Xauthority file. Note that other programs use HOME to find + # configuration files and this may lead to privilege escalation! + Defaults env_keep += "DISPLAY HOME" + + # User alias specification + User_Alias FULLTIMERS = millert, mikef, dowdy + User_Alias PARTTIMERS = bostley, jwfox, crawl + User_Alias WEBMASTERS = will, wendy, wim + + # Runas alias specification + Runas_Alias OP = root, operator + Runas_Alias DB = oracle, sybase + Runas_Alias ADMINGRP = adm, oper + + # Host alias specification + Host_Alias SPARC = bigtime, eclipse, moet, anchor :\ + SGI = grolsch, dandelion, black :\ + ALPHA = widget, thalamus, foobar :\ + HPPA = boa, nag, python + Host_Alias CUNETS = 128.138.0.0/255.255.0.0 + Host_Alias CSNETS = 128.138.243.0, 128.138.204.0/24, 128.138.242.0 + Host_Alias SERVERS = master, mail, www, ns + Host_Alias CDROM = orion, perseus, hercules + + # Cmnd alias specification + Cmnd_Alias DUMPS = /usr/bin/mt, /usr/sbin/dump, /usr/sbin/rdump,\ + /usr/sbin/restore, /usr/sbin/rrestore,\ + sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ== \ + /home/operator/bin/start_backups + Cmnd_Alias KILL = /usr/bin/kill + Cmnd_Alias PRINTING = /usr/sbin/lpc, /usr/bin/lprm + Cmnd_Alias SHUTDOWN = /usr/sbin/shutdown + Cmnd_Alias HALT = /usr/sbin/halt + Cmnd_Alias REBOOT = /usr/sbin/reboot + Cmnd_Alias SHELLS = /usr/bin/sh, /usr/bin/csh, /usr/bin/ksh,\ + /usr/local/bin/tcsh, /usr/bin/rsh,\ + /usr/local/bin/zsh + Cmnd_Alias SU = /usr/bin/su + Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less + + Here we override some of the compiled in default values. We want ssuuddoo to + log via syslog(3) using the _a_u_t_h facility in all cases. We don't want to + subject the full time staff to the ssuuddoo lecture, user mmiilllleerrtt need not + give a password, and we don't want to reset the LOGNAME or USER + environment variables when running commands as root. Additionally, on + the machines in the _S_E_R_V_E_R_S Host_Alias, we keep an additional local log + file and make sure we log the year in each log line since the log entries + will be kept around for several years. Lastly, we disable shell escapes + for the commands in the PAGERS Cmnd_Alias (_/_u_s_r_/_b_i_n_/_m_o_r_e, _/_u_s_r_/_b_i_n_/_p_g and + _/_u_s_r_/_b_i_n_/_l_e_s_s). Note that this will not effectively constrain users with + ssuuddoo AALLLL privileges. + + # Override built-in defaults + Defaults syslog=auth + Defaults>root !set_logname + Defaults:FULLTIMERS !lecture + Defaults:millert !authenticate + Defaults@SERVERS log_year, logfile=/var/log/sudo.log + Defaults!PAGERS noexec + + The _U_s_e_r _s_p_e_c_i_f_i_c_a_t_i_o_n is the part that actually determines who may run + what. + + root ALL = (ALL) ALL + %wheel ALL = (ALL) ALL + + We let rroooott and any user in group wwhheeeell run any command on any host as + any user. + + FULLTIMERS ALL = NOPASSWD: ALL + + Full time sysadmins (mmiilllleerrtt, mmiikkeeff, and ddoowwddyy) may run any command on + any host without authenticating themselves. + + PARTTIMERS ALL = ALL + + Part time sysadmins bboossttlleeyy, jjwwffooxx, and ccrraawwll) may run any command on any + host but they must authenticate themselves first (since the entry lacks + the NOPASSWD tag). + + jack CSNETS = ALL + + The user jjaacckk may run any command on the machines in the _C_S_N_E_T_S alias + (the networks 128.138.243.0, 128.138.204.0, and 128.138.242.0). Of those + networks, only 128.138.204.0 has an explicit netmask (in CIDR notation) + indicating it is a class C network. For the other networks in _C_S_N_E_T_S, + the local machine's netmask will be used during matching. + + lisa CUNETS = ALL + + The user lliissaa may run any command on any host in the _C_U_N_E_T_S alias (the + class B network 128.138.0.0). + + operator ALL = DUMPS, KILL, SHUTDOWN, HALT, REBOOT, PRINTING,\ + sudoedit /etc/printcap, /usr/oper/bin/ + + The ooppeerraattoorr user may run commands limited to simple maintenance. Here, + those are commands related to backups, killing processes, the printing + system, shutting down the system, and any commands in the directory + _/_u_s_r_/_o_p_e_r_/_b_i_n_/. Note that one command in the DUMPS Cmnd_Alias includes a + sha224 digest, _/_h_o_m_e_/_o_p_e_r_a_t_o_r_/_b_i_n_/_s_t_a_r_t___b_a_c_k_u_p_s. This is because the + directory containing the script is writable by the operator user. If the + script is modified (resulting in a digest mismatch) it will no longer be + possible to run it via ssuuddoo. + + joe ALL = /usr/bin/su operator + + The user jjooee may only su(1) to operator. + + pete HPPA = /usr/bin/passwd [A-Za-z]*, !/usr/bin/passwd *root* + + %opers ALL = (: ADMINGRP) /usr/sbin/ + + Users in the ooppeerrss group may run commands in _/_u_s_r_/_s_b_i_n_/ as themselves + with any group in the _A_D_M_I_N_G_R_P Runas_Alias (the aaddmm and ooppeerr groups). + + The user ppeettee is allowed to change anyone's password except for root on + the _H_P_P_A machines. Because command line arguments are matched as a + single, concatenated string, the `*' wildcard will match _m_u_l_t_i_p_l_e words. + This example assumes that passwd(1) does not take multiple user names on + the command line. Note that on GNU systems, options to passwd(1) may be + specified after the user argument. As a result, this rule will also + allow: + + passwd username --expire + + which may not be desirable. + + bob SPARC = (OP) ALL : SGI = (OP) ALL + + The user bboobb may run anything on the _S_P_A_R_C and _S_G_I machines as any user + listed in the _O_P Runas_Alias (rroooott and ooppeerraattoorr.) + + jim +biglab = ALL + + The user jjiimm may run any command on machines in the _b_i_g_l_a_b netgroup. + ssuuddoo knows that "biglab" is a netgroup due to the `+' prefix. + + +secretaries ALL = PRINTING, /usr/bin/adduser, /usr/bin/rmuser + + Users in the sseeccrreettaarriieess netgroup need to help manage the printers as + well as add and remove users, so they are allowed to run those commands + on all machines. + + fred ALL = (DB) NOPASSWD: ALL + + The user ffrreedd can run commands as any user in the _D_B Runas_Alias (oorraaccllee + or ssyybbaassee) without giving a password. + + john ALPHA = /usr/bin/su [!-]*, !/usr/bin/su *root* + + On the _A_L_P_H_A machines, user jjoohhnn may su to anyone except root but he is + not allowed to specify any options to the su(1) command. + + jen ALL, !SERVERS = ALL + + The user jjeenn may run any command on any machine except for those in the + _S_E_R_V_E_R_S Host_Alias (master, mail, www and ns). + + jill SERVERS = /usr/bin/, !SU, !SHELLS + + For any machine in the _S_E_R_V_E_R_S Host_Alias, jjiillll may run any commands in + the directory _/_u_s_r_/_b_i_n_/ except for those commands belonging to the _S_U and + _S_H_E_L_L_S Cmnd_Aliases. While not specifically mentioned in the rule, the + commands in the _P_A_G_E_R_S Cmnd_Alias all reside in _/_u_s_r_/_b_i_n and have the + _n_o_e_x_e_c option set. + + steve CSNETS = (operator) /usr/local/op_commands/ + + The user sstteevvee may run any command in the directory + /usr/local/op_commands/ but only as user operator. + + matt valkyrie = KILL + + On his personal workstation, valkyrie, mmaatttt needs to be able to kill hung + processes. + + WEBMASTERS www = (www) ALL, (root) /usr/bin/su www + + On the host www, any user in the _W_E_B_M_A_S_T_E_R_S User_Alias (will, wendy, and + wim), may run any command as user www (which owns the web pages) or + simply su(1) to www. + + ALL CDROM = NOPASSWD: /sbin/umount /CDROM,\ + /sbin/mount -o nosuid\,nodev /dev/cd0a /CDROM + + Any user may mount or unmount a CD-ROM on the machines in the CDROM + Host_Alias (orion, perseus, hercules) without entering a password. This + is a bit tedious for users to type, so it is a prime candidate for + encapsulating in a shell script. + +SSEECCUURRIITTYY NNOOTTEESS + LLiimmiittaattiioonnss ooff tthhee ``!!'' ooppeerraattoorr + It is generally not effective to "subtract" commands from AALLLL using the + `!' operator. A user can trivially circumvent this by copying the + desired command to a different name and then executing that. For + example: + + bill ALL = ALL, !SU, !SHELLS + + Doesn't really prevent bbiillll from running the commands listed in _S_U or + _S_H_E_L_L_S since he can simply copy those commands to a different name, or + use a shell escape from an editor or other program. Therefore, these + kind of restrictions should be considered advisory at best (and + reinforced by policy). + + In general, if a user has sudo AALLLL there is nothing to prevent them from + creating their own program that gives them a root shell (or making their + own copy of a shell) regardless of any `!' elements in the user + specification. + + SSeeccuurriittyy iimmpplliiccaattiioonnss ooff _f_a_s_t___g_l_o_b + If the _f_a_s_t___g_l_o_b option is in use, it is not possible to reliably negate + commands where the path name includes globbing (aka wildcard) characters. + This is because the C library's fnmatch(3) function cannot resolve + relative paths. While this is typically only an inconvenience for rules + that grant privileges, it can result in a security issue for rules that + subtract or revoke privileges. + + For example, given the following _s_u_d_o_e_r_s file entry: + + john ALL = /usr/bin/passwd [a-zA-Z0-9]*, /usr/bin/chsh [a-zA-Z0-9]*,\ + /usr/bin/chfn [a-zA-Z0-9]*, !/usr/bin/* root + + User jjoohhnn can still run /usr/bin/passwd root if _f_a_s_t___g_l_o_b is enabled by + changing to _/_u_s_r_/_b_i_n and running ./passwd root instead. + + PPrreevveennttiinngg sshheellll eessccaappeess + Once ssuuddoo executes a program, that program is free to do whatever it + pleases, including run other programs. This can be a security issue + since it is not uncommon for a program to allow shell escapes, which lets + a user bypass ssuuddoo's access control and logging. Common programs that + permit shell escapes include shells (obviously), editors, paginators, + mail and terminal programs. + + There are two basic approaches to this problem: + + restrict Avoid giving users access to commands that allow the user to + run arbitrary commands. Many editors have a restricted mode + where shell escapes are disabled, though ssuuddooeeddiitt is a better + solution to running editors via ssuuddoo. Due to the large number + of programs that offer shell escapes, restricting users to the + set of programs that do not is often unworkable. + + noexec Many systems that support shared libraries have the ability to + override default library functions by pointing an environment + variable (usually LD_PRELOAD) to an alternate shared library. + On such systems, ssuuddoo's _n_o_e_x_e_c functionality can be used to + prevent a program run by ssuuddoo from executing any other + programs. Note, however, that this applies only to native + dynamically-linked executables. Statically-linked executables + and foreign executables running under binary emulation are not + affected. + + The _n_o_e_x_e_c feature is known to work on SunOS, Solaris, *BSD, + Linux, IRIX, Tru64 UNIX, macOS, HP-UX 11.x and AIX 5.3 and + above. It should be supported on most operating systems that + support the LD_PRELOAD environment variable. Check your + operating system's manual pages for the dynamic linker (usually + ld.so, ld.so.1, dyld, dld.sl, rld, or loader) to see if + LD_PRELOAD is supported. + + On Solaris 10 and higher, _n_o_e_x_e_c uses Solaris privileges + instead of the LD_PRELOAD environment variable. + + To enable _n_o_e_x_e_c for a command, use the NOEXEC tag as + documented in the User Specification section above. Here is + that example again: + + aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi + + This allows user aaaarroonn to run _/_u_s_r_/_b_i_n_/_m_o_r_e and _/_u_s_r_/_b_i_n_/_v_i + with _n_o_e_x_e_c enabled. This will prevent those two commands from + executing other commands (such as a shell). If you are unsure + whether or not your system is capable of supporting _n_o_e_x_e_c you + can always just try it out and check whether shell escapes work + when _n_o_e_x_e_c is enabled. + + Note that restricting shell escapes is not a panacea. Programs running + as root are still capable of many potentially hazardous operations (such + as changing or overwriting files) that could lead to unintended privilege + escalation. In the specific case of an editor, a safer approach is to + give the user permission to run ssuuddooeeddiitt (see below). + + SSeeccuurree eeddiittiinngg + The ssuuddooeerrss plugin includes ssuuddooeeddiitt support which allows users to + securely edit files with the editor of their choice. As ssuuddooeeddiitt is a + built-in command, it must be specified in the _s_u_d_o_e_r_s file without a + leading path. However, it may take command line arguments just as a + normal command does. Wildcards used in _s_u_d_o_e_d_i_t command line arguments + are expected to be path names, so a forward slash (`/') will not be + matched by a wildcard. + + Unlike other ssuuddoo commands, the editor is run with the permissions of the + invoking user and with the environment unmodified. More information may + be found in the description of the --ee option in sudo(1m). + + For example, to allow user operator to edit the "message of the day" + file: + + operator sudoedit /etc/motd + + The operator user then runs ssuuddooeeddiitt as follows: + + $ sudoedit /etc/motd + + The editor will run as the operator user, not root, on a temporary copy + of _/_e_t_c_/_m_o_t_d. After the file has been edited, _/_e_t_c_/_m_o_t_d will be updated + with the contents of the temporary copy. + + Users should _n_e_v_e_r be granted ssuuddooeeddiitt permission to edit a file that + resides in a directory the user has write access to, either directly or + via a wildcard. If the user has write access to the directory it is + possible to replace the legitimate file with a link to another file, + allowing the editing of arbitrary files. To prevent this, starting with + version 1.8.16, symbolic links will not be followed in writable + directories and ssuuddooeeddiitt will refuse to edit a file located in a writable + directory unless the _s_u_d_o_e_d_i_t___c_h_e_c_k_d_i_r option has been disabled or the + invoking user is root. Additionally, in version 1.8.15 and higher, + ssuuddooeeddiitt will refuse to open a symbolic link unless either the + _s_u_d_o_e_d_i_t___f_o_l_l_o_w option is enabled or the _s_u_d_o_e_d_i_t command is prefixed + with the FOLLOW tag in the _s_u_d_o_e_r_s file. + + TTiimmee ssttaammpp ffiillee cchheecckkss + ssuuddooeerrss will check the ownership of its time stamp directory + (_/_v_a_r_/_r_u_n_/_s_u_d_o_/_t_s by default) and ignore the directory's contents if it + is not owned by root or if it is writable by a user other than root. + Older versions of ssuuddoo stored time stamp files in _/_t_m_p; this is no longer + recommended as it may be possible for a user to create the time stamp + themselves on systems that allow unprivileged users to change the + ownership of files they create. + + While the time stamp directory _s_h_o_u_l_d be cleared at reboot time, not all + systems contain a _/_r_u_n or _/_v_a_r_/_r_u_n directory. To avoid potential + problems, ssuuddooeerrss will ignore time stamp files that date from before the + machine booted on systems where the boot time is available. + + Some systems with graphical desktop environments allow unprivileged users + to change the system clock. Since ssuuddooeerrss relies on the system clock for + time stamp validation, it may be possible on such systems for a user to + run ssuuddoo for longer than _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t by setting the clock back. To + combat this, ssuuddooeerrss uses a monotonic clock (which never moves backwards) + for its time stamps if the system supports it. + + ssuuddooeerrss will not honor time stamps set far in the future. Time stamps + with a date greater than current_time + 2 * TIMEOUT will be ignored and + ssuuddooeerrss will log and complain. + + If the _t_i_m_e_s_t_a_m_p___t_y_p_e option is set to "tty", the time stamp record + includes the device number of the terminal the user authenticated with. + This provides per-terminal granularity but time stamp records may still + outlive the user's session. + + Unless the _t_i_m_e_s_t_a_m_p___t_y_p_e option is set to "global", the time stamp + record also includes the session ID of the process that last + authenticated. This prevents processes in different terminal sessions + from using the same time stamp record. On systems where a process's + start time can be queried, the start time of the session leader is + recorded in the time stamp record. If no terminal is present or the + _t_i_m_e_s_t_a_m_p___t_y_p_e option is set to "ppid", the start time of the parent + process is used instead. In most cases this will prevent a time stamp + record from being re-used without the user entering a password when + logging out and back in again. + +DDEEBBUUGGGGIINNGG + Versions 1.8.4 and higher of the ssuuddooeerrss plugin support a flexible + debugging framework that can help track down what the plugin is doing + internally if there is a problem. This can be configured in the + sudo.conf(4) file. + + The ssuuddooeerrss plugin uses the same debug flag format as the ssuuddoo front-end: + _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y. + + The priorities used by ssuuddooeerrss, in order of decreasing severity, are: + _c_r_i_t, _e_r_r, _w_a_r_n, _n_o_t_i_c_e, _d_i_a_g, _i_n_f_o, _t_r_a_c_e and _d_e_b_u_g. Each priority, + when specified, also includes all priorities higher than it. For + example, a priority of _n_o_t_i_c_e would include debug messages logged at + _n_o_t_i_c_e and higher. + + The following subsystems are used by the ssuuddooeerrss plugin: + + _a_l_i_a_s User_Alias, Runas_Alias, Host_Alias and Cmnd_Alias processing + + _a_l_l matches every subsystem + + _a_u_d_i_t BSM and Linux audit code + + _a_u_t_h user authentication + + _d_e_f_a_u_l_t_s _s_u_d_o_e_r_s file _D_e_f_a_u_l_t_s settings + + _e_n_v environment handling + + _l_d_a_p LDAP-based sudoers + + _l_o_g_g_i_n_g logging support + + _m_a_t_c_h matching of users, groups, hosts and netgroups in the _s_u_d_o_e_r_s + file + + _n_e_t_i_f network interface handling + + _n_s_s network service switch handling in ssuuddooeerrss + + _p_a_r_s_e_r _s_u_d_o_e_r_s file parsing + + _p_e_r_m_s permission setting + + _p_l_u_g_i_n The equivalent of _m_a_i_n for the plugin. + + _p_t_y pseudo-tty related code + + _r_b_t_r_e_e redblack tree internals + + _s_s_s_d SSSD-based sudoers + + _u_t_i_l utility functions + For example: + + Debug sudo /var/log/sudo_debug match@info,nss@info + + For more information, see the sudo.conf(4) manual. + +SSEEEE AALLSSOO + ssh(1), su(1), fnmatch(3), glob(3), mktemp(3), strftime(3), sudo.conf(4), + sudo_plugin(4), sudoers.ldap(4), sudoers_timestamp(4), sudo(1m), visudo(1m) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +CCAAVVEEAATTSS + The _s_u_d_o_e_r_s file should aallwwaayyss be edited by the vviissuuddoo command which + locks the file and does grammatical checking. It is imperative that the + _s_u_d_o_e_r_s file be free of syntax errors since ssuuddoo will not run with a + syntactically incorrect _s_u_d_o_e_r_s file. + + When using netgroups of machines (as opposed to users), if you store + fully qualified host name in the netgroup (as is usually the case), you + either need to have the machine's host name be fully qualified as + returned by the hostname command or use the _f_q_d_n option in _s_u_d_o_e_r_s. + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 December 20, 2018 Sudo 1.8.26 diff --git a/doc/sudoers.ldap.cat b/doc/sudoers.ldap.cat new file mode 100644 index 0000000..0d48b9a --- /dev/null +++ b/doc/sudoers.ldap.cat @@ -0,0 +1,1033 @@ +SUDOERS.LDAP(4) File Formats Manual SUDOERS.LDAP(4) + +NNAAMMEE + ssuuddooeerrss..llddaapp - sudo LDAP configuration + +DDEESSCCRRIIPPTTIIOONN + In addition to the standard _s_u_d_o_e_r_s file, ssuuddoo may be configured via + LDAP. This can be especially useful for synchronizing _s_u_d_o_e_r_s in a + large, distributed environment. + + Using LDAP for _s_u_d_o_e_r_s has several benefits: + + ++oo ssuuddoo no longer needs to read _s_u_d_o_e_r_s in its entirety. When LDAP is + used, there are only two or three LDAP queries per invocation. This + makes it especially fast and particularly usable in LDAP environments. + + ++oo ssuuddoo no longer exits if there is a typo in _s_u_d_o_e_r_s. It is not + possible to load LDAP data into the server that does not conform to + the sudoers schema, so proper syntax is guaranteed. It is still + possible to have typos in a user or host name, but this will not + prevent ssuuddoo from running. + + ++oo It is possible to specify per-entry options that override the global + default options. _/_e_t_c_/_s_u_d_o_e_r_s only supports default options and + limited options associated with user/host/commands/aliases. The + syntax is complicated and can be difficult for users to understand. + Placing the options directly in the entry is more natural. + + ++oo The vviissuuddoo program is no longer needed. vviissuuddoo provides locking and + syntax checking of the _/_e_t_c_/_s_u_d_o_e_r_s file. Since LDAP updates are + atomic, locking is no longer necessary. Because syntax is checked + when the data is inserted into LDAP, there is no need for a + specialized tool to check syntax. + + SSUUDDOOeerrss LLDDAAPP ccoonnttaaiinneerr + The _s_u_d_o_e_r_s configuration is contained in the ou=SUDOers LDAP container. + + Sudo first looks for the cn=defaults entry in the SUDOers container. If + found, the multi-valued sudoOption attribute is parsed in the same manner + as a global Defaults line in _/_e_t_c_/_s_u_d_o_e_r_s. In the following example, the + SSH_AUTH_SOCK variable will be preserved in the environment for all + users. + + dn: cn=defaults,ou=SUDOers,dc=my-domain,dc=com + objectClass: top + objectClass: sudoRole + cn: defaults + description: Default sudoOption's go here + sudoOption: env_keep+=SSH_AUTH_SOCK + + The equivalent of a sudoer in LDAP is a sudoRole. It consists of the + following attributes: + + ssuuddooUUsseerr + A user name, user ID (prefixed with `#'), Unix group name or ID + (prefixed with `%' or `%#' respectively), user netgroup (prefixed + with `+'), or non-Unix group name or ID (prefixed with `%:' or + `%:#' respectively). User netgroups are matched using the user and + domain members only; the host member is not used when matching. + Non-Unix group support is only available when an appropriate + _g_r_o_u_p___p_l_u_g_i_n is defined in the global _d_e_f_a_u_l_t_s sudoRole object. + + ssuuddooHHoosstt + A host name, IP address, IP network, or host netgroup (prefixed + with a `+'). The special value ALL will match any host. Host + netgroups are matched using the host (both qualified and + unqualified) and domain members only; the user member is not used + when matching. If a sudoHost entry is preceded by an exclamation + point, `!', and the entry matches, the sudoRole in which it resides + will be ignored. Negated sudoHost entries are only supported by + version 1.8.18 or higher. + + ssuuddooCCoommmmaanndd + A fully-qualified Unix command name with optional command line + arguments, potentially including globbing characters (aka wild + cards). If a command name is preceded by an exclamation point, + `!', the user will be prohibited from running that command. + + The built-in command "sudoedit" is used to permit a user to run + ssuuddoo with the --ee option (or as ssuuddooeeddiitt). It may take command line + arguments just as a normal command does. Note that "sudoedit" is a + command built into ssuuddoo itself and must be specified in without a + leading path. + + The special value ALL will match any command. + + If a command name is prefixed with a SHA-2 digest, it will only be + allowed if the digest matches. This may be useful in situations + where the user invoking ssuuddoo has write access to the command or its + parent directory. The following digest formats are supported: + sha224, sha256, sha384 and sha512. The digest name must be + followed by a colon (`:') and then the actual digest, in either hex + or base64 format. For example, given the following value for + sudoCommand: + + sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ /bin/ls + + The user may only run _/_b_i_n_/_l_s if its sha224 digest matches the + specified value. Command digests are only supported by version + 1.8.7 or higher. + + ssuuddooOOppttiioonn + Identical in function to the global options described above, but + specific to the sudoRole in which it resides. + + ssuuddooRRuunnAAssUUsseerr + A user name or uid (prefixed with `#') that commands may be run as + or a Unix group (prefixed with a `%') or user netgroup (prefixed + with a `+') that contains a list of users that commands may be run + as. The special value ALL will match any user. If a sudoRunAsUser + entry is preceded by an exclamation point, `!', and the entry + matches, the sudoRole in which it resides will be ignored. If + sudoRunAsUser is specified but empty, it will match the invoking + user. If neither sudoRunAsUser nor sudoRunAsGroup are present, the + value of the _r_u_n_a_s___d_e_f_a_u_l_t sudoOption is used (defaults to root). + + The sudoRunAsUser attribute is only available in ssuuddoo versions + 1.7.0 and higher. Older versions of ssuuddoo use the sudoRunAs + attribute instead. Negated sudoRunAsUser entries are only + supported by version 1.8.26 or higher. + + ssuuddooRRuunnAAssGGrroouupp + A Unix group or gid (prefixed with `#') that commands may be run + as. The special value ALL will match any group. If a + sudoRunAsGroup entry is preceded by an exclamation point, `!', and + the entry matches, the sudoRole in which it resides will be + ignored. + + The sudoRunAsGroup attribute is only available in ssuuddoo versions + 1.7.0 and higher. Negated sudoRunAsGroup entries are only + supported by version 1.8.26 or higher. + + ssuuddooNNoottBBeeffoorree + A timestamp in the form yyyymmddHHMMSSZ that can be used to provide + a start date/time for when the sudoRole will be valid. If multiple + sudoNotBefore entries are present, the earliest is used. Note that + timestamps must be in Coordinated Universal Time (UTC), not the + local timezone. The minute and seconds portions are optional, but + some LDAP servers require that they be present (contrary to the + RFC). + + The sudoNotBefore attribute is only available in ssuuddoo versions + 1.7.5 and higher and must be explicitly enabled via the + SSUUDDOOEERRSS__TTIIMMEEDD option in _/_e_t_c_/_l_d_a_p_._c_o_n_f. + + ssuuddooNNoottAAfftteerr + A timestamp in the form yyyymmddHHMMSSZ that indicates an + expiration date/time, after which the sudoRole will no longer be + valid. If multiple sudoNotAfter entries are present, the last one + is used. Note that timestamps must be in Coordinated Universal + Time (UTC), not the local timezone. The minute and seconds + portions are optional, but some LDAP servers require that they be + present (contrary to the RFC). + + The sudoNotAfter attribute is only available in ssuuddoo versions 1.7.5 + and higher and must be explicitly enabled via the SSUUDDOOEERRSS__TTIIMMEEDD + option in _/_e_t_c_/_l_d_a_p_._c_o_n_f. + + ssuuddooOOrrddeerr + The sudoRole entries retrieved from the LDAP directory have no + inherent order. The sudoOrder attribute is an integer (or floating + point value for LDAP servers that support it) that is used to sort + the matching entries. This allows LDAP-based sudoers entries to + more closely mimic the behavior of the sudoers file, where the + order of the entries influences the result. If multiple entries + match, the entry with the highest sudoOrder attribute is chosen. + This corresponds to the "last match" behavior of the sudoers file. + If the sudoOrder attribute is not present, a value of 0 is assumed. + + The sudoOrder attribute is only available in ssuuddoo versions 1.7.5 + and higher. + + Each attribute listed above should contain a single value, but there may + be multiple instances of each attribute type. A sudoRole must contain at + least one sudoUser, sudoHost and sudoCommand. + + The following example allows users in group wheel to run any command on + any host via ssuuddoo: + + dn: cn=%wheel,ou=SUDOers,dc=my-domain,dc=com + objectClass: top + objectClass: sudoRole + cn: %wheel + sudoUser: %wheel + sudoHost: ALL + sudoCommand: ALL + + AAnnaattoommyy ooff LLDDAAPP ssuuddooeerrss llooookkuupp + When looking up a sudoer using LDAP there are only two or three LDAP + queries per invocation. The first query is to parse the global options. + The second is to match against the user's name and the groups that the + user belongs to. (The special ALL tag is matched in this query too.) If + no match is returned for the user's name and groups, a third query + returns all entries containing user netgroups and other non-Unix groups + and checks to see if the user belongs to any of them. + + If timed entries are enabled with the SSUUDDOOEERRSS__TTIIMMEEDD configuration + directive, the LDAP queries include a sub-filter that limits retrieval to + entries that satisfy the time constraints, if any. + + If the NNEETTGGRROOUUPP__BBAASSEE configuration directive is present (see _C_o_n_f_i_g_u_r_i_n_g + _l_d_a_p_._c_o_n_f below), queries are performed to determine the list of + netgroups the user belongs to before the sudoers query. This makes it + possible to include netgroups in the sudoers query string in the same + manner as Unix groups. The third query mentioned above is not performed + unless a group provider plugin is also configured. The actual LDAP + queries performed by ssuuddoo are as follows: + + 1. Match all nisNetgroup records with a nisNetgroupTriple containing + the user, host and NIS domain. The query will match + nisNetgroupTriple entries with either the short or long form of the + host name or no host name specified in the tuple. If the NIS domain + is set, the query will match only match entries that include the + domain or for which there is no domain present. If the NIS domain + is _n_o_t set, a wildcard is used to match any domain name but be aware + that the NIS schema used by some LDAP servers may not support wild + cards for nisNetgroupTriple. + + 2. Repeated queries are performed to find any nested nisNetgroup + records with a memberNisNetgroup entry that refers to an already- + matched record. + + For sites with a large number of netgroups, using NNEETTGGRROOUUPP__BBAASSEE can + significantly speed up ssuuddoo's execution time. + + DDiiffffeerreenncceess bbeettwweeeenn LLDDAAPP aanndd nnoonn--LLDDAAPP ssuuddooeerrss + One of the major differences between LDAP and file-based _s_u_d_o_e_r_s is that + in LDAP, ssuuddoo-specific Aliases are not supported. + + For the most part, there is little need for ssuuddoo-specific Aliases. Unix + groups, non-Unix groups (via the _g_r_o_u_p___p_l_u_g_i_n) or user netgroups can be + used in place of User_Aliases and Runas_Aliases. Host netgroups can be + used in place of Host_Aliases. Since groups and netgroups can also be + stored in LDAP there is no real need for ssuuddoo-specific aliases. + + There are also some subtle differences in the way sudoers is handled once + in LDAP. Probably the biggest is that according to the RFC, LDAP + ordering is arbitrary and you cannot expect that Attributes and Entries + are returned in any specific order. + + The order in which different entries are applied can be controlled using + the sudoOrder attribute, but there is no way to guarantee the order of + attributes within a specific entry. If there are conflicting command + rules in an entry, the negative takes precedence. This is called + paranoid behavior (not necessarily the most specific match). + + Here is an example: + + # /etc/sudoers: + # Allow all commands except shell + johnny ALL=(root) ALL,!/bin/sh + # Always allows all commands because ALL is matched last + puddles ALL=(root) !/bin/sh,ALL + + # LDAP equivalent of johnny + # Allows all commands except shell + dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com + objectClass: sudoRole + objectClass: top + cn: role1 + sudoUser: johnny + sudoHost: ALL + sudoCommand: ALL + sudoCommand: !/bin/sh + + # LDAP equivalent of puddles + # Notice that even though ALL comes last, it still behaves like + # role1 since the LDAP code assumes the more paranoid configuration + dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com + objectClass: sudoRole + objectClass: top + cn: role2 + sudoUser: puddles + sudoHost: ALL + sudoCommand: !/bin/sh + sudoCommand: ALL + + Another difference is that it is not possible to use negation in a + sudoUser, sudoRunAsUser or sudoRunAsGroup attribute. For example, the + following attributes do not behave the way one might expect. + + # does not match all but joe + # rather, does not match anyone + sudoUser: !joe + + # does not match all but joe + # rather, matches everyone including Joe + sudoUser: ALL + sudoUser: !joe + + CCoonnvveerrttiinngg bbeettwweeeenn ffiillee--bbaasseedd aanndd LLDDAAPP ssuuddooeerrss + The cvtsudoers(1) utility can be used to convert between file-based and + LDAP _s_u_d_o_e_r_s. However, there are features in the file-based sudoers that + have no equivalent in LDAP-based sudoers (and vice versa). These cannot + be converted automatically. + + For example, a Cmnd_Alias in a _s_u_d_o_e_r_s file may be converted to a + sudoRole that contains multiple commands. Multiple users and/or groups + may be assigned to the sudoRole. + + Also, host, user, runas and command-based Defaults entries are not + supported. However, a sudoRole may contain one or more sudoOption + attributes which can often serve the same purpose. + + Consider the following _s_u_d_o_e_r_s lines: + + Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less + Defaults!PAGERS noexec + alice, bob ALL = ALL + + In this example, alice and bob are allowed to run all commands, but the + commands listed in PAGERS will have the noexec flag set, preventing shell + escapes. + + When converting this to LDAP, two sudoRole objects can be used: + + dn: cn=PAGERS,ou=SUDOers,dc=my-domain,dc=com + objectClass: top + objectClass: sudoRole + cn: PAGERS + sudoUser: alice + sudoUser: bob + sudoHost: ALL + sudoCommand: /usr/bin/more + sudoCommand: /usr/bin/pg + sudoCommand: /usr/bin/less + sudoOption: noexec + sudoOrder: 900 + + dn: cn=ADMINS,ou=SUDOers,dc=my-domain,dc=com + objectClass: top + objectClass: sudoRole + cn: ADMINS + sudoUser: alice + sudoUser: bob + sudoHost: ALL + sudoCommand: ALL + sudoOrder: 100 + + In the LDAP version, the sudoOrder attribute is used to guarantee that + the PAGERS sudoRole with _n_o_e_x_e_c has precedence. Unlike the _s_u_d_o_e_r_s + version, the LDAP version requires that all users for whom the + restriction should apply be assigned to the PAGERS sudoRole. Using a + Unix group or netgroup in PAGERS rather than listing each user would make + this easier to maintain. + + Per-user Defaults entries can be emulated by using one or more sudoOption + attributes in a sudoRole. Consider the following _s_u_d_o_e_r_s lines: + + User_Alias ADMINS = john, sally + Defaults:ADMINS !authenticate + ADMINS ALL = (ALL:ALL) ALL + + In this example, john and sally are allowed to run any command as any + user or group. + + When converting this to LDAP, we can use a Unix group instead of the + User_Alias. + + dn: cn=admins,ou=SUDOers,dc=my-domain,dc=com + objectClass: top + objectClass: sudoRole + cn: admins + sudoUser: %admin + sudoHost: ALL + sudoRunAsUser: ALL + sudoRunAsGroup: ALL + sudoCommand: ALL + sudoOption: !authenticate + + This assumes that users john and sally are members of the "admins" Unix + group. + + SSuuddooeerrss sscchheemmaa + In order to use ssuuddoo's LDAP support, the ssuuddoo schema must be installed on + your LDAP server. In addition, be sure to index the sudoUser attribute. + + The ssuuddoo distribution includes versions of the ssuuddooeerrss schema for + multiple LDAP servers: + + _s_c_h_e_m_a_._O_p_e_n_L_D_A_P + OpenLDAP slapd and OpenBSD ldapd + + _s_c_h_e_m_a_._o_l_c_S_u_d_o + OpenLDAP slapd 2.3 and higher when on-line configuration is enabled + + _s_c_h_e_m_a_._i_P_l_a_n_e_t + Netscape-derived servers such as the iPlanet, Oracle, and 389 + Directory Servers + + _s_c_h_e_m_a_._A_c_t_i_v_e_D_i_r_e_c_t_o_r_y + Microsoft Active Directory + + The schema in OpenLDAP format is also included in the _E_X_A_M_P_L_E_S section. + + CCoonnffiigguurriinngg llddaapp..ccoonnff + Sudo reads the _/_e_t_c_/_l_d_a_p_._c_o_n_f file for LDAP-specific configuration. + Typically, this file is shared between different LDAP-aware clients. As + such, most of the settings are not ssuuddoo-specific. Note that ssuuddoo parses + _/_e_t_c_/_l_d_a_p_._c_o_n_f itself and may support options that differ from those + described in the system's ldap.conf(4) manual. The path to _l_d_a_p_._c_o_n_f may + be overridden via the _l_d_a_p___c_o_n_f plugin argument in sudo.conf(4). + + Also note that on systems using the OpenLDAP libraries, default values + specified in _/_e_t_c_/_o_p_e_n_l_d_a_p_/_l_d_a_p_._c_o_n_f or the user's _._l_d_a_p_r_c files are not + used. + + Only those options explicitly listed in _/_e_t_c_/_l_d_a_p_._c_o_n_f as being supported + by ssuuddoo are honored. Configuration options are listed below in upper + case but are parsed in a case-independent manner. + + Lines beginning with a pound sign (`#') are ignored. Leading white space + is removed from the beginning of lines. + + BBIINNDD__TTIIMMEELLIIMMIITT _s_e_c_o_n_d_s + The BBIINNDD__TTIIMMEELLIIMMIITT parameter specifies the amount of time, in + seconds, to wait while trying to connect to an LDAP server. If + multiple UURRIIs or HHOOSSTTs are specified, this is the amount of time to + wait before trying the next one in the list. + + BBIINNDDDDNN _D_N + The BBIINNDDDDNN parameter specifies the identity, in the form of a + Distinguished Name (DN), to use when performing LDAP operations. + If not specified, LDAP operations are performed with an anonymous + identity. By default, most LDAP servers will allow anonymous + access. + + BBIINNDDPPWW _s_e_c_r_e_t + The BBIINNDDPPWW parameter specifies the password to use when performing + LDAP operations. This is typically used in conjunction with the + BBIINNDDDDNN parameter. The _s_e_c_r_e_t may be a plain text password or a + base64-encoded string with a "base64:" prefix. For example: + + BINDPW base64:dGVzdA== + + If a plain text password is used, it should be a simple string + without quotes. Plain text passwords may not include the comment + character (`#') and the escaping of special characters with a + backslash (`\') is not supported. + + DDEERREEFF _n_e_v_e_r_/_s_e_a_r_c_h_i_n_g_/_f_i_n_d_i_n_g_/_a_l_w_a_y_s + How alias dereferencing is to be performed when searching. See the + ldap.conf(4) manual for a full description of this option. + + HHOOSSTT _n_a_m_e_[_:_p_o_r_t_] _._._. + If no UURRII is specified (see below), the HHOOSSTT parameter specifies a + white space-delimited list of LDAP servers to connect to. Each + host may include an optional _p_o_r_t separated by a colon (`:'). The + HHOOSSTT parameter is deprecated in favor of the UURRII specification and + is included for backwards compatibility only. + + KKRRBB55__CCCCNNAAMMEE _f_i_l_e _n_a_m_e + The path to the Kerberos 5 credential cache to use when + authenticating with the remote server. This option is only + relevant when using SASL authentication (see below). + + LLDDAAPP__VVEERRSSIIOONN _n_u_m_b_e_r + The version of the LDAP protocol to use when connecting to the + server. The default value is protocol version 3. + + NNEETTGGRROOUUPP__BBAASSEE _b_a_s_e + The base DN to use when performing LDAP netgroup queries. + Typically this is of the form ou=netgroup,dc=my-domain,dc=com for + the domain my-domain.com. Multiple NNEETTGGRROOUUPP__BBAASSEE lines may be + specified, in which case they are queried in the order specified. + + This option can be used to query a user's netgroups directly via + LDAP which is usually faster than fetching every sudoRole object + containing a sudoUser that begins with a `+' prefix. The NIS + schema used by some LDAP servers need a modification to support + querying the nisNetgroup object by its nisNetgroupTriple member. + OpenLDAP's ssllaappdd requires the following change to the + nisNetgroupTriple attribute: + + attributetype ( 1.3.6.1.1.1.1.14 NAME 'nisNetgroupTriple' + DESC 'Netgroup triple' + EQUALITY caseIgnoreIA5Match + SUBSTR caseIgnoreIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + NNEETTGGRROOUUPP__SSEEAARRCCHH__FFIILLTTEERR _l_d_a_p___f_i_l_t_e_r + An LDAP filter which is used to restrict the set of records + returned when performing an LDAP netgroup query. Typically, this + is of the form attribute=value or + (&(attribute=value)(attribute2=value2)). The default search filter + is: objectClass=nisNetgroup. If _l_d_a_p___f_i_l_t_e_r is omitted, no search + filter will be used. This option is only when querying netgroups + directly via LDAP. + + NNEETTWWOORRKK__TTIIMMEEOOUUTT _s_e_c_o_n_d_s + An alias for BBIINNDD__TTIIMMEELLIIMMIITT provided for OpenLDAP compatibility. + + PPOORRTT _p_o_r_t___n_u_m_b_e_r + If no UURRII is specified, the PPOORRTT parameter specifies the default + port to connect to on the LDAP server if a HHOOSSTT parameter does not + specify the port itself. If no PPOORRTT parameter is used, the default + is port 389 for LDAP and port 636 for LDAP over TLS (SSL). The + PPOORRTT parameter is deprecated in favor of the UURRII specification and + is included for backwards compatibility only. + + RROOOOTTBBIINNDDDDNN _D_N + The RROOOOTTBBIINNDDDDNN parameter specifies the identity, in the form of a + Distinguished Name (DN), to use when performing privileged LDAP + operations, such as _s_u_d_o_e_r_s queries. The password corresponding to + the identity should be stored in the or the path specified by the + _l_d_a_p___s_e_c_r_e_t plugin argument in sudo.conf(4), which defaults to + _/_e_t_c_/_l_d_a_p_._s_e_c_r_e_t. If no RROOOOTTBBIINNDDDDNN is specified, the BBIINNDDDDNN + identity is used (if any). + + RROOOOTTUUSSEE__SSAASSLL _o_n_/_t_r_u_e_/_y_e_s_/_o_f_f_/_f_a_l_s_e_/_n_o + Enable RROOOOTTUUSSEE__SSAASSLL to enable SASL authentication when connecting + to an LDAP server from a privileged process, such as ssuuddoo. + + SSAASSLL__AAUUTTHH__IIDD _i_d_e_n_t_i_t_y + The SASL user name to use when connecting to the LDAP server. By + default, ssuuddoo will use an anonymous connection. This option is + only relevant when using SASL authentication. + + SSAASSLL__MMEECCHH _m_e_c_h_a_n_i_s_m_s + A white space-delimited list of SASL authentication mechanisms to + use. By default, ssuuddoo will use GSSAPI authentication. + + SSAASSLL__SSEECCPPRROOPPSS _n_o_n_e_/_p_r_o_p_e_r_t_i_e_s + SASL security properties or _n_o_n_e for no properties. See the SASL + programmer's manual for details. This option is only relevant when + using SASL authentication. + + SSSSLL _o_n_/_t_r_u_e_/_y_e_s_/_o_f_f_/_f_a_l_s_e_/_n_o + If the SSSSLL parameter is set to on, true or yes, TLS (SSL) + encryption is always used when communicating with the LDAP server. + Typically, this involves connecting to the server on port 636 + (ldaps). + + SSSSLL _s_t_a_r_t___t_l_s + If the SSSSLL parameter is set to start_tls, the LDAP server + connection is initiated normally and TLS encryption is begun before + the bind credentials are sent. This has the advantage of not + requiring a dedicated port for encrypted communications. This + parameter is only supported by LDAP servers that honor the + _s_t_a_r_t___t_l_s extension, such as the OpenLDAP and Tivoli Directory + servers. + + SSUUDDOOEERRSS__BBAASSEE _b_a_s_e + The base DN to use when performing ssuuddoo LDAP queries. Typically + this is of the form ou=SUDOers,dc=my-domain,dc=com for the domain + my-domain.com. Multiple SSUUDDOOEERRSS__BBAASSEE lines may be specified, in + which case they are queried in the order specified. + + SSUUDDOOEERRSS__DDEEBBUUGG _d_e_b_u_g___l_e_v_e_l + This sets the debug level for ssuuddoo LDAP queries. Debugging + information is printed to the standard error. A value of 1 results + in a moderate amount of debugging information. A value of 2 shows + the results of the matches themselves. This parameter should not + be set in a production environment as the extra information is + likely to confuse users. + + The SSUUDDOOEERRSS__DDEEBBUUGG parameter is deprecated and will be removed in a + future release. The same information is now logged via the ssuuddoo + debugging framework using the "ldap" subsystem at priorities _d_i_a_g + and _i_n_f_o for _d_e_b_u_g___l_e_v_e_l values 1 and 2 respectively. See the + sudo.conf(4) manual for details on how to configure ssuuddoo debugging. + + SSUUDDOOEERRSS__SSEEAARRCCHH__FFIILLTTEERR _l_d_a_p___f_i_l_t_e_r + An LDAP filter which is used to restrict the set of records + returned when performing a ssuuddoo LDAP query. Typically, this is of + the form attribute=value or + (&(attribute=value)(attribute2=value2)). The default search filter + is: objectClass=sudoRole. If _l_d_a_p___f_i_l_t_e_r is omitted, no search + filter will be used. + + SSUUDDOOEERRSS__TTIIMMEEDD _o_n_/_t_r_u_e_/_y_e_s_/_o_f_f_/_f_a_l_s_e_/_n_o + Whether or not to evaluate the sudoNotBefore and sudoNotAfter + attributes that implement time-dependent sudoers entries. + + TTIIMMEELLIIMMIITT _s_e_c_o_n_d_s + The TTIIMMEELLIIMMIITT parameter specifies the amount of time, in seconds, + to wait for a response to an LDAP query. + + TTIIMMEEOOUUTT _s_e_c_o_n_d_s + The TTIIMMEEOOUUTT parameter specifies the amount of time, in seconds, to + wait for a response from the various LDAP APIs. + + TTLLSS__CCAACCEERRTT _f_i_l_e _n_a_m_e + An alias for TTLLSS__CCAACCEERRTTFFIILLEE for OpenLDAP compatibility. + + TTLLSS__CCAACCEERRTTFFIILLEE _f_i_l_e _n_a_m_e + The path to a certificate authority bundle which contains the + certificates for all the Certificate Authorities the client knows + to be valid, e.g., _/_e_t_c_/_s_s_l_/_c_a_-_b_u_n_d_l_e_._p_e_m. This option is only + supported by the OpenLDAP libraries. Netscape-derived LDAP + libraries use the same certificate database for CA and client + certificates (see TTLLSS__CCEERRTT). + + TTLLSS__CCAACCEERRTTDDIIRR _d_i_r_e_c_t_o_r_y + Similar to TTLLSS__CCAACCEERRTTFFIILLEE but instead of a file, it is a directory + containing individual Certificate Authority certificates, e.g., + _/_e_t_c_/_s_s_l_/_c_e_r_t_s. The directory specified by TTLLSS__CCAACCEERRTTDDIIRR is + checked after TTLLSS__CCAACCEERRTTFFIILLEE. This option is only supported by the + OpenLDAP libraries. + + TTLLSS__CCEERRTT _f_i_l_e _n_a_m_e + The path to a file containing the client certificate which can be + used to authenticate the client to the LDAP server. The + certificate type depends on the LDAP libraries used. + + OpenLDAP: + tls_cert /etc/ssl/client_cert.pem + + Netscape-derived: + tls_cert /var/ldap/cert7.db + + Tivoli Directory Server: + Unused, the key database specified by TTLLSS__KKEEYY contains both + keys and certificates. + + When using Netscape-derived libraries, this file may also + contain Certificate Authority certificates. + + TTLLSS__CCHHEECCKKPPEEEERR _o_n_/_t_r_u_e_/_y_e_s_/_o_f_f_/_f_a_l_s_e_/_n_o + If enabled, TTLLSS__CCHHEECCKKPPEEEERR will cause the LDAP server's TLS + certificated to be verified. If the server's TLS certificate + cannot be verified (usually because it is signed by an unknown + certificate authority), ssuuddoo will be unable to connect to it. If + TTLLSS__CCHHEECCKKPPEEEERR is disabled, no check is made. Note that disabling + the check creates an opportunity for man-in-the-middle attacks + since the server's identity will not be authenticated. If + possible, the CA's certificate should be installed locally so it + can be verified. This option is not supported by the Tivoli + Directory Server LDAP libraries. + + TTLLSS__KKEEYY _f_i_l_e _n_a_m_e + The path to a file containing the private key which matches the + certificate specified by TTLLSS__CCEERRTT. The private key must not be + password-protected. The key type depends on the LDAP libraries + used. + + OpenLDAP: + tls_key /etc/ssl/client_key.pem + + Netscape-derived: + tls_key /var/ldap/key3.db + + Tivoli Directory Server: + tls_key /usr/ldap/ldapkey.kdb + When using Tivoli LDAP libraries, this file may also contain + Certificate Authority and client certificates and may be encrypted. + + TTLLSS__CCIIPPHHEERRSS _c_i_p_h_e_r _l_i_s_t + The TTLLSS__CCIIPPHHEERRSS parameter allows the administer to restrict which + encryption algorithms may be used for TLS (SSL) connections. See + the OpenLDAP or Tivoli Directory Server manual for a list of valid + ciphers. This option is not supported by Netscape-derived + libraries. + + TTLLSS__KKEEYYPPWW _s_e_c_r_e_t + The TTLLSS__KKEEYYPPWW contains the password used to decrypt the key + database on clients using the Tivoli Directory Server LDAP library. + The _s_e_c_r_e_t may be a plain text password or a base64-encoded string + with a "base64:" prefix. For example: + + TLS_KEYPW base64:dGVzdA== + + If a plain text password is used, it should be a simple string + without quotes. Plain text passwords may not include the comment + character (`#') and the escaping of special characters with a + backslash (`\') is not supported. If this option is used, + _/_e_t_c_/_l_d_a_p_._c_o_n_f must not be world-readable to avoid exposing the + password. Alternately, a _s_t_a_s_h _f_i_l_e can be used to store the + password in encrypted form (see below). + + If no TTLLSS__KKEEYYPPWW is specified, a _s_t_a_s_h _f_i_l_e will be used if it + exists. The _s_t_a_s_h _f_i_l_e must have the same path as the file + specified by TTLLSS__KKEEYY, but use a .sth file extension instead of + .kdb, e.g., ldapkey.sth. The default ldapkey.kdb that ships with + Tivoli Directory Server is encrypted with the password + ssl_password. The _g_s_k_8_c_a_p_i_c_m_d utility can be used to manage the + key database and create a _s_t_a_s_h _f_i_l_e. This option is only + supported by the Tivoli LDAP libraries. + + TTLLSS__RREEQQCCEERRTT _l_e_v_e_l + The TTLLSS__RREEQQCCEERRTT parameter controls how the LDAP server's TLS + certificated will be verified (if at all). If the server's TLS + certificate cannot be verified (usually because it is signed by an + unknown certificate authority), ssuuddoo will be unable to connect to + it. The following _l_e_v_e_l values are supported: + + never The server certificate will not be requested or + checked. + + allow The server certificate will be requested. A missing + or invalid certificate is ignored and not considered + an error. + + try The server certificate will be requested. A missing + certificate is ignored but an invalid certificate + will result in a connection error. + + demand | _h_a_r_d + The server certificate will be requested. A missing + or invalid certificate will result in a connection + error. This is the default behavior. + + This option is only supported by the OpenLDAP libraries. Other + LDAP libraries only support the TTLLSS__CCHHEECCKKPPEEEERR parameter. + + TTLLSS__RRAANNDDFFIILLEE _f_i_l_e _n_a_m_e + The TTLLSS__RRAANNDDFFIILLEE parameter specifies the path to an entropy source + for systems that lack a random device. It is generally used in + conjunction with _p_r_n_g_d or _e_g_d. This option is only supported by + the OpenLDAP libraries. + + UURRII _l_d_a_p_[_s_]_:_/_/_[_h_o_s_t_n_a_m_e_[_:_p_o_r_t_]_] _._._. + Specifies a white space-delimited list of one or more URIs + describing the LDAP server(s) to connect to. The _p_r_o_t_o_c_o_l may be + either _l_d_a_p _l_d_a_p_s, the latter being for servers that support TLS + (SSL) encryption. If no _p_o_r_t is specified, the default is port 389 + for ldap:// or port 636 for ldaps://. If no _h_o_s_t_n_a_m_e is specified, + ssuuddoo will connect to _l_o_c_a_l_h_o_s_t. Multiple UURRII lines are treated + identically to a UURRII line containing multiple entries. Only + systems using the OpenSSL libraries support the mixing of ldap:// + and ldaps:// URIs. Both the Netscape-derived and Tivoli LDAP + libraries used on most commercial versions of Unix are only capable + of supporting one or the other. + + UUSSEE__SSAASSLL _o_n_/_t_r_u_e_/_y_e_s_/_o_f_f_/_f_a_l_s_e_/_n_o + Enable UUSSEE__SSAASSLL for LDAP servers that support SASL authentication. + + RROOOOTTSSAASSLL__AAUUTTHH__IIDD _i_d_e_n_t_i_t_y + The SASL user name to use when RROOOOTTUUSSEE__SSAASSLL is enabled. + + See the _l_d_a_p_._c_o_n_f entry in the _E_X_A_M_P_L_E_S section. + + CCoonnffiigguurriinngg nnsssswwiittcchh..ccoonnff + Unless it is disabled at build time, ssuuddoo consults the Name Service + Switch file, _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f, to specify the _s_u_d_o_e_r_s search order. + Sudo looks for a line beginning with sudoers: and uses this to determine + the search order. Note that ssuuddoo does not stop searching after the first + match and later matches take precedence over earlier ones. The following + sources are recognized: + + files read sudoers from _/_e_t_c_/_s_u_d_o_e_r_s + ldap read sudoers from LDAP + + In addition, the entry [NOTFOUND=return] will short-circuit the search if + the user was not found in the preceding source. + + To consult LDAP first followed by the local sudoers file (if it exists), + use: + + sudoers: ldap files + + The local _s_u_d_o_e_r_s file can be ignored completely by using: + + sudoers: ldap + + If the _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f file is not present or there is no sudoers + line, the following default is assumed: + + sudoers: files + + Note that _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f is supported even when the underlying + operating system does not use an nsswitch.conf file, except on AIX (see + below). + + CCoonnffiigguurriinngg nneettssvvcc..ccoonnff + On AIX systems, the _/_e_t_c_/_n_e_t_s_v_c_._c_o_n_f file is consulted instead of + _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f. ssuuddoo simply treats _n_e_t_s_v_c_._c_o_n_f as a variant of + _n_s_s_w_i_t_c_h_._c_o_n_f; information in the previous section unrelated to the file + format itself still applies. + + To consult LDAP first followed by the local sudoers file (if it exists), + use: + + sudoers = ldap, files + + The local _s_u_d_o_e_r_s file can be ignored completely by using: + + sudoers = ldap + + To treat LDAP as authoritative and only use the local sudoers file if the + user is not present in LDAP, use: + + sudoers = ldap = auth, files + + Note that in the above example, the auth qualifier only affects user + lookups; both LDAP and _s_u_d_o_e_r_s will be queried for Defaults entries. + + If the _/_e_t_c_/_n_e_t_s_v_c_._c_o_n_f file is not present or there is no sudoers line, + the following default is assumed: + + sudoers = files + + IInntteeggrraattiioonn wwiitthh ssssssdd + On systems with the _S_y_s_t_e_m _S_e_c_u_r_i_t_y _S_e_r_v_i_c_e_s _D_a_e_m_o_n (SSSD) and where ssuuddoo + has been built with SSSD support, it is possible to use SSSD to cache + LDAP _s_u_d_o_e_r_s rules. To use SSSD as the _s_u_d_o_e_r_s source, you should use + sssd instead of ldap for the sudoers entry in _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f. Note + that the _/_e_t_c_/_l_d_a_p_._c_o_n_f file is not used by the SSSD ssuuddoo back end. + Please see sssd-sudo(4) for more information on configuring ssuuddoo to work + with SSSD. + +FFIILLEESS + _/_e_t_c_/_l_d_a_p_._c_o_n_f LDAP configuration file + + _/_e_t_c_/_n_s_s_w_i_t_c_h_._c_o_n_f determines sudoers source order + + _/_e_t_c_/_n_e_t_s_v_c_._c_o_n_f determines sudoers source order on AIX + +EEXXAAMMPPLLEESS + EExxaammppllee llddaapp..ccoonnff + # Either specify one or more URIs or one or more host:port pairs. + # If neither is specified sudo will default to localhost, port 389. + # + #host ldapserver + #host ldapserver1 ldapserver2:390 + # + # Default port if host is specified without one, defaults to 389. + #port 389 + # + # URI will override the host and port settings. + uri ldap://ldapserver + #uri ldaps://secureldapserver + #uri ldaps://secureldapserver ldap://ldapserver + # + # The amount of time, in seconds, to wait while trying to connect to + # an LDAP server. + bind_timelimit 30 + # + # The amount of time, in seconds, to wait while performing an LDAP query. + timelimit 30 + # + # Must be set or sudo will ignore LDAP; may be specified multiple times. + sudoers_base ou=SUDOers,dc=my-domain,dc=com + # + # verbose sudoers matching from ldap + #sudoers_debug 2 + # + # Enable support for time-based entries in sudoers. + #sudoers_timed yes + # + # optional proxy credentials + #binddn <who to search as> + #bindpw <password> + #rootbinddn <who to search as, uses /etc/ldap.secret for bindpw> + # + # LDAP protocol version, defaults to 3 + #ldap_version 3 + # + # Define if you want to use an encrypted LDAP connection. + # Typically, you must also set the port to 636 (ldaps). + #ssl on + # + # Define if you want to use port 389 and switch to + # encryption before the bind credentials are sent. + # Only supported by LDAP servers that support the start_tls + # extension such as OpenLDAP. + #ssl start_tls + # + # Additional TLS options follow that allow tweaking of the + # SSL/TLS connection. + # + #tls_checkpeer yes # verify server SSL certificate + #tls_checkpeer no # ignore server SSL certificate + # + # If you enable tls_checkpeer, specify either tls_cacertfile + # or tls_cacertdir. Only supported when using OpenLDAP. + # + #tls_cacertfile /etc/certs/trusted_signers.pem + #tls_cacertdir /etc/certs + # + # For systems that don't have /dev/random + # use this along with PRNGD or EGD.pl to seed the + # random number pool to generate cryptographic session keys. + # Only supported when using OpenLDAP. + # + #tls_randfile /etc/egd-pool + # + # You may restrict which ciphers are used. Consult your SSL + # documentation for which options go here. + # Only supported when using OpenLDAP. + # + #tls_ciphers <cipher-list> + # + # Sudo can provide a client certificate when communicating to + # the LDAP server. + # Tips: + # * Enable both lines at the same time. + # * Do not password protect the key file. + # * Ensure the keyfile is only readable by root. + # + # For OpenLDAP: + #tls_cert /etc/certs/client_cert.pem + #tls_key /etc/certs/client_key.pem + # + # For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either + # a directory, in which case the files in the directory must have the + # default names (e.g., cert8.db and key4.db), or the path to the cert + # and key files themselves. However, a bug in version 5.0 of the LDAP + # SDK will prevent specific file names from working. For this reason + # it is suggested that tls_cert and tls_key be set to a directory, + # not a file name. + # + # The certificate database specified by tls_cert may contain CA certs + # and/or the client's cert. If the client's cert is included, tls_key + # should be specified as well. + # For backward compatibility, "sslpath" may be used in place of tls_cert. + #tls_cert /var/ldap + #tls_key /var/ldap + # + # If using SASL authentication for LDAP (OpenSSL) + # use_sasl yes + # sasl_auth_id <SASL user name> + # rootuse_sasl yes + # rootsasl_auth_id <SASL user name for root access> + # sasl_secprops none + # krb5_ccname /etc/.ldapcache + + SSuuddooeerrss sscchheemmaa ffoorr OOppeennLLDDAAPP + The following schema, in OpenLDAP format, is included with ssuuddoo source + and binary distributions as _s_c_h_e_m_a_._O_p_e_n_L_D_A_P. Simply copy it to the + schema directory (e.g., _/_e_t_c_/_o_p_e_n_l_d_a_p_/_s_c_h_e_m_a), add the proper include + line in _s_l_a_p_d_._c_o_n_f and restart ssllaappdd. Sites using the optional on-line + configuration supported by OpenLDAP 2.3 and higher should apply the + _s_c_h_e_m_a_._o_l_c_S_u_d_o file instead. + + attributetype ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + + attributetype ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + + objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ + sudoRunAsGroup $ sudoOption $ sudoNotBefore $ sudoNotAfter $ + sudoOrder $ description ) + ) + +SSEEEE AALLSSOO + cvtsudoers(1), ldap.conf(4), sssd-sudo(4), sudo.conf(4), sudoers(4) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +CCAAVVEEAATTSS + Note that there are differences in the way that LDAP-based _s_u_d_o_e_r_s is + parsed compared to file-based _s_u_d_o_e_r_s. See the _D_i_f_f_e_r_e_n_c_e_s _b_e_t_w_e_e_n _L_D_A_P + _a_n_d _n_o_n_-_L_D_A_P _s_u_d_o_e_r_s section for more information. + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 November 9, 2018 Sudo 1.8.26 diff --git a/doc/sudoers.ldap.man.in b/doc/sudoers.ldap.man.in new file mode 100644 index 0000000..a767d64 --- /dev/null +++ b/doc/sudoers.ldap.man.in @@ -0,0 +1,1712 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2003-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "SUDOERS.LDAP" "@mansectform@" "November 9, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudoers.ldap\fR +\- sudo LDAP configuration +.SH "DESCRIPTION" +In addition to the standard +\fIsudoers\fR +file, +\fBsudo\fR +may be configured +via LDAP. +This can be especially useful for synchronizing +\fIsudoers\fR +in a large, distributed environment. +.PP +Using LDAP for +\fIsudoers\fR +has several benefits: +.TP 3n +\fB\(bu\fR +\fBsudo\fR +no longer needs to read +\fIsudoers\fR +in its entirety. +When LDAP is used, there are only two or three LDAP queries per invocation. +This makes it especially fast and particularly usable in LDAP environments. +.TP 3n +\fB\(bu\fR +\fBsudo\fR +no longer exits if there is a typo in +\fIsudoers\fR. +It is not possible to load LDAP data into the server that does +not conform to the sudoers schema, so proper syntax is guaranteed. +It is still possible to have typos in a user or host name, but +this will not prevent +\fBsudo\fR +from running. +.TP 3n +\fB\(bu\fR +It is possible to specify per-entry options that override the global +default options. +\fI@sysconfdir@/sudoers\fR +only supports default options and limited options associated with +user/host/commands/aliases. +The syntax is complicated and can be difficult for users to understand. +Placing the options directly in the entry is more natural. +.TP 3n +\fB\(bu\fR +The +\fBvisudo\fR +program is no longer needed. +\fBvisudo\fR +provides locking and syntax checking of the +\fI@sysconfdir@/sudoers\fR +file. +Since LDAP updates are atomic, locking is no longer necessary. +Because syntax is checked when the data is inserted into LDAP, there +is no need for a specialized tool to check syntax. +.SS "SUDOers LDAP container" +The +\fIsudoers\fR +configuration is contained in the +\fRou=SUDOers\fR +LDAP container. +.PP +Sudo first looks for the +\fRcn=defaults\fR +entry in the SUDOers container. +If found, the multi-valued +\fRsudoOption\fR +attribute is parsed in the same manner as a global +\fRDefaults\fR +line in +\fI@sysconfdir@/sudoers\fR. +In the following example, the +\fRSSH_AUTH_SOCK\fR +variable will be preserved in the environment for all users. +.nf +.sp +.RS 4n +dn: cn=defaults,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: defaults +description: Default sudoOption's go here +sudoOption: env_keep+=SSH_AUTH_SOCK +.RE +.fi +.PP +The equivalent of a sudoer in LDAP is a +\fRsudoRole\fR. +It consists of the following attributes: +.TP 6n +\fBsudoUser\fR +A user name, user ID (prefixed with +\(oq#\(cq), +Unix group name or ID (prefixed with +\(oq%\(cq +or +\(oq%#\(cq +respectively), user netgroup (prefixed with +\(oq+\(cq), +or non-Unix group name or ID (prefixed with +\(oq%:\(cq +or +\(oq%:#\(cq +respectively). +User netgroups are matched using the user and domain members only; +the host member is not used when matching. +Non-Unix group support is only available when an appropriate +\fIgroup_plugin\fR +is defined in the global +\fIdefaults\fR +\fRsudoRole\fR +object. +.TP 6n +\fBsudoHost\fR +A host name, IP address, IP network, or host netgroup (prefixed with a +\(oq+\(cq). +The special value +\fRALL\fR +will match any host. +Host netgroups are matched using the host (both qualified and unqualified) +and domain members only; the user member is not used when matching. +If a +\fRsudoHost\fR +entry is preceded by an exclamation point, +\(oq\&!\(cq, +and the entry matches, the +\fRsudoRole\fR +in which it resides will be ignored. +Negated +\fRsudoHost\fR +entries are only supported by version 1.8.18 or higher. +.TP 6n +\fBsudoCommand\fR +A fully-qualified Unix command name with optional command line arguments, +potentially including globbing characters (aka wild cards). +If a command name is preceded by an exclamation point, +\(oq\&!\(cq, +the user will be prohibited from running that command. +.sp +The built-in command +\(lq\fRsudoedit\fR\(rq +is used to permit a user to run +\fBsudo\fR +with the +\fB\-e\fR +option (or as +\fBsudoedit\fR). +It may take command line arguments just as a normal command does. +Note that +\(lq\fRsudoedit\fR\(rq +is a command built into +\fBsudo\fR +itself and must be specified in without a leading path. +.sp +The special value +\fRALL\fR +will match any command. +.sp +If a command name is prefixed with a SHA-2 digest, it will +only be allowed if the digest matches. +This may be useful in situations where the user invoking +\fBsudo\fR +has write access to the command or its parent directory. +The following digest formats are supported: sha224, sha256, sha384 and sha512. +The digest name must be followed by a colon +(\(oq:\&\(cq) +and then the actual digest, in either hex or base64 format. +For example, given the following value for sudoCommand: +.nf +.sp +.RS 10n +sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ /bin/ls +.RE +.fi +.RS 6n +.sp +The user may only run +\fI/bin/ls\fR +if its sha224 digest matches the specified value. +Command digests are only supported by version 1.8.7 or higher. +.RE +.TP 6n +\fBsudoOption\fR +Identical in function to the global options described above, but +specific to the +\fRsudoRole\fR +in which it resides. +.TP 6n +\fBsudoRunAsUser\fR +A user name or uid (prefixed with +\(oq#\(cq) +that commands may be run as or a Unix group (prefixed with a +\(oq%\(cq) +or user netgroup (prefixed with a +\(oq+\(cq) +that contains a list of users that commands may be run as. +The special value +\fRALL\fR +will match any user. +If a +\fRsudoRunAsUser\fR +entry is preceded by an exclamation point, +\(oq\&!\(cq, +and the entry matches, the +\fRsudoRole\fR +in which it resides will be ignored. +If +\fRsudoRunAsUser\fR +is specified but empty, it will match the invoking user. +If neither +\fRsudoRunAsUser\fR +nor +\fRsudoRunAsGroup\fR +are present, the value of the +\fIrunas_default\fR +\fRsudoOption\fR +is used (defaults to +\fR@runas_default@\fR). +.sp +The +\fRsudoRunAsUser\fR +attribute is only available in +\fBsudo\fR +versions +1.7.0 and higher. +Older versions of +\fBsudo\fR +use the +\fRsudoRunAs\fR +attribute instead. +Negated +\fRsudoRunAsUser\fR +entries are only supported by version 1.8.26 or higher. +.TP 6n +\fBsudoRunAsGroup\fR +A Unix group or gid (prefixed with +\(oq#\(cq) +that commands may be run as. +The special value +\fRALL\fR +will match any group. +If a +\fRsudoRunAsGroup\fR +entry is preceded by an exclamation point, +\(oq\&!\(cq, +and the entry matches, the +\fRsudoRole\fR +in which it resides will be ignored. +.sp +The +\fRsudoRunAsGroup\fR +attribute is only available in +\fBsudo\fR +versions +1.7.0 and higher. +Negated +\fRsudoRunAsGroup\fR +entries are only supported by version 1.8.26 or higher. +.TP 6n +\fBsudoNotBefore\fR +A timestamp in the form +\fRyyyymmddHHMMSSZ\fR +that can be used to provide a start date/time for when the +\fRsudoRole\fR +will be valid. +If multiple +\fRsudoNotBefore\fR +entries are present, the earliest is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.sp +The +\fRsudoNotBefore\fR +attribute is only available in +\fBsudo\fR +versions 1.7.5 and higher and must be explicitly enabled via the +\fBSUDOERS_TIMED\fR +option in +\fI@ldap_conf@\fR. +.TP 6n +\fBsudoNotAfter\fR +A timestamp in the form +\fRyyyymmddHHMMSSZ\fR +that indicates an expiration date/time, after which the +\fRsudoRole\fR +will no longer be valid. +If multiple +\fRsudoNotAfter\fR +entries are present, the last one is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.sp +The +\fRsudoNotAfter\fR +attribute is only available in +\fBsudo\fR +versions +1.7.5 and higher and must be explicitly enabled via the +\fBSUDOERS_TIMED\fR +option in +\fI@ldap_conf@\fR. +.TP 6n +\fBsudoOrder\fR +The +\fRsudoRole\fR +entries retrieved from the LDAP directory have no inherent order. +The +\fRsudoOrder\fR +attribute is an integer (or floating point value for LDAP servers +that support it) that is used to sort the matching entries. +This allows LDAP-based sudoers entries to more closely mimic the behavior +of the sudoers file, where the order of the entries influences the result. +If multiple entries match, the entry with the highest +\fRsudoOrder\fR +attribute is chosen. +This corresponds to the +\(lqlast match\(rq +behavior of the sudoers file. +If the +\fRsudoOrder\fR +attribute is not present, a value of 0 is assumed. +.sp +The +\fRsudoOrder\fR +attribute is only available in +\fBsudo\fR +versions 1.7.5 and higher. +.PP +Each attribute listed above should contain a single value, but there +may be multiple instances of each attribute type. +A +\fRsudoRole\fR +must contain at least one +\fRsudoUser\fR, +\fRsudoHost\fR +and +\fRsudoCommand\fR. +.PP +The following example allows users in group wheel to run any command +on any host via +\fBsudo\fR: +.nf +.sp +.RS 4n +dn: cn=%wheel,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: %wheel +sudoUser: %wheel +sudoHost: ALL +sudoCommand: ALL +.RE +.fi +.SS "Anatomy of LDAP sudoers lookup" +When looking up a sudoer using LDAP there are only two or three +LDAP queries per invocation. +The first query is to parse the global options. +The second is to match against the user's name and the groups that +the user belongs to. +(The special +\fRALL\fR +tag is matched in this query too.) +If no match is returned for the user's name and groups, a third +query returns all entries containing user netgroups and other +non-Unix groups and checks to see if the user belongs to any of them. +.PP +If timed entries are enabled with the +\fBSUDOERS_TIMED\fR +configuration directive, the LDAP queries include a sub-filter that +limits retrieval to entries that satisfy the time constraints, if any. +.PP +If the +\fBNETGROUP_BASE\fR +configuration directive is present (see +\fIConfiguring ldap.conf\fR +below), queries are performed to determine +the list of netgroups the user belongs to before the sudoers query. +This makes it possible to include netgroups in the sudoers query +string in the same manner as Unix groups. +The third query mentioned above is not performed unless a group provider +plugin is also configured. +The actual LDAP queries performed by +\fBsudo\fR +are as follows: +.TP 5n +1.\& +Match all +\fRnisNetgroup\fR +records with a +\fRnisNetgroupTriple\fR +containing the user, host and NIS domain. +The query will match +\fRnisNetgroupTriple\fR +entries with either the short or long form of the host name or +no host name specified in the tuple. +If the NIS domain is set, the query will match only match entries +that include the domain or for which there is no domain present. +If the NIS domain is +\fInot\fR +set, a wildcard is used to match any domain name but be aware that the +NIS schema used by some LDAP servers may not support wild cards for +\fRnisNetgroupTriple\fR. +.TP 5n +2.\& +Repeated queries are performed to find any nested +\fRnisNetgroup\fR +records with a +\fRmemberNisNetgroup\fR +entry that refers to an already-matched record. +.PP +For sites with a large number of netgroups, using +\fBNETGROUP_BASE\fR +can significantly speed up +\fBsudo\fR's +execution time. +.SS "Differences between LDAP and non-LDAP sudoers" +One of the major differences between LDAP and file-based +\fIsudoers\fR +is that in LDAP, +\fBsudo\fR-specific +Aliases are not supported. +.PP +For the most part, there is little need for +\fBsudo\fR-specific +Aliases. +Unix groups, non-Unix groups (via the +\fIgroup_plugin\fR) +or user netgroups can be used in place of User_Aliases and Runas_Aliases. +Host netgroups can be used in place of Host_Aliases. +Since groups and netgroups can also be stored in LDAP there is no real need for +\fBsudo\fR-specific +aliases. +.PP +There are also some subtle differences in the way sudoers is handled +once in LDAP. +Probably the biggest is that according to the RFC, LDAP ordering +is arbitrary and you cannot expect that Attributes and Entries are +returned in any specific order. +.PP +The order in which different entries are applied can be controlled +using the +\fRsudoOrder\fR +attribute, but there is no way to guarantee the order of attributes +within a specific entry. +If there are conflicting command rules in an entry, the negative +takes precedence. +This is called paranoid behavior (not necessarily the most specific +match). +.PP +Here is an example: +.nf +.sp +.RS 4n +# /etc/sudoers: +# Allow all commands except shell +johnny ALL=(root) ALL,!/bin/sh +# Always allows all commands because ALL is matched last +puddles ALL=(root) !/bin/sh,ALL + +# LDAP equivalent of johnny +# Allows all commands except shell +dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role1 +sudoUser: johnny +sudoHost: ALL +sudoCommand: ALL +sudoCommand: !/bin/sh + +# LDAP equivalent of puddles +# Notice that even though ALL comes last, it still behaves like +# role1 since the LDAP code assumes the more paranoid configuration +dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role2 +sudoUser: puddles +sudoHost: ALL +sudoCommand: !/bin/sh +sudoCommand: ALL +.RE +.fi +.PP +Another difference is that it is not possible to use negation in a +sudoUser, sudoRunAsUser or sudoRunAsGroup attribute. +For example, the following attributes do not behave the way one might expect. +.nf +.sp +.RS 4n +# does not match all but joe +# rather, does not match anyone +sudoUser: !joe + +# does not match all but joe +# rather, matches everyone including Joe +sudoUser: ALL +sudoUser: !joe +.RE +.fi +.SS "Converting between file-based and LDAP sudoers" +The +cvtsudoers(1) +utility can be used to convert between file-based and LDAP +\fIsudoers\fR. +However, there are features in the file-based sudoers that have +no equivalent in LDAP-based sudoers (and vice versa). +These cannot be converted automatically. +.PP +For example, a Cmnd_Alias in a +\fIsudoers\fR +file may be converted to a +\fRsudoRole\fR +that contains multiple commands. +Multiple users and/or groups may be assigned to the +\fRsudoRole\fR. +.PP +Also, host, user, runas and command-based +\fRDefaults\fR +entries are not supported. +However, a +\fRsudoRole\fR +may contain one or more +\fRsudoOption\fR +attributes which can often serve the same purpose. +.PP +Consider the following +\fIsudoers\fR +lines: +.nf +.sp +.RS 4n +Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less +Defaults!PAGERS noexec +alice, bob ALL = ALL +.RE +.fi +.PP +In this example, alice and bob are allowed to run all commands, but +the commands listed in PAGERS will have the noexec flag set, +preventing shell escapes. +.PP +When converting this to LDAP, two sudoRole objects can be used: +.nf +.sp +.RS 4n +dn: cn=PAGERS,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: PAGERS +sudoUser: alice +sudoUser: bob +sudoHost: ALL +sudoCommand: /usr/bin/more +sudoCommand: /usr/bin/pg +sudoCommand: /usr/bin/less +sudoOption: noexec +sudoOrder: 900 + +dn: cn=ADMINS,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: ADMINS +sudoUser: alice +sudoUser: bob +sudoHost: ALL +sudoCommand: ALL +sudoOrder: 100 +.RE +.fi +.PP +In the LDAP version, the sudoOrder attribute is used to guarantee +that the PAGERS sudoRole with +\fInoexec\fR +has precedence. +Unlike the +\fIsudoers\fR +version, the LDAP version requires that all users for whom the restriction +should apply be assigned to the PAGERS sudoRole. +Using a Unix group or netgroup in PAGERS rather than listing each +user would make this easier to maintain. +.PP +Per-user +\fRDefaults\fR +entries can be emulated by using one or more sudoOption attributes +in a sudoRole. +Consider the following +\fIsudoers\fR +lines: +.nf +.sp +.RS 4n +User_Alias ADMINS = john, sally +Defaults:ADMINS !authenticate +ADMINS ALL = (ALL:ALL) ALL +.RE +.fi +.PP +In this example, john and sally are allowed to run any command +as any user or group. +.PP +When converting this to LDAP, we can use a Unix group instead +of the User_Alias. +.nf +.sp +.RS 4n +dn: cn=admins,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: admins +sudoUser: %admin +sudoHost: ALL +sudoRunAsUser: ALL +sudoRunAsGroup: ALL +sudoCommand: ALL +sudoOption: !authenticate +.RE +.fi +.PP +This assumes that users john and sally are members of the +\(lqadmins\(rq +Unix group. +.SS "Sudoers schema" +In order to use +\fBsudo\fR's +LDAP support, the +\fBsudo\fR +schema must be +installed on your LDAP server. +In addition, be sure to index the +\fRsudoUser\fR +attribute. +.PP +The +\fBsudo\fR +distribution includes versions of the +\fBsudoers\fR +schema for multiple LDAP servers: +.TP 6n +\fIschema.OpenLDAP\fR +OpenLDAP slapd and +OpenBSD +ldapd +.TP 6n +\fIschema.olcSudo\fR +OpenLDAP slapd 2.3 and higher when on-line configuration is enabled +.TP 6n +\fIschema.iPlanet\fR +Netscape-derived servers such as the iPlanet, Oracle, +and 389 Directory Servers +.TP 6n +\fIschema.ActiveDirectory\fR +Microsoft Active Directory +.PP +The schema in OpenLDAP format is also included in the +\fIEXAMPLES\fR +section. +.SS "Configuring ldap.conf" +Sudo reads the +\fI@ldap_conf@\fR +file for LDAP-specific configuration. +Typically, this file is shared between different LDAP-aware clients. +As such, most of the settings are not +\fBsudo\fR-specific. +Note that +\fBsudo\fR +parses +\fI@ldap_conf@\fR +itself and may support options that differ from those described in the +system's +ldap.conf(@mansectform@) +manual. +The path to +\fIldap.conf\fR +may be overridden via the +\fIldap_conf\fR +plugin argument in +sudo.conf(@mansectform@). +.PP +Also note that on systems using the OpenLDAP libraries, default +values specified in +\fI/etc/openldap/ldap.conf\fR +or the user's +\fI.ldaprc\fR +files are not used. +.PP +Only those options explicitly listed in +\fI@ldap_conf@\fR +as being supported by +\fBsudo\fR +are honored. +Configuration options are listed below in upper case but are parsed +in a case-independent manner. +.PP +Lines beginning with a pound sign +(\(oq#\(cq) +are ignored. +Leading white space is removed from the beginning of lines. +.TP 6n +\fBBIND_TIMELIMIT\fR \fIseconds\fR +The +\fBBIND_TIMELIMIT\fR +parameter specifies the amount of time, in seconds, to wait while trying +to connect to an LDAP server. +If multiple +\fBURI\fRs +or +\fBHOST\fRs +are specified, this is the amount of time to wait before trying +the next one in the list. +.TP 6n +\fBBINDDN\fR \fIDN\fR +The +\fBBINDDN\fR +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing LDAP operations. +If not specified, LDAP operations are performed with an anonymous identity. +By default, most LDAP servers will allow anonymous access. +.TP 6n +\fBBINDPW\fR \fIsecret\fR +The +\fBBINDPW\fR +parameter specifies the password to use when performing LDAP operations. +This is typically used in conjunction with the +\fBBINDDN\fR +parameter. +The +\fIsecret\fR +may be a plain text password or a base64-encoded string with a +\(lqbase64:\(rq +prefix. +For example: +.nf +.sp +.RS 10n +BINDPW base64:dGVzdA== +.RE +.fi +.RS 6n +.sp +If a plain text password is used, it should be a simple string without quotes. +Plain text passwords may not include the comment character +(\(oq#\(cq) +and the escaping of special characters with a backslash +(\(oq\e\(cq) +is not supported. +.RE +.TP 6n +\fBDEREF\fR \fInever/searching/finding/always\fR +How alias dereferencing is to be performed when searching. +See the +ldap.conf(@mansectform@) +manual for a full description of this option. +.TP 6n +\fBHOST\fR \fIname[:port] ...\fR +If no +\fBURI\fR +is specified (see below), the +\fBHOST\fR +parameter specifies a white space-delimited list of LDAP servers to connect to. +Each host may include an optional +\fIport\fR +separated by a colon +(\(oq:\&\(cq). +The +\fBHOST\fR +parameter is deprecated in favor of the +\fBURI\fR +specification and is included for backwards compatibility only. +.TP 6n +\fBKRB5_CCNAME\fR \fIfile name\fR +The path to the Kerberos 5 credential cache to use when authenticating +with the remote server. +This option is only relevant when using SASL authentication (see below). +.TP 6n +\fBLDAP_VERSION\fR \fInumber\fR +The version of the LDAP protocol to use when connecting to the server. +The default value is protocol version 3. +.TP 6n +\fBNETGROUP_BASE\fR \fIbase\fR +The base DN to use when performing LDAP netgroup queries. +Typically this is of the form +\fRou=netgroup,dc=my-domain,dc=com\fR +for the domain +\fRmy-domain.com\fR. +Multiple +\fBNETGROUP_BASE\fR +lines may be specified, in which case they are queried in the order specified. +.sp +This option can be used to query a user's netgroups directly via LDAP +which is usually faster than fetching every +\fRsudoRole\fR +object containing a +\fRsudoUser\fR +that begins with a +\(oq+\(cq +prefix. +The NIS schema used by some LDAP servers need a modification to +support querying the +\fRnisNetgroup\fR +object by its +\fRnisNetgroupTriple\fR +member. +OpenLDAP's +\fBslapd\fR +requires the following change to the +\fRnisNetgroupTriple\fR +attribute: +.nf +.sp +.RS 10n +attributetype ( 1.3.6.1.1.1.1.14 NAME 'nisNetgroupTriple' + DESC 'Netgroup triple' + EQUALITY caseIgnoreIA5Match + SUBSTR caseIgnoreIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +.RE +.fi +.TP 6n +\fBNETGROUP_SEARCH_FILTER\fR \fIldap_filter\fR +An LDAP filter which is used to restrict the set of records returned +when performing an LDAP netgroup query. +Typically, this is of the +form +\fRattribute=value\fR +or +\fR(&(attribute=value)(attribute2=value2))\fR. +The default search filter is: +\fRobjectClass=nisNetgroup\fR. +If +\fIldap_filter\fR +is omitted, no search filter will be used. +This option is only when querying netgroups directly via LDAP. +.TP 6n +\fBNETWORK_TIMEOUT\fR \fIseconds\fR +An alias for +\fBBIND_TIMELIMIT\fR +provided for OpenLDAP compatibility. +.TP 6n +\fBPORT\fR \fIport_number\fR +If no +\fBURI\fR +is specified, the +\fBPORT\fR +parameter specifies the default port to connect to on the LDAP server if a +\fBHOST\fR +parameter does not specify the port itself. +If no +\fBPORT\fR +parameter is used, the default is port 389 for LDAP and port 636 for LDAP +over TLS (SSL). +The +\fBPORT\fR +parameter is deprecated in favor of the +\fBURI\fR +specification and is included for backwards compatibility only. +.TP 6n +\fBROOTBINDDN\fR \fIDN\fR +The +\fBROOTBINDDN\fR +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing privileged LDAP operations, such as +\fIsudoers\fR +queries. +The password corresponding to the identity should be stored in the +or the path specified by the +\fIldap_secret\fR +plugin argument in +sudo.conf(@mansectform@), +which defaults to +\fI@ldap_secret@\fR. +If no +\fBROOTBINDDN\fR +is specified, the +\fBBINDDN\fR +identity is used (if any). +.TP 6n +\fBROOTUSE_SASL\fR \fIon/true/yes/off/false/no\fR +Enable +\fBROOTUSE_SASL\fR +to enable SASL authentication when connecting +to an LDAP server from a privileged process, such as +\fBsudo\fR. +.TP 6n +\fBSASL_AUTH_ID\fR \fIidentity\fR +The SASL user name to use when connecting to the LDAP server. +By default, +\fBsudo\fR +will use an anonymous connection. +This option is only relevant when using SASL authentication. +.TP 6n +\fBSASL_MECH\fR \fImechanisms\fR +A white space-delimited list of SASL authentication mechanisms to use. +By default, +\fBsudo\fR +will use +\fRGSSAPI\fR +authentication. +.TP 6n +\fBSASL_SECPROPS\fR \fInone/properties\fR +SASL security properties or +\fInone\fR +for no properties. +See the SASL programmer's manual for details. +This option is only relevant when using SASL authentication. +.TP 6n +\fBSSL\fR \fIon/true/yes/off/false/no\fR +If the +\fBSSL\fR +parameter is set to +\fRon\fR, +\fRtrue\fR +\fRor\fR +\fRyes\fR, +TLS (SSL) encryption is always used when communicating with the LDAP server. +Typically, this involves connecting to the server on port 636 (ldaps). +.TP 6n +\fBSSL\fR \fIstart_tls\fR +If the +\fBSSL\fR +parameter is set to +\fRstart_tls\fR, +the LDAP server connection is initiated normally and TLS encryption is +begun before the bind credentials are sent. +This has the advantage of not requiring a dedicated port for encrypted +communications. +This parameter is only supported by LDAP servers that honor the +\fIstart_tls\fR +extension, such as the OpenLDAP and Tivoli Directory servers. +.TP 6n +\fBSUDOERS_BASE\fR \fIbase\fR +The base DN to use when performing +\fBsudo\fR +LDAP queries. +Typically this is of the form +\fRou=SUDOers,dc=my-domain,dc=com\fR +for the domain +\fRmy-domain.com\fR. +Multiple +\fBSUDOERS_BASE\fR +lines may be specified, in which case they are queried in the order specified. +.TP 6n +\fBSUDOERS_DEBUG\fR \fIdebug_level\fR +This sets the debug level for +\fBsudo\fR +LDAP queries. +Debugging information is printed to the standard error. +A value of 1 results in a moderate amount of debugging information. +A value of 2 shows the results of the matches themselves. +This parameter should not be set in a production environment as the +extra information is likely to confuse users. +.sp +The +\fBSUDOERS_DEBUG\fR +parameter is deprecated and will be removed in a future release. +The same information is now logged via the +\fBsudo\fR +debugging framework using the +\(lqldap\(rq +subsystem at priorities +\fIdiag\fR +and +\fIinfo\fR +for +\fIdebug_level\fR +values 1 and 2 respectively. +See the +sudo.conf(@mansectform@) +manual for details on how to configure +\fBsudo\fR +debugging. +.TP 6n +\fBSUDOERS_SEARCH_FILTER\fR \fIldap_filter\fR +An LDAP filter which is used to restrict the set of records returned +when performing a +\fBsudo\fR +LDAP query. +Typically, this is of the +form +\fRattribute=value\fR +or +\fR(&(attribute=value)(attribute2=value2))\fR. +The default search filter is: +\fRobjectClass=sudoRole\fR. +If +\fIldap_filter\fR +is omitted, no search filter will be used. +.TP 6n +\fBSUDOERS_TIMED\fR \fIon/true/yes/off/false/no\fR +Whether or not to evaluate the +\fRsudoNotBefore\fR +and +\fRsudoNotAfter\fR +attributes that implement time-dependent sudoers entries. +.TP 6n +\fBTIMELIMIT\fR \fIseconds\fR +The +\fBTIMELIMIT\fR +parameter specifies the amount of time, in seconds, to wait for a +response to an LDAP query. +.TP 6n +\fBTIMEOUT\fR \fIseconds\fR +The +\fBTIMEOUT\fR +parameter specifies the amount of time, in seconds, to wait for a +response from the various LDAP APIs. +.TP 6n +\fBTLS_CACERT\fR \fIfile name\fR +An alias for +\fBTLS_CACERTFILE\fR +for OpenLDAP compatibility. +.TP 6n +\fBTLS_CACERTFILE\fR \fIfile name\fR +The path to a certificate authority bundle which contains the certificates +for all the Certificate Authorities the client knows to be valid, e.g., +\fI/etc/ssl/ca-bundle.pem\fR. +This option is only supported by the OpenLDAP libraries. +Netscape-derived LDAP libraries use the same certificate +database for CA and client certificates (see +\fBTLS_CERT\fR). +.TP 6n +\fBTLS_CACERTDIR\fR \fIdirectory\fR +Similar to +\fBTLS_CACERTFILE\fR +but instead of a file, it is a directory containing individual +Certificate Authority certificates, e.g., +\fI/etc/ssl/certs\fR. +The directory specified by +\fBTLS_CACERTDIR\fR +is checked after +\fBTLS_CACERTFILE\fR. +This option is only supported by the OpenLDAP libraries. +.TP 6n +\fBTLS_CERT\fR \fIfile name\fR +The path to a file containing the client certificate which can +be used to authenticate the client to the LDAP server. +The certificate type depends on the LDAP libraries used. +.PP +.RS 6n +.PD 0 +.TP 6n +OpenLDAP: +\fRtls_cert /etc/ssl/client_cert.pem\fR +.PD +.TP 6n +Netscape-derived: +\fRtls_cert /var/ldap/cert7.db\fR +.TP 6n +Tivoli Directory Server: +Unused, the key database specified by +\fBTLS_KEY\fR +contains both keys and certificates. +.sp +When using Netscape-derived libraries, this file may also contain +Certificate Authority certificates. +.PD 0 +.PP +.RE +.PD +.TP 6n +\fBTLS_CHECKPEER\fR \fIon/true/yes/off/false/no\fR +If enabled, +\fBTLS_CHECKPEER\fR +will cause the LDAP server's TLS certificated to be verified. +If the server's TLS certificate cannot be verified (usually because it +is signed by an unknown certificate authority), +\fBsudo\fR +will be unable to connect to it. +If +\fBTLS_CHECKPEER\fR +is disabled, no check is made. +Note that disabling the check creates an opportunity for man-in-the-middle +attacks since the server's identity will not be authenticated. +If possible, the CA's certificate should be installed locally so it can +be verified. +This option is not supported by the Tivoli Directory Server LDAP libraries. +.TP 6n +\fBTLS_KEY\fR \fIfile name\fR +The path to a file containing the private key which matches the +certificate specified by +\fBTLS_CERT\fR. +The private key must not be password-protected. +The key type depends on the LDAP libraries used. +.PP +.RS 6n +.PD 0 +.TP 6n +OpenLDAP: +\fRtls_key /etc/ssl/client_key.pem\fR +.PD +.TP 6n +Netscape-derived: +\fRtls_key /var/ldap/key3.db\fR +.TP 6n +Tivoli Directory Server: +\fRtls_key /usr/ldap/ldapkey.kdb\fR +.PD 0 +.PP +When using Tivoli LDAP libraries, this file may also contain +Certificate Authority and client certificates and may be encrypted. +.RE +.PD +.TP 6n +\fBTLS_CIPHERS\fR \fIcipher list\fR +The +\fBTLS_CIPHERS\fR +parameter allows the administer to restrict which encryption algorithms +may be used for TLS (SSL) connections. +See the OpenLDAP or Tivoli Directory Server manual for a list of valid +ciphers. +This option is not supported by Netscape-derived libraries. +.TP 6n +\fBTLS_KEYPW\fR \fIsecret\fR +The +\fBTLS_KEYPW\fR +contains the password used to decrypt the key database on clients +using the Tivoli Directory Server LDAP library. +The +\fIsecret\fR +may be a plain text password or a base64-encoded string with a +\(lqbase64:\(rq +prefix. +For example: +.nf +.sp +.RS 10n +TLS_KEYPW base64:dGVzdA== +.RE +.fi +.RS 6n +.sp +If a plain text password is used, it should be a simple string without quotes. +Plain text passwords may not include the comment character +(\(oq#\(cq) +and the escaping of special characters with a backslash +(\(oq\e\(cq) +is not supported. +If this option is used, +\fI@ldap_conf@\fR +must not be world-readable to avoid exposing the password. +Alternately, a +\fIstash file\fR +can be used to store the password in encrypted form (see below). +.sp +If no +\fBTLS_KEYPW\fR +is specified, a +\fIstash file\fR +will be used if it exists. +The +\fIstash file\fR +must have the same path as the file specified by +\fBTLS_KEY\fR, +but use a +\fR.sth\fR +file extension instead of +\fR.kdb\fR, +e.g., +\fRldapkey.sth\fR. +The default +\fRldapkey.kdb\fR +that ships with Tivoli Directory Server is encrypted with the password +\fRssl_password\fR. +The +\fIgsk8capicmd\fR +utility can be used to manage the key database and create a +\fIstash file\fR. +This option is only supported by the Tivoli LDAP libraries. +.RE +.TP 6n +\fBTLS_REQCERT\fR \fIlevel\fR +The +\fBTLS_REQCERT\fR +parameter controls how the LDAP server's TLS certificated will be +verified (if at all). +If the server's TLS certificate cannot be verified (usually because it +is signed by an unknown certificate authority), +\fBsudo\fR +will be unable to connect to it. +The following +\fIlevel\fR +values are supported: +.RS 10n +.TP 10n +never +The server certificate will not be requested or checked. +.TP 10n +allow +The server certificate will be requested. +A missing or invalid certificate is ignored and not considered an error. +.TP 10n +try +The server certificate will be requested. +A missing certificate is ignored but an invalid certificate will +result in a connection error. +.TP 10n +demand | \fIhard\fR +The server certificate will be requested. +A missing or invalid certificate will result in a connection error. +This is the default behavior. +.RE +.RS 6n +.sp +This option is only supported by the OpenLDAP libraries. +Other LDAP libraries only support the +\fBTLS_CHECKPEER\fR +parameter. +.RE +.TP 6n +\fBTLS_RANDFILE\fR \fIfile name\fR +The +\fBTLS_RANDFILE\fR +parameter specifies the path to an entropy source for systems that lack +a random device. +It is generally used in conjunction with +\fIprngd\fR +or +\fIegd\fR. +This option is only supported by the OpenLDAP libraries. +.TP 6n +\fBURI\fR \fIldap[s]://[hostname[:port]] ...\fR +Specifies a white space-delimited list of one or more URIs describing +the LDAP server(s) to connect to. +The +\fIprotocol\fR +may be either +\fIldap\fR +\fIldaps\fR, +the latter being for servers that support TLS (SSL) encryption. +If no +\fIport\fR +is specified, the default is port 389 for +\fRldap://\fR +or port 636 for +\fRldaps://\fR. +If no +\fIhostname\fR +is specified, +\fBsudo\fR +will connect to +\fIlocalhost\fR. +Multiple +\fBURI\fR +lines are treated identically to a +\fBURI\fR +line containing multiple entries. +Only systems using the OpenSSL libraries support the mixing of +\fRldap://\fR +and +\fRldaps://\fR +URIs. +Both the Netscape-derived and Tivoli LDAP libraries used on most commercial +versions of Unix are only capable of supporting one or the other. +.TP 6n +\fBUSE_SASL\fR \fIon/true/yes/off/false/no\fR +Enable +\fBUSE_SASL\fR +for LDAP servers that support SASL authentication. +.TP 6n +\fBROOTSASL_AUTH_ID\fR \fIidentity\fR +The SASL user name to use when +\fBROOTUSE_SASL\fR +is enabled. +.PP +See the +\fIldap.conf\fR +entry in the +\fIEXAMPLES\fR +section. +.SS "Configuring nsswitch.conf" +Unless it is disabled at build time, +\fBsudo\fR +consults the Name Service Switch file, +\fI@nsswitch_conf@\fR, +to specify the +\fIsudoers\fR +search order. +Sudo looks for a line beginning with +\fRsudoers\fR: +and uses this to determine the search order. +Note that +\fBsudo\fR +does +not stop searching after the first match and later matches take +precedence over earlier ones. +The following sources are recognized: +.PP +.RS 4n +.PD 0 +.TP 10n +files +read sudoers from +\fI@sysconfdir@/sudoers\fR +.TP 10n +ldap +read sudoers from LDAP +.RE +.PD +.PP +In addition, the entry +\fR[NOTFOUND=return]\fR +will short-circuit the search if the user was not found in the +preceding source. +.PP +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.nf +.sp +.RS 4n +sudoers: ldap files +.RE +.fi +.PP +The local +\fIsudoers\fR +file can be ignored completely by using: +.nf +.sp +.RS 4n +sudoers: ldap +.RE +.fi +.PP +If the +\fI@nsswitch_conf@\fR +file is not present or there is no sudoers line, the following +default is assumed: +.nf +.sp +.RS 4n +sudoers: files +.RE +.fi +.PP +Note that +\fI@nsswitch_conf@\fR +is supported even when the underlying operating system does not use +an nsswitch.conf file, except on AIX (see below). +.SS "Configuring netsvc.conf" +On AIX systems, the +\fI@netsvc_conf@\fR +file is consulted instead of +\fI@nsswitch_conf@\fR. +\fBsudo\fR +simply treats +\fInetsvc.conf\fR +as a variant of +\fInsswitch.conf\fR; +information in the previous section unrelated to the file format +itself still applies. +.PP +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.nf +.sp +.RS 4n +sudoers = ldap, files +.RE +.fi +.PP +The local +\fIsudoers\fR +file can be ignored completely by using: +.nf +.sp +.RS 4n +sudoers = ldap +.RE +.fi +.PP +To treat LDAP as authoritative and only use the local sudoers file +if the user is not present in LDAP, use: +.nf +.sp +.RS 4n +sudoers = ldap = auth, files +.RE +.fi +.PP +Note that in the above example, the +\fRauth\fR +qualifier only affects user lookups; both LDAP and +\fIsudoers\fR +will be queried for +\fRDefaults\fR +entries. +.PP +If the +\fI@netsvc_conf@\fR +file is not present or there is no sudoers line, the following +default is assumed: +.nf +.sp +.RS 4n +sudoers = files +.RE +.fi +.SS "Integration with sssd" +On systems with the +\fISystem Security Services Daemon\fR +(SSSD) and where +\fBsudo\fR +has been built with SSSD support, +it is possible to use SSSD to cache LDAP +\fIsudoers\fR +rules. +To use SSSD as the +\fIsudoers\fR +source, you should use +\fRsssd\fR +instead of +\fRldap\fR +for the sudoers entry in +\fI@nsswitch_conf@\fR. +Note that the +\fI@ldap_conf@\fR +file is not used by the SSSD +\fBsudo\fR +back end. +Please see +sssd-sudo(@mansectform@) +for more information on configuring +\fBsudo\fR +to work with SSSD. +.SH "FILES" +.TP 26n +\fI@ldap_conf@\fR +LDAP configuration file +.TP 26n +\fI@nsswitch_conf@\fR +determines sudoers source order +.TP 26n +\fI@netsvc_conf@\fR +determines sudoers source order on AIX +.SH "EXAMPLES" +.SS "Example ldap.conf" +.nf +.RS 2n +# Either specify one or more URIs or one or more host:port pairs. +# If neither is specified sudo will default to localhost, port 389. +# +#host ldapserver +#host ldapserver1 ldapserver2:390 +# +# Default port if host is specified without one, defaults to 389. +#port 389 +# +# URI will override the host and port settings. +uri ldap://ldapserver +#uri ldaps://secureldapserver +#uri ldaps://secureldapserver ldap://ldapserver +# +# The amount of time, in seconds, to wait while trying to connect to +# an LDAP server. +bind_timelimit 30 +# +# The amount of time, in seconds, to wait while performing an LDAP query. +timelimit 30 +# +# Must be set or sudo will ignore LDAP; may be specified multiple times. +sudoers_base ou=SUDOers,dc=my-domain,dc=com +# +# verbose sudoers matching from ldap +#sudoers_debug 2 +# +# Enable support for time-based entries in sudoers. +#sudoers_timed yes +# +# optional proxy credentials +#binddn <who to search as> +#bindpw <password> +#rootbinddn <who to search as, uses /etc/ldap.secret for bindpw> +# +# LDAP protocol version, defaults to 3 +#ldap_version 3 +# +# Define if you want to use an encrypted LDAP connection. +# Typically, you must also set the port to 636 (ldaps). +#ssl on +# +# Define if you want to use port 389 and switch to +# encryption before the bind credentials are sent. +# Only supported by LDAP servers that support the start_tls +# extension such as OpenLDAP. +#ssl start_tls +# +# Additional TLS options follow that allow tweaking of the +# SSL/TLS connection. +# +#tls_checkpeer yes # verify server SSL certificate +#tls_checkpeer no # ignore server SSL certificate +# +# If you enable tls_checkpeer, specify either tls_cacertfile +# or tls_cacertdir. Only supported when using OpenLDAP. +# +#tls_cacertfile /etc/certs/trusted_signers.pem +#tls_cacertdir /etc/certs +# +# For systems that don't have /dev/random +# use this along with PRNGD or EGD.pl to seed the +# random number pool to generate cryptographic session keys. +# Only supported when using OpenLDAP. +# +#tls_randfile /etc/egd-pool +# +# You may restrict which ciphers are used. Consult your SSL +# documentation for which options go here. +# Only supported when using OpenLDAP. +# +#tls_ciphers <cipher-list> +# +# Sudo can provide a client certificate when communicating to +# the LDAP server. +# Tips: +# * Enable both lines at the same time. +# * Do not password protect the key file. +# * Ensure the keyfile is only readable by root. +# +# For OpenLDAP: +#tls_cert /etc/certs/client_cert.pem +#tls_key /etc/certs/client_key.pem +# +# For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either +# a directory, in which case the files in the directory must have the +# default names (e.g., cert8.db and key4.db), or the path to the cert +# and key files themselves. However, a bug in version 5.0 of the LDAP +# SDK will prevent specific file names from working. For this reason +# it is suggested that tls_cert and tls_key be set to a directory, +# not a file name. +# +# The certificate database specified by tls_cert may contain CA certs +# and/or the client's cert. If the client's cert is included, tls_key +# should be specified as well. +# For backward compatibility, "sslpath" may be used in place of tls_cert. +#tls_cert /var/ldap +#tls_key /var/ldap +# +# If using SASL authentication for LDAP (OpenSSL) +# use_sasl yes +# sasl_auth_id <SASL user name> +# rootuse_sasl yes +# rootsasl_auth_id <SASL user name for root access> +# sasl_secprops none +# krb5_ccname /etc/.ldapcache +.RE +.fi +.SS "Sudoers schema for OpenLDAP" +The following schema, in OpenLDAP format, is included with +\fBsudo\fR +source and binary distributions as +\fIschema.OpenLDAP\fR. +Simply copy +it to the schema directory (e.g., +\fI/etc/openldap/schema\fR), +add the proper +\fRinclude\fR +line in +\fIslapd.conf\fR +and restart +\fBslapd\fR. +Sites using the optional on-line configuration supported by OpenLDAP 2.3 +and higher should apply the +\fIschema.olcSudo\fR +file instead. +.nf +.sp +.RS 2n +attributetype ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + +objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ + sudoRunAsGroup $ sudoOption $ sudoNotBefore $ sudoNotAfter $ + sudoOrder $ description ) + ) +.RE +.fi +.SH "SEE ALSO" +cvtsudoers(1), +ldap.conf(@mansectform@), +sssd-sudo(@mansectform@), +sudo.conf(@mansectform@), +sudoers(@mansectform@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "CAVEATS" +Note that there are differences in the way that LDAP-based +\fIsudoers\fR +is parsed compared to file-based +\fIsudoers\fR. +See the +\fIDifferences between LDAP and non-LDAP sudoers\fR +section for more information. +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers.ldap.mdoc.in b/doc/sudoers.ldap.mdoc.in new file mode 100644 index 0000000..c7ab8a8 --- /dev/null +++ b/doc/sudoers.ldap.mdoc.in @@ -0,0 +1,1567 @@ +.\" +.\" Copyright (c) 2003-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 9, 2018 +.Dt SUDOERS.LDAP @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudoers.ldap +.Nd sudo LDAP configuration +.Sh DESCRIPTION +In addition to the standard +.Em sudoers +file, +.Nm sudo +may be configured +via LDAP. +This can be especially useful for synchronizing +.Em sudoers +in a large, distributed environment. +.Pp +Using LDAP for +.Em sudoers +has several benefits: +.Bl -bullet -width 1n +.It +.Nm sudo +no longer needs to read +.Em sudoers +in its entirety. +When LDAP is used, there are only two or three LDAP queries per invocation. +This makes it especially fast and particularly usable in LDAP environments. +.It +.Nm sudo +no longer exits if there is a typo in +.Em sudoers . +It is not possible to load LDAP data into the server that does +not conform to the sudoers schema, so proper syntax is guaranteed. +It is still possible to have typos in a user or host name, but +this will not prevent +.Nm sudo +from running. +.It +It is possible to specify per-entry options that override the global +default options. +.Pa @sysconfdir@/sudoers +only supports default options and limited options associated with +user/host/commands/aliases. +The syntax is complicated and can be difficult for users to understand. +Placing the options directly in the entry is more natural. +.It +The +.Nm visudo +program is no longer needed. +.Nm visudo +provides locking and syntax checking of the +.Pa @sysconfdir@/sudoers +file. +Since LDAP updates are atomic, locking is no longer necessary. +Because syntax is checked when the data is inserted into LDAP, there +is no need for a specialized tool to check syntax. +.El +.Ss SUDOers LDAP container +The +.Em sudoers +configuration is contained in the +.Li ou=SUDOers +LDAP container. +.Pp +Sudo first looks for the +.Li cn=defaults +entry in the SUDOers container. +If found, the multi-valued +.Li sudoOption +attribute is parsed in the same manner as a global +.Li Defaults +line in +.Pa @sysconfdir@/sudoers . +In the following example, the +.Ev SSH_AUTH_SOCK +variable will be preserved in the environment for all users. +.Bd -literal -offset 4n +dn: cn=defaults,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: defaults +description: Default sudoOption's go here +sudoOption: env_keep+=SSH_AUTH_SOCK +.Ed +.Pp +The equivalent of a sudoer in LDAP is a +.Li sudoRole . +It consists of the following attributes: +.Bl -tag -width 4n +.It Sy sudoUser +A user name, user ID (prefixed with +.Ql # ) , +Unix group name or ID (prefixed with +.Ql % +or +.Ql %# +respectively), user netgroup (prefixed with +.Ql + ) , +or non-Unix group name or ID (prefixed with +.Ql %: +or +.Ql %:# +respectively). +User netgroups are matched using the user and domain members only; +the host member is not used when matching. +Non-Unix group support is only available when an appropriate +.Em group_plugin +is defined in the global +.Em defaults +.Li sudoRole +object. +.It Sy sudoHost +A host name, IP address, IP network, or host netgroup (prefixed with a +.Ql + ) . +The special value +.Li ALL +will match any host. +Host netgroups are matched using the host (both qualified and unqualified) +and domain members only; the user member is not used when matching. +If a +.Li sudoHost +entry is preceded by an exclamation point, +.Ql \&! , +and the entry matches, the +.Li sudoRole +in which it resides will be ignored. +Negated +.Li sudoHost +entries are only supported by version 1.8.18 or higher. +.It Sy sudoCommand +A fully-qualified Unix command name with optional command line arguments, +potentially including globbing characters (aka wild cards). +If a command name is preceded by an exclamation point, +.Ql \&! , +the user will be prohibited from running that command. +.Pp +The built-in command +.Dq Li sudoedit +is used to permit a user to run +.Nm sudo +with the +.Fl e +option (or as +.Nm sudoedit ) . +It may take command line arguments just as a normal command does. +Note that +.Dq Li sudoedit +is a command built into +.Nm sudo +itself and must be specified in without a leading path. +.Pp +The special value +.Li ALL +will match any command. +.Pp +If a command name is prefixed with a SHA-2 digest, it will +only be allowed if the digest matches. +This may be useful in situations where the user invoking +.Nm sudo +has write access to the command or its parent directory. +The following digest formats are supported: sha224, sha256, sha384 and sha512. +The digest name must be followed by a colon +.Pq Ql :\& +and then the actual digest, in either hex or base64 format. +For example, given the following value for sudoCommand: +.Bd -literal -offset 4n +sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ /bin/ls +.Ed +.Pp +The user may only run +.Pa /bin/ls +if its sha224 digest matches the specified value. +Command digests are only supported by version 1.8.7 or higher. +.It Sy sudoOption +Identical in function to the global options described above, but +specific to the +.Li sudoRole +in which it resides. +.It Sy sudoRunAsUser +A user name or uid (prefixed with +.Ql # ) +that commands may be run as or a Unix group (prefixed with a +.Ql % ) +or user netgroup (prefixed with a +.Ql + ) +that contains a list of users that commands may be run as. +The special value +.Li ALL +will match any user. +If a +.Li sudoRunAsUser +entry is preceded by an exclamation point, +.Ql \&! , +and the entry matches, the +.Li sudoRole +in which it resides will be ignored. +If +.Li sudoRunAsUser +is specified but empty, it will match the invoking user. +If neither +.Li sudoRunAsUser +nor +.Li sudoRunAsGroup +are present, the value of the +.Em runas_default +.Li sudoOption +is used (defaults to +.Li @runas_default@ ) . +.Pp +The +.Li sudoRunAsUser +attribute is only available in +.Nm sudo +versions +1.7.0 and higher. +Older versions of +.Nm sudo +use the +.Li sudoRunAs +attribute instead. +Negated +.Li sudoRunAsUser +entries are only supported by version 1.8.26 or higher. +.It Sy sudoRunAsGroup +A Unix group or gid (prefixed with +.Ql # ) +that commands may be run as. +The special value +.Li ALL +will match any group. +If a +.Li sudoRunAsGroup +entry is preceded by an exclamation point, +.Ql \&! , +and the entry matches, the +.Li sudoRole +in which it resides will be ignored. +.Pp +The +.Li sudoRunAsGroup +attribute is only available in +.Nm sudo +versions +1.7.0 and higher. +Negated +.Li sudoRunAsGroup +entries are only supported by version 1.8.26 or higher. +.It Sy sudoNotBefore +A timestamp in the form +.Li yyyymmddHHMMSSZ +that can be used to provide a start date/time for when the +.Li sudoRole +will be valid. +If multiple +.Li sudoNotBefore +entries are present, the earliest is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.Pp +The +.Li sudoNotBefore +attribute is only available in +.Nm sudo +versions 1.7.5 and higher and must be explicitly enabled via the +.Sy SUDOERS_TIMED +option in +.Pa @ldap_conf@ . +.It Sy sudoNotAfter +A timestamp in the form +.Li yyyymmddHHMMSSZ +that indicates an expiration date/time, after which the +.Li sudoRole +will no longer be valid. +If multiple +.Li sudoNotAfter +entries are present, the last one is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.Pp +The +.Li sudoNotAfter +attribute is only available in +.Nm sudo +versions +1.7.5 and higher and must be explicitly enabled via the +.Sy SUDOERS_TIMED +option in +.Pa @ldap_conf@ . +.It Sy sudoOrder +The +.Li sudoRole +entries retrieved from the LDAP directory have no inherent order. +The +.Li sudoOrder +attribute is an integer (or floating point value for LDAP servers +that support it) that is used to sort the matching entries. +This allows LDAP-based sudoers entries to more closely mimic the behavior +of the sudoers file, where the order of the entries influences the result. +If multiple entries match, the entry with the highest +.Li sudoOrder +attribute is chosen. +This corresponds to the +.Dq last match +behavior of the sudoers file. +If the +.Li sudoOrder +attribute is not present, a value of 0 is assumed. +.Pp +The +.Li sudoOrder +attribute is only available in +.Nm sudo +versions 1.7.5 and higher. +.El +.Pp +Each attribute listed above should contain a single value, but there +may be multiple instances of each attribute type. +A +.Li sudoRole +must contain at least one +.Li sudoUser , +.Li sudoHost +and +.Li sudoCommand . +.Pp +The following example allows users in group wheel to run any command +on any host via +.Nm sudo : +.Bd -literal -offset 4n +dn: cn=%wheel,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: %wheel +sudoUser: %wheel +sudoHost: ALL +sudoCommand: ALL +.Ed +.Ss Anatomy of LDAP sudoers lookup +When looking up a sudoer using LDAP there are only two or three +LDAP queries per invocation. +The first query is to parse the global options. +The second is to match against the user's name and the groups that +the user belongs to. +(The special +.Li ALL +tag is matched in this query too.) +If no match is returned for the user's name and groups, a third +query returns all entries containing user netgroups and other +non-Unix groups and checks to see if the user belongs to any of them. +.Pp +If timed entries are enabled with the +.Sy SUDOERS_TIMED +configuration directive, the LDAP queries include a sub-filter that +limits retrieval to entries that satisfy the time constraints, if any. +.Pp +If the +.Sy NETGROUP_BASE +configuration directive is present (see +.Sx Configuring ldap.conf +below), queries are performed to determine +the list of netgroups the user belongs to before the sudoers query. +This makes it possible to include netgroups in the sudoers query +string in the same manner as Unix groups. +The third query mentioned above is not performed unless a group provider +plugin is also configured. +The actual LDAP queries performed by +.Nm sudo +are as follows: +.Bl -enum +.It +Match all +.Li nisNetgroup +records with a +.Li nisNetgroupTriple +containing the user, host and NIS domain. +The query will match +.Li nisNetgroupTriple +entries with either the short or long form of the host name or +no host name specified in the tuple. +If the NIS domain is set, the query will match only match entries +that include the domain or for which there is no domain present. +If the NIS domain is +.Em not +set, a wildcard is used to match any domain name but be aware that the +NIS schema used by some LDAP servers may not support wild cards for +.Li nisNetgroupTriple . +.It +Repeated queries are performed to find any nested +.Li nisNetgroup +records with a +.Li memberNisNetgroup +entry that refers to an already-matched record. +.El +.Pp +For sites with a large number of netgroups, using +.Sy NETGROUP_BASE +can significantly speed up +.Nm sudo Ns 's +execution time. +.Ss Differences between LDAP and non-LDAP sudoers +One of the major differences between LDAP and file-based +.Em sudoers +is that in LDAP, +.Nm sudo Ns -specific +Aliases are not supported. +.Pp +For the most part, there is little need for +.Nm sudo Ns -specific +Aliases. +Unix groups, non-Unix groups (via the +.Em group_plugin ) +or user netgroups can be used in place of User_Aliases and Runas_Aliases. +Host netgroups can be used in place of Host_Aliases. +Since groups and netgroups can also be stored in LDAP there is no real need for +.Nm sudo Ns -specific +aliases. +.Pp +There are also some subtle differences in the way sudoers is handled +once in LDAP. +Probably the biggest is that according to the RFC, LDAP ordering +is arbitrary and you cannot expect that Attributes and Entries are +returned in any specific order. +.Pp +The order in which different entries are applied can be controlled +using the +.Li sudoOrder +attribute, but there is no way to guarantee the order of attributes +within a specific entry. +If there are conflicting command rules in an entry, the negative +takes precedence. +This is called paranoid behavior (not necessarily the most specific +match). +.Pp +Here is an example: +.Bd -literal -offset 4n +# /etc/sudoers: +# Allow all commands except shell +johnny ALL=(root) ALL,!/bin/sh +# Always allows all commands because ALL is matched last +puddles ALL=(root) !/bin/sh,ALL + +# LDAP equivalent of johnny +# Allows all commands except shell +dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role1 +sudoUser: johnny +sudoHost: ALL +sudoCommand: ALL +sudoCommand: !/bin/sh + +# LDAP equivalent of puddles +# Notice that even though ALL comes last, it still behaves like +# role1 since the LDAP code assumes the more paranoid configuration +dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role2 +sudoUser: puddles +sudoHost: ALL +sudoCommand: !/bin/sh +sudoCommand: ALL +.Ed +.Pp +Another difference is that it is not possible to use negation in a +sudoUser, sudoRunAsUser or sudoRunAsGroup attribute. +For example, the following attributes do not behave the way one might expect. +.Bd -literal -offset 4n +# does not match all but joe +# rather, does not match anyone +sudoUser: !joe + +# does not match all but joe +# rather, matches everyone including Joe +sudoUser: ALL +sudoUser: !joe +.Ed +.Ss Converting between file-based and LDAP sudoers +The +.Xr cvtsudoers 1 +utility can be used to convert between file-based and LDAP +.Em sudoers . +However, there are features in the file-based sudoers that have +no equivalent in LDAP-based sudoers (and vice versa). +These cannot be converted automatically. +.Pp +For example, a Cmnd_Alias in a +.Em sudoers +file may be converted to a +.Li sudoRole +that contains multiple commands. +Multiple users and/or groups may be assigned to the +.Li sudoRole . +.Pp +Also, host, user, runas and command-based +.Li Defaults +entries are not supported. +However, a +.Li sudoRole +may contain one or more +.Li sudoOption +attributes which can often serve the same purpose. +.Pp +Consider the following +.Em sudoers +lines: +.Bd -literal -offset 4n +Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less +Defaults!PAGERS noexec +alice, bob ALL = ALL +.Ed +.Pp +In this example, alice and bob are allowed to run all commands, but +the commands listed in PAGERS will have the noexec flag set, +preventing shell escapes. +.Pp +When converting this to LDAP, two sudoRole objects can be used: +.Bd -literal -offset 4n +dn: cn=PAGERS,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: PAGERS +sudoUser: alice +sudoUser: bob +sudoHost: ALL +sudoCommand: /usr/bin/more +sudoCommand: /usr/bin/pg +sudoCommand: /usr/bin/less +sudoOption: noexec +sudoOrder: 900 + +dn: cn=ADMINS,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: ADMINS +sudoUser: alice +sudoUser: bob +sudoHost: ALL +sudoCommand: ALL +sudoOrder: 100 +.Ed +.Pp +In the LDAP version, the sudoOrder attribute is used to guarantee +that the PAGERS sudoRole with +.Em noexec +has precedence. +Unlike the +.Em sudoers +version, the LDAP version requires that all users for whom the restriction +should apply be assigned to the PAGERS sudoRole. +Using a Unix group or netgroup in PAGERS rather than listing each +user would make this easier to maintain. +.Pp +Per-user +.Li Defaults +entries can be emulated by using one or more sudoOption attributes +in a sudoRole. +Consider the following +.Em sudoers +lines: +.Bd -literal -offset 4n +User_Alias ADMINS = john, sally +Defaults:ADMINS !authenticate +ADMINS ALL = (ALL:ALL) ALL +.Ed +.Pp +In this example, john and sally are allowed to run any command +as any user or group. +.Pp +When converting this to LDAP, we can use a Unix group instead +of the User_Alias. +.Bd -literal -offset 4n +dn: cn=admins,ou=SUDOers,dc=my-domain,dc=com +objectClass: top +objectClass: sudoRole +cn: admins +sudoUser: %admin +sudoHost: ALL +sudoRunAsUser: ALL +sudoRunAsGroup: ALL +sudoCommand: ALL +sudoOption: !authenticate +.Ed +.Pp +This assumes that users john and sally are members of the +.Dq admins +Unix group. +.Ss Sudoers schema +In order to use +.Nm sudo Ns 's +LDAP support, the +.Nm sudo +schema must be +installed on your LDAP server. +In addition, be sure to index the +.Li sudoUser +attribute. +.Pp +The +.Nm sudo +distribution includes versions of the +.Nm sudoers +schema for multiple LDAP servers: +.Bl -tag -width 4n +.It Pa schema.OpenLDAP +OpenLDAP slapd and +.Ox +ldapd +.It Pa schema.olcSudo +OpenLDAP slapd 2.3 and higher when on-line configuration is enabled +.It Pa schema.iPlanet +Netscape-derived servers such as the iPlanet, Oracle, +and 389 Directory Servers +.It Pa schema.ActiveDirectory +Microsoft Active Directory +.El +.Pp +The schema in OpenLDAP format is also included in the +.Sx EXAMPLES +section. +.Ss Configuring ldap.conf +Sudo reads the +.Pa @ldap_conf@ +file for LDAP-specific configuration. +Typically, this file is shared between different LDAP-aware clients. +As such, most of the settings are not +.Nm sudo Ns -specific. +Note that +.Nm sudo +parses +.Pa @ldap_conf@ +itself and may support options that differ from those described in the +system's +.Xr ldap.conf @mansectform@ +manual. +The path to +.Pa ldap.conf +may be overridden via the +.Em ldap_conf +plugin argument in +.Xr sudo.conf @mansectform@ . +.Pp +Also note that on systems using the OpenLDAP libraries, default +values specified in +.Pa /etc/openldap/ldap.conf +or the user's +.Pa .ldaprc +files are not used. +.Pp +Only those options explicitly listed in +.Pa @ldap_conf@ +as being supported by +.Nm sudo +are honored. +Configuration options are listed below in upper case but are parsed +in a case-independent manner. +.Pp +Lines beginning with a pound sign +.Pq Ql # +are ignored. +Leading white space is removed from the beginning of lines. +.Bl -tag -width 4n +.It Sy BIND_TIMELIMIT Ar seconds +The +.Sy BIND_TIMELIMIT +parameter specifies the amount of time, in seconds, to wait while trying +to connect to an LDAP server. +If multiple +.Sy URI Ns s +or +.Sy HOST Ns s +are specified, this is the amount of time to wait before trying +the next one in the list. +.It Sy BINDDN Ar DN +The +.Sy BINDDN +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing LDAP operations. +If not specified, LDAP operations are performed with an anonymous identity. +By default, most LDAP servers will allow anonymous access. +.It Sy BINDPW Ar secret +The +.Sy BINDPW +parameter specifies the password to use when performing LDAP operations. +This is typically used in conjunction with the +.Sy BINDDN +parameter. +The +.Ar secret +may be a plain text password or a base64-encoded string with a +.Dq base64: +prefix. +For example: +.Bd -literal -offset 4n +BINDPW base64:dGVzdA== +.Ed +.Pp +If a plain text password is used, it should be a simple string without quotes. +Plain text passwords may not include the comment character +.Pq Ql # +and the escaping of special characters with a backslash +.Pq Ql \e +is not supported. +.It Sy DEREF Ar never/searching/finding/always +How alias dereferencing is to be performed when searching. +See the +.Xr ldap.conf @mansectform@ +manual for a full description of this option. +.It Sy HOST Ar name[:port] ... +If no +.Sy URI +is specified (see below), the +.Sy HOST +parameter specifies a white space-delimited list of LDAP servers to connect to. +Each host may include an optional +.Em port +separated by a colon +.Pq Ql :\& . +The +.Sy HOST +parameter is deprecated in favor of the +.Sy URI +specification and is included for backwards compatibility only. +.It Sy KRB5_CCNAME Ar file name +The path to the Kerberos 5 credential cache to use when authenticating +with the remote server. +This option is only relevant when using SASL authentication (see below). +.It Sy LDAP_VERSION Ar number +The version of the LDAP protocol to use when connecting to the server. +The default value is protocol version 3. +.It Sy NETGROUP_BASE Ar base +The base DN to use when performing LDAP netgroup queries. +Typically this is of the form +.Li ou=netgroup,dc=my-domain,dc=com +for the domain +.Li my-domain.com . +Multiple +.Sy NETGROUP_BASE +lines may be specified, in which case they are queried in the order specified. +.Pp +This option can be used to query a user's netgroups directly via LDAP +which is usually faster than fetching every +.Li sudoRole +object containing a +.Li sudoUser +that begins with a +.Ql + +prefix. +The NIS schema used by some LDAP servers need a modification to +support querying the +.Li nisNetgroup +object by its +.Li nisNetgroupTriple +member. +OpenLDAP's +.Sy slapd +requires the following change to the +.Li nisNetgroupTriple +attribute: +.Bd -literal -offset 4n +attributetype ( 1.3.6.1.1.1.1.14 NAME 'nisNetgroupTriple' + DESC 'Netgroup triple' + EQUALITY caseIgnoreIA5Match + SUBSTR caseIgnoreIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) +.Ed +.It Sy NETGROUP_SEARCH_FILTER Ar ldap_filter +An LDAP filter which is used to restrict the set of records returned +when performing an LDAP netgroup query. +Typically, this is of the +form +.Li attribute=value +or +.Li (&(attribute=value)(attribute2=value2)) . +The default search filter is: +.Li objectClass=nisNetgroup . +If +.Ar ldap_filter +is omitted, no search filter will be used. +This option is only when querying netgroups directly via LDAP. +.It Sy NETWORK_TIMEOUT Ar seconds +An alias for +.Sy BIND_TIMELIMIT +provided for OpenLDAP compatibility. +.It Sy PORT Ar port_number +If no +.Sy URI +is specified, the +.Sy PORT +parameter specifies the default port to connect to on the LDAP server if a +.Sy HOST +parameter does not specify the port itself. +If no +.Sy PORT +parameter is used, the default is port 389 for LDAP and port 636 for LDAP +over TLS (SSL). +The +.Sy PORT +parameter is deprecated in favor of the +.Sy URI +specification and is included for backwards compatibility only. +.It Sy ROOTBINDDN Ar DN +The +.Sy ROOTBINDDN +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing privileged LDAP operations, such as +.Em sudoers +queries. +The password corresponding to the identity should be stored in the +or the path specified by the +.Em ldap_secret +plugin argument in +.Xr sudo.conf @mansectform@ , +which defaults to +.Pa @ldap_secret@ . +If no +.Sy ROOTBINDDN +is specified, the +.Sy BINDDN +identity is used (if any). +.It Sy ROOTUSE_SASL Ar on/true/yes/off/false/no +Enable +.Sy ROOTUSE_SASL +to enable SASL authentication when connecting +to an LDAP server from a privileged process, such as +.Nm sudo . +.It Sy SASL_AUTH_ID Ar identity +The SASL user name to use when connecting to the LDAP server. +By default, +.Nm sudo +will use an anonymous connection. +This option is only relevant when using SASL authentication. +.It Sy SASL_MECH Ar mechanisms +A white space-delimited list of SASL authentication mechanisms to use. +By default, +.Nm sudo +will use +.Dv GSSAPI +authentication. +.It Sy SASL_SECPROPS Ar none/properties +SASL security properties or +.Em none +for no properties. +See the SASL programmer's manual for details. +This option is only relevant when using SASL authentication. +.It Sy SSL Ar on/true/yes/off/false/no +If the +.Sy SSL +parameter is set to +.Li on , +.Li true +.Li or +.Li yes , +TLS (SSL) encryption is always used when communicating with the LDAP server. +Typically, this involves connecting to the server on port 636 (ldaps). +.It Sy SSL Ar start_tls +If the +.Sy SSL +parameter is set to +.Li start_tls , +the LDAP server connection is initiated normally and TLS encryption is +begun before the bind credentials are sent. +This has the advantage of not requiring a dedicated port for encrypted +communications. +This parameter is only supported by LDAP servers that honor the +.Em start_tls +extension, such as the OpenLDAP and Tivoli Directory servers. +.It Sy SUDOERS_BASE Ar base +The base DN to use when performing +.Nm sudo +LDAP queries. +Typically this is of the form +.Li ou=SUDOers,dc=my-domain,dc=com +for the domain +.Li my-domain.com . +Multiple +.Sy SUDOERS_BASE +lines may be specified, in which case they are queried in the order specified. +.It Sy SUDOERS_DEBUG Ar debug_level +This sets the debug level for +.Nm sudo +LDAP queries. +Debugging information is printed to the standard error. +A value of 1 results in a moderate amount of debugging information. +A value of 2 shows the results of the matches themselves. +This parameter should not be set in a production environment as the +extra information is likely to confuse users. +.Pp +The +.Sy SUDOERS_DEBUG +parameter is deprecated and will be removed in a future release. +The same information is now logged via the +.Nm sudo +debugging framework using the +.Dq ldap +subsystem at priorities +.Em diag +and +.Em info +for +.Em debug_level +values 1 and 2 respectively. +See the +.Xr sudo.conf @mansectform@ +manual for details on how to configure +.Nm sudo +debugging. +.It Sy SUDOERS_SEARCH_FILTER Ar ldap_filter +An LDAP filter which is used to restrict the set of records returned +when performing a +.Nm sudo +LDAP query. +Typically, this is of the +form +.Li attribute=value +or +.Li (&(attribute=value)(attribute2=value2)) . +The default search filter is: +.Li objectClass=sudoRole . +If +.Ar ldap_filter +is omitted, no search filter will be used. +.It Sy SUDOERS_TIMED Ar on/true/yes/off/false/no +Whether or not to evaluate the +.Li sudoNotBefore +and +.Li sudoNotAfter +attributes that implement time-dependent sudoers entries. +.It Sy TIMELIMIT Ar seconds +The +.Sy TIMELIMIT +parameter specifies the amount of time, in seconds, to wait for a +response to an LDAP query. +.It Sy TIMEOUT Ar seconds +The +.Sy TIMEOUT +parameter specifies the amount of time, in seconds, to wait for a +response from the various LDAP APIs. +.It Sy TLS_CACERT Ar file name +An alias for +.Sy TLS_CACERTFILE +for OpenLDAP compatibility. +.It Sy TLS_CACERTFILE Ar file name +The path to a certificate authority bundle which contains the certificates +for all the Certificate Authorities the client knows to be valid, e.g., +.Pa /etc/ssl/ca-bundle.pem . +This option is only supported by the OpenLDAP libraries. +Netscape-derived LDAP libraries use the same certificate +database for CA and client certificates (see +.Sy TLS_CERT ) . +.It Sy TLS_CACERTDIR Ar directory +Similar to +.Sy TLS_CACERTFILE +but instead of a file, it is a directory containing individual +Certificate Authority certificates, e.g., +.Pa /etc/ssl/certs . +The directory specified by +.Sy TLS_CACERTDIR +is checked after +.Sy TLS_CACERTFILE . +This option is only supported by the OpenLDAP libraries. +.It Sy TLS_CERT Ar file name +The path to a file containing the client certificate which can +be used to authenticate the client to the LDAP server. +The certificate type depends on the LDAP libraries used. +.Bl -tag -width 4n +.It OpenLDAP: +.Li tls_cert /etc/ssl/client_cert.pem +.It Netscape-derived: +.Li tls_cert /var/ldap/cert7.db +.It Tivoli Directory Server: +Unused, the key database specified by +.Sy TLS_KEY +contains both keys and certificates. +.Pp +When using Netscape-derived libraries, this file may also contain +Certificate Authority certificates. +.El +.It Sy TLS_CHECKPEER Ar on/true/yes/off/false/no +If enabled, +.Sy TLS_CHECKPEER +will cause the LDAP server's TLS certificated to be verified. +If the server's TLS certificate cannot be verified (usually because it +is signed by an unknown certificate authority), +.Nm sudo +will be unable to connect to it. +If +.Sy TLS_CHECKPEER +is disabled, no check is made. +Note that disabling the check creates an opportunity for man-in-the-middle +attacks since the server's identity will not be authenticated. +If possible, the CA's certificate should be installed locally so it can +be verified. +This option is not supported by the Tivoli Directory Server LDAP libraries. +.It Sy TLS_KEY Ar file name +The path to a file containing the private key which matches the +certificate specified by +.Sy TLS_CERT . +The private key must not be password-protected. +The key type depends on the LDAP libraries used. +.Bl -tag -width 4n +.It OpenLDAP: +.Li tls_key /etc/ssl/client_key.pem +.It Netscape-derived: +.Li tls_key /var/ldap/key3.db +.It Tivoli Directory Server: +.Li tls_key /usr/ldap/ldapkey.kdb +.El +When using Tivoli LDAP libraries, this file may also contain +Certificate Authority and client certificates and may be encrypted. +.It Sy TLS_CIPHERS Ar cipher list +The +.Sy TLS_CIPHERS +parameter allows the administer to restrict which encryption algorithms +may be used for TLS (SSL) connections. +See the OpenLDAP or Tivoli Directory Server manual for a list of valid +ciphers. +This option is not supported by Netscape-derived libraries. +.It Sy TLS_KEYPW Ar secret +The +.Sy TLS_KEYPW +contains the password used to decrypt the key database on clients +using the Tivoli Directory Server LDAP library. +The +.Ar secret +may be a plain text password or a base64-encoded string with a +.Dq base64: +prefix. +For example: +.Bd -literal -offset 4n +TLS_KEYPW base64:dGVzdA== +.Ed +.Pp +If a plain text password is used, it should be a simple string without quotes. +Plain text passwords may not include the comment character +.Pq Ql # +and the escaping of special characters with a backslash +.Pq Ql \e +is not supported. +If this option is used, +.Pa @ldap_conf@ +must not be world-readable to avoid exposing the password. +Alternately, a +.Em stash file +can be used to store the password in encrypted form (see below). +.Pp +If no +.Sy TLS_KEYPW +is specified, a +.Em stash file +will be used if it exists. +The +.Em stash file +must have the same path as the file specified by +.Sy TLS_KEY , +but use a +.Li .sth +file extension instead of +.Li .kdb , +e.g., +.Li ldapkey.sth . +The default +.Li ldapkey.kdb +that ships with Tivoli Directory Server is encrypted with the password +.Li ssl_password . +The +.Em gsk8capicmd +utility can be used to manage the key database and create a +.Em stash file . +This option is only supported by the Tivoli LDAP libraries. +.It Sy TLS_REQCERT Ar level +The +.Sy TLS_REQCERT +parameter controls how the LDAP server's TLS certificated will be +verified (if at all). +If the server's TLS certificate cannot be verified (usually because it +is signed by an unknown certificate authority), +.Nm sudo +will be unable to connect to it. +The following +.Ar level +values are supported: +.Bl -tag -width 8n -offset 4n +.It never +The server certificate will not be requested or checked. +.It allow +The server certificate will be requested. +A missing or invalid certificate is ignored and not considered an error. +.It try +The server certificate will be requested. +A missing certificate is ignored but an invalid certificate will +result in a connection error. +.It demand | Ar hard +The server certificate will be requested. +A missing or invalid certificate will result in a connection error. +This is the default behavior. +.El +.Pp +This option is only supported by the OpenLDAP libraries. +Other LDAP libraries only support the +.Sy TLS_CHECKPEER +parameter. +.It Sy TLS_RANDFILE Ar file name +The +.Sy TLS_RANDFILE +parameter specifies the path to an entropy source for systems that lack +a random device. +It is generally used in conjunction with +.Em prngd +or +.Em egd . +This option is only supported by the OpenLDAP libraries. +.It Sy URI Ar ldap[s]://[hostname[:port]] ... +Specifies a white space-delimited list of one or more URIs describing +the LDAP server(s) to connect to. +The +.Em protocol +may be either +.Em ldap +.Em ldaps , +the latter being for servers that support TLS (SSL) encryption. +If no +.Em port +is specified, the default is port 389 for +.Li ldap:// +or port 636 for +.Li ldaps:// . +If no +.Em hostname +is specified, +.Nm sudo +will connect to +.Em localhost . +Multiple +.Sy URI +lines are treated identically to a +.Sy URI +line containing multiple entries. +Only systems using the OpenSSL libraries support the mixing of +.Li ldap:// +and +.Li ldaps:// +URIs. +Both the Netscape-derived and Tivoli LDAP libraries used on most commercial +versions of Unix are only capable of supporting one or the other. +.It Sy USE_SASL Ar on/true/yes/off/false/no +Enable +.Sy USE_SASL +for LDAP servers that support SASL authentication. +.It Sy ROOTSASL_AUTH_ID Ar identity +The SASL user name to use when +.Sy ROOTUSE_SASL +is enabled. +.El +.Pp +See the +.Pa ldap.conf +entry in the +.Sx EXAMPLES +section. +.Ss Configuring nsswitch.conf +Unless it is disabled at build time, +.Nm sudo +consults the Name Service Switch file, +.Pa @nsswitch_conf@ , +to specify the +.Em sudoers +search order. +Sudo looks for a line beginning with +.Li sudoers : +and uses this to determine the search order. +Note that +.Nm sudo +does +not stop searching after the first match and later matches take +precedence over earlier ones. +The following sources are recognized: +.Pp +.Bl -tag -width 8n -offset 4n -compact +.It files +read sudoers from +.Pa @sysconfdir@/sudoers +.It ldap +read sudoers from LDAP +.El +.Pp +In addition, the entry +.Li [NOTFOUND=return] +will short-circuit the search if the user was not found in the +preceding source. +.Pp +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.Bd -literal -offset 4n +sudoers: ldap files +.Ed +.Pp +The local +.Em sudoers +file can be ignored completely by using: +.Bd -literal -offset 4n +sudoers: ldap +.Ed +.Pp +If the +.Pa @nsswitch_conf@ +file is not present or there is no sudoers line, the following +default is assumed: +.Bd -literal -offset 4n +sudoers: files +.Ed +.Pp +Note that +.Pa @nsswitch_conf@ +is supported even when the underlying operating system does not use +an nsswitch.conf file, except on AIX (see below). +.Ss Configuring netsvc.conf +On AIX systems, the +.Pa @netsvc_conf@ +file is consulted instead of +.Pa @nsswitch_conf@ . +.Nm sudo +simply treats +.Pa netsvc.conf +as a variant of +.Pa nsswitch.conf ; +information in the previous section unrelated to the file format +itself still applies. +.Pp +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.Bd -literal -offset 4n +sudoers = ldap, files +.Ed +.Pp +The local +.Em sudoers +file can be ignored completely by using: +.Bd -literal -offset 4n +sudoers = ldap +.Ed +.Pp +To treat LDAP as authoritative and only use the local sudoers file +if the user is not present in LDAP, use: +.Bd -literal -offset 4n +sudoers = ldap = auth, files +.Ed +.Pp +Note that in the above example, the +.Li auth +qualifier only affects user lookups; both LDAP and +.Em sudoers +will be queried for +.Li Defaults +entries. +.Pp +If the +.Pa @netsvc_conf@ +file is not present or there is no sudoers line, the following +default is assumed: +.Bd -literal -offset 4n +sudoers = files +.Ed +.Ss Integration with sssd +On systems with the +.Em System Security Services Daemon +(SSSD) and where +.Nm sudo +has been built with SSSD support, +it is possible to use SSSD to cache LDAP +.Em sudoers +rules. +To use SSSD as the +.Em sudoers +source, you should use +.Li sssd +instead of +.Li ldap +for the sudoers entry in +.Pa @nsswitch_conf@ . +Note that the +.Pa @ldap_conf@ +file is not used by the SSSD +.Nm sudo +back end. +Please see +.Xr sssd-sudo @mansectform@ +for more information on configuring +.Nm sudo +to work with SSSD. +.Sh FILES +.Bl -tag -width 24n +.It Pa @ldap_conf@ +LDAP configuration file +.It Pa @nsswitch_conf@ +determines sudoers source order +.It Pa @netsvc_conf@ +determines sudoers source order on AIX +.El +.Sh EXAMPLES +.Ss Example ldap.conf +.Bd -literal -offset 2n +# Either specify one or more URIs or one or more host:port pairs. +# If neither is specified sudo will default to localhost, port 389. +# +#host ldapserver +#host ldapserver1 ldapserver2:390 +# +# Default port if host is specified without one, defaults to 389. +#port 389 +# +# URI will override the host and port settings. +uri ldap://ldapserver +#uri ldaps://secureldapserver +#uri ldaps://secureldapserver ldap://ldapserver +# +# The amount of time, in seconds, to wait while trying to connect to +# an LDAP server. +bind_timelimit 30 +# +# The amount of time, in seconds, to wait while performing an LDAP query. +timelimit 30 +# +# Must be set or sudo will ignore LDAP; may be specified multiple times. +sudoers_base ou=SUDOers,dc=my-domain,dc=com +# +# verbose sudoers matching from ldap +#sudoers_debug 2 +# +# Enable support for time-based entries in sudoers. +#sudoers_timed yes +# +# optional proxy credentials +#binddn <who to search as> +#bindpw <password> +#rootbinddn <who to search as, uses /etc/ldap.secret for bindpw> +# +# LDAP protocol version, defaults to 3 +#ldap_version 3 +# +# Define if you want to use an encrypted LDAP connection. +# Typically, you must also set the port to 636 (ldaps). +#ssl on +# +# Define if you want to use port 389 and switch to +# encryption before the bind credentials are sent. +# Only supported by LDAP servers that support the start_tls +# extension such as OpenLDAP. +#ssl start_tls +# +# Additional TLS options follow that allow tweaking of the +# SSL/TLS connection. +# +#tls_checkpeer yes # verify server SSL certificate +#tls_checkpeer no # ignore server SSL certificate +# +# If you enable tls_checkpeer, specify either tls_cacertfile +# or tls_cacertdir. Only supported when using OpenLDAP. +# +#tls_cacertfile /etc/certs/trusted_signers.pem +#tls_cacertdir /etc/certs +# +# For systems that don't have /dev/random +# use this along with PRNGD or EGD.pl to seed the +# random number pool to generate cryptographic session keys. +# Only supported when using OpenLDAP. +# +#tls_randfile /etc/egd-pool +# +# You may restrict which ciphers are used. Consult your SSL +# documentation for which options go here. +# Only supported when using OpenLDAP. +# +#tls_ciphers <cipher-list> +# +# Sudo can provide a client certificate when communicating to +# the LDAP server. +# Tips: +# * Enable both lines at the same time. +# * Do not password protect the key file. +# * Ensure the keyfile is only readable by root. +# +# For OpenLDAP: +#tls_cert /etc/certs/client_cert.pem +#tls_key /etc/certs/client_key.pem +# +# For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either +# a directory, in which case the files in the directory must have the +# default names (e.g., cert8.db and key4.db), or the path to the cert +# and key files themselves. However, a bug in version 5.0 of the LDAP +# SDK will prevent specific file names from working. For this reason +# it is suggested that tls_cert and tls_key be set to a directory, +# not a file name. +# +# The certificate database specified by tls_cert may contain CA certs +# and/or the client's cert. If the client's cert is included, tls_key +# should be specified as well. +# For backward compatibility, "sslpath" may be used in place of tls_cert. +#tls_cert /var/ldap +#tls_key /var/ldap +# +# If using SASL authentication for LDAP (OpenSSL) +# use_sasl yes +# sasl_auth_id <SASL user name> +# rootuse_sasl yes +# rootsasl_auth_id <SASL user name for root access> +# sasl_secprops none +# krb5_ccname /etc/.ldapcache +.Ed +.Ss Sudoers schema for OpenLDAP +The following schema, in OpenLDAP format, is included with +.Nm sudo +source and binary distributions as +.Pa schema.OpenLDAP . +Simply copy +it to the schema directory (e.g., +.Pa /etc/openldap/schema ) , +add the proper +.Li include +line in +.Pa slapd.conf +and restart +.Nm slapd . +Sites using the optional on-line configuration supported by OpenLDAP 2.3 +and higher should apply the +.Pa schema.olcSudo +file instead. +.Bd -literal -offset 2n +attributetype ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + +objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ + sudoRunAsGroup $ sudoOption $ sudoNotBefore $ sudoNotAfter $ + sudoOrder $ description ) + ) +.Ed +.Sh SEE ALSO +.Xr cvtsudoers 1 , +.Xr ldap.conf @mansectform@ , +.Xr sssd-sudo @mansectform@ , +.Xr sudo.conf @mansectform@ , +.Xr sudoers @mansectform@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh CAVEATS +Note that there are differences in the way that LDAP-based +.Em sudoers +is parsed compared to file-based +.Em sudoers . +See the +.Sx Differences between LDAP and non-LDAP sudoers +section for more information. +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in new file mode 100644 index 0000000..e2470b5 --- /dev/null +++ b/doc/sudoers.man.in @@ -0,0 +1,5831 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.nr SL @SEMAN@ +.nr BA @BAMAN@ +.nr LC @LCMAN@ +.nr PS @PSMAN@ +.TH "SUDOERS" "@mansectform@" "December 20, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudoers\fR +\- default sudo security policy plugin +.SH "DESCRIPTION" +The +\fBsudoers\fR +policy plugin determines a user's +\fBsudo\fR +privileges. +It is the default +\fBsudo\fR +policy plugin. +The policy is driven by +the +\fI@sysconfdir@/sudoers\fR +file or, optionally in LDAP. +The policy format is described in detail in the +\fISUDOERS FILE FORMAT\fR +section. +For information on storing +\fBsudoers\fR +policy information +in LDAP, please see +sudoers.ldap(@mansectform@). +.SS "Configuring sudo.conf for sudoers" +\fBsudo\fR +consults the +sudo.conf(@mansectform@) +file to determine which policy and I/O logging plugins to load. +If no +sudo.conf(@mansectform@) +file is present, or if it contains no +\fRPlugin\fR +lines, +\fBsudoers\fR +will be used for policy decisions and I/O logging. +To explicitly configure +sudo.conf(@mansectform@) +to use the +\fBsudoers\fR +plugin, the following configuration can be used. +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.RE +.fi +.PP +Starting with +\fBsudo\fR +1.8.5, it is possible to specify optional arguments to the +\fBsudoers\fR +plugin in the +sudo.conf(@mansectform@) +file. +These arguments, if present, should be listed after the path to the plugin +(i.e., after +\fIsudoers.so\fR). +Multiple arguments may be specified, separated by white space. +For example: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so sudoers_mode=0400 +.RE +.fi +.PP +The following plugin arguments are supported: +.TP 10n +ldap_conf=pathname +The +\fIldap_conf\fR +argument can be used to override the default path to the +\fIldap.conf\fR +file. +.TP 10n +ldap_secret=pathname +The +\fIldap_secret\fR +argument can be used to override the default path to the +\fIldap.secret\fR +file. +.TP 10n +sudoers_file=pathname +The +\fIsudoers_file\fR +argument can be used to override the default path to the +\fIsudoers\fR +file. +.TP 10n +sudoers_uid=uid +The +\fIsudoers_uid\fR +argument can be used to override the default owner of the sudoers file. +It should be specified as a numeric user ID. +.TP 10n +sudoers_gid=gid +The +\fIsudoers_gid\fR +argument can be used to override the default group of the sudoers file. +It must be specified as a numeric group ID (not a group name). +.TP 10n +sudoers_mode=mode +The +\fIsudoers_mode\fR +argument can be used to override the default file mode for the sudoers file. +It should be specified as an octal value. +.PP +For more information on configuring +sudo.conf(@mansectform@), +please refer to its manual. +.SS "User Authentication" +The +\fBsudoers\fR +security policy requires that most users authenticate +themselves before they can use +\fBsudo\fR. +A password is not required +if the invoking user is root, if the target user is the same as the +invoking user, or if the policy has disabled authentication for the +user or command. +Unlike +su(1), +when +\fBsudoers\fR +requires +authentication, it validates the invoking user's credentials, not +the target user's (or root's) credentials. +This can be changed via +the +\fIrootpw\fR, +\fItargetpw\fR +and +\fIrunaspw\fR +flags, described later. +.PP +If a user who is not listed in the policy tries to run a command +via +\fBsudo\fR, +mail is sent to the proper authorities. +The address +used for such mail is configurable via the +\fImailto\fR +Defaults entry +(described later) and defaults to +\fR@mailto@\fR. +.PP +Note that no mail will be sent if an unauthorized user tries to run +\fBsudo\fR +with the +\fB\-l\fR +or +\fB\-v\fR +option unless there is an authentication error and +either the +\fImail_always\fR +or +\fImail_badpass\fR +flags are enabled. +This allows users to +determine for themselves whether or not they are allowed to use +\fBsudo\fR. +All attempts to run +\fBsudo\fR +(successful or not) +will be logged, regardless of whether or not mail is sent. +.PP +If +\fBsudo\fR +is run by root and the +\fRSUDO_USER\fR +environment variable +is set, the +\fBsudoers\fR +policy will use this value to determine who +the actual user is. +This can be used by a user to log commands +through sudo even when a root shell has been invoked. +It also +allows the +\fB\-e\fR +option to remain useful even when invoked via a +sudo-run script or program. +Note, however, that the +\fIsudoers\fR +file lookup is still done for root, not the user specified by +\fRSUDO_USER\fR. +.PP +\fBsudoers\fR +uses per-user time stamp files for credential caching. +Once a user has been authenticated, a record is written +containing the user ID that was used to authenticate, the +terminal session ID, the start time of the session leader +(or parent process) and a time stamp +(using a monotonic clock if one is available). +The user may then use +\fBsudo\fR +without a password for a short period of time +(\fR@timeout@\fR +minutes unless overridden by the +\fItimestamp_timeout\fR +option) +\&. +By default, +\fBsudoers\fR +uses a separate record for each terminal, which means that +a user's login sessions are authenticated separately. +The +\fItimestamp_type\fR +option can be used to select the type of time stamp record +\fBsudoers\fR +will use. +.SS "Logging" +\fBsudoers\fR +can log both successful and unsuccessful attempts (as well +as errors) to +syslog(3), +a log file, or both. +By default, +\fBsudoers\fR +will log via +syslog(3) +but this is changeable via the +\fIsyslog\fR +and +\fIlogfile\fR +Defaults settings. +See +\fILOG FORMAT\fR +for a description of the log file format. +.PP +\fBsudoers\fR +is also capable of running a command in a pseudo-tty and logging all +input and/or output. +The standard input, standard output and standard error can be logged +even when not associated with a terminal. +I/O logging is not on by default but can be enabled using +the +\fIlog_input\fR +and +\fIlog_output\fR +options as well as the +\fRLOG_INPUT\fR +and +\fRLOG_OUTPUT\fR +command tags. +See +\fII/O LOG FILES\fR +for details on how I/O log files are stored. +.SS "Command environment" +Since environment variables can influence program behavior, +\fBsudoers\fR +provides a means to restrict which variables from the user's +environment are inherited by the command to be run. +There are two +distinct ways +\fBsudoers\fR +can deal with environment variables. +.PP +By default, the +\fIenv_reset\fR +option is enabled. +This causes commands +to be executed with a new, minimal environment. +On AIX (and Linux +systems without PAM), the environment is initialized with the +contents of the +\fI/etc/environment\fR +file. +.if \n(LC \{\ +On +BSD +systems, if the +\fIuse_loginclass\fR +option is enabled, the environment is initialized +based on the +\fIpath\fR +and +\fIsetenv\fR +settings in +\fI/etc/login.conf\fR. +.\} +The new environment contains the +\fRTERM\fR, +\fRPATH\fR, +\fRHOME\fR, +\fRMAIL\fR, +\fRSHELL\fR, +\fRLOGNAME\fR, +\fRUSER\fR +and +\fRSUDO_*\fR +variables +in addition to variables from the invoking process permitted by the +\fIenv_check\fR +and +\fIenv_keep\fR +options. +This is effectively a whitelist +for environment variables. +The environment variables +\fRLOGNAME\fR +and +\fRUSER\fR +are treated specially. +If one of them is preserved (or removed) from user's environment, the other +will be as well. +If +\fRLOGNAME\fR +and +\fRUSER\fR +are to be preserved but only one of them is present in the user's environment, +the other will be set to the same value. +This avoids an inconsistent environment where one of the variables +describing the user name is set to the invoking user and one is +set to the target user. +\fR()\fR +are removed unless both the name and value parts are matched by +\fIenv_keep\fR +or +\fIenv_check\fR, +as they may be interpreted as functions by the +\fBbash\fR +shell. +Prior to version 1.8.11, such variables were always removed. +.PP +If, however, the +\fIenv_reset\fR +option is disabled, any variables not +explicitly denied by the +\fIenv_check\fR +and +\fIenv_delete\fR +options are +inherited from the invoking process. +In this case, +\fIenv_check\fR +and +\fIenv_delete\fR +behave like a blacklist. +Prior to version 1.8.21, environment variables with a value beginning with +\fR()\fR +were always removed. +Beginning with version 1.8.21, a pattern in +\fIenv_delete\fR +is used to match +\fBbash\fR +shell functions instead. +Since it is not possible +to blacklist all potentially dangerous environment variables, use +of the default +\fIenv_reset\fR +behavior is encouraged. +.PP +Environment variables specified by +\fIenv_check\fR, +\fIenv_delete\fR, +or +\fIenv_keep\fR +may include one or more +\(oq*\(cq +characters which will match zero or more characters. +No other wildcard characters are supported. +.PP +By default, environment variables are matched by name. +However, if the pattern includes an equal sign +(\(oq=\&\(cq), +both the variables name and value must match. +For example, a +\fBbash\fR +shell function could be matched as follows: +.nf +.sp +.RS 4n +env_keep += "BASH_FUNC_my_func%%=()*" +.RE +.fi +.PP +Without the +\(lq\fR=()*\fR\(rq +suffix, this would not match, as +\fBbash\fR +shell functions are not preserved by default. +.PP +The complete list of environment variables that +\fBsudo\fR +allows or denies is contained in the output of +\(lq\fRsudo -V\fR\(rq +when run as root. +Please note that this list varies based on the operating system +\fBsudo\fR +is running on. +.PP +On systems that support PAM where the +\fBpam_env\fR +module is enabled for +\fBsudo\fR, +variables in the PAM environment may be merged in to the environment. +If a variable in the PAM environment is already present in the +user's environment, the value will only be overridden if the variable +was not preserved by +\fBsudoers\fR. +When +\fIenv_reset\fR +is enabled, variables preserved from the invoking user's environment +by the +\fIenv_keep\fR +list take precedence over those in the PAM environment. +When +\fIenv_reset\fR +is disabled, variables present the invoking user's environment +take precedence over those in the PAM environment unless they +match a pattern in the +\fIenv_delete\fR +list. +.PP +Note that the dynamic linker on most operating systems will remove +variables that can control dynamic linking from the environment of +setuid executables, including +\fBsudo\fR. +Depending on the operating +system this may include +\fR_RLD*\fR, +\fRDYLD_*\fR, +\fRLD_*\fR, +\fRLDR_*\fR, +\fRLIBPATH\fR, +\fRSHLIB_PATH\fR, +and others. +These type of variables are +removed from the environment before +\fBsudo\fR +even begins execution +and, as such, it is not possible for +\fBsudo\fR +to preserve them. +.PP +As a special case, if +\fBsudo\fR's +\fB\-i\fR +option (initial login) is +specified, +\fBsudoers\fR +will initialize the environment regardless +of the value of +\fIenv_reset\fR. +The +\fRDISPLAY\fR, +\fRPATH\fR +and +\fRTERM\fR +variables remain unchanged; +\fRHOME\fR, +\fRMAIL\fR, +\fRSHELL\fR, +\fRUSER\fR, +and +\fRLOGNAME\fR +are set based on the target user. +On AIX (and Linux +systems without PAM), the contents of +\fI/etc/environment\fR +are also +included. +.if \n(LC \{\ +On +BSD +systems, if the +\fIuse_loginclass\fR +flag is +enabled, the +\fIpath\fR +and +\fIsetenv\fR +variables in +\fI/etc/login.conf\fR +are also applied. +.\} +All other environment variables are removed unless permitted by +\fIenv_keep\fR +or +\fIenv_check\fR, +described above. +.PP +Finally, the +\fIrestricted_env_file\fR +and +\fIenv_file\fR +files are applied, if present. +The variables in +\fIrestricted_env_file\fR +are applied first and are subject to the same restrictions as the +invoking user's environment, as detailed above. +The variables in +\fIenv_file\fR +are applied last and are not subject to these restrictions. +In both cases, variables present in the files will only be set to +their specified values if they would not conflict with an existing +environment variable. +.SH "SUDOERS FILE FORMAT" +The +\fIsudoers\fR +file is composed of two types of entries: aliases +(basically variables) and user specifications (which specify who +may run what). +.PP +When multiple entries match for a user, they are applied in order. +Where there are multiple matches, the last match is used (which is +not necessarily the most specific match). +.PP +The +\fIsudoers\fR +file grammar will be described below in Extended Backus-Naur +Form (EBNF). +Don't despair if you are unfamiliar with EBNF; it is fairly simple, +and the definitions below are annotated. +.SS "Quick guide to EBNF" +EBNF is a concise and exact way of describing the grammar of a language. +Each EBNF definition is made up of +\fIproduction rules\fR. +E.g., +.PP +\fRsymbol ::= definition\fR | \fRalternate1\fR | \fRalternate2 ...\fR +.PP +Each +\fIproduction rule\fR +references others and thus makes up a +grammar for the language. +EBNF also contains the following +operators, which many readers will recognize from regular +expressions. +Do not, however, confuse them with +\(lqwildcard\(rq +characters, which have different meanings. +.TP 6n +\fR\&?\fR +Means that the preceding symbol (or group of symbols) is optional. +That is, it may appear once or not at all. +.TP 6n +\fR*\fR +Means that the preceding symbol (or group of symbols) may appear +zero or more times. +.TP 6n +\fR+\fR +Means that the preceding symbol (or group of symbols) may appear +one or more times. +.PP +Parentheses may be used to group symbols together. +For clarity, +we will use single quotes +('') +to designate what is a verbatim character string (as opposed to a symbol name). +.SS "Aliases" +There are four kinds of aliases: +\fRUser_Alias\fR, +\fRRunas_Alias\fR, +\fRHost_Alias\fR +and +\fRCmnd_Alias\fR. +.nf +.sp +.RS 0n +Alias ::= 'User_Alias' User_Alias_Spec (':' User_Alias_Spec)* | + 'Runas_Alias' Runas_Alias_Spec (':' Runas_Alias_Spec)* | + 'Host_Alias' Host_Alias_Spec (':' Host_Alias_Spec)* | + 'Cmnd_Alias' Cmnd_Alias_Spec (':' Cmnd_Alias_Spec)* + +User_Alias ::= NAME + +User_Alias_Spec ::= User_Alias '=' User_List + +Runas_Alias ::= NAME + +Runas_Alias_Spec ::= Runas_Alias '=' Runas_List + +Host_Alias ::= NAME + +Host_Alias_Spec ::= Host_Alias '=' Host_List + +Cmnd_Alias ::= NAME + +Cmnd_Alias_Spec ::= Cmnd_Alias '=' Cmnd_List + +NAME ::= [A-Z]([A-Z][0-9]_)* +.RE +.fi +.PP +Each +\fIalias\fR +definition is of the form +.nf +.sp +.RS 0n +Alias_Type NAME = item1, item2, ... +.RE +.fi +.PP +where +\fIAlias_Type\fR +is one of +\fRUser_Alias\fR, +\fRRunas_Alias\fR, +\fRHost_Alias\fR, +or +\fRCmnd_Alias\fR. +A +\fRNAME\fR +is a string of uppercase letters, numbers, +and underscore characters +(\(oq_\(cq). +A +\fRNAME\fR +\fBmust\fR +start with an +uppercase letter. +It is possible to put several alias definitions +of the same type on a single line, joined by a colon +(\(oq:\&\(cq). +E.g., +.nf +.sp +.RS 0n +Alias_Type NAME = item1, item2, item3 : NAME = item4, item5 +.RE +.fi +.PP +It is a syntax error to redefine an existing +\fIalias\fR. +It is possible to use the same name for +\fIaliases\fR +of different types, but this is not recommended. +.PP +The definitions of what constitutes a valid +\fIalias\fR +member follow. +.nf +.sp +.RS 0n +User_List ::= User | + User ',' User_List + +User ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* +netgroup | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* User_Alias +.RE +.fi +.PP +A +\fRUser_List\fR +is made up of one or more user names, user IDs +(prefixed with +\(oq#\(cq), +system group names and IDs (prefixed with +\(oq%\(cq +and +\(oq%#\(cq +respectively), netgroups (prefixed with +\(oq+\(cq), +non-Unix group names and IDs (prefixed with +\(oq%:\(cq +and +\(oq%:#\(cq +respectively) and +\fRUser_Alias\fRes. +Each list item may be prefixed with zero or more +\(oq\&!\(cq +operators. +An odd number of +\(oq\&!\(cq +operators negate the value of +the item; an even number just cancel each other out. +User netgroups are matched using the user and domain members only; +the host member is not used when matching. +.PP +A +\fRuser name\fR, +\fRuid\fR, +\fRgroup\fR, +\fRgid\fR, +\fRnetgroup\fR, +\fRnonunix_group\fR +or +\fRnonunix_gid\fR +may be enclosed in double quotes to avoid the +need for escaping special characters. +Alternately, special characters +may be specified in escaped hex mode, e.g., \ex20 for space. +When +using double quotes, any prefix characters must be included inside +the quotes. +.PP +The actual +\fRnonunix_group\fR +and +\fRnonunix_gid\fR +syntax depends on +the underlying group provider plugin. +For instance, the QAS AD plugin supports the following formats: +.TP 3n +\fB\(bu\fR +Group in the same domain: "%:Group Name" +.TP 3n +\fB\(bu\fR +Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" +.TP 3n +\fB\(bu\fR +Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" +.PP +See +\fIGROUP PROVIDER PLUGINS\fR +for more information. +.PP +Note that quotes around group names are optional. +Unquoted strings must use a backslash +(\(oq\e\(cq) +to escape spaces and special characters. +See +\fIOther special characters and reserved words\fR +for a list of +characters that need to be escaped. +.nf +.sp +.RS 0n +Runas_List ::= Runas_Member | + Runas_Member ',' Runas_List + +Runas_Member ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* +netgroup | + '!'* Runas_Alias +.RE +.fi +.PP +A +\fRRunas_List\fR +is similar to a +\fRUser_List\fR +except that instead +of +\fRUser_Alias\fRes +it can contain +\fRRunas_Alias\fRes. +Note that +user names and groups are matched as strings. +In other words, two +users (groups) with the same uid (gid) are considered to be distinct. +If you wish to match all user names with the same uid (e.g., +root and toor), you can use a uid instead (#0 in the example given). +.nf +.sp +.RS 0n +Host_List ::= Host | + Host ',' Host_List + +Host ::= '!'* host name | + '!'* ip_addr | + '!'* network(/netmask)? | + '!'* +netgroup | + '!'* Host_Alias +.RE +.fi +.PP +A +\fRHost_List\fR +is made up of one or more host names, IP addresses, +network numbers, netgroups (prefixed with +\(oq+\(cq) +and other aliases. +Again, the value of an item may be negated with the +\(oq\&!\(cq +operator. +Host netgroups are matched using the host (both qualified and unqualified) +and domain members only; the user member is not used when matching. +If you specify a network number without a netmask, +\fBsudo\fR +will query each of the local host's network interfaces and, +if the network number corresponds to one of the hosts's network +interfaces, will use the netmask of that interface. +The netmask may be specified either in standard IP address notation +(e.g., 255.255.255.0 or ffff:ffff:ffff:ffff::), +or CIDR notation (number of bits, e.g., 24 or 64). +A host name may include shell-style wildcards (see the +\fIWildcards\fR +section below), +but unless the +\fRhost name\fR +command on your machine returns the fully +qualified host name, you'll need to use the +\fIfqdn\fR +option for wildcards to be useful. +Note that +\fBsudo\fR +only inspects actual network interfaces; this means that IP address +127.0.0.1 (localhost) will never match. +Also, the host name +\(lqlocalhost\(rq +will only match if that is the actual host name, which is usually +only the case for non-networked systems. +.nf +.sp +.RS 0n +digest ::= [A-Fa-f0-9]+ | + [[A-Za-z0-9\+/=]+ + +Digest_Spec ::= "sha224" ':' digest | + "sha256" ':' digest | + "sha384" ':' digest | + "sha512" ':' digest + +Cmnd_List ::= Cmnd | + Cmnd ',' Cmnd_List + +command name ::= file name | + file name args | + file name '""' + +Cmnd ::= Digest_Spec? '!'* command name | + '!'* directory | + '!'* "sudoedit" | + '!'* Cmnd_Alias +.RE +.fi +.PP +A +\fRCmnd_List\fR +is a list of one or more command names, directories, and other aliases. +A command name is a fully qualified file name which may include +shell-style wildcards (see the +\fIWildcards\fR +section below). +A simple file name allows the user to run the command with any +arguments he/she wishes. +However, you may also specify command line arguments (including +wildcards). +Alternately, you can specify +\fR\&""\fR +to indicate that the command +may only be run +\fBwithout\fR +command line arguments. +A directory is a +fully qualified path name ending in a +\(oq/\(cq. +When you specify a directory in a +\fRCmnd_List\fR, +the user will be able to run any file within that directory +(but not in any sub-directories therein). +.PP +If a +\fRCmnd\fR +has associated command line arguments, then the arguments +in the +\fRCmnd\fR +must match exactly those given by the user on the command line +(or match the wildcards if there are any). +Note that the following characters must be escaped with a +\(oq\e\(cq +if they are used in command arguments: +\(oq,\&\(cq, +\(oq:\&\(cq, +\(oq=\&\(cq, +\(oq\e\(cq. +The built-in command +\(lq\fRsudoedit\fR\(rq +is used to permit a user to run +\fBsudo\fR +with the +\fB\-e\fR +option (or as +\fBsudoedit\fR). +It may take command line arguments just as a normal command does. +Note that +\(lq\fRsudoedit\fR\(rq +is a command built into +\fBsudo\fR +itself and must be specified in the +\fIsudoers\fR +file without a leading path. +.PP +If a +\fRcommand name\fR +is prefixed with a +\fRDigest_Spec\fR, +the command will only match successfully if it can be verified +using the specified SHA-2 digest. +The following digest formats are supported: sha224, sha256, sha384 and sha512. +The string may be specified in either hex or base64 format +(base64 is more compact). +There are several utilities capable of generating SHA-2 digests in hex +format such as openssl, shasum, sha224sum, sha256sum, sha384sum, sha512sum. +.PP +For example, using openssl: +.nf +.sp +.RS 0n +$ openssl dgst -sha224 /bin/ls +SHA224(/bin/ls)= 118187da8364d490b4a7debbf483004e8f3e053ec954309de2c41a25 +.RE +.fi +.PP +It is also possible to use openssl to generate base64 output: +.nf +.sp +.RS 0n +$ openssl dgst -binary -sha224 /bin/ls | openssl base64 +EYGH2oNk1JC0p9679IMATo8+BT7JVDCd4sQaJQ== +.RE +.fi +.PP +Warning, if the user has write access to the command itself (directly or via a +\fBsudo\fR +command), it may be possible for the user to replace the command after the +digest check has been performed but before the command is executed. +A similar race condition exists on systems that lack the +fexecve(2) +system call when the directory in which the command is located +is writable by the user. +See the description of the +\fIfdexec\fR +setting for more information on how +\fBsudo\fR +executes commands that have an associated digest. +.PP +Command digests are only supported by version 1.8.7 or higher. +.SS "Defaults" +Certain configuration options may be changed from their default +values at run-time via one or more +\fRDefault_Entry\fR +lines. +These may affect all users on any host, all users on a specific host, a +specific user, a specific command, or commands being run as a specific user. +Note that per-command entries may not include command line arguments. +If you need to specify arguments, define a +\fRCmnd_Alias\fR +and reference +that instead. +.nf +.sp +.RS 0n +Default_Type ::= 'Defaults' | + 'Defaults' '@' Host_List | + 'Defaults' ':' User_List | + 'Defaults' '!' Cmnd_List | + 'Defaults' '>' Runas_List + +Default_Entry ::= Default_Type Parameter_List + +Parameter_List ::= Parameter | + Parameter ',' Parameter_List + +Parameter ::= Parameter '=' Value | + Parameter '+=' Value | + Parameter '-=' Value | + '!'* Parameter +.RE +.fi +.PP +Parameters may be +\fBflags\fR, +\fBinteger\fR +values, +\fBstrings\fR, +or +\fBlists\fR. +Flags are implicitly boolean and can be turned off via the +\(oq\&!\(cq +operator. +Some integer, string and list parameters may also be +used in a boolean context to disable them. +Values may be enclosed +in double quotes +(\&"") +when they contain multiple words. +Special characters may be escaped with a backslash +(\(oq\e\(cq). +.PP +Lists have two additional assignment operators, +\fR+=\fR +and +\fR-=\fR. +These operators are used to add to and delete from a list respectively. +It is not an error to use the +\fR-=\fR +operator to remove an element +that does not exist in a list. +.PP +Defaults entries are parsed in the following order: generic, host, +user and runas Defaults first, then command defaults. +If there are multiple Defaults settings of the same type, the last +matching setting is used. +The following Defaults settings are parsed before all others since +they may affect subsequent entries: +\fIfqdn\fR, +\fIgroup_plugin\fR, +\fIrunas_default\fR, +\fIsudoers_locale\fR. +.PP +See +\fISUDOERS OPTIONS\fR +for a list of supported Defaults parameters. +.SS "User specification" +.nf +.RS 0n +User_Spec ::= User_List Host_List '=' Cmnd_Spec_List \e + (':' Host_List '=' Cmnd_Spec_List)* + +Cmnd_Spec_List ::= Cmnd_Spec | + Cmnd_Spec ',' Cmnd_Spec_List + +Cmnd_Spec ::= Runas_Spec? Option_Spec* Tag_Spec* Cmnd + +Runas_Spec ::= '(' Runas_List? (':' Runas_List)? ')' + +.ie \n(SL \{\ +.ie \n(PS Option_Spec ::= (SELinux_Spec | Solaris_Priv_Spec | Date_Spec | Timeout_Spec) +.el Option_Spec ::= (SELinux_Spec | Date_Spec | Timeout_Spec) +.\} +.el \{\ +.ie \n(PS Option_Spec ::= (Solaris_Priv_Spec | Date_Spec | Timeout_Spec) +.el Option_Spec ::= (Date_Spec | Timeout_Spec) +.\} + +.if \n(SL \{\ +SELinux_Spec ::= ('ROLE=role' | 'TYPE=type') + +.\} +.if \n(PS \{\ +Solaris_Priv_Spec ::= ('PRIVS=privset' | 'LIMITPRIVS=privset') + +.\} +Date_Spec ::= ('NOTBEFORE=timestamp' | 'NOTAFTER=timestamp') + +Timeout_Spec ::= 'TIMEOUT=timeout' + +Tag_Spec ::= ('EXEC:' | 'NOEXEC:' | 'FOLLOW:' | 'NOFOLLOW' | + 'LOG_INPUT:' | 'NOLOG_INPUT:' | 'LOG_OUTPUT:' | + 'NOLOG_OUTPUT:' | 'MAIL:' | 'NOMAIL:' | 'PASSWD:' | + 'NOPASSWD:' | 'SETENV:' | 'NOSETENV:') +.RE +.fi +.PP +A +\fBuser specification\fR +determines which commands a user may run +(and as what user) on specified hosts. +By default, commands are +run as +\fBroot\fR, +but this can be changed on a per-command basis. +.PP +The basic structure of a user specification is +\(lqwho where = (as_whom) what\(rq. +Let's break that down into its constituent parts: +.SS "Runas_Spec" +A +\fRRunas_Spec\fR +determines the user and/or the group that a command +may be run as. +A fully-specified +\fRRunas_Spec\fR +consists of two +\fRRunas_List\fRs +(as defined above) separated by a colon +(\(oq:\&\(cq) +and enclosed in a set of parentheses. +The first +\fRRunas_List\fR +indicates +which users the command may be run as via +\fBsudo\fR's +\fB\-u\fR +option. +The second defines a list of groups that can be specified via +\fBsudo\fR's +\fB\-g\fR +option in addition to any of the target user's groups. +If both +\fRRunas_List\fRs +are specified, the command may be run with any combination of users +and groups listed in their respective +\fRRunas_List\fRs. +If only the first is specified, the command may be run as any user +in the list but no +\fB\-g\fR +option +may be specified. +If the first +\fRRunas_List\fR +is empty but the +second is specified, the command may be run as the invoking user +with the group set to any listed in the +\fRRunas_List\fR. +If both +\fRRunas_List\fRs +are empty, the command may only be run as the invoking user. +If no +\fRRunas_Spec\fR +is specified the command may be run as +\fBroot\fR +and +no group may be specified. +.PP +A +\fRRunas_Spec\fR +sets the default for the commands that follow it. +What this means is that for the entry: +.nf +.sp +.RS 0n +dgb boulder = (operator) /bin/ls, /bin/kill, /usr/bin/lprm +.RE +.fi +.PP +The user +\fBdgb\fR +may run +\fI/bin/ls\fR, +\fI/bin/kill\fR, +and +\fI/usr/bin/lprm\fR +on the host +boulder\(embut +only as +\fBoperator\fR. +E.g., +.nf +.sp +.RS 0n +$ sudo -u operator /bin/ls +.RE +.fi +.PP +It is also possible to override a +\fRRunas_Spec\fR +later on in an entry. +If we modify the entry like so: +.nf +.sp +.RS 0n +dgb boulder = (operator) /bin/ls, (root) /bin/kill, /usr/bin/lprm +.RE +.fi +.PP +Then user +\fBdgb\fR +is now allowed to run +\fI/bin/ls\fR +as +\fBoperator\fR, +but +\fI/bin/kill\fR +and +\fI/usr/bin/lprm\fR +as +\fBroot\fR. +.PP +We can extend this to allow +\fBdgb\fR +to run +\fR/bin/ls\fR +with either +the user or group set to +\fBoperator\fR: +.nf +.sp +.RS 0n +dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\e + /usr/bin/lprm +.RE +.fi +.PP +Note that while the group portion of the +\fRRunas_Spec\fR +permits the +user to run as command with that group, it does not force the user +to do so. +If no group is specified on the command line, the command +will run with the group listed in the target user's password database +entry. +The following would all be permitted by the sudoers entry above: +.nf +.sp +.RS 0n +$ sudo -u operator /bin/ls +$ sudo -u operator -g operator /bin/ls +$ sudo -g operator /bin/ls +.RE +.fi +.PP +In the following example, user +\fBtcm\fR +may run commands that access +a modem device file with the dialer group. +.nf +.sp +.RS 0n +tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\e + /usr/local/bin/minicom +.RE +.fi +.PP +Note that in this example only the group will be set, the command +still runs as user +\fBtcm\fR. +E.g.\& +.nf +.sp +.RS 0n +$ sudo -g dialer /usr/bin/cu +.RE +.fi +.PP +Multiple users and groups may be present in a +\fRRunas_Spec\fR, +in which case the user may select any combination of users and groups via the +\fB\-u\fR +and +\fB\-g\fR +options. +In this example: +.nf +.sp +.RS 0n +alan ALL = (root, bin : operator, system) ALL +.RE +.fi +.PP +user +\fBalan\fR +may run any command as either user root or bin, +optionally setting the group to operator or system. +.SS "Option_Spec" +A +\fRCmnd\fR +may have zero or more options associated with it. +Options may consist of +.if \n(SL \{\ +SELinux roles and/or types, +.\} +.if \n(PS \{\ +Solaris privileges sets, +.\} +start and/or end dates and command timeouts. +Once an option is set for a +\fRCmnd\fR, +subsequent +\fRCmnd\fRs +in the +\fRCmnd_Spec_List\fR, +inherit that option unless it is overridden by another option. +.if \n(SL \{\ +.SS "SELinux_Spec" +On systems with SELinux support, +\fIsudoers\fR +file entries may optionally have an SELinux role and/or type associated +with a command. +If a role or +type is specified with the command it will override any default values +specified in +\fIsudoers\fR. +A role or type specified on the command line, +however, will supersede the values in +\fIsudoers\fR. +.\} +.if \n(PS \{\ +.SS "Solaris_Priv_Spec" +On Solaris systems, +\fIsudoers\fR +file entries may optionally specify Solaris privilege set and/or limit +privilege set associated with a command. +If privileges or limit privileges are specified with the command +it will override any default values specified in +\fIsudoers\fR. +.PP +A privilege set is a comma-separated list of privilege names. +The +ppriv(1) +command can be used to list all privileges known to the system. +For example: +.nf +.sp +.RS 0n +$ ppriv -l +.RE +.fi +.PP +In addition, there are several +\(lqspecial\(rq +privilege strings: +.TP 10n +none +the empty set +.TP 10n +all +the set of all privileges +.TP 10n +zone +the set of all privileges available in the current zone +.TP 10n +basic +the default set of privileges normal users are granted at login time +.PP +Privileges can be excluded from a set by prefixing the privilege +name with either an +\(oq\&!\(cq +or +\(oq\-\(cq +character. +.\} +.SS "Date_Spec" +\fBsudoers\fR +rules can be specified with a start and end date via the +\fRNOTBEFORE\fR +and +\fRNOTAFTER\fR +settings. +The time stamp must be specified in +\fIGeneralized Time\fR +as defined by RFC 4517. +The format is effectively +\fRyyyymmddHHMMSSZ\fR +where the minutes and seconds are optional. +The +\(oqZ\(cq +suffix indicates that the time stamp is in Coordinated Universal Time (UTC). +It is also possible to specify a timezone offset from UTC in hours +and minutes instead of a +\(oqZ\(cq. +For example, +\(oq-0500\(cq +would correspond to Eastern Standard time in the US. +As an extension, if no +\(oqZ\(cq +or timezone offset is specified, local time will be used. +.PP +The following are all valid time stamps: +.nf +.sp +.RS 4n +20170214083000Z +2017021408Z +20160315220000-0500 +20151201235900 +.RE +.fi +.SS "Timeout_Spec" +A command may have a timeout associated with it. +If the timeout expires before the command has exited, the +command will be terminated. +The timeout may be specified in combinations of days, hours, +minutes and seconds with a single-letter case-insensitive suffix +that indicates the unit of time. +For example, a timeout of 7 days, 8 hours, 30 minutes and +10 seconds would be written as +\fR7d8h30m10s\fR. +If a number is specified without a unit, seconds are assumed. +Any of the days, minutes, hours or seconds may be omitted. +The order must be from largest to smallest unit and a unit +may not be specified more than once. +.PP +The following are all +\fIvalid\fR +timeout values: +\fR7d8h30m10s\fR, +\fR14d\fR, +\fR8h30m\fR, +\fR600s\fR, +\fR3600\fR. +The following are +\fIinvalid\fR +timeout values: +\fR12m2w1d\fR, +\fR30s10m4h\fR, +\fR1d2d3h\fR. +.PP +This option is only supported by version 1.8.20 or higher. +.SS "Tag_Spec" +A command may have zero or more tags associated with it. +The following tag values are supported: +\fREXEC\fR, +\fRNOEXEC\fR, +\fRFOLLOW\fR, +\fRNOFOLLOW\fR, +\fRLOG_INPUT\fR, +\fRNOLOG_INPUT\fR, +\fRLOG_OUTPUT\fR, +\fRNOLOG_OUTPUT\fR, +\fRMAIL\fR, +\fRNOMAIL\fR, +\fRPASSWD\fR, +\fRNOPASSWD\fR, +\fRSETENV\fR, +and +\fRNOSETENV\fR. +Once a tag is set on a +\fRCmnd\fR, +subsequent +\fRCmnd\fRs +in the +\fRCmnd_Spec_List\fR, +inherit the tag unless it is overridden by the opposite tag (in other words, +\fRPASSWD\fR +overrides +\fRNOPASSWD\fR +and +\fRNOEXEC\fR +overrides +\fREXEC\fR). +.TP 2n +\fIEXEC\fR and \fINOEXEC\fR +.sp +If +\fBsudo\fR +has been compiled with +\fInoexec\fR +support and the underlying operating system supports it, the +\fRNOEXEC\fR +tag can be used to prevent a dynamically-linked executable from +running further commands itself. +.sp +In the following example, user +\fBaaron\fR +may run +\fI/usr/bin/more\fR +and +\fI/usr/bin/vi\fR +but shell escapes will be disabled. +.nf +.sp +.RS 2n +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.RE +.fi +.RS 2n +.sp +See the +\fIPreventing shell escapes\fR +section below for more details on how +\fRNOEXEC\fR +works and whether or not it will work on your system. +.RE +.TP 2n +\fIFOLLOW\fR and \fINOFOLLOW\fR +Starting with version 1.8.15, +\fBsudoedit\fR +will not open a file that is a symbolic link unless the +\fIsudoedit_follow\fR +option is enabled. +The +\fIFOLLOW\fR +and +\fINOFOLLOW\fR +tags override the value of +\fIsudoedit_follow\fR +and can be used to permit (or deny) the editing of symbolic links +on a per-command basis. +These tags are only effective for the +\fIsudoedit\fR +command and are ignored for all other commands. +.TP 2n +\fILOG_INPUT\fR and \fINOLOG_INPUT\fR +.sp +These tags override the value of the +\fIlog_input\fR +option on a per-command basis. +For more information, see the description of +\fIlog_input\fR +in the +\fISUDOERS OPTIONS\fR +section below. +.TP 2n +\fILOG_OUTPUT\fR and \fINOLOG_OUTPUT\fR +.sp +These tags override the value of the +\fIlog_output\fR +option on a per-command basis. +For more information, see the description of +\fIlog_output\fR +in the +\fISUDOERS OPTIONS\fR +section below. +.TP 2n +\fIMAIL\fR and \fINOMAIL\fR +.sp +These tags provide fine-grained control over whether +mail will be sent when a user runs a command by +overriding the value of the +\fImail_all_cmnds\fR +option on a per-command basis. +They have no effect when +\fBsudo\fR +is run with the +\fB\-l\fR +or +\fB\-v\fR +options. +A +\fINOMAIL\fR +tag will also override the +\fImail_always\fR +and +\fImail_no_perms\fR +options. +For more information, see the descriptions of +\fImail_all_cmnds\fR, +\fImail_always\fR, +and +\fImail_no_perms\fR +in the +\fISUDOERS OPTIONS\fR +section below. +.TP 2n +\fIPASSWD\fR and \fINOPASSWD\fR +.sp +By default, +\fBsudo\fR +requires that a user authenticate him or herself +before running a command. +This behavior can be modified via the +\fRNOPASSWD\fR +tag. +Like a +\fRRunas_Spec\fR, +the +\fRNOPASSWD\fR +tag sets +a default for the commands that follow it in the +\fRCmnd_Spec_List\fR. +Conversely, the +\fRPASSWD\fR +tag can be used to reverse things. +For example: +.nf +.sp +.RS 2n +ray rushmore = NOPASSWD: /bin/kill, /bin/ls, /usr/bin/lprm +.RE +.fi +.RS 2n +.sp +would allow the user +\fBray\fR +to run +\fI/bin/kill\fR, +\fI/bin/ls\fR, +and +\fI/usr/bin/lprm\fR +as +\fBroot\fR +on the machine rushmore without authenticating himself. +If we only want +\fBray\fR +to be able to +run +\fI/bin/kill\fR +without a password the entry would be: +.nf +.sp +.RS 2n +ray rushmore = NOPASSWD: /bin/kill, PASSWD: /bin/ls, /usr/bin/lprm +.RE +.fi +.sp +Note, however, that the +\fRPASSWD\fR +tag has no effect on users who are in the group specified by the +\fIexempt_group\fR +option. +.sp +By default, if the +\fRNOPASSWD\fR +tag is applied to any of the entries for a user on the current host, +he or she will be able to run +\(lq\fRsudo -l\fR\(rq +without a password. +Additionally, a user may only run +\(lq\fRsudo -v\fR\(rq +without a password if the +\fRNOPASSWD\fR +tag is present for all a user's entries that pertain to the current host. +This behavior may be overridden via the +\fIverifypw\fR +and +\fIlistpw\fR +options. +.RE +.TP 2n +\fISETENV\fR and \fINOSETENV\fR +.sp +These tags override the value of the +\fIsetenv\fR +option on a per-command basis. +Note that if +\fRSETENV\fR +has been set for a command, the user may disable the +\fIenv_reset\fR +option from the command line via the +\fB\-E\fR +option. +Additionally, environment variables set on the command +line are not subject to the restrictions imposed by +\fIenv_check\fR, +\fIenv_delete\fR, +or +\fIenv_keep\fR. +As such, only trusted users should be allowed to set variables in this manner. +If the command matched is +\fBALL\fR, +the +\fRSETENV\fR +tag is implied for that command; this default may be overridden by use of the +\fRNOSETENV\fR +tag. +.SS "Wildcards" +\fBsudo\fR +allows shell-style +\fIwildcards\fR +(aka meta or glob characters) +to be used in host names, path names and command line arguments in the +\fIsudoers\fR +file. +Wildcard matching is done via the +glob(3) +and +fnmatch(3) +functions as specified by +IEEE Std 1003.1 (\(lqPOSIX.1\(rq). +.TP 10n +\fR*\fR +Matches any set of zero or more characters (including white space). +.TP 10n +\fR\&?\fR +Matches any single character (including white space). +.TP 10n +\fR[...]\fR +Matches any character in the specified range. +.TP 10n +\fR[!...]\fR +Matches any character +\fInot\fR +in the specified range. +.TP 10n +\fR\ex\fR +For any character +\(oqx\(cq, +evaluates to +\(oqx\(cq. +This is used to escape special characters such as: +\(oq*\(cq, +\(oq\&?\(cq, +\(oq[\&\(cq, +and +\(oq]\&\(cq. +.PP +\fBNote that these are not regular expressions.\fR +Unlike a regular expression there is no way to match one or more +characters within a range. +.PP +Character classes may be used if your system's +glob(3) +and +fnmatch(3) +functions support them. +However, because the +\(oq:\&\(cq +character has special meaning in +\fIsudoers\fR, +it must be +escaped. +For example: +.nf +.sp +.RS 4n +/bin/ls [[\e:\&alpha\e:\&]]* +.RE +.fi +.PP +Would match any file name beginning with a letter. +.PP +Note that a forward slash +(\(oq/\(cq) +will +\fInot\fR +be matched by +wildcards used in the file name portion of the command. +This is to make a path like: +.nf +.sp +.RS 4n +/usr/bin/* +.RE +.fi +.PP +match +\fI/usr/bin/who\fR +but not +\fI/usr/bin/X11/xterm\fR. +.PP +When matching the command line arguments, however, a slash +\fIdoes\fR +get matched by wildcards since command line arguments may contain +arbitrary strings and not just path names. +.PP +\fBWildcards in command line arguments should be used with care.\fR +.br +Command line arguments are matched as a single, concatenated string. +This mean a wildcard character such as +\(oq\&?\(cq +or +\(oq*\(cq +will match across word boundaries, which may be unexpected. +For example, while a sudoers entry like: +.nf +.sp +.RS 4n +%operator ALL = /bin/cat /var/log/messages* +.RE +.fi +.PP +will allow command like: +.nf +.sp +.RS 4n +$ sudo cat /var/log/messages.1 +.RE +.fi +.PP +It will also allow: +.nf +.sp +.RS 4n +$ sudo cat /var/log/messages /etc/shadow +.RE +.fi +.PP +which is probably not what was intended. +In most cases it is better to do command line processing +outside of the +\fIsudoers\fR +file in a scripting language. +.SS "Exceptions to wildcard rules" +The following exceptions apply to the above rules: +.TP 10n +\fR\&""\fR +If the empty string +\fR\&""\fR +is the only command line argument in the +\fIsudoers\fR +file entry it means that command is not allowed to be run with +\fIany\fR +arguments. +.TP 10n +sudoedit +Command line arguments to the +\fIsudoedit\fR +built-in command should always be path names, so a forward slash +(\(oq/\(cq) +will not be matched by a wildcard. +.SS "Including other files from within sudoers" +It is possible to include other +\fIsudoers\fR +files from within the +\fIsudoers\fR +file currently being parsed using the +\fR#include\fR +and +\fR#includedir\fR +directives. +.PP +This can be used, for example, to keep a site-wide +\fIsudoers\fR +file in addition to a local, per-machine file. +For the sake of this example the site-wide +\fIsudoers\fR +file will be +\fI/etc/sudoers\fR +and the per-machine one will be +\fI/etc/sudoers.local\fR. +To include +\fI/etc/sudoers.local\fR +from within +\fI/etc/sudoers\fR +we would use the +following line in +\fI/etc/sudoers\fR: +.nf +.sp +.RS 4n +#include /etc/sudoers.local +.RE +.fi +.PP +When +\fBsudo\fR +reaches this line it will suspend processing of the current file +(\fI/etc/sudoers\fR) +and switch to +\fI/etc/sudoers.local\fR. +Upon reaching the end of +\fI/etc/sudoers.local\fR, +the rest of +\fI/etc/sudoers\fR +will be processed. +Files that are included may themselves include other files. +A hard limit of 128 nested include files is enforced to prevent include +file loops. +.PP +If the path to the include file is not fully-qualified (does not +begin with a +\(oq/\(cq), +it must be located in the same directory as the sudoers file it was +included from. +For example, if +\fI/etc/sudoers\fR +contains the line: +.nf +.sp +.RS 4n +\fR#include sudoers.local\fR +.RE +.fi +.PP +the file that will be included is +\fI/etc/sudoers.local\fR. +.PP +The file name may also include the +\fR%h\fR +escape, signifying the short form of the host name. +In other words, if the machine's host name is +\(lqxerxes\(rq, +then +.nf +.sp +.RS 4n +#include /etc/sudoers.%h +.RE +.fi +.PP +will cause +\fBsudo\fR +to include the file +\fI/etc/sudoers.xerxes\fR. +.PP +The +\fR#includedir\fR +directive can be used to create a +\fIsudoers.d\fR +directory that the system package manager can drop +\fIsudoers\fR +file rules into as part of package installation. +For example, given: +.nf +.sp +.RS 4n +#includedir /etc/sudoers.d +.RE +.fi +.PP +\fBsudo\fR +will suspend processing of the current file and read each file in +\fI/etc/sudoers.d\fR, +skipping file names that end in +\(oq~\(cq +or contain a +\(oq.\&\(cq +character to avoid causing problems with package manager or editor +temporary/backup files. +Files are parsed in sorted lexical order. +That is, +\fI/etc/sudoers.d/01_first\fR +will be parsed before +\fI/etc/sudoers.d/10_second\fR. +Be aware that because the sorting is lexical, not numeric, +\fI/etc/sudoers.d/1_whoops\fR +would be loaded +\fIafter\fR +\fI/etc/sudoers.d/10_second\fR. +Using a consistent number of leading zeroes in the file names can be used +to avoid such problems. +After parsing the files in the directory, control returns to the +file that contained the +\fR#includedir\fR +directive. +.PP +Note that unlike files included via +\fR#include\fR, +\fBvisudo\fR +will not edit the files in a +\fR#includedir\fR +directory unless one of them contains a syntax error. +It is still possible to run +\fBvisudo\fR +with the +\fB\-f\fR +flag to edit the files directly, but this will not catch the +redefinition of an +\fIalias\fR +that is also present in a different file. +.SS "Other special characters and reserved words" +The pound sign +(\(oq#\(cq) +is used to indicate a comment (unless it is part of a #include +directive or unless it occurs in the context of a user name and is +followed by one or more digits, in which case it is treated as a +uid). +Both the comment character and any text after it, up to the end of +the line, are ignored. +.PP +The reserved word +\fBALL\fR +is a built-in +\fIalias\fR +that always causes a match to succeed. +It can be used wherever one might otherwise use a +\fRCmnd_Alias\fR, +\fRUser_Alias\fR, +\fRRunas_Alias\fR, +or +\fRHost_Alias\fR. +You should not try to define your own +\fIalias\fR +called +\fBALL\fR +as the built-in alias will be used in preference to your own. +Please note that using +\fBALL\fR +can be dangerous since in a command context, it allows the user to run +\fIany\fR +command on the system. +.PP +An exclamation point +(\(oq\&!\(cq) +can be used as a logical +\fInot\fR +operator in a list or +\fIalias\fR +as well as in front of a +\fRCmnd\fR. +This allows one to exclude certain values. +For the +\(oq\&!\(cq +operator to be effective, there must be something for it to exclude. +For example, to match all users except for root one would use: +.nf +.sp +.RS 4n +ALL,!root +.RE +.fi +.PP +If the +\fBALL\fR, +is omitted, as in: +.nf +.sp +.RS 4n +!root +.RE +.fi +.PP +it would explicitly deny root but not match any other users. +This is different from a true +\(lqnegation\(rq +operator. +.PP +Note, however, that using a +\(oq\&!\(cq +in conjunction with the built-in +\fBALL\fR +alias to allow a user to run +\(lqall but a few\(rq +commands rarely works as intended (see +\fISECURITY NOTES\fR +below). +.PP +Long lines can be continued with a backslash +(\(oq\e\(cq) +as the last character on the line. +.PP +White space between elements in a list as well as special syntactic +characters in a +\fIUser Specification\fR +(\(oq=\&\(cq, +\(oq:\&\(cq, +\(oq(\&\(cq, +\(oq)\&\(cq) +is optional. +.PP +The following characters must be escaped with a backslash +(\(oq\e\(cq) +when used as part of a word (e.g., a user name or host name): +\(oq\&!\(cq, +\(oq=\&\(cq, +\(oq:\&\(cq, +\(oq,\&\(cq, +\(oq(\&\(cq, +\(oq)\&\(cq, +\(oq\e\(cq. +.SH "SUDOERS OPTIONS" +\fBsudo\fR's +behavior can be modified by +\fRDefault_Entry\fR +lines, as explained earlier. +A list of all supported Defaults parameters, grouped by type, are listed below. +.PP +\fBBoolean Flags\fR: +.TP 18n +always_query_group_plugin +If a +\fIgroup_plugin\fR +is configured, use it to resolve groups of the form %group as long +as there is not also a system group of the same name. +Normally, only groups of the form %:group are passed to the +\fIgroup_plugin\fR. +This flag is +\fIoff\fR +by default. +.TP 18n +always_set_home +If enabled, +\fBsudo\fR +will set the +\fRHOME\fR +environment variable to the home directory of the target user +(which is root unless the +\fB\-u\fR +option is used). +This effectively means that the +\fB\-H\fR +option is always implied. +Note that by default, +\fRHOME\fR +will be set to the home directory of the target user when the +\fIenv_reset\fR +option is enabled, so +\fIalways_set_home\fR +only has an effect for configurations where either +\fIenv_reset\fR +is disabled or +\fRHOME\fR +is present in the +\fIenv_keep\fR +list. +This flag is +\fIoff\fR +by default. +.TP 18n +authenticate +If set, users must authenticate themselves via a password (or other +means of authentication) before they may run commands. +This default may be overridden via the +\fRPASSWD\fR +and +\fRNOPASSWD\fR +tags. +This flag is +\fIon\fR +by default. +.TP 18n +case_insensitive_group +If enabled, group names in +\fIsudoers\fR +will be matched in a case insensitive manner. +This may be necessary when users are stored in LDAP or AD. +This flag is +\fIon\fR +by default. +.TP 18n +case_insensitive_user +If enabled, user names in +\fIsudoers\fR +will be matched in a case insensitive manner. +This may be necessary when groups are stored in LDAP or AD. +This flag is +\fIon\fR +by default. +.TP 18n +closefrom_override +If set, the user may use +\fBsudo\fR's +\fB\-C\fR +option which overrides the default starting point at which +\fBsudo\fR +begins closing open file descriptors. +This flag is +\fIoff\fR +by default. +.TP 18n +compress_io +If set, and +\fBsudo\fR +is configured to log a command's input or output, +the I/O logs will be compressed using +\fBzlib\fR. +This flag is +\fIon\fR +by default when +\fBsudo\fR +is compiled with +\fBzlib\fR +support. +.TP 18n +exec_background +By default, +\fBsudo\fR +runs a command as the foreground process as long as +\fBsudo\fR +itself is running in the foreground. +When the +\fIexec_background\fR +flag is enabled and the command is being run in a pty (due to I/O logging +or the +\fIuse_pty\fR +flag), the command will be run as a background process. +Attempts to read from the controlling terminal (or to change terminal +settings) will result in the command being suspended with the +\fRSIGTTIN\fR +signal (or +\fRSIGTTOU\fR +in the case of terminal settings). +If this happens when +\fBsudo\fR +is a foreground process, the command will be granted the controlling terminal +and resumed in the foreground with no user intervention required. +The advantage of initially running the command in the background is that +\fBsudo\fR +need not read from the terminal unless the command explicitly requests it. +Otherwise, any terminal input must be passed to the command, whether it +has required it or not (the kernel buffers terminals so it is not possible +to tell whether the command really wants the input). +This is different from historic +\fIsudo\fR +behavior or when the command is not being run in a pty. +.sp +For this to work seamlessly, the operating system must support the +automatic restarting of system calls. +Unfortunately, not all operating systems do this by default, +and even those that do may have bugs. +For example, macOS fails to restart the +\fBtcgetattr\fR() +and +\fBtcsetattr\fR() +system calls (this is a bug in macOS). +Furthermore, because this behavior depends on the command stopping with the +\fRSIGTTIN\fR +or +\fRSIGTTOU\fR +signals, programs that catch these signals and suspend themselves +with a different signal (usually +\fRSIGTOP\fR) +will not be automatically foregrounded. +Some versions of the linux +su(1) +command behave this way. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.7 or higher. +It has no effect unless I/O logging is enabled or the +\fIuse_pty\fR +flag is enabled. +.TP 18n +env_editor +If set, +\fBvisudo\fR +will use the value of the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +environment variables before falling back on the default editor list. +Note that this may create a security hole as it allows the user to +run any arbitrary command as root without logging. +A safer alternative is to place a colon-separated list of editors +in the +\fIeditor\fR +variable. +\fBvisudo\fR +will then only use +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +if they match a value specified in +\fIeditor\fR. +If the +\fIenv_reset\fR +flag is enabled, the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +and/or +\fREDITOR\fR +environment variables must be present in the +\fIenv_keep\fR +list for the +\fIenv_editor\fR +flag to function when +\fBvisudo\fR +is invoked via +\fBsudo\fR. +This flag is +\fI@env_editor@\fR +by default. +.TP 18n +env_reset +If set, +\fBsudo\fR +will run the command in a minimal environment containing the +\fRTERM\fR, +\fRPATH\fR, +\fRHOME\fR, +\fRMAIL\fR, +\fRSHELL\fR, +\fRLOGNAME\fR, +\fRUSER\fR +and +\fRSUDO_*\fR +variables. +Any variables in the caller's environment or in the file specified +by the +\fIrestricted_env_file\fR +option that match the +\fRenv_keep\fR +and +\fRenv_check\fR +lists are then added, followed by any variables present in the file +specified by the +\fIenv_file\fR +option (if any). +The contents of the +\fRenv_keep\fR +and +\fRenv_check\fR +lists, as modified by global Defaults parameters in +\fIsudoers\fR, +are displayed when +\fBsudo\fR +is run by root with the +\fB\-V\fR +option. +If the +\fIsecure_path\fR +option is set, its value will be used for the +\fRPATH\fR +environment variable. +This flag is +\fI@env_reset@\fR +by default. +.TP 18n +fast_glob +Normally, +\fBsudo\fR +uses the +glob(3) +function to do shell-style globbing when matching path names. +However, since it accesses the file system, +glob(3) +can take a long time to complete for some patterns, especially +when the pattern references a network file system that is mounted +on demand (auto mounted). +The +\fIfast_glob\fR +option causes +\fBsudo\fR +to use the +fnmatch(3) +function, which does not access the file system to do its matching. +The disadvantage of +\fIfast_glob\fR +is that it is unable to match relative path names such as +\fI./ls\fR +or +\fI../bin/ls\fR. +This has security implications when path names that include globbing +characters are used with the negation operator, +\(oq!\&\(cq, +as such rules can be trivially bypassed. +As such, this option should not be used when the +\fIsudoers\fR +file contains rules that contain negated path names which include globbing +characters. +This flag is +\fIoff\fR +by default. +.TP 18n +fqdn +Set this flag if you want to put fully qualified host names in the +\fIsudoers\fR +file when the local host name (as returned by the +\fRhostname\fR +command) does not contain the domain name. +In other words, instead of myhost you would use myhost.mydomain.edu. +You may still use the short form if you wish (and even mix the two). +This option is only effective when the +\(lqcanonical\(rq +host name, as returned by the +\fBgetaddrinfo\fR() +or +\fBgethostbyname\fR() +function, is a fully-qualified domain name. +This is usually the case when the system is configured to use DNS +for host name resolution. +.sp +If the system is configured to use the +\fI/etc/hosts\fR +file in preference to DNS, the +\(lqcanonical\(rq +host name may not be fully-qualified. +The order that sources are queried for host name resolution +is usually specified in the +\fI@nsswitch_conf@\fR, +\fI@netsvc_conf@\fR, +\fI/etc/host.conf\fR, +or, in some cases, +\fI/etc/resolv.conf\fR +file. +In the +\fI/etc/hosts\fR +file, the first host name of the entry is considered to be the +\(lqcanonical\(rq +name; subsequent names are aliases that are not used by +\fBsudoers\fR. +For example, the following hosts file line for the machine +\(lqxyzzy\(rq +has the fully-qualified domain name as the +\(lqcanonical\(rq +host name, and the short version as an alias. +.sp +.RS 24n +192.168.1.1 xyzzy.sudo.ws xyzzy +.RE +.RS 18n +.sp +If the machine's hosts file entry is not formatted properly, the +\fIfqdn\fR +option will not be effective if it is queried before DNS. +.sp +Beware that when using DNS for host name resolution, turning on +\fIfqdn\fR +requires +\fBsudoers\fR +to make DNS lookups which renders +\fBsudo\fR +unusable if DNS stops working (for example if the machine is disconnected +from the network). +Also note that just like with the hosts file, you must use the +\(lqcanonical\(rq +name as DNS knows it. +That is, you may not use a host alias +(\fRCNAME\fR +entry) +due to performance issues and the fact that there is no way to get all +aliases from DNS. +.sp +This flag is +\fI@fqdn@\fR +by default. +.RE +.TP 18n +ignore_audit_errors +Allow commands to be run even if +\fBsudoers\fR +cannot write to the audit log. +If enabled, an audit log write failure is not treated as a fatal error. +If disabled, a command may only be run after the audit event is successfully +written. +This flag is only effective on systems for which +\fBsudoers\fR +supports audit logging, including +FreeBSD, +Linux, macOS and Solaris. +This flag is +\fIon\fR +by default. +.TP 18n +ignore_dot +If set, +\fBsudo\fR +will ignore "." or "" (both denoting current directory) in the +\fRPATH\fR +environment variable; the +\fRPATH\fR +itself is not modified. +This flag is +\fI@ignore_dot@\fR +by default. +.TP 18n +ignore_iolog_errors +Allow commands to be run even if +\fBsudoers\fR +cannot write to the I/O log. +If enabled, an I/O log write failure is not treated as a fatal error. +If disabled, the command will be terminated if the I/O log cannot be written to. +This flag is +\fIoff\fR +by default. +.TP 18n +ignore_logfile_errors +Allow commands to be run even if +\fBsudoers\fR +cannot write to the log file. +If enabled, a log file write failure is not treated as a fatal error. +If disabled, a command may only be run after the log file entry is successfully +written. +This flag only has an effect when +\fBsudoers\fR +is configured to use file-based logging via the +\fIlogfile\fR +option. +This flag is +\fIon\fR +by default. +.TP 18n +ignore_local_sudoers +If set via LDAP, parsing of +\fI@sysconfdir@/sudoers\fR +will be skipped. +This is intended for Enterprises that wish to prevent the usage of local +sudoers files so that only LDAP is used. +This thwarts the efforts of rogue operators who would attempt to add roles to +\fI@sysconfdir@/sudoers\fR. +When this option is present, +\fI@sysconfdir@/sudoers\fR +does not even need to exist. +Since this option tells +\fBsudo\fR +how to behave when no specific LDAP entries have been matched, this +sudoOption is only meaningful for the +\fRcn=defaults\fR +section. +This flag is +\fIoff\fR +by default. +.TP 18n +ignore_unknown_defaults +If set, +\fBsudo\fR +will not produce a warning if it encounters an unknown Defaults entry +in the +\fIsudoers\fR +file or an unknown sudoOption in LDAP. +This flag is +\fIoff\fR +by default. +.TP 18n +insults +If set, +\fBsudo\fR +will insult users when they enter an incorrect password. +This flag is +\fI@insults@\fR +by default. +.TP 18n +log_host +If set, the host name will be logged in the (non-syslog) +\fBsudo\fR +log file. +This flag is +\fIoff\fR +by default. +.TP 18n +log_input +If set, +\fBsudo\fR +will run the command in a pseudo-tty and log all user input. +If the standard input is not connected to the user's tty, due to +I/O redirection or because the command is part of a pipeline, that +input is also captured and stored in a separate log file. +Anything sent to the standard input will be consumed, regardless of +whether or not the command run via +\fBsudo\fR +is actually reading the standard input. +This may have unexpected results when using +\fBsudo\fR +in a shell script that expects to process the standard input. +For more information about I/O logging, see the +\fII/O LOG FILES\fR +section. +This flag is +\fIoff\fR +by default. +.TP 18n +log_output +If set, +\fBsudo\fR +will run the command in a pseudo-tty and log all output that is sent +to the screen, similar to the +script(1) +command. +For more information about I/O logging, see the +\fII/O LOG FILES\fR +section. +This flag is +\fIoff\fR +by default. +.TP 18n +log_year +If set, the four-digit year will be logged in the (non-syslog) +\fBsudo\fR +log file. +This flag is +\fIoff\fR +by default. +.TP 18n +long_otp_prompt +When validating with a One Time Password (OTP) scheme such as +\fBS/Key\fR +or +\fBOPIE\fR, +a two-line prompt is used to make it easier +to cut and paste the challenge to a local window. +It's not as pretty as the default but some people find it more convenient. +This flag is +\fI@long_otp_prompt@\fR +by default. +.TP 18n +mail_all_cmnds +Send mail to the +\fImailto\fR +user every time a user attempts to run a command via +\fBsudo\fR +(this includes +\fBsudoedit\fR). +No mail will be sent if the user runs +\fBsudo\fR +with the +\fB\-l\fR +or +\fB\-v\fR +option unless there is an authentication error and the +\fImail_badpass\fR +flag is also set. +This flag is +\fIoff\fR +by default. +.TP 18n +mail_always +Send mail to the +\fImailto\fR +user every time a user runs +\fBsudo\fR. +This flag is +\fIoff\fR +by default. +.TP 18n +mail_badpass +Send mail to the +\fImailto\fR +user if the user running +\fBsudo\fR +does not enter the correct password. +If the command the user is attempting to run is not permitted by +\fBsudoers\fR +and one of the +\fImail_all_cmnds\fR, +\fImail_always\fR, +\fImail_no_host\fR, +\fImail_no_perms\fR +or +\fImail_no_user\fR +flags are set, this flag will have no effect. +This flag is +\fIoff\fR +by default. +.TP 18n +mail_no_host +If set, mail will be sent to the +\fImailto\fR +user if the invoking user exists in the +\fIsudoers\fR +file, but is not allowed to run commands on the current host. +This flag is +\fI@mail_no_host@\fR +by default. +.TP 18n +mail_no_perms +If set, mail will be sent to the +\fImailto\fR +user if the invoking user is allowed to use +\fBsudo\fR +but the command they are trying is not listed in their +\fIsudoers\fR +file entry or is explicitly denied. +This flag is +\fI@mail_no_perms@\fR +by default. +.TP 18n +mail_no_user +If set, mail will be sent to the +\fImailto\fR +user if the invoking user is not in the +\fIsudoers\fR +file. +This flag is +\fI@mail_no_user@\fR +by default. +.TP 18n +match_group_by_gid +By default, +\fBsudoers\fR +will look up each group the user is a member of by group ID to +determine the group name (this is only done once). +The resulting list of the user's group names is used when matching +groups listed in the +\fIsudoers\fR +file. +This works well on systems where the number of groups listed in the +\fIsudoers\fR +file is larger than the number of groups a typical user belongs to. +On systems where group lookups are slow, where users may belong +to a large number of groups, and where the number of groups listed +in the +\fIsudoers\fR +file is relatively small, it may be prohibitively expensive and +running commands via +\fBsudo\fR +may take longer than normal. +On such systems it may be faster to use the +\fImatch_group_by_gid\fR +flag to avoid resolving the user's group IDs to group names. +In this case, +\fBsudoers\fR +must look up any group name listed in the +\fIsudoers\fR +file and use the group ID instead of the group name when determining +whether the user is a member of the group. +.sp +Note that if +\fImatch_group_by_gid\fR +is enabled, group database lookups performed by +\fBsudoers\fR +will be keyed by group name as opposed to group ID. +On systems where there are multiple sources for the group database, +it is possible to have conflicting group names or group IDs in the local +\fI/etc/group\fR +file and the remote group database. +On such systems, enabling or disabling +\fImatch_group_by_gid\fR +can be used to choose whether group database queries are performed +by name (enabled) or ID (disabled), which may aid in working around +group entry conflicts. +.sp +The +\fImatch_group_by_gid\fR +flag has no effect when +\fIsudoers\fR +data is stored in LDAP. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.18 or higher. +.TP 18n +netgroup_tuple +If set, netgroup lookups will be performed using the full netgroup +tuple: host name, user name and domain (if one is set). +Historically, +\fBsudo\fR +only matched the user name and domain for netgroups used in a +\fRUser_List\fR +and only matched the host name and domain for netgroups used in a +\fRHost_List\fR. +This flag is +\fIoff\fR +by default. +.TP 18n +noexec +If set, all commands run via +\fBsudo\fR +will behave as if the +\fRNOEXEC\fR +tag has been set, unless overridden by an +\fREXEC\fR +tag. +See the description of +\fIEXEC and NOEXEC\fR +above as well as the +\fIPreventing shell escapes\fR +section at the end of this manual. +This flag is +\fIoff\fR +by default. +.TP 18n +pam_session +On systems that use PAM for authentication, +\fBsudo\fR +will create a new PAM session for the command to be run in. +Disabling +\fIpam_session\fR +may be needed on older PAM implementations or on operating systems where +opening a PAM session changes the utmp or wtmp files. +If PAM session support is disabled, resource limits may not be updated +for the command being run. +If +\fIpam_session\fR, +\fIpam_setcred\fR, +and +\fIuse_pty\fR +are disabled and I/O logging has not been configured, +\fBsudo\fR +will execute the command directly instead of running it as a child +process. +This flag is +\fI@pam_session@\fR +by default. +.sp +This setting is only supported by version 1.8.7 or higher. +.TP 18n +pam_setcred +On systems that use PAM for authentication, +\fBsudo\fR +will attempt to establish credentials for the target user by default, +if supported by the underlying authentication system. +One example of a credential is a Kerberos ticket. +If +\fIpam_session\fR, +\fIpam_setcred\fR, +and +\fIuse_pty\fR +are disabled and I/O logging has not been configured, +\fBsudo\fR +will execute the command directly instead of running it as a child +process. +This flag is +\fIon\fR +by default. +.sp +This setting is only supported by version 1.8.8 or higher. +.TP 18n +passprompt_override +If set, the prompt specified by +\fIpassprompt\fR +or the +\fRSUDO_PROMPT\fR +environment variable will always be used and will replace the +prompt provided by a PAM module or other authentication method. +This flag is +\fIoff\fR +by default. +.TP 18n +path_info +Normally, +\fBsudo\fR +will tell the user when a command could not be +found in their +\fRPATH\fR +environment variable. +Some sites may wish to disable this as it could be used to gather +information on the location of executables that the normal user does +not have access to. +The disadvantage is that if the executable is simply not in the user's +\fRPATH\fR, +\fBsudo\fR +will tell the user that they are not allowed to run it, which can be confusing. +This flag is +\fI@path_info@\fR +by default. +.TP 18n +preserve_groups +By default, +\fBsudo\fR +will initialize the group vector to the list of groups the target user is in. +When +\fIpreserve_groups\fR +is set, the user's existing group vector is left unaltered. +The real and effective group IDs, however, are still set to match the +target user. +This flag is +\fIoff\fR +by default. +.TP 18n +pwfeedback +By default, +\fBsudo\fR +reads the password like most other Unix programs, +by turning off echo until the user hits the return (or enter) key. +Some users become confused by this as it appears to them that +\fBsudo\fR +has hung at this point. +When +\fIpwfeedback\fR +is set, +\fBsudo\fR +will provide visual feedback when the user presses a key. +Note that this does have a security impact as an onlooker may be able to +determine the length of the password being entered. +This flag is +\fIoff\fR +by default. +.TP 18n +requiretty +If set, +\fBsudo\fR +will only run when the user is logged in to a real tty. +When this flag is set, +\fBsudo\fR +can only be run from a login session and not via other means such as +cron(@mansectsu@) +or cgi-bin scripts. +This flag is +\fIoff\fR +by default. +.TP 18n +root_sudo +If set, root is allowed to run +\fBsudo\fR +too. +Disabling this prevents users from +\(lqchaining\(rq +\fBsudo\fR +commands to get a root shell by doing something like +\(lq\fRsudo sudo /bin/sh\fR\(rq. +Note, however, that turning off +\fIroot_sudo\fR +will also prevent root from running +\fBsudoedit\fR. +Disabling +\fIroot_sudo\fR +provides no real additional security; it exists purely for historical reasons. +This flag is +\fI@root_sudo@\fR +by default. +.TP 18n +rootpw +If set, +\fBsudo\fR +will prompt for the root password instead of the password of the invoking user +when running a command or editing a file. +This flag is +\fIoff\fR +by default. +.TP 18n +runaspw +If set, +\fBsudo\fR +will prompt for the password of the user defined by the +\fIrunas_default\fR +option (defaults to +\fR@runas_default@\fR) +instead of the password of the invoking user +when running a command or editing a file. +This flag is +\fIoff\fR +by default. +.TP 18n +set_home +If enabled and +\fBsudo\fR +is invoked with the +\fB\-s\fR +option the +\fRHOME\fR +environment variable will be set to the home directory of the target +user (which is root unless the +\fB\-u\fR +option is used). +This effectively makes the +\fB\-s\fR +option imply +\fB\-H\fR. +Note that +\fRHOME\fR +is already set when the +\fIenv_reset\fR +option is enabled, so +\fIset_home\fR +is only effective for configurations where either +\fIenv_reset\fR +is disabled +or +\fRHOME\fR +is present in the +\fIenv_keep\fR +list. +This flag is +\fIoff\fR +by default. +.TP 18n +set_logname +Normally, +\fBsudo\fR +will set the +\fRLOGNAME\fR +and +\fRUSER\fR +environment variables to the name of the target user (usually root unless the +\fB\-u\fR +option is given). +However, since some programs (including the RCS revision control system) use +\fRLOGNAME\fR +to determine the real identity of the user, it may be desirable to +change this behavior. +This can be done by negating the set_logname option. +Note that +\fIset_logname\fR +will have no effect +if the +\fIenv_reset\fR +option has not been disabled and the +\fIenv_keep\fR +list contains +\fRLOGNAME\fR +or +\fRUSER\fR. +This flag is +\fIon\fR +by default. +.TP 18n +set_utmp +When enabled, +\fBsudo\fR +will create an entry in the utmp (or utmpx) file when a pseudo-tty +is allocated. +A pseudo-tty is allocated by +\fBsudo\fR +when the +\fIlog_input\fR, +\fIlog_output\fR +or +\fIuse_pty\fR +flags are enabled. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +This flag is +\fIon\fR +by default. +.TP 18n +setenv +Allow the user to disable the +\fIenv_reset\fR +option from the command line via the +\fB\-E\fR +option. +Additionally, environment variables set via the command line are +not subject to the restrictions imposed by +\fIenv_check\fR, +\fIenv_delete\fR, +or +\fIenv_keep\fR. +As such, only trusted users should be allowed to set variables in this manner. +This flag is +\fIoff\fR +by default. +.TP 18n +shell_noargs +If set and +\fBsudo\fR +is invoked with no arguments it acts as if the +\fB\-s\fR +option had been given. +That is, it runs a shell as root (the shell is determined by the +\fRSHELL\fR +environment variable if it is set, falling back on the shell listed +in the invoking user's /etc/passwd entry if not). +This flag is +\fIoff\fR +by default. +.TP 18n +stay_setuid +Normally, when +\fBsudo\fR +executes a command the real and effective UIDs are set to the target +user (root by default). +This option changes that behavior such that the real UID is left +as the invoking user's UID. +In other words, this makes +\fBsudo\fR +act as a setuid wrapper. +This can be useful on systems that disable some potentially +dangerous functionality when a program is run setuid. +This option is only effective on systems that support either the +setreuid(2) +or +setresuid(2) +system call. +This flag is +\fIoff\fR +by default. +.TP 18n +sudoedit_checkdir +.br +If set, +\fBsudoedit\fR +will check all directory components of the path to be edited for writability +by the invoking user. +Symbolic links will not be followed in writable directories and +\fBsudoedit\fR +will refuse to edit a file located in a writable directory. +These restrictions are not enforced when +\fBsudoedit\fR +is run by root. +On some systems, if all directory components of the path to be edited +are not readable by the target user, +\fBsudoedit\fR +will be unable to edit the file. +This flag is +\fIon\fR +by default. +.sp +This setting was first introduced in version 1.8.15 but initially +suffered from a race condition. +The check for symbolic links in writable intermediate directories +was added in version 1.8.16. +.TP 18n +sudoedit_follow +By default, +\fBsudoedit\fR +will not follow symbolic links when opening files. +The +\fIsudoedit_follow\fR +option can be enabled to allow +\fBsudoedit\fR +to open symbolic links. +It may be overridden on a per-command basis by the +\fIFOLLOW\fR +and +\fINOFOLLOW\fR +tags. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.15 or higher. +.TP 18n +syslog_pid +When logging via +syslog(3), +include the process ID in the log entry. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.21 or higher. +.TP 18n +targetpw +If set, +\fBsudo\fR +will prompt for the password of the user specified +by the +\fB\-u\fR +option (defaults to +\fRroot\fR) +instead of the password of the invoking user +when running a command or editing a file. +Note that this flag precludes the use of a uid not listed in the passwd +database as an argument to the +\fB\-u\fR +option. +This flag is +\fIoff\fR +by default. +.TP 18n +tty_tickets +If set, users must authenticate on a per-tty basis. +With this flag enabled, +\fBsudo\fR +will use a separate record in the time stamp file for each terminal. +If disabled, a single record is used for all login sessions. +.sp +This option has been superseded by the +\fItimestamp_type\fR +option. +.TP 18n +umask_override +If set, +\fBsudo\fR +will set the umask as specified in the +\fIsudoers\fR +file without modification. +This makes it possible to specify a umask in the +\fIsudoers\fR +file that is more permissive than the user's own umask and matches +historical behavior. +If +\fIumask_override\fR +is not set, +\fBsudo\fR +will set the umask to be the union of the user's umask and what is specified in +\fIsudoers\fR. +This flag is +\fI@umask_override@\fR +by default. +.if \n(BA \{\ +.TP 18n +use_loginclass +If set, +\fBsudo\fR +will apply the defaults specified for the target user's login class +if one exists. +Only available if +\fBsudo\fR +is configured with the +\fR--with-logincap\fR +option. +This flag is +\fIoff\fR +by default. +.\} +.TP 18n +use_netgroups +If set, netgroups (prefixed with +\(oq+\(cq), +may be used in place of a user or host. +For LDAP-based sudoers, netgroup support requires an expensive +sub-string match on the server unless the +\fBNETGROUP_BASE\fR +directive is present in the +\fI@ldap_conf@\fR +file. +If netgroups are not needed, this option can be disabled to reduce the +load on the LDAP server. +This flag is +\fIon\fR +by default. +.TP 18n +use_pty +If set, and +\fBsudo\fR +is running in a terminal, the command will be run in a pseudo-pty +(even if no I/O logging is being done). +If the +\fBsudo\fR +process is not attached to a terminal, +\fIuse_pty\fR +has no effect. +.sp +A malicious program run under +\fBsudo\fR +may be capable of injecting commands into the user's +terminal or running a background process that retains access to the +user's terminal device even after the main program has finished +executing. +By running the command in a separate pseudo-pty, this attack is +no longer possible. +This flag is +\fIoff\fR +by default. +.TP 18n +user_command_timeouts +If set, the user may specify a timeout on the command line. +If the timeout expires before the command has exited, the +command will be terminated. +If a timeout is specified both in the +\fIsudoers\fR +file and on the command line, the smaller of the two timeouts will be used. +See the +\fRTimeout_Spec\fR +section for a description of the timeout syntax. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.20 or higher. +.TP 18n +utmp_runas +If set, +\fBsudo\fR +will store the name of the runas user when updating the utmp (or utmpx) file. +By default, +\fBsudo\fR +stores the name of the invoking user. +This flag is +\fIoff\fR +by default. +.TP 18n +visiblepw +By default, +\fBsudo\fR +will refuse to run if the user must enter a password but it is not +possible to disable echo on the terminal. +If the +\fIvisiblepw\fR +flag is set, +\fBsudo\fR +will prompt for a password even when it would be visible on the screen. +This makes it possible to run things like +\(lq\fRssh somehost sudo ls\fR\(rq +since by default, +ssh(1) +does +not allocate a tty when running a command. +This flag is +\fIoff\fR +by default. +.PP +\fBIntegers\fR: +.TP 18n +closefrom +Before it executes a command, +\fBsudo\fR +will close all open file descriptors other than standard input, +standard output and standard error (ie: file descriptors 0-2). +The +\fIclosefrom\fR +option can be used to specify a different file descriptor at which +to start closing. +The default is +\fR3\fR. +.TP 18n +command_timeout +The maximum amount of time a command is allowed to run before +it is terminated. +See the +\fRTimeout_Spec\fR +section for a description of the timeout syntax. +.sp +This setting is only supported by version 1.8.20 or higher. +.TP 18n +maxseq +The maximum sequence number that will be substituted for the +\(lq\fR%{seq}\fR\(rq +escape in the I/O log file (see the +\fIiolog_dir\fR +description below for more information). +While the value substituted for +\(lq\fR%{seq}\fR\(rq +is in base 36, +\fImaxseq\fR +itself should be expressed in decimal. +Values larger than 2176782336 (which corresponds to the +base 36 sequence number +\(lqZZZZZZ\(rq) +will be silently truncated to 2176782336. +The default value is 2176782336. +.sp +Once the local sequence number reaches the value of +\fImaxseq\fR, +it will +\(lqroll over\(rq +to zero, after which +\fBsudoers\fR +will truncate and re-use any existing I/O log path names. +.sp +This setting is only supported by version 1.8.7 or higher. +.TP 18n +passwd_tries +The number of tries a user gets to enter his/her password before +\fBsudo\fR +logs the failure and exits. +The default is +\fR@passwd_tries@\fR. +.TP 18n +syslog_maxlen +On many systems, +syslog(3) +has a relatively small log buffer. +IETF RFC 5424 states that syslog servers must support messages of +at least 480 bytes and should support messages up to 2048 bytes. +By default, +\fBsudoers\fR +creates log messages up to 980 bytes which corresponds to the +historic +BSD +syslog implementation which used a 1024 byte buffer +to store the message, date, hostname and program name. +To prevent syslog messages from being truncated, +\fBsudoers\fR +will split up log messages that are larger than +\fIsyslog_maxlen\fR +bytes. +When a message is split, additional parts will include the string +\(lq(command continued)\(rq +after the user name and before the continued command line arguments. +.sp +This setting is only supported by version 1.8.19 or higher. +.PP +\fBIntegers that can be used in a boolean context\fR: +.TP 18n +loglinelen +Number of characters per line for the file log. +This value is used to decide when to wrap lines for nicer log files. +This has no effect on the syslog log file, only the file log. +The default is +\fR@loglen@\fR +(use 0 or negate the option to disable word wrap). +.TP 18n +passwd_timeout +Number of minutes before the +\fBsudo\fR +password prompt times out, or +\fR0\fR +for no timeout. +The timeout may include a fractional component +if minute granularity is insufficient, for example +\fR2.5\fR. +The +default is +\fR@password_timeout@\fR. +.TP 18n +timestamp_timeout +.br +Number of minutes that can elapse before +\fBsudo\fR +will ask for a passwd again. +The timeout may include a fractional component if +minute granularity is insufficient, for example +\fR2.5\fR. +The default is +\fR@timeout@\fR. +Set this to +\fR0\fR +to always prompt for a password. +If set to a value less than +\fR0\fR +the user's time stamp will not expire until the system is rebooted. +This can be used to allow users to create or delete their own time stamps via +\(lq\fRsudo -v\fR\(rq +and +\(lq\fRsudo -k\fR\(rq +respectively. +.TP 18n +umask +Umask to use when running the command. +Negate this option or set it to 0777 to preserve the user's umask. +The actual umask that is used will be the union of the user's umask +and the value of the +\fIumask\fR +option, which defaults to +\fR@sudo_umask@\fR. +This guarantees +that +\fBsudo\fR +never lowers the umask when running a command. +Note: on systems that use PAM, the default PAM configuration may specify +its own umask which will override the value set in +\fIsudoers\fR. +.PP +\fBStrings\fR: +.TP 18n +authfail_message +Message that is displayed after a user fails to authenticate. +The message may include the +\(oq%d\(cq +escape which will expand to the number of failed password attempts. +If set, it overrides the default message, +\fR%d incorrect password attempt(s)\fR. +.TP 18n +badpass_message +Message that is displayed if a user enters an incorrect password. +The default is +\fR@badpass_message@\fR +unless insults are enabled. +.TP 18n +editor +A colon +(\(oq:\&\(cq) +separated list of editors path names used by +\fBsudoedit\fR +and +\fBvisudo\fR. +For +\fBsudoedit\fR, +this list is used to find an editor when none of the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +environment variables are set to an editor that exists and is executable. +For +\fBvisudo\fR, +it is used as a white list of allowed editors; +\fBvisudo\fR +will choose the editor that matches the user's +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +environment variable if possible, or the first editor in the +list that exists and is executable if not. +Unless invoked as +\fBsudoedit\fR, +\fBsudo\fR +does not preserve the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +and +\fREDITOR\fR +environment variables by default, even when the +\fIenv_reset\fR +option is enabled. +The default is +\fI@editor@\fR. +.TP 18n +iolog_dir +The top-level directory to use when constructing the path name for +the input/output log directory. +Only used if the +\fIlog_input\fR +or +\fIlog_output\fR +options are enabled or when the +\fRLOG_INPUT\fR +or +\fRLOG_OUTPUT\fR +tags are present for a command. +The session sequence number, if any, is stored in the directory. +The default is +\fI@iolog_dir@\fR. +.sp +The following percent +(\(oq%\(cq) +escape sequences are supported: +.PP +.RS 18n +.PD 0 +.TP 6n +\fR%{seq}\fR +expanded to a monotonically increasing base-36 sequence number, such as 0100A5, +where every two digits are used to form a new directory, e.g., +\fI01/00/A5\fR +.PD +.TP 6n +\fR%{user}\fR +expanded to the invoking user's login name +.TP 6n +\fR%{group}\fR +expanded to the name of the invoking user's real group ID +.TP 6n +\fR%{runas_user}\fR +expanded to the login name of the user the command will +be run as (e.g., root) +.TP 6n +\fR%{runas_group}\fR +expanded to the group name of the user the command will +be run as (e.g., wheel) +.TP 6n +\fR%{hostname}\fR +expanded to the local host name without the domain name +.TP 6n +\fR%{command}\fR +expanded to the base name of the command being run +.PP +In addition, any escape sequences supported by the system's +strftime(3) +function will be expanded. +.sp +To include a literal +\(oq%\(cq +character, the string +\(oq%%\(cq +should be used. +.RE +.TP 18n +iolog_file +The path name, relative to +\fIiolog_dir\fR, +in which to store input/output logs when the +\fIlog_input\fR +or +\fIlog_output\fR +options are enabled or when the +\fRLOG_INPUT\fR +or +\fRLOG_OUTPUT\fR +tags are present for a command. +Note that +\fIiolog_file\fR +may contain directory components. +The default is +\(lq\fR%{seq}\fR\(rq. +.sp +See the +\fIiolog_dir\fR +option above for a list of supported percent +(\(oq%\(cq) +escape sequences. +.sp +In addition to the escape sequences, path names that end in six or +more +\fRX\fRs +will have the +\fRX\fRs +replaced with a unique combination of digits and letters, similar to the +mktemp(3) +function. +.sp +If the path created by concatenating +\fIiolog_dir\fR +and +\fIiolog_file\fR +already exists, the existing I/O log file will be truncated and +overwritten unless +\fIiolog_file\fR +ends in six or +more +\fRX\fRs. +.TP 18n +iolog_flush +If set, +\fBsudo\fR +will flush I/O log data to disk after each write instead of buffering it. +This makes it possible to view the logs in real-time as the program +is executing but may significantly reduce the effectiveness of I/O +log compression. +This flag is +\fIoff\fR +by default. +.sp +This setting is only supported by version 1.8.20 or higher. +.TP 18n +iolog_group +The group name to look up when setting the group ID on new I/O log +files and directories. +If +\fIiolog_group\fR +is not set, +the primary group ID of the user specified by +\fIiolog_user\fR +is used. +If neither +\fIiolog_group\fR +nor +\fIiolog_user\fR +are set, I/O log files and directories are created with group ID 0. +.sp +This setting is only supported by version 1.8.19 or higher. +.TP 18n +iolog_mode +The file mode to use when creating I/O log files. +Mode bits for read and write permissions for owner, group or other +are honored, everything else is ignored. +The file permissions will always include the owner read and +write bits, even if they are not present in the specified mode. +When creating I/O log directories, search (execute) bits are added +to match the read and write bits specified by +\fIiolog_mode\fR. +Defaults to 0600 (read and write by user only). +.sp +This setting is only supported by version 1.8.19 or higher. +.TP 18n +iolog_user +The user name to look up when setting the user and group IDs on new +I/O log files and directories. +If +\fIiolog_group\fR +is set, it will be used instead of the user's primary group ID. +By default, I/O log files and directories are created with user and +group ID 0. +.sp +This setting can be useful when the I/O logs are stored on a Network +File System (NFS) share. +Having a dedicated user own the I/O log files means that +\fBsudoers\fR +does not write to the log files as user ID 0, which is usually +not permitted by NFS. +.sp +This setting is only supported by version 1.8.19 or higher. +.TP 18n +lecture_status_dir +The directory in which +\fBsudo\fR +stores per-user lecture status files. +Once a user has received the lecture, a zero-length file is +created in this directory so that +\fBsudo\fR +will not lecture the user again. +This directory should +\fInot\fR +be cleared when the system reboots. +The default is +\fI@vardir@/lectured\fR. +.if \n(PS \{\ +.TP 18n +limitprivs +The default Solaris limit privileges to use when constructing a new +privilege set for a command. +This bounds all privileges of the executing process. +The default limit privileges may be overridden on a per-command basis in +\fIsudoers\fR. +This option is only available if +\fBsudoers\fR +is built on Solaris 10 or higher. +.\} +.TP 18n +mailsub +Subject of the mail sent to the +\fImailto\fR +user. +The escape +\fR%h\fR +will expand to the host name of the machine. +Default is +\(lq\fR@mailsub@\fR\(rq. +.TP 18n +noexec_file +As of +\fBsudo\fR +version 1.8.1 this option is no longer supported. +The path to the noexec file should now be set in the +sudo.conf(@mansectform@) +file. +.TP 18n +pam_login_service +.br +On systems that use PAM for authentication, this is the service +name used when the +\fB\-i\fR +option is specified. +The default value is +\(lq\fR@pam_login_service@\fR\(rq. +See the description of +\fIpam_service\fR +for more information. +.sp +This setting is only supported by version 1.8.8 or higher. +.TP 18n +pam_service +On systems that use PAM for authentication, the service name +specifies the PAM policy to apply. +This usually corresponds to an entry in the +\fIpam.conf\fR +file or a file in the +\fI/etc/pam.d\fR +directory. +The default value is +\(lq\fRsudo\fR\(rq. +.sp +This setting is only supported by version 1.8.8 or higher. +.TP 18n +passprompt +The default prompt to use when asking for a password; can be overridden via the +\fB\-p\fR +option or the +\fRSUDO_PROMPT\fR +environment variable. +The following percent +(\(oq%\(cq) +escape sequences are supported: +.PP +.RS 18n +.PD 0 +.TP 6n +\fR%H\fR +expanded to the local host name including the domain name +(only if the machine's host name is fully qualified or the +\fIfqdn\fR +option is set) +.PD +.TP 6n +\fR%h\fR +expanded to the local host name without the domain name +.TP 6n +\fR%p\fR +expanded to the user whose password is being asked for (respects the +\fIrootpw\fR, +\fItargetpw\fR +and +\fIrunaspw\fR +flags in +\fIsudoers\fR) +.TP 6n +\fR\&%U\fR +expanded to the login name of the user the command will +be run as (defaults to root) +.TP 6n +\fR%u\fR +expanded to the invoking user's login name +.TP 6n +\fR%%\fR +two consecutive +\fR%\fR +characters are collapsed into a single +\fR%\fR +character +.PP +On systems that use PAM for authentication, +\fIpassprompt\fR +will only be used if the prompt provided by the PAM module matches the string +\(lqPassword: \(rq +or +\(lqusername's Password: \(rq. +This ensures that the +\fIpassprompt\fR +setting does not interfere with challenge-response style authentication. +The +\fIpassprompt_override\fR +flag can be used to change this behavior. +.sp +The default value is +\(lq\fR@passprompt@\fR\(rq. +.RE +.if \n(PS \{\ +.TP 18n +privs +The default Solaris privileges to use when constructing a new +privilege set for a command. +This is passed to the executing process via the inherited privilege set, +but is bounded by the limit privileges. +If the +\fIprivs\fR +option is specified but the +\fIlimitprivs\fR +option is not, the limit privileges of the executing process is set to +\fIprivs\fR. +The default privileges may be overridden on a per-command basis in +\fIsudoers\fR. +This option is only available if +\fBsudoers\fR +is built on Solaris 10 or higher. +.\} +.if \n(SL \{\ +.TP 18n +role +The default SELinux role to use when constructing a new security +context to run the command. +The default role may be overridden on a per-command basis in the +\fIsudoers\fR +file or via command line options. +This option is only available when +\fBsudo\fR +is built with SELinux support. +.\} +.TP 18n +runas_default +The default user to run commands as if the +\fB\-u\fR +option is not specified on the command line. +This defaults to +\fR@runas_default@\fR. +.TP 18n +sudoers_locale +Locale to use when parsing the sudoers file, logging commands, and +sending email. +Note that changing the locale may affect how sudoers is interpreted. +Defaults to +\(lq\fRC\fR\(rq. +.TP 18n +timestamp_type +\fBsudoers\fR +uses per-user time stamp files for credential caching. +The +\fItimestamp_type\fR +option can be used to specify the type of time stamp record used. +It has the following possible values: +.PP +.RS 18n +.PD 0 +.TP 8n +global +A single time stamp record is used for all of a user's login sessions, +regardless of the terminal or parent process ID. +An additional record is used to serialize password prompts when +\fBsudo\fR +is used multiple times in a pipeline, but this does not affect authentication. +.PD +.TP 8n +ppid +A single time stamp record is used for all processes with the same parent +process ID (usually the shell). +Commands run from the same shell (or other common parent process) +will not require a password for +\fItimestamp_timeout\fR +minutes +(\fR@timeout@\fR +by default) +\&. +Commands run via +\fBsudo\fR +with a different parent process ID, for example from a shell script, +will be authenticated separately. +.TP 8n +tty +One time stamp record is used for each terminal, +which means that a user's login sessions are authenticated separately. +If no terminal is present, the behavior is the same as +\fIppid\fR. +Commands run from the same terminal will not require a password for +\fItimestamp_timeout\fR +minutes +(\fR@timeout@\fR +by default) +\&. +.TP 8n +kernel +The time stamp is stored in the kernel as an attribute of the terminal +device. +If no terminal is present, the behavior is the same as +\fIppid\fR. +Negative +\fItimestamp_timeout\fR +values are not supported and positive values are limited to a maximum +of 60 minutes. +This is currently only supported on +OpenBSD. +.PP +The default value is +\fI@timestamp_type@\fR. +.sp +This setting is only supported by version 1.8.21 or higher. +.RE +.TP 18n +timestampdir +The directory in which +\fBsudo\fR +stores its time stamp files. +This directory should be cleared when the system reboots. +The default is +\fI@rundir@/ts\fR. +.TP 18n +timestampowner +The owner of the lecture status directory, time stamp directory and all +files stored therein. +The default is +\fRroot\fR. +.if \n(SL \{\ +.TP 18n +type +The default SELinux type to use when constructing a new security +context to run the command. +The default type may be overridden on a per-command basis in the +\fIsudoers\fR +file or via command line options. +This option is only available when +\fBsudo\fR +is built with SELinux support. +.PP +\fBStrings that can be used in a boolean context\fR: +.TP 14n +env_file +The +\fIenv_file\fR +option specifies the fully qualified path to a file containing variables +to be set in the environment of the program being run. +Entries in this file should either be of the form +\(lq\fRVARIABLE=value\fR\(rq +or +\(lq\fRexport VARIABLE=value\fR\(rq. +The value may optionally be surrounded by single or double quotes. +Variables in this file are only added if the variable does not already +exist in the environment. +This file is considered to be part of the security policy, +its contents are not subject to other +\fBsudo\fR +environment restrictions such as +\fIenv_keep\fR +and +\fIenv_check\fR. +.TP 14n +exempt_group +Users in this group are exempt from password and PATH requirements. +The group name specified should not include a +\fR%\fR +prefix. +This is not set by default. +.TP 14n +fdexec +Determines whether +\fBsudo\fR +will execute a command by its path or by an open file descriptor. +It has the following possible values: +.PP +.RS 14n +.PD 0 +.TP 8n +always +Always execute by file descriptor. +.PD +.TP 8n +never +Never execute by file descriptor. +.TP 8n +digest_only +Only execute by file descriptor if the command has an associated digest +in the +\fIsudoers\fR +file. +.PP +The default value is +\fIdigest_only\fR. +This avoids a time of check versus time of use race condition when +the command is located in a directory writable by the invoking user. +.sp +Note that +\fIfdexec\fR +will change the first element of the argument vector for scripts +($0 in the shell) due to the way the kernel runs script interpreters. +Instead of being a normal path, it will refer to a file descriptor. +For example, +\fI/dev/fd/4\fR +on Solaris and +\fI/proc/self/fd/4\fR +on Linux. +A workaround is to use the +\fRSUDO_COMMAND\fR +environment variable instead. +.sp +The +\fIfdexec\fR +setting is only used when the command is matched by path name. +It has no effect if the command is matched by the built-in +\fBALL\fR +alias. +.sp +This setting is only supported by version 1.8.20 or higher. +If the operating system does not support the +fexecve(2) +system call, this setting has no effect. +.RE +.TP 14n +group_plugin +A string containing a +\fBsudoers\fR +group plugin with optional arguments. +The string should consist of the plugin +path, either fully-qualified or relative to the +\fI@PLUGINDIR@\fR +directory, followed by any configuration arguments the plugin requires. +These arguments (if any) will be passed to the plugin's initialization function. +If arguments are present, the string must be enclosed in double quotes +(\&""). +.sp +For more information see +\fIGROUP PROVIDER PLUGINS\fR. +.TP 14n +lecture +This option controls when a short lecture will be printed along with +the password prompt. +It has the following possible values: +.PP +.RS 14n +.PD 0 +.TP 8n +always +Always lecture the user. +.PD +.TP 8n +never +Never lecture the user. +.TP 8n +once +Only lecture the user the first time they run +\fBsudo\fR. +.PP +If no value is specified, a value of +\fIonce\fR +is implied. +Negating the option results in a value of +\fInever\fR +being used. +The default value is +\fI@lecture@\fR. +.RE +.TP 14n +lecture_file +Path to a file containing an alternate +\fBsudo\fR +lecture that will be used in place of the standard lecture if the named +file exists. +By default, +\fBsudo\fR +uses a built-in lecture. +.TP 14n +listpw +This option controls when a password will be required when a user runs +\fBsudo\fR +with the +\fB\-l\fR +option. +It has the following possible values: +.PP +.RS 14n +.PD 0 +.TP 10n +all +All the user's +\fIsudoers\fR +file entries for the current host must have +the +\fRNOPASSWD\fR +flag set to avoid entering a password. +.PD +.TP 10n +always +The user must always enter a password to use the +\fB\-l\fR +option. +.TP 10n +any +At least one of the user's +\fIsudoers\fR +file entries for the current host +must have the +\fRNOPASSWD\fR +flag set to avoid entering a password. +.TP 10n +never +The user need never enter a password to use the +\fB\-l\fR +option. +.PP +If no value is specified, a value of +\fIany\fR +is implied. +Negating the option results in a value of +\fInever\fR +being used. +The default value is +\fIany\fR. +.RE +.TP 14n +logfile +Path to the +\fBsudo\fR +log file (not the syslog log file). +Setting a path turns on logging to a file; +negating this option turns it off. +By default, +\fBsudo\fR +logs via syslog. +.TP 14n +mailerflags +Flags to use when invoking mailer. +Defaults to +\fB\-t\fR. +.TP 14n +mailerpath +Path to mail program used to send warning mail. +Defaults to the path to sendmail found at configure time. +.TP 14n +mailfrom +Address to use for the +\(lqfrom\(rq +address when sending warning and error mail. +The address should be enclosed in double quotes +(\&"") +to protect against +\fBsudo\fR +interpreting the +\fR@\fR +sign. +Defaults to the name of the user running +\fBsudo\fR. +.TP 14n +mailto +Address to send warning and error mail to. +The address should be enclosed in double quotes +(\&"") +to protect against +\fBsudo\fR +interpreting the +\fR@\fR +sign. +Defaults to +\fR@mailto@\fR. +.TP 14n +restricted_env_file +The +\fIrestricted_env_file\fR +option specifies the fully qualified path to a file containing variables +to be set in the environment of the program being run. +Entries in this file should either be of the form +\(lq\fRVARIABLE=value\fR\(rq +or +\(lq\fRexport VARIABLE=value\fR\(rq. +The value may optionally be surrounded by single or double quotes. +Variables in this file are only added if the variable does not already +exist in the environment. +Unlike +\fIenv_file\fR, +the file's contents are not trusted and are processed in a manner +similar to that of the invoking user's environment. +If +\fIenv_reset\fR +is enabled, variables in the file will only be added if they are +matched by either the +\fIenv_check\fR +or +\fIenv_keep\fR +list. +If +\fIenv_reset\fR +is disabled, variables in the file are added as long as they +are not matched by the +\fIenv_delete\fR +list. +In either case, the contents of +\fIrestricted_env_file\fR +are processed before the contents of +\fIenv_file\fR. +.TP 14n +secure_path +Path used for every command run from +\fBsudo\fR. +If you don't trust the +people running +\fBsudo\fR +to have a sane +\fRPATH\fR +environment variable you may want to use this. +Another use is if you want to have the +\(lqroot path\(rq +be separate from the +\(lquser path\(rq. +Users in the group specified by the +\fIexempt_group\fR +option are not affected by +\fIsecure_path\fR. +This option is @secure_path@ by default. +.TP 14n +syslog +Syslog facility if syslog is being used for logging (negate to +disable syslog logging). +Defaults to +\fR@logfac@\fR. +.sp +The following syslog facilities are supported: +\fBauthpriv\fR +(if your +OS supports it), +\fBauth\fR, +\fBdaemon\fR, +\fBuser\fR, +\fBlocal0\fR, +\fBlocal1\fR, +\fBlocal2\fR, +\fBlocal3\fR, +\fBlocal4\fR, +\fBlocal5\fR, +\fBlocal6\fR, +and +\fBlocal7\fR. +.TP 14n +syslog_badpri +.br +Syslog priority to use when the user is not allowed to run a command or +when authentication is unsuccessful. +Defaults to +\fR@badpri@\fR. +.sp +The following syslog priorities are supported: +\fBalert\fR, +\fBcrit\fR, +\fBdebug\fR, +\fBemerg\fR, +\fBerr\fR, +\fBinfo\fR, +\fBnotice\fR, +\fBwarning\fR, +and +\fBnone\fR. +Negating the option or setting it to a value of +\fBnone\fR +will disable logging of unsuccessful commands. +.TP 14n +syslog_goodpri +Syslog priority to use when the user is allowed to run a command and +authentication is successful. +Defaults to +\fR@goodpri@\fR. +.sp +See +\fIsyslog_badpri\fR +for the list of supported syslog priorities. +Negating the option or setting it to a value of +\fBnone\fR +will disable logging of successful commands. +.TP 14n +verifypw +This option controls when a password will be required when a user runs +\fBsudo\fR +with the +\fB\-v\fR +option. +It has the following possible values: +.PP +.RS 14n +.PD 0 +.TP 8n +all +All the user's +\fIsudoers\fR +file entries for the current host must have the +\fRNOPASSWD\fR +flag set to avoid entering a password. +.PD +.TP 8n +always +The user must always enter a password to use the +\fB\-v\fR +option. +.TP 8n +any +At least one of the user's +\fIsudoers\fR +file entries for the current host must have the +\fRNOPASSWD\fR +flag set to avoid entering a password. +.TP 8n +never +The user need never enter a password to use the +\fB\-v\fR +option. +.PP +If no value is specified, a value of +\fIall\fR +is implied. +Negating the option results in a value of +\fInever\fR +being used. +The default value is +\fIall\fR. +.RE +.PP +\fBLists that can be used in a boolean context\fR: +.\} +.TP 18n +env_check +Environment variables to be removed from the user's environment +unless they are considered +\(lqsafe\(rq. +For all variables except +\fRTZ\fR, +\(lqsafe\(rq +means that the variable's value does not contain any +\(oq%\(cq +or +\(oq/\(cq +characters. +This can be used to guard against printf-style format vulnerabilities +in poorly-written programs. +The +\fRTZ\fR +variable is considered unsafe if any of the following are true: +.PP +.RS 18n +.PD 0 +.TP 3n +\fB\(bu\fR +It consists of a fully-qualified path name, +optionally prefixed with a colon +(\(oq:\&\(cq), +that does not match the location of the +\fIzoneinfo\fR +directory. +.PD +.TP 3n +\fB\(bu\fR +It contains a +\fI..\fR +path element. +.TP 3n +\fB\(bu\fR +It contains white space or non-printable characters. +.TP 3n +\fB\(bu\fR +It is longer than the value of +\fRPATH_MAX\fR. +.PP +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using +the +\fR=\fR, +\fR+=\fR, +\fR-=\fR, +and +\fR\&!\fR +operators respectively. +Regardless of whether the +\fRenv_reset\fR +option is enabled or disabled, variables specified by +\fRenv_check\fR +will be preserved in the environment if they pass the aforementioned check. +The global list of environment variables to check is displayed when +\fBsudo\fR +is run by root with +the +\fB\-V\fR +option. +.RE +.TP 18n +env_delete +Environment variables to be removed from the user's environment when the +\fIenv_reset\fR +option is not in effect. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +\fR=\fR, +\fR+=\fR, +\fR-=\fR, +and +\fR\&!\fR +operators respectively. +The global list of environment variables to remove is displayed when +\fBsudo\fR +is run by root with the +\fB\-V\fR +option. +Note that many operating systems will remove potentially dangerous +variables from the environment of any setuid process (such as +\fBsudo\fR). +.TP 18n +env_keep +Environment variables to be preserved in the user's environment when the +\fIenv_reset\fR +option is in effect. +This allows fine-grained control over the environment +\fBsudo\fR-spawned +processes will receive. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +\fR=\fR, +\fR+=\fR, +\fR-=\fR, +and +\fR\&!\fR +operators respectively. +The global list of variables to keep +is displayed when +\fBsudo\fR +is run by root with the +\fB\-V\fR +option. +.SH "GROUP PROVIDER PLUGINS" +The +\fBsudoers\fR +plugin supports its own plugin interface to allow non-Unix +group lookups which can query a group source other +than the standard Unix group database. +This can be used to implement support for the +\fRnonunix_group\fR +syntax described earlier. +.PP +Group provider plugins are specified via the +\fIgroup_plugin\fR +Defaults setting. +The argument to +\fIgroup_plugin\fR +should consist of the plugin path, either fully-qualified or relative to the +\fI@PLUGINDIR@\fR +directory, followed by any configuration options the plugin requires. +These options (if specified) will be passed to the plugin's initialization +function. +If options are present, the string must be enclosed in double quotes +(\&""). +.PP +The following group provider plugins are installed by default: +.TP 10n +group_file +The +\fIgroup_file\fR +plugin supports an alternate group file that uses the same syntax as the +\fI/etc/group\fR +file. +The path to the group file should be specified as an option +to the plugin. +For example, if the group file to be used is +\fI/etc/sudo-group\fR: +.nf +.sp +.RS 10n +Defaults group_plugin="group_file.so /etc/sudo-group" +.RE +.fi +.TP 10n +system_group +The +\fIsystem_group\fR +plugin supports group lookups via the standard C library functions +\fBgetgrnam\fR() +and +\fBgetgrid\fR(). +This plugin can be used in instances where the user belongs to +groups not present in the user's supplemental group vector. +This plugin takes no options: +.nf +.sp +.RS 10n +Defaults group_plugin=system_group.so +.RE +.fi +.PP +The group provider plugin API is described in detail in +sudo_plugin(@mansectform@). +.SH "LOG FORMAT" +\fBsudoers\fR +can log events using either +syslog(3) +or a simple log file. +The log format is almost identical in both cases. +.SS "Accepted command log entries" +Commands that sudo runs are logged using the following format (split +into multiple lines for readability): +.nf +.sp +.RS 4n +date hostname progname: username : TTY=ttyname ; PWD=cwd ; \e + USER=runasuser ; GROUP=runasgroup ; TSID=logid ; \e + ENV=env_vars COMMAND=command +.RE +.fi +.PP +Where the fields are as follows: +.TP 14n +date +The date the command was run. +Typically, this is in the format +\(lqMMM, DD, HH:MM:SS\(rq. +If logging via +syslog(3), +the actual date format is controlled by the syslog daemon. +If logging to a file and the +\fIlog_year\fR +option is enabled, +the date will also include the year. +.TP 14n +hostname +The name of the host +\fBsudo\fR +was run on. +This field is only present when logging via +syslog(3). +.TP 14n +progname +The name of the program, usually +\fIsudo\fR +or +\fIsudoedit\fR. +This field is only present when logging via +syslog(3). +.TP 14n +username +The login name of the user who ran +\fBsudo\fR. +.TP 14n +ttyname +The short name of the terminal (e.g., +\(lqconsole\(rq, +\(lqtty01\(rq, +or +\(lqpts/0\(rq) +\fBsudo\fR +was run on, or +\(lqunknown\(rq +if there was no terminal present. +.TP 14n +cwd +The current working directory that +\fBsudo\fR +was run in. +.TP 14n +runasuser +The user the command was run as. +.TP 14n +runasgroup +The group the command was run as if one was specified on the command line. +.TP 14n +logid +An I/O log identifier that can be used to replay the command's output. +This is only present when the +\fIlog_input\fR +or +\fIlog_output\fR +option is enabled. +.TP 14n +env_vars +A list of environment variables specified on the command line, +if specified. +.TP 14n +command +The actual command that was executed. +.PP +Messages are logged using the locale specified by +\fIsudoers_locale\fR, +which defaults to the +\(lq\fRC\fR\(rq +locale. +.SS "Denied command log entries" +If the user is not allowed to run the command, the reason for the denial +will follow the user name. +Possible reasons include: +.TP 3n +user NOT in sudoers +The user is not listed in the +\fIsudoers\fR +file. +.TP 3n +user NOT authorized on host +The user is listed in the +\fIsudoers\fR +file but is not allowed to run commands on the host. +.TP 3n +command not allowed +The user is listed in the +\fIsudoers\fR +file for the host but they are not allowed to run the specified command. +.TP 3n +3 incorrect password attempts +The user failed to enter their password after 3 tries. +The actual number of tries will vary based on the number of +failed attempts and the value of the +\fIpasswd_tries\fR +option. +.TP 3n +a password is required +\fBsudo\fR's +\fB\-n\fR +option was specified but a password was required. +.TP 3n +sorry, you are not allowed to set the following environment variables +The user specified environment variables on the command line that +were not allowed by +\fIsudoers\fR. +.SS "Error log entries" +If an error occurs, +\fBsudoers\fR +will log a message and, in most cases, send a message to the +administrator via email. +Possible errors include: +.TP 3n +parse error in @sysconfdir@/sudoers near line N +\fBsudoers\fR +encountered an error when parsing the specified file. +In some cases, the actual error may be one line above or below the +line number listed, depending on the type of error. +.TP 3n +problem with defaults entries +The +\fIsudoers\fR +file contains one or more unknown Defaults settings. +This does not prevent +\fBsudo\fR +from running, but the +\fIsudoers\fR +file should be checked using +\fBvisudo\fR. +.TP 3n +timestamp owner (username): \&No such user +The time stamp directory owner, as specified by the +\fItimestampowner\fR +setting, could not be found in the password database. +.TP 3n +unable to open/read @sysconfdir@/sudoers +The +\fIsudoers\fR +file could not be opened for reading. +This can happen when the +\fIsudoers\fR +file is located on a remote file system that maps user ID 0 to +a different value. +Normally, +\fBsudoers\fR +tries to open the +\fIsudoers\fR +file using group permissions to avoid this problem. +Consider either changing the ownership of +\fI@sysconfdir@/sudoers\fR +or adding an argument like +\(lqsudoers_uid=N\(rq +(where +\(oqN\(cq +is the user ID that owns the +\fIsudoers\fR +file) to the end of the +\fBsudoers\fR +\fRPlugin\fR +line in the +sudo.conf(@mansectform@) +file. +.TP 3n +unable to stat @sysconfdir@/sudoers +The +\fI@sysconfdir@/sudoers\fR +file is missing. +.TP 3n +@sysconfdir@/sudoers is not a regular file +The +\fI@sysconfdir@/sudoers\fR +file exists but is not a regular file or symbolic link. +.TP 3n +@sysconfdir@/sudoers is owned by uid N, should be 0 +The +\fIsudoers\fR +file has the wrong owner. +If you wish to change the +\fIsudoers\fR +file owner, please add +\(lqsudoers_uid=N\(rq +(where +\(oqN\(cq +is the user ID that owns the +\fIsudoers\fR +file) to the +\fBsudoers\fR +\fRPlugin\fR +line in the +sudo.conf(@mansectform@) +file. +.TP 3n +@sysconfdir@/sudoers is world writable +The permissions on the +\fIsudoers\fR +file allow all users to write to it. +The +\fIsudoers\fR +file must not be world-writable, the default file mode +is 0440 (readable by owner and group, writable by none). +The default mode may be changed via the +\(lqsudoers_mode\(rq +option to the +\fBsudoers\fR +\fRPlugin\fR +line in the +sudo.conf(@mansectform@) +file. +.TP 3n +@sysconfdir@/sudoers is owned by gid N, should be 1 +The +\fIsudoers\fR +file has the wrong group ownership. +If you wish to change the +\fIsudoers\fR +file group ownership, please add +\(lqsudoers_gid=N\(rq +(where +\(oqN\(cq +is the group ID that owns the +\fIsudoers\fR +file) to the +\fBsudoers\fR +\fRPlugin\fR +line in the +sudo.conf(@mansectform@) +file. +.TP 3n +unable to open @rundir@/ts/username +\fBsudoers\fR +was unable to read or create the user's time stamp file. +This can happen when +\fItimestampowner\fR +is set to a user other than root and the mode on +\fI@rundir@\fR +is not searchable by group or other. +The default mode for +\fI@rundir@\fR +is 0711. +.TP 3n +unable to write to @rundir@/ts/username +\fBsudoers\fR +was unable to write to the user's time stamp file. +.TP 3n +@rundir@/ts is owned by uid X, should be Y +The time stamp directory is owned by a user other than +\fItimestampowner\fR. +This can occur when the value of +\fItimestampowner\fR +has been changed. +\fBsudoers\fR +will ignore the time stamp directory until the owner is corrected. +.TP 3n +@rundir@/ts is group writable +The time stamp directory is group-writable; it should be writable only by +\fItimestampowner\fR. +The default mode for the time stamp directory is 0700. +\fBsudoers\fR +will ignore the time stamp directory until the mode is corrected. +.SS "Notes on logging via syslog" +By default, +\fBsudoers\fR +logs messages via +syslog(3). +The +\fIdate\fR, +\fIhostname\fR, +and +\fIprogname\fR +fields are added by the system's +\fBsyslog\fR() +function, not +\fBsudoers\fR +itself. +As such, they may vary in format on different systems. +.PP +The maximum size of syslog messages varies from system to system. +The +\fIsyslog_maxlen\fR +setting can be used to change the maximum syslog message size +from the default value of 980 bytes. +For more information, see the description of +\fIsyslog_maxlen\fR. +.SS "Notes on logging to a file" +If the +\fIlogfile\fR +option is set, +\fBsudoers\fR +will log to a local file, such as +\fI/var/log/sudo\fR. +When logging to a file, +\fBsudoers\fR +uses a format similar to +syslog(3), +with a few important differences: +.TP 5n +1.\& +The +\fIprogname\fR +and +\fIhostname\fR +fields are not present. +.TP 5n +2.\& +If the +\fIlog_year\fR +option is enabled, +the date will also include the year. +.TP 5n +3.\& +Lines that are longer than +\fIloglinelen\fR +characters (80 by default) are word-wrapped and continued on the +next line with a four character indent. +This makes entries easier to read for a human being, but makes it +more difficult to use +grep(1) +on the log files. +If the +\fIloglinelen\fR +option is set to 0 (or negated with a +\(oq\&!\(cq), +word wrap will be disabled. +.SH "I/O LOG FILES" +When I/O logging is enabled, +\fBsudo\fR +will run the command in a pseudo-tty and log all user input and/or output, +depending on which options are enabled. +I/O is logged to the directory specified by the +\fIiolog_dir\fR +option +(\fI@iolog_dir@\fR +by default) +using a unique session ID that is included in the +\fBsudo\fR +log line, prefixed with +\(lq\fRTSID=\fR\(rq. +The +\fIiolog_file\fR +option may be used to control the format of the session ID. +.PP +Each I/O log is stored in a separate directory that contains the +following files: +.TP 10n +\fIlog\fR +a text file containing the time the command was run, the name of the user +who ran +\fBsudo\fR, +the name of the target user, the name of the target group (optional), +the terminal that +\fBsudo\fR +was run from, the number of rows and columns of the terminal, +the working directory the command was run from and the path name of +the command itself (with arguments if present) +.TP 10n +\fItiming\fR +a log of the amount of time between, and the number of bytes in, each +I/O log entry (used for session playback) +.TP 10n +\fIttyin\fR +input from the user's tty (what the user types) +.TP 10n +\fIstdin\fR +input from a pipe or file +.TP 10n +\fIttyout\fR +output from the pseudo-tty (what the command writes to the screen) +.TP 10n +\fIstdout\fR +standard output to a pipe or redirected to a file +.TP 10n +\fIstderr\fR +standard error to a pipe or redirected to a file +.PP +All files other than +\fIlog\fR +are compressed in gzip format unless the +\fIcompress_io\fR +flag has been disabled. +Due to buffering, it is not normally possible to display the I/O logs in +real-time as the program is executing +The I/O log data will not be complete until the program run by +\fBsudo\fR +has exited or has been terminated by a signal. +The +\fIiolog_flush\fR +flag can be used to disable buffering, in which case I/O log data +is written to disk as soon as it is available. +The output portion of an I/O log file can be viewed with the +sudoreplay(@mansectsu@) +utility, which can also be used to list or search the available logs. +.PP +Note that user input may contain sensitive information such as +passwords (even if they are not echoed to the screen), which will +be stored in the log file unencrypted. +In most cases, logging the command output via +\fIlog_output\fR +or +\fRLOG_OUTPUT\fR +is all that is required. +.PP +Since each session's I/O logs are stored in a separate directory, +traditional log rotation utilities cannot be used to limit the +number of I/O logs. +The simplest way to limit the number of I/O is by setting the +\fImaxseq\fR +option to the maximum number of logs you wish to store. +Once the I/O log sequence number reaches +\fImaxseq\fR, +it will be reset to zero and +\fBsudoers\fR +will truncate and re-use any existing I/O logs. +.SH "FILES" +.TP 26n +\fI@sysconfdir@/sudo.conf\fR +Sudo front end configuration +.TP 26n +\fI@sysconfdir@/sudoers\fR +List of who can run what +.TP 26n +\fI/etc/group\fR +Local groups file +.TP 26n +\fI/etc/netgroup\fR +List of network groups +.TP 26n +\fI@iolog_dir@\fR +I/O log files +.TP 26n +\fI@rundir@/ts\fR +Directory containing time stamps for the +\fBsudoers\fR +security policy +.TP 26n +\fI@vardir@/lectured\fR +Directory containing lecture status files for the +\fBsudoers\fR +security policy +.TP 26n +\fI/etc/environment\fR +Initial environment for +\fB\-i\fR +mode on AIX and Linux systems +.SH "EXAMPLES" +Below are example +\fIsudoers\fR +file entries. +Admittedly, some of these are a bit contrived. +First, we allow a few environment variables to pass and then define our +\fIaliases\fR: +.nf +.sp +.RS 0n +# Run X applications through sudo; HOME is used to find the +# .Xauthority file. Note that other programs use HOME to find +# configuration files and this may lead to privilege escalation! +Defaults env_keep += "DISPLAY HOME" + +# User alias specification +User_Alias FULLTIMERS = millert, mikef, dowdy +User_Alias PARTTIMERS = bostley, jwfox, crawl +User_Alias WEBMASTERS = will, wendy, wim + +# Runas alias specification +Runas_Alias OP = root, operator +Runas_Alias DB = oracle, sybase +Runas_Alias ADMINGRP = adm, oper + +# Host alias specification +Host_Alias SPARC = bigtime, eclipse, moet, anchor :\e + SGI = grolsch, dandelion, black :\e + ALPHA = widget, thalamus, foobar :\e + HPPA = boa, nag, python +Host_Alias CUNETS = 128.138.0.0/255.255.0.0 +Host_Alias CSNETS = 128.138.243.0, 128.138.204.0/24, 128.138.242.0 +Host_Alias SERVERS = master, mail, www, ns +Host_Alias CDROM = orion, perseus, hercules + +# Cmnd alias specification +Cmnd_Alias DUMPS = /usr/bin/mt, /usr/sbin/dump, /usr/sbin/rdump,\e + /usr/sbin/restore, /usr/sbin/rrestore,\e + sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ== \e + /home/operator/bin/start_backups +Cmnd_Alias KILL = /usr/bin/kill +Cmnd_Alias PRINTING = /usr/sbin/lpc, /usr/bin/lprm +Cmnd_Alias SHUTDOWN = /usr/sbin/shutdown +Cmnd_Alias HALT = /usr/sbin/halt +Cmnd_Alias REBOOT = /usr/sbin/reboot +Cmnd_Alias SHELLS = /usr/bin/sh, /usr/bin/csh, /usr/bin/ksh,\e + /usr/local/bin/tcsh, /usr/bin/rsh,\e + /usr/local/bin/zsh +Cmnd_Alias SU = /usr/bin/su +Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less +.RE +.fi +.PP +Here we override some of the compiled in default values. +We want +\fBsudo\fR +to log via +syslog(3) +using the +\fIauth\fR +facility in all cases. +We don't want to subject the full time staff to the +\fBsudo\fR +lecture, user +\fBmillert\fR +need not give a password, and we don't want to reset the +\fRLOGNAME\fR +or +\fRUSER\fR +environment variables when running commands as root. +Additionally, on the machines in the +\fISERVERS\fR +\fRHost_Alias\fR, +we keep an additional local log file and make sure we log the year +in each log line since the log entries will be kept around for several years. +Lastly, we disable shell escapes for the commands in the PAGERS +\fRCmnd_Alias\fR +(\fI/usr/bin/more\fR, +\fI/usr/bin/pg\fR +and +\fI/usr/bin/less\fR) +\&. +Note that this will not effectively constrain users with +\fBsudo\fR +\fBALL\fR +privileges. +.nf +.sp +.RS 0n +# Override built-in defaults +Defaults syslog=auth +Defaults>root !set_logname +Defaults:FULLTIMERS !lecture +Defaults:millert !authenticate +Defaults@SERVERS log_year, logfile=/var/log/sudo.log +Defaults!PAGERS noexec +.RE +.fi +.PP +The +\fIUser specification\fR +is the part that actually determines who may run what. +.nf +.sp +.RS 0n +root ALL = (ALL) ALL +%wheel ALL = (ALL) ALL +.RE +.fi +.PP +We let +\fBroot\fR +and any user in group +\fBwheel\fR +run any command on any host as any user. +.nf +.sp +.RS 0n +FULLTIMERS ALL = NOPASSWD: ALL +.RE +.fi +.PP +Full time sysadmins +(\fBmillert\fR, +\fBmikef\fR, +and +\fBdowdy\fR) +may run any command on any host without authenticating themselves. +.nf +.sp +.RS 0n +PARTTIMERS ALL = ALL +.RE +.fi +.PP +Part time sysadmins +\fBbostley\fR, +\fBjwfox\fR, +and +\fBcrawl\fR) +may run any command on any host but they must authenticate themselves +first (since the entry lacks the +\fRNOPASSWD\fR +tag). +.nf +.sp +.RS 0n +jack CSNETS = ALL +.RE +.fi +.PP +The user +\fBjack\fR +may run any command on the machines in the +\fICSNETS\fR +alias (the networks +\fR128.138.243.0\fR, +\fR128.138.204.0\fR, +and +\fR128.138.242.0\fR). +Of those networks, only +\fR128.138.204.0\fR +has an explicit netmask (in CIDR notation) indicating it is a class C network. +For the other networks in +\fICSNETS\fR, +the local machine's netmask will be used during matching. +.nf +.sp +.RS 0n +lisa CUNETS = ALL +.RE +.fi +.PP +The user +\fBlisa\fR +may run any command on any host in the +\fICUNETS\fR +alias (the class B network +\fR128.138.0.0\fR). +.nf +.sp +.RS 0n +operator ALL = DUMPS, KILL, SHUTDOWN, HALT, REBOOT, PRINTING,\e + sudoedit /etc/printcap, /usr/oper/bin/ +.RE +.fi +.PP +The +\fBoperator\fR +user may run commands limited to simple maintenance. +Here, those are commands related to backups, killing processes, the +printing system, shutting down the system, and any commands in the +directory +\fI/usr/oper/bin/\fR. +Note that one command in the +\fRDUMPS\fR +Cmnd_Alias includes a sha224 digest, +\fI/home/operator/bin/start_backups\fR. +This is because the directory containing the script is writable by the +operator user. +If the script is modified (resulting in a digest mismatch) it will no longer +be possible to run it via +\fBsudo\fR. +.nf +.sp +.RS 0n +joe ALL = /usr/bin/su operator +.RE +.fi +.PP +The user +\fBjoe\fR +may only +su(1) +to operator. +.nf +.sp +.RS 0n +pete HPPA = /usr/bin/passwd [A-Za-z]*, !/usr/bin/passwd *root* + +%opers ALL = (: ADMINGRP) /usr/sbin/ +.RE +.fi +.PP +Users in the +\fBopers\fR +group may run commands in +\fI/usr/sbin/\fR +as themselves +with any group in the +\fIADMINGRP\fR +\fRRunas_Alias\fR +(the +\fBadm\fR +and +\fBoper\fR +groups). +.PP +The user +\fBpete\fR +is allowed to change anyone's password except for +root on the +\fIHPPA\fR +machines. +Because command line arguments are matched as a single, +concatenated string, the +\(oq*\(cq +wildcard will match +\fImultiple\fR +words. +This example assumes that +passwd(1) +does not take multiple user names on the command line. +Note that on GNU systems, options to +passwd(1) +may be specified after the user argument. +As a result, this rule will also allow: +.nf +.sp +.RS 4n +passwd username --expire +.RE +.fi +.PP +which may not be desirable. +.nf +.sp +.RS 0n +bob SPARC = (OP) ALL : SGI = (OP) ALL +.RE +.fi +.PP +The user +\fBbob\fR +may run anything on the +\fISPARC\fR +and +\fISGI\fR +machines as any user listed in the +\fIOP\fR +\fRRunas_Alias\fR +(\fBroot\fR +and +\fBoperator\fR.) +.nf +.sp +.RS 0n +jim +biglab = ALL +.RE +.fi +.PP +The user +\fBjim\fR +may run any command on machines in the +\fIbiglab\fR +netgroup. +\fBsudo\fR +knows that +\(lqbiglab\(rq +is a netgroup due to the +\(oq+\(cq +prefix. +.nf +.sp +.RS 0n ++secretaries ALL = PRINTING, /usr/bin/adduser, /usr/bin/rmuser +.RE +.fi +.PP +Users in the +\fBsecretaries\fR +netgroup need to help manage the printers as well as add and remove users, +so they are allowed to run those commands on all machines. +.nf +.sp +.RS 0n +fred ALL = (DB) NOPASSWD: ALL +.RE +.fi +.PP +The user +\fBfred\fR +can run commands as any user in the +\fIDB\fR +\fRRunas_Alias\fR +(\fBoracle\fR +or +\fBsybase\fR) +without giving a password. +.nf +.sp +.RS 0n +john ALPHA = /usr/bin/su [!-]*, !/usr/bin/su *root* +.RE +.fi +.PP +On the +\fIALPHA\fR +machines, user +\fBjohn\fR +may su to anyone except root but he is not allowed to specify any options +to the +su(1) +command. +.nf +.sp +.RS 0n +jen ALL, !SERVERS = ALL +.RE +.fi +.PP +The user +\fBjen\fR +may run any command on any machine except for those in the +\fISERVERS\fR +\fRHost_Alias\fR +(master, mail, www and ns). +.nf +.sp +.RS 0n +jill SERVERS = /usr/bin/, !SU, !SHELLS +.RE +.fi +.PP +For any machine in the +\fISERVERS\fR +\fRHost_Alias\fR, +\fBjill\fR +may run +any commands in the directory +\fI/usr/bin/\fR +except for those commands +belonging to the +\fISU\fR +and +\fISHELLS\fR +\fRCmnd_Aliases\fR. +While not specifically mentioned in the rule, the commands in the +\fIPAGERS\fR +\fRCmnd_Alias\fR +all reside in +\fI/usr/bin\fR +and have the +\fInoexec\fR +option set. +.nf +.sp +.RS 0n +steve CSNETS = (operator) /usr/local/op_commands/ +.RE +.fi +.PP +The user +\fBsteve\fR +may run any command in the directory /usr/local/op_commands/ +but only as user operator. +.nf +.sp +.RS 0n +matt valkyrie = KILL +.RE +.fi +.PP +On his personal workstation, valkyrie, +\fBmatt\fR +needs to be able to kill hung processes. +.nf +.sp +.RS 0n +WEBMASTERS www = (www) ALL, (root) /usr/bin/su www +.RE +.fi +.PP +On the host www, any user in the +\fIWEBMASTERS\fR +\fRUser_Alias\fR +(will, wendy, and wim), may run any command as user www (which owns the +web pages) or simply +su(1) +to www. +.nf +.sp +.RS 0n +ALL CDROM = NOPASSWD: /sbin/umount /CDROM,\e + /sbin/mount -o nosuid\e,nodev /dev/cd0a /CDROM +.RE +.fi +.PP +Any user may mount or unmount a CD-ROM on the machines in the CDROM +\fRHost_Alias\fR +(orion, perseus, hercules) without entering a password. +This is a bit tedious for users to type, so it is a prime candidate +for encapsulating in a shell script. +.SH "SECURITY NOTES" +.SS "Limitations of the \(oq!\&\(cq operator" +It is generally not effective to +\(lqsubtract\(rq +commands from +\fBALL\fR +using the +\(oq!\&\(cq +operator. +A user can trivially circumvent this by copying the desired command +to a different name and then executing that. +For example: +.nf +.sp +.RS 0n +bill ALL = ALL, !SU, !SHELLS +.RE +.fi +.PP +Doesn't really prevent +\fBbill\fR +from running the commands listed in +\fISU\fR +or +\fISHELLS\fR +since he can simply copy those commands to a different name, or use +a shell escape from an editor or other program. +Therefore, these kind of restrictions should be considered +advisory at best (and reinforced by policy). +.PP +In general, if a user has sudo +\fBALL\fR +there is nothing to prevent them from creating their own program that gives +them a root shell (or making their own copy of a shell) regardless of any +\(oq!\&\(cq +elements in the user specification. +.SS "Security implications of \fIfast_glob\fR" +If the +\fIfast_glob\fR +option is in use, it is not possible to reliably negate commands where the +path name includes globbing (aka wildcard) characters. +This is because the C library's +fnmatch(3) +function cannot resolve relative paths. +While this is typically only an inconvenience for rules that grant privileges, +it can result in a security issue for rules that subtract or revoke privileges. +.PP +For example, given the following +\fIsudoers\fR +file entry: +.nf +.sp +.RS 0n +john ALL = /usr/bin/passwd [a-zA-Z0-9]*, /usr/bin/chsh [a-zA-Z0-9]*,\e + /usr/bin/chfn [a-zA-Z0-9]*, !/usr/bin/* root +.RE +.fi +.PP +User +\fBjohn\fR +can still run +\fR/usr/bin/passwd root\fR +if +\fIfast_glob\fR +is enabled by changing to +\fI/usr/bin\fR +and running +\fR./passwd root\fR +instead. +.SS "Preventing shell escapes" +Once +\fBsudo\fR +executes a program, that program is free to do whatever +it pleases, including run other programs. +This can be a security issue since it is not uncommon for a program to +allow shell escapes, which lets a user bypass +\fBsudo\fR's +access control and logging. +Common programs that permit shell escapes include shells (obviously), +editors, paginators, mail and terminal programs. +.PP +There are two basic approaches to this problem: +.TP 10n +restrict +Avoid giving users access to commands that allow the user to run +arbitrary commands. +Many editors have a restricted mode where shell +escapes are disabled, though +\fBsudoedit\fR +is a better solution to +running editors via +\fBsudo\fR. +Due to the large number of programs that +offer shell escapes, restricting users to the set of programs that +do not is often unworkable. +.TP 10n +noexec +Many systems that support shared libraries have the ability to +override default library functions by pointing an environment +variable (usually +\fRLD_PRELOAD\fR) +to an alternate shared library. +On such systems, +\fBsudo\fR's +\fInoexec\fR +functionality can be used to prevent a program run by +\fBsudo\fR +from executing any other programs. +Note, however, that this applies only to native dynamically-linked +executables. +Statically-linked executables and foreign executables +running under binary emulation are not affected. +.sp +The +\fInoexec\fR +feature is known to work on SunOS, Solaris, *BSD, +Linux, IRIX, Tru64 UNIX, macOS, HP-UX 11.x and AIX 5.3 and above. +It should be supported on most operating systems that support the +\fRLD_PRELOAD\fR +environment variable. +Check your operating system's manual pages for the dynamic linker +(usually ld.so, ld.so.1, dyld, dld.sl, rld, or loader) to see if +\fRLD_PRELOAD\fR +is supported. +.sp +On Solaris 10 and higher, +\fInoexec\fR +uses Solaris privileges instead of the +\fRLD_PRELOAD\fR +environment variable. +.sp +To enable +\fInoexec\fR +for a command, use the +\fRNOEXEC\fR +tag as documented +in the User Specification section above. +Here is that example again: +.nf +.sp +.RS 10n +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.RE +.fi +.RS 10n +.sp +This allows user +\fBaaron\fR +to run +\fI/usr/bin/more\fR +and +\fI/usr/bin/vi\fR +with +\fInoexec\fR +enabled. +This will prevent those two commands from +executing other commands (such as a shell). +If you are unsure whether or not your system is capable of supporting +\fInoexec\fR +you can always just try it out and check whether shell escapes work when +\fInoexec\fR +is enabled. +.RE +.PP +Note that restricting shell escapes is not a panacea. +Programs running as root are still capable of many potentially hazardous +operations (such as changing or overwriting files) that could lead +to unintended privilege escalation. +In the specific case of an editor, a safer approach is to give the +user permission to run +\fBsudoedit\fR +(see below). +.SS "Secure editing" +The +\fBsudoers\fR +plugin includes +\fBsudoedit\fR +support which allows users to securely edit files with the editor +of their choice. +As +\fBsudoedit\fR +is a built-in command, it must be specified in the +\fIsudoers\fR +file without a leading path. +However, it may take command line arguments just as a normal command does. +Wildcards used in +\fIsudoedit\fR +command line arguments are expected to be path names, so a forward slash +(\(oq/\(cq) +will not be matched by a wildcard. +.PP +Unlike other +\fBsudo\fR +commands, the editor is run with the permissions of the invoking +user and with the environment unmodified. +More information may be found in the description of the +\fB\-e\fR +option in +sudo(@mansectsu@). +.PP +For example, to allow user operator to edit the +\(lqmessage of the day\(rq +file: +.nf +.sp +.RS 6n +operator sudoedit /etc/motd +.RE +.fi +.PP +The operator user then runs +\fBsudoedit\fR +as follows: +.nf +.sp +.RS 6n +$ sudoedit /etc/motd +.RE +.fi +.PP +The editor will run as the operator user, not root, on a temporary copy of +\fI/etc/motd\fR. +After the file has been edited, +\fI/etc/motd\fR +will be updated with the contents of the temporary copy. +.PP +Users should +\fInever\fR +be granted +\fBsudoedit\fR +permission to edit a file that resides in a directory the user +has write access to, either directly or via a wildcard. +If the user has write access to the directory it is possible to +replace the legitimate file with a link to another file, +allowing the editing of arbitrary files. +To prevent this, starting with version 1.8.16, symbolic links will +not be followed in writable directories and +\fBsudoedit\fR +will refuse to edit a file located in a writable directory +unless the +\fIsudoedit_checkdir\fR +option has been disabled or the invoking user is root. +Additionally, in version 1.8.15 and higher, +\fBsudoedit\fR +will refuse to open a symbolic link unless either the +\fIsudoedit_follow\fR +option is enabled or the +\fIsudoedit\fR +command is prefixed with the +\fRFOLLOW\fR +tag in the +\fIsudoers\fR +file. +.SS "Time stamp file checks" +\fBsudoers\fR +will check the ownership of its time stamp directory +(\fI@rundir@/ts\fR +by default) +and ignore the directory's contents if it is not owned by root or +if it is writable by a user other than root. +Older versions of +\fBsudo\fR +stored time stamp files in +\fI/tmp\fR; +this is no longer recommended as it may be possible for a user +to create the time stamp themselves on systems that allow +unprivileged users to change the ownership of files they create. +.PP +While the time stamp directory +\fIshould\fR +be cleared at reboot time, not all systems contain a +\fI/run\fR +or +\fI/var/run\fR +directory. +To avoid potential problems, +\fBsudoers\fR +will ignore time stamp files that date from before the machine booted +on systems where the boot time is available. +.PP +Some systems with graphical desktop environments allow unprivileged +users to change the system clock. +Since +\fBsudoers\fR +relies on the system clock for time stamp validation, it may be +possible on such systems for a user to run +\fBsudo\fR +for longer than +\fItimestamp_timeout\fR +by setting the clock back. +To combat this, +\fBsudoers\fR +uses a monotonic clock (which never moves backwards) for its time stamps +if the system supports it. +.PP +\fBsudoers\fR +will not honor time stamps set far in the future. +Time stamps with a date greater than current_time + 2 * +\fRTIMEOUT\fR +will be ignored and +\fBsudoers\fR +will log and complain. +.PP +If the +\fItimestamp_type\fR +option is set to +\(lqtty\(rq, +the time stamp record includes the device number of the terminal +the user authenticated with. +This provides per-terminal granularity but time stamp records may still +outlive the user's session. +.PP +Unless the +\fItimestamp_type\fR +option is set to +\(lqglobal\(rq, +the time stamp record also includes the session ID of the process +that last authenticated. +This prevents processes in different terminal sessions from using +the same time stamp record. +On systems where a process's start time can be queried, +the start time of the session leader +is recorded in the time stamp record. +If no terminal is present or the +\fItimestamp_type\fR +option is set to +\(lqppid\(rq, +the start time of the parent process is used instead. +In most cases this will prevent a time stamp record from being re-used +without the user entering a password when logging out and back in again. +.SH "DEBUGGING" +Versions 1.8.4 and higher of the +\fBsudoers\fR +plugin support a flexible debugging framework that can help track +down what the plugin is doing internally if there is a problem. +This can be configured in the +sudo.conf(@mansectform@) +file. +.PP +The +\fBsudoers\fR +plugin uses the same debug flag format as the +\fBsudo\fR +front-end: +\fIsubsystem\fR@\fIpriority\fR. +.PP +The priorities used by +\fBsudoers\fR, +in order of decreasing severity, +are: +\fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR +and +\fIdebug\fR. +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +\fInotice\fR +would include debug messages logged at +\fInotice\fR +and higher. +.PP +The following subsystems are used by the +\fBsudoers\fR +plugin: +.TP 10n +\fIalias\fR +\fRUser_Alias\fR, +\fRRunas_Alias\fR, +\fRHost_Alias\fR +and +\fRCmnd_Alias\fR +processing +.TP 10n +\fIall\fR +matches every subsystem +.TP 10n +\fIaudit\fR +BSM and Linux audit code +.TP 10n +\fIauth\fR +user authentication +.TP 10n +\fIdefaults\fR +\fIsudoers\fR +file +\fIDefaults\fR +settings +.TP 10n +\fIenv\fR +environment handling +.TP 10n +\fIldap\fR +LDAP-based sudoers +.TP 10n +\fIlogging\fR +logging support +.TP 10n +\fImatch\fR +matching of users, groups, hosts and netgroups in the +\fIsudoers\fR +file +.TP 10n +\fInetif\fR +network interface handling +.TP 10n +\fInss\fR +network service switch handling in +\fBsudoers\fR +.TP 10n +\fIparser\fR +\fIsudoers\fR +file parsing +.TP 10n +\fIperms\fR +permission setting +.TP 10n +\fIplugin\fR +The equivalent of +\fImain\fR +for the plugin. +.TP 10n +\fIpty\fR +pseudo-tty related code +.TP 10n +\fIrbtree\fR +redblack tree internals +.TP 10n +\fIsssd\fR +SSSD-based sudoers +.TP 10n +\fIutil\fR +utility functions +.PD 0 +.PP +For example: +.nf +.sp +.RS 0n +Debug sudo /var/log/sudo_debug match@info,nss@info +.RE +.fi +.PD +.PP +For more information, see the +sudo.conf(@mansectform@) +manual. +.SH "SEE ALSO" +ssh(1), +su(1), +fnmatch(3), +glob(3), +mktemp(3), +strftime(3), +sudo.conf(@mansectform@), +sudo_plugin(@mansectform@), +sudoers.ldap(@mansectform@), +sudoers_timestamp(@mansectform@), +sudo(@mansectsu@), +visudo(@mansectsu@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "CAVEATS" +The +\fIsudoers\fR +file should +\fBalways\fR +be edited by the +\fBvisudo\fR +command which locks the file and does grammatical checking. +It is +imperative that the +\fIsudoers\fR +file be free of syntax errors since +\fBsudo\fR +will not run with a syntactically incorrect +\fIsudoers\fR +file. +.PP +When using netgroups of machines (as opposed to users), if you +store fully qualified host name in the netgroup (as is usually the +case), you either need to have the machine's host name be fully qualified +as returned by the +\fRhostname\fR +command or use the +\fIfqdn\fR +option in +\fIsudoers\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers.man.in.sed b/doc/sudoers.man.in.sed new file mode 100644 index 0000000..37df7af --- /dev/null +++ b/doc/sudoers.man.in.sed @@ -0,0 +1,116 @@ +s/^\(.TH .*\)/.nr SL @SEMAN@\ +.nr BA @BAMAN@\ +.nr LC @LCMAN@\ +.nr PS @PSMAN@\ +\1/ + +/^On$/N +/^On\nBSD$/,/^.*\.$/ { + /^On\nBSD$/i\ +.if \\n(LC \\{\\ + /\.$/a\ +.\\} +} + +/^\.SS "SELinux_Spec"$/,/^\.SS/ { + /^\.SS / { + /^\.SS "SELinux_Spec"$/i\ +.if \\n(SL \\{\\ + /^\.SS "SELinux_Spec"$/!i\ +.\\} + } +} + +/^\.SS "Solaris_Priv_Spec"$/,/^\.SS/ { + /^\.SS / { + /^\.SS "Solaris_Priv_Spec"$/i\ +.if \\n(PS \\{\\ + /^\.SS "Solaris_Priv_Spec"$/!i\ +.\\} + } +} + +/^Option_Spec ::= / { + s/^.*$/.ie \\n(SL \\{\\\ +.ie \\n(PS Option_Spec ::= (SELinux_Spec | Solaris_Priv_Spec | Date_Spec | Timeout_Spec)\ +.el Option_Spec ::= (SELinux_Spec | Date_Spec | Timeout_Spec)\ +.\\}\ +.el \\{\\\ +.ie \\n(PS Option_Spec ::= (Solaris_Priv_Spec | Date_Spec | Timeout_Spec)\ +.el Option_Spec ::= (Date_Spec | Timeout_Spec)\ +.\\}/ +} + +/^SELinux_Spec ::=/ { + i\ +.if \\n(SL \\{\\ + N + a\ +.\\} +} + +/^Solaris_Priv_Spec ::=/ { + i\ +.if \\n(PS \\{\\ + N + a\ +.\\} +} + +/^SELinux roles.*types,/ { + i\ +.if \\n(SL \\{\\ + a\ +.\\} +} + +/^Solaris privileges sets,/ { + i\ +.if \\n(PS \\{\\ + a\ +.\\} +} + +/^\.TP 18n$/ { + N + /^\.TP 18n\nuse_loginclass$/,/^\.TP 18n/ { + /^\.TP 18n/ { + /^\.TP 18n\nuse_loginclass$/i\ +.if \\n(BA \\{\\ + /^\.TP 18n\nuse_loginclass$/!i\ +.\\} + } + } + /^\.TP 18n\nlimitprivs$/,/^\.TP 18n/ { + /^\.TP 18n/ { + /^\.TP 18n\nlimitprivs$/i\ +.if \\n(PS \\{\\ + /^\.TP 18n\nlimitprivs$/!i\ +.\\} + } + } + /^\.TP 18n\nprivs$/,/^\.TP 18n/ { + /^\.TP 18n/ { + /^\.TP 18n\nprivs$/i\ +.if \\n(PS \\{\\ + /^\.TP 18n\nprivs$/!i\ +.\\} + } + } + /^\.TP 18n\nrole$/,/^\.TP 18n/ { + /^\.TP 18n/ { + /^\.TP 18n\nrole$/i\ +.if \\n(SL \\{\\ + /^\.TP 18n\nrole$/!i\ +.\\} + } + } + /^\.TP 18n\ntype$/,/^\.TP 18n/ { + /^\.TP 18n/ { + /^\.TP 18n\ntype$/i\ +.if \\n(SL \\{\\ + /^\.TP 18n\ntype$/!i\ +.\\} + } + } +} diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in new file mode 100644 index 0000000..2053b5d --- /dev/null +++ b/doc/sudoers.mdoc.in @@ -0,0 +1,5398 @@ +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.nr SL @SEMAN@ +.nr BA @BAMAN@ +.nr LC @LCMAN@ +.nr PS @PSMAN@ +.Dd December 20, 2018 +.Dt SUDOERS @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudoers +.Nd default sudo security policy plugin +.Sh DESCRIPTION +The +.Nm +policy plugin determines a user's +.Nm sudo +privileges. +It is the default +.Nm sudo +policy plugin. +The policy is driven by +the +.Pa @sysconfdir@/sudoers +file or, optionally in LDAP. +The policy format is described in detail in the +.Sx SUDOERS FILE FORMAT +section. +For information on storing +.Nm sudoers +policy information +in LDAP, please see +.Xr sudoers.ldap @mansectform@ . +.Ss Configuring sudo.conf for sudoers +.Nm sudo +consults the +.Xr sudo.conf @mansectform@ +file to determine which policy and I/O logging plugins to load. +If no +.Xr sudo.conf @mansectform@ +file is present, or if it contains no +.Li Plugin +lines, +.Nm +will be used for policy decisions and I/O logging. +To explicitly configure +.Xr sudo.conf @mansectform@ +to use the +.Nm +plugin, the following configuration can be used. +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.Ed +.Pp +Starting with +.Nm sudo +1.8.5, it is possible to specify optional arguments to the +.Nm +plugin in the +.Xr sudo.conf @mansectform@ +file. +These arguments, if present, should be listed after the path to the plugin +(i.e., after +.Pa sudoers.so ) . +Multiple arguments may be specified, separated by white space. +For example: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so sudoers_mode=0400 +.Ed +.Pp +The following plugin arguments are supported: +.Bl -tag -width 8n +.It ldap_conf=pathname +The +.Em ldap_conf +argument can be used to override the default path to the +.Pa ldap.conf +file. +.It ldap_secret=pathname +The +.Em ldap_secret +argument can be used to override the default path to the +.Pa ldap.secret +file. +.It sudoers_file=pathname +The +.Em sudoers_file +argument can be used to override the default path to the +.Em sudoers +file. +.It sudoers_uid=uid +The +.Em sudoers_uid +argument can be used to override the default owner of the sudoers file. +It should be specified as a numeric user ID. +.It sudoers_gid=gid +The +.Em sudoers_gid +argument can be used to override the default group of the sudoers file. +It must be specified as a numeric group ID (not a group name). +.It sudoers_mode=mode +The +.Em sudoers_mode +argument can be used to override the default file mode for the sudoers file. +It should be specified as an octal value. +.El +.Pp +For more information on configuring +.Xr sudo.conf @mansectform@ , +please refer to its manual. +.Ss User Authentication +The +.Nm sudoers +security policy requires that most users authenticate +themselves before they can use +.Nm sudo . +A password is not required +if the invoking user is root, if the target user is the same as the +invoking user, or if the policy has disabled authentication for the +user or command. +Unlike +.Xr su 1 , +when +.Nm sudoers +requires +authentication, it validates the invoking user's credentials, not +the target user's (or root's) credentials. +This can be changed via +the +.Em rootpw , +.Em targetpw +and +.Em runaspw +flags, described later. +.Pp +If a user who is not listed in the policy tries to run a command +via +.Nm sudo , +mail is sent to the proper authorities. +The address +used for such mail is configurable via the +.Em mailto +Defaults entry +(described later) and defaults to +.Li @mailto@ . +.Pp +Note that no mail will be sent if an unauthorized user tries to run +.Nm sudo +with the +.Fl l +or +.Fl v +option unless there is an authentication error and +either the +.Em mail_always +or +.Em mail_badpass +flags are enabled. +This allows users to +determine for themselves whether or not they are allowed to use +.Nm sudo . +All attempts to run +.Nm sudo +(successful or not) +will be logged, regardless of whether or not mail is sent. +.Pp +If +.Nm sudo +is run by root and the +.Ev SUDO_USER +environment variable +is set, the +.Nm sudoers +policy will use this value to determine who +the actual user is. +This can be used by a user to log commands +through sudo even when a root shell has been invoked. +It also +allows the +.Fl e +option to remain useful even when invoked via a +sudo-run script or program. +Note, however, that the +.Em sudoers +file lookup is still done for root, not the user specified by +.Ev SUDO_USER . +.Pp +.Nm sudoers +uses per-user time stamp files for credential caching. +Once a user has been authenticated, a record is written +containing the user ID that was used to authenticate, the +terminal session ID, the start time of the session leader +(or parent process) and a time stamp +(using a monotonic clock if one is available). +The user may then use +.Nm sudo +without a password for a short period of time +.Po +.Li @timeout@ +minutes unless overridden by the +.Em timestamp_timeout +option +.Pc . +By default, +.Nm sudoers +uses a separate record for each terminal, which means that +a user's login sessions are authenticated separately. +The +.Em timestamp_type +option can be used to select the type of time stamp record +.Nm sudoers +will use. +.Ss Logging +.Nm sudoers +can log both successful and unsuccessful attempts (as well +as errors) to +.Xr syslog 3 , +a log file, or both. +By default, +.Nm sudoers +will log via +.Xr syslog 3 +but this is changeable via the +.Em syslog +and +.Em logfile +Defaults settings. +See +.Sx "LOG FORMAT" +for a description of the log file format. +.Pp +.Nm sudoers +is also capable of running a command in a pseudo-tty and logging all +input and/or output. +The standard input, standard output and standard error can be logged +even when not associated with a terminal. +I/O logging is not on by default but can be enabled using +the +.Em log_input +and +.Em log_output +options as well as the +.Li LOG_INPUT +and +.Li LOG_OUTPUT +command tags. +See +.Sx "I/O LOG FILES" +for details on how I/O log files are stored. +.Ss Command environment +Since environment variables can influence program behavior, +.Nm sudoers +provides a means to restrict which variables from the user's +environment are inherited by the command to be run. +There are two +distinct ways +.Nm sudoers +can deal with environment variables. +.Pp +By default, the +.Em env_reset +option is enabled. +This causes commands +to be executed with a new, minimal environment. +On AIX (and Linux +systems without PAM), the environment is initialized with the +contents of the +.Pa /etc/environment +file. +.if \n(LC \{\ +On +.Bx +systems, if the +.Em use_loginclass +option is enabled, the environment is initialized +based on the +.Em path +and +.Em setenv +settings in +.Pa /etc/login.conf . +.\} +The new environment contains the +.Ev TERM , +.Ev PATH , +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev LOGNAME , +.Ev USER +and +.Ev SUDO_* +variables +in addition to variables from the invoking process permitted by the +.Em env_check +and +.Em env_keep +options. +This is effectively a whitelist +for environment variables. +The environment variables +.Ev LOGNAME +and +.Ev USER +are treated specially. +If one of them is preserved (or removed) from user's environment, the other +will be as well. +If +.Ev LOGNAME +and +.Ev USER +are to be preserved but only one of them is present in the user's environment, +the other will be set to the same value. +This avoids an inconsistent environment where one of the variables +describing the user name is set to the invoking user and one is +set to the target user. +.Li () +are removed unless both the name and value parts are matched by +.Em env_keep +or +.Em env_check , +as they may be interpreted as functions by the +.Sy bash +shell. +Prior to version 1.8.11, such variables were always removed. +.Pp +If, however, the +.Em env_reset +option is disabled, any variables not +explicitly denied by the +.Em env_check +and +.Em env_delete +options are +inherited from the invoking process. +In this case, +.Em env_check +and +.Em env_delete +behave like a blacklist. +Prior to version 1.8.21, environment variables with a value beginning with +.Li () +were always removed. +Beginning with version 1.8.21, a pattern in +.Em env_delete +is used to match +.Sy bash +shell functions instead. +Since it is not possible +to blacklist all potentially dangerous environment variables, use +of the default +.Em env_reset +behavior is encouraged. +.Pp +Environment variables specified by +.Em env_check , +.Em env_delete , +or +.Em env_keep +may include one or more +.Ql * +characters which will match zero or more characters. +No other wildcard characters are supported. +.Pp +By default, environment variables are matched by name. +However, if the pattern includes an equal sign +.Pq Ql =\& , +both the variables name and value must match. +For example, a +.Sy bash +shell function could be matched as follows: +.Bd -literal -offset 4n +env_keep += "BASH_FUNC_my_func%%=()*" +.Ed +.Pp +Without the +.Dq Li =()* +suffix, this would not match, as +.Sy bash +shell functions are not preserved by default. +.Pp +The complete list of environment variables that +.Nm sudo +allows or denies is contained in the output of +.Dq Li sudo -V +when run as root. +Please note that this list varies based on the operating system +.Nm sudo +is running on. +.Pp +On systems that support PAM where the +.Sy pam_env +module is enabled for +.Nm sudo , +variables in the PAM environment may be merged in to the environment. +If a variable in the PAM environment is already present in the +user's environment, the value will only be overridden if the variable +was not preserved by +.Nm . +When +.Em env_reset +is enabled, variables preserved from the invoking user's environment +by the +.Em env_keep +list take precedence over those in the PAM environment. +When +.Em env_reset +is disabled, variables present the invoking user's environment +take precedence over those in the PAM environment unless they +match a pattern in the +.Em env_delete +list. +.Pp +Note that the dynamic linker on most operating systems will remove +variables that can control dynamic linking from the environment of +setuid executables, including +.Nm sudo . +Depending on the operating +system this may include +.Ev _RLD* , +.Ev DYLD_* , +.Ev LD_* , +.Ev LDR_* , +.Ev LIBPATH , +.Ev SHLIB_PATH , +and others. +These type of variables are +removed from the environment before +.Nm sudo +even begins execution +and, as such, it is not possible for +.Nm sudo +to preserve them. +.Pp +As a special case, if +.Nm sudo Ns 's +.Fl i +option (initial login) is +specified, +.Nm sudoers +will initialize the environment regardless +of the value of +.Em env_reset . +The +.Ev DISPLAY , +.Ev PATH +and +.Ev TERM +variables remain unchanged; +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev USER , +and +.Ev LOGNAME +are set based on the target user. +On AIX (and Linux +systems without PAM), the contents of +.Pa /etc/environment +are also +included. +.if \n(LC \{\ +On +.Bx +systems, if the +.Em use_loginclass +flag is +enabled, the +.Em path +and +.Em setenv +variables in +.Pa /etc/login.conf +are also applied. +.\} +All other environment variables are removed unless permitted by +.Em env_keep +or +.Em env_check , +described above. +.Pp +Finally, the +.Em restricted_env_file +and +.Em env_file +files are applied, if present. +The variables in +.Em restricted_env_file +are applied first and are subject to the same restrictions as the +invoking user's environment, as detailed above. +The variables in +.Em env_file +are applied last and are not subject to these restrictions. +In both cases, variables present in the files will only be set to +their specified values if they would not conflict with an existing +environment variable. +.Sh SUDOERS FILE FORMAT +The +.Em sudoers +file is composed of two types of entries: aliases +(basically variables) and user specifications (which specify who +may run what). +.Pp +When multiple entries match for a user, they are applied in order. +Where there are multiple matches, the last match is used (which is +not necessarily the most specific match). +.Pp +The +.Em sudoers +file grammar will be described below in Extended Backus-Naur +Form (EBNF). +Don't despair if you are unfamiliar with EBNF; it is fairly simple, +and the definitions below are annotated. +.Ss Quick guide to EBNF +EBNF is a concise and exact way of describing the grammar of a language. +Each EBNF definition is made up of +.Em production rules . +E.g., +.Pp +.Li symbol ::= definition | alternate1 | alternate2 ... +.Pp +Each +.Em production rule +references others and thus makes up a +grammar for the language. +EBNF also contains the following +operators, which many readers will recognize from regular +expressions. +Do not, however, confuse them with +.Dq wildcard +characters, which have different meanings. +.Bl -tag -width 4n +.It Li \&? +Means that the preceding symbol (or group of symbols) is optional. +That is, it may appear once or not at all. +.It Li * +Means that the preceding symbol (or group of symbols) may appear +zero or more times. +.It Li + +Means that the preceding symbol (or group of symbols) may appear +one or more times. +.El +.Pp +Parentheses may be used to group symbols together. +For clarity, +we will use single quotes +.Pq '' +to designate what is a verbatim character string (as opposed to a symbol name). +.Ss Aliases +There are four kinds of aliases: +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias +and +.Li Cmnd_Alias . +.Bd -literal +Alias ::= 'User_Alias' User_Alias_Spec (':' User_Alias_Spec)* | + 'Runas_Alias' Runas_Alias_Spec (':' Runas_Alias_Spec)* | + 'Host_Alias' Host_Alias_Spec (':' Host_Alias_Spec)* | + 'Cmnd_Alias' Cmnd_Alias_Spec (':' Cmnd_Alias_Spec)* + +User_Alias ::= NAME + +User_Alias_Spec ::= User_Alias '=' User_List + +Runas_Alias ::= NAME + +Runas_Alias_Spec ::= Runas_Alias '=' Runas_List + +Host_Alias ::= NAME + +Host_Alias_Spec ::= Host_Alias '=' Host_List + +Cmnd_Alias ::= NAME + +Cmnd_Alias_Spec ::= Cmnd_Alias '=' Cmnd_List + +NAME ::= [A-Z]([A-Z][0-9]_)* +.Ed +.Pp +Each +.Em alias +definition is of the form +.Bd -literal +Alias_Type NAME = item1, item2, ... +.Ed +.Pp +where +.Em Alias_Type +is one of +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias , +or +.Li Cmnd_Alias . +A +.Li NAME +is a string of uppercase letters, numbers, +and underscore characters +.Pq Ql _ . +A +.Li NAME +.Sy must +start with an +uppercase letter. +It is possible to put several alias definitions +of the same type on a single line, joined by a colon +.Pq Ql :\& . +E.g., +.Bd -literal +Alias_Type NAME = item1, item2, item3 : NAME = item4, item5 +.Ed +.Pp +It is a syntax error to redefine an existing +.Em alias . +It is possible to use the same name for +.Em aliases +of different types, but this is not recommended. +.Pp +The definitions of what constitutes a valid +.Em alias +member follow. +.Bd -literal +User_List ::= User | + User ',' User_List + +User ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* +netgroup | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* User_Alias +.Ed +.Pp +A +.Li User_List +is made up of one or more user names, user IDs +(prefixed with +.Ql # ) , +system group names and IDs (prefixed with +.Ql % +and +.Ql %# +respectively), netgroups (prefixed with +.Ql + ) , +non-Unix group names and IDs (prefixed with +.Ql %: +and +.Ql %:# +respectively) and +.Li User_Alias Ns es. +Each list item may be prefixed with zero or more +.Ql \&! +operators. +An odd number of +.Ql \&! +operators negate the value of +the item; an even number just cancel each other out. +User netgroups are matched using the user and domain members only; +the host member is not used when matching. +.Pp +A +.Li user name , +.Li uid , +.Li group , +.Li gid , +.Li netgroup , +.Li nonunix_group +or +.Li nonunix_gid +may be enclosed in double quotes to avoid the +need for escaping special characters. +Alternately, special characters +may be specified in escaped hex mode, e.g., \ex20 for space. +When +using double quotes, any prefix characters must be included inside +the quotes. +.Pp +The actual +.Li nonunix_group +and +.Li nonunix_gid +syntax depends on +the underlying group provider plugin. +For instance, the QAS AD plugin supports the following formats: +.Bl -bullet -width 1n +.It +Group in the same domain: "%:Group Name" +.It +Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" +.It +Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" +.El +.Pp +See +.Sx "GROUP PROVIDER PLUGINS" +for more information. +.Pp +Note that quotes around group names are optional. +Unquoted strings must use a backslash +.Pq Ql \e +to escape spaces and special characters. +See +.Sx Other special characters and reserved words +for a list of +characters that need to be escaped. +.Bd -literal +Runas_List ::= Runas_Member | + Runas_Member ',' Runas_List + +Runas_Member ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* +netgroup | + '!'* Runas_Alias +.Ed +.Pp +A +.Li Runas_List +is similar to a +.Li User_List +except that instead +of +.Li User_Alias Ns es +it can contain +.Li Runas_Alias Ns es . +Note that +user names and groups are matched as strings. +In other words, two +users (groups) with the same uid (gid) are considered to be distinct. +If you wish to match all user names with the same uid (e.g., +root and toor), you can use a uid instead (#0 in the example given). +.Bd -literal +Host_List ::= Host | + Host ',' Host_List + +Host ::= '!'* host name | + '!'* ip_addr | + '!'* network(/netmask)? | + '!'* +netgroup | + '!'* Host_Alias +.Ed +.Pp +A +.Li Host_List +is made up of one or more host names, IP addresses, +network numbers, netgroups (prefixed with +.Ql + ) +and other aliases. +Again, the value of an item may be negated with the +.Ql \&! +operator. +Host netgroups are matched using the host (both qualified and unqualified) +and domain members only; the user member is not used when matching. +If you specify a network number without a netmask, +.Nm sudo +will query each of the local host's network interfaces and, +if the network number corresponds to one of the hosts's network +interfaces, will use the netmask of that interface. +The netmask may be specified either in standard IP address notation +(e.g., 255.255.255.0 or ffff:ffff:ffff:ffff::), +or CIDR notation (number of bits, e.g., 24 or 64). +A host name may include shell-style wildcards (see the +.Sx Wildcards +section below), +but unless the +.Li host name +command on your machine returns the fully +qualified host name, you'll need to use the +.Em fqdn +option for wildcards to be useful. +Note that +.Nm sudo +only inspects actual network interfaces; this means that IP address +127.0.0.1 (localhost) will never match. +Also, the host name +.Dq localhost +will only match if that is the actual host name, which is usually +only the case for non-networked systems. +.Bd -literal +digest ::= [A-Fa-f0-9]+ | + [[A-Za-z0-9\+/=]+ + +Digest_Spec ::= "sha224" ':' digest | + "sha256" ':' digest | + "sha384" ':' digest | + "sha512" ':' digest + +Cmnd_List ::= Cmnd | + Cmnd ',' Cmnd_List + +command name ::= file name | + file name args | + file name '""' + +Cmnd ::= Digest_Spec? '!'* command name | + '!'* directory | + '!'* "sudoedit" | + '!'* Cmnd_Alias +.Ed +.Pp +A +.Li Cmnd_List +is a list of one or more command names, directories, and other aliases. +A command name is a fully qualified file name which may include +shell-style wildcards (see the +.Sx Wildcards +section below). +A simple file name allows the user to run the command with any +arguments he/she wishes. +However, you may also specify command line arguments (including +wildcards). +Alternately, you can specify +.Li \&"" +to indicate that the command +may only be run +.Sy without +command line arguments. +A directory is a +fully qualified path name ending in a +.Ql / . +When you specify a directory in a +.Li Cmnd_List , +the user will be able to run any file within that directory +(but not in any sub-directories therein). +.Pp +If a +.Li Cmnd +has associated command line arguments, then the arguments +in the +.Li Cmnd +must match exactly those given by the user on the command line +(or match the wildcards if there are any). +Note that the following characters must be escaped with a +.Ql \e +if they are used in command arguments: +.Ql ,\& , +.Ql :\& , +.Ql =\& , +.Ql \e . +The built-in command +.Dq Li sudoedit +is used to permit a user to run +.Nm sudo +with the +.Fl e +option (or as +.Nm sudoedit ) . +It may take command line arguments just as a normal command does. +Note that +.Dq Li sudoedit +is a command built into +.Nm sudo +itself and must be specified in the +.Em sudoers +file without a leading path. +.Pp +If a +.Li command name +is prefixed with a +.Li Digest_Spec , +the command will only match successfully if it can be verified +using the specified SHA-2 digest. +The following digest formats are supported: sha224, sha256, sha384 and sha512. +The string may be specified in either hex or base64 format +(base64 is more compact). +There are several utilities capable of generating SHA-2 digests in hex +format such as openssl, shasum, sha224sum, sha256sum, sha384sum, sha512sum. +.Pp +For example, using openssl: +.Bd -literal +$ openssl dgst -sha224 /bin/ls +SHA224(/bin/ls)= 118187da8364d490b4a7debbf483004e8f3e053ec954309de2c41a25 +.Ed +.Pp +It is also possible to use openssl to generate base64 output: +.Bd -literal +$ openssl dgst -binary -sha224 /bin/ls | openssl base64 +EYGH2oNk1JC0p9679IMATo8+BT7JVDCd4sQaJQ== +.Ed +.Pp +Warning, if the user has write access to the command itself (directly or via a +.Nm sudo +command), it may be possible for the user to replace the command after the +digest check has been performed but before the command is executed. +A similar race condition exists on systems that lack the +.Xr fexecve 2 +system call when the directory in which the command is located +is writable by the user. +See the description of the +.Em fdexec +setting for more information on how +.Nm sudo +executes commands that have an associated digest. +.Pp +Command digests are only supported by version 1.8.7 or higher. +.Ss Defaults +Certain configuration options may be changed from their default +values at run-time via one or more +.Li Default_Entry +lines. +These may affect all users on any host, all users on a specific host, a +specific user, a specific command, or commands being run as a specific user. +Note that per-command entries may not include command line arguments. +If you need to specify arguments, define a +.Li Cmnd_Alias +and reference +that instead. +.Bd -literal +Default_Type ::= 'Defaults' | + 'Defaults' '@' Host_List | + 'Defaults' ':' User_List | + 'Defaults' '!' Cmnd_List | + 'Defaults' '>' Runas_List + +Default_Entry ::= Default_Type Parameter_List + +Parameter_List ::= Parameter | + Parameter ',' Parameter_List + +Parameter ::= Parameter '=' Value | + Parameter '+=' Value | + Parameter '-=' Value | + '!'* Parameter +.Ed +.Pp +Parameters may be +.Sy flags , +.Sy integer +values, +.Sy strings , +or +.Sy lists . +Flags are implicitly boolean and can be turned off via the +.Ql \&! +operator. +Some integer, string and list parameters may also be +used in a boolean context to disable them. +Values may be enclosed +in double quotes +.Pq \&"" +when they contain multiple words. +Special characters may be escaped with a backslash +.Pq Ql \e . +.Pp +Lists have two additional assignment operators, +.Li += +and +.Li -= . +These operators are used to add to and delete from a list respectively. +It is not an error to use the +.Li -= +operator to remove an element +that does not exist in a list. +.Pp +Defaults entries are parsed in the following order: generic, host, +user and runas Defaults first, then command defaults. +If there are multiple Defaults settings of the same type, the last +matching setting is used. +The following Defaults settings are parsed before all others since +they may affect subsequent entries: +.Em fqdn , +.Em group_plugin , +.Em runas_default , +.Em sudoers_locale . +.Pp +See +.Sx SUDOERS OPTIONS +for a list of supported Defaults parameters. +.Ss User specification +.Bd -literal +User_Spec ::= User_List Host_List '=' Cmnd_Spec_List \e + (':' Host_List '=' Cmnd_Spec_List)* + +Cmnd_Spec_List ::= Cmnd_Spec | + Cmnd_Spec ',' Cmnd_Spec_List + +Cmnd_Spec ::= Runas_Spec? Option_Spec* Tag_Spec* Cmnd + +Runas_Spec ::= '(' Runas_List? (':' Runas_List)? ')' + +.ie \n(SL \{\ +.ie \n(PS Option_Spec ::= (SELinux_Spec | Solaris_Priv_Spec | Date_Spec | Timeout_Spec) +.el Option_Spec ::= (SELinux_Spec | Date_Spec | Timeout_Spec) +.\} +.el \{\ +.ie \n(PS Option_Spec ::= (Solaris_Priv_Spec | Date_Spec | Timeout_Spec) +.el Option_Spec ::= (Date_Spec | Timeout_Spec) +.\} + +.if \n(SL \{\ +SELinux_Spec ::= ('ROLE=role' | 'TYPE=type') + +.\} +.if \n(PS \{\ +Solaris_Priv_Spec ::= ('PRIVS=privset' | 'LIMITPRIVS=privset') + +.\} +Date_Spec ::= ('NOTBEFORE=timestamp' | 'NOTAFTER=timestamp') + +Timeout_Spec ::= 'TIMEOUT=timeout' + +Tag_Spec ::= ('EXEC:' | 'NOEXEC:' | 'FOLLOW:' | 'NOFOLLOW' | + 'LOG_INPUT:' | 'NOLOG_INPUT:' | 'LOG_OUTPUT:' | + 'NOLOG_OUTPUT:' | 'MAIL:' | 'NOMAIL:' | 'PASSWD:' | + 'NOPASSWD:' | 'SETENV:' | 'NOSETENV:') +.Ed +.Pp +A +.Sy user specification +determines which commands a user may run +(and as what user) on specified hosts. +By default, commands are +run as +.Sy root , +but this can be changed on a per-command basis. +.Pp +The basic structure of a user specification is +.Dq who where = (as_whom) what . +Let's break that down into its constituent parts: +.Ss Runas_Spec +A +.Li Runas_Spec +determines the user and/or the group that a command +may be run as. +A fully-specified +.Li Runas_Spec +consists of two +.Li Runas_List Ns s +(as defined above) separated by a colon +.Pq Ql :\& +and enclosed in a set of parentheses. +The first +.Li Runas_List +indicates +which users the command may be run as via +.Nm sudo Ns 's +.Fl u +option. +The second defines a list of groups that can be specified via +.Nm sudo Ns 's +.Fl g +option in addition to any of the target user's groups. +If both +.Li Runas_List Ns s +are specified, the command may be run with any combination of users +and groups listed in their respective +.Li Runas_List Ns s. +If only the first is specified, the command may be run as any user +in the list but no +.Fl g +option +may be specified. +If the first +.Li Runas_List +is empty but the +second is specified, the command may be run as the invoking user +with the group set to any listed in the +.Li Runas_List . +If both +.Li Runas_List Ns s +are empty, the command may only be run as the invoking user. +If no +.Li Runas_Spec +is specified the command may be run as +.Sy root +and +no group may be specified. +.Pp +A +.Li Runas_Spec +sets the default for the commands that follow it. +What this means is that for the entry: +.Bd -literal +dgb boulder = (operator) /bin/ls, /bin/kill, /usr/bin/lprm +.Ed +.Pp +The user +.Sy dgb +may run +.Pa /bin/ls , +.Pa /bin/kill , +and +.Pa /usr/bin/lprm +on the host +.No boulder Ns \(em Ns but +only as +.Sy operator . +E.g., +.Bd -literal +$ sudo -u operator /bin/ls +.Ed +.Pp +It is also possible to override a +.Li Runas_Spec +later on in an entry. +If we modify the entry like so: +.Bd -literal +dgb boulder = (operator) /bin/ls, (root) /bin/kill, /usr/bin/lprm +.Ed +.Pp +Then user +.Sy dgb +is now allowed to run +.Pa /bin/ls +as +.Sy operator , +but +.Pa /bin/kill +and +.Pa /usr/bin/lprm +as +.Sy root . +.Pp +We can extend this to allow +.Sy dgb +to run +.Li /bin/ls +with either +the user or group set to +.Sy operator : +.Bd -literal +dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\e + /usr/bin/lprm +.Ed +.Pp +Note that while the group portion of the +.Li Runas_Spec +permits the +user to run as command with that group, it does not force the user +to do so. +If no group is specified on the command line, the command +will run with the group listed in the target user's password database +entry. +The following would all be permitted by the sudoers entry above: +.Bd -literal +$ sudo -u operator /bin/ls +$ sudo -u operator -g operator /bin/ls +$ sudo -g operator /bin/ls +.Ed +.Pp +In the following example, user +.Sy tcm +may run commands that access +a modem device file with the dialer group. +.Bd -literal +tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\e + /usr/local/bin/minicom +.Ed +.Pp +Note that in this example only the group will be set, the command +still runs as user +.Sy tcm . +E.g.\& +.Bd -literal +$ sudo -g dialer /usr/bin/cu +.Ed +.Pp +Multiple users and groups may be present in a +.Li Runas_Spec , +in which case the user may select any combination of users and groups via the +.Fl u +and +.Fl g +options. +In this example: +.Bd -literal +alan ALL = (root, bin : operator, system) ALL +.Ed +.Pp +user +.Sy alan +may run any command as either user root or bin, +optionally setting the group to operator or system. +.Ss Option_Spec +A +.Li Cmnd +may have zero or more options associated with it. +Options may consist of +.if \n(SL \{\ +SELinux roles and/or types, +.\} +.if \n(PS \{\ +Solaris privileges sets, +.\} +start and/or end dates and command timeouts. +Once an option is set for a +.Li Cmnd , +subsequent +.Li Cmnd Ns s +in the +.Li Cmnd_Spec_List , +inherit that option unless it is overridden by another option. +.if \n(SL \{\ +.Ss SELinux_Spec +On systems with SELinux support, +.Em sudoers +file entries may optionally have an SELinux role and/or type associated +with a command. +If a role or +type is specified with the command it will override any default values +specified in +.Em sudoers . +A role or type specified on the command line, +however, will supersede the values in +.Em sudoers . +.\} +.if \n(PS \{\ +.Ss Solaris_Priv_Spec +On Solaris systems, +.Em sudoers +file entries may optionally specify Solaris privilege set and/or limit +privilege set associated with a command. +If privileges or limit privileges are specified with the command +it will override any default values specified in +.Em sudoers . +.Pp +A privilege set is a comma-separated list of privilege names. +The +.Xr ppriv 1 +command can be used to list all privileges known to the system. +For example: +.Bd -literal +$ ppriv -l +.Ed +.Pp +In addition, there are several +.Dq special +privilege strings: +.Bl -tag -width 8n +.It none +the empty set +.It all +the set of all privileges +.It zone +the set of all privileges available in the current zone +.It basic +the default set of privileges normal users are granted at login time +.El +.Pp +Privileges can be excluded from a set by prefixing the privilege +name with either an +.Ql \&! +or +.Ql \- +character. +.\} +.Ss Date_Spec +.Nm sudoers +rules can be specified with a start and end date via the +.Li NOTBEFORE +and +.Li NOTAFTER +settings. +The time stamp must be specified in +.Em Generalized Time +as defined by RFC 4517. +The format is effectively +.Li yyyymmddHHMMSSZ +where the minutes and seconds are optional. +The +.Ql Z +suffix indicates that the time stamp is in Coordinated Universal Time (UTC). +It is also possible to specify a timezone offset from UTC in hours +and minutes instead of a +.Ql Z . +For example, +.Ql -0500 +would correspond to Eastern Standard time in the US. +As an extension, if no +.Ql Z +or timezone offset is specified, local time will be used. +.Pp +The following are all valid time stamps: +.Bd -literal -offset 4n +20170214083000Z +2017021408Z +20160315220000-0500 +20151201235900 +.Ed +.Ss Timeout_Spec +A command may have a timeout associated with it. +If the timeout expires before the command has exited, the +command will be terminated. +The timeout may be specified in combinations of days, hours, +minutes and seconds with a single-letter case-insensitive suffix +that indicates the unit of time. +For example, a timeout of 7 days, 8 hours, 30 minutes and +10 seconds would be written as +.Li 7d8h30m10s . +If a number is specified without a unit, seconds are assumed. +Any of the days, minutes, hours or seconds may be omitted. +The order must be from largest to smallest unit and a unit +may not be specified more than once. +.Pp +The following are all +.Em valid +timeout values: +.Li 7d8h30m10s , +.Li 14d , +.Li 8h30m , +.Li 600s , +.Li 3600 . +The following are +.Em invalid +timeout values: +.Li 12m2w1d , +.Li 30s10m4h , +.Li 1d2d3h . +.Pp +This option is only supported by version 1.8.20 or higher. +.Ss Tag_Spec +A command may have zero or more tags associated with it. +The following tag values are supported: +.Li EXEC , +.Li NOEXEC , +.Li FOLLOW , +.Li NOFOLLOW , +.Li LOG_INPUT , +.Li NOLOG_INPUT , +.Li LOG_OUTPUT , +.Li NOLOG_OUTPUT , +.Li MAIL , +.Li NOMAIL , +.Li PASSWD , +.Li NOPASSWD , +.Li SETENV , +and +.Li NOSETENV . +Once a tag is set on a +.Li Cmnd , +subsequent +.Li Cmnd Ns s +in the +.Li Cmnd_Spec_List , +inherit the tag unless it is overridden by the opposite tag (in other words, +.Li PASSWD +overrides +.Li NOPASSWD +and +.Li NOEXEC +overrides +.Li EXEC ) . +.Bl -hang -width 0n +.It Em EXEC No and Em NOEXEC +.sp +If +.Nm sudo +has been compiled with +.Em noexec +support and the underlying operating system supports it, the +.Li NOEXEC +tag can be used to prevent a dynamically-linked executable from +running further commands itself. +.Pp +In the following example, user +.Sy aaron +may run +.Pa /usr/bin/more +and +.Pa /usr/bin/vi +but shell escapes will be disabled. +.Bd -literal +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.Ed +.Pp +See the +.Sx Preventing shell escapes +section below for more details on how +.Li NOEXEC +works and whether or not it will work on your system. +.It Em FOLLOW No and Em NOFOLLOW +Starting with version 1.8.15, +.Nm sudoedit +will not open a file that is a symbolic link unless the +.Em sudoedit_follow +option is enabled. +The +.Em FOLLOW +and +.Em NOFOLLOW +tags override the value of +.Em sudoedit_follow +and can be used to permit (or deny) the editing of symbolic links +on a per-command basis. +These tags are only effective for the +.Em sudoedit +command and are ignored for all other commands. +.It Em LOG_INPUT No and Em NOLOG_INPUT +.sp +These tags override the value of the +.Em log_input +option on a per-command basis. +For more information, see the description of +.Em log_input +in the +.Sx SUDOERS OPTIONS +section below. +.It Em LOG_OUTPUT No and Em NOLOG_OUTPUT +.sp +These tags override the value of the +.Em log_output +option on a per-command basis. +For more information, see the description of +.Em log_output +in the +.Sx SUDOERS OPTIONS +section below. +.It Em MAIL No and Em NOMAIL +.sp +These tags provide fine-grained control over whether +mail will be sent when a user runs a command by +overriding the value of the +.Em mail_all_cmnds +option on a per-command basis. +They have no effect when +.Nm sudo +is run with the +.Fl l +or +.Fl v +options. +A +.Em NOMAIL +tag will also override the +.Em mail_always +and +.Em mail_no_perms +options. +For more information, see the descriptions of +.Em mail_all_cmnds , +.Em mail_always , +and +.Em mail_no_perms +in the +.Sx SUDOERS OPTIONS +section below. +.It Em PASSWD No and Em NOPASSWD +.sp +By default, +.Nm sudo +requires that a user authenticate him or herself +before running a command. +This behavior can be modified via the +.Li NOPASSWD +tag. +Like a +.Li Runas_Spec , +the +.Li NOPASSWD +tag sets +a default for the commands that follow it in the +.Li Cmnd_Spec_List . +Conversely, the +.Li PASSWD +tag can be used to reverse things. +For example: +.Bd -literal +ray rushmore = NOPASSWD: /bin/kill, /bin/ls, /usr/bin/lprm +.Ed +.Pp +would allow the user +.Sy ray +to run +.Pa /bin/kill , +.Pa /bin/ls , +and +.Pa /usr/bin/lprm +as +.Sy root +on the machine rushmore without authenticating himself. +If we only want +.Sy ray +to be able to +run +.Pa /bin/kill +without a password the entry would be: +.Bd -literal +ray rushmore = NOPASSWD: /bin/kill, PASSWD: /bin/ls, /usr/bin/lprm +.Ed +.Pp +Note, however, that the +.Li PASSWD +tag has no effect on users who are in the group specified by the +.Em exempt_group +option. +.Pp +By default, if the +.Li NOPASSWD +tag is applied to any of the entries for a user on the current host, +he or she will be able to run +.Dq Li sudo -l +without a password. +Additionally, a user may only run +.Dq Li sudo -v +without a password if the +.Li NOPASSWD +tag is present for all a user's entries that pertain to the current host. +This behavior may be overridden via the +.Em verifypw +and +.Em listpw +options. +.It Em SETENV No and Em NOSETENV +.sp +These tags override the value of the +.Em setenv +option on a per-command basis. +Note that if +.Li SETENV +has been set for a command, the user may disable the +.Em env_reset +option from the command line via the +.Fl E +option. +Additionally, environment variables set on the command +line are not subject to the restrictions imposed by +.Em env_check , +.Em env_delete , +or +.Em env_keep . +As such, only trusted users should be allowed to set variables in this manner. +If the command matched is +.Sy ALL , +the +.Li SETENV +tag is implied for that command; this default may be overridden by use of the +.Li NOSETENV +tag. +.El +.Ss Wildcards +.Nm sudo +allows shell-style +.Em wildcards +(aka meta or glob characters) +to be used in host names, path names and command line arguments in the +.Em sudoers +file. +Wildcard matching is done via the +.Xr glob 3 +and +.Xr fnmatch 3 +functions as specified by +.St -p1003.1 . +.Bl -tag -width 8n +.It Li * +Matches any set of zero or more characters (including white space). +.It Li \&? +Matches any single character (including white space). +.It Li [...] +Matches any character in the specified range. +.It Li [!...] +Matches any character +.Em not +in the specified range. +.It Li \ex +For any character +.Sq x , +evaluates to +.Sq x . +This is used to escape special characters such as: +.Ql * , +.Ql \&? , +.Ql [\& , +and +.Ql ]\& . +.El +.Pp +.Bf -symbolic +Note that these are not regular expressions. +.Ef +Unlike a regular expression there is no way to match one or more +characters within a range. +.Pp +Character classes may be used if your system's +.Xr glob 3 +and +.Xr fnmatch 3 +functions support them. +However, because the +.Ql :\& +character has special meaning in +.Em sudoers , +it must be +escaped. +For example: +.Bd -literal -offset 4n +/bin/ls [[\e:\&alpha\e:\&]]* +.Ed +.Pp +Would match any file name beginning with a letter. +.Pp +Note that a forward slash +.Pq Ql / +will +.Em not +be matched by +wildcards used in the file name portion of the command. +This is to make a path like: +.Bd -literal -offset 4n +/usr/bin/* +.Ed +.Pp +match +.Pa /usr/bin/who +but not +.Pa /usr/bin/X11/xterm . +.Pp +When matching the command line arguments, however, a slash +.Em does +get matched by wildcards since command line arguments may contain +arbitrary strings and not just path names. +.Pp +.Bf -symbolic +Wildcards in command line arguments should be used with care. +.Ef +.br +Command line arguments are matched as a single, concatenated string. +This mean a wildcard character such as +.Ql \&? +or +.Ql * +will match across word boundaries, which may be unexpected. +For example, while a sudoers entry like: +.Bd -literal -offset 4n +%operator ALL = /bin/cat /var/log/messages* +.Ed +.Pp +will allow command like: +.Bd -literal -offset 4n +$ sudo cat /var/log/messages.1 +.Ed +.Pp +It will also allow: +.Bd -literal -offset 4n +$ sudo cat /var/log/messages /etc/shadow +.Ed +.Pp +which is probably not what was intended. +In most cases it is better to do command line processing +outside of the +.Em sudoers +file in a scripting language. +.Ss Exceptions to wildcard rules +The following exceptions apply to the above rules: +.Bl -tag -width 8n +.It Li \&"" +If the empty string +.Li \&"" +is the only command line argument in the +.Em sudoers +file entry it means that command is not allowed to be run with +.Em any +arguments. +.It sudoedit +Command line arguments to the +.Em sudoedit +built-in command should always be path names, so a forward slash +.Pq Ql / +will not be matched by a wildcard. +.El +.Ss Including other files from within sudoers +It is possible to include other +.Em sudoers +files from within the +.Em sudoers +file currently being parsed using the +.Li #include +and +.Li #includedir +directives. +.Pp +This can be used, for example, to keep a site-wide +.Em sudoers +file in addition to a local, per-machine file. +For the sake of this example the site-wide +.Em sudoers +file will be +.Pa /etc/sudoers +and the per-machine one will be +.Pa /etc/sudoers.local . +To include +.Pa /etc/sudoers.local +from within +.Pa /etc/sudoers +we would use the +following line in +.Pa /etc/sudoers : +.Bd -literal -offset 4n +#include /etc/sudoers.local +.Ed +.Pp +When +.Nm sudo +reaches this line it will suspend processing of the current file +.Pq Pa /etc/sudoers +and switch to +.Pa /etc/sudoers.local . +Upon reaching the end of +.Pa /etc/sudoers.local , +the rest of +.Pa /etc/sudoers +will be processed. +Files that are included may themselves include other files. +A hard limit of 128 nested include files is enforced to prevent include +file loops. +.Pp +If the path to the include file is not fully-qualified (does not +begin with a +.Ql / ) , +it must be located in the same directory as the sudoers file it was +included from. +For example, if +.Pa /etc/sudoers +contains the line: +.Bd -literal -offset 4n +.Li #include sudoers.local +.Ed +.Pp +the file that will be included is +.Pa /etc/sudoers.local . +.Pp +The file name may also include the +.Li %h +escape, signifying the short form of the host name. +In other words, if the machine's host name is +.Dq xerxes , +then +.Bd -literal -offset 4n +#include /etc/sudoers.%h +.Ed +.Pp +will cause +.Nm sudo +to include the file +.Pa /etc/sudoers.xerxes . +.Pp +The +.Li #includedir +directive can be used to create a +.Pa sudoers.d +directory that the system package manager can drop +.Em sudoers +file rules into as part of package installation. +For example, given: +.Bd -literal -offset 4n +#includedir /etc/sudoers.d +.Ed +.Pp +.Nm sudo +will suspend processing of the current file and read each file in +.Pa /etc/sudoers.d , +skipping file names that end in +.Ql ~ +or contain a +.Ql .\& +character to avoid causing problems with package manager or editor +temporary/backup files. +Files are parsed in sorted lexical order. +That is, +.Pa /etc/sudoers.d/01_first +will be parsed before +.Pa /etc/sudoers.d/10_second . +Be aware that because the sorting is lexical, not numeric, +.Pa /etc/sudoers.d/1_whoops +would be loaded +.Em after +.Pa /etc/sudoers.d/10_second . +Using a consistent number of leading zeroes in the file names can be used +to avoid such problems. +After parsing the files in the directory, control returns to the +file that contained the +.Li #includedir +directive. +.Pp +Note that unlike files included via +.Li #include , +.Nm visudo +will not edit the files in a +.Li #includedir +directory unless one of them contains a syntax error. +It is still possible to run +.Nm visudo +with the +.Fl f +flag to edit the files directly, but this will not catch the +redefinition of an +.Em alias +that is also present in a different file. +.Ss Other special characters and reserved words +The pound sign +.Pq Ql # +is used to indicate a comment (unless it is part of a #include +directive or unless it occurs in the context of a user name and is +followed by one or more digits, in which case it is treated as a +uid). +Both the comment character and any text after it, up to the end of +the line, are ignored. +.Pp +The reserved word +.Sy ALL +is a built-in +.Em alias +that always causes a match to succeed. +It can be used wherever one might otherwise use a +.Li Cmnd_Alias , +.Li User_Alias , +.Li Runas_Alias , +or +.Li Host_Alias . +You should not try to define your own +.Em alias +called +.Sy ALL +as the built-in alias will be used in preference to your own. +Please note that using +.Sy ALL +can be dangerous since in a command context, it allows the user to run +.Em any +command on the system. +.Pp +An exclamation point +.Pq Ql \&! +can be used as a logical +.Em not +operator in a list or +.Em alias +as well as in front of a +.Li Cmnd . +This allows one to exclude certain values. +For the +.Ql \&! +operator to be effective, there must be something for it to exclude. +For example, to match all users except for root one would use: +.Bd -literal -offset 4n +ALL,!root +.Ed +.Pp +If the +.Sy ALL , +is omitted, as in: +.Bd -literal -offset 4n +!root +.Ed +.Pp +it would explicitly deny root but not match any other users. +This is different from a true +.Dq negation +operator. +.Pp +Note, however, that using a +.Ql \&! +in conjunction with the built-in +.Sy ALL +alias to allow a user to run +.Dq all but a few +commands rarely works as intended (see +.Sx SECURITY NOTES +below). +.Pp +Long lines can be continued with a backslash +.Pq Ql \e +as the last character on the line. +.Pp +White space between elements in a list as well as special syntactic +characters in a +.Em User Specification +.Po +.Ql =\& , +.Ql :\& , +.Ql (\& , +.Ql )\& +.Pc +is optional. +.Pp +The following characters must be escaped with a backslash +.Pq Ql \e +when used as part of a word (e.g., a user name or host name): +.Ql \&! , +.Ql =\& , +.Ql :\& , +.Ql ,\& , +.Ql (\& , +.Ql )\& , +.Ql \e . +.Sh SUDOERS OPTIONS +.Nm sudo Ns 's +behavior can be modified by +.Li Default_Entry +lines, as explained earlier. +A list of all supported Defaults parameters, grouped by type, are listed below. +.Pp +.Sy Boolean Flags : +.Bl -tag -width 16n +.It always_query_group_plugin +If a +.Em group_plugin +is configured, use it to resolve groups of the form %group as long +as there is not also a system group of the same name. +Normally, only groups of the form %:group are passed to the +.Em group_plugin . +This flag is +.Em off +by default. +.It always_set_home +If enabled, +.Nm sudo +will set the +.Ev HOME +environment variable to the home directory of the target user +(which is root unless the +.Fl u +option is used). +This effectively means that the +.Fl H +option is always implied. +Note that by default, +.Ev HOME +will be set to the home directory of the target user when the +.Em env_reset +option is enabled, so +.Em always_set_home +only has an effect for configurations where either +.Em env_reset +is disabled or +.Ev HOME +is present in the +.Em env_keep +list. +This flag is +.Em off +by default. +.It authenticate +If set, users must authenticate themselves via a password (or other +means of authentication) before they may run commands. +This default may be overridden via the +.Li PASSWD +and +.Li NOPASSWD +tags. +This flag is +.Em on +by default. +.It case_insensitive_group +If enabled, group names in +.Em sudoers +will be matched in a case insensitive manner. +This may be necessary when users are stored in LDAP or AD. +This flag is +.Em on +by default. +.It case_insensitive_user +If enabled, user names in +.Em sudoers +will be matched in a case insensitive manner. +This may be necessary when groups are stored in LDAP or AD. +This flag is +.Em on +by default. +.It closefrom_override +If set, the user may use +.Nm sudo Ns 's +.Fl C +option which overrides the default starting point at which +.Nm sudo +begins closing open file descriptors. +This flag is +.Em off +by default. +.It compress_io +If set, and +.Nm sudo +is configured to log a command's input or output, +the I/O logs will be compressed using +.Sy zlib . +This flag is +.Em on +by default when +.Nm sudo +is compiled with +.Sy zlib +support. +.It exec_background +By default, +.Nm sudo +runs a command as the foreground process as long as +.Nm sudo +itself is running in the foreground. +When the +.Em exec_background +flag is enabled and the command is being run in a pty (due to I/O logging +or the +.Em use_pty +flag), the command will be run as a background process. +Attempts to read from the controlling terminal (or to change terminal +settings) will result in the command being suspended with the +.Dv SIGTTIN +signal (or +.Dv SIGTTOU +in the case of terminal settings). +If this happens when +.Nm sudo +is a foreground process, the command will be granted the controlling terminal +and resumed in the foreground with no user intervention required. +The advantage of initially running the command in the background is that +.Nm sudo +need not read from the terminal unless the command explicitly requests it. +Otherwise, any terminal input must be passed to the command, whether it +has required it or not (the kernel buffers terminals so it is not possible +to tell whether the command really wants the input). +This is different from historic +.Em sudo +behavior or when the command is not being run in a pty. +.Pp +For this to work seamlessly, the operating system must support the +automatic restarting of system calls. +Unfortunately, not all operating systems do this by default, +and even those that do may have bugs. +For example, macOS fails to restart the +.Fn tcgetattr +and +.Fn tcsetattr +system calls (this is a bug in macOS). +Furthermore, because this behavior depends on the command stopping with the +.Dv SIGTTIN +or +.Dv SIGTTOU +signals, programs that catch these signals and suspend themselves +with a different signal (usually +.Dv SIGTOP ) +will not be automatically foregrounded. +Some versions of the linux +.Xr su 1 +command behave this way. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.7 or higher. +It has no effect unless I/O logging is enabled or the +.Em use_pty +flag is enabled. +.It env_editor +If set, +.Nm visudo +will use the value of the +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +environment variables before falling back on the default editor list. +Note that this may create a security hole as it allows the user to +run any arbitrary command as root without logging. +A safer alternative is to place a colon-separated list of editors +in the +.Em editor +variable. +.Nm visudo +will then only use +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +if they match a value specified in +.Em editor . +If the +.Em env_reset +flag is enabled, the +.Ev SUDO_EDITOR , +.Ev VISUAL +and/or +.Ev EDITOR +environment variables must be present in the +.Em env_keep +list for the +.Em env_editor +flag to function when +.Nm visudo +is invoked via +.Nm sudo . +This flag is +.Em @env_editor@ +by default. +.It env_reset +If set, +.Nm sudo +will run the command in a minimal environment containing the +.Ev TERM , +.Ev PATH , +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev LOGNAME , +.Ev USER +and +.Ev SUDO_* +variables. +Any variables in the caller's environment or in the file specified +by the +.Em restricted_env_file +option that match the +.Li env_keep +and +.Li env_check +lists are then added, followed by any variables present in the file +specified by the +.Em env_file +option (if any). +The contents of the +.Li env_keep +and +.Li env_check +lists, as modified by global Defaults parameters in +.Em sudoers , +are displayed when +.Nm sudo +is run by root with the +.Fl V +option. +If the +.Em secure_path +option is set, its value will be used for the +.Ev PATH +environment variable. +This flag is +.Em @env_reset@ +by default. +.It fast_glob +Normally, +.Nm sudo +uses the +.Xr glob 3 +function to do shell-style globbing when matching path names. +However, since it accesses the file system, +.Xr glob 3 +can take a long time to complete for some patterns, especially +when the pattern references a network file system that is mounted +on demand (auto mounted). +The +.Em fast_glob +option causes +.Nm sudo +to use the +.Xr fnmatch 3 +function, which does not access the file system to do its matching. +The disadvantage of +.Em fast_glob +is that it is unable to match relative path names such as +.Pa ./ls +or +.Pa ../bin/ls . +This has security implications when path names that include globbing +characters are used with the negation operator, +.Ql !\& , +as such rules can be trivially bypassed. +As such, this option should not be used when the +.Em sudoers +file contains rules that contain negated path names which include globbing +characters. +This flag is +.Em off +by default. +.It fqdn +Set this flag if you want to put fully qualified host names in the +.Em sudoers +file when the local host name (as returned by the +.Li hostname +command) does not contain the domain name. +In other words, instead of myhost you would use myhost.mydomain.edu. +You may still use the short form if you wish (and even mix the two). +This option is only effective when the +.Dq canonical +host name, as returned by the +.Fn getaddrinfo +or +.Fn gethostbyname +function, is a fully-qualified domain name. +This is usually the case when the system is configured to use DNS +for host name resolution. +.Pp +If the system is configured to use the +.Pa /etc/hosts +file in preference to DNS, the +.Dq canonical +host name may not be fully-qualified. +The order that sources are queried for host name resolution +is usually specified in the +.Pa @nsswitch_conf@ , +.Pa @netsvc_conf@ , +.Pa /etc/host.conf , +or, in some cases, +.Pa /etc/resolv.conf +file. +In the +.Pa /etc/hosts +file, the first host name of the entry is considered to be the +.Dq canonical +name; subsequent names are aliases that are not used by +.Nm . +For example, the following hosts file line for the machine +.Dq xyzzy +has the fully-qualified domain name as the +.Dq canonical +host name, and the short version as an alias. +.sp +.Dl 192.168.1.1 xyzzy.sudo.ws xyzzy +.sp +If the machine's hosts file entry is not formatted properly, the +.Em fqdn +option will not be effective if it is queried before DNS. +.Pp +Beware that when using DNS for host name resolution, turning on +.Em fqdn +requires +.Nm +to make DNS lookups which renders +.Nm sudo +unusable if DNS stops working (for example if the machine is disconnected +from the network). +Also note that just like with the hosts file, you must use the +.Dq canonical +name as DNS knows it. +That is, you may not use a host alias +.Po +.Li CNAME +entry +.Pc +due to performance issues and the fact that there is no way to get all +aliases from DNS. +.Pp +This flag is +.Em @fqdn@ +by default. +.It ignore_audit_errors +Allow commands to be run even if +.Nm +cannot write to the audit log. +If enabled, an audit log write failure is not treated as a fatal error. +If disabled, a command may only be run after the audit event is successfully +written. +This flag is only effective on systems for which +.Nm +supports audit logging, including +.Fx , +Linux, macOS and Solaris. +This flag is +.Em on +by default. +.It ignore_dot +If set, +.Nm sudo +will ignore "." or "" (both denoting current directory) in the +.Ev PATH +environment variable; the +.Ev PATH +itself is not modified. +This flag is +.Em @ignore_dot@ +by default. +.It ignore_iolog_errors +Allow commands to be run even if +.Nm +cannot write to the I/O log. +If enabled, an I/O log write failure is not treated as a fatal error. +If disabled, the command will be terminated if the I/O log cannot be written to. +This flag is +.Em off +by default. +.It ignore_logfile_errors +Allow commands to be run even if +.Nm +cannot write to the log file. +If enabled, a log file write failure is not treated as a fatal error. +If disabled, a command may only be run after the log file entry is successfully +written. +This flag only has an effect when +.Nm +is configured to use file-based logging via the +.Em logfile +option. +This flag is +.Em on +by default. +.It ignore_local_sudoers +If set via LDAP, parsing of +.Pa @sysconfdir@/sudoers +will be skipped. +This is intended for Enterprises that wish to prevent the usage of local +sudoers files so that only LDAP is used. +This thwarts the efforts of rogue operators who would attempt to add roles to +.Pa @sysconfdir@/sudoers . +When this option is present, +.Pa @sysconfdir@/sudoers +does not even need to exist. +Since this option tells +.Nm sudo +how to behave when no specific LDAP entries have been matched, this +sudoOption is only meaningful for the +.Li cn=defaults +section. +This flag is +.Em off +by default. +.It ignore_unknown_defaults +If set, +.Nm sudo +will not produce a warning if it encounters an unknown Defaults entry +in the +.Em sudoers +file or an unknown sudoOption in LDAP. +This flag is +.Em off +by default. +.It insults +If set, +.Nm sudo +will insult users when they enter an incorrect password. +This flag is +.Em @insults@ +by default. +.It log_host +If set, the host name will be logged in the (non-syslog) +.Nm sudo +log file. +This flag is +.Em off +by default. +.It log_input +If set, +.Nm sudo +will run the command in a pseudo-tty and log all user input. +If the standard input is not connected to the user's tty, due to +I/O redirection or because the command is part of a pipeline, that +input is also captured and stored in a separate log file. +Anything sent to the standard input will be consumed, regardless of +whether or not the command run via +.Nm sudo +is actually reading the standard input. +This may have unexpected results when using +.Nm sudo +in a shell script that expects to process the standard input. +For more information about I/O logging, see the +.Sx "I/O LOG FILES" +section. +This flag is +.Em off +by default. +.It log_output +If set, +.Nm sudo +will run the command in a pseudo-tty and log all output that is sent +to the screen, similar to the +.Xr script 1 +command. +For more information about I/O logging, see the +.Sx "I/O LOG FILES" +section. +This flag is +.Em off +by default. +.It log_year +If set, the four-digit year will be logged in the (non-syslog) +.Nm sudo +log file. +This flag is +.Em off +by default. +.It long_otp_prompt +When validating with a One Time Password (OTP) scheme such as +.Sy S/Key +or +.Sy OPIE , +a two-line prompt is used to make it easier +to cut and paste the challenge to a local window. +It's not as pretty as the default but some people find it more convenient. +This flag is +.Em @long_otp_prompt@ +by default. +.It mail_all_cmnds +Send mail to the +.Em mailto +user every time a user attempts to run a command via +.Nm sudo +(this includes +.Nm sudoedit ) . +No mail will be sent if the user runs +.Nm sudo +with the +.Fl l +or +.Fl v +option unless there is an authentication error and the +.Em mail_badpass +flag is also set. +This flag is +.Em off +by default. +.It mail_always +Send mail to the +.Em mailto +user every time a user runs +.Nm sudo . +This flag is +.Em off +by default. +.It mail_badpass +Send mail to the +.Em mailto +user if the user running +.Nm sudo +does not enter the correct password. +If the command the user is attempting to run is not permitted by +.Nm sudoers +and one of the +.Em mail_all_cmnds , +.Em mail_always , +.Em mail_no_host , +.Em mail_no_perms +or +.Em mail_no_user +flags are set, this flag will have no effect. +This flag is +.Em off +by default. +.It mail_no_host +If set, mail will be sent to the +.Em mailto +user if the invoking user exists in the +.Em sudoers +file, but is not allowed to run commands on the current host. +This flag is +.Em @mail_no_host@ +by default. +.It mail_no_perms +If set, mail will be sent to the +.Em mailto +user if the invoking user is allowed to use +.Nm sudo +but the command they are trying is not listed in their +.Em sudoers +file entry or is explicitly denied. +This flag is +.Em @mail_no_perms@ +by default. +.It mail_no_user +If set, mail will be sent to the +.Em mailto +user if the invoking user is not in the +.Em sudoers +file. +This flag is +.Em @mail_no_user@ +by default. +.It match_group_by_gid +By default, +.Nm +will look up each group the user is a member of by group ID to +determine the group name (this is only done once). +The resulting list of the user's group names is used when matching +groups listed in the +.Em sudoers +file. +This works well on systems where the number of groups listed in the +.Em sudoers +file is larger than the number of groups a typical user belongs to. +On systems where group lookups are slow, where users may belong +to a large number of groups, and where the number of groups listed +in the +.Em sudoers +file is relatively small, it may be prohibitively expensive and +running commands via +.Nm sudo +may take longer than normal. +On such systems it may be faster to use the +.Em match_group_by_gid +flag to avoid resolving the user's group IDs to group names. +In this case, +.Nm +must look up any group name listed in the +.Em sudoers +file and use the group ID instead of the group name when determining +whether the user is a member of the group. +.Pp +Note that if +.Em match_group_by_gid +is enabled, group database lookups performed by +.Nm +will be keyed by group name as opposed to group ID. +On systems where there are multiple sources for the group database, +it is possible to have conflicting group names or group IDs in the local +.Pa /etc/group +file and the remote group database. +On such systems, enabling or disabling +.Em match_group_by_gid +can be used to choose whether group database queries are performed +by name (enabled) or ID (disabled), which may aid in working around +group entry conflicts. +.Pp +The +.Em match_group_by_gid +flag has no effect when +.Em sudoers +data is stored in LDAP. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.18 or higher. +.It netgroup_tuple +If set, netgroup lookups will be performed using the full netgroup +tuple: host name, user name and domain (if one is set). +Historically, +.Nm sudo +only matched the user name and domain for netgroups used in a +.Li User_List +and only matched the host name and domain for netgroups used in a +.Li Host_List . +This flag is +.Em off +by default. +.It noexec +If set, all commands run via +.Nm sudo +will behave as if the +.Li NOEXEC +tag has been set, unless overridden by an +.Li EXEC +tag. +See the description of +.Em EXEC and NOEXEC +above as well as the +.Sx Preventing shell escapes +section at the end of this manual. +This flag is +.Em off +by default. +.It pam_session +On systems that use PAM for authentication, +.Nm sudo +will create a new PAM session for the command to be run in. +Disabling +.Em pam_session +may be needed on older PAM implementations or on operating systems where +opening a PAM session changes the utmp or wtmp files. +If PAM session support is disabled, resource limits may not be updated +for the command being run. +If +.Em pam_session , +.Em pam_setcred , +and +.Em use_pty +are disabled and I/O logging has not been configured, +.Nm sudo +will execute the command directly instead of running it as a child +process. +This flag is +.Em @pam_session@ +by default. +.Pp +This setting is only supported by version 1.8.7 or higher. +.It pam_setcred +On systems that use PAM for authentication, +.Nm sudo +will attempt to establish credentials for the target user by default, +if supported by the underlying authentication system. +One example of a credential is a Kerberos ticket. +If +.Em pam_session , +.Em pam_setcred , +and +.Em use_pty +are disabled and I/O logging has not been configured, +.Nm sudo +will execute the command directly instead of running it as a child +process. +This flag is +.Em on +by default. +.Pp +This setting is only supported by version 1.8.8 or higher. +.It passprompt_override +If set, the prompt specified by +.Em passprompt +or the +.Ev SUDO_PROMPT +environment variable will always be used and will replace the +prompt provided by a PAM module or other authentication method. +This flag is +.Em off +by default. +.It path_info +Normally, +.Nm sudo +will tell the user when a command could not be +found in their +.Ev PATH +environment variable. +Some sites may wish to disable this as it could be used to gather +information on the location of executables that the normal user does +not have access to. +The disadvantage is that if the executable is simply not in the user's +.Ev PATH , +.Nm sudo +will tell the user that they are not allowed to run it, which can be confusing. +This flag is +.Em @path_info@ +by default. +.It preserve_groups +By default, +.Nm sudo +will initialize the group vector to the list of groups the target user is in. +When +.Em preserve_groups +is set, the user's existing group vector is left unaltered. +The real and effective group IDs, however, are still set to match the +target user. +This flag is +.Em off +by default. +.It pwfeedback +By default, +.Nm sudo +reads the password like most other Unix programs, +by turning off echo until the user hits the return (or enter) key. +Some users become confused by this as it appears to them that +.Nm sudo +has hung at this point. +When +.Em pwfeedback +is set, +.Nm sudo +will provide visual feedback when the user presses a key. +Note that this does have a security impact as an onlooker may be able to +determine the length of the password being entered. +This flag is +.Em off +by default. +.It requiretty +If set, +.Nm sudo +will only run when the user is logged in to a real tty. +When this flag is set, +.Nm sudo +can only be run from a login session and not via other means such as +.Xr cron @mansectsu@ +or cgi-bin scripts. +This flag is +.Em off +by default. +.It root_sudo +If set, root is allowed to run +.Nm sudo +too. +Disabling this prevents users from +.Dq chaining +.Nm sudo +commands to get a root shell by doing something like +.Dq Li sudo sudo /bin/sh . +Note, however, that turning off +.Em root_sudo +will also prevent root from running +.Nm sudoedit . +Disabling +.Em root_sudo +provides no real additional security; it exists purely for historical reasons. +This flag is +.Em @root_sudo@ +by default. +.It rootpw +If set, +.Nm sudo +will prompt for the root password instead of the password of the invoking user +when running a command or editing a file. +This flag is +.Em off +by default. +.It runaspw +If set, +.Nm sudo +will prompt for the password of the user defined by the +.Em runas_default +option (defaults to +.Li @runas_default@ ) +instead of the password of the invoking user +when running a command or editing a file. +This flag is +.Em off +by default. +.It set_home +If enabled and +.Nm sudo +is invoked with the +.Fl s +option the +.Ev HOME +environment variable will be set to the home directory of the target +user (which is root unless the +.Fl u +option is used). +This effectively makes the +.Fl s +option imply +.Fl H . +Note that +.Ev HOME +is already set when the +.Em env_reset +option is enabled, so +.Em set_home +is only effective for configurations where either +.Em env_reset +is disabled +or +.Ev HOME +is present in the +.Em env_keep +list. +This flag is +.Em off +by default. +.It set_logname +Normally, +.Nm sudo +will set the +.Ev LOGNAME +and +.Ev USER +environment variables to the name of the target user (usually root unless the +.Fl u +option is given). +However, since some programs (including the RCS revision control system) use +.Ev LOGNAME +to determine the real identity of the user, it may be desirable to +change this behavior. +This can be done by negating the set_logname option. +Note that +.Em set_logname +will have no effect +if the +.Em env_reset +option has not been disabled and the +.Em env_keep +list contains +.Ev LOGNAME +or +.Ev USER . +This flag is +.Em on +by default. +.It set_utmp +When enabled, +.Nm sudo +will create an entry in the utmp (or utmpx) file when a pseudo-tty +is allocated. +A pseudo-tty is allocated by +.Nm sudo +when the +.Em log_input , +.Em log_output +or +.Em use_pty +flags are enabled. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +This flag is +.Em on +by default. +.It setenv +Allow the user to disable the +.Em env_reset +option from the command line via the +.Fl E +option. +Additionally, environment variables set via the command line are +not subject to the restrictions imposed by +.Em env_check , +.Em env_delete , +or +.Em env_keep . +As such, only trusted users should be allowed to set variables in this manner. +This flag is +.Em off +by default. +.It shell_noargs +If set and +.Nm sudo +is invoked with no arguments it acts as if the +.Fl s +option had been given. +That is, it runs a shell as root (the shell is determined by the +.Ev SHELL +environment variable if it is set, falling back on the shell listed +in the invoking user's /etc/passwd entry if not). +This flag is +.Em off +by default. +.It stay_setuid +Normally, when +.Nm sudo +executes a command the real and effective UIDs are set to the target +user (root by default). +This option changes that behavior such that the real UID is left +as the invoking user's UID. +In other words, this makes +.Nm sudo +act as a setuid wrapper. +This can be useful on systems that disable some potentially +dangerous functionality when a program is run setuid. +This option is only effective on systems that support either the +.Xr setreuid 2 +or +.Xr setresuid 2 +system call. +This flag is +.Em off +by default. +.It sudoedit_checkdir +If set, +.Nm sudoedit +will check all directory components of the path to be edited for writability +by the invoking user. +Symbolic links will not be followed in writable directories and +.Nm sudoedit +will refuse to edit a file located in a writable directory. +These restrictions are not enforced when +.Nm sudoedit +is run by root. +On some systems, if all directory components of the path to be edited +are not readable by the target user, +.Nm sudoedit +will be unable to edit the file. +This flag is +.Em on +by default. +.Pp +This setting was first introduced in version 1.8.15 but initially +suffered from a race condition. +The check for symbolic links in writable intermediate directories +was added in version 1.8.16. +.It sudoedit_follow +By default, +.Nm sudoedit +will not follow symbolic links when opening files. +The +.Em sudoedit_follow +option can be enabled to allow +.Nm sudoedit +to open symbolic links. +It may be overridden on a per-command basis by the +.Em FOLLOW +and +.Em NOFOLLOW +tags. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.15 or higher. +.It syslog_pid +When logging via +.Xr syslog 3 , +include the process ID in the log entry. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.21 or higher. +.It targetpw +If set, +.Nm sudo +will prompt for the password of the user specified +by the +.Fl u +option (defaults to +.Li root ) +instead of the password of the invoking user +when running a command or editing a file. +Note that this flag precludes the use of a uid not listed in the passwd +database as an argument to the +.Fl u +option. +This flag is +.Em off +by default. +.It tty_tickets +If set, users must authenticate on a per-tty basis. +With this flag enabled, +.Nm sudo +will use a separate record in the time stamp file for each terminal. +If disabled, a single record is used for all login sessions. +.Pp +This option has been superseded by the +.Em timestamp_type +option. +.It umask_override +If set, +.Nm sudo +will set the umask as specified in the +.Em sudoers +file without modification. +This makes it possible to specify a umask in the +.Em sudoers +file that is more permissive than the user's own umask and matches +historical behavior. +If +.Em umask_override +is not set, +.Nm sudo +will set the umask to be the union of the user's umask and what is specified in +.Em sudoers . +This flag is +.Em @umask_override@ +by default. +.if \n(LC \{\ +.It use_loginclass +If set, +.Nm sudo +will apply the defaults specified for the target user's login class +if one exists. +Only available if +.Nm sudo +is configured with the +.Li --with-logincap +option. +This flag is +.Em off +by default. +.\} +.It use_netgroups +If set, netgroups (prefixed with +.Ql + ) , +may be used in place of a user or host. +For LDAP-based sudoers, netgroup support requires an expensive +sub-string match on the server unless the +.Sy NETGROUP_BASE +directive is present in the +.Pa @ldap_conf@ +file. +If netgroups are not needed, this option can be disabled to reduce the +load on the LDAP server. +This flag is +.Em on +by default. +.It use_pty +If set, and +.Nm sudo +is running in a terminal, the command will be run in a pseudo-pty +(even if no I/O logging is being done). +If the +.Nm sudo +process is not attached to a terminal, +.Em use_pty +has no effect. +.Pp +A malicious program run under +.Nm sudo +may be capable of injecting commands into the user's +terminal or running a background process that retains access to the +user's terminal device even after the main program has finished +executing. +By running the command in a separate pseudo-pty, this attack is +no longer possible. +This flag is +.Em off +by default. +.It user_command_timeouts +If set, the user may specify a timeout on the command line. +If the timeout expires before the command has exited, the +command will be terminated. +If a timeout is specified both in the +.Pa sudoers +file and on the command line, the smaller of the two timeouts will be used. +See the +.Li Timeout_Spec +section for a description of the timeout syntax. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.20 or higher. +.It utmp_runas +If set, +.Nm sudo +will store the name of the runas user when updating the utmp (or utmpx) file. +By default, +.Nm sudo +stores the name of the invoking user. +This flag is +.Em off +by default. +.It visiblepw +By default, +.Nm sudo +will refuse to run if the user must enter a password but it is not +possible to disable echo on the terminal. +If the +.Em visiblepw +flag is set, +.Nm sudo +will prompt for a password even when it would be visible on the screen. +This makes it possible to run things like +.Dq Li ssh somehost sudo ls +since by default, +.Xr ssh 1 +does +not allocate a tty when running a command. +This flag is +.Em off +by default. +.El +.Pp +.Sy Integers : +.Bl -tag -width 16n +.It closefrom +Before it executes a command, +.Nm sudo +will close all open file descriptors other than standard input, +standard output and standard error (ie: file descriptors 0-2). +The +.Em closefrom +option can be used to specify a different file descriptor at which +to start closing. +The default is +.Li 3 . +.It command_timeout +The maximum amount of time a command is allowed to run before +it is terminated. +See the +.Li Timeout_Spec +section for a description of the timeout syntax. +.Pp +This setting is only supported by version 1.8.20 or higher. +.It maxseq +The maximum sequence number that will be substituted for the +.Dq Li %{seq} +escape in the I/O log file (see the +.Em iolog_dir +description below for more information). +While the value substituted for +.Dq Li %{seq} +is in base 36, +.Em maxseq +itself should be expressed in decimal. +Values larger than 2176782336 (which corresponds to the +base 36 sequence number +.Dq ZZZZZZ ) +will be silently truncated to 2176782336. +The default value is 2176782336. +.Pp +Once the local sequence number reaches the value of +.Em maxseq , +it will +.Dq roll over +to zero, after which +.Nm +will truncate and re-use any existing I/O log path names. +.Pp +This setting is only supported by version 1.8.7 or higher. +.It passwd_tries +The number of tries a user gets to enter his/her password before +.Nm sudo +logs the failure and exits. +The default is +.Li @passwd_tries@ . +.It syslog_maxlen +On many systems, +.Xr syslog 3 +has a relatively small log buffer. +IETF RFC 5424 states that syslog servers must support messages of +at least 480 bytes and should support messages up to 2048 bytes. +By default, +.Nm +creates log messages up to 980 bytes which corresponds to the +historic +.Bx +syslog implementation which used a 1024 byte buffer +to store the message, date, hostname and program name. +To prevent syslog messages from being truncated, +.Nm +will split up log messages that are larger than +.Em syslog_maxlen +bytes. +When a message is split, additional parts will include the string +.Dq Pq command continued +after the user name and before the continued command line arguments. +.Pp +This setting is only supported by version 1.8.19 or higher. +.El +.Pp +.Sy Integers that can be used in a boolean context : +.Bl -tag -width 16n +.It loglinelen +Number of characters per line for the file log. +This value is used to decide when to wrap lines for nicer log files. +This has no effect on the syslog log file, only the file log. +The default is +.Li @loglen@ +(use 0 or negate the option to disable word wrap). +.It passwd_timeout +Number of minutes before the +.Nm sudo +password prompt times out, or +.Li 0 +for no timeout. +The timeout may include a fractional component +if minute granularity is insufficient, for example +.Li 2.5 . +The +default is +.Li @password_timeout@ . +.It timestamp_timeout +Number of minutes that can elapse before +.Nm sudo +will ask for a passwd again. +The timeout may include a fractional component if +minute granularity is insufficient, for example +.Li 2.5 . +The default is +.Li @timeout@ . +Set this to +.Li 0 +to always prompt for a password. +If set to a value less than +.Li 0 +the user's time stamp will not expire until the system is rebooted. +This can be used to allow users to create or delete their own time stamps via +.Dq Li sudo -v +and +.Dq Li sudo -k +respectively. +.It umask +Umask to use when running the command. +Negate this option or set it to 0777 to preserve the user's umask. +The actual umask that is used will be the union of the user's umask +and the value of the +.Em umask +option, which defaults to +.Li @sudo_umask@ . +This guarantees +that +.Nm sudo +never lowers the umask when running a command. +Note: on systems that use PAM, the default PAM configuration may specify +its own umask which will override the value set in +.Em sudoers . +.El +.Pp +.Sy Strings : +.Bl -tag -width 16n +.It authfail_message +Message that is displayed after a user fails to authenticate. +The message may include the +.Ql %d +escape which will expand to the number of failed password attempts. +If set, it overrides the default message, +.Li %d incorrect password attempt(s) . +.It badpass_message +Message that is displayed if a user enters an incorrect password. +The default is +.Li @badpass_message@ +unless insults are enabled. +.It editor +A colon +.Pq Ql :\& +separated list of editors path names used by +.Nm sudoedit +and +.Nm visudo . +For +.Nm sudoedit , +this list is used to find an editor when none of the +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +environment variables are set to an editor that exists and is executable. +For +.Nm visudo , +it is used as a white list of allowed editors; +.Nm visudo +will choose the editor that matches the user's +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +environment variable if possible, or the first editor in the +list that exists and is executable if not. +Unless invoked as +.Nm sudoedit , +.Nm sudo +does not preserve the +.Ev SUDO_EDITOR , +.Ev VISUAL +and +.Ev EDITOR +environment variables by default, even when the +.Em env_reset +option is enabled. +The default is +.Pa @editor@ . +.It iolog_dir +The top-level directory to use when constructing the path name for +the input/output log directory. +Only used if the +.Em log_input +or +.Em log_output +options are enabled or when the +.Li LOG_INPUT +or +.Li LOG_OUTPUT +tags are present for a command. +The session sequence number, if any, is stored in the directory. +The default is +.Pa @iolog_dir@ . +.Pp +The following percent +.Pq Ql % +escape sequences are supported: +.Bl -tag -width 4n +.It Li %{seq} +expanded to a monotonically increasing base-36 sequence number, such as 0100A5, +where every two digits are used to form a new directory, e.g., +.Pa 01/00/A5 +.It Li %{user} +expanded to the invoking user's login name +.It Li %{group} +expanded to the name of the invoking user's real group ID +.It Li %{runas_user} +expanded to the login name of the user the command will +be run as (e.g., root) +.It Li %{runas_group} +expanded to the group name of the user the command will +be run as (e.g., wheel) +.It Li %{hostname} +expanded to the local host name without the domain name +.It Li %{command} +expanded to the base name of the command being run +.El +.Pp +In addition, any escape sequences supported by the system's +.Xr strftime 3 +function will be expanded. +.Pp +To include a literal +.Ql % +character, the string +.Ql %% +should be used. +.It iolog_file +The path name, relative to +.Em iolog_dir , +in which to store input/output logs when the +.Em log_input +or +.Em log_output +options are enabled or when the +.Li LOG_INPUT +or +.Li LOG_OUTPUT +tags are present for a command. +Note that +.Em iolog_file +may contain directory components. +The default is +.Dq Li %{seq} . +.Pp +See the +.Em iolog_dir +option above for a list of supported percent +.Pq Ql % +escape sequences. +.Pp +In addition to the escape sequences, path names that end in six or +more +.Li X Ns s +will have the +.Li X Ns s +replaced with a unique combination of digits and letters, similar to the +.Xr mktemp 3 +function. +.Pp +If the path created by concatenating +.Em iolog_dir +and +.Em iolog_file +already exists, the existing I/O log file will be truncated and +overwritten unless +.Em iolog_file +ends in six or +more +.Li X Ns s . +.It iolog_flush +If set, +.Nm sudo +will flush I/O log data to disk after each write instead of buffering it. +This makes it possible to view the logs in real-time as the program +is executing but may significantly reduce the effectiveness of I/O +log compression. +This flag is +.Em off +by default. +.Pp +This setting is only supported by version 1.8.20 or higher. +.It iolog_group +The group name to look up when setting the group ID on new I/O log +files and directories. +If +.Em iolog_group +is not set, +the primary group ID of the user specified by +.Em iolog_user +is used. +If neither +.Em iolog_group +nor +.Em iolog_user +are set, I/O log files and directories are created with group ID 0. +.Pp +This setting is only supported by version 1.8.19 or higher. +.It iolog_mode +The file mode to use when creating I/O log files. +Mode bits for read and write permissions for owner, group or other +are honored, everything else is ignored. +The file permissions will always include the owner read and +write bits, even if they are not present in the specified mode. +When creating I/O log directories, search (execute) bits are added +to match the read and write bits specified by +.Em iolog_mode . +Defaults to 0600 (read and write by user only). +.Pp +This setting is only supported by version 1.8.19 or higher. +.It iolog_user +The user name to look up when setting the user and group IDs on new +I/O log files and directories. +If +.Em iolog_group +is set, it will be used instead of the user's primary group ID. +By default, I/O log files and directories are created with user and +group ID 0. +.Pp +This setting can be useful when the I/O logs are stored on a Network +File System (NFS) share. +Having a dedicated user own the I/O log files means that +.Nm +does not write to the log files as user ID 0, which is usually +not permitted by NFS. +.Pp +This setting is only supported by version 1.8.19 or higher. +.It lecture_status_dir +The directory in which +.Nm sudo +stores per-user lecture status files. +Once a user has received the lecture, a zero-length file is +created in this directory so that +.Nm sudo +will not lecture the user again. +This directory should +.Em not +be cleared when the system reboots. +The default is +.Pa @vardir@/lectured . +.if \n(PS \{\ +.It limitprivs +The default Solaris limit privileges to use when constructing a new +privilege set for a command. +This bounds all privileges of the executing process. +The default limit privileges may be overridden on a per-command basis in +.Em sudoers . +This option is only available if +.Nm +is built on Solaris 10 or higher. +.\} +.It mailsub +Subject of the mail sent to the +.Em mailto +user. +The escape +.Li %h +will expand to the host name of the machine. +Default is +.Dq Li @mailsub@ . +.It noexec_file +As of +.Nm sudo +version 1.8.1 this option is no longer supported. +The path to the noexec file should now be set in the +.Xr sudo.conf @mansectform@ +file. +.It pam_login_service +On systems that use PAM for authentication, this is the service +name used when the +.Fl i +option is specified. +The default value is +.Dq Li @pam_login_service@ . +See the description of +.Em pam_service +for more information. +.Pp +This setting is only supported by version 1.8.8 or higher. +.It pam_service +On systems that use PAM for authentication, the service name +specifies the PAM policy to apply. +This usually corresponds to an entry in the +.Pa pam.conf +file or a file in the +.Pa /etc/pam.d +directory. +The default value is +.Dq Li sudo . +.Pp +This setting is only supported by version 1.8.8 or higher. +.It passprompt +The default prompt to use when asking for a password; can be overridden via the +.Fl p +option or the +.Ev SUDO_PROMPT +environment variable. +The following percent +.Pq Ql % +escape sequences are supported: +.Bl -tag -width 4n +.It Li %H +expanded to the local host name including the domain name +(only if the machine's host name is fully qualified or the +.Em fqdn +option is set) +.It Li %h +expanded to the local host name without the domain name +.It Li %p +expanded to the user whose password is being asked for (respects the +.Em rootpw , +.Em targetpw +and +.Em runaspw +flags in +.Em sudoers ) +.It Li \&%U +expanded to the login name of the user the command will +be run as (defaults to root) +.It Li %u +expanded to the invoking user's login name +.It Li %% +two consecutive +.Li % +characters are collapsed into a single +.Li % +character +.El +.Pp +On systems that use PAM for authentication, +.Em passprompt +will only be used if the prompt provided by the PAM module matches the string +.Dq "Password: " +or +.Dq "username's Password: " . +This ensures that the +.Em passprompt +setting does not interfere with challenge-response style authentication. +The +.Em passprompt_override +flag can be used to change this behavior. +.Pp +The default value is +.Dq Li "@passprompt@" . +.if \n(PS \{\ +.It privs +The default Solaris privileges to use when constructing a new +privilege set for a command. +This is passed to the executing process via the inherited privilege set, +but is bounded by the limit privileges. +If the +.Em privs +option is specified but the +.Em limitprivs +option is not, the limit privileges of the executing process is set to +.Em privs . +The default privileges may be overridden on a per-command basis in +.Em sudoers . +This option is only available if +.Nm +is built on Solaris 10 or higher. +.\} +.if \n(SL \{\ +.It role +The default SELinux role to use when constructing a new security +context to run the command. +The default role may be overridden on a per-command basis in the +.Em sudoers +file or via command line options. +This option is only available when +.Nm sudo +is built with SELinux support. +.\} +.It runas_default +The default user to run commands as if the +.Fl u +option is not specified on the command line. +This defaults to +.Li @runas_default@ . +.It sudoers_locale +Locale to use when parsing the sudoers file, logging commands, and +sending email. +Note that changing the locale may affect how sudoers is interpreted. +Defaults to +.Dq Li C . +.It timestamp_type +.Nm sudoers +uses per-user time stamp files for credential caching. +The +.Em timestamp_type +option can be used to specify the type of time stamp record used. +It has the following possible values: +.Bl -tag -width 6n +.It global +A single time stamp record is used for all of a user's login sessions, +regardless of the terminal or parent process ID. +An additional record is used to serialize password prompts when +.Nm sudo +is used multiple times in a pipeline, but this does not affect authentication. +.It ppid +A single time stamp record is used for all processes with the same parent +process ID (usually the shell). +Commands run from the same shell (or other common parent process) +will not require a password for +.Em timestamp_timeout +minutes +.Po +.Li @timeout@ +by default +.Pc . +Commands run via +.Nm sudo +with a different parent process ID, for example from a shell script, +will be authenticated separately. +.It tty +One time stamp record is used for each terminal, +which means that a user's login sessions are authenticated separately. +If no terminal is present, the behavior is the same as +.Em ppid . +Commands run from the same terminal will not require a password for +.Em timestamp_timeout +minutes +.Po +.Li @timeout@ +by default +.Pc . +.It kernel +The time stamp is stored in the kernel as an attribute of the terminal +device. +If no terminal is present, the behavior is the same as +.Em ppid . +Negative +.Em timestamp_timeout +values are not supported and positive values are limited to a maximum +of 60 minutes. +This is currently only supported on +.Ox . +.El +.Pp +The default value is +.Em @timestamp_type@ . +.Pp +This setting is only supported by version 1.8.21 or higher. +.It timestampdir +The directory in which +.Nm sudo +stores its time stamp files. +This directory should be cleared when the system reboots. +The default is +.Pa @rundir@/ts . +.It timestampowner +The owner of the lecture status directory, time stamp directory and all +files stored therein. +The default is +.Li root . +.if \n(SL \{\ +.It type +The default SELinux type to use when constructing a new security +context to run the command. +The default type may be overridden on a per-command basis in the +.Em sudoers +file or via command line options. +This option is only available when +.Nm sudo +is built with SELinux support. +.\} +.El +.Pp +.Sy Strings that can be used in a boolean context : +.Bl -tag -width 12n +.It env_file +The +.Em env_file +option specifies the fully qualified path to a file containing variables +to be set in the environment of the program being run. +Entries in this file should either be of the form +.Dq Li VARIABLE=value +or +.Dq Li export VARIABLE=value . +The value may optionally be surrounded by single or double quotes. +Variables in this file are only added if the variable does not already +exist in the environment. +This file is considered to be part of the security policy, +its contents are not subject to other +.Nm sudo +environment restrictions such as +.Em env_keep +and +.Em env_check . +.It exempt_group +Users in this group are exempt from password and PATH requirements. +The group name specified should not include a +.Li % +prefix. +This is not set by default. +.It fdexec +Determines whether +.Nm sudo +will execute a command by its path or by an open file descriptor. +It has the following possible values: +.Bl -tag -width 6n +.It always +Always execute by file descriptor. +.It never +Never execute by file descriptor. +.It digest_only +Only execute by file descriptor if the command has an associated digest +in the +.Em sudoers +file. +.El +.Pp +The default value is +.Em digest_only . +This avoids a time of check versus time of use race condition when +the command is located in a directory writable by the invoking user. +.Pp +Note that +.Em fdexec +will change the first element of the argument vector for scripts +($0 in the shell) due to the way the kernel runs script interpreters. +Instead of being a normal path, it will refer to a file descriptor. +For example, +.Pa /dev/fd/4 +on Solaris and +.Pa /proc/self/fd/4 +on Linux. +A workaround is to use the +.Dv SUDO_COMMAND +environment variable instead. +.Pp +The +.Em fdexec +setting is only used when the command is matched by path name. +It has no effect if the command is matched by the built-in +.Sy ALL +alias. +.Pp +This setting is only supported by version 1.8.20 or higher. +If the operating system does not support the +.Xr fexecve 2 +system call, this setting has no effect. +.It group_plugin +A string containing a +.Nm sudoers +group plugin with optional arguments. +The string should consist of the plugin +path, either fully-qualified or relative to the +.Pa @PLUGINDIR@ +directory, followed by any configuration arguments the plugin requires. +These arguments (if any) will be passed to the plugin's initialization function. +If arguments are present, the string must be enclosed in double quotes +.Pq \&"" . +.Pp +For more information see +.Sx "GROUP PROVIDER PLUGINS" . +.It lecture +This option controls when a short lecture will be printed along with +the password prompt. +It has the following possible values: +.Bl -tag -width 6n +.It always +Always lecture the user. +.It never +Never lecture the user. +.It once +Only lecture the user the first time they run +.Nm sudo . +.El +.Pp +If no value is specified, a value of +.Em once +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em @lecture@ . +.It lecture_file +Path to a file containing an alternate +.Nm sudo +lecture that will be used in place of the standard lecture if the named +file exists. +By default, +.Nm sudo +uses a built-in lecture. +.It listpw +This option controls when a password will be required when a user runs +.Nm sudo +with the +.Fl l +option. +It has the following possible values: +.Bl -tag -width 8n +.It all +All the user's +.Em sudoers +file entries for the current host must have +the +.Li NOPASSWD +flag set to avoid entering a password. +.It always +The user must always enter a password to use the +.Fl l +option. +.It any +At least one of the user's +.Em sudoers +file entries for the current host +must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It never +The user need never enter a password to use the +.Fl l +option. +.El +.Pp +If no value is specified, a value of +.Em any +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em any . +.It logfile +Path to the +.Nm sudo +log file (not the syslog log file). +Setting a path turns on logging to a file; +negating this option turns it off. +By default, +.Nm sudo +logs via syslog. +.It mailerflags +Flags to use when invoking mailer. +Defaults to +.Fl t . +.It mailerpath +Path to mail program used to send warning mail. +Defaults to the path to sendmail found at configure time. +.It mailfrom +Address to use for the +.Dq from +address when sending warning and error mail. +The address should be enclosed in double quotes +.Pq \&"" +to protect against +.Nm sudo +interpreting the +.Li @ +sign. +Defaults to the name of the user running +.Nm sudo . +.It mailto +Address to send warning and error mail to. +The address should be enclosed in double quotes +.Pq \&"" +to protect against +.Nm sudo +interpreting the +.Li @ +sign. +Defaults to +.Li @mailto@ . +.It restricted_env_file +The +.Em restricted_env_file +option specifies the fully qualified path to a file containing variables +to be set in the environment of the program being run. +Entries in this file should either be of the form +.Dq Li VARIABLE=value +or +.Dq Li export VARIABLE=value . +The value may optionally be surrounded by single or double quotes. +Variables in this file are only added if the variable does not already +exist in the environment. +Unlike +.Em env_file , +the file's contents are not trusted and are processed in a manner +similar to that of the invoking user's environment. +If +.Em env_reset +is enabled, variables in the file will only be added if they are +matched by either the +.Em env_check +or +.Em env_keep +list. +If +.Em env_reset +is disabled, variables in the file are added as long as they +are not matched by the +.Em env_delete +list. +In either case, the contents of +.Em restricted_env_file +are processed before the contents of +.Em env_file . +.It secure_path +Path used for every command run from +.Nm sudo . +If you don't trust the +people running +.Nm sudo +to have a sane +.Ev PATH +environment variable you may want to use this. +Another use is if you want to have the +.Dq root path +be separate from the +.Dq user path . +Users in the group specified by the +.Em exempt_group +option are not affected by +.Em secure_path . +This option is @secure_path@ by default. +.It syslog +Syslog facility if syslog is being used for logging (negate to +disable syslog logging). +Defaults to +.Li @logfac@ . +.Pp +The following syslog facilities are supported: +.Sy authpriv +(if your +OS supports it), +.Sy auth , +.Sy daemon , +.Sy user , +.Sy local0 , +.Sy local1 , +.Sy local2 , +.Sy local3 , +.Sy local4 , +.Sy local5 , +.Sy local6 , +and +.Sy local7 . +.It syslog_badpri +Syslog priority to use when the user is not allowed to run a command or +when authentication is unsuccessful. +Defaults to +.Li @badpri@ . +.Pp +The following syslog priorities are supported: +.Sy alert , +.Sy crit , +.Sy debug , +.Sy emerg , +.Sy err , +.Sy info , +.Sy notice , +.Sy warning , +and +.Sy none . +Negating the option or setting it to a value of +.Sy none +will disable logging of unsuccessful commands. +.It syslog_goodpri +Syslog priority to use when the user is allowed to run a command and +authentication is successful. +Defaults to +.Li @goodpri@ . +.Pp +See +.Em syslog_badpri +for the list of supported syslog priorities. +Negating the option or setting it to a value of +.Sy none +will disable logging of successful commands. +.It verifypw +This option controls when a password will be required when a user runs +.Nm sudo +with the +.Fl v +option. +It has the following possible values: +.Bl -tag -width 6n +.It all +All the user's +.Em sudoers +file entries for the current host must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It always +The user must always enter a password to use the +.Fl v +option. +.It any +At least one of the user's +.Em sudoers +file entries for the current host must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It never +The user need never enter a password to use the +.Fl v +option. +.El +.Pp +If no value is specified, a value of +.Em all +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em all . +.El +.Pp +.Sy Lists that can be used in a boolean context : +.Bl -tag -width 16n +.It env_check +Environment variables to be removed from the user's environment +unless they are considered +.Dq safe . +For all variables except +.Li TZ , +.Dq safe +means that the variable's value does not contain any +.Ql % +or +.Ql / +characters. +This can be used to guard against printf-style format vulnerabilities +in poorly-written programs. +The +.Li TZ +variable is considered unsafe if any of the following are true: +.Bl -bullet -width 1n +.It +It consists of a fully-qualified path name, +optionally prefixed with a colon +.Pq Ql :\& , +that does not match the location of the +.Pa zoneinfo +directory. +.It +It contains a +.Pa .. +path element. +.It +It contains white space or non-printable characters. +.It +It is longer than the value of +.Li PATH_MAX . +.El +.Pp +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using +the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +Regardless of whether the +.Li env_reset +option is enabled or disabled, variables specified by +.Li env_check +will be preserved in the environment if they pass the aforementioned check. +The global list of environment variables to check is displayed when +.Nm sudo +is run by root with +the +.Fl V +option. +.It env_delete +Environment variables to be removed from the user's environment when the +.Em env_reset +option is not in effect. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +The global list of environment variables to remove is displayed when +.Nm sudo +is run by root with the +.Fl V +option. +Note that many operating systems will remove potentially dangerous +variables from the environment of any setuid process (such as +.Nm sudo ) . +.It env_keep +Environment variables to be preserved in the user's environment when the +.Em env_reset +option is in effect. +This allows fine-grained control over the environment +.Nm sudo Ns -spawned +processes will receive. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +The global list of variables to keep +is displayed when +.Nm sudo +is run by root with the +.Fl V +option. +.El +.Sh GROUP PROVIDER PLUGINS +The +.Nm +plugin supports its own plugin interface to allow non-Unix +group lookups which can query a group source other +than the standard Unix group database. +This can be used to implement support for the +.Li nonunix_group +syntax described earlier. +.Pp +Group provider plugins are specified via the +.Em group_plugin +Defaults setting. +The argument to +.Em group_plugin +should consist of the plugin path, either fully-qualified or relative to the +.Pa @PLUGINDIR@ +directory, followed by any configuration options the plugin requires. +These options (if specified) will be passed to the plugin's initialization +function. +If options are present, the string must be enclosed in double quotes +.Pq \&"" . +.Pp +The following group provider plugins are installed by default: +.Bl -tag -width 8n +.It group_file +The +.Em group_file +plugin supports an alternate group file that uses the same syntax as the +.Pa /etc/group +file. +The path to the group file should be specified as an option +to the plugin. +For example, if the group file to be used is +.Pa /etc/sudo-group : +.Bd -literal +Defaults group_plugin="group_file.so /etc/sudo-group" +.Ed +.It system_group +The +.Em system_group +plugin supports group lookups via the standard C library functions +.Fn getgrnam +and +.Fn getgrid . +This plugin can be used in instances where the user belongs to +groups not present in the user's supplemental group vector. +This plugin takes no options: +.Bd -literal +Defaults group_plugin=system_group.so +.Ed +.El +.Pp +The group provider plugin API is described in detail in +.Xr sudo_plugin @mansectform@ . +.Sh LOG FORMAT +.Nm +can log events using either +.Xr syslog 3 +or a simple log file. +The log format is almost identical in both cases. +.Ss Accepted command log entries +Commands that sudo runs are logged using the following format (split +into multiple lines for readability): +.Bd -literal -offset 4n +date hostname progname: username : TTY=ttyname ; PWD=cwd ; \e + USER=runasuser ; GROUP=runasgroup ; TSID=logid ; \e + ENV=env_vars COMMAND=command +.Ed +.Pp +Where the fields are as follows: +.Bl -tag -width 12n +.It date +The date the command was run. +Typically, this is in the format +.Dq MMM, DD, HH:MM:SS . +If logging via +.Xr syslog 3 , +the actual date format is controlled by the syslog daemon. +If logging to a file and the +.Em log_year +option is enabled, +the date will also include the year. +.It hostname +The name of the host +.Nm sudo +was run on. +This field is only present when logging via +.Xr syslog 3 . +.It progname +The name of the program, usually +.Em sudo +or +.Em sudoedit . +This field is only present when logging via +.Xr syslog 3 . +.It username +The login name of the user who ran +.Nm sudo . +.It ttyname +The short name of the terminal (e.g., +.Dq console , +.Dq tty01 , +or +.Dq pts/0 ) +.Nm sudo +was run on, or +.Dq unknown +if there was no terminal present. +.It cwd +The current working directory that +.Nm sudo +was run in. +.It runasuser +The user the command was run as. +.It runasgroup +The group the command was run as if one was specified on the command line. +.It logid +An I/O log identifier that can be used to replay the command's output. +This is only present when the +.Em log_input +or +.Em log_output +option is enabled. +.It env_vars +A list of environment variables specified on the command line, +if specified. +.It command +The actual command that was executed. +.El +.Pp +Messages are logged using the locale specified by +.Em sudoers_locale , +which defaults to the +.Dq Li C +locale. +.Ss Denied command log entries +If the user is not allowed to run the command, the reason for the denial +will follow the user name. +Possible reasons include: +.Bl -tag -width 4 +.It user NOT in sudoers +The user is not listed in the +.Em sudoers +file. +.It user NOT authorized on host +The user is listed in the +.Em sudoers +file but is not allowed to run commands on the host. +.It command not allowed +The user is listed in the +.Em sudoers +file for the host but they are not allowed to run the specified command. +.It 3 incorrect password attempts +The user failed to enter their password after 3 tries. +The actual number of tries will vary based on the number of +failed attempts and the value of the +.Em passwd_tries +option. +.It a password is required +.Nm sudo Ns 's +.Fl n +option was specified but a password was required. +.It sorry, you are not allowed to set the following environment variables +The user specified environment variables on the command line that +were not allowed by +.Em sudoers . +.El +.Ss Error log entries +If an error occurs, +.Nm +will log a message and, in most cases, send a message to the +administrator via email. +Possible errors include: +.Bl -tag -width 4 +.It parse error in @sysconfdir@/sudoers near line N +.Nm +encountered an error when parsing the specified file. +In some cases, the actual error may be one line above or below the +line number listed, depending on the type of error. +.It problem with defaults entries +The +.Em sudoers +file contains one or more unknown Defaults settings. +This does not prevent +.Nm sudo +from running, but the +.Em sudoers +file should be checked using +.Nm visudo . +.It timestamp owner (username): \&No such user +The time stamp directory owner, as specified by the +.Em timestampowner +setting, could not be found in the password database. +.It unable to open/read @sysconfdir@/sudoers +The +.Em sudoers +file could not be opened for reading. +This can happen when the +.Em sudoers +file is located on a remote file system that maps user ID 0 to +a different value. +Normally, +.Nm +tries to open the +.Em sudoers +file using group permissions to avoid this problem. +Consider either changing the ownership of +.Pa @sysconfdir@/sudoers +or adding an argument like +.Dq sudoers_uid=N +(where +.Sq N +is the user ID that owns the +.Em sudoers +file) to the end of the +.Nm +.Li Plugin +line in the +.Xr sudo.conf @mansectform@ +file. +.It unable to stat @sysconfdir@/sudoers +The +.Pa @sysconfdir@/sudoers +file is missing. +.It @sysconfdir@/sudoers is not a regular file +The +.Pa @sysconfdir@/sudoers +file exists but is not a regular file or symbolic link. +.It @sysconfdir@/sudoers is owned by uid N, should be 0 +The +.Em sudoers +file has the wrong owner. +If you wish to change the +.Em sudoers +file owner, please add +.Dq sudoers_uid=N +(where +.Sq N +is the user ID that owns the +.Em sudoers +file) to the +.Nm +.Li Plugin +line in the +.Xr sudo.conf @mansectform@ +file. +.It @sysconfdir@/sudoers is world writable +The permissions on the +.Em sudoers +file allow all users to write to it. +The +.Em sudoers +file must not be world-writable, the default file mode +is 0440 (readable by owner and group, writable by none). +The default mode may be changed via the +.Dq sudoers_mode +option to the +.Nm +.Li Plugin +line in the +.Xr sudo.conf @mansectform@ +file. +.It @sysconfdir@/sudoers is owned by gid N, should be 1 +The +.Em sudoers +file has the wrong group ownership. +If you wish to change the +.Em sudoers +file group ownership, please add +.Dq sudoers_gid=N +(where +.Sq N +is the group ID that owns the +.Em sudoers +file) to the +.Nm +.Li Plugin +line in the +.Xr sudo.conf @mansectform@ +file. +.It unable to open @rundir@/ts/username +.Nm sudoers +was unable to read or create the user's time stamp file. +This can happen when +.Em timestampowner +is set to a user other than root and the mode on +.Pa @rundir@ +is not searchable by group or other. +The default mode for +.Pa @rundir@ +is 0711. +.It unable to write to @rundir@/ts/username +.Nm sudoers +was unable to write to the user's time stamp file. +.It @rundir@/ts is owned by uid X, should be Y +The time stamp directory is owned by a user other than +.Em timestampowner . +This can occur when the value of +.Em timestampowner +has been changed. +.Nm sudoers +will ignore the time stamp directory until the owner is corrected. +.It @rundir@/ts is group writable +The time stamp directory is group-writable; it should be writable only by +.Em timestampowner . +The default mode for the time stamp directory is 0700. +.Nm sudoers +will ignore the time stamp directory until the mode is corrected. +.El +.Ss Notes on logging via syslog +By default, +.Nm sudoers +logs messages via +.Xr syslog 3 . +The +.Em date , +.Em hostname , +and +.Em progname +fields are added by the system's +.Fn syslog +function, not +.Nm +itself. +As such, they may vary in format on different systems. +.Pp +The maximum size of syslog messages varies from system to system. +The +.Em syslog_maxlen +setting can be used to change the maximum syslog message size +from the default value of 980 bytes. +For more information, see the description of +.Em syslog_maxlen . +.Ss Notes on logging to a file +If the +.Em logfile +option is set, +.Nm sudoers +will log to a local file, such as +.Pa /var/log/sudo . +When logging to a file, +.Nm sudoers +uses a format similar to +.Xr syslog 3 , +with a few important differences: +.Bl -enum +.It +The +.Em progname +and +.Em hostname +fields are not present. +.It +If the +.Em log_year +option is enabled, +the date will also include the year. +.It +Lines that are longer than +.Em loglinelen +characters (80 by default) are word-wrapped and continued on the +next line with a four character indent. +This makes entries easier to read for a human being, but makes it +more difficult to use +.Xr grep 1 +on the log files. +If the +.Em loglinelen +option is set to 0 (or negated with a +.Ql \&! ) , +word wrap will be disabled. +.El +.Sh I/O LOG FILES +When I/O logging is enabled, +.Nm sudo +will run the command in a pseudo-tty and log all user input and/or output, +depending on which options are enabled. +I/O is logged to the directory specified by the +.Em iolog_dir +option +.Po +.Pa @iolog_dir@ +by default +.Pc +using a unique session ID that is included in the +.Nm sudo +log line, prefixed with +.Dq Li TSID= . +The +.Em iolog_file +option may be used to control the format of the session ID. +.Pp +Each I/O log is stored in a separate directory that contains the +following files: +.Bl -tag -width 8n +.It Pa log +a text file containing the time the command was run, the name of the user +who ran +.Nm sudo , +the name of the target user, the name of the target group (optional), +the terminal that +.Nm sudo +was run from, the number of rows and columns of the terminal, +the working directory the command was run from and the path name of +the command itself (with arguments if present) +.It Pa timing +a log of the amount of time between, and the number of bytes in, each +I/O log entry (used for session playback) +.It Pa ttyin +input from the user's tty (what the user types) +.It Pa stdin +input from a pipe or file +.It Pa ttyout +output from the pseudo-tty (what the command writes to the screen) +.It Pa stdout +standard output to a pipe or redirected to a file +.It Pa stderr +standard error to a pipe or redirected to a file +.El +.Pp +All files other than +.Pa log +are compressed in gzip format unless the +.Em compress_io +flag has been disabled. +Due to buffering, it is not normally possible to display the I/O logs in +real-time as the program is executing +The I/O log data will not be complete until the program run by +.Nm sudo +has exited or has been terminated by a signal. +The +.Em iolog_flush +flag can be used to disable buffering, in which case I/O log data +is written to disk as soon as it is available. +The output portion of an I/O log file can be viewed with the +.Xr sudoreplay @mansectsu@ +utility, which can also be used to list or search the available logs. +.Pp +Note that user input may contain sensitive information such as +passwords (even if they are not echoed to the screen), which will +be stored in the log file unencrypted. +In most cases, logging the command output via +.Em log_output +or +.Li LOG_OUTPUT +is all that is required. +.Pp +Since each session's I/O logs are stored in a separate directory, +traditional log rotation utilities cannot be used to limit the +number of I/O logs. +The simplest way to limit the number of I/O is by setting the +.Em maxseq +option to the maximum number of logs you wish to store. +Once the I/O log sequence number reaches +.Em maxseq , +it will be reset to zero and +.Nm +will truncate and re-use any existing I/O logs. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +Sudo front end configuration +.It Pa @sysconfdir@/sudoers +List of who can run what +.It Pa /etc/group +Local groups file +.It Pa /etc/netgroup +List of network groups +.It Pa @iolog_dir@ +I/O log files +.It Pa @rundir@/ts +Directory containing time stamps for the +.Nm sudoers +security policy +.It Pa @vardir@/lectured +Directory containing lecture status files for the +.Nm sudoers +security policy +.It Pa /etc/environment +Initial environment for +.Fl i +mode on AIX and Linux systems +.El +.Sh EXAMPLES +Below are example +.Em sudoers +file entries. +Admittedly, some of these are a bit contrived. +First, we allow a few environment variables to pass and then define our +.Em aliases : +.Bd -literal +# Run X applications through sudo; HOME is used to find the +# .Xauthority file. Note that other programs use HOME to find +# configuration files and this may lead to privilege escalation! +Defaults env_keep += "DISPLAY HOME" + +# User alias specification +User_Alias FULLTIMERS = millert, mikef, dowdy +User_Alias PARTTIMERS = bostley, jwfox, crawl +User_Alias WEBMASTERS = will, wendy, wim + +# Runas alias specification +Runas_Alias OP = root, operator +Runas_Alias DB = oracle, sybase +Runas_Alias ADMINGRP = adm, oper + +# Host alias specification +Host_Alias SPARC = bigtime, eclipse, moet, anchor :\e + SGI = grolsch, dandelion, black :\e + ALPHA = widget, thalamus, foobar :\e + HPPA = boa, nag, python +Host_Alias CUNETS = 128.138.0.0/255.255.0.0 +Host_Alias CSNETS = 128.138.243.0, 128.138.204.0/24, 128.138.242.0 +Host_Alias SERVERS = master, mail, www, ns +Host_Alias CDROM = orion, perseus, hercules + +# Cmnd alias specification +Cmnd_Alias DUMPS = /usr/bin/mt, /usr/sbin/dump, /usr/sbin/rdump,\e + /usr/sbin/restore, /usr/sbin/rrestore,\e + sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ== \e + /home/operator/bin/start_backups +Cmnd_Alias KILL = /usr/bin/kill +Cmnd_Alias PRINTING = /usr/sbin/lpc, /usr/bin/lprm +Cmnd_Alias SHUTDOWN = /usr/sbin/shutdown +Cmnd_Alias HALT = /usr/sbin/halt +Cmnd_Alias REBOOT = /usr/sbin/reboot +Cmnd_Alias SHELLS = /usr/bin/sh, /usr/bin/csh, /usr/bin/ksh,\e + /usr/local/bin/tcsh, /usr/bin/rsh,\e + /usr/local/bin/zsh +Cmnd_Alias SU = /usr/bin/su +Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less +.Ed +.Pp +Here we override some of the compiled in default values. +We want +.Nm sudo +to log via +.Xr syslog 3 +using the +.Em auth +facility in all cases. +We don't want to subject the full time staff to the +.Nm sudo +lecture, user +.Sy millert +need not give a password, and we don't want to reset the +.Ev LOGNAME +or +.Ev USER +environment variables when running commands as root. +Additionally, on the machines in the +.Em SERVERS +.Li Host_Alias , +we keep an additional local log file and make sure we log the year +in each log line since the log entries will be kept around for several years. +Lastly, we disable shell escapes for the commands in the PAGERS +.Li Cmnd_Alias +.Po +.Pa /usr/bin/more , +.Pa /usr/bin/pg +and +.Pa /usr/bin/less +.Pc . +Note that this will not effectively constrain users with +.Nm sudo +.Sy ALL +privileges. +.Bd -literal +# Override built-in defaults +Defaults syslog=auth +Defaults>root !set_logname +Defaults:FULLTIMERS !lecture +Defaults:millert !authenticate +Defaults@SERVERS log_year, logfile=/var/log/sudo.log +Defaults!PAGERS noexec +.Ed +.Pp +The +.Em User specification +is the part that actually determines who may run what. +.Bd -literal +root ALL = (ALL) ALL +%wheel ALL = (ALL) ALL +.Ed +.Pp +We let +.Sy root +and any user in group +.Sy wheel +run any command on any host as any user. +.Bd -literal +FULLTIMERS ALL = NOPASSWD: ALL +.Ed +.Pp +Full time sysadmins +.Po +.Sy millert , +.Sy mikef , +and +.Sy dowdy +.Pc +may run any command on any host without authenticating themselves. +.Bd -literal +PARTTIMERS ALL = ALL +.Ed +.Pp +Part time sysadmins +.Sy bostley , +.Sy jwfox , +and +.Sy crawl ) +may run any command on any host but they must authenticate themselves +first (since the entry lacks the +.Li NOPASSWD +tag). +.Bd -literal +jack CSNETS = ALL +.Ed +.Pp +The user +.Sy jack +may run any command on the machines in the +.Em CSNETS +alias (the networks +.Li 128.138.243.0 , +.Li 128.138.204.0 , +and +.Li 128.138.242.0 ) . +Of those networks, only +.Li 128.138.204.0 +has an explicit netmask (in CIDR notation) indicating it is a class C network. +For the other networks in +.Em CSNETS , +the local machine's netmask will be used during matching. +.Bd -literal +lisa CUNETS = ALL +.Ed +.Pp +The user +.Sy lisa +may run any command on any host in the +.Em CUNETS +alias (the class B network +.Li 128.138.0.0 ) . +.Bd -literal +operator ALL = DUMPS, KILL, SHUTDOWN, HALT, REBOOT, PRINTING,\e + sudoedit /etc/printcap, /usr/oper/bin/ +.Ed +.Pp +The +.Sy operator +user may run commands limited to simple maintenance. +Here, those are commands related to backups, killing processes, the +printing system, shutting down the system, and any commands in the +directory +.Pa /usr/oper/bin/ . +Note that one command in the +.Li DUMPS +Cmnd_Alias includes a sha224 digest, +.Pa /home/operator/bin/start_backups . +This is because the directory containing the script is writable by the +operator user. +If the script is modified (resulting in a digest mismatch) it will no longer +be possible to run it via +.Nm sudo . +.Bd -literal +joe ALL = /usr/bin/su operator +.Ed +.Pp +The user +.Sy joe +may only +.Xr su 1 +to operator. +.Bd -literal +pete HPPA = /usr/bin/passwd [A-Za-z]*, !/usr/bin/passwd *root* + +%opers ALL = (: ADMINGRP) /usr/sbin/ +.Ed +.Pp +Users in the +.Sy opers +group may run commands in +.Pa /usr/sbin/ +as themselves +with any group in the +.Em ADMINGRP +.Li Runas_Alias +(the +.Sy adm +and +.Sy oper +groups). +.Pp +The user +.Sy pete +is allowed to change anyone's password except for +root on the +.Em HPPA +machines. +Because command line arguments are matched as a single, +concatenated string, the +.Ql * +wildcard will match +.Em multiple +words. +This example assumes that +.Xr passwd 1 +does not take multiple user names on the command line. +Note that on GNU systems, options to +.Xr passwd 1 +may be specified after the user argument. +As a result, this rule will also allow: +.Bd -literal -offset 4n +passwd username --expire +.Ed +.Pp +which may not be desirable. +.Bd -literal +bob SPARC = (OP) ALL : SGI = (OP) ALL +.Ed +.Pp +The user +.Sy bob +may run anything on the +.Em SPARC +and +.Em SGI +machines as any user listed in the +.Em OP +.Li Runas_Alias +.Po +.Sy root +and +.Sy operator . +.Pc +.Bd -literal +jim +biglab = ALL +.Ed +.Pp +The user +.Sy jim +may run any command on machines in the +.Em biglab +netgroup. +.Nm sudo +knows that +.Dq biglab +is a netgroup due to the +.Ql + +prefix. +.Bd -literal ++secretaries ALL = PRINTING, /usr/bin/adduser, /usr/bin/rmuser +.Ed +.Pp +Users in the +.Sy secretaries +netgroup need to help manage the printers as well as add and remove users, +so they are allowed to run those commands on all machines. +.Bd -literal +fred ALL = (DB) NOPASSWD: ALL +.Ed +.Pp +The user +.Sy fred +can run commands as any user in the +.Em DB +.Li Runas_Alias +.Po +.Sy oracle +or +.Sy sybase +.Pc +without giving a password. +.Bd -literal +john ALPHA = /usr/bin/su [!-]*, !/usr/bin/su *root* +.Ed +.Pp +On the +.Em ALPHA +machines, user +.Sy john +may su to anyone except root but he is not allowed to specify any options +to the +.Xr su 1 +command. +.Bd -literal +jen ALL, !SERVERS = ALL +.Ed +.Pp +The user +.Sy jen +may run any command on any machine except for those in the +.Em SERVERS +.Li Host_Alias +(master, mail, www and ns). +.Bd -literal +jill SERVERS = /usr/bin/, !SU, !SHELLS +.Ed +.Pp +For any machine in the +.Em SERVERS +.Li Host_Alias , +.Sy jill +may run +any commands in the directory +.Pa /usr/bin/ +except for those commands +belonging to the +.Em SU +and +.Em SHELLS +.Li Cmnd_Aliases . +While not specifically mentioned in the rule, the commands in the +.Em PAGERS +.Li Cmnd_Alias +all reside in +.Pa /usr/bin +and have the +.Em noexec +option set. +.Bd -literal +steve CSNETS = (operator) /usr/local/op_commands/ +.Ed +.Pp +The user +.Sy steve +may run any command in the directory /usr/local/op_commands/ +but only as user operator. +.Bd -literal +matt valkyrie = KILL +.Ed +.Pp +On his personal workstation, valkyrie, +.Sy matt +needs to be able to kill hung processes. +.Bd -literal +WEBMASTERS www = (www) ALL, (root) /usr/bin/su www +.Ed +.Pp +On the host www, any user in the +.Em WEBMASTERS +.Li User_Alias +(will, wendy, and wim), may run any command as user www (which owns the +web pages) or simply +.Xr su 1 +to www. +.Bd -literal +ALL CDROM = NOPASSWD: /sbin/umount /CDROM,\e + /sbin/mount -o nosuid\e,nodev /dev/cd0a /CDROM +.Ed +.Pp +Any user may mount or unmount a CD-ROM on the machines in the CDROM +.Li Host_Alias +(orion, perseus, hercules) without entering a password. +This is a bit tedious for users to type, so it is a prime candidate +for encapsulating in a shell script. +.Sh SECURITY NOTES +.Ss Limitations of the So !\& Sc operator +It is generally not effective to +.Dq subtract +commands from +.Sy ALL +using the +.Ql !\& +operator. +A user can trivially circumvent this by copying the desired command +to a different name and then executing that. +For example: +.Bd -literal +bill ALL = ALL, !SU, !SHELLS +.Ed +.Pp +Doesn't really prevent +.Sy bill +from running the commands listed in +.Em SU +or +.Em SHELLS +since he can simply copy those commands to a different name, or use +a shell escape from an editor or other program. +Therefore, these kind of restrictions should be considered +advisory at best (and reinforced by policy). +.Pp +In general, if a user has sudo +.Sy ALL +there is nothing to prevent them from creating their own program that gives +them a root shell (or making their own copy of a shell) regardless of any +.Ql !\& +elements in the user specification. +.Ss Security implications of Em fast_glob +If the +.Em fast_glob +option is in use, it is not possible to reliably negate commands where the +path name includes globbing (aka wildcard) characters. +This is because the C library's +.Xr fnmatch 3 +function cannot resolve relative paths. +While this is typically only an inconvenience for rules that grant privileges, +it can result in a security issue for rules that subtract or revoke privileges. +.Pp +For example, given the following +.Em sudoers +file entry: +.Bd -literal +john ALL = /usr/bin/passwd [a-zA-Z0-9]*, /usr/bin/chsh [a-zA-Z0-9]*,\e + /usr/bin/chfn [a-zA-Z0-9]*, !/usr/bin/* root +.Ed +.Pp +User +.Sy john +can still run +.Li /usr/bin/passwd root +if +.Em fast_glob +is enabled by changing to +.Pa /usr/bin +and running +.Li ./passwd root +instead. +.Ss Preventing shell escapes +Once +.Nm sudo +executes a program, that program is free to do whatever +it pleases, including run other programs. +This can be a security issue since it is not uncommon for a program to +allow shell escapes, which lets a user bypass +.Nm sudo Ns 's +access control and logging. +Common programs that permit shell escapes include shells (obviously), +editors, paginators, mail and terminal programs. +.Pp +There are two basic approaches to this problem: +.Bl -tag -width 8n +.It restrict +Avoid giving users access to commands that allow the user to run +arbitrary commands. +Many editors have a restricted mode where shell +escapes are disabled, though +.Nm sudoedit +is a better solution to +running editors via +.Nm sudo . +Due to the large number of programs that +offer shell escapes, restricting users to the set of programs that +do not is often unworkable. +.It noexec +Many systems that support shared libraries have the ability to +override default library functions by pointing an environment +variable (usually +.Ev LD_PRELOAD ) +to an alternate shared library. +On such systems, +.Nm sudo Ns 's +.Em noexec +functionality can be used to prevent a program run by +.Nm sudo +from executing any other programs. +Note, however, that this applies only to native dynamically-linked +executables. +Statically-linked executables and foreign executables +running under binary emulation are not affected. +.Pp +The +.Em noexec +feature is known to work on SunOS, Solaris, *BSD, +Linux, IRIX, Tru64 UNIX, macOS, HP-UX 11.x and AIX 5.3 and above. +It should be supported on most operating systems that support the +.Ev LD_PRELOAD +environment variable. +Check your operating system's manual pages for the dynamic linker +(usually ld.so, ld.so.1, dyld, dld.sl, rld, or loader) to see if +.Ev LD_PRELOAD +is supported. +.Pp +On Solaris 10 and higher, +.Em noexec +uses Solaris privileges instead of the +.Ev LD_PRELOAD +environment variable. +.Pp +To enable +.Em noexec +for a command, use the +.Li NOEXEC +tag as documented +in the User Specification section above. +Here is that example again: +.Bd -literal +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.Ed +.Pp +This allows user +.Sy aaron +to run +.Pa /usr/bin/more +and +.Pa /usr/bin/vi +with +.Em noexec +enabled. +This will prevent those two commands from +executing other commands (such as a shell). +If you are unsure whether or not your system is capable of supporting +.Em noexec +you can always just try it out and check whether shell escapes work when +.Em noexec +is enabled. +.El +.Pp +Note that restricting shell escapes is not a panacea. +Programs running as root are still capable of many potentially hazardous +operations (such as changing or overwriting files) that could lead +to unintended privilege escalation. +In the specific case of an editor, a safer approach is to give the +user permission to run +.Nm sudoedit +(see below). +.Ss Secure editing +The +.Nm sudoers +plugin includes +.Nm sudoedit +support which allows users to securely edit files with the editor +of their choice. +As +.Nm sudoedit +is a built-in command, it must be specified in the +.Em sudoers +file without a leading path. +However, it may take command line arguments just as a normal command does. +Wildcards used in +.Em sudoedit +command line arguments are expected to be path names, so a forward slash +.Pq Ql / +will not be matched by a wildcard. +.Pp +Unlike other +.Nm sudo +commands, the editor is run with the permissions of the invoking +user and with the environment unmodified. +More information may be found in the description of the +.Fl e +option in +.Xr sudo @mansectsu@ . +.Pp +For example, to allow user operator to edit the +.Dq message of the day +file: +.Bd -literal -offset indent +operator sudoedit /etc/motd +.Ed +.Pp +The operator user then runs +.Nm sudoedit +as follows: +.Bd -literal -offset indent +$ sudoedit /etc/motd +.Ed +.Pp +The editor will run as the operator user, not root, on a temporary copy of +.Pa /etc/motd . +After the file has been edited, +.Pa /etc/motd +will be updated with the contents of the temporary copy. +.Pp +Users should +.Em never +be granted +.Nm sudoedit +permission to edit a file that resides in a directory the user +has write access to, either directly or via a wildcard. +If the user has write access to the directory it is possible to +replace the legitimate file with a link to another file, +allowing the editing of arbitrary files. +To prevent this, starting with version 1.8.16, symbolic links will +not be followed in writable directories and +.Nm sudoedit +will refuse to edit a file located in a writable directory +unless the +.Em sudoedit_checkdir +option has been disabled or the invoking user is root. +Additionally, in version 1.8.15 and higher, +.Nm sudoedit +will refuse to open a symbolic link unless either the +.Em sudoedit_follow +option is enabled or the +.Em sudoedit +command is prefixed with the +.Li FOLLOW +tag in the +.Em sudoers +file. +.Ss Time stamp file checks +.Nm sudoers +will check the ownership of its time stamp directory +.Po +.Pa @rundir@/ts +by default +.Pc +and ignore the directory's contents if it is not owned by root or +if it is writable by a user other than root. +Older versions of +.Nm sudo +stored time stamp files in +.Pa /tmp ; +this is no longer recommended as it may be possible for a user +to create the time stamp themselves on systems that allow +unprivileged users to change the ownership of files they create. +.Pp +While the time stamp directory +.Em should +be cleared at reboot time, not all systems contain a +.Pa /run +or +.Pa /var/run +directory. +To avoid potential problems, +.Nm sudoers +will ignore time stamp files that date from before the machine booted +on systems where the boot time is available. +.Pp +Some systems with graphical desktop environments allow unprivileged +users to change the system clock. +Since +.Nm sudoers +relies on the system clock for time stamp validation, it may be +possible on such systems for a user to run +.Nm sudo +for longer than +.Em timestamp_timeout +by setting the clock back. +To combat this, +.Nm sudoers +uses a monotonic clock (which never moves backwards) for its time stamps +if the system supports it. +.Pp +.Nm sudoers +will not honor time stamps set far in the future. +Time stamps with a date greater than current_time + 2 * +.Li TIMEOUT +will be ignored and +.Nm sudoers +will log and complain. +.Pp +If the +.Em timestamp_type +option is set to +.Dq tty , +the time stamp record includes the device number of the terminal +the user authenticated with. +This provides per-terminal granularity but time stamp records may still +outlive the user's session. +.Pp +Unless the +.Em timestamp_type +option is set to +.Dq global , +the time stamp record also includes the session ID of the process +that last authenticated. +This prevents processes in different terminal sessions from using +the same time stamp record. +On systems where a process's start time can be queried, +the start time of the session leader +is recorded in the time stamp record. +If no terminal is present or the +.Em timestamp_type +option is set to +.Dq ppid , +the start time of the parent process is used instead. +In most cases this will prevent a time stamp record from being re-used +without the user entering a password when logging out and back in again. +.Sh DEBUGGING +Versions 1.8.4 and higher of the +.Nm +plugin support a flexible debugging framework that can help track +down what the plugin is doing internally if there is a problem. +This can be configured in the +.Xr sudo.conf @mansectform@ +file. +.Pp +The +.Nm +plugin uses the same debug flag format as the +.Nm sudo +front-end: +.Em subsystem Ns @ Ns Em priority . +.Pp +The priorities used by +.Nm , +in order of decreasing severity, +are: +.Em crit , err , warn , notice , diag , info , trace +and +.Em debug . +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +.Em notice +would include debug messages logged at +.Em notice +and higher. +.Pp +The following subsystems are used by the +.Nm +plugin: +.Bl -tag -width 8n +.It Em alias +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias +and +.Li Cmnd_Alias +processing +.It Em all +matches every subsystem +.It Em audit +BSM and Linux audit code +.It Em auth +user authentication +.It Em defaults +.Em sudoers +file +.Em Defaults +settings +.It Em env +environment handling +.It Em ldap +LDAP-based sudoers +.It Em logging +logging support +.It Em match +matching of users, groups, hosts and netgroups in the +.Em sudoers +file +.It Em netif +network interface handling +.It Em nss +network service switch handling in +.Nm sudoers +.It Em parser +.Em sudoers +file parsing +.It Em perms +permission setting +.It Em plugin +The equivalent of +.Em main +for the plugin. +.It Em pty +pseudo-tty related code +.It Em rbtree +redblack tree internals +.It Em sssd +SSSD-based sudoers +.It Em util +utility functions +.El +For example: +.Bd -literal +Debug sudo /var/log/sudo_debug match@info,nss@info +.Ed +.Pp +For more information, see the +.Xr sudo.conf @mansectform@ +manual. +.Sh SEE ALSO +.Xr ssh 1 , +.Xr su 1 , +.Xr fnmatch 3 , +.Xr glob 3 , +.Xr mktemp 3 , +.Xr strftime 3 , +.Xr sudo.conf @mansectform@ , +.Xr sudo_plugin @mansectform@ , +.Xr sudoers.ldap @mansectform@ , +.Xr sudoers_timestamp @mansectform@ , +.Xr sudo @mansectsu@ , +.Xr visudo @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh CAVEATS +The +.Em sudoers +file should +.Sy always +be edited by the +.Nm visudo +command which locks the file and does grammatical checking. +It is +imperative that the +.Em sudoers +file be free of syntax errors since +.Nm sudo +will not run with a syntactically incorrect +.Em sudoers +file. +.Pp +When using netgroups of machines (as opposed to users), if you +store fully qualified host name in the netgroup (as is usually the +case), you either need to have the machine's host name be fully qualified +as returned by the +.Li hostname +command or use the +.Em fqdn +option in +.Em sudoers . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers_timestamp.cat b/doc/sudoers_timestamp.cat new file mode 100644 index 0000000..cf87d70 --- /dev/null +++ b/doc/sudoers_timestamp.cat @@ -0,0 +1,201 @@ +SUDOERS_TIMESTAMP(4) File Formats Manual SUDOERS_TIMESTAMP(4) + +NNAAMMEE + ssuuddooeerrss__ttiimmeessttaammpp - Sudoers Time Stamp Format + +DDEESSCCRRIIPPTTIIOONN + The ssuuddooeerrss plugin uses per-user time stamp files for credential caching. + Once a user has been authenticated, they may use ssuuddoo without a password + for a short period of time (5 minutes unless overridden by the + _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t option). By default, ssuuddooeerrss uses a separate record + for each terminal, which means that a user's login sessions are + authenticated separately. The _t_i_m_e_s_t_a_m_p___t_y_p_e option can be used to + select the type of time stamp record ssuuddooeerrss will use. + + A multi-record time stamp file format was introduced in ssuuddoo 1.8.10 that + uses a single file per user. Previously, a separate file was used for + each user and terminal combination unless tty-based time stamps were + disabled. The new format is extensible and records of multiple types and + versions may coexist within the same file. + + All records, regardless of type or version, begin with a 16-bit version + number and a 16-bit record size. + + Time stamp records have the following structure: + + /* Time stamp entry types */ + #define TS_GLOBAL 0x01 /* not restricted by tty or ppid */ + #define TS_TTY 0x02 /* restricted by tty */ + #define TS_PPID 0x03 /* restricted by ppid */ + #define TS_LOCKEXCL 0x04 /* special lock record */ + + /* Time stamp flags */ + #define TS_DISABLED 0x01 /* entry disabled */ + #define TS_ANYUID 0x02 /* ignore uid, only valid in key */ + + struct timestamp_entry { + unsigned short version; /* version number */ + unsigned short size; /* entry size */ + unsigned short type; /* TS_GLOBAL, TS_TTY, TS_PPID */ + unsigned short flags; /* TS_DISABLED, TS_ANYUID */ + uid_t auth_uid; /* uid to authenticate as */ + pid_t sid; /* session ID associated with tty/ppid */ + struct timespec start_time; /* session/ppid start time */ + struct timespec ts; /* time stamp (CLOCK_MONOTONIC) */ + union { + dev_t ttydev; /* tty device number */ + pid_t ppid; /* parent pid */ + } u; + }; + + The timestamp_entry struct fields are as follows: + + version + The version number of the timestamp_entry struct. New entries are + created with a version number of 2. Records with different version + numbers may coexist in the same file but are not inter-operable. + + size The size of the record in bytes. + + type The record type, currently TS_GLOBAL, TS_TTY, or TS_PPID. + + flags + Zero or more record flags which can be bit-wise ORed together. + Supported flags are TS_DISABLED, for records disabled via ssuuddoo --kk + and TS_ANYUID, which is used only when matching records. + + auth_uid + The user ID that was used for authentication. Depending on the + value of the _r_o_o_t_p_w, _r_u_n_a_s_p_w and _t_a_r_g_e_t_p_w options, the user ID may + be that of the invoking user, the root user, the default runas user + or the target user. + + sid The ID of the user's terminal session, if present. The session ID + is only used when matching records of type TS_TTY. + + start_time + The start time of the session leader for records of type TS_TTY or + of the parent process for records of type TS_PPID. The _s_t_a_r_t___t_i_m_e + is used to help prevent re-use of a time stamp record after a user + has logged out. Not all systems support a method to easily + retrieve a process's start time. The _s_t_a_r_t___t_i_m_e field was added in + ssuuddooeerrss version 1.8.22 for the second revision of the + timestamp_entry struct. + + ts The actual time stamp. A monotonic time source (which does not + move backward) is used if the system supports it. Where possible, + ssuuddooeerrss uses a monotonic timer that increments even while the + system is suspended. The value of _t_s is updated each time a + command is run via ssuuddoo. If the difference between _t_s and the + current time is less than the value of the _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t + option, no password is required. + + u.ttydev + The device number of the terminal associated with the session for + records of type TS_TTY. + + u.ppid + The ID of the parent process for records of type TS_PPID. + +LLOOCCKKIINNGG + In ssuuddooeerrss versions 1.8.10 through 1.8.14, the entire time stamp file was + locked for exclusive access when reading or writing to the file. + Starting in ssuuddooeerrss 1.8.15, individual records are locked in the time + stamp file instead of the entire file and the lock is held for a longer + period of time. This scheme is described below. + + The first record in the time stamp file is of type TS_LOCKEXCL and is + used as a _l_o_c_k record to prevent more than one ssuuddoo process from adding a + new record at the same time. Once the desired time stamp record has been + located or created (and locked), the TS_LOCKEXCL record is unlocked. The + lock on the individual time stamp record, however, is held until + authentication is complete. This allows ssuuddooeerrss to avoid prompting for a + password multiple times when it is used more than once in a pipeline. + + Records of type TS_GLOBAL cannot be locked for a long period of time + since doing so would interfere with other ssuuddoo processes. Instead, a + separate lock record is used to prevent multiple ssuuddoo processes using the + same terminal (or parent process ID) from prompting for a password as the + same time. + +SSEEEE AALLSSOO + sudoers(4), sudo(1m) + +HHIISSTTOORRYY + Originally, ssuuddoo used a single zero-length file per user and the file's + modification time was used as the time stamp. Later versions of ssuuddoo + added restrictions on the ownership of the time stamp files and directory + as well as sanity checks on the time stamp itself. Notable changes were + introduced in the following ssuuddoo versions: + + 1.4.0 + Support for tty-based time stamp file was added by appending the + terminal name to the time stamp file name. + + 1.6.2 + The time stamp file was replaced by a per-user directory which + contained any tty-based time stamp files. + + 1.6.3p2 + The target user name was added to the time stamp file name when the + _t_a_r_g_e_t_p_w option was set. + + 1.7.3 + Information about the terminal device was stored in tty-based time + stamp files for sanity checking. This included the terminal device + numbers, inode number and, on systems where it was not updated when + the device was written to, the inode change time. This helped + prevent re-use of the time stamp file after logout. + + 1.8.6p7 + The terminal session ID was added to tty-based time stamp files to + prevent re-use of the time stamp by the same user in a different + terminal session. It also helped prevent re-use of the time stamp + file on systems where the terminal device's inode change time was + updated by writing. + + 1.8.10 + A new, multi-record time stamp file format was introduced that uses + a single file per user. The terminal device's change time was not + included since most systems now update the change time after a + write is performed as required by POSIX. + + 1.8.15 + Individual records are locked in the time stamp file instead of the + entire file and the lock is held until authentication is complete. + + 1.8.22 + The start time of the terminal session leader or parent process is + now stored in non-global time stamp records. This prevents re-use + of the time stamp file after logout in most cases. + + Support was added for the kernel-based tty time stamps available in + OpenBSD which do not use an on-disk time stamp file. + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +BBUUGGSS + If you feel you have found a bug in ssuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 October 7, 2018 Sudo 1.8.26 diff --git a/doc/sudoers_timestamp.man.in b/doc/sudoers_timestamp.man.in new file mode 100644 index 0000000..86acce4 --- /dev/null +++ b/doc/sudoers_timestamp.man.in @@ -0,0 +1,310 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2017-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "SUDOERS_TIMESTAMP" "@mansectform@" "October 7, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudoers_timestamp\fR +\- Sudoers Time Stamp Format +.SH "DESCRIPTION" +The +\fBsudoers\fR +plugin uses per-user time stamp files for credential caching. +Once a user has been authenticated, they may use +\fBsudo\fR +without a password for a short period of time +(\fR@timeout@\fR +minutes unless overridden by the +\fItimestamp_timeout\fR +option) +\&. +By default, +\fBsudoers\fR +uses a separate record for each terminal, which means that +a user's login sessions are authenticated separately. +The +\fItimestamp_type\fR +option can be used to select the type of time stamp record +\fBsudoers\fR +will use. +.PP +A multi-record time stamp file format was introduced in +\fBsudo\fR +1.8.10 that uses a single file per user. +Previously, a separate file was used for each user and terminal +combination unless tty-based time stamps were disabled. +The new format is extensible and records of multiple types and versions +may coexist within the same file. +.PP +All records, regardless of type or version, begin with a 16-bit version +number and a 16-bit record size. +.PP +Time stamp records have the following structure: +.nf +.sp +.RS 0n +/* Time stamp entry types */ +#define TS_GLOBAL 0x01 /* not restricted by tty or ppid */ +#define TS_TTY 0x02 /* restricted by tty */ +#define TS_PPID 0x03 /* restricted by ppid */ +#define TS_LOCKEXCL 0x04 /* special lock record */ + +/* Time stamp flags */ +#define TS_DISABLED 0x01 /* entry disabled */ +#define TS_ANYUID 0x02 /* ignore uid, only valid in key */ + +struct timestamp_entry { + unsigned short version; /* version number */ + unsigned short size; /* entry size */ + unsigned short type; /* TS_GLOBAL, TS_TTY, TS_PPID */ + unsigned short flags; /* TS_DISABLED, TS_ANYUID */ + uid_t auth_uid; /* uid to authenticate as */ + pid_t sid; /* session ID associated with tty/ppid */ + struct timespec start_time; /* session/ppid start time */ + struct timespec ts; /* time stamp (CLOCK_MONOTONIC) */ + union { + dev_t ttydev; /* tty device number */ + pid_t ppid; /* parent pid */ + } u; +}; +.RE +.fi +.PP +The timestamp_entry struct fields are as follows: +.TP 6n +version +The version number of the timestamp_entry struct. +New entries are created with a version number of 2. +Records with different version numbers may coexist in the +same file but are not inter-operable. +.TP 6n +size +The size of the record in bytes. +.TP 6n +type +The record type, currently +\fRTS_GLOBAL\fR, +\fRTS_TTY\fR, +or +\fRTS_PPID\fR. +.TP 6n +flags +.br +Zero or more record flags which can be bit-wise ORed together. +Supported flags are +\fRTS_DISABLED\fR, +for records disabled via +\fBsudo\fR +\fB\-k\fR +and +\fRTS_ANYUID\fR, +which is used only when matching records. +.TP 6n +auth_uid +The user ID that was used for authentication. +Depending on the value of the +\fIrootpw\fR, +\fIrunaspw\fR +and +\fItargetpw\fR +options, the user ID may be that of the invoking user, the root user, +the default runas user or the target user. +.TP 6n +sid +The ID of the user's terminal session, if present. +The session ID is only used when matching records of type +\fRTS_TTY\fR. +.TP 6n +start_time +The start time of the session leader for records of type +\fRTS_TTY\fR +or of the parent process for records of type +\fRTS_PPID\fR. +The +\fIstart_time\fR +is used to help prevent re-use of a time stamp record after a +user has logged out. +Not all systems support a method to easily retrieve a process's +start time. +The +\fIstart_time\fR +field was added in +\fBsudoers\fR +version 1.8.22 for the second revision of the timestamp_entry struct. +.TP 6n +ts +The actual time stamp. +A monotonic time source (which does not move backward) is used if the +system supports it. +Where possible, +\fBsudoers\fR +uses a monotonic timer that increments even while the system +is suspended. +The value of +\fIts\fR +is updated each time a command is run via +\fBsudo\fR. +If the difference between +\fIts\fR +and the current time is less than the value of the +\fItimestamp_timeout\fR +option, no password is required. +.TP 6n +u.ttydev +The device number of the terminal associated with the session for +records of type +\fRTS_TTY\fR. +.TP 6n +u.ppid +The ID of the parent process for records of type +\fRTS_PPID\fR. +.SH "LOCKING" +In +\fBsudoers\fR +versions 1.8.10 through 1.8.14, the entire time stamp file was +locked for exclusive access when reading or writing to the file. +Starting in +\fBsudoers\fR +1.8.15, individual records are locked in the time stamp file instead +of the entire file and the lock is held for a longer period of time. +This scheme is described below. +.PP +The first record in the time stamp file is of type +\fRTS_LOCKEXCL\fR +and is used as a +\fIlock\fR +record to prevent more than one +\fBsudo\fR +process from adding a new record at the same time. +Once the desired time stamp record has been located or created (and +locked), the +\fRTS_LOCKEXCL\fR +record is unlocked. +The lock on the individual time stamp record, however, is held until +authentication is complete. +This allows +\fBsudoers\fR +to avoid prompting for a password multiple times when it +is used more than once in a pipeline. +.PP +Records of type +\fRTS_GLOBAL\fR +cannot be locked for a long period of time since doing so would +interfere with other +\fBsudo\fR +processes. +Instead, a separate lock record is used to prevent multiple +\fBsudo\fR +processes using the same terminal (or parent process ID) from +prompting for a password as the same time. +.SH "SEE ALSO" +sudoers(@mansectform@), +sudo(@mansectsu@) +.SH "HISTORY" +Originally, +\fBsudo\fR +used a single zero-length file per user and the file's modification +time was used as the time stamp. +Later versions of +\fBsudo\fR +added restrictions on the ownership of the time stamp files and +directory as well as sanity checks on the time stamp itself. +Notable changes were introduced in the following +\fBsudo\fR +versions: +.TP 6n +1.4.0 +.br +Support for tty-based time stamp file was added +by appending the terminal name to the time stamp file name. +.TP 6n +1.6.2 +.br +The time stamp file was replaced by a per-user directory which +contained any tty-based time stamp files. +.TP 6n +1.6.3p2 +The target user name was added to the time stamp file name when the +\fItargetpw\fR +option was set. +.TP 6n +1.7.3 +.br +Information about the terminal device was stored in +tty-based time stamp files for sanity checking. +This included the terminal device numbers, inode number and, on systems +where it was not updated when the device was written to, the inode change time. +This helped prevent re-use of the time stamp file after logout. +.TP 6n +1.8.6p7 +The terminal session ID was added to tty-based time stamp files to +prevent re-use of the time stamp by the same user in a different +terminal session. +It also helped prevent re-use of the time stamp file on systems where +the terminal device's inode change time was updated by writing. +.TP 6n +1.8.10 +A new, multi-record time stamp file format was introduced that uses a +single file per user. +The terminal device's change time was not included since most +systems now update the change time after a write is performed +as required by POSIX. +.TP 6n +1.8.15 +Individual records are locked in the time stamp file instead of the +entire file and the lock is held until authentication is complete. +.TP 6n +1.8.22 +The start time of the terminal session leader or parent process is +now stored in non-global time stamp records. +This prevents re-use of the time stamp file after logout in most cases. +.sp +Support was added for the kernel-based tty time stamps available in +OpenBSD +which do not use an on-disk time stamp file. +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBsudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoers_timestamp.mdoc.in b/doc/sudoers_timestamp.mdoc.in new file mode 100644 index 0000000..b385590 --- /dev/null +++ b/doc/sudoers_timestamp.mdoc.in @@ -0,0 +1,288 @@ +.\" +.\" Copyright (c) 2017-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 7, 2018 +.Dt SUDOERS_TIMESTAMP @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudoers_timestamp +.Nd Sudoers Time Stamp Format +.Sh DESCRIPTION +The +.Nm sudoers +plugin uses per-user time stamp files for credential caching. +Once a user has been authenticated, they may use +.Nm sudo +without a password for a short period of time +.Po +.Li @timeout@ +minutes unless overridden by the +.Em timestamp_timeout +option +.Pc . +By default, +.Nm sudoers +uses a separate record for each terminal, which means that +a user's login sessions are authenticated separately. +The +.Em timestamp_type +option can be used to select the type of time stamp record +.Nm sudoers +will use. +.Pp +A multi-record time stamp file format was introduced in +.Nm sudo +1.8.10 that uses a single file per user. +Previously, a separate file was used for each user and terminal +combination unless tty-based time stamps were disabled. +The new format is extensible and records of multiple types and versions +may coexist within the same file. +.Pp +All records, regardless of type or version, begin with a 16-bit version +number and a 16-bit record size. +.Pp +Time stamp records have the following structure: +.Bd -literal +/* Time stamp entry types */ +#define TS_GLOBAL 0x01 /* not restricted by tty or ppid */ +#define TS_TTY 0x02 /* restricted by tty */ +#define TS_PPID 0x03 /* restricted by ppid */ +#define TS_LOCKEXCL 0x04 /* special lock record */ + +/* Time stamp flags */ +#define TS_DISABLED 0x01 /* entry disabled */ +#define TS_ANYUID 0x02 /* ignore uid, only valid in key */ + +struct timestamp_entry { + unsigned short version; /* version number */ + unsigned short size; /* entry size */ + unsigned short type; /* TS_GLOBAL, TS_TTY, TS_PPID */ + unsigned short flags; /* TS_DISABLED, TS_ANYUID */ + uid_t auth_uid; /* uid to authenticate as */ + pid_t sid; /* session ID associated with tty/ppid */ + struct timespec start_time; /* session/ppid start time */ + struct timespec ts; /* time stamp (CLOCK_MONOTONIC) */ + union { + dev_t ttydev; /* tty device number */ + pid_t ppid; /* parent pid */ + } u; +}; +.Ed +.Pp +The timestamp_entry struct fields are as follows: +.Bl -tag -width 4n +.It version +The version number of the timestamp_entry struct. +New entries are created with a version number of 2. +Records with different version numbers may coexist in the +same file but are not inter-operable. +.It size +The size of the record in bytes. +.It type +The record type, currently +.Li TS_GLOBAL , +.Li TS_TTY , +or +.Li TS_PPID . +.It flags +Zero or more record flags which can be bit-wise ORed together. +Supported flags are +.Li TS_DISABLED , +for records disabled via +.Nm sudo +.Fl k +and +.Li TS_ANYUID , +which is used only when matching records. +.It auth_uid +The user ID that was used for authentication. +Depending on the value of the +.Em rootpw , +.Em runaspw +and +.Em targetpw +options, the user ID may be that of the invoking user, the root user, +the default runas user or the target user. +.It sid +The ID of the user's terminal session, if present. +The session ID is only used when matching records of type +.Li TS_TTY . +.It start_time +The start time of the session leader for records of type +.Li TS_TTY +or of the parent process for records of type +.Li TS_PPID . +The +.Em start_time +is used to help prevent re-use of a time stamp record after a +user has logged out. +Not all systems support a method to easily retrieve a process's +start time. +The +.Em start_time +field was added in +.Nm sudoers +version 1.8.22 for the second revision of the timestamp_entry struct. +.It ts +The actual time stamp. +A monotonic time source (which does not move backward) is used if the +system supports it. +Where possible, +.Nm sudoers +uses a monotonic timer that increments even while the system +is suspended. +The value of +.Em ts +is updated each time a command is run via +.Nm sudo . +If the difference between +.Em ts +and the current time is less than the value of the +.Em timestamp_timeout +option, no password is required. +.It u.ttydev +The device number of the terminal associated with the session for +records of type +.Li TS_TTY . +.It u.ppid +The ID of the parent process for records of type +.Li TS_PPID . +.El +.Sh LOCKING +In +.Nm sudoers +versions 1.8.10 through 1.8.14, the entire time stamp file was +locked for exclusive access when reading or writing to the file. +Starting in +.Nm sudoers +1.8.15, individual records are locked in the time stamp file instead +of the entire file and the lock is held for a longer period of time. +This scheme is described below. +.Pp +The first record in the time stamp file is of type +.Li TS_LOCKEXCL +and is used as a +.Em lock +record to prevent more than one +.Nm sudo +process from adding a new record at the same time. +Once the desired time stamp record has been located or created (and +locked), the +.Li TS_LOCKEXCL +record is unlocked. +The lock on the individual time stamp record, however, is held until +authentication is complete. +This allows +.Nm sudoers +to avoid prompting for a password multiple times when it +is used more than once in a pipeline. +.Pp +Records of type +.Li TS_GLOBAL +cannot be locked for a long period of time since doing so would +interfere with other +.Nm sudo +processes. +Instead, a separate lock record is used to prevent multiple +.Nm sudo +processes using the same terminal (or parent process ID) from +prompting for a password as the same time. +.Sh SEE ALSO +.Xr sudoers @mansectform@ , +.Xr sudo @mansectsu@ +.Sh HISTORY +Originally, +.Nm sudo +used a single zero-length file per user and the file's modification +time was used as the time stamp. +Later versions of +.Nm sudo +added restrictions on the ownership of the time stamp files and +directory as well as sanity checks on the time stamp itself. +Notable changes were introduced in the following +.Nm sudo +versions: +.Bl -tag -width 4n +.It 1.4.0 +Support for tty-based time stamp file was added +by appending the terminal name to the time stamp file name. +.It 1.6.2 +The time stamp file was replaced by a per-user directory which +contained any tty-based time stamp files. +.It 1.6.3p2 +The target user name was added to the time stamp file name when the +.Em targetpw +option was set. +.It 1.7.3 +Information about the terminal device was stored in +tty-based time stamp files for sanity checking. +This included the terminal device numbers, inode number and, on systems +where it was not updated when the device was written to, the inode change time. +This helped prevent re-use of the time stamp file after logout. +.It 1.8.6p7 +The terminal session ID was added to tty-based time stamp files to +prevent re-use of the time stamp by the same user in a different +terminal session. +It also helped prevent re-use of the time stamp file on systems where +the terminal device's inode change time was updated by writing. +.It 1.8.10 +A new, multi-record time stamp file format was introduced that uses a +single file per user. +The terminal device's change time was not included since most +systems now update the change time after a write is performed +as required by POSIX. +.It 1.8.15 +Individual records are locked in the time stamp file instead of the +entire file and the lock is held until authentication is complete. +.It 1.8.22 +The start time of the terminal session leader or parent process is +now stored in non-global time stamp records. +This prevents re-use of the time stamp file after logout in most cases. +.Pp +Support was added for the kernel-based tty time stamps available in +.Ox +which do not use an on-disk time stamp file. +.El +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoreplay.cat b/doc/sudoreplay.cat new file mode 100644 index 0000000..d3dd9ba --- /dev/null +++ b/doc/sudoreplay.cat @@ -0,0 +1,303 @@ +SUDOREPLAY(1m) System Manager's Manual SUDOREPLAY(1m) + +NNAAMMEE + ssuuddoorreeppllaayy - replay sudo session logs + +SSYYNNOOPPSSIISS + ssuuddoorreeppllaayy [--hhnnRRSS] [--dd _d_i_r] [--ff _f_i_l_t_e_r] [--mm _n_u_m] [--ss _n_u_m] ID + + ssuuddoorreeppllaayy [--hh] [--dd _d_i_r] --ll [search expression] + +DDEESSCCRRIIPPTTIIOONN + ssuuddoorreeppllaayy plays back or lists the output logs created by ssuuddoo. When + replaying, ssuuddoorreeppllaayy can play the session back in real-time, or the + playback speed may be adjusted (faster or slower) based on the command + line options. + + The _I_D should either be a six character sequence of digits and upper case + letters, e.g., 0100A5, or a pattern matching the _i_o_l_o_g___f_i_l_e option in the + _s_u_d_o_e_r_s file. When a command is run via ssuuddoo with _l_o_g___o_u_t_p_u_t enabled in + the _s_u_d_o_e_r_s file, a TSID=ID string is logged via syslog or to the ssuuddoo + log file. The _I_D may also be determined using ssuuddoorreeppllaayy's list mode. + + In list mode, ssuuddoorreeppllaayy can be used to find the ID of a session based on + a number of criteria such as the user, tty or command run. + + In replay mode, if the standard input and output are connected to a + terminal and the --nn option is not specified, ssuuddoorreeppllaayy will operate + interactively. In interactive mode, ssuuddoorreeppllaayy will attempt to adjust + the terminal size to match that of the session and write directly to the + terminal (not all terminals support this). Additionally, it will poll + the keyboard and act on the following keys: + + `\n' or `\r' Skip to the next replay event; useful for long pauses. + + ` ' (space) Pause output; press any key to resume. + + `<' Reduce the playback speed by one half. + + `>' Double the playback speed. + + The session can be interrupted via control-C. When the session has + finished, the terminal is restored to its original size if it was changed + during playback. + + The options are as follows: + + --dd _d_i_r, ----ddiirreeccttoorryy=_d_i_r + Store session logs in _d_i_r instead of the default, + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o. + + --ff _f_i_l_t_e_r, ----ffiilltteerr=_f_i_l_t_e_r + Select which I/O type(s) to display. By default, ssuuddoorreeppllaayy + will display the command's standard output, standard error + and tty output. The _f_i_l_t_e_r argument is a comma-separated + list, consisting of one or more of following: _s_t_d_i_n, _s_t_d_o_u_t, + _s_t_d_e_r_r, _t_t_y_i_n, and _t_t_y_o_u_t. + + --hh, ----hheellpp Display a short help message to the standard output and exit. + + --ll, ----lliisstt [_s_e_a_r_c_h _e_x_p_r_e_s_s_i_o_n] + Enable "list mode". In this mode, ssuuddoorreeppllaayy will list + available sessions in a format similar to the ssuuddoo log file + format, sorted by file name (or sequence number). If a + _s_e_a_r_c_h _e_x_p_r_e_s_s_i_o_n is specified, it will be used to restrict + the IDs that are displayed. An expression is composed of the + following predicates: + + command _p_a_t_t_e_r_n + Evaluates to true if the command run matches the + POSIX extended regular expression _p_a_t_t_e_r_n. + + cwd _d_i_r_e_c_t_o_r_y + Evaluates to true if the command was run with the + specified current working directory. + + fromdate _d_a_t_e + Evaluates to true if the command was run on or after + _d_a_t_e. See _D_a_t_e _a_n_d _t_i_m_e _f_o_r_m_a_t for a description of + supported date and time formats. + + group _r_u_n_a_s___g_r_o_u_p + Evaluates to true if the command was run with the + specified _r_u_n_a_s___g_r_o_u_p. Note that unless a + _r_u_n_a_s___g_r_o_u_p was explicitly specified when ssuuddoo was + run this field will be empty in the log. + + runas _r_u_n_a_s___u_s_e_r + Evaluates to true if the command was run as the + specified _r_u_n_a_s___u_s_e_r. Note that ssuuddoo runs commands + as user _r_o_o_t by default. + + todate _d_a_t_e + Evaluates to true if the command was run on or prior + to _d_a_t_e. See _D_a_t_e _a_n_d _t_i_m_e _f_o_r_m_a_t for a description + of supported date and time formats. + + tty _t_t_y _n_a_m_e + Evaluates to true if the command was run on the + specified terminal device. The _t_t_y _n_a_m_e should be + specified without the _/_d_e_v_/ prefix, e.g., _t_t_y_0_1 + instead of _/_d_e_v_/_t_t_y_0_1. + + user _u_s_e_r _n_a_m_e + Evaluates to true if the ID matches a command run by + _u_s_e_r _n_a_m_e. + + Predicates may be abbreviated to the shortest unique string. + + Predicates may be combined using _a_n_d, _o_r and _! operators as + well as `(' and `)' grouping (note that parentheses must + generally be escaped from the shell). The _a_n_d operator is + optional, adjacent predicates have an implied _a_n_d unless + separated by an _o_r. + + --mm, ----mmaaxx--wwaaiitt _m_a_x___w_a_i_t + Specify an upper bound on how long to wait between key + presses or output data. By default, ssuuddoorreeppllaayy will + accurately reproduce the delays between key presses or + program output. However, this can be tedious when the + session includes long pauses. When the --mm option is + specified, ssuuddoorreeppllaayy will limit these pauses to at most + _m_a_x___w_a_i_t seconds. The value may be specified as a floating + point number, e.g., _2_._5. A _m_a_x___w_a_i_t of zero or less will + eliminate the pauses entirely. + + --nn, ----nnoonn--iinntteerraaccttiivvee + Do not prompt for user input or attempt to re-size the + terminal. The session is written to the standard output, not + directly to the user's terminal. + + --RR, ----nnoo--rreessiizzee + Do not attempt to re-size the terminal to match the terminal + size of the session. + + --SS, ----ssuussppeenndd--wwaaiitt + Wait while the command was suspended. By default, ssuuddoorreeppllaayy + will ignore the time interval between when the command was + suspended and when it was resumed. If the --SS option is + specified, ssuuddoorreeppllaayy will wait instead. + + --ss, ----ssppeeeedd _s_p_e_e_d___f_a_c_t_o_r + This option causes ssuuddoorreeppllaayy to adjust the number of seconds + it will wait between key presses or program output. This can + be used to slow down or speed up the display. For example, a + _s_p_e_e_d___f_a_c_t_o_r of _2 would make the output twice as fast whereas + a _s_p_e_e_d___f_a_c_t_o_r of _._5 would make the output twice as slow. + + --VV, ----vveerrssiioonn + Print the ssuuddoorreeppllaayy versions version number and exit. + + DDaattee aanndd ttiimmee ffoorrmmaatt + The time and date may be specified multiple ways, common formats include: + + HH:MM:SS am MM/DD/CCYY timezone + 24 hour time may be used in place of am/pm. + + HH:MM:SS am Month, Day Year timezone + 24 hour time may be used in place of am/pm, and month and day + names may be abbreviated. Note that month and day of the week + names must be specified in English. + + CCYY-MM-DD HH:MM:SS + ISO time format + + DD Month CCYY HH:MM:SS + The month name may be abbreviated. + + Either time or date may be omitted, the am/pm and timezone are optional. + If no date is specified, the current day is assumed; if no time is + specified, the first second of the specified date is used. The less + significant parts of both time and date may also be omitted, in which + case zero is assumed. + + The following are all valid time and date specifications: + + now The current time and date. + + tomorrow + Exactly one day from now. + + yesterday + 24 hours ago. + + 2 hours ago + 2 hours ago. + + next Friday + The first second of the Friday in the next (upcoming) week. Not + to be confused with "this Friday" which would match the Friday of + the current week. + + last week + The current time but 7 days ago. This is equivalent to "a week + ago". + + a fortnight ago + The current time but 14 days ago. + + 10:01 am 9/17/2009 + 10:01 am, September 17, 2009. + + 10:01 am + 10:01 am on the current day. + + 10 10:00 am on the current day. + + 9/17/2009 + 00:00 am, September 17, 2009. + + 10:01 am Sep 17, 2009 + 10:01 am, September 17, 2009. + + Note that relative time specifications do not always work as expected. + For example, the "next" qualifier is intended to be used in conjunction + with a day such as "next Monday". When used with units of weeks, months, + years, etc the result will be one more than expected. For example, "next + week" will result in a time exactly two weeks from now, which is probably + not what was intended. This will be addressed in a future version of + ssuuddoorreeppllaayy. + + DDeebbuuggggiinngg ssuuddoorreeppllaayy + ssuuddoorreeppllaayy versions 1.8.4 and higher support a flexible debugging + framework that is configured via Debug lines in the sudo.conf(4) file. + + For more information on configuring sudo.conf(4), please refer to its + manual. + +FFIILLEESS + _/_e_t_c_/_s_u_d_o_._c_o_n_f Debugging framework configuration + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o The default I/O log directory. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_l_o_g + Example session log info. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_s_t_d_i_n + Example session standard input log. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_s_t_d_o_u_t + Example session standard output log. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_s_t_d_e_r_r + Example session standard error log. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_t_t_y_i_n + Example session tty input file. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_t_t_y_o_u_t + Example session tty output file. + + _/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o_/_0_0_/_0_0_/_0_1_/_t_i_m_i_n_g + Example session timing file. + + Note that the _s_t_d_i_n, _s_t_d_o_u_t and _s_t_d_e_r_r files will be empty unless ssuuddoo + was used as part of a pipeline for a particular command. + +EEXXAAMMPPLLEESS + List sessions run by user _m_i_l_l_e_r_t: + + # sudoreplay -l user millert + + List sessions run by user _b_o_b with a command containing the string vi: + + # sudoreplay -l user bob command vi + + List sessions run by user _j_e_f_f that match a regular expression: + + # sudoreplay -l user jeff command '/bin/[a-z]*sh' + + List sessions run by jeff or bob on the console: + + # sudoreplay -l ( user jeff or user bob ) tty console + +SSEEEE AALLSSOO + script(1), sudo.conf(4), sudo(1m) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +BBUUGGSS + If you feel you have found a bug in ssuuddoorreeppllaayy, please submit a bug + report at https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + ssuuddoorreeppllaayy is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 October 6, 2018 Sudo 1.8.26 diff --git a/doc/sudoreplay.man.in b/doc/sudoreplay.man.in new file mode 100644 index 0000000..7bb2da6 --- /dev/null +++ b/doc/sudoreplay.man.in @@ -0,0 +1,486 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 2009-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "SUDOREPLAY" "@mansectsu@" "October 6, 2018" "Sudo @PACKAGE_VERSION@" "System Manager's Manual" +.nh +.if n .ad l +.SH "NAME" +\fBsudoreplay\fR +\- replay sudo session logs +.SH "SYNOPSIS" +.HP 11n +\fBsudoreplay\fR +[\fB\-hnRS\fR] +[\fB\-d\fR\ \fIdir\fR] +[\fB\-f\fR\ \fIfilter\fR] +[\fB\-m\fR\ \fInum\fR] +[\fB\-s\fR\ \fInum\fR] +ID +.HP 11n +\fBsudoreplay\fR +[\fB\-h\fR] +[\fB\-d\fR\ \fIdir\fR] +\fB\-l\fR +[search\ expression] +.SH "DESCRIPTION" +\fBsudoreplay\fR +plays back or lists the output logs created by +\fBsudo\fR. +When replaying, +\fBsudoreplay\fR +can play the session back in real-time, or the playback speed may be +adjusted (faster or slower) based on the command line options. +.PP +The +\fIID\fR +should either be a six character sequence of digits and +upper case letters, e.g., +\fR0100A5\fR, +or a pattern matching the +\fIiolog_file\fR +option in the +\fIsudoers\fR +file. +When a command is run via +\fBsudo\fR +with +\fIlog_output\fR +enabled in the +\fIsudoers\fR +file, a +\fRTSID=ID\fR +string is logged via syslog or to the +\fBsudo\fR +log file. +The +\fIID\fR +may also be determined using +\fBsudoreplay\fR's +list mode. +.PP +In list mode, +\fBsudoreplay\fR +can be used to find the ID of a session based on a number of criteria +such as the user, tty or command run. +.PP +In replay mode, if the standard input and output are connected to a terminal +and the +\fB\-n\fR +option is not specified, +\fBsudoreplay\fR +will operate interactively. +In interactive mode, +\fBsudoreplay\fR +will attempt to adjust the terminal size to match that of the session and +write directly to the terminal (not all terminals support this). +Additionally, it will poll the keyboard and act on the following keys: +.TP 14n +\(oq\fR\en\fR\(cq or \(oq\fR\er\fR\(cq +Skip to the next replay event; useful for long pauses. +.TP 14n +\(oq\fR\ \fR\(cq (space) +Pause output; press any key to resume. +.TP 14n +\(oq<\(cq +Reduce the playback speed by one half. +.TP 14n +\(oq>\(cq +Double the playback speed. +.PP +The session can be interrupted via control-C. +When the session has finished, the terminal is restored to its +original size if it was changed during playback. +.PP +The options are as follows: +.TP 12n +\fB\-d\fR \fIdir\fR, \fB\--directory\fR=\fIdir\fR +Store session logs in +\fIdir\fR +instead of the default, +\fI@iolog_dir@\fR. +.TP 12n +\fB\-f\fR \fIfilter\fR, \fB\--filter\fR=\fIfilter\fR +Select which I/O type(s) to display. +By default, +\fBsudoreplay\fR +will display the command's standard output, standard error and tty output. +The +\fIfilter\fR +argument is a comma-separated list, consisting of one or more of following: +\fIstdin\fR, +\fIstdout\fR, +\fIstderr\fR, +\fIttyin\fR, +and +\fIttyout\fR. +.TP 12n +\fB\-h\fR, \fB\--help\fR +Display a short help message to the standard output and exit. +.TP 12n +\fB\-l\fR, \fB\--list\fR [\fIsearch expression\fR] +Enable +\(lqlist mode\(rq. +In this mode, +\fBsudoreplay\fR +will list available sessions in a format similar to the +\fBsudo\fR +log file format, sorted by file name (or sequence number). +If a +\fIsearch expression\fR +is specified, it will be used to restrict the IDs that are displayed. +An expression is composed of the following predicates: +.PP +.RS 12n +.PD 0 +.TP 8n +command \fIpattern\fR +Evaluates to true if the command run matches the POSIX extended +regular expression +\fIpattern\fR. +.PD +.TP 8n +cwd \fIdirectory\fR +Evaluates to true if the command was run with the specified current +working directory. +.TP 8n +fromdate \fIdate\fR +Evaluates to true if the command was run on or after +\fIdate\fR. +See +\fIDate and time format\fR +for a description of supported date and time formats. +.TP 8n +group \fIrunas_group\fR +Evaluates to true if the command was run with the specified +\fIrunas_group\fR. +Note that unless a +\fIrunas_group\fR +was explicitly specified when +\fBsudo\fR +was run this field will be empty in the log. +.TP 8n +runas \fIrunas_user\fR +Evaluates to true if the command was run as the specified +\fIrunas_user\fR. +Note that +\fBsudo\fR +runs commands as user +\fIroot\fR +by default. +.TP 8n +todate \fIdate\fR +Evaluates to true if the command was run on or prior to +\fIdate\fR. +See +\fIDate and time format\fR +for a description of supported date and time formats. +.TP 8n +tty \fItty name\fR +Evaluates to true if the command was run on the specified terminal device. +The +\fItty name\fR +should be specified without the +\fI/dev/\fR +prefix, e.g., +\fItty01\fR +instead of +\fI/dev/tty01\fR. +.TP 8n +user \fIuser name\fR +Evaluates to true if the ID matches a command run by +\fIuser name\fR. +.PP +Predicates may be abbreviated to the shortest unique string. +.sp +Predicates may be combined using +\fIand\fR, +\fIor\fR +and +\fI\&!\fR +operators as well as +\(oq\&(\(cq +and +\(oq\&)\(cq +grouping (note that parentheses must generally be escaped from the shell). +The +\fIand\fR +operator is optional, adjacent predicates have an implied +\fIand\fR +unless separated by an +\fIor\fR. +.RE +.TP 12n +\fB\-m\fR, \fB\--max-wait\fR \fImax_wait\fR +Specify an upper bound on how long to wait between key presses or output data. +By default, +\fBsudoreplay\fR +will accurately reproduce the delays between key presses or program output. +However, this can be tedious when the session includes long pauses. +When the +\fB\-m\fR +option is specified, +\fBsudoreplay\fR +will limit these pauses to at most +\fImax_wait\fR +seconds. +The value may be specified as a floating point number, e.g., +\fI2.5\fR. +A +\fImax_wait\fR +of zero or less will eliminate the pauses entirely. +.TP 12n +\fB\-n\fR, \fB\--non-interactive\fR +Do not prompt for user input or attempt to re-size the terminal. +The session is written to the standard output, not directly to +the user's terminal. +.TP 12n +\fB\-R\fR, \fB\--no-resize\fR +Do not attempt to re-size the terminal to match the terminal size +of the session. +.TP 12n +\fB\-S\fR, \fB\--suspend-wait\fR +Wait while the command was suspended. +By default, +\fBsudoreplay\fR +will ignore the time interval between when the command was suspended +and when it was resumed. +If the +\fB\-S\fR +option is specified, +\fBsudoreplay\fR +will wait instead. +.TP 12n +\fB\-s\fR, \fB\--speed\fR \fIspeed_factor\fR +This option causes +\fBsudoreplay\fR +to adjust the number of seconds it will wait between key presses or +program output. +This can be used to slow down or speed up the display. +For example, a +\fIspeed_factor\fR +of +\fI2\fR +would make the output twice as fast whereas a +\fIspeed_factor\fR +of +\fI.5\fR +would make the output twice as slow. +.TP 12n +\fB\-V\fR, \fB\--version\fR +Print the +\fBsudoreplay\fR +versions version number and exit. +.SS "Date and time format" +The time and date may be specified multiple ways, common formats include: +.TP 8n +HH:MM:SS am MM/DD/CCYY timezone +24 hour time may be used in place of am/pm. +.TP 8n +HH:MM:SS am Month, Day Year timezone +24 hour time may be used in place of am/pm, and month and day names +may be abbreviated. +Note that month and day of the week names must be specified in English. +.TP 8n +CCYY-MM-DD HH:MM:SS +ISO time format +.TP 8n +DD Month CCYY HH:MM:SS +The month name may be abbreviated. +.PP +Either time or date may be omitted, the am/pm and timezone are optional. +If no date is specified, the current day is assumed; if no time is +specified, the first second of the specified date is used. +The less significant parts of both time and date may also be omitted, +in which case zero is assumed. +.PP +The following are all valid time and date specifications: +.TP 8n +now +The current time and date. +.TP 8n +tomorrow +Exactly one day from now. +.TP 8n +yesterday +24 hours ago. +.TP 8n +2 hours ago +2 hours ago. +.TP 8n +next Friday +The first second of the Friday in the next (upcoming) week. +Not to be confused with +\(lqthis Friday\(rq +which would match the Friday of the current week. +.TP 8n +last week +The current time but 7 days ago. +This is equivalent to +\(lqa week ago\(rq. +.TP 8n +a fortnight ago +The current time but 14 days ago. +.TP 8n +10:01 am 9/17/2009 +10:01 am, September 17, 2009. +.TP 8n +10:01 am +10:01 am on the current day. +.TP 8n +10 +10:00 am on the current day. +.TP 8n +9/17/2009 +00:00 am, September 17, 2009. +.TP 8n +10:01 am Sep 17, 2009 +10:01 am, September 17, 2009. +.PP +Note that relative time specifications do not always work as expected. +For example, the +\(lqnext\(rq +qualifier is intended to be used in conjunction with a day such as +\(lqnext Monday\(rq. +When used with units of weeks, months, years, etc +the result will be one more than expected. +For example, +\(lqnext week\(rq +will result in a time exactly two weeks from now, which is probably +not what was intended. +This will be addressed in a future version of +\fBsudoreplay\fR. +.SS "Debugging sudoreplay" +\fBsudoreplay\fR +versions 1.8.4 and higher support a flexible debugging framework +that is configured via +\fRDebug\fR +lines in the +sudo.conf(@mansectform@) +file. +.PP +For more information on configuring +sudo.conf(@mansectform@), +please refer to its manual. +.SH "FILES" +.TP 26n +\fI@sysconfdir@/sudo.conf\fR +Debugging framework configuration +.TP 26n +\fI@iolog_dir@\fR +The default I/O log directory. +.TP 26n +\fI@iolog_dir@/00/00/01/log\fR +Example session log info. +.TP 26n +\fI@iolog_dir@/00/00/01/stdin\fR +Example session standard input log. +.TP 26n +\fI@iolog_dir@/00/00/01/stdout\fR +Example session standard output log. +.TP 26n +\fI@iolog_dir@/00/00/01/stderr\fR +Example session standard error log. +.TP 26n +\fI@iolog_dir@/00/00/01/ttyin\fR +Example session tty input file. +.TP 26n +\fI@iolog_dir@/00/00/01/ttyout\fR +Example session tty output file. +.TP 26n +\fI@iolog_dir@/00/00/01/timing\fR +Example session timing file. +.PP +Note that the +\fIstdin\fR, +\fIstdout\fR +and +\fIstderr\fR +files will be empty unless +\fBsudo\fR +was used as part of a pipeline for a particular command. +.SH "EXAMPLES" +List sessions run by user +\fImillert\fR: +.nf +.sp +.RS 6n +# sudoreplay -l user millert +.RE +.fi +.PP +List sessions run by user +\fIbob\fR +with a command containing the string vi: +.nf +.sp +.RS 6n +# sudoreplay -l user bob command vi +.RE +.fi +.PP +List sessions run by user +\fIjeff\fR +that match a regular expression: +.nf +.sp +.RS 6n +# sudoreplay -l user jeff command '/bin/[a-z]*sh' +.RE +.fi +.PP +List sessions run by jeff or bob on the console: +.nf +.sp +.RS 6n +# sudoreplay -l ( user jeff or user bob ) tty console +.RE +.fi +.SH "SEE ALSO" +script(1), +sudo.conf(@mansectform@), +sudo(@mansectsu@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you feel you have found a bug in +\fBsudoreplay\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBsudoreplay\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/sudoreplay.mdoc.in b/doc/sudoreplay.mdoc.in new file mode 100644 index 0000000..4eefaf6 --- /dev/null +++ b/doc/sudoreplay.mdoc.in @@ -0,0 +1,431 @@ +.\" +.\" Copyright (c) 2009-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 6, 2018 +.Dt SUDOREPLAY @mansectsu@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudoreplay +.Nd replay sudo session logs +.Sh SYNOPSIS +.Nm sudoreplay +.Op Fl hnRS +.Op Fl d Ar dir +.Op Fl f Ar filter +.Op Fl m Ar num +.Op Fl s Ar num +ID +.Pp +.Nm +.Op Fl h +.Op Fl d Ar dir +.Fl l +.Op search expression +.Sh DESCRIPTION +.Nm +plays back or lists the output logs created by +.Nm sudo . +When replaying, +.Nm +can play the session back in real-time, or the playback speed may be +adjusted (faster or slower) based on the command line options. +.Pp +The +.Em ID +should either be a six character sequence of digits and +upper case letters, e.g., +.Li 0100A5 , +or a pattern matching the +.Em iolog_file +option in the +.Em sudoers +file. +When a command is run via +.Nm sudo +with +.Em log_output +enabled in the +.Em sudoers +file, a +.Li TSID=ID +string is logged via syslog or to the +.Nm sudo +log file. +The +.Em ID +may also be determined using +.Nm sudoreplay Ns 's +list mode. +.Pp +In list mode, +.Nm +can be used to find the ID of a session based on a number of criteria +such as the user, tty or command run. +.Pp +In replay mode, if the standard input and output are connected to a terminal +and the +.Fl n +option is not specified, +.Nm +will operate interactively. +In interactive mode, +.Nm +will attempt to adjust the terminal size to match that of the session and +write directly to the terminal (not all terminals support this). +Additionally, it will poll the keyboard and act on the following keys: +.Bl -tag -width 12n +.It So Li \en Sc No or So Li \er Sc +Skip to the next replay event; useful for long pauses. +.It So Li \ Sc Pq space +Pause output; press any key to resume. +.It Ql < +Reduce the playback speed by one half. +.It Ql > +Double the playback speed. +.El +.Pp +The session can be interrupted via control-C. +When the session has finished, the terminal is restored to its +original size if it was changed during playback. +.Pp +The options are as follows: +.Bl -tag -width Fl +.It Fl d Ar dir , Fl -directory Ns = Ns Ar dir +Store session logs in +.Ar dir +instead of the default, +.Pa @iolog_dir@ . +.It Fl f Ar filter , Fl -filter Ns = Ns Ar filter +Select which I/O type(s) to display. +By default, +.Nm +will display the command's standard output, standard error and tty output. +The +.Ar filter +argument is a comma-separated list, consisting of one or more of following: +.Em stdin , +.Em stdout , +.Em stderr , +.Em ttyin , +and +.Em ttyout . +.It Fl h , -help +Display a short help message to the standard output and exit. +.It Fl l , -list Op Ar search expression +Enable +.Dq list mode . +In this mode, +.Nm +will list available sessions in a format similar to the +.Nm sudo +log file format, sorted by file name (or sequence number). +If a +.Ar search expression +is specified, it will be used to restrict the IDs that are displayed. +An expression is composed of the following predicates: +.Bl -tag -width 6n +.It command Ar pattern +Evaluates to true if the command run matches the POSIX extended +regular expression +.Ar pattern . +.It cwd Ar directory +Evaluates to true if the command was run with the specified current +working directory. +.It fromdate Ar date +Evaluates to true if the command was run on or after +.Ar date . +See +.Sx Date and time format +for a description of supported date and time formats. +.It group Ar runas_group +Evaluates to true if the command was run with the specified +.Ar runas_group . +Note that unless a +.Ar runas_group +was explicitly specified when +.Nm sudo +was run this field will be empty in the log. +.It runas Ar runas_user +Evaluates to true if the command was run as the specified +.Ar runas_user . +Note that +.Nm sudo +runs commands as user +.Em root +by default. +.It todate Ar date +Evaluates to true if the command was run on or prior to +.Ar date . +See +.Sx Date and time format +for a description of supported date and time formats. +.It tty Ar tty name +Evaluates to true if the command was run on the specified terminal device. +The +.Ar tty name +should be specified without the +.Pa /dev/ +prefix, e.g., +.Pa tty01 +instead of +.Pa /dev/tty01 . +.It user Ar user name +Evaluates to true if the ID matches a command run by +.Ar user name . +.El +.Pp +Predicates may be abbreviated to the shortest unique string. +.Pp +Predicates may be combined using +.Em and , +.Em or +and +.Em \&! +operators as well as +.Ql \&( +and +.Ql \&) +grouping (note that parentheses must generally be escaped from the shell). +The +.Em and +operator is optional, adjacent predicates have an implied +.Em and +unless separated by an +.Em or . +.It Fl m , -max-wait Ar max_wait +Specify an upper bound on how long to wait between key presses or output data. +By default, +.Nm +will accurately reproduce the delays between key presses or program output. +However, this can be tedious when the session includes long pauses. +When the +.Fl m +option is specified, +.Nm +will limit these pauses to at most +.Em max_wait +seconds. +The value may be specified as a floating point number, e.g., +.Em 2.5 . +A +.Em max_wait +of zero or less will eliminate the pauses entirely. +.It Fl n , -non-interactive +Do not prompt for user input or attempt to re-size the terminal. +The session is written to the standard output, not directly to +the user's terminal. +.It Fl R , -no-resize +Do not attempt to re-size the terminal to match the terminal size +of the session. +.It Fl S , -suspend-wait +Wait while the command was suspended. +By default, +.Nm +will ignore the time interval between when the command was suspended +and when it was resumed. +If the +.Fl S +option is specified, +.Nm +will wait instead. +.It Fl s , -speed Ar speed_factor +This option causes +.Nm +to adjust the number of seconds it will wait between key presses or +program output. +This can be used to slow down or speed up the display. +For example, a +.Ar speed_factor +of +.Em 2 +would make the output twice as fast whereas a +.Ar speed_factor +of +.Em .5 +would make the output twice as slow. +.It Fl V , -version +Print the +.Nm +versions version number and exit. +.El +.Ss Date and time format +The time and date may be specified multiple ways, common formats include: +.Bl -tag -width 6n +.It HH:MM:SS am MM/DD/CCYY timezone +24 hour time may be used in place of am/pm. +.It HH:MM:SS am Month, Day Year timezone +24 hour time may be used in place of am/pm, and month and day names +may be abbreviated. +Note that month and day of the week names must be specified in English. +.It CCYY-MM-DD HH:MM:SS +ISO time format +.It DD Month CCYY HH:MM:SS +The month name may be abbreviated. +.El +.Pp +Either time or date may be omitted, the am/pm and timezone are optional. +If no date is specified, the current day is assumed; if no time is +specified, the first second of the specified date is used. +The less significant parts of both time and date may also be omitted, +in which case zero is assumed. +.Pp +The following are all valid time and date specifications: +.Bl -tag -width 6n +.It now +The current time and date. +.It tomorrow +Exactly one day from now. +.It yesterday +24 hours ago. +.It 2 hours ago +2 hours ago. +.It next Friday +The first second of the Friday in the next (upcoming) week. +Not to be confused with +.Dq this Friday +which would match the Friday of the current week. +.It last week +The current time but 7 days ago. +This is equivalent to +.Dq a week ago . +.It a fortnight ago +The current time but 14 days ago. +.It 10:01 am 9/17/2009 +10:01 am, September 17, 2009. +.It 10:01 am +10:01 am on the current day. +.It 10 +10:00 am on the current day. +.It 9/17/2009 +00:00 am, September 17, 2009. +.It 10:01 am Sep 17, 2009 +10:01 am, September 17, 2009. +.El +.Pp +Note that relative time specifications do not always work as expected. +For example, the +.Dq next +qualifier is intended to be used in conjunction with a day such as +.Dq next Monday . +When used with units of weeks, months, years, etc +the result will be one more than expected. +For example, +.Dq next week +will result in a time exactly two weeks from now, which is probably +not what was intended. +This will be addressed in a future version of +.Nm . +.Ss Debugging sudoreplay +.Nm +versions 1.8.4 and higher support a flexible debugging framework +that is configured via +.Li Debug +lines in the +.Xr sudo.conf @mansectform@ +file. +.Pp +For more information on configuring +.Xr sudo.conf @mansectform@ , +please refer to its manual. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +Debugging framework configuration +.It Pa @iolog_dir@ +The default I/O log directory. +.It Pa @iolog_dir@/00/00/01/log +Example session log info. +.It Pa @iolog_dir@/00/00/01/stdin +Example session standard input log. +.It Pa @iolog_dir@/00/00/01/stdout +Example session standard output log. +.It Pa @iolog_dir@/00/00/01/stderr +Example session standard error log. +.It Pa @iolog_dir@/00/00/01/ttyin +Example session tty input file. +.It Pa @iolog_dir@/00/00/01/ttyout +Example session tty output file. +.It Pa @iolog_dir@/00/00/01/timing +Example session timing file. +.El +.Pp +Note that the +.Em stdin , +.Em stdout +and +.Em stderr +files will be empty unless +.Nm sudo +was used as part of a pipeline for a particular command. +.Sh EXAMPLES +List sessions run by user +.Em millert : +.Bd -literal -offset indent +# sudoreplay -l user millert +.Ed +.Pp +List sessions run by user +.Em bob +with a command containing the string vi: +.Bd -literal -offset indent +# sudoreplay -l user bob command vi +.Ed +.Pp +List sessions run by user +.Em jeff +that match a regular expression: +.Bd -literal -offset indent +# sudoreplay -l user jeff command '/bin/[a-z]*sh' +.Ed +.Pp +List sessions run by jeff or bob on the console: +.Bd -literal -offset indent +# sudoreplay -l ( user jeff or user bob ) tty console +.Ed +.Sh SEE ALSO +.Xr script 1 , +.Xr sudo.conf @mansectform@ , +.Xr sudo @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/visudo.cat b/doc/visudo.cat new file mode 100644 index 0000000..ac5eca3 --- /dev/null +++ b/doc/visudo.cat @@ -0,0 +1,226 @@ +VISUDO(1m) System Manager's Manual VISUDO(1m) + +NNAAMMEE + vviissuuddoo - edit the sudoers file + +SSYYNNOOPPSSIISS + vviissuuddoo [--cchhqqssVV] [[--ff] _s_u_d_o_e_r_s] + +DDEESSCCRRIIPPTTIIOONN + vviissuuddoo edits the _s_u_d_o_e_r_s file in a safe fashion, analogous to vipw(1m). + vviissuuddoo locks the _s_u_d_o_e_r_s file against multiple simultaneous edits, + provides basic sanity checks, and checks for parse errors. If the + _s_u_d_o_e_r_s file is currently being edited you will receive a message to try + again later. + + vviissuuddoo parses the _s_u_d_o_e_r_s file after editing and will not save the + changes if there is a syntax error. Upon finding an error, vviissuuddoo will + print a message stating the line number(s) where the error occurred and + the user will receive the "What now?" prompt. At this point the user may + enter `e' to re-edit the _s_u_d_o_e_r_s file, `x' to exit without saving the + changes, or `Q' to quit and save changes. The `Q' option should be used + with extreme caution because if vviissuuddoo believes there to be a parse + error, so will ssuuddoo and no one will be able to run ssuuddoo again until the + error is fixed. If `e' is typed to edit the _s_u_d_o_e_r_s file after a parse + error has been detected, the cursor will be placed on the line where the + error occurred (if the editor supports this feature). + + There are two _s_u_d_o_e_r_s settings that determine which editor vviissuuddoo will + run. + + editor A colon (`:') separated list of editors allowed to be used with + vviissuuddoo. vviissuuddoo will choose the editor that matches the user's + SUDO_EDITOR, VISUAL or EDITOR environment variable if possible, + or the first editor in the list that exists and is executable. + Note that the SUDO_EDITOR, VISUAL and EDITOR environment + variables are not preserved by default when the _e_n_v___r_e_s_e_t + _s_u_d_o_e_r_s option is enabled. The default editor path is _v_i which + can be set at compile time via the --with-editor configure + option. + + env_editor + If set, vviissuuddoo will use the value of the SUDO_EDITOR, VISUAL or + EDITOR environment variables before falling back on the default + editor list. Note that this may create a security hole as it + allows the user to run any arbitrary command as root without + logging. A safer alternative is to place a colon-separated + list of editors in the _e_d_i_t_o_r variable. vviissuuddoo will then only + use SUDO_EDITOR, VISUAL or EDITOR if they match a value + specified in _e_d_i_t_o_r. If the _e_n_v___r_e_s_e_t flag is enabled, the + SUDO_EDITOR, VISUAL and/or EDITOR environment variables must be + present in the _e_n_v___k_e_e_p list for the _e_n_v___e_d_i_t_o_r flag to + function when vviissuuddoo is invoked via ssuuddoo. The default value is + _o_f_f, which can be set at compile time via the --with-env-editor + configure option. + + The options are as follows: + + --cc, ----cchheecckk + Enable _c_h_e_c_k_-_o_n_l_y mode. The existing _s_u_d_o_e_r_s file (and any + other files it includes) will be checked for syntax errors. + If the path to the _s_u_d_o_e_r_s file was not specified, vviissuuddoo + will also check the file owner and mode. A message will be + printed to the standard output describing the status of + _s_u_d_o_e_r_s unless the --qq option was specified. If the check + completes successfully, vviissuuddoo will exit with a value of 0. + If an error is encountered, vviissuuddoo will exit with a value of + 1. + + --ff _s_u_d_o_e_r_s, ----ffiillee=_s_u_d_o_e_r_s + Specify an alternate _s_u_d_o_e_r_s file location, see below. As of + version 1.8.27, the _s_u_d_o_e_r_s path can be specified without + using the --ff option. + + --hh, ----hheellpp Display a short help message to the standard output and exit. + + --qq, ----qquuiieett + Enable _q_u_i_e_t mode. In this mode details about syntax errors + are not printed. This option is only useful when combined + with the --cc option. + + --ss, ----ssttrriicctt + Enable _s_t_r_i_c_t checking of the _s_u_d_o_e_r_s file. If an alias is + referenced but not actually defined or if there is a cycle in + an alias, vviissuuddoo will consider this a parse error. Note that + it is not possible to differentiate between an alias and a + host name or user name that consists solely of uppercase + letters, digits, and the underscore (`_') character. + + --VV, ----vveerrssiioonn + Print the vviissuuddoo and _s_u_d_o_e_r_s grammar versions and exit. + + A _s_u_d_o_e_r_s file may be specified instead of the default, _/_e_t_c_/_s_u_d_o_e_r_s. + The lock file used is the specified _s_u_d_o_e_r_s file with ".tmp" appended to + it. In _c_h_e_c_k_-_o_n_l_y mode only, `-' may be used to indicate that _s_u_d_o_e_r_s + will be read from the standard input. Because the policy is evaluated in + its entirety, it is not sufficient to check an individual _s_u_d_o_e_r_s include + file for syntax errors. + + DDeebbuuggggiinngg aanndd ssuuddooeerrss pplluuggiinn aarrgguummeennttss + vviissuuddoo versions 1.8.4 and higher support a flexible debugging framework + that is configured via Debug lines in the sudo.conf(4) file. + + Starting with ssuuddoo 1.8.12, vviissuuddoo will also parse the arguments to the + _s_u_d_o_e_r_s plugin to override the default _s_u_d_o_e_r_s path name, UID, GID and + file mode. These arguments, if present, should be listed after the path + to the plugin (i.e., after _s_u_d_o_e_r_s_._s_o). Multiple arguments may be + specified, separated by white space. For example: + + Plugin sudoers_policy sudoers.so sudoers_mode=0400 + + The following arguments are supported: + + sudoers_file=pathname + The _s_u_d_o_e_r_s___f_i_l_e argument can be used to override the default + path to the _s_u_d_o_e_r_s file. + + sudoers_uid=uid + The _s_u_d_o_e_r_s___u_i_d argument can be used to override the default + owner of the sudoers file. It should be specified as a numeric + user ID. + + sudoers_gid=gid + The _s_u_d_o_e_r_s___g_i_d argument can be used to override the default + group of the sudoers file. It must be specified as a numeric + group ID (not a group name). + + sudoers_mode=mode + The _s_u_d_o_e_r_s___m_o_d_e argument can be used to override the default + file mode for the sudoers file. It should be specified as an + octal value. + + For more information on configuring sudo.conf(4), please refer to its + manual. + +EENNVVIIRROONNMMEENNTT + The following environment variables may be consulted depending on the + value of the _e_d_i_t_o_r and _e_n_v___e_d_i_t_o_r _s_u_d_o_e_r_s settings: + + SUDO_EDITOR Invoked by vviissuuddoo as the editor to use + + VISUAL Used by vviissuuddoo if SUDO_EDITOR is not set + + EDITOR Used by vviissuuddoo if neither SUDO_EDITOR nor VISUAL is set + +FFIILLEESS + _/_e_t_c_/_s_u_d_o_._c_o_n_f Sudo front end configuration + + _/_e_t_c_/_s_u_d_o_e_r_s List of who can run what + + _/_e_t_c_/_s_u_d_o_e_r_s_._t_m_p Lock file for visudo + +DDIIAAGGNNOOSSTTIICCSS + In addition to reporting _s_u_d_o_e_r_s parse errors, vviissuuddoo may produce the + following messages: + + sudoers file busy, try again later. + Someone else is currently editing the _s_u_d_o_e_r_s file. + + /etc/sudoers.tmp: Permission denied + You didn't run vviissuuddoo as root. + + you do not exist in the passwd database + Your user ID does not appear in the system passwd database. + + Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined + Either you are trying to use an undeclared + {User,Runas,Host,Cmnd}_Alias or you have a user or host name listed + that consists solely of uppercase letters, digits, and the + underscore (`_') character. In the latter case, you can ignore the + warnings (ssuuddoo will not complain). The message is prefixed with + the path name of the _s_u_d_o_e_r_s file and the line number where the + undefined alias was used. In --ss (strict) mode these are errors, + not warnings. + + Warning: unused {User,Runas,Host,Cmnd}_Alias + The specified {User,Runas,Host,Cmnd}_Alias was defined but never + used. The message is prefixed with the path name of the _s_u_d_o_e_r_s + file and the line number where the unused alias was defined. You + may wish to comment out or remove the unused alias. + + Warning: cycle in {User,Runas,Host,Cmnd}_Alias + The specified {User,Runas,Host,Cmnd}_Alias includes a reference to + itself, either directly or through an alias it includes. The + message is prefixed with the path name of the _s_u_d_o_e_r_s file and the + line number where the cycle was detected. This is only a warning + unless vviissuuddoo is run in --ss (strict) mode as ssuuddoo will ignore cycles + when parsing the _s_u_d_o_e_r_s file. + + unknown defaults entry "name" + The _s_u_d_o_e_r_s file contains a Defaults setting not recognized by + vviissuuddoo. + +SSEEEE AALLSSOO + vi(1), sudo.conf(4), sudoers(4), sudo(1m), vipw(1m) + +AAUUTTHHOORRSS + Many people have worked on ssuuddoo over the years; this version consists of + code written primarily by: + + Todd C. Miller + + See the CONTRIBUTORS file in the ssuuddoo distribution + (https://www.sudo.ws/contributors.html) for an exhaustive list of people + who have contributed to ssuuddoo. + +CCAAVVEEAATTSS + There is no easy way to prevent a user from gaining a root shell if the + editor used by vviissuuddoo allows shell escapes. + +BBUUGGSS + If you feel you have found a bug in vviissuuddoo, please submit a bug report at + https://bugzilla.sudo.ws/ + +SSUUPPPPOORRTT + Limited free support is available via the sudo-users mailing list, see + https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search + the archives. + +DDIISSCCLLAAIIMMEERR + vviissuuddoo is provided "AS IS" and any express or implied warranties, + including, but not limited to, the implied warranties of merchantability + and fitness for a particular purpose are disclaimed. See the LICENSE + file distributed with ssuuddoo or https://www.sudo.ws/license.html for + complete details. + +Sudo 1.8.26 December 24, 2018 Sudo 1.8.26 diff --git a/doc/visudo.man.in b/doc/visudo.man.in new file mode 100644 index 0000000..9d6fc48 --- /dev/null +++ b/doc/visudo.man.in @@ -0,0 +1,465 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" Copyright (c) 1996,1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.TH "VISUDO" "@mansectsu@" "December 24, 2018" "Sudo @PACKAGE_VERSION@" "System Manager's Manual" +.nh +.if n .ad l +.SH "NAME" +\fBvisudo\fR +\- edit the sudoers file +.SH "SYNOPSIS" +.HP 7n +\fBvisudo\fR +[\fB\-chqsV\fR] +[[\fB\-f\fR]\ \fIsudoers\fR] +.SH "DESCRIPTION" +\fBvisudo\fR +edits the +\fIsudoers\fR +file in a safe fashion, analogous to +vipw(@mansectsu@). +\fBvisudo\fR +locks the +\fIsudoers\fR +file against multiple simultaneous edits, provides basic sanity checks, +and checks for parse errors. +If the +\fIsudoers\fR +file is currently being edited you will receive a message to try again later. +.PP +\fBvisudo\fR +parses the +\fIsudoers\fR +file after editing and will not save the changes if there is a syntax error. +Upon finding an error, +\fBvisudo\fR +will print a message stating the line number(s) +where the error occurred and the user will receive the +\(lqWhat now?\(rq +prompt. +At this point the user may enter +\(oqe\(cq +to re-edit the +\fIsudoers\fR +file, +\(oqx\(cq +to exit without saving the changes, or +\(oqQ\(cq +to quit and save changes. +The +\(oqQ\(cq +option should be used with extreme caution because if +\fBvisudo\fR +believes there to be a parse error, so will +\fBsudo\fR +and no one +will be able to run +\fBsudo\fR +again until the error is fixed. +If +\(oqe\(cq +is typed to edit the +\fIsudoers\fR +file after a parse error has been detected, the cursor will be placed on +the line where the error occurred (if the editor supports this feature). +.PP +There are two +\fIsudoers\fR +settings that determine which editor +\fBvisudo\fR +will run. +.TP 10n +editor +A colon +(\(oq:\&\(cq) +separated list of editors allowed to be used with +\fBvisudo\fR. +\fBvisudo\fR +will choose the editor that matches the user's +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +environment variable if possible, or the first editor in the +list that exists and is executable. +Note that the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +and +\fREDITOR\fR +environment variables are not preserved by default when the +\fIenv_reset\fR +\fIsudoers\fR +option is enabled. +The default editor path is +\fI@editor@\fR +which can be set at compile time via the +\fR--with-editor\fR +configure option. +.TP 10n +env_editor +If set, +\fBvisudo\fR +will use the value of the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +environment variables before falling back on the default editor list. +Note that this may create a security hole as it allows the user to +run any arbitrary command as root without logging. +A safer alternative is to place a colon-separated list of editors +in the +\fIeditor\fR +variable. +\fBvisudo\fR +will then only use +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +or +\fREDITOR\fR +if they match a value specified in +\fIeditor\fR. +If the +\fIenv_reset\fR +flag is enabled, the +\fRSUDO_EDITOR\fR, +\fRVISUAL\fR +and/or +\fREDITOR\fR +environment variables must be present in the +\fIenv_keep\fR +list for the +\fIenv_editor\fR +flag to function when +\fBvisudo\fR +is invoked via +\fBsudo\fR. +The default value is +\fI@env_editor@\fR, +which can be set at compile time via the +\fR--with-env-editor\fR +configure option. +.PP +The options are as follows: +.TP 12n +\fB\-c\fR, \fB\--check\fR +Enable +\fIcheck-only\fR +mode. +The existing +\fIsudoers\fR +file (and any other files it includes) will be +checked for syntax errors. +If the path to the +\fIsudoers\fR +file was not specified, +\fBvisudo\fR +will also check the file owner and mode. +A message will be printed to the standard output describing the status of +\fIsudoers\fR +unless the +\fB\-q\fR +option was specified. +If the check completes successfully, +\fBvisudo\fR +will exit with a value of 0. +If an error is encountered, +\fBvisudo\fR +will exit with a value of 1. +.TP 12n +\fB\-f\fR \fIsudoers\fR, \fB\--file\fR=\fIsudoers\fR +Specify an alternate +\fIsudoers\fR +file location, see below. +As of version 1.8.27, the +\fIsudoers\fR +path can be specified without using the +\fB\-f\fR +option. +.TP 12n +\fB\-h\fR, \fB\--help\fR +Display a short help message to the standard output and exit. +.TP 12n +\fB\-q\fR, \fB\--quiet\fR +Enable +\fIquiet\fR +mode. +In this mode details about syntax errors are not printed. +This option is only useful when combined with +the +\fB\-c\fR +option. +.TP 12n +\fB\-s\fR, \fB\--strict\fR +Enable +\fIstrict\fR +checking of the +\fIsudoers\fR +file. +If an alias is referenced but not actually defined +or if there is a cycle in an alias, +\fBvisudo\fR +will consider this a parse error. +Note that it is not possible to differentiate between an +alias and a host name or user name that consists solely of uppercase +letters, digits, and the underscore +(\(oq_\(cq) +character. +.TP 12n +\fB\-V\fR, \fB\--version\fR +Print the +\fBvisudo\fR +and +\fIsudoers\fR +grammar versions and exit. +.PP +A +\fIsudoers\fR +file may be specified instead of the default, +\fI@sysconfdir@/sudoers\fR. +The lock file used is the specified +\fIsudoers\fR +file with +\(lq\.tmp\(rq +appended to it. +In +\fIcheck-only\fR +mode only, +\(oq-\(cq +may be used to indicate that +\fIsudoers\fR +will be read from the standard input. +Because the policy is evaluated in its entirety, it is not sufficient +to check an individual +\fIsudoers\fR +include file for syntax errors. +.SS "Debugging and sudoers plugin arguments" +\fBvisudo\fR +versions 1.8.4 and higher support a flexible debugging framework +that is configured via +\fRDebug\fR +lines in the +sudo.conf(@mansectform@) +file. +.PP +Starting with +\fBsudo\fR +1.8.12, +\fBvisudo\fR +will also parse the arguments to the +\fIsudoers\fR +plugin to override the default +\fIsudoers\fR +path name, UID, GID and file mode. +These arguments, if present, should be listed after the path to the plugin +(i.e., after +\fIsudoers.so\fR). +Multiple arguments may be specified, separated by white space. +For example: +.nf +.sp +.RS 6n +Plugin sudoers_policy sudoers.so sudoers_mode=0400 +.RE +.fi +.PP +The following arguments are supported: +.TP 10n +sudoers_file=pathname +The +\fIsudoers_file\fR +argument can be used to override the default path to the +\fIsudoers\fR +file. +.TP 10n +sudoers_uid=uid +The +\fIsudoers_uid\fR +argument can be used to override the default owner of the sudoers file. +It should be specified as a numeric user ID. +.TP 10n +sudoers_gid=gid +The +\fIsudoers_gid\fR +argument can be used to override the default group of the sudoers file. +It must be specified as a numeric group ID (not a group name). +.TP 10n +sudoers_mode=mode +The +\fIsudoers_mode\fR +argument can be used to override the default file mode for the sudoers file. +It should be specified as an octal value. +.PP +For more information on configuring +sudo.conf(@mansectform@), +please refer to its manual. +.SH "ENVIRONMENT" +The following environment variables may be consulted depending on +the value of the +\fIeditor\fR +and +\fIenv_editor\fR +\fIsudoers\fR +settings: +.TP 17n +\fRSUDO_EDITOR\fR +Invoked by +\fBvisudo\fR +as the editor to use +.TP 17n +\fRVISUAL\fR +Used by +\fBvisudo\fR +if +\fRSUDO_EDITOR\fR +is not set +.TP 17n +\fREDITOR\fR +Used by +\fBvisudo\fR +if neither +\fRSUDO_EDITOR\fR +nor +\fRVISUAL\fR +is set +.SH "FILES" +.TP 26n +\fI@sysconfdir@/sudo.conf\fR +Sudo front end configuration +.TP 26n +\fI@sysconfdir@/sudoers\fR +List of who can run what +.TP 26n +\fI@sysconfdir@/sudoers.tmp\fR +Lock file for visudo +.SH "DIAGNOSTICS" +In addition to reporting +\fIsudoers\fR +parse errors, +\fBvisudo\fR +may produce the following messages: +.TP 6n +\fRsudoers file busy, try again later.\fR +Someone else is currently editing the +\fIsudoers\fR +file. +.TP 6n +\fR@sysconfdir@/sudoers.tmp: Permission denied\fR +You didn't run +\fBvisudo\fR +as root. +.TP 6n +\fRyou do not exist in the passwd database\fR +Your user ID does not appear in the system passwd database. +.TP 6n +\fRWarning: {User,Runas,Host,Cmnd}_Alias referenced but not defined\fR +Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias +or you have a user or host name listed that consists solely of +uppercase letters, digits, and the underscore +(\(oq_\(cq) +character. +In the latter case, you can ignore the warnings +(\fBsudo\fR +will not complain) +\&. +The message is prefixed with the path name of the +\fIsudoers\fR +file and the line number where the undefined alias was used. +In +\fB\-s\fR +(strict) mode these are errors, not warnings. +.TP 6n +\fRWarning: unused {User,Runas,Host,Cmnd}_Alias\fR +The specified {User,Runas,Host,Cmnd}_Alias was defined but never +used. +The message is prefixed with the path name of the +\fIsudoers\fR +file and the line number where the unused alias was defined. +You may wish to comment out or remove the unused alias. +.TP 6n +\fRWarning: cycle in {User,Runas,Host,Cmnd}_Alias\fR +The specified {User,Runas,Host,Cmnd}_Alias includes a reference to +itself, either directly or through an alias it includes. +The message is prefixed with the path name of the +\fIsudoers\fR +file and the line number where the cycle was detected. +This is only a warning unless +\fBvisudo\fR +is run in +\fB\-s\fR +(strict) mode as +\fBsudo\fR +will ignore cycles when parsing +the +\fIsudoers\fR +file. +.TP 6n +\fRunknown defaults entry \&"name\&"\fR +The +\fIsudoers\fR +file contains a +\fRDefaults\fR +setting not recognized by +\fBvisudo\fR. +.SH "SEE ALSO" +vi(1), +sudo.conf(@mansectform@), +sudoers(@mansectform@), +sudo(@mansectsu@), +vipw(@mansectsu@) +.SH "AUTHORS" +Many people have worked on +\fBsudo\fR +over the years; this version consists of code written primarily by: +.sp +.RS 6n +Todd C. Miller +.RE +.PP +See the CONTRIBUTORS file in the +\fBsudo\fR +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "CAVEATS" +There is no easy way to prevent a user from gaining a root shell if +the editor used by +\fBvisudo\fR +allows shell escapes. +.SH "BUGS" +If you feel you have found a bug in +\fBvisudo\fR, +please submit a bug report at https://bugzilla.sudo.ws/ +.SH "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.SH "DISCLAIMER" +\fBvisudo\fR +is provided +\(lqAS IS\(rq +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +\fBsudo\fR +or https://www.sudo.ws/license.html for complete details. diff --git a/doc/visudo.mdoc.in b/doc/visudo.mdoc.in new file mode 100644 index 0000000..140d5d6 --- /dev/null +++ b/doc/visudo.mdoc.in @@ -0,0 +1,447 @@ +.\" +.\" Copyright (c) 1996,1998-2005, 2007-2018 +.\" Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.Dd December 24, 2018 +.Dt VISUDO @mansectsu@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm visudo +.Nd edit the sudoers file +.Sh SYNOPSIS +.Nm visudo +.Op Fl chqsV +.Op Bo Fl f Bc Ar sudoers +.Sh DESCRIPTION +.Nm +edits the +.Em sudoers +file in a safe fashion, analogous to +.Xr vipw @mansectsu@ . +.Nm +locks the +.Em sudoers +file against multiple simultaneous edits, provides basic sanity checks, +and checks for parse errors. +If the +.Em sudoers +file is currently being edited you will receive a message to try again later. +.Pp +.Nm +parses the +.Em sudoers +file after editing and will not save the changes if there is a syntax error. +Upon finding an error, +.Nm +will print a message stating the line number(s) +where the error occurred and the user will receive the +.Dq What now? +prompt. +At this point the user may enter +.Ql e +to re-edit the +.Em sudoers +file, +.Ql x +to exit without saving the changes, or +.Ql Q +to quit and save changes. +The +.Ql Q +option should be used with extreme caution because if +.Nm +believes there to be a parse error, so will +.Nm sudo +and no one +will be able to run +.Nm sudo +again until the error is fixed. +If +.Ql e +is typed to edit the +.Em sudoers +file after a parse error has been detected, the cursor will be placed on +the line where the error occurred (if the editor supports this feature). +.Pp +There are two +.Em sudoers +settings that determine which editor +.Nm visudo +will run. +.Bl -tag -width 8n +.It editor +A colon +.Pq Ql :\& +separated list of editors allowed to be used with +.Nm . +.Nm +will choose the editor that matches the user's +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +environment variable if possible, or the first editor in the +list that exists and is executable. +Note that the +.Ev SUDO_EDITOR , +.Ev VISUAL +and +.Ev EDITOR +environment variables are not preserved by default when the +.Em env_reset +.Em sudoers +option is enabled. +The default editor path is +.Pa @editor@ +which can be set at compile time via the +.Li --with-editor +configure option. +.It env_editor +If set, +.Nm +will use the value of the +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +environment variables before falling back on the default editor list. +Note that this may create a security hole as it allows the user to +run any arbitrary command as root without logging. +A safer alternative is to place a colon-separated list of editors +in the +.Em editor +variable. +.Nm +will then only use +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +if they match a value specified in +.Em editor . +If the +.Em env_reset +flag is enabled, the +.Ev SUDO_EDITOR , +.Ev VISUAL +and/or +.Ev EDITOR +environment variables must be present in the +.Em env_keep +list for the +.Em env_editor +flag to function when +.Nm +is invoked via +.Nm sudo . +The default value is +.Em @env_editor@ , +which can be set at compile time via the +.Li --with-env-editor +configure option. +.El +.Pp +The options are as follows: +.Bl -tag -width Fl +.It Fl c , -check +Enable +.Em check-only +mode. +The existing +.Em sudoers +file (and any other files it includes) will be +checked for syntax errors. +If the path to the +.Em sudoers +file was not specified, +.Nm +will also check the file owner and mode. +A message will be printed to the standard output describing the status of +.Em sudoers +unless the +.Fl q +option was specified. +If the check completes successfully, +.Nm +will exit with a value of 0. +If an error is encountered, +.Nm +will exit with a value of 1. +.It Fl f Ar sudoers , Fl -file Ns = Ns Ar sudoers +Specify an alternate +.Em sudoers +file location, see below. +As of version 1.8.27, the +.Em sudoers +path can be specified without using the +.Fl f +option. +.It Fl h , -help +Display a short help message to the standard output and exit. +.It Fl q , -quiet +Enable +.Em quiet +mode. +In this mode details about syntax errors are not printed. +This option is only useful when combined with +the +.Fl c +option. +.It Fl s , -strict +Enable +.Em strict +checking of the +.Em sudoers +file. +If an alias is referenced but not actually defined +or if there is a cycle in an alias, +.Nm +will consider this a parse error. +Note that it is not possible to differentiate between an +alias and a host name or user name that consists solely of uppercase +letters, digits, and the underscore +.Pq Ql _ +character. +.It Fl V , -version +Print the +.Nm +and +.Em sudoers +grammar versions and exit. +.El +.Pp +A +.Em sudoers +file may be specified instead of the default, +.Pa @sysconfdir@/sudoers . +The lock file used is the specified +.Em sudoers +file with +.Dq \.tmp +appended to it. +In +.Em check-only +mode only, +.Ql - +may be used to indicate that +.Em sudoers +will be read from the standard input. +Because the policy is evaluated in its entirety, it is not sufficient +to check an individual +.Em sudoers +include file for syntax errors. +.Ss Debugging and sudoers plugin arguments +.Nm +versions 1.8.4 and higher support a flexible debugging framework +that is configured via +.Li Debug +lines in the +.Xr sudo.conf @mansectform@ +file. +.Pp +Starting with +.Nm sudo +1.8.12, +.Nm +will also parse the arguments to the +.Em sudoers +plugin to override the default +.Em sudoers +path name, UID, GID and file mode. +These arguments, if present, should be listed after the path to the plugin +(i.e., after +.Pa sudoers.so ) . +Multiple arguments may be specified, separated by white space. +For example: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so sudoers_mode=0400 +.Ed +.Pp +The following arguments are supported: +.Bl -tag -width 8n +.It sudoers_file=pathname +The +.Em sudoers_file +argument can be used to override the default path to the +.Em sudoers +file. +.It sudoers_uid=uid +The +.Em sudoers_uid +argument can be used to override the default owner of the sudoers file. +It should be specified as a numeric user ID. +.It sudoers_gid=gid +The +.Em sudoers_gid +argument can be used to override the default group of the sudoers file. +It must be specified as a numeric group ID (not a group name). +.It sudoers_mode=mode +The +.Em sudoers_mode +argument can be used to override the default file mode for the sudoers file. +It should be specified as an octal value. +.El +.Pp +For more information on configuring +.Xr sudo.conf @mansectform@ , +please refer to its manual. +.Sh ENVIRONMENT +The following environment variables may be consulted depending on +the value of the +.Em editor +and +.Em env_editor +.Em sudoers +settings: +.Bl -tag -width 15n +.It Ev SUDO_EDITOR +Invoked by +.Nm +as the editor to use +.It Ev VISUAL +Used by +.Nm +if +.Ev SUDO_EDITOR +is not set +.It Ev EDITOR +Used by +.Nm +if neither +.Ev SUDO_EDITOR +nor +.Ev VISUAL +is set +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +Sudo front end configuration +.It Pa @sysconfdir@/sudoers +List of who can run what +.It Pa @sysconfdir@/sudoers.tmp +Lock file for visudo +.El +.Sh DIAGNOSTICS +In addition to reporting +.Em sudoers +parse errors, +.Nm +may produce the following messages: +.Bl -tag -width 4n +.It Li sudoers file busy, try again later. +Someone else is currently editing the +.Em sudoers +file. +.It Li @sysconfdir@/sudoers.tmp: Permission denied +You didn't run +.Nm +as root. +.It Li you do not exist in the passwd database +Your user ID does not appear in the system passwd database. +.It Li Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined +Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias +or you have a user or host name listed that consists solely of +uppercase letters, digits, and the underscore +.Pq Ql _ +character. +In the latter case, you can ignore the warnings +.Po +.Nm sudo +will not complain +.Pc . +The message is prefixed with the path name of the +.Em sudoers +file and the line number where the undefined alias was used. +In +.Fl s +(strict) mode these are errors, not warnings. +.It Li Warning: unused {User,Runas,Host,Cmnd}_Alias +The specified {User,Runas,Host,Cmnd}_Alias was defined but never +used. +The message is prefixed with the path name of the +.Em sudoers +file and the line number where the unused alias was defined. +You may wish to comment out or remove the unused alias. +.It Li Warning: cycle in {User,Runas,Host,Cmnd}_Alias +The specified {User,Runas,Host,Cmnd}_Alias includes a reference to +itself, either directly or through an alias it includes. +The message is prefixed with the path name of the +.Em sudoers +file and the line number where the cycle was detected. +This is only a warning unless +.Nm +is run in +.Fl s +(strict) mode as +.Nm sudo +will ignore cycles when parsing +the +.Em sudoers +file. +.It Li unknown defaults entry \&"name\&" +The +.Em sudoers +file contains a +.Li Defaults +setting not recognized by +.Nm . +.El +.Sh SEE ALSO +.Xr vi 1 , +.Xr sudo.conf @mansectform@ , +.Xr sudoers @mansectform@ , +.Xr sudo @mansectsu@ , +.Xr vipw @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh CAVEATS +There is no easy way to prevent a user from gaining a root shell if +the editor used by +.Nm +allows shell escapes. +.Sh BUGS +If you feel you have found a bug in +.Nm , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. |