Agent Installation

There are many methods to install the Morpheus Agent on supported targets. All Agent installation methods are executing a script on the target that calls back to the Morpheus appliance over port 443.

Important

All Agent installation methods require the Target (VM or Host) to resolve and reach the appliance URL over port 443. In addition to the main Appliance URL (in Administration > Settings), additional Appliance URLs can be set per cloud in the Advanced Options section of the Create/Edit Cloud modal. When this field is populated, it will override the main Appliance URL for anything provisioned into that Cloud.

Basic Installation Steps

  1. An Agent installation method is used to get the install script onto the target VM or Host
  2. The Agent installation script is executed on the target VM or Host, installing the Agent and all dependencies
  3. The Agent is started and makes a websocket connection to the configured Appliance URL over port 443 using the target VM or Host API key

It is important to note these are three separate steps with varying requirements. The first requires a path to get the script on the target. The second requires successful execution of the Agent installation script. The third requires a successful websocket connection. Requirements for the successful execution of each step are covered in the sections below.

Tip

The Morpheus UI current log, located at /var/log/morpheus/morpheus-ui/current, is very helpful when troubleshooting Agent installations.

Agent Install Modes

Agent Installation Method is determined by:

  • The AGENT INSTALL MODE setting on target Cloud: - SSH / WinRM / Guest Execution - Cloud Init / Unattend (when available)
  • Platform / OS type on Virtual Image or target (VM or Host)
  • Virtual Image configuration
  • RPC Mode setting (VMware Clouds only)

Agent Installation Methods

The Morpheus Agent can be installed with a variety of automated methods. It is important to note these methods simply get the Agent install script to the target. Successful execution of the Agent install script is not directly related to the Agent install method.

SSH

Morpheus makes an SSH connection to the VM or Host, CURLs, and executes the Agent install script:

curl -k -s "https://${applianceUrl}/api/server-script/agentInstall?apiKey=${apiKey}" | bash

WinRM
Morpheus makes a WinRM connection to the VM or Host and executes the Agent install script
VMware Tools
Morpheus executes agentInstall.sh or agentInstall.ps1 via VMware Tools Guest Execution
Cloud-Init
Morpheus executes agentInstall.sh via cloud-init runcmd
Cloudbase-Init
Morpheus adds WindowsAgentCloudInitInstallScript to CloudbaseInitUserData
Windows Unattend
Morpheus adds getWindowsAgentDownloadScript to unattend.xml (RunSynchronousCommand)
Manual
User executes agentInstall.sh or agentInstall.ps1 manually on the VM or Host. These scripts can be obtained on the VM or Host detail page via Actions > Download Agent Script

SSH

Process

Morpheus makes an SSH connection to the VM or Host, CURLs, and executes the Agent install script:

curl -k -s "https://${applianceUrl}/api/server-script/agentInstall?apiKey=${apiKey}" | bash

Requirements

  • Port 22 is open for Linux images, and SSH is enabled
  • Credentials have been entered on the image if using a custom or synced image. Credentials can be entered on images in the Provisioning > Virtual Images section

WinRM

Process

Morpheus makes a WinRM connection to the VM or Host and executes the Agent install script

Requirements

  • Port 5985 must be open and winRM enabled for Windows images
  • Credentials have been entered on the image if using a custom or synced image. Credentials can be entered on images in the Provisioning > Virtual Images section
  • Administrator User (SID 500) is required for Windows Agent install

VMware Tools

Process

Morpheus executes agentInstall.sh or agentInstall.ps1 via VMware Tools Guest Execution

Requirements

  • VMware Tools is installed on the template(s)
  • Credentials have been entered on the Image if using an uploaded or synced image when Cloud-init, Guest Customizations, or Sysprep for Windows are not used. Credentials can be entered on Images in the Provisioning > Virtual Images section
  • Administrator User (SID 500) is required for Windows Agent install.

Cloud-Init

Process

Morpheus executes agentInstall.sh via Cloud-Init runcmd

Requirements

  • Cloud-Init is installed on Virtual Image
  • “IS CLOUD INIT ENABLED?” is checked (true) on the Morpheus Virtual Image record
  • Cloud-Init User is configured in the Admin > Provisioning section

Cloudbase-init

Process

Morpheus adds WindowsAgentCloudInitInstallScript to CloudbaseInitUserData

Requirements

  • Cloudbase-Init is installed on the Virtual Image
  • “IS CLOUD INIT ENABLED?” is checked (true) on the Morpheus Virtual Image record
  • Windows Administrator password defined in the Administration -> Provisioning section

