Configuring Automic Web Interface

You have already installed the Automic Web Interface. Now you can proceed with configuration activities. Many of them are optional.

This page includes the following:

Configuration Steps

Optimizing the Server Configuration Sizes » Securing Access to AWI via SSLL » Customizing the Configuration Path » Configuring the Login and User Authentication » Configuring the Logging in AWI » Customizing the User Interface » Adapt the Configuration Files » Setting Up the Load Balancer and Configure Proxies

Optimizing the Server Configuration Sizes

Notes:

Server Configuration Sizes

Securing Access to AWI via SSL

Tomcat

  1. Create a KeyStore File for your Tomcat Installation.

    1. Open a command prompt with administrator rights and change the path to the Tomcat configuration directory (TOMCAT_HOME/conf/).

    2. Create a keystore file with a self-signed certificate, using the following command. This will result in the output as shown below (status after complete editing).

      The cursor will jump to the first line you can enter your values in. After each entry confirm with the Return key to jump to the next line.

      "%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -keystore tomcat-keystore.jks -storepass myTomcatKeystorePassword

      What is your first and last name?  
       [Unknown]:  localhost
      What is the name of your organizational unit?
        [Unknown]:  YOUR_UNIT
      What is the name of your organization?  
       [Unknown]:  YOUR_ORGANIZATION
      What is the name of your City or Locality?  
       [Unknown]: YOUR_CITY
      What is the name of your State or Province?
       [Unknown]: YOUR_STATE
      What is the two-letter country code for this unit?
      [Unknown]: AT
      Is CN=localhost, OU=YOUR_UNIT, O=YOUR_ORGANIZATION, L=YOUR_CITY, ST=YOUR_STATE, C=AT correct?
      [no]: YES

      Enter key password for <tomcat>
        (RETURN if same as keystore password):

      Notes:

      • You have to use the hostname / domain of your AWI instance as your first and last name (localhost in this example).

      • This command will create a new keystore file named tomcat-keystore.jks protected with the password myTomcatKeystorePassword located in the configuration directory. The keystore contains a self-signed certificate for your AWI instance.

  2. Import a signed certificate into the keystore (optional).

    You can skip this step, if you use a self-signed certificate that you created in the previous step.

    1. Use the following command to import a chain certificate or root certificate (if available) into your keystore first:

      "%JAVA_HOME%\bin\keytool" -import -alias root -keystore tomcat-keystore.jks -trustcacerts -file <filename_of_the_chain_certificate>

    2. Now import the certificate using this command:

      "%JAVA_HOME%\bin\keytool" -import -alias tomcat -keystore tomcat-keystore.jks -file <your_certificate_filename>

    3. Important! The Tomcat only supports keys and certificates in the JKS, PKCS11 or PKCS12 format.

    4. To import an existing certificate signed by your own Certificate Authority (CA) into a PKCS12 keystore using OpenSSL you would execute a command like this:

      openssl pkcs12 -export -in mycert.crt -inkey mykey.key
          -out mycert.p12 -name tomcat -CAfile myCA.crt
          -caname root -chain

  3. Configure the Tomcat connection.

    1. Open the server.xml file located in the configuration directory of your Tomcat instance.

    2. Add the following connector configuration to your configuration file and save it:

      <Connector port="8443"
      protocol="Enter the current apache protocol here"
          keyAlias="tomcat" keystoreFile="conf\tomcat-keystore.jks" keystorePass="myTomcatKeystorePassword"
          maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
          clientAuth="false" sslProtocol="TLS" />

    3. For the parameter keystorePass enter the password of the tomcat-keystore.jks.

      Important! The previous example illustrates the how to configure the connector as it is at the time of writing. Check the Tomcat documentation for potential changes and for the latest information at Apache Tomcat.

    4. Restart your Tomcat instance to apply the changes.

  4. Test the access to your AWI instance.

    You can now access the Automic Web Interface using a secure connection.

    • As URL use https://YOUR_DOMAIN:8443/awi/ (for example: https://localhost:8443/awi/)

    • If you are using a self-signed certificate you may receive a warning that the connection is untrusted, because is not possible to verify the identity.

      You can only avoid this warning if you are using signed certificates by a trusted certificate authority. The connection's encryption is the same as with a self-signed certificate.

      Note: You have to confirm (add a security exception) that you want to use the self-signed certificate.

