2018 Update Rollup 2

Installation on Linux SystemsPermanent link for this heading

Install the Fabasoft app.telemetry packages from the product media using the yum-command. The server (apptelemetryserver-<version>.rpm) has to be installed once in the infrastructure and the agent (apptelemetryagent-<version>.rpm) on every system (also on the server).

Since version 16.3 RHEL/CentOS 7 systems also require the installation of the
apptelemetry-libs-<version>.rpm package on all systems.

The Fabasoft app.telemetry server installation also requires a locally installed app.telemetry agent and Software-Telemetry web (apptelemetryweb) package.

Since version 2012 Fall Release Fabasoft app.telemetry supports SELinux on RHEL/CentOS 6 and with Fabasoft app.telemetry 2015 also RHEL/CentOS 7. For other platforms SELinux must be turned off in order to use Fabasoft app.telemetry.

Note: Installing Fabasoft app.telemetry on a RHEL/CentOS 6 or 7 system with enabled SELinux will also install the SELinux files for Fabasoft app.telemetry and load the SELinux policy on the target system. Loading SELinux policies may take a while and will slow down the RPM installation process!

For more details about Fabasoft app.telemetry with SELinux see chapter “Fabasoft app.telemetry with SELinux” in appendix.

Since Fabasoft app.telemetry 2015 we support the installation on a RHEL/CentOS 7 platform. The installation procedure is very similar than before. But the daemon startup is now handled by the systemd tools. For more details on installing or using Fabasoft app.telemetry on RHEL/CentOS 7 see chapter “Installing Fabasoft app.telemetry on RHEL/CentOS 7” in appendix.

Installation of Fabasoft app.telemetry AgentPermanent link for this heading

Installation (Linux Shell)

[root@localhost]# yum localinstall apptelemetryagent-<version>-<os>.x86_64.rpm apptelemetry-libs-<version>-<os>.x86_64.rpm

Preparing...           ######################################### [100%]
  2:apptelemetryagent  ######################################### [100%]

[root@localhost]# systemctl start apptelemetryagent.service

On RHEL/CentOS 6 the apptelemetry-libs package is not available and not required.

Installation of Fabasoft app.telemetry Software-Telemetry Web ServicePermanent link for this heading

Optionally you can install the Fabasoft app.telemetry Software-Telemetry web service (also known as WebAPI) additionally on some agent platforms. (This web service is required for End-2-End instrumented applications using the Fabasoft app.telemetry JavaScript SDK.)

The RPM package for the Fabasoft app.telemetry Software-Telemetry web service is located in the installation folder TelemetryWeb and is named apptelemetryweb-<version>.<os>.x86_64.rpm.

Installation (Linux Shell)

[root@localhost]# yum localinstall apptelemetryweb-<version>-<os>.x86_64.rpm

Preparing...           ######################################### [100%]
  2:apptelemetryweb    ######################################### [100%]

Installation of additional (optional) Fabasoft app.telemetry ModulesPermanent link for this heading

Optionally you can install the Fabasoft app.telemetry Apache module (mod_telemetry) from the installation folder Telemetry-Modules which provides instrumentation for general requests handled by the Apache web server. If the requests are not part of another application instrumentation you can configure a new Software-Telemetry log pool for the Apache web server (with the application filter “Apache”) including the specific log definition file …/Telemetry-Modules/LogDefinitions/webserver-logdefinition-apache.xml.

Another optional app.telemetry module is the syslog forwarder module required for capturing syslog events on behalf of a normal Software-Telemetry log pool. This feature requires the Linux syslog daemon rsyslog (>= 5.8.10) and is only available for RHEL/CentOS 6 or 7. In order to get syslog events as telemetry requests you have to create a new log pool with the specific application filter “Fabasoft app.telemetry” as application name and “Syslog Forwarder” as application tier name and import the specific log definition file …/Telemetry-Modules/LogDefinitions/syslogforwarder-logdefinition.xml.

Installation of Fabasoft app.telemetry ServerPermanent link for this heading

Installation (Linux Shell)

[root@localhost]# yum localinstall apptelemetryagent-<version>-<os>.x86_64.rpm apptelemetryserver-<version>-<os>.x86_64.rpm apptelemetryweb-<version>-<os>.x86_64.rpm apptelemetry-libs-<version>-<os>.x86_64.rpm

Preparing...           ######################################### [100%]
  1:apptelemetry-libs  ######################################### [ 25%]
  2:apptelemetryagent  ######################################### [ 50%]
  
3:apptelemetryweb    ######################################### [ 75%]
  
4:apptelemetryserver ######################################### [100%]

Run "/opt/app.telemetry/bin/serversetup.sh" to configure the app.telemetry server the first time.

Then call the setup script to configure the Fabasoft app.telemetry server for initial use and follow the instructions on screen. This script will set up the system as described in the following sub chapters automatically.

Setup (Linux Shell)

/opt/app.telemetry/bin/serversetup.sh

Note: The configuration steps described in the following sub chapters are only informational and for special needs (a default configuration is already performed by the serversetup.sh script).

Loading Fabasoft app.telemetry LicensePermanent link for this heading

Put the Fabasoft app.telemetry license on the Fabasoft app.telemetry server into the directory /etc/app.telemetry/configuration and save it with the name license.lic.

After a valid license is stored in /etc/app.telemetry/configuration/license.lic restart the Fabasoft app.telemetry server daemon.

Configuration of Apache Web Server for Fabasoft app.telemetryPermanent link for this heading