Windows Unattend

Process

Morpheus adds getWindowsAgentDownloadScript to unattend.xml (RunSynchronousCommand)

Requirements

VMware
  • Windows Administrator password defined in the Administration > Provisioning section OR Administrator User (SID 500) and valid Windows password are defined on the Morpheus Virtual Image record
  • “FORCE GUEST CUSTOMIZATION?” is checked (true) on the Morpheus Virtual Image record when using DHCP
  • “IS CLOUD INIT ENABLED?” is unchecked (false) on the Morpheus Virtual Image record
Nutainx/SCVMM/Openstack
  • Windows Administrator password defined in the Administration > Provisioning section OR Administrator User (SID 500) and valid Windows password are defined on the Morpheus Virtual Image record
  • “ENABLED SYSPREP?” is checked (true) on the Morpheus Virtual Image record
  • “IS CLOUD INIT ENABLED?” is unchecked (false) on the Morpheus Virtual Image record

Manual

Process

  • From the VM or Host record page (/infrastructure/servers/${id}) run ACTIONS -> Download Agent Script
  • This is will generate an Agent install script based off the target OS and platform, Appliance URL, and API key
  • Manually execute the downloaded script on the Target VM or Host

Agent Install Requirements

Agent Installation Requirements
Requirement Agent Installation Method
SSH WINRM VMWARE TOOLS CLOUD-INIT CLOUDBASE-INIT UNATTEND MANUAL
Target (vm/host) to resolve and reach Appliance URL over 443 YES YES YES YES YES YES YES
Target (vm/host) to resolve and reach Appliance URL over 80 Ubuntu 14.04 Only   Ubuntu 14.04 Only Ubuntu 14.04 Only     Ubuntu 14.04 Only
Websockets enabled when using load balancer YES YES YES YES YES YES YES
Access to Target VM/Host on port 22 YES NO NO NO NO NO NO
Access to Target VM/Host on port 5985 NO YES NO NO NO NO NO
Vmware Tools installed and flagged on Virtual Image NO NO YES NO NO YES NO
Syspreped Image and Sysprep Enabled flagged on Virtual Image (Nutanix, Openstack, SCVMM) NO NO NO NO NO YES NO
Force Guest Customizaitons flagged on Virtual Image NO NO DHCP NO NO DHCP NO
Cloud-Init installed and flagged on Virtual Image NO NO NO YES YES NO NO
Global Cloud-Init user populated in /admin/provisioning NO NO NO YES NO NO NO
Windows Administrator Password populated in /admin/provisioning NO NO NO NO YES YES NO
Access to configured YUM or APT repos NO but will cause delay in Agent Install N/A NO but will cause delay in Agent Install NO but will cause delay in Agent Install N/A N/A NO but will cause delay in Agent Install
.net >=4.5.2 (Windows, Morpheus >= 4.1.2) N/A YES YES N/A YES YES YES
User with Sudo Access set on Virtual Image (Greenfield) YES N/A YES NO N/A N/A N/A
Adminsitrator User (SID 500) set on Virtual Image (Greenfield) N/A YES YES N/A NO N/A N/A
User with Sudo Access set on VM/Host Record (Brownfield) YES N/A YES N/A N/A N/A N/A
Adminsitrator User (SID 500) set on VM/Host Record (Brownfield) N/A YES YES N/A N/A N/A N/A

When provisioning an Instance, there are network and configuration requirements to consider in order to successfully install the Morpheus Agent. Typically, when a VM Instance is still in the provisioning phase long after the VM is up, the Instance is unable to reach Morpheus. Depending on the Agent install mode, it could also mean Morpheus is unable to reach the Instance.

The most common reason an Agent install fails is the provisioned Instance cannot reach the Morpheus Appliance via the Appliance URL set in Administration > Settings over port 443. When an Instance is provisioned from Morpheus, it must be able to reach the Morpheus appliance via the Appliance URL or the Agent will not be installed.

../../_images/agent-7c9a2.png

In addition to the main Appliance URL in Administration > Settings, additional Appliance URLs can be set per Cloud in the Advanced Options section of the Cloud configuration modal when creating or editing a Cloud. When this field is populated, it will override the main Appliance URL for anything provisioned into that Cloud.

Tip

The Morpheus UI current log, located at /var/log/morpheus/morpheus-ui/current, is very helpful when troubleshooting Agent installations.

