Gateway Set Up
Below you will find the instructions for setting up the xx Gateway with the Gateway and xx chain software for the first time. These instructions are only for the Gateway. For instructions for setting up a Node, refer to Node Set Up.
The installation instructions assume that your machine meets or exceeds the Gateway Hardware Requirements and that it is configured per the Operating System Installation and Configuration instructions.
Overview
Setting up Gateway and xx chain software 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:
- Install and configure the operating system
- Install and configure the Gateway and xx chain software
- Copy TLS credentials from the Node machine
- Install and configure the database
- Set up and start the services
- Backup important files Make sure not to skip this critical step!
Before Starting
Before installing the software, make sure that:
- Your Gateway machine meets or exceeds Gateway Hardware Requirements
- You have followed the Operating System Installation and Configuration instructions
Download Software
Change the working directory to /opt/.
Download the tarball for Gateway using
curl
with the following URL. The newest versions can also be found on the xx network website.It will show the download progress similar to below.
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 toNo 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, similar to below. 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.Next, extract the Gateway 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 tonot 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/xxnetwork-chain The binary for the xx chain software. config/gateway.yaml The configuration file for the Gateway 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. gateway-wrapper.py A management script for the Gateway binary. xxnetwork-chain.service systemd service file for the xx chain binary. xxnetwork-gateway.service systemd service file for the Gateway Wrapper Script. Next, make the binaries executable.
Copy Identity 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 two TLS certificates are generated on the Node machine. The Gateway credentials (gateway-cert.crt and gateway-key.key) and the cMix public certificate (cmix-cert.crt) need to be copied to the Gateway machine.
The instructions below assume that you have SSH enabled and configured on your Gateway machine. If you have not, follow the instructions for Setting Up SSH.
If you have not already, Generate the Node's and Gateway's TLS certificates on the Node machine and transfer the files to your personal computer.
First, get the address for the Gateway machine.
If you are on the same local network as the Gateway machine, then this will be the Gateway's local IP address. Get the local IP address of the Gateway with the following command.
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.If you are not on the same network as the Gateway, then you will need to get the machine’s public IP address by running the following command.
ipinfo.io is a third-party service. You can use any valid IP lookup service.
Next, you will need the username for the Gateway machine. If you do not remember your username, use
whoami
.Using SCP, you will remotely connect to the Gateway machine and copy the three required files gateway-cert.crt, gateway-key.key, and cmix-cert.crt.
This should be back on your personal computer that has the cred/ directory copied to it.The three files should download to the cred/ directory.
Check that all the correct files are in the cred/ directory using
ls
to list the files.This should be run on the Gateway machine.Delete the Gateway's private key gateway-key.key from the Node machine.
Ensure that the Gateway key was copied correctly to the Gateway or securely backed up before deleting it off the Node machine.This should be done on the Node machine.
Configuring Gateway and xx chain
Gateway Configuration
Configuring the Gateway 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 Gateway README file to learn more.
The default gateway.yaml file only requires setting the public IP address of its Node if no changes have been made to the default file names and directory locations. However, there are other optional flags for non-standard configurations. Database information is set in a later step.
Get the Node’s public IP address by running the following command on the Node machine.
This should be run on the Node machine.ipinfo.io is a third-party service. You can use any valid IP lookup service.The Gateway configuration file must be modified to include the Node's IP address. To do this, open gateway.yaml in nano or your favorite text editor.
Once the file is open, use the down arrow key ↓ to scroll down to the line that says
cmixAddress
and replace the placeholder with the one found in step 1. Make sure to include the chosen port for cMix (the default is 11420).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.By default, the Gateway runs on port 22840; however, this can be modified using the port flag.
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 theport
flag.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 external communication, the public IP and port can be manually set via
overridePublicIP
. If no port is set, then the port from theport
flag is used. This expects an IPv4 address only.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
,cmixCertPath
, andschedulingCertPath
.
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 Gateway 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.
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
.Open xxnetwork-gateway.service with nano or your favorite text editor.
Under the
[Service]
heading, after theUser=
field, modify the username to the one found in step 1.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.
Open xxnetwork-chain.service with nano or your favorite text editor.
Under the
[Service]
heading, after theUser=
field, modify the username to the one found in step 1.Next, the name used for telemetry of your Gateway needs to be configured.Use the down key ↓ to navigate to the line that starts with
ExecStart
and, after/opt/xxnetwork/bin/xxnetwork-chain
, add the flag--name
followed by your desired name for the Gateway. While not required, you may want to make the name unique so you can differentiate your Gateway from other Nodes and Gateways. If you do not set a name, then a random name will automatically be assigned to your Gateway.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 Gateway 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.
Install PostgreSQL and its dependencies.
Once the installation is complete, enable the PostgreSQL service.
Next, start the service.
Create a database user with the username
cmix
, which is used to access the database.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 except when putting it into the Gateway configuration file. Never provide this password to anyone.Create the required database with the name
cmix_gateway
.The following output:could not change directory to "/current/working/directory": Permission denied
can safely be ignored.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.
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.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.
Log in with the
postgres
account.Run the PostgreSQL client server via
psql
.The command prompt has changed from$
to#
.Once at the postgres prompt, enter in
\l
to get a list of databases (do not enter thepostgres-#
part).Ensure that the correct databases with the correct owners show up.
Enter
\q
to exit the command line.Enter
exit
to return to your prompt.
System Services
This section describes how to install the service files for Gateway and xx chain.
Before starting services, ensure that the clock is synchronized by entering the following command.
This should result in the following output.
If
System clock synchronized
is set toyes
andNTP service
is set toactive
, then proceed to the next step. Otherwise, refer back to the Clock Synchronization (NTP) section.Next, soft link the systemd service file(s) to the systemd directory /etc/systemd/system/.
For Gateway:
For xx chain:
Reload the systemd service files.
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 usewhoami
to get your username.Next, enable the service(s) for the appropriate binary.
For Gateway:
This should result in the following output.
For xx chain:
This should result in the following output.
Then, start the services.
For Gateway:
For xx chain:
Verify the Service has Started
First, check the status of the service to ensure it is running.
For Gateway:
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.
Next, check that the process is running. If the commands result in the expected output, then the Gateway and xx chain processes are running.
This will print a list of running xx network processes. If
xxnetwork-gatew
appears on the list, then the Gateway process is running. Ifxxnetwork-chain
appears on the list, then the xx chain process is running.The PID (the first number printed) and the elapsed time will be different.
Backup Certificates and Important Files
ATTENTION
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 extremely important 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
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/ Move these five files to a safe, secure, and reliable location.
Delete Copied Files
Once the files are backed up, you need to delete the unsecured copies that you downloaded from the Node machine.
Delete the files in the cred directory from your personal machine. You can do so using your computer's file browser or by using the command below.
Run this on your personal computerThis will then print a list of all removed files.
![]() | Your Node is now fully set up with the Gateway and xx chain software! Continue to the instructions for Staking a Node. |