Configuring NuoDB Admin

NuoDB Admin (nuoadmin) uses nuoadmin.conf file to secure the domain and configure membership connection attributes. The nuoadmin.conf configuration file is located in the $NUODB_CFGDIR directory. See also the the sample $NUODB_HOME/etc/nuoadmin.conf.sample file shipped with NuoDB.

For information on the environment variables, see Environment Variables.

Configuring Admin Processes (APs)

An Admin Process (AP), also known as an admin service or an admin server, participates as a domain member in a NuoDB domain and is identified by its IP address and port number. Each AP has a unique server ID with an alphanumeric string value. To configure an AP for a given host machine, there are some important properties (located in nuoadmin.conf) that require review and/or configuration.

  • ThisServerId

  • initialMembership

  • peer

  • altAddr

For information on additional properties that may be set for an Admin Process and example configuration, see Host Properties (nuoadmin.conf).

The minimal steps to configure the NuoDB Admin Process on a particular host are described below.

Step 1 - Configure ThisServerId

ThisServerId is a unique identifier for a particular AP that is permanently assigned. It should be stable and can’t be changed without removing the durable Raft state (the raftlog file located in $NUODB_VARDIR) for that AP. For more information, see Deprovisioning Hosts in a Multi-Host Configuration (Scaling In).

If a DNS name is used as ThisServerId, it should not change after a host restart or re-provision.

Step 2 - Configure initialMembership

A special startup procedure called bootstrap is performed when the NuoDB domain is started for the first time. To prevent cross-domain communication a unique domain ID is generated and confirmed by the majority of the initial domain members. To define one or more NuoDB APs capable of performing domain bootstrap or allowing non-initial member peers to enter a domain, set a value for the initialMembership property in nuoadmin.conf. Each key is a server ID with a value that has the corresponding Raft protocol version and connection details for that server. If the domain has not been bootstrapped yet, then it can only be bootstrapped by a majority of the servers configured in the initialMembership. All domain members that specify an initial membership must have the same initialMembership value configured.

To prevent the creation of disjoint domains any admin servers which are not in the initial membership cannot be added until after the domain is bootstrapped.

The initialMembership is immutable during the domain lifecycle. Changing it requires destroying the domain and bootstrapping a new one.

For more information and example configuration, see Notes on Setting the peer and initialMembership Properties

Step 3 - Configure peer (optional)

The peer can be the address of a specific admin server in the membership or a load-balancer that is routing traffic to existing admin servers. The newly started admin servers will try to fetch the initial membership from the peer endpoint if specified. Otherwise, the configured initialMembership in nuoadmin.conf will be used when joining the domain.

When peer is set to load-balancer, it is not recommend to use an empty initialMembership, because it can lead to servers bootstrapping disjoint domains.

For more information and example configuration, see Notes on Setting the peer and initialMembership Properties

Step 4 - Configure altAddr (optional)

By default, an AP stores its hostname in the durable membership (which other APs can then use to communicate with it). In situations when a different hostname or IP address should be advertized by a particular Admin Process, altAddr can be configured. For example, an AP host having public and private IP addresses, the public address may need to be advertised.

The address specified in the transport field of the initialMembership entry for ThisServerId must be the same as the hostname configured in altAddr if an altAddr is specified). Once the domain is bootstrapped, the altAddr can be changed.

Step 5 - Configure Transport Layer Security

The certificates and keystore files used by Transport Layer Security (TLS) must be provisioned before starting the AP. By default, TLS is enabled in nuoadmin.conf by the line "ssl": "true",. It can be disabled by setting "ssl": false", in nuoadmin.conf. If TLS is disabled the keystore and truststore properties will be ignored.

For information on how to generate certificates, see Enabling TLS Encryption.

Step 6 - Start NuoDB Admin service

The admin service startup command can differ depending on the NuoDB installation type.

Step 7 - Verify NuoDB Admin domain status

Use the NuoDB Command (nuocmd) command line tool and run nuocmd show domain to display all Admin Processes and their status. Make sure that all APs are reported as Connected and a leader is elected.

For information on extending existing domain, see Extending the Database Across a Second Host (Scaling Out), and Admin Process (AP).