Installing the agent on Linux
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.
- Create a directory to hold the Avantra Agent software, i.e.
/opt/avantra.root$ mkdir /opt/avantra - Create an operating system user
avantramember of an operating system groupavantrain 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.
- Add the user
avantrato the groupsapsys.
The user running the Avantra Agent needs the permissions to read and access the home directories of any user[sid]admof the installed instances, as well as the profile directories/usr/sap/[SID]/SYS/profile. - Verify that the following access permissions are set for the directory
/home/[sid]adm, i.e. the group read permissions are set for the groupsapsys:
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
- Verify the group access permission of
/usr/sap/[SID]/SYS/profilein the same way.- For SAP installations based on an Oracle database, add the user
avantrato the groupdba.
For SAP installations based on an Oracle database, the useravantraneeds permissions to read and access the directory/oracle/[SID]|(and all sub-directories). In particular, it needs the permissions to read allinit*files in/oracle/[SID]/[ORAVERS]/dbs_. - For SAP installations based on an IBM DB2 UDB/LUW database add the user
avantrato the groupdb[sid]adm.
For SAP installations based on an IBM DB2 UDB/LUW database, the useravantraneeds permissions to read and access the fail-over log archive path directory (FAILARCHPATH), if configured.
- For SAP installations based on an Oracle database, add the user
- It is recommended that the path to the
javaexecutable is included in thePATHenvironment of the useravantra. Additionally, the path/opt/avantra/javais searched for suitable Java Virtual Machines.
If no Java executable can be found during the installation, the setup is aborted. - Change ownership of
/opt/avantradirectory toavantra.root$ chown avantra /opt/avantra - Change user to
avantraand directory to/opt/avantra.
root$ su - avantra
avantra$ cd /opt/avantra
- Copy the Avantra Agent installation software
agent-[version].bininto your current working directory/opt/avantraand start the installer:
xandria$ chmod +x agent-[version].bin
xandria$ ./agent-[version].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 Parameter Sets for more information.
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'
- 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 parameterstartorstop. This can either be done by userrootor by useravantra.
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:
| Option | Description |
|---|---|
-- | 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-[version].bin -- --silent
Example 2: Install the agent in a separate directory with a separate JVM, on a different port and without automatic start
./agent-[version].bin -- --silent --target-dir=/opt/agent --jvm=/usr/lib/jvm/java-17/ \
--port=9052 --start=no
Installation with 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-{product-release-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's done, automatic monitoring of the server will start.
Installation with systemd configuration on Linux hosts
You can also 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-{product-release-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