Troubleshooting

Admins
Home / Admins / Agent / Troubleshooting

Troubleshooting

This article enumerates methods for Kolide administrators and end-users to try when the Kolide agent isn’t working as expected.

Diagnosing Common Issues

The doctor command is a great way to troubleshoot obvious problems with the Kolide agent before engaging Kolide support. The doctor command is capable of checking for common issues that often prevent the Kolide agent from connecting successfully to the service.

macOS / Linux

To run doctor on Mac and Linux devices, follow these instructions:

  1. Open the Terminal application (macOS Instructions).

  2. Type or copy & paste the following command:

    sudo /usr/local/kolide-k2/bin/launcher doctor

  3. You will be prompted for your computer password. Type it in when prompted and press enter. As a security precaution, your password will not be displayed as you type it into the terminal.

Windows

  1. Access the Power User Menu by right-clicking the Start Menu (the Windows icon).

  2. When the menu appears, select Windows PowerShell (Admin).

  3. When the PowerShell terminal appears, type or copy and paste the following command:

    & "C:\Program Files\Kolide\Launcher-kolide-k2\bin\launcher.exe" doctor | Out-String

Interpreting The Output

Once you’ve successfully run the command, you will see output similar to the following:

✅ Process Report: found 5 kolide processes
Platform: platform: darwin, architecture: arm64
Launcher Version: version 1.1.2
✅ Root directory contents: root directory (/var/kolide-k2/k2device.kolide.com) contains 26 files
❌ Check communication with Kolide: Trouble connecting to: device(k2device.kolide.com), control(k2control.kolide.com)
✅ Logs: debug.json is 2164586 bytes, and was last modified at 2023-10-31 13:38:18.577590971 -0400 EDT
✅ Binary directory contents: binary directory (/usr/local/kolide-k2) contains 2 files
✅ Launchd: state is running
✅ Enrollment Secret: claim for XXXXX
✅ Network Report: launcher can listen on local network
✅ Osquery: osqueryd version 5.10.2
✅ Launcher Flags: launcher.flags exists and is parsable
✅ Quarantine: no quarantine directories found
❌ System Time: could not get valid server time

Checkups with failures:
    * Check communication with Kolide
    * System Time

Any failing checkup will be denoted with a “❌” emoji and also listed in the Checkups with Failures section at the bottom.

Use the output to determine next steps. For example, in the above output, one could check for general Internet connectivity issues or if third-party firewalls might be preventing outbound network connections to the Kolide service.

Obtaining a Kolide Agent Flare

In some situations, Kolide staff may ask you to send debugging information (what Kolide staff call a “Flare”) for a device that may be having issues. Flares are designed to collect relevant logs and other context about the device useful for debugging connectivity issues or other unexpected agent behavior.

macOS / Linux

To obtain a flare on Mac and Linux style devices, follow these instructions:

  1. Open the Terminal application (macOS Instructions).

  2. Type or copy & paste the following command

    sudo /usr/local/kolide-k2/bin/launcher flare

  3. You will be prompted for your computer password. Type it in when prompted and press enter. As a security precaution, your password will not be displayed as you type it into the terminal.

  4. You will see some debugging information print. Once completed, you will see something like msg="Flare uploaded successfully" file=2023/11/21/01HFRVP9WWSWCARZMTWP5YZSWK.zip. Please let support know what the file name is.

Windows

  1. Access the Power User Menu by right-clicking the Start Menu (The Windows Icon).

  2. When the menu appears, select Windows Powershell (Admin)

  3. When the PowerShell terminal appears, type or copy and paste the following commands:

    cd $HOME
& "C:\Program Files\Kolide\Launcher-kolide-k2\bin\launcher.exe" flare

  4. You will see some debugging information print. Once completed, you will see something like msg="Flare uploaded successfully" file=2023/11/21/01HFRVP9WWSWCARZMTWP5YZSWK.zip. Please let support know what the file name is.

Log Locations

The flare command will collect the Kolide debug logs which often contain useful information, including warnings and errors that may explain why the Kolide agent isn’t working correctly. In addition to the flare output, these debug logs can be found in the following locations:

  • macOS: /var/kolide-k2/k2device.kolide.com/debug.json
  • Linux: /var/kolide-k2/k2device.kolide.com/debug.json
  • Windows: C:\Program Files\Kolide\Launcher-kolide-k2\data\debug.json

Troubleshooting Connectivity Issues

For a full list of HTTPS endpoints that the Kolide agent connects to, please see About Kolide’s Agent - Network Communication.

Linux DNS Resolution

The Kolide Agent uses /etc/resolv.conf to perform DNS resolution. Some Linux variants use systemd-resolved and do not provide /etc/resolv.conf, which may interfere with Kolide’s ability to communicate. There are several ways to resolve this problem. See https://wiki.archlinux.org/title/Systemd-resolved#DNS for information.

Third-Party Firewalls

Some third-party firewall software reports outbound connections. Due to how Kolide’s agent performs DNS resolution, this is sometimes reported as a connection to an IP address, and not to the DNS name. This is a reporting discrepancy and can be safely ignored.

Local Port Communication

During authentication, the browser communicates over local ports with our agent. Users may not be able to authenticate successfully if a third-party service, such as an adblocker or VPN, is impeding our ability to communicate over these local ports. Please configure any such third-party services to allow traffic to the appropriate ports, which are listed below. You can also check out this repo for a canonical list.

12519
40978
52115
22287
60685
22322

Repairing The Agent On Windows

Kolide provides a convenient native MSI package to install our agent on supported versions of Windows. Usually, installation is as easy as double-clicking the MSI and following the prompts, but sometimes things can go wrong during the installation, or a previously working installation can stop checking in.

These steps are designed to give you strategies you can use to repair a failed installation of the Kolide Agent on Windows or to repair an agent that has stopped checking in.

  1. First, obtain the latest Windows installer from Kolide.

  2. Locate the new installer on your Windows PC, right-click it, and choose Repair.

  3. Follow any on-screen prompts, and if prompted to reboot, please do so. Once the repair process is complete, the device should reconnect immediately to Kolide.

Should you encounter one of the following errors during the process, please follow their corresponding instructions to recover.

“This Action is Only Valid For Products That Are Installed”

This message can appear during the repair process if either the Windows device never previously had Kolide installed, or it was installed with a different version of our installer. Please follow the Windows Removal Instructions and try again.

This error message can sometimes occur if you have the Service Manager (services.msc) open during the installation process. If this manager is open, it can prevent Windows from correctly modifying and restarting services. Close the service manager and attempt a repair again to avoid this error.

If this persists, follow the Windows Removal Instructions and try again.

“Another version of this product is already installed”

This message can appear during a repair or an install process if a different version of the MSI was used. Please follow the Windows Removal Instructions and try again.

If the Repair Failed to Work and Did Not Produce an Error Message

In rare circumstances, this repair process may not work and produce no actionable errors. If this is the case, we recommend taking the following steps:

  1. Reboot your device - There are instances where the corresponding service cannot successfully start itself without a full system reboot.

  2. Uninstall and reinstall the agent - Follow the Windows Removal Instructions.

  3. Contact Support - If you are still having issues connecting the Windows Agent to Kolide, please contact us at support@kolide.co.