Skip to main content

Troubleshoot: JumpCloud Agent

This article outlines common issues and resolutions that occur when installing or configuring the JumpCloud Agent.

All OSes​

Device or Agent Has Been Offline for an Extended Period

Devices managed by JumpCloud that remain offline for an extended period can face challenges such as expired certificates, outdated policies, and delayed commands.

note

The device’s service enrollment certificate has a lifespan of one year, and the agent will attempt to renew it beginning 30 days prior to the anniversary date.

Before bringing an offline device back online, check the device health, back up important data, and ensure network access.

Follow these steps to bring an offline device back online and ensure it updates properly:

  • Connect to the Internet: Ensure the device is connected to a stable network (WiFi or Ethernet).
  • The agent should automatically start when the device boots up and perform its initial checks.
  • Verify Agent Status. See Stop, Start, or Restart the JumpCloud Agent for more details.
  • Check the certificate status:
    • macOS & Linux:
      sudo openssl x509 -in /opt/jc/client.crt -noout -text | grep -i not
    • Windows:
      $path = 'c:\Program Files\JumpCloud\Plugins\Contrib\client.crt' $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($path) $cert.NotAfter
  • Update Device Policies
    • Once the device is online, policies and configurations should automatically apply. You can verify this by checking the device status in the JumpCloud Admin Portal. If the policies do not update on the device, you can try reapplying them by unbinding and then rebinding the device to the desired policies.
note

On macOS, if the agent has run into an error condition preventing it from starting correctly (e.g. no longer has full disk access), then LaunchD may disable the service to prevent it from cycling. In these cases, reinstalling the agent over the top of the existing configuration will reset the service and should allow the agent to start.

Linux​

Error: Your OS/architecture [ … ] is not supported.

Symptoms​

Attempting to install the JumpCloud agent fails on a Linux system and logs an error noting that Your OS/architecture [ ] is not supported.

Cause​

On Linux, JumpCloud uses both the architecture of your kernel (uname -m) as well as the contents of your /etc/issue or /etc/os-release file to determine the OS type of your servers. If the contents do not match JumpCloud current set of supported operating system types, you will receive this error.

See Agent Compatibility, System Requirements, and Impacts for supported Linux versions.

Resolution​

Returning the /etc/issue or /etc/os-release file to its original contents can often correct this issue.

(Unsupported) Workaround​

Install the agent on the unsupported distribution at your own risk.

warning

Installing the JumpCloud agent on an unsupported version does not guarantee functionality.

You will need to edit the etc/issue, etc/os release, and/or etc/system-release files to match those of a JumpCloud-supported distribution before installing the agent.

HTTP 408 Errors While Installing the JumpCloud Agent on Amazon EC2

Symptoms​

After installing the JumpCloud Agent using the curl command to a Linux Amazon EC2 hosted system, the agent will fail to start and will report the following within /var/log/jcagent.log:

2016/02/02 19:11:04 [9762] Initial certificate checks failed, err='Could not seal the agent to JumpCloud, err='Could not initialize client certificate, err='Could not sign the certificate, err='CSR request failed with status=408, body='<html><body><h1>408 Request Time-out</h1>

Your browser didn't send a complete request in time.

Resolution​

The problem involves improper packet splitting. When Amazon identifies an internal instance, it sets the MTU to 9001 (jumbo frames). However, outbound traffic is still set to an MTU of 1500. The default version of curl was not properly reading the correct MTU, and was thus attempting to send a 9001 size frame, but only the first 1500chars were actually copied.

On the Linux instance run:

ifconfig <interface> mtu 1500 up

You may also make a permanent change in /etc/sysconfig/network-scripts/ifcfg-&lt;interface&gt; by adding MTU=1500

macOS​

Migration Assistant Interference with the JumpCloud Agent and MDM Enrollment

Symptoms​

  • After migrating user data from an old Mac to a new Mac using Migration Assistant, the JumpCloud Agent no longer starts or synchronizes.
  • The new device becomes active under the old device records.
  • The new device may show as inactive (red) or behave erratically when performing actions in the Admin Portal.
  • Policies or commands fail to apply to the migrated device.

Cause​

Using Migration Assistant to transfer Applications, Other Files & Folders, or System & Network Settings from a JumpCloud-managed device causes a failed state for the new device in JumpCloud. This is caused by Migration Assistant transferring device agent and MDM settings from the old device to the new device.

Resolution​

You may need to delete the device record from the Admin Portal, uninstall the agent manually, and reinstall or re-enroll the device in MDM.

warning

Use of Migration Assistant is not supported for JumpCloud-managed or MDM enrolled JumpCloud devices. We recommend using a cloud backup solution or manually copying user data to the new device.

If your environment requires using Migration Assistant, proceed at your own risk. Select only the user home directory during the Migration Assistant wizard (as highlighted in the following image). Do not migrate Applications, Other Files & Folders, or System & Network Settings, and ensure these are deselected during the Migration Assistant process.

See Use Apple Migration Assistant with JumpCloud to learn more.

Error: “Agent Not Running” During Installation

Symptoms​

An error message appears during or after the agent installation: Agent is not running.

Cause​

This error typically occurs when installing the agent on a device that previously had it installed, or after restoring data from an old device using a Time Machine backup. Leftover files interfere with the new installation and cause it to fail.

Resolution​

To resolve this error, clear all existing JumpCloud files and profiles from the Mac, then reinstall the agent:

  1. Remove the MDM Profile on the Mac:
    1. Go to System Settings > General > Device Management.
    2. Select the MDM Enrollment Profile, and click Unenroll.
  2. Clear all JumpCloud files by running the macOS cleanup script. See Manually Remove the Agent from an Inactive Device to learn more.
  3. Confirm that no firewall or VPN on the Mac is blocking the JumpCloud agent. See JumpCloud Agent Networking and Port Requirements to learn more.
  4. Restart the Mac to clear any active processes.
  5. Download a new copy of the agent installer file and reinstall the agent.

Was this information helpful?