GBase Database 8c Port Conflicts: Installation Succeeds, but Services Won't Start

Port conflicts in GBase Database(GBase 8c) can be difficult to diagnose because installation may complete successfully, while the actual failure appears later when a service attempts to start.

Instead of reporting an obvious port conflict, the logs may only show connection failures or instance startup errors.

The first step is to understand the port allocation across the cluster. The second is to check every host for duplicate ports, including service, proxy, and agent ports.

Here is a practical approach to troubleshooting GBase Database port conflicts before and after installation.

1. Understand the GBase Database Port Map

Before deployment, classify ports by component and purpose.

The following table summarizes the commonly used ports in the GBase Database(GBase 8c) deployment examples.

In addition to these service and proxy ports, each instance has its own agent port.

Do not treat this table as a universal port allocation template. Actual assignments depend on the selected deployment layout and the number of instances running on each host.

2. Three Common Causes of Port Conflicts

Cause 1: Multiple Roles on the Same Host

A single physical or virtual machine may run multiple GBase Database components.

For example, in the single-HA-group layout, one host can run:

• GTM primary
• CN3
• DN1_1

These components have different service roles, but their ports still share the same host network namespace.

If the same agent port is copied across multiple instances, a later instance may fail to start because the port is already occupied.

The deployment manual recommends maintaining a port gap of at least 1,000 between HA groups.

The key is to allocate ports by host and instance, not simply by component name.

Cause 2: Copying Port Settings Across Deployment Layouts

Different GBase Database deployment layouts may use different port assignments.

For example, the GTM agent ports differ between two official configuration examples:

These values are intentional differences between the examples.

Copying port settings from one layout into another without checking the host-role mapping can introduce conflicts that are difficult to identify from the installation output.

Always start with the official gbase.yml example matching the target topology, then adjust ports according to the actual host assignments.

Cause 3: Processes Left Behind by Previous Tests

Another common cause is a process from an earlier installation or deployment test that is still listening on a required port.

Before installing GBase Database, scan the commonly used ports:

for p in 20001 2379 6666 5432 15432 15433 20010 6001 7001 17001; do ss -tlnp | grep -q ":$p " && echo "BUSY $p" || echo "free $p" done 

This script provides a quick initial check of TCP listening ports.

If a port is occupied, identify the process before deciding what to do.

There are two possible solutions:

• Stop the old process if it is no longer required.
• Assign a different port if the existing service must remain running.

Never terminate an unknown process simply because it occupies a port needed by the new deployment.

3. Changing a Port Requires More Than Editing gbase.yml

If you decide to change a port, check three places:

1. GBase Database configuration

Update the corresponding port in gbase.yml.

2. Firewall policy

Make sure the new port is allowed by the host firewall and any relevant network security policies.

3. Client connection settings

Update application connection strings and other dependent configurations where the affected service port is referenced.

Changing only gbase.yml can leave the database configured correctly while external connections continue to fail.

4. A Subtle Problem: The Port Is Listening on the Wrong Address

Not every connection failure is caused by a duplicate port.

Sometimes the service is listening, but only on the loopback address:

127.0.0.1 

This creates a confusing situation:

• Local connection tests succeed.
• Remote clients cannot connect.
• The problem may initially look like an authentication failure.

Check both the listening port and its bound address:

ss -tlnp 

A service bound only to 127.0.0.1 cannot accept connections through the host's external network interface.

Verify the expected listen address before changing authentication rules or client credentials.

5. Do Not Forget Agent Port Conflicts

Service ports and proxy ports are usually easier to identify because they appear in application connection settings or deployment documentation.

Agent ports are easier to overlook.

They do not normally appear in client connection strings, but they can collide just like other listening ports.

The resulting error may simply report that an instance failed to start, without clearly identifying the port conflict.

For this reason, maintain three separate port categories in the deployment plan:

A complete port inventory should be organized by host, not just by component.

6. Build a Host-Based Port Validation Checklist

The most reliable approach to GBase Database port planning is to start with the host-role mapping.

Follow this sequence:

1. List every host in the target cluster.
2. Record all database components assigned to each host.
3. Assign service, proxy, and agent ports.
4. Check for duplicate port assignments on each host.
5. Scan existing TCP listeners before installation.
6. Verify firewall rules and expected listen addresses.
7. Archive the final port allocation table with gbase.yml.

Ideally, generate the port scanning script from the same host-role table rather than maintaining a separate hardcoded port list.

This reduces inconsistencies between the deployment plan and the actual validation process.

Conclusion: Port Planning Starts With Host Roles

GBase Database(GBase 8c) port conflicts are not always installation problems. Many appear only when individual services start or when remote connections are established.

The most effective prevention strategy is to define the host-role mapping first, allocate service, proxy, and agent ports separately, and validate every host before installation.

A successful installation does not automatically mean that every service can start correctly.

For GBase Database deployment, a host-based port inventory is much cheaper than troubleshooting port conflicts after installation.