upgrading - Migration

Possible Migration

New versions of nodectl can offer three main purposes:

1. Bug Fixes
2. Security Fixes
3. Feature Updates

In some cases, if a new feature is offered, it may require that we update nodectl's main configuration file cn-config.yaml.

This will allow nodectl to work with the new features while persisting your current configuration setup.

No Migration Needed

If you receive the following message (shown in the window below 👇) you can continue reading this section of the documentation.

If you do not receive the migration message, you can skip this step and move to the next section upgrading - Continue.

Migrate Configuration

We received the following banner, so we can continue to migrate our Node.

========================================
= CONSTELLATION NETWORK HYPERGRAPH     =
=             VERSION 2.0              =
=        CONFIGURATION MIGRATION       =
========================================
Code Name: Princess Warrior

During program initialization, an outdated and/or improperly formatted configuration file was found on this server/Node.

nodectl will backup your original configuration file and attempt to migrate to the new required format.

It is very important to migrate the configuration, otherwise you will most likely encounter a configuration error message, and nodectl will terminate.

Start Migration

We can press Enter to accept the default y.

Attempt update and migrate configuration file? [y]:

Backups

You will see the migration start with a backup of our current configuration.

Backing up cn-config yaml ..................... complete

You will get a warning message to remind you that the backup can introduce a possible vulnerability. This is because it may contain a clear text passphrase.

DANGER The backup configuration YAML file MAY CONTAIN A P12 PASSPHRASE, FOR SECURITY PURPOSES, PLEASE REMOVE AS NECESSARY!

Good Practice

It is good practice to keep the backups when asked to clear them (say n), test your Node's functionality to ensure you maintain full access to your Node's features, and then remove.

Later in the upgrade process, after the migrator is completed, you will receive another warning from the upgrader asking you if you want to remove your backups.

It is important to remember, if you choose yes you will lose the ability to recover the configuration.

We will be reminded again in this documentation, so we do not have to worry about it at this point in the upgrade process.

CAUTION After the migration is complete, the upgrader will continue and will prompt you to remove the contents of the backup directory where the original configuration YAML file has been backed up within.

If you choose to empty the contents of this directory, you will remove the backup configuration YAML file file.

You will see information the backup that was created.

note

nodectl will backup the configuration multiple times depending on which modules are activated during the upgrade.

backup filename: backup_cn-config_2024-XX-XX-XX:XX:XXZ
backup location: /var/tessellation/backups

Migration Complete

The migrator will show a successful completion.

Creating configuration file ................... complete

cn-config.yaml upgraded
MIGRATION COMPLETED SUCCESSFULLY!!

You will be offered the opportunity to review the configuration file changes.

This is an optional step to help you get acquainted with the values in the configuration file, however it is not necessary. Although we will choose n here, you may choose y and page through the configuration using the Enter to progress or the q+Enter to quit the process at any time and return to the next steps.

We will say press Enter to accept the n default answer.

Ready to continue with upgrade

Would you like to review your new configuration? [n]:

nodectl will continue to the actual upgrade process.