Version: 0.4.0-beta

Node Wizard Installation

Node Wizard Requirements

Supported Host OSes are Ubuntu 20.04, 22.04, 24.04, Rocky Linux 9.2 and RHEL 9.2
Network Bridge
1. Node Wizard assumes a network bridge exists on the host.
2. This bridge requires internet access.
- See the creating network bridges guide for more information.

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.

Download a release tarball from Download

Extract Node Wizard

tar -xvf node-wizard-0.4.0-ubuntu22.tgz;

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
- A gateway IP address
- A list of name servers
- A bridge name that will be attached
- Virsh pool name configured for Ceph RBD pool (optional)
The network configuration will be used for VMs, not for the host machine. See basic VM network settings for more information.

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

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

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

Cause: The env_node.json file has not been created.
Solution: Use deploy-node-wizard.sh with -d option. See Install Node Wizard as system service

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

Cause: The env_node.json file is malformated.
Solution: Use deploy-node-wizard.sh with -d option. See Install Node Wizard as system service

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

Node Wizard Requirements​

Install Node Wizard as system service​

Verify Node Wizard is running​

Node Wizard location​

GuestOS Setup​

Troubleshooting​

Quick Diagnostic Commands​

Common Problems​

Corrupted node-wizard-0.4.0.tgz file​

Corrupted subscription RHEL​

Missing env_node.json file​

Invalid env_node.json file​

NTP Problem​

Service Running But Server Unavailable​

NTP Problem​

Network Management​

Node Wizard Requirements

Install Node Wizard as system service

Verify Node Wizard is running

Node Wizard location

GuestOS Setup

Troubleshooting

Quick Diagnostic Commands

Common Problems

Corrupted node-wizard-0.4.0.tgz file

Corrupted subscription RHEL

Missing env_node.json file

Invalid env_node.json file

NTP Problem

Service Running But Server Unavailable

NTP Problem

Network Management