# PCD CLI - pcdctl

<code class="expression">space.vars.product\_acronym</code> CLI (`pcdctl`) is a unified command line interface (CLI) tool to manage all your <code class="expression">space.vars.product\_name</code> services. `pcdctl` lets you install, manage, update Platform9 host agent and related software components on your hypervisor hosts. It also enables you to run all supported operations across all <code class="expression">space.vars.product\_name</code> services. The goal of <code class="expression">space.vars.product\_acronym</code> CLI is to be a single unified tool that enables you to control all <code class="expression">space.vars.product\_name</code> services and automate them.

## Under The Hood

`pcdctl` acts as a wrapper on [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) and exposes all OpenStack CLI commands for OpenStack services that <code class="expression">space.vars.product\_name</code> is API compatible with. Read [Service Specific Commands](#service-specific-commands) for more info.

`pcdctl` also provides access to all non OpenStack services that <code class="expression">space.vars.product\_name</code> utilizes and exposes.

{% hint style="warning" %}
**Important**

`pcdctl` acts as a wrapper on [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) and exposes all OpenStack CLI commands for OpenStack services that <code class="expression">space.vars.product\_name</code> is API compatible with. Read [Service Specific Commands](#service-specific-commands) for more info.
{% endhint %}

## Before You Install

Before you install <code class="expression">space.vars.product\_acronym</code> CLI, please note the following:

* If you have <code class="expression">space.vars.product\_acronym</code> CLI installed previously and need to update it with the latest <code class="expression">space.vars.product\_acronym</code> CLI then do run the command`rm /usr/bin/pcdctl` before running the curl to the setup script
* When using <code class="expression">space.vars.product\_acronym</code> CLI to prepare and onboard a new host to be added to <code class="expression">space.vars.product\_name</code>, you need to install and run the CLI on the host being added. Ability to perform remote install and onboarding of new host using <code class="expression">space.vars.product\_acronym</code> is coming in the future.
* When using <code class="expression">space.vars.product\_acronym</code> CLI to control your <code class="expression">space.vars.product\_name</code> services, you can run <code class="expression">space.vars.product\_acronym</code> CLI on any node with network connectivity to your <code class="expression">space.vars.product\_name</code> environment.

## Prerequisites

* If using <code class="expression">space.vars.product\_acronym</code> CLI to onboard a new host into your <code class="expression">space.vars.product\_name</code> setup, make sure to install <code class="expression">space.vars.product\_acronym</code> CLI on that host. Also ensure that the [host prerequisites](https://docs.platform9.com/private-cloud-director/getting-started/pre-requisites#hypervisor-host-prerequisites) are met before using <code class="expression">space.vars.product\_acronym</code> CLI to onboard a new host.
* If using <code class="expression">space.vars.product\_acronym</code> to access your <code class="expression">space.vars.product\_name</code> service specific commands beyond host onboarding, you can install it on any Ubuntu machine with network access to your <code class="expression">space.vars.product\_name</code> setup.
* If your host is configured with network bonds, verify that the bonding mode is either active-passive or LACP.

## Installation

To install <code class="expression">space.vars.product\_acronym</code> CLI `pcdctl`, execute the following command on the machine you are installing the CLI on:

{% tabs %}
{% tab title="Bash" %}

```yaml
bash <(curl -s https://pcdctl.s3.us-west-2.amazonaws.com/pcdctl-setup)
```

{% endtab %}
{% endtabs %}

To view available commands and their information, use the help command:

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl --help
```

{% endtab %}
{% endtabs %}

For help with a specific command, run the following:

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl [command] --help
```

{% endtab %}
{% endtabs %}

### Global Flags

Following global flags apply to any run of `pcdctl`

`--log-dir` string — path to save pcdctl logs

`--no-prompt` disable all user prompts

`--verbose` print verbose logs

### Check External Connectivity

Before configuring, installing, or upgrading, use the following command to verify connectivity to external endpoints required by the platform:

```
pcdctl check-url
```

This command checks whether the system can reach a predefined set of external URLs.

**Usage notes**

* In an internet-connected environment, all required URLs should be reachable.
* If any required URLs are unreachable, verify network connectivity, DNS resolution, and proxy configuration.

{% hint style="info" %}
**Air-Gapped Environments**

This command is not intended to validate air-gapped setups. In air-gapped environments, failures reported by this command are expected and do not indicate an issue.
{% endhint %}

## Configuration

Before using `pcdctl` with your <code class="expression">space.vars.product\_name</code> environment, you need to configure it:

1. Navigate to `Settings` menu option located on the top right corner in the UI.
2. Choose API Access -> pcdctl RC.
3. Copy the contents to a new file named `pcdctlrc`
4. Update `OS_PASSWORD` with your <code class="expression">space.vars.product\_name</code> password
5. Run `source pcdctlrc` to set the required environment variables

### Configuration Commands

#### config set

This command sets the configuration details for your <code class="expression">space.vars.product\_name</code> setup. These configuration details are stored in ``~/pf9/db/config.json `file`.``

Run this command first prior to running any other `pcdctl` commands to set your account url and credentials once instead of having to specify it for each command.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl config set
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-u, --account-url` string – Sets account URL

`-h, --help` – Displays help for set

`-p, --password` string – Sets password (use 'single quotes' to pass password)

`-r, --region` string – Sets region

`-t, --tenant` string – Sets tenant

`-e, --username` string – Sets the username

`-l, --proxy-url` string — Sets the http(s) proxy URL specified as \[]\[:@]:

{% hint style="warning" %}
For the repository specified by the `--private-package-repo` flag to be used to install dependencies and to avoid configuring ubuntu official repositories `pcdctl prep-node` must be run with the `--skip-repo-config` flag.

**Note:** User themselves needs to make sure no unreachable apt sources are present before they run pcdctl. Also, users need to manually trust CA certs for Self-Signed Private Registries as this is NOT being handled within pcdctl.
{% endhint %}

`--private-package-repo` string — Sets the URL for the registry to use for installing dependencies

#### config get

Retrieves the current configuration settings

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl config get
```

{% endtab %}
{% endtabs %}

## Host Onboarding & Management Commands

### prep-node

The `prep-node` command allows you to add a new host to your <code class="expression">space.vars.product\_name</code> environment. This command prepares the host with required pre-requisites by downloading and installing a set of required software packages on the host, so that it can be used in your <code class="expression">space.vars.product\_name</code> environment.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl prep-node
```

{% endtab %}
{% endtabs %}

**Parameters:**

{% hint style="info" %}
You can configure the private repository by using `pcdctl config set --private-package-repo <repo>`
{% endhint %}

`--skip-repo-config` boolean, default: false — disable configuration of ubuntu cloud archive repos - only applicable if using private repos to host dependencies

### authorize-node

{% hint style="info" %}
`authorize-node` is deprecated. There is no replacement CLI command.

Use the console to authorize the host and assign roles.
{% endhint %}

This command assigns a <code class="expression">space.vars.product\_name</code> role to the host.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl authorize-node [flags]
```

{% endtab %}
{% endtabs %}

Flags:

`-h, --help` help message for authorize-node

`--role` string role for the host

### decommission-node

Decommissions this host from <code class="expression">space.vars.product\_acronym</code> management plane and purges all <code class="expression">space.vars.product\_acronym</code> components on the host.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl decommission-node [flags]
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-h, --help` help message for decommission-node

### deauthorize-node

Removes roles from an onboarded node.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl deauthorize-node [flags]
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-h, --help` help message for deauthorize-node

`-t, --timeout` string, default: "5m", timeout for the operation

## Service Specific Commands

`pcdctl` acts as a wrapper on open source [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) for all operations specific to the following <code class="expression">space.vars.product\_name</code> services, as these services expose OpenStack APIs.

* Compute Service
* Block Storage Service
* Network Service
* Identity Service

It exposes all commands that are exposed by the [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) corresponding to these services.

You can find a [complete reference here](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) for supported OpenStack CLI commands. When executing these commands with pcdctl, replace `openstack` with `pcdctl` before executing the command.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl [command] [flags] [subcommands]
```

{% endtab %}
{% endtabs %}

**Examples**

Following command lists all block storage volumes.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl volume list
```

{% endtab %}
{% endtabs %}

Following command lists all networks in your <code class="expression">space.vars.product\_name</code> setup

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl network list
```

{% endtab %}
{% endtabs %}

## Troubleshooting

If you encounter issues:

* Ensure your configuration file is sourced correctly
* If you receive endpoint or SSLErrors, it is likely due to using a self-signed certificate. The `--insecure` flag can be used as a workaround
* Verify network connectivity to your <code class="expression">space.vars.product\_name</code> environment
* Check that you have the necessary permissions for the operation
* Review logs for detailed error information

#### Support bundle

The `pcdctl generate-support-bundle` utility generates an encrypted archive file containing logs and configuration files specific to PCD troubleshooting scenarios. This command must be **executed from the host** where the support bundle is required, as the collected data pertains exclusively to that host.

Options specific to the `generate-support-bundle` command are:

{% tabs %}
{% tab title="Bash" %}

```yaml
$ sudo pcdctl generate-support-bundle --help
Gathers support bundle that includes logs for pf9 services and pf9ctl.

Usage:
  pcdctl generate-support-bundle [flags]

Flags:
  -h, --help   help for generate-support-bundle

Global Flags:
      --log-dir string   path to save logs
      --no-prompt        disable all user prompts
      --verbose          print verbose logs
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Info**

It is recommended to run the command with `--verbose` option to monitor the progress of support bundle generation.
{% endhint %}

The command to generate the support bundle is:

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --verbose
```

{% endtab %}
{% endtabs %}

A sample execution of the support bundle generation:

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --verbose

DEBUG ==========Genetating SupportBundle==========
DEBUG Using local executor
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "LD_LIBRARY_PATH="/opt/pf9/python/pf9-lib:${LD_LIBRARY_PATH}""
DEBUG stdout:stderr:
DEBUG Ran command sudo "bash" "-c" "PYTHONPATH="/opt/pf9/python/lib/python3.9:${PYTHONPATH}""
DEBUG stdout:stderr:
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "/opt/pf9/hostagent/bin/python /opt/pf9/hostagent/lib/python3.9/site-packages/datagatherer/datagatherer.py"
DEBUG stdout:stderr:
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "ls /tmp | grep -i pf9-support.tgz.*"
DEBUG stdout:pf9-support.tgz.[hash].gpg
stderr:
✓ Support bundle generated successfully. 
✓ Location of bundle: /tmp/pf9-support.tgz.*.gpg
```

{% endtab %}
{% endtabs %}

The archived contents are stored in an encrypted format within the *`/tmp/pf9-support.tgz.*.gpg`* file by default. For comprehensive guidance on sharing the support bundle, please reach out to the Platform9 support team.

To specify a custom path for the archived support bundle, use the `--log-dir` option.

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --log-dir <PATH_TO_FOLDER> --verbose
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/reference/pcdctl-command-line.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.