Difference between revisions of "How to use EPrints with HTTPS"

From EPrints Documentation
Jump to: navigation, search
(Updated to reflect more recent versions of EPrints)
Line 5: Line 5:
 
If you are using Debian/Ubuntu see [[HTTPS for Debian/Ubuntu]].
 
If you are using Debian/Ubuntu see [[HTTPS for Debian/Ubuntu]].
  
===Configuration===
+
''Note: Setting up your Apache Web server is beyond the scope of this document.  Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.''
  
Edit <tt>archives/[repoid]/cfg/cfg.d/10_core.pl</tt>. It will probably look like this:
+
== Configuration ==
  
  $c->{host} = 'yomiko.ecs.soton.ac.uk';
+
 
  $c->{port} = 8080;
+
To start setting up your existing archive to work under HTTPS, you must first edit <tt>archives/[repoid]/cfg/cfg.d/10_core.pl</tt>. Initially it will probably look something like the following which is the basic 10_core.pl configuration file after you have run <tt>bin/epadmin create</tt> to setup your archive.  Alternatively you could run <tt>bin/epadmin config_core [repoid]</tt> that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.
 +
 
 +
  $c->{host} = 'your.dnshostname.org';
 +
  $c->{port} = 80;
 
  $c->{aliases} = [];
 
  $c->{aliases} = [];
  #$c->{securehost} = 'yomiko.ecs.soton.ac.uk';
+
  $c->{securehost} = '';
  #$c->{secureport} = 8083;
+
  $c->{secureport} = 443;
  #$c->{securepath} = '/secure';
+
  $c->{http_root} = undef;
  
Add to the end of this file the following settings:
+
Update the file to define the secure host and modify ports as needed.  If your Apache web server is not using the standard ports (80,443) you can adjust the 'port' and 'secureport' parameters in the config file accordingly.
  
  $c->{securehost} = 'HOSTNAME';
+
  $c->{host} = 'your.dnshostname.org';
  #$c->{secureport} = 'PORT';
+
  $c->{port} = 80;
 +
$c->{aliases} = [];
 +
$c->{securehost} = 'your.dnshostname.org';
 +
$c->{secureport} = 443;
 +
$c->{http_root} = undef;
 +
 
 +
These additional settings may (but rarely) come into play are the following for special or for older setups.  In general these settings are only used when dealing with keeping settings from earlier versions of the EPrints software where you've migrated the 10_core.pl file from originally.  These configuration parameters tend to be deprecated.
  
  $c->{http_root} = "";
+
  $c->{securepath} = '/secure';
 
  $c->{https_root} = '/secure';
 
  $c->{https_root} = '/secure';
 
  $c->{http_cgiroot} = '/cgi';
 
  $c->{http_cgiroot} = '/cgi';
 
  $c->{https_cgiroot} = '/secure/cgi';
 
  $c->{https_cgiroot} = '/secure/cgi';
  
Where HOSTNAME is the hostname of your HTTPS server. If your HTTPS server is not using the standard port 443 specify it here. The <tt>http(s)_(cgi)root</tt> variables specify the path to EPrints on your HTTP and HTTPS servers.
 
  
Now run <tt>bin/generate_apacheconf</tt> to generate the secure Apache configuration and copy the default template to the template used for HTTPS.
+
== Generate the Apache Configuration File for HTTPS ==
  
Add the following line inside your Apache SSL virtual host declaration (probably in <tt>/etc/httpd/conf.d/mod_ssl.conf</tt>):
+
Run <tt>bin/generate_apacheconf</tt> to generate the secure Apache configuration files and depending upon the version of EPrints you are using, it may copy the default template <tt>archives/[repoid]/cfg/lang/en/templates/default.xml</tt> to the template used for HTTPS <tt>archives/[repoid]/cfg/lang/en/templates/secure.xml</tt>.  This will also setup the repository configuration file located in the <tt>/opt/eprints3/cfg/apache_ssl/</tt> directory named [repoid].conf.
 +
 
 +
 
 +
== Add the Main Apache Config File to SSL Config ==
 +
 
 +
