Skip to main content
Version: NG-2.16

JAVA Agents

Java agents are JVM-based collectors used for application/JVM telemetry such as health metrics, logs, and runtime signals from Java workloads. They depend on a compatible Java runtime (JAVA_HOME/PATH) and are commonly deployed on enterprise UNIX platforms (AIX/Solaris/HP-UX), Linux & Windows platforms(vuAppAgent) as background daemons. In production, they should be integrated with the OS startup mechanism so they reliably start after reboot; currently, AIX and Solaris installations use legacy boot integration (inittab and rc runlevel links respectively), while HP-UX uses init.d/rc runlevel links. At runtime, Java agents execute under a non-privileged account, with elevation needed only for boot/service registration steps where required.

Setting JAVA_HOME and PATH for Java Agents​

Java agents (e.g., vuAppAgent / vuHealthagent / vuLogagent) require a valid Java runtime. Ensure JAVA_HOME and PATH are available in the same execution context used to start the agent:

  • OS-managed service start context (system service)
  • User-mode legacy start context (manual/user process)

Legacy mode (user process)​

When used: agent is started manually using <AGENT_HOME>/<agent> start.

Steps (persistent user profile)​

  1. Identify Java home (examples):
  • /usr/lib/jvm/java-11-openjdk
  • /usr/lib/jvm/java-1.8.0-openjdk
  • /opt/java/jdk1.8.0_xxx
  1. Add to the agent execution user profile:

bash/sh/ksh:~/.profile (or ~/.bash_profile or ~/.bashrc)

export JAVA_HOME=/path/to/java
export PATH=$JAVA_HOME/bin:$PATH
  1. Apply + validate:
source ~/.profile
echo $JAVA_HOME
which java
java -version

✅ Result: Java is available when the user manually starts the agent.

Lingering mode (Linux-only: systemd user service)​

When used: agent is managed via:
systemctl --user start <agent>.service
(and boot start typically requires loginctl enable-linger <user> depending on policy)

note

systemd user services often do not inherit interactive shell profiles. Set Java in the user service definition.

Edit:

~/.config/systemd/user/<agent>.service

Add:

[Service]
Environment="JAVA_HOME=/path/to/java"
Environment="PATH=/path/to/java/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

Reload + restart:

systemctl --user daemon-reload
systemctl --user restart <agent>.service
systemctl --user status <agent>.service

Option B: use an EnvironmentFile​

Create:

 ~/.config/<agent>/env.conf
JAVA_HOME=/path/to/java
PATH=/path/to/java/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Reference in unit:

[Service]
EnvironmentFile=%h/.config/<agent>/env.conf

✅ Result: Java is always available for user-service starts and restarts.

systemctl mode (Linux system service)​

When used: agent is managed via:
sudo systemctl start <agent>.service

Important: system services do not rely on user profiles. Set Java in systemd unit or env file.

sudo systemctl edit <agent>.service

Add:

[Service]
Environment="JAVA_HOME=/path/to/java"
Environment="PATH=/path/to/java/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

Reload + restart:

sudo systemctl daemon-reload
sudo systemctl restart <agent>.service
sudo systemctl status <agent>.service

Option B: env file (cleaner)​

Create:

sudo mkdir -p /etc/vunet
sudo vi /etc/vunet/<agent>.env

Add:

JAVA_HOME=/path/to/java
PATH=/path/to/java/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Reference:

sudo systemctl edit <agent>.service

Add:

[Service]
EnvironmentFile=/etc/vunet/<agent>.env

Reload + restart:

sudo systemctl daemon-reload
sudo systemctl restart <agent>.service

✅ Result: Java is available at boot and during service restarts.

AIX / Solaris / HP-UX (Non-systemd UNIX)​

These OSes typically use legacy startup mechanisms (inittab/rc scripts/init.d) or OS-native service managers (SRC/SMF), depending on how the agent is integrated. The rule is the same:

Legacy mode (user process)​

When used: agent is started manually by a non-root user.