WebSphere

The procedure to secure the access to AWI depends on the WebSphere profile used in your company. Please refer to the official IBM WebSphere documentation for more information.

Customizing the Configuration Path

By default, the AWI configuration files are located in the web applications folder on the WebServer. In some cases it can be convenient to change this path, for example if the users who will configure the AWI should have no access rights to the WebServer folder.

Whether you are installing via the ONE Installer or manually, you can customize the path in which the configuration files should be stored. For this purpose, you set the following JVM arguments, either specifying them in the Java environment or using the management utilities of your WebServer:

Note: After setting this argument you must restart the application server.

Configuring the Login and User Authentication

The Automic Web Interface supports different user authentication configurations which result in different user login options. As a system administrator, you can configure AWI to support the authentication and login approach that you want.

By default, when users log into AWI, the entire authentication process is handled by the Automation Engine to which the instance is connected. AE confirms whether the user credentials match the values in the related user object (USER).

You can also enable single sign-on using either the Kerberos or SAML protocol, or enable parametrized login.

Using the Standard AWI Login

By default, the AWI users have to provide the following login information when they open the AWI:

Your browser stores your login entries (except password) for your next login.

Note: You can always change the session color from the session menu in the main menu bar.

Using Single Sign-On

Setting up single sign-on for the Automation Engine system allows users to login only once, without having to enter login details over and over again. The Automation Engine supports Kerberos Key Distribution Center (KDC) and the Security Assertion Markup Language 2.0 (SAML 2.0) protocols.

You enable single sign-on (SSO) in the configuration.properties of your Automic Web Interface instance by setting the sso.kdc.enabled or sso.saml.enabled property to true, depending on which protocol you want to use. For more information, see configuration.properties.

You can also decide if you want to enable autologin to use a fully or partially automatic login:

For more information on SSO, Kerberos and SAML configuration, see Setting up Single Sign-On.

Enabling Parametrized Login in AWI

Another convenient feature is enabling parametrized login, which you do by appending the login parameters in the URL that you use to start AWI. This is helpful if you or users use several connections and/or clients. You can just bookmark the various login combinations. When you open the bookmarked URL, you have to enter only your password.

  1. In your AWI instance, set the parameter_login.enabled property to true in the configuration.properties file, see configuration.properties.

  2. In your AWI startup URL, append the login information that you want to have already entered in the login window.

    Example

    https://<AWI >/?system=ConnectionName&client=9999&name=MyUserName&department=Dept&logintype=AE(default)|KERBEROS|SAML&language=MyLanguage&autologin=true

    Note: If your browser does not access AWI over an SSL protocol, your URL will start with http://.

    As an administrator, you might want to send individualized URLs to your new users

Configuring the Logging in AWI

For information about the kind of log data to collect for an CA Automic Support ticket, see Preparing Log Files for Error Reporting.

If errors occur, the logging information can help you finding the source for the error. Logging is enabled by default. You can change the default log level if you want more or less event occurrences written to the log file.

Logging in the AWI is handled by the Tomcat logback framework. You can define the log level in the logback.xml file. The specified log level defines the lowest severity. Its occurrence and the occurrence of events of higher severity are logged. Extensive logging, however, can impact AWI's performance. When you encounter performance problems, check your log level and reduce the written messages by specifying a higher log level, if necessary.

Logging involves the following files:

Log Levels

The log level values available (highest to lowest) are:

Changing the Log Level

Logging is enabled by default set to DEBUG, but, if necessary, you can change the log level in the logback.xml configuration file that you find in the ...\<AWI>\config folder of your application server.

Important! Do not change any other parameters in this file. Changing other parameters might prevent CA Automic from investigating situations that cause errors.

The log level is defined in the<root> element by the level="[log_level]"> element The <root> element contains the <appender-ref> element that specifies that this<root> element defines the LOGGER appender. The LOGGER appender is the component that writes the logging events to the log file.

