Configuring the Automic Web Interface

You have installed the Automic Web Interface. Now you can configure it. Many configuration parameters are optional.

Note: Some configuration files are delivered with an additional ".sample" extension to ensure that your existing configuration files will not be overwritten when you update the AWI installation. You can remove ".sample" and adapt the parameters in these files or you can use the old, already configured files.

Optimizing the Server Configuration Sizes

This is our recommendation to optimize your server configuration.

Notes:

• The servlet container/application server can only make use of the memory it is configured to use. Choose the heap size according to your hardware configuration.

• Use the G1 garbage collector, which significantly reduces garbage collection pauses for large heaps.

• The number of users presented below are concurrent users, which means users logged in at the same time, being more or less active. 

• The recommended hardware configurations already include some headroom and yield very good response times for the given amount of users below.

• If possible, use a fast network connection (10Gbit/s Ethernet) for the connection to Automation Engine.

  Usually, not even a hundredth of that is used under very high load, but a fast connection helps with latency and keeps data transfers short, which in turn reduces CP usage.

Recommended Server Configuration Sizes

• Small Single Server Configuration

  A small VM will run up to 50 concurrent sessions:

  • CPU: 4 virtual cores
  • Memory: 16GB

• Basic Single Server Configuration

  A medium size VM will run up to 200 concurrent sessions:

  • CPU: 8 virtual cores
  • Memory: 32GB

• Fast Single Server Configuration

  A medium size VM will run up to 500 concurrent sessions:

  • CPU: 16 virtual cores
  • Memory: 64GB

Securing Access to AWI via TLS/SSL

This section explains how to configure a secure communication between AWI and the application server.

Important! Although enabling TLS/SSL for the communication between AWI and an application server is optional, we strongly recommend that you enable it.

For information about how to secure the communication between AWI and the Automation Engine, see uc4config.xml - Configuring the Connection Between AWI and AE.

Important! The AWI supports a KeyStore in PKCS12 (.p12) format only!

Enabling TLS/SSL for Installations with the Bundled Jetty Launcher

Follow these instructions:

1. Create a new certificate for the Jetty Application Server and add it to the keystore.

   For information about how to do it, please refer to the Configuring TLS/SSL topics in the Eclipse Jetty official documentation.

2. Add the following parameters to the configuration.properties file:

   https.enabled=true

   https.port=7443

   https.keystore.filename=keystore.selfsigned

   https.keystore.password=secret

   https.manager.password=secret

   https.cert.alias = certificate_alias

3. Restart the Jetty Application Server for the changes take effect.

Important!

To guarantee that AWI runs in secure mode, you must enable HTTPS and disable HTTP. This means that you need to configure the AWI properties as follows:

http.enabled=false

https.enabled=true

Enabling TLS/SSL for Installations with Tomcat

Follow these instructions:

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>

   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" />

   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. In this case, you have to explicitly confirm that you want to use it by adding a security exception.

     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.

Securing the Access to AWI for Installations with 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.

Customizing the Configuration Path in Installations with the Jetty Launcher

The Jetty Launcher supports multiple AWI installations in one and the same Jetty instance. You may want to do this for load balancing purposes or to have a back-up of your AWI configurations.

Let's suppose that you have two AWI instances, one for your TEST environment and another one for PROD. You configure the respective paths as follows:

• In your TEST environment

  java -Dcom.uc4.ecc.config.dir=C:\AWI\Config-TEST\ -jar C:\AWI\<version>\aa-webui-launcher.jar

• In your PROD environment

  java -Dcom.uc4.ecc.config.dir=C:\AWI\Config-PROD\ -jar C:\AWI\<version>\aa-webui-launcher.jar

Notes:

• Make sure that all relevant configuration files (logback.xml, configuration.properties, uc4config.xml) exist in the specified folder.

• To run different Jetty instances in parallel, specify different ports for each instnace in configuration.properties.

• Specify the -D parameter before the -jar parameter on the command line.

After setting this argument, restart the application server.

Customizing the Configuration Path in Installations with Tomcat, WebSphere or WebLogic

Set the following JVM arguments, either specifying them in the Java environment or using the management utilities of your WebServer:

• For installations with Tomcat

  • -Dcom.uc4.ecc.config.dir=

    Change the path when installing manually

    Example:

    In a Tomcat installation, the default path of the configuration files is <webserver>/webapps/awi/config. You want to store the configuration files in the C:\AWI_config\config folder.

    Add the following attribute to the CATALINA_OPTS environment parameter:

    CATALINA_OPTS="-Dcom.uc4.ecc.config.dir=C:\AWI_config\config\".

  • -Dcom.uc4.ecc.autoinstall.dir=

    Changes the path when using the ONE Installer

    Example:

    In a Tomcat installation, the default path of the configuration files is <webserver>/webapps/awi/WEB-INF/autoinstall. You want to store the configuration files in the C:\AWI_config\plugins folder.

    Add the following attribute to the CATALINA_OPTS environment parameter:

    CATALINA_OPTS="-Dcom.uc4.ecc.autoinstall.dir=C:\AWI_config\plugins"

