KSS Cluster deployment

The "Cluster Mode" feature has been added to the Quantum Quetzalcoatl version of Atakama to meet higher demands for automated processes and backups. This mode creates and connects multiple Keyshard Server instances. 

To use Cluster Mode, a shared MySQL database must be available to all instances, and the machine hosting the database and all the Keyshard Server instances must be connected to the same network. 

When instances join the shared database, they will share the same Keyshard Server ID and provide the same services. If one instance goes offline, the other instances will help resolve MofNop requests.

MySQL installation:

MySQL is an open-source database management system used by our software to create a shared database between multiple Atakama profile users to fulfill the Cluster environment with our Key Shard Servers. MySQL can be downloaded by clicking here

Downloading the application installer will suggest creating an account to download it, but this can be skipped by clicking “No thanks, just start the download.”

Before installing MySQL, it is important to open port 3306 on the computer that will store the database. The steps for opening the port are the following:

  1. Go to Start > Control Panel > Select “System and Security”.

  2. In “System and Security”, select “Windows Defender Firewall”.

  3. Check the left sidebar and click on “Advanced Settings”, this will open the “Windows Defender Firewall with Advanced Security”.

  4. Right-click “Inbound Rules” on the left sidebar and select “New Rule”.

  5. On the Wizard window, select the following options:

    1. Rule type: Port.

    2. Does this rule apply to: Select TCP.

    3. Does this Rule apply to all local ports or specific local ports?: Specific Local ports - 3306.

    4. Action: Allow the Connection.

    5. Profile: Domain, Private, and Public.

    6. Name: MySQL. 

    7. Click "Accept" to open the port.

After opening port 3306 for MySQL, proceed to continue to install the application.

  1. Proceed to launch the “MySQL” installation program (a MSI installer).

  2. On the first tab, it is recommended to choose the setup type: “Full” and click next.

  1. After we get into the “Check requirements” step, click Execute to proceed to install the necessary products for MySQL.

  1. At some point, the "Microsoft Visual C++ 2015-2019 Redistributable (x64)" popup will appear. Check the box "I agree to the license terms and conditions" and click "Install".

  2. Close the window of "Microsoft Visual C++ 2015-2019 Redistributable (x64)" after installation.

  3. After installing the products and any additional programs, click multiple "Next" on the MySQL installer until it gets the user into the "Accounts and Roles" tab. It's recommended to add a strong root password. Finally, continue clicking "Next" until it gets the user into the "Apply Configuration" tab. Execute and finish the created configuration.

  1. For MySQL router configuration, it can be skipped by clicking the "Next" button till it gets to the "Connect to Server" tab.

  2. The "Connect to Server" tab will require the user to connect to the server by using the "root" username, adding the password added in step 6, and clicking on the "Check" button to confirm the connection. Click "Next" once it's available. Apply configurations by clicking "Execute" on the next tab.

  3. Once the last configurations have been applied, click on the "Finish" button to finalize the installation. This will require you to click on a "Next" button and finally the last "Finish" button. This is going to start both the "MySQL Shell" and the "MySQL Workbench".

Database creation Security Recommendations for MySQL Database:

In terms of security configurations for MySQL, it's worth noting that Atakama exclusively supports mysql_native_password  command configurations. Unfortunately, Atakama doesn't currently support MySQL8 default configurations: sha265_password  or caching_sha265_password. For more comprehensive information regarding MySQL security, we recommend following the security guide provided by MySQL.

To ensure the reliability of the KeyShard Server Clusters which rely entirely on this database for their functioning, Atakama highly recommends using resilient deployments for the database. MySQL offers a variaty of resources covering Backup and Recovery Features and the Creation of Cluster Environments for its Database

Database creation

The creation of a database for the KSS Cluster is required and can be done by launching MySQL Command Line Client and executing the following commands:

create database cvfs;

create user '[User]'@'%' identified by '[Add password here]';

grant all privileges on *.* to '[User]'@'%' with grant option;

flush privileges;


Checking the Database in MySQL Workbench

After the database has been created, users can check the newly added database by launching "MySQL Workbench".

Accessing the Workbench will show the local instance that was created during the installation of MySQL, and it can be accessed by using the same credentials that were created during the installation process.

Once the local instance has been accessed, the database can be found on the left sidebar by clicking on the "Schemas" tab.

The "Schemas" tab should show the "cvfs" database, which should be empty until Atakama creates the Keyshard Server and accesses the database.

If necessary, the database can be deleted by right-clicking on the database and selecting the option "Drop Schema...>Drop Now".

Onboarding a new Keyserver with the shared database

To connect to the shared database from another computer within the same network that has Atakama installed, open either the cmd or Powershell and run the following command:

atakama keyserver create [--db-uri URI] [--backup-path PATH] [--policy-path PATH]  [--ignore-security-checks] 

(--ignore-security-checks is optional)


atakama keyserver create --db-uri "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs") --policy-path [path to the policy file]  [--ignore-security-checks]

The backup key for the KeyShard Server should be created within the %homepath% directory. In case the previous backup key is missing or not found, the following command can be used to create a new KSS backup key:

keyserver save-backup-key [PATH] 
keyserver save-backup-key "%homepath%\backup-key.txt"
The setup will require a minimum threshold of three (3) devices and five (5) total devices as part of the profile unless the --ignore-security-checks flag is passed.

Keyserver should now be enabled using MySQL. To confirm, check the MySQL “cvfs” database and see that the tables are now populated with data. 

Keyserver Instance Initialization

If a Keyshard Server Instance has been already created in a shared database, you can add new instances on different machines by installing atakama on those machines, adding the Keyserver.yml from the first Keyshard Server Instance to %localappdata%/atakama, and using the following commands in cmd or Powershell:

 First, it's important for admins to activate the license using the command:

atakama settings update-license [Add enterprise license key]

After adding a license, you can continue initializing by using:

atakama keyserver initialize --db-uri [--db-uri URI]


atakama keyserver initialize --db-uri "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs")

In order to join the Keyshard Server Cluster, the MofNop approval process must be completed by the 3 devices that were used to approve the first Keyshard server instance that created the database.

Once the MofNop request is approved, a message "Keyshard server initialized: restarting Atakama" will appear in the terminal. This message confirms that the Keyshard server instance has successfully joined the Keyshard Server Cluster.

Converting a non-cluster Keyshard Server to Cluster Mode

To upgrade a non-cluster keyshard server to cluster mode, you need to be using the Quantum Quetzalcoatl version of Atakama. It's important to upgrade from any previous versions of Atakama to this version or newer to perform this action.

To activate cluster mode, you need to create a shared database and connect the keyserver to it.

To start the upgrade process, first shutdown the server, and then execute the following command in a terminal (such as cmd or Windows Powershell):

keyserver clone-db [NEW_URI]


atakama keyserver clone-db "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs"

Once this command line is executed, this keyserver will start using the shared database and the cluster mode will be activated. It should be possible to initialize additional Keyshard Server Instances.

Checking Key Shard Server Cluster Status

All Key shard server instances in Cluster mode have the capacity to check the status of other instances, by using the command:

atakama keyserver instance list

The command will show both the Keyshard Server Instance ID and its status (Online/Offline).

Additional Commands

Enabling/Disabling the Key Shard Server

All request responses can be disabled via the command

atakama keyserver disable

When the KSS is disabled, you must use the command to re-enable it

atakama keyserver enable
To see the status of the KSS and to retrieve its ID, use the command
atakama keyserver status
These commands work for both a regular Key Shard Server and Key Shard Server instances in Cluster Mode.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.