Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Platform9 OS

Overview

Platform9 OS is a purpose-built host operating system, powered by Rocky Linux from CIQ Pro 10.2 (RLC-Pro), delivered as a single self-contained ISO. One ISO installs the operating system and every Private Cloud Director host dependency, and then lets you connect the host to your management plane. No separate operating system installation or manual agent setup is required.

For CVE information relevant to the underlying operating system, see CIQ's public CVE disclosure page.

Installing the operating system needs no network connectivity, because the PCD payload is carried on the ISO itself. Network connectivity is required only when you connect the host to your management plane, which is a separate step after installation.

You can connect an installed host to the management plane in either of two ways, and both are interchangeable: the Host Boot Console, a text interface on the host itself, or the Host Management Console, a web console. This guide covers both.

The latest Platform9 OS ISO is available at this link.

In this guide, you will boot the Platform9 OS ISO, install the operating system with the on-screen wizard, connect the host to your PCD management plane, and authorize it for use.

To install Platform9 OS across many hosts, see Network Boot (PXE) for booting the same ISO over the network.

Prerequisites

  • Target disk: at least 100 GB. The installer does not list disks smaller than 100 GB. A disk of 250 GB or larger is recommended.

  • Network reachability for onboarding: the host must be able to reach your PCD management plane over the network in order to connect to it. This is not required to install the operating system.

  • Account details for onboarding. Collect these in the PCD UI under Infrastructure > Cluster Hosts > Add New Hosts:

    • Account URL: your region URL, for example https://<your-org>.app.platform9.io

    • Username and Password

    • Region

    • Tenant

All prerequisites noted on the hypervisor configuration prerequisites page continue to apply to this installation mode.

Install Platform9 OS From the ISO

Boot the Installer

Attach the Platform9 OS ISO as virtual media or a bootable USB device and boot the host. The Platform9 OS Installer launches automatically, and its header shows the build number of the ISO you booted (for example, Build <version>).

The installer is a guided text wizard with five steps, shown as a breadcrumb across the top:

Navigate using the keys shown in the footer of each step: Up/Down to move within a list, Tab to move between fields, Enter to confirm, Esc to go back, and Ctrl+C to exit and reboot.

Step 1: Select the Keyboard Layout

Select the keyboard layout for the server. English (US) is preselected. The layout applies immediately and is used by the installed system. Press Enter to continue.

Step 2: Set the Root Password

Set and confirm the password for the root account on the installed system. It is stored in the install configuration as a hashed value.

The following requirements are enforced and shown on screen:

  • At least 8 characters

  • Upper and lower case

  • At least one number

  • At least one symbol

A strength meter and a Passwords match confirmation update as you type. Press Tab to move to the confirmation field, then Enter to continue.

Step 3: Choose the Target Disk

Choose the disk to install onto. The selected disk is erased.

Two constraints apply on this step:

  • Only disks of 100 GB or larger are listed. The installer media and any disk under 100 GB are not shown, and other disks are left untouched.

  • A [!] marker flags any disk below the recommended 250 GB size.

Select the disk and press Enter. A Confirm Disk Erase dialog appears, naming the disk and warning that the operation permanently erases all data on it. Press Enter to confirm.

If the host boots from SAN, the installer enumerates, partitions, installs to, and boots from the remote LUN with no special handling required. The resulting LVM layout (GPT, a pcd volume group, and a grow-to-fill root volume) is identical to a local-disk install; only the storage location differs.

Step 4: Set the Hostname

Give the host a name that identifies it in the management plane and on the network. The default is pcd-host-01. Press Enter to continue.

Step 5: Review the Summary and Install

Confirm the summary: keyboard layout, root password, target disk to be erased, and hostname. The screen notes that no network is required, because the installer partitions the disk and installs both the operating system and Private Cloud Director from the ISO.

Press Enter to begin the install.

Automated Installation and First Boot

The installer runs unattended from this point:

  1. It partitions the target disk, using GPT with an LVM volume group named pcd and a grow-to-fill root volume, then installs the operating system and the PCD payload from the ISO. This takes a few minutes.

  2. The host reboots into the Host Boot Console.

  3. On first boot, the host automatically applies CIS Level 1 hardening.

As part of CIS hardening, direct root SSH access is disabled after the first boot. Administer the host from the boot console shell (F12) or from the Host Management Console, neither of which is affected.

The Host Boot Console

After installation, the host displays the Private Cloud Director Host Boot Console, which summarizes the host and its connection state:

  • CPU and Memory

  • Host Name

  • Network: the primary interface and its IP address, for example ens3 · 172.16.122.85/24

  • PCD Connectivity: initially an amber Not connected

The console also shows the two ways to connect and the web console URL, which is https://<host-ip>:9090.

Two footer actions are available:

  • F2: Customize System, which opens the System Customization menu.

  • F12: Exit to Shell, which prompts for the root password.

System Customization Menu (F2)

Pressing F2 prompts for the root password before it opens the menu. After you authenticate, the System Customization menu offers three options:

  • Configure Management Network: configure NICs, IPv4 and IPv6 addressing, VLAN tagging, and DNS for the host.

  • Connect to PCD Management Plane: onboard the host, as described in the next section.

  • View PF9 Service Status: view and restart the PCD host services.

Configure Management Network can tag a VLAN on top of a NIC you select, but it does not create bonded interfaces. If the management network ultimately needs to run on a bond, use this flow to reach the Host Management Console first, then create the bond from its Networking page (see Host Management Console).

Connect the Host to the Management Plane

Connect the host in either of two ways: from the Host Boot Console or from the Host Management Console. Both perform the same onboarding, so a host connected either way is configured identically. Use whichever fits your workflow.

Before you connect, make sure the host can reach the management plane. If it cannot (because there is no route, the host is on the wrong VLAN, or the environment requires a proxy), configure networking first, either from the boot console under F2 > Configure Management Network or from the Host Management Console's Networking page.

Have the values from Prerequisites ready: Account URL, Username, Password, Region, Tenant, and an optional Proxy URL.

Option 1: Host Boot Console

  1. At the boot console, press F2 and enter the root password.

  2. Select Connect to PCD Management Plane.

  3. Complete the form:

    • Account URL: your region URL, for example https://<your-org>.app.platform9.io

    • Username

    • Password: press F3 to show or hide the value

    • Region

    • Tenant

    • Proxy URL: optional, and only required if the host reaches the management plane through a proxy. To configure a proxy separately, use Configure Network > Proxy Configuration.

  4. Press Enter to connect. The host authenticates and onboards, and the screen shows a Connecting message while it installs and starts the host agents. This takes a few minutes.

  5. On success, the console returns to the dashboard and PCD Connectivity turns green and reads Connected.

Option 2: Host Management Console

  1. In a browser, go to https://<host-ip>:9090 (the URL shown on the boot console) and log in as root. The Host Management Console opens with a left navigation containing PCD Connection, Host Readiness, Storage, Networking, PCD Logs, OS Hardening, and Terminal. PCD Connection is the default page.

  2. On the PCD Connection page, complete the form (Account URL, Username, Password, Region, Tenant, and optional Proxy URL), then click Connect. Every field except the proxy is required.

  3. A live log streams while the host authenticates and onboards, reporting each stage as it completes: setting the configuration, running pcdctl prep-node, loading the configuration, and running prerequisite checks while installing any missing operating system packages.

  4. On success, the page switches to a Connected to PCD Management Plane view. This view shows the connection details (Account URL, Username, Region, Tenant, Web Portal, and Outbound Proxy), along with a PCD Services list containing Network, Hostagent (pf9-hostagent), Comms (pf9-comms), and Sidekick (pf9-sidekick). Each service reports active and offers Restart and View logs actions.

The Connected to PCD Management Plane view also exposes a Passwordless Root Access toggle for Advanced Remote Support. It is disabled by default.

For details on the other Host Management Console pages (Host Readiness, Storage, Networking, PCD Logs, OS Hardening, and Terminal), see Host Management Console.

Authorize and Verify the Host

After the host connects, it registers with the management plane and appears in the PCD UI under Infrastructure > Cluster Hosts.

A newly connected host is registered but unauthorized, because it has no roles yet. Until you authorize it, the host is registered but shows as not responding. Authorize the host and assign its roles in the PCD UI. See Authorize Host And Assign Roles for the full procedure.

Once the host is authorized and its agent is communicating, you can confirm that it is connected from any of three places:

  1. PCD UI: the host shows Connected under Infrastructure > Cluster Hosts.

  2. Host Management Console: the PCD Connection page at https://<host-ip>:9090 shows Connected to PCD Management Plane, with all services active.

  3. Host Boot Console: PCD Connectivity shows green and reads Connected.

The boot console reads its PCD Connectivity status when the home screen is drawn. If you onboarded the host from the Host Management Console, the console can still show Not connected until the screen is redrawn. Press F2 and then Esc to return to the home screen and refresh the status.

At this point the host is a fully onboarded PCD host.

Caveats and Troubleshooting

Topic
Detail

Network for install compared with onboarding

Installing the operating system needs no network, because the operating system and the PCD payload are both on the ISO. Connecting to the management plane does require network reachability.

Disk requirements

Only disks of 100 GB or larger are selectable, and 250 GB or larger is recommended. Disks below the recommended size are flagged with [!].

UEFI

Boot the installer in UEFI mode.

CIS hardening and root SSH

The first boot applies CIS Level 1 hardening, after which direct root SSH is disabled. Use the boot console shell (F12) or the Host Management Console's terminal instead. See Platform9 OS CIS Hardening for the full compliance report and export options.

A FATAL configuration line appears while connecting

On the Host Boot Console path only, a line such as FATAL Could not load config: … config.json: no such file can appear at the very start of onboarding. This is benign (it is the initial configuration probe running before the configuration is written), and onboarding continues normally. The Host Management Console does not surface this line.

The host registers but stays "not responding"

A connected host that has not yet been authorized, and so has no role assigned, registers but shows as not responding until you authorize it in the PCD UI.

Onboarding takes several minutes

Connecting installs and starts the host agents and pulls host packages, so it legitimately takes a few minutes before the host shows as connected.

The boot console still shows "Not connected"

The console refreshes its connectivity status when the home screen is drawn. Press F2 and then Esc to redraw it.

Limitations

  • vTPM 1.2 is not supported for guest VMs. Platform9 OS installs and runs without a TPM chip; no TPM is required to install or boot the host itself. However, once installed, the host's libvirt/swtpm stack only exposes a TPM 2.0 backend to guest VMs (visible via domcapabilities). Guest VMs that request vTPM version 1.2 fail to schedule on the host with a NoValidHost error. Configure guest VMs that require a vTPM to request version 2.0.

  • Shared swtpm storage is required for multi-host vTPM. For vTPM to work correctly across a multi-host cluster, /var/lib/libvirt/swtpm must be shared over NFS across all compute hosts in the cluster, mounted with vers=3,local_lock=all, and the swtpm UID must match across hosts. Note that libvirt itself is not part of the installed Platform9 OS image; it is installed later, when the host is assigned a hypervisor role through the Management Plane.

  • Live migration across operating systems is not supported. Live migration and VM evacuation of a VM from an Ubuntu host to a Platform9 OS host are not supported and fail to complete. Cold migration is the supported cross-OS path. For details, see Live Migration Across Operating System Families.

Related Pages

PreviousTeleport Installation
NextHost Management Console

Last updated

Was this helpful?