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

Revision as of 21:56, 17 July 2023

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.

In case you encounter any issues during the installation process, check the Possible Node Onboarding Errors page. Otherwise, post your issue in the IC Node Provider Matrix channel.

Many thanks for your efforts in building the Internet Computer.

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

1. Download installation image

🚨🚨🚨 Download the IC-OS image and checksum released 2023-07-10, 7:38:52 AM UTC. Do NOT use the IC-OS image and checksum released 2023-07-17, 2:20:46 PM UTC.

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

2. Verify checksum and unarchive file

Mac OS X

Open the Terminal and type:

shasum -a 256 ~/Downloads/disk-img.tar.gz

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

Linux / Ubuntu

Open the Terminal and type:
```
sha256sum ~/Downloads/disk-img.tar.gz
```
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.gz
```

Windows

Open PowerShell and type:

Get-FileHash -Algorithm SHA256 .\Downloads\disk-img.tar.gz

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

3. Create Bootable USB Stick

Mac OS X

Open the Terminal and type:
```
diskutil list
```
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
```
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.
```
sudo dd if=/Users/YOUR_USER_NAME/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M
```
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

Open the Terminal and type
```
blkid
```
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/sdb1
```
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.
```
sudo dd if=~/Downloads/disk.img of=/dev/YOUR_USB_DEVICE bs=1M
```

Windows

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

4. 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.
Double-click config.ini to open it in TextEdit.

Linux

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.
Double-click config.ini to open it in KWrite.

Windows

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

B. Edit Config.ini

Insert your IPv6 prefix, subnet and gateway.
- 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:100
- 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.
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.
- If you need help, please do not hesitate to post your issue in the Node Provider Matrix channel.

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

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

7. IC-OS Installation

Please wait while the USB Installer is booting up. This process can take up to 3 minutes.
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.
Once you get asked to insert the HSM, please remove the keyboard and instead insert the HSM USB device.
If the installation finished successfully, it will initiate a reboot. Please do not unplug the USB stick or HSM USB device at this point.

8. First Boot

Please remember to check the Possible Node Onboarding Errors page if you encounter any errors onboarding. 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. 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. Your machine successfully joined the Internet Computer!

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!

9. Verify node onboarding

Verify that your node was successfully onboarded by checking its status on the dashboard is set to either “Awaiting Subnet” or “Active in Subnet”.
- The dashboard can be searched by your Node Provider principal. There, you should see the Node ID of your node (Node ID outputted in step 8).
- 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 contact the Node Provider Matrix channel for assistance.

@@ Line 22: / Line 22: @@
 # 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].
+# 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.gz</syntaxhighlight>
@@ Line 28: / Line 28: @@
 # Open the Terminal and type:
 #: <syntaxhighlight lang="shell">sha256sum ~/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].
+# 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.gz</syntaxhighlight>
@@ Line 34: / Line 34: @@
 # Open PowerShell and type:
 #: <syntaxhighlight lang="shell">Get-FileHash -Algorithm SHA256 .\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].
+# 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.gz</syntaxhighlight>
@@ Line 44: / Line 44: @@
 #:<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.
-#:<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</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 ===
@@ Line 65: / Line 66: @@
 == 4. Add configuration ==
-=== Mac OS X ===
+=== 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]]
+#:[[File:mac_01.png|580px|screenshot]]
-# Double-click to open it in TextEdit.
+# Double-click <code>config.ini</code> 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].
+===='''Linux'''====
-#:[[File:mac_03.png|580px|screenshot]]
+# 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 <code>config.ini</code> to open it in KWrite.
+==== '''Windows''' ====
-=== Windows ===
 # Open the Disk Management utility with a right click on the Start menu
-#: [[File:09-b.png|300px|screenshot]]#:
+#:[[File:09-b.png|300px|screenshot]]#:
 # Right click the CONFIG partition
 # Select Change drive letter or paths...
-#: [[File:10-b.png|780px|screenshot]]
+#:[[File:10-b.png|780px|screenshot]]
 # Select any letter from the drop-down list
-#: [[File:11-b.png|480px|screenshot]]
+#:[[File:11-b.png|480px|screenshot]]
 # 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.
-# 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]]
+# Insert your IPv6 prefix, subnet and gateway.
-# Double-click to open it in KWrite.
+#:[[File:Edit config ini.png|580px|screenshot]]
-# Insert your IPv6 prefix, subnet and gateway.
+#:* The IPv6 prefix should consist of four groups of hexadecimal digits, separated by colons (':'). Each group can contain up to four hex digits.
-#: [[File:linux_02.png|580px|screenshot]]
+#:* For example, a valid prefix could look like this: <code>2a00:fb01:400:100</code>
-# 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].
+#:*'''Important:'''
-#:[[File:linux_03.png|580px|screenshot]]
+#:** 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.
+# 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.
+#:* If you need help, please do not hesitate to post your issue in the [[Node Provider Matrix channel]].
+#:*:[[File:mac_03.png|580px|screenshot]]
 == 5. Connect Crash Cart ==