Introduction & Challenges in Multi-VSYS Environments
Virtual Systems (VSYS) on Palo Alto Networks firewalls allow a single physical or virtual device to be partitioned into multiple independent logical firewalls. Each VSYS typically operates with its own routing, security policies, NAT, and other configurations. A significant challenge arises when User-ID is required across these independent contexts, particularly regarding the collection and sharing of IP-to-User and User-to-Group mappings.
Challenges in Multi-VSYS Environments for User-ID Sharing
Without a centralized sharing mechanism, multi-VSYS environments face several difficulties:
- Configuration Duplication: Each VSYS needing User-ID must be individually configured to poll Domain Controllers, connect to User-ID Agents, or receive syslog/XML API updates. This replicates configuration efforts across multiple VSYS contexts.
- Increased Directory Server Load: Multiple VSYS polling the same Domain Controllers or LDAP servers simultaneously can significantly increase the load on these critical infrastructure components.
- Inconsistent Mappings: While theoretically collecting from the same sources, independent polling cycles or configuration differences can lead to slight inconsistencies in the mapping tables maintained by each VSYS.
- Mapping Loss at VSYS Boundaries: If traffic from a user mapped in VSYS A needs policy enforcement in VSYS B, VSYS B must have independently learned the mapping or be able to retrieve it, otherwise the user will be unknown in VSYS B's context.
- Management Overhead: Managing User-ID sources and configurations across many VSYS becomes complex and prone to error.
These challenges highlight the need for a method to unify User-ID collection and distribution within a single multi-VSYS firewall.
User-ID Hub Solution: Concept
The User-ID Hub is Palo Alto Networks' solution to centralize User-ID mapping collection and distribution within a single multi-VSYS firewall. It designates one specific VSYS to act as the central collection point, sharing its learned mappings with other VSYS on the same device.
How the User-ID Hub Works
The core concept is straightforward:
- One VSYS is explicitly configured as the User-ID Hub .
- All primary User-ID source configurations (Server Monitoring for DCs/Exchange, Group Mapping for LDAP/AD, User-ID Agent connections, Syslog, XML API) should be consolidated onto the Hub VSYS.
- The Hub VSYS actively collects IP-to-User and User-to-Group mappings from these configured sources.
- Other VSYS on the same firewall, known as Spoke VSYS , are configured to query the Hub VSYS when they need mapping information that isn't available in their own local mapping table.
- This internal query mechanism happens automatically when the spoke VSYS processes traffic or policy that requires User-ID lookup for an unknown user/IP.

