Morpheus Agent

The Morpheus Agent is an important and powerful facet of Morpheus as a orchestration tool. Though it is not required (one unique capability of our platform vs. some of the competitors out there), it is recommended for use as it brings with it a lot of insightful benefits. Not only does it provide statistics of the guest operating system and resource utilization, it also brings along with it monitoring and log aggregation capabilities. After an initial brownfield discovery users can decide to convert unmanaged vms to managed. The Morpheus Agent is very lightweight and secure.

Note

The agent is not required by Morpheus to become a managed instance. If you don’t have the agent installed we try to aggregate stats but it can vary based on the cloud and can be limited or inaccurate.

The Morpheus Agent does not open any inbound network ports but rather only opens an outbound connection back to the Morpheus appliance over port 443 (https or wss protocol). This allows for a bidirectional command bus where instructions can be sent to orchestrate a workload without needing access to things like SSH or WinRM. The tool can even be installed at provision time via things like cloud-init, such that the Morpheus appliance itself doesn’t even need direct network access to the VLAN under which the workload resides. By doing this we address many of the network security concerns that come up with regards to the agent while demonstrating its security benefits as well as analytics benefits. We can even use this statistical data at the guest OS level rather than the hypervisor level to provide extremely precise right-sizing recommendations.

Key Agent Features

  • Provides key enhanced statistics (disc usage, CPU usage, network, disc IO)
  • Handles log aggregation
  • Provides a command bus to where Morpheus doesn’t need to get credentials to access a box. Can still run workflows if credentials are changed
  • SSH agent can be disabled and still get access to the box
  • Agent can be installed over Cloud-init, Windows unattend.xml, VMware Tools, SSH, WinRM, Cloudbase-init, or manually.
  • Makes a single connect that’s persistence over HTTPs web socket and runs as a service
  • Health and Monitoring Checks
  • Agent buffers and compresses logs and sends them in chunks to minimize packets
  • Supports syslog forwarding
  • Linux agent can be shrunk and should be less then 0.2% peak
  • Accepts commands, can execute commands, write files, and manipulate firewalls
  • Agent installation is optional for provisioning and converting Discovered resources to managed

Morpheus Agent OS Support

Name Platform Category Bit Count Agent Supported
centOS linux centos 64 1
centOS 6 linux centos 64 1
centOS 6 64-bit linux centos 64 1
centOS 64-bit linux centos 64 1
centOS 7 linux centos 64 1
centOS 7 64-bit linux centos 64 1
debian linux debian 32 1
debian 6 linux debian 32 1
debian 6 64-bit linux debian 64 1
debian 64-bit linux debian 64 1
debian 7 linux debian 32 1
debian 7 64-bit linux debian 64 1
debian 8 linux debian 32 1
debian 8 64-bit linux debian 64 1
debian 9.4 64-bit linux debian 64 1
fedora linux fedora 32 1
fedora 64-bit linux fedora 64 1
mac os osx mac 64 1
oracle enterprise linux oracle 32 1
oracle enterprise 64-bit linux oracle 64 1
oracle linux 64-bit linux oracle 64 1
redhat linux redhat 64 1
redhat 6 linux redhat 64 1
redhat 6 64-bit linux redhat 64 1
redhat 64-bit linux redhat 64 1
redhat 7 linux redhat 64 1
redhat 7 64-bit linux redhat 64 1
ubuntu linux ubuntu 32 1
ubuntu 12 linux ubuntu 32 1
ubuntu 12 64-bit linux ubuntu 64 1
ubuntu 13 linux ubuntu 32 1
ubuntu 13 64-bit linux ubuntu 64 1
ubuntu 14 linux ubuntu 32 1
ubuntu 14 64-bit linux ubuntu 64 1
ubuntu 15 linux ubuntu 32 1
ubuntu 15 64-bit linux ubuntu 64 1
ubuntu 16 linux ubuntu 32 1
ubuntu 16 64-bit linux ubuntu 64 1
ubuntu 18.04 linux ubuntu 32 1
ubuntu 18.04 64-bit linux ubuntu 64 1
ubuntu 64-bit linux ubuntu 64 1
windows 10 windows windows 32 1
windows 10 64-bit windows windows 64 1
windows 7 windows windows 32 1
windows 7 64-bit windows windows 64 1
windows 8 64-bit windows windows 64 1
windows server 2008 windows windows 64 1
windows server 2008 R2 windows windows 64 1
windows server 2012 windows windows 64 1
windows server 2016 windows windows 64 1
windows server 2019 windows windows 64 1

