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-24.0.n.bin
xandria$ ./agent-24.0.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. /usr/lib/jvm/java-17/.

--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 1. Install the Agent into ./agent, find java and start automatically
./agent-24.0.n.bin -- --silent
Example 2. Install the agent in a separate directory with a separate JVM, on a different port and without automatic start
./agent-24.0.n.bin -- --silent --target-dir=/opt/agent --jvm=/usr/lib/jvm/java-17/ \
    --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-24.0.n.bin -- --masterhost=yourmasterhost.x.y.z --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.

Name Unix Command Line Option Mandatory Description

Master Host

--masterhost=…​

Mandatory (when Master Connect Route is not defined)

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

Master Port

--masterport=…​

Optional

Listener port of the server, only used when server host is specified. If not defined, 9050 will be used.

Master Connect Route

--masterconnectroute=".."

Mandatory (when server Host is not defined)

Route valid for the agent, if the server 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 WebUI.

Agent IP Address

--ipaddress=…​

Optional

FQDN/IP address of the agent, as seen from the server. If this is left undefined, Avantra will use the remote IP address of the agent when server host is used, or the last node’s address in the route when server 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 WebUI.

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 server 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 Server 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 WebUI, 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 server 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-24.0.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