Skip to main content
Version: 3.0

CubeCOS Installation

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​

info

Please verify both hardware and network requirements have been met before proceeding with the installation.

Downloading the installation files​

Navigate to the CubeCOS GitHub repository 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​

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​

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

      restore
    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.

  3. After the installation completes, reboot the system with:

    1. Confirm by entering YES

      reboot
single-node-functions

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.

cubecos_3_0_console-image

Login to begin installation​

Use the default credentials to log in:

  • Username: admin
  • Password: admin

Choose a setup option - Wizard​

Enter 1 to launch the interactive setup wizard.

    First Time Setup Options:
    1: Wizard
    2: Advanced
    Enter index: 1

Read and accept the EULA​

Follow the prompts to read and accept the license terms.

    -- 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​

By default, CubeCOS updates the password after set_ready. It uses the format [email protected], 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: [email protected].

To change the password manually:

    -- 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​

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
    -- 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​

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 section.

Skip to Configure an 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.

    -- 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​

Skip if VLAN tagging is not required.

    -- 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​

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
    -- 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: <your-cluster-ip-address>
    Enter the IPv4 subnet mask: <your-subnet-mask>
    Enter the IPv4 default gateway: <your-gateway-address>

    -- 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​

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.

    -- 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​

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.

    -- 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​

To learn about CubeCOS architecture and node roles, refer to the Architecture section or the Roles section.

    -- 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.

    - 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: <replace-with-your-secret> # 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​

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.

    -- 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.

        Specify control virtual Hostname: <cluster-virtual-hostname>
        Specify control virtual IP: <cluster-virtual-ip>
        Specify control group hostname [HOST,HOST,...]: <control-node-hostname-1>,<control-node-hostname-2>,<control-node-hostname-3>
        Specify control group address [IP,IP,...]: <control-node-ip-1>, <control-node-ip-2>, <control-node-ip-3>

        -- 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​

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.

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.

    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.

Verify success in the console

Policy changes were successfully applied.

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​

Resolve erroneous configuration.​

If there are errors in the configuration, the installation process will fail and display an error message.

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.

    Policy changes could not be applied. System must be rebooted.
    Press enter to continue:

Resolve the No images found error​

If the restore command returns the following error, the installer cannot locate the installation media:

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 the installer CLI and log in as root:

uefi-installer> exit

At the login prompt, enter the following credentials:

  • Username: root
  • Password: admin
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​

Run lsblk to identify block devices and verify whether the installation media is mounted:

# lsblk
lsblk-command

If the installation USB drive (for example, sdd1) has no listed mount point, proceed to the next step.

Mount the installation media manually​

  1. Mount the installation partition to /mnt/install.

    mount /dev/sdd1 /mnt/install

  2. Verify the mount results.

    # 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​

Switch back to the admin user to resume the installation:

# 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 and continue.

Last updated on by Brian Su