Upgrade to sudo 1.7. See the WHATSNEW files for details.

1 files changed, 81 insertions, 268 deletions

diff --git a/usr.bin/sudo/README.LDAP b/usr.bin/sudo/README.LDAP
index df4ad2107ec..85f05f54994 100644
--- a/usr.bin/sudo/README.LDAP
+++ b/usr.bin/sudo/README.LDAP
@@ -1,16 +1,27 @@
-This file explains how to use the optional LDAP functionality of SUDO to
+This file explains how to build the optional LDAP functionality of SUDO to
 store /etc/sudoers information.  This feature is distinct from LDAP passwords.
 
+For general sudo LDAP configuration details, see the sudoers.ldap manual that
+comes with the sudo distribution.  A pre-formatted version of the manual may
+be found in the sudoers.ldap.cat file.
+
+The sudo binary compiled with LDAP support should be totally backward
+compatible and be syntactically and source code equivalent to its
+non LDAP-enabled build.
+
 LDAP philosophy
 ===============
 As times change and servers become cheap, an enterprise can easily have 500+
 UNIX servers.  Using LDAP to synchronize Users, Groups, Hosts, Mounts, and
 others across an enterprise can greatly reduce the administrative overhead.
 
-Sudo in the past has only used a single local configuration file /etc/sudoers.
-Some have attempted to workaround this by synchronizing changes via
-RCS/CVS/RSYNC/RDIST/RCP/SCP and even NFS.  Many have asked for a Hesiod, NIS,
-or LDAP patch for sudo, so here is my attempt at LDAP'izing sudo.
+In the past, sudo has used a single local configuration file, /etc/sudoers.
+While the same sudoers file can be shared among machines, no built-in
+mechanism exists to distribute it.  Some have attempted to workaround this
+by synchronizing changes via CVS/RSYNC/RDIST/RCP/SCP and even NFS.
+
+By using LDAP for sudoers we gain a centrally administered, globally
+available configuration source for sudo.
 
 For information on OpenLDAP, please see http://www.openldap.org/.
 
@@ -22,75 +33,6 @@ server, structure and contents.
 Many times 'options' are used in this document to refer to sudoer 'defaults'.
 They are one and the same.
 
-Design Features
-===============
-
-  * Sudo no longer needs to read sudoers in its entirety.  Parsing of
-    /etc/sudoers requires the entire file to be read.  The LDAP feature of sudo
-    uses two (sometimes three) LDAP queries per invocation.  It never reads all
-    the sudoer entries in the LDAP store.  This makes it especially fast and
-    particularly usable in LDAP environments.  The first query is to parse
-    default options (see below).  The second is to match against the username or
-    groups a user belongs to.  (The special ALL tag is matched in this query
-    too.) If no match is made against the username, the third query pulls the
-    entries that match against user netgroups to compare back to the user.
-
-  * Sudo no longer blows up if there is a typo.  Parsing of /etc/sudoers can
-    still blow up when sudo is invoked.  However when using the LDAP feature of
-    sudo, LDAP syntax rules are applied before the data is uploaded into the
-    LDAP server, so proper syntax is always guaranteed!  One can of course still
-    insert a bogus hostname or username, but sudo will not care.
-
-  * Options inside of entries now override global default options.
-    /etc/sudoers allowed for only default options and limited options associated
-    with user/host/command aliases.  The syntax can be difficult for the newbie.
-    The LDAP feature attempts to simplify this and yet still provide maximum
-    flexibility.
-
-    Sudo first looks for an entry called 'cn=default' in the SUDOers container.
-    If found, the multi-valued sudoOption attribute is parsed the same way the
-    global 'Defaults' line in /etc/sudoers is parsed.
-
-    If on the second or third query, a response contains a sudoRole which
-    matches against the user, host, and command, then the matched object is
-    scanned for a additional options to override the top-level defaults.  See
-    the example LDAP content below for more information.
-
-  * Visudo is no longer needed.  Visudo provides locking and syntax checking
-    against the /etc/sudoers file.  Since LDAP updates are atomic, locking is no
-    longer necessary.  Because syntax is checked when the data is inserted into
-    LDAP, the sudoers syntax check becomes unnecessary.
-
-  * Aliases are no longer needed.  User, Host, and Command Aliases were setup
-    to allow simplification and readability of the sudoers files.  Since the
-    LDAP sudoer entry allows multiple values for each of its attributes and
-    since most LDAP browsers are graphical and easy to work with, original
-    aliases are no longer needed.
-
-    If you want to specify lots of users into an entry or want to have similar
-    entries with identical users, then use either groups or user netgroups.
-    Thats what groups and netgroups are for and Sudo handles this well.
-    Alternately, one can just paste them all into the LDAP record.
-
-    If you want to specify lots of hosts into an entry, use netgroups or IP
-    address matches (10.2.3.4/255.255.0.0).  Thats what netgroups are for and
-    Sudo handles this well.  Or just past them all into the LDAP record.
-
-    If you want to specify lots of commands, use directories or wildcards, or
-    just paste them all into LDAP.  That's what it's for.
-
-  * The /etc/sudoers file can be disabled.  Paranoid security administrators
-    can now disallow parsing of any local /etc/sudoers file by an LDAP
-    sudoOption 'ignore_local_sudoers'.  This way all sudoers can be controlled
-    and audited in one place because local entries are not allowed.
-    In fact, if this option is included in the cn=defaults object of LDAP,
-    sudo won't even look for a /etc/sudoers file.
-
-  * The sudo binary compiled with LDAP support should be totally backward
-    compatible and be syntactically and source code equivalent to its non
-    LDAP-enabled build.
-
-
 Build instructions
 ==================
 The most simplest way to build sudo with LDAP support is to include the
