Maintaining a Symbol Node

Once you have created a Symbol node, be it manually or using Symbol bootstrap, the node is mostly autonomous. But there is still a little bit of maintenance required, explained in this guide.

 

Server updates

New Symbol server versions will be released periodically. If you want to benefit from the added features and bugfixes you will need to update your node to use the latest server version.

Additionally, if your node’s server version falls too far behind, other nodes might refuse to connect to it.

The main version to keep track of is the Catapult Server version, since this component is used by all peer nodes. Additionally, API nodes need to keep track of the REST component version too.

  • Finding out what are the latest versions:

    Whenever there is a new server version released it will be announced through the NEM Forum and the Slack channel. You can also keep an eye on the different GitHub repositories and the compatibility matrix page to know the latest Server and REST versions.

  • Finding out your node versions:

    You can find the versions used by your node in the Symbol Explorer nodes list.

    Additionally, if your node is an API node, you can also query it directly:

    • Server version: /node/info endpoint, version property. See an example.

      Note

      The version is encoded as a single 4-byte integer, where the Most-Significant Byte encodes the Major version, and the rest of bytes are the Minor, the Micro and the Patch version.

      For example, version 16777472 (decimal) is 01000100h (hex), which corresponds to version 1.0.1.0.

    • REST version: /node/server endpoint, restVersion property. See an example.

      restVersion is a version string like “2.3.6”, for example.

The exact procedure to update your node depends on how you created it. Read the appropriate section below.

Update nodes created with Bootstrap

If you used Symbol Bootstrap to create your node (following the Running a Symbol node guide), keeping it up to date is very simple.

  1. Update Symbol Bootstrap first (see the Using Symbol Bootstrap guide for more details):

     npm install -g symbol-bootstrap

  2. Then move to the folder where the node’s data folder is (typically target) and make a backup copy of it:

     cp -r target target.BAK

  3. Finally, stop and restart the node with the --upgrade flag to update all necessary component versions.

    The exact commands depend on whether your node was running in detached mode or not:

    • If you started in detached mode with symbol-bootstrap start -d:

      From the folder containing the target folder type:

       symbol-bootstrap stop
symbol-bootstrap start --upgrade -d -c custom-presets.yml

    • If you did not start in detached mode:

      You must have a terminal running somewhere with all the output from the server. Stop it by pressing Ctrl+C and then type:

       symbol-bootstrap start --upgrade -c custom-presets.yml

  4. Once the node is up and running again, and you verify that the component versions have been updated, you can remove the backup copy.

Update nodes created manually

If you followed the Running a Symbol node manually guide, you need to rebuild the Catapult Server and keep the previous data folder so the same accounts and cached data is reused.

In summary, you need to:

  • Stop the running Catapult Server with Ctrl+C.
  • Update the Catapult Server source repository with the latest version and build it again following the Catapult Server instructions.
  • Restart the server from the same folder it was initially launched. Data and configuration files will be reused.

Note

The above procedure works but brings the server offline while the new version is being built, which could be a lengthy process.

If you install the server (with make install) instead of running it from the same folder where it is built, though, you have the option to build the new version while the previous one is still running. In this way the service interruption should be minimal.

The steps then would be:

  • Update the Catapult Server source repository and build it again.
  • Stop the running Catapult Server.
  • Install the new version of the server.
  • Restart the server.
 

Voting key renewal

If your node is a Voting node it requires a valid voting key to operate. For security these keys expire after 6 months, so you need to renew them as part of the regular node maintenance.

Read the appropriate section about renewing the voting keys depending on whether you used Symbol Bootstrap or not to build your node: