Operating a DevNet CDN PoP Node

The binary of the CDN PoP node is not yet publicly available. It will be made available soon to operators for the Testnet launch. Prior to official network launch the code will be open-sourced.

Fill out this form to be notified upon the release: https://docs.google.com/forms/d/e/1FAIpQLScbxN1qlstpbyU55K5I1UPufzfwshcv7uRJG6aLZQDk52ma0w/viewform After the binary is released, follow these instructions for installation

Introduction:

We will begin by launching devNet to collect statistical data and validate the protocol. The project will feature three distinct networks: devNet, testNet, and mainNet

Join the devNet

Join our devNet today! This initiative provides node operators the chance to build a reputation ahead of the incentivized testnet launch.

💡 Prepare for Testnet: The incentivized testnet will follow, rewarding those who demonstrate strong performance. Both PoP Nodes and Guardian Nodes will play critical roles in shaping the future of Pipe Network.

Key Features

  • Location-Based Rewards: Operators in underrepresented or high-demand regions earn additional incentives.

  • PoP Node Rewards: Rewards are based on metrics such as data served, latency, and uptime. Consistent uptime and performance standards yield higher rewards, while downtime and churn result in rejoin penalties to deter disruption.

Devnet Prerequisites

  • Linux computer with 2 vCPU's and 2GB of RAM (less than 2GB is possible, but requires additional settings)

  • Basic linux knowledge (running a systemd service, finding and copying files, familiarity with terminal and common commands like: ls, rm, mkdir)

  • Positive attitude and lack of entitlement

Node Registration Process

To request registration of your node, you'll be generating specific tokens and logging in to your account. Follow the steps below:

  1. Log In to Generate Access Token

    Open a terminal and execute the command below to log in:

    /opt/dcdn/pipe-tool login --node-registry-url="https://rpc.pipedev.network"

    This will generate a credentials.json file in the ~/.permissionless directory which comprises your access token. This token proves your identity on the network.

  2. Generate Registration Token

    Use the following command to generate a Pipe Network registration token:

    /opt/dcdn/pipe-tool generate-registration-token --node-registry-url="https://rpc.pipedev.network" --credentials-dir=/root/.permissionless

    This will create a file named registration_token.json in the /root/.permissionless directory which comprises your node registration token, valid for one year. This token is necessary for registering or re-registering nodes.

  3. Authentication Process

    • Scan the QR code or use the browser window that opens automatically.

    • Create an account or sign in with your Google credentials.

    • Return to the terminal. Upon successful login, you will see the message: “Logged in successfully!”

Your access token will be saved in ~/.permissionless/credentials.json. Make sure both registration_token.json and credentials.json tokens are present when managing nodes.

Setup Instructions

Download the Node Client Binary

  1. Create Directory:

    sudo mkdir -p /opt/dcdn

  2. Download Pipe tool Binary from the URL you were provided ($PIPE-URL is a placeholder):

    sudo curl -L "$PIPE-URL" -o /opt/dcdn/pipe-tool

  3. Download Node Binary from the URL you were provided ($DCDND-URL is a placeholder):

    sudo curl -L "$DCDND-URL" -o /opt/dcdn/dcdnd

  4. Make Binary Executable:

    sudo chmod +x /opt/dcdn/pipe-tool
sudo chmod +x /opt/dcdn/dcdnd

Setup the dcdnd node systemd service

To configure the systemd service, follow these steps:

Create the Service File: Save your service definition in a .service file within the /etc/systemd/system/ directory.

Sample Service File Creation:

# Create service file using tee
sudo tee /etc/systemd/system/dcdnd.service << 'EOF'
[Unit]
Description=DCDN Node Service
After=network.target
Wants=network-online.target

[Service]
# Path to the executable and its arguments
ExecStart=/opt/dcdn/dcdnd \
                --grpc-server-url=0.0.0.0:8002 \
                --http-server-url=0.0.0.0:8003 \
                --node-registry-url="https://rpc.pipedev.network" \
                --cache-max-capacity-mb=1024 \
                --credentials-dir=/root/.permissionless \
                --allow-origin=*

# Restart policy
Restart=always
RestartSec=5

# Resource and file descriptor limits
LimitNOFILE=65536
LimitNPROC=4096

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=dcdn-node


# Working directory
WorkingDirectory=/opt/dcdn