Important

Amazon Linux is not supported by the Morpheus Agent

Agent Install

When provisioning an instance, there are some network and configuration requirements 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 , or depending on agent install mode, 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 Admin -> Settings over both 443 and 80. 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 Admin -> Settings, additional appliance_urls can be set per cloud in the Advanced options of the cloud configuration pane when creating or editing a cloud. When this field is populated, it will override the main appliance url for anything provisioned into that cloud.

Once installed, Morpheus agent is located in /opt/morpheus-node on a Linux box. In Windows, it’s located in \Program Files (x86)\Morpheus\Morpheus Windows Agent.

Tip

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

Agent Install Methods

../../_images/agent_ssh.gif

The Morpheus Agent can be installed with a variety of automated methods:

  • ssh (linux)
  • winRM
  • VMware Tools
  • Cloud-init
  • Cloudbase-init
  • Windows unattend.xml

Agents can also be manually installed.

For All Agent Install modes

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

  • The Morpheus appliance_url (Admin -> Settings) is both reachable and resolvable from the provisioned node.
  • The appliance_url begins with to 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 VM’s and container hosts on port 443 (needed for agent communication)
  • Private (non-morpheus provided) vm images/templates must have their credentials entered. These can be entered/edited in the Provisioning - Virtual Images section but clicking the Actions dropdown of an image 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 section during provisioning. IP Pools can also be created in the Infrastructure -> Networks -> IP Pools section and added to clouds network sections for IPAM.
  • DNS is not configured and the node cannot resolve the appliance. If dns cannot be configure, the ip address of the Morpheus appliance can be used as the main or cloud appliance.

SSH/Winrm

Linux Agent

  • Port 22 is open for Linux images, and ssh is enabled
  • 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.

Windows Agent

  • Port 5985 must be open and winRM enabled for Windows images.
  • 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.

Note

Administrator user is required for Windows agent install.

VMware tools (vmtools) rpc mode

  • VMware tools is installed on the template(s)
  • Credentials have been entered on the Image if using uploaded or synced image when Cloud-init or Guest Customizations or Sysprep for Windows are not used. Credentials can be entered on Images in the Provisioning -> Virtual Images section.

Cloud-Init agent install mode

  • Cloud-Init is configured in Admin -> Provisioning section
  • Provisioned image/blueprint has Cloud-Init (linux) or Cloudbase-Init (windows) installed

Morpheus Agent Install Troubleshooting

When provisioning an instance, there are some network and configuration requirements 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 , or depending on agent install mode, 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 Admin -> Settings over 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 Admin -> Settings, additional appliance_urls can be set per cloud in the Advanced options of the cloud configuration pane 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.

Agent Install Modes

There are 3 Agent install modes:

  • ssh/winrm
  • VMware Tools
  • cloud-init

For All Agent Install modes

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

  • The Morpheus appliance_url (Admin -> Settings) is both reachable and resolvable from the provisioned node.
  • The appliance_url begins with to 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 VM’s and container hosts on port 443 (needed for agent communication)
  • Private (non-morpheus provided) vm images/templates must have their credentials entered. These can be entered/edited in the Provisioning - Virtual Images section but clicking the Actions dropdown of an image 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 section during provisioning. IP Pools can also be created in the Infrastructure -> Networks -> IP Pools section and added to clouds network sections for IPAM.
  • DNS is not configured and the node cannot resolve the appliance. If dns cannot be configure, the ip address of the Morpheus appliance can be used as the main or cloud appliance.

SSH/Winrm

  • Port 22 is open for Linux images, and ssh is enabled
  • 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.
  • Port 5985 must be open and winRM enabled for Windows images.
  • 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.

Note

Administrator user is required for Windows agent install.

VMware tools (vmtools) rpc mode

  • 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.

Cloud-Init agent install mode

  • Cloud-Init is configured in Admin -> Provisioning section
  • Provisioned image/blueprint has Cloud-Init (linux) or Cloudbase-Init (windows) installed

Manually Installing a Morpheus Agent

