ESM Server Installation Guide - Unix

Important note

It is recommended that you review the document titled Functional Overview of ESM before continuing with the tasks outlined here.

System requirements

Hardware Requirements

Provisioning a standalone host to run the ESM Server component is advisable. The following host specifications are recommended:

• Minimum 2 CPUs or vCPUs (4 recommended)
• 8GB RAM
• 2GB system Storage for the ESM Server installation
• 50 – 100GB Storage for the underlying ESM Database tablespace

Larger deployments with an increased number of end users, jobs or nodes may require more resource. If in doubt, contact Boemska Support for assistance when sizing the ESM Server host.

Supported Versions of Unix/Linux

• 64 bit Linux (RedHat / CentOS EL6 or later recommended)

Supported Databases

• A standalone database installation is no longer required.

Note on supported databases

As of March 2018, support for third party databases is being phased out in favour of the embedded ESM Database (currently based on PostgreSQL 9.5). The embedded ESM database ships with the ESM Server binaries, and provisioning of a standalone database component is no longer required. For legacy documentation on MySQL or Oracle based deployment methods please contact Boemska Support.

Installation Requirements

Ports

If a firewall is configured, the following ports will need to be opened for communication between the ESM Agent(s) and the ESM Server. The default ports are listed below. Custom ports can be specified during installation if required:

Port	Description	Mandatory	Notes
18080	Default HTTP port for ESM communication
18181	Default HTTPS port for ESM communication		For embedded HTTPS, not required
14848	Default Glassfish administration port		For debug purposes, not required
15432	Default Database JDBC connection port		When configuring DB replication

Correct functioning of embedded HTTPS requires manual configuration of certificates. As an alternative, configuration with a separate reverse proxy is recommended. For details contact Boemska Support.

If the ESM Embedded Database is clustered across multiple hosts, more detailed firewall configuration may be required.

User Accounts

An Operating System account under which to run the ESM Server is required. ESM requires an account with the following properties:

• A centrally managed or non-expiring password (recommended)
• Read/Write access to the target installation directory and subdirectories

Warning

Do not install the ESM Server as the root user. The Operating System username chosen for the ESM user account also cannot be the same as the Database account username specified during the configuration of the embedded ESM database, which by default is esm. For a vanilla installation it is therefore recommended that the name esm is avoided when provisioning an Operating System user for the ESM application to run under. A username starting with esm, such as esmuser or esmserver, is acceptable.

ESM Server Installation

Unpacking the ESM Server Installation package

1. Log on to the server using the nominated account with the required installation privileges (see installation requirements for more details)

2. Download the appropriate ESM Server installation package for your Linux/Unix operating system. Installation packages can be obtained by signing in to the Boemska Downloads site at https://boemskats.com or by contacting your Boemska representative.

3. Unpack the archive to a suitable temporary location. This guide assumes a target location of /pub/esm/esm-server-installer

tar xzf ./esm-server-x64-linux-v1.0-branch_build.tar.gz -C /pub/esm

Running the Installation Wizard

1. Change directory to the destination of the unpacked installation package and execute the setup.sh script to start the ESM Server Installation Wizard.

cd /pub/esm/esm-server-installer/
./setup.sh

1. The ESM Server installation wizard will now start. You should be greeted with the Terms of License, which you can accept by typing 'y':

   $ ./setup.sh 
   
    Terms of License and User Agreement 
   
   Please review the following Terms of License before installing the ESM Agent.
   
        By typing 'y' you confirm that:
   
   i)   there is a valid license agreement in place which duly authorises you to use this
   ii)  you have read the Software License Agreement and you understand its terms and
   iii) you agree to be bound by the terms and conditions of the Software License
        software and describes your rights and obligations as a licensee of this software
   
        You should not proceed and select 'n' if you cannot confirm any of the
        statements above.
   
   If you accept the Terms of License above please type 'y' to continue.  y
   

2. You will be presented with a choice of database. Select 1) Embedded:

   =============================================================================
    ESM Server Installer Started.
    Current time:  Sun Jul  8 20:34:22 UTC 2018
   =============================================================================
   
   
   1) Embedded (pgsql, most common option)
   2) MySQL
   3) Oracle
   4) PostgreSQL
   Please choose the database which will be used: 1
   Embedded database selected.
   
   Embedded database hostname set to localhost.
   

