Difference between revisions of "Node Deployment Guide (with an HSM)"

From Internet Computer Wiki
Jump to: navigation, search
m
m
 
(60 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
This runbook covers all steps necessary to install the Internet Computer Operating System (IC-OS) on [[Node Provider Machine Hardware Guide#Gen 2 Node Machine requirements|Gen-2 hardware]] using the legacy NitroKey HSM instructions. To use the current instructions, follow the [[IC OS Installation Runbook]].
+
This runbook covers all steps necessary to install the Internet Computer Operating System (IC-OS) using the legacy NitroKey HSM instructions. To use the non-HSM onboarding instructions, follow the [[IC-OS Installation Runbook]].
  
 
The physical machine is expected to be racked and stacked according to its respective manual.
 
The physical machine is expected to be racked and stacked according to its respective manual.
  
−
In case you encounter any issues during the installation process, check the [[Possible Node Onboarding Errors]] page. Otherwise, post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
+
To complete these steps, you are expected to be physically present in the data center your machine(s) reside(s). Once you successfully onboarded your first node, you can bring up the other nodes in parallel.
  
−
Many thanks for your efforts in building the Internet Computer.
+
If you encounter issues during any of these steps, consult the [[Troubleshooting Node Deployment Errors]] page.
  
−
== Requirements ==
+
⚠️ DFINITY does '''not''' offer live support for Node Providers attempting to deploy nodes.
−
* A USB (3.0 speed that can hold at least 4GB) to put the image file on (Faster USBs will allow the process to go much faster.)
 
−
* The NitroKey HSM for your data center.
 
−
* [Optional] A USB hub
 
−
** This is helpful at some data centers for simultaneously connecting keyboard, mouse, Nitrokey, etc..  
 
  
−
== 1. Download installation image ==
+
==1. Choose onboarding path (HSM vs no HSM)==
−
Download the latest release of the '''IC-OS USB Installer Image''' and the '''corresponding checksum''' from the [https://dashboard.internetcomputer.org/releases Internet Computer Dashboard Releases].
+
If you chose the [[Node Provider Onboarding#5. Choose onboarding path .28HSM vs no HSM.29|HSM Node Provider Onboarding Path]], '''continue to the next step.'''
  
−
== 2. Verify checksum and unarchive file ==
+
If you chose to onboard '''without''' a Nitrokey HSM, follow the [[IC-OS Installation Runbook]] to onboard your nodes.
−
=== Mac OS X ===
 
−
# Open the Terminal and type:
 
−
#: <syntaxhighlight lang="shell">shasum -a 256 ~/Downloads/disk-img.tar.gz</syntaxhighlight>
 
−
# Compare the calculated checksum with the file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
 
−
#: Open the Terminal and type: <syntaxhighlight lang="shell">tar xzvf ~/Downloads/disk-img.tar.gz</syntaxhighlight>
 
  
−
=== Linux / Ubuntu ===
+
==2. Obtain requirements==
−
# Open the Terminal and type:
+
*A USB (3.0 speed that can hold at least 4GB) to put the image file on.
−
#: <syntaxhighlight lang="shell">sha256sum ~/Downloads/disk-img.tar.gz</syntaxhighlight>
+
** Faster USBs will allow the process to go much faster.
−
# Compare the calculated checksum with the file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
+
*The NitroKey HSM for your data center.
−
#: Open the Terminal and type: <syntaxhighlight lang="shell">tar xzvf ~/Downloads/disk-img.tar.gz</syntaxhighlight>
+
*[Optional] A USB hub
 +
** This is helpful at some data centers for simultaneously connecting keyboard, mouse, Nitrokey, etc.
 +
*It is recommended that each server has a label with the BMC's MAC address for ease of identification in future dashboard upgrades.
  
−
=== Windows ===
+
==3. Download installation image==
−
# Open PowerShell and type:
+
Download the latest release of the '''IC-OS USB Installer Image''' and the '''corresponding checksum''' from the [https://dashboard.internetcomputer.org/releases Internet Computer Dashboard Releases].  
−
#: <syntaxhighlight lang="shell">Get-FileHash -Algorithm SHA256 .\Downloads\disk-img.tar.gz</syntaxhighlight>
+
*'''Note that you should always use a release from the last 6 weeks (newer is better) in order to ensure that your node can correctly correct to the network.'''
−
# Compare the calculated checksum with the file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
 
−
#: Open PowerShell and type: <syntaxhighlight lang="shell">tar xzvf .\Downloads\disk-img.tar.gz</syntaxhighlight>
 
  
−
== 3. Create Bootable USB Stick ==
+
==4. Verify checksum and unarchive file==
−
=== Mac OS X ===
+
===Mac OS X===
−
# Open the Terminal and type:  
+
#Open the Terminal and type:
−
#:<syntaxhighlight lang="shell">diskutil list</syntaxhighlight>  
+
#:<syntaxhighlight lang="shell">shasum -a 256 ~/Downloads/disk-img.tar.zst</syntaxhighlight>
−
# All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive:
+
#Compare the calculated checksum with the '''IC-OS installation image checksum''' file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [[Node Provider Matrix channel]].
 +
#:Open the Terminal and type: <syntaxhighlight lang="shell">tar xzvf ~/Downloads/disk-img.tar.zst</syntaxhighlight>
 +
 
 +
===Linux / Ubuntu===
 +
#Open the Terminal and type:
 +
#:<syntaxhighlight lang="shell">sha256sum ~/Downloads/disk-img.tar.zst</syntaxhighlight>
 +
#Compare the calculated checksum with the '''IC-OS installation image checksum''' file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [[Node Provider Matrix channel]].
 +
#:Open the Terminal and type: <syntaxhighlight lang="shell">tar xzvf ~/Downloads/disk-img.tar.zst</syntaxhighlight>
 +
 
 +
===Windows===
 +
#Open PowerShell and type:
 +
#:<syntaxhighlight lang="shell">Get-FileHash -Algorithm SHA256 .\Downloads\disk-img.tar.zst</syntaxhighlight>
 +
#Compare the calculated checksum with the '''IC-OS installation image checksum''' file downloaded in the previous step. '''Warning:''' Only continue if they are identical, otherwise please post your issue in the [[Node Provider Matrix channel]].
 +
#:Open PowerShell and type: <syntaxhighlight lang="shell">tar xzvf .\Downloads\disk-img.tar.zst</syntaxhighlight>
 +
 
 +
==5. Create Bootable USB Stick==
 +
===Mac OS X===
 +
#Open the Terminal and type:  
 +
#:<syntaxhighlight lang="shell">diskutil list</syntaxhighlight>
 +
#All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive:
 
#:<syntaxhighlight lang="shell">sudo diskutil unmount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/disk4s1</syntaxhighlight>
 
#:<syntaxhighlight lang="shell">sudo diskutil unmount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/disk4s1</syntaxhighlight>
−
# The file path is an example. Use the absolute path to the downloaded image. '''Warning:''' You risk losing your own data if you specify a wrong device.  
+
#Replace ''/dev/YOUR_USB_DEVICE'' with the device that corresponds to your USB stick. Additionally, replace the path to your downloaded IC-OS ''disk.img'' file. '''Warning:''' You risk losing your own data if you specify a wrong drive.
−
#:<syntaxhighlight lang="shell">sudo dd if=/Users/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M</syntaxhighlight>  
+
#:<syntaxhighlight lang="shell">sudo dd if=/Users/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M status=progress</syntaxhighlight>If you get a “device is busy” error from the dd command, you can try running the following command to unmount all of the partitions on the disk, then re-run the dd command:
 +
#:<syntaxhighlight lang="shell">sudo diskutil unmountDisk /dev/YOUR_USB_DEVICE # E.g. /dev/disk4</syntaxhighlight>
  
−
=== Linux / Ubuntu ===
+
===Linux / Ubuntu===
−
# Open the Terminal and type  
+
#Open the Terminal and type  
 
#:<syntaxhighlight lang="shell">blkid</syntaxhighlight>
 
#:<syntaxhighlight lang="shell">blkid</syntaxhighlight>
−
# All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive:
+
#All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive:
−
#:<syntaxhighlight lang="shell">sudo diskutil unmount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/sdb1</syntaxhighlight>
+
#:<syntaxhighlight lang="shell">sudo umount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/sdb1</syntaxhighlight>
−
# Replace ''/dev/YOUR_USB_DEVICE'' with the device that corresponds to your USB stick. '''Warning:''' You risk losing your own data if you specify a wrong drive.  
+
#Replace ''/dev/YOUR_USB_DEVICE'' with the device that corresponds to your USB stick. Additionally, replace the path to your downloaded IC-OS ''disk.img'' file. '''Warning:''' You risk losing your own data if you specify a wrong drive.
−
#:<syntaxhighlight lang="shell">sudo dd if=~/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M</syntaxhighlight>  
+
#:<syntaxhighlight lang="shell">sudo dd if=/home/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M status=progress</syntaxhighlight>
 +
 
 +
===Windows===
 +
#Download and install [https://rufus.ie/en/ Rufus Portable]
 +
#Start Rufus
 +
#Select the USB stick under device and select the previously downloaded IC-OS disk image and press start
 +
#:[[File:05.png|480px|screenshot]]
 +
#You may see some warnings. Make sure you don't have any other USBs in your computer and chose OK
 +
#:[[File:06.png|480px|screenshot]]
 +
#:[[File:07.png|480px|screenshot]]
 +
#The "Ready" bar will go from left to right as it completes.
 +
 
 +
==6. Add configuration ==
 +
 
 +
===A. Open Config.ini in a text editor===
 +
 
 +
===='''Mac OS X'''====
 +
 
 +
#Open Finder. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
 +
#:[[File:mac_01.png|580px|screenshot]]
 +
#Double-click <code>config.ini</code> to open it in TextEdit.
 +
 
 +
 
 +
===='''Linux'''====
  
−
=== Windows ===
+
#Open the File Manager. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
−
# Download and install [https://rufus.ie/en/ Rufus Portable]
+
#:[[File:linux_01.png|580px|screenshot]]
−
# Start Rufus
+
#Double-click <code>config.ini</code> to open it in KWrite.
−
# Select the USB stick under device and select the previously downloaded IC-OS disk image and press start
 
−
#: [[File:05.png|480px|screenshot]]
 
−
# You may see some warnings. Make sure you don't have any other USBs in your computer and chose OK
 
−
#: [[File:06.png|480px|screenshot]]
 
−
#: [[File:07.png|480px|screenshot]]
 
−
# The "Ready" bar will go from left to right as it completes.
 
  
−
== 4. Add configuration ==
 
−
=== Mac OS X ===
 
−
# Open Finder. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
 
−
#: [[File:mac_01.png|580px|screenshot]]
 
−
# Double-click to open it in TextEdit.
 
−
# Insert your IPv6 prefix, subnet and gateway.
 
−
#: [[File:mac_02.png|580px|screenshot]]
 
−
# Once done, don’t forget to save the changes. If you need help, please do not hesitate to post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
 
−
#:[[File:mac_03.png|580px|screenshot]]
 
  
−
=== Windows ===
+
===='''Windows'''====
−
# Open the Disk Management utility with a right click on the Start menu  
+
 
−
#: [[File:09-b.png|300px|screenshot]]#:
+
#Open the Disk Management utility with a right click on the Start menu.
−
# Right click the CONFIG partition  
+
#:[[File:09-b.png|300px|screenshot]]#:
−
# Select Change drive letter or paths...
+
#Right click the CONFIG partition.
−
#: [[File:10-b.png|780px|screenshot]]
+
#Select Change drive letter or paths...
−
# Select any letter from the drop-down list  
+
#:[[File:10-b.png|780px|screenshot]]
−
#: [[File:11-b.png|480px|screenshot]]
+
#Select any letter from the drop-down list.
 +
#:[[File:11-b.png|480px|screenshot]]
 
# Click OK.
 
# Click OK.
−
# You should now be able to see the CONFIG partition in your Windows Explorer. Select the config.ini configuration file  
+
# You should now be able to see the CONFIG partition in your Windows Explorer. Select the <code>config.ini</code> configuration file.
−
#: [[File:12-b.png|780px|screenshot]]
+
#:[[File:12-b.png|780px|screenshot]]
−
# Click on Edit to open it.
+
#Click on Edit to open it.
−
# Insert your IPv6 prefix, subnet and gateway.
 
−
#: [[File:13-b.png|580px|screenshot]]
 
−
# Once done, don’t forget to save the changes. If you need help, please do not hesitate to post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
 
−
#:[[File:14-b.png|580px|screenshot]]
 
−
# If onboarding without a NitroKey HSM, copy <code>node_operator_private_key.pem</code> (created in [[Node Provider Onboarding#7.%20Setup%20the%20Node%20Operator%20keys|Node Provider Onboarding step 7]]) to the <code>CONFIG</code> partition. This file should have the name <code>node_operator_private_key.pem</code>, and sit next to <code>config.ini</code>, NOT inside the <code>ssh_authorized_keys</code> folder.
 
  
−
=== Linux ===
+
===B. Edit Config.ini===
−
# Open the File Manager. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
 
−
#: [[File:linux_01.png|580px|screenshot]]
 
−
# Double-click to open it in KWrite.
 
−
# Insert your IPv6 prefix, subnet and gateway.
 
−
#: [[File:linux_02.png|580px|screenshot]]
 
−
# Once done, don’t forget to save the changes. If you need help, please do not hesitate to post your issue in the [https://app.element.io/#/room/#ic-node-providers:matrix.org IC Node Provider Matrix channel].
 
−
#:[[File:linux_03.png|580px|screenshot]]
 
  
−
== 5. Connect Crash Cart ==
+
Edit the config.ini file to add your network configuration.
−
# In order to configure the UEFI and initiate the installation of the IC-OS, please connect a crash cart to the physical machine.
 
−
# Plug-in the VGA/Video, keyboard and IC-OS USB stick
 
−
#: [[File:08.png|580px|screenshot]]
 
  
−
== 6. UEFI Setup and Boot Menu ==
+
Note that '''all Node Providers are requested to deploy two nodes with IPv4 and a domain name for every data center they operate in.''' Node Providers should deploy IPv4 to the '''first two nodes in their first rack.'''
 +
 
 +
#Insert your IPv6 prefix and gateway.
 +
#:[[File:IPv6 config ini.png|780px|screenshot]]
 +
#:*The IPv6 prefix should consist of four groups of hexadecimal digits, separated by colons (':'). Each group can contain up to four hex digits.
 +
#:* For example, a valid prefix could look like this: <code>2a00:fb01:400:200</code>
 +
#:*'''Important:'''
 +
#:**The prefix should not have a trailing ':'
 +
#:**IPv6 CIDR notation allows for a double colon ('::') to represent consecutive groups of zeroes in an address. However, the  prefix configuration in this context does '''not''' support '::'. The '::' shorthand should '''not''' be used. Even if some groups are all zeros, they must be explicitly written out.
 +
#[Optional] Insert your IPv4 info and domain name.
 +
#:[[File:IPv4 config ini.png|780px|screenshot]]
 +
#:*Configuring your node with IPv4 settings is optional, but if you do configure your node with IPv4 settings, you must also define the domain name for your node.
 +
#:*'''Important:'''
 +
#:**Please note that you '''must use a unique IPv4 address for each node you deploy.''' This means that you cannot use a single IC-OS installation image to deploy multiple nodes (like you are able to do when just configuring IPv6 nodes).  '''After each IPv4 node deployment, you must plug your IC-OS Installation USB stick back into your laptop and return to [[Node Deployment Guide (with an HSM)#6. Add configuration|step 6]] in the node deployment guide to reconfigure your installation image.'''
 +
#:**You can add, remove, or update your node’s IPv4 address and domain name after completing node deployment using dfx commands. See [[Updating your node's IPv4 and domain name|here]] for details.
 +
#Save the changes.
 +
#:*If you have trouble saving this file directly, you may need to save to a known location first, then copy the file into place.
 +
#:*:[[File:mac_03.png|580px|screenshot]]
 +
 
 +
==7. Connect Crash Cart==
 +
#In order to configure the UEFI and initiate the installation of the IC-OS, please connect a crash cart to the physical machine.
 +
#Plug-in the VGA/Video, keyboard and IC-OS USB stick
 +
#:[[File:08.png|580px|screenshot]]
 +
 
 +
==8. UEFI Setup and Boot Menu==
 
Use the related page below to set up the BIOS/UEFI according to your hardware vendor.
 
Use the related page below to set up the BIOS/UEFI according to your hardware vendor.
  
−
* [[Node Provider Machine Hardware Guide#Gen 2 Node Machine requirements|Gen2 hardware]]
+
*[[Node Provider Machine Hardware Guide#Gen 2 Node Machine requirements|Gen2 hardware]]
−
** [[IC-OS Installation - UEFI Configuration - Gen2 Dell]]
+
**[[IC-OS Installation - UEFI Configuration - Gen2 Dell]]
−
** [[IC-OS Installation - UEFI Configuration - Gen2 Supermicro]]
+
**[[IC-OS Installation - UEFI Configuration - Gen2 Supermicro]]
−
** <!--
+
**[[IC-OS Installation - UEFI Configuration - Gen2 Gigabyte]]
−
* * [[IC OS Installation - UEFI Configuration - ASUS]]
+
**[[IC-OS Installation - UEFI Configuration - Gen2 ASUS]]
−
* [[IC OS Installation - UEFI Configuration - Gigabyte]]
+
*[[Node Provider Machine Hardware Guide#Gen 1 Node Machine requirements|Gen1 hardware]]
−
-->
+
**[[IC-OS Installation - UEFI Configuration - Gen1 Dell|IC-OS Installation - UEFI Configuration - Gen1 Dell (Poweredge R6525)]]
−
* [[Node Provider Machine Hardware Guide#Gen 1 Node Machine requirements|Gen1 hardware]]
+
**[[IC-OS Installation - UEFI Configuration - Gen1 Supermicro]]
−
** [[IC-OS Installation - UEFI Configuration - Gen1 Dell]]
+
***
−
** [[IC-OS Installation - UEFI Configuration - Gen1 Supermicro]]
 
−
***  
 
 
'''Important:''' Do NOT enable the RAID bios setting. Doing so will cause issues with the IC-OS installation.
 
'''Important:''' Do NOT enable the RAID bios setting. Doing so will cause issues with the IC-OS installation.
  
 
Resume from this point when you are finished configuring the BIOS.
 
Resume from this point when you are finished configuring the BIOS.
  
−
== 7. IC-OS Installation ==
+
==9. IC-OS Installation ==
−
# Please wait while the USB Installer is booting up. This process can take up to 3 minutes.
+
#Please wait while the USB Installer is booting up. This process can take up to 3 minutes.
−
#: [[File:35-sm.png|580px|screenshot]]
+
#:[[File:35-sm.png|580px|screenshot]]
−
# The IC-OS installation starts. Please keep an eye on the progress. This part can take up to 10 minutes. Please remember to check the [[Possible Node Onboarding Errors]] page if you encounter any errors.
+
#The IC-OS installation starts. Please keep an eye on the progress. This part can take up to 10 minutes. Please remember to check the [[Troubleshooting Node Deployment Errors]] page if you encounter any errors.
 
#:[[File:36-sm.png|580px|screenshot]]
 
#:[[File:36-sm.png|580px|screenshot]]
−
# Once you get asked to insert the HSM, please remove the keyboard and instead insert the HSM USB device.  
+
#Once you get asked to insert the HSM, please remove the keyboard and instead insert the HSM USB device.  
 
#:[[File:37-sm.png|580px|screenshot]]
 
#:[[File:37-sm.png|580px|screenshot]]
−
# If the installation finished successfully, it will initiate a reboot. '''Please do not unplug the USB stick or HSM USB''' device at this point.
+
#If the installation finished successfully, it will initiate a reboot. 🚨 '''Please do not unplug the USB stick or HSM USB''' device at this point. 🚨
 
#:[[File:38-sm.png|580px|screenshot]]
 
#:[[File:38-sm.png|580px|screenshot]]
  
  
−
== 8. First Boot ==
+
==10. First Boot==
−
Please remember to check the [[Possible Node Onboarding Errors]] page if you encounter any errors onboarding.
+
Please remember to check the [[Troubleshooting Node Deployment Errors]] page if you encounter any errors.
−
'''Do NOT re-try the onboarding after proceeding to this section, as this can cause duplication within the registry.'''
+
#The first boot of the IC-OS '''still requires the HSM USB device to be plugged in'''. Please wait to take out the device until further instructions. This step can take several minutes.
−
# The first boot of the IC-OS still requires the HSM USB device. Please wait until further instructions. This step can take up to 2 minutes.
+
#Once you see this message, you may unplug the HSM USB device, USB stick and VGA/Video.
−
#:[[File:39-sm.png|580px|screenshot]]
+
#:[[File:Node join message.png|580px|screenshot]]
−
# Once you see this message, you may unplug the HSM USB device, USB stick and VGA/Video. Your machine successfully joined the Internet Computer!
+
 
−
#:[[File:40-sm.png|580px|screenshot]]
+
 
 +
Congratulations! Your machine successfully joined the Internet Computer! The machine has joined the IC and the Node Provider will start receiving rewards!
 +
 
 +
'''Note that if you do NOT see a "Join request successful" message, your node may still have successfully onboarded. Continue to the next step to attempt to verify node onboarding.'''
 +
 
 +
==11. Verify node onboarding==
  
−
Congratulations! Your machine successfully joined the Internet Computer! Again, once you see this message, '''do NOT re-try the onboarding after proceeding to this section, as this can cause duplication within the registry.''' The machine has joined the IC and the node provider will start receiving rewards!
+
#Obtain your Node ID
 +
#*Your Node ID should have been outputted in the previous step. If it wasn't, '''please wait at least 10 minutes to see if the node ID is logged to the console.'''
 +
#Verify that your node was successfully onboarded by checking its status on the [https://dashboard.internetcomputer.org/ dashboard]
 +
#*The dashboard can be searched by your Node Provider principal. There, you should see the Node ID of your node.
 +
#*If the status of your node is either “Awaiting Subnet” or “Active in Subnet,” '''congratulations! Your machine successfully joined the Internet Computer!'''
 +
#*If the status of your node is NOT either “Awaiting Subnet” or “Active in Subnet”, or if it is NOT listed under your Node Provider principal, you should consult the [[Troubleshooting Node Deployment Errors]] page.
 +
#*:[[File:Node onboarding verification.png|680px|screenshot]]
 +
#If deploying with IPv4, verify that IPv4 was successfully configured
 +
#*Ten minutes after the initial <code>Join request successful!</code> message, you should see another log indicating a successful IPv4 deployment:
 +
#*:[[File:IPv4 log.jpg|680px|screenshot]]
 +
#*If your log says <code>IPv4: none configured</code>, then your IPv4 deployment failed.
  
−
== 9. Verify node onboarding ==
 
  
−
# Return to the [[Node Provider Onboarding#10. Onboard nodes|Node Provider Onboarding]] instructions to verify that your nodes were successfully onboarded
+
If you are failing to verify your node onboarding, consult the [[Troubleshooting Node Deployment Errors]] page.

Latest revision as of 21:12, 13 November 2024

This runbook covers all steps necessary to install the Internet Computer Operating System (IC-OS) using the legacy NitroKey HSM instructions. To use the non-HSM onboarding instructions, follow the IC-OS Installation Runbook.

The physical machine is expected to be racked and stacked according to its respective manual.

To complete these steps, you are expected to be physically present in the data center your machine(s) reside(s). Once you successfully onboarded your first node, you can bring up the other nodes in parallel.

If you encounter issues during any of these steps, consult the Troubleshooting Node Deployment Errors page.

⚠️ DFINITY does not offer live support for Node Providers attempting to deploy nodes.

1. Choose onboarding path (HSM vs no HSM)

If you chose the HSM Node Provider Onboarding Path, continue to the next step.

If you chose to onboard without a Nitrokey HSM, follow the IC-OS Installation Runbook to onboard your nodes.

2. Obtain requirements

  • A USB (3.0 speed that can hold at least 4GB) to put the image file on.
    • Faster USBs will allow the process to go much faster.
  • The NitroKey HSM for your data center.
  • [Optional] A USB hub
    • This is helpful at some data centers for simultaneously connecting keyboard, mouse, Nitrokey, etc.
  • It is recommended that each server has a label with the BMC's MAC address for ease of identification in future dashboard upgrades.

3. Download installation image

Download the latest release of the IC-OS USB Installer Image and the corresponding checksum from the Internet Computer Dashboard Releases.

  • Note that you should always use a release from the last 6 weeks (newer is better) in order to ensure that your node can correctly correct to the network.

4. Verify checksum and unarchive file

Mac OS X

  1. Open the Terminal and type: 
    shasum -a 256 ~/Downloads/disk-img.tar.zst
  2. Compare the calculated checksum with the IC-OS installation image checksum file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please post your issue in the Node Provider Matrix channel.
    Open the Terminal and type: 
    tar xzvf ~/Downloads/disk-img.tar.zst

Linux / Ubuntu

  1. Open the Terminal and type: 
    sha256sum ~/Downloads/disk-img.tar.zst
  2. Compare the calculated checksum with the IC-OS installation image checksum file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please post your issue in the Node Provider Matrix channel.
    Open the Terminal and type: 
    tar xzvf ~/Downloads/disk-img.tar.zst

Windows

  1. Open PowerShell and type: 
    Get-FileHash -Algorithm SHA256 .\Downloads\disk-img.tar.zst
  2. Compare the calculated checksum with the IC-OS installation image checksum file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please post your issue in the Node Provider Matrix channel.
    Open PowerShell and type: 
    tar xzvf .\Downloads\disk-img.tar.zst

5. Create Bootable USB Stick

Mac OS X

  1. Open the Terminal and type: 
    diskutil list
  2. All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive: 
    sudo diskutil unmount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/disk4s1
  3. Replace /dev/YOUR_USB_DEVICE with the device that corresponds to your USB stick. Additionally, replace the path to your downloaded IC-OS disk.img file. Warning: You risk losing your own data if you specify a wrong drive. 
    sudo dd if=/Users/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M status=progress
    If you get a “device is busy” error from the dd command, you can try running the following command to unmount all of the partitions on the disk, then re-run the dd command:
    sudo diskutil unmountDisk /dev/YOUR_USB_DEVICE # E.g. /dev/disk4

Linux / Ubuntu

  1. Open the Terminal and type 
    blkid
  2. All available drives should be shown. Identify which device corresponds to your USB stick. You may need to unmount the USB drive: 
    sudo umount /dev/YOUR_USB_DEVICE_MOUNTED_PARTITION # E.g. /dev/sdb1
  3. Replace /dev/YOUR_USB_DEVICE with the device that corresponds to your USB stick. Additionally, replace the path to your downloaded IC-OS disk.img file. Warning: You risk losing your own data if you specify a wrong drive. 
    sudo dd if=/home/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M status=progress

Windows

  1. Download and install Rufus Portable
  2. Start Rufus
  3. Select the USB stick under device and select the previously downloaded IC-OS disk image and press start
    screenshot
  4. You may see some warnings. Make sure you don't have any other USBs in your computer and chose OK
    screenshot
    screenshot
  5. The "Ready" bar will go from left to right as it completes.

6. Add configuration

A. Open Config.ini in a text editor

Mac OS X

  1. Open Finder. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
    screenshot
  2. Double-click config.ini to open it in TextEdit.


Linux

  1. Open the File Manager. You should now be able to see the CONFIG partition. If it's not visible, remove the USB and insert it again.
    screenshot
  2. Double-click config.ini to open it in KWrite.


Windows

  1. Open the Disk Management utility with a right click on the Start menu.
    screenshot#:
  2. Right click the CONFIG partition.
  3. Select Change drive letter or paths...
    screenshot
  4. Select any letter from the drop-down list.
    screenshot
  5. Click OK.
  6. You should now be able to see the CONFIG partition in your Windows Explorer. Select the config.ini configuration file.
    screenshot
  7. Click on Edit to open it.

B. Edit Config.ini

Edit the config.ini file to add your network configuration.

Note that all Node Providers are requested to deploy two nodes with IPv4 and a domain name for every data center they operate in. Node Providers should deploy IPv4 to the first two nodes in their first rack.

  1. Insert your IPv6 prefix and gateway.
    screenshot
    • The IPv6 prefix should consist of four groups of hexadecimal digits, separated by colons (':'). Each group can contain up to four hex digits.
    • For example, a valid prefix could look like this: 2a00:fb01:400:200
    • Important:
      • The prefix should not have a trailing ':'
      • IPv6 CIDR notation allows for a double colon ('::') to represent consecutive groups of zeroes in an address. However, the prefix configuration in this context does not support '::'. The '::' shorthand should not be used. Even if some groups are all zeros, they must be explicitly written out.
  2. [Optional] Insert your IPv4 info and domain name.
    screenshot
    • Configuring your node with IPv4 settings is optional, but if you do configure your node with IPv4 settings, you must also define the domain name for your node.
    • Important:
      • Please note that you must use a unique IPv4 address for each node you deploy. This means that you cannot use a single IC-OS installation image to deploy multiple nodes (like you are able to do when just configuring IPv6 nodes). After each IPv4 node deployment, you must plug your IC-OS Installation USB stick back into your laptop and return to step 6 in the node deployment guide to reconfigure your installation image.
      • You can add, remove, or update your node’s IPv4 address and domain name after completing node deployment using dfx commands. See here for details.
  3. Save the changes.
    • If you have trouble saving this file directly, you may need to save to a known location first, then copy the file into place.
      screenshot

7. Connect Crash Cart

  1. In order to configure the UEFI and initiate the installation of the IC-OS, please connect a crash cart to the physical machine.
  2. Plug-in the VGA/Video, keyboard and IC-OS USB stick
    screenshot

8. UEFI Setup and Boot Menu

Use the related page below to set up the BIOS/UEFI according to your hardware vendor.

Important: Do NOT enable the RAID bios setting. Doing so will cause issues with the IC-OS installation.

Resume from this point when you are finished configuring the BIOS.

9. IC-OS Installation

  1. Please wait while the USB Installer is booting up. This process can take up to 3 minutes.
    screenshot
  2. The IC-OS installation starts. Please keep an eye on the progress. This part can take up to 10 minutes. Please remember to check the Troubleshooting Node Deployment Errors page if you encounter any errors.
    screenshot
  3. Once you get asked to insert the HSM, please remove the keyboard and instead insert the HSM USB device.
    screenshot
  4. If the installation finished successfully, it will initiate a reboot. 🚨 Please do not unplug the USB stick or HSM USB device at this point. 🚨
    screenshot


10. First Boot

Please remember to check the Troubleshooting Node Deployment Errors page if you encounter any errors.

  1. The first boot of the IC-OS still requires the HSM USB device to be plugged in. Please wait to take out the device until further instructions. This step can take several minutes.
  2. Once you see this message, you may unplug the HSM USB device, USB stick and VGA/Video.
    screenshot


Congratulations! Your machine successfully joined the Internet Computer! The machine has joined the IC and the Node Provider will start receiving rewards!

Note that if you do NOT see a "Join request successful" message, your node may still have successfully onboarded. Continue to the next step to attempt to verify node onboarding.

11. Verify node onboarding

  1. Obtain your Node ID
    • Your Node ID should have been outputted in the previous step. If it wasn't, please wait at least 10 minutes to see if the node ID is logged to the console.
  2. Verify that your node was successfully onboarded by checking its status on the dashboard
    • The dashboard can be searched by your Node Provider principal. There, you should see the Node ID of your node.
    • If the status of your node is either “Awaiting Subnet” or “Active in Subnet,” congratulations! Your machine successfully joined the Internet Computer!
    • If the status of your node is NOT either “Awaiting Subnet” or “Active in Subnet”, or if it is NOT listed under your Node Provider principal, you should consult the Troubleshooting Node Deployment Errors page.
      screenshot
  3. If deploying with IPv4, verify that IPv4 was successfully configured
    • Ten minutes after the initial Join request successful! message, you should see another log indicating a successful IPv4 deployment:
      screenshot
    • If your log says IPv4: none configured, then your IPv4 deployment failed.


If you are failing to verify your node onboarding, consult the Troubleshooting Node Deployment Errors page.

Retrieved from "https://wiki.internetcomputer.org/w/index.php?title=Node_Deployment_Guide_(with_an_HSM)&oldid=7985"