To Change the Log Level

  1. Switch to the webapps\<AWI>\config folder and open the logback.xml.
  2. Search for the <root> element.

    Note: You can find the <root> element best by searching for ref="LOGGER". The <root> element is one line above.

  3. Change the log level for the root appender by setting the level="[log_level]" attribute to the lowest log level for which you want messages to be written to the log file. For more information, see Log Levels.
  4. For the changes to take effect, stop and restart your application server.

Example

The log level is set to "DEBUG" (default value) in the following example. If you change it to "INFO", fewer messages are written to the file, as non-critical log messages are ignored.

<!-- Log level is set here. Possible values: TRACE, DEBUG, INFO, WARN, ERROR

          DEBUG is recommended on testing and development instances.

          INFO is recommended on production instances.

-->

<root level="DEBUG">

          <appender-ref ref="LOGGER" />

</root>

AWI Log Files

The log files are located in the logs folder of your application server and are named <host name>_ECC_Log.##.TXT:

The current log file is a .txt file, older log files are compressed in .zip archives.

Note: As an administrator, you can also enable writing trace files (similarly named as the log files (<Host name>_ECC_TRACE.##)) to this folder to find the cause of an error.

Customizing the User Interface

By default the AWI interface has the CA Automic logo on the login dialog and in the header bar. All pages use the default gold color and shades of black and gray. You can customize the color and logo to reflect your company brand.

To Change the Logo

  1. Prepare your logo file. Make sure the image size is not larger than:

    • Width: 96px

    • Height: 70px

  2. Copy logo.png into the …\<AWI>\config\theme folder.

  3. Add the configuration parameter logo.filename = logo.png to the color.properties file to specify the new logo.

  4. Depending on how your logo looks like, you may want to add a white box to differentiate it from the dark background. To do so, add the parameter white.background = true to the color.properties file

    Note: If you do not see the changes with the next login to AWI, restart the Tomcat Webserver.

To Change the Color Scheme

  1. Open the colors.properties file that is available in the …\webapps\<AWI>\config\theme folder. For more information, see colors.properties.

  2. In the maincolor parameter, specify the RGB color code. Make sure to precede it with the pound sign (#) and follow it with a semicolon (;).

    For example, enter "maincolor = #fac800;" for the default gold.

    Note: If you do not see the changes with the next login to AWI, restart the Tomcat Webserver.

Adapt the Configuration Files

There is a number of mandatory and optional configuration files that you have to modify.

Important! The configuration files that are not included here should not be modified.

After installing and configuring AWI you can start setting up your system or you can continue with the installation of other plug-ins and components.

For more information, see Requirements and Installation Types.

Setting Up the Load Balancer and Configure Proxies

You can use the Automic Web Interface through any kind of proxy in the general sense, whether for TLS termination, load balancing, redundancy or all of these at the same time.

A single, powerful server can handle the traffic expected in AWI in a high performance Automation Engine installation. Therefore, you do not need to set up load balancers to improve the performance of the Automic Web Interface.

However, if you want high availability, you must have different AWI instances running on different hosts.

In this case, you need a load balancer to redirect the traffic in case one of the AWI instances fails.

Tip: It is recommended to have a hot/hot configuration with two instances, both of them serving traffic together. A switchover should only happen if the one server fails. Also, each instance must be able to handle all the traffic. Otherwise, if the other instance fails, the one that takes over would overload. If for any reason a single server cannot handle the load, you can add more instances to handle failures. For example, four or five instances instead of the required three.

Requirements for Load Balancers

Health Check

If your load balancer does health checks via additional http requests, please use the relative path or check to do so. For example, if your AWI is reachable via https://myawiserver/awi, the health check should invoke https://myawiserver/awi/check

This URL will return a response with status code 200 if AWI is running and the servlet container is handling requests, and not create any http sessions.

Upgrading

A load balancer or proxy can be very useful for transparently switching over between two versions of AWI when finalizing a Zero Downtime Upgrade. For more information, see Zero Downtime Upgrade.

WebSockets

On Tomcat, AWI uses WebSockets as an efficient way of sending information to the client. If you are using Weblogic or Websphere, AWI will fall back to long polling. 

Notes:

Tips:

Locate Bottlenecks

AWI shows loading indicators while waiting for responses to backend requests. Possible bottleneck symptoms are: