For your convenience, we provide an opportunity to monitor the Oz system behavior. The checklist below contains the monitoring recommendations: what to check and how to interpret results to ensure everything works well, and the system is ready to properly process your requests. To perform the check, you can use any monitoring system.

System Metrics

1. Ensure all servers are accessible. Use the ping command.

2. Check the free space on all disks. It should be 10% or more.

3. Check the RAM usage of your servers. It should be 90% or less.

Oz Internal Metrics

1. Check the accessibility of the oz-api services. Launch the health check by calling GET `/api/version`. The successful response returns code 200.

2. Check the accessibility of the oz-bio services. Call GET `/v1/models/inquisitor`. The successful response returns code 200.

3. Check if the oz-bio license is up-to-date. Execute the code below in your console:

curl -s -d '{"inputs": {"images_bytes": [{"b64": ""}]}}'  -X POST  http://localhost:8501/v1/models/inquisitor:predict | grep -c assertion

This code should return 1 in the console.

4. Check if there were any unusual delays in the last series of analyses. Execute the code below to get the 90 percentile delay value in seconds:

docker exec -i --user postgres oz-api-pg psql -X -A -t -d gateway -c "select percentile_disc(0.9) within group(order by date_part('epoch', time_updated-time_created)) from gw_analyse_abstract where time_updated > current_timestamp - interval '10 minutes'"

The result in your console should be lower than 20.

5. Check if the suspicious analyses queue is growing. Execute the code below to get the amount of unfinished analyses in the queue:

docker exec -i oz-api-rabbitmq rabbitmqctl list_queues | egrep -i '^tfss\s' | awk '{ print $2 }'

The result in your console should be lower than 20.

If anything doesn’t work as expected, please contact us at support@ozforensics.com.

Installation

• Contact us to get the docker image archive link and download the archive

• Load the image to docker: docker load -i <path to image tar file>

• Run docker: docker run -p {port}:80 -t ozforensics/oz-api-lite:{tag}

Main Parameters

The parameters are set by environment variables when starting the Docker container.

The following parameters are valid:

• NUM_WORKERS – maximum for the analyses performing at once; might be different in different cases. Default: 16.

• TF_ENABLE_ONEDNN_OPTS – used for acceleration. Default: 1, for AMD processors, set 0.

Usage

Interaction with the biometric processor is based on the REST API. The HTTPS protocol is used.

API Access Point

API access base URL: https://{hostname}/v1/face/pattern or https://{hostname}/v1/face/liveness depending on method (please refer to Oz API Lite methods).

Where:

• {hostname} – the hostname and port of the deployed biometric processor server.

Example: localhost/v1/face/pattern

The API supports the following request content types ("Content-Type" HTTP header):

• «multipart/form-data»;

• «application/octet-stream»;

• «image/jpeg» or «image/png»;

HTTP Response Codes

this part covers the installation of Oz modules: both full and lite versions.

Oz Liveness WEB Adapter is set up via changes in the configuration file stored at the Oz Liveness WEB Adapter server: /core/app_config.json

Please find a sample for Oz Liveness Web SDK here. To make it work, replace <web-adapter-url> with the Web Adapter URL you've received from us.

For Angular and React, replace https://web-sdk.sandbox.ozforensics.com in index.html.

• Angular sample

• React sample

What Is Standalone Installer

The standalone installer is a software made to install all Oz Forensics modules to customers servers, performing all required settings related to personal topology and customer requirements.

This installer is intended to deploy the software to servers directly, under the server administration user account. The direct access to the Internet can be provided or not (with some notes). Linux OS should be preinstalled with the ability to connect with full access via SSH.

For installation to OpenShift and other orchestrators, please .

Prerequisites

Server Requirements

Oz Biometry / Liveness Server

• CPU: 16 cores

• RAM: 32 GB

• Disk: 80 GB

Oz API / Web UI / Web SDK Server

• CPU: 8 cores

• RAM: 16 GB

• Disk: 300 GB

Please check the OS version with our team.

Kubernetes (K8s) Requirements

Kubernetes version: 1.27.

Mandatory components:

• Prometheus (Helm chart version (kube-prometheus-stack) – 45.7.1),

• ClusterIssuers.

Optional components:

• Any Storage Class that supports the ReadWriteMany (RWX) mode.

Node resources’ requirements:

• CPU Architecture: Intel

Preparation

1. Request a list of clients’ URLs and the corresponding SSL certificates.

2. Check that all servers are accessible via the local network.

3. Check that access is allowed either via SSH with authorization by password or by key file and sudo without password.

4. For the installation, we recommend Docker or Podman. Alternatively, you need the Internet to download and install Docker or Podman automatically.

   or
6. Check the availability of license service by address https://api.cryptlex.com for servers. The client’s firewall should be opened for this address.

7. Check that AVX flags for CPU on BIO host are supported. To verify this, run the lscpu | grep -E 'avx256|avx512' | wc -l command. The response should be 1.

8. The client’s firewall should not block:

   • any running scripts or binary image supplied;

   • any local ports for the processes’ intercommunication (docker networks: 192.168.0.1/24, 192.168.10.0/24, 192.168.11.0/24, 192.168.12.0/24, 192.168.13.0/24);

   • ports 80, 8000, 8080, 8090 on the API server and port 8091 on the BIO server;

   • port 5432 for the additional Postgres installations.

Please be ready to terminate the HTTPS connection and decrypt the traffic before forwarding it to the API server. This is typically done by a firewall or other security device.

It is important that you warn our team about all non-typical and/or non-official software or services preinstalled on the host servers.

How to Get the Installer

Trial bundle

You can order a trial bundle for free. For this bundle, you'll need two servers meeting system requirements listed above.

How to Run the Installer

To run the installer, you need any machine with Windows or Linux matching the following system requirements:

• 1 GB RAM, 1 CPU, 3 GB hard drive

• Windows 10+ (recommended)

• Linux 64 bit (Python 3.7 is required)

Prepare the Installer

Download and unpack your personal installer bundle.

Put the required configuration to the settings.yml file. The most important settings are described below. Usually, it is only required to fill the authorization and variables sections.

Please note: the configuration file is your personal copy, sharing it with any 3rd side is prohibited.

Settings

Running

Run the command prompt with administrator's rights. Use the cd command to go to the folder where the unzipped installer is located. Launch the installation.

Windows:

Linux:

Optional parameters:

• filename – filename with settings ('settings.yml' by default)

• private_key – a path to the private SSH key (overwrites the appropriate option from settings file)

• key_password – password to SSH key (if not specified, the system will ask to enter it in the console)

• ssh_password – password for SSH login

• debug – generate additional logging information for support

Usage example:

Troubleshooting

Every step of the installer echoes information to process.log. To report any installation issues, please, attach that file to your ticket.

Use the Putty ppk File for Connection

You need to extract the private part of the key and then specify the path to that file in section auth -> ssh_private_key

docker-compose: Command Not Found

This error could arise when the docker-compose tool was installed independently before the installer and default binary was set to /usr/local/bin

For the correct work of the installer, please, make a symbolic link:

Some configuration file parameters can be changed without direct editing of the /core/app_config.json file. You can do it using the environment variables.

• WA_ARCHITECTURE – redefines the architecture parameter

• WA_API_URL – redefines the api_url parameter

Here's an example of using environment variables for the dockered Web SDK in the Lite mode:

Oz Forensics provides flexible licensing rules for all products. To support licensing for servers without an Internet connection, you need to install an offline license server.

How to Install an Offline Licensing Server

1. Unpack the Software

2. Install the License Service

The installation is complete. For the next steps, use the Web interface on port 8090.

3. Activate the License

Open the default page in your Web browser http://server:8090 and authorize with your login and password.

Go to theSettings section.

Online activation

The easiest way to activate the license server is via the Internet. Enter the license key and click ACTIVATE.

Offline activation

If your server isn't connected to the Internet, use the offline activation option. Click the SWITCH TO OFFLINE ACTIVATION link.

Enter the license key and hit NEXT.

ClickDOWNLOAD REQUEST FILE.

Enter the activation code in the offline activation response window and hit ACTIVATE.

Activate modules

Oz Api Lite

Add an extra command line parameter with the LICENSE_KEY environment variable with license server host address and port.

Oz Bio

Create the license.key file with the content of license host and IP and bind this file to your container:

This part covers the containing of the /core/app_config.json file.

• use_for_liveness – the option is used when bank managers are taking clients' videos. If the option is set to true, mobile devices use the back camera by default, and on desktop, flip and oval circling are off.

• preinit – this optional parameter switches on the preliminary loading of scripts and face detection initialization. This is needed to reduce the plugin loading time. The default value is off that means all the scripts are loaded after calling OzLiveness.open(). The script value means that the scripts will be loaded before the plugin launches. The full value enables preliminary loading of scripts and face detection initialization.

• architecture – this optional parameter is used to choose the architecture for Web SDK. The default value is normal.

  • normal is used for the full Oz API version;

  • lite is used for API Lite;

  • capture is used for the mode that aims to work directly with client backend. In this mode, Oz Liveness Web Plugin can be distributed via static files only (without the adapter part; implemented in 0.7.4);

• api_url – Oz API server address, a text parameter;

• api_token – Oz API access token, a text parameter;

• api_use_token – a parameter to specify the source of the Oz API access token for the system. Possible values = config, client.

  • If the parameter value is client, then an Oz API access token is expected to be derived from the JS plug-in;

  • If you specify config in this parameter, a token will be retrieved from the api_token parameter of the Oz Liveness Web Adapter configuration file.

• video_actions_list – block of video file tags used in the system, a text array. Current tag list.

• photo_actions_list – block of photo file tags used in the system, a text array. Current tag list.

• actions_default_importance – this parameter specifies whether override with an actions array from a web plug-in is allowed at launching an analysis. Possible values = true, false;

  • If true, the Adapter will use an actions array from the configuration file.

  • If false, the Adapter will use an actions array forwarded from your browser with the use of the open(options) method.

• actions_default – the actions array. Options include:

  • video_count – the number of transmitted video files, a numeric parameter;

  • photo_front – whether there is a front-side page in the document. Possible values = true, false;

  • photo_back – whether there is a back-side page in the document. Possible values = true, false.

• analyses – a block for configuring the launch of analyses. Options include:

  • quality – launch of Oz Liveness analysis. Possible values = true, false;

  • biometry – launch of Oz Biometry analysis. Possible values = true, false;

  • documents – launch of Oz Text analysis. Possible values = true, false;

  • collection_ids (since 1.4.0) – an array of the identifiers of collections for the Black List analysis.

• extract_best_shot – a parameter that specifies if a direct link to the best shot (bestshot) extracted from the video should be appended to the analysis result. Possible values = true, false. If true, the response will contain a link to the extracted image inoutput_images (results_media);

• result_mode – a parameter that specifies the contents of the server response with verification results. Possible values:

  • safe– only the state of analyses is returned (completed or not yet);

  • status– results of completed analyses are returned;

  • folder – same as status but with folder identifier added;

  • full– full Oz API response on the analyses is returned in the JSON format.

• result_codes– a block of response codes with annotations.

• delete_old_sessions: true, false– whether you want to delete old sessions

• delete_old_sessions_offset_minutes: ***– old sessions deletion time offset (in minutes)

• video_required_actions_list– the array of required actions

"video_required_actions_list":
[
  "video_selfie_smile"
],

• save_lossless_frame: true– saving the original frame without compression

• video_file_format – optional; here you can choose the video file format. This video file is passed to the api. Possible values: zip (recommended) and mov (less secure). If you need to retrieve your captured video in the MP4 format, please find the instructions here.

• debug (since 1.1.0) – if true, enables access to the /debug.php page, which contains information about the current configuration and the current license.

• load_3d_mask (since 1.2.1) – if true, loads the model to process the video taken with the 3D mask functionality. The default value is false which means that the model is not used, and the 3D mask is unavailable (the enable_3d_mask parameter is being ignored).

• enable_3d_mask (since 1.2.1) – enables the 3D mask as the default face capture behavior. This parameter works only if load_3d_mask is set to true; the default value is false.

• master_license_signature (since 1.3.1) – the parameter for the master license signature; the default value is null.

• results_polling_interval (since 1.4.0) – the interval for polling for the analyses’ results in ms; the default value is 1000.

• get_user_media_timeout (since 1.5.0) – it defines camera access timeout in sec; after this timeout it displays a hint on how to solve the problem; default_default for all browsers and android_facebook for Facebook

"get_user_media_timeout": {
        "default_default": 40,
        "android_facebook": 5
    }

• disable_adapter_errors_on_screen (since 1.5.0) – if true, disables the display of API errors in modal windows, allowing you to view them solely using the on_error callback. The default value is False.

The configuration settings are contained in theconfig.py file. Its location depends on the installation method:

• host machine or Docker container oz-api: /opt/gateway/configs

• standalone installer: /var/lib/docker/volumes/api_oz-api-config-vol/_data

Postgres Connection

DB_USER = 'user name'
DB_HOST = 'Postgres server address'
DB_PASS = 'user password'
DB_NAME = 'database name'

Path to Media Files

All incoming media files are saved in the local directory mounted to one of possible endpoints depending of the installation method:

• host server or Docker container: /opt/gateway/static

• in case of standalone installer: /var/lib/docker/volumes/api_oz-api-static-vol/_data

• any path specified via configuration

In most of the integration cases, the media files can be accessed in web using the direct links to randomly generated filenames.

To access the media, you need to specify in the configuration file their external host name or IP address, port, and connection protocol.

PORT = 443
SCHEME = 'https'
HOST = 'api.globalbank.com'

Connection to Oz Bio / Liveness

OZ_SERVICE_TFSS_HOST = 'http://bio-server-name:8501/v1/'

Timing and Limits

# amount of retries to perform analyses to Oz Bio
OZ_CELERY_RETRY_MAX_COUNT = 7
# delay between tries
OZ_CELERY_RETRY_STEP = 30

# maximum wait time of one analyse
OZ_ANALYSE_PROCESSING_EXPIRE_TIMEOUT = 15 * 60  # 15 minutes
# maximum wait time of analyse from API
OZ_ANALYSE_DELIVERY_EXPIRE_TIMEOUT = 60 * 60  # 1 hour
# frequency for check analyse expiration
OZ_ANALYSE_EXPIRE_BEAT_PERIOD = 1 * 60  # every minute

# maximum amount of attached media
OZ_ATTACHMENT_MAX_COUNT = 10
# maximum size of one media file
OZ_ATTACHMENT_MAX_SIZE = 10 * 1024 * 1024  # 10Mb

# amount of seconds until access token expiration
OZ_SESSION_TTL = 60 * 15  # 15 minutes
# amount of seconds until service access token expiration
OZ_SESSION_LONGLIVE_TTL = 60 * 60 * 24 * 365 * 5  # 5 years

# maximum size of thumbnail in bytes
OZ_IMAGE_SIZE_THUMBNAIL = 300
# maximum duration of video file
OZ_VIDEO_DURATION_MAX = 30

• WA_CORS_ORIGINS defines what sources are allowed to make requests. The's no default value. Please bear in mind that if you don't set this value, the CORS headers will be switched off and no such headers will be added within the Web SDK container.

• WA_CORS_METHODS(optional) – HTTP methods allowed to use. If the variable is not set, it gets the default value, which is 'GET, POST, OPTIONS'. If the variable is not used, any method is accepted.

• WA_CORS_HEADERS(optional) – HTTP headers allowed to use. If the variable is not set, it gets the default value which is 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type'. If the variable is not used, any header is accepted.

An example of using environment variables for server configuration:

docker run -d -p 80:80 \
-e WA_CORS_ORIGINS='*' \
-e WA_CORS_METHODS='GET, POST, OPTIONS' \
-e WA_CORS_HEADERS='DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type' \
ozforensics/oz-webliveness:{tag}

Installation

Our engineers will help you to install Oz Web SDK using the standalone installer (requires your technical personnel to take part) or manually (everything is done by us). Once installed, the adapter part generates the plugin files: file with styles (ozliveness.css) and the primary script of the plugin (plugin_liveness.php).

Licensing

To generate the license, we need the domain name of the website where you are going to use Oz Forensics Web SDK, for instance, your-website.com. You can also define subdomains.

1. Unzip the file received:

unzip license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json.zip

2. Copy the JSON license file to the host where you’ve deployed the container from the ozforensics/oz-webliveness-dev:latest image.

Example

scp -i ~/ozforensics/keys/id_rsa-test-hostname-vm license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json user@hostname:/opt/oz/web-sdk

• -i ~/ozforensics/keys/id_rsa-test-hostname-vm is the path to the public ssh key of your host license.

• 0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json is the JSON license file.

• user is the username on host.

• hostname is the host alias.

• /opt/oz/web-sdk is the directory where you’ve deployed the Web SDK container.

3. Replace the license file.

Example

ssh user@hostname -i ~/ozforensics/keys/id_rsa-test-hostname-vm sudo cp -v /opt/oz/web-sdk/license.license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json /opt/oz/web-sdk/license.json

4. Restart the Web SDK container for the new license to be applied.

Example

ssh user@hostname -i ~/ozforensics/keys/id_rsa-test-hostname-vm sudo docker restart web-sdk

• web-sdk is the name of the container you’ve deployed from the ozforensics/oz-webliveness-dev:latest image.

Once the license is added, the system will check its validity on launch.

License Errors