@@ -103,33 +45,56 @@ to specify them at configure time.  E.g.
 
   $ ./configure --with-ldap=/usr/local/ldapsdk
 
-Sudo is developed using OpenLDAP.  Other LDAP implementations may
-require adding '-lldif' to SUDO_LIBS in the Makefile.
+Sudo is developed using OpenLDAP but Netscape-based LDAP libraries
+(such as those present in Solaris) are also known to work.
 
 Your Mileage may vary.  Please let the sudo workers mailing list
-<sudo-workers@sudo.ws> know what combinations worked best for your
-OS and LDAP Combinations so we can improve sudo.
-
-More Build Notes:
-HP-UX 11.23 (gcc3) Galen Johnson <Galen.Johnson@sas.com>
-  CFLAGS="-D__10_10_compat_code" LDFLAGS="-L/opt/ldapux/lib"
+<sudo-workers@sudo.ws> know if special configuration was required
+to build an LDAP-enabled sudo so we can improve sudo.
 
 Schema Changes
 ==============
-Add the appropriate schema to your LDAP server so that it may contain
-sudoers content.
+You must add the appropriate schema to your LDAP server before it
+can store sudoers content.
+
+For OpenLDAP, copy the file schema.OpenLDAP to the schema directory
+(e.g. /etc/openldap/schema).  You must then edit your slapd.conf and
+add an include line the new schema, e.g.
+
+    # Sudo LDAP schema
+    include	/etc/openldap/schema/sudo.schema
+
+In order for sudoRole LDAP queries to be efficient, the server must index
+the attribute 'sudoUser', e.g.
+
+    # Indices to maintain
+    index	sudoUser	eq
+
+After making the changes to slapd.conf, restart slapd.
 
-For OpenLDAP, simply copy schema.OpenLDAP to the schema directory
-(e.g. /etc/openldap/schema) and 'include' it in your slapd.conf and
-restart slapd.  For other LDAP servers, provide this to your LDAP
-Administrator.  Make sure to index the attribute 'sudoUser'.
+For Netscape-derived LDAP servers such as SunONE, iPlanet or Fedora Directory,
+copy the schema.iPlanet file to the schema directory with the name 99sudo.ldif.
 
-For netscape-derived LDAP servers such as SunONE, iPlanet or Fedora
-Directory, use the schema.iPlanet file.
+On Solaris, schemas are stored in /var/Sun/mps/slapd-`hostname`/config/schema/.
+For Fedora Directory Server, they are stored in /etc/dirsrv/schema/.
 
-Importing /etc/sudoers to LDAP
-==============================
-Importing is a two step process.
+After copying the schema file to the appropriate directory, restart
+the LDAP server.
+
+Finally, using an LDAP browser/editor, enable indexing by editing the
+client profile to provide a Service Search Descriptor (SSD) for sudoers,
+replacing example.com with your domain:
+
+    serviceSearchDescriptor: sudoers: ou=sudoers,dc=example,dc=com
+
+If using an Active Directory server, copy schema.ActiveDirectory
+to your Windows domain controller and run the following command:
+
+    ldifde -i -f schema.ActiveDirectory -c dc=X dc=example,dc=com
+
+Importing /etc/sudoers into LDAP
+================================
+Importing sudoers is a two-step process.
 
 Step 1:
 Ask your LDAP Administrator where to create the ou=SUDOers container.
