Node 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 the xx Node with the cMix and xx chain software for the first time. These instructions are only for the Node. For instructions for setting up a Gateway, refer to Gateway Set Up.

The installation instructions assume that your machine meets or exceeds the Node Hardware Requirements and that it is configured per the Operating System Installation and Configuration instructions.

Overview

Setting up cMix and xx chain is not particularly difficult, but it can take up to 2 hours due to the number of components. The general steps for setting up the xx software are:

  1. Install and configure the operating system (with the GPU drivers)
  2. Install and configure the cMix and xx chain software
  3. Generate TLS credentials
  4. Install and configure the database
  5. Set up and start the services
  6. Backup important files
    Make sure not to skip this critical step!

Before Starting

Before installing the software, make sure that:

  1. Your Node machine meets or exceeds Node Hardware Requirements.
  2. You have followed the Operating System Installation and Configuration instructions.
  3. You have installed GPU drivers.

Download Software

  1. Change the working directory to /opt/.

  2. Download the tarball for Node using curl with the following URL. The newest versions can also be found on the xx network website.

    The download progress will be printed similarly to below.

  3. Optional: To verify that the integrity of the downloaded tarball, you can verify that its SHA256 checksum matches the checksum provided on the xx network website. Run the sha256sum to generate the checksum.

    If this command produces an error similar to No such file or directory, then the file name is incorrect or the file did not download correctly in the previous step. Try downloading the file again and ensure the URL is correct.

    The checksum and file name are printed. Make sure to verify that the checksum matches the checksum on the xx network website.

    If the checksums differ, then try downloading and checking the checksum a two more times. If the checksums still differ, then contact the team.
  4. Next, extract the Node tarball to the /opt/ directory. Use tar to extract it with the flags -xf so that the directory structure remains intact. This will create a new /opt/xxnetwork/ directory with the extracted files inside.

    If this command produces an error similar to not in gzip format, then the file did not download correctly in the previous step. Try downloading the file again and ensure the URL is correct.

    It will print out all the files extracted to the newly created /opt/xxnetwork/ directory. Those files are:

    File Note
    bin/id-generation Binary used to generate cMix identity.
    bin/xxnetwork-chain The binary for the xx chain software.
    cmix-wrapper.py A management script for the cMix binary.
    config/cmix.yaml The configuration file for the cMix binary.
    cred/network-management.crt The TLS certificate used to authenticate commands sent to the Wrapper Script.
    cred/scheduling-cert.crt The TLS certificate for communicating with the Scheduling server.
    generate-certs.py TLS certificate/key generator script.
    xxnetwork-chain.service systemd service file for the xx chain binary.
    xxnetwork-cmix.service systemd service file for the cMix Wrapper Script.
  5. Next, make the binaries executable.

Generate Identity Information

The two TLS credentials (a certificate and private key pair) and Node's IDF generated in the following section are extremely important to back up and store securely. Loss of these files will make it impossible to reconnect your Node to the network. If following the default configuration, then these files are named cmix-cert.crt, cmix-key.key, cmix-IDF.json, gateway-cert.crt, and gateway-key.key. Refer to the Lost Certificate and Important Files Policy for more information.

Each Node and Gateway is identified by its ID (contained in an ID File or IDF) and TLS certificate (a public certificate and private key pair). TLS credentials for the Node and Gateway are critical to its identity in the network.

The provided script generate-certs.py automatically generates the Node and Gateway TLS certificate pair and the Node's ID and IDF. The TLS certificates can be manually generated using the info in Cryptographic and Network Primitives. The Node's IDF can be generated using the provided id-generation binary.

Once generated, the Node's and Gateway's public certificates are copied and the private key is moved to the Gateway machine.

  1. Using the provided generate-certs.py script, generate the TLS certificates and keys for Node and Gateway and Node's IDF. 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 and IDF will be generated and moved into cred/.

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

Copy Files to Personal Computer

Later in the setup processes, the credentials and Node IDF generated will need to be backed up and the Gateway credentials and cMix public certificate will need to be copied to the Gateway machine. To make this process easier, the files need to be copied to an intermediary machine, which will most likely be your personal computer.

These instructions assume you have securely set up SSH and have a valid key pair between the Node machine and your computer.

  1. First, get the address for the Node machine.

    1. If you are on the same local network as your Node machine, then this will be the machine's local IP address. Get the local IP address of the machine with the following command.

      If the Node has multiple network interfaces or an IPv6 address, then they will also appear in this list. Ensure that only the correct internal IPv4 address is used.
    2. If you are not on the same network as your machine, then you will need to get the Node’s public IP address by running the following command.

      ipinfo.io is a third-party service. You can use any valid IP lookup service.
  2. Next, you will need the username for the Node machine. If you do not remember your username, use whoami.

    This should be run on the Node machine.
  3. Open the terminal on your personal computer.

  4. Using SCP, you will remotely connect to the Node machine and copy the cred/ directory to your personal machine.

    Terminal
    This should be done on your computer.
  5. There should now be a cred/ directory on your personal computer. In later steps, you will back up these files and then delete them from your computer.

  6. Delete the Gateway private key from the Node machine.

    This should be run on the Node machine.

