Skip to main content
Common Reference

tpm INI File Configuration

tpm uses an INI file to manage host configuration. This is the preferred deployment method and should be used instead of the Staging deployment method for new installations.

In order to configure Tungsten on your server using an INI file you must still complete all of the prerequisites. Copying SSH keys between your servers is optional but setting them up makes sure that certain scripts packaged with Continuent Tungsten will still work.

Creating an INI File​

Behavior Change

Behavior Change since 7.2.0.

The behavior of tpm changed from v7.2.0. Use the tab headings to ensure you follow the notes appropriate to the release you are using.

When using an INI configuration the tpm command, by default, expect the configuration to be in /etc/tungsten/tungsten.ini

If you wish to use an alternative path, filename, or have tpm use multiple files, then this can be achieved by supplying a comma-separated list using the --ini.

warning

Extreme care must be taken if using multiple ini files to ensure properties are not duplicated between files as there is no guarantee what order the properties will be applied and the end result may not always be what you expect.

The INI file(s) must be readable by the tungsten system user.

Example tungsten.ini
[defaults]
user=tungsten
install-directory=/opt/continuent
profile-script=~/.bash_profile
replication-user=tungsten
replication-password=password
replication-port=13306
application-user=app_user
application-password=secret
application-port=3306
rest-api-admin-user=apiuser
rest-api-admin-password=secret
install=true
connector-rest-api-address=0.0.0.0
manager-rest-api-address=0.0.0.0
replicator-rest-api-address=0.0.0.0

[alpha]
topology=clustered
master=host1
members=host1,host2,host3
connectors=host4
Show argument definitions
user=tungstenOS System User, for example tungsten. DO NOT use root.
profile-script=~/.bash_profileAppend commands to include env.sh in this profile script.
replication-user=tungstenUser for database connection.
application-user=app_userDatabase username for the connector.
application-password=secretDatabase password for the connector.
application-port=3306Port for the connector to listen on.
rest-api-admin-user=apiuserSpecify the initial Admin Username for API access.Available from v7.0.0
rest-api-admin-password=secretSpecify the initial Admin User Password for API access. rest-api-admin-password alias only available from version 7.1.2 onwards.Available from v7.0.0
install=trueConfigures services with systemd during installation. The same as executing deployall after installation.
connector-rest-api-address=0.0.0.0Address for the API to bind too.Available from v7.0.0
manager-rest-api-address=0.0.0.0Address for the API to bind too.Available from v7.0.0
replicator-rest-api-address=0.0.0.0Address for the API to bind too.Available from v7.0.0

Here is an example of a configuration file that would setup a simple dataservice.

The section name inside of the square brackets is used as the service name. The [defaults] section should always be included and is especially useful if defining multiple services in a single file where you want certain options to apply globally.

Service names should be Alphanumeric characters only, and may include a hyphen (-) or an underscore (_). No other special characters should be used. Whilst there is no enforced max length of string you can define, for simplicity and easy administration, service names should be kept short and meaningful, ideally 15 characters or less.

Include any host-specific options in the appropriate section. This configuration will only apply to the local server, so there is no need to put host-specific settings in a different section.

Installation with an INI File​

Once you have created the tungsten.ini file, the tpm command will recognize it and use it for configuration. Unpack the software into /opt/continuent/software and run the tpm install command, for example:

shell> cd /opt/continuent/software/tungsten-clustering-8.0.4-132
shell> ./tools/tpm install

or

shell> cd /opt/continuent/software/tungsten-replicator-8.0.4-132
shell> ./tools/tpm install --ini /my/directory/myconfig.ini

The tpm command will read the tungsten.ini file and setup all dataservices on the current server.

Upgrades with an INI File​

Use the tpm update command to upgrade to the latest version.

shell> cd /opt/continuent/software
shell> tar zxf tungsten-clustering-8.0.4-132.tar.gz
shell> cd tungsten-clustering-8.0.4-132
shell> ./tools/tpm update --replace-release
Important

The use of --replace-release is not mandatory for minor configuration changes, however it is highly recommended.

Using this option will ensure that underlying metadata and property files are cleanly rebuilt, thus ensuring any new or deprecated properties between releases are correctly added/removed acordingly.

After unpacking the new software into the staging directory, the tpm update command will read the tungsten.ini configuration and install the new software. All services will be stopped and the new services will be started.

The tpm update command may cause a brief outage while restarting the connectors. This will occur if you are upgrading to a new version. You can avoid that with:

shell> ./tools/tpm update --replace-release --no-connectors

Afterwards, the connectors must still be restarted on each server to pick up the new version or any changes, this can be done when convenient, by running:

shell> tpm promote-connector

During the lifetime of the cluster, switches may happen and the current primary may well be a different node than what is reflected in the static ini file in the master= line. Normally, this difference is ignored during an update or an upgrade.

However, if a customer has some kind of procedure (i.e. automation) which hand-edits the ini configuration file master= line at some point, and such hand-edits do not reflect the current reality at the time of the update/upgrade, an update/upgrade will fail and the cluster may be left in an indeterminate state.

Important

The best practice is to NOT change the master= line in the INI configuration file after installation.

There is still a window of opportunity for failure. The update will continue, passing the CurrentTopologyCheck test and potentially leaving the cluster in an indeterminate state if the master= option is set to a hostname that is not the current primary or the current host.

Configuration Changes with an INI File​

The tpm update also allows you to apply any configuration changes. Start by making any necessary changes to the tungsten.ini file. Then proceed to running tpm update.

shell> cd /opt/continuent/tungsten
shell> ./tools/tpm update

If you configured the profile-script option in your INI file, then the environment will be configured with aliases and PATHS set, therefore you can also simply execute:

shell> tpm update

If you are making significant changes such as adding/removing nodes or you are changing hostnames, then it is recommended to execute the update from the software staging path to ensure all metadata files are updated correctly, for example:

shell> cd /opt/continuent/software/tungsten-clustering-8.0.4-132
shell> ./tools/tpm update --replace-release

This will read the tungsten.ini file and apply the settings. The tpm command will identify what services likely need to be restarted and will just restart those. You can manually restart the desired services if you are unsure if the new configuration has been applied.

Tungsten Clustering Users

The tpm update command may cause a brief outage while restarting the connectors. This will occur if you are upgrading to a new version. You can avoid that with:

shell> ./tools/tpm update --replace-release --no-connectors

Afterwards, the connectors must still be restarted on each server to pick up the new version or any changes, this can be done when convenient, by running:

shell> tpm promote-connector