Skip to main content
Version: 0.4.0-beta

Node Client (CLI) Installation

Node Client provides a lightweight control plane interface within the Cluster Wizard system.

It can be used to register and control Node Wizard managed hosts in environments where the full Cluster Wizard control plane is not required. Node Client provides authenticated access for node registration, state management, and centralized control of Node Wizard hosts. Node Client acts as a management interface and can run on any machine that has network access to a Node Wizard node.

Node Client is available as both a command line interface (CLI) and a web based interface (Node Client Web UI). Both provide the same control plane functionality for interacting with Node Wizard managed hosts. This document covers the Node Client CLI and how to configure it for use in this role. For the web-based interface, see Node Client Web UI.

Node Client Requirements​

  1. Supported Host OSes are Ubuntu 20.04, 22.04, 24.04, Rocky Linux 9.2, RHEL 9.2, Windows (amd64) or MacOS (amd64 or arm64)
  2. The system running Node Client must have network connectivity to the Node Wizard managed hosts it controls.

Install Node Client​

The file naming convention is node-client-<version>-<distribution>. In this guide we will use version 0.4.0. Please see Release for alternative versions and distributions.

  1. Download a release tarball from Download
  2. Extract Node Client
 tar -xvf node-client-0.4.0-<distribution>.tgz;
  1. Deploy Node Client

    • Linux OSes​

      After unpacking the deployment package, run deploy-node-client.sh. deploy-node-client.sh checks dependencies and previously installed versions. It will install any missing dependencies and deploy the node-client binary.

      Supported Parameters for deploy-node-client.sh:

      • -a Deploy all : default
      • -d Deploy node-client and check package dependencies. Skip version and Ubuntu ISO checking.
      • -l <version> link the installed node-client to this specific version
      • -h print usage
      cd node-client-0.4.0;
      ./deploy-node-client.sh;
      note

      node-client deployment on Linux systems provides autocompletion.

    • Windows / MacOS​

      No deployment script is provided for Windows and MacOS. The MacOS package includes just the node-client binary, and the Windows one provides a .exe file.
      You can run this binary using the terminal or powershell. For convenience, you can put the file into a directory in your $PATH.

      note

      No autocompletion is provided for Windows/MacOS.

Troubleshooting​

Quick Diagnostic Commands​

Run these first to quickly assess the situation:

# Check if node-client is working
node-client --version

Common Problems​

Corrupted node-client-0.4.0.tgz file​

  • Bash output of tar -xvf node-client-0.4.0-<distribution>.tgz is one of: 
    • gzip: stdin: unexpected end of file
      tar: Unexpected EOF in archive
      tar: Unexpected EOF in archive
      tar: Error is not recoverable: exiting now        
    • gzip: stdin: not in gzip format
      tar: Child returned status 1
      tar: Error is not recoverable: exiting now
    • gzip: stdin: invalid compressed data--crc error
      gzip: stdin: invalid compressed data--length error
      tar: Child returned status 1
      tar: Error is not recoverable: exiting now
    • tar: This does not look like a tar archive
      tar: Skipping to next header
      tar: A lone zero block at 11
      tar: Exiting with failure status due to previous errors
  • Cause: The node-client.tgz file is corrupted.
    • Verify:
      • Verify the file type matches expectations: 
        file node-client-latest-ubuntu22.tgz
        node-client-latest-ubuntu22.tgz: gzip compressed data...
      • check compression integrity (no output indicates success). 
        gzip -t node-client-latest-ubuntu22.tgz
  • Solution: Download Node Client again.

Incorrect architecture of node-client​

  • Bash output of running node-client 
    • bash: ./node-client: cannot execute binary file: Exec format error
  • Cause: Incorrect node-client architecture selected for download.
    • Verify:
      • check file type, it should match the target host environment: 
        #Linux x86_64
        file ./node-client
        ./node-client: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, Go BuildID=-iZte5sEl8PviVFqmcG1/3tFITwexGAaYU6eINNfK/H0jYpXh8P_dWFc5ljoWI/ZBGHplVsfVcpmWP_7_97, with debug_info, not stripped

        #macOS ARM64
        file ./node-client
        ./node-client: Mach-O 64-bit arm64 executable, flags:<|DYLDLINK|PIE>

        #macOS x86_64
        file ./node-client
        ./node-client: Mach-O 64-bit x86_64 executable, flags:<|DYLDLINK|PIE>
  • Solution: Download the correct architecture version of Node Client that matches the target host.

Incorrect distribution of node-client​

  • Bash output of running node-client 
    • bash: ./node-client /lib/x86_64-linux-gnu/libc.so.Z: version `GLIBC_X.YY' not found
  • Cause: Incorrect node-client distribution selected for download.
  • Solution: Download the correct distribution of Node Client that matches the target host.

Missing library​

  • Version command output: 
    node-client: error while loading shared libraries: libGL.so.1: cannot open shared object file: No such file or directory
  • Cause: A library is missing
  • Solution: Manually install the missing library or use deploy-node-client.sh with -d option. See Install Node Client