Set in the user’s profile:

ksh/sh (common on AIX/Solaris/HP-UX): ~/.profile

export JAVA_HOME=/path/to/java
export PATH=$JAVA_HOME/bin:$PATH

Validate:

echo $JAVA_HOME
which java
java -version

✅ Result: Java is available when the user starts the agent manually.

Service/boot integration mode (root-installed boot start)​

When used: agent starts at boot using:

  • AIX: /etc/inittab (legacy) or SRC
  • Solaris: rc runlevel scripts (legacy) or SMF
  • HP-UX: /sbin/init.d + /sbin/rc*.d links (legacy)

Important: Boot scripts generally run in a minimal environment and may not load user profiles.

Set Java explicitly in the startup script / method that starts the agent (one of these patterns):

Option A: Export JAVA_HOME in the agent boot script​

Add near the top of the boot/start script:

JAVA_HOME=/path/to/java
PATH=$JAVA_HOME/bin:$PATH
export JAVA_HOME PATH

Option B: Source a dedicated env file​

Create a stable env file, for example:

  • /etc/vunet/<agent>.env (root-readable and controlled)

Contents:

JAVA_HOME=/path/to/java
PATH=$JAVA_HOME/bin:/usr/bin:/bin
export JAVA_HOME PATH

Then in the boot/start script:

. /etc/vunet/<agent>.env

✅ Result: Java is available consistently during boot start, restarts, and non-interactive runs.

Validation (All OS)​

After the agent is started, confirm it is using the correct Java:

  • Check agent logs for Java version/path (if printed), OR
  • Confirm java -version works in the same context:
    • Legacy user mode: run as the agent user
    • Service mode: verify the boot script explicitly exports JAVA_HOME/PATH or sources env file

vuAppAgent(Linux/Windows)​

Overview​

vuAppAgent is a Java-based agent that runs plug-ins for Java middleware and applications, including WebSphere Application Server, WebLogic, JBoss, Apache Tomcat, IIB, WebSphere MQ, OHS, AppDynamics, and local/remote JVMs. It schedules plug-ins to collect metrics and sends them to vuSmartMaps.

Prerequisites​

Java​

Java Runtime Environment ≥ 1.8 on the target server.

Network​

Allow outbound connectivity from the target host to vuSmartMaps data collection endpoints on:

  • 9092/TCP – non-SSL (Till 2.16 Build)
  • 9094/TCP – SSL (Till 2.16 Build)

User / Permissions​

  • Linux: non-root user with permissions to access application/JVM and install path; --setupinit systemctl requires sudo for service registration.
  • Windows: installation and service management must be done from an elevated Command Prompt (Run as Administrator).
    • Non-admin install on Windows is currently not supported. If required, we must implement Scheduled Tasks as an enhancement.

Installation and Management​

Linux​

Root/Admin installation steps​
  1. Extract the downloaded vuAppagent package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] --setupinit systemctl [--enablessl]

Arguments

  • --quick – non-interactive quick installation.
  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/vuappagent.
  • --cpulimit <#cores> – CPU core limit (default: 1).
  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).
  • --setupinit systemctl – systemd system service (requires sudo).
  • --enablessl – enables SSL and switches Kafka port to 9094.
Root/Admin agent management steps​
sudo systemctl <start|stop|status> vuappagent.service
Non-root installation steps​
  1. Extract the downloaded Logbeat package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] [--setupinit <lingering|legacy>] [--enablessl]

Arguments

  • --quick – non-interactive quick installation.
  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/vuappagent.
  • --cpulimit <#cores> – CPU core limit (default: 1).
  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).
  • --setupinit <mode> – startup mode:
    • legacy – user-mode process; no auto-start after reboot.
    • lingering – systemd user service with loginctl enable-linger.
      note

      A normal (non-sudo) user can enable lingering for their own account only if the distro ships systemd’s org.freedesktop.login1.set-self-linger polkit action with defaults set to allow it. This was added/fixed in systemd around v230. If a distro is on systemd < 230, there is no “self-linger without root” path; you’ll need root (or an admin/polkit override). Refer here before proceeding with lingering.

  • --enablessl – enables SSL and switches Kafka port to 9094.