Depending upon the version of EPrints you are running there are a couple files that may be involved.  It is recommended to run <tt>bin/generate_apacheconf --man</tt> or view the source of <tt>bin/generate_apacheconf</tt> file to understand what file(s) need to be setup.  In general you will need to place a line like either of the following inside your Apache SSL Virtual Host declaration (most likely found in <tt>/etc/httpd/conf.d/mod_ssl.conf</tt> or <tt>/etc/httpd/conf.d/ssl.conf</tt>).  Make sure that these lines are placed inside the <VirtualHost> Apache directive.
  
 
  Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf
 
  Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf
  
Restart Apache.
+
Or
 +
 
 +
Include /opt/eprints3/cfg/apache_ssl.conf
 +
 
 +
 
 +
== Restart Apache to pick up the changes to the Apache configuration ==
 +
Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as <tt>root</tt> or using <tt>sudo</tt>:
 +
# /sbin/service httpd restart
 +
 
 +
# /etc/init.d/apache2 restart
 +
 
 +
 
 +
== Confirmation ==
 +
 
 +
Open your web browser and access your repository via its URL, this should be done over HTTP.  When you click to login you should notice that you will be redirected to an HTTPS connection.  Note that in general most tasks that require you to login are now redirected to an HTTPS connection otherwise an HTTP request will be used.

Revision as of 15:09, 6 October 2015

Manual Sections

For information on setting up HTTPS on EPrints versions earlier than 3.0.5 see Https3.

If you are using Debian/Ubuntu see HTTPS for Debian/Ubuntu.

Note: Setting up your Apache Web server is beyond the scope of this document. Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.

Configuration

To start setting up your existing archive to work under HTTPS, you must first edit archives/[repoid]/cfg/cfg.d/10_core.pl. Initially it will probably look something like the following which is the basic 10_core.pl configuration file after you have run bin/epadmin create to setup your archive. Alternatively you could run bin/epadmin config_core [repoid] that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.

$c->{host} = 'your.dnshostname.org';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = ;
$c->{secureport} = 443;
$c->{http_root} = undef;

Update the file to define the secure host and modify ports as needed. If your Apache web server is not using the standard ports (80,443) you can adjust the 'port' and 'secureport' parameters in the config file accordingly.

$c->{host} = 'your.dnshostname.org';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = 'your.dnshostname.org';
$c->{secureport} = 443;
$c->{http_root} = undef;

These additional settings may (but rarely) come into play are the following for special or for older setups. In general these settings are only used when dealing with keeping settings from earlier versions of the EPrints software where you've migrated the 10_core.pl file from originally. These configuration parameters tend to be deprecated.

$c->{securepath} = '/secure';
$c->{https_root} = '/secure';
$c->{http_cgiroot} = '/cgi';
$c->{https_cgiroot} = '/secure/cgi';


Generate the Apache Configuration File for HTTPS

Run bin/generate_apacheconf to generate the secure Apache configuration files and depending upon the version of EPrints you are using, it may copy the default template archives/[repoid]/cfg/lang/en/templates/default.xml to the template used for HTTPS archives/[repoid]/cfg/lang/en/templates/secure.xml. This will also setup the repository configuration file located in the /opt/eprints3/cfg/apache_ssl/ directory named [repoid].conf.


Add the Main Apache Config File to SSL Config

Depending upon the version of EPrints you are running there are a couple files that may be involved. It is recommended to run bin/generate_apacheconf --man or view the source of bin/generate_apacheconf file to understand what file(s) need to be setup. In general you will need to place a line like either of the following inside your Apache SSL Virtual Host declaration (most likely found in /etc/httpd/conf.d/mod_ssl.conf or /etc/httpd/conf.d/ssl.conf). Make sure that these lines are placed inside the <VirtualHost> Apache directive.

Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf

Or

Include /opt/eprints3/cfg/apache_ssl.conf


Restart Apache to pick up the changes to the Apache configuration

Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as root or using sudo:

# /sbin/service httpd restart
# /etc/init.d/apache2 restart


Confirmation

Open your web browser and access your repository via its URL, this should be done over HTTP. When you click to login you should notice that you will be redirected to an HTTPS connection. Note that in general most tasks that require you to login are now redirected to an HTTPS connection otherwise an HTTP request will be used.