Skip to main content

Device Discovery and Registration

Overview​

This document describes how the system discovers and registers devices. The process consists of two main phases:

  1. Device Discovery - Identifying device characteristics and operating system details
  2. Device Registration - Placing devices into appropriate groups based on their characteristics

Device Discovery​

Device discovery is the process of identifying and collecting information about a device when it first connects to the system or when its configuration changes.

Discovery Methods​

The system uses different discovery methods depending on whether the device is local or remote:

Local Device Discovery​

For devices running the agent locally, the system performs direct discovery by:

  • Network Information: Collecting IPv4, IPv6, and MAC addresses from active network interfaces
  • Operating System Detection: Identifying the OS type, version, and whether it's a server or desktop edition
  • Hardware Information: Gathering CPU details including family, description, and processor count
  • Environment Variables: Capturing system environment variables for use in policies and scripts

Remote Device Discovery​

For remote devices accessed through credentials, the system:

  • Executes remote commands to gather environment information
  • Determines if the system is Windows or Unix/Linux based
  • Collects basic platform information including device name and network details
  • Handles special cases for cloud, ESX, Splunk, and database connections

For ESXi/vCenter discovery, see ESXi / vCenter Discovery.

Supported Operating Systems​

For the full list of supported operating systems, see the Support Matrix.

Operating System Detection Methods​

Windows OS Type Detection​

Windows operating system detection uses build numbers to accurately identify the OS version, as the standard version information isn't reliable for Windows Server 2012 R2 and later versions.

Detection Process:

  1. Registry Information: The system reads from HKLM\Software\Microsoft\Windows NT\CurrentVersion:

    • ProductName: Identifies if it's a server or desktop edition
    • CurrentVersion: Major.Minor version number
    • CurrentBuild: Build number (critical for accurate detection)

  2. Build Number Mapping: The system uses specific build numbers to identify OS versions:

    • 9600: Windows Server 2012 R2 / Windows 8.1
    • 14393: Windows Server 2016 / Windows 10
    • 17763: Windows Server 2019 / Windows 10
    • 20348: Windows Server 2022
    • 21996+: Windows 11
    • 26100+: Windows Server 2025

  3. Server vs Desktop: The system checks the ProductName registry value for the word "server" to distinguish between server and desktop editions

Example: A system with build number 20348 and "server" in the product name is identified as Windows Server 2022, while the same build without "server" would be Windows 10.

Linux Platform Detection​

Linux platform detection uses a three-method sequential approach to ensure accurate identification across different distributions:

Method 1: LSB (Linux Standard Base)

The system first attempts to use the lsb_release command if available:

  1. Checks if lsb_release command exists using which lsb_release
  2. If found, executes lsb_release -sd to get distribution description
  3. Parses the output to identify distribution name and version
  4. Extracts version number from the description string

Method 2: Release Files