[Install]
WantedBy=multi-user.target
EOF

Optional: Enhanced Security

For enhanced security, run dcdnd.service under a dedicated service account. This is a more advanced configuration.

# Create dedicated service account:
sudo useradd -r -m -s /sbin/nologin dcdn-svc-user -d /home/dcdn-svc-user
# Create token subfolder
sudo mkdir -p /home/dcdn-svc-user/.permissionless
sudo chown -R dcdn-svc-user:dcdn-svc-user /home/dcdn-svc-user/.permissionless
# Update the .service file [Service] to include:
User=dcdn-svc-user
Group=dcdn-svc-user
# Update the credentials path under [Service] accordingly:
sudo nano /etc/systemd/system/dcdnd.service # open the service file
--credentials-dir=/home/dcdn-svc-user/.permissionless \ # line to update
# Move the previously generated registration token to the service users home folder:
mv /root/.permissionless/registration_token.json /home/dcdn-svc-user/.permissionless

Ports to open

The ports you need to open based on the provided service file are:

  1. Port 8002: This is for the gRPC server (--grpc-server-url=0.0.0.0:8002).

  2. Port 8003: This is for the HTTP server (--http-server-url=0.0.0.0:8003).

On UFW (Ubuntu/Debian):


sudo ufw allow 8002/tcp
sudo ufw allow 8003/tcp
sudo ufw reload

Additional Notes:

  • Ensure these ports are opened in any cloud provider's network security settings (e.g., AWS Security Groups, Azure Network Security Groups, etc.), if the server is hosted in the cloud.

  • Make sure no other service is already using these ports to avoid conflicts.

To load, enable and start the new service, follow these steps:

  1. Reload Systemd Daemon: Use this command to reload the systemd manager configuration.

    sudo systemctl daemon-reload

  2. Check the .service file: Test the .service file for formatting errors sudo systemd-analyze verify dcdnd.service

  3. Enable Service at Boot: Configure the service to start automatically upon system boot.

    sudo systemctl enable dcdnd

  4. Start the Service: Manually start the service.

    sudo systemctl start dcdnd

Recap and explanation:

The steps outlined above guide you through configuring a systemd service for a DCDN Node Service. By creating a service file in /etc/systemd/system/, you define how the service starts and stops, as well as setting necessary parameters like the executable path and network dependencies. After creating the file, you reload the systemd daemon to apply changes, start the service to check its functionality, and enable it to ensure it automatically starts at boot. Lastly, the service's status is verified to confirm it is running as expected.

Follow these steps to manage the state and configuration of the dcdnd service

Managing the dcdnd Service

1. View Logs

To view the logs for the dcdnd service in real-time, use:

sudo journalctl -f -u dcdnd.service

2. Restart Service

To restart the dcdnd service after making configuration changes, execute:

sudo systemctl restart dcdnd

3. Stop Service

If you need to stop the dcdnd service, use:

sudo systemctl stop dcdnd

4. Check Status

To check the current status of the dcdnd service, run:

sudo systemctl status dcdnd

Pipe Network Wallet Setup & Registration

Log In to Pipe Network

To log in to the Pipe Network, execute the following command:

pipe-tool login --node-registry-url="https://rpc.pipedev.network"

Generate and Register Wallet

You can either generate and register a new wallet or link an existing wallet

Generate a new wallet (Solana Keypair):

To generate a Solana keypair, run the following command:

pipe-tool generate-wallet --node-registry-url="https://rpc.pipedev.network"

You will be prompted to enter an optional 12-word passphrase Keypair Location: By default, the keypair is saved to ~/.permissionless/key.json. If saving the keypair to a different location, you must specify the desired file path in your dcdnd.service: --key-path=<path to save the keypair file> Wallet security: To ensure the security of your wallet, it's crucial to back up your 12-word recovery phrase and key file in a secure location. Failure to do so may result in losing access if the key file or recovery phrase is compromised. When you run the command successfully, you'll receive the 12-word recovery phrase, the public key of the keypair, and the location where the file is stored. The public key is sent to our pipe.network backend as specified by the –node-registry-url

Linking Your Existing Wallet

Alternatively you can link your existing wallet’s public address (generated by solana-keygen or other wallets that support Solana) to your account. Two different methods are described:

Using Base58 Encoded Public Key

To link your wallet using a base58 encoded public key, run the following command:

