Appendix: Agent Installation Instructions

Here are the steps to install the agent on the login node of M:Arthur.

1. Introduction

This procedure is for installing the agent used for M:Arthur in your environment.
This procedure is to be performed only on the login node (administrative node).

OpenPBS or Slurm must already be installed to perform this procedure.
For other prerequisites, please refer to Appendix: Assumed Settings.

Please install the agent by following the procedure from 2. below.

2. (Customer Work) Issuing an Activation Code

After you provide us with the administrator’s email address and other information, we will create your account and send you the login information by email.

Information we will send you
- Login URL of the management console
- Registered email address
- Password

After logging in with the above information, create an activation by referring to the Create an Activation and Register a Login Server chapter of this manual.
Make sure you have the following on hand before proceeding to the next step.

The command to run for the activation
- The command contains the activation information.

3. (Customer Work) Agent Installation

Please install the agent according to the procedure of 3.1.~3.2.

3.1. Copying the Command

On the activation screen of the management console ([Setting] > [Server] > [Activation]), click the copy icon at the right end of the added row (the red frame in the figure below). The command to run is copied to the clipboard.
When you hover the mouse over the icon, the command to be copied is displayed.

activation_copy_icon

The copied command includes the activation code (--code), the activation ID (--id) and the HPC Type selected when the activation was created (--hpc). You do not need to edit the command by hand.
For how to create an activation, see Create an Activation and Register a Login Server.

If you are using a Proxy

If the login server connects to the outside through a proxy, enter the proxy URL in the “Proxy URL” field on the screen in the form http://hostname:port before copying the command.
The copied command then includes the proxy settings. You do not need to configure the proxy manually.

If your proxy accepts https connections, enter https://hostname:port.
For a proxy that requires authentication, you can enter http://user:password@hostname:port. If the user name or password contains symbols other than letters, digits and . _ ~ -, percent-encode them, such as %40 for @. The password is saved in the systemd configuration files on the server (readable only by root). While the command is running, other users may be able to see the command line, including the password.

3.2. Running the Command

Run the copied command on the login server.
The command is a single line like the following (the values of --code and --id differ for each activation. --hpc is the job scheduler type selected for the activation, either pbs or slurm).

$ curl -fsSL https://agent.m-arthur.com/install.sh | sudo -E sh -s -- --code "xxxxx" --id "xxxxx" --hpc pbs

This command downloads and runs our registration script. The script does all of the following, so you do not need to use different commands for each OS.

Installs the agent (amazon-ssm-agent) and registers it with M:Arthur (using the registration tool provided by AWS, which also verifies the agent’s signature)
Installs the CloudWatch Agent (amazon-cloudwatch-agent), and configures and starts it to collect the job logs (the OpenPBS server logs or the Slurm logs)
If you entered a proxy, configures the agents to use it
Checks the registration and that the agent and the CloudWatch Agent are running

When it finishes successfully, the following is displayed at the end. The server appears in the server list of the management console in a few minutes.

[M:Arthur] CloudWatch Agent is running.
[M:Arthur] Completed. Managed instance ID: mi-xxxxxxxxxxxxxxxxx
[M:Arthur] The server will appear in the management console in a few minutes.

sudo privileges and curl are required. You can also run it as the root user as it is.
HTTPS (port 443) access from the login server to agent.m-arthur.com and *.amazonaws.com is required.
Supported CPU architectures are x86_64 and aarch64.
If you run it on a server that is already registered, the registration is not changed; the agent is restarted and only the CloudWatch Agent is configured.
The CloudWatch Agent setup supports RHEL-based operating systems such as AlmaLinux / Rocky Linux, and Ubuntu / Debian.
If WARNING: --hpc is not given is displayed, the job logs are not collected. Copy the command again from the activation code screen and run it.

Re-registering a previously registered server

A server that was registered before (for example, one deleted from the management console) still has the previous registration information. If you run the command as it is, the registration is skipped and the agent starts with the previous registration (This server is already registered is displayed).
To register it again, add --reregister to the end of the copied command. The script removes the previous registration information and registers the server again.

$ curl -fsSL https://agent.m-arthur.com/install.sh | sudo -E sh -s -- --code "xxxxx" --id "xxxxx" --hpc pbs --reregister

This completes the installation process.
You can now begin operations in accordance with the User Guide.

4. If the Installation Fails

Each time the registration script runs, it records what it displays on the screen and information about the server environment in a log file. If the installation fails, it also records the results of checking the connections to the required endpoints, the agent logs and other details.

Log file: /var/lib/m-arthur/agent-install.log (readable only by root)
The activation code and the proxy user name and password are not recorded in the log (they are recorded as ****)

If the installation fails, Installation failed is displayed. Copy the log file with the following command and send it to our support.

$ sudo cp /var/lib/m-arthur/agent-install.log ~/m-arthur-agent-install.log && sudo chown "$USER" ~/m-arthur-agent-install.log

Checking in advance (nothing is changed)

If you run the script with --diagnose, it does not install or configure the agents, and only checks the server environment and whether it can connect to the required endpoints (*.amazonaws.com). The results are recorded on the screen and in the log file. We may ask you to run this check.

$ curl -fsSL https://agent.m-arthur.com/install.sh | sudo -E sh -s -- --diagnose

If you use a proxy, add --proxy http://hostname:port after --diagnose (and add -x http://hostname:port to curl).