Automated agent installation

Before deploying agents, upload the agent packages to the Avantra Server as described in Preparing the Avantra Agent Deployment. Alternatively, download them directly from the Customer Hub under Software Downloads, using a tool like curl, wget, or a browser — over the same network connection the agent will use.

The standard installation described in Installing the Avantra Agent requires logging into each server individually. This approach doesn't scale well. The following sections cover remote installation options for Linux and Windows.

note

This procedure covers the initial agent deployment. For subsequent updates, use the automatic agent update feature — see Upgrading Agents Automatically.

Deploy Avantra agents to Linux remotely

Deploy the Avantra Agent remotely to Linux servers using SSH. The target server must be remotely accessible, the OS user must be the same user that runs the Avantra Agent, and that user must be able to run passwordless sudo commands. See Red Hat Developer Documentation: How to enable sudo on Red Hat Enterprise Linux for more information.

Use the following script as a template, or check for the latest version in our Bitbucket Repository: Install Avantra Agent via SSH.

#!/bin/sh -xe
# -----------------------------------------------------------
# Change the following variables according to your needs
#
# AVANTRA_HOST  is the Avantra server's dns name or IP address
# AGENT_VERSION is the version of an Avantra Agent uploaded
#               to the UI
# JAVA_INSTALL  is the command to install Java 21. Adapt to
#               your distro
# AGENT_USER    is the OS user on the target system that runs
#               the Avantra agent, is accessible by SSH, and
#               can run sudo without a password.
# DISTDIR       is the directory the agent is going to be
#               installed to
# SERVICE_NAME  is the name of the service in systemd
#
# Run as:
# ssh <AGENT_USER>@<TARGET> 'sh -s' < deploy-avantra-agent.sh
# -----------------------------------------------------------
AVANTRA_HOST=
AGENT_VERSION=
JAVA_INSTALL="yum install -y java-21-openjdk" # Red Hat, CentOS, Fedora
# JAVA_INSTALL="zypper install -y java-21-openjdk" # SUSE
AGENT_USER=
DISTDIR=/opt/avantra
SERVICE_NAME=avantra-agent
## -- install java
sudo $JAVA_INSTALL
## -- install agent --
sudo mkdir -p "$DISTDIR" \
    && sudo chown -R $AGENT_USER: "$DISTDIR" \
    && cd "$DISTDIR" \
    && sudo -u $AGENT_USER curl -s http://$AVANTRA_HOST:9050/AgentUpdate/agent-$AGENT_VERSION.bin -o agent-$AGENT_VERSION.bin \
    && sudo -u $AGENT_USER chmod 755 ./agent-$AGENT_VERSION.bin \
    && sudo -u $AGENT_USER ./agent-$AGENT_VERSION.bin -- --silent --start=no
## -- create service file for systemd --
sudo cat <<ENDSVCFILE | sudo tee "/etc/systemd/system/$SERVICE_NAME.service" > /dev/null
[Unit]
Description=Avantra Agent $AGENT_VERSION
After=network.target

[Service]
ExecStart=$DISTDIR/agent/rc.agent start
ExecStop=$DISTDIR/agent/rc.agent stop
User=$AGENT_USER
KillMode=process
Type=forking
PIDFile=$DISTDIR/agent/log/agent.pid

[Install]
WantedBy=multi-user.target
ENDSVCFILE
## -- allow $AGENT_USER to sudo systemctl --
sudo cat <<ENDSUDOERSFILE | sudo tee "/etc/sudoers.d/$AGENT_USER" > /dev/null
$AGENT_USER ALL=NOPASSWD: /usr/bin/systemctl start $SERVICE_NAME
$AGENT_USER ALL=NOPASSWD: /usr/bin/systemctl stop $SERVICE_NAME
$AGENT_USER ALL=NOPASSWD: /usr/bin/systemctl restart $SERVICE_NAME
ENDSUDOERSFILE
sudo visudo -cf "/etc/sudoers.d/$AGENT_USER"
## -- enable service --
sudo systemctl enable "/etc/systemd/system/$SERVICE_NAME.service" \
    && sudo systemctl start $SERVICE_NAME

Adapt the following variables:

Variable	Description
AVANTRA_HOST	The DNS name or IP address of the Avantra Server.
AGENT_VERSION	The version (e.g. 20.5.1) of the Avantra Agent you have uploaded to the Avantra Server.
AGENT_USER	The OS user to run the Avantra Agent with. <sid>adm may be a good choice for servers hosting SAP application servers. Otherwise, choose an existing OS user.
JAVA_INSTALL	The OS command to install the Java 21 Runtime Environment on your Linux host. Verify the correct package name for your distribution before running.

Then run the following command to install the Avantra Agent remotely:

ssh <AGENT_USER>@<TARGET> 'sh -s' < avantra-agent-deploy.sh

