Symptoms<\/h3>\n\n\n\n
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:<\/p>\n\n\n\n
- \n
- Account provisioning\/takeover.<\/li>\n\n\n\n
- Password changes.<\/li>\n\n\n\n
- User details or privilege level.<\/li>\n\n\n\n
- MFA Settings.<\/li>\n<\/ul>\n\n\n\n
Cause<\/h3>\n\n\n\n
- \n
- Time is not synchronized.<\/li>\n\n\n\n
- The agent is not up to date.<\/li>\n\n\n\n
- The agent is not running.<\/li>\n\n\n\n
- The device is inactive (red) in the console.<\/li>\n\n\n\n
- The user is not active (green) in the console.<\/li>\n\n\n\n
- The changes are not valid.<\/li>\n\n\n\n
- Usernames are not case matched.<\/li>\n\n\n\n
- MFA Tokens have not been validated.<\/li>\n\n\n\n
- Other management software reverts changes to the device.<\/li>\n<\/ul>\n\n\n\n
Resolution<\/h3>\n\n\n\n
- \n
- Verify the device time is synchronized to ntp.org<\/a> or similar reliable time source.<\/li>\n\n\n\n
- 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<\/a>, and reinstall.<\/li>\n\n\n\n
- Make sure the agent is running. If so, restart it. See Stop, Start, or Restart the Agent<\/a>.<\/li>\n\n\n\n
- Verify the agent is active (green) in the console. See Agent does not register or a device stops reporting<\/a>.<\/li>\n\n\n\n
- If the user status is not active (green), then hover over the status indicator to obtain the cause and take the necessary corrective action.<\/li>\n\n\n\n
- 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<\/a>.<\/li>\n\n\n\n
- Usernames are case sensitive, even on Windows<\/strong>. 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<\/a> to verify existing device usernames.<\/li>\n\n\n\n
- Devices will not prompt for MFA until the user has confirmed their TOTP token, see Enable TOTP MFA for Devices<\/a>.<\/li>\n\n\n\n
- 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<\/a> for a detailed list of files the JumpCloud agent manages.<\/li>\n<\/ol>\n\n\n\n
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>.<\/p>\n\n\n\n
- \n
- A description of specifically what fails to synchronize, including affected username(s)<\/li>\n\n\n\n
- The device ID(s)<\/li>\n\n\n\n
- OS Version\/build number<\/li>\n\n\n\n
- Agent version, found in\n
- \n
- MAC | LINUX<\/strong>: \/opt\/jc\/version.txt<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Program Files\\JumpCloud\\plugins\\contrib\\version.txt<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- The agent log, found in\n
- \n
- MAC | LINUX<\/strong>: \/var\/log\/jcagent.log<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Windows\\Temp\\jcagent.log<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Your timezone, and the time when the change was made in the Admin Console<\/li>\n<\/ul>\n<\/div><\/div><\/div>\n\n\n\n
<\/p>\n\n\n\n
Agent does not register or a device stops reporting.<\/a>\nSymptoms<\/h3>\n\n\n\n
- \n
- A newly installed agent does not show up as a new device record in the console.<\/li>\n\n\n\n
- A newly installed agent shows up in the console, then goes inactive (red) within 10 minutes.<\/li>\n\n\n\n
- A previously reporting device has gone inactive (red) in the console.<\/li>\n<\/ul>\n\n\n\n
Cause<\/h3>\n\n\n\n
- \n
- The service is not running\/not running properly\/won’t start.<\/li>\n\n\n\n
- There is a network issue.<\/li>\n\n\n\n
- Devices are deployed from an image<\/a> that has not been configured correctly with a preinstalled agent.<\/li>\n<\/ul>\n\n\n\n
Resolution<\/h3>\n\n\n\n
- \n
- Verify the device complies with Agent Compatibility, System Requirements, and Impacts<\/a>.<\/li>\n\n\n\n
- 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. <\/li>\n<\/ul>\n\n\n\n
Service issues:<\/h4>\n\n\n\n
- \n
- 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<\/a>.<\/li>\n\n\n\n
- If the agent does not start or stay running, follow the Agent does not start or synchronize changes<\/a>.<\/li>\n<\/ol>\n\n\n\n
Network Issues:<\/h4>\n\n\n\n
- \n
- Verify both the device and network comply with Agent and Port Requirements<\/a>.<\/li>\n<\/ol>\n\n\n\n
If after verifying all prerequisites and the service status, gather the following information and submit a Support Request<\/a>.<\/p>\n\n\n\n
- \n
- OS Version\/build number<\/li>\n\n\n\n
- Agent version, found in\n
- \n
- MAC | LINUX:<\/strong> \/opt\/jc\/version.txt<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Program Files\\JumpCloud\\Plugins\\Contrib\\version.txt<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- The agent log, found in\n
- \n
- MAC | LINUX:<\/strong> \/var\/log\/jcagent.log<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Windows\\Temp\\jcagent.log<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/div><\/div><\/div>\n\n\n\n
<\/p>\n\n\n\n
Agent fails to register due to ICMP packet filtering.<\/a>\nWhen 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.<\/p>\n<\/div><\/div><\/div>\n\n\n\n
<\/p>\n\n\n\n
Agent stops checking in and creates a duplicate object in JumpCloud.<\/a>\nSymptoms<\/h3>\n\n\n\n
A device has been offline for more than 30 days during the certificate renewal period and it creates a new device entry after reconnecting.<\/p>\n\n\n\n
Resolution<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
You can verify this by inspecting the expiration date of the agent certificate directly on the device with the following commands:<\/p>\n\n\n\n
macOS & Linux<\/h4>\n\n\n\n
\nsudo openssl x509 -in \/opt\/jc\/client.crt -noout -text | grep -i not<\/p>\n<\/div><\/div>\n\n\n\n
Windows PowerShell<\/h4>\n\n\n\n
\n$path = ‘c:\\Program Files\\JumpCloud\\Plugins\\Contrib\\client.crt’ $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($path) $cert.NotAfter<\/p>\n<\/div><\/div>\n\n\n\n
Interpreting the Results<\/h4>\n\n\n\n
Command Line<\/strong>:<\/p>\n\n\n\n
Inspect the results of the command and look at the certificate expiration date (the Not After<\/strong> 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.
![\"\"](\"https:\/\/jumpcloud.com\/wp-content\/uploads\/2024\/09\/macos_agent_certificate_expiration.png\")
<\/p>\n\n\n\nWhen 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.<\/p>\n\n\n\n
JumpCloud Agent Log<\/strong>:<\/p>\n\n\n\n
The JumpCloud Agent also details this process within the agent log. The following example details these events:<\/p>\n\n\n\n
\ntime=2023-04-03 15:05:10.42-06:00 PID=93988 level=info msg=REGISTRATION: Certificates have expired, resealing as a new system in JumpCloud
time=2023-04-03 15:05:10.42-06:00 PID=93988 level=info msg=REGISTRATION: No existing valid certificate found, initializing it
time=2023-04-03 15:05:10.42-06:00 PID=93988 level=info msg=REGISTRATION: Creating client certificates <\/p>\n<\/div><\/div>\n\n\n\n![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/tip-icon.png\")
<\/p><\/div>Tip:<\/strong> \nSearch for resealing<\/kbd> when exploring agent logs. This generally confirms it was a certificate renewal miss that caused the new device object in JumpCloud.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
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.\u00a0<\/p>\n<\/div><\/div><\/div>\n\n\n\n
<\/p>\n\n\n\n
Agent behavior on devices with multiple OSes (dual booting).<\/a>\nAlthough JumpCloud doesn\u2019t recommend or officially support dual boot\/multi-boot devices, we understand this might be a necessity for your org.<\/p>\n\n\n\n
![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/warning-icon.png\")
<\/p><\/div>Warning:<\/strong> \nConfiguring your devices in this manner can cause discrepancies within the Admin Portal, potentially leading to various errors. JumpCloud does not guarantee full functionality with dual boot\/multi-boot devices.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
Overview of agent configuration on a dual boot device:<\/p>\n\n\n\n
- \n
- You completely understand the risks this involves as mentioned in the legend above.<\/li>\n\n\n\n
- JumpCloud Agent Compatibility, System Requirements, and Impacts<\/a> are still the same for this configuration, please choose a compatible OS to avoid further issues.<\/li>\n\n\n\n
- Install the JumpCloud Agent on both operating systems using the respective installer for the OS you are using.<\/li>\n\n\n\n
- 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.<\/li>\n<\/ol>\n<\/div><\/div><\/div>\n\n\n\n
Linux<\/h2>\n\n\n\n
- WINDOWS:<\/strong> C:\\Windows\\Temp\\jcagent.log<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/div><\/div><\/div>\n\n\n\n
- WINDOWS:<\/strong> C:\\Program Files\\JumpCloud\\Plugins\\Contrib\\version.txt<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- MAC | LINUX:<\/strong> \/opt\/jc\/version.txt<\/li>\n\n\n\n
- If the agent does not start or stay running, follow the Agent does not start or synchronize changes<\/a>.<\/li>\n<\/ol>\n\n\n\n
- 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. <\/li>\n<\/ul>\n\n\n\n
- Verify the device complies with Agent Compatibility, System Requirements, and Impacts<\/a>.<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Windows\\Temp\\jcagent.log<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- WINDOWS:<\/strong> C:\\Program Files\\JumpCloud\\plugins\\contrib\\version.txt<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- MAC | LINUX<\/strong>: \/opt\/jc\/version.txt<\/li>\n\n\n\n
- 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<\/a>, and reinstall.<\/li>\n\n\n\n
- Verify the device time is synchronized to ntp.org<\/a> or similar reliable time source.<\/li>\n\n\n\n