While it should not be necessary to manually install an agent if the requirements are met, it is possible to manually install an agent on an instance. This can also be handy when troubleshooting an agent install.

Linux

  1. In Morpheus , go to the VM’s host detail page in Infrastructure->Hosts->Virtual Machines you will see an API Key that is unique to that host.

  2. As root user, run: (replacing ${} with the relevant information)

    curl -k -s "${opts.applianceUrl}/api/server-script/agentInstall?apiKey=${opts.apiKey}" | bash
    
  3. This will pull the Morpheus Agent install script from the Morpheus appliance and run it.

  4. Once the agent is installed, run morpheus-node-ctl reconfigure to complete the manual process.

Windows

  • The windows agent setup can be downloaded at https://[morpheus-applaince-url]/msi/morpheus-agent/MorpheusAgentSetup.msi
  • On the Morpheus appliance package the windows agent is located at /var/opt/morpheus/package-repos/msi/morpheus-agent
  • WinRM, VMware Tools, or Cloudbase-Init can be used to install the agent from the Morpheus appliance
  • The initial windows installer is MorpheusAgentSetup.msi
  • Once the Windows agent is downloaded and installed with Morpheus AgentSetup.msi the agent is located and runs from /Program Files x86/morpheus/morpheus Windows Agent
  • Logs can be viewed in the Event Viewer under Applications and Services Logs -> Morpheus Windows Agent
  1. Replace the values for $apiKey and $applianceUrl in the script below.

  2. Execute this script on the Windows box in Powershell.

    $apiKey = "add VM apiKey here"
    $applianceUrl = "https://your_appliance_url.com/"
    
    $client = New-Object System.Net.WebClient
    $client.DownloadFile($applianceUrl + "/msi/morpheus-agent/MorpheusAgentSetup.msi", "C:\Program Files (x86)\Common Files\MorpheusAgentSetup.msi")
    Start-Sleep -Seconds 10
    cd ${env:commonprogramfiles(x86)}
    $serviceName = "Morpheus Windows Agent"
    if(Get-Service $serviceName -ErrorAction SilentlyContinue) {
    Stop-Service -displayname $serviceName -ErrorAction SilentlyContinue
    Stop-Process -Force -processname Morpheus* -ErrorAction SilentlyContinue
    Stop-Process -Force -processname Morpheus* -ErrorAction SilentlyContinue
    Start-Sleep -s 5
    $serviceId = (get-wmiobject Win32_Product -Filter "Name = 'Morpheus Windows Agent'" | Format-Wide -Property IdentifyingNumber | Out-String).Trim()
    cmd.exe /c "msiexec /x $serviceId /q"
    }
    [Console]::Out.Flush()
    [gc]::collect()
    try {
    Write-VolumeCache C
    }
    Catch {
    }
    $MSIArguments= @(
    "/i"
    "MorpheusAgentSetup.msi"
    "/qn"
    "/norestart"
    "/l*v"
    "morpheus_install.log"
    "apiKey=$apiKey"
    "host=$applianceUrl"
    "username=`".\LocalSystem`""
    "vmMode=`"true`""
    "logLevel=`"1`""
    )
    $installResults = Start-Process msiexec.exe -Verb runAs -Wait -ArgumentList $MSIArguments
    [Console]::Out.Flush()
    [gc]::collect()
    try {
    Write-VolumeCache C
    }
    Catch {
    }
    start-sleep -s 10
    $attempts = 0
    Do {
    try {
            Get-Service $serviceName -ea silentlycontinue -ErrorVariable err
            if([string]::isNullOrEmpty($err)) {
                    Break
            } else {
                    start-sleep -s 10
                    $attempts++
            }
    }
    Catch {
            start-sleep -s 10
            $attempts++
    }
    }
    While ($attempts -ne 6)
    Set-Service $serviceName -startuptype "automatic"
    $service = Get-WmiObject -Class Win32_Service -Filter "Name='$serviceName'"
    if ($service -And $service.State -ne "Running") {Restart-Service -displayname $serviceName}
    exit $installResults.ExitCode
    
  3. If the agent doesn’t install, logs can be found in the morpheus_install.log file located at C:\Program Files (x86)\Common Files\

Restarting the Morpheus Agent

In some situations is 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.

Uninstall Morpheus Agent

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

centOS/RHEL 7 Images

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.