Setting up the environment by using the setup script

The IBM Hyper Protect Virtual Servers provides an automated procedure that simplifies the installation and configuration of the IBM Hyper Protect Virtual Servers environment.

This procedure is intended for users with the role cloud administrator.

Before you begin

Refer to the checklist that you prepared for the management server in the topic Planning for the environment.
Check that you have IBM Hyper Protect Virtual Servers installation binary on the x86 or Linux on IBM Z/LinuxONE (i.e., s390x architecture) management server. For more information, see Downloading IBM Hyper Protect Virtual Servers.
Check that the x86 or Linux on IBM Z/LinuxONE (i.e., s390x architecture) management server has the following required software packages:
- One of supported Docker versions
- OpenSSL
- GPG
- The haveged utility

Procedure

On your x86 or Linux on IBM Z/LinuxONE (i.e., s390x architecture) management server, complete the following steps under the <installation_directory> directory.

Run the setup.sh shell script to complete the environment preparation on the management server. When you run the setup script the first time, you must accept the license in order to continue with the setup.
```
./setup.sh -e LICENSE=accept
```
A message is displayed stating that the license was accepted and the setup continues.
To view the license you can run the following command.
```
./setup.sh -e LICENSE=view -e LANG=xx
```
where xx is the language code. See Available language codes for the list of available language codes. If no language code is specified, the default language is used which is English.
You can also deny accepting the license by running the following code. However, you cannot proceed with the setup without accepting the license.
```
sh setup.sh -e LICENSE=deny
```
If you have already accepted the license earlier and want to run the setup script again, you can use the following command.
```
./setup.sh
```
Note: If you have not accepted the license even once, then running the script results in an error and you are prompted to accept the license.

The setup.sh shell script automates the following actions:
- Invoke the envcheck.sh script to validate the prerequisites. The envcheck.sh shell script automates checking of the following requirements of the management server and does the following:
  - The system architecture: when the system architecture is not x86 or Linux on IBM Z/LinuxONE (i.e., s390x architecture), the script fails and a message stating that the architecture is not supported is displayed.
  - The Linux distribution: When the Linux distribution is not Ubuntu or RHEL, the script fails and a message is displayed stating that the script is supported only Ubuntu and RHEL based systems.
  - The Ubuntu or RHEL Version: When the Ubuntu Version is not 20.04 or later, or the RHEL Version is not 7.X or later, or 8.X or later, a warning message is displayed indicating that the Ubuntu or RHEL versions are not supported and the script continues execution.
  - GPG version: When the GPG version is not 2.2.4 or later, the script fails and a message is displayed stating that the GPG version must be upgraded.
  - Docker Installation: When Docker is not installed, the script fails. Also, when Docker is not at version 19.03.2 or later for x86, and 18.06.3 or later for s390x, the script fails.
  - Number of CPU cores: When number of cores is less than 4 for x86 and 1 for x390x, a warning message is displayed that there are lesser number of cores than required and the script continues execution.
  - Amount of memory: When the memory is less than 8 GB, a warning message is displayed that the memory is less than required and the script continues execution.
  - Disk space: When the disk space is less than 150 GB, a warning message is displayed that the disk space is less than required and the script continues execution.
  - OpenSSL: When OpenSSL is not installed, the script fails. A message prompting you to install OpenSSL and retry the script is displayed.
  - The haveged utility: When haveged is not installed, the script fails. A message prompting you to install haveged and retry the script is displayed.
- Sets the PATH for the hpvs commands
- Creates the $HOME/hpvs (working directory) directory structure and copies all the keys, registry files, and all the required config files and creates symbolic links of the images to this folder.
- Extracts and verifies the base images in the installation directory.
- Loads the base images hpvsop-base and hpvsop-base-ssh into your local Docker registry.
- Creates and updates the $HOME/hpvs/config/reg.json config file with the registry details for your remote Docker registry server, or with the IBM Cloud Container Registry details. The credentials will be encrypted after the script completes.
- Updates the $HOME/hpvs/hosts config file with the Secure Service Container partition information. You need to enter the IP address of the partition, and connection credentials.
You are prompted to select an option for configuring the container registry. Select a value of 1 when you want to use Docker Hub (publicly hosted). Select a value of 2 when you want to use the IBM Cloud Container Registry. Use one of the following set of instructions depending on the option you choose for configuring the container registry.
1. When the script is executing the setup of the Docker registry (when you chose a value of 1), you are prompted to enter the following information.
- The Docker registry name, for example docker_hub.
- The Docker registry Username, for example docker_username.
- The Docker registry password. Type in the password of the Docker registry.
1. When the script is executing the setup of the IBM Cloud Container Registry (when you chose a value of 2), you are prompted to enter the following information.
- The IBM Cloud Container Registry name, for example cloud_reg.
- The IBM Cloud Container Registry Server URL, for example us.icr.io.
- The CONTENT_TRUST_SERVER URL, for example https://notary.us.icr.io
- The IBM Cloud API key: Type in the IBM Cloud API key. (For more information, see the section Creating an IBM Cloud API Key).
- IBM Cloud Container Registry (ICR) supports only Red Hat signing of the images.
When the script is executing the setup of the hosts config file, you are prompted to enter the following information.
- The Secure Service Container LPAR (Host) IP address, for example 10.20.4.23.
- The Secure Service Container LPAR (Host) Name, for example zbcor5.
- The Username of the Secure Service Container LPAR, for example blockchain.
- The password.
To push base images to the container registry, refer the instructions provided in Registering base images in the remote registry server.

