x-node

README

Open source projects from n2x.io.

n2x-node

This repository contains the n2x-node agent, the component that runs on the machines you want to connect to your n2x network.

n2x-node is available for a variety of Linux platforms, macOS and Windows.

Minimum Requirements

n2x-node has the same minimum requirements as Go:

• Linux kernel version 2.6.23 or later
• Windows 7 or later
• FreeBSD 11.2 or later
• MacOS 10.11 El Capitan or later

Getting Started

The instructions in this repo assume you already have a n2x account and are ready to start adding nodes.

See Quick Start to learn how to start building your n2x cloud-agnostic architecture.

The fastest way to add Linux nodes to your n2x network is by generating a magic link in the n2x web UI or with n2xctl:

n2xctl node add

See Installation for more details and other platforms.

Documentation

For the complete n2x platform documentation visit n2x.io/docs.

Installation

Binary Downloads

Linux, macOS and Windows binary downloads are available from the Releases page.

You can download the pre-compiled binaries and install them with the appropriate tools.

Linux Installation

Linux installation with magic link

The easiest way to add nodes to your n2x network is by generating a magic link in the n2x web UI or with n2xctl:

n2xctl node add

You will be able to use the magic link to install the n2x-node agent in seconds with no additional configuration required.

Once installed you can review the configuration at /etc/n2x/n2x-node.yml.

See the n2x-node configuration reference to find all the configuration options.

Linux binary installation with curl

1. Download the latest release.

   curl -LO "https://dl.n2x.io/binaries/stable/latest/linux/amd64/n2x-node"
   

2. Validate the binary (optional).

   Download the n2x-node checksum file:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/linux/amd64/n2x-node_checksum.sha256"
   

   Validate the n2x-node binary against the checksum file:

   sha256sum --check < n2x-node_checksum.sha256
   

   If valid, the output must be:

   n2x-node: OK
   

   If the check fails, sha256 exits with nonzero status and prints output similar to:

   n2x-node: FAILED
   sha256sum: WARNING: 1 computed checksum did NOT match
   

3. Install n2x-node and create its configuration file according to your needs.

   sudo install -o root -g root -m 0750 n2x-node /usr/local/bin/n2x-node
   sudo mkdir /var/lib/n2x
   sudo mkdir /var/cache/n2x
   sudo mkdir /etc/n2x
   sudo vim /etc/n2x/n2x-node.yml
   

   See the n2x-node configuration reference to find all the configuration options.

4. Create the n2x-node.service for systemd.

   sudo cat << EOF > /etc/systemd/system/n2x-node.service
   [Unit]
   Description=n2x-node service
   Documentation=https://github.com/n2x-io/x-node
   After=network.target
   
   [Service]
   Type=simple
   
   # Another Type: forking
   
   # User=
   WorkingDirectory=/var/lib/n2x
   ExecStart=/usr/local/bin/n2x-node start
   Restart=always
   
   # Other restart options: always, on-abort, etc
   
   # The install section is needed to use
   
   # 'systemctl enable' to start on boot
   
   # For a user service that you want to enable
   
   # and start automatically, use 'default.target'
   
   # For system level services, use 'multi-user.target'
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

5. Ensure the tun kernel module is loaded.

   sudo modprobe tun
   

6. Start the n2x-node service.

   sudo systemctl daemon-reload
   sudo systemctl enable n2x-node
   sudo systemctl restart n2x-node
   

Uninstall Linux n2x-node

To remove n2x-node from the system, use the following commands:

sudo systemctl stop n2x-node
sudo systemctl disable n2x-node
sudo rm /etc/systemd/system/n2x-node.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/n2x-node
sudo rm /etc/n2x/n2x-node.yml
sudo rmdir /etc/n2x
sudo rm -rf /var/lib/n2x
sudo rm -rf /var/cache/n2x

Package Repository

n2x provides a package repository that contains both DEB and RPM downloads.