@@ -150,28 +115,12 @@ options.
   # ./sudoers2ldif /etc/sudoers > /tmp/sudoers.ldif
 
 Step 2:
-Import into your directory server.  If you are using OpenLDAP, do the following
-if you are using another directory, provide the LDIF file to your LDAP
-Administrator.  An example is shown below.
+Import into your directory server.  The following example is for
+OpenLDAP.  If you are using another directory, provide the LDIF
+file to your LDAP Administrator.
 
   # ldapadd -f /tmp/sudoers.ldif -h ldapserver \
-  > -D cn=Manager,dc=example,dc=com -W -x
-
-Example sudoers Entries in LDAP
-===============================
-The equivalent of a sudoer in LDAP is a 'sudoRole'.  It contains sudoUser(s),
-sudoHost, sudoCommand and optional sudoOption(s) and sudoRunAs(s).
-
-The following example allows users in group wheel to run any
-command on any host through sudo:
-
-dn: cn=%wheel,ou=SUDOers,dc=example,dc=com
-objectClass: top
-objectClass: sudoRole
-cn: %wheel
-sudoUser: %wheel
-sudoHost: ALL
-sudoCommand: ALL
+    -D cn=Manager,dc=example,dc=com -W -x
 
 Managing LDAP entries
 =====================
@@ -198,168 +147,32 @@ I recommend using any of the following LDAP browsers to administer your SUDOers.
 
   There are dozens of others, some Open Source, some free, some not.
 
-
-Configure your /etc/ldap.conf
-=============================
+Configure your /etc/ldap.conf and /etc/nsswitch.conf
+====================================================
 The /etc/ldap.conf file is meant to be shared between sudo, pam_ldap, nss_ldap
 and other ldap applications and modules.  IBM Secureway unfortunately uses
 the same filename but has a different syntax.  If you need to rename where
 this file is stored, re-run configure with the --with-ldap-conf-file=filename
 option.
 
-Make sure you sudoers_base matches exactly with the location you specified
-when you imported the sudoers.  Below is an example /etc/ldap.conf
-
-  # 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
-  sudoers_base   ou=SUDOers,dc=example,dc=com
-  #
-  # verbose sudoers matching from ldap
-  #sudoers_debug 2
-  #
-  # optional proxy credentials
-  #binddn        <who to search as>
-  #bindpw        <password>
-  #rootbinddn    <who to search as, uses /etc/ldap.passwd 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, the file 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/cert7.db
-  #tls_key /var/ldap/key3.db
+See the "Configuring ldap.conf" section in the sudoers.ldap manual
+for a list of supported ldap.conf parameters and an example ldap.conf
+
+Make sure you sudoers_base matches the location you specified when you
+imported the sudoers ldif data.
+
+After configuring /etc/ldap.conf, you must add a line in /etc/nsswitch.conf
+to tell sudo to look in LDAP for sudoers.  See the "Configuring nsswitch.conf"
+section in the sudoers.ldap manual for details.  Note that sudo will use
+/etc/nsswitch.conf even if the underlying operating system does not support it.
+To disable nsswitch support, run configure with the --with-nsswitch=no option.
+This will cause sudo to consult LDAP first and /etc/sudoers second, unless the
+ignore_sudoers_file flag is set in the global LDAP options.
 
 Debugging your LDAP configuration
 =================================
 Enable debugging if you believe sudo is not parsing LDAP the way you think it
-it should.  A value of 1 shows moderate debugging.  A value of 2 shows the
-results of the matches themselves.  Make sure to set the value back to zero
-so that other users don't get confused by the debugging messages.  This value
-is 'sudoers_debug' in the /etc/ldap.conf.
-
-Parsing Differences between /etc/sudoers and LDAP
-=================================================
-There are some subtle differences in the way sudoers is handled once in LDAP.
-Probably the biggest is that according to the RFC, LDAP's ordering is
-arbitrary and you cannot expect that Attributes & Entries are returned in
-any order.  If there are conflicting command rules on 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 negations on the Host, User or Runas are
-currently ignorred.  For example, these attributes do not work how
-they first seem.
-
-  # 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
-
-  # does not match all but web01
-  # rather, matches all hosts including web01
-  sudoHost: ALL
-  sudoHost: !web01
+should.  Setting the 'sudoers_debug' parameter to a value of 1 shows moderate
+debugging.  A value of 2 shows the results of the matches themselves.  Make
+sure to set the value back to zero so that other users don't get confused by
+the debugging messages.