Installation Guide

Prerequisite Versions

The version of Java and Tomcat seen on the screenshots in this guide do not reflect the actual version required for installing various products. Please refer to the prerequisite lists on the product's page. Usually, Tomcat 8+ and Java 8+ is required. The process of installation is the same as what is described below.

Installation of the Java Runtime Environment

  1. Run the JRE Installer as Administrator.
  2. The installation process starts.
  3. Click the Install button to accept the license terms and to continue with the installation.
  4. A few brief dialogs confirm the last steps of the installation process.
  5. Click Close on the last dialog. This will complete Java installation process.

Java Setup - Welcome Screen

Java Setup - Complete Screen

Installing Apache Tomcat

  1. Run the Apache Tomcat Windows Installer as Administrator.
  2. Follow the instructions.
  3. Select Service Startup and Native options, then click Next.
  4. Setup Service name, Ports, Administrator user, etc.

Administrator login should have the admin role to access JMelody (/monitoring) page. These settings and more can be modified later in conf/server.xml file. Care should be taken when editing this file. Only the default configuration modified using steps described here is supported. Other settings may not be supported (e.g. multiple hosts, clustering). Consult with an engineer before modifying this file to accommodate customer networking needs like redirction, HA, etc.

  1. Set JRE path.
  2. Set install path.
  3. Finish installation.
  4. Check service installation result.
  5. Modify the maxThread setting of the Connector as required by the anticipated load.

The default of 200 is enough for 200 event queue connections (each page, each API client has one of these), but requests also consume a thread for a short time, so the default supports about 100 users if each has one page. In server.xml modify the Connector definition:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="1024"   scheme="https" secure="true" SSLCertificateFile="..." SSLCertificateKeyFile="..." clientAuth="false" sslProtocol="TLS"/\>
  1. Set the maximum / minimum memory for the Tomcat JVM to 2048 / 1024 MB. This can be done with Tomcat8w.exe, running on the tray: right click -> Configure -> Java tab -> Initial memory pool / maximum memory pool
  2. Add the following JVM flags on the Java tab on the Tomcat config tool (Tomcat8w.exe): 
    -Xloggc:\<logs folder\>/gc.log  
    -XX:+PrintGCDetails  
    -XX:+PrintGCDateStamps

This enables Garbage Collector logging.

  1. Restart the server. Consult Tomcat documentation for high-load installations for further optimization of Tomcat configuration.

Apache Tomcat Setup - Welcome screen

WebServer Security hardening

Hardening security on Desktop Connect application WebServer please visit this article

Generate Self Signed Certificate

This section provides only one method of server self signed certificate creation.

Create Certificate Request for Web Server

  1. Login into the Desktop Connect Server with a domain user that is also local administrator on the machine.
  2. Start the Management Console by typing mmc in the start menu.
  3. Click File.
  4. Click Add / Remove Snap-in.
  5. Select the Certificate Snap-in and add it to the console.
  6. Select Computer Account to manage the certificates installed on computer.
  7. Select Local Computer and finish the wizard.
  8. Expand the Personal folder in the Certificates.
  9. Right-click on All Tasks.
  10. Select Advanced Operations.
  11. Create Custom Request.
  12. Go to Start the certificate request.
  13. Select the Enrollment Policy.
  14. Select the template of the certificate to the Reverse Proxy must select Web Server/Web Server Plus Client Exportable template.
  15. Expand Details on the Certificate Information tab.
  16. Click ***Properties ***to configure the options of the Certificate.
  17. Navigate to the Subject tab on the Certificate Properties page.

  18. Specify the following: Common Name and Value set the FQDN of the primary service that uses the certificate – this is Desktop Connect server e.g. desktopconnect.yourdomain.com.

  19. Select Typer as part of Alternative Name: IP and DNS.

  20. Add all FQDN's that bear the certificate.

  21. Set the Friendly Name of the certificate on the General tab. This option does not affect any functionality of the certificate. Just add a brief description of the functionality of the certificate.

  22. Expand the Key Options on the Private Key tab and check the Make Private key exportable. Apply the changes and finish the wizard.

  23. Select the folder where the request is saved under Certificate Enrollment advance and finish the assistant.

Download Certificate from CA (.cer file)

  1. Access the Active Directory Certificate Services on your network https://<FQDN Certificate Authority>/CertSrv
  2. Click Request Certificate.
  3. Click the Advanced Certificate Request.
  4. Select Submit a certificate request by using the base 64-encoded CMC or PKCS # 10 file, or submit a renewal request by using the base 64-encoded PKCS # 7 file.
  5. Open the request file (DesktopConnect_self) in Notepad, select and copy the entire content.
  6. Paste the content of the file request in the space Saved Request.
  7. Select the Certificate Template: Web Server/Web Server Plus Client Exportable.
  8. Click Submit.
  9. The certificate will be generated.
  10. Click Download Certificate and save the certificate in a folder.
  11. Check that the settings of the certificate are correct and that the option of private key is present in the certificate.

Import the Certificate (.cer file)

  1. Return to the Management Console and expand Personal.
  2. Right click on Certificates.
  3. Select All Tasks
  4. Click Import
  5. Start the certificate import.
  6. Select the saved certificate.
  7. Go to the configuration of the Certificate Store.
  8. Finalize the wizard.
  9. The certificate must be imported and ready to be linked to services.

Export Certificate to PFX file

  1. Once the certificate was successfully installed, it is ready to be exported into PFX format.
  2. Navigate to Personal → Certificates in the Management console.
  3. Locate the imported certificate.
  4. Right click on All Tasks → **Export.
  5. Click Next.
  6. Select **Yes, export the private key.
  7. Select **Personal Information Exchange* – PKCS #12 (.PFX)*
  8. Specify a password to protect the private key.
  9. Specify the file name.
  10. Complete the export.

Configure HTTPS on Tomcat

HTTPS has to be configured on the Desktop Connect server if Salesforce.com is only accessible over a secure hypertext transfer protocol.

In such scenario, it is strongly recommended that Desktop Connect web content is also served over HTTPS as the web browser tends to display on secured content and usually do not allow mixed mode.

Install OpenSSL and APR Native Library

OpenSSL

  1. Locate the OpenSSL installer within the ISO image. Download is available via: https://slproweb.com/products/Win32OpenSSL.html

  2. Execute the installer *Win32OpenSSL_Light-1_0_1i.exe.
    *

  3. Follow the standard installation steps. The application is installed on C:\OpenSSL by default.

APR Native Library

The Apache Tomcat Native Library is an optional component to use with Apache Tomcat. This allows Tomcat to use certain native resources for performance, compatibility, etc.

Specifically, the Apache Tomcat Native Library gives Tomcat access to the Apache Portable Runtime (APR) library's network connection (socket) implementation and random-number generator. See the Apache Tomcat documentation for more information on how to configure Tomcat to use the APR connector.

Features of the APR connector:

  • Non-blocking I/O for Keep-Alive requests (between requests)
  • Uses OpenSSL for TLS/SSL capabilities (if supported by linked APR library)
  • FIPS 140-2 support for TLS/SSL (if supported by linked OpenSSL library)

  1. Locate the APR native zip file tomcat-native-1.1.32-win32-bin.zip within the ISO image. Download is available via: http://tomcat.apache.org/tomcat-7.0-doc/apr.html

  2. Extract the tcnative-1.dll that applies to your OS system.

  3. Place it in the Tomcat binary folder.

Configure Tomcat

Once the OpenSSL and APR Native library has been installed and configured on the system, the Tomcat configuration can be completed.

  1. Run the following Open SSL commands using Windows Run command:

    • Run the following command to export the private key, when prompted type in the password that was used to secure the private key: openssl pkcs12 -in DesktopConnect.pfx -nocerts -out key.pem -nodes
    • Run the following command to export the certificate, when prompted type in the password that was used to secure the private key: openssl pkcs12 -in DesktopConnect.pfx -nokeys -out cert.pem
    • Run the following command to remove the passphrase from the private key: openssl rsa -in key.pem -out DesktopConnect.key

  2. Locate and open the *server.xml* file from the Tomcat installation. This should be located under: [TOMCAT Folder]/config/server.xml.

  3. Make sure the following values are set in the server configuration:

     <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /><Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="1024" scheme="https" secure="true" SSLCertificateFile="[CertificatePath]/DesktopConnect.cer" SSLCertificateKeyFile="[CertificatePath]/DesktopConnect.key" clientAuth="false" sslProtocol="TLS"/><!-- Define an AJP 1.3 Connector on port 8009 --><Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> e.g. [CertificatePath] = C:/Program Files/Apache Software Foundation/Tomcat 6.0/conf/

  4. Restart Tomcat.

This method requires OpenSSL and APR Native library to be installed on Tomcat.

Sorry, your browser does not support inline SVG. article updatedarticle updated6/23/2020 9:06:57 AM (UTC)6/23/2020 9:06:57 AM (UTC)