Post-Installation Guide
Prerequisites
This guide assumes that you have successfully reached and completed the last step in the “DGMV ICT BlackBox OS - Installation Guide” document.
Please only continue, once you have managed to connect via SSH.
Step 1: Backup or restore seed phrase
The system will automatically initialize a master seed key file. It’s important to write the contents of the file down in a secure location where only designated people have access. It’s crucial that the master seed can only be accessed by authorized personnel. The DGMV ICT BlackBox OS uses this key file to derive other secrets and passwords. A different master seed will result in absolutely different secrets and passwords.
Note that in particular backups will be encrypted using this secret file. A loss of the master seed means you will be unable to access backups of the system.
You can find the file under:
/var/dgmv/data/config/seed_phrase
Backup the contents of the master seed file while treating it confidential.
DigiCorp Labs strongly advises against digital storage of this secret. Instead, it should be physically recorded on paper, sealed in an envelope, and secured in a controlled-access location, such as a metal safe accessible only to authorized personnel.
Step 2: Determine root domain
In order to complete the system post-installation procedure, a root domain has to be chosen. Use a public TLD domain if you are hosting the system publicly accessible in the cloud, or use a custom DNS of your private organization. You may include a subdomain too.
Valid examples:
myorg.network
blackbox.myorg.network
blackbox.myorg.com (TLD)
Whatever root domain is chosen by your organization, DGMV ICT BlackBox OS will expect to use five subdomains of the root domain:
iam.rootdomainiam-auth.rootdomainiam-dashboard.rootdomainhcp-auth.rootdomainoverview.rootdomain
CAUTION: In a self-hosted environment, you need to take care of providing appropriate certificates for the root domain you chose, whereas publicly accessible TLD domains may benefit from using Letsencrypt (supported by the system).
Once you have chosen the root domain, you need to edit the contents of a file on the filesystem using vi.
You can find the file under: /var/dgmv/data/config/domain.
Replace existing contents with the domain that was chosen by your organization.
Choose a root domain where the DGMV ICT BlackBox OS can create services under.
Step 3: Choosing or uploading certificates
By default, the system will create self-signed certificates. While this will work by default, it’s not recommended to use this in a production setup. Please provide custom certificates or set up Letsencrypt to issue the certificates.
Custom certificates:
This option can be enabled by editing the file /var/dgmv/data/config/certs/mode to “manual”. You may then copy the corresponding key files (*.pem and *.key) under /var/dgmv/data/config/certs .
This can be achieved using:
scp -O -P 2208 cert.pem cert.key
root@<blackbox-hostname>:/var/dgmv/data/config/certs
LetsEncrypt:
This option can be enabled by changing the contents of the file /var/dgmv/data/config/certs/mode to “letsencrypt”. In order for LetsEncrypt to work, the system must have a public IP address and the DNS entries must point to that IP address. Make sure to create a DNS entry for each subdomain as described in Step 2.
Decide whether to enable Custom Certificates or LetsEncrypt by modifying the mode file and possibly feasibly uploading the certificate + key file to the designated remote location.
Step 4: Grant access to other personnel
The DGMV ICT BlackBox OS will apply all ssh-keys that are provided by a cloud provider. Generally, they allow you to specify 1..n public keys that will be transferred to the operating system, allowing you to define who has access to the system. The BlackBox OS also allows you to statically define ssh public keys that are persisted across reboots. This file can be found at /var/dgmv/metadata/authorized_keys.
Note that editing this file in on-premise systems is very dangerous, as it might lock you out from the system. Always make sure to provide the correct credentials to the system. The modifications will only take effect after rebooting.
Define who has access to the system by registering corresponding ssh public keys.
Make sure to only grant access to trusted personnel and devices. DigiCorp Labs recommends to only allow the superadmin of your organization to get ssh access to the system. After configuring the BlackBox OS, direct access is only needed for system backups and management.
Step 5: Determine active services
In this step, we will let the operating system know which services we want to be active. By default, the following services will be active and cannot be disabled:
DGMV-IAM: Identity Provider which is the core component in the operating system. It will make sure every application is properly protected. Comes with a web interface that allows you to authenticate using the DGMV-ID Enterprise Mobile App
DGMV-IAM Admin CLI: Web interface that allows you to do deep-level configurations related to DGMV-IAM. This is specifically required during early setup but can only be used with an SSH tunnel.
DGMV-IAM Database: This database will store essential metadata and configurations of DGMV-IAM
DGMV-IAM Admin Dashboard: Allows you to administrate DGMV-IAM through a graphical browser-based user interface
DGMV ICT BlackBox Frontpage: Gives you a placative overview of what applications are installed.
However, you may also enable:
HCP-Auth: adds additional protection to your HCP Clusters
B(LOG): blockchain-based logging receiver, protecting the integrity of system and application logs using blockchain transactions
The services can be enabled by creating corresponding files under /var/dgmv/data/config/services:
HCP-Auth can be enabled by creating /var/dgmv/data/config/services/hcp
B(LOG) can be enabled by creating /var/dgmv/data/config/services/blog
Note that the files just have to exist. Leaving them empty will work.
Decide whether to enable HCP-Auth and/or B(LOG) by creating the corresponding filesystem entries
Step 7: Optional: Use a custom geo IP database
The DGMV ICT BlackBox OS contains a default IP database. However, you may choose to replace it with your own geo IP database, such as a MaxMind or IP2Location database.
The database that is shipped by default provides basic location mapping, but its accuracy can be improved by using more professional databases.
You can choose the geo type by editing the file under /var/dgmv/data/config/geo/type. Example: you may enter geolite2 as a value. You can upload a custom database file to the same directory, make sure the database file is called /var/dgmv/data/config/geo/db (no extension).
You may copy the file using scp:
scp -O -P 2208 geolite2.mmdb root@<blackbox-hostname>:/var/dgmv/data/config/geo/db
Decide whether to use a custom database and upload it to the BlackBox OS.
Step 8: Apply configuration
The configuration can be applied by creating a file
/var/dgmv/data/config/UPDATE
Note that the file will disappear very quickly once it was consumed by the BlackBox OS. If it disappears, it means the system will process the new configuration.
Post-Installation complete
Congratulations! After these steps the BlackBox OS should be up and running. You can verify this by visiting
https://overview.ROOTDOMAIN using your browser.
The configuration can be applied by creating a file
/var/dgmv/data/config/UPDATE
Note that the file will disappear very quickly once it was consumed by the BlackBox OS. If it disappears, it means the system will process the new configuration.
Post-Installation complete
Congratulations! After these steps the BlackBox OS should be up and running. You can verify this by visiting
https://overview.ROOTDOMAIN using your browser.
Last updated