Morpheus Agent installation supports multiple install methods.

  • SSH/WinRM
  • VM Tools
  • Cloud-Init & Cloudbase-Init
  • Windows Unattended
  • Manual

For All Agent Install Methods

When an Instance is provisioned and the Agent does not install, verify the following for any Agent install mode:

  • The Morpheus Appliance URL (Administration > Settings) is both reachable and resolvable from the provisioned node
  • The Appliance URL begins with https://, not http://

Note

Be sure to use https:// even when using an IP address for the appliance.

  • Inbound connectivity access to the Morpheus appliance from provisioned VMs and container hosts on port 443 (needed for Agent communication)
  • Private (non-Morpheus provided) VM images and templates must have their credentials stored. These can be entered or edited in the Provisioning > Virtual Images section by clicking the Actions dropdown on an imaged detail page and selecting Edit.

Note

Administrator user is required for Windows Agent install.

  • The Instance does not have an IP address assigned. For scenarios without a DHCP server, static IP information must be entered by selecting the Network Type: Static in the Advanced Options section during provisioning. IP Pools can also be created in the Infrastructure > Networks > IP Pools section and added to Cloud network sections for IPAM
  • DNS is not configured and the node cannot resolve the appliance. If DNS cannot be configured, the IP address of the Morpheus appliance can be used as the main or Cloud appliance

SSH

  • Port 22 is open for Linux images, and SSH is enabled
  • Credentials set on the image if using a custom or synced image. Credentials can be entered on images in the Provisioning > Virtual Images section

WinRM

  • Port 5985 must be open and WinRM enabled for Windows images
  • Credentials have been entered on the image if using a custom or synced image. Credentials can be entered on images in the Provisioning > Virtual Images section

Note

Administrator user is required for Windows Agent install.

VMware Tools (vmtools)

  • VMware Tools is installed on the template(s)
  • Credentials have been entered on the image if using custom or synced image. Credentials can be entered on images in the Provisioning > Virtual Images section
  • Sudo priveleges required for Linux
  • Administrator User required for Windows (SID 500)

Cloud-Init

  • Cloud-Init settings configured in Administration > Provisioning section
  • Cloud-Init installed on Virtual Image
  • Cloud-Init enabled on Virtual Image config

Cloudbase-Init

  • Windows Administrator Password defined in Administration > Provisioning section
  • Cloudbase-Init installed on Virtual Image
  • Cloud-Init enabled on Virtual Image config

Note

Unattend Agent Installation and customizations are recommended over Cloudbase-Init

Windows Unattended

  • Windows Administrator Password defined in Administration > Provisioning section
  • VMware: Force Guest Customizations set to forced on Virtual Image config when using DHCP (Static Assignment will already force Guest Customizations)
  • Nutanix & SCVMM: Virtual Image is sysprepped and shutdown, Sysprep Enabled flagged on Virtual Image config

Manual

  • Agent Install scripts can be downloaded from Morpheus and ran manually on the target host when required via Actions -> Download Agent Script on the managed Resource. Please note the script will be unique per managed Resource.

In some situations, it may necessary to restart the Morpheus Agent on the host to re-sync communication from the Agent to the Morpheus appliance.

Linux

On the target host, run sudo morpheus-node-ctl restart morphd and the Morpheus agent will restart. morpheus-node-ctl status will also show the agent status.

Windows

The Morpheus Windows Agent service can be restarted in Administrative Tools -> Services.

Tip

The Morpheus Remote Console is not dependent on Agent communication and can be used to install or restart the Morpheus agent on an Instance.

You can use the following to uninstall the linux agent:

sudo rm /etc/apt/sources.list.d/morpheus.list
sudo morpheus-node-ctl kill
sudo apt-get -y purge morpheus-node
sudo apt-get -y purge morpheus-vm-node
sudo systemctl stop morpheus-node-runsvdir
sudo rm -f /etc/systemd/system/morpheus-node-runsvdir.service
sudo systemctl daemon-reload
sudo rm -rf /var/run/morpheus-node
sudo rm -rf /opt/morpheus-node
sudo rm -rf /etc/morpheus/
sudo rm -rf /var/log/morpheus-node
sudo pkill runsv
sudo pkill runsvdir
sudo pkill morphd
sudo usermod -l morpheus-old morpheus-node

For custom CentOS 7 images we highly recommend setting up Cloud-Init and fixing the network device names. More information for custom CentOS images can be found in the CentOS 7 image guide.