Port Mappings

Port Mappings translate raw TCP and UDP port numbers into human-readable service names throughout the platform. Instead of seeing port 443 in flow tables and charts, you see HTTPS. Instead of port 3306, you see MYSQL. These mappings are used across flow dashboards, top talkers, Sankey diagrams, reports, and any query that references the appid field.

How Port Mappings Work

Port mappings are stored in a ClickHouse port_names table and exposed via a port_dict dictionary using the FLAT layout for constant-time lookups. The flows_all table has a MATERIALIZED column called appid that automatically resolves the destination port to a service name at insert time using this dictionary:

appid String MATERIALIZED dictGetOrDefault('port_dict', 'service_name', dst_port, 'UNKNOWN')

This means every flow record is permanently stamped with the service name that was current when the flow was ingested. If a port mapping didn't exist at ingestion time, the flow's appid will be UNKNOWN — updating the mapping later will not retroactively change existing flow records, only new flows going forward.

Port Mappings Table

The table displays all configured mappings sorted by port number with the following columns:

Column	Description
Port	The TCP or UDP port number (0–65535). Port 0 is a special catch-all used for the UNKNOWN fallback service.
Protocol	The transport protocol: TCP, UDP, or ANY. The ANY protocol is used for the port 0 UNKNOWN mapping. Most well-known services specify their primary protocol.
Service Name	The short label displayed throughout the UI (e.g., SSH, HTTP, DNS, KAFKA). Service names are typically uppercase by convention.
Description	A longer description of the service for reference (e.g., "Hypertext Transfer Protocol", "Simple Network Management Protocol").
Actions	Edit or delete the mapping.

Managing Port Mappings

+ Add Port Mapping

Opens a form to create a new mapping with the following fields:

• Port (required) — The port number to map. Must be between 0 and 65535. Each port/protocol combination must be unique.
• Protocol (required) — Select TCP, UDP, or ANY.
• Service Name (required) — The short label to display. Keep this concise — it appears in chart labels, table columns, and filter dropdowns.
• Description — Optional longer description of the service.

After adding or modifying a mapping, the ClickHouse dictionary reloads automatically (the dictionary has a LIFETIME of 3600 seconds). New flows arriving after the reload will use the updated mapping.

Edit

Opens the mapping form pre-populated with the current values. You can change the service name or description — the port and protocol serve as the composite key identifying the mapping.

Delete

Removes the mapping. Flows that were previously tagged with this service name retain their appid value in ClickHouse. New flows on the deleted port will fall back to UNKNOWN.

Pre-loaded Mappings

Chompy ships with a comprehensive set of well-known port mappings covering common network services. A sample of the default mappings:

Port	Protocol	Service	Description
22	TCP	SSH	Secure Shell
53	UDP	DNS	Domain Name System
80	TCP	HTTP	Hypertext Transfer Protocol
443	TCP	HTTPS	HTTP Secure
161	UDP	SNMP	Simple Network Management Protocol
514	UDP	SYSLOG	Syslog
3306	TCP	MYSQL	MySQL Database
3389	TCP	RDP	Remote Desktop Protocol
5432	TCP	POSTGRESQL	PostgreSQL Database
6379	TCP	REDIS	Redis Database
8080	TCP	HTTP-ALT	HTTP Alternate
9092	TCP	KAFKA	Apache Kafka

The full default set includes approximately 40 common services. You can add custom mappings for any application-specific ports used in your environment (e.g., internal APIs, proprietary services, or non-standard port assignments).

Custom Application Ports

Many environments run services on non-standard ports. For example, if your organization runs an internal web application on port 8443, adding a mapping with service name INTERNAL-APP and description Internal Application Portal ensures that traffic to this port is clearly identified in all dashboards rather than showing as UNKNOWN.

Common scenarios for custom mappings include:

• Internal applications running on high-numbered ports.
• Development or staging services on alternate ports (e.g., 3000 for Node.js dev servers).
• Vendor-specific protocols (e.g., proprietary network management tools).
• Game servers, media streaming, or other specialized traffic you want to identify.

Troubleshooting

Flows showing "UNKNOWN" for a known port

If a port mapping exists but flows still show UNKNOWN, the dictionary may not have reloaded yet. The port_dict dictionary refreshes every 3600 seconds (1 hour). You can force a reload by running in ClickHouse:

SYSTEM RELOAD DICTIONARY port_dict;

Flows ingested before the mapping was added will retain their original UNKNOWN value since appid is a MATERIALIZED column computed at insert time.

Dictionary not loading data

If the dictionary returns empty strings, verify that the port_names source table contains data and that the dictionary's SOURCE clause includes the correct ClickHouse user credentials. Check with:

SELECT count() FROM port_names;
SHOW CREATE DICTIONARY port_dict;

Duplicate port/protocol combinations

Each port/protocol pair must be unique. If you need to map the same port under different protocols (e.g., DNS on both TCP/53 and UDP/53), create separate entries for each protocol.