Being a holiday and the geek that I am, today I decided to tackle the insanely difficult process of attempting to compile the Atlassian Crowd authenticator module for Apache into a cPanel server running CentOS.
Inherently it seems that noone had successfully documented this anywhere as the RPMs would not install correctly (due to the fact they were compiled against an old version of Apache) and therefore needed to be built from source.
So to document how on earth I achieved this please see below. Note I have tested this on a default cPanel install on an up to date CentOS 5.6 Final install as at... 10 minutes ago 
.
Prerequisites
- Have a test server, and for the love of your own sanity ensure you completely backup your config PRIOR to attempting this. I make no warranties express or implied that your server won't implode into its own miniature black-hole right in front of your very eyes.
- Have root access to the server, all commands below must be executed as the root user
 | Things to note Throughout developing this procedure I managed to discover that the ./configure script for the Atlassian Crowd Authenticator module has a few little quirks, I have managed to modify this procedure from the original "extended" procedure to make things far easier. If you wish to see the original unabridged version of the steps you can find them at the bottom of this document. |
Steps
| No. | Description | Notes/Gotchas | ||||
|---|---|---|---|---|---|---|
| 1 | Take a backup of your server and configs | REALLY I mention this again as I know some people WONT do this. Do "future you" a favour and take a backup now! | ||||
| 2 | Install apr and apr devel with yum | This is required as a pre-requisite even if apr is compiled in cPanel's apache install yum install apr apr-devel | ||||
| 3 | Make software folder and change to that directory | This is not required, just good policy. mkdir /root/software cd /root/software | ||||
| 4 | Download the authenticator module and extract | For the latest download link see http://confluence.atlassian.com/display/CROWD/Installing+the+Crowd+Apache+Connector+on+Other+UNIX-Like+Systems wget https://studio.plugins.atlassian.com/svn/CWDAPACHE/tags/2.0.2/mod_authnz_crowd-2.0.2.tar.gz tar -xvzf mod_authnz_crowd-2.0.2.tar.gz cd mod_authnz_crowd-2.0.2 | ||||
| 5 | Run autoreconf to prepare for compiling | autoreconf --install | ||||
| 6 | Create symbolic links | See "Configure Script Gotchas" below for details ln -s /usr/local/apache/ /usr/local/apache2 ln -s /usr/local/apache/ /usr/lib/apache2
| ||||
| 7 | Recompile apache with Dav, and Dav Lock | You can do this with either /scripts/easyapache or the WHM Interface | ||||
| 8 | Create "dummy" modules | This will ensure that the ./configure script can complete successfully. While this is not ideal until such a time as Atlassian can resolve the ./configure script issues it is the easiest way around this. touch /usr/local/apache/modules/mod_dav.so /usr/local/apache/modules/mod_dav_lock.so chmod a+x /usr/local/apache/modules/mod_dav.so /usr/local/apache/modules/mod_dav_lock.so | ||||
| 9 | Install Subversion | Subversion is required by the subversion authentication connector. This must include the mod_dav_svn apache module not just the SVN client for CentOS.
| ||||
| 10 | Change directory back to downloaded module | cd /root/software/mod_authnz_crowd-2.0.2 | ||||
| 11 | Configure, make and install the module | ./configure make make install | ||||
| 12 | Remove the following lines from /usr/local/apache/conf/httpd.conf | LoadModule authnz_crowd_module modules/mod_authnz_crowd.so LoadModule dav_svn_module modules/mod_dav_svn.so LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so | ||||
| 13 | Add the following lines to Apache global includes | Add the following directives into /usr/local/apache/conf/includes/pre_main_global.conf, this can be done via SSH or via the WHM interface if you prefer. LoadModule authnz_crowd_module modules/mod_authnz_crowd.so <IfModule mod_dav_svn.c> LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so </IfModule> | ||||
| 14 | Restart Apache | service httpd restart | ||||
| 15 | Installation is completed | Don't forget to remove the dummy modules rm -rf /usr/local/apache/modules/mod_dav.so /usr/local/apache/modules/mod_dav_lock.so |
Configure Script Gotchas
I have logged two bugs to Atlassian for issues with the configure script. If you use this script please consider voting on these issues as they would greatly simplify the process:
- https://jira.atlassian.com/browse/CWD-2742 <-- ./configure script does not work with certain Apache configurations due to hardcoded file locations
- https://jira.atlassian.com/browse/CWD-2743 <-- ./configure script fails when mod_dav is compiled as static module in Apache
Possible errors you may encounter throughout the process
| Error | Likely occurrence | Mitigation | Related Step No. |
|---|---|---|---|
| configure: error: apr_pool_pre_cleanup_register was not found in libapr- | If you try to run ./configure for the apache module prior to downloading apr and apr-devel | Install apr and apr-devel | 2 |
| -bash: ./configure: No such file or directory | Autoreconf has not yet been run | Run autoreconf | 5 |
| configure: error: Could not locate Apache include directory | Symbolic links have not been created | Create symbolic links | 6 |
| configure: error: Could not locate Subversion directory | Subversion has not been installed | Install subversion | 9 |
| configure: error: Could not locate Apache modules directory | Symbolic links have not been created | Create symbolic links | 6 |
Original Extended version of the Steps with all workarounds
Steps
| No. | Description | Notes/Gotchas | ||
|---|---|---|---|---|
| 1 | Take a backup of your server and configs | REALLY I mention this again as I know some people WONT do this. Do "future you" a favour and take a backup now! | ||
| 2 | Install apr and apr devel with yum | This is required as a pre-requisite even if apr is compiled in cPanel's apache install yum install apr apr-devel | ||
| 3 | Make software folder and change to that directory | This is not required, just good policy. mkdir /root/software cd /root/software | ||
| 4 | Download the authenticator module and extract | For the latest download link see http://confluence.atlassian.com/display/CROWD/Installing+the+Crowd+Apache+Connector+on+Other+UNIX-Like+Systems wget https://studio.plugins.atlassian.com/svn/CWDAPACHE/tags/2.0.2/mod_authnz_crowd-2.0.2.tar.gz tar -xvzf mod_authnz_crowd-2.0.2.tar.gz cd mod_authnz_crowd-2.0.2 | ||
| 5 | Run autoreconf to prepare for compiling | autoreconf --install | ||
| 6 | Create symbolic links | See "Filesystem Gotcha's" below for details ln -s /usr/local/apache/ /usr/local/apache2 ln -s /usr/local/apache/ /usr/lib/apache2 | ||
| 7 | Create custom EasyApache hooks | For full details see http://docs.cpanel.net/twiki/bin/view/EasyApache3/CustomConfigureFlags for which file you should create based on your version if it is different to apache 2.2 Create file /var/cpanel/easy/apache/rawopts/Apache2_2 with below content (one per line) --enable-dav=shared --enable-dav-fs=shared --enable-dav-lock=shared | ||
| 8 | Run EasyApache to recompile | Ensure you deselect Dav, Dav FS, and Dav Lock on the exhaustive modules list screen before selecting to compile. This can be run either via the command line or the WHM Interface. /scripts/easyapache | ||
| 9 | Add Load_Module directives to Apache global includes | Add the following directives into /usr/local/apache/conf/includes/pre_main_global.conf, this can be done via SSH or via the WHM interface if you prefer. LoadModule dav_module modules/mod_dav.so LoadModule dav_lock_module modules/mod_dav_lock.so LoadModule dav_fs_module modules/mod_dav_fs.so | ||
| 10 | Restart Apache | service httpd restart | ||
| 11 | Install Subversion | Subversion is required by the authentication connector, how you do this is up to you, I am working on a script but it is old and buggy if you wish to get a copy please leave a comment here. This must include the mod_dav_svn apache module not just the SVN client for CentOS.
| ||
| 12 | Change directory back to downloaded module | cd /root/software/mod_authnz_crowd-2.0.2 | ||
| 13 | Configure, make and install the module | ./configure make make install | ||
| 14 | Remove the following lines from /usr/local/apache/conf/httpd.conf | LoadModule authnz_crowd_module modules/mod_authnz_crowd.so LoadModule dav_svn_module modules/mod_dav_svn.so LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so | ||
| 15 | Add the following lines to Apache global includes | Add the following directives into /usr/local/apache/conf/includes/pre_main_global.conf, this can be done via SSH or via the WHM interface if you prefer. LoadModule authnz_crowd_module modules/mod_authnz_crowd.so LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so | ||
| 16 | Restart Apache | service httpd restart | ||
| 17 | Installation is completed |