============================ Quickstart Guide for ERS 3.0 ============================ Contents ========= 1. Prerequisites - HPUX - Solaris - Win32 Known Issue 2. Installation Instructions - Long Filenames Require GTAR on Solaris and HPUX - compat-db package is required on Linux platform 3. Testing the Installation Using Preconfigured Default Servers 4. Customizing the Preconfigured Servers 5. Detailed Instructions for Creating New Server Instances 6. Detailed Instructions for Covalent Enterprise Ready Server 3.0 Migration from ERS 2.4 ============================================== Prerequisites: Please read before installation ============================================== ================== HPUX Prerequisites ================== Before installing ERS 3.0 on HPUX please make note of the following: 1. HPUX requires valid user to run WWW services =============================================== On HPUX there must be a valid user and group to run the Apache httpd server. Make sure that the user www exists in /etc/passwd and that the group www exists in /etc/group before attempting to start the Apache server. Look in both files and verify that the www user and group are listed. If the www user and group are not listed, please create them. Example: bash-2.04$ grep www /etc/passwd www:*:30:34::/: bash-2.04$ grep www /etc/group www::34:www 2. SSL requires sufficient entropy =================================== Certain items like OpenSSL, auth_digest and so on need a significant amount of entropy - or truly random (not pseudorandom) data. HP 11.11 does not include /dev/urandom by default, but it is available from HP directly at no cost; http://software.hp.com/cgi-bin/swdepot_parser.cgi/cgi/displayProductInfo.pl?productNumber=KRNG11I Install the HPUX Strong Random number generator to enable SSL and related functionality. 3. JSP support requires user-installed JSDK from HP =================================================== Covalent provides a runtime JVM with ERS that enables Java servlets to run on Tomcat. However, you must install a full Java SDK to run JSP's, including the Tomcat JSP examples. This SDK should be downloaded for HPUX 11 and 11i from HP at the following location: http://www.hp.com/products1/unix/java/index.html Once the JSDK is installed (typically to /opt/java1.4) the Tomcat startup scripts should be modified to point to it as JAVA_HOME. The tomcat startup script "tomcat_startup.sh" resides in 4 locations at installation time. It is in both /default20 and /default13 and in the master template directories which are used for custom deployments. Edit the following four files to set JAVA_HOME to the appropriate directory in each one: /tomcat5.0/_instance/bin/tomcat_startup.sh /tomcat4.1/_instance/bin/tomcat_startup.sh /servers/default20/bin/tomcat_startup.sh /servers/default13/bin/tomcat_startup.sh In each file you will see the statement that sets JAVA_HOME: JAVA_HOME=$root_dir/j2se1.4; export JAVA_HOME Change that statement to reflect the location of your JAVA_HOME. For example: JAVA_HOME=/opt/java1.4; export JAVA_HOME Once this is done, Tomcat will start with the installed JVM and JSDK and JSP support will be enabled. ===================== Solaris Prerequisites ===================== Before installing ERS 3.0 on Solaris please make note of the following: 1. SSL requires sufficient entropy =================================== Certain items like OpenSSL, auth_digest and so on need a significant amount of entropy - or truly random (not pseudorandom) data. Solaris 8 does not include /dev/urandom by default, but it is available from Sun directly at no cost; http://sunsolve6.sun.com/pub-cgi/getpatch.pl?documentId=112438 Install the Solaris /kernel/drv/random patch to enable SSL, auth_digest, and related functionality. =================== Linux Prerequisites =================== Please note that compat-db package is required on Linux platform as the dynamically linked libdb.so.3 library depends on the compat-db libraries. Some of Linux systems, for example RedHat AS4, do not have this package installed by default. In the absence of this package, the following error occurs during server startup: httpsd.prefork: error while loading shared libraries: libdb.so.3: cannot open shared object file: No such file or directory Server start FAILED =================== Win32 Known Issues =================== There is one known issue with this release on Win32, and that is if the Apache HTTP server is run at LogLevel=debug while in SSL mode, Apache will experience a crash during shutdown. Normal runtime server functionality is not affected, the error only occurs as the server shuts down. Known Issues Specific to ERS 3.0.1 Win32 release: ================================================= There are config errors in newly generated servers. Below are the things that need to be corrected for new server instances you create with ers-server.pl. These issues are not in the /default20 and /default13 apache servers, but are only found when using ers-server.pl to create new servers. ***Note: The Win32 Apache service will not install until the httpsd.conf file is correct*** *** Please make all the changes to file noted below, and -then- install the service*** 1. The startup script under the /bin directory is missing a new line character. - Edit the //bin/apache_startp.bat file - see the following section setlocal set root_dir=D:/installs/covalent/win32-ers301 set server_name=newtestset apache_bin=%root_dir%\apache2.0\bin\httpsd.exe set server_root=%root_dir%\servers\%server_name% Notice the extra long line. Add a new line before the word "set". Should now look like this: [These examples refer to D:/installs/covalent/win32-ers301 as the install directory. Please replace with your actual installation directory.] setlocal set root_dir=D:/installs/covalent/win32-ers301 set server_name=newtest set apache_bin=%root_dir%\apache2.0\bin\httpsd.exe set server_root=%root_dir%\servers\%server_name% - save file and exit 2. The conf file used as a template for new servers has some linux directives that do not work on Win32. - Edit the //conf/httpsd.conf file - see the following lines: LoadModule suexec_module "D:/installs/covalent/win32-ers301/apache2.0/modules/standard/mod_suexec.so" User nobody Group nobody - Delete those lines. They are not needed on windows. 3. (optional) Comment out the snmp module lines unless you need that module. It causes some issues on shutdown, preventing servers from shutting down properly. #LoadModules for non-standard modules. #LoadModule covalent_snmpcommon_module "D:/installs/covalent/win32-ers301/apache2.0/modules/covalent/mod_snmpcommon.so" #LoadModule covalent_snmpagt_module "D:/installs/covalent/win32-ers301/apache2.0/modules/covalent/mod_snmpmonagt.so" 4. You need to make one change to the /conf/startup.pl file - edit apache_startup.bat install ================================= End of Win32 Known issues Section ================================= ******************** ******************** ==================================================== General Installation Instructions for all platforms ==================================================== Long Filenames Require GTAR on Solaris and HPUX =============================================== ERS 3.0 is delivered in .tar.gz format. Be aware that when downloading using some web browsers, that the file may be renamed .tar.tar by the browser. If this happens just rename the file to .tar.gz and proceed. Solaris and HPUX users note: "gtar" must be used to unpack the archive as the archive contains long file names not supported by Solaris and HPUX "tar". If you do not have GTAR, please contact Covalent for a self-executing archive (sfx) file. The instructions are as follows: 1. gunzip and tar -xvf the tarball into your desired installation directory (ERS 3 can be unpacked into an existing ERS 2.4 install directory or into an empty directory) 2. from the install directory, run ./fixrootpath.pl Fixrootpath configures ERS 3 by setting the correct path name in all the files in the installation that require it. ======================================================== Special Win32 installation steps: Running fixrootpath.pl ======================================================== Windows does not come with PERL by default, so make use of the PERL included with ERS when running PERL scripts. Run the fixrootpath script with the following syntax, from the ERS installation directory. Example: > perl5.8\bin\perl fixrootpath.pl End of special Win32 instructions ================================= Testing the installation using preconfigured default servers ============================================================ ERS includes two preconfigured server instances. Use these instances to test the installation. After testing, you can then use the script "ers-server.pl" to create new customized instances or import instances from an ERS 2.4 installation. The default instances have all options enabled and all examples installed. More information on the use of the ers-server.pl script is provided below in the detailed instruction sections below. All server instances are located in the servers directory: //servers/. The two preconfigured default instances are /default20 and /default13. The /default20 instance is configured to run Apache 2.0 and Tomcat 5.0. The /default13 instance is configured to run Apache 1.3 and Tomcat 4.1. 1. Choose one instance to test, either /default20 or /default13. 2. Start tomcat and apache: Example: Steps below refer to /default20 instance, but the same commands apply in the /default13 instance //servers/default20/bin/tomcat_startup.sh start //servers/default20/bin/apache_startup.sh start That will start Tomcat 5.0 and Apache 2.0 respectively. ============================================================= Special Win32 installation steps: Installing Windows Services ============================================================= To install the Apache and Tomcat servers as windows services, invoke the respective startup.bat scripts with the "install" option. Example: > tomcat_startup.bat install > apache_startup.bat install This will install services into the Windows Services control panel, making use of the server name in the service. For example the default20/ services will be called: ERS default20 httpsd ERS default20 tomcat To remove the services, use the uninstall option. Example: > tomcat_startup.bat uninstall > apache_startup.bat uninstall To Install the services so that Apache starts in SSL mode, install with the "installssl" option. NOTE you cannot have both SSL and non-SSL services installed at the same time. You must uninstall one before installing the other. Example Example: > apache_startup.bat uninstall > apache_startup.bat installssl End of special Win32 instructions ================================= The default apache port is set to 8080, so test by: http://yourservername:8080 The default login information is covalent/covalent. Once authenticated you can test the tomcat examples, perl examples, and php examples. By substituting startssl for start in the apache_startup.sh command above, you can also test by: https://yourservername:8443/ using a self-signed, generic (insecure!) key. Customizing the pre-configured servers ====================================== The preconfigured servers include all the Tomcat, PERL, and PHP examples enabled. If you want to customize the Apache or Tomcat configuration while keeping the examples enabled, use the ers-server.pl script to copy one of the default directories to a new location. You can also switch the Tomcat or Apache version to combine Apache 1.3 and Tomcat 5.0 if desired, or to combine Apache 2.0 and Tomcat 4.1. To make a copy of one of the existing server directories, invoke the ers-server.pl script and provide the name of the server directory you wish to copy, and the new name of the directory you wish to have created. The copy will be placed in the new directory. Example: cd ./ers-server.pl --server=newserver --migrate=default20 The example above will create a new server called "newserver" in the servers folder, using the /servers/default20 instance as the source. This means /servers/newserver will have Apache 2.0 and Tomcat 5.0 enabled. Then you can customize the newserver instance while preserving /servers/default20 unchanged. You can also make copies of servers you have customized, and use the script to switch Tomcat or Apache versions. Example2: cd ./ers-server.pl --server=newservertom4 --migrate=newserver --tomcatver=4.1 The example above will copy your newserver server and change the version of tomcat enabled from 5.0 to 4.1. ======================================================= Special Win32 installation steps: Running ers-server.pl ======================================================= Windows does not come with PERL by default, so make use of the PERL included with ERS when running PERL scripts. Run the ers-server script with the following syntax, from the ERS installation directory. Example: > perl5.8\bin\perl ers-server.pl End of special Win32 instructions ================================= ======================================================= Detailed Instructions for Creating New Server Instances ======================================================= Create new server instances using the ers-server.pl script. New server instances do not have examples enabled, and are intended for production usage. When you use ers-server.pl to create a new instance you will be asked a series of questions which will control the configuration of the server you create. You choose the versions of Apache and Tomcat to include in the instance, and you choose which of the extensions to install: PERL, PHP, and/or SNMP. To create a new instance (versus copying an existing one) do not provide the "--migrate" argument. If you leave the argument out, the script assumes you intend to create new custom instance with no preconfigured content other than a default welcome page. Example: cd ./ers-server.pl --server=prodserver --apachever=2.0 --tomcatver=5.0 The above command will create a new server instance with Apache 2.0 and Tomcat 5.0 enabled. You will be asked a series of configuration questions, giving you the options to enable or disable mod_JK, SSL, PERL, PHP and SNMP. You will set the port numbers and provide an initial user account and password and create a temporary SSL certificate and key as part of the installation. You can create server instances of standalone Apache or Standalone Tomcat by only including the version of the component you desire. Example: cd ./ers-server.pl --server=prodtomcat5 --tomcatver=5.0 The above command will create a new server instance with only Tomcat 5.0 enabled. ===================================================================================== Detailed Instructions for Covalent Enterprise Ready Server 3.0 Migration from ERS 2.4 ===================================================================================== Thank you for using Covalent Enterprise Ready Server. This README file contains important information to migrate an installation of servers/{instance} to the new ERS 3.0 product tree. This document does not apply to fresh server installations under ERS 3.0. We recommend that you read the entire document. What's in this README file ========================== - Structural Changes - Enterprise Ready Server 3.0 Contents - Installing the ERS 3.0 Upgrade - Who should apply this upgrade release - Preparing to Upgrade from ERS 2.4 and Previous Releases - Preparing to Upgrade from ERS 2.3 and Previous Releases - Preparing to Upgrade from ERS 2.1 and ERS 2.2 Releases - Migrating to Tomcat 4.1 - Migrating to Tomcat 5.0 - Migrating from Covalent authentication to ASF authentication Structural Changes ================== The new ERS 3.0 product made broad changes to the product deployment directory tree, in order to provide our customers with all of today's supported technologies, and to anticipate our expansions tomorrow. The following list demonstrates the changes from the original to new directory layout, from the Enterprise Ready Server 2.x perspective. ERS 2.x ERS 3.x ------- ------- apache1.3/ apache/ -> apache2.0/ (Any module compiled for Apache 2.0.43 or later can be loaded into this server.) docs/ -> (documentation is distributed seperately) jsdk/ -> j2se1.4/ (j2se1.3 was distributed prior to ERS 2.3) licenses/ -> licenses/ (there is no change, all licenses are collected here) modperl1.3/ modperl/ -> modperl2.0/ php/ -> php4.3/ (available for ERS 2.x only as a patch) snmp/ -> snmp2.0/ (these are simple snmp diagnostic tools) tools/ -> (T.B.D.) perl/ -> perl5.8/ (perl 5.6 was distributed prior to ERS 2.4) servers/ -> servers/ (there is no change, ERS 3 uses servers/ as ERS 2 did) tomcat/ -> tomcat4.1/ (tomcat 4.0 was distributed prior to ERS 2.3) tomcat5.0/ (available for ERS 2.x only as a patch) Enterprise Ready Server 3.0 Contents ==================================== This release contains; Apache HTTP Server 1.3.33 Apache HTTP Server 2.0.53 with Worker and Prefork MPMs. ModPerl 2.0 Release Candidate 4 build PHP 4.3.10 (No zts thread support) Jakarta mod_jk connector 1.2.8 Apache Tomcat 4.1.30 Apache Tomcat 5.0.30 In addition, the distributed support libraries include zlib library 1.2.1-patched (for a security flaw) openldap 2.2.17 client library openssl 0.9.7i perl 5.8.4 Java 2 SDK 1.4.2 No longer included in ERS mod_compat has been deprecated from this release. Since ERS 3.0 includes both Apache 1.3 and Apache 2.0, users who used mod_compat before in the Apache 2.0 environment for Apache 1.3 backend content can now use ProxyReverse directive in mod_proxy module in achieving the same result. This configuration enables a combination of version 2.0 and 1.3 web content at the same site be served from the respective web servers. Third party Apache 1.3 modules, formerly used in compatibility mode in the Apache 2.0 environment, should be obtained from the third party vendor for the latest version. Who should apply this upgrade release ===================================== This update applies to: * Covalent Enterprise Ready Server releases 2.1 through 2.4 * Covalent Enterprise FTP Server releases 2.1 through 2.4 Please follow _all_ of the designated sections, below. E.g. if upgrading an installation from ERS 2.4, follow only the first section below. If upgrading from ERS 2.3, follow the directions under both the upgrading from ERS 2.4 and upgrading from ERS 2.3 sections. All users must follow the instructions for migrating from Covalent authentication to ASF authentication. Installing the ERS 3.0 Upgrade ============================================= Unpack the ers-3.0-{platform}-{date}.tar.gz candidate into the desired ERS product directory. This may either be an ERS 2.4 installation root, or a brand new directory. 1) Copy the appropriate ers-3.0-{platform}-{reldate}.tar.gz product archive to the base directory where the Enterprise Ready Server was originally installed (typically /covalent/ers/, although another path could have been chosen). This is the directory that contains the 'apache', 'modperl', 'tomcat', 'servers' and other server component directories. -or- If a brand new location is desired, create the desired with the mkdir command, and copy the product archive to this new location. 2) Unpack the files from this product archive using the Unix tar utility. cd /covalent/ers tar -zxvf ers-3.0-{platform}-{reldate}.tar.gz -or- gzip -dc ers-3.0-{platform}-{reldate}.tar.gz | tar -xvf - 3) Correct the root paths by invoking the fixrootpath.pl perl script, from within this Covalent Enterprise Ready Server root directory. perl fixrootpath.pl This script, with no additional arguments, will transform each occurance of @@PRODUCT_ROOT@@ in every script and configuration file in the product tree with the working directory from which it is launched. This script must be run under perl 5.005 or later version. Proceed through the instructions below to migrate each installed server instance in the servers/ tree, making required manual adjustments to the configuration files. Then manually stop each previous migrated server and start the corresponding newly created server. Once migration is satisfactory, do not neglect to change any system boot scripts which invoke any of the previous servers, to point to and start the newly migrated servers. Preparing to Upgrade from ERS 2.4 and Previous Releases ======================================================= The first step for all ERS migrations is to use the server migration script ers-server.pl to create an ERS 3.0 based installation. The ers-server.pl script will -not- overwrite an existing server instance, but will copy a server instance in the servers/{servername}/ tree to a new directory, chosen by the user. For example, to copy the server from servers/testserver/ to servers/testserver3/, invoke the following command from the ERS root directory; ./ers-server.pl --migrate=testserver --server=testserver3 which copies the structure to servers/testserver3/, without moving the logs/, work/, var/ or temp/ working directories. This tool only migrates ERS 2.x servers using Apache 2.0. However, it allows the choice between Tomcat 4.1 or 5.0, with the default being Tomcat 4.1. To migrate this same server using the Tomcat 5.0 distribution, invoke; ./ers-server.pl --migrate=testserver --server=testserver3 --tomcatver=5.0 Finally, if the ERS 2.4 tree is installed to a different product root path, say, /opt/ers2.4/, then you may use the syntax; ./ers-server.pl --migrate=testserver --server=testserver3 --erssrc=/opt/ers2.4 to specific a default 'source' tree for the location of the original 'testserver'. In this example, servers/testserver3/ would be created relative to the current working directory, from the /opt/ers2.4/servers/testserver/ tree. Once ers-server.pl is used to assist with mass-updates, several manual changes must be made to the installed directory tree; Preparing to Upgrade from ERS 2.4 and Previous Releases ======================================================= Several steps are required to upgrade the Apache 2.0 httpsd.conf file for each installed server instance. * If you are using the preview of PHP 4 support, you must change from the Apache 2.0 worker MPM to the prefork MPM. In order to support the widest variety of third-party PHP loadable modules, this package includes only the non-threaded build of PHP 4.3.10 with Pear support, and was not built with experimental zts thread safety support. * The Covalent authorization and authentication schema (auth) has been deprecated, and is replaced with the Apache Software Foundation's auth stack. See below section entitled "Migrating from Covalent Authentication to ASF Authentication" for instructions. * The ers-server.pl migration tool modifies httpsd.conf configuration files from mod_covalent_ssl to mod_ssl based on OpenSSL. However, it cannot adjust for hardware crypto device support. You should modify SSLNFast On directives to SSLCryptoDevice chil if you are using this device. When using the hardware acceleration feature, it is important to add the path of the hardware acceleration libraries into the LD_LIBRARY_PATH (linux/solaris/aix) or SHLIB_PATH (hpux). Modify the library path for each instance in the path-to-ers/servers/{servername}/bin/apache_startup.sh script. Preparing to Upgrade from ERS 2.3 and Previous Releases ======================================================= There are two additional changes between your installed Covalent Enterprise Ready Server 2.3.0 and 2.3.1 releases and this patch release (2.4 version users should ignore this list): * The Covalent Headers module is no longer distributed with Covalent Enterprise Ready Server release 2.3.2 or later. These products are now distributed with the Apache Headers module. All references to the mod_covalent_headers.so and its configuration directives must be replaced with mod_headers.so and its corresponding configuration directives. * On Windows installations, the SSLMutex directive must be: SSLMutex default in order to start the server. The SSLMutex file directive that was part of the stock configuration is no longer valid under Windows (Unix users are not affected by this step.) Correct the above issues as applicable, in all httpsd.conf files, prior to updating to this patch release. Preparing to Upgrade from ERS 2.1 and ERS 2.2 Releases ====================================================== There are additional httpsd.conf server configuration directives which have changed between the Covalent Enterprise Ready Server 2.1 and 2.2 releases and this patch release (2.3 and 2.4 version users should ignore this list): * The SSLLog and SSLLogLevel directives are gone, and must be removed from all configuration files (those messages are now logged in accordance with the ErrorLog and LogLevel directives). * SSLSessionCache must be specified when mod_ssl.so or mod_covalent_ssl.so is loaded. Earlier httpsd.conf files from Covalent Enterprise Ready Server loaded mod_covalent_ssl.so unconditionally, and wrapped all SSL configuration directives within an block. Surround the LoadModule line with the same block to avoid this problem, e.g. LoadModule ssl_module "path-to-ers/apache/modules/standard/mod_ssl.so" * The LoadModule directive, for Perl modules only, is now LoadPerlModule (loadable Apache .so modules continue to use the LoadModule directive). * The Covalent Logging module is no longer distributed with Covalent Enterprise Ready Server release 2.2 and later. All references to the Covalent Logging module mod_log_covalent.so and its configuration directives must be removed. * The PHP module is no longer distributed with Covalent Enterprise Ready Server release 2.2 or later, but will be introduced again in the next full ERS release. All references to the PHP module mod_php4.so and its configuration directives must be removed, or contact your support representitive for a preview release of the coming PHP support. * The Covalent Usertrack module is no longer distributed with Covalent Enterprise Ready Server release 2.2 or later. All references to the mod_covalent_usertrack.so and its configuration directives must be removed. * Using the CGI.pm module (available from CPAN and generally distributed with Perl, including the bundled Perl in Covalent Enterprise Ready Server) with modperl now requires the line 'use Apache::compat ();' to be enabled in the server's startup.pl configuration script. Remove the # comment prefix for that line. * HP/UX Users Only: You must modify the apache_startup.sh script in each of your installed servers. Locate the lines in the script: LD_LIBRARY_PATH="$root_dir/apache/lib:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH for each installed {server} in /usr/covalent/ers-2.1/servers/{server}/bin and replace the LD_LIBRARY text with SHLIB, so the apache_startup.sh scripts now read: SHLIB_PATH="$root_dir/apache/lib:$SHLIB_PATH" export SHLIB_PATH Migrating to Tomcat 4.1 ======================= You must modify your server.xml file to point at an appropriate connector, Apache Tomcat 4.1 now uses the Coyote connector technology, to provide a more sophisticated hosting environment. In the server.xml files, replace these attribute; className="org.apache.ajp.tomcat4.Ajp13Connector" with the preferred Tomcat 4.1 Connector choice; className="org.apache.coyote.tomcat4.CoyoteConnector" protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler" Migrating to Tomcat 5.0 ======================= You must modify your server.xml file to point at an appropriate connector, Apache Tomcat 5 no longer uses any className arguments to define the connector. In the server.xml files, replace these attributes; className="org.apache.coyote.tomcat4.CoyoteConnector" protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler" or the older attribute from Tomcat 4.0 and 4.1.12; className="org.apache.ajp.tomcat4.Ajp13Connector" with the new Tomcat 5 attribute; protocol="AJP/1.3" Here is an example of the port 8009 connector after the changes. Note the removal of the className argument, and the change in the protocol value: For the web.xml configuration file, the url-pattern '*' is no longer understood. You must modify your url-pattern tags to be somewhat more specific (e.g. "*.jsp"). Within the Security Manager .policy files, codeBase URLs for jar files loaded from the web application repositories followed the "jar:file:path/to/code.jar!/-" syntax in Tomcat 4.0. This must be simplified to "file:path/to/code.jar" for Tomcat 4.1 and 5.0. Some existing servlets, taglibs etc, must be recompiled for the new jars. This may include the taglib used by the Covalent example pages. You may ignore any errors in the Covalent example pages caused by the Tomcat 4 taglib. Migrating from Covalent Authentication to ASF Authentication ============================================================ ERS 3.0 contains the ASF authentication stack. The Covalent authentication stack is no longer provided or supported. Migrating to ASF authentication involves editing the httpsd.conf file and making the changes described below. NIS, Oracle, and ODBC authentication are no longer supported. Remove Covalent Authentication ================================ 1) Comment or remove all the Covalent and Switchboard auth module load lines: [remove these if you find them] #LoadFile "/path/to/apache/lib/liblber.so" #LoadFIle "/path/to/apache/lib/libldap.so" #LoadModule switchboard_module "/path/to/apache/modules/covalent/mod_covalent_switchboard.so" #LoadModule covalent_ldap_module "/path/to/apache/modules/covalent/mod_covalent_auth_ldap.so" #LoadModule covalent_auth_module .. (etc) 2) Comment or remove all 'AddCovalentAuthBackEnd' lines in the conf file. 3) Remove all instances of the word "covalent" in the authentication directives in the body of the httpsd.conf file For example: CovalentAuthUserFile should be changed to AuthUserFile Add ASF authentication ========================= Depending on the method of authentication desired, load the appropriate ASF authentication modules. Note that all authentication methods requre the mod_auth module, and this is the only module required for basic file authentication. Basic file authentication: LoadModule auth_module "/path/to/apache2.0/modules/standard/mod_auth.so" Anonymous authentication: LoadModule auth_module "/path/to/apache2.0/modules/standard/mod_auth.so" LoadModule auth_anon_module "/path/to/apache2.0/modules/standard/mod_auth_anon.so" DBM authentication: LoadModule auth_module "/path/to/apache2.0/modules/standard/mod_auth.so" LoadModule auth_dbm_module "/path/to/apache2.0/modules/standard/mod_auth_dbm.so" Digest authentication: LoadModule auth_module "/path/to/apache2.0/modules/standard/mod_auth.so" LoadModule auth_digest_module "/path/to/apache2.0/modules/standard/mod_auth_digest.so" LDAP authentication (requires additional syntax changes described below): Load the following modules in this order. LoadModule auth_module "/path/to/apache2.0/modules/standard/mod_auth.so" LoadModule ldap_module "/path/to/apache2.0/modules/standard/mod_ldap.so" LoadModule auth_ldap_module "/path/to/apache2.0/modules/standard/mod_auth_ldap.so" Then follow the instructions below to convert the syntax to the new ASF syntax. This documentation applies only to the Apache 2.0 LDAP module. Complete documentation for the mod_auth_ldap module can be found at: http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html Connection Directives The 4 directives that specify the LDAP directory in Covalent auth have been replaced by a single directive, AuthLDAPUrl. [http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html#authldapurl] For example: CovalentLDAPServer 10.0.0.110 CovalentLDAPPort 389 CovalentLDAPBaseDN o=Covalent,c=US CovalentLDAPLoginProperty uid Is now: AuthLDAPUrl ldap://10.0.0.110:389/o=Covalent,c=USuidsub See the AuthLDAPUrl documentation for more information. It's of note that any attribute listed in the attributes section (uid in the example above) will be passed into the environment, making the Covalent auth CovalentLDAPPassProperty directive no longer required. The directives CovalentLDAPBindDN and CovalentLDAPBindPW have moved to AuthLDAPBindDN and AuthLDAPBindPassword respectively. [http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html#authldapbinddn] [http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html#authldapbindpassword] Authorization CovalentLDAPGroupProperty has moved to AuthLDAPGroupAttribute. The syntax of 'require group' has changed to include the group base, so the CovalentLDAPGroupBase directive is no longer needed. [http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html#authldapgroupattribute] For example: CovalentLDAPGroupBase ou=Groups,o=Covalent Technologies, c=US require group "All Staff" Is now: require group cn=All Staff, ou=Groups, o=Covalent Technologies, c=US The directive CovalentLDAPRequireAll has been deprecated, so if any require line succeeds, authorization will succeed. With upcoming versions of mod_ldap, this will again be supported by use of the Require ldap-filter directive. This is currently in the Apache 2.1 tree, and may be released in Apache 2.2. SSL Support SSL support in mod_ldap has also changed. SSL can be enabled by using the directives LDAPTrustedCA and LDAPTrustedCAType in addition to using ldaps:// in the AuthLdapURL. [http://httpd.apache.org/docs-2.0/mod/mod_ldap.html#ldaptrustedca] [http://httpd.apache.org/docs-2.0/mod/mod_ldap.html#ldaptrustedca] For more information on using SSL see: http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html#usingssl TLS Support Covalent has backported the TLS fixes on the 2.1 version of mod_ldap into 2.0. To use TLS simply add STARTTLS or TLS as a second argument to the AuthLDAPUrl. Currently client certificates are not supported. Caching and Connection Pools LDAP caching is implemented in auth_ldap. CovalentLDAPCacheExpires is now LDAPCacheTTL. CovalentLDAPCacheEntries is now LDAPCacheEntries. [http://httpd.apache.org/docs-2.0/mod/mod_ldap.html#ldapcachettl]. [http://httpd.apache.org/docs-2.0/mod/mod_ldap.html#ldapcacheentries] The CovalentLDAPCacheMaxAccesses is no longer supported. The LDAP module has built-in connection pooling, so mod_switchboard is no longer required. For more information see the LDAP module documentation: http://httpd.apache.org/docs-2.0/mod/mod_ldap.html