For DEB-based platforms (e.g. Ubuntu and Debian) run the following to setup a new APT sources.list entry and install n2x-node:

echo 'deb [trusted=yes] https://repo.n2x.io/apt/ /' | sudo tee /etc/apt/sources.list.d/n2x.list
sudo apt update
sudo apt install n2x-node

For RPM-based platforms (e.g. RHEL, CentOS) use the following to create a repo file and install n2x-node:

cat <<EOF | sudo tee /etc/yum.repos.d/n2x.repo
[n2x]
name=n2x repository - stable
baseurl=https://repo.n2x.io/yum
enabled=1
gpgcheck=0
EOF
sudo yum install n2x-node

macOS Installation

macOS binary installation with curl

1. Download the latest release.

   Intel:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/darwin/amd64/n2x-node"
   

   Apple Silicon:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/darwin/arm64/n2x-node"
   

2. Validate the binary (optional).

   Download the n2x-node checksum file:

   Intel:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/darwin/amd64/n2x-node_checksum.sha256"
   

   Apple Silicon:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/darwin/arm64/n2x-node_checksum.sha256"
   

   Validate the n2x-node binary against the checksum file:

   shasum --algorithm 256 --check n2x-node_checksum.sha256
   

   If valid, the output must be:

   n2x-node: OK
   

   If the check fails, sha256 exits with non-zero status and prints output similar to:

   n2x-node: FAILED
   sha256sum: WARNING: 1 computed checksum did NOT match
   

3. Install n2x-node and create its configuration file according to your needs.

   chmod +x n2x-node
   sudo mkdir -p /opt/n2x/libexec
   sudo mv n2x-node /opt/n2x/libexec/n2x-node
   sudo chown root: /opt/n2x/libexec/n2x-node
   sudo mkdir -p /opt/n2x/etc
   sudo vim /opt/n2x/etc/n2x-node.yml
   sudo chmod 600 /opt/n2x/etc/n2x-node.yml
   sudo mkdir -p /opt/n2x/var/lib
   sudo mkdir -p /opt/n2x/var/cache
   

   IMPORTANT: In macOS, iface must be utun[0-9]+ in the n2x-node.yml, being utun7 usually a good choice for that setting. Use the command ifconfig -a before launching the n2x-node service and check that the interface is not in-use.

   See the n2x-node configuration reference to find all the configuration options.

4. Install and start the n2x-node agent as a system service.

   sudo /opt/n2x/libexec/n2x-node service-install
   

5. Check the service status.

   launchctl print system/com.n2x.n2x-node
   

   You should get an output like this:

   system/com.n2x.n2x-node = {
       active count = 1
       path = /Library/LaunchDaemons/com.n2x.n2x-node.plist
       state = running
   
       program = /opt/n2x/libexec/n2x-node
       arguments = {
           /opt/n2x/libexec/n2x-node
           service-start
       }
   
       working directory = /var/tmp
   
       stdout path = /usr/local/var/log/com.n2x.n2x-node.out.log
       stderr path = /usr/local/var/log/com.n2x.n2x-node.err.log
       default environment = {
           PATH => /usr/bin:/bin:/usr/sbin:/sbin
       }
   
       environment = {
           XPC_SERVICE_NAME => com.n2x.n2x-node
       }
   
       domain = system
       minimum runtime = 10
       exit timeout = 5
       runs = 1
       pid = 3925
       immediate reason = speculative
       forks = 28
       execs = 1
       initialized = 1
       trampolined = 1
       started suspended = 0
       proxy started suspended = 0
       last exit code = (never exited)
   
       spawn type = daemon (3)
       jetsam priority = 4
       jetsam memory limit (active) = (unlimited)
       jetsam memory limit (inactive) = (unlimited)
       jetsamproperties category = daemon
       submitted job. ignore execute allowed
       jetsam thread limit = 32
       cpumon = default
   
       properties = keepalive | runatload | inferred program
   }
   

Uninstall macOS n2x-node

To remove n2x-node from the system, use the following commands:

