ApacheConfigMigration

Apache Configuration

The EPrints apache configuration is distributed across a number of files. This layout changed between EPrints version 3.1 and 3.2 - this page explains the differences and advises how to migrate to the new layout after upgrading from 3.1 to 3.2+.

Apache Configuration in 3.1

cfg/
└── apache.conf
var/
├── auto-apache.conf
└── auto-apache-includes.conf
archives/
└── <ARCHIVEID>
    ├── cfg
    │   ├── apache.conf
    │   └── apachevhost.conf
    └── var
        ├── auto-apache.conf
        ├── auto-secure.conf
        └── entities.dtd

Note auto-secure.conf will only be present if using SSL

File Overview (3.1)

cfg/apache.conf

• Loads files from var/

var/auto-apache-includes.conf

• Loads HTTP configuration for each repository: archives/<ARCHIVEID>/cfg/apache.conf

var/auto-apache.conf

• Global HTTP configuration

archives/<ARCHIVEID>/cfg/apache.conf

• Loads archives/<ARCHIVEID>/var/auto-apache.conf

archives/<ARCHIVEID>/var/auto-apache.conf

• VirtualHost for repository
• Loads archives/<ARCHIVEID>/cfg/apachevhost.conf

archives/<ARCHIVEID>/cfg/apachevhost.conf

• Empty - add custom directives here

archives/<ARCHIVEID>/var/auto-secure.conf

• Repository-specific SSL configuration (note no VirtualHost)

Loading into Apache (3.1)

Example 1 - Debian/Ubuntu

HTTP - create a new "site" which loads the top level EPrints apache configuration file:

$ cat /etc/apache2/sites-available/eprints3
Include /opt/eprints3/cfg/apache.conf
$ a2ensite eprints3

SSL - load the repository-specific EPrints apache configuration file from inside an SSL VirtualHost:

$ cat /etc/apache2/sites-available/default-ssl
<IfModule mod_ssl.c>
	<VirtualHost _default_:443>
		...
		Include /opt/eprints3/archives/<ARCHIVEID>/var/auto-secure.conf
	</VirtualHost>
</IfModule>
$ a2ensite default-ssl

Example 2 - RedHat/CentOS

HTTP - load top level EPrints apache configuration file:

$ tail /etc/httpd/conf/httpd.conf
...
Include /opt/eprints3/cfg/apache.conf

Note if EPrints is installed from RPM, check /etc/httpd/conf.d/eprints.conf

SSL - load the repository-specific SSL configuration from inside an SSL VirtualHost:

$ cat /etc/httpd/conf.d/ssl.conf
...
<VirtualHost _default:443>
	...
	Include /opt/eprints3/archives/<ARCHIVEID>/var/auto-secure.conf
</VirtualHost>

Apache Configuration in 3.2+

From 3.2 onwards things were simplified - there are fewer configuration files in a single location. The configuration files are shorter as much of the processing was moved into the EPrints::Apache::Rewrite module.

cfg/
├── apache.conf
├── apache
│   └── <ARCHIVEID>.conf
├── apache_ssl.conf
└── apache_ssl
    └── <ARCHIVEID>.conf

Note apache_ssl* files will only be present if using SSL.

File Overview (3.2+)

cfg/apache.conf

• Global configuration
• Loads HTTP configuration for each repository: cfg/apache/*.conf

cfg/apache/<ARCHIVEID>.conf

• VirtualHost for repository
• Loads archives/<ARCHIVEID>/cfg/apachevhost.conf if present

cfg/apache_ssl.conf

• Global SSL configuration
• Loads SSL configuration for each repository: cfg/apache_ssl/*.conf

cfg/apache_ssl/<ARCHIVEID>.conf

• Repository-specific SSL configuration (note no VirtualHost)

Loading into Apache (3.2+)

Example 1 - Debian/Ubuntu

HTTP - create a new "site" which loads the top level EPrints apache configuration file:

$ cat /etc/apache2/sites-available/eprints3
Include /opt/eprints3/cfg/apache.conf
$ a2ensite eprints3

SSL - load the top level EPrints apache configuration file from inside an SSL VirtualHost:

$ cat /etc/apache2/sites-available/default-ssl
<IfModule mod_ssl.c>
	<VirtualHost _default_:443>
		...
		Include /opt/eprints3/cfg/apache_ssl.conf
	</VirtualHost>
</IfModule>
$ a2ensite default-ssl

Note: this assumes a single SSL repository or multiple SSL repositories sharing the same securehost - for multiple repositories with different securehost settings each reposity-specific SSL configuration file may need to be loaded in a separate VirtualHost.

Example 2 - RedHat/CentOS

HTTP - load top level EPrints apache configuration file:

$ tail /etc/httpd/conf/httpd.conf
...
Include /opt/eprints3/cfg/apache.conf

Note if EPrints is installed from RPM, check /etc/httpd/conf.d/eprints.conf

SSL - load the repository-specific SSL configuration from inside an SSL VirtualHost:

$ cat /etc/httpd/conf.d/ssl.conf
...
<VirtualHost _default:443>
	...
	Include /opt/eprints3/cfg/apache_ssl.conf
</VirtualHost>

Note: this assumes a single SSL repository or multiple SSL repositories sharing the same securehost - for multiple repositories with different securehost settings each reposity-specific SSL configuration file may need to be loaded in a separate VirtualHost.

Migrating apache configuration from 3.1 to 3.2+

This won't happen automatically when you upgrade from 3.1 to 3.2+ so follow the steps below to migrate the apache configuration after upgrading:

1. Back up the 3.1 apache configuration files
2. Check for any custom directives added to 3.1 apache config files, in particular cfg/apache.conf and archives/<ARCHIVEID>/cfg/apache.conf
3. Run bin/generate_apacheconf --system --replace - this will generate the new apache configuration files as above
4. If using SSL change the top level apache SSL configuration file to load /opt/eprints3/cfg/apache_ssl.conf instead of /opt/eprints3/archives/<ARCHIVEID>/var/auto-secure.conf
5. Merge custom directives back in as appropriate (noting that custom directives may be lost if generate_apacheconf is run with the --system or --replace option)
6. Restart apache
7. After successful testing, the following 3.1 configuration files can be removed:

var/auto-apache.conf
var/auto-apache-includes.conf
archives/<ARCHIVEID>/cfg/apache.conf
archives/<ARCHIVEID>/var/auto-apache.conf
archives/<ARCHIVEID>/var/auto-secure.conf