This chapter describes the configuration steps of the Apache web server for the Fabasoft app.telemetry server for a manual installation. The serversetup.sh script will perform these basic configuration steps automatically with default settings.

Starting Apache Web ServerPermanent link for this heading

The Fabasoft app.telemetry server requires the Apache web server to be installed, configured and running. Start the Apache web server (httpd) and set it up for automatic startup:

Autostart Apache Daemon

systemctl enable --now httpd

Configuration of Basic AuthenticationPermanent link for this heading

To change the password of an existing user or to create a new user to access app.telemetry execute the following command.

Setup User Credentials (Linux Shell)

htpasswd /etc/app.telemetry/htpasswd username

User/Group PermissionsPermanent link for this heading

The app.telemetry group privileges separate user permissions with a membership check of the login username against the following Apache groups:

  • apptelemetryadministrators: full administrative access
  • apptelemetryusers: read-only access to all data
  • apptelemetrydashboardusers: only able to view dashboards assigned to this group and public-marked dashboards
  • apptelemetrylogpoolusers: only able to view telemetry data and reports for log pools assigned to this group
  • apptelemetrywebformusers: only able to view feedback inbox, forms and website configuration

Example of group file (/etc/app.telemetry/htgroup)

apptelemetryadministrators: user1 user2

apptelemetryusers: user5 user6 user7

apptelemetrydashboardusers: user8 user9

apptelemetrylogpoolusers: user10 user11

apptelemetrywebformusers: user12 user13

All those user accounts have to be created via the htpasswd command in the htpasswd file as mentioned above. Changes in the group membership require reloading the Apache configuration.

Note: User accounts with domain login (e.g: “APM\pool1”) have to be listed in the group file with escaped backslash (\\)

Example of group file with escaped domain-accounts (/etc/app.telemetry/htgroup)

apptelemetryadministrators: root admin

apptelemetrylogpoolusers: loggy APM\\pool1 APM\\pool2

limitedaccess: APM\\pool1 APM\\pool2

Configuration for KeycloakPermanent link for this heading

Configure authentication for Keycloak using the mod_auth_openid. Install this module and load into apache webserver:

Load authentication module (/etc/httpd/conf.modules.d/openidc.conf)

LoadModule auth_openidc_module modules/mod_auth_openidc.so

Configure the required parameters for opened-connect

Sample configuration (/etc/httpd/conf.d/openidc.conf)

OIDCClientID ${OIDC_CLIENT_ID}

OIDCClientSecret ${OIDC_CLIENT_SECRET}

OIDCRedirectURI /openidc/redirect-uri

OIDCProviderIssuer ${EXTERNAL_KEYCLOAK_BASE_URL}/auth/realms/${OIDC_REALM}

OIDCProviderAuthorizationEndpoint ${EXTERNAL_KEYCLOAK_BASE_URL}/auth/realms/${OIDC_REALM}/protocol/openid-connect/auth

OIDCProviderTokenEndpoint ${KEYCLOAK_BASE_URL}/auth/realms/${OIDC_REALM}/protocol/openid-connect/token

OIDCProviderJwksUri ${KEYCLOAK_BASE_URL}/auth/realms/${OIDC_REALM}/protocol/openid-connect/certs

OIDCCryptoPassphrase a-random-secret-used-by-apache-oidc-and-balancer

OIDCRemoteUserClaim preferred_username

OIDCOAuthSSLValidateServer Off

OIDCOAuthIntrospectionEndpoint ${EXTERNAL_KEYCLOAK_BASE_URL}/auth/realms/${OIDC_REALM}/protocol/openid-connect/token/introspect

OIDCOAuthIntrospectionEndpointParams token_type_hint=access_token

OIDCOAuthClientID ${OIDC_CLIENT_ID}

OIDCOAuthClientSecret ${OIDC_CLIENT_SECRET}

OIDCCookie mod_auth_openidc_session_inspire

Use openid-connect as login method in Fabasoft app.telemetry:

Load authentication module (/etc/httpd/conf.d/apptelemetry-login.conf)

<Location /apptelemetry>

  AuthType openid-connect

  Require claim "roles~Fabasoft app\.telemetry .*"

</Location>

If you need to disable the certificate check when Fabasoft app.telemetry accesses the Keycloak master service, add the following environment variable to apache configuration:

Disable certificate check (/etc/httpd/conf.d/apptelemetry-login.conf)

SetEnv APM_OIDC_VERIFY_PEER off

Add any of the Fabasoft app.telemetry roles in Keycloak.

  • Fabasoft app.telemetry Administrators
  • Fabasoft app.telemetry Dashboard Users
  • Fabasoft app.telemetry Logpool Users
  • Fabasoft app.telemetry Users
  • Fabasoft app.telemetry Web Form Users

Assign the roles to the particular users.

Define additional roles in Keycloak and reference these Roles in Fabasoft app.telemetry Dashboards and Log Pools to provide access to those resources for the assigned users.

Under Keycloak select the client used for authentication (OIDC_CLIENT_ID) and add a mapper

Under “Service Account Roles” select the Client Role “master-realm” and assign the “view-realm” Role. This provides read access for the Fabasoft app.telemetry Server to the available roles list, so Fabasoft app.telemetry can provide a list of available roles in the Dashboard and Log Pool configuration dialogs.

Users have to relogin with Keycloak after assigning the role to be able to use Fabasoft app.telemetry.

Enable Data compressionPermanent link for this heading

To enable data compression between Fabasoft app.telemetry web server and the Fabasoft app.telemetry client make sure that the deflate_module is installed and loaded into your Apache HTTPD.