Node Client CLI Usage
Node Client CLI provides a command line interface for interacting with Node Wizard managed hosts.
Standard user Usage:
Usage :node-client [options] -c [command] [command-options]
Options:
-v [vm name] vm name
-new [new vm name] new vm name
-t [template name] template name
-f [json filename] file name
-token [token] token
-snap [snapshot name] snapshot name
-pci [pci address] pci address of format xx:xx.x
-target [name] target of disk device
-br [bridge name] bridge network interface name
-S [server] GRPC server address
-key [key] key name
-ip [ip] ip to use
-value [value] value name
-out-type [json] output type - text(default) or json
Commands:
license/server management:
register-server -S [server] -token [token] register the GRPC server as known node-wizard server
list-server list all node-wizard server known by your node-client
list-license list all node-wizard server with license
unregister-server -S [server] unregister the GRPC server from known node-wizard server list
set-license -f [license_file] set the license in the license list of the program
request-license open a graphical user interface to send a request to the license server
node-wizard management:
get-host-env -S [server] print environment values of server
set-host-env -S [server] -key [key] -value [value] set environment value of server using key ["pool"/"gateway"/"nameservers"/"bridge"]
version -S [server] print node-wizard software version
vm management:
list -S [server] list vm(s) on the server
vm-start -S [server] -v [vm name] start server's vm
vm-shutdown -S [server] -v [vm name] shutdown server's vm
vm-destroy -S [server] -v [vm name] destroy server's vm
dumpxml -S [server] -v [vm name] dump server vm's XML configuration
vncdisplay -S [server] -v [vm name] show IP address and port number of the VNC display for server's vm
vm-create -S [server] -v [vm name] -f [json name] create vm with json file on server
vm-delete -S [server] -v [vm name] delete server's vm include snapshots
vm-rename -S [server] -v [vm name] -new [new vm name] rename vm
vm-hostdev-attach -S [server] -v [vm name] -pci [pci address] attach host device of a given pci address
vm-hostdev-detach -S [server] -v [vm name] -pci [pci address] detach host device of a given pci address
vm-disk-attach -S [server] -v [vm name] -target [name] -f [json file] attach a disk
vm-disk-detach -S [server] -v [vm name] -target [name] detach a disk
vm-bridge-attach -S [server] -v [vm name] -br [bridge name] attach network bridge
vm-bridge-detach -S [server] -v [vm name] -mac [mac address] detach network bridge
vm-bridge-update -S [server] -v [vm name] -mac [mac] -br [new bridge] update bridge of vm
vm-domain-info -S [server] -v [vm name] -key [ipaddr/os/bridge/hostdev/disk] show ip address(es) or os of running vm or vm bridge(s) or vm hostdev(s) or vm disk(s) (key ["ipaddr"/"os"/"bridge"/"hostdev"/"disk"])
snapshot:
snapshot local:
local-snapshots -S [server] -v [vm name] list vm's local snapshots on server
take-local-snap -S [server] -v [vm name] -snap [snapshot name] create snapshot of server's vm
delete-local-snap -S [server] -v [vm name] -snap [snapshot name] delete snapshot of server's vm
rollback-local -S [server] -v [vm name] -snap [snapshot name] server's vm rollback to snapshot
template/clone:
vm-template-local -S [server] -v [vm name] -t [template name] [-dryrun] create a template from vm, use -dryrun(optional) to see if template is supported
vm-clone -S [server] -t [template name] -v [vm name] -ip [ip] clone a vm from template (ip can be dhcp)
vm-template-local-list -S [server] print template list
network management:
list-vxlan -S [server] list vxlan(s) on host
register-vxlan -S [server] -id [vxlan id] -dev [device name] register vxlan
unregister-vxlan -S [server] -vxlan [vxlan name] unregister vxlan
list-vlan -S [server] list vlan(s) on host
register-vlan -S [server] -id [vlan id] -dev [device name] register vlan
unregister-vlan -S [server] -vlan [vlan name] unregister vlan
list-bridge -S [server] [-detail] list bridge(s) on host, use -detail(optional) to list bridge(s)/vm(s) info
register-bridge -S [server] -suffix [bridge name suffix] -dev [device name] register bridge
unregister-bridge -S [server] -br [bridge name] unregister bridge
list-network-interface -S [server] list network interface(s) on host
iso management
iso-list -S [server] list iso files on host
iso-download -S [server] -url [download url] download iso file from url
system management:
system-info -S [server] list system informations (CPU, Memory, Disk, etc...)
system-log -S [server] print node-wizard error log (Max 100 lines)
list-allowed -S [server] list allowed pci addresses
list-disallowed -S [server] list disallowed device names
Help:
node-client -h|--help print general help
node-client -desc [command] print descriptions for vm-create/vm-disk-attach
node-client --version print node-client version
node-client --autocompletion print node-client autocompletion script
Description (-desc command): vm-create
- vm-create : create a vm command
note
Some Host OSes are known to have issues with VM names containing an underscore "_"
usage :
-c vm-create -v [vm name] -f [json file name] -S [server] create vm with json file on server
json file format :
{
"vm_mem" :"vm memory in GiB",
"vm_core" :"vm number of core",
"vm_img_size":"vm image size in GiB",
"os_variant" :"vm os version [ubuntu20.04/ubuntu22.04/ubuntu24.04, rocky9.2/rocky9.5/rocky10.0, rhel9.2/rhel9.5/rhel10.0, sles15/sles15-sp6/sles15-sp7 or win2k19]",
"vm_img_type":"vm image type [rbd or local]",
"localpath" :"a path to vm image, required when vm_img_type is local",
"fstype" :"xfs or ext4 (default:xfs), set for linux only",
"ipaddr" :"vm [ip address/subnet] or [dhcp] for using dhcp4",
"username" :"vm username",
"passwd" :"password - plain text for windows vm and hash string for the rest",
"auth_keys" :["ssh keys (optional)"],
"bridge" :"bridge name (optional)",
"gateway" :"gateway or "none" (optional),
"nameservers":"nameservers or "none" (optional)",
"repo" :"ubuntu repository (default: "http://us.archive.ubuntu.com/ubuntu") (optional),
"log_partition":"/var/log partition size in GiB (optional) for ubuntu vm (default: 16)"
}
example)
{
"vm_mem" :"12",
"vm_core" :"4",
"vm_img_size":"64",
"os_variant" :"ubuntu20.04",
"vm_img_type":"rbd",
"localpath" :"",
"fstype" :"xfs",
"ipaddr" :"172.25.20.133/17",
"username" :"cluster-admin",
"passwd" :"$6$q4j7WjSYTWHwje1B$o/z1qyy....",
"auth_keys" :["ssh-rsa A#BCW!@#.... "],
"bridge" :"br0External",
"gateway" :"172.25.101.1",
"nameservers":"172.25.100.1,172.25.110.1",
"log_partition":"18"
}
example for windows vm)
{
"vm_mem" :"12",
"vm_core" :"4",
"vm_img_size":"64",
"os_variant" :"win2k19",
"vm_img_type":"local",
"localpath" :"/storage/VM/images/",
"ipaddr" :"172.25.20.133/17",
"username" :"cluster-admin",
"passwd" :"ChangeMe"
}
Description (-desc command): vm-disk-attach
- vm-disk-attach : attach a disk to a vm command
usage :
-c vm-disk-attach -v [vm name] -target [name] -f [json file] -S [server] attach a disk to vm with json file
json file format :
{
"img_type" :"image type [rbd or local]",
"img_size" :"image size in GiB",
"img_format" :"image format when img_type is local [raw or qcow2]",
"localpath" :"image path when img_type is local"
}
example)
{
"img_type" :"local",
"img_size" :"128",
"img_format" :"qcow2",
"localpath" :"/storage/VM/images"
}
How to register a VM host ?
To register a VM host,
- Get Node Wizard token from the VM host - use the printed token during the Node Wizard installation, or connect to the host and use the command below.
sudo /root/bin/node_wizard/node-wizard --token
- Register the host using its IP address or DNS name.
node-client -c register-server -S [server] -token [token]
- Verify that the host is registered.
node-client -c list-server
warning
If IP address is used for host registration and changed after that, the host needs to be re-registered.
node-client -c unregister-server -S [IP address]
node-client -c register-server -S [new IP address]
How to create a VM ?
This is a walk-through for VM Creation.
- To get a hash of a password, we will use the mkpasswd utility.
$ sudo apt install whois
$ mkpasswd
Password: mypassword
$y$j9T$0/PuSDxIvi6GlhLZ6ddOI1$K9KTlLvUvH9eNzRA06EpagXsSds/tHTYTUTdDFbfv81 - Next, we will create a JSON file that describes my VM. The command
node-client -desc vm-createcan provide more information about the JSON file format.configs/test-vm.json{
"vm_mem" :"4",
"vm_core" :"4",
"vm_img_size":"64",
"os_variant" :"ubuntu24.04",
"vm_img_type":"local",
"localpath" :"/storage/VM/images/",
"fstype" :"ext4",
"ipaddr" :"dhcp",
"username" :"cluster-admin",
"passwd" :"$y$j9T$0/PuSDxIvi6GlhLZ6ddOI1$K9KTlLvUvH9eNzRA06EpagXsSds/tHTYTUTdDFbfv81"
} - It's finally time to create the VM.
Depending on the host and network, it will take some time for the VM auto-installation to be done. When it is done, the status of VM will be shut-off.
$ node-client -S localhost -c vm-create -v test-vm -f configs/test-vm.jsonIf you want to check the progress, you may connect to the vnc of the VM console. The VNC connection detail can be retrieved using Node Client as well.$ node-client -S localhost -c list$ node-client -S localhost -c vncdisplay -v test-vm - Once the installation is finished, we start the test-vm, connect to it, and begin work.\
To find the IP address assigned by DHCP, we again use Node Client.
$ node-client -S localhost -c vm-start -v test-vm$ node-client -S localhost -c vm-domain-info -v test-vm -key ipaddr - Now, we can connect to the VM through ssh using the IP provided by the previous command.