Skip to main content
Version: 0.5.0

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 (WebUI). 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 WebUI.

Node Client Requirements​

  1. Supported Host OSes are Ubuntu 20.04, 22.04, 24.04, Rocky Linux 9.2, RHEL 9.2, SLES 15 SP7, 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​

Install Node Client (using auto deployment script)​

  1. Download an auto deployment script from Cluster Wizard Product Deployments on the host.
wget https://raw.githubusercontent.com/corespeq-cw/deployments/refs/heads/main/scripts/auto_deploy_software.sh
  1. Install Node Client by running the downloaded script, auto_deploy_software.sh. It will detect the Host OS, download and install Node Client accordingly (Please note that the auto deployment is not available for Windows).
bash auto_deploy_software.sh node-client 0.5.1
You are going to download node-client 0.5.1 for ubuntu24
Do you want to continue? (y/n)
y
Confirmed, continuing...

...

Do you accept the license? (y/n)
y
Confirmed, continuing...

Install Node Client (using the tarball)​

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

  1. Download a release tarball from Node Client Downloads
  2. Extract Node Client
 tar -xvf node-client-0.5.1-<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 with checking dependencies, skip checking version
      • -s Skip checking dependencies and installing missing packages
      • -l <version> link the installed node-client to this specific version (the version need to be installed)
      • -h print usage
      cd node-client-0.5.1;
      ./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.5.1.tgz file​

  • Bash output of tar -xvf node-client-0.5.1-<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

Missing subscription​

  • Bash output of running deploy-node-client.sh
...
Installing package_name
Error: Failed to install package_name
...
Installing Repo
Error: Failed to install Repo
  • Cause: Your RHEL or SLES subscription seems expired or invalid.
  • Solution: Please try to re-register your system.

Auto Deployment script failure​

  • Cause: If the auto deployment script is failing with error related to package installation, a conflict or an invalid subscription is probably the cause.
  • Solution: Try to run the auto deployment script with -s option
Do you want to continue? (y/n)
y
Confirmed, continuing...

NO LICENSE DISPLAYED

Do you accept the license? (y/n)
Do you accept the license? (y/n)
y
Confirmed, continuing...

END OF SCRIPT

---

echo $?
1
  • Cause: The auto deployment script requires a network access to download the license content and download the binary to install.
  • Solution: Please verify your network connection and that you have access to gitlab.com website.