Installing the Avantra Agent

Before you start your installation, please ensure to read the release notes for Avantra 21.11 and use the latest software versions and patches of Avantra, as described in the Components section.

Verify Network Connectivity

Network Connectivity

The Avantra Agent contacts the Avantra Server on TCP port 9050. The other way round, the Avantra Server connects to the Avantra Agent on TCP Port 9051.

Verify the connection from the Avantra Agent to the Avantra Server using

telnet [avantra_server] 9050

The telnet tool will report an error if a connection cannot be established.

If network restrictions are in place on your site, please contact your network staff to enable the communication in both directions, from the Avantra Agent to Avantra Server on port 9050, and the other direction on port 9051.

Preparing the Installation

This section describes preparations that are required to monitor SAP Systems or Databases using the Avantra Agent. If the agent shall only monitor the operating system, no preparations are required and you can continue reading the appropriate installation section: Installing the Agent on Microsoft Windows or Installing the Agent on Unix.

To monitor ABAP or ABAP+Java SAP Systems, the Avantra Agent needs an ABAP user to connect with, the so-called Avantra RFC User. We recommend creating a dedicated RFC user for Avantra, as described in Avantra RFC User Setup.

Make sure to import the transport requests before you create the RFC user since the transport requests include an authorization object and an authorization profile that the user requires.

For an ABAP+Java system, we recommend enabling the RFC user as a J2EE Administrator as well.

For a Java-only system, we recommend creating a user avantra_j2ee, as described in Avantra J2EE User Setup.

Importing the SAP Transport Request

For a general overview of our ABAP interface, please see Avantra ABAP Interface.

This section does not apply to Java-only systems.

The current version of Avantra ships with five transport requests, two client independent transports containing ABAP Objects and three role transports. You only need to import two transport requests, one ABAP transport and one role transport that match the basis release of your SAP System. Unicode and non-Unicode systems of all basis releases listed in SAP Basis are supported.

The following table gives an overview of all transports released with the latest version of Avantra:

Table 1. Transport Request Overview
Transport Short Text Client Dep.

AVAK900241

Avantra Interface V21.11.0 for SAP Release 7.30 Patch ≥ SP5 *

No

XANK900264

Avantra Interface V7 for SAP Release 7.30 ≤ SP4 and older *

No

AVAK900245

Role for Avantra (ZAVANTRA) for SAP Release 7.30 Patch ≥ SP5

Yes

ASMK900006

Role for Avantra (ZAVANTRA_SOLMAN) for Solution Manager only

Yes

XANK900262

Role for Avantra (ZAVANTRA) for SAP Release 7.30 Patch ≤ SP4 and older

Yes

* SAP_BASIS patch level

Avantra Agent also supports the V7 interface delivered with Syslink Xandria 7.3 in transport request XANK900264. However, we recommend importing the new interface for SAP Basis Release 7.30 and above. The ABAP code delivered with the new transports has been rewritten from scratch and is also a new codebase for future releases. If you are using SAP releases 7.20 or older, you can continue with XANK900264.

Make sure to import the workbench request before the customizing request containing the role, that is, first import AVAK900241 or XANK900264, and then import AVAK900245 or XANK900262. On Solution Manager systems the additional transport ASMK900006 is also needed.

Transports AVAK900241 and XANK900264 are workbench requests and thus client independent. They contain ABAP Objects required for retrieving monitoring-related data, which cannot be directly retrieved by RFC. These are described in greater detail below:

Table 2. Content of Transport Requests AVAK900241`
Short Description Program ID Object Type Object Name

Namespace

R3TR

NSPC

/SYSLINK/

Class

R3TR

CLAS

/SYSLINK/CL_APPLOG_GET … /SYSLINK/CL_WORKLOAD_GET (not all 77 classes listed here)

Package

R3TR

DEVC

/SYSLINK/XANDRIA

Domain

R3TR

DOMA

/SYSLINK/RESULTS_TYPE

Data Element

R3TR

DTEL

/SYSLINK/DMC_MT_IDENTIFIER

Data Element

R3TR

DTEL

/SYSLINK/IUUC_REPL_CONFIG_GUID

Data Element

R3TR

DTEL

/SYSLINK/RESULTS_TYPE

Function Group

R3TR

FUGR

/SYSLINK/MON_XANDRIA

Message Class

R3TR

MSAG

/SYSLINK/MON_XANDRIA

Program

R3TR

PROG

/SYSLINK/RUNMON

Authorization Object

R3TR

SUSO

ZSYSXANMON

Structure

R3TR

TABL

/SYSLINK/AUGENERICRC

Structure

R3TR

TABL

/SYSLINK/AUPFLACTIVATE

Structure

R3TR

TABL

/SYSLINK/AUPFLMAINTAIN

Structure

R3TR

TABL

/SYSLINK/AUPFLUPLOAD

Structure

R3TR

TABL

/SYSLINK/JOBNAME_RANGE_S

Structure

R3TR

TABL

/SYSLINK/MONSTRUCT

Structure

R3TR

TABL

/SYSLINK/SLT_HEALTHCHK

Structure

R3TR

TABL

/SYSLINK/SLT_SRCTGT

Structure

R3TR

TABL

/SYSLINK/TABNAME_RANGE_S

Table Type

R3TR

TTYP

/SYSLINK/AUTPFLPROTOCOL

Table Type

R3TR

TTYP

/SYSLINK/BDCDATA_TTY

Table Type

R3TR

TTYP

/SYSLINK/JOBNAME_RANGE_T

Table Type

R3TR

TTYP

/SYSLINK/LIST_TTY

Table Type

R3TR

TTYP

/SYSLINK/SELOPS_TTY

Table Type

R3TR

TTYP

/SYSLINK/SLT_SRCTGT_TAB

Table Type

R3TR

TTYP

/SYSLINK/TABNAME_RANGE_T

Table Type

R3TR

TTYP

/SYSLINK/ZBAPILAWRGE_SYS_TTY
Table 3. Content of Transport Request XANK900264
Short Description Program ID Object Type Object Name

Namespace

/SYSLINK/

Package

R3TR

DEVC

/SYSLINK/XANDRIA

Package

R3TR

DEVC

ZXAN

Function Group

R3TR

FUGR

/SYSLINK/MON_XANDRIA

Report Source Code

LIMU

REPS

/SYSLINK/RUNMON

Authorization object

R3TR

SUSO

ZSYSXANMON

Structure

R3TR

TABL

/SYSLINK/MONSTRUCT

All objects, except for the authorization object, use the registered namespace /SYSLINK/. This is not possible for the authorization object, so it is delivered in the customer name range.

Transports AVAK900245, ASMK900006 and XANK900262 are customizing requests and thus are client dependent. Please import the requests to the same client as the RFC user (see Avantra RFC User Setup). Based on your SAP release, choose the appropriate transport between AVAK900245 and XANK900262, it contains the ZAVANTRA role only. This role includes the ZSYSXANMON authorization object, which is required for the Avantra monitoring interface and other system authorization objects.

For Solution Manager systems an additional role ZAVANTRA_SOLMAN is needed. Import transport ASMK900006 and assign the role ZAVANTRA_SOLMAN to the monitoring user (in addition to the already assigned role ZAVANTRA).

We recommend that the following steps are only performed by an SAP Basis administrator or another person with proper knowledge of the SAP transport system.

To import the transport request, replace all occurrences xxxx with the numbers indicated above.

Proceed as follows for all requests you have chosen to import:

Procedure: Import Transport Requests

  1. Download the file transports-for-avantra-21.11.zip either from the Support menu of avantra.com (it is in the CONTRIB RELEASE 21.11 section) or from your Avantra Server (if you followed Preparing the Avantra Agent Deployment):

    $ curl http://[avantra-server]:9050/AgentUpdate/transports-for-avantra-21.11.zip > transports-for-avantra-21.11.zip

  2. Extract the zip file to some proper location, referenced as <transport-source> in this procedure.

  3. Copy the control files <transport-source>/cofiles/K90xxxx.* to the directory cofiles of your transport domain, e.g. /usr/sap/trans/cofiles (on Unix-like operating systems).

  4. Set the file permission of the copied cofiles in a way that they are readable and writable for any operating system user [sid]adm supposed to import the request. On Unix-like operating systems, you can do this like in the following example:

    root$ chgrp sapsys K90xxxx.*
root$ chmod 664 K90xxxx.*

    On Microsoft Windows operating systems, you can use the Properties menu opened from the context menu of the file in order to modify the file attributes and other file security settings. Refer to your operating system documentation for further information.

  5. Copy the data files <transport-source>/data/R90xxxx.* to the directory data of your transport domain, e.g. /usr/sap/trans/data (on Unix-like operating systems).

  6. Set the file permission of the copied data files in a way that they are read- and writable for any operating system user [sid]adm supposed to import the request. On Unix-like operating systems, you can do this like in the following example:

    root$ chgrp sapsys R90xxxx.*
root$ chmod 644 R90xxxx.*

    On Microsoft Windows operating systems, you can use the file Properties menu opened from the context menu of the file in order to modify the file attributes and other file security settings. Refer to your operating system documentation for further information.

  7. Import the transport requests. This might be done with the SAP transport program tp on operating system level, however, we recommend using transaction STMS:

    1. Start transaction STMS.

    2. Select Import Overview and select the SAP System where you want to import the request.

    3. Choose menu item Extras  Other requests  Add and type the transport number [XAN|ASM|AVA]K90xxxx e.g. AVAK90xxxx in the transport request text field of the following dialog.

      Please set the Ignore Invalid Component Version flag at the Options tab, otherwise, the import may fail.

      Press the Continue button. The transport request has been added to the import queue.

    4. Import the request. If you are not sure whether to import all requests or only the newly added Avantra request AVAK90xxxx, import AVAK90xxxx only.

      Repeat the steps until all transport requests are imported.

  8. Check the transport log for errors. Warnings can usually be ignored.

Add Role ZAVANTRA to other Clients

If you need the ZAVANTRA role (ZAVANTRA_SOLMAN for Solution Manager) in more than one client, import the AVAK900245 or ASMK900006 or XANK900262 transport into each client you require.

Avantra RFC User Setup

If you do not know how to set up an SAP (ABAP) user, please contact your SAP Basis or security administrator to perform the following steps:

  1. Start SAP GUI and log in to the SAP System to monitor.

  2. Please choose an appropriate logon client:

    • For ABAP+Java systems using SAP Java User Management Engine (UME), the user has to be created in the master client used by UME to enable it for Java monitoring.

    • If you intend to monitor an SAP BI/BW system, you need to create the user in the standard client of the BI/BW system.

    • If you intend to monitor an SAP PI/XI system, you need to create the user in the productive client of the PI/XI system.

    • Otherwise, we recommend using client 000.

  3. Call the user maintenance transaction SU01.

  4. Enter the name of the new user in the User field and press the Create button. We recommend naming the user AVANTRA_RFC.

  5. Enter at least a value for Last name in the following screen and switch to the Logon data tab.

  6. In the Logon data screen, enter a password in the fields Initial password and Repeat password.

  7. Also in Logon data, for User type choose the value System (or Communication, or Background).

  8. Switch to the Roles tab and enter the role ZAVANTRA ( plus ZAVANTRA_SOLMAN if in Solution Manager). This profile has been imported with transport request either`AVAK900245` or XANK900262, plus ASMK900006 (if in Solution Manager). If the transport has not been imported yet, see Importing the SAP Transport Request for instructions on how to import a transport request and then assign a profile.

  9. Press the Save button.

You may need a license for the user you fill in. In case of doubt, double-check with SAP.

If you want to make use of security-related monitoring, like the Custom Checks USER_PROFILES or USER_AUTHORIZATIONS, you may want to create the RFC user in all clients you want to monitor.

Avantra J2EE User Setup

Things are getting a little bit more complicated if Java comes into play. We need to distinguish between ABAP+Java and Java-only systems.

Setup for ABAP+Java systems

For an ABAP+Java System, we recommend authorizing the user created as described in Avantra RFC User Setup as an administrator in the J2EE instance.

The easiest way to achieve this is to assign the ABAP role SAP_J2EE_ADMIN to the user created in the ABAP part.

  1. Go to transaction SU01, enter the name of the user created as described in Avantra RFC User Setup in the User field, and click Change.

  2. Switch to the Roles tab and enter the role SAP_J2EE_ADMIN.

    If you intend to monitor SAP XI/PI systems, you have to assign the ABAP role SAP_XI_MONITOR to the user.

    Additionally, you must assign the action xi_af_channel_admin_display to the SAP Java user to enable PI channel monitoring.

  3. Press the Save button.

Setup for Java-only systems

For a Java-only system, we recommend creating a new user (for example AVANTRA_J2EE) and authorize it with the available read-only role AVANTRA_READONLY. Do not use the Administrator user for monitoring.

  1. Start the UME console pointing your browser at the URL http://<hostname>:<port>/useradmin.

  2. Logon as administrator user.

  3. Click Create User and fill in the required fields. Afterward, save the user.

  4. Import the role AVANTRA_READONLY according to the instructions from this solution document.

  5. For a PI/PO system, also assign the SAP_XI_MONITOR_J2EE role.

  6. For a MII system, also assign the SAP_XMII_ADMINISTRATOR role

  7. Click Save.

  8. Follow the solution document JavaJobs and JavaJobStat check critical with message "No scheduler assigned" in order for the checks JavaJobs and JavaJobstat to run properly.

You may need a license for the user you fill in. In case of doubt, double-check with SAP.

User Setup for Database Monitoring

The Avantra Agent needs the credentials of an SQL (!) Database User to connect to a stand-alone Database or the Database instance of an SAP System.

Database instance of an SAP System

As a general rule, use the following Database users to monitor the Database instance of an SAP System:

ABAP-only SAP System

Use the SAP ABAP schema user (e.g. SAPSR3)

Java-only SAP System

Use the SAP Java schema user (e.g. SAPSR3DB)

Double-stack SAP System

Use both users

For an SAP System with MaxDB Database, you also need a DBM Operator (e.g. the CONTROL user). Customers with a higher focus on security can use their own database user instead of using schema user. Please follow the instructions under "Stand-­alone Databases" to create users with minimal required permissions.

Stand-alone Databases

As a general rule, use an administrative Database user for the Database monitoring.

If for security reasons administrative users are not allowed, please follow the steps below:

Oracle

Please make sure the SQL user you use has the permission to access the Catalog Views in Oracle; at least the role SELECT_CATALOG_ROLE must be granted to the user unless it is an Oracle administrator user. To do so, connect to your Oracle Database using SQLPlus and enter the following command:

SQL> GRANT CONNECT, SELECT_CATALOG_ROLE TO <sql-user>

Additionally, when using BR*Tools, the SQL user must be granted SELECT privileges to the SDBAH table in the corresponding SAP schema, unless you already use the SAP schema owner or an administrator user.

The same holds true for the table BC_COMPVERS found in the SAP schema of Java SAP Instances.

DB2

Please make sure your user is part of the SYSMON authority group or has system administration or system control authority. Please refer to your DB2 documentation on how to grant those authorities to your user.

Microsoft SQL Server

Please make sure the user you use has been assigned view server state and db_datareader permissions. See the Microsoft SQL Server documentation on how to grant the permissions to your login user.

Avantra supports both, SQL Server authentication and Windows authentication. In case you choose a Windows authentication user, please define the user in domain format in the Avantra UI: [domain]\[username].
MaxDB

Please define a user in the DBA User Class. For a MaxDB Database, you also need a DBM Operator (e.g. the CONTROL user).

The CONTROL user usually is not able to run SQL commands!
SAP HANA

Please make sure the user is assigned the role Monitoring. In case you run a Java SAP Instance on top of HANA the Database user also needs the following permissions:

GRANT SELECT ON TABLE [DBSCHEMA.]BC_COMPVERS TO [user]
SAP ASE (formerly SAP Sybase ASE)

Please make sure the user has assigned the roles mon_role and oper_role.

For the SYB_Backup check, the permission setting depends on whether granular permissions are enabled for the database or not.

With granular permissions enabled, the dump configuration privilege must be granted to the user.

With granular permissions disabled, according to official Sybase ASE documentation, the role oper_role should be sufficient for the check SYB_Backup (all other checks only require mon_role permissions). Unfortunately, tests have shown that the stored procedure called for SYB_Backup fails with permission error unless the user is a member of sa_role.
SAP SQL Anywhere

Please make sure the user has assigned the system privileges to run the procedure sa_disk_free_space. To do this, run the following grant statements:

GRANT EXECUTE ON sa_disk_free_space to [user]
GRANT MANAGE ANY DBSPACE to [user]
GRANT SELECT ON maint_plan to [user]
GRANT SELECT ON maint_plan_report to [user]

Make sure to replace [user] with the real user name.

SAP IQ

Please make sure the SAP IQ system role SYS_AUTH_OPERATOR_ROLE is granted to the database user for the checks to run in SAP IQ.

MySQL / MariaDB

In this version only the DBCONNECT check and the RUN_JS Custom Check are supported. The permissions required for the database user depends on the functionality included in the Custom Checks.

PostgreSQL

In this version only the DBCONNECT check and the RUN_JS Custom Check are supported. The permissions required for the database user depends on the functionality included in the Custom Checks.

You may need a license for the user you fill in. In case of doubt, double-check with your database vendor.

Verify Java requirements

The Java 8 Runtime Environment is required.

You will need a 64-bit JVM on 64-bit operating systems.

You may use the package management tools of your operating system to install a suitable version.

Otherwise, download the JRE from the Avantra Server (if you followed Preparing the Avantra Agent Deployment) or directly from https://www.java.com/en/download/manual.jsp and install it.

Stand-alone Oracle-specific requirements

If you intend to monitor Oracle stand-alone Databases using the OCI driver connection method, make sure the ORACLE_HOME environment variable is properly set in the environment of the user running the Avantra Agent. On some platforms, you might need to set the library path environment variable as well. Otherwise, the Oracle OCI driver will not be able to access the native shared libraries.

Deploying Avantra Agents to the target systems

On the Physical Servers supposed to run the Avantra Agent, download the appropriate package agent-21.11.n.bin (on Unix-like operating systems) or agent-21.11.n-setup.exe (on Microsoft Windows operating systems) from the Avantra Server (if you followed Preparing the Avantra Agent Deployment).

$ curl http://[avantra-server]:9050/AgentUpdate/agent-21.11.n.bin > agent-21.11.n.bin

Otherwise, download directly from the Support menu of avantra.com (in the AGENT RELEASE 21.11.n section)

Starting with Avantra Version 21.11, it is possible to install the Agent with the self-registration function for Linux operating systems, which is described here Installation on Unix-like operating systems with automatic Agent registration. This feature will also support Microsoft Windows operating systems in future releases.

Installing the Agent on Microsoft Windows

Start the Microsoft installer file agent-21.11.n-setup.exe and follow the instructions on the screen:

  1. On the introduction screen press Next.

  2. Read and accept the license agreement and click I Agree.

  3. Choose installation location and press Next.

  4. The installer will search for a suitable Java Runtime Environment.

    If no suitable Java Virtual Machine is found automatically, click Select Java to choose an installed Java Virtual Machine.

    Press Next to continue if a Java Virtual Machine is defined.

  5. To define a custom agent listener port in case the default port (9051) does not match, select the Set Agent Port checkbox and enter the custom port. If the port settings are correct proceed by pressing Next.

    If you change this value, you must set the AgentListenerPort Monitoring Parameter for this Server accordingly. See Maintaining Parameter Sets and Maintaining Parameter Sets.

  6. On the next page, options for agent self registration can be specified. Please refer to Installation with automatic Agent registration

  7. Read the Windows Firewall configuration rules which will be added to your system. Press Next to proceed.

  8. On the next screen, you can define a different service user. The Avantra Agent service by default runs using the LocalSystem user account. This user may not be allowed to access network resources. If some of your SAP Systems profile data are located on remote (shared) resources, the SAP System will most likely not be monitored. In this case, it is necessary to change the service user to an operating system user allowed to read the network resources (e.g. the SAP System's [sid]adm user).

    Using the SAP System’s [sid]adm as the service user is especially recommended for Java-only SAP System running with a MaxDB.

    If you have chosen the user account press Install to proceed.

  9. Wait until Avantra Agent installation is completed. Press Next to proceed.

  10. Select Start Avantra Agent to start the windows service now. You can also start Avantra Agent later in Windows Services. Press Finish to finish the installation.

In case there is any issue with the installation, you can find the log files in $TEMP{avantra} Installation Logs.

Unattended/Silent Installation on Microsoft Windows operating systems

The Avantra Agent can be installed in an unattended (silent) mode. This is useful if the Agent is installed on many servers with scripts.

Following options can be set to configure the installation:

/S

Required. Start the Agent in silent mode.

/JAVA_PATH

Required. Path to Java installation directory. Do NOT point to java.exe or jvm.dll, JAVA_PATH must point to the directory where java is installed.

/PORT

Required. The port used for the Agent (default is 9051).

/START_SERVICE

Optional. Set to 1 if the Agent should be started immediately after the installation.

/USER

Optional. Set the service user. If not set the Local System account user is used.

/PASSWORD

Optional. Set the password of the service user. Only required if USER is set (see above).

/D

Optional. Installation path. This setting must be the last! Spaces are allowed. If you use spaces, do not wrap with "". If you do not set the path, the Avantra Agent will be installed to %ProgramFiles%\syslink\agent.

Example 1. Install the Agent into the default directory
agent-21.11.n.-setup.exe /S /JAVA_PATH="C:\Program Files\Java\jre1.8.0_92" /PORT=9051
Example 2. Install the Agent into a different directory and start automatically
agent-21.11.n-setup.exe /S /JAVA_PATH="C:\Program Files\Java\jre1.8.0_92" /PORT=9051 /START_SERVICE=1 /D=C:\syslink

Installing the Agent on Unix

On Linux, you need to have the GNU C Library (glibc) version 2.7 or higher installed.

It is recommended to create a dedicated file system for the Avantra Agent of at least 1.5 GB size.

  1. Create a directory to hold the Avantra Agent software, i.e. /opt/avantra.

    root$ mkdir /opt/avantra

  2. Create an operating system user avantra member of an operating system group avantra in order to run the Avantra Agent.

    If you want to run the Avantra Agent using another OS user (e.g. sidadm), simply follow the instructions with user sidadm instead of avantra.

  3. Add the user avantra to the group sapsys.

    The user running the Avantra Agent needs the permissions to read and access the home directories of any user [sid]adm of the installed instances, as well as the profile directories /usr/sap/[SID]/SYS/profile.

  4. Verify that the following access permissions are set for the directory /home/[sid]adm, i.e. the group read permissions are set for the group sapsys:

    drwxr-x---   2 [sid]adm    sapsys    2048 Jan 24 17:28 .
-rw-r-----   1 [sid]adm    sapsys    1515 Apr  9  2002 .cshrc
-rw-r-----   1 [sid]adm    sapsys    2820 Apr 17  2002 .dbenv_[hostname].csh
-rw-r-----   1 [sid]adm    sapsys    7307 Apr 17  2002 .sapenv_[hostname].csh

  5. Verify the group access permission of /usr/sap/[SID]/SYS/profile in the same way.

    1. For SAP installations based on an Oracle database, add the user avantra to the group dba.

      For SAP installations based on an Oracle database, the user avantra needs permissions to read and access the directory /oracle/[SID| (and all sub-directories). In particular, it needs the permissions to read all init* files in `/oracle/[SID]/[ORA`VERS]/dbs_.

    2. For SAP installations based on an IBM DB2 UDB/LUW database add the user avantra to the group db[sid]adm.

      For SAP installations based on an IBM DB2 UDB/LUW database, the user avantra needs permissions to read and access the fail-over log archive path directory (FAILARCHPATH), if configured.

  6. It is recommended that the path to the java executable is included in the PATH environment of the user avantra. Additionally, the path /opt/avantra/java is searched for suitable Java Virtual Machines.

    If no Java executable can be found during the installation, the setup is aborted.

  7. Change ownership of /opt/avantra directory to avantra.

    root$ chown avantra /opt/avantra

  8. Change user to avantra and directory to /opt/avantra.

    root$ su - avantra
avantra$ cd /opt/avantra

  9. Copy the Avantra Agent installation software agent-[version].bin into your current working directory /opt/avantra and start the installer:

    xandria$ chmod +x agent-21.11.n.bin
xandria$ ./agent-21.11.n.bin

    The installer will ask for the Agent listener port during the installation and whether it should start or not. Usually, you can confirm the default port 9051 by pressing Return. You may as well start the Agent immediately.

    Please enter the agent listener port[9051]:
Start Avantra Agent [version]? [y,n] y

    If you change this value, you must set the AgentListenerPort Monitoring Parameter for this Server accordingly. See Maintaining Parameter Sets and Maintaining Parameter Sets.

    If everything works fine, you will get a notice:

    Starting 'avantra_agent' using property 'agent.cfg': Sending nohup output to nohup.out.
Done, running with pid 4128818
Removing 'agent-inst'

  10. You may want to include the Avantra Agent into your system initialization process. The way how to achieve this depends on the Unix type.

    To manually start and stop the Avantra Agent, simply execute the rc script either with parameter start or stop. This can either be done by user root or by user avantra. Example:

    root$ /syslink/agent/rc.agent start
agent is running with PID 12345
xandria$ /syslink/agent/rc.agent stop
Stopping 'avantra_agent' using property 'agent.cfg': Done

Unattended/Silent Installation on Unix-like operating systems

The Unix Agent can be installed in an unattended (silent) mode. This is useful if the Agent is installed on many servers with scripts.

Following options can be set to configure the installation:

--

Required to pass arguments to the integrated self installation script.

--silent

Required. Turns on unattended/silent installation without any questions.

--target-dir=full path to target dir

Optional. Path to the target directory where the Agent will be installed. Default: <current working dir>/agent.

--jvm=start to search for compatible JVM in this directory

Optional. Path to the directory to start searching for a compatible Java. If not specified PATH environment is searched. To use a certain JVM, be as specific as possible, e.g. /opt/java/jre1.8.0_102/.

--port=<number>

Optional. The TCP/IP port the Agent is listening on (default is 9051).

--start=no

Optional. Do not automatically start the Agent process after installation.

Example 3. Install the Agent into ./agent, find java and start automatically
./agent-21.11.n.bin -- --silent
Example 4. Install the agent in a separate directory with a separate JVM, on a different port and without automatic start
./agent-21.11.n.bin -- --silent --target-dir=/opt/agent --jvm=/opt/java/jre1.8.0_102/ \
    --port=9052 --start=no

Installation with automatic Agent registration

Starting with Avantra Version 21.11, you have the possibility to use our new feature - Avantra Agent Self-Registration. This feature allows the Avantra Agent to self-register, eliminating the need for administrators to perform these tasks.

All previously described preconditions must be met, i.e. you must verify the required permissions, create a directory, upload the Agent binary to the installation directory.

To start the Agent in self-registration mode on Unix operating systems, execute the command:

$> agent-21.11.n.bin -- --masterhost=yourmasterhost.x.y.z:9050 --custid=yourcustomerid

To start the Agent in self-registration mode on Microsoft Windows, enable the Activate Self Registration check box in the installer and fill in the corresponding fields.

The following table lists all available self-registration options for agent installation.

Windows Installer Option Unix Command Line Option Mandatory Description

Master Host

--masterhost=…​

Mandatory (when Master Connect Route is not defined)

FQDN or IP address of the master as seen from the agent if agent connects directly to the master

Master Port

--masterport=…​

Optional

Listener port of the master, only used when Master Host is specified. If not defined, 9050 will be used.

Master Connect Route

--masterconnectroute=".."

Mandatory (when Master Host is not defined)

Route valid for the agent, if the master can’t be connected directly. Copy this value from the MasterConnectRoute field of the corresponding Route in the Route Configurator, see The Route Configurator.

Customer ID

--custid=…​

Mandatory

Numeric customer ID of the customer the server shall be registered for. You may look up the customer ID in the customer details in Avantra UI.

Agent IP Address

--ipaddress=…​

Optional

FQDN/IP address of the agent, as seen from the master. If this is left undefined, Avantra will use the remote IP address of the agent when Master Host is used, or the last node’s address in the route when Master Connect Route is used.

System Role

--srtype="…​"

Optional

System role name to be set for the server. If not defined, Test will be set. The role name must match one of the system roles in Settings > Customizing > System Roles in Avantra UI.

Agent Port

--port=…​

Optional

Listener port of the agent. If not defined, 9051 will be used. If set, the agent will listen on that port, and the Avantra master will configure the corresponding AgentListenerPort monitoring parameter for the server.

Specifying the MasterHost or MasterConnectRoute parameters will cause the Agent to self-register during your installation. In case the Agent self-registration failed for any reason, the installation will still be completed.

Once the Avantra Master receives the data from the self-registered Agent, it will execute the following steps:

  • Create a server if it doesn’t already exist (servers are created with the Auto Detected flag)

  • Set the customer specified by option custid

  • Set a system role

After the installation is complete, navigate to the Avantra UI, where the newly installed server/s will appear under Systems > Servers. Open the server details, check the orange fields, press Confirm. This confirmation is necessary for security reasons, and as soon as it is done, automatic monitoring of the server will start.

Installation with systemd configuration on Linux hosts

Starting with Avantra Version 21.11, you additionally can use the systemd configuration feature, which will automatically set up the agent as a systemd service.

The systemd configuration can be used together with the agent self registration feature or independent of it. You can let the agent register itself at the master and at the same time have it configured as as systemd service, but you can also only perform self registration without systemd configuration and vice versa.

To configure your agent as a systemd service during installation, you need to run the installer with superuser privileges.

Please execute the following command:

$> sudo agent-21.11.n.bin -- --systemd --user=youravantraosuser

The following table lists all available systemd options for agent installation.

Unix Command Line Mandatory Description

--systemd

Mandatory

Switch to trigger systemd configuration.

--user=…​

Mandatory*

OS user which will be set as application owner and as sudo user for systemd operations. *If you don’t specify a user, the agent will be created for user 'root', which is strongly discouraged.

--service=…​

Optional

Service name of the systemd service. If not defined, avantra-agent will be used.

A systemd configuration triggers the following actions on the agent host:

  • A systemd service file for the agent is created and moved to /etc/systemd/system/

  • The systemd service is enabled.

  • A sudoers file for the specified user is created and moved to /etc/sudoers.d/, containing the permissions to start, stop, and restart the agent using systemctl.

Regardless of any failures during systemd configuration, the agent installation will be completed. Therefore, please verify if the systemd configuration was successful and the agent is running by calling (adapt the service name if needed):

$> sudo systemctl status avantra-agent

Additional Setup for Monitoring of Java-only SAP Systems with MaxDB

There is still some work to do in order to make the Avantra Agent work properly with a Java-only SAP System using MaxDB.

To make the handling easier, we urgently recommend running the Avantra Agent service for Java-only SAP System using MaxDB on Microsoft Windows operating systems as the user [sid]adm.

The user running Avantra Agent (usually, the user avantra on Unix-like operating systems and the user [sid]adm on Microsoft Windows operating systems), needs a so-called XUSER entry to access the MaxDB Database. See also the MaxDB documentation: MaxDB Library  Tools  Utilities  XUSER.

Proceed as follows to create the XUSER entry:

  1. Depending on your operating system:

    • On Unix-like operating systems login to the host running the Avantra Agent and switch to the user avantra.

    • On Microsoft Windows operating systems login as [sid]adm to the host running the Avantra Agent and open a command shell.

  2. Execute the following command to verify if there are any XUSER entries present for this user:

    [path_to_sapdb]/programs/bin/xuser list

    If there is already a key DEFAULT present, you can skip the following step. If there is also a key c with a user name CONTROL present, then you are done!

  3. Execute the following command to create the DEFAULT key. This is required (by the MaxDB system) although not used by Avantra. See also the MaxDB documentation : MaxDB Library  Tools  Utilities  XUSER  Creating or Changing XUSER Entries.

    [path_to_sapdb]/programs/bin/xuser  -u CONTROL,[pw_of_CONTROL] -d [SID] -n [host]

    where pw_of_CONTROL is the password of the CONTROL database user and SID is the database name which usually is the same as the Real SAP SID of the SAP System.

  4. Repeat the command from Step 2. You should see the following entry:

    XUSER Entry  1
--------------
Key         :DEFAULT
Username    :CONTROL
UsernameUCS2:C.O.N.T.R.O.L. . . . . . .
Password    :?????????
PasswordUCS2:?????????
Dbname      :[SID]
Nodename    :[host]
Sqlmode     :<unspecified>
Cachelimit  :-1
Timeout     :-1
Isolation   :-1
Charset     :<unspecified>

  5. Execute the following command to create a c key:

    [path_to_sapdb]/programs/bin/xuser -Uc -u CONTROL,[pw_of_CONTROL] -d [SID] -n [host]

  6. Repeat the command from Step 2. You should also see the following entry:

XUSER Entry  2
--------------
Key         :c
Username    :CONTROL
UsernameUCS2:C.O.N.T.R.O.L. . . . . . .
Password    :?????????
PasswordUCS2:?????????
Dbname      :[SID]
Nodename    :[host]
Sqlmode     :<unspecified>
Cachelimit  :-1
Timeout     :-1
Isolation   :-1
Charset     :<unspecified>

Post-Installation Connectivity Check

Verify the connection from the Avantra Server to the Avantra Agent using a browser (or wget or curl) on the Avantra Server. Open http://<host name or IP-address of Avantra Agent>:9051/hello:

You have reached the Avantra Agent release 21.11.n running on [host].
Local date/time:
UTC date/time: