1. Administering Oracle Blockchain Platform
  2. Install Your Oracle Blockchain Platform Instance

3 Install Your Oracle Blockchain Platform Instance

Topics

Deploy Your Virtual Machine

Load Oracle Blockchain Platform Enterprise Edition on your Virtual Machine Hosting Software

  1. On the Oracle Blockchain Platform Enterprise Edition page, click Download and follow the steps to download the Oracle Blockchain Platform Enterprise Edition package. Extract the OVA image, obpee_21_1_2.ova, from the downloaded archive file.
  2. Import the VM into your virtual machine hosting software. For example, on Oracle VirtualBox, complete the following steps. For information about using VMWare ESXi, see Load Oracle Blockchain Platform Enterprise Edition on VMWare ESXi.
    1. Select File then Import Appliance, and browse to the directory where the OVA has been extracted.
    2. On the Appliance settings page, you may check Reinitialize the MAC address of all network cards if you plan on running more than 1 VM in your setup. You can create multiple VMs by either importing the appliance multiple times, or cloning the VM immediately after it's imported. Click Import.
  3. After a few minutes, the VM will be displayed in the list of machines in VirtualBox Manager. Right-click on the VM and select Settings:
    1. Under System on the Motherboard tab, select Hardware Clock in UTC Time to ensure the guest VM and the host's clocks are consistent in terms of timezones.
    2. Under Network on the Adapter tab connected to the network you want the VM to be on, ensure Enable Network Adapter is selected, and select Bridged Adapter.

The VM is now ready to be used.

Load Oracle Blockchain Platform Enterprise Edition on VMWare ESXi

  1. In the VMWare ESXi navigator, select the Virtual Machines page, and then click Create / Register VM.
  2. Under Select creation type, select Deploy a virtual machine from an OVF or OVA file and then click Next.
  3. Enter a name for the virtual machine and select the blockchain package (OVA file) that you downloaded and then click Next.
  4. Accept the default values and click Next for the remaining pages.
  5. Click Finish, and then wait for the VM to be provisioned.
  6. Once the VM is running, open a console to the VM and log in using the default user name oracle and the default password Welcome1. You'll be prompted to change the password. After you change the password, log in again using the new password.
  7. To enable DHCP to obtain an IP address, use the sudo command to change to the root account and then complete the following steps:
    1. Copy the file /etc/sysconfig/network-scripts/ifcfg-enp0s3 to a new file in the same directory called ifcfg-ens160.
    2. Edit the ifcfg-ens160 file to change the adapter name from enp0s3 to ens160.
    3. Power off the VM.
    4. Change the network adapter type from E1000 to VMXNET 3.
  8. Power on the VM.

The VM is now ready to be used.

Expand the Available Space for the Ledger

Because the ledger and logs for Oracle Blockchain Platform are persistent, you need to expand the root volume to ensure you don't run out of space.

  1. Add a hard disk for the SCSI controller. In VirtualBox click Settings then select Storage. Add a new hard disk. The recommended file type is VHD (Virtual Hard Disk); select either fixed or extensible mode.
  2. Create the logical volume partition: 
    sudo fdisk -c -u /dev/sdb
    Enter the following subcommands sequentially: 
    n Create new partition Press 
p Choose primary partition use p
1 Choose 1 for the primary partition
after this press return key twice for max allocation
t Change the type
8e Change the partition type to Linux LVM
p Print the partition
w write the changes
  3. Create the new physical volume: 
    sudo pvcreate /dev/sdb1
  4. Restart the system.
  5. Verify the physical volume: 
    sudo pvs
PV         VG    Fmt  Attr PSize    PFree
/dev/sda2  vg00  lvm2 a--  96.66g   <25.41g
/dev/sdb1  vg00  lvm2 a--  <200.00g <200.00g
  6. Add /dev/sdb1 to vg00 to extend the size to get more space for expanding the logical volume: 
    sudo vgextend vg00 /dev/sdb1
  7. Check the size of the volume group: 
    sudo vgs
VG #PV #LV #SN Attr VSize VFree
vg00 2 5 0 wz-n <296.66g 225.40g
    In this example, 225.4 GB are free.
  8. Extend the size of the logical volume: 
    lvextend /dev/vg00/root -L+24G
    where 24G is the size you're by which you're extending the logical volume which can be modified as needed. To determine the maximum space it can be extended to, use the vgdisplay command to check the value for the Free PE / Size.
  9. After extending, resize the file system: 
    sudo resize2fs /dev/vg00/root\
  10. Check the logical volume: 
    /dev/vg00/root
df -h
/dev/mapper/vg00-root 194G 18G 169G 10% /

Start Oracle Blockchain Platform

Once your network and sytem settings are configured, start the VM by selecting it and clicking Start. It should start within a minute.

Once the VM has started, hit the Enter key to get a login prompt.

Update Your Docker Root CA Certificate

The Docker root CA certificates included with Oracle Blockchain Platform Enterprise Edition must be updated on each of the Oracle Blockchain Platform Enterprise Edition virtual machines.

To update your certificates:
  1. On one of your Oracle Blockchain Platform Enterprise Edition VMs, create a folder /u01/renewCerts/docker-certs.
  2. Go to this folder and run the following commands to generate new certificates:
    openssl genrsa -aes256 -passout pass:example -out rootCA.key 4096 
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 3650 -out rootCA.crt -subj "/C=US/ST=CA/L=RedwoodShores/O=Oracle/OU=/CN=oracle.com" -passin pass:example
    The above commands will generate:
    • rootCA.crt
    • rootCA.key
    in /u01/renewCerts/docker-certs. These files will be used to update all VMs of all your Blockchain Platform instances.
  3. Check the ownership of the two files. It should be set as root:root. If not, change the ownership.
  4. Copy the rootCA.crt and rootCA.key files generated in step 2 to all the Oracle Blockchain Platform Enterprise Edition VMs of all instances, in a folder under /u01.
    For consistency, you can create a folder path /u01/renewCerts/docker-certs on each of the VMs and copy the files to this folder.
  5. For each of the Oracle Blockchain Platform Enterprise Edition VMs of all instances do the following:
    1. Backup the existing root CA certificate files to /u01/renewCerts/:
      cp /etc/docker/ssl/rootCA.crt /u01/renewCerts/rootCA-orig.crt
cp /etc/docker/ssl/rootCA.key /u01/renewCerts/rootCA-orig.key
    2. Copy the newly generated rootCA.crt and rootCA.key to /etc/docker/ssl.
    3. Verify that the files rootCA.crt and rootCA.key in/etc/docker/ssl are the new files.
    4. Restart the VM.

      Note:

      The same rootCA.crt and rootCA.key files generated in step 2 must be copied to each Oracle Blockchain Platform Enterprise Edition VM.

Update Your OpenLDAP and Blockchain Platform Manager Certificates

The OpenLDAP and Blockchain Plaform Manager certificates that are included with Oracle Blockchain Platform Enterprise Edition must be updated on each of the Oracle Blockchain Platform Enterprise Edition virtual machines.

Before you update the OpenLDAP and Blockchain Platform Manager certificates, update the Docker root CA certificate. The following script relies on artifacts that are created when you update the Docker root CA certificate.

To update the OpenLDAP and Blockchain Platform Manager certificates, run the following script from a command prompt:

#!/bin/bash

echo "OBPEE 21.1.2 Cert provisioning script"

newRootCACertPath='/u01/renewCerts/docker-certs/rootCA.crt'
newRootCAKeyPath='/u01/renewCerts/docker-certs/rootCA.key'

cpRootCACert='/u01/blockchain/cp/certs/rootCA.crt'
cpRootCAKey='/u01/blockchain/cp/certs/rootCA.key'

registryRootCACert='/u01/blockchain/registry/certs/rootCA.crt'
registryRootCAKey='/u01/blockchain/registry/certs/rootCA.key'

cpid=$(docker ps | grep 'controlplane' | awk '{ print $1 }')
echo "CP container ID -> $cpid"

ldapid=$(docker ps | grep 'openldap' | awk '{ print $1 }')
echo "OpenLDAP container ID -> $ldapid"

if [ -z "$ldapid" ] || [ -z "$cpid" ]; then
  echo 'ERROR: Failed to detect running containers. Abort.'
  exit        
else
  echo "Openldap and CP containers are running."
fi

if [ ! -f $newRootCACertPath ] || [ ! -f $newRootCAKeyPath ]; then
    echo "Error: New RootCA cert and/or key not found. Abort."
    exit
else
    echo "New RootCA cert and key detected."   
fi

#### CP changes ####

	#Backup existing image
	docker tag bcs/control-plane:latest bcs/control-plane:latest_bk

	#Modify existing image
	docker cp $newRootCACertPath ${cpid}:/tmp/rootCA.crt
	docker exec -it ${cpid} bash -c "keytool -import -trustcacerts -keystore /usr/lib/jvm/jre/lib/security/cacerts -storepass changeit -alias defaultOpenLdapCACert2022 -import -file /tmp/rootCA.crt -noprompt"

	#Commit image
	docker commit ${cpid} bcs/control-plane:latest

	#Backup existing cert and key
	cp -f $cpRootCACert ${cpRootCACert}.old
	cp -f $cpRootCAKey ${cpRootCAKey}.old

	#Replace new cert and key
	cp -f $newRootCACertPath ${cpRootCACert}
	cp -f $newRootCAKeyPath ${cpRootCAKey}

	#Restart
	echo "Restarting controlplane service"
	systemctl restart controlplane

#### OpenLDAP changes ####

	#Backup existing image
	docker tag obp/ol-openldap:latest obp/ol-openldap:latest_bk

	docker cp $newRootCACertPath ${ldapid}:/tmp/rootCA.crt
	docker cp $newRootCAKeyPath ${ldapid}:/tmp/rootCA.key

	docker exec -it ${ldapid} bash -c "cp -f /tmp/rootCA.crt /etc/ssl/certs/ca_server.pem"

	#Commit image
	docker commit $ldapid obp/ol-openldap:latest

	#Restart
	echo "Restarting OpenLDAP service"
	systemctl restart openldap

#### Registry changes ####

	#Backup existing cert and key
	cp -f $registryRootCACert ${registryRootCACert}.old
	cp -f $registryRootCAKey ${registryRootCAKey}.old

	#Replace new cert and key
	cp -f $newRootCACertPath $registryRootCACert
	cp -f $newRootCAKeyPath $registryRootCAKey

	#Restart
	echo "Restarting registry service"
	systemctl restart dregistry

echo "Successfully completed cert renewals"

Log on to Oracle Blockchain Platform for the First Time

After you've deployed and started Oracle Blockchain Platform Enterprise Edition on your VM hosting software, you can log on to Blockchain Platform Manager to create an instance.

You can directly log on to the Platform Manager by using the URL:
https://<hostname of your VM>:7443/console/index.html
The initial user name is obpadmin and the password is welcome1. This user is only meant for performing initial configuration and does not have instance creation privileges.

In order to use the internal LDAP server, the admin password must first be changed. Blockchain Platform Manager will not allow you to use an internal LDAP configuration with the default password.

Set the Blockchain Platform Manager Name

On the Configuration page Platform Settings tab of Blockchain Platform Manager, you can set a name for the Platform Manager.

Note:

Once the name for the Platform Manager has been set, any users added to the LDAP server will be associated with this name. If you change the name after adding users, those users will lose access to Blockchain Platform Manager and any Oracle Blockchain Platform instances.

Set the Notification and Console Idle Timeouts

On the Configuration page Platform Settings tab of Blockchain Platform Manager, you can set the timeouts for notifications and the console.
  • Console Idle Timeout: in minutes, how long the console can be idle before it logs out the current user.
  • Notification Timeout: in seconds, how long notifications will remain visible on the browser. Select -1 if you want notifications to remain visible until you close them.

Configure a Hardware Security Module Client

Oracle Blockchain Platform Enterprise Edition support using a hardware security module (HSM) to manage keys. You can use an HSM server on your network or a data protection on-demand (DPoD) service.

To use an HSM, you must install client software on each virtual machine (VM). Currently SafeNet Luna HSMs are supported.

You can configure an instance to use a HSM only when the instance is created. You cannot add HSM capabilities to existing instance.

Install the Client for SafeNet Luna Network HSM Devices

A script is provided in the virtual machine (VM) to assist with installing and configuring the SafeNet Luna Client for use with a hardware security module (HSM).

Prerequisites
  • The script supports version 10.2 and later of the SafeNet Luna Client.
  • The script is for use with SafeNet Luna Network HSM devices, not the SafeNet Luna HSM on Demand service.
  • The script is written to use the standard naming and folder structure for the client installer. If you change the location or file name of the client installer, the script might fail.
  • The script must be run using root privileges.
  • The script must be run after the host name and IP address for the VM are configured. If you change the host name or IP address after installing the client, you might need to reconfigure the client.
  1. To install and configure the SafeNet Luna Client, enter the following command: configureLunaClient.sh installConfigure client_installer_tar_file_full_path luna_server_ip_or_fqdn luna_server_ssh_port luna_server_username partition_name luna_ntls_port
    For example, enter the following command: configureLunaClient.sh installConfigure /UC_Installer.tar MyServer.example.com 22 admin MyPartition 1792
  2. To configure the SafeNet Luna Client to work with an additional server or a different partition, enter the following command: configureLunaClient.sh configure luna_server_ip_or_fqdn luna_server_ssh_port luna_server_username partition_name luna_ntls_port
    For example, enter the following command to add MyPartition2: configureLunaClient.sh configure MyServer.example.com 22 admin MyPartition2 1792

Manually Install the Client for SafeNet Luna Network HSM Devices

If you need more control over installation of the SafeNet Luna client than the provided script affords, you can install the client manually.

Prerequisites
  • The SafeNet Luna Network HSM is set up and the client archive is downloaded to the host computer.
  • You must have sudo privileges on the host computer.
  1. Copy the client .tar file to a directory and then enter the following command to extract the archive: tar xvf client_archive_file.
  2. Navigate to either the 32 or 64 directory, depending on your operating system.
  3. Run the install.sh script to install the client. To install all components, enter the following command: sudo sh install.sh.
    You are prompted to accept a license agreement when the installation script runs.
  4. From the list of products, press 1 to select Luna Network HSM, and then press Enter.
  5. Press N and then Enter to advance to the Advanced menu.
  6. In the Advanced menu, press 1, 2, and 3 to select Luna SDK, Luna JSP (Java), and Luna JCProv (Java), and then press Enter.
  7. Press I and then Enter to install the components.
  8. To add the SafeNet Luna client to the system path, add the following lines to the system's .bash_profile file:
    export PATH="$PATH:/usr/safenet/lunaclient/bin"
export PATH="$PATH:/usr/safenet/lunaclient/sbin"
After you install and configure the SafeNet Luna client on each VM, run the following commands from the LunaCM command prompt, one time only to initialize the partition and to set up roles. In the following sequence of commands, you are prompted for the partition domain name, and you are prompted to set and change the passwords for the Partition SO (security officer), Crypto Officer, and Crypto User roles. 
partition init -label fabric
role login -name Partition SO
role init -name Crypto Officer
role logout
role login -name Crypto Officer
role changepw -name Crypto Officer
role init -name Crypto User
role logout
role login -name Crypto User
role changepw -name Crypto User

Install the Client for SafeNet Luna HSM on Demand

To use the SafeNet Luna HSM on Demand service to manage keys, you download a pre-configured SafeNet Luna client archive and extract it on each virtual machine (VM) in the instance.

Prerequisites
  • The SafeNet Luna HSM on Demand service is set up and the client archive is downloaded to the host computer.
  • The client installation directory must be under the /etc/hyperledger/fabric path.
  • You must have sudo privileges on the host computer.
  1. Enter the following command to create the installation directory: sudo mkdir -p /etc/hyperledger/fabric/dpod/fabric.
  2. Extract the setup-fabric.zip archive file to the /etc/hyperledger/fabric/dpod/fabric directory.
  3. In the /etc/hyperledger/fabric/dpod/fabric directory, enter the following command to extract the cvclient-min.tar file: tar xvf cvclient-min.tar.
  4. Enter the following command to create a configuration file: source ./setenv.
    If the command does not run because of a permissions issue, change the folder permissions to 777 and then retry the command.
  5. Enter the following command to set the ChrystokiConfigurationPath environment variable to the location of the configuration file: export ChrystokiConfigurationPath=/etc/hyperledger/fabric/dpod/fabric.
  6. In the REST section of the file, add the following line: ClientProxy = restproxy.example.com:80; where restproxy.example.com is the host name of the REST proxy.
  7. Enter the following commands to start the Luna client:
    sudo bash
source ./setenv
export LC_ALL=C; unset LANGUAGE
./bin/64/lunacm
    The LunaCM command prompt is displayed.
  8. Complete the previous steps for all VMs in the instance where you plan to use the SafeNet Luna HSM on Demand service.
After you install and configure the SafeNet Luna client on each VM, run the following commands from the LunaCM command prompt, one time only to initialize the partition and to set up roles. In the following sequence of commands, you are prompted for the partition domain name, and you are prompted to set and change the passwords for the Partition SO (security officer), Crypto Officer, and Crypto User roles. 
partition init -label fabric
role login -name Partition SO
role init -name Crypto Officer
role logout
role login -name Crypto Officer
role changepw -name Crypto Officer
role init -name Crypto User
role logout
role login -name Crypto User
role changepw -name Crypto User