Node and Gateway Set Up

From xx network wiki
Jump to navigation Jump to search
This is a team contributed page

Below you will find the instructions for setting up a Node and Gateway on the xx network for the first time. These instructions detail how to install both a Node and Gateway on separate machines along with the xx chain software. Follow the instructions once for each machine.

The installation instructions assume that your machine has an active internet connection and an empty storage drive or a drive that can be written over with enough space as outlined in the Hardware Requirements.

Overview

Setting up xx Node Gateway, and chain is not particularly difficult, but due to the number of components, can take up to 2 hours. The steps for setting up a Node and Gateway are almost identical and the instructions can be followed for both. The general steps for setting up the xx software are:

  1. Install the operating system
  2. Synchronize the system clock (NTP)
  3. Configuring the local network
  4. Install the GPU drivers (if setting up a Node with GPU)
  5. Install and configure the Node and Gateway software
  6. Generate TLS credentials
  7. Install and configure the databases
  8. Set up and start the services
  9. Backup important files
    Make sure to not skip this important step!

Some Tips for Inexperienced Users

If this is your first time using a command line interface or you do not remember how to use it, the following are some tips to make using the interface a little easier.

  • In this document, anytime code is presented in a black box with monospaced font it means that it is command line input or output. Commands prefixed by a $ are commands that you should enter into your command prompt (do not include $ in the command). Any lines without that prefix are output from the system.
  • The sudo command is often prepended to commands found in these instructions. This enables commands to be run with elevated privileges. When used, the system will ask for your password to continue running the command.
  • Whenever the system asks for a password to continue, no characters will appear when typing, but type in your password and press Enter and it will work.
  • When typing a command or path, use the Tab key to auto complete a partially written statement.

Installing the Operating System

The xx network software has been tested only on Ubuntu Server 18.04. We cannot guarantee support if a different operating system version is used, although no decisions have been made to specifically preclude any operating systems.

  1. Download Ubuntu Server install image from the Official Ubuntu website.

    Click on the link "64-bit PC (AMD64) server install image" to download the Ubuntu Server image.
  2. Next, a bootable disk with Linux needs to be created. This can be done by writing it to a DVD or more commonly, a flash drive. Follow one of the following tutorials on how to do so depending on your current operating system and chosen media.

  3. Once your flash drive or DVD are ready, follow the Tutorial on Installing Ubuntu Server.

    1. In step 6, make sure you select the first option Install Ubuntu.

    2. In step 7, make sure to configure your internet connection and get an IP address.

    3. In step 8, ensure that you select Use an Entire Disk.

    4. In step 12, pick a server name that does not have any personal identifying information and select a strong password.

      Create a strong but memorable password. It is recommended that it is longer than 12 characters. Store this password in a safe and secure location. Never share this password with anyone.
  4. Make sure the machine has turned back on and login using the credentials created in the previous step. Sometimes extra text will be printed and you will not be able to see the login prompt. The prompt should still be there; just type your username and press Enter to continue.

Check Internet Connection

The rest of the instructions require internet access. Follow these steps to ensure the machine is connected.

  1. Check your current local connection status and local IP address.

    This should result in a similar output to below. The machine should have a valid local IP address.

  2. Finally, check that the machine has access to the internet by pinging another server. We chose to use xx.network, but you can use any domain.

    If the machine is connected to the internet, the output should look similar to the following example.

Updating Software and Installing Dependencies

To ensure all the software works correctly, the system needs to be updated. In addition, an additional dependency for the Wrapper Script to function.

  1. Before continuing, check for updates. This will print many lines about what software is being checked.

  2. Once the check is done, install the updates.

  3. Reboot the machine to ensure all updates are installed fully. Once the machine starts up, log back in.

  4. Install the Python package installer.

  5. Update the package installer.

  6. Install the boto3, pyOpenSSL, and substrate-interface dependencies. The Wrapper Script uses the first package to read commands and send logs to xx network through AWS and the second is used to authenticate them. The third, substrate-interface, is used to interact with the Substrate node.

Setting Up UFW

Uncomplicated Firewall (UFW) is the default firewall configuration tool for Ubuntu. UFW should already be installed; the following instructions will describe how to enable it and allow the correct ports to be open.

  1. First, ensure that UFW is disabled so that it can be configured.

    This should result in the following output.

  2. Allow the port that the Node will use to communicate on over TCP. Only do this for machines running the Node software.

    Port 11420 is the default port in the provided Node configuration file. A different port may be used, but it must be configured in node.yaml, which is downloaded in a future step.
  3. Allow the port that the Gateway will use to communicate over TCP. Only do this for machines running the Gateway software.

    Port 22840 is the default port in the provided Gateway configuration file. A different port may be used, but it must be configured in gateway.yaml, which is downloaded in a future step.
  4. If you want to manage your node remotely, you may want to allow port 22 over TCP for SSH. SSH should only be enabled with key authentication. Improper SSH setup can allow unwanted access so take care when setting up remote access. If you do not want to use SSH or do not know how to, then skip this step.

  5. Finally, enable UFW.

    If you are connected over SSH, you may be prompted to continue, press Y. Note that you may be disconnected when doing so.

Clock Synchronization (NTP)

Commands received from the Permissioning server are time-stamped and a synchronized clock is important to properly interpret them. To do so, NTP (Network Time Protocol) must be set up and synchronized.

