Skip to main content
Version: 0.4.0-beta

Wizard Client (CLI) Installation

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. If Cluster Wizard is deployed without a certificate signed by a trusted Certificate Authority (CA), a CA certificate must be configured.
  3. 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.