Glossary#
|
Term |
Description |
|---|---|
|
Approximate Garbage Score (AGS) |
The ยซqualityยป value of a face as determined by the neural network prior to descriptor extraction |
|
Bestshot |
A frame of a video stream in which a face is captured at the optimal angle for further processing |
|
Bbox (Bounding Box) |
A rectangle that bounds the image space with the detected face |
|
Biometric Sample (BS) |
Normalized (centered and cropped) image obtained after face detection, prior to descriptor extraction |
|
Deepfake |
An artificial intelligence-based human image synthesis technique. It is used to combine and superimpose existing images and videos onto source images or videos |
|
Docker |
An open platform for developing, shipping, and running applications. Docker provides the ability to package and run an application in a loosely isolated environment called a container |
|
Docker Compose |
A tool for defining and running multi-container Docker applications |
|
Docker registry |
A tool for storing Docker images |
|
Descriptor |
Data set in closed, binary format prepared by recognition system based on the characteristic being analyzed |
|
Docker container |
A runnable instance of an image. A container is defined by its image as well as any configuration options provided to it when it was created or started. When a container is removed, any changes to its state that are not stored in persistent storage disappear. The isolation and security allow to run many containers simultaneously on a given host |
|
Docker image |
A read-only template with instructions for creating a Docker container |
|
Liveness algorithm |
Software method that enables you to confirm whether a person in one or more images is โrealโ or a fraudster using a fake ID (printed face photo, video, paper or 3D mask) |
|
LUNA PLATFORM 5 (LP5) |
VisionLabs automated facial recognition system designed to process, collect, analyze, store, and compare biometric data obtained from facial images |
|
LUNA Remote SDK (Software development kit) |
VisionLabs development kit including libraries and neural networks for face detection, attribute estimation and Liveness estimation on the acquired image |
|
Plugin |
Independently compiled program module, dynamically connected to LUNA PASS API and designed to extend its capabilities |
|
Spoofing attack |
Substitution of a real person for a fake image (for example, a photograph) to deceive the system |
Introduction#
The document describes:
- architecture and components of LUNA PASS;
- LUNA PASS working principle;
- plugins working principle;
- the process of installing, launching and uninstalling the LUNA PASS API;
- dependencies required for LUNA PASS operation.
Overview#
LUNA PASS is a service for checking Liveness using frames of a video stream from a webcam.
LUNA PASS consists of two components:
- client component, LUNA PASS UI;
- software component, LUNA PASS API.
LUNA PASS UI performs:
- capturing video stream of webcam or mobile device camera with two shooting modes (see the integration documentation for details โ /docs/jslib/LunaPass.html):
- operator: the operator takes pictures, the resulting image isn't mirrored;
- selfie: the operator does not participate in the shooting process, the resulting image is mirrored;
- sending video stream frames to LUNA PASS API;
- displaying the processing results.
LUNA PASS UI works: works in a web browser on PCs and mobile devices, as well as in WebView[^1] in mobile device applications.
LUNA PASS API performs:
- receiving video stream frames from LUNA PASS UI;
- frame processing;
- face detection;
- face attributes extraction and estimation;
- Liveness check;
- Deepfake score;
- Image modification score;
- sending the results to LUNA PASS UI.
[^1]: Android WebView is a pre-installed system component from Google that allows Android apps to display web content.
System requirements#
LUNA PASS is delivered in Docker containers and can use both CPU and GPU processors.
Docker container LUNA PASS images are required for installation. An Internet connection is required to download the Docker images to the server. You can also download images to any other device and transfer to the server. Authorization to the VisionLabs Docker registry is required to download Docker images.
LUNA PASS can be deployed using the Docker Compose script.
Running LUNA PASS has been tested on the following versions of the above software:
- Docker: 25.0.3
- Docker Compose: 2.24.6
It is not guaranteed to work with other versions of the above software.
Using the plugin mechanism requires developing scripts that take into account the syntax and functionality provided by Python 3.11.
It is considered that installation is performed on the server with Almalinux 8 OS, where LUNA PASS was not installed.
Processors requirements#
The configuration below guarantees software package minimum power operating. System requirements for the production system are calculated based on the intended system load.
The hardware specifications below are based on servicing up to 10 client sessions simultaneously.
CPU#
The following minimum system requirements should be met for the LUNA PASS software package installation:
- Intel(R) Xeon(R) CPU E5-2640 v4 @ 2.40 Hz (8 virtual cores);
- AVX2 instruction set support;
- 64-bit processor;
- DDR4 RAM, 16 GB or higher;
- Free storage size must be 10 Gb or higher.
GPU#
For GPU acceleration an NVIDIA GPU is required. The following architectures are supported:
- Pascal and newer;
- Compute Capability 6.1 or higher is required.
SSD 100GB of free hard disk space. 8GB of VRAM or more recommended.
CUDA version 11.4 must be installed where Remote SDK and Lambda (optional) service is deployed. The recommended NVIDIA driver is r470.
Service architecture#
The Service architecture is shown in the diagram (Figure 1), a description of the architecture components is presented below (Table 1).
Table 1. Components of the LUNA PASS architecture
|
Component name |
Description of interaction |
|---|---|
|
LUNA PASS UI |
LUNA PASS client component responsible for capturing video stream, sending video stream frames to LUNA PASS API and displaying processing results. An external system with similar functions can be used instead of LUNA PASS UI, provided that the LPProto protocol is used to connect to the Backend (see the "LPProto protocol" section for operating principle). |
|
LUNA PASS API |
LUNA PASS server component, built on AIOHTTP. It processes frame, checks image and Liveness using plugins, then, based on the results of the check, makes decisions about whether the image passes inspection. |
|
LUNA Configurator |
LP5 component that stores configurations of all services. |
|
LUNA Licenses |
LUNA Licenses contains information about available licensed features and their limitations, provides information about license conditions to LUNA PASS components: license expiration date; maximum number of created faces with descriptors; information about the availability of Liveness and Deepfake. LUNA Licenses is required for the operation of the Service components and their interaction with the LP5 components. |
|
LUNA Remote SDK |
VisionLabs development kit including libraries and neural networks for detection, attribute estimation and Liveness estimation on the acquired face image. |
|
LUNA PASS VIDEO |
LUNA PASS server component that implements the gluing of frames received within LUNA PASS API sessions into video. |
|
NGINX |
Optional component. HTTP server and reverse proxy server for load balancing. It is not part of the product, install and configure component separately (see the "Appendix" secion). |
|
LPProto |
A transport layer information transfer protocol that defines the structure of transmitted frames using WebSocket. Frame is a fragment of protocol data. See LPProto Protocol section for the list of frames. |
The first frame is processed in five stages (Table 2).
Table 2. Frame processing stages
|
Stage |
Description |
|---|---|
|
1 |
PreProcessingโpreliminary frame processing (implementation of the LPProto protocol, conversion, etc.), as well as the operation of plugins that do not need frames |
|
2 |
Frame processing using Remote SDK (2-3) 1. Evaluation and selection of the "main" face; 2. Evaluation of the biometric sample; 3. Evaluation of face/head attributes; 4. Checking whether the session was previously marked as fake; 5. Liveness, Deepfake, Image modification evaluation as well as descriptor extraction. In case of errors, frame processing is terminated. |
|
3 |
Parallel operation of FaceMatcher, ActiveLiveness, VirtualCameraChecker plugins. |
|
4 |
Decision Phaseโthe stage of making a decision on further continuation of the session, if, for example:
|
|
5 |
Response to the caller and creation of background tasks for file post-processing (FileLogger, VideoRedis, etc.), which must complete either before the end of the session or before receiving the next frame. |
LUNA PASS API forms a JWT packet with the bestshot, on successful passing of Liveness. The network communication scheme is shown below (Figure 2).
LPProto Protocol#
LPProto is a transport layer protocol developed by VisionLabs to restrict information transmitted using WebSocket. The principle of operation is transmission of consecutive frames with messages.
Frame is a fragment of protocol data, which must be specified strictly according to the template. The definition applies only to this section, in the rest of the document the frame is a part of the video stream. The first line of each frame specifies its command within the protocol.
Connection settings that are transmitted as part of the CONNECT command:
- heartbeat:1000
- session-id:623e1bbc-24f9-4d84-907f-8000978ec2a1
The session ID is passed in the session-id header when the connection is initialized.
LPProto protocol format#
A schematic representation of the protocol format is shown below (Figure 3).
The message consists of three lines:
- First line โ message type or command (Table 3);
- The second line โ section with any number of headers;
- The third line โ message body, separated by an empty line.
Table 3. Supported message types
|
Command |
Description |
Example |
|---|---|---|
|
CONNECT |
Start request to establish a connection to the LUNA PASS API. Without an established connection, work is not possible. Acceptable headings:
Possible answers:
|
CONNECT version:1.0 heartbeat:1000 |
|
CONNECTED |
Response from LUNA PASS API about successful connection to LUNA PASS UI over WebSocket. Acceptable headings:
|
CONNECTED session-id:623e1bbc-24f9-4d84 -907f-8000978ec2a1 version: 1.0 |
|
FRAME |
A request from LUNA PASS UI containing information about the image: a frame of the video stream in the format specified in the content-type header. Acceptable headings:
Possible answers: STATS โ image/face failed the test; SUCCESS โ the test was successful; ERROR โ error within a frame check request. LUNA PASS UI restriction: the next FRAME cannot be sent until a response is received, this is necessary to synchronize data sending, including cases of using multiple LUNA PASS UI instances and minimize errors. |
FRAME content-type:image/x-jpeg-base64 /9j/4AAQSkZJRgABAQABAAโฆ |
|
STATS |
LUNA PASS API response after unsuccessful image estimation, containing
the error codes detected (see If a face was found in the image, the BBox information is returned. Acceptable headings:
|
STATS content-type:application/json {isOk: false, errors: [12], estimations: {,โฆ}} estimations: {,โฆ} estimations: {,โฆ} BBox, if available. errors: [12] isOk: false |
|
SUCCESS |
LUNA PASS API response after successfully validating the image, selecting the bestshot and evaluating the face. Acceptable headings:
After receiving the frame WebSocket connection is closed. Further work requires reconnection. |
SUCCESS content-type:application/jwt eyJ0eXAiOiJKVโฆ |
|
ERROR |
LUNA PASS API response when an internal error occurs:
Acceptable headings:
The following system errors exist in this version:
|
ERROR error: 1002 |
|
HEARTBEAT |
Optional recurring background request from Backend to keep WebSocket open. See CONNECT for how to enable it. Sends an empty frame every N ms. |
HEARTBEAT |
JWT package#
JSON Web Token (JWT) โ A JSON object that allows signed text information to be transmitted.
JThe WT consists of 3 parts, separated by dotsโheader.payload.signature. The sections use Base64 encoding:
1๏ผ Title: Header
Description: JWT Type Information.
Example of decoded Base64:
The following attributes are used during LUNA PASS operation: { "alg": "HS256", "typ": "JWT" }. The "algorithm" attribute is configured in lunapassapi in JWT configuration parameters.
2๏ผ Title: Payload
Description: A message body containing information on the recognized attributes.
See /docs/jslib/LunaPass.js.html for a detailed description.
Example decoded Base64:
{
"errors": [],
"bestshot": "***",
"estimations": {
"faceCount": 1,
"ags": null,
"imageQuality": {
"blur": 0.9192548394203186,
"isBlurred": false,
"light": 0.7044228315353394,
"isHighlighted": false,
"darkness": 0.7675179243087769,
"isDark": false,
"illumination": 0.2165278196334839,
"isIlluminated": false,
"specularity": 0.5341013669967651,
"isSpecular": false
},
"faceFramePosition": {
"faceRect": {
"x": 135,
"y": 167,
"width": 243,
"height": 336
},
"frameRect": {
"x": 0,
"y": 0,
"width": 480,
"height": 640
},
"margins": [
167,
102,
137,
135
]
},
"headPose": {
"yaw": 6.0508646965026855,
"roll": 0.8311771750450134,
"pitch": 3.0268990993499756
},
"eyes": {
"left": "open",
"right": "open",
"state": "open"
},
"mouth": {
"opened": 0.013608532957732677,
"smile": 0.0012621879577636719,
"occluded": 0.0009340881952084601,
"state": "opened"
},
"eyeglasses": "no_glasses",
"deepfake": {
"score": 0.9797163605690002,
"state": "real"
},
"liveness": {
"score": 0.9812202453613281
}
},
"isOk": true,
"iat": 1747917134,
"jti": "d52158fa-e154-4203-9bc0-b6045b7a1a1f"
}
3๏ผ Title: Signature
Description: Unique message signature.
Interaction of LUNA PASS components#
The interaction of the LUNA PASS components is presented in the diagram (Figure 4), a description of the component interaction is given below (Table 4).
Table 4. Description of the process of interaction LUNA PASS components during frame processing and Liveness estimation
|
Step |
Description |
|---|---|
|
0 |
The user accesses LUNA PASS UI by opening the corresponding page in a web browser. LUNA PASS UI requests access to the webcam |
|
1 |
The browser displays an appropriate message requesting permission from the user. The user grants access to continue using LUNA PASS |
|
2โ3 |
LUNA PASS UI establishes a WebSocket connection to the LUNA PASS API using the LPProto protocol, which sends a CONNECT request |
|
4 |
LUNA PASS API checks the received data, assigns a session-id and opens a WebSocket connection |
|
5 |
LUNA PASS UI connects to the webcam and captures the image from the webcam |
|
6 |
Video stream frames from the webcam are sent to the LUNA PASS UI |
|
7 |
LUNA PASS UI displays the video stream received from the webcam in near real-time mode |
|
8 |
LUNA PASS UI sends frames of the video stream, on which, for example, it was possible to detect a face, to the server in the LUNA PASS API using a secure Web Socket protocol |
|
9 |
LUNA SDK as part of the LUNA PASS API performs face detection, determines attributes, and performs Liveness estimation |
|
10 |
If the Liveness estimation was not successful, the LUNA PASS API returns the results of the checks in the LUNA PASS UI |
|
11 |
LUNA PASS UI displays appropriate prompts based on the data obtained in step 10. If the LUNA PASS API detects poor quality on the received frames or fails to checkup (the user is sitting far away from the camera or his/her head is turned at too large an angle), the web browser will display instructions in the form of prompts on how the user should change the position of his/her face relative to the webcam |
|
12 |
If the Liveness estimation was successful, the LUNA PASS API analyzes the current frame. If the current frame is a bestshot (successfully passed all checks), it is sent in a signed JWT token |
LUNA PASS UI#
User panel#
User opens LUNA PASS UI page in a web browser to pass the checks. The LUNA PASS UI requests access to the webcam. If the user allows access, the screen shows a stream from the camera (Figure 5).
Here the user can:
- change the video stream mode by clicking the
(1). There are two modes:
- operator: the operator takes pictures, the resulting image isn't mirrored;
- selfie: the operator does not participate in the shooting process, the resulting image is mirrored;
- zoom in with
and
(2) to meet size requirements for face image;
- select the source of the video stream (3);
- start the check by clicking on the button (4).
If the user fails the checks, for example because they are sitting too far away from the camera or their head tilt angle is too above, the web browser shows tips on how to change the position relative to the webcam to pass the check.
Administrator panel#
The administrator manages user interface settings via the admin panel (Figure 6).
From the panel home page, the administrator can:
- manage user interface configs (1). Click on "UI configs" to go to details โ viewing the list of configs, creating and editing configs;
- manage authentication and authorization settings (2). Click on "AUTHENTICATION AND AUTHORIZATION" to go to details:
- creating other panel users with access to specified parts of the admin panel;
- creating user groups with access to specified parts of the admin panel. For example, you can create another administrator with the right to manage user interface settings;
- view the history of actions in the interface in the "Recent actions" block (3). Click on an action from the list to return to it;
- view the result of applying config on the page for passing checks by clicking โVIEW SITEโ (4);
- change password of the administrator account by clicking โCHANGE PASSWORDโ (5);
- log out of the account by clicking "LOG OUT" (6);
- change the theme to dark or light mode by clicking on
or
(7).
UI configs#
Viewing configs#
To view the list of configs created in the admin panel (Figure 7), click on โUI configsโ on the home page.
These actions the administrator is able to do on the page with the list of configs:
- edit a config by clicking on its name;
- add a new config by clicking "Add UI config" (1);
- delete selected configs, for this:
- tick the checkboxes for configs to delete or tick the checkbox next to โUI CONFIGโ above the list of configs to select all ones (2);
- select "Delete selected ui configs" in the "Action" field;
- click the "Go" button;
- confirm the deletion by clicking โYes, Iโm sureโ, or cancel by clicking โNo, take me backโ in the opened page with a description of the objects to be deleted.
Creating config#
To create a new config of user interface, click the "Add" button in the "UI configs" section on the home page. You can also create a new config from the page with a list of configs by clicking "Add UI config" .
In the opened page (Figure 8), set:
- name of the config, "Name" field;
- address where the user is redirected after passing check, "Redirect url" field;
- width and height of the camera image, in px, "Image width" and "Image height" fields;
- width and height of the camera stream image, in px, โVideo widthโ and โVideo heightโ fields;
- shooting mode in "Mode" field:
- operator: the operator takes pictures, the resulting image isn't mirrored;
- selfie: the operator does not participate in the shooting process, the resulting image is mirrored;
- description of errors that are showed when the user fails the checks, as well as description of tips on how to change the position of the face relative to the webcam in order to pass the checks, "Error messages" field;
- message that is shown when the user successfully passes the checks, "Success message" field;
- name of the button to start checking, which is shown in the user panel, โButton start messageโ field;
- tooltip for changing the video stream mode in the user panel, โMode tooltipโ field;
- message that is shown to the user if it was not possible to connect to the camera, the โCamera is not attached messageโ field;
- colors of buttons, backgrounds, messages of the user panel, the โStylesโ field for html code;
Editing config#
To start editing config, open the list of configs, then select the one that you want to edit by clicking on its name. Edit the fields and save the changes. See the "Creating config" section for the description of the fields.
Applying config#
The system supports creating and using multiple configs of user interface. LUNA PASS UI always operates with a single UI configuration per session. The required configuration is specified when opening LUNA PASS UI via a URL parameter.
Link format:
https://{host}:{port}/?cn={config_name}
Where:
https://{host}:{port}โthe base address of the LUNA PASS UI;config_nameโthe name of the UI configuration specified when it was created in the administrator panel.
Thus, an unlimited number of UI configurations can be created, each accessible via its own dedicated link.
LUNA PASS API#
The general principle of operation of LUNA PASS API is as follows:
- a frame comes to the input;
- LUNA Remote SDK estimates and checks the frame;
- plugins are executed sequentially if they are enabled:
- FaceMatcher plugin;
- VirtualCameraChecker plugin;
- ActiveLiveness plugin;
- the aggregated value of Liveness, Deepfake, Image modification score as well as mouth, eye status and glasses type estimations are calculated;
- the result of the plugin and check work is analyzed.
By default, all plugins are enabled.
Frame estimation process#
The frame estimation process is the sequential execution of checks. A description of the checks is presented below (Table 5).
Table 5. Checks for frame estimation process
|
Check |
Internal checks |
|---|---|
|
Multiface |
Whether the face is:
|
|
Image quality |
|
|
The size and position of the face in the frame |
Indentation of the face border from the frame border:
Frame size:
The size of the face in the frame:
|
|
Head position |
|
|
Eyes status |
|
|
Mouth status |
|
|
Glasses |
|
|
AGS (check the overall image quality metric) |
\โ |
|
Liveness |
Liveness estimation |
|
Deepfake |
Deepfake estimation |
|
Image modification |
Automatically determine the fact of image modification/editing by the presence of characteristic artifacts:
|
If a frame does not pass any of the checks, then the next frame is analyzed. The user sees the corresponding prompts on the page with LUNA PASS UI.
Enable and configure plugins via the Luna Configurator service: http://{host}:5070/dashboard/settings.htmlโserver address, port 5070, /dashboard/settings.html.
FaceMatcher plugin#
The plugin allows you to terminate the session if several main faces are detected on two frames within one session. Set the previous_face_similarity parameter = 0.85.
Description of the general working principle of the FaceMatcher plugin:
If the first frame arrives, Facematcher remembers photo of face. If the second frame arrives, Facematcher compares photo of face from the received frame with the photo of the face from the previous frame:
-
if faces on the photos from the two frames are different, then no further checks are carried out;
-
if faces on the photos from the two frames are the same, then the frame is sent for further checks.
VirtualCameraChecker plugin#
The plugin allows you to detect when a user is using a virtual camera instead of a real device camera. Virtual camera detection data is recorded to the logs.
ActiveLiveness plugin#
The plugin allows you to confirm vitality by several frames in which the user interacts with the Service: blinks, turns his head left and right along the Y axis, tilts his head up and down along the X axis. The description of the general working principle of the plugin is presented below (Table 6).
Table 6. Description of the general principle of operation of the ActiveLiveness plugin
|
Step |
Description |
|---|---|
|
1 |
The administrator selects an arbitrary set of checks*. The number of checks is specified in the settings. |
|
2 |
If the current frame fails Liveness check, the plugin generates errors. Errors tell what the user should do to pass the verification. |
|
3 |
ActiveLiveness checks#
Blinking
The check begins when both eyes are open, or one eye is open and the accept_one_eye_open parameter is enabled. To pass the check, the two frames must then arrive: with eyes closed and again with open ones, or, if the accept_one_eye_open parameter is enabled, a frame with one eye closed and a frame with one open.
Head turn
To start checking, the head turn angle must be less than the value of yaw_start_deg. Next, the two frames must arrive: with a turn angle value greater than yaw_threshold_deg and with a turn angle value less than yaw_start_deg.
Head tilt
To start checking, the head tilt angle must be less than the value of pitch_start_deg. Next, the two frames must arrive: with a tilt angle value greater than pitch_threshold_deg and with a tilt angle value less than pitch_start_deg.
For more information about the values of the turn and tilt angles, see configuration parameters of the ActiveLiveness plugin
LUNA PASS VIDEO#
LUNA PASS VIDEO allows you to create a video file based on the received set of frames and process it on the client side for further work with the file (saving, transfer, etc.).
LUNA PASS VIDEO performs splicing together a video file from a webcam or mobile app camera in a single session using the codec set in the settings.
The number of frames (N) from which the gluing should be performed is regulated in LUNA PASS configuration parameter frames_limit:
-
in case when less than N frames are received during the session, LUNA PASS performs gluing from the available number of frames;
-
in case if more than N frames are received during the session, LUNA PASS performs gluing from the last N frames from the end of the session.
Video file gluing from frames is performed for all sessions independently of the result of estimations performed in LUNA PASS API or expiration of the number of attempts to pass certain checks. Set the logic for processing received videos in the example-docker/lunapassvideo.task.py file.
The name of the file directly depends on the parameter args.workerTask, which is set in the configuration of LUNA PASS API.
In case of reconnection at WebSocket session break, LUNA PASS VIDEO forms one common video file for one session ID and saves it to the storage.
Service setup#
Specify the connection settings to redis in the LUNAPASS_REDIS_DB_ADDRESS block in the Luna Configurator service, for example:
{
"host": "10.16.30.110",
"port": 6379,
"user": "default",
"password": "lunapass",
"sentinel": {
"master_name": "trustgate_provider",
"sentinels": [],
"user": "",
"password": ""
},
"number": 0
}
Configure LUNA PASS VIDEO according to the parameters shown in Table 8.
Table 8. LUNA PASS VIDEO configuration parameters
|
Parameter |
Description |
Default value |
|---|---|---|
|
VIDEO |
||
|
codec |
The codec used for video encoding (Table 9). Available values:
|
H265 |
|
framesLimit |
Limit the maximum number of frames in a video If the value is 0, the restriction is not applied For values greater than 0, the last N frames are taken for the video Default: 0 |
|
|
REDIS |
||
|
connection String |
Redis connection string |
redis://127.0.0.1:6379 |
|
queueName |
Name of the Redis video queue |
default |
Replace the default
redis://127.0.0.1address with the address of the host where it runs, otherwise pages associated with these addresses will not appear in the interface.
Table 9. Estimation of video encoding types (codecs)
|
Estimating Parameter |
h.264 |
h.265 |
VP9 |
|---|---|---|---|
|
Video processing speed |
โ |
ร |
ร |
|
Availability across devices |
โ |
ร |
ร |
|
Compression ratio |
ร |
โ |
ร |
|
High quality video |
ร |
โ |
โ |
|
Availability of license restrictions |
โ |
โ |
ร |
Licensing#
The LUNA PASS service requires a LUNA PLATFORM 5 license. The set of licenses depends on the functionality provided (Table 10):
|
Check Type |
License |
|---|---|
|
Liveness |
PlatformLiveness |
|
Deepfake |
PlatformDeepfake |
|
Image Modification |
PlatformISO |
For detailed licensing information, see the LP5 documentation.
Installing LUNA PASS#
The LUNA PASS service requires LUNA PLATFORM 5 (LP5) minimum version 5.126.0.
Warning
LUNA PASS uses only a subset of LUNA PLATFORM 5 services. Installing other LP5 components is optional.
Do not install LUNA PASS on a server where LP5 is already running for other tasks. To ensure stable operation, deploy the systems on separate servers.
Installing LUNA PLATFORM 5#
1. Preparing for installation
Follow the steps from the docker compose deployment documentation according to the LP5 version you received. For this, select the required documentation version on the site.
Steps for deploying LP5:
1๏ผ Unpack the distribution 2๏ผ Create a symbolic link 3๏ผ Configure SELinux and Firewall (if required) 4๏ผ Activate the license 5๏ผ Install Docker and Docker Compose 6๏ผ Log in to the registry
2. Run
1๏ผ Go to the directory with the Docker Compose script:
cd /var/lib/luna/current/example-docker
2๏ผ Run the script:
./start_platform.sh --pass
To use the GPU in the Remote SDK service, add the --gpu flag. GPU parameters, such as the device number, are configured in the docker-compose.gpu.yml file.
This script:
- Starts the PostgreSQL database and the Redis database
- Prepares the environment for Luna Configurator and loads the settings
- Starts the services:
- Luna Configurator
- Luna Licenses
- Luna Remote SDK
Important: An example for deployment is provided. For industrial use, please contact a VisionLabs employee.
Preparing and unpacking the distribution#
The distribution package is an archive of the form "luna_pass_2.2.3".
Before the installation process, place the distribution files in a directory on the server. For example, in the /root directory. There should be no other distribution files in this directory other than the target files used to install the final product.
Perform the following steps.
1๏ผ Switch to root superuser mode:
sudo su
2๏ผ Create a directory to unzip the distribution:
mkdir -p /var/lib/luna-pass
3๏ผ Move the distribution to the directory you created:
mv /root/luna_pass_2.2.3 /var/lib/luna-pass
4๏ผ Install the unzip archiver if it is not installed:
yum install unzip
5๏ผ Change to the distribution directory:
cd /var/lib/luna-pass
6๏ผ Unzip the files:
unzip luna_pass_2.2.3.zip
7๏ผ Create a symbolic link. The link indicates that it is the current version of the distribution that is used for launching:
ln -s luna_pass_2.2.3 current
If the /var/lib/luna-pass/current link is missing, the startup scripts will not be able to locate the binary files of the current release, and further installation will not be possible.
Before starting, update the settings in the configurator:
docker run --rm --entrypoint='' --network=host dockerhub.visionlabs.ru/lunapass/lunapass-configs:v3.2.3 python3 -m configs.migrate head --config_db_url postgres://luna:luna@127.0.0.1:5432/luna_configurator
127.0.0.1 is the configurator host. Specify your address if the configurator is located on another one.
Quick Start#
After you unpack the distribution and configure the license, run LUNA PASS with the command:
./start_selfsigned.sh {host}:{port}
Specify the host and port on which you plan to open the interface.
Script start_selfsigned.sh:
- generates a self-signed certificate for nginx and places it in the desired directory (see point 3 of the "Running jslib examples" section);
- generates the directories necessary for operation (./LOGS, ./videos) and sets the necessary permissions for them;
- starts services at the following addresses:
- https://{host}:{port}โlunapassui;
- https://{host}:{port}/adminโlunapassui admin panel. Default login/passwordโadmin/admin;
- http://{host}:8321โlunapassapi;
- http://{host}:8320โfilebrowser interface, where you can view, for example, saved videos and session frames. Default login/passwordโadmin/adminl;
- http://{host}:5070/dashboard/settings.html โ Luna Configurator service, stores all service configurations;
- https://{host}:{port}/statistics โ service operation statistics: information on the number of completed sessions, the composition of failed checks, time metrics.
Starting LUNA PASS in container mode#
Enter the current data and settings into the files before running in docker. The data to enter see the section "Service Configuration".
1๏ผ Change to the Docker directory:
cd /var/lib/luna-pass/current/example-docker
2๏ผ Create configuration files for the services to be used (for example, from the example files in each service) to be mounted in docker. To start the service, enter the command:
docker-compose up -d
3๏ผ Check the status of all running Docker containers.
docker-compose ps
Service configuration#
Configure Selinux and Firewall so that they do not block the service.
The service is configured via the Luna Configurator service. The Luna Configurator service requires Postgresql to be installed.
1๏ผ Launch Luna Configurator: http://{host}:5070/dashboard/settings.htmlโserver address, port 5070, /dashboard/settings.html
2๏ผ Specify lunapass as a group to display the desired settings (Figure 9):
3๏ผ Perform the settings according to the description (Tables 11-19 and Figures 10-20)
Configuring the service in Luna Configurator#
Table 11. Selecting the operating mode and configuring the JWT packet
|
Parameter |
Description |
|---|---|
|
Operating mode |
|
|
env |
LUNA PASS has two operating modes:
Default: The development mode allows you to track the correctness of LUNA PASS operation and is usually used during the debugging and testing period. In an industrial circuit, it is recommended to enable the production mode. |
|
Configuration parameters LUNA_PASS.JWT |
|
|
algorithm |
Successful frame encryption algorithm Default: |
|
key |
Successful frame encryption secret Default: |
Table 12. Session parameters
|
Parameter |
Description |
|---|---|
|
Session parameters |
|
|
max_attempts |
Maximum number of frames received within 1 session. If the value is exceeded, the current frame is sent as is and the connection is terminated. If no value is present, the frames are checked until there is a successfully passed Liveness Default: |
|
max_liveness_attempts |
The maximum number of frames that have reached the Liveness estimation. If the value is exceeded, the current frame is sent as is and the connection is terminated. If no value is present, the frames are checked until there is a successfully passed Liveness Default: |
|
aggregate_frames |
Number of frames to aggregate. Must be at least 1 Default: |
|
accept_one_eye_open |
Allow one eye to be checked for openness:
Default: |
|
previous_face_similarity |
Similarity threshold. If the similarity value is below the threshold, then it is considered that
the frames have different faces and the session is terminated. Specify a value of Default: |
|
multiface_policy |
Policy for selecting a person to check Liveness. Available values:
Default: |
Table 13. Parameters for the ROI face recognition zone
|
Parameter |
Description |
|---|---|
|
center_x |
The center of the ROI zone along the X axis Default: The
Default: |
|
center_y |
The center of the ROI zone along the Y axis Default: The
Default: |
|
width |
The width of the ROI zone Default: The
Default: |
|
height |
Height of the ROI zone Default: The
Default: |
Table 14. Face estimation thresholds
|
Parameter |
Description |
|---|---|
|
blur |
Photo blurring Default: |
|
light |
Backlighting of the photo image Default: |
|
dark |
Darkening of the photo image Default: |
|
illumination |
Uniformity of image illumination, 0 โ uniform, 1 โ there are overexposures Default: |
|
specularity |
Glare on the image, 0 โ no glare, 1 โ there are glare Default: |
|
face_width |
Face frame width Default: |
|
face_height |
Face frame height Default: |
|
yaw |
Rotation around the vertical axis of the head Default: |
|
pitch |
Rotation around the transverse axis of the head Default: |
|
roll |
Rotation around the longitudinal axis of the head Default: |
|
mouth |
Required accuracy of mouth status assessment Default: |
|
glasses |
Availability of glasses. Available values:
Default: |
|
deepfake |
Required accuracy of the Deepfake estimation. Specify a value of Default: |
|
liveness |
Thresholds for the OneShot Liveness test result at which a person will be considered ยซaliveยป Default: |
|
image_modification |
Threshold for checking for image modification/editing based on the presence of
characteristic artifacts. Specify a value of Default: |
Table 15. ActiveLiveness parameters
|
Parameter |
Description |
|---|---|
|
is_enabled |
Active Liveness Default: |
|
cooldown_frames_count |
Minimum number of frames after passing active Liveness Default: |
|
interaction_list |
Used checks:
Default: [ |
|
interaction_count |
Number of user interactions to use. The maximum number
must not exceed the number of checks specified in Default: |
|
interaction_order |
The order of interaction of checks:
Default: |
|
yaw_start_deg |
Initial angle of rotation at which it is possible to begin interaction with head turns Default: |
|
yaw_threshold_deg |
Threshold angle of rotation at which interaction on head turns is considered completed Default: |
|
pitch_start_deg |
The initial head tilt angle at which it is possible to begin head tilt interaction Default: |
|
pitch_threshold_deg |
The head tilt angle threshold at which the head tilt interaction is considered completed Default: |
Table 16. VirtualCameraChecker, FileLogger, VideoRedis parameters
|
Parameter |
Description |
|---|---|
|
Virtual Camera Checker parameter |
|
|
is_enabled |
Check frames for use of a virtual camera Default: |
|
File Logger parameters |
|
|
is_enabled |
Saves all incoming photos and the results of their estimation within one session to a file Default: |
|
path |
Path for saving file logs Default: |
|
Video Redis parameters* |
|
|
is_enabled |
Stitching frames together to create a video and sending session frames to Redis Default: |
Table 17. LUNA PASS_VIDEO parameters
|
Parameter |
Description |
|---|---|
|
LUNA PASS_VIDEO settings |
|
|
codec |
The codec used for video encoding Default: |
|
frames_limit |
Limit the maximum number of frames in a video:
Default: |
|
expires |
Number of seconds for Redis to store frames that were not used in the video.
The information is erased after the Default: |
|
result_ttl |
How long Redis stores information about successful tasks and their ะะพ ัะผะพะปัะฐะฝะธั: |
|
session_timeout |
Number of seconds to start building video after session termination if no bestshot is available Default: |
Table 18. LUNAPASS_REDIS_DB_ADDRESS parameters
|
Parameter |
Description |
|---|---|
|
host |
Redis DB IP address Default: |
|
port |
The port number on which Redis listens for incoming network connections and listens to execute commands from clients Default: |
|
user |
Redis database username No default value |
|
password |
Redis database password No default value |
|
master_name |
The name of the Redis database master that is monitored and managed by Sentinel Default: |
|
sentinels |
List of Sentinel server addresses and ports that will be used by clients to discover and monitor Redis databases. Default: [] |
|
user |
Sentinel server username No default |
|
password |
Sentinel server user password No default |
|
number |
Database number Default: |
Table 19. LUNAPASS_VIDEO_LOGGER parameters
|
Parameter |
Description |
|---|---|
|
log_level |
Sets the level of debug printing, by priority: "ERROR", "WARNING", "INFO", "DEBUG" Default: |
|
folder_with_logs |
The folder where the logs are stored (the relative path starts from the directory with the application) Default: |
|
max_log_file_size |
Maximum log file size in MB before rotation (0 - do not use rotation) Default: |
|
log_time |
The time format used in log entries: "LOCAL" or "UTC" Default: |
|
log_to_stdout |
Enables you to send the log to standard output (stdout). Two options are available - "true" or "false" Default: |
|
log_to_file |
Enables you to send the log to a file. Two options are available - "true" or "false" Default: |
|
multiline_stack_trace |
Enables or disables multi-line traces in logs. Two options are available - "true" or "false" Default: |
|
format |
Log format Default: |
Table 20. LUNAPASS_VIDEO_HTTP_SETTINGS parameters
|
Parameter |
Description |
|---|---|
|
request_timeout |
The amount of time between when a new open TCP connection is passed to the server (in seconds) Default: |
|
response_timeout |
The amount of time between when the server passes an HTTP request to the application and when the HTTP response is sent to the client (in seconds) Default: |
|
request_max_size |
The maximum request size in bytes Default: |
|
keep_alive_timeout |
HTTP keep-alive timeout Default: |
Table 21. LUNA_REMOTE_SDK_ADDRESS parameters
|
Parameter |
Description |
|---|---|
|
origin |
Protocol, IP address and port of the Remote SDK service Default: |
|
api_version |
Remote SDK service API version. Available API version is "1". Default: |
Running services with different configurations#
Tagged configurations allow you to run multiple instances of the same service, each using different settings from Luna Configurator. There are two ways to apply tagged configurations:
- by passing arguments directly to the service startup command;
- by using the
EXTEND_CMDenvironment variable.
1. Passing arguments to the startup command
1๏ผ Duplicate an existing configuration or create a new one and assign a tag. For example, you can duplicate the lunapass_video configuration and assign it the tag lunapass_video_tagname.
2๏ผ Pass the corresponding arguments to the run.py command of the container:
--luna-config โ flag specifying the address of the Luna Configurator service
--<configuration_name> โ flag specifying the configuration name and its tag
For example, to start a container with the lunapass_video configuration tagged lunapass_video_tagname, the command would look like this:
docker run \
...
dockerhub.visionlabs.ru/luna/lunapass_video:v.3.2.2
python3 /srv/lunapass_video/run.py --luna-config http://{host}:{port} --lunapass_video lunapass_video_tagname
2. Using the EXTEND_CMD environment variable
The EXTEND_CMD environment variable can be used to specify tagged configuration arguments. For example, launching two instances of LUNAPASS_API with different tags may look like this:
services:
api:
container_name: lunapass-api
image: registry.dev.vlabs/lunapass-api:PASS-49_configurator-tags
restart: always
network_mode: ${NETWORK_MODE}
environment:
- EXTEND_CMD=--LUNAPASS_API=tagname --LUNAPASS_API_LOGGER=tagname2
- RELOAD_CONFIG=1
- RELOAD_CONFIG_INTERVAL=10
- CONFIGURATOR_HOST=${CONFIGURATOR_HOST}
- CONFIGURATOR_PORT=${CONFIGURATOR_PORT}
- PORT=${LUNAPASSAPI_PORT}
Variable descriptions:
CONFIGURATOR_HOSTandCONFIGURATOR_PORTโ address and port of the Luna Configurator service;LUNAPASSAPI_PORTโ port on which the LUNA PASS API runs;NETWORK_MODEโ container network mode.
Running jslib examples#
This section describes how to configure jslib to display frame processing results.
1๏ผ Launch LUNA PASS in container mode.
2๏ผ Make sure NGNIX is installed.
3๏ผ Make sure that SSL certificates are used or generated, for example:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/certs/servername.key -out /etc/nginx/certs/servername.crt
4๏ผ Create an nginx configuration to display static example files. To do this:
4๏ผ1. Login via SSH to the server;
4๏ผ2. Go to the directory with configuration files:
cd /etc/nginx/conf.d/
4๏ผ3 Create a configuration for luna-pass:
nano luna-pass.conf
Example content:
upstream lunapassapi {
server 10.16.30.144:8321;
}
server {
listen 443 ssl;
ssl_certificate /root/10.16.30.144.crt;
ssl_certificate_key /root/10.16.30.144.key;
ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "RC4:HIGH:!aNULL:!MD5:!kEDH";
add_header Strict-Transport-Security 'max-age=604800';
root /var/lib/luna/luna_pass_2.2.3/jslib/examples;
index index.html;
location /ws {
error_log /var/lib/luna/logs/error.log;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_pass http://lunapassapi;
}
location/{
try_files $uri $uri/ /index.html =404;
add_header Cache-Control "no-store, no-cache, must-revalidate";
}
}
4๏ผ4. Save and check the syntax of nginx configs:
[root@nginx-test conf.d]# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
4๏ผ5. Restart nginx
systemctl restart nginx
5๏ผ Check the operation of jslib on the page with examples of luna-pass https://<server_ip>.
Removing LUNA PASS#
Uninstallation is performed by terminating and deleting running Docker containers:
1๏ผ Switch to root superuser mode:
sudo su
2๏ผ Remove the containers:
docker-compose down
Appendix#
Example of NGINX configuration setup:
server {
listen 443 ssl;
server_name luna-pass.frontend.vlabs;
# SSL settings
#ssl_certificate ....
# Path to luna-pass jslib
root /var/lib/luna-pass/current/jslib/examples;
# Static settings
location/{
try_files $uri $uri/ /index.html =404;
add_header Cache-Control "no-store, no-cache, must-revalidate";
}
# Websocket connection with the backend
location /ws {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_pass http://127.0.0.1:8321;
}
}