Troubleshoot: JumpCloud Agent

Symptoms

The agent does not start, starts then stops, or changes made to a device do not synchronize after waiting more than two minutes. Changes can include, but not limited to:

• Account provisioning/takeover.
• Password changes.
• User details or privilege level.
• MFA Settings.

Cause

• Time is not synchronized.
• The agent is not up to date.
• The agent is not running.
• The device is inactive (red) in the console.
• The user is not active (green) in the console.
• The changes are not valid.
• Usernames are not case matched.
• MFA Tokens have not been validated.
• Other management software reverts changes to the device.

Resolution

1. Verify the device time is synchronized to ntp.org or similar reliable time source.
2. If the agent was installed from a saved file or device image, update the agent with the most recent version available. If necessary, delete the device record from the admin console, uninstall the agent manually, and reinstall.
3. Make sure the agent is running. If so, restart it.  See Stop, Start, or Restart the Agent.
4. Verify the agent is active (green) in the console. See Agent does not register or a device stops reporting.
5. If the user status is not active (green), then hover over the status indicator to obtain the cause and take the necessary corrective action.
6. Certain changes are not valid and will cause a notification alert. When this happens, it’s possible the synchronization will partially work, or not work at all. See Understand Alerts.
7. Usernames are case sensitive, even on Windows. A case mismatch between the JumpCloud directory and the local device account will result in a variety of sync issues. See Naming Conventions for Users to verify existing device usernames.
8. Devices will not prompt for MFA until the user has confirmed their TOTP token, see Enable TOTP MFA for Devices.
9. Some configuration software such as Puppet may be configured to manage files that JumpCloud manages. This will cause a conflict. See Agent Compatibility, System Requirements, and Impacts for a detailed list of files the JumpCloud agent manages.

There may be other conditions that cause the agent to fail to either start or synchronize changes. Verify the above resolution steps, then gather the following information and submit a Support Request.

• A description of specifically what fails to synchronize, including affected username(s)
• The device ID(s)
• OS Version/build number
• Agent version, found in
  • MAC | LINUX: /opt/jc/version.txt
  • WINDOWS: C:\Program Files\JumpCloud\plugins\contrib\version.txt
• The agent log, found in
  • MAC | LINUX: /var/log/jcagent.log
  • WINDOWS: C:\Windows\Temp\jcagent.log
• Your timezone, and the time when the change was made in the Admin Console

Symptoms

• A newly installed agent does not show up as a new device record in the console.
• A newly installed agent shows up in the console, then goes inactive (red) within 10 minutes.
• A previously reporting device has gone inactive (red) in the console.

Cause

• The service is not running/not running properly/won’t start.
• There is a network issue.
• Devices are deployed from an image that has not been configured correctly with a preinstalled agent.

Resolution

• Verify the device complies with Agent Compatibility, System Requirements, and Impacts.
• If deploying from an image, DO NOT start the agent after deleting the the specified files. When the agent starts, it recreates the files and also creates a unique device record in your organization. Deploying from an image in this state will result in duplicate device records where only the most recent to check in will show active. 

Service issues:

1. Check that the service is running.  If it is not, start it and verify the service stays running. See Stop, Start, or Restart the Agent.
2. If the agent does not start or stay running, follow the Agent does not start or synchronize changes.

Network Issues:

1. Verify both the device and network comply with Agent and Port Requirements.

If after verifying all prerequisites and the service status, gather the following information and submit a Support Request.

• OS Version/build number
• Agent version, found in
  • MAC | LINUX: /opt/jc/version.txt
  • WINDOWS: C:\Program Files\JumpCloud\Plugins\Contrib\version.txt
• The agent log, found in
  • MAC | LINUX: /var/log/jcagent.log
  • WINDOWS: C:\Windows\Temp\jcagent.log

When ICMP type 3 code 4 (Fragmentation Needed) packets are filtered on your network, you may experience failures of the JumpCloud agent to complete its registration. Enabling this on your network may correct the registration issue. See http://en.wikipedia.org/wiki/Path_MTU_Discovery for more details.

Symptoms

A device has been offline for more than 30 days during the certificate renewal period and it creates a new device entry after reconnecting.

Resolution

The JumpCloud Agent certificate used to authenticate and secure device communications has a one-year lifespan. The agent will renew this certificate during a window beginning 30 days prior to the expiration date.

When a device is offline for more than 30 days overlapping this renewal window, the certificate will no longer be valid when the when the device comes back online. This causes the device object to remain offline in the Admin Portal.

You can verify this by inspecting the expiration date of the agent certificate directly on the device with the following commands:

macOS & Linux

Windows PowerShell

Interpreting the Results

Command Line:

Inspect the results of the command and look at the certificate expiration date (the Not After date). The certificate renewal period would begin 30 days prior to. In this example, June 20, 2023 would be the earliest the certificate renewal date.

When the device comes online next, it will attempt to re-seal to JumpCloud, generating a new client certificate, SystemID, and Device entry in the Admin Portal. The former device object will be abandoned and remain in an offline state.

JumpCloud Agent Log:

The JumpCloud Agent also details this process within the agent log. The following example details these events:

For devices offline more than 30 days that don't create a new device entry upon reconnection, you might need to reinstall the agent. If this fails, you may need to fully uninstall and reinstall the agent. 

Although JumpCloud doesn’t recommend or officially support dual boot/multi-boot devices, we understand this might be a necessity for your org.

Overview of agent configuration on a dual boot device:

1. You completely understand the risks this involves as mentioned in the legend above.
2. JumpCloud Agent Compatibility, System Requirements, and Impacts are still the same for this configuration, please choose a compatible OS to avoid further issues.
3. Install the JumpCloud Agent on both operating systems using the respective installer for the OS you are using.
4. Once installed, there will be two registries in the Admin Portal for the same device but with different operating systems. This is unavoidable, as the underlying hardware information is the same for both, given they are on the same device.

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. 

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.

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 1500 chars were actually copied.

On the Linux instance run:

You may also make a permanent change in /etc/sysconfig/network-scripts/ifcfg-<interface> by adding MTU=1500