drawing

Tech5-nxGen MBAP Admin Guide (Linux Version)

Version 1.0

This document explains the procedure of installing, deploying and managing the T5-nxGen MBAP

Disclaimers

The information contained in this document is the proprietary and exclusive property of Tech5 except as otherwise indicated. No part of this document, in whole or in part, maybe reproduced, stored, transmitted, or used for design purposes without the prior written permission of Tech5.
The information contained in this document is subject to change without notice. The information in this document is provided for informational purposes only. Tech5 specifically disclaims all warranties, express or limited, including, but not limited, to the implied warranties of merchantability and fitness for a particular purpose, except as provided for in a separate software license agreement.

Privacy Information

This document may contain information of a sensitive nature. This information should not be given to persons other than those who are involved in the T5-MBAP or who will become involved during the life cycle.
Contact : support@tech5-sa.com

Table of contents

  1. Overview
    1.1. Introduction
    1.2. T5-MBAP Overview
    1.3. MBAP Components OverView
    1.3.1. MBAP Components Description

  2. Installation Procedure
    2.1. MBAP Prerequisites
    2.2. Java Installation steps
    2.3. T5 Biometric SDKs Installation
    2.3.1. Face SDK
    2.3.1.1. Dependencies Installation
    2.3.1.2. FaceSDK Installation
    2.3.1.3. License request generation
    2.4. T5 MBAP Installation
    2.4.1. MBAP Software Download
    2.4.2. MBAP Configuration
    2.4.3. MBAP Startup

  3. Testing MBAP Application
    3.1. Testing Procedure using Java CLI utility
    3.2. Testing Procedure using .Net GUI utility

1. Overview

1.1. Introduction

This document is intended to be consumed by Administrators and DevOps teams. They should be able to install all the necessary dependencies and components required for deploying Tech5’s MBAP.

MBAP is Multi Biometric Authentication Platform primarily designed for a highly efficient and scalable 1:1 search engine.

1.2. T5-MBAP Overview

overview

1.3. MBAP Components Overview

This is an authentication platform of all three Biometric modalities like Face, Finger & Iris. MBAP is designed to do Authentication/Verification of any or all three modalities. It works with the cache db files that are generated by the T5-MBAP Search Engine. All the data enrolled in T5-ABIS Cache can be Verified using MBAP(when used with T5-ABIS). If T5-MBAP is used as individual component, you can enroll & verify records.

1.3.1. MBAP Components Description:

  1. Gallery : Gallery is a collection of all the identities (people) that can be search using a single biometric modality. Gallery is a logical container and can be distributed over multiple physical nodes.
  2. Master cluster: Its job is to orchestrate the enrollment and search transactions. Itsends enrollment transactions to all open sets of respective modality. It splits search transactions and sends them to appropriate group or sets and combines results from partitions to form one consolidated result from the entire gallery.
  3. Cache: The templates are stored in a cache file on the local disk. Currently we use SQLite DB to store the ID number and associated biometric template. On cold starts templates are loaded into RAM from this SQLite DB called as cache.
  4. Template Creator: These nodes load Tech5 biometrics technologies SDK to create templates and return quality scores. Each node loads only one technology to avoid disruption in services due to other technology failures. These are stateless nodes and thus can be configured for auto recovery and automatic scaling.

2. Installation Procedure

2.1. MBAP Prerequisites

2.2. Java Installation steps

Check which version of Java is running on the servers:

 # java -version

If Java is not installed, proceed and download Java software. We should unlink OpenJDK before installing SunJDK.

 # java -version
      openjdk version "1.8.0_191"
      OpenJDK Runtime Environment (build 1.8.0_191-b12)
      OpenJDK 64-Bit Server VM (build 25.191-b12, mixed mode)

Unlink OpenJDK from /usr/bin/java as shown below:

# whereis java
      java: /usr/bin/java /usr/lib/java /etc/java /usr/share/java/usr/share/man/man1/java.1.gz
# unlink /usr/bin/java

Now please download Java Runtime Environment and install it as shown below:

# cd /tmp
# curl -L -b "oraclelicense=1" https://javadl.oracle.com/webapps/download/AutoDL?BundleId=241525_1f5b5a70bf22433b84d0e960903adac8 --output jre_1.8.rpm
# rpm -ivh jre_1.8.rpm

After installation is successful, check the version to make sure the right version is installed:

#java -version
    java version "1.8.0_241"
    Java(TM) SE Runtime Environment (build 1.8.0_241-b07)
    Java HotSpot(TM) 64-Bit Server VM (build 25.241-b07, mixed mode)

2.3. T5 Biometric SDKs Installation

Following dependencies of Face SDK should be installed.

2.3.1. Face SDK

2.3.1.1. Dependencies Installation:

Following packages are required for the FaceSDK to and should be installed on all the nodes on which Face modality will be configured.
opencv
openblas-serial
lapack
libgomp
boost-system
boost-filesystem
boost-program-options

All the packages are available in EPEL and Default packages if you are using CentOS.Incase of RHEL, rhel-7-server-optional-rpms and epel must be activated on Repo list.

Installation steps
$ yum -y install epel-release && yum install -y opencv openblas-serial lapack libgomp
boost-system boost-filesystem boost-program-options
#yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

2.3.1.2. FaceSDK Installation steps

Download the FaceSDK RPMs

Download FaceSDK component from the URL and credentials specified in the email.

Lets create a directory and download software to it.

# mkdir /opt/Tech5 /opt/Tech5/software
# cd /opt/Tech5/software/
# wget --ask-password <ftp link provided to you>/*

Once the RPMs are downloaded, use the script to install all these RPMs one by one as shown:

#cat InstallFaceRPMs.sh
yum -y localinstall tech5-face_sdk-cpu-1.6-0.x86_64.rpm
yum -y localinstall tech5-face_sdk-cpu-devel-1.6-0.x86_64.rpm
yum -y localinstall tech5-face_sdk-age_gender_100-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-alignment_100-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-alignment_101-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-alignment_102-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-alignment_103-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-builder_100-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-builder_101-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-builder_102-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-builder_103-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-builder_104-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-face_detector_100-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-face_detector_101-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-face_detector_102-1.6-0.noarch.rpm
yum -y localinstall tech5-face_sdk-face_detector_103-1.6-0.noarch.rpm

After the installation of above packages is complete, you should be able to see if the version of below:

# face_sdk_utils --version
Face SDK utils. Version 1.6 Mozart(664754b94f8ba0db1b9498f0d6086326c9c7e1ca)

It confirms that Face SDK version 1.6 is installed successfully.

2.3.1.3. License request generation

Run the below command to generate License request for FaceSDK and send it to Tech5 team,they will send the license file:
(Replace CompanyName with your Company or Project & WinComputer01 with the hostname of your machine/server)

# /usr/bin/face_sdk_utils --request --out $HOME/<YourCompany-or-ProjectName>face_sdk.req

We will send the face_sdk.lic file and that has to be copied into the folder /usr/share/face_sdk.

Note:
face_sdk_utils script requires read access to product_uuid attribute on device dmi/id (usually it is this /sys/devices/virtual/dmi/id/product_uuid file) for the util to work without errors.

2.4. T5 MBAP Installation

2.4.1. MBAP Software Download

Download Software:

Get the copy of T5-MBAP software from the URL and credentials specified in the email.

Download the software to Tech5 folder in /opt partition. This has to be done on all the servers where ever MBAP will be running.

Create T5-MBAP Directory then Extract the tar file

# cd /opt/Tech5/software/
# wget --ask-password <ftp link provided to you for MBAP>
# mkdir /opt/Tech5/T5-MBAP
# tar xvf abc*.tar -C /optTech5/T5-MBAP --strip-components=1

This will extract all the MBAP containers to /opt/Tech5/T5-MBAP folder. Now we should create a cache folder(if it does not exists). Cache folder will be used to store Face/Iris/Finger cache.

