Wizard Client CLI Usage
Wizard Client CLI provides a command line interface for interacting with Cluster Wizard.
Standard user Usage:
wizard-client -c [command] [options]
options:
-u [username] username
-pass [password] password
-v [vm name] vm name
-g [vm group name] vm group name
-snap [snapshot name] shapshot name
-key [key name] key
-s [server address] GRPC server address (default: cluster-wizard)
-p [server port] GRPC server port (default: 50001)
-cert [filename] certificate filename
-ca [CA filename] CA cert filename
-pkey [private key] private key filename
-out-type [json] output type - text(default) or json
command (default: list) :
All user
vm management
list list vm(s)
vm-start -v [vm name] start vm
vm-shutdown -v [vm name] shutdown vm
vm-destroy -v [vm name] destroy vm
dumpxml -v [vm name] dump vm's XML configuration
vncdisplay -v [vm name] show IP address and port number of the VNC display for vm
vm-info -v [vm name] show vm information
vm-domain-info -v [vm name] -key [ipaddr/os/bridge/hostdev/disk]
show ip address/os of running vm or bridge/hostdev/disk of vm
snapshot
snapshots list vm(s) and snapshots
take-snap -v [vm name] -snap [snapshot name] create rbd snapshot of vm
delete-snap -v [vm name] -snap [snapshot name] delete snapshot of vm
rollback -v [vm name] -snap [snapshot name] [optional:-key [domainxml key]]
vm rollback to snapshot, (optional define)using saved domain xml by xml key
dumpxml-snap -v [vm name] -snap [snapshot name] vm's XML configuration when snapshot was created
local-snapshots -v [vm name] list vm's local snapshots
take-local-snap -v [vm name] -snap [snapshot name] create local snapshot of vm
domainxml-list -v [vm name] list vm's saved XML informations
domainxml-get -v [vm name] -key [user-defined key] get vm's saved XML string by key
group
groups list user's groups
group-add -g [group name] create group
group-delete -g [group name] delete group
group-add-vm -g [group name] -v [vm name] add vm to group
group-remove-vm -g [group name] -v [vm name] remove vm from group
Help
-h|--help print general help
--help-admin|-c help-admin print help for admin
--version print wizard-client version
--autocompletion print autocompletion script
usage)$ source <(wizard-client --autocompletion)
-c version print software version of all servers
-c get-commands print authorized commands for current user
-c passwd change password
-c [command] -u [username] -pass [passwd] use username/password instead of certificate
Certificate
-c cert-gen-keys generate private/public key pair to create CSR
-c cert-create-csr create CSR file to get certificate
-c cert-set -cert [cert] [optional:-ca [CA cert]] set certificate and CA(optional)
-c cert-info print current certificate info
-c [command] -cert [cert] -ca [ca] -pkey [private key] using cert/ca/private key files instead of installed certificate
Cluster Wizard Connection
- default server=cluster-wizard, port=50001
- command line
$ wizard-client -s [server address] -p [port]
- environment variables on linux
$ export CLUSTER_WIZARD_SERVER=[server address]
$ export CLUSTER_WIZARD_PORT=[port]
notes:
Please make sure that a target vm is shut-off during take-snap and rollback.
Admin Usage:
wizard-client -c [command] [options]
options:
-u [username] username
-pass [password] password
-v [vm name] vm name
-g [vm group name] vm group name
-f [filename] file name
-t [template name] template name
-snap [snapshot name] shapshot name
-uu [target username] target username
-host [host name] hostname
-ip [ip addr] ip address
-s [server address] GRPC server address (default: cluster-wizard)
-p [server port] GRPC server port (default: 50001)
-pci [pci address] pci address of format xx:xx.x
-mac [mac address] mac address
-target [name] target of disk device
-br [bridge name] bridge network interface name
-suffix [bridge name suffix] bridge name suffix
-key [key name] key
-value [value ] value of key
-role [role ] role (admin or poweruser)
-cert [filename] certificate filename
-ca [CA filename] CA cert filename
-pkey [private key] private key filename
-vxlan [vxlan name] vxlan name
-dev [device name]] device name
-vlan [vlan name] vlan name
-id [id] id
-new [new value] new value
-o [option] option
-days [days] days
-url [url] url
-deleted
-detail
-dryrun
-out-type [json] output type - text(default) or json
command (default: list) :
All user
vm management
list list vm(s)
vm-start -v [vm name] start vm
vm-shutdown -v [vm name] shutdown vm
vm-destroy -v [vm name] destroy vm
dumpxml -v [vm name] dump vm's XML configuration
vncdisplay -v [vm name] show IP address and port number of the VNC display for vm
vm-info -v [vm name] show vm information
vm-domain-info -v [vm name] -key [ipaddr/os/bridge/hostdev/disk]
show ip address/os of running vm or bridge/hostdev/disk of vm
snapshot
snapshots list vm(s) and snapshots
take-snap -v [vm name] -snap [snapshot name] create rbd snapshot of vm
delete-snap -v [vm name] -snap [snapshot name] delete snapshot of vm
rollback -v [vm name] -snap [snapshot name] [optional:-key [domainxml key]]
vm rollback to snapshot, (optional define)using saved domain xml by xml key
dumpxml-snap -v [vm name] -snap [snapshot name] vm's XML configuration when snapshot was created
local-snapshots -v [vm name] list vm's local snapshots
take-local-snap -v [vm name] -snap [snapshot name] create local snapshot of vm
domainxml-list -v [vm name] list vm's saved XML informations
domainxml-get -v [vm name] -key [user-defined key] get vm's saved XML string by key
group
groups list user's groups
group-add -g [group name] create group
group-delete -g [group name] delete group
group-add-vm -g [group name] -v [vm name] add vm to group
group-remove-vm -g [group name] -v [vm name] remove vm from group
Admin
vm info
vm-list [optional:-host [host name]] list all vm, by host using -host(optional)
vm-list-host [optional:-host [host name]] list all vms on assigned hosts, by host using -host(optional)
update-vminfo -v [vm name] update db for a vm
update-vminfo-all update db for all vms
delete-vminfo -v [vm name] delete all data of vm from db
snapshots-list list all vm(s) and snapshots
vm assignment
assignments [optional:-uu [user name]] list vm assignments, optional by user
assignment-add -uu [target user name] -v [vm name] assign vm to user
assignment-delete -uu [target user name] -v [vm name] revoke vm from user
user management
users list users
user-add -uu [user name] add user
user-delete -uu [user name] delete user
user-set -uu [user name] -key [key] -value [val] update user using key [start_date/end_date/disabled/cluster_role/revoke_role/email/fullname/password/enable_password]
date format [YYYY-MM-DD HH24:MI:SS], disabled [true/false], cluster_role/revoke_role [admin/audit]
eg) -key start_date -value "2023-03-01 09:30:00"
eg) -key cluster_role -value admin (to give cluster admin role to user )
eg) -key revoke_role -value admin (to revoke cluster admin role from user)
eg) -key fullname -value "Firstname M Lastname"
host management
hosts [optional:-deleted] list hosts or deleted hosts with [-deleted]
host-add -host [host name] -ip [ip addr] -token [token] add host with ip address and token from node-wizard deployment
host-delete -host [host name] delete host
host-update -host [host name] -key [key] -value [value] [optional:-token [token]]
update host info with key[ipaddr/active] and value[ip address or true/false], required token for [ipaddr]
host-renew-lic [optional:-host [host name]] renew host licenses for all host or one host(optional)
host-info -host [host name] print system information of host
get-host-env -host [host name] print env values of host
set-host-env -host [host name] -key [key] -value [value] set env value of host using key [pool/gateway/nameservers/bridge]
host-log -host [host name] print node-wizard recent error log of host
list-allowed -host [host name] list allowed pci addresses on host
list-disallowed -host [host name] list disallowed network device/bridge names on host
host assignment
assignments-host [optional:-uu [user name]/-host [host name]] list host assignments, optional by user/host
assignment-host-add -uu [target user name] -host [host name] -role [admin or poweruser]
assign host and role to user
assignment-host-delete -uu [target user name] -host [host name] -role [admin or poweruser]
revoke host and role from user
group
group-list list groups for all user
vm management
vm-create -v [vm name] -f [json name] -host [host name] create vm with json file on host, -desc for usage
vm-delete -v [vm name] delete vm include snapshots
vm-hostdev-attach -v [vm name] -pci [pci address] attach host device of a given pci address
vm-hostdev-detach -v [vm name] -pci [pci address] detach host device of a given pci address
vm-disk-attach -v [vm name] -target [name] -f [json file] attach a disk, -desc for usage
vm-disk-detach -v [vm name] -target [name] detach a disk
vm-bridge-attach -v [vm name] -br [bridge name] attach network bridge
vm-bridge-detach -v [vm name] -mac [mac address] detach network bridge
vm-bridge-update -v [vm name] -mac [mac] -br [new bridge] update bridge of vm
vm-template -v [vm name] -t [template] [optional:-dryrun] create a template from vm
vm-clone -t [template name] -v [vm name] -ip [ip(x.x.x.x/x) or dhcp] -host [host name]
clone a vm from template, on host with ip(x.x.x.x/x or dhcp)
vm-template-list [optional:-host [host name]] print template list, by host using -host(optional)
vm-template-dumpxml -t [template name] dumpxml of template origin vm
vm-disable -v [vm name] disable vm
vm-enable -v [vm name] enable disabled-vm
vm-rename -v [vm name] -new [new vm name] rename vm
vm-migrate -v [vm name] -host [host] -o [live/offline] migrate vm using rbd storage to host with option[live/offline]
domainxml-save -v [vm name] -key [user-defined key] save vm's current XML configuration with key
domainxml-delete -v [vm name] -key [user-defined key] delete XML information by key
host network management
list-vxlan -host [host name] list vxlan(s) on host
register-vxlan -host [host name] -id [vxlan id] -dev [device] register vxlan
unregister-vxlan -host [host name] -vxlan [vxlan name] unregister vxlan
list-vlan -host [host name] list vlan(s) on host
register-vlan -host [host name] -id [vlan id] -dev [device] register vlan
unregister-vlan -host [host name] -vlan [vlan name] unregister vlan
list-bridge -host [host name] [optional:-detail] list bridge(s) on host, use -detail(optional) to list bridge/vm info
register-bridge -host [host name] -suffix [bridge name suffix] -dev [device name]
register bridge
unregister-bridge -host [host name] -br [bridge name] unregister bridge
list-network-interface -host [host name] list network interface(s) on host
iso management
iso-list -host [host name] list iso files on host
iso-download -host [host name] -url [download url] download iso file from url
user certificate management
cert-list-csr -o [option] [optional:-uu [user name]] list csrs with option[all/requested(default)/approved/rejected] and optional username
cert-sign-csr -id [id] -email/noemail -o [approve(default)/reject] -days [valid days]
sign csr for valid days(default:365) with option[approve(default)/reject], either -email/noemail for sending notification email or not
-uu [user name] -email/noemail -days [valid days(default:365)]
re-sign user's latest/approved csr, either -email/noemail
cert-get-csr -id [id] get csr information
cluster management
dashboard print summary of cluster
cluster-health [optional:-detail] print health status of cluster-wizard
cluster-env print env values of cluster-wizard
cluster-config print miscellaneous configurations for cluster
cluster-config-set -key [ubuntu_repo] -value [value] set value of key[ubuntu_repo] for cluster configuration
eg) -key ubuntu_repo -value [repo address]
eg) -key ubuntu_repo -value unset (to use default)
default(ubuntu repo):"http://archive.ubuntu.com/ubuntu/"
Help
-h|--help print general help
--help-admin|-c help-admin print help for admin
--version print wizard-client version
--autocompletion print autocompletion script
usage)$ source <(wizard-client --autocompletion)
-c version print software version of all servers
-c get-commands print authorized commands for current user
-c passwd change password
-c [command] -u [username] -pass [passpasswd] use username/password instead of certificate
-desc [command] print descriptions for vm-create/vm-disk-attach
Certificate
-c cert-gen-keys generate private/public key pair to create CSR
-c cert-create-csr create CSR file to get certificate
-c cert-set -cert [cert] [optional:-ca [CA cert]] set certificate and CA(optional)
-c cert-info print current certificate info
-c [command] -cert [cert] -ca [ca] -pkey [private key] using cert/ca/private key files instead of installed certificate
Cluster Wizard Connection
- default server=cluster-wizard, port=50001
- command line
$ wizard-client -s [server address] -p [port]
- environment variables on linux
$ export CLUSTER_WIZARD_SERVER=[server address]
$ export CLUSTER_WIZARD_PORT=[port]
notes:
Please make sure that a target vm is shut-off during take-snap and rollback.
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] -host [host name] create vm with json file on host
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) - specify instead of using default bridge",
"gateway" :"gateway (optional) - specify ip instead of using default gateway or "none" for not using gateway at all",
"nameservers":"nameservers (optional) - specify ip(s) instead of using default nameservers or "none" for not using nameservers at all",
"repo" :"ubuntu repository(optional) for ubuntu vm (default:"http://archive.ubuntu.com/ubuntu/")",
"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] 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" :"/lstorage/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.
wizard-client -c host-add -host [host name] -ip [host ip address] -token [token]
- Verify that the host is registered.
wizard-client -c hosts
warning
If IP address changes after a host is registered, it needs to be updated.
wizard-client -c host-update -host [host name] -key ipaddr -value [ip address] -token [token]
How to create a VM ?
To create a VM,
- Prepare a hash of a password for a VM's user account. You may use mkpasswd utility.
$ mkpasswd
Password: [password string]
- Create a json file that describes a VM's configuration with the password hash. Please refer to json file format for vm-create for detail or use
-desc vm-createcommand.
$ wizard-client -desc vm-create
- Create a VM with the json file. The VM will be created on the node specified by [host name].
$ wizard-client -c vm-create -v [vm name] -f [json filename] -host [host name]
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.
If you want to check the progress, you may connect to the vnc of the VM console. The VNC connection detail can be retrieved as shown below.
$ wizard-client -c vncdisplay -v [vm name]
For a detailed walk-through, please see Node Client - How to create a VM which provides steps using Node Client.