Representation of the User-ID Hub and Spoke VSYS relationship within a single firewall.
The User-ID Hub is a feature *within* a single multi-vsys firewall instance, not a method to share User-ID between separate firewalls (that's typically handled by Panorama or external means).
Mapping Types Shared & Lookup Precedence
Mapping Types Shared
When configuring a VSYS as a User-ID Hub, you must specify which types of mappings it will centralize and share. You can select one or both:
- IP User Mapping: Sharing the standard IP address-to-username associations collected from sources like Server Monitoring, User-ID Agents, GlobalProtect, etc.
- User Group Mapping: Sharing the username-to-group membership information obtained via Group Mapping configuration (LDAP/AD queries).
You must enable at least one of these mapping types for the Hub functionality to be active.
Lookup Precedence
Understanding the order in which a Spoke VSYS looks up mapping information is critical for predicting User-ID behavior in a Hub environment. When a Spoke VSYS needs a mapping for a specific IP or user:
The Spoke VSYS checks for mappings in this order:
- Local Mapping Table: It first checks its own locally learned mapping table. Mappings learned directly by the Spoke VSYS (e.g., via Captive Portal, GlobalProtect sessions terminating on that VSYS, or local configuration for a specific IP) take highest precedence.
- User-ID Hub Query: If no matching local mapping is found, the Spoke VSYS queries the designated User-ID Hub VSYS for the required mapping information.
- Result: If the Hub VSYS has the mapping, it is provided to the Spoke and used for policy evaluation and logging. If the Hub does not have the mapping, the user/group remains unknown to the Spoke VSYS for that transaction.
Key Takeaway: Local mappings on a Spoke VSYS ALWAYS override mappings for the same IP/user received from the Hub.

Flowchart illustrating the User-ID mapping lookup order on a spoke VSYS.
Benefits of Using a User-ID Hub
Implementing a User-ID Hub in a multi-VSYS environment offers significant advantages:
- Simplified Configuration: User-ID source configurations (Server Monitoring, Group Mapping, User-ID Agents) are centralized on the Hub VSYS, eliminating the need to duplicate these settings across multiple Spoke VSYS.
- Consistency: All Spoke VSYS query the same central mapping table on the Hub, ensuring consistent and up-to-date User-ID information is used throughout the firewall.
- Reduced Directory Server Load: Only the Hub VSYS actively polls Domain Controllers/LDAP servers for User-ID information, drastically reducing the number of connections and queries originating from the firewall towards these servers.
- Efficient Policy Enforcement: Allows for seamless user-based policy enforcement across VSYS boundaries, as Spoke VSYS can retrieve mappings from the Hub for users whose traffic might traverse multiple VSYS.
- Improved Management Plane Efficiency: Reduces the load on the management plane of Spoke VSYS by offloading the active User-ID collection tasks to the Hub.
- Single Point of Visibility: Troubleshooting User-ID collection issues can be focused on the Hub VSYS.
These benefits are fully realized only when User-ID source configurations are correctly consolidated on the Hub and removed from the Spoke VSYS.
User-ID Hub vs. Sharing via Panorama
It's important to distinguish the User-ID Hub feature from User-ID collection and reporting capabilities offered by Panorama. While both involve centralization, they serve different purposes and operate differently:
Feature | User-ID Hub | Panorama Centralized User-ID |
---|---|---|
Scope | Shares mappings between VSYS on a single firewall . | Collects mappings from multiple firewalls (managed devices) for centralized visibility, reporting, and potentially policy decisions based on users seen on *any* managed device. |
Primary Use Case | Simplify User-ID configuration and ensure consistent mapping within a multi-VSYS firewall. | Centralized visibility, reporting, and policy control across an organization's firewalls, often involving User-ID correlation from many sources/devices. |
Mechanism | Internal VSYS-to-VSYS query mechanism. Spoke VSYS directly query the Hub VSYS on the same device. | Managed firewalls send User-ID logs/syslog/API updates to Panorama. Panorama acts as a central collection point for reporting and policy push. No direct internal VSYS-to-VSYS query like the Hub. |
Configuration | Enabled on a specific VSYS under Device > Virtual Systems. User-ID sources configured on the Hub VSYS. | Configured on Panorama (Collector Groups, Log Collectors). Firewalls are configured to forward User-ID logs/syslog to Panorama. User-ID policies managed on Panorama and pushed to firewalls. |
Mapping Precedence | Local VSYS mapping > Hub VSYS mapping. | Firewall local mapping > Panorama mapping (if firewall receives user info directly). Policies on Panorama can utilize the consolidated view. |
Licensing | Feature of PAN-OS, generally available on multi-VSYS platforms. | Requires Panorama license. |
The User-ID Hub specifically addresses the challenge of User-ID within a single multi-VSYS device, whereas Panorama addresses User-ID challenges across multiple devices in an enterprise network.
Configuration Steps
Configuring the User-ID Hub involves selecting a Hub VSYS, enabling the feature, and consolidating User-ID source configurations.
-
Choose the Hub Virtual System:
Identify one existing VSYS that will serve as the central User-ID Hub. Consider a VSYS that has reliable network access to your Domain Controllers, LDAP servers, and User-ID Agents. This VSYS will handle the primary load of collecting mappings.
-
Enable Hub Functionality on the Chosen VSYS:
- GUI Path: Navigate to Device > Virtual Systems .
- Select the chosen Hub VSYS and click Edit .
- Go to the Resource tab.
-
Check the box
Make this vsys a User-ID data hub
. - Confirm the action if prompted.
-
Under
Mapping Type
, select the types of mappings the Hub will share by checkingIP User Mapping
and/orUser Group Mapping
. You must select at least one. - Click OK to save the VSYS properties.
-
Consolidate User-ID Source Configuration onto the Hub:
This is the most critical step after enabling the Hub. The Hub VSYS must be actively collecting the mappings it is intended to share.
- Log in to the context of the Hub VSYS .
-
Configure or verify all necessary User-ID source settings here:
- Server Monitoring: Configure and enable polling of Domain Controllers ( Device > User Identification > User Mapping > Server Monitoring ).
- Group Mapping: Configure LDAP Server Profiles ( Device > Server Profiles > LDAP ) and Group Mapping Settings ( Device > User Identification > Group Mapping Settings ) to fetch user group memberships.
- User-ID Agents: Configure connections to any necessary User-ID Agents ( Device > User Identification > User-ID Agents ).
- Any other sources like Syslog Parsing Profiles or XML API integrations should be configured to direct data to the Hub VSYS.
Ensure the Hub VSYS has appropriate network connectivity (via service routes or data interfaces) to reach these User-ID sources.
-
Remove Duplicate Configurations from Spoke VSYS:
Equally critical for proper functioning and gaining benefits. To avoid unnecessary load on directory servers and prevent confusion from local precedence overrides, remove the User-ID source configurations that are now handled by the Hub from all *other* VSYS (the Spoke VSYS).
- Log in to the context of each Spoke VSYS in turn.
- Navigate to Device > User Identification .
- Remove or disable Server Monitoring configurations.
- Remove or disable Group Mapping configurations.
- Remove or disable User-ID Agent connections.
- Any other local collection configurations should also be reviewed and removed if they are now covered by the Hub.
-
Commit Changes:
Perform a commit to apply the changes globally or per VSYS as needed.
Verification
After configuring the User-ID Hub, use CLI commands to verify that the Hub is active, collecting mappings, and that Spoke VSYS can retrieve them.
-
show user user-id-agent statistics
: This command provides an overview of User-ID agent connections and status. The output will indicate which VSYS is configured as the User-ID data hub. Look for a line likeUser-ID data hub:
. -
show user ip-user-mapping all virtual-system <vsys-name>
: Use this command while logged into the Spoke VSYS context. It shows the IP-to-User mappings known to that specific Spoke VSYS. If the Hub is working, you should see mappings here that were learned by the Hub (unless a local mapping exists for the same IP). The source column might indicate 'Hub'. -
show user group list virtual-system <vsys-name>
: Run this from a Spoke VSYS context. It lists the user groups available for policy matching on that VSYS. These groups should match those configured for Group Mapping on the Hub, provided User-Group mapping sharing is enabled. -
show user group name "
: From a Spoke VSYS context, verify the members of a specific group are correctly populated from the Hub's Group Mapping data.<group-name>
" virtual-system <vsys-name> -
show user group-mapping state all virtual-system <hub-vsys-name>
: Check the status of the Group Mapping connections (LDAP/AD) *on the Hub VSYS* to ensure the Hub is successfully collecting group information. -
show user server-monitor state all virtual-system <hub-vsys-name>
: Check the status of the Server Monitoring connections *on the Hub VSYS* to ensure it's collecting IP-User mappings.
Always specify the
virtual-system <vsys-name>
argument in CLI commands to ensure you are viewing data for the correct VSYS context.
Troubleshooting and Debugging
Troubleshooting User-ID in a Hub environment often requires focusing on the Hub VSYS first, then verifying communication and precedence on the Spokes.
Common Troubleshooting Steps:
-
Verify Hub is Enabled:
- Check the VSYS configuration ( Device > Virtual Systems > [Hub VSYS] > Resource ).
-
Use
show user user-id-agent statistics
to confirm the Hub is active.
-
Verify Hub is Collecting Mappings:
- Log into the Hub VSYS context.
-
Check the status of your User-ID sources:
-
Server Monitoring:
show user server-monitor state all virtual-system <hub_vsys>
-
Group Mapping:
show user group-mapping state all virtual-system <hub_vsys>
-
User-ID Agents:
show user user-id-agent state all virtual-system <hub_vsys>
-
Server Monitoring:
-
Verify mappings exist in the Hub's tables:
show user ip-user-mapping all virtual-system <hub_vsys>
andshow user group list virtual-system <hub_vsys>
. If the Hub isn't collecting, fix the source configuration on the Hub VSYS.
-
Verify Spoke VSYS Configuration:
- Log into each Spoke VSYS context.
- Ensure redundant User-ID source configurations (Server Monitoring, Group Mapping, Agents) have been removed or disabled. They should rely on the Hub.
-
Check Mapping Precedence:
-
If a Spoke isn't using a mapping you expect from the Hub, check if a local mapping exists for that specific IP/user on the Spoke VSYS (
show user ip-user-mapping ip <ip> virtual-system <spoke_vsys>
). Remember, local takes precedence.
-
If a Spoke isn't using a mapping you expect from the Hub, check if a local mapping exists for that specific IP/user on the Spoke VSYS (
-
Review Logs:
-
Check the
useridd.log
on the management plane for errors related to User-ID collection (on the Hub) or querying the Hub (on Spokes). Useless mp-log useridd.log
. - Monitor traffic logs for sessions where User-ID is expected but showing as 'unknown'. This indicates a failure to map the IP.
-
Check the
-
Check Connectivity for Hub Sources:
- If the Hub isn't collecting, verify network connectivity from the Hub VSYS (considering service routes or data interfaces used for User-ID sources) to the Domain Controllers, LDAP servers, or User-ID Agents. Use PING or packet capture if needed.

Sequence diagram illustrating the User-ID query and mapping flow in a Hub environment.
Caveats and Gotchas
Be aware of these potential pitfalls when implementing and managing a User-ID Hub, especially important for PCNSE exam preparation:
- Terminal Server Agent Mappings NOT Shared: User-ID mappings collected by a User-ID Agent specifically configured for Terminal Services (TS Agent), which map IP address + port to username, are NOT shared via the User-ID Hub mechanism. These mappings must be collected independently by the VSYS that handles the TS traffic.
- Manual Configuration Consolidation: Enabling the "Make this vsys a User-ID data hub" setting does NOT automatically migrate or consolidate your existing User-ID source configurations. You MUST manually configure the sources (Server Monitoring, Group Mapping, Agents, etc.) on the Hub VSYS and remove them from the Spoke VSYS.
- Local Mappings Override Hub Mappings: Remember the lookup precedence! If a Spoke VSYS learns a mapping for an IP locally (e.g., via Captive Portal, GlobalProtect, or a lingering old configuration), it will use that local mapping and will NOT query the Hub for that specific IP, even if the Hub has a different or more current mapping for the same IP.
- Hub Performance Impact: The Hub VSYS's management plane takes on the full load of collecting mappings for the entire firewall. In environments with very high User-ID churn or many sources, ensure the firewall model and the chosen Hub VSYS have sufficient resources. Monitor the management plane CPU and memory on the Hub VSYS.
- Service Routes for Sources: If your User-ID sources (DCs, LDAP, Agents) are reachable via a different data interface than the management interface on the Hub VSYS, you may need to configure Service Routes on the Hub VSYS to ensure the User-ID processes can reach them.
- No Inter-VSYS Policy Requirement: The internal communication between the Spoke VSYS and the Hub VSYS for mapping queries does NOT require you to configure explicit inter-VSYS security policies or routing between the management interfaces of the VSYS. This communication is handled internally by the firewall processes.
Best Practices
Follow these best practices for a successful User-ID Hub implementation:
- Choose Your Hub Wisely: Select a VSYS that is stable, has good connectivity to User-ID sources, and is intended for long-term use. Avoid using a temporary or test VSYS as the Hub.
- Perform Full Consolidation: Don't partially consolidate. Configure ALL Server Monitoring, Group Mapping, and User-ID Agent connections on the Hub and remove them entirely from the Spokes. This is key to realizing the benefits.
- Standardize Naming: Ensure primary and alternate username attributes in Group Mapping settings on the Hub are consistent with how usernames are learned from other sources (Agents, GlobalProtect). This prevents mismatches.
- Monitor Hub Resources: Actively monitor the management plane CPU and memory utilization of the Hub VSYS, especially after initial deployment or significant changes.
- Document Your Configuration: Clearly document which VSYS is the Hub, which mappings are shared, and where the User-ID sources are configured.
- Use Service Routes if Needed: If User-ID sources are not on the management network, configure Service Routes on the Hub VSYS to ensure reachability from the User-ID processes.
PCNSE Exam Focus
The PCNSE exam often tests your understanding of multi-VSYS environments and User-ID. Pay close attention to these points regarding the User-ID Hub:
- Understand the PROBLEM the Hub solves: Duplication, inconsistency, and load in multi-VSYS User-ID collection.
- Know the SOLUTION : Designate ONE VSYS as the User-ID Hub.
- Identify the GUI LOCATION to enable the Hub: Device > Virtual Systems > [VSYS Name] > Resource tab .
- Recall the MAPPING TYPES SHARED : IP-User Mapping and User-Group Mapping. You must select at least one.
- Crucially understand the need to CONSOLIDATE all User-ID source configurations (Server Monitoring, Group Mapping, Agents) onto the Hub VSYS.
- Memorize the LOOKUP ORDER/PRECEDENCE : Local VSYS Mappings > Hub VSYS Mappings . A Spoke checks its local table first.
- Know the KEY LIMITATION : Terminal Server Agent (TS Agent) mappings are NOT shared via the Hub.
-
Be familiar with basic
CLI VERIFICATION COMMANDS
, especially those using the
virtual-system <name>
parameter to check data on specific VSYS contexts. Examples:show user user-id-agent statistics
(for Hub status),show user ip-user-mapping all virtual-system <name>
,show user group list virtual-system <name>
. - Understand that no inter-VSYS security policy or routing is required for the internal Hub-Spoke mapping query mechanism itself.
- Know that the Hub vs Panorama comparison often centers on Hub being *within* a device (multi-vsys) vs. Panorama being *across* devices.
Look for scenario-based questions testing your understanding of mapping precedence or the TS Agent limitation.
User-ID Hub & Mapping Quiz
Test your knowledge on User-ID Hub and related User-ID concepts.