FSO Agent Deployment: Install, Verify and Troubleshoot

FSO Agent Deployment: Install, Verify and Troubleshoot

Deploy the FSO Agent on a Windows or Linux server, verify that it’s reporting to Applications Manager, and resolve any installation errors.

Info
Quick start: Installing now? Start with Before you begin. Install command already failed? Go to Quick error lookup.

Before you begin

RequirementWindowsLinux
Applications Manager buildv175500 or laterv175500 or later
Supported OS versionsSee FSO Agent system requirementsSee FSO Agent system requirements
Run the install command asPowerShell opened as AdministratorRoot, or a user with sudo (sudo must be installed)
Tools neededPowerShell script execution allowedwget (required), curl (for live status on the FSO Agent page)
Network accessHTTPS to Applications Manager (default port 10099)HTTPS to Applications Manager (default port 10099)

Deploy the FSO Agent

  1. Sign in to Applications Manager as an Admin user and go to the FSO Agent page (Settings → Discovery & Data Collection → FSO Agent).
  2. If the target server reaches Applications Manager through a different address (FQDN, IP, NAT or proxy) or a port other than the default 10099, update Host or Port under Agent Bundle & Capabilities → Applications Manager address and save.
  3. Copy the install command and run it on the target server: on Windows, in PowerShell opened as Administrator; on Linux, in a terminal as root or a user with sudo.

Track installation progress

The install command runs in five steps. The first line, FSO agent registration - https://<host>:<port>, shows the address it connects to. Select a step to go to its fix.

On Linux, when you reinstall, the existing agent is removed between Step 3 and Step 4 (Uninstalling existing FSO agent).

When a step fails, it shows FAILED and an ERROR: message. A failed run always ends with a support line that includes the log file path, if a log was kept (see Collect diagnostic logs).

Verify the deployment

When all five steps show OK, you’ll see The FSO Agent is installed. It appears in View Agents once it registers with Applications Manager. Open View Agents in Applications Manager to check that the agent is listed.

Info
Note: After the install command completes, it can take 1 to 2 minutes for the agent to appear in View Agents in Applications Manager.
Notes
Seeing FAILED, an ERROR: message or any unexpected output in the terminal? Look it up in Quick error lookup.

Quick error lookup

StageWhat you seeGo to
Before Step 1running scripts is disabled on this system (Windows)PowerShell blocks the script (Windows)
Before Step 1A license key is required…License key not provided
Step 1[1/5] … FAILEDStep 1 of 5 · Privilege check failed
Step 2[2/5] … ALREADY INSTALLEDStep 2 of 5 · Agent already installed
Step 3[3/5] … FAILEDStep 3 of 5 · Connectivity check failed
After Step 3 (Linux reinstall)Uninstalling existing FSO agent … FAILED (Linux)Reinstall blocked: existing agent not removed (Linux)
Step 4[4/5] … FAILEDStep 4 of 5 · Installer download failed
Step 5[5/5] … FAILEDStep 5 of 5 · Installation failed
After Step 5 (Windows)Restart this machine to complete the setup (Windows)Not an error. See Step 5 of 5 · Installation failed (Windows)
Any stepWARNING: Could not send '<stage>' status…Status update warning (no action needed)
Any stepThe install command stops at a step and shows no resultCheck the connection items in Step 3 of 5 · Connectivity check failed, then the download items in Step 4 of 5 · Installer download failed

Resolve installation errors

Each section matches a message from the install command, in the order the install command runs. When a message says See <log>, open fso_agent_register.log. Its full path is shown in the install script’s output (see Collect diagnostic logs).

PowerShell blocks the script (Windows)

Error: … cannot be loaded because running scripts is disabled on this system.

Cause: The PowerShell execution policy blocks scripts.

Fix:

  1. In the same elevated PowerShell window, run:
    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  2. Run the install command again.
Info
This doesn’t change your system’s policy. -Scope Process applies only to the current PowerShell window, and the setting is discarded when you close it.
Notes
If the policy is set by Group Policy, contact your system administrator.

↑ Back to error lookup

License key not provided