Deploy Avantra agents to Windows remotely

You can deploy the Avantra Agent remotely to Windows servers using PowerShell Remoting.

note

PowerShell Remoting works best in an Active Directory environment. If you have not already set up PowerShell Remoting, the setup effort may outweigh the benefits for smaller deployments.

note

Set the Execution Policy on the computer where you intend to run the script. Check whether your security policies allow this change. Consider using the value RemoteSigned.

Use the following script as a template, or check for the latest version in our Bitbucket Repository: Install Avantra Agent via PowerShell.

# - Upload the Avantra Agent installer as a package to the Agent Update rpository
# - Adapt these variable according to your needs
# - Modify the execution policy to allow running powershell scripts
[string]$user = '<DOMAIN\user>'          # Access to the remote system
[string]$target = '<target-host>'        # The remote system
[string]$avantrahost = '<avantra-server>' # The FQDN of the Avantra Sever
[string]$agentversion = '26.0'            # The agent version (uploaded to the repository)
[string]$javapath = 'C:\Program Files\Java'
# Adapt this to the latest Java 21 JRE .msi: Go to https://adoptium.net/en-GB/temurin/releases/?version=21,
# choose Windows x64, right-click the .msi next to JRE, and copy the direct link.
[uri]$javaurl = '<JAVA_21_MSI_URL>'       # Replace with the direct .msi download URL for Eclipse Temurin Java 21 JRE

# There should be no need to change anything below this line

[uri]$agenturl = 'http://' + $avantrahost + ':9050/AgentUpdate/agent-' + $agentversion + '-setup.exe'

