Skip to main content
Version: 0.4.0-beta

Node Wizard Installation

Node Wizard is a node level component of the Cluster Wizard system. Once installed, Node Wizard must be registered with a control plane, either Cluster Wizard or a Node Client, to become operational. Registration links the node to the control plane and establishes the identity and network information used for ongoing management and communication. This document describes how to install Node Wizard and prepare a host for integration into the Cluster Wizard system.

Node Wizard Requirements​

  1. Supported Host OSes are Ubuntu 20.04, 22.04, 24.04, Rocky Linux 9.2 and RHEL 9.2
  2. Network Bridge
    1. Node Wizard assumes a network bridge exists on the host. If one does not exist, it must be created before Node Wizard installation.
    2. This bridge requires Internet access.
  3. The node must have network connectivity to the selected control plane (Cluster Wizard or Node Client), depending on your deployment.
warning

Node Wizard creates a permanent identity for each node at registration time.

  • After registration, do not clone this system or move its operating system to another machine. Doing so will cause identity and authentication failures and may require the node to be reinstalled and re-registered.
  • Node Wizard data stored on each node must persist across reboots and updates.
  • If the IP address assigned to the bridge changes after registration, the node will be unable to reconnect until its configuration is updated in Cluster Wizard or Node Client.

Install Node Wizard as system service​

The file naming convention is node-wizard-<version>-<distribution>. In this guide we will assume version 0.4.0 and Ubuntu 22.04. Please see Node Wizard Release for alternative versions and distributions.

  1. Download a release tarball from Download
  2. Extract Node Wizard 
    tar -xvf node-wizard-0.4.0-ubuntu22.tgz;
  3. Create the Node Wizard systemd service by running the included installer, deploy-node-wizard.sh.
    You will be asked to specify the following for VMs that are run on this host:
    • A gateway IP address
    • A list of name servers (DNS)
    • The name of a network bridge to be used as the default network for VMs on this host
      • At least one network bridge must exist on the host.
      • If multiple bridges are available, the selected bridge will be used by default for newly created VMs unless explicitly overridden during VM creation.
      • See basic VM network settings for help listing available network bridges.
      • If a bridge is not available, see basic bridge creation for guidance on creating network bridges.
    • Virsh storage pool name configured for Ceph RBD pool (optional)
      • see basic VM network settings for more information about listing virsh pools.
      • If a virsh storage pool for Ceph is not available and a Ceph storage service is available, see ceph configuration for steps on creating a virsh RBD storage pool.

The network configuration provided here will be used for VMs only and will not modify the host machine’s network settings.

Supported Parameters for deploy-node-wizard.sh:

  • -a Deploy all : default
  • -d Deploy node-wizard and check package dependencies. Skip version checking.
  • -i Specify the path of env_node.json instead of using default values. eg) -i /tmp/env_node.json
  • -h print usage
cd node-wizard-0.4.0;
sudo ./deploy-node-wizard.sh;
note

The deploy-node-wizard.sh will print a token. This token is necessary to add this kvm host to node-client.

Verify Node Wizard is running​

  1. To verify the installation of Node Wizard, check that the status of the systemd service is in an active running state. 
    sudo systemctl status node-wizard.service

Node Wizard location​

  1. The Node-wizard binary is located at /root/bin/node_wizard/node-wizard.

GuestOS Setup​

  • To create a VM with the following guest OSes, the corresponding installer ISO files need to be placed at /storage/VM/iso directory:

  • GuestOS

    • RedHat 9.2 : rhel-9.2-x86_64-dvd.iso
    • RedHat 9.5 : rhel-9.5-x86_64-dvd.iso
    • Rocky 9.2 : Rocky-9.2-x86_64-dvd.iso
    • Rocky 9.5 : Rocky-9.5-x86_64-dvd.iso
    • SUSE Linux 15 SP5 : SLE-15-SP5-Full-x86_64-GM-Media1.iso
    • SUSE Linux 15 SP6 : SLE-15-SP6-Full-x86_64-GM-Media1.iso
    • Ubuntu 20.04 : ubuntu-20.04.4-live-server-amd64.iso
    • Ubuntu 22.04 : ubuntu-22.04.2-live-server-amd64.iso
    • Ubuntu 24.04 : ubuntu-24.04.1-live-server-amd64.iso
    • Windows Server 2019: Windows_Server2019.iso / virtio-win.iso

  • To download these files and verify md5sums, please see GuestOS download page

Troubleshooting​

Quick Diagnostic Commands​

Run these first to quickly assess the situation:

# Check if node-wizard is running
systemctl status node-wizard

# Check for logs
cat /var/log/node-wizard-err.log
cat /var/log/node-wizard-out.log

Common Problems​

Corrupted node-wizard-0.4.0.tgz file​

  • Bash output of tar -xvf node-wizard-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-wizard.tgz file is corrupted.
    • Verify:
      • Verify the file type matches expectations: 
        file node-wizard-latest-ubuntu22.tgz
        node-wizard-latest-ubuntu22.tgz: gzip compressed data...
      • check compression integrity (no output indicates success). 
        gzip -t node-wizard-latest-ubuntu22.tgz
  • Solution: Download Node Wizard again.

Corrupted subscription RHEL​

  • Bash output of deploy-node-wizard.sh contains:

       Retrieving all needed dependencies
       Update package list
       Installing This...
       Error: Failed to install This.

  • Cause: The deployment script can't retrieve required dependencies

    • Verify:
      • Verify the subscription using : 
        subscription-manager status

  • Solution: Reset and re-register your RHEL system with subscription-manager

    subscription-manager clean
    subscription-manager register