Prompt: Enter the Applications Manager license key
Error: A license key is required. Copy the install command again from Applications Manager.

Cause: The command was run without its key. This usually means it was copied only partly, or the script file was run on its own.

Fix: Copy the complete install command from the FSO Agent page and run it again. Don’t run register.sh or register.ps1 by themselves.

↑ Back to error lookup

Step 1 of 5 · Privilege check failed

Windows
Linux
Windows

Error: Run this script from an elevated PowerShell (Run as Administrator).

Fix: Open PowerShell with Run as Administrator and run the install command as described in Deploy the FSO Agent.

Linux

Error: No sudo access. Run 'sudo -v' to authenticate, then re-run this script.

Cause: The script checks sudo without prompting for a password, so the check fails if your sudo session has expired.

Fix: Run sudo -v, enter your password, then run the install command right away.

Idea
Tip: Run both in one line so the sudo session can’t expire in between: sudo -v && <install command>

Error: sudo is required but not installed on this machine.

Cause: sudo is not installed. The install command needs it even when you’re logged in as root.

Fix: Install sudo (yum install sudo or apt-get install sudo), then run the install command again.

↑ Back to error lookup

Step 2 of 5 · Agent already installed

Message: [2/5] Checking for an existing agent ... ALREADY INSTALLED, followed by The FSO Agent is already installed on this server. No changes were made.

If the existing agent is working, no action is needed. To reinstall:

Windows
Linux
Windows
  1. Uninstall the FSO Agent from Settings → Apps → Installed apps.
  2. Run the install command again.
Linux

At the prompt Uninstall the existing FSO agent and reinstall? [y/N]:, answer y. The script removes the old agent only after the connection check in Step 3 passes.

Warning
If Step 4 or Step 5 fails after the old agent is removed, the server has no FSO Agent until you fix that error and run the install command again.

Got “No changes were made” without answering? Pressing Enter counts as No, and so does running the install command without an interactive terminal (for example, from an automation tool). Run it from a terminal and answer y, or uninstall first:

sudo /opt/applicationsmanager/monagent/bin/uninstall

↑ Back to error lookup

Step 3 of 5 · Connectivity check failed

Error: Cannot reach Applications Manager at <host>:<port>. Check the host name and port, and make sure a firewall is not blocking the connection.

Cause: One of these:

  • The host name can’t be resolved from the target server.
  • A firewall blocks the port.
  • The address in the install command is wrong.

Fix:

1. Test the connection from the target server:

Windows
Linux
Windows
Test-NetConnection <host> -Port <port>

The port is reachable if the output shows TcpTestSucceeded : True.

Linux
timeout 5 bash -c "</dev/tcp/<host>/<port>" && echo open || echo closed

The port is reachable if the output is open.

2. Fix what the test shows:

  • The host name doesn’t resolve: change Host to an FQDN or IP under Agent Bundle & Capabilities → Applications Manager address, then copy the new install command.
  • The port is not reachable: allow it in every firewall between the two servers.

↑ Back to error lookup

Reinstall blocked: existing agent not removed (Linux)

This appears only when you answered y in Step 2.

Error:

  • Uninstall failed. See <log>
  • Uninstall did not remove the existing FSO agent. See <log>

Fix:

  1. Open fso_agent_register.log and check the Uninstall: section.
  2. Run the uninstaller manually and fix any error it reports:
    sudo /opt/applicationsmanager/monagent/bin/uninstall
  3. Confirm that /opt/applicationsmanager/monagent/bin/uninstall no longer exists, then run the install command again.

↑ Back to error lookup

Step 4 of 5 · Installer download failed

Windows
Linux
Windows

Error: Download failed from <url>: <reason>

Reason containsWhat to do
(404) Not FoundUpload the latest FSO Agent bundle under Agent Bundle & Capabilities and retry.
Unable to connect, connection was closed, SSL/TLS secure channelAllow HTTPS downloads from Applications Manager (check the proxy and firewall), and make sure TLS 1.2 is enabled.

Error: Installer not found at <path> after download.

Fix: Make sure the current folder is writable and that antivirus isn’t removing the downloaded .msi file.

