n2x.dev/x-node

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.io 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.io account and are ready to start adding nodes.

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

See Installation for more details and other platforms.

Documentation

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

Installation

Download Binaries

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 one-line command

The n2x.io platform provides a one-line command for the simplest and quickest way to install the n2x-node agent in Linux. You'll find this command readily available when you add a new node through the n2x.io webUI.

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

• Download the latest release.

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

• 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
  

• 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.

• 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
  

• Ensure the tun kernel module is loaded.

  sudo modprobe tun
  

• Start the n2x-node service.

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

Package Repository

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

Debian/Ubuntu

• 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
  

• Check n2x-node service status:

  sudo systemctl status n2x-node
  

RHEL/CentOS

• Run the following to create a n2x.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
  

• Check n2x-node service status:

  sudo systemctl status n2x-node
  

macOS Installation

macOS installation with one-line command

The n2x.io platform provides a one-line command for the simplest and quickest way to install the n2x-node agent in macOS. You'll find this command readily available when you add a new node through the n2x.io webUI.

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.

macOS binary installation with curl

• 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"
  

• 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
  

• 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.

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

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

• 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
  }
  

Windows Installation

Windows installation with one-line command

The n2x.io platform provides a one-line command for the simplest and quickest way to install the n2x-node agent in Windows. You'll find this command readily available when you add a new node through the n2x.io webUI.

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.

Windows binary installation with curl

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

  mkdir 'C:\Program Files\n2x'
  

• Download the latest release into the n2x folder.

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

• 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]
    

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

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

• 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.

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

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

  'C:\Program Files\n2x\n2x-node.exe' service-install
  

• Start the n2x-node service.

  start-Service n2x-node
  

• Check n2x-node service status.

  get-Service n2x-node
  

Running with Docker

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

Registry:

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

One-line command

The n2x.io platform provides a one-line command for the simplest and quickest way to running the n2x-node agent with Docker. You'll find this command readily available when you add a new node through the n2x.io webUI.

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.

Manual

Example usage:

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

Artifacts Verification

Binaries

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

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

• Verify the signature:

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

• 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

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.

Uninstall

Uninstall Linux n2x-node agent

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

Binary

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

Debian/Ubuntu

sudo systemctl stop n2x-node
sudo apt-get -y remove 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

RHEL/Centos

sudo systemctl stop n2x-node
sudo yum -y remove 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

Uninstall macOS n2x-node agent

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

Uninstall Windows n2x-node agent

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

stop-Service "n2x-node"
'C:\Program Files\n2xn2x-node.exe` service-uninstall
rm 'C:\Program Files\n2x' -r -force

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.