Skip to main content

​
Introduction

SetupOS is an operating system designed specifically for installing both HostOS and GuestOS onto new Internet Computer nodes. It enables Node Providers to independently onboard their nodes without external assistance.
SetupOS runs from a bootable USB drive and performs hardware validation, system preparation, and installation of both operating systems.

​
Purpose

SetupOS serves as the bootstrapping mechanism for IC nodes:

Hardware Validation

Verifies system hardware meets IC requirements

Network Verification

Tests connectivity and NNS reachability

Disk Preparation

Prepares storage with proper partitioning

OS Installation

Installs HostOS and GuestOS to disk

​
Installation Process

Node Providers follow these steps to onboard a new node:
1

Obtain SetupOS Image

Download the SetupOS image from the official source
2

Prepare USB Drive

Write the SetupOS image to a bootable USB drive:
dd if=setupos.img of=/dev/sdX bs=4M status=progress
sync
3

Add Configuration

Mount the USB drive and add necessary configuration files:
  • config.ini: Network and node settings
  • node_operator_private_key.pem: Node operator credentials
  • Other bootstrap configuration
4

Boot from USB

Plug the USB drive into the node machine and configure BIOS/UEFI to boot from USB
5

Automatic Installation

SetupOS boots and automatically:
  • Validates hardware
  • Checks network connectivity
  • Prepares disk storage
  • Installs HostOS
  • Installs GuestOS
  • Configures the system
6

Reboot to HostOS

Once complete, the machine automatically reboots into HostOS, which then launches GuestOS
The installation process will erase all data on the target disk. Ensure you have backed up any important data before starting.

​
Hardware Requirements

For detailed hardware and networking requirements, visit the Node Provider Onboarding Wiki.

​
Minimum Requirements

  • CPU: x86-64 with virtualization support (Intel VT-x or AMD-V)
  • Memory: Sufficient RAM for both HostOS and GuestOS
  • Storage: SSD with adequate space for dual-boot partitions
  • Network: IPv6 connectivity to the Internet Computer network

​
Under the Hood

SetupOS uses a systemd-based installation process:

​
Installation Service

The installation is initiated by the systemd service unit file setupos.service:
  • Service Type: idle (starts after all other units)
  • Purpose: Ensures system is fully ready before installation
  • Location: Systemd unit file

​
Installation Scripts

The installation process consists of multiple Shell and Python scripts located in /opt/ic/bin:
1

check-hardware.sh

Hardware VerificationValidates system hardware components:
  • CPU features and capabilities
  • Memory capacity
  • Storage devices
  • Network interfaces
  • Virtualization support
Fails installation if hardware does not meet requirements.
2

check-network.sh

Network ConnectivityTests network connectivity:
  • IPv6 configuration
  • Internet connectivity
  • NNS (Network Nervous System) reachability
  • DNS resolution
Ensures the node can communicate with the IC network.
3

setup-disk.sh

Disk PreparationPrepares the storage device:
  • Purges existing LVM configurations
  • Removes existing partitions
  • Creates new partition table
  • Sets up partition structure
This step destroys all existing data on the disk.
4

install-hostos.sh

HostOS InstallationInstalls and configures HostOS:
  • Writes HostOS image to appropriate partitions
  • Configures bootloader
  • Sets up initial HostOS configuration
  • Prepares for GuestOS VM management
5

install-guestos.sh

GuestOS InstallationInstalls and configures GuestOS:
  • Writes GuestOS image to appropriate partitions
  • Configures VM settings
  • Sets up initial GuestOS configuration
  • Prepares IC runtime environment
6

setup-hostos-config.sh

Configuration FinalizationSets up the HostOS config partition:
  • Writes configuration files
  • Sets up encryption keys
  • Configures networking
  • Prepares bootstrap data

​
Script Execution Flow

The main installation script setupos.sh orchestrates the execution of all scripts in the correct order, with error handling and logging at each step.

​
Node Provider Roles

Understanding the different roles in node management:
Entity that owns the hardware
  • Purchases and owns the physical node hardware
  • Receives rewards for the node’s useful work
  • Responsible for overall node operation
  • Registers with the Network Nervous System (NNS)

​
Node Onboarding Flow

The complete process for onboarding nodes:
1

Create Node Operator Key

Node Provider generates a private/public key pair:
# Generate key pair
openssl genpkey -algorithm ED25519 -out node_operator_private_key.pem
openssl pkey -in node_operator_private_key.pem -pubout -out node_operator_public_key.pem
2

Create Node Operator Record

Node Provider creates a Node Operator record in the NNS containing:
  • Node Operator public key
  • Node Provider identity
  • Node allowance
  • Other metadata
See node_operator.proto for details.
3

Share Private Key

Node Provider shares the Node Operator private key with their Node Technician, enabling the technician to onboard nodes on behalf of the Node Provider.
4

NNS Verification

Before approving onboarding, the NNS verifies:
  • Node Operator record exists and is valid
  • Node Provider is authorized to onboard nodes
  • Node Provider has not exceeded their node allotment
  • Cryptographic signature is valid
5

Node Registration

Upon successful verification, the node is registered in the IC registry and can join the network.

​
Configuration Files

SetupOS requires specific configuration files on the USB drive:

​
config.ini

Main configuration file containing: 
[network]
ipv6_prefix = 2001:db8::/64
ipv6_gateway = 2001:db8::1

[node]
hostname = node-1234
domain = example.com

[nns]
registry_url = https://nns.ic0.app

​
Node Operator Private Key

The private key file (node_operator_private_key.pem) used for:
  • Authenticating with the NNS
  • Signing node registration requests
  • Proving authorization to onboard nodes
Keep the Node Operator private key secure. Anyone with access to this key can onboard nodes under your Node Provider identity.

​
Bootstrap Package

Optional ic-bootstrap.tar containing:
  • Initial IC configuration
  • SSH authorized keys
  • Network settings
  • Custom configuration

​
Troubleshooting

​
Installation Failures

Common causes:
  • CPU lacks virtualization support
  • Insufficient memory
  • Storage device too small
  • Missing network interfaces
Solution: Verify hardware meets minimum requirements
Common causes:
  • No IPv6 connectivity
  • Firewall blocking NNS access
  • DNS resolution issues
  • Network misconfiguration
Solution: Verify network configuration and connectivity
Common causes:
  • Slow storage device
  • Hardware issues
  • Corrupted image
Solution: Check console output for errors, verify USB drive integrity
Common causes:
  • Incorrect Node Operator private key
  • Node allowance exceeded
  • Invalid configuration
  • Network issues
Solution: Verify Node Operator credentials and NNS reachability

​
Viewing Installation Logs

SetupOS logs are available through systemd: 
# View installation service logs
journalctl -u setupos.service

# View all logs
journalctl -b

# Follow logs in real-time
journalctl -u setupos.service -f

​
Manual Intervention

If automatic installation fails, you can access the SetupOS system:
For development images, the root account is enabled with username and password both set to root.
# Access console
# Login as root

# Check script status
cd /opt/ic/bin
ls -la

# Run scripts manually
./check-hardware.sh
./check-network.sh

​
Building SetupOS

To build a SetupOS image, refer to the Building IC-OS guide.
SetupOS has both prod and dev build targets. Use dev for testing and debugging, prod for actual node deployments.

​
Next Steps

Build SetupOS

Learn how to build SetupOS images

HostOS

Understand what happens after installation

Node Provider Onboarding

Complete onboarding documentation

IC-OS Overview

Return to IC-OS overview

Build docs developers (and LLMs) love

Get started for freeTalk to us