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

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