Check the installer URL manually: from the target server, open https://<host>:<port>/resources/FSO/latest/server/windows/installer/ApplicationsManager_Windows_Installer.msi in a browser or with Invoke-WebRequest. If it doesn’t download, the problem is the network path or the uploaded bundle, not the install command.

Linux

Error: Download failed (wget exit code <n>). See <log> (find the log)

wget exit codeMeaningWhat to do
127wget is not installedInstall it (yum install wget or apt-get install wget) and retry.
4Network failureCheck proxy and firewall rules for HTTPS between the two servers, and make sure TLS 1.2 is enabled.
8Applications Manager returned an error, usually 404 Not FoundUpload the latest FSO Agent bundle under Agent Bundle & Capabilities and retry.

For any other code, check the Download: section of the log.

Error: Downloaded installer is empty: <url>

Fix: The installer file on Applications Manager is empty or incomplete. Upload the FSO Agent bundle again and retry.

Check the installer URL manually: from the target server, open https://<host>:<port>/resources/FSO/latest/server/linux/installer/ApplicationsManagerFullStackAgent_LinuxIns.sh in a browser or with wget. If it doesn’t download, the problem is the network path or the uploaded bundle, not the install command.

↑ Back to error lookup

Step 5 of 5 · Installation failed

Windows
Linux
Windows

Error: Installation failed (msiexec exit code <n>). See <log> (find the log)

Exit codeMeaningWhat to do
1603General install errorIn the log, search for Return value 3 and read the lines just above it. The cause is often permissions or antivirus.
1618Another installation is in progressWait for it to finish, or restart the server, then retry.
1625Blocked by system policyContact your system administrator.
Info
Exit code 3010 is not an error. The agent is installed, and you’ll see Restart this machine to complete the setup. Restart the server when convenient.
Linux

Error: Installation failed (installer exit code <n>). See <log> (find the log)

Fix: Check the Install: section of the log for the reason.

Error: Installer finished, but no FSO agent was found at /opt/applicationsmanager/monagent/bin/monagent. See <log> (find the log)

Cause: The installer can finish without reporting an error even when nothing was installed. Check the Install: section of the log. Common causes:

  • The agent files couldn’t be downloaded from Applications Manager. Check the Step 4 items and re-upload the bundle if needed.
  • The license key was rejected. Copy a fresh install command and retry.
  • The server isn’t 64-bit x86. Run uname -m; the output must be x86_64.

↑ Back to error lookup

Status update warning (no action needed)

Message: WARNING: Could not send '<stage>' status to AppManager (…)

Info
Installation continues normally. The command only couldn’t update its live progress on the FSO Agent page.
  • On Linux, (server unreachable) can also mean curl isn’t installed.
  • If the FSO Agent page shows the wrong status, check View Agents for the agent’s actual state.

↑ Back to error lookup

Still failing? Collect diagnostic logs and contact support.

Collect diagnostic logs

fso_agent_register.log is kept when installation fails and deleted when it succeeds. Its full path is shown in the install script’s output (register.ps1 on Windows, register.sh on Linux), in the support line at the end of a failed run.

Windows
Linux
Windows
  • When it’s created: Only at Step 5 (msiexec verbose log). If the failure is earlier, use the on-screen message.
  • What it contains: The msiexec install log.
  • Where to find it: Use the path shown in the support line of the register.ps1 output.
Linux
  • When it’s created: At the start of every run.
  • What it contains: Output of the download, uninstall and install, in sections named Download:, Uninstall: and Install:.
  • Where to find it: Use the path shown in the support line of the register.sh output.

Still need help? Contact support

Email appmanager-support@manageengine.com or submit a ticket with:

  • the full console output of the install command
  • fso_agent_register.log, if it exists, from the path shown in the install script’s output
  • the target server’s OS and version, and your Applications Manager build number
How to capture the console output
  • Windows: Before running the install command, run Start-Transcript -Path C:\Temp\fso_install_console.txt. When it finishes, run Stop-Transcript and attach the file.
  • Linux: Select all the text in the terminal, from the install command you ran to the last line, and paste it into your email or ticket.