The following is an example of the directory structure (working directory) created by the setup script which shows the symbolic links that were created.

 .
 ├── config
 │   ├── grep11
 │   │   ├── images
 │   │   │   └── hpcsKpGrep11_runq.tar.gz -> /var/127-GA/images/hpcsKpGrep11_runq.tar.gz
 │   │   ├── keys
 │   │   ├── regfiles
 │   │   └── vs_grep11.yml
 │   ├── hpvsopbase
 │   │   ├── images
 │   │   │   └── HpvsopBase.tar.gz -> /var/127-GA/images/HpvsopBase.tar.gz
 │   │   ├── keys
 │   │   ├── regfiles
 │   │   └── vs_hpvsopbase.yml
 │   ├── hpvsopbasessh
 │   │   ├── images
 │   │   │   └── HpvsopBaseSSH.tar.gz -> /var/127-GA/images/HpvsopBaseSSH.tar.gz
 │   │   ├── keys
 │   │   ├── regfiles
 │   │   └── vs_hpvsopbasessh.yml
 │   ├── monitoring
 │   │   ├── images
 │   │   │   ├── CollectdHost.tar.gz -> /var/127-GA/images/CollectdHost.tar.gz
 │   │   │   └── Monitoring.tar.gz -> /var/127-GA/images/Monitoring.tar.gz
 │   │   ├── keys
 │   │   ├── regfiles
 │   │   └── vs_monitoring.yml
 │   ├── reg.json
 │   ├── securebuild
 │   │   ├── images
 │   │   │   └── SecureDockerBuild.tar.gz -> /var/127-GA/images/SecureDockerBuild.tar.gz
 │   │   ├── keys
 │   │   ├── regfiles
 │   │   ├── secure_build.yml.example
 │   │   ├── secure_create.yml.example
 │   │   └── vs_securebuild.yml
 │   ├── templates
 │   │   ├── virtualserver.template.readme.yml
 │   │   └── virtualserver.template.yml
 │   ├── vs_configfile_readme.yml
 │   └── vs_regfiledeployexample.yml
 ├── hosts
 └── logs

Where:

images/HpvsopBase.tar.gz, which is the base image of a Hyper Protect Virtual Servercontainer without the secure shell (SSH) access.
images/HpvsopBaseSSH.tar.gz, which is the base image of a Hyper Protect Virtual Server container with the secure shell (SSH) access.
images/CollectdHost.tar.gz, which is the base image of collectd-host container of the monitoring infrastructure.
images/SecureDockerBuild.tar.gz, which is the docker image of the Secure Build container.
images/Monitoring.tar.gz, which is the base image of monitoring-host container of the monitoring infrastructure.
images/hpcsKpGrep11_runq.tar.gz, which is the base image of the GREP11 container.
config/templates/virtualserver.template.yml, which is the template example of network, quotagroup, and resoource definitions for the virtual server.
config/yaml, a directory that contains configuration example files for the Hyper Protect Virtual Server containers.
config/grep11/keys, config/grep11/regfiles, config/hpvsopbase/keys, config/hpvsopbase/ regfiles, config/hpvsopbasessh/keys, config/hpvsopbasessh/regfiles, config/securebuild/keys, config/securebuild/regfiles, config/monitoring/keys, and config/monitoring/regfiles, you can use these folders to save the keys or .enc files you generate.

After the script completes, you can run the hpvs command locally to validate the environment is ready for use. The hpvs command shows you a list of supported actions to manage IBM Hyper Protect Virtual Servers. For more information about the hpvs command, see Commands for IBM Hyper Protect Virtual Servers.

Available language codes

Language Code	Language
cs	Slovak
en	English
in	Malay
ko	Korean
pt	Portuguese
tr	Turkish
de	German
es	Spanish
it	Italian
ru	Russian
zh	Chinese
el	Greek
fr	French
ja	Japanese
pl	Polish
sl	Slovenian
zh_TW	Chinese Traditional

To configure the environment for IBM Hyper Protect Virtual Servers, follow the instructions in Creating a Hyper Protect Virtual Server instance.

Setting up the environment by using the setup script

Before you begin

Procedure

The following is an example of the directory structure (working directory) created by the setup script which shows the symbolic links that were created.

Available language codes

Next