# CubeCOS Installation > Learn how to install CubeCOS for both small-scale and large-scale cluster deployments, from single-node setups to enterprise-grade infrastructure. CubeCOS installation consists of the following process. 1. **Image restore (Installation)**: Restoring (installing) CubeCOS onto the target device of the endpoint. 2. **Role configuration**: Configure nodes with roles for your cluster setup, set network information, and high availablility if required. 3. **Cluster setup**: The cluster can be `set_ready` after installation and node role configuration, initializing the SDS and completing cluster service of setup for CubeCOS. ## Prerequisites for CubeCOS installation {#prerequisites-for-cubecos-installation} :::info Please verify both hardware and network requirements have been met before proceeding with the installation. ::: ### Downloading the installation files {#downloading-the-installation-files} Navigate to the [CubeCOS GitHub repository](https://github.com/bigstack-oss/cubecos/releases/latest) to download the installation files corresponding to your chosen installation method. CubeCOS supports and provides installation medias for following installation methods: - **Image via USB Flash Drive**: Boot and install directly from a USB device. - **ISO for Virtual Media or DVD**: Mount the ISO using virtual media or burn it to a physical DVD for installation. - **Network Boot via PXE Server (IMG/ISO)**: Deploy over the network using a PXE server with either image or ISO format. ## Begin the installation process {#begin-the-installation-process} Once you have prepared your chosen installation media and booted the target machine from it, proceed to start the installation process. ### Login and restore to setup CubeCOS {#login-and-restore-to-setup-cubecos} :::info Before starting the setup, verify the IP address and IP CIDR configuration. Ensure that: - The assigned IP address is within the correct subnet range. - The CIDR notation accurately reflects the intended network mask (e.g., /24 for 255.255.255.0). - There are no IP conflicts within the target network. ::: :::danger The restore operation **erases all data** on the selected disk. Backup any important data before proceeding. ::: 1. At the `uefi-installer` login prompt, enter the following credentials. 1. **Username**: `admin` 2. **Password**: `admin` 2. Run the following command to start the installation: 1. Select the target partition when prompted 2. Confirm by entering `YES` ```bash restore ``` :::info[Resolving the `No Images Found` error] If the installer returns a `hex_install: Error: No images found` error, resolve the issue following [Resolve the `No images found` error](#resolve-no-images-found-error). ::: 3. After the installation completes, reboot the system with: 1. Confirm by entering `YES` ```bash reboot ``` ### Getting started from the CubeCOS console {#getting-started-from-the-cubecos-console} After completing the `restore` process and rebooting, you'll see the CubeCOS setup banner. Press `F2` to begin the setup process. ### Login to begin installation {#login-to-begin-installation} Use the default credentials to log in: - Username: `admin` - Password: `admin` ### Choose a setup option - Wizard {#choose-a-setup-option---wizard} Enter `1` to launch the interactive setup wizard. ```bash First Time Setup Options: 1: Wizard 2: Advanced Enter index: 1 ``` ### Read and accept the EULA {#read-and-accept-the-eula} Follow the prompts to read and accept the license terms. ```bash -- Welcome -- Welcome to the Cube Appliance setup wizard. Using this setup wizard, you can: * View and accept the Software License Agreement * Set the appliance password * View and configure networking Press Enter to continue. -- Software License Agreement -- Currently selected language: English 1: Select language for license display 2: Read Bigstack terms 3: Read non-Bigstack terms 4: Proceed to acceptance Select option: 4 By choosing 'I agree,' you agree that (1) you have had the opportunity to review the terms of licenses presented above and (2) such terms govern this transaction. If you do not agree, choose 'I do not agree'. 1: I agree 2: I do not agree Select option: 1 ``` ### Change the password {#change-the-password} By default, CubeCOS updates the password after `set_ready`. It uses the format `Cube@xxx.xxx`, where `xxx.xxx` are the last two octets of the cluster's VIP. :::note If the cluster VIP is `192.168.100.100`, the updated default password will be: `Cube@100.100`. ::: To change the password manually: ```bash -- Appliance Password -- Password changes are applied immediately. Password has not been modified. 1: Change password x: Exit p: Previous screen n: Next screen Select option: 1 - Change Password - Enter old password: admin Enter new password: Confirm new password: Password successfully changed. ``` ### Configure hostname {#configure-hostname} :::warning A valid hostname must be in lowercase and cannot contain special characters (!@#$%^&\*()), underscores (\_), or spaces. ::: A valid hostname must: - Contain only lowercase letters (a-z), numbers (0-9), and hyphens (-) - Be 64 characters or less in length - Be unique within the network - Must start with a letter - Not be entirely numeric ```bash -- Host Name Configuration -- Host name: unconfigured 1: Change the host name x: Exit p: Previous screen n: Next screen Select option: 1 - Change the Host Name - Enter the new host name: control-converged -- Host Name Configuration -- Host name: control-converged 1: Change the host name x: Exit p: Previous screen n: Next screen Select option: n ``` ### [Optional] Configure network bonding {#optional-configure-network-bonding} Network bonding is optional and only required for deployments that require network redundancy. To better understand network configuration options and deployment scenarios, refer to the [network configuration](../category/network) section. Skip to [Configure an IP address for a specific interface](#configure-ip-address-for-a-specific-interface) if bonding and VLAN are not required. :::info If a network cable is connected, the `[Speed]` column will display the link status (e.g., 1000Mb/s, 10Gb/s). If no cable is detected, it will show `N/A`. ::: :::warning Do not use system reserved names such as `bond0`, `bond1`, `bondx`, or `bd0` as bonding interface names. ::: ```bash -- Network Bonding Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display policy 2: Configure network bonding x: Exit p: Previous screen n: Next screen Select option: n ``` ### [Optional] Configure VLAN {#optional-configure-vlan} Skip if VLAN tagging is not required. ```bash -- VLAN Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display policy 2: Configure vlan network x: Exit p: Previous screen n: Next screen Select option: n ``` ### Configure an IP address for a specific interface {#configure-ip-address-for-a-specific-interface} Assign a static IPv4 address, subnet mask, and default gateway to the primary interface. This guide assumes a single network interface labelled `IF.1`. Before proceeding, make sure you have the following information: - The static IP address for the CubeCOS management VIP - The subnet mask of the management network - The default gateway for the subnet - The IP addresses of DNS servers to be used ```bash -- Networking Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display device status 2: Display policy 3: Configure IF.1 x: Exit p: Previous screen n: Next screen Select option: 3 - Configure IF.1 - Enter the IPv4 address: Enter the IPv4 subnet mask: Enter the IPv4 default gateway: -- Networking Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display device status 2: Display policy 3: Configure IF.1 x: Exit p: Previous screen n: Next screen Select option: n ``` ### Configure DNS servers {#configure-dns-servers} Enter the DNS servers that CubeCOS should use, this can be internal or external DNS resolves. Set up to three DNS servers to use. The following example has been provided for setting an external DNS server at `1.1.1.1`. ```bash -- DNS Configuration -- No DNS servers configured. 1: Set DNS server 1 2: Set DNS server 2 3: Set DNS server 3 x: Exit p: Previous screen n: Next screen Select option: 1 - Set DNS Server 1 - Enter the DNS server IP address: 1.1.1.1 ``` ### Configure time zone {#configure-time-zone} :::info Set the same timezone on all nodes in the cluster. Consistent timekeeping is critical for coordinating services, ensuring accurate log timestamps, and avoiding synchronization issues. ::: To configure the time zone, select option `1`. ```bash -- Time Configuration -- Time configuration changes are applied immediately. Time Zone: America/New_York Date: 05/29/2025 Time: 14:00:37 1: Change the time zone 2: Change the date 3: Change the time x: Exit p: Previous screen n: Next screen Select option: 1 ``` ### Configure CubeCOS node role {#configure-cubecos-node-role} To learn about CubeCOS architecture and node roles, refer to the [Architecture section](../getting-started/architecture) or the [Roles section](../getting-started/roles). ```bash -- Cube Role -- Current role: undef Current Management: IF.1 Current Domain/Region: default/RegionOne Current Cube Secret Seed: N/A 1: Change role x: Exit p: Previous screen n: Next screen Select option: 1 ``` When prompted, enter the following values: :::warning The cluster secret seed serves as an input variable for cryptographic value generation. Set a unique and strong value to ensure secure cluster communications and cryptographic operations. ::: ```bash - Change Role - Select a role: 1: control 2: compute 3: storage 4: control-converged 5: edge-core 6: moderator Enter index: 4 # Select the desired role, control-converged is selected for example Specify external IP/domain [optional]: # Leave blank Specify management interface: IF.1 # Interface for control/API traffic Specify provider interface: IF.1 # Interface for VM data and external traffic Specify overlay interface: IF.1 # Interface used for internal SDN tunnel traffic Specify storage interface [frontend(,backend)]: IF.1 # Interface for Ceph traffic Specify region ("RegionOne"): # Keep default or customize as needed Specify cluster secret seed: # Unique secret shared among nodes in the same cluster Specify management CIDR ("10.254.0.0/16"): # (Optional) Change only if there is a subnet conflict, must be /16 subnet ``` ### Configure High Availability {#configure-high-availability} :::note High availability (HA) is not supported for single-node deployments ::: For single node deployment without HA, press `n` to skip the configuration. Enable high availability on a three node cluster to provide fault tolerance features. Select `Change HA` by selecting option `1`. Then answer `Yes` to enabling high availability Cube. ```bash -- Cube High Availability -- Current HA setting: disabled 1: Change HA x: Exit p: Previous screen n: Next screen Select option: 1 - Change HA - High Available Cube: 1: Yes 2: No Enter index: 1 ``` Select option `n` to proceed. ```bash Specify control virtual Hostname: Specify control virtual IP: Specify control group hostname [HOST,HOST,...]: ,, Specify control group address [IP,IP,...]: , , -- Cube High Availability -- Current HA setting: enabled Current Control Virtual Hostname: ccvip # sample output Current Control Virtual IP: 10.32.2.230 # Sample output Current Control Group: cc1(10.32.2.231),cc2(10.32.2.232),cc3(10.32.2.233) # example output 1: Change HA x: Exit p: Previous screen n: Next screen Select option: n ``` ### Beginning policy application and cluster initialization {#beginning-policy-application-and-cluster-initialization} In any CubeCOS cluster deployment, the first control host initialized becomes the master node. This node is responsible for establishing core service initialization and applying the base configuration for the cluster. :::danger[Apply and confirm master node policy application] Do not proceed with additional control nodes until the first control node has completed applying the policy. Starting other nodes before the master node finishes may result in: - Service registration failures - Configuration drift - Cluster instability or inconsistent state ::: After the master node completes its setup and displays a successful policy application message (Policy changes were successfully applied), you can safely accept the configuration on the remaining two control nodes. The following is an example of a complete configuration used during deployment. ```bash Summary Password has not been modified. Host name: control-converged IF.1 Default interface. IPv4 Mode: Manual IPv4 Address: 10.32.2.231 IPv4 Netmask: 255.255.0.0 IPv4 Gateway: 10.32.0.254 IPv6 Mode: Automatic DNS server 1: 1.1.1.1 Time Zone: Asia/Taipei Date: 05/29/2025 Time: 14:54:19 Role: control-converged External IP/Domain: N/A Management: IF.1 Provider: IF.1 Overlay: IF.1 Storage: IF.1 Domain/Region: default/RegionOne Cube Secret Seed: bigstack Management CIDR: 10.254.0.0/16 High Availability: enabled Control Virtual Hostname: ccvip Control Virtual IP: 10.32.2.230 Control Group: cc1(10.32.2.231),cc2(10.32.2.232),cc3(10.32.2.233) High Availability: disabled 1: Accept the configuration 2: Cancel the configuration 3: Modify the configuration Select option: 1 ``` The time required to apply the configuration may vary depending on system hardware performance. Monitor the console output. When the process completes successfully, you’ll see a confirmation message. :::tip[Verify success in the console] Policy changes were successfully applied. ::: ### Exit and re-login to apply policy changes {#exit-and-re-login-to-apply-policy-changes} After the policy has been successfully applied, log out and log back into the console to ensure the changes take effect and are reflected in the interface. ## Troubleshooting {#troubleshooting} ### Resolve erroneous configuration. {#resolve-erroneous-configuration} If there are errors in the configuration, the installation process will fail and display an error message. :::caution[Reboot required] Allow the node to reboot before retrying. After rebooting, carefully review your configuration settings and make any necessary corrections before attempting the installation again. ::: ```bash Policy changes could not be applied. System must be rebooted. Press enter to continue: ``` ### Resolve the `No images found` error {#resolve-no-images-found-error} If the `restore` command returns the following error, the installer cannot locate the installation media: ```bash uefi-installer> restore hex_install: Error: No images found Unexpected error uefi-installer> ``` To resolve this, manually mount the installation media by completing the following steps. #### Exit the installer CLI and open a root shell {#exit-installer-open-root-shell} Exit the installer CLI and log in as `root`: ```bash uefi-installer> exit ``` At the login prompt, enter the following credentials: - **Username:** `root` - **Password:** `admin` ```bash uefi-installer login: root Password: Last login: Mon Jul 11 06:49:03 on ttyS0 Welcome to the Cube Appliance Installer # ``` #### Verify block devices with lsblk {#verify-block-devices-lsblk} Run `lsblk` to identify block devices and verify whether the installation media is mounted: ```bash # lsblk ``` If the installation USB drive (for example, `sdd1`) has no listed mount point, proceed to the next step. #### Mount the installation media manually {#mount-installation-media-manually} 1. Mount the installation partition to `/mnt/install`. ```bash mount /dev/sdd1 /mnt/install ``` 2. Verify the mount results. ```bash # lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT sda 8:0 0 744.6G 0 disk ├─sda1 8:1 0 1000M 0 part ├─sda2 8:2 0 2G 0 part ├─sda5 8:5 0 357.4G 0 part ├─sda6 8:6 0 357.4G 0 part └─sda7 8:7 0 26.9G 0 part sdb 8:16 0 5.1T 0 disk ├─sdb1 8:17 0 400M 0 part ├─sdb2 8:18 0 400M 0 part ├─sdb3 8:19 0 2.6T 0 part └─sdb4 8:20 0 2.6T 0 part sdc 8:32 0 5.1T 0 disk ├─sdc1 8:33 0 400M 0 part ├─sdc2 8:34 0 400M 0 part ├─sdc3 8:35 0 2.6T 0 part └─sdc4 8:36 0 2.6T 0 part sdd 8:48 1 28.7G 0 disk └─sdd1 8:49 1 5.7G 0 part /mnt/install sr0 11:0 1 1024M 0 rom sr1 11:1 1 1024M 0 rom ``` Confirm that `sdd1` now shows `/mnt/install` as its mount point. #### Return to the installer CLI and resume installation {#return-installer-cli-resume-installation} Switch back to the `admin` user to resume the installation: ```bash # su admin Welcome to the Cube Appliance Installer Welcome to the Cube Appliance Enter "help" for a list of available commands uefi-installer> ``` Return to [Begin the installation process](#begin-the-installation-process) and continue.