Skip to main content
Version: 0.4.0-beta

Wizard Client (CLI) Installation

Wizard Client is a command line interface for interacting with the Cluster Wizard control plane. It provides authenticated access for performing management operations such as registering nodes and querying cluster state. Wizard Client acts as a management interface and can run on any machine that has network access to Cluster Wizard.

Wizard Client is available as both a command line interface (CLI) and a web based interface (Wizard Client Web UI). Both provide the same control plane functionality.

This document describes how to install and configure the Wizard Client CLI. For the web based interface, see Wizard Client Web UI.

Wizard Client Requirements​

  1. Supported host operating systems:
  • Ubuntu 20.04, 22.04, 24.04
  • Rocky Linux 9.2
  • RHEL 9.2
  • Windows (amd64)
  • macOS (amd64 or arm64)
  1. A Cluster Wizard server must be installed and running.
  2. The system running Wizard Client must have network connectivity to the Cluster Wizard service.
  3. If Cluster Wizard is deployed without a certificate signed by a trusted Certificate Authority (CA), a CA certificate must be configured.
  4. If Cluster Wizard is deployed with a certificate that includes dnsNames, those DNS entries must be resolvable from the host where Wizard Client is installed.

Install Wizard Client​

The file naming convention is wizard-client-<version>-<distribution>. In this guide we will use version 0.4.0.
See Wizard Client Downloads for alternative versions and distributions.

  1. Download a release tarball from Wizard Client Downloads
  2. Extract the tarball to obtain the wizard-client binary and the included README file:
 tar -xvf wizard-client-0.4.0-<distribution>.tgz;
  1. Setup Wizard Client

    • If Cluster Wizard is deployed with a certificate that includes dnsNames, those DNS entries must be resolvable from the current host. Consider:

      • Adding the required entries to your DNS server.
      • On Linux or macOS adding entries to /etc/hosts.
      • On Windows adding entries to C:\Windows\System32\drivers\etc\hosts.
      note

      The Wizard Client defaults to a DNS name of cluster-wizard and port 50001. To use a different name or port:

      • On Linux or macOS, set the environment variable CLUSTER_WIZARD_SERVER and CLUSTER_WIZARD_PORT

      Example:

      export CLUSTER_WIZARD_SERVER="my-cluster-wizard.corespeq.com"
      export CLUSTER_WIZARD_PORT="443"
      • Alternatively, wizard-client accepts the -s (server address) and -p (port) parameters.

      Example:

      wizard-client -s my-cluster-wizard.corespeq.com -p 443

      Both methods are equivalent, use whichever is more convenient for your environment.

Configure Wizard Client with client certificate and CA​

  • Client certificate
    1. Generate certificate key pair 
      wizard-client -c cert-gen-keys
    2. Generate certificate signing request (CSR). The CSR will be sent to the Cluster Wizard administrator, who may approve it and provide the client certificate and CA files. 
      wizard-client -c cert-create-csr
    3. Use the cert-set command to configure Wizard Client with the certificate. If Cluster Wizard is deployed without a certificate signed by a trusted CA, use the -ca flag to specify the CA certificate: 
      wizard-client -c cert-set -cert <cert_file> -ca <ca_file>
  • Optional: Set Up Shell Auto-Completion (Linux Only)
    • Install required packages: 
      apt install jq
    • Enable auto-completion: 
      source <(wizard-client --autocompletion)

Troubleshooting​

Common Problems​

Corrupted wizard-client-0.4.0.tgz file​

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

Incorrect permissions on wizard-client​

  • Bash output of running wizard-client 
    • bash: ./wizard-client: Permission denied
  • Cause: Incorrect file permissions on wizard-client
    • Verify:
      • check file exists and is executable by running: 
        [ -e ./wizard-client ] && ( [ -x ./wizard-client ] && echo "wizard-client is executable" || echo "wizard-client exists but is NOT executable" ) || echo "wizard-client does not exist"
  • Solution: Correct file permissions to make file executable chmod a+x wizard-client

Incorrect architecture of wizard-client​

  • Bash output of running wizard-client 
    • bash: ./wizard-client: cannot execute binary file: Exec format error
  • Cause: Incorrect wizard-client architecture selected for download.
    • Verify:
      • check file type, it should match the target host environment: 
        #Linux x86_64
        file ./wizard-client
        ./wizard-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 ./wizard-client
        ./wizard-client: Mach-O 64-bit arm64 executable, flags:<|DYLDLINK|PIE>

        #macOS x86_64
        file ./wizard-client
        ./wizard-client: Mach-O 64-bit x86_64 executable, flags:<|DYLDLINK|PIE>
  • Solution: Download the correct architecture version of Wizard Client that matches the target host.