Non-root agent management steps​

The exact commands depend on --setupinit:

Legacy mode (legacy) – user process:

<AGENT_HOME>/vuappagent <start|stop|status>

User service (lingering) – systemd user service:

systemctl --user <start|stop|status> vuappagent.service
note

Auto-start behavior (Linux non-root installs)

If the agent is not installed as a system service, it will not auto-start after reboot by default. Use one of these mechanisms:

  • Recommended: lingering user service (systemd user unit) + loginctl enable-linger
  • Alternative: a periodic cron “ensure-running” job (starts agent if not running)
  • Least reliable: start on user login via shell profile
note

(Linux – JAVA_HOME and PATH)

vuAppAgent is Java-based and uses the system Java runtime. On Linux, ensure:

  • JAVA_HOME is set correctly
  • $PATH includes $JAVA_HOME/bin
  • These settings are persistent for the user who runs vuAppAgent.
    note

    system services may not source interactive profiles; ensure JAVA_HOME/PATH is available in the service environment if required.

Windows​

Root/Admin installation steps​
  1. Extract the vuAppAgent package.
  2. Open Command Prompt as Administrator.
  3. Run:
.\vuappagent-installer.exe [--enablessl] /SILENT /NOCANCEL /DIR="<path>\vuappagent" /JAVAPATH="<path\to\java>\bin\java.exe" /MEMLIMIT "<MB>" /CPULIMIT "<#cores>"

Arguments

  • /DIR – optional (default: C:\vunet\vuappagent).
  • /JAVAPATH – required; full path to java.exe (typically JAVA_HOME\bin\java.exe).
  • /MEMLIMIT and /CPULIMIT – as with other agents.
  • --enablessl – enable SSL.
Root/Admin agent management steps​

In an elevated Command Prompt:

sc <start|stop|query> vuappagent
Non-root/Non-Admin installation steps​

Currently, we do not support installing the agent as a non-administrator user on Windows.
If required, we must implement Windows Task Scheduler–based startup (Scheduled Tasks) as an enhancement.

Uninstallation​

Linux​

cd <AGENT_HOME>
./uninstall

Windows​

cd C:\vunet\vuappagent   # or your custom path
.\unins000.exe

Update resource limits​

Linux​

From AGENT_HOME:
cd $AGENT_HOME
./update --resource_cap --cpulimit <cores> --memlimit <MB>

Windows​

Update the limits section in supervisor.ini:

[limits]
memory_mb = {MEMLIMIT}
cpu_limit = {CPULIMIT}

Supported Operating Systems​

  • Linux (Ubuntu, RHEL, CentOS, etc.)
  • Windows Server / Windows desktop (11)

vuHealthagent (Unix)​

Overview​

vuHealthagent is a Java-based metrics and health agent for Unix platforms (AIX, HP-UX, Solaris). It collects OS metrics, runs custom commands, and monitors availability of infrastructure components, sending the data to vuSmartMaps.

Prerequisites​

Operating System​

Supported Unix families:

  • AIX
  • HP-UX
  • SunOS (Solaris)
info

The installer exits for any other uname (via os_check()).

Java​

  • Java 1.8 or later.
  • JAVA_HOME and PATH must be set correctly for the execution context (see Java note in the shared section for these OSes).

Network​

Outbound connectivity from the Unix host to vuSmartMaps:

Till 2.16 build:

  • 9092/TCP – non-SSL
  • 9094/TCP – SSL

Permissions​

Can be installed as non-root or root.

Root is required only for:

  • Automatic boot-time registration (--setupinit)
  • Allowing the script to create entries in inittab / rc directories (OS-specific boot wiring)

Installation and Management​

Installation​

The same install script framework is used across the Unix Java agents. For vuHealthagent:

Run:

./install --quick \
          [--installpath <path>] \
          [--cpulimit <#cores>] \
          [--memlimit <MB>] \
          [--setupinit] \
          [--enablessl]

Arguments

  • --quick
    Enables non-interactive quick installation. Mandatory for this flow.
  • --installpath <path>
    Base directory for installation (default: $HOME).
    Agent home becomes: <path>/vuhealthagent.
  • --cpulimit <#cores>
    CPU hint (float or int, e.g., 0.5, 1, 4).
  • --memlimit <MB>
    Memory hint in MB.
    Clamped to a minimum of 128.
    Used for Java heap sizing and resource caps.
  • --setupinit
    Registers the agent to start on boot.
    • As root: installer automatically configures OS boot integration (inittab/rc).
    • As non-root: installer prints the exact manual steps for the Unix admin to complete.
  • --enablessl
    Updates vuSmartMaps output configuration:
    • Sets SSL flags in conf.d/config.yml
    • Replaces ports 9092/{PORT} with 9094

Managing Agent​

OS-specific startup script location

  • AIX:
AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/rc.d/init.d/vuhealthagent
  • Solaris (SunOS):
AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/init.d/vuhealthagent
  • HP-UX:
 AGENT_STARTUP_SCRIPT=$AGENT_HOME/sbin/init.d/vuhealthagent

Non-root runtime (manual operation)​

You can always start/stop the agent manually as the installation user:

  • AIX
$AGENT_HOME/etc/rc.d/init.d/vuhealthagent < start | stop | status >
  • Solaris (SunOS)
$AGENT_HOME/etc/init.d/vuhealthagent < start | stop | status >
  • HP-UX
$AGENT_HOME/sbin/init.d/vuhealthagent < start | stop | status >

If --setupinit was run as non-root, boot integration is not applied automatically; the installer prints the manual commands for a Unix admin (root) to wire boot startup.

Root runtime + boot integration (--setupinit)​

If installed with --setupinit as root, the installer configures boot startup as below:

AIX

  • Adds inittab entry so agent starts at runlevel 2.
  • Auto-start occurs after reboot at the configured runlevel.

Solaris (SunOS)

  • Creates the runlevel startup linkage so the agent starts in multi-user runlevel.
  • Auto-start occurs after reboot in the configured runlevel.

HP-UX

  • Wires init scripts and rc runlevels and installs rc config.
  • Auto-start occurs after reboot in the configured runlevels.
info

Even with boot integration, you still manage the agent using $AGENT_STARTUP_SCRIPT.

Auto-start behavior notes (Unix Java agents)​

  • Recommended: install with --setupinit using root/admin so the agent is wired into OS boot startup (inittab/rc).
  • If installed without boot integration, it will not auto-start after reboot by default. For non-root installs, the portable alternative is a periodic cron watchdog (runs every minute and starts the agent if not running).

Uninstall​

From AGENT_HOME:
cd $AGENT_HOME
./uninstall

Update resource limits​

From AGENT_HOME:
cd $AGENT_HOME

# (A) Update resource caps only
./update --resource_cap --cpulimit <cores> --memlimit <MB>

Supported Operating Systems​

  • AIX
  • HP-UX
  • Solaris (SunOS)

vuLogagent (Unix)​

Overview​

vuLogagent is the Unix log collection agent. It is Java-based and uses JSON configuration (vulogagent.json) to read logs from files and send them to vuSmartMaps.

Prerequisites​

Operating System​

Supported Unix families:

  • AIX
  • HP-UX
  • SunOS (Solaris)
info

The installer exits for any other uname (via os_check()).

Java​

  • Java 1.8 or later.
  • JAVA_HOME and PATH must be set correctly for the execution context (see Java note in the shared section for these OSes).

Network​

Outbound connectivity from the Unix host to vuSmartMaps:

Till 2.16 build:

  • 9092/TCP – non-SSL
  • 9094/TCP – SSL

Permissions​

Can be installed as non-root or root.

Root is required only for:

  • Automatic boot-time registration (--setupinit)
  • Allowing the script to create entries in inittab / rc directories (OS-specific boot wiring)

Installation and Management​

Installation​

The same install script framework is used across the Unix Java agents. For vuLogagent:

Run:

./install --quick \
          [--installpath <path>] \
          [--cpulimit <#cores>] \
          [--memlimit <MB>] \
          [--setupinit] \
          [--enablessl]

Arguments

  • --quick
    Enables non-interactive quick installation. Mandatory for this flow.
  • --installpath <path>
    Base directory for installation (default: $HOME).
    Agent home becomes: <path>/vulogagent.
  • --cpulimit <#cores>
    CPU hint (float or int, e.g., 0.5, 1, 4).
  • --memlimit <MB>
    Memory hint in MB.
    Clamped to a minimum of 128.
    Used for Java heap sizing and resource caps.
  • --setupinit
    Registers the agent to start on boot.
    • As root: installer automatically configures OS boot integration (inittab/rc).
    • As non-root: installer prints the exact manual steps for the Unix admin to complete.
  • --enablessl
    Updates vuSmartMaps output configuration:
    • Sets SSL flags in conf.d/config.yml
    • Replaces ports 9092/{PORT} with 9094

Managing Agent​

OS-specific startup script location

  • AIX:
 AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/rc.d/init.d/vulogagent
  • Solaris (SunOS):
 AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/init.d/vulogagent
  • HP-UX:
AGENT_STARTUP_SCRIPT=$AGENT_HOME/sbin/init.d/vulogagent

Non-root runtime (manual operation)​

You can always start/stop the agent manually as the installation user:

  • AIX
$AGENT_HOME/etc/rc.d/init.d/vulogagent < start | stop | status >
  • Solaris (SunOS)
$AGENT_HOME/etc/init.d/vulogagent < start | stop | status >
  • HP-UX
$AGENT_HOME/sbin/init.d/vulogagent < start | stop | status >

If --setupinit was run as non-root, boot integration is not applied automatically; the installer prints the manual commands for a Unix admin (root) to wire boot startup.

Root runtime + boot integration (--setupinit)​

If installed with --setupinit as root, the installer configures boot startup as below:

AIX

  • Adds inittab entry so agent starts at runlevel 2.
  • Auto-start occurs after reboot at the configured runlevel.

Solaris (SunOS)

  • Creates the runlevel startup linkage so the agent starts in multi-user runlevel.
  • Auto-start occurs after reboot in the configured runlevel.

HP-UX

  • Wires init scripts and rc runlevels and installs rc config.
  • Auto-start occurs after reboot in the configured runlevels.
info

Even with boot integration, you still manage the agent using $AGENT_STARTUP_SCRIPT.

Auto-start behavior notes (Unix Java agents)​

  • Recommended: install with --setupinit using root/admin so the agent is wired into OS boot startup (inittab/rc).
  • If installed without boot integration, it will not auto-start after reboot by default. For non-root installs, the portable alternative is a periodic cron watchdog (runs every minute and starts the agent if not running).

Uninstall​

From AGENT_HOME:
cd $AGENT_HOME
./uninstall

Update resource limits​

From AGENT_HOME:
cd $AGENT_HOME

# (A) Update resource caps only
./update --resource_cap --cpulimit <cores> --memlimit <MB>

Supported Operating Systems​

  • AIX
  • HP-UX
  • Solaris (SunOS)

vuAppagent (Unix)​

Overview​

On Unix (AIX / HP-UX / Solaris), vuAppagent uses the same Unix installer framework and is Java-based. It runs plug-ins defined under plugins.d to collect metrics from application servers and middleware, and sends data to vuSmartMaps. This section is specific to Unix; Linux/Windows installation for vuAppAgent is covered separately.

Prerequisites​

Operating System​

Supported Unix families:

  • AIX
  • HP-UX
  • SunOS (Solaris)
info

The installer exits for any other uname (via os_check()).

Java​

  • Java 1.8 or later.
  • JAVA_HOME and PATH must be set correctly for the execution context (see Java note in the shared section for these OSes).

Network​

Outbound connectivity from the Unix host to vuSmartMaps:

Till 2.16 build:

  • 9092/TCP – non-SSL
  • 9094/TCP – SSL

Permissions​

Can be installed as non-root or root.

Root is required only for:

  • Automatic boot-time registration (--setupinit)
  • Allowing the script to create entries in inittab / rc directories (OS-specific boot wiring)

Installation and Management​

Installation​

The same install script framework is used across the Unix Java agents. For vuAppagent:

Run:

./install --quick \
          [--installpath <path>] \
          [--cpulimit <#cores>] \
          [--memlimit <MB>] \
          [--setupinit] \
          [--enablessl]

Arguments

  • --quick
    Enables non-interactive quick installation. Mandatory for this flow.
  • --installpath <path>
    Base directory for installation (default: $HOME).
    Agent home becomes: <path>/vuappagent.
  • --cpulimit <#cores>
    CPU hint (float or int, e.g., 0.5, 1, 4).
  • --memlimit <MB>
    Memory hint in MB.
    Clamped to a minimum of 128.
    Used for Java heap sizing and resource caps.
  • --setupinit
    Registers the agent to start on boot.
    • As root: installer automatically configures OS boot integration (inittab/rc).
    • As non-root: installer prints the exact manual steps for the Unix admin to complete.
  • --enablessl
    Updates vuSmartMaps output configuration:
    • Sets SSL flags in conf.d/config.yml
    • Replaces ports 9092/{PORT} with 9094

Managing Agent​

OS-specific startup script location

  • AIX:
AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/rc.d/init.d/vuappagent
  • Solaris (SunOS):
AGENT_STARTUP_SCRIPT=$AGENT_HOME/etc/init.d/vuappagent
  • HP-UX:
AGENT_STARTUP_SCRIPT=$AGENT_HOME/sbin/init.d/vuappagent

Non-root runtime (manual operation)​

You can always start/stop the agent manually as the installation user:

  • AIX
$AGENT_HOME/etc/rc.d/init.d/vuappagent < start | stop | status >
  • Solaris (SunOS)
$AGENT_HOME/etc/init.d/vuappagent < start | stop | status >
  • HP-UX
$AGENT_HOME/sbin/init.d/vuappagent < start | stop | status >

If --setupinit was run as non-root, boot integration is not applied automatically; the installer prints the manual commands for a Unix admin (root) to wire boot startup.

Root runtime + boot integration (--setupinit)​

If installed with --setupinit as root, the installer configures boot startup as below:

AIX

  • Adds inittab entry so agent starts at runlevel 2.
  • Auto-start occurs after reboot at the configured runlevel.

Solaris (SunOS)

  • Creates the runlevel startup linkage so the agent starts in multi-user runlevel.
  • Auto-start occurs after reboot in the configured runlevel.

HP-UX

  • Wires init scripts and rc runlevels and installs rc config.
  • Auto-start occurs after reboot in the configured runlevels.
info

Even with boot integration, you still manage the agent using $AGENT_STARTUP_SCRIPT.

Auto-start behavior notes (Unix Java agents)​

  • Recommended: install with --setupinit using root/admin so the agent is wired into OS boot startup (inittab/rc).
  • If installed without boot integration, it will not auto-start after reboot by default. For non-root installs, the portable alternative is a periodic cron watchdog (runs every minute and starts the agent if not running).

Uninstall​

From AGENT_HOME:
cd $AGENT_HOME
./uninstall

Update resource limits​

From AGENT_HOME:
cd $AGENT_HOME

# (A) Update resource caps only
./update --resource_cap --cpulimit <cores> --memlimit <MB>

Supported Operating Systems​

  • AIX
  • HP-UX
  • Solaris (SunOS)