pipe-tool link-wallet --node-registry-url="https://rpc.pipedev.network" --public-key="<base58 encoded public key>"

This command will look for the key.json file at the default location ~/.permissionless/key.json. You can specify a custom path to your key file using:

--key-path="<path to file>"

Linking Wallet Using Keypair File

To link your wallet's public address with a keypair file, execute:

pipe-tool link-wallet --node-registry-url="https://rpc.pipedev.network"

Conclusion

Your node should be functioning at this point, here are a few ways to test it out:

Basic tests:

1. pipe-tool list-nodes --node-registry-url="https://rpc.pipedev.network" # only available for the test group which received v1.1 or newer

2. Confirm the ports are open and traffic can get to your node over the internet. Below are two simplistic ways to simply see if the port is open:

a) Use a web based port tester to test against your public IP on port 8002 & 8003. You may Google 'web based port tester' to choose a suitable one at your discretion. OR b) Have a friend at another location try 'telnet <YOUR-PUBLIC-IP> 8002' and 'telnet <YOUR-PUBLIC-IP> 8003' to see if an initial connection is made.

Appendix

Removing dcdnd node:

Remove the service:

sudo systemctl stop dcdnd.service
sudo systemctl disable dcdnd.service
sudo rm /etc/systemd/system/dcdnd.service
sudo systemctl daemon-reload

Remove the application binaries:

rm -r /opt/dcdn

Remove the folder containing the tokens: if you plan to move the node or re-install you may want to skip this step

rm -r ~/.permissionless

Unregister a node completely (node will no longer appear in 'list-nodes')

pipe-tool decommission-node --node-registry-url "https://rpc.pipedev.network" --node-id <NODE_ID>

Appropriate for:

  • Removing a node registration that will never be online again, for example cleaning up a duplicate node registration.

Not appropriate for:

  • simply moving your node to a new computer

Wallet Utilities

View Private Key

To view your wallet’s private address, run the following command:

pipe-tool show-private-key

You can also specify a custom key file location using:

--key-path="<path to key file>"

By default, the key file is located at ~/.permissionless/key.json.

View Public Key

To view your wallet’s public address, use the command:

pipe-tool show-public-key

Similarly, you can specify a custom key file location:

--key-path="<path to key file>"

The default location for the key file is ~/.permissionless/key.json.

View Linked Wallet

To view the wallet linked to your account, execute the following command:

pipe-tool link-wallet --show-linked --node-registry-url="https://rpc.pipedev.network"

pipe-tool Command Appendix

Command pipe-tool login

Usage

pipe-tool login --node-registry-url <NODE_REGISTRY_URL> [OPTIONS]

Options

  • --credentials-dir <CREDENTIALS_DIR> Directory for storing credentials. Environment Variable: CREDENTIALS_DIR Default: ~/.permissionless

  • --node-registry-url <NODE_REGISTRY_URL> URL for the node registry. Environment Variable: NODE_REGISTRY_URL

Command: generate-registration-token

This command generates a token for registering a node with the Pipe network. Ensure you log in or register as a node operator before executing this command.

Usage

pipe-tool generate-registration-token --node-registry-url <NODE_REGISTRY_URL> [OPTIONS]

Options

  • --credentials-dir <CREDENTIALS_DIR> Sets the directory for credentials tokens. Environment Variable: CREDENTIALS_DIR Default: ~/.permissionless

  • --node-registry-url <NODE_REGISTRY_URL> Specifies the URL for the node registry. **Environment Variable

Command: generate-wallet

Usage

pipe-tool generate-wallet --node-registry-url <NODE_REGISTRY_URL> [OPTIONS]

Description

The generate-wallet command generates a Solana keypair to associate with your account.

Options

  • --key-path <KEY_PATH> Environment Variable: KEY_PATH Default: ~/.permissionless/key.json Specify the file path for the key.

  • --credentials-dir <CREDENTIALS_DIR> Environment Variable: CREDENTIALS_DIR Default: ~/.permissionless Specify the directory for storing credentials.

  • --node-registry-url <NODE_REGISTRY_URL> Environment Variable: NODE_REGISTRY_URL Specify the URL of the

Command link-wallet

The link-wallet command is used to link an existing Solana keypair with your account.

Usage

pipe-tool link-wallet --node-registry-url <NODE_REGISTRY_URL> [OPTIONS]