# mkdir /opt/Tech5/T5-MBAP/cache

In “/etc/hosts” each modality will have a Matcher container and Template Container and one Master container. If you are running all this on a single high-compute server, then we can start all Modalities including Master in the same server. However, if you want to distribute MBAP components among multiple servers, then copy appropriate containers to each server depending on your design.

You can leave the appropriate folder and delete the other folders on each server. Like on Master server delete FaceTC, FaceM and other containers if exists. And same way in Face Matcher container, you can delete Master, FaceM and other containers and so on. General practice is to run each container on each server.

Get the IP addresses of the MBAP server. Then add the IP address and hostname of the host in the “/etc/hosts” file as shown in the below example:

Example of /etc/hosts file:

# cat /etc/hosts
####### Master, DB and BMW Nodes ##########
192.168.234.2 rac1-c3-b01-master01
192.168.234.14 rac2-c3-b01-master02
192.168.234.26 rac3-c3-b01-master03
####### Face Nodes ######################
192.168.234.3 rac1-c3-b02-fmat01
192.168.234.15 rac2-c3-b02-ftc01

2.4.2. MBAP Configuration

You can skip this step, if you are running all modules on a single high-compute server

In all the MBAP servers, we should edit the configuration files and add the actual host IP address of same server. Each MBAP server node will multicast the self IP address and other node will get connected to it.

In the Master configuration file, you should change the same value to the actual Master’s host IP addresses:
( Master configuration file: “/opt/Tech5/T5-MBAP/Master/conf/mbap-nextgen.xml”)

<property name="addresses">
	<list> 
		<value>192.168.1.100:47500..47509</value>
	</list>
</property>

In the FaceTC configuration file, you should change the same value to the actual FaceTC’s host IP addresses:
( FaceTC configuration file: “/opt/Tech5/T5-MBAP/FaceTC/conf/mbap-nextgen.xml”)

<property name="addresses">
	<list> 
		<value>192.168.1.101:47500..47509</value>
	</list>
</property>	

In the similar way we should change the IP address in FaceM
( FaceM configuration file: “/opt/Tech5/T5-MBAP/FaceM/conf/mbap-nextgen.xml”)

<property name="addresses">
	<list> 
		<value>192.168.1.102:47500..47509</value>
	</list>
</property>
... 

Once all these configurations files are updated,  we can go-ahead and start the services and check the logs to see if there are any issues during the startup of services.

2.4.3. MBAP Startup

After editing the above configuration files mapping to the correct IP address and the cache folder, now run below commands to start the services on each server.

Starting the services

Before starting the services we should export the LD Library paths and Native folder path of MBAP application like this:

# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/:/usr/lib64/:/usr/lib/:/usr/local/lib64/:/opt/Tech5/T5-MBAP/native:

Step1: Starting Master Service

In the command terminal go to Master Service path and start the Master Service.

# cd /opt/Tech5/T5-MBAP/Master/bin
# sh startMaster.sh start

Check the Logs in the

# tail -f /opt/Tech5/T5-MBAP/Master/bin/T5-MBAP-NextGen.log

If all good, the service starts without any error message and it says “Application Tech5-MBAP-NextGen initialized successfully”, let’s move on to start the Face Template Creator services.

Step2: Starting FaceTC Service

In the command terminal go to FaceTC Service path and start the FaceTC Service.

# cd /opt/Tech5/T5-MBAP/FaceTC/bin
# sh startMaster.sh start

Check the Logs in the

# tail -f /opt/Tech5/T5-MBAP/FaceTC/bin/T5-MBAP-NextGen.log

If all good, template creator service starts without any error message and it says “Application Tech5-MBAP-NextGen initialized successfully”, lets start Face matcher service now.

Step3: Starting FaceM Service

In the command terminal go to FaceM Service path and start the FaceM Service.

# cd /opt/Tech5/T5-MBAP/FaceM/bin
# sh startMaster.sh start

Check the Logs in the

# tail -f /opt/Tech5/T5-MBAP/FaceM/bin/T5-MBAP-NextGen.log

