Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    What steps are required to set up SSL on a Voyager server?

    • Product: Voyager
    • Product Version: All
    • Relevant for Installation Type: Multi-Tenant Direct, Dedicated-Direct, Local, TotalCare

    Table of contents

    Question

    How would SSL be set up on a Voyager server?

    Answer

    Customers are allowed to install SSL on their Voyager servers. The standard Voyager installation can be configured for this.

    For instructions on installing SSL using LetsEncrypt! see Can we install LetsEncrypt SSL certificate with Voyager

    Ex Libris does not provide support for Voyager SSL. The steps outlined below are meant as advisement on how this procedure may be accomplished. Note that exact steps may vary depending on local hardware and other variables.

    Note that implementing SSL may require outgoing http links from WebVoyage to be changed to https. An example might be found in the /jscripts/googleBooksAvail.js file. Otherwise the browser may throw errors or warnings that say something like "Only secure content is displayed." or "This request has been blocked; the content must be served over HTTPS."

    Set up directories and initial configuration on Voyager server
    1. SSH/telnet to server as root
    2. Create directory for Secure Certificate information.

    mkdir /m1/shared/apache2/conf/tls
    chmod 700 /m1/shared/apache2/conf/tls

     

    1. Create directory for SSL session cache.

    mkdir -p /var/cache/apache2
    chmod 700 /var/cache/apache2

    ​​​​​​

    1. Start process of creating encryption key and certificate signing request (CSR):

    /m1/shared/openssl/bin/openssl req -newkey rsa:2048-nodes \

       -keyout /m1/shared/apache2/conf/tls/server.key \

       -out /m1/shared/apache2/conf/tls/server.csr

    1. Enter data when command prompts for it
      1. Country Name (2 letter code) - This is ISO Alpha-2 Country code for your country:
        • US (United States)
        • GB (United Kingdom)
        • AU (Australia)
        • NZ (New Zealand)
        • FI (Finland)
        • CA (Canada)
      2. State or Province Name (full name). This is the full name of your state or province, e.g. Illinois
      3. Locality Name (typically city), e.g. Des Plaines
      4. Organization Name, e.g. Ex Libris Group
      5. Organizational Unit Name, e.g. Voyager Support
      6. Common Name - This is the DNS name that your users will be connecting to the server with, e.g. voyager.exlibrisgroup.com
      7. E-mail Address - The name of the administrative contact for the certificate (your e-mail address)
      8. Challenge password: This is a password that your Secure Certificate provider may use to authenticate you
      9. An optional company name: press enter here
    2. Print the certificate signing request to the screen: cat /m1/shared/apache2/conf/tls/server.csrThe output will look something like this:
    -----BEGIN CERTIFICATE REQUEST-----
    MIIDGDCCAgACAQAwgb0xCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhJbGxpbm9pczEU
    MBIGA1UEBwwLRGVzIFBsYWluZXMxGDAWBgNVBAoMD0V4IExpYnJpcyBHcm91cDEQ
    MA4GA1UECwwHVm95YWdlcjEoMCYGA1UEAwwfdXMtcGlwMDMuY29ycC5leGxpYnJp
    c2dyb3VwLmNvbTEvMC0GCSqGSIb3DQEJARYgamFtZXMubWl0Y2hlbGxAZXhsaWJy
    aXNncm91cC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCoauNf
    n88j/AjblRmozZQEYJgQ9ka4NEUVGXF9O4lIUZRSrXk+vR2HlDlurm1oS7HaBJVe
    8oMy8b+euqzxnUuz3t0YNd1YNOe1tDv3B6j0YNjByDHWrjcHq/r/8MrvDWOMpXg+
    QqFLWwN3dgXA50bbJ+VluoywUJExr9ZgP5221JZfoALafJJ3tYb5GLu+wfW7ACfA
    DM+LKof7+Lg6LkTxSpvi1lDI5ZLlefdC+dL4G9LIx3N9Kx6/Gb0qOGsUjWovgElo
    k9vf37NlE/3JVhBqLEe32TwwMYNnd34TPykVzFovXmakesf945vy1ea+XAGceqnh
    AHpfd8PwXCdUEcrzAgMBAAGgFTATBgkqhkiG9w0BCQcxBgwEZnJlZDANBgkqhkiG
    9w0BAQsFAAOCAQEATJobrJFpx5UGWO38ZnvqbeaXYtjobtD1seitLSsDZZMAIXsJ
    Vc3H85rC/wMwyCZKfRDVU4ZvSjsUPleldPSZIUgE267CP1ktxfDWpFc71J0uQa8Y
    EiRrptAkDvwZc6Ko4ivs1BXmVN4bqABBURAbGwl8PP2bQT6NnVNqNt/3558qocbn
    RTM5JIFkNCfeS3wVOkbfw4wftltNcBSjqAKbkMkTkc9wIR87arIlDVYdS5xrcwEE
    dZQk1nXZo5jcgex4+tSI9XB+5ZiKBDoYNztwogNDMeLAonrF+Mk7Yq+4x1xayJVO
    B2DMlwwx8wkMwCShD/Jn0EKPtklVOjyCDYEOiA==
    -----END CERTIFICATE REQUEST-----
    Purchase certificate and add to Voyager server
    1. Purchase SSL certificate from certificate provider.
    2. Copy and paste contents of /m1/shared/apache2/conf/tls/server.csr (from Step 6 in previous section) in field provided for CSR (Certificate Signing Request). The Certificate Provider will evaluate request and send a new SSL certificate file. There will also typically be a SSL CA Certificate provided.
    3. Save the certificate file to your server as /m1/shared/apache2/conf/tls/server.crt.
    4. If provided, save the SSL CA Certificate as /m1/shared/apache2/conf/tls/provider.crt
    Configure Apache for SSL
    1. As root on the server where certificate(s) saved, configure Apache:

    cd /m1/shared/apache2/conf/modules.conf
    mv mod_ssl.CONF mod_ssl.conf

    If no mod_ssl.CONF exists in the above location, try:

    cd /m1/shared/apache2/conf.new/modules.conf
    mv mod_ssl.CONF /m1/shared/apache2/conf/modules.conf/mod_ssl.conf

    1. Back up the file for the Apache virtual host that you wish to configured.

    cd /m1/shared/apache2/conf/ActivatedVirtualHosts

    cp xxxdb_vwebv_httpd.conf ../ConfiguredVirtualHosts/xxxdb_vwebv_httpd.conf-preSSL

    1. Edit xxxdb_vwebv_httpd.confto set up SSL Handling. Find section near the top of the file where the Virtual Host port is configured. Typical configuration before the change might be:

    Listen *:80
    <VirtualHost *:80>

    1. Copy these lines to a note file (will use later) and update configuration. Typically port 443 will be configured:

    Listen *:443
    <VirtualHost *:443>

     

    If there is no line for Listen, add one.

    1. Look for Configuration options ServerName and ServerAlias and copy these lines to note file.
    2. Find the log section:

    ErrorLog logs/xxxdb/error.log
    CustomLog logs/xxxdb/access.log common

    1. Insert the following lines before the log configuration:

    SSLEngine on
    SSLCipherSuite ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS
    SSLCertificateFile /m1/shared/apache2/conf/tls/server.crt
    SSLCertificateKeyFile /m1/shared/apache2/conf/tls/server.key

    1. If there is a provider certificate, also include this line:

    SSLCertificateChainFile /m1/shared/apache2/conf/tls/provider.crt

    1. Add a new Virtual Host to redirect users from old (http) URL to the new (https) URL. At bottom of the file, and insert the lines copied from main virtual host here - Listen, <VirtualHost...>, ServerName and ServerAlias lines in the order they occurred above
    2. Add the following line, wheresecure.example.com is new DNS name as entered for CN when generating the CSR: Redirect permanent / https://secure.example.com/
    3. Close the Virtual Host block with </VirtualHost>
    4. The result should look something like this (see also: Can ExLibris provide a SSL httpd config sample?)

    Listen *:80
    <VirtualHost *:80>
    ServerName www.example.com
    ServerAlias library.example.com
    Redirect permanent / https://secure.example.com/

    </VirtualHost>

    1. Save.
    2. For Solaris servers, you may need to change the ownership for the SSL directories.  Find the entries for 'User' and 'Group' in /m1/shared/apache2/conf/httpd.conf.  These are typically 'elgweb' and 'nobody'. Change the ownership of the SSL directories you set up accordingly:

     chown -R elgweb:nobody /m1/shared/apache2/conf/tls /var/cache/apache2 

    Check syntax and restart Apache

     

    1. Check Apache changes for errors:  /m1/shared/apache2/bin/apachectl -t
    2. If Apache is happy with changes, the result will beSyntax OK If that is not result, correct errors, and repeat check.
    3. Restart apache: /m1/shared/apache2/bin/apachectl restartand watch for any errors printed to the screen
    4. Check that apache started successfully: ps -ef |grep http should produce result similar to
      $ ps -ef |grep http
    root      4796     1  0 04:36 ?        00:00:00 /m1/shared/httpd/2.2.31_2015.09.1/bin/httpd -k start
    nobody    4859  4796  0 04:36 ?        00:00:00 /m1/shared/httpd/2.2.31_2015.09.1/bin/httpd -k start
    nobody    4860  4796  0 04:36 ?        00:00:00 /m1/shared/httpd/2.2.31_2015.09.1/bin/httpd -k start
    voyager   6578     1  0 04:37 ?        00:00:00 /m1/shared/apache2/bin/httpd -d /m1/voyager/xxxdb/pds/apache
    voyager   6581  6578  0 04:37 ?        00:00:00 /m1/shared/apache2/bin/httpd -d /m1/voyager/xxxdb/pds/apache
    voyager   6582  6578  0 04:37 ?        00:00:00 /m1/shared/apache2/bin/httpd -d /m1/voyager/xxxdb/pds/apache
    voyager   6583  6578  0 04:37 ?        00:00:00 /m1/shared/apache2/bin/httpd -d /m1/voyager/xxxdb/pds/apache
    1. If no httpd processes running, or if only PDS apache processes are running, check last few lines of /m1/shared/apache2/logs/error_log:tail -20 /m1/shared/apache2/logs/error_log

    2. Correct any errors indicated by error log, and repeat until Apache starts.

    3. Test the new https URL. Also test that connecting with http redirects to https URL.

    • Article last edited: 09-Apr-2018