Incorrect distribution of wizard-client​

  • Bash output of running wizard-client 
    • bash: ./wizard-client /lib/x86_64-linux-gnu/libc.so.Z: version `GLIBC_X.YY' not found
  • Cause: Incorrect wizard-client distribution selected for download.
  • Solution: Download the correct distribution of Wizard Client that matches the target host.

Cluster Wizard certificate not trusted or incorrect certificate specified​

  • Bash output of running wizard-client 
    • ./wizard-client -c list
      [ERROR] : rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: tls: failed to verify certificate: x509: certificate signed by unknown authority (possibly because of \"x509: ECDSA verification failure\" while trying to verify candidate authority certificate \"CORESPEQ INC\")"
  • Cause: The Cluster Wizard certificate, ca_cert.pem, is incorrect or not trusted by target host.
  • Solutions:
    • If ca_cert.pem was set by wizard-client for future use, verify that ca_cert.pem exists: 
      ls ~/.wizard-clients/ca_cert.pem
      If certificate exists, it does not match the Cluster Wizard that wizard-client is communicating with. Delete and replace with Cluster Wizard certificate, ca_cert.pem, provided by Cluster Wizard admin.
    • If ca_cert.pem was not set by wizard-client for future use, obtain a Cluster Wizard certificate, ca_cert.pem, from a Cluster Wizard admin and use -ca ./ca_cert.pem when using wizard-client. eg: 
      wizard-client -c cert-create-csr -ca ./ca_cert.pem
    • Obtain a Cluster Wizard certificate, ca_cert.pem, from a Cluster Wizard admin and set it for future use when adding the user's certificate. 
       wizard-client -c cert-set -cert user_cert.pem -ca ./ca_cert.pem
      See Configure Wizard Client with client certificate and CA.
    • Obtain a Cluster Wizard certificate, ca_cert.pem, from a Cluster Wizard admin and add it to target hosts certificate trust. Steps vary depending on target host OS.
    • Use a publicly trusted certificate for Cluster Wizard.

DNS name of Cluster Wizard is not resolvable​

  • Bash output of running wizard-client 
    • ./wizard-client -c list
      [ERROR] : rpc error: code = Unavailable desc = dns: A record lookup error: lookup cluster-wizard: server misbehaving
  • Cause: The DNS name used by Cluster Wizard is not resolvable by target host
  • Solutions:

User certificate and private key do not match​

  • Bash output of running wizard-client 
    • ./wizard-client -c list
      [ERROR] : failed to load client cert: tls: private key type does not match public key type
  • Cause: The user's certificate and private key used for mTLS communication to Cluster Wizard do not match.
  • Solutions:
    • If using -cert and -pkey with wizard-client the certificate and private key specified do not match. Use the correct files for certificate and private key. eg:
    ./wizard-client -c list -cert user-cert.crt -ca ./ca_cert.pem  -pkey user-private.key
    • The certificate stored at ~/.wizard-clients/wizard-clients_cert.pem and private key stored at ~/.wizard-clients/wizard-clients_private_key.pem do not match. Backup files, and replace with correct files. If correct files are missing, consider creating a new key pair and submitting a CSR, see Configure Wizard Client with client certificate and CA.

Cluster Wizard does not trust user's certificate​

  • Bash output of running wizard-client 
    • ./wizard-client -c list 
      [ERROR] : rpc error: code = Unavailable desc = connection error: desc = "error reading server preface: remote error: tls: unknown certificate authority"
  • Cause: Cluster Wizard does not trust the user's certificate. Either the certificate was signed by a different CA, or the certificate used is incorrect.
  • Solutions: If a signed certificate is not available see Configure Wizard Client with client certificate and CA for steps on how to obtain a signed certificate.
    • If using -cert and -pkey with wizard-client the certificate specified is not trusted by Cluster Wizard. Use a certificate signed by the Cluster Wizard's CA. eg:
    ./wizard-client -c list -cert user-cert.crt -ca ./ca_cert.pem  -pkey user-private.key
    • If not using -cert and -pkey, then the certificate stored at ~/.wizard-clients/wizard-clients_cert.pem is not trusted by Cluster Wizard. Backup file, and replace with a Cluster Wizard signed certifcate.

User key pair already exists when generating a new key pair​

  • Bash output of running wizard-client 
    • ./wizard-client -c cert-gen-keys
      [ERROR] : create Key Files - File [/home/user/.wizard-clients/wizard-clients_private_key.pem] exists
  • Cause: When generating a new key pair, if a key pair already exists wizard-client will exit with an error.
  • Solution: The key pair stored at ~/.wizard-clients/wizard-clients_cert.pem and ~/.wizard-clients/wizard-clients_private_key.pem prevents wizard-client from generating a new one. Confirm that the current key pair is no longer needed, then delete or back it up.

User attempted to submit a CSR, but no key pair exists​

  • Bash output of running wizard-client 
    • wizard-client -c cert-create-csr
      [ERROR] : private key - File [/home/cluster-admin/.wizard-clients/wizard-clients_private_key.pem] does not exist
  • Cause: User attempted to submit a CSR, but no key pair exists to create a CSR.
  • Solution: The user needs to run ./wizard-client -c cert-gen-keys before wizard-client -c cert-create-csr. See Configure Wizard Client with client certificate and CA.