drawing

Tech5-nxGen MBAP Admin Guide (Windows 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-ABIS 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 ABIS/MBAP cache as required.
  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

Download Java Runtime Environment and install Java as shown below:

    # https://www.oracle.com/java/technologies/javase-jre8-downloads.html

Select compatible version of JRE for your OS & install.

2.2.1 Now export Environment variables for java installation

  1. In Search, search for and then select: System (Control Panel)
  2. Click the Advanced system settings link.
  3. Click Environment Variables. In the section System Variables, find the PATH environment variable and select it. Click Edit. If the PATH environment variable does not exist, click New.
  4. In the Edit System Variable (or New System Variable) window, specify the value of the PATH environment variable. Click OK. Close all remaining windows by clicking OK.
  5. Reopen Command prompt window, and run java -version command.

After installation of JRE and exporting environment variable path check the Java version once again.

#java -version
java version "1.8.0_201"
Java(TM) SE Runtime Environment (build 1.8.0_201-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.201-b09, mixed mode)

2.3. T5 Biometric SDKs Installation

Following dependencies of Face/Finger/Iris SDKs depending on the modalities used should be installed.

2.3.1. Face SDK

2.3.1.1. FaceSDK Installation steps

Download the FaceSDK :

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

Lets create a directory and download software to it.

# Create Directory "C:\Program Files\Tech5\"
# Extract downloaded SDK archive to "C:\Program Files\Tech5\"
# Rename extracted folder to "face_sdk"

Folder Structure of Tech5 FaceSDK

Follow the Step 2.2.1 and export below environment variable path,

C:\Windows\System32;C:\Program Files\Tech5\face_sdk\lib;C:\Program Files\Tech5\face_sdk\bin;C:\Program Files\Tech5\face_sdk\share\face_sdk;C:\Program Files\Java\jdk1.8.0_241\bin;C:\Program Files\Tech5\T5-MBAP\FaceM\native;%FACE_SDK_BIN_ROOT%;%LD_LIBRARY_PATH%

Exporting Path

Exporting Path

After this, you should be able to run face sdk and see the version if all the PATHs and environmental variables set appropriately.
Open command promt, run below commands and check:

# face_sdk_utils --version
Face SDK utils. Version 1.6 XUXU(d350a6bf94c57d551ef00e724bfbd0bbcea4f8fc)

Face SDK version

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)

# face_sdk_utils --request --output CompanyName-WinComputer01.req

Please replace CompanyName with your company say XYZ & WinComputer01 with the hostname of your server something like MatchingNode01 and so your request file will be like XYZ-MatchingNode01.req

Face SDK License Request Generation

Please send us the license request file that is generated XYZ-MatchingNode01.req and we can issue the license file (face_sdk.lic).

The license file that you receive from Tech5 support team has to be copied to this location.

 C:\Program Files\Tech5\face_sdk\share\face_sdk

enter image description here

Note:
Once after copying the license file to above specified location, you can see the license details as shown in below screenshot… and if incase you see any errors, try these steps:

  1. Please close the command prompt window.
  2. Search for “Command prompt” from windows search bar, Right click on the “Command prompt” from the results list and choose “Run as administrator” option.
  3. This should open Common prompt as administrator account and then re-run license request commands.

Check Face SDK license Validity

2.4. T5 MBAP Installation step

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. This has to be done on all the servers where ever MBAP has to be installed.

# Create Directory "C:\Program Files\Tech5\T5-MBAP"
# Extract downloaded SDK archive to "C:\Program Files\Tech5\T5-MBAP"

NxGen MBAP Folder Structure

In “C:\Program Files\Tech5\T5-MBAP” each modality will have its own Apache Tomcat containers say Master, Template Creator & Matcher container. If you are running all these on a single high-compute server, then we can start all containers including Master in the same server. However, if you want to distribute MBAP components among multiple servers for different purposes like horizontal scaling or High Availability, 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 with enough resources to attain high throughput.

Get the IP addresses of the MBAP server. Then add the IP address and hostname of the host in the c:\Windows\System32\Drivers\etc\hosts file as shown in the below example:

Example of c:\Windows\System32\Drivers\etc\hosts:

# cat /etc/hosts
####### Master, DB and BMW Nodes ##########
192.168.1.98 rac1-c3-b01-master01
192.168.1.99 rac2-c3-b01-master02
192.168.1.100 rac3-c3-b01-master03
####### Face Nodes ######################
192.168.234.102 rac1-c3-b02-fmat01
192.168.234.101 rac2-c3-b02-ftc01

After editing the hosts file, you should be able to ping MBAP node using its hostname.

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: “C:\Program Files\Tech5\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: “C:\Program Files\Tech5\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: “C:\Program Files\Tech5\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

Start command prompt with administrator privileges, and run below commands to start the services on each server.

Starting the services

Step1: Starting Master Service

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

# cd C:\Program Files\Tech5\T5-MBAP\Master\bin
# startMaster.bat start

Start Master Service

Check the Logs in the

C:\Program Files\Tech5\T5-MBAP\Master\logs\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 prompt go to FaceTC Service path and start the FaceTC Service.

# cd C:\Program Files\Tech5\T5-MBAP\FaceTC\bin
# startFaceTC.bat start

Start FaceTC Service

Check the Logs in the

C:\Program Files\Tech5\T5-MBAP\FaceTC\logs\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 prompt go to FaceM Service path and start the FaceM Service.

# cd C:\Program Files\Tech5\T5-MBAP\FaceM\bin
# startFaceM.bat start

Start FaceM Service

Check the Logs in the

C:\Program Files\Tech5\T5-MBAP\FaceM\logs\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

This page shows you the information of all the connected instances in the MBAP cluster and their status information including the verison of MBAP etc.

3.0 Testing MBAP RestAPI

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