Options

  • SHOW_LINKED Set this option to true or false to show linked accounts. Command: --show-linked

  • PUBLIC_KEY Provide a base58 public key using this environment variable. Command: --public-key <PUBLIC_KEY>

  • KEY_PATH Specify the key path. Default: ~/.permissionless/key.json Command: --key-path <KEY_PATH>

  • CREDENTIALS_DIR Specify the directory for credentials. Default: ~/.permissionless Command: --credentials-dir <CREDENTIALS_DIR>

  • NODE_REGISTRY_URL Provide the node registry URL. Command: `--node-registry-url <NODE

Command: pipe-tool show-public-key

Description: Display the base58 encoded public key from the keypair file.

Usage:

pipe-tool show-public-key [OPTIONS]

Options:

  • --key-path <KEY_PATH> Specify the path to the key file Environment Variable: KEY_PATH

Command: Display Private Key

Description: Use this command to display the private key and the complete key pair file as a base58 encoded string.

Usage

pipe-tool show-private-key [OPTIONS]

Options

  • --key-path <KEY_PATH> Specifies the path to the key file. Environment Variable: KEY_PATH

Command: Decomission Node

Description: This command is to permanently decommission a node registration

Usage

pipe-tool decommission-node --node-registry-url <NODE_REGISTRY_URL> --node-id <NODE_ID>

Options

  • --node-id <NODE_ID> Specifies the node ID from 'list-nodes'

Troubleshooting

Issue: Failed to login to pipe-tool after authentication expired

Error: Failed to list nodes: Status { code: Unauthenticated, message: "Failed to extract token: ExpiredSignature", metadata: MetadataMap { headers: {"server": "nginx/1.24.0 (Ubuntu)", "date": "Sat, 30 Nov 2024 14:01:27 GMT", "content-type": "application/grpc", "content-length": "0"} }, source: None } Login to view your nodes.

The key point in the error message is "Login to view your nodes." Pipe-tool requires an authenticated session, for security best practices the authentication is does not stay logged in (similar to how most internet applications do not remain logged in forever). If you have not used pipe-tool for awhile, then you will need to login again.

Issue: "Health" "unreachable" in list-nodes on 'ACTIVE' Status node

There may be numerous reasons an operators node is unreachable due to various conditions on the operators end. It is commonly due to the required ports being unreachable to your node. Running your node over a VPN may also cause the 'unreachable' condition.

Solution: ensure the required ports are reachable

Issue: "No token provided. Please provide a token in the token file."

Cause: The dcdnd binary is not finding your token files

Solution:

Review the commands you ran which created the tokens to see where you specified they should be saved, this is typically ~/.permissionless or /home/dcdn-svc-user/.permissionless if you followed the best-practices enhanced security path.

Also review the "--credentials-dir=" specified in your dcdnd.service with cat /etc/systemd/system/dcdnd.service To check for existence of the tokens and confirm their location:

ls ~/.permissionless

and

ls /home/dcdn-svc-user/.permissionless

The "--credentials-dir=" must match the actual location of the tokens

Issue: ERROR dcdnd: Failed to register node: Other("status: Internal, message: "protocol error: received message with invalid compression flag: 60 (valid flags are 0 and 1) while receiving response with status: 502 Bad Gateway"

Background: The DevNet backend was reset on 12/24/24 10:30 AM PST.

Solution: Operators who ran prior to the reset must re-register their node by following the below instructions.

  1. Re-login /opt/dcdn/pipe-tool login --node-registry-url="https://rpc.pipedev.network"

  2. Generate new registration token /opt/dcdn/pipe-tool generate-registration-token --node-registry-url="https://rpc.pipedev.network" **Note: if your tokens are in a location other than the current users ~/.permissionless folder then you may need to include '--credentials-dir=' for example, '--credentials-dir=/root/.permissionless' or --credentials-dir=/home/dcdn-svc-user/.permissionlessif you followed the enhanced security steps. The path is defined in your dcdnd.service configuration file.

  3. Restart the dcdn service sudo systemctl restart dcdnd

  4. Confirm your node is registered /opt/dcdn/pipe-tool list-nodes --node-registry-url="https://rpc.pipedev.network"

Perform basic tests

PreviousOpportunities and Use CasesNextPerformance and fraud detection

Last updated