3. Confirm the port and JDBC URL for the embedded defaults.

   Enter the database port number for Embedded database: [default: 15432]
   
   Port 15432 is ok.
   Enter the JDBC connection URL for Embedded database: [default: jdbc:postgresql://localhost:15432/esm]  
   

4. Specify the username and password for the user which will be created in the ESM database and which the ESM application will use to connect. Note the Warning in the User Accounts section above.

   Enter the Embedded database password (type 'none' for blank password): [default: esm]
   esmdb123 
   (again) Confirm the database password: 
   esmdb123
   

5. Next, specify the filesystem paths where ESM will be deployed. For a single filesystem deployment, the defaults are sane; if a separate partition is provisioned for data storage, specify it in the Embedded database data directory step:

   Please specify esm-server install path: [default: /home/esmuser]
   
   Enter the Embedded database installation directory: [default: /home/esmuser/esm-server/pgsql]
   
   Selected installation directory for Embedded is /home/esmuser/esm-server/pgsql.
   
   Enter the Embedded database data directory: [default: /home/esmuser/esm-server/pgsql/data]
   
   Selected data dir for Embedded is /home/esmuser/esm-server/pgsql/data.
   
   Enter the Embedded database logs directory: [default: /home/esmuser/esm-server/pgsql/logs]
   
   Selected logs dir for Embedded is /home/esmuser/esm-server/pgsql/logs.
   

6. At this stage the database will be deployed, and the SQL output from the schema generation will most likely fill the terminal screen. The output should look something like this (significant output highlighted):

   Extracting embedded postgres database to /home/esmuser/esm-server/pgsql ...
   Initializing embedded database...
   The files belonging to this database system will be owned by user "esmuser".
   This user must also own the server process.
   
   The database cluster will be initialized with locale "en_US.UTF-8".
   The default text search configuration will be set to "english".
   
   Data page checksums are disabled.
   
   fixing permissions on existing directory /home/esmuser/esm-server/pgsql/data ... ok
   creating subdirectories ... ok
   selecting default max_connections ... 100
   selecting default shared_buffers ... 128MB
   selecting dynamic shared memory implementation ... posix
   creating configuration files ... ok
   running bootstrap script ... ok
   performing post-bootstrap initialization ... ok
   syncing data to disk ... ok
   
   WARNING: enabling "trust" authentication for local connections
   You can change this by editing pg_hba.conf or using the option -A, or
   --auth-local and --auth-host, the next time you run initdb.
   
   Success. You can now start the database server using:
   
       ./pg_ctl -D /home/esmuser/esm-server/pgsql/data -l logfile start
   
   Appending database tunning parameters to postgresql.conf file...
   waiting for server to start.... done
   server started
   LOG:  database system was shut down at 2018-07-08 20:34:57 UTC
   LOG:  MultiXact member wraparound protections are now enabled
   LOG:  database system is ready to accept connections
   LOG:  autovacuum launcher started
   CREATE ROLE
   GRANT
   Checking database connection...
   Embedded database successfully checked.
   <...>
   

   This will be followed by around 600 lines of SQL output, trailing with something like the following:

   20:35:02,046  INFO SchemaExport:268 - schema export complete
   20:35:02,046  INFO DriverManagerConnectionProvider:170 - cleaning up connection pool: 
                   jdbc:postgresql://localhost:15432/esm
   Jul 08, 2018 8:35:02 PM com.acedigital.esm.server.HibernateUtil exportSchema
   INFO: SCHEMA EXPORT DONE...
   waiting for server to shut down.... done
   server stopped
   

7. Next configure the ports on which the ESM Server application will bind to. You may want to cange the ESM Server port, but should accept the defaults for all other ports unless more than one instance of ESM Server is to be installed on this machine.

   Enter the port that esm server will use: [default: 18080]
   
   Port 18080 is ok.
   Enter the port that esm admin will use: [default: 14848]
   
   Port 14848 is ok.
   Enter the port that esm will use for secure connection: [default: 18181]
   
   Port 18181 is ok.
   Enter the port that esm admin will use for JMS service: [default: 17676]
   
   Port 17676 is ok.
   Enter the port that esm admin will use for EJB service: [default: 13700]
   
   Port 13700 is ok.
   

8. Specify the username and password for the ESM Administrator account, which will be used to configure ESM from the Web interface:

   Enter the esm admin settings username: [default: esmadm]
   
   Enter the esm admin settings password: [default: Orion123]
   

   Keep the ESM Administrator username and password details safe.

9. The ESM server will now be extracted and installed. On successful completion, you should see a message similar to the following. Enter 'y' to start the ESM Server:

   Extracting server to /home/esmuser ...
   Configuring server installation...
   Configuring server database connection...
   Configuring esm admin user...
   Exporting selected database...
   Exporting database scripts...
   
   -----------------------------------------------------------------------------
      ESM server installation complete:
      Successfully installed to: /home/esmuser/esm-server
   -----------------------------------------------------------------------------
   
      NOTE: Make sure that port 18080 is open for agents connections.
   
   You can start ESM Server by running this command:
      /home/esmuser/esm-server/bin/esm-server.sh start
   
   You can access to your server at:
      http://esmsrv:18080/esm-1.0/
   
    Your esm administration username: esmadm
    Your esm administration password: XXXXX
   
   Do you want to start it now? (y/n):  y
   Starting embedded database...
   waiting for server to start.... done
   server started
   Waiting for domain1 to start ....
   Successfully started the domain : domain1
   domain  Location: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1
   Log File: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1/logs/server.log
   Admin Port: 14848
   Command start-domain executed successfully.
   

Note

It will take around 30 to 60 seconds before the web interface is accessible, as the ESM Web Application is deployed into its Application Server for the first time. During this deployment, a java process owned by the ESM installation user will consume a lot of CPU. Once this process has subsided, the application will be ready and accessible via the URL provided.

Updating the ESM License

1. Using a web browser, navigate to http://localhost:18080/esm-1.0/ where 18080 is the port you configured ESM Server on. If accessing from a machine other than the server, you must specify the hostname or IP address of the ESM Server in place of localhost. You should be presented with a screen requesting a license file
   

2. Click Browse to navigate and select your ESM license file.

3. Click Upload, then click Renew License.

4. The License Holder and Expiry Date should be updated with the new license details.

5. Click Refresh. You should see the main ESM Web Application screen.

Validating the Database Connection

1. Click on Admin Settings button from the main ribbon (top right)
   

2. Enter the ESM Administrator username and password you configured during installation

3. Verify that the application is connecting to the database correctly, by checking the reported Database Size: The size of the database should be reported, showing a good connection between the ESM Server and the ESM Database and normal operation of the ESM Server application.

Note

This concludes the ESM Server Installation and Configuration steps. Now proceed with the ESM Agent installation and configuration steps for each node to be monitored, as outlined in the ESM Agent Installation Guide for Unix.

Server Administration

Starting and Stopping the ESM Server

Starting ESM Server

1. Change directory (cd) to the path of the ESM Server binaries e.g. /pub/esm/esm-server/bin

2. Run the following command to start ESM:

   ./esm-server.sh start
   

3. The server will now launch and a message similar to the following should be displayed:

   [esmuser@esmsrv bin]$ ./esm-server.sh start
   Starting embedded database...
   waiting for server to start.... done
   server started
   Waiting for domain1 to start ...................
   Successfully started the domain : domain1
   domain  Location: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1
   Log File: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1/logs/server.log
   Admin Port: 14848
   Command start-domain executed successfully.
   

Stopping ESM Server

1. Change directory (cd) to the path of the ESM Server binaries e.g. /pub/esm/esm-server/bin

2. Run the following command to stop ESM:

   ./esm-server.sh stop
   

3. The server will now stop and a message similar to the following should be displayed:

   [user@esmserver bin]$ ./esm-server.sh stop
   Waiting for the domain to stop .
   Command stop-domain executed successfully.
   Stopping embedded database...
   waiting for server to shut down.... done
   server stopped
   

4. Should you encounter any issues stopping ESM server, a force-stop command can be issued as follows:

   ./esm-server.sh force-stop
   

5. Force stop identifies the pid under which the server is running and issues a SIGKILL signal. This command should only be used if the normal stop command fails to stop the server.

Restarting ESM Server

Stopping and starting ESM server can be achieved using the restart option on the ESM Server script

1. Change directory (cd) to the path of the ESM Server binaries e.g. /pub/esm/esm-server/bin

2. Run the following command to start ESM:

   ./esm-server.sh restart
   

3. The server will now stop and immediately start. A message similar to the following should be displayed:

   Waiting for the domain to stop .
   Command stop-domain executed successfully.
   Stopping embedded database...
   waiting for server to shut down.... done
   server stopped
   Starting embedded database...
   waiting for server to start.... done
   server started
   Waiting for domain1 to start ...................
   Successfully started the domain : domain1
   domain  Location: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1
   Log File: /home/esmuser/esm-server/esm-core/glassfish/domains/domain1/logs/server.log
   Admin Port: 14848
   Command start-domain executed successfully.
   

Inspecting the ESM Server Log files

The ESM Server log generates two log files: one for the application JVM, and one for the embedded database.

ESM Server JVM Log

By default, the ESM Server log file is located under the logs path of the Glassfish application server instance inside the ESM Server directory:

/pub/esm/esm-server/esm-core/glassfish/domains/domain1/logs/

ESM Server Database Log

By default, the ESM Database log file is located under the logs path of the embedded PostgreSQL database instance inside the ESM Server directory:

/pub/esm/esm-server/pgsql/logs

By default, minimal logging is enabled for both the JVM and the Database, to ensure maximum performance in Production Environment workloads. More detailed logging can be enabled with the assistance of Boemska Support. For further details please email support@boemskats.com

Uninstalling ESM Server

Removal of the ESM Server application is simple:

1. Ensure ESM Server is not running by issuing the stop server command. See section titled Stopping ESM Server for further details

2. Delete the installation directory and contents.

This concludes the removal procedure for ESM Server.