sigh, looks like we need libtool too

[debian/sudo] / README.LDAP

diff --git a/README.LDAP b/README.LDAP
index 030c1f9fe822a08678b2d7758405d87f0065ac52..84ac231d662c9002411f1680a361185ce049c384 100644 (file)
--- a/README.LDAP
+++ b/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.
 
 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.
 
 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/.
 
 
 For information on OpenLDAP, please see http://www.openldap.org/.
 


@@ -22,78 +33,9 @@ server, structure and contents.
 Many times 'options' are used in this document to refer to sudoer 'defaults'.
 They are one and the same.
 
 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
 ==================
 Build instructions
 ==================

-The most simplest way to build sudo with LDAP support is to include the
+The simplest way to build sudo with LDAP support is to include the

 '--with-ldap' option.
 
   $ ./configure --with-ldap
 '--with-ldap' option.
 
   $ ./configure --with-ldap


@@ -103,32 +45,56 @@ to specify them at configure time.  E.g.
 
   $ ./configure --with-ldap=/usr/local/ldapsdk
 
 
   $ ./configure --with-ldap=/usr/local/ldapsdk
 

-Sudo is developed using OpenLDAP.  Other LDAP implementations may
-require adding '-lldif' to SUDO_LIBS in the Makefile.
-
-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.
+Sudo is developed using OpenLDAP but Netscape-based LDAP libraries
+(such as those present in Solaris) are also known to work.

 
 

-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"
+Your mileage may vary.  Please let the sudo workers mailing list
+<sudo-workers@sudo.ws> know if special configuration was required
+to build an LDAP-enabled sudo so we can improve sudo.

 
 Schema Changes
 ==============
 
 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 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.
+
+On Solaris, schemas are stored in /var/Sun/mps/slapd-`hostname`/config/schema/.
+For Fedora Directory Server, they are stored in /etc/dirsrv/schema/.
+
+After copying the schema file to the appropriate directory, restart
+the LDAP server.

 
 

-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'.
+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:

 
 

-For the SunONE or iPlanet LDAP server, use the schema.iPlanet file.
+    serviceSearchDescriptor: sudoers: ou=sudoers,dc=example,dc=com

 
 

-Importing /etc/sudoers to LDAP
-==============================
-Importing is a two step process.
+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.
 
 Step 1:
 Ask your LDAP Administrator where to create the ou=SUDOers container.


@@ -149,18 +115,12 @@ options.
   # ./sudoers2ldif /etc/sudoers > /tmp/sudoers.ldif
 
 Step 2:
   # ./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 \
 
   # 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).
-<put an example here>
+    -D cn=Manager,dc=example,dc=com -W -x

 
 Managing LDAP entries
 =====================
 
 Managing LDAP entries
 =====================


@@ -173,6 +133,11 @@ I recommend using any of the following LDAP browsers to administer your SUDOers.
     and since it is Schema aware, I don't need to create a sudoRole template.
        http://biot.com/gq/
 
     and since it is Schema aware, I don't need to create a sudoRole template.
        http://biot.com/gq/
 

+  * phpQLAdmin - Open Source - phpQLAdmin is an administration tool,
+    originally for QmailLDAP, that supports editing sudoRole objects
+    in version 2.3.2 and higher.
+       http://phpqladmin.com/
+

   * LDAP Browser/Editor - by Jarek Gawor - I use this a lot on Windows
     and Solaris.  It runs anywhere in a Java Virtual Machine including
     web pages.  You have to make a template from an existing sudoRole entry.
   * LDAP Browser/Editor - by Jarek Gawor - I use this a lot on Windows
     and Solaris.  It runs anywhere in a Java Virtual Machine including
     web pages.  You have to make a template from an existing sudoRole entry.


@@ -180,153 +145,39 @@ I recommend using any of the following LDAP browsers to administer your SUDOers.
        http://www.mcs.anl.gov/~gawor/ldap
        http://ldapmanager.com
 
        http://www.mcs.anl.gov/~gawor/ldap
        http://ldapmanager.com
 

-  There are dozens of others, some open source, some free, some not.
+  * Apache Directory Studio - Open Source - an Eclipse-based LDAP
+    development platform.  Includes an LDAP browser, and LDIF editor,
+    a schema editor and more.
+    http://directory.apache.org/studio

 
 

+  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 /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, recompile SUDO with the -DLDAP_CONFIG compile 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 a uri or host & port
-  #host          ldapserver
-  #port          389
-  #
-  # URI will override host & port settings
-  # but only works with LDAP SDK's that support
-  # ldap_initialize() such as OpenLDAP
-  uri            ldap://ldapserver
-  #uri            ldaps://secureldapserver
-  #
-  # 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 port 389 and switch to
-  # encryption before the bind credentials are sent
-  #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.
-  #
-  #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.
-  #
-  #tls_randfile /etc/egd-pool
-  #
-  # You may restrict which ciphers are used.  Consult your SSL
-  # documentation for which options go here.
-  #
-  #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.
-  #
-  #tls_cert /etc/certs/client_cert.pem
-  #tls_key  /etc/certs/client_key.pem
-  #
+the same file name but has a different syntax.  If you need to change where
+this file is stored, re-run configure with the --with-ldap-conf-file=PATH
+option.

 
 

-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.  If you desperately want this to be changed, contact Aaron Spangler
-(aaron@spangler.ods.org).
-
-  # 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
+See the "Configuring ldap.conf" section in the sudoers.ldap manual
+for a list of supported ldap.conf parameters and an example ldap.conf

 
 

-  # does not match all but web01
-  # rather, matches all hosts including web01
-  sudoHost: ALL
-  sudoHost: !web01
+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.

 
 

-Configure your /etc/nsswitch.conf
+Debugging your LDAP configuration

 =================================
 =================================

-At the time of this writing, sudo does not consult nsswitch.conf for the
-search order.  But if it did, it would look like this:
-This might be implemented in the future.  For now just skip this step.
-
-  sudoers: files ldap
+Enable debugging if you believe sudo is not parsing LDAP the way you think it
+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.