Version: 0.4.0-beta

Wizard Client (CLI) Installation

Wizard Client Requirements

Supported host operating systems:

Ubuntu 20.04, 22.04, 24.04
Rocky Linux 9.2
RHEL 9.2
Windows (amd64)
macOS (amd64 or arm64)

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

Download a release tarball from Wizard Client Downloads
Extract the tarball to obtain the wizard-client binary and the included README file:

 tar -xvf wizard-client-0.4.0-<distribution>.tgz;

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:
- See Install Wizard Client for steps on ensuring Cluster Wizard DNS name is resolvable.

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.

Wizard Client Requirements​

Install Wizard Client​

Configure Wizard Client with client certificate and CA​

Troubleshooting​

Common Problems​

Corrupted wizard-client-0.4.0.tgz file​

Incorrect permissions on wizard-client​

Incorrect architecture of wizard-client​

Incorrect distribution of wizard-client​

Cluster Wizard certificate not trusted or incorrect certificate specified​

DNS name of Cluster Wizard is not resolvable​

User certificate and private key do not match​

Cluster Wizard does not trust user's certificate​

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

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

Wizard Client Requirements

Install Wizard Client

Configure Wizard Client with client certificate and CA

Troubleshooting

Common Problems

Corrupted wizard-client-0.4.0.tgz file

Incorrect permissions on wizard-client

Incorrect architecture of wizard-client

Incorrect distribution of wizard-client

Cluster Wizard certificate not trusted or incorrect certificate specified

DNS name of Cluster Wizard is not resolvable

User certificate and private key do not match

Cluster Wizard does not trust user's certificate

User key pair already exists when generating a new key pair

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