Skip to content

Install n2x.io CLI

The n2x.io CLI, n2xctl, is an open-source tool that allows you to manage your n2x.io SASE platform directly from the command line.

n2xctl is available for a variety of Linux platforms, macOS and Windows.

Check out its GitHub repository for more details and information on support, contributing, etc.

Minimum Requirements

n2xctl 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

Download Binaries

Linux, macOS and Windows binary downloads are available from the Releases page at the n2x-cli GitHub Repository.

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

Linux Installation

  1. Download the latest release.

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

  2. Validate the binary (optional).

    Download the n2xctl checksum file:

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

    Validate the n2xctl binary against the checksum file:

    sha256sum --check < n2xctl_checksum.sha256

    If valid, the output must be:

    n2xctl: OK

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

    n2xctl: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

  3. Install n2xctl.

    sudo install -o root -g root -m 0755 n2xctl /usr/local/bin/n2xctl

    Note

    If you do not have root access on the target system, you can still install n2xctl to the ~/.local/bin directory:

    chmod +x n2xctl
mkdir -p ~/.local/bin
mv ./n2xctl ~/.local/bin/n2xctl
# and then append (or prepend) ~/.local/bin to $PATH

  4. Verify that the installed version is the latest:

    n2xctl version show

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

  1. Run the following to setup a new APT sources.list entry and install n2x-cli:

    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-cli

  2. Verify that the installed version is the latest:

    n2xctl version show

  1. Run the following to create a n2x.repo file and install n2x-cli:

    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-cli

  2. Verify that the installed version is the latest:

    n2xctl version show

If you are on Linux and using Homebrew package manager, you can install the n2x.io CLI with Homebrew.

  1. Run the installation command:

    brew install n2x/tap/n2x-cli

  2. Verify that the installed version is the latest:

    n2xctl version show

macOS Installation

  1. Download the latest release.

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

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

  2. Validate the binary (optional).

    Download the n2xctl checksum file:

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

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

    Validate the n2xctl binary against the checksum file:

    shasum --algorithm 256 --check n2xctl_checksum.sha256

    If valid, the output must be:

    meshctl: OK

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

    n2xctl: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

  3. Make the n2xctl binary executable.

    chmod +x n2xctl

  4. Move the n2xctl binary to a file location on your system PATH.

    sudo mkdir -p /usr/local/bin
sudo mv n2xctl /usr/local/bin/n2xctl
sudo chown root: /usr/local/bin/n2xctl

    Note

    Make sure /usr/local/bin is in your PATH environment variable.

  5. Verify that the installed version is the latest:

    n2xctl version show

If you are on macOS and using Homebrew package manager, you can install the n2x.io CLI with Homebrew.

  1. Run the installation command:

    brew install n2x/tap/n2x-cli

  2. Verify that the installed version is the latest:

    n2xctl version show

Windows Installation

  1. Open the Windows PowerShell as Administrator and create the n2x folder.

    mkdir 'C:\Program Files\n2x'

  2. Download the latest release into the n2x folder.

    cd 'C:\Program Files\n2x'
curl -Uri "https://dl.n2x.io/binaries/stable/latest/windows/amd64/n2xctl.exe" -Outfile n2xctl.exe

  3. Validate the binary (optional).

    Download the n2xctl.exe checksum file:

    curl -Uri "https://dl.n2x.io/binaries/stable/latest/windows/amd64/n2xctl.exe_checksum.sha256" -Outfile n2xctl.exe_checksum.sha256

    Validate the n2xctl.exe binary against the checksum file:

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

      CertUtil -hashfile n2xctl.exe SHA256
type n2xctl.exe_checksum.sha256

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

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

  4. Add the folder C:\Program Files\n2x to your PATH environment variable. You can either append or prepend it to the existing value.

    $ENV:PATH="$ENV:PATH;C:\Program Files\n2x"

  5. Verify that the installed version is the latest:

    n2xctl version show

Running with Docker

You can also run n2xctl as a Docker container.

Registry:

  • ghcr.io/n2x-io/n2xctl

Example usage:

docker run --rm -ti -v $HOME/.n2x:/root/.n2x:ro ghcr.io/n2x-io/n2xctl help

Artifacts Verification

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

Our Docker images are signed with cosign.

Verify the signatures:

COSIGN_EXPERIMENTAL=1 cosign verify n2xdev/n2xctl

Usage

To view a list of available commands and options, simply run:

n2xctl help

For in-depth information about specific commands and their usage, refer to our dedicated CLI Command Reference guide.

Note

  • Login Credentials: When you run n2xctl auth login, your account's temporary credentials are stored securely by default in the file $HOME/.n2x/apikey.

  • Logout and Credential Removal: Executing n2xctl auth logout will remove the $HOME/.n2x/apikey file, ensuring your credentials are not stored after the session ends.

Uninstall

To remove n2xctl from the system, use the following commands:

sudo rm /usr/local/bin/n2xctl
sudo rm -f $HOME/.n2x

sudo apt-get -y remove n2x-cli
sudo rm -f $HOME/.n2x

sudo yum -y remove n2x-cli
sudo rm -f $HOME/.n2x

To remove n2xctl from the system, use the following commands:

sudo rm /usr/local/bin/n2xctl
sudo rm -f $HOME/.n2x

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

rm 'C:\Program Files\n2x' -r -force