If LSB isn't available, the system examines release files in /etc/:

  1. Searches for files matching /etc/*release (including symlinks)
  2. Reads and parses these files as key-value pairs
  3. Looks for specific keys:
    • PRETTY_NAME: Preferred human-readable name
    • NAME: Distribution name
    • VERSION_ID: Version number
    • CPE_NAME: Common Platform Enumeration identifier
  4. Identifies distribution by matching keywords (centos, ubuntu, redhat, debian, suse, oracle, amazon, rocky, fedora)

Method 3: uname Command

If the previous methods fail, the system falls back to the uname -a command:

  1. Executes uname -a to get kernel and system information
  2. Searches the output for distribution-specific keywords
  3. Uses generic "Unix" or "Linux" classification if it finds no specific match

Version Refinement: After the distribution family is identified, the system maps the major version number to specific OS types (e.g., Ubuntu 20, Ubuntu 22, Ubuntu 24).

Example Detection Sequence:

  • System tries lsb_release -sd → Returns "Ubuntu 22.04.1 LTS"
  • Parses to identify: Distribution = Ubuntu, Version = 22.04
  • Maps to OS Type: LinuxUbuntu22

Discovery Process Details​

The discovery process collects the following information:

  1. Device Name: The hostname or computer name
  2. Fully Qualified Domain Name (FQDN): Complete domain name if available
  3. IP Addresses: Both IPv4 and IPv6 addresses from active network interfaces
  4. MAC Addresses: Physical addresses of network adapters
  5. Operating System: Type, version, and edition (server vs. desktop) - detected using the methods in Operating System Detection Methods
  6. Platform Information: Architecture and system details
  7. CPE Name: Common Platform Enumeration identifier (for Linux systems)
  8. Agent Version: Version of the installed agent software

Device Registration​

Device registration is the process of placing newly discovered devices into appropriate groups based on their characteristics and any custom business rules.

Registration Process Flow​

When a device is first discovered or re-registered, it follows this sequence:

  1. Initial Placement: The system places the device in both the "New Devices" and "Awaiting Registration" groups

    • The "New Devices" group provides a fallback — if the registration process fails for any reason, you can still find the device here
    • This ensures devices are never "lost" during the registration process

  2. Registration Report Execution: The system runs a registration report to collect device characteristics

    • The report gathers information such as operating system type, version, and other attributes
    • This data determines appropriate group placement

  3. Group Assignment: Based on the report results and custom scripts, the system assigns the device to groups

    • Custom registration scripts can examine the collected data and apply business logic
    • If no custom script exists, default OS-based group assignment is used

  4. Final Placement: The system moves the device from "Awaiting Registration" to its target groups

    • If the system finds appropriate groups, it removes the device from "New Devices" and adds it to the target groups
    • If the system finds no appropriate groups or registration fails, the device remains in "New Devices" for manual review
    • The system always adds the device to the "All Devices" group regardless of other group assignments

Default Group Assignment​

The registration process uses the "New Device Registration Process" report to determine group placement. By default, the system assigns devices to groups based on their operating system. Each supported OS maps to a corresponding device group (for example, "Windows 2022" or "Linux Ubuntu 24"). For the full list of supported operating systems and their group mappings, see the Support Matrix.

Custom Registration Scripts​

Organizations can customize the registration process by providing a custom registration script. This script can:

  • Examine device characteristics collected by the registration report
  • Apply custom business logic to determine group membership
  • Assign devices to multiple groups based on complex criteria
  • Override default OS-based group assignments

When a custom script identifies multiple groups for a device, the system assigns the device to all identified groups (subject to the AllRegistrationGroupsExist configuration setting). To enforce a group naming convention during registration, see Custom Group Name Prefix.

Group Assignment Sequence​

The system follows this sequence when assigning groups:

  1. Initial State: Device is already in both "New Devices" and "Awaiting Registration" groups (placed there during initial discovery)

  2. Remove from Awaiting Registration: The system removes the device from the "Awaiting Registration" group

  3. Evaluate Custom Script: If a custom registration script exists, the system executes it with the device characteristics

  4. Determine Target Groups: The system identifies groups based on:

    • Custom script results (if script exists)
    • Default OS-based mapping from the registration report (if no script)

  5. Validate Groups: If AllRegistrationGroupsExist is enabled, all identified groups must exist

    • If any group doesn't exist, the system aborts the entire registration
    • The device remains in "New Devices" for manual intervention
    • If CustomGroupNamePrefix is set, an additional prefix-validation check runs as part of this step. See Custom Group Name Prefix for details.

  6. Remove from Previous OS Groups: If EnableAutoReregisterAgentAfterOsChange is enabled, the system removes the device from previous OS-specific groups (during re-registration scenarios)

  7. Add to Target Groups: The system adds the device to all identified groups (if validation passed)

  8. Add to All Devices: The system always adds the device to the "All Devices" group

  9. Handle New Devices Group:

    • If the system successfully assigned custom or OS-specific groups, it removes the device from "New Devices"
    • If the system found no groups or registration failed, the device remains in "New Devices" as a fallback
    • This ensures administrators can always find devices that need manual group assignment

Registration Failure Handling​

If the registration process encounters issues, the device remains in the "New Devices" group where the system initially placed it:

  • No Response: If a device doesn't respond to the registration report, it remains in the "New Devices" group (the system never removes it)

  • Missing Groups: If AllRegistrationGroupsExist is enabled and any identified group doesn't exist, the device remains in "New Devices" and the system logs a warning

  • Script Errors: If the custom registration script fails, the device remains in "New Devices" by default and the system logs the error

  • Validation Failures: Any validation failure during the registration process results in the device staying in "New Devices"

This fallback approach ensures you can always find devices requiring manual intervention in the "New Devices" group, preventing devices from being "lost" in the system.

Configuration Settings​

AllRegistrationGroupsExist​

Purpose: Controls whether all groups identified for a device must exist before the system moves the device from "New Devices".

Default Value: false

Behaviour:

  • When true: If any identified group doesn't exist, the device remains in "New Devices" and the system logs a warning
  • When false: The system adds the device to groups that exist and logs missing groups as errors, but missing groups don't prevent registration

Use Case: Enable this setting in production environments to register devices only when all required groups exist and are properly configured.

EnableAutoReregisterAgentAfterOsChange​

Purpose: Controls whether the system automatically re-registers devices when it detects an operating system change.

Default Value: false

Behaviour:

  • When true: If a device's OS changes (e.g., after an upgrade), the system automatically moves it back to "Awaiting Registration" and runs the registration process again
  • When false: OS changes don't trigger automatic re-registration

Use Case: Enable this setting if you want the system to automatically reassign devices to appropriate OS-specific groups after operating system upgrades.

CustomGroupNamePrefix​

Configure CustomGroupNamePrefix to require that at least one registration group follow a naming convention. See Custom Group Name Prefix.

Logging Configuration​

To troubleshoot device discovery and registration issues, you can enable detailed logging for specific components.

Device Discovery Logging​

To enable detailed logging for device discovery, set the log level for DesktopDevicePlatformDiscovery:

Location: Agent log4net.config file

<logger name="DesktopDevicePlatformDiscovery">
  <level value="DEBUG" />
</logger>

Information Logged:

  • Operating system detection details
  • Network interface discovery
  • Hardware information collection
  • Remote discovery command execution
  • Version parsing and OS family identification

Device Registration Logging​

To enable detailed logging for device registration, set the log level for CollateComplianceReportDataBackgroundTaskWorker:

Location: Hub log4net.config file

<logger name="CollateComplianceReportDataBackgroundTaskWorker">
  <level value="DEBUG" />
</logger>

Information Logged:

  • Registration report processing
  • Custom script execution results
  • Group assignment decisions
  • Device movement between groups
  • Configuration setting evaluations
  • Timing information for performance analysis

Additional Logging​

For comprehensive troubleshooting, you may also want to enable DEBUG logging for:

  • AgentTaskManager: For agent task creation and polling
  • DirectoryManager: For group membership operations
  • EventRepository: For registration event processing

Troubleshooting​

OS Type Not Correctly Identified​

Impact: If the agent can't correctly identify the operating system type, the device registration process will encounter problems because both the registration report and custom registration scripts depend on accurate OS Type information.

Possible Causes:

  1. Outdated Agent: Agent version doesn't recognize newer operating systems
  2. New OS Release: Operating system is newer than the agent's OS detection code
  3. Unsupported OS: Operating system variant not included in detection logic
  4. Registry/System File Issues: On Windows, registry keys may be missing or corrupted; on Linux, release files may be non-standard

Common Scenarios:

  • New Windows OS Release: A completely new Windows version is released (e.g., Windows 12, Windows Server 2027) before agent code is updated to recognize it
    • Note: New builds of existing OS versions (e.g., Windows 11 updates) are handled by build number ranges and won't cause issues
  • New Linux Distribution or Major Version: A new Linux distribution or major version is released that doesn't match existing detection patterns
  • Beta/Preview OS: Running preview or beta versions of operating systems with non-standard version information or identifiers

Symptoms:

  • Device shows generic OS type (e.g., "Windows" instead of "Windows 2022", or "Linux" instead of "Linux Ubuntu 22")
  • Device not assigned to correct OS-specific group during registration
  • Registration report may fail or return unexpected results
  • Custom registration script may not execute correctly due to missing or incorrect OS information

Resolution Steps:

  1. Check Agent Version:

    • Verify the agent version on the affected device
    • Compare with the latest available agent version
    • Review agent release notes for OS support information

  2. Review OS Detection Logs:

    • Enable DEBUG logging for DesktopDevicePlatformDiscovery
    • Check logs for OS detection details
    • Look for warnings about unrecognized build numbers or distribution names

  3. Verify OS Information:

    • Windows: Check registry values at HKLM\Software\Microsoft\Windows NT\CurrentVersion
      • Verify CurrentBuild value exists and is numeric
      • Check ProductName contains expected OS name
    • Linux: Check release files in /etc/ directory
      • Verify /etc/os-release or /etc/*release files exist
      • Check if lsb_release command is available

  4. Update Agent:

    • If a newer agent version is available that supports the OS, upgrade the agent
    • After upgrade, you may need to re-register the device (see EnableAutoReregisterAgentAfterOsChange)

  5. Temporary Workaround:

    • Manually assign device to appropriate groups
    • Document the OS type issue for future reference
    • Consider using custom registration script to handle the specific OS variant

  6. Report to Support:

    • If the OS should be supported but isn't recognized, contact support with:
      • Agent version
      • Operating system details (name, version, build number)
      • OS detection logs with DEBUG enabled
      • Registry/release file contents

Prevention:

  • Keep agents updated to the latest version
  • Test new OS versions in non-production environments before deployment
  • Monitor agent release notes for new OS support
  • Plan agent upgrades before deploying new operating systems

Device Not Appearing in Expected Group​

Possible Causes:

  1. Custom registration script returned unexpected group names
  2. Target group doesn't exist and AllRegistrationGroupsExist is enabled
  3. Registration report didn't complete successfully
  4. Device didn't respond to registration report task

Resolution Steps:

  1. Enable DEBUG logging for CollateComplianceReportDataBackgroundTaskWorker
  2. Check logs for group assignment decisions
  3. Verify all target groups exist in the system
  4. Review custom registration script logic if applicable
  5. Check that device responded to registration report task

Device Stuck in "Awaiting Registration"​

Possible Causes:

  1. Registration report hasn't run yet
  2. Device is offline or not responding
  3. Registration report task timed out

Resolution Steps:

  1. Check device connectivity
  2. Verify agent is running and can communicate with Hub
  3. Review registration report schedule
  4. Check for task timeout issues in logs

Device Not Re-registering After OS Upgrade​

Possible Causes:

  1. EnableAutoReregisterAgentAfterOsChange is disabled
  2. OS change wasn't detected by the system
  3. Agent hasn't polled since the OS change

Resolution Steps:

  1. Enable EnableAutoReregisterAgentAfterOsChange configuration setting
  2. Restart the agent to force a poll
  3. Enable DEBUG logging for AgentTaskManager to see OS change detection

Multiple Devices in Wrong Groups After Registration​

Possible Causes:

  1. Custom registration script has logic errors
  2. Registration report collecting incorrect data
  3. Group names in script don't match actual group names

Resolution Steps:

  1. Review custom registration script logic
  2. Test script with sample device data
  3. Verify group display names match script output
  4. Enable AllRegistrationGroupsExist to prevent partial registrations

Best Practices​

  1. Test Custom Scripts: Always test custom registration scripts in a non-production environment before deployment

  2. Enable AllRegistrationGroupsExist: In production environments, enable this setting to ensure devices are only registered when all required groups exist

  3. Monitor Registration Logs: Regularly review registration logs to identify patterns or issues

  4. Create Groups Before Registration: Ensure all target groups exist before running registration reports

  5. Use Descriptive Group Names: Use clear, descriptive group names that match your organizational structure

  6. Document Custom Logic: If using custom registration scripts, document the business rules and group assignment logic

  7. Plan for OS Upgrades: If you perform OS upgrades, consider enabling EnableAutoReregisterAgentAfterOsChange to automatically reassign devices

  8. Regular Audits: Periodically audit device group memberships to ensure they remain accurate

Summary​

The device discovery and registration process provides a flexible framework for automatically organizing devices based on their characteristics. By understanding the discovery methods, supported operating systems, registration flow, and configuration options, you can effectively manage device onboarding and ensure devices are placed in appropriate groups for policy application and reporting.