After setting this argument, 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. You have the following options:

• Standard AWI login

• Single Sign-On

  • Kerberos
  • SAML

• Parametrized login

Standard AWI login

This is the 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).

Users have to provide the following login information when they open the AWI:

• Language

  English (default), Deutsch, Français

• Connection

  Depending on how the automationEngine.index parameter in configuration.properties is defined, either one or all defined connections to the backend Automation Engine are listed

  For more information, see configuration.properties - Configuring Your Local Setup.

• Client

  The number of the user Client

• Name

  User name in the user definition

• Department (optional)

  The department as defined in the User object

• Password

  If the LDAP option is selected in the user definition, this is the user's domain password, which she uses when logging into the computer at startup. Without LDAP, this is the password that is entered in the user definition.

• Session Color (optional)

  An accent color for the process strip at the top of the AWI browser page and for highlighted selections. When users open more than one session, having different session colors helps users distinguish which session they are in.

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

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 the following protocols:

• Kerberos Key Distribution Center (KDC)
• Security Assertion Markup Language 2.0 (SAML 2.0)

To Enable Single Sign-On (SSO)

Set the sso.kdc.enabled or sso.saml.enabled property to true in the configuration.properties file. For more information, see configuration.properties - Configuring Your Local Setup.

(Optional) To Enable Autologin (Fully or Partially Automatic Login)

Set the autologin parameter in parameter_login.enabled to true.

Enabling this option results in a fully automatic login and allows you to bypass entering any login information in the future. Select your session options (Language, Connection, Client, Session Color) before enabling it.

Disabling autologin results in a partially automatic login and allows you to change your session options (Language, Connection, Client, Session Color) without having to enter your user information or password.

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

Parametrized Login

Use the parametrized login if you and your users are going to connect to more than one Automation Engine and/or Clients. The parametrized login lets users bookmark the various login combinations. When they open the bookmarked URL, they have to enter only their passwords.

To Enable Parametrized Login

1. Set the parameter_login.enabled property to true in the configuration.properties file, see configuration.properties - Configuring Your Local Setup.

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 a TLS/SSL protocol, your URL will start with http://.

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

Configuring the Logging

If errors occur, the logging information will help you find the reason. Logging is enabled by default in the logback.xml configuration file. If you want more or less event occurrences written to the log file, you can change the default log level either in logback.xml or through the Automic Web Interface.

For information about the logging and tracing options in AWI, and how to collect log data to report an error, see Preparing Log Files for Reporting Errors.

For information about the logback.xmls file, see logback.xml - Configuring Log Levels.

For information about how to change the log level in the user interface, see AWI Management: Logging.

For information about how to configure the AWI log file in Automic Automation Kubernetes Edition, see Configuring Container-Based Systems.

Log File Location

You find the logback.xml file in the ...\<AWI>\config folder of your application server.

You find the AWI log files in the following location:

• Installations with Tomcat, WebSphere and WebLogic

  In the logs folder of your application folder

• Installations with the bundled Jetty launcher

  AWI stores the log files in the /osgi-tmp folder. Each running instance creates a subfolder with an ascending number, starting at 0. The folders contain both the osgi-related data and the AWI log files.

  Exception: If you start AWI using the command line and you add the -console parameter to the command, the log is written to the console instead.

  For more information about starting AWI using the command line, see Start AWI.

AWI Log Files

The AWI log files are named <host name>_ECC_Log.##.TXT, where

• <host name> is the name of the computer where the application server is running.

• ## is an ascending number, where 00 is the current log file.

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.

Log Levels

The log level defines the lowest severity and it determines the type and amount of information that is written to the log files.

Note: Extensive logging can impact AWI's performance. In case of performance problems, check your log level and reduce the written messages by specifying a higher log level.

There are five log levels. The available log levels from highest to lowest are:

• ERROR

  Failure of some action of an AWI component that AWI was not able to recover from, such as nullPointExceptions or closedStreamExceptions.

  Tracing Data in Message

  No user-identifying data. However, hostnames, other site-specific data, class names, object names, and the like are included with the event related specifications. The message contains the full stack trace.

• WARNING

  Unexpected behavior of an AWI component, such as unstable network connections that require auto-reconnect from AWI, a post-timeout retry, or triggering of a workaround for a third-party bug .

  Tracing Data in Message

  Same as ERROR level

• INFO (default)

  Configuration values at login or component startup, or global configuration changes.

  Tracing Data in Message

  Same as ERROR level but without the full stack trace.

• DEBUG

  High-level user-specific actions such as login/logout events, user changes (such as object edits), authorization related events (such as successful/failed setup actions), and important performance measures

  Tracing Data in Message

  User information (such as user ID and HTTP session ID) and event related specifications.

• TRACE

  Low-level user-specific actions such as navigation, object open, button clicks, the payload of backend-calls, internal application events, and all calls to the backend.

  Tracing Data in Message

  Same as DEBUG.

Changing the Log Level

Logging is enabled by default and it is set to INFO, but you can change it either in the logback.xml configuration file or in the user interface.

Important! If you change the log level through the user interface, this change will be lost as soon as you restart the application server.

For information about how to change the log level, see:

• logback.xml - Configuring Log Levels

• AWI Management: Logging

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 the following values:

   • 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. You find this file here:

   • For installations with Tomcat, in the ...\webapps\AWI\config\theme folder
   • For installations with the bundled Jetty launcher, in the /config folder contained in the delivery artifact

2. In the maincolor parameter, specify the RGB color code preceded by the pound sign (#) and followed by a semicolon (;).

   Example:maincolor = #fac800; for the default gold

   Note: (Tomcat) If you do not see the changes with the next login to AWI, restart the web server.

For more information, see colors.properties - Configuring the Color Scheme.

Adapt the Configuration Files

AWI has mandatory and optional configuration files that you must/can modify. The following list provides links to the topics that describe those files:

• uc4config.xml - Configuring the Connection Between AWI and AE: Mandatory.

  Used to define the connection between the AWI installation to the AE systems that can be used as its backend.

  In the Automic Automation Kubernetes Edition, any changes to the configuration file uc4config.xml must be done in the awi-properties section of the configmap. For more information, see Configuring Container-Based Systems.

• logback.xml - Configuring Log Levels: Optional. Default settings are provided.

  Controls logging behavior. You can change the lowest severity level of messages that you want to have tracked. The delivered value is "INFO".

• configuration.properties - Configuring Your Local Setup: Mandatory.

  Used to define aspects of the communication between the AWI and the AE, such as the security options and timeout intervals.

• colors.properties - Configuring the Color Scheme: Optional.

  Defines a custom theme color for the AWI user interface.

Important! The configuration files that are not described in this documentation 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.

Environment Variables

As of this version, you can also use environment variables to define the parameters of the AWI configuration files.

All AWI settings use the syntax pattern ${PREFIX_KEYNAME:DEFINITION}:

• PREFIX: AUTOMIC

  Constant prefix for all AWI settings.

• KEYNAME:

  Matches the property name as defined in the configuration.properties.xml and corlors.properties.xml files. The KEYNAME is written in uppercase and dots are replaces by underscores. For example, the session.colors property becomes AUTOMIC_SESSION_COLORS.

• DEFINITION:

  The value that you want to define for the key

Example:

• Environment variable key: AUTOMIC_SSO_SAML_ENABLED

  Value: Specifies whether single sign-on (SSO) can be used for AWI log in

  Example: true

Environment Variables in Container-Based Systems

In the Automic Automation Kubernetes Edition, you must use environment variables to define the parameters of the AWI configuration files.

You can set the environment variables using the values.yaml file before and after the installation. Once your instance has been provisioned, you can also use the ae-properties and awi-properties section of the configmap to make changes.

More information:

• Setting Environment Variables.

• Setting Environment Variables after Deployment.

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/SSL 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

• To run with AWI, your load balancer must support sticky sessions. Like many Java webapps, AWI uses the JSESSIONID session cookie. You can configure your load balancer to use this cookie, or add its own, to route requests of the same session to the same server. 

• If you run AWI with websockets enabled, your load balancer must support them.

• Please use the same path on your load balancer and the servlet containers.

  Example

  If your servers are located on http://backend1/awi and http://backend2/awi, and your load balancer is located on the host publicawihost, configure your load balancer to serve AWI on http(s)://publicawihost/awi.

Health Check

Use the AWI's health check to verify that the application server has deployed AWI correctly and that it is up and running.

1. Add the word status to the URL:

   http://hostName:<port>/AWI/status

2. The standard HTTP 200 OK status response code is returned and a page is displayed with the word OK indicating that AWI is running. Otherwise, the corresponding standard HTTP message is displayed.

You can use this health check endpoint in your internal URL monitoring systems to ensure that AWI is functioning properly.

You can also use this endpoint in Shell scripts to call the status of the Automic Web Interface.

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

AWI uses WebSockets as an efficient way of sending information to the Client. If the application server does not support WebSockets, AWI falls back to long polling. 

Notes:

• Set the allowWebsockets=false parameter in the configuration.properties file. For details, see Network Settings Specific for the Bundled AWI Launcher
• Running AWI without WebSockets slightly increases the CPU load on the servlet container. Add more resources to compensate for this.

Tips:

• Do not increase system or Client settings that affect how much data is shown to the user unless absolutely necessary
• Do not put too many objects in the root folder. Apart from being overwhelming to navigate for a human user, it has a side effect on performance. The root folder is shown in Process Assembly by default and a long list of objects (thousands) significantly increases the memory per session as well as the CPU used when retrieving the folder list.

Locate Bottlenecks

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

• The web interface locks up

  The AWI server likely is the bottleneck.

  What you can do:

  • Increase the memory and Java heap space

  • Increase the amount of CPU cores

• Loading times are too high

  Automation Engine is probably the bottleneck. You can increase the number of DWPs and JWPs.