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 SSL » Customizing the Configuration Path » Configuring the Login and User Authentication » Configuring the Logging in AWI » Customizing the User Interface » Adapting 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.

    3. 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.

    3. 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 details.

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

Automic Workload Automation offers different user authentication configurations which result in different user login options. As an administrator, you can configure AWI to support the authentication and login approach that you want. Sometimes prerequisite setup in Automation Engine is needed. This topic describes the authentication and login options and how you set them up.

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

There are two options to make logging into AWI simpler for your users:

Using the Default 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.

Losing Kerberos Connection

If you lose Kerberos connection, the login dialog is displayed regardless of your previous choices and shows the following warning message:

Screenshot of the warning that reads the following:"Kerberos login is not available"

This can happen if you log in from a computer or server that is not in the Windows domain where Kerberos is installed or if there is a problem in the configuration or Kerberos. In the meantime, you can log in with your CA Automic user name and password.

Reason: When an AWI instance is set up for SSO, authentication is passed onto Kerberos. If Kerberos is not in the Windows domain, then Windows tries to authenticate with Windows NT LAN manager (NTLM) which cannot process the Kerberos authentication information. The login defaults to the standard Automic Workload Automation login. For more information, see Configuring Automic Web Interface.

Enabling Parametrized Login in AWI

Another convenience 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. For more information, see configuration.properties.

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

    For example, https://<AWI >/#&system=ConnectionName&client=9999&name=MyUserName&department=Dept

    Note: If your browser is not accessing 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. Changethe 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 change both of these 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.

Adapting 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 (ZDU). For more information, see Zero Downtime Upgrade.

Websockets

On Tomcat 7, 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: