Month: September 2022

IMPORTANT For Instructions on current versions of exacqVision Enterprise Manager versions 22.06 or higher see Knowledge Base Article #12804

This document details how to enable HTTPS connections to exacqVision Enterprise System Manager on versions 22.03 or lower.

For a trusted certificate, it is recommended that you purchase a third-party intermediate certificate from one of many online providers. If you are using a third-party certificate you may skip ahead to the section titled, “Obtaining a Third-Party Certificate”. 

These steps will detail how to create a self-signed certificate, but be aware that web browsers will warn users that the certificate is untrusted if you are using a self-signed certificate or one from a private/internal certificate authority.

CREATING A SELF-SIGNED SSL CERTIFICATE

Windows

1) Click on the Windows Start button and type ‘CMD’. Right-click on the CMD icon and choose ‘Run as Administrator’.

2) Set the environmental variable that will be used by OpenSSL later by typing:

set OPENSSL_CONF=C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf\openssl.cnf

Press Enter.

3) Change your working directory by typing:

cd "C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\bin"  

Press Enter.

4) Create a certificate request by typing:

openssl req -new -out %USERPROFILE%\Desktop\server.csr 

Press Enter.

You will be prompted to enter a PEM pass phrase. Enter anything you like but you will need to re-enter this in the following steps. 

PEM pass phrase:  

5) You will be prompted with several questions for the certificate, answer these according to your needs. COMMON NAME should be the IP address or FQDN that users will access to reach the ESM web site (ex. www.domain.com or esmserver.domain.com).

6) Remove the pass phrase by typing:

openssl rsa -in privkey.pem -out %USERPROFILE%\Desktop\server.key  

Press Enter. 

You will be prompted to enter the pass phrase you created in step 4. Enter this pass phrase and press Enter. 

7) Set the expiration date for the certificate by typing:

openssl x509 -in %USERPROFILE%\Desktop\server.csr -out %USERPROFILE%\Desktop\server.crt -req -signkey %USERPROFILE%\Desktop\server.key -days 365  

Press Enter.

8) Copy the resulting files from your Desktop to the C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf\ directory.

Linux

These instructions were tested with exacqVision Enterprise Manager 20.09 running on Ubuntu 18.04

Step 1  Create self-signed Cert and Key files 

cd /usr/local/exacq/esm/apache_solr/apache2/conf/

sudo openssl req -new -x509 -sha256 -days 365 -nodes -out server.crt -keyout server.key

You will be prompted with a series of questions.
– Use data specific to your site.
– Items can be left blank with the exception of Common Name
– Common Name (e.g. server FQDN or YOUR name) should be the IP address of EM Server

Step 2 Validate the Cert and Key files 

sudo openssl x509 -noout -modulus -in /usr/local/exacq/esm/apache_solr/apache2/conf/server.crt | openssl md5

sudo openssl rsa -noout -modulus -in /usr/local/exacq/esm/apache_solr/apache2/conf/server.key | openssl md5

Verify the md5 hashes match, if they DO NOT then see the troubleshooting section below before proceeding.

Step 3 Edit Apache Configuration

cd /usr/local/exacq/esm/apache_solr/apache2/conf/extra

sudo gedit httpd-ssl.conf

Make the following changes, save the file and then close gedit.

Step 4 Restart the enterprise-webservice

sudo service enterprise-webservice stop

sudo service enterprise-webservice start

<br>

OBTAINING A THIRD-PARTY CERTIFICATE

If you are planning to acquire a third-party certificate from a trusted provider, you may need to provide them with a Certificate Signing Request (CSR) file. 

You may use our tool at the following URL to generate a CSR file.   https://exacq.com/support/gencsr/

Enter all the fields click on the ‘Submit’ button to download the ZIP file. Inside this ZIP file is the CSR file and RSA key to give to your certificate provider. 

If you purchased a chained certificate, be sure to download the appropriate intermediate bundle.

Once you have downloaded the files from your provider:

• Rename the .crt file to ‘server.crt’. 
• Rename the .key file to ‘server.key’.
• If you have a chained certificate, rename the chain file to ‘server-ca.crt’.

Place the renamed files from your Certificate Authority (CA) into the following directory:

• Windows: C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf\
• Linux:  /etc/evapache/

TIPS

When purchasing an SSL certificate, many providers offer an Intermediate Bundle, or additional certificates that must be present to link your certificate to a root certification authority. Usually the provider will have documentation on how to accomplish this with Apache, but it is a good idea to ask them before or during the purchasing process. Exacq is not responsible for making your certificates capable of working with Apache. 

It is possible to combine all the intermediate certificates that a provider may give you into one file. Consult your provider for more information. 

<br>

ENABLING SSL FOR HTTPS CONNECTIONS

Be sure that you have followed the steps above to place the certificate files necessary for either a third-party certificate or a self-signed certificate into the correct directory before continuing with the following steps.

Windows

1) Click on the Windows Start menu and find the Windows Notepad program. Right-click on this and choose to ‘Run as Administrator’. If you do not run Notepad as an administrator you will be unable to save your changes. 

2) With Notepad open, click on the ‘File’ menu and choose ‘Open’ or press CTRL-O on the keyboard. 

In the Open browser, change the drop-down menu for File Type from ‘Text Documents (*.txt)’ to ‘All Files (*.*)’.

Use the Open browser to open the C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf directory and highlight the file titled ‘httpd.conf’ then click ‘Open’.

3) Find the following line:

LoadModule ssl_module modules/mod_ssl.so  

Remove any pound (#) sign in front of this line if there is one. 

Now, find the following line:

Include conf/extra/httpd-ssl.conf  

Remove any pound (#) sign in front of this line if there is one. 

Save the file. 

4) Still using Notepad, open the file titled ‘httpd-ssl.conf’ located in C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf\extra

Find the following line:

ServerName www.example.com:443  

Change the ‘www.example.com’ portion of this line to ‘localhost’.

Save the file and close the window. 

5) Restart the solrApache service in Windows services (services.msc).

Linux

1) Open a Terminal prompt.

2) Change your working directory by typing:

cd /usr/local/exacq/esm/apache_solr/apache2/conf  

Press Enter.

3) You may use any editor you feel comfortable with, such as vi or nano, but if your are more inclined to using a graphical interface you may use a program called ‘gedit’ to make the following changes.

In the Terminal, type:

sudo gedit httpd.conf  

Press Enter.

4) Find the following line:

LoadModule ssl_module modules/mod_ssl.so  

Remove any pound (#) sign in front of the line if there is one.

Now, find the following line:

Include conf/extra/httpd-ssl.conf  

Remove any pound (#) sign in front of the line if there is one. 

Save the file and close the ‘gedit’ editor window to return to the Terminal prompt.

5) In the Terminal, type:

sudo gedit extra/httpd-ssl.conf  

Press Enter.

Find the following line:

ServerName www.example.com:443  

Change the ‘www.example.com’ portion of this line to ‘localhost’.

Save the file and close the window to return to the Terminal prompt. 

6) Restart the service in the Terminal by typing:

sudo service ESMWebservice restart  

<br>

FORCED REDIRECT FROM HTTP TO HTTPS

If you want to force users who try to access the site on port 80, using HTTP, to use the secure HTTPS connection you will need to enable a redirection.

Windows

1) Click on the Windows Start menu and find the Windows Notepad program. Right-click on this and choose to ‘Run as Administrator’. If you do not run Notepad as an administrator you will be unable to save your changes. 

2) With Notepad open, click on the ‘File’ menu and choose ‘Open’ or press CTRL-O on the keyboard. 

In the Open browser, change the drop-down menu for File Type from ‘Text Documents (*.txt)’ to ‘All Files (*.*)’.

Use the Open browser to open the C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\conf directory and highlight the file titled ‘httpd.conf’ then click ‘Open’.

3) Find the following lines:

#RewriteCond %{SERVER PORT} !^443$  
#RewriteRule ^/(.*) https://{HTTP_HOST}/$1 [NC,R=301,L]  

Remove the pound (#) signs in front of these two lines.

Save the file.

4) Restart the solrApache service in Windows services (services.msc).

Linux

1) You may use any editor you feel comfortable with, such as vi or nano, but if your are more inclined to using a graphical interface you may use a program called ‘gedit’ to make the following changes.

In the Terminal, type:

sudo gedit /usr/local/exacq/esm/apache_solr/apache2/conf/httpd.conf  

Press Enter.

2) Find the following lines:

#RewriteCond %{SERVER PORT} !^443$  
#RewriteRule ^/(.*) https://{HTTP_HOST}/$1 [NC,R=301,L]  

Remove the pound (#) signs in front of these two lines.

Save the file and close the ‘gedit’ window to return to the Terminal prompt.

3) Restart the service in Terminal by typing:

sudo service ESMWebservice restart
or
sudo service enterprise-webservice restart

<br>

TROUBLESHOOTING

1) Some versions of Internet Explorer do not easily work with services running locally or may display pages incorrectly. If this happens, try clearing the browser’s cache by pressing CTRL-F5 on the keyboard. If the problem is persistent try installing another web browser, such as Chrome. 

2) If the solrApache service fails to start after configuring it for SSL:

a) Open the Apache error logs

• Windows:   C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\logs\error.log
• Linux:   /usr/local/exacq/esm/apache_solr/apache2/logs/error_log

b) Look for an entry like the following:

[Wed Mar 04 09:08:54.512004 2017] [ssl:emerg] [pid 19116] AH02565: Certificate and private key www.example.com:443:0 from server.crt and server.key do not match AH00016: Configuration Failed  

c) If you see this log entry, complete the following steps:

1) Change your working directory to the location of openssl.exe

• Windows (CMD) – cd C:\Program Files\exacqVision\EnterpriseManager\apache_solr\apache2\bin
• Linux (Terminal) – cd /etc/evapache/extra

2) Run the following commands:

openssl x509 -noout -modulus -in ../conf/server.crt | openssl md5  

Press Enter.

openssl rsa -noout -modulus -in ../conf/server.key | openssl md5  

Press Enter.

openssl req -noout -modulus -in ../conf/server.csr | openssl md5  

Press Enter.

3) Compare the resulting values output after running each of the preceding commands. Each resulting string should be identical. If the values do not match, confer with the certificate authority that issued the certificate.