In Ubuntu Server 18.04, this is done through timedatectl. In most installations, it is already running and Node operators only need to check that it is correctly configured. However, the process for other operating systems may be different and it will need to be enabled.

  1. Check if the time synchronization service is running and that the clock is synchronized by entering the following command.

    This will print the following output.

    1. If System clock synchronized is set to yes and systemd-timesyncd.service active is set to yes, then no further action is needed. Skip to the next section Modifying Max Number of Processes and Files. Otherwise, continue to the next step.

    2. If System clock synchronized is set to no and systemd-timesyncd.service active is set to yes, then the service has had insufficient time to synchronize the clock. Skip to the next section Modifying Max Number of Processes and Files but make sure to check that the clock is synchronized before starting the Node or Gateway software. Otherwise, continue to the next step.

      Ensure the time is synchronized before starting the software in the System Services section.
    3. If System clock synchronized is set to no and systemd-timesyncd.service active is set to no, then the service must be manually started in the next step.

  2. Enter in the following command to get a list of time zones.

    This will print a list of time zones. Use the up key and down key to navigate the list and find the time zone that the machine is in. Once found, make a note of the time zone, and press Q to exit.

  3. Once the correct time zone for the machine is found, use the following command to set it.

  4. Using the date command, ensure that the correct time zone was selected. If the printed time is incorrect, return to step 2 to select a new time zone.

  5. Begin the clock synchronization service by entering the following command.

  6. Ensure that the service is running by calling timedatectl again.

    If systemd-timesyncd.service active is set to yes, then it has been successful. If System clock synchronized is set to yes, then this section is done. If it is set to {{inline-code|no||, then it may take up to 30 minutes for the clock to synchronize. You can continue to the following section, but make sure to check that the clock is synchronized before starting the Node or Gateway software.

Modifying Max Number of Processes and Files

By default, there is a maximum number of processes and files that can be opened at once. To prevent the Node and Gateway from encountering this limit, it must be removed for all users.

  1. To remove this limit for users, open the limits configuration file using nano or your favorite text editor.

    The following process of using the nano text editor to modify a file is used elsewhere in this document. Refer back here for detailed steps on how to use it.
  2. Once the file is open, use the down arrow key to go to the second to last line above where it says # End of file. Add the following four lines above that line.

  3. To save the file, press Ctrl+X and when prompted to save the buffer, press Y.

  4. Finally, when prompted with the file name, press Enter to exit.

  5. Once the change has been made, reboot the system.

Configuring TCP Networking Options

The congestion window size limits the maximum amount of data sent out to a network after a time of little operation. The default size needs to be increased to remove a bottleneck in the xx network.

This change is necessary for the xx network because the cMix protocol transmits in short bursts. As a result, the congestion windows contract between transmissions, causing them to need to reopen on every transmission, significantly slowing down the network in high latency environments.

The following instructions are required to be completed on both the Node and Gateway machines.

  1. First, to prevent the congestion windows from shrinking unnecessarily when the connection is idle, disable tcp_slow_start_after_idle.

  2. To make these settings persist across reboots, store them in the sysctl configuration file.

  3. Modify the TCP congestion control algorithm (CCA) to use TCP Bottleneck Bandwidth and RRT (BBR).

  4. Modify the default queuing discipline to be fq; this is required to use BBR.

  5. Apply these two options to sysctl.conf so they persist on reboot.

Optional Configuration to Make Initial Connection Not Slow

While disabling tcp_slow_start_after_idle will keep the congestion windows large after connections are used a few times, you can optionally modify the initial congestion window size using the following instructions to make the minimum congestion window size large enough for cMix batches.

Please note that these changes can have negative effects in other areas of network performance, so it is generally not recommended to use these settings and you should only change these options if and only if you are certain that the rest of your network will work with these new settings.
  1. First, set congestion windows size on sending and receiving to be 700 times the maximum segment size.

  2. Store the above command in /etc/rc.local, to make it run on boot.

Note, if this fails to work or causes problems, such as increased timeouts or instability, remove the file and reboot.

Configuring Local Network (Port Forwarding)

To ensure that the machine can be accessed from outside the local network, the network’s router or gateway must be configured to allow external access to the machine on ports configured above. Three main pieces of information are needed for this part: (1) the port numbers to forward (the defaults are 11420 and 22840), (2) the protocol to use (TCP), and (3) the local IP address of the machine, which is retrieved below.

  1. Get the local IP address of the machine. If Node and Gateway are being run off separate machines on the same network, then run this on both machines.

    The local IP address will be printed; it will be in the form of 0.0.0.0. Make sure to make note of this for the later steps.

    If the machine has multiple network interfaces or an IPv6 address, they will also appear in this list. Ensure that only the correct internal IPv4 address is used.


The following section describes how to configure the networking equipment on your network. Because of the varying type of equipment configurations, these instructions are generic and may not be accurate for your hardware. Please refer to the manufacturer’s instructions for more detailed and accurate information. Configuration of the network will most likely occur from a different machine on the network.
  1. To access the router to configure, its IP address is needed.

    This will output the following line, where the first address printed is the router IP address.

  2. Go to this IP address in a browser (on a different machine) and login using the router credentials. These credentials are either set up by the network administrator or are the default credentials located on the router or found online.

  3. Locate the port forwarding options (occasionally called virtual server). These options are sometimes found under the advanced section.

    Before forwarding the port found above, you may want to provide a static local IP address to the machine. However, that is outside the scope of these instructions.
  4. Add the new ports to forward for the Node and Gateway. For each, create a new entry and enter the IP address found in step 1, set the port to the chosen ports (by default it is 11420 for Node and 22840 for Gateway), and select the TCP protocol. Make sure to save or apply the changes.

GPU Drivers

The Node software requires a Nvidia RTX graphic processor and the installation of its drivers.

  1. Install the Nvidia driver.

  2. Once the installation is complete, reboot the system.

  3. Once the system reboots, log back into the computer.

Verifying the Driver Installation

  1. Check that the system has claimed the device.

    This should result in a similar output to the following.

  2. Next, check the driver and state information.

    This should result in a similar output to the following.

Node and Gateway Software

  1. Change the working directory to /opt/.

  2. Download the tarball for Node and/or Gateway using curl with the following URLs. The newest versions can also be found on the xx network website.

    For Node:

    For Gateway:

  3. Next, the downloaded files need to be extracted to the /opt/ directory. Use tar extract them with the flags -xf so that the directory structure remains intact. This will create a new /opt/xxnetwork/ directory with the extracted files inside.

    For Node:

    For Gateway:

    Both node.tar.gz and gateway.tar.gz contain some files that are the same (e.g., xxnetwork-wrapper.py). When extracting both files, it is expected that these files will be overwritten. Order of extraction does not matter.
    If this command produces an error similar to not in gzip format, then that means the file did not download correctly in the previous step. Try downloading the file again and ensure the URL is correct.

    The file needed to install the software are in the newly created /opt/xxnetwork/ directory. Those files are:

    Node Gateway Note
    bin/xxnetwork-node bin/xxnetwork-gateway The binary for Node or Gateway.
    node.yaml gateway.yaml The configuration file for the binary.
    xxnetwork-node.service xxnetwork-gateway.service systemd service file.
    xxnetwork-wrapper.py xxnetwork-wrapper.py A management script for the binary.
    generate_certs.py generate_certs.py TLS certificate/key generator script.
    creds/network_management.crt creds/network_management.crt The TLS certificate used to authenticate commands sent to the Wrapper Script.
    creds/permissioning_cert.crt creds/permissioning_cert.crt The TLS certificate for Permissioning.
    lib/libpowmosm75.so GPU dependency (for Node only).
    lib/libpow.fatbin GPU dependency (for Node only).

Generate TLS Credentials

TLS credentials for the Node and Gateway are critical to its identity in the network. For more information refer to Cryptographic and Network Primitives. If running Node and Gateway on different machines, then generate the certificates on the Node machine and copy the necessary credentials to the Gateway server.

The two TLS credentials (a certificate and private key pair) generated in the following section are extremely important to back up and store securely. Loss of these files will make it impossible to reconnect a Node to the network. In following the default configuration, these files are named node_cert.crt, node_key.key, gateway_cert.crt, and gateway_key.key. In addition, it is important to back up the file nodeIDF.json, which is generated on the initial run. Refer to the Lost Certificate and Important Files Policy for more information.
  1. Using the provided generate_certs.py script, generate the TLS certificates and keys for Node and Gateway. It will provide prompts for all the information required. Start the script using Python 3. Note that this must be run inside the /opt/xxnetwork/ directory.

    You do not need to use this script to generate the required TLS credentials. Use the requirements in the TLS Credentials section of Cryptographic and Network Primitives to ensure the generated certificates meet the network requirements.
  2. The script will launch and query for various information to create the credentials for Node and Gateway. If you choose not to provide any details, default values will be used. After every answer press Enter.

    Once all the details have been provided, the certificates will be generated and moved into creds/.

  3. To check that all the correct files are in the creds/ directory, use ls to list the files.

  4. If running Gateway on a separate machine from Node, then copy gateway_cert.crt, gateway_key.key, and node_cert.crt to the Gateway machine and delete gateway_key.key from the Node machine.

Configuring Node and Gateway

Configuring Node and Gateway requires modifying their respective YAML files retrieved in the previous steps. These instructions go over the basic configuration to get a Node and Gateway working in the default state. Refer to the Server and Gateway README files to learn more. Note that all addresses must be IPv4; IPv6 is not currently supported.

If you are currently configuring the Node on its own machine, then proceed to Node Configuration.

Gateway Configuration

The default gateway.yaml file only requires setting the address of its Node. However, there are other optional flags for non-standard configurations. Database information is set in a later step.

  1. Get the IP address of the Node. If the Node is being run on the same machine as Gateway, then this IP address is 0.0.0.0:port (where the default port is 11420). If the Node and Gateway are installed on separate machines, then you will need to get the Node’s public IP address, by running the following command on the Node.

    This should be run on the Node machine.
  2. The Gateway configuration file has to be modified to include this IP address. To do this, on the Gateway machine, open gateway.yaml in nano or your favorite text editor.

  3. Once the file is open, use the down arrow key to get to the line that says nodeAddress and replace the placeholder with the one found in step 1. Make sure to include the chosen port, as shown.

  4. For non-default setups and experienced users, the following options can be used.

    1. By default, the Gateway runs on port 22840; however, this can be modified using the port flag.

    2. The internal listening address of the Gateway defaults to 0.0.0.0. However, a different internal address can be set via listeningAddress. This expects an IPv4 address without a port; it uses the port from the port flag.

    3. The public IP of the Gateway, as reported to the network, is determined by pinging an external service. To override this or to avoid this outside communication, the public IP and port can be manually set via overridePublicIP. If no port is set, then the port from the port flag is used. This expects an IPv4 address only.

    4. If you placed the TLS certificate and key files in a different location than the default one in the Generate TLS Credentials, then modify the location via keypath, certPath, serverCertPath, and permissioningCertPath.

  5. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Node Configuration

The default node.yaml file only requires setting your registration code. However, there are other optional flags for non-standard configurations. Database information is set in a later step.

  1. Every Node operator will receive a unique registration code from [email protected] in order to join the network. The registration code will look similar to the following example.

    Example Registration Code: UvyGCZU8WP18PmmIdcpVmx00QA3xNe7sEB9Hixkk=

    The Node configuration file has to be modified to include this registration code. To do this, open node.yaml in nano or your favorite text editor.

  2. Enter this code into the registrationCode field between the two quotes "".

  3. For non-default setups and experienced users, the following options can be used.

    1. If the Node does not have a GPU, then set useGPU to false.

      Running a Node without a GPU is not a recommended configuration. Only do so if the CPU in the machine is very powerful.
    2. By default, the Node runs on port 11420; however, this can be modified using the port flag.

    3. The internal listening address of the Node defaults to 0.0.0.0. However, a different internal address can be set via listeningAddress. This expects an IPv4 address without a port; it uses the port from the port flag.

    4. The public IP of the Node, as reported to the network, is determined by pinging an external service. To override this or to avoid this outside communication, the public IP and port can be manually set via overridePublicIP. If no port is set, then the port from the port flag is used. This expects an IPv4 address only.

    5. If you placed the TLS certificate and key files in a different location than the default one in the Generate TLS Credentials, then modify the location via node > paths > cert, node > paths > key, gateway > paths > cert, and permissioning > paths > cert

  4. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Configure Service Files

To ensure that the Node and Gateway services are run as the correct user, they will need to be modified.

  1. The following steps require the machine’s username. For most users, this will be the username created and installation of the operating system. If you do not remember your username, use whoami.

  2. Open the service file for the binary being run. If both Node and Gateway are being run, this modification will need to be made with both files. Open either xxnetwork-node.service or xxnetwork-gateway.service with nano or your favorite text editor.

    For Node:

    For Gateway:

  3. Under the [Service] heading, after the User= field, modify the username to the one found in step 1.

  4. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

  5. Repeat step 1 through step 4 for the other service file if both Node and Gateway are being run.

Databases

Both the Node and Gateway require PostgreSQL databases. The Node database stores key pairs with clients while the Gateway database is used to store encrypted messages for users. The following instructions detail how to install PostgreSQL and set up the required databases for the two possible setups: running the Node and Gateway on the same machine and on separate machines. Follow the case pertaining to your setup and at the end make sure to Verify the Database.

Case 1: Node and Gateway Run on the Same Machine

These instructions are for Node operators who run the Node and Gateway software on the same machine. Note that a separate drive for the Gateway database is required that meets the hardware specifications. Before starting, prepare the second disk for the Gateway database by mounting and partitioning it. To learn more, refer to Adding the Gateway Database (One Computer Configuration) post on the xx network forum.

  1. Install PostgreSQL and its dependencies.

  2. Once the installation is complete, enable the PostgreSQL service.

  3. Next, start the service.

  4. Create a database user with the username cmix, which is used to access the database.

  5. You will be asked to set a password for the cmix user. Create a long and secure password but note that it will only be saved into the Node and Gateway configuration files in the following steps and you will not need to remember it once everything is configured.

    Never store this password digitally unless directed to do so by xx network. Never provide this password to anyone.

Node Database Setup

  1. Create the required database with the name cmix_node.

  2. Next, modify the Node configuration file to use the newly generated password in step 5 above. To do this, open node.yaml in nano or your favorite text editor.

  3. Under the field database > password, enter in the new password. If the database was created with a different username or database name, then update those values too.

  4. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Gateway Database Setup

  1. Determine the location to place the Gateway database. The following directions use /mnt/ts_gateway as an example path; replace it with the location on the secondary drive.

  2. Create a directory on the secondary drive to store the database in using mkdir.

  3. Change the ownership of the directory.

  4. Switch to the postgres user account.

  5. Run the PostgreSQL client server via psql.

    The command prompt has changed from $ to #.
  6. Once at the postgres prompt, create the tablespace and point it to the directory on the second disk drive (enter everything after the postgres-# part).

  7. Enter \q to exit the session.

  8. Enter exit to return back to your user.

  9. Create the Gateway database with the name cmix_gateway with the previously made tablespace.

  10. Finally, modify the Gateway configuration file to use the password generated when setting up the database user cmix. To do this, open gateway.yaml in nano or your favorite text editor.

  11. Under the field dbPassword, enter in the new password. If the database was created with a different username or database name, then update those values too.

  12. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Case 2: Node and Gateway are Run on Separate Machines

These instructions are for operators who run the Node and Gateway software on the separate machines.

Node Database Setup on Node Machine

Follow the instructions below on the machine running the Node software.

  1. Install PostgreSQL and its dependencies.

  2. Once the installation is complete, enable the PostgreSQL service.

  3. Next, start the service.

  4. Create a database user with the username cmix, which is used to access the database.

  5. You will be asked to set a password for the cmix user. Create a long and secure password but note that it will only be saved into the Node configuration file in the following steps and you will not need to remember it once everything is configured.

    Never store this password digitally unless directed to do so by xx network. Never provide this password to anyone.
  6. Create the required database with the name cmix_node.

  7. Next, modify the Node configuration file to use the newly generated password in step 5 above. To do this, open node.yaml in nano or your favorite text editor.

  8. Under the field database > password, enter in the new password. If the database was created with a different username or database name, then update those values too.

  9. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Gateway Database Setup on Gateway Machine

Follow the instructions below on the machine running the Gateway software.

  1. Install PostgreSQL and its dependencies.

  2. Once the installation is complete, enable the PostgreSQL service.

  3. Next, start the service.

  4. Create a database user with the username cmix, which is used to access the database.

  5. You will be asked to set a password for the cmix user. Create a long and secure password but note that it will only be saved into the Gateway configuration file in the following steps and you will not need to remember it once everything is configured.

    Never store this password digitally unless directed to do so by xx network. Never provide this password to anyone.
  6. Create the required database with the name cmix_gateway.

  7. Next, modify the Gateway configuration file to use the newly generated password in step 5 above. To do this, open gateway.yaml in nano or your favorite text editor.

  8. Under the field dbPassword, enter in the new password. If the database was created with a different username or database name, then update those values too.

  9. Once the change is made, save the file by pressing Ctrl+X and when prompted to save buffer, press Y. Finally, when prompted with the file name, press Enter.

Verify the Database

The following steps will describe how to ensure the database was created correctly. This section is optional but highly recommended.

  1. Login with the postgres account.

  2. Run the PostgreSQL client server via psql.

    The command prompt has changed from $ to #.
  3. Once at the postgres prompt, enter in \l to get a list of databases (do not enter the postgres-# part).

    Ensure that the correct databases with the correct owners show up. If Node and Gateway are on the same machine, then the output should appear similar to below. If each is being run separately, then only the cmix_node or cmix_gateway should be displayed.

  4. If Node and Gateway are run off the same machine, verify the gateway tablespace points to the directory on the second disk drive by typing \db to get a list of available tablespaces. Ensure that the tablespace ts_gateway has the correct location set.

  5. Enter \q to exit the command line.

  6. Enter exit to return back to your prompt.

System Services

This section describes how to install the service files for Node and Gateway. Follow only the instructions related to the type of machine you are deploying. Follow both Node and Gateway instructions if running both off of the same machine.

The following steps will start the Node and/or Gateway software and will have it join the xx network. If you do not want to do so currently, then do not do the following steps until you are ready.
  1. Before starting the Node or Gateway service, ensure that the clock is synchronized by entering the following command.

    This should result in the following output.

  2. If both System clock synchronized and systemd-timesyncd.service active are set to yes, then proceed to the next step. Otherwise, refer back to the Clock Synchronization (NTP) section.

  3. Next, soft link the systemd service file(s) to the systemd directory /etc/systemd/system/.

    For Node:

    For Gateway:

  4. Reload the systemd service files.

  5. To ensure that your user has the correct permissions, run the following command. Make sure to replace both instances of [user] with your username.

  6. Next, enable the service(s) for the appropriate binary.

    For Node:

    This should result in the following output.

    For Gateway:

    This should result in the following output.

  7. Then, start the services.

    For Node:

    For Gateway:

Verify the Service has Started

  1. First, check the status of the service to ensure it is running.

    For Node:

    This should result in the following output. Press Q to exit the output.

    For Gateway:

    This should result in the following output. Press Q to exit the output.

  2. Next, check that the process is running. If the commands result in the expected output, then the Node or Gateway process is running.

    This will print a list of running xx network processes. If xxnetwork-gatew appears on the list, then the Gateway process is running. If xxnetwork-node appears on the list, then the Node process is running.

    The PID (the first number printed) and the elapsed time will be different.



Backup Certificates and Important Files

Ambox warning pn.svg ATTENTION Ambox warning pn.svg


Lost Certificates Cannot be Recovered

Once the Node and Gateway are properly functioning, Node operators must backup some important files. Loss of these files will irreparably disconnect a Node from the network. Follow the instructions on the next page detailing how to do so.

Warning: The following instructions are extremely important to follow to ensure that your Node and Gateway can stay operating on the network. Failure to follow these instructions can lead to your Node or Gateway being permanently unable to operate on the network.
Warning: The files described below are sensitive as they identify your Node and Gateway uniquely. Anybody who gains access to these files can appear on the network as your Node or Gateway. It is extremely important to keep these files secure as any third party access can lead to the compromising of your Node and Gateway’s identity.

There are six files that your Node/Gateway requires to authenticate itself on the network. Loss of these files will lead to your Node or Gateway being unable to participate in the network and regeneration of these files is contingent on the policy outlined above. Therefore, every Node Operator must backup these files to a secure location not on the same machine. It is recommended that these files be backed up to multiple secure locations. For example, a flash drive or secure cloud storage.

Backing Up Files

  1. Locate the six files that must be backed up. If you used the default paths in the configuration instructions, then these files can be found according to the table below.

    File Default Name Default Location
    1. Node’s public certificate node_cert.crt /opt/xxnetwork/creds/
    2. Node’s private key node_key.key /opt/xxnetwork/creds/
    3. Node’s ID file (IDF) nodeIDF.json /opt/xxnetwork/node-logs/
    4. Gateway’s public certificate gateway_cert.crt /opt/xxnetwork/creds/
    5. Gateway’s private key gateway_key.key /opt/xxnetwork/creds/
    6. Gateway’s ID file (IDF) gatewayIDF.json /opt/xxnetwork/gateway-logs/

    If you cannot locate the files, then their paths can be found in the Node and Gateway YAML files as shown in the table below.

    File YAML File Flag
    1. Node’s public certificate node.yaml node.paths.cert
    2. Node’s private key node.yaml node.paths.key
    3. Node’s ID file (IDF) node.yaml node.paths.idf
    4. Gateway’s public certificate gateway.yaml certPath
    5. Gateway’s private key gateway.yaml keyPath
    6. Gateway’s ID file (IDF) gateway.yaml idfPath
  2. The easiest method to copy these files off of the machine is to use a USB flash drive; you can use the same one that you may have used to install the operating system. First, insert the flash drive and then run lsblk to find the mount point of the flash drive.

    This should output a list of mount points on your computer. Locate the name of the flash drive. This can be done by looking at the size and finding which mount point has the same size as your flash drive.

  3. Copy all six files to the flash drive path found in the previous step. If your files are in the default locations, it will be similar to the following command.

    To copy one file at a time, use the following command.

  4. Once the files are copied, remove the flash drive, and save it in a secure location. We highly recommend that you back up these files in at least one other location.

    Ensure that these files only exist in secure locations. If anyone gains access to these files, your Node and Gateway’s identity on the network can be compromised.