TIL: Six Environment Fields That Decide Whether GBase Database Installation Starts

When reading a GBase Database(GBase 8c) gbase.yml configuration file, most engineers jump straight to datanode, where DN groups and replicas are defined.

But there is another section worth checking first: env, at the bottom of the configuration file.

These environment parameters do not define the cluster topology. They determine whether the installation environment is ready and whether the deployment process can proceed as expected.

Here is an example:

env: cluster_type: multiple-nodes pkg_path: /home/gbase/gbase_package prefix: /home/gbase/gbase_db version: V6_S1.0.0_B20 user: gbase port: 22 third_ssh: false 

Let's look at the six key environment settings and why each one matters during GBase Database installation.

1. cluster_type: Architecture Mode, Not Host Count

This parameter has two documented values:

• multiple-nodes: Distributed deployment mode
• single-inst: Primary-standby deployment mode

One detail is easy to misunderstand: all three official deployment layouts discussed in the examples use multiple-nodes, including the minimal single-host layout.

Why?

Because cluster_type describes the deployment architecture mode, not simply the number of physical machines.

A single-host installation does not automatically mean single-inst.

2. pkg_path: Where the Installation Package Lives

pkg_path specifies the directory containing the unpacked GBase Database installation package.

For example:

pkg_path: /home/gbase/gbase_package 

Before installation, verify that the directory exists and contains the expected package files.

An incorrect package path or an incomplete extraction can prevent the installation process from finding the required installation resources.

3. prefix: Where the Runtime Environment Is Created

prefix defines the target runtime installation directory.

For example:

prefix: /home/gbase/gbase_db 

This directory should be empty before a fresh installation and owned by the gbase user.

This is particularly important when reinstalling GBase Database.

Leftover files from a previous deployment can interfere with initialization. The resulting error may appear during a later installation stage rather than explicitly identifying the directory as the root cause.

Check both ownership and directory contents before proceeding.

4. version: Match the Unpacked Package

The version value must correspond to the actual installation package.

There is a small inconsistency in the documentation example worth watching.

The parameter table shows:

V6_S1.0.0B20 

But the YAML example shows:

V6_S1.0.0_B20 

The difference is a single underscore.

Do not copy the version string blindly. Verify the actual package version and follow the format required by the target release.

A version mismatch can introduce unnecessary troubleshooting during deployment.

5. user: The Installation Account

The documented installation account is:

user: gbase 

Make sure the account exists and has the appropriate permissions over the package and runtime directories.

Also verify that the directory ownership matches the intended installation account.

Using the wrong account or inconsistent ownership can lead to permission problems during installation and initialization.

6. port and third_ssh: SSH Connection Settings

These two settings are easy to confuse with database service configuration.

The port parameter specifies the SSH connection port, not the database listening port.

The default example uses:

port: 22 

If the target hosts use a different SSH port, update this setting accordingly.

The third_ssh parameter indicates whether a third-party SSH tool is being used:

third_ssh: false 

Keep it false unless the deployment environment actually uses the corresponding third-party SSH mechanism.

Do not confuse SSH connectivity with database service port allocation. They belong to different parts of the deployment configuration.

A Five-Minute GBase Database Environment Review

Before running the installation, these Linux commands provide a quick first-pass check.

1. Check runtime directory ownership:

ls -ld /home/gbase/gbase_db 

Confirm that the directory belongs to the intended installation account.

2. Check whether the runtime directory is empty:

ls -A /home/gbase/gbase_db 

No output means the directory contains no visible entries.

3. Verify the package version:

Inspect the unpacked package and confirm that its actual release matches the version field in gbase.yml.

4. Verify the installation account:

id gbase 

Confirm that the account exists and that directory permissions are appropriate.

5. Verify SSH connectivity and port configuration:

Check the configured SSH port in gbase.yml against the actual SSH service configuration on the target hosts.

For example:

ssh -p 22 gbase@<target-host> 

Replace 22 with the actual SSH port when necessary.

6. Review third-party SSH configuration:

Confirm whether the deployment uses a third-party SSH tool and set third_ssh accordingly.

Why Read env Before datanode?

The distinction is simple.

A topology mistake can produce a cluster that does not match the intended architecture.

An environment configuration mistake can prevent the installation from completing at all.

That is why my recommended reading order for GBase Database(GBase 8c) gbase.yml is:

1. env: Verify the installation environment and basic deployment settings.
2. Component sections: Understand the service instances and their roles.
3. datanode: Review DN groups, replicas, and data distribution.

Declarative deployment makes configuration accuracy important from the very beginning. The installer follows the declared settings, so engineers should verify the environment before focusing on cluster topology.

Five minutes spent reviewing these fields can prevent much longer troubleshooting sessions during initialization.