Missing env_node.json file​

  • Systemctl Output: 
    × node-wizard.service - Run node_wizard for kvm functionality expose
       Loaded: loaded (/etc/systemd/system/node-wizard.service; enabled; preset: enabled)
       Active: failed (Result: exit-code) since Mon 2025-09-22 23:04:27 CEST; 7min ago
     Duration: 42ms
      Process: 268436 ExecStart=/root/bin/node_wizard/node-wizard (code=exited, status=1/FAILURE)
     Main PID: 268436 (code=exited, status=1/FAILURE)
          CPU: 26ms
  • Error Logs:
2025/09/22 23:04:27 ERROR : open /root/bin/node_wizard/env_node.json: no such file or directory
2025/09/22 23:04:27 ERROR : SHUTDOWN node-wizard - failed to set env values - open /root/bin/node_wizard/env_node.json: no such file or directory

Invalid env_node.json file​

  • Systemctl Output: 
     × node-wizard.service - Run node_wizard for kvm functionality expose
      Loaded: loaded (/etc/systemd/system/node-wizard.service; enabled; preset: enabled)
      Active: failed (Result: exit-code) since Mon 2025-09-22 23:27:00 CEST; 1s ago
     Duration: 55ms
      Process: 271557 ExecStart=/root/bin/node_wizard/node-wizard (code=exited, status=1/FAILURE)
     Main PID: 271557 (code=exited, status=1/FAILURE)
      CPU: 33ms
  • Error Logs:
2025/09/22 23:27:00 ERROR : invalid character ':' after top-level value
2025/09/22 23:27:00 ERROR : SHUTDOWN node-wizard - failed to set env values - invalid character ':' after top-level value

NTP Problem​

  • Systemctl Output: 
     × node-wizard.service - Run node_wizard for kvm functionality expose
       Loaded: loaded (/etc/systemd/system/node-wizard.service; enabled; preset: enabled)
       Active: failed (Result: exit-code) since Mon 2025-09-22 23:37:23 CEST; 30s ago
     Duration: 2min 20.154s
      Process: 272695 ExecStart=/root/bin/node_wizard/node-wizard (code=exited, status=1/FAILURE)
     Main PID: 272695 (code=exited, status=1/FAILURE)
          CPU: 66ms
  • Error Logs:
2025/09/22 23:37:23 ERROR : time servers - retrying attempt 15 of 15
2025/09/22 23:37:23 ERROR : cannot get current time from time server 0
2025/09/22 23:37:23 ERROR : cannot get current time from time server 1
2025/09/22 23:37:23 ERROR : cannot get current time from time server 2
2025/09/22 23:37:23 ERROR : cannot get current time from time server 3
2025/09/22 23:37:23 ERROR : cannot get current time from time server 4
2025/09/22 23:37:23 ERROR : cannot get current time from time servers
2025/09/22 23:37:23 ERROR : SHUTDOWN node-wizard - failed to check current time - ERROR : cannot get current time from time servers
  • Cause: NTP servers are not available.
  • Solution: Check your firewall settings and your internet connection.

Service Running But Server Unavailable​

NTP Problem​

  • Systemctl Output: 
     ● node-wizard.service - Run node_wizard for kvm functionality expose
       Loaded: loaded (/etc/systemd/system/node-wizard.service; enabled; preset: enabled)
       Active: active (running) since Mon 2025-09-22 23:39:54 CEST; 10s ago
     Main PID: 273395 (node-wizard)
        Tasks: 6 (limit: 76757)
       Memory: 8.3M (peak: 9.2M)
          CPU: 32ms
       CGroup: /system.slice/node-wizard.service
               └─273395 /root/bin/node_wizard/node-wizard
  • Error Logs:
2025/09/22 23:37:23 ERROR : time servers - retrying attempt 5 of 15
2025/09/22 23:37:23 ERROR : cannot get current time from time server 0
2025/09/22 23:37:23 ERROR : cannot get current time from time server 1
2025/09/22 23:37:23 ERROR : cannot get current time from time server 2
2025/09/22 23:37:23 ERROR : cannot get current time from time server 3
2025/09/22 23:37:23 ERROR : cannot get current time from time server 4
...
  • Cause: NTP servers are not available and server is retrying to access them.
  • Solution: Check your firewall settings and your internet connection.

Network Management​

  • Systemctl Output: 
     ● node-wizard.service - Run node_wizard for kvm functionality expose
       Loaded: loaded (/etc/systemd/system/node-wizard.service; enabled; preset: enabled)
       Active: active (running) since Mon 2025-09-22 23:39:54 CEST; 10s ago
     Main PID: 273395 (node-wizard)
        Tasks: 6 (limit: 76757)
       Memory: 8.3M (peak: 9.2M)
          CPU: 32ms
       CGroup: /system.slice/node-wizard.service
               └─273395 /root/bin/node_wizard/node-wizard
  • Output Logs:
2025/09/22 23:48:27 Startup Vxlan: Vxlan {vxl517 517 enp2s0} already exists. Skipping.
2025/09/22 23:48:27 Startup Vxlan: Creating vxlan network.vxlan{Vxlanname:"vxl758", Vxlanid:758, Dev:"bla"}
2025/09/22 23:48:27 Startup Vxlan: Warning - Failed to create vxlan {Vxlanname:vxl758 Vxlanid:758 Dev:bla}. Cannot find device "bla"
, exit status 1
...
  • Cause: At startup, the different networks are created. If they are based on interfaces that no longer exist, the server keeps trying to create them. During this time, it remains unavailable.
  • Solution: After startup, try removing the networks causing issues to ensure a faster startup next time (using unregister-vxlan/unregister-vlan/unregister-bridge commands).