sudo /opt/n2x/libexec/n2x-node service-uninstall
sudo rm /opt/n2x/libexec/n2x-node
sudo rm /opt/n2x/etc/n2x-node.yml
sudo rm -rf /opt/n2x

Windows Installation

Windows binary installation with curl

1. Open the Command Prompt as Administrator and create a folder for n2x.

   mkdir 'C:\Program Files\n2x'
   

2. Download the latest release into the n2x folder.

   curl -LO "https://dl.n2x.io/binaries/stable/latest/windows/amd64/n2x-node.exe"
   

3. Validate the binary (optional).

   Download the n2x-node.exe checksum file:

   curl -LO "https://dl.n2x.io/binaries/stable/latest/windows/amd64/n2x-node.exe_checksum.sha256"
   

   Validate the n2x-node.exe binary against the checksum file:

   • Using Command Prompt to manually compare CertUtil's output to the checksum file downloaded:

     CertUtil -hashfile n2x-node.exe SHA256
     type n2x-node.exe_checksum.sha256
     

   • Using PowerShell to automate the verification using the -eq operator to get a True or False result:

     $($(CertUtil -hashfile .\n2x-node.exe SHA256)[1] -replace " ", "") -eq $(type .\n2x-node.exe_checksum.sha256).split(" ")[0]
     

4. Download the wintun driver from https://wintun.net.

5. Unzip the wintun archive and copy the AMD64 binary wintun.dll to C:\Program Files\n2x.

6. Use an editor to create the n2x-node configuration file C:\Program Files\n2x\n2x-node.yml.

   See the n2x-node configuration reference to find all the configuration options.

7. Install the n2x-node agent as a Windows service.

   The instructions below assume that the wintun.dll, n2x-node.exe and n2x-node.yml files are stored in C:\Program Files\n2x.

   .\n2x-node.exe service-install --config "C:\Program Files\n2x\n2x-node.yml"
   

   Make sure to provide the absolute path of the n2x-node.yml configuration file, otherwise the Windows service may fail to start.

8. Start the service.

   net start "n2x-node"
   

Uninstall Windows n2x-node

To remove n2x-node from the system, open the Command Prompt as Administrator and use the following commands:

net stop "n2x-node"
cd 'C:\Program Files\n2x'
.\n2x-node.exe service-uninstall
del *.*
cd ..
rmdir 'C:\Program Files\n2x'

Artifacts Verification

Binaries

All artifacts are checksummed and the checksum file is signed with cosign.

1. Download the files you want and the checksums.txt, checksum.txt.pem and checksums.txt.sig files from the Releases page:

2. Verify the signature:

   cosign verify-blob \
       --cert checksums.txt.pem \
       --signature checksums.txt.sig \
       checksums.txt
   

3. If the signature is valid, you can then verify the SHA256 sums match with the downloaded binary:

   sha256sum --ignore-missing -c checksums.txt
   

Docker Images

Our Docker images are signed with cosign.

Verify the signatures:

COSIGN_EXPERIMENTAL=1 cosign verify ghcr.io/n2x-io/n2x-node

Configuration

See the n2x-node configuration reference to find all the configuration options.

Running with Docker

You can also run the n2x-node agent as a Docker container. See examples below.

Registries:

• ghcr.io/n2x-io/n2x-node
• n2xdev/n2x-node

Example usage:

docker run -d --restart=always \
  --net=host \
  --cap-add=net_admin \
  --device=/dev/net/tun \
  --name n2x-node \
  -v /etc/n2x:/etc/n2x:ro \
  ghcr.io/n2x-io/n2x-node:latest start

Community

Have questions, need support and or just want to talk about n2x?

Get in touch with the n2x community!

Code of Conduct

Participation in the n2x community is governed by the Contributor Covenant Code of Conduct. Please make sure to read and observe this document.

Please make sure to read and observe this document. By participating, you are expected to uphold this code.

License

The n2x open source projects are licensed under the Apache 2.0 License.