BlackBox OS Installation Guide
Step 1: Determine Deployment Environment
First make sure to examine the environment of where the DGMV BlackBox ICT Operating System will be installed.
There are two primary types of installations for the Operating System:
Cloud-Based Installation: A cloud provider (IaaS) such as DigitalOcean or Vultr. They typically allow you to upload VM images (qcow2) format. Note that you might have to convert the format to the expected format. For this, please refer to the documentation of your cloud provider. In some cases (e.g. Vultr) they allow you to upload ISO images too, which are usually used in on-premise installations.
On-Premise Installation: This refers to physical hardware in which you might have to plug in a USB stick or a CDROM instead of uploading an image to an online portal. You might also want to use PXE Boot to install the operating system.
Decide whether to use Cloud-based installation or On-Premise installation.
Step 2: Choosing the right image
You can find a couple of variants in the DGMV distribution portal, in which recent versions of the operating system are regularly uploaded. You can find this portal here: https://downloads.dgmv.id
The access credentials are provided to you by DigiCorp Labs.
In a directory, you will see a bunch of files. Each file has the upload date depicted in the right column.
For each file there is also a corresponding checksum file (denoted by the extension .sha256). It’s recommended to compare the checksum after downloading a file, to make sure that the file did not get corrupted by the download or transfer to an installation medium.
Choose the right image for your deployment environment (chosen in Step 1). Here is a general guide how to select this:
Cloud-Based Installation: .qcow2 extension
On-Premise Installation: .iso extension
Download the corresponding installation image for your selected distribution environment.
Step 3: Preparing the installation medium
At this point, you have the correct operating system image downloaded. You now have to prepare the installation medium.
For cloud-based installations this means you have to upload the selected image to the portal of the cloud provider. Example: In DigitalOcean you have to navigate to:
Manage > Backups & Snapshots > Custom Images
and click the Primary Action Button “Upload image”.
Depending on the file size, you might have to spin up a temporary http server to be able to upload the image due to the constraints of browser based uploads.
Refer to your cloud-provider’s official documentation to see how to install VMs from prepared installation images.
For on-premise installations you have to choose either:
USB based installation: You have to format your USB stick using a tool like dd (Linux) or Rufus (Windows). Example command for Linux:
sudo dd if=/path/to/image.iso of=/dev/sdX bs=4M status=progress oflag=sync
(Make sure to specify the correct location of the iso image and select the correct device (sdX). CAUTION: This will wipe all your data on the USB stick. A misuse of the command is dangerous.
PXE boot based installation: You can boot the server via network. You have to make sure the ISO image is accessible within your network. Here is an illustrative example of how to complete this (may be incomplete). Extract the ISO to a reachable machine within your network. Spin up an http server and use a iPXE script like this to boot the server:
kernel http://HOSTNAME/blackbox/vmlinuz boot=casper netboot=http fetch=http://HOSTNAME/blackbox/blackbox.tar
initrd http://HOSTNAME/blackbox/initrd
boot
Furthermore, you have to inject your SSH public key into the installation.
Prepare the installation medium using the hints above. Continue to the next step, if you see the machine is booting up.
Step 4: Perform the installation
Cloud-Based Installation: The cloud based installation will be installed on its own. So you are basically done here. Make sure to upload your SSH public keys to the provider’s portal and select those during the installation. This is crucial so you will have access to the system after the installation. The first boot might take 5-10 minutes as it will encrypt the attached storage.
On-Premise Installation: In on-premise installations you will have to do a few manual interactions in order to install the system:
Prepare the ssh public key
Confirm key selection
Select a target disk for the installation
Confirm disk selection
The installer will either allow you to enter a given key manually, or enter an url such as http:// or https:// within the same network of the installer (DHCP required), as shown in this screenshot:
When installing the on-premise system using serial, you may be able to conveniently paste the ssh key. However, when you have access to VGA only and you cannot host a key in your local network, you may have to enter the key manually, which is very inconvenient.
We recommend to use an Ed25519 key for that use case, as they are resulting in smaller public keys. They are also considered more secure overall.
Hosting the key file via the network is the most convenient method. Hint: Such a server can easily be created using python:
python3 -m http.server
This will spin up a server on port 8000 on a system of your choice. Beforehand, you may create an authorized_keys file with your public key file in it.
Select a distribution method for your ssh public key. It’s recommended to use an HTTP server within your local network to host the authorized_keys file
You will also have the option to ignore entering an ssh public key, however, this is not recommended as you will be unable to continue with the post-installation steps.
After confirming the The system will wait for you to make a decision to select the target disk. It will list detected disks and ask you to input the index number shown on the left and shown in the screenshot below.
In this case, there is only one option that can be selected, as only one disk is attached to the system. By the way, it’s advised to use a raid system for additional redundancy and/or speed.
Select a target disk for the installation from the list of detected disks.
For the above screenshot, you will have to enter the number 0 and confirm by pressing Enter/Return.
After entering a number, it will show you one more time which physical disk you selected and it will ask you to confirm this action once more, as this will erase all data on that disk.
CAUTION: This will wipe all data on your disk. It might not be able to recover any data that has been lost. Make sure to backup your existing data, if you have any.
After confirming this with a yes, the system will install the assets and then attempt to reboot. Make sure to detach the installation medium before the system finishes the reboot. Otherwise it might boot from the installation medium again. If that happens, detach the installation medium and reboot the system again. It will then boot up the DGMV ICT BlackBox OS. Note, that the system usually takes a few minutes to boot for the first time. Subsequent boots will be very fast.
Step 5: Confirm operation
At this point, please confirm the operation.
There are two things you can confirm. First of all, for especially for cloud-based deployments, you can examine the virtual screen to see if is looking like this:
This screenshot shows the stage in which the operating system should be in. If you can see this, you know it’s up and running.
For on-premise deployments that have a VGA screen attached, you may see this too. Otherwise, you may need to examine the network address that the system received via DHCP or your manual network connection settings.
You may then test the connection using ssh:
ssh -p 2208 root@HOSTNAME_OR_IP
which hopefully brings up the following tty connection:
Congratulations! You have successfully installed the DGMV ICT BlackBox OS. You may now continue with the Post-Installation Steps document.
Last updated