# Self-elevate the script if required
if (-Not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] 'Administrator')) {
    if ([int](Get-CimInstance -Class Win32_OperatingSystem | Select-Object -ExpandProperty BuildNumber) -ge 6000) {
        $CommandLine = "-File `"" + $MyInvocation.MyCommand.Path + "`" " + $MyInvocation.UnboundArguments
        Start-Process -FilePath PowerShell.exe -Verb Runas -ArgumentList $CommandLine
    Exit
    }
}

$session = New-PSSession -ComputerName $target -Credential $user

Invoke-Command -Session $session -ScriptBlock {
    param($javaurl, $agenturl, $javapath)
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Invoke-WebRequest `
        -Uri $javaurl `
        -OutFile 'C:\Windows\Temp\java-installer.msi'
    Invoke-WebRequest `
        -Uri $agenturl `
        -OutFile 'C:\Windows\Temp\agent-installer.exe'
    msiexec /i C:\Windows\Temp\java-installer.msi /quiet `
        ADDLOCAL="FeatureMain,FeatureEnvironment,FeatureJarFileRunWith,FeatureJavaHome,FeatureOracleJavaSoft" `
        INSTALLDIR=`"$javapath`"
    C:\Windows\Temp\agent-installer.exe /S /JAVA_PATH=`"$javapath`" /START_SERVICE=1 /PORT=9051 /D=C:\Program Files\avantra
} -ArgumentList $javaurl,$agenturl,$javapath
    Remove-Item -path 'C:\Windows\Temp\java-installer.msi'
    Remove-Item -path 'C:\Windows\Temp\agent-installer.exe'
Remove-PSSession $session

Adapt the following variables:

Variable	Description
$user	The (Domain) user to access the remote system.
$target	The name of the remote system.
$avantrahost	The DNS name or IP address of the Avantra Server.
$agentversion	The version (e.g., 26.0) of the Avantra Agent you have uploaded to the Avantra Server.
$javaurl	The direct download URL for the Eclipse Temurin Java 21 JRE .msi. Go to Adoptium Temurin releases, select Windows and x64, then right-click the .msi next to JRE to copy the direct link.

Run the following in an elevated PowerShell:

PS> .\deploy-avantra-agent.ps1

Agent mass deployments

For large-scale deployments, use Ansible. An example playbook is available for the remote deployment of Avantra Agents to Linux and Windows servers.

note

This is an example Ansible playbook demonstrating how to install Java and the Avantra Agent on Linux and Windows. The purpose is to illustrate the tasks all in one file. It is by no means a good way to design an Ansible playbook.

At minimum, adapt the variables avantra_host and agent_version. The latest version is also available in our Bitbucket Repository: Install the Avantra Agent using an Ansible Playbook.

# NOTE:
# This is an example ansible playbook demonstrating how to install Java 21
# and the Avantra Agent on Linux and Windows. The purpose is to illustrate
# the tasks all in one file. It is by no means a good way to design an
# ansible playbook.
#
- name: Install Java 21 JRE and Avantra Agent
  hosts: all
  vars:
    # Adapt this value to your Avantra Server, if you have uploaded the agent
    # packages. Or see the comments below how to use direct download links.
    avantra_host: your.avantra.server
    # Adapt to the agent version
    agent_version: 26.0
    agent_dir: /opt/avantra
    agent_win_dir: ansible_env['ProgramFiles']\avantra
    agent_user: avantra
    create_user: true
    agent_service: avantra-agent

  tasks:
  - name: Install Java 21 on SUSE
    become: true
    package: >
      name=java-21-openjdk
      state=latest
    when: ansible_os_family == 'SUSE'

  - name: Install Java 21 on RedHat
    become: true
    package: >
      name=java-21-openjdk
      state=latest
    when: ansible_os_family == 'RedHat'

  - name: Install Eclipse Temurin Java 21 on Windows
    when: ansible_os_family == 'Windows'
    block:
    - name: Get Temurin Java 21 JRE release info
      win_uri:
        url: "https://api.adoptium.net/v3/assets/latest/21/hotspot?os=windows&architecture=x64&image_type=jre"
        return_content: true
        follow_redirects: all
      register: release_info
    - name: Find installer url
      set_fact:
          release_url: >-
            {{
              (release_info.content | from_json).binaries | map(attribute='installer_link') | list +
              (release_info.content | from_json).binaries | map(attribute='installer_name') | list
            }}
    - name: 'Download artifact {{ release_url[1] }}'
      win_get_url:
        url: '{{ release_url[0] }}'
        dest: '%TEMP%'
        force: true
      register: file_downloaded
      retries: 20
      delay: 5
      until: file_downloaded is succeeded
    - name: Install from remote
      win_package:
        path: '{{ file_downloaded.dest }}'
        state: present

  - name: Create user and directory on Linux
    when: ansible_system == 'Linux'
    block:
    - name: Create User
      become: true
      when: create_user
      user:
        name: "{{ agent_user }}"
        state: present
    - name: Create directory
      become: true
      file:
        path: "{{ agent_dir }}"
        state: directory
        owner: "{{ agent_user }}"
        group: "{{ agent_user }}"
        mode: 0755

  - name: Download and Install Avantra Agent on Linux
    when: ansible_system == 'Linux'
    block:
    - name: Download Agent
      get_url:
        # NOTE: You can also head to downloads.avantra.com, generate a direct
        # download link, and use it here. Keep in mind that these generated
        # links expire after 12 hours.
        url: http://{{ avantra_host }}:9050/AgentUpdate/agent-{{ agent_version }}.bin
        dest: /tmp
        mode: '0755'
    - name: Install Agent
      command: /tmp/agent-{{ agent_version }}.bin -- --silent --start=no
      become: true
      become_user: "{{ agent_user }}"
      args:
        chdir: "{{ agent_dir }}"
    - name: Create Systemd Service file
      become: true
      copy:
        dest: /etc/systemd/system/{{ agent_service }}.service
        content: |
          [Unit]
          Description=Avantra Agent
          After=network.target

          [Service]
          ExecStart={{ agent_dir }}/agent/rc.agent start
          ExecStop={{ agent_dir }}/agent/rc.agent stop
          User={{ agent_user }}
          Type=forking
          KillMode=process
          PIDFile={{ agent_dir }}/agent/log/agent.pid

          [Install]
          WantedBy=multi-user.target
    - name: Enable Agent service
      become: true
      service:
        daemon_reload: yes
        name: "{{ agent_service }}"
        enabled: yes
        state: started
    - name: Enable agent_user to run systemctl
      become: true
      copy:
        dest: /etc/sudoers.d/{{ agent_user }}
        content: |
          {{ agent_user }} ALL=NOPASSWD: /usr/bin/systemctl start {{ agent_service }}
          {{ agent_user }} ALL=NOPASSWD: /usr/bin/systemctl stop {{ agent_service }}
          {{ agent_user }} ALL=NOPASSWD: /usr/bin/systemctl restart {{ agent_service }}
        validate: 'visudo -cf %s'

  - name: Install Avantra Agent on Windows
    win_package:
      # NOTE: You can also head to downloads.avantra.com, generate a direct
      # download link, and use it here. Keep in mind that these generated
      # links expire after 12 hours.
      path: http://{{ avantra_host }}:9050/AgentUpdate/agent-{{ agent_version }}-setup.exe
      creates_path: '{{ agent_win_dir }}'
      arguments:
        - /S
        - /START_SERVICE=1
        - /PORT=9051
        - /D={{ agent_win_dir }}
      state: present
    when: ansible_os_family == 'Windows'

Post-installation setup

After deploying the Avantra Agents, follow the steps in Preparing the Avantra Agent deployment.

The transport request mentioned there is already available at /opt/avantra/AgentUpdate on the Avantra Server. It can be accessed in the same way (via HTTP) as described in the Product Guide (and as described in the deployment steps above).

note

Also follow steps 3 to 6 of Installing the Agent on Linux, replacing the OS user xandria with the value you chose for AGENT_USER.