Installation on Linux Systems
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). Additionally installation of the apptelemetry-libs-<version>.rpm package is required on all systems.
The Fabasoft app.telemetry server installation also requires a locally installed app.telemetry agent and Software-Telemetry web (apptelemetryweb) package.
SELinux is supported, for more details about Fabasoft app.telemetry with SELinux see chapter “Fabasoft app.telemetry with SELinux” in appendix.
Note: Installing Fabasoft app.telemetry on a RHEL/CentOS 7 or 8 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 on installing and using Fabasoft app.telemetry on RHEL/CentOS 7/8 see chapter “Installing Fabasoft app.telemetry on RHEL/CentOS 7 and 8” in appendix.
Installation of Fabasoft app.telemetry Agent
Installation (Linux Shell) |
|---|
[root@localhost]# yum localinstall apptelemetryagent-<version>-<os>.x86_64.rpm apptelemetry-libs-<version>-<os>.x86_64.rpm Preparing... ######################################### [100%] [root@localhost]# systemctl start apptelemetryagent.service |
Installation of Fabasoft app.telemetry Software-Telemetry Web Service
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%] |
ImageProxy
The Fabasoft app.telemetry Software-Telemetry Web Service includes the ImageProxy feature, that is used by the screenshot rendering script in den feedback functionality to download images from foreign hosts, because cross site download is not allowed by the browser. As this is a potential security risk (see Server Side Request Forgery) this feature has been deactivated by default in a Hotfix of Version 2023. To reactivate the feature you have to enable it in the apache web server configuration. Restrict the valid URLs using a regular expression in “APMImageProxyURLFilter”.
Enable ImageProxy (see /etc/httpd/onf.d/sotwaretelemetryweb.conf) |
|---|
# the APMImageProxyEnabled directive is Global # default: off # ImageProxy has been disabled by default because it allows Server-Side-Request-Forgery attack # enable it with care to allow web clients to load images from foreign web servers during # screenshots rendering. APMImageProxyEnabled on # the APMImageProxyURLFilter directive is Global # default: ^https://.*\.fabasoft\.com/.* # Set regular expression filtering URLs used in ImageProxy requests to restrict requests # to known hosts. APMImageProxyURLFilter ^https://.*\.fabasoft\.com/.* |
Installation of additional (optional) Fabasoft app.telemetry Modules
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). 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 Server
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%] 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 License
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 configuration daemon.
Configuration of Apache Web Server for Fabasoft app.telemetry
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 Server
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 --now enable httpd |
Configuration of Basic Authentication
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 Permissions
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
- apptelemetrydevops: read-only access to the app.telemetry configuration
- apptelemetryusers: read-only access to all data assigned to this group
- 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 Keycloak
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 DevOps
- 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 compression
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.