If all good, the matcher service starts without any error message and it says “Application Tech5-MBAP-NextGen initialized successfully”. As we have started all the components, we can go-ahead and check the status page in below URL: :

	http://<serverIP>:9090/MBAP/V1/status

3.0. Testing MBAP Application

3.1. Testing Procedure using Java CLI utility

We are providing a sample application which can do basic functionality of Enroll/Verify records to test MBAP deployment. Sample application can be used in CLI and GUI.

GUI app is developed in .net and can be used in Windows. CLI is developed in Java and can be used in both Linux/Windows systems.

3.1.1. Download Utility:

Utility can be downloaded from the below URL:

http://hink.tech5.tech/share/Utils/nxGen-MBAP/nxGenMBA-TestUtil-V1.6.7.rar

Utility is written in Java and hence we can run it either on Windows or Linux machine where Java 8 or higher version is installed.

Also this utility has couple of parameters (explained below) and it can be customized according to our testing scenario and run it as needed.

3.1.2. Format of the Util

After configuration changes as shown in section 3.1.3, You can run utility by below command

# cd <Full path of Folder where Util and config files are copied>
# java -jar MBAPNG-TestUtil-V1.6.7.jar

Config file has the parameters which has to be changes depending on the requirement. Please read the config-readme file to understand how it can be changed.

MBAP Test tool CLI

3.1.3 Configuration Parameters

Param1:
sourceFolder =FolderPath
Path to the folder where Biometric Records are there which has to be enrolled or identified “E:\Tech5\Enroll-T5Tools\MBAPNG-TestUtil\Data\One”

Param2:
apiURL=http://facetcloud.tech5.tech:9090/MBAP/V1/
You need to provide your MBAP master server’s URL

Param3:
apiOperation=enroll/verify/delete/uidstatus/createtemplate/bio-bio

apiOperation=enroll --> This has to be used to enroll a record into MBAP.
apiOperation=verify --> This has to be used to verify a record that is enrolled in MBAP.
apiOperation=delete --> This has to be used to delete a record from MBAP.
apiOperation=bio-bio --> This has to be used to Match two Face Images.

Folders for bio-bio matching

probeFolder=E:\Tech5\Enroll-T5Tools\MBAPNG-TestUtil\Data\Probe
galleryFolder=E:\Tech5\Enroll-T5Tools\MBAPNG-TestUtil\Data\Gallery

Param4:
writeTemplates =true/false
We can create templates to disk by setting this to True.

Param5:
templatesFolder= FolderPath
Specify location to write folders to “E:\Tech5\Enroll-T5Tools\MBAPNG-TestUtil\Data\Templates”

Param6:
inputType= Images/Templates as input

Param7:
isFinger=true
We can mark this as True if you want to include Finger in your current operation

Param8:
isFace=true
We can mark this as True if you want to include Face in your current operation.

Param9:
isIris=true
We can mark this as True if you want to include Iris in your current operation.

Param10:
irisThreshold = 0.5
Ideally this threshold has to be set depending on the data set that we are running MBAP on.

Param11:
face Threshold = 8.0
Ideally this threshold has to be set depending on the data set that we are running MBAP on.

Param12:
fingerThreshold = 0.2
Ideally this threshold has to be set depending on the data set that we are running MBAP on.

3.2 Testing Procedure using .Net GUI utility

This is a GUI .net Utility and it can be downloaded from :

http://hink.tech5.tech/share/Utils/nxGen-MBAP/nxGenMBAP-GUI-AuthTool2.4.1.rar

GUI utility looks like this:

MBAP Test tool GUI

You should be able to Enroll/Verify from this utility by pointing to your MBAP server’s IP from the confiruration file : “mBAP.AuthTestTool.exe.config” like this:

<appSettings>
	<add key="mbap" value="http://facetcloud.tech5.tech:9090/MBAP/V1/"/>
</appSettings>

Please go-ahead and use these utilities and do let us know if you see any issues or send us an email.
Contact : support@tech5-sa.com

THANK YOU