Configuring cMix and xx chain

cMix Configuration

Configuring the cMix software requires modification of the YAML file retrieved in Download Software. These instructions go over the basic configuration to get cMix working in the default state. Refer to the Server README file to learn more.

The default cmix.yaml file does not require any changes if no changes have been made to the default file names and directory locations. If you have used the defaults and do not require a special network setup, continue to Service File Configuration.

However, continue below for optional flags used for non-standard configurations. Database information is set in a later step.

  1. Open cmix.yaml in nano or your favorite text editor.

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

    Note that all addresses must be IPv4; IPv6 is not currently supported.
    1. If the Node does not have a GPU, then set useGPU to false.

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

    3. The internal listening address 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 external 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 Identity Information, then modify the location via cmix > paths > cert, node > paths > key, gateway > paths > cert, and scheduling > paths > cert.

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

Service File Configuration

The service files contain the parameters and flags to use when running the cMix and xx chain software. For default setups, these files come correctly preconfigured and only the username needs to be modified. For additional information on the flags, refer to Management Tools.

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

  2. Open xxnetwork-cmix.service with nano or your favorite text editor.

  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 the buffer, press Y. Finally, when prompted with the file name, press Enter.

  5. Open xxnetwork-chain.service with nano or your favorite text editor.

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

  7. Next, the name used for telemetry of your Node needs to be configured.Use the down key to navigate to the line that starts with ExecStart and, after the --validator flag, add the flag --name followed by your desired name for the Node. While not required, you may want to make the name unique so you can differentiate your Node from other Nodes and Gateways. If you do not set a name, then a random name will automatically be assigned to your Node.

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

Database Set Up

The cMix software requires a PostgreSQL database to store key pairs with clients. The following instructions detail how to install PostgreSQL, set up the required database, and Verify the Database.

  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 cMix configuration file in the following steps and you will not need to remember it once everything is configured.

    Never store this password digitally except when putting it into the cMix configuration file. Never provide this password to anyone.
  6. Create the required database with the name cmix_node.

    The following output: could not change directory to "/current/working/directory": Permission denied can safely be ignored.
  7. Next, modify the cMix configuration file to use the newly generated password in step 5 above. To do this, open cmix.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 the 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. Log in with the postgres account.

  2. Run the PostgreSQL client server via psql.

    The command prompt will change from $ to postgres-#.
  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.

  4. Enter \q to exit the command line.

  5. Enter exit to return to your prompt.

System Services

This section describes how to install the service files for cMix and xx chain.

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

    This should result in the following output.

  2. If System clock synchronized is set to yes and NTP service is set to active, 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 cMix:

    For xx chain:

  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.

    You can use whoami to get your username.
  6. Next, enable the service(s) for the appropriate binary.

    For cMix:

    This should result in the following output.

    For xx chain:

    This should result in the following output.

  7. Then, start the services.

    For xx chain:

    For cMix:

Verify the Service has Started

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

    For cMix:

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

    For xx chain:

    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 cMix and xx chain processes are running.

    This will print a list of running xx network processes. If xxnetwork-chain appears on the list, then the xx chain process is running. xxnetwork-cmix will not appear until you have staked your Node.

    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 and Identity Cannot Be Recovered

Node operators must backup the TLS credentials for their Node and Gateway and the IDF for the Node. Loss of these files will irreparably disconnect a Node and Gateway from the network.

These files are sensitive as they identify your Node and Gateway uniquely on the network. Therefore, anybody who gains access to these files can appear on the network as your Node or Gateway.

It is imperative to keep these files secure as any third-party access can compromise your Node and Gateway’s identity.

There are five important files that need to be backed up; Node's TLS credentials and IDF and Gateway's TLS credentials. These files are unrecoverable. Loss of these files will lead to your Node or Gateway being unable to participate in the network. 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.

Backing Up Files

  1. During the software setup, you should have copied the cred/ directory to your personal computer. Find that directory. It should include the following files.

    File Default Name Default Location on Server
    1. cMix’s public certificate cmix-cert.crt /opt/xxnetwork/cred/
    2. cMix’s private key cmix-key.key /opt/xxnetwork/cred/
    3. cMix’s ID file (IDF) cmix-IDF.json /opt/xxnetwork/cred/
    4. Gateway’s public certificate gateway-cert.crt /opt/xxnetwork/cred/
    5. Gateway’s private key gateway-key.key /opt/xxnetwork/cred/
  2. Move these five files to a safe, secure, and reliable location.

  3. Do not delete the files off your personal machine yet, as you will need them when setting up the Gateway.