Glossary#

Introduction#

The document describes the process of installing and configuring the VisionLabs LUNA Access service version 2.19.0 (hereinafter — Access), and also contains hardware and software requirements for the software.

The configuration and installation process must be performed under a superuser account (with root rights).

System requirements#

Software Requirements (Table 1).

Table 1. Software Requirements

Workstation hardware requirements (Table 2).

Table 2. Hardware Requirements

Access architecture#

Access scheme#

The Access scheme is shown below (Figure 1) and (Table 3).

Table 3. Scheme description.

Sequence diagrams#

Interaction of internal components of Access#

Interaction of Access components on the example of typical integration of video signal source + LP5 + Sigur (Figure 2) and (Table 4).

Table 4. Sequence diagram description

Creating a component#

Creating a component in Access UI (Figure 3) and (Table 5).

Table 5. Sequence diagram description

Automatic monitoring#

Automatic monitoring of the state of components (Figure 4) and (Table 6).

Table 6. Sequence diagram description

Licensing#

Access does not require a license to work.

Systems and services that are used in the integration may require license. In this case, the license is purchased separately from the copyright holder.

Deploying the Access#

This section describes how to install and use Docker and Docker Compose to deploy Access.

Docker and Docker Compose are not included in the Service distribution package.

The configuration and installation process must be performed under a superuser account (with root privileges).

The manual provides commands for CentOS.

Preparing for installation#

Create a main directory where all versions of the product will be located in the future and go to it.:

sudo mkdir -p -v /var/lib/vl-access-2/
sudo chown $(whoami) /var/lib/vl-access-2/
cd /var/lib/vl-access-2/

Docker and Docker Compose installation#

Use the official instructions to install Docker Engine and Docker Compose for the OS you are using.

Before starting Access, you need to make sure that Docker is running and active.

1． Start Docker:

systemctl start docker
systemctl enable docker

2． Check Docker status:

systemctl status docker

Response must contain Active (running) status.

3． Check Docker Compose installation:

docker-compose --version

The response should indicate the docker-compose version, for example: docker-compose version 1.29.2, build 5becea4.

Preparing and unpacking the distribution#

The distribution package is an archive of the form «vl-access-2-v2.19.0».

A link to download the distribution kit must be requested from a VisionLabs representative.

The archive contains the components necessary for the installation and operation of Access.

The archive does not include dependencies that are included in the standard distribution package of OS and can be downloaded from open sources.

The Service is launched from a Docker image.

Follow these steps:

1． Move vl-access-2-v2.19.0.zip to /var/lib/vl-access-2.

2． Install the unzip archiver if it is not installed.

yum install unzip

The installation command may differ depending on the package manager in the OS, for example, apt is used in Ubuntu/Debian, and dnf in AlmaLinux.

3． Unpack files:

unzip vl-access-2-v2.19.0.zip -d vl-access-2-v2.19.0

The distribution contains (Table 7):

Table 7. Distribution composition

| CHANGELOG.md | Full description of version changes. | | docker-compose.yml | A file containing commands for running Docker containers. | | conf.yml | A file containing configurations for the log-agent service. | | README_FOR_ENGINEERS.md | Quick start guide for implementation engineers. | | /scripts | Directory with useful scripts, see Administrator's Guide. | | vl-access-2-images-v2.19.0.tar.gz | Access distribution, when selecting an archive with an image. | | /tls | Directory for storing certificates for interaction with external systems in .pem format (created automatically when Access starts). |

4． Go to the directory:

cd vl-access-2-v2.19.0

When working with a distribution without an image, you must download the image at startup, see Launching

Setting up Access#

Make the configuration using the .env file (Table 8):

nano .env

Table 8. Description of env parameters

Launching the Access#

1． Import the image:

1．1. If there is an image in the archive:

docker load -i vl-access-2-images-v2.19.0.tar.gz

1．2. Without image:

docker login dockerhub.visionlabs.ru
docker-compose pull
docker logout dockerhub.visionlabs.ru

2． Add symlink to the directory /var/lib/vl-access-2/, which links to the latest version of the product:

ln -s /var/lib/vl-access-2-v2.19.0 /var/lib/vl-access-2/current

3． Run the Service:

docker-compose up -d

Access containers come with pre-installed utilities needed to work with the image.

4． Check the availability of the GUI at: http://<IP_address>:9092/.

To access the Access interface, create an administrator (see Account Management).

Accounts Management#

Adding an administrator account#

Access supports creating an account with the Administrator role. For more information about roles and accesses, see the Roles in the Service section in the User's Guide.

1． Run the administrator creation script:

docker-compose exec fastapi python backend/manage.py createadmin

2． Follow the console instructions:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py createadmin
Admin creation:
Enter your login: admin
Enter your password:
Confirm your password
Admin user created successfully

The administrator's login must be unique

3． Check if the administrator was created correctly. Log in to the created account: http://<IP_address>:9092/.

Viewing Account List#

1． Run the command to view the list of created administrators:

docker-compose exec fastapi python backend/manage.py listadmin

A list of administrators will be displayed in the console:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py listadmin
admin
admin2

Deleting Account#

Get the login information for the account you need to delete using the view command.

1． Run the command to remove the administrator:

docker-compose exec fastapi python backend/manage.py deleteadmin

2． Enter the administrator login.

In response to the request, the console will display a message about successful deletion:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py deleteadmin
Admin deletion:
Enter your login: admin2
Admin was deleted successfully.

Scripts#

Image loading script#

The script scripts/save_images.sh allows you to upload docker images using the paths specified in docker-compose.yml format tar.gz (Table 9).

Uploading may be necessary to save images to storage media and transfer them to an object in the absence/poor Internet connection.

Running the script:

./save_images.sh -f <path_to/docker-compose.yml> -d <local_path_to/docker_images> -u <dockerhub_username> -p <dockerhub_password> 

Table 9. Available Commands:

The final archive must be placed in the Access directory and launched according to instructions.

Access update#

1． Export the settings file of the old version of the product by clicking on the to the right of the user's avatar and click on the Export settings button (Figure 5).

A file with all component settings in json format will be loaded.

2． Save the configuration file.the env of the old version, located along the path /var/lib/vl-access-2/vl-access-2-v2.*.*/.env, where v2.*.* is the version number of the product.

3． To update Access, perform Deletion → Unpacking the new distribution version → Configuring env parameters (transfer the necessary variable values from the saved configuration file.env the old version to a new file) and repeat Installing and launching Access.

4． After installing the new version, go to UI Access, click on the arrow to the right of the user's avatar and the Import Settings button (Figure 6).

In the window that opens, select the previously saved json file, enter the name of the setting and click the Upload button (Figure 7).

When trying to import a settings file from an earlier version of Access to a new one, backward compatibility errors may occur. In case of problems, contact VisionLabs technical support.

Deleting Access#

Deleting Access is done by stopping and deleting Docker containers.

Follow these steps:

1． Switch to the super user:

sudo su

2． Delete the Access directory:

rm -rf vl-access-2-v2.*.*

Log collection and analysis#

Logging guide#

Collecting logs is necessary for:

• Providing VisionLabs technical support information for filing a ticket to find a problem;
• Independent search for errors.

To receive complete information about an emergency situation when using Access, you must prepare and submit information to a VisionLabs representative about:

• Settings file;
• Container logs;
• File .env;
• Information about the working environment;
• UI Screenshots (only in cases of UI errors).

Settings file#

Settings file is a JSON file that contains information about the components used in Access.

The settings file becomes available for export after creating any component in Access.

1． After creating any of the 4 types of components, click on to the right of the user's avatar and click the "Export Settings" button (Figure 8).

This will download a JSON file called vl-access_settings.json.

2． Find the JSON on your local machine.

For Linux systems, the default is /home/\<username>/Downloads.

3． Rename the settings file depending on the main services and devices used, for example, bolid+gate+fast.json.

Container logs#

Container log files contain all information about the operation of Access from the moment of startup (docker compose up) to the creation of logs, provided that the containers are running.

1． Open the Access directory in the console.

For self-checking, make sure that this directory contains /db and docker-compose.yml (Figure 9).

2． Activate debug mode: in the .env file, set the value of the variable DEBUG=1.

3． Restart Access:

docker-compose down
docker-compose up

4． Run the commands to record worker and fastapi containers logs:

The name of the log file must contain the names of the main components.

docker-compose logs worker &> worker_<имена сервисов/устройств, bolid+gate+fast>.log
docker-compose logs fastapi &> fastapi_<имена сервисов/устройств, bolid+gate+fast>.log

5． Check for the generated .log files in the same directory.

Env file#

The .env file is located in the root folder of the distribution (in the same place as docker-compose.yml), but may not appear in the default UI.

1． Locate the .env file to provide to your VisionLabs representative.

Information about the working environment#

Check the hardware and software properties of the working machine with the minimum ones (see Requirements).

To check the requirements, run the view commands:

1． OS version of the local machine:

hostnamectl

2． Docker/docker-compose version:

docker --version
docker-compose --version

3． Information about hardware:

cat /proc/cpuinfo | grep "model name"

4． Amount of free RAM:

free -h

5． Amount of free physical memory:

df -h

Screenshots of UI#

Screenshots are only needed to find a problem with the UI:

• the is_alive status of the component is displayed inadequately,
• a component is displayed that should not exist (it was removed, but it “resurrected”),
• an unreadable error appeared,
• there are duplicates in the list in LUNA Clementine - the screenshot should include the dates of creation of the persons in the list,
• in the events in LUNA Clementine something doesn’t match correctly, the event tag is incorrect,
• other problems with the UI.

Tracking passages using trace_id#

A unique identifier, trace_id, is generated for each passage through the ACS. This identifier links all events related to one passage of a specific person: from the moment of detection to the provision of access through the turnstile.

Using trace_id allows you to quickly and accurately track the entire passage process, analyze delays at different stages and identify possible problems.

Using trace_id, you can track:

• The time of receiving and processing events in the system;
• Information about the recognition result: full name, card number, identifiers in the ACS and biometric system;
• The time of execution of key operations: detection, recognition, sending data to the terminal and controller;
• Other technical details related to processing the passage.

Tracking Luna Platform Event Passes#

1． Open the Luna CLEMENTINE / Luna Platform interface and go to the Latest Events section.

2． Find the oldest successful recognition event.

3． Go to the card of this event by clicking on the arrow in the upper right corner next to the photo (Figure 10).

4． Copy the eight-digit trace_id from the Tags field (Figure 11).

5． Make sure that debug mode (debug) is enabled in LUNA Access 2 and DEBUG-level messages are present in the worker log. 6． Find all logs related to this pass by running the command:

docker-compose logs fastapi worker | grep "<trace_id>"

Example (Figure 12).

How to find trace_id by person's full name#

1． Make sure debug mode (debug) is enabled for LUNA Access 2 and there are DEBUG logs in the worker.

2． Find the required log by full name:

docker-compose logs worker | grep -i "<name>"

3． The found log will contain trace_id in the format trace <trace_id> (Figure 13).

4． Use this trace_id to search all related logs:

docker-compose logs fastapi worker | grep "<trace_id>"

Search for an event in Luna Platform by trace_id#

The steps to display an event by trace_id in the UI are as follows (Figure 14).

1． In Luna CLEMENTINE / Luna Platform, go to Recent Events.

2． Click the filter icon on the right.

3． Enter the trace_id value in the Tags field.

4． Click the Filter button.

Logging during replication#

Replication logging in Access allows tracking the process of synchronizing user (face) data and controllers from the ACS to the LUNA PLATFORM 5 face recognition system.

Proper understanding of replication logs allows for quick identification and resolution of Access integration issues with ACS. Log analysis helps ensure reliable operation of the access control system and timely detection of potential data synchronization problems.

For additional information on tracking specific passage events and using Trace ID, refer to the section Tracking passages with trace_id.

Viewing replication logs#

To view replication logs, you need to perform the following steps:

1． Navigate to the product directory:

cd /var/lib/vl-access-2/

2． Output the logs of the FastAPI and Worker containers in real-time mode:

docker compose logs fastapi worker --follow

Each line contains information about a replication event with a timestamp, logging level (INFO, ERROR, etc.), and event description.

To stop viewing logs and return to the command line, press one of the following key combinations:

Ctrl + Z / Ctrl + C / Ctrl + D

Log filtering#

Logs can be filtered by various criteria by adding the grep command to the output command.

1． To search by user's full name:

docker compose logs fastapi worker --follow | grep "Full name"

Where: Full name - data in the "Information" field of the target person in CLEMENTINE

2． To search by user ID:

3． Enter the trace_id value in the Tags field.

docker compose logs fastapi worker --follow | grep "external_id"

Where: external_id - person identifier from ACS

3． To search by component ID:

docker compose logs fastapi worker --follow | grep "component_id"

Where: component_id - component identifier in Access.

Replication Process Structure#

The replication process consists of the following main stages:

1． Replication initiation - replication is launched automatically upon creation or reboot of the ACS component, or manually in the ACS software interface;

2． Controller replication - synchronization of ACS controller data (if applicable);

3． Face replication - synchronization of user data with their photos;

4． Error and exception handling - logging any problems that arise during the process;

5． Completion of replication - final logging of status.

Key replication logs

1． Start of controller replication.

When the ACS component starts replication, you will see logs of the following type:

Start controller replication

The log indicates that the system is starting to synchronize controllers from the ACS.

2． Start of face replication (Figure 15).

Log:

Start face replication

This log serves as a marker for the start of the main user synchronization process.

3． Creating a new face and saving it to storage (Figure 16).

When the system finds a new user in the ACS who has not yet been added to the LP5 face storage, a new record is created:

Create new face: [face_id], ID [UUID], external ID [external_id] to list [list_id]
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Log parameters:

• face_id - internal face ID in the biometric system
• UUID - unique identifier of a record in the Access system
• external_id - person identifier from ACS
• list_id - the identifier of the list to which the face is added
• storage_name - the name of the storage into which
• additional_info - additional information about the person, for example the value of the additional field MDM_ID

The log informs that a new user record has been successfully created in the system and confirms that the user data has been successfully synchronized and saved in the local Access storage.

4． User data modification (Figure 17).

When user data is changed in the ACS (for example, a change in full name, photo, or other attributes), the system may perform a "delete and recreate" operation, and you will see the following logs:

Successfully updated face [face_id] name: [name] in list Luna
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Log parameters:

• face_id - internal face ID in the biometric system
• name - Full name of the person in the ACS
• external_id - identifier of a person from the ACS
• storage_name - the name of the storage into which
• additional_info - additional information about the person, for example, the value of the additional field MDM_ID

This operation can occur not only during full replication, but also during system operation when the ACS administrator makes changes to user data.

5． Completion of replication (Figure 18).

When all users have been processed, the system logs the completion of replication:

End face replication

The log indicates the successful completion of the face synchronization process.

Recommendations for log analysis#

In case of replication issues:

1． Define the time range:

• Find the logs "Start face replication" and "End face replication", this will give you the exact time frame of the problem

2． Filter logs by component:

• Use search commands with the component ID to focus on a specific ACS (see Log filtering)

3． Find errors/warnings:

• Look for lines containing "ERROR" or "WARNING"

4． Check a specific user:

• Use search commands by full name or face ID from the ACS (see Log filtering)
• Ensure that the user has been successfully replicated

5． Check the sequence of operations:

• Ensure that the logs are in the correct order
• Check for both successful save logs and potential errors

Solving typical problems#

When analyzing replication logs, you may encounter various errors and warnings. The table below serves as a quick reference for diagnosing issues and finding solutions. Each scenario corresponds to a specific type of error you might see in the logs and indicates possible causes and actions to fix it (Table 10).

Table 10. Solving typical problems

Multiple Faces Error in Image#

When the LUNA biometric system detects multiple faces in a single photograph, an error is logged.

ERROR: LUNA API ERROR 11038 Multiple faces found in image

Possible reasons:

• The photo contains several people;
• The photo quality is low, and the biometric system incorrectly interprets parts of the image as separate faces.

Face does not meet requirements#

If the photo does not meet the facial recognition system requirements, a corresponding error is logged:

ERROR: LUNA API ERROR [code] [error_description]

OR

LUNA CLIENT ERROR The face hasn't been created due to wrong handler policies. <details>

Typical validation errors include:

• Face is too small;
• The face is turned at a large angle;
• Insufficient lighting;
• Part of the face is covered;
• Incorrect photo: flipped/blurry, etc.

Possible causes:

• The photo does not meet the quality requirements of LUNA PLATFORM;
• The photo does not meet the processor's policy requirements;
• Incorrect photo processing before sending.

User Blocking#

If a user is blocked in the ACS, the system logs:

Person is blocked

Possible reasons:

• The user is blocked in the ACS.