Internet Computer wiki

This Node deployment runbook covers all steps necessary to install the Internet Computer Operating System (hereinafter called IC-OS). The physical machine is expected to be racked and stacked according to the respective manual. In case you encounter any issues during the installation process, we kindly ask you to send an email with the error message to: support@internetcomputer.org

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 (A faster USB will allow the process to go much faster.)
• The Nitrokey HSM for your data center.
• A USB hub is helpful at some data centers, so you may wish to have one available.
• It is recommended that you have a plan for providing details if troubleshooting assistance is needed. We recommend that you track the serial number (on the pull-out tab) for each server and compare the screenshots in the directions with each step. If assistance is needed, you will need to provide:
  • The serial number of the server in question
  • Which step was last completed
  • A screenshot or video showing any results that are different from what is expected.
  • Verification of the HSM key and config.ini file that is being used.

I. Download installation image

1. Download the IC-OS disk image here:
   https://download.dfinity.systems/blessed/ic/f736069ae6a6e39a73f211c587705e0f8dfdfb06/setup-os/disk-img/disk-img.tar.gz
   
2. Download the corresponding checksum here:
   https://download.dfinity.systems/blessed/ic/f736069ae6a6e39a73f211c587705e0f8dfdfb06/setup-os/disk-img/SHA256SUMS

II. 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 file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please contact the Internet Computer Association.
• In the Terminal 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 file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please contact the Internet Computer Association.
• In the Terminal 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 file downloaded in the previous step. Warning: Only continue if they are identical, otherwise please contact the Internet Computer Association.
• In PowerShell type:

  tar xzvf .\Downloads\disk-img.tar.gz
  

All Operating Systems

• Compare the calculated checksum with the one provided by the DFINITY foundation. Only continue if they are identical, otherwise please contact the DFINITY foundation.

III. Create Bootable IC-OS USB Stick

Mac OS X

1. Open the Terminal and type:

   diskutil list
   

2. The diskutil command simply shows all available drives. Verify the drive that identifies your USB stick.
3. In this next command, edit /dev/sda if needed so that it refers to your USB stick and not any other drive. Warning: You risk losing your own data if you specify a wrong drive.

   dd if=~/Downloads/setup-os_<version>.img of=/dev/sda
   

Linux / Ubuntu

1. Open the Terminal and type

   blkid
   

2. The blkid command simply shows all available drives. Verify the drive that identifies your USB stick.
3. In this next command, edit /dev/sda if needed so that it refers to your USB stick and not any other drive. Warning: You risk losing your own data if you specify a wrong drive.

   dd if=~/Downloads/setup-os_<version>.img of=/dev/sda
   

Windows

1. Download Rufus Portable from: https://rufus.ie/en/
2. Start Rufus
3. Select the USB stick under Device and SELECT the previously downloaded IC-OS disk image and press START

   

4. You may see some warnings. Make sure you don't have any other USBs in your computer and chose OK. Warning: You risk losing your own data if you specify a wrong drive.

   

   

5. The Ready bar will go from left to right as it completes.

IV. Add configuration

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.

   

2. Double-click to open it in TextEdit.
3. Overwrite the example with your the IPv6 prefix, subnet and gateway of your data center.

   

4. Once done, don’t forget to save the changes. If you need help, please do not hesitate to contact the Internet Computer Association.

   

Windows

1. Open the Disk Management utility with a right click on the Start menu

   

2. Right click the CONFIG partition
3. Select Change drive letter or paths...

   

4. Select any letter from the drop-down list

   

5. Click OK.
6. You should now be able to see the CONFIG partition in your Windows Explorer. Select the config.ini configuration file.

   

7. Click on Edit to open it in a text-only editor. Do not use an editor that will add formatting, as this could cause the installation to fail.
8. Overwrite the example with your own IPv6 prefix, subnet and gateway.

   

9. Once done, don’t forget to save the changes. If you need help, please do not hesitate to contact the Internet Computer Association.

   

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.

   

2. Double-click to open it in KWrite.
3. Overwrite the example with your own IPv6 prefix, subnet and gateway.

   

4. Once done, don’t forget to save the changes. If you need help, please do not hesitate to contact the Internet Computer Association.

   

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

   

VI. UEFI - Enter System Setup and reset IDRAC password

1. Reboot or power on the server.
2. Watch for the blue screen with boot options in the top left corner.
3. Press F2 a couple of times, once the options are listed.
4. If your option is recognized by the system, it should be highlighting Entering System Setup.
5. In the System Setup, select iDRAC Settings and press enter.

   screenshot

6. Select User Configuration and press enter.

   screenshot

7. Select Change Password and press enter.

   screenshot

8. Enter in your desired password and select OK.

   screenshot

9. Select Back and Finish.

VII. UEFI - System BIOS

1. In the System Setup, select System BIOS and press enter.

   

2. In the System BIOS, select Processor Settings and press enter.

   

3. Set NUMA Nodes Per Socket to 0

   Set Minimum SEV non-ES ASID to 253

   Select back to return to System BIOS.

   

VIII. UEFI - Boot Settings

1. Select Boot Settings and press enter.

   

2. Set Boot Mode to UEFI

   Select back to return to System BIOS.

   

IX. UEFI - Integrated Devices

1. Select Integrated Devices and press enter.

   

2. Set PCIe Preferred IO Bus to Enabled

   Set Enhanced Preferred IO to Enabled

   Set SR-IOV Global Enable to Enabled

   Select back to return to System BIOS.

   

X. UEFI - Miscellaneous Settings

1. Select Miscellaneous Settings and press enter.

   

2. Set F1/F2 Prompt on Error to Disabled

   Select back to return to System BIOS.

   

3. Select Finish and press enter.

   

4. Select Yes to save the changes and press enter.

   

5. Select OK and press enter.

   

6. Confirm the exit and press enter. The system will reboot now. Please do not unplug the IC-OS USB stick at this point.

XI. Boot Manager - Enter Boot Manager

1. Watch for the Blue screen with boot options in the top left corner. Press F11 a couple of times, once the options are listed.

   

2. If your option is recognized by the system, it should be highlighting Entering Boot Manager.

   

3. In the Boot Manager, select One-shot UEFI Boot Menu and press enter.

   

4. In the Boot Menu, select your USB device and press enter.

   

XII. IC-OS - Installer Boot

1. Please wait while the USB Installer is booting up. This process can take up to 3 minutes.

   

2. The IC-OS installation starts. Please keep an eye on the progress. This part can take up to 10 minutes (the duration heavily depends on the speed of the IC-OS USB device).

   If you encounter any issues, please send an email with the error message to: support@internetcomputer.org.

   

3. Once you get asked to insert the HSM, please remove the keyboard and instead insert the HSM USB device.

   

4. If the installation finished successfully, it will initiate a reboot. Please do not unplug the IC-OS USB stick or HSM USB device at this point.

   

XIII. IC-OS - First Boot

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

   

2. Once you see this message, you may unplug the HSM USB device, IC-OS USB stick and VGA/Video. Your machine successfully joined the Internet Computer.

   

Return to the Onboarding Document