The agent can be installed once in a folder shared by several hosts (for example an NFS mount), instead of one copy of hpa_agent_dir per host.

In this shared install mode, the shared folder holds the agent versions and the configuration, and each host runs its own copy of the active version, in hpa_agent_dir/hosts/<hostname>/. Everything an agent writes while running (agent logs, infrastructure agent files, data collection files) stays in the directory of its host.

Without shared install mode, a folder used by several hosts is not supported: the hosts write to the same files and the infrastructure agent (SystemEdge) fails to start on the second host.

Layout

hpa_agent_dir/                            shared
  deploy.sh, hpa_agent_*.sh, hpa_agent_config.sh, override_config/, default_config/
  wily-<version>/ apmia-<version>/        unzipped versions
  wily -> wily-<version>                  active version
  hosts/<hostname>/                       one directory per host, created by deploy.sh
    hpa_agent_config.sh                   optional, host-specific settings
    wily-<version>/ apmia-<version>/      copy of the active version run by this host
    override_config, default_config       links to the shared folders

<hostname> is the output of the hostname command on the host.

Activation

Add the following line to hpa_agent_dir/hpa_agent_config.sh:

export HPA_SHARED_INSTALL=1

Installation and upgrade

Unzip the agent once into hpa_agent_dir, as described in Agent installation.
On each host, as the user that starts Calypso on that host, run the deploy command. It sets the active version of the folder and creates or updates the copy of the host:
```
bash {{hpa_agent_dir}}/deploy.sh x.xx
```
It can be run while the Calypso components and the infrastructure agent of the host are running: they keep using their files until restarted.

On each host, restart the infrastructure agent if it is used:

{{hpa_agent_dir}}/hpa_agent_common.sh stop
{{hpa_agent_dir}}/hpa_agent_common.sh start

Restart the Calypso components of each host.

The deploy command must also be run on each host after any change of hpa_agent_config.sh.

A Calypso component started on a host where the deploy command was never run starts without agent, and its startup output shows:

WARNING : HPA shared install not deployed on this host, run deploy.sh on <hostname>. HPA not activated

A host still running an older copy than the active version keeps running it, and its startup output shows a warning until the deploy command is run on it.

Rollback: run the deploy command with the previous version on each host.

Host-specific settings

Any variable of hpa_agent_config.sh can be set differently for one host in hpa_agent_dir/hosts/<hostname>/hpa_agent_config.sh, read after the shared file. For example, to monitor the Calypso database from one host only:

# hpa_agent_dir/hosts/<hostname>/hpa_agent_config.sh
export HPA_CALYPSO_DATABASE_ENABLED=1

The deploy command must be run on that host after the file is created or modified.

Users and permissions

NFS checks permissions by numeric user id (UID) and group id (GID), not by name. They can be checked with id <user> on each host. Two setups are supported:

The same user runs Calypso on every host: this user must have the same UID and GID on every host. Nothing else is needed.
A different user runs Calypso on each host (for example calypsoA on host A and calypsoB on host B): these users must share a group, with the same GID on every host and on the NFS server. See below.

In both setups, each host is deployed by the user that runs Calypso on that host: its directory hpa_agent_dir/hosts/<hostname>/ belongs to that user, which also starts the Calypso components and the infrastructure agent of the host.

Different users sharing a group

Every user writes to the shared part of the folder (active version links, hosts/, override_config/, unzipped versions), which must therefore belong to the group and be writable by it. The agent zip and the deploy command create their files and directories this way. The folder itself is set up once:

New folder, before the first unzip, by the user creating it:

mkdir {{hpa_agent_dir}}                  # creates the empty folder
chgrp <group> {{hpa_agent_dir}}          # gives it to the group shared by the users
chmod 2775 {{hpa_agent_dir}}             # 775: writable by the group; 2 (setgid): what is created inside belongs to the group

Existing folder: only the owner of a file, or root on the NFS server, can change its group and permissions. Each user runs the following commands, which change only the files owned by that user (run as root on the NFS server, without -user $(id -un), they change all the files at once):

cd {{hpa_agent_dir}}
# gives the files and directories of the user (except links and host directories) to the group, writable by it
find . -path './hosts/*' -prune -o -user $(id -un) \! -type l -exec chgrp <group> {} + -exec chmod g+w {} +
# sets setgid on the directories of the user: what is created inside belongs to the group
find . -path './hosts/*' -prune -o -user $(id -un) -type d -exec chmod g+s {} +

The directory of each host, hosts/<hostname>/, is left as is: it belongs to the user of that host.

A file created or copied into the folder by hand (for example hpa_agent_config.sh created from its template, or a file added to override_config/) can only be modified by its creator. It is made writable by the group by that user:

chmod g+w <file>

The following command lists the directories and configuration files the group cannot modify. Each one listed is fixed with chmod g+w <path> by its owner, shown first on each line:

cd {{hpa_agent_dir}}
find . -path './hosts/*' -prune -o \( -type d -o -name hpa_agent_config.sh -o -path './override_config/*' \) \! -perm -g+w -printf '%u %m %p\n'

The other files of the folder (agent versions, scripts) are only replaced by unzip -o: they don’t need to be writable by the group.

Switching an existing folder to shared install mode

Unzip the new agent version into the folder.
Add export HPA_SHARED_INSTALL=1 to hpa_agent_config.sh, and the host-specific files if needed.
Run the deploy command on each host.
On each host, run hpa_agent_common.sh stop (it also stops the infrastructure agent started from the shared folder), then hpa_agent_common.sh start, and restart the Calypso components.

Until the deploy command is run on a host, its Calypso components start without agent.

The Oracle monitoring password already entered is kept: it does not need to be entered again.

Oracle monitoring password

The password is entered once, on the first host monitoring the database (see Oracle extension). The deploy command then reuses it:

from the previous copy of the same host,
otherwise from another host monitoring the same database,
otherwise from the folder before the switch to shared install mode.

To change the password, update it on each host monitoring the database.

Logs and data collection files

Agent logs: hpa_agent_dir/hosts/<hostname>/wily/logs.
Infrastructure agent logs: hpa_agent_dir/hosts/<hostname>/apmia/logs.

When HPA_AGENT_LOG_DIR is set (see Agent logs), it is used as is by every host. To keep one directory per host, include the host name:

export HPA_AGENT_LOG_DIR=/path/to/logs/$(hostname)

The hpa.dumpDirectory property, if set in a profile override, must point to a directory local to each host.

Limits

override_config and default_config are shared by all hosts: host-specific settings are limited to the variables of hpa_agent_config.sh (see Host-specific settings). The deploy command stops with an error when hpa_agent_dir/hosts/<hostname>/override_config or default_config is a directory instead of a link, and gives the steps to fix it.
Old versions are not removed automatically. A wily-<version> or apmia-<version> directory (in hpa_agent_dir and in hpa_agent_dir/hosts/*/) can be removed once no host uses it and the Calypso components and infrastructure agents were restarted on a newer version.

HPA installation and deployment HPA agent Calypso Agent folder shared by several hosts