---
title: FQDN Map
description: Key:Value maps of incoming hostname to outgoing domain. Use this property to map requests with virtual, invalid, or partial hostnames to a correct FQDN.
component: java-agents
version: 2025.11
page_id: java-agents:properties-reference:org.forgerock.agents.fqdn.map
canonical_url: https://docs.pingidentity.com/java-agents/2025.11/properties-reference/org.forgerock.agents.fqdn.map.html
---

# FQDN Map

Key:Value maps of incoming hostname to outgoing domain. Use this property to map requests with virtual, invalid, or partial hostnames to a correct FQDN.

This property requires [Enable FQDN Checking](org.forgerock.agents.fqdn.check.enabled.html) to be `true`, and [Default FQDN](org.forgerock.agents.fqdn.default.html) to be set to suitable default FQDN.

The agent maintains the following maps, which can each contain multiple entries:

* Map 1, where the key is the incoming hostname without wildcards, and the value is the outgoing domain.

* Map 2, where the key is the incoming hostname with wildcards (\* or ?), and the value is the outgoing domain.

Map keys are case insensitive. Incoming hostnames are converted to lowercase before the agent maps them, and the agent automatically converts uppercase keys and values to lowercase before mapping.

The agent maps FQDNs as follows:

1. Searches map 1 for the incoming hostname. If there is a match, the agent redirects the request to the mapped value.

2. Searches map 2 for a pattern that matches the incoming hostname, iterating through the entries in random order. If there is a match, the agent redirects the request to the mapped value.

3. Redirects the request to the hostname in [Default FQDN](org.forgerock.agents.fqdn.default.html).

Examples:

`org.forgerock.agents.fqdn.map[agent]=agent.localtest.me`

`org.forgerock.agents.fqdn.map[agent.virtualtest.me]=virtual-host.localtest.me`

`org.forgerock.agents.fqdn.map[agent-*.localtest.me]=agent.localtest.me`

|                          |                                                                                                                                                                                                                   |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Property name            | `org.forgerock.agents.fqdn.map`                                                                                                                                                                                   |
| Aliases                  | `com.sun.identity.agents.config.fqdn.mapping`   Introduced in Java Agent 5.0   [Recognized](preface.html#how_am_manages_multiple_aliases) from AM 6`org.forgerock.agents.fqdn.map`   Introduced in Java Agent 5.6 |
| Function                 | Fully qualified domain name                                                                                                                                                                                       |
| Type                     | Map- Keys: canonical name of invalid server

- Values: canonical name of valid server                                                                                                                             |
| Bootstrap property       | No                                                                                                                                                                                                                |
| Required property        | No                                                                                                                                                                                                                |
| Restart required         | No                                                                                                                                                                                                                |
| Local configuration file | `AgentConfig.properties`                                                                                                                                                                                          |
| AM console               | Tab: `Global`Title: `FQDN Map`Legacy title: `FQDN Virtual Host Map`                                                                                                                                               |