Welcome to FindFace CIBR documentation!
FindFace CIBR (Criminal Investigation Biometric Registry) is a forensic platform powered by a cutting-edge facial recognition technology. It is designed to conduct criminal investigations based on associated video footage and to search individuals across Public and Transport Safety systems.
FindFace CIBR forensic functionality
Biometric forensic databases. Upload the databases to FindFace CIBR by creating a Record Index and assigning records of individuals under observation to relevant watch lists (Wanted, Fugitives, etc.). It can be done in bulk. A record accommodates aggregated data about an individual: a face biometric sample, document scans, criminal record, and other information.
Case files. Upload a video footage of an incident or a photo to FindFace CIBR to detect and identify human faces in them. If there are individuals whose facial biometric data are in the forensic databases, FindFace CIBR will be able to spot them during this stage.
Go ahead and process the facial recognition results, using a built-in tool. Tell apart participants from bystanders and identify suspects and victims.
Search. Search the system for specific individuals.
Remote alerting. Combine FindFace CIBR with Public and Transport Safety systems. Receive real-time alerts on appearance of specific individuals from remote facial recognition systems. This will help track the offender’s location and routes, detect alleged accomplices, find missing people.
Remote search. Search specific individuals in remote facial recognition systems.
Facial verification. Verify that two given faces belong to the same individual.
Reports. Detailed reports on search results and records.
Technical features
AI-based platform.
Developer-friendly installer and user-friendly interface.
Single- and multi-host deployment.
Increased performance and fault-tolerance in high load systems with numerous cameras and clients.
Network or on-premise licensing.
CPU- and GPU-based acceleration for your choice.
System security
Advanced user management. Possibility of integrating with Active Directory.
Comprehensive, friendly, searchable audit logs.
Backup and recovery utilities.
Possibility of monitoring user sessions and blocking devices without deactivating user accounts.
Useful little things
Quick record index creation.
Extended set of search filters.
Integration
Integration via HTTP API.
What’s New in FindFace CIBR 2.1.1
New Features:
Upload a photo to a case: the end user is now able to upload only photos, videos, or photos along with videos to a case.
Rematching clusters with the record index: once new photos are uploaded to the record index, the system checks them against all existing clusters of open cases to find out new matches.
“Inbox” of cases: the system marks cases that have at least one unacknowledged case cluster with a special sign so that the end user does not miss it.
See Case Files
Technical Changes:
Technical architecture: microservices instead of monolith.
See Architecture
Docker-based distribution: FindFace CIBR 2.1.1 runs as a set of docker containers described in a
docker-composefile.Deployment: FindFace CIBR is distributed with its own installer now.
CentOS / Debian support.
Enhanced Algorithms, UI, UX:
Improvements to the mechanism of clustering and more flexible work with clusters: clusters can now be manually merged and unmerged.
Record index batch upload reinstated.
Enhanced Daily search functionality: last 24-hour’ location registration of the objects of interest in remote monitoring.
Fresh Neural Networks:
Face detection: a new face detection model
face.jasmine_fast.003with improved characteristics.Face image normalization: new face image normalization models
facenorm.multicrop_full_center_size400andfacenorm.multicrop_full_crop2x_size400that use smarter normalization algorithm and a new versionbee.v3with improved characteristics.Face recognition: brand-new
nectarine_xs_320andnectarine_m_160face recognition models, much faster and more accurate than preceding models.Face quality recognition: a new version
quality_fast.v1that predicts face quality to get the best shot and filter trash.
System Administrator’s Guide
This chapter is all about FindFace CIBR deployment and further updates and maintenance during exploitation.
Architecture
Though you mostly interact with FindFace CIBR through its web interface, be sure to take a minute to learn the FindFace CIBR architecture. This knowledge is essential for the FindFace CIBR deployment, integration, maintenance, and troubleshooting.
In this chapter:
Recognition Process
FindFace CIBR detects a human face in the photo or video and prepares its image through normalization. The normalized image is then used for extracting the face’s feature vector (an n-dimensional vector of numerical features that represent the face). Face feature vectors are stored in the database and further used for verification and identification purposes.
Docker Platform
FindFace CIBR is deployed in Docker, a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers. Each FindFace CIBR service runs in a Docker container.
Architectural Elements
FindFace CIBR consists of the following fundamental architectural elements:
FindFace core, a cutting-edge AI-based recognition technology that can be used as a separate product FindFace Enterprise Server.
Application Module (FindFace CIBR), implementing a set of tools for criminal investigations based on video footage and photo files.
Architecture scheme
FindFace core
There is a separate product FindFace Enterprise Server inside the FindFace core. It includes the following components:
Component |
Ports in use |
Description |
Vendor |
|---|---|---|---|
findface-extraction-api |
18666 |
Service that uses neural networks to detect a face in an image and extract its feature vector. It also recognizes face attributes, for example, gender, age, emotions, beard, glasses, etc. CPU- or GPU-acceleration. |
NtechLab own deployment |
findface-sf-api |
18411 |
Service that implements the internal HTTP API for face detection and recognition. |
|
findface-tarantool-server |
32001, shard ports (default 330xx, 81xx) |
Service that provides interaction between the |
|
findface-upload |
3333 |
NginX-based web server used as a storage for original images, thumbnails, and normalized face images. |
|
findface-facerouter |
18820 |
Service used to define processing directives for detected faces. In FindFace CIBR,
its functions are performed by |
|
findface-video-manager |
18810, 18811 |
Service, part of the video face detection module, that is used for managing the video face detection functionality, configuring the video face detector settings and specifying the list of to-be-processed video files. |
|
findface-video-worker |
18999 |
Service, part of the video face detection module, that recognizes a face in
the video and posts its normalized image, full frame and metadata (such as
detection time) to the |
|
findface-ntls |
443 (TCP), 3133, 3185 |
License server that interfaces with the NtechLab Global License Server, a USB dongle, or hardware fingerprint to verify the license of your FindFace CIBR instance. |
|
findface-counter |
18300 |
Service used for event deduplication. |
|
Tarantool |
Shard ports (default 330xx, 81xx) |
Third-party software that implements the feature vector database that stores extracted face feature vectors and identification events. The system data, records, user accounts are stored in PostgreSQL (part of the FindFace CIBR application module). |
|
etcd |
2379 |
Third-party software that implements a distributed key-value store for
|
|
NginX |
80; SSL: 8002, 8003, 443, 80 |
Third-party software that implements the system web interfaces. |
|
memcached |
11211 |
Third-party software that implements a distributed memory caching system.
Used by |
Application Module (FindFace CIBR)
The FindFace CIBR application module includes the following components:
Component |
Ports in use |
Description |
Vendor |
|---|---|---|---|
findface-multi-legacy |
Configurable |
Service that serves as a gateway to the FindFace core. Provides interaction between the FindFace core and the web interface, the system functioning as a whole, HTTP and web socket, face monitoring, event notifications, etc. |
NtechLab own deployment |
findface-multi-pause |
n/a |
Internal services that assist |
|
findface-multi-audit |
8012, 8013, 8014 |
||
findface-multi-identity-provider |
8022, 8023, 8024 |
||
cleaner |
n/a |
The service is responsible for the data cleanup. |
|
findface-multi-ui |
Configurable |
Main web interface used to interact with FindFace CIBR. Based on the Django framework. Allows you to work with face recognition events, search for faces, manage cases, users, record index, watch lists, and many more. |
|
NATS |
4222 |
Third-party software that implements a message broker in |
|
etcd |
2379 |
Third-party software that implements locks in the |
|
Pgbouncer |
5439 |
Third-party software, a lightweight connection pooler for PostgreSQL. Optional, used to increase the database performance under high load. |
|
PostgreSQL |
5432 |
Third-party software that implements the main system database. This database stores records of individuals and data for internal use. The face feature vectors and face identification events are stored in Tarantool (part of the FindFace core). |
See also
CPU- and GPU-acceleration
The findface-extraction-api and findface-video-worker services can be either CPU- or GPU-based. You will have an opportunity to choose the acceleration type you need during the installation.
Important
Refer to Requirements when choosing hardware configuration.
Important
If video resolution is more than 1280x720px, it is strongly recommended to use the GPU-accelerated package findface-video-worker.
Requirements
In this chapter:
System Requirements for Basic Configuration
To calculate the FindFace CIBR host(s) characteristics, use the requirements provided below.
Tip
Be sure to learn about the FindFace CIBR architecture first.
Important
If the video resolution is more than 1280x720px, it is strongly recommended to use the GPU-accelerated package findface-video-worker-gpu.
Important
On AMD CPU servers, the full functionality of the CPU-accelerated findface-extraction-api service is not guaranteed. Use the GPU-accelerated service findface-extraction-api-gpu along with the GPU-version of neural networks instead.
Note
In case of a high-load system (~> 15 events per second), be sure to use an SSD.
Minimum |
Recommended |
|
|---|---|---|
CPU |
Intel Core i5 CPU with 4+ physical cores 3+ GHz. AVX2 support |
Intel Xeon Silver/Gold with 6+ physical cores |
The own needs of FindFace CIBR require 2 cores HT > 2.5 GHz. The characteristics also depend on the number of
video files in process. A single video file |
||
GPU (optional) |
GeForce® RTX 3060 12 GB |
NVIDIA A10 |
Supported devices: NVIDIA, Pascal architecture and above. Note: NVIDIA GeForce RTX 40 Series graphics cards are currently not supported. |
||
RAM |
16 Gb |
32+ Gb |
The RAM consumption depends on:
A single video file Please, contact our support team for details (support@ntechlab.com). |
||
HDD (SSD for best performance) |
65 Gb |
65+ Gb |
The own needs of FindFace CIBR require 65 GB. The total volume is the subject to the required depth of the event archive in the database and in the log, at the rate of 1.5 Mb per 1 event. |
||
Operating system |
Ubuntu from 18 to 22, x64 only, RHEL / CentOS 7, Debian 11. |
|
Note
You can also use an Intel-based VM if there is AVX2 support, and eight physical cores are allocated exclusively to the VM.
Tip
For more accurate hardware selection, contact our support team by support@ntechlab.com.
Required Administrator Skills
A FindFace CIBR administrator must know and understand the OS, on which the product instance is deployed, at the level of an advanced user.
Video File Formats
FindFace CIBR supports a wide variety of file formats depending on the acceleration type, CPU or GPU.
Both CPU- and GPU-accelerated instances support all FFmpeg codecs. In addition to that, the following codecs are supported:
CPU-based acceleration: FLV (both as a codec and as a container), H263, H264, H265, MJPEG, VP8, VP9, MPEG1VIDEO, MPEG2VIDEO, MSMPEG4v2, MSMPEG4v3.
GPU-based acceleration: MJPEG, H264, H265, VP9, and others, depending on the list of codecs supported by the used video card. Apart from that, for instances with
video-worker-gpu, you can expand the number of supported codecs by enabling video decoding on the CPU, which is not available by default.
To enable video decoding on the CPU for GPU-based acceleration, do the following:
Open the
/opt/findface-cibr/configs/findface-video-worker/findface-video-worker.yamlfile.sudo vi /opt/findface-cibr/configs/findface-video-worker/findface-video-worker.yaml
Set
cpu: truein thevideo_decodersection.... video_decoder: cpu: true ...
Restart the
findface-cibr-findface-video-worker-1container.sudo docker container restart findface-cibr-findface-video-worker-1
Deploy and Remove FindFace CIBR
Docker platform
FindFace CIBR 2.1.1 is Docker-based. You must install and start a set of Docker products before proceeding with the FindFace CIBR deployment. For your convenience, this chapter contains Ubuntu, CentOS, and Debian server preparation sections covering the intricacies of installing Docker on the above-mentioned operating systems. For other platforms, please refer to the Docker documentation.
NVIDIA driver and NVIDIA Container Runtime (GPU only)
If you intend to deploy FindFace CIBR with GPU-acceleration, you need to install the NVIDIA driver and NVIDIA Container Runtime. Again, you will find the relevant information in the server preparation sections.
Deployment options
After you are finished with the server preparation, you are all set for the FindFace CIBR deployment. You are provided with the following options here:
Automatically install FindFace CIBR standalone in one run. Being the simplest, this installation type is excellent to kick-start your experience with FindFace CIBR. We recommend choosing it if you are a first-timer. See FindFace CIBR Standalone Automated Deployment for guidance.
Fully customized installation. It requires fundamental understanding of the product architecture. See Fully Customized Installation.
Note
If you select the installation type #2, keep in mind to install necessary neural network models along with the findface-extraction-api component.
Installer questions and automatic deployment from the installation file
Before starting the actual installation, the installer asks you a few questions and performs several automated checks to ensure that the host meets the system requirements. After filling out each prompt, press Enter.
To install the same configuration of FindFace CIBR on a different host, use the automatic deployment from the installation file. In this case, you won’t have to answer the installation questions again. The exact path to the installation file is displayed right after the last question, before the installer starts off active progress:
[I 2023-10-06 13:30:48,766 main:142] Your answers were saved to /tmp/findface-installer-p01n9sn3.json
Important
Be sure to remove fields *.config, exp_ip, and int_ip before installing FindFace CIBR on a host with a different IP address.
To launch the automatic deployment from the /tmp/<findface-installer-*>.json file, execute:
sudo ./<findface-*>.run -f /tmp/<findface-installer-*>.json
Post-development procedures and how-to’s
Browse through the Post-deployment Procedures and How-to’s section to learn how to set the time zone, license your instance, and configure logging. This section will also provide you with few basic commands that will help you to kick-start your work with FindFace CIBR containers, in case you are a newbie to Docker.
Important
Starting the GPU-accelerated services findface-extraction-api and findface-video-worker for the first time after deployment may take a considerable amount of time due to the caching process (up to 45 minutes).
Important
Although FindFace CIBR provides tools to ensure its protection from unauthorized access, they are not replacing a properly configured firewall. Be sure to use a firewall to heighten the FindFace CIBR network protection.
Instance removal
To remove your instance, you must run a set of commands. See the Remove FindFace CIBR Instance section.
Ubuntu Server Preparation
To prepare a server on Ubuntu for the FindFace CIBR deployment, follow the instructions below minding the sequence.
Note
For other platforms, please refer to the following resources:
In this section:
GPU: Install NVIDIA Drivers
The first step of the server preparation is the NVIDIA driver installation. It’s applicable only for the GPU configuration. Go straight to the Docker installation if your configuration is CPU-accelerated.
With the GPU-accelerated FindFace CIBR, you’ll need the NVIDIA driver version 530 or above. Add the NVIDIA repository and install an applicable driver from it.
Warning
We do not recommend using a .run installer from NVIDIA Driver Downloads instead, as its drivers may conflict with the drivers installed via packages.
To install the 530 driver from a repository, do the following:
Install the repository signature key:
arch=$(uname -m); version=$(. /etc/os-release; echo $ID$VERSION_ID | sed -r 's/\.//g'); sudo bash -c \ "sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/$ID$version/$arch/3bf863cc.pub \ && apt update"
Install
aptitudeand execute the following command:sudo aptitude install nvidia-driver-530
Install Docker Products
Docker products must be installed on both CPU and GPU servers. Do the following:
Update the
aptpackage index and install packages to allowaptto use a repository over HTTPS.sudo apt-get update sudo apt-get install \ ca-certificates \ curl \ gnupg \ lsb-release
Tip
You may receive the following errors when running
sudo apt-get install \:E: Could not get lock /var/lib/dpkg/lock-frontend - open (11: Resource temporarily unavailable) E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?
There are two ways to resolve them:
Forcibly terminate all the
apt-getprocesses currently running in the system.sudo killall apt apt-get
If the previous command didn’t help, run the set of commands below. It’s fine if some of the to-be-deleted directories do not exist — just keep going.
sudo rm /var/lib/apt/lists/lock sudo rm /var/cache/apt/archives/lock sudo rm /var/lib/dpkg/lock sudo rm /var/lib/dpkg/lock-frontend sudo dpkg --configure -a
Add the Docker’s official GPG key (GNU Privacy Guard key) to the host.
sudo mkdir -m 0755 -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
Set up the Docker repository.
echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Update the apt package index one more time.
sudo apt-get update
Tip
If you have received a GPG error when running this command, try granting read permission for the Docker public key file before updating the package index.
sudo chmod a+r /etc/apt/keyrings/docker.gpg sudo apt-get update
Install
24.*versions of Docker products.sudo apt-get install docker-ce=5:24* docker-ce-cli=5:24* containerd.io docker-buildx-plugin
Check whether the Docker installation was a success. The following command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.
sudo docker run hello-world Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world 2db29710123e: Pull complete Digest: sha256:aa0cc8055b82dc2509bed2e19b275c8f463506616377219d9642221ab53cf9fe Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly. To generate this message, Docker took the following steps: 1. The Docker client contacted the Docker daemon. 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64) 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading. 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal. To try something more ambitious, you can run an Ubuntu container with: $ docker run -it ubuntu bash Share images, automate workflows, and more with a free Docker ID: https://hub.docker.com/ For more examples and ideas, visit: https://docs.docker.com/get-started/
Install
docker-compose.sudo curl -SL https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Perform the Docker Engine post-installation procedures to ease your future work with Docker and FindFace CIBR containers. Once you can manage Docker as a non-root user, you don’t have to apply
sudoin the commands related to Docker.sudo groupadd docker sudo usermod -aG docker $USER newgrp docker
Configure the Docker network.
sudo su BIP=10.$((RANDOM % 256)).$((RANDOM % 256)).1 cat > /etc/docker/daemon.json <<EOF { "bip": "$BIP/24", "fixed-cidr": "$BIP/24" } EOF
GPU: Install NVIDIA Container Runtime
To deploy containerized GPU-accelerated FindFace CIBR, you need NVIDIA Container Runtime. We recommend installing NVIDIA Container Toolkit that includes this runtime. Do the following:
Specify the repository and install NVIDIA Container Toolkit from it by executing the following commands.
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \ && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \ && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \ sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart dockerConfigure the Docker network. Configure usage of the NVIDIA Container Runtime installed along with NVIDIA Container Toolkit.
sudo su BIP=10.$((RANDOM % 256)).$((RANDOM % 256)) cat > /etc/docker/daemon.json <<EOF { "default-address-pools": [ {"base":"$BIP.0/16","size":24} ], "bip": "$BIP.1/24", "fixed-cidr": "$BIP.0/24", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": [] } }, "default-runtime": "nvidia" } EOFRestart Docker.
systemctl restart docker
Now you are all set to install FindFace CIBR. Refer to the following sections:
CentOS 7 Server Preparation
To prepare a server on CentOS 7 for the FindFace CIBR deployment, follow the instructions below minding the sequence.
Note
For other platforms, please refer to the following resources:
In this section:
Install Updates
Run updates and reboot the server.
sudo yum update sudo reboot
Install
fuseby running the following command.sudo yum -y install fuse
GPU: Install NVIDIA Drivers
The first step of the server preparation is the NVIDIA driver installation. It’s applicable only for the GPU configuration. Go straight to the Docker installation if your configuration is CPU-accelerated.
With the GPU-accelerated FindFace CIBR, you’ll need the NVIDIA driver version 530 or above. Download a relevant .run installer from NVIDIA Driver Downloads.
Since you use a .run installer from NVIDIA, the following dependencies must be installed:
sudo yum install kernel-devel gcc kernel-headers
Install Docker Products
Docker products must be installed on both CPU and GPU servers. Do the following:
Install the
yum-utilspackage (which provides theyum-config-managerutility) and set up the repository.sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
Install
24.*versions of Docker products.sudo yum install docker-ce-3:24* docker-ce-cli-1:24* docker-ce-rootless-extras-24* containerd.io docker-buildx-plugin docker-compose-plugin
Start and enable Docker.
sudo systemctl start docker sudo systemctl enable docker
Check whether the Docker installation was a success. The following command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.
sudo docker run hello-world Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world 2db29710123e: Pull complete Digest: sha256:aa0cc8055b82dc2509bed2e19b275c8f463506616377219d9642221ab53cf9fe Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly. To generate this message, Docker took the following steps: 1. The Docker client contacted the Docker daemon. 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64) 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading. 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal. To try something more ambitious, you can run an Ubuntu container with: $ docker run -it ubuntu bash Share images, automate workflows, and more with a free Docker ID: https://hub.docker.com/ For more examples and ideas, visit: https://docs.docker.com/get-started/
Install
docker-compose.sudo curl -SL https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Perform the Docker Engine post-installation procedures to ease your future work with Docker and FindFace CIBR containers. Once you can manage Docker as a non-root user, you don’t have to apply
sudoin the commands related to Docker.sudo groupadd docker sudo usermod -aG docker $USER newgrp docker
Configure the Docker network and
devicemapperusage.sudo su BIP=10.$((RANDOM % 256)).$((RANDOM % 256)).1 cat > /etc/docker/daemon.json <<EOF { "bip": "$BIP/24", "fixed-cidr": "$BIP/24", "storage-driver": "devicemapper" } EOF
GPU: Install NVIDIA Container Runtime
To deploy containerized GPU-accelerated FindFace CIBR, you need NVIDIA Container Runtime. We recommend installing NVIDIA Container Toolkit that includes this runtime. Do the following:
Specify the repository and install NVIDIA Container Toolkit from it by executing the following commands.
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \ && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.repo | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo sudo yum clean expire-cache sudo yum install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker
Configure the Docker network,
devicemapperusage, and usage of the NVIDIA Container Runtime installed along with NVIDIA Container Toolkit.sudo su BIP=10.$((RANDOM % 256)).$((RANDOM % 256)) cat > /etc/docker/daemon.json <<EOF { "default-address-pools": [ {"base":"$BIP.0/16","size":24} ], "bip": "$BIP.1/24", "fixed-cidr": "$BIP.0/24", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": [] } }, "default-runtime": "nvidia", "storage-driver": "devicemapper" } EOFRestart Docker.
systemctl restart docker
Now you are all set to install FindFace CIBR. Refer to the following sections:
Debian 11 Server Preparation
To prepare a server on Debian 11 for the FindFace CIBR deployment, follow the instructions below minding the sequence.
Note
For other platforms, please refer to the following resources:
In this section:
Install FUSE
Install FUSE (Filesystem in Userspace) by running the following command.
sudo apt install fuse -y
GPU: Install NVIDIA Drivers
The first step of the server preparation is the NVIDIA driver installation. It’s applicable only for the GPU configuration. Go straight to the Docker installation if your configuration is CPU-accelerated.
With the GPU-accelerated FindFace CIBR, you’ll need the NVIDIA driver version 530 or above. Download a relevant .run installer from NVIDIA Driver Downloads.
Since you use a .run installer from NVIDIA, the following dependencies must be installed:
sudo apt install linux-headers-$(uname -r)
sudo apt install build-essential
Install Docker Products
Docker products must be installed on both CPU and GPU servers. Do the following:
Update the
aptpackage index and install packages to allowaptto use a repository over HTTPS.sudo apt-get update sudo apt-get install ca-certificates curl gnupg
Add the Docker’s official GPG key (GNU Privacy Guard key) to the host.
sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg
Set up the Docker repository.
echo \ "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \ "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Update the
aptpackage index one more time.sudo apt-get update
Install
24.*versions of Docker products.sudo apt-get install docker-ce=5:24* docker-ce-cli=5:24* containerd.io docker-buildx-plugin
Check whether the Docker installation was a success.
sudo docker run hello-world
The following command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.
Install
docker-compose.sudo curl -SL https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Perform the Docker Engine post-installation procedures to ease your future work with Docker and FindFace CIBR containers. Once you can manage Docker as a non-root user, you don’t have to apply
sudoin the commands related to Docker.sudo groupadd docker sudo usermod -aG docker $USER newgrp docker
Configure the Docker network.
sudo su BIP=10.$((RANDOM % 256)).$((RANDOM % 256)).1 cat > /etc/docker/daemon.json <<EOF { "bip": "$BIP/24", "fixed-cidr": "$BIP/24" } EOF
GPU: Install NVIDIA Container Runtime
To deploy containerized GPU-accelerated FindFace CIBR, you need NVIDIA Container Runtime. We recommend installing NVIDIA Container Toolkit that includes this runtime. Do the following:
Specify the repository and install NVIDIA Container Toolkit from it by executing the following commands.
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \ && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \ && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \ sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart dockerSwitch to the superuser account.
sudo su
Configure the Docker network. Configure usage of the NVIDIA Container Runtime installed along with NVIDIA Container Toolkit.
BIP=10.$((RANDOM % 256)).$((RANDOM % 256)) cat > /etc/docker/daemon.json <<EOF { "default-address-pools": [ {"base":"$BIP.0/16","size":24} ], "bip": "$BIP.1/24", "fixed-cidr": "$BIP.0/24", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": [] } }, "default-runtime": "nvidia" } EOFRestart Docker.
systemctl restart docker
Now you are all set to install FindFace CIBR. Refer to the following sections:
FindFace CIBR Standalone Automated Deployment
To deploy FindFace CIBR as a standalone server in one run, follow the instructions below. Being the simplest, this installation type is excellent to start off your work with FindFace CIBR. Be sure to meet the system requirements and, depending on your OS, prepare the server first:
See:
Important
The FindFace CIBR host must have a static IP address in order to be running successfully. To make the IP address static, open the /etc/network/interfaces file and modify the current primary network interface entry as shown in the case study below. Be sure to substitute the suggested addresses with the actual ones, subject to your network specification.
sudo vi /etc/network/interfaces
iface eth0 inet static
address 192.168.112.144
netmask 255.255.255.0
gateway 192.168.112.254
dns-nameservers 192.168.112.254
Restart networking.
sudo service networking restart
Be sure to edit the etc/network/interfaces file with extreme care. Please refer to the Ubuntu guide on networking before proceeding.
Do the following:
Download the installer file
findface-*.run.Put the
.runfile into some directory on the designated host (for example,/home/username).From this directory, make the
.runfile executable.Note
Be sure to specify the actual file name instead of
findface-*.chmod +x findface-*.run
Execute the
.runfile.sudo ./findface-*.run
The installer will ask you a few questions and perform several automated checks to ensure that the host meets the system requirements. After filling out each prompt, press Enter. The questions and answers are the following:
Q:
Which product should be installed?A:
1- 1 [cibr ] FindFace CIBR - 2 [video-worker] FindFace Video Worker (default: cibr) product> 1
Q:
Please choose installation type:A:
1- 1 [stand-alone ] Single Server - 2 [multi-worker] Single Server, Multiple video workers - 3 [images ] Don't configure or start anything, just load the images and copy the models - 4 [custom ] Fully customized installation (default: stand-alone) type> 1
Q:
Directory to install into:A: Specify the FindFace CIBR installation directory. By default, it’s
/opt/findface-cibr. Press Enter to confirm it. Otherwise, specify the directory of your choice and press Enter.Directory to install into: (default: /opt/findface-cibr) dest_dir>
Q:
Found X interface(s). Which one should we announce as our external address?A: Choose the interface that you are going to use as the instance IP address.
Found 2 interface(s). Which one should we announce as our external address? - 1 [lo ] 127.0.0.1 - 2 [ens3 ] 192.168.112.254 (default: 192.168.112.254) ext_ip.advertised> 2
Q:
Which variant of Video Worker should be installed?A: Specify the
findface-video-workerpackage type, CPU or GPU.Which variant of Video Worker should be installed? - 1 [cpu] CPU-based implementation, slower but doesn't require GPU - 2 [gpu] CUDA-based implementation of video detector, requires NVIDIA GPU (default: cpu) findface-video-worker.variant> 1
Q:
Which variant of Extraction API should be installed?A: Specify the
findface-extraction-apipackage type, CPU or GPU.Which variant of Extraction API should be installed? - 1 [cpu] CPU-only implementation, slower but doesn't require GPU - 2 [gpu] CUDA-based implementation, faster, requires NVIDIA GPU (supports both CPU and GPU models) (default: cpu) findface-extraction-api.variant> 1
Q:
Do you want to configure face features right now?(y/n)A: We recommend you to configure face attribute recognition functionality straightaway during the installation. Answer
yto initiate the process. You can skip it, though, by answeringnand perform the necessary steps later, following the instructions in the Enable Face Attribute Recognition section.Do you want to configure face features right now?(y/n) configure> y
Q:
Please select face features to install:A: This question appears if you have requested configuration of face attributes. By default, all face attributes are subject to installation. Answer
doneto confirm it. If some attribute is not necessary, you can enter the keyword (number) related to it. For example, enter7to exclude the head pose recognition. Then enterdone.Please select face features to install: - 1 [v] Age - 2 [v] Gender - 3 [v] Emotions - 4 [v] Beard - 5 [v] Glasses - 6 [v] Medicine masks Enter keyword to select matching choices or -keyword to clear selection. Enter "done" to save your selection and proceed to another step. face_features> done
Q:
Please set findface-cibr admin passwordA: Set the Super Administrator (
superuser) password.Please set findface-cibr admin password findface-multi-admin-password> admin
After the final question you will see a path to a JSON file with your answers:
Your answers were saved to /tmp/findface-installer-t8qk_isw.json
The installer will pull the FindFace CIBR images from the Ntechlab registry and start the following services in Docker containers:
Service
Container
Configuration
pause
findface-cibr-pause-1
Started
nats-jetstream
findface-cibr-nats-jetstream-1
Started
mongodb
findface-cibr-mongodb-1
Started
findface-ntls
findface-cibr-findface-ntls-1
Started
nats
findface-cibr-nats-1
Started
postgresql
findface-cibr-postgresql-1
Started
memcached
findface-cibr-memcached-1
Started
findface-upload
findface-cibr-findface-upload-1
Started
etcd
findface-cibr-etcd-1
Started
findface-sf-api
findface-cibr-findface-sf-api-1
Started
findface-extraction-api
findface-cibr-findface-extraction-api-1
Started (CPU/GPU-acceleration)
findface-tarantool-server-shard-*
findface-cibr-findface-tarantool-server-shard-*-1
Started. The number of shards is calculated using the formula:
N = min(max(min(mem_mb // 2000, cpu_cores), 1), 16 * cpu_cores). I.e., it is equal to the RAM size in MB divided by 2000, or the number of CPU physical cores (but at least one shard), or the number of CPU physical cores multiplied by 16, if the first obtained value is greater.findface-video-manager
findface-cibr-findface-video-manager-1
Started
findface-counter
findface-cibr-findface-counter-1
Started
pgbouncer
findface-cibr-pgbouncer-1
Started
findface-liveness-api
findface-cibr-findface-liveness-api-1
Started
findface-video-worker
findface-cibr-findface-video-worker-1
Started (CPU/GPU-acceleration)
findface-multi-audit
findface-cibr-findface-multi-audit-1
Started
findface-multi-identity-provider
findface-cibr-findface-multi-identity-provider-1
Started
findface-multi-legacy
findface-cibr-findface-multi-legacy-1
Started
findface-multi-ui
findface-cibr-findface-multi-ui-1
Started
redis
findface-cibr-redis-1
Started
cleaner
findface-cibr-cleaner-1
Started
After the installation is complete, the following output is shown in the console:
Tip
Be sure to save this data: you will need it later.
############################################################################# # Installation is complete # ############################################################################# - all configuration and data is stored in /opt/findface-cibr - upload your license to http://192.168.112.254/#/license/ - user interface: http://192.168.112.254/ superuser: admin documentation: http://192.168.112.254/doc/ 2023/10/17 09:24:25 Installer finished
Perform the post-deployment procedures.
Tip
To install the same configuration of FindFace CIBR on a different host, use the automatic deployment from the installation file. In this case, you won’t have to answer the installation questions again. The exact path to a JSON file with answers is displayed right after the last question, before the installer starts active progress:
[I 2023-10-17 09:20:57,264 main:142] Your answers were saved to /tmp/findface-installer-t8qk_isw.json
Be sure to remove fields *.config, exp_ip, and int_ip before installing FindFace CIBR on a host with a different IP address.
To launch the automatic deployment from the /tmp/<findface-installer-*>.json file, execute:
sudo ./<findface-*>.run -f /tmp/<findface-installer-*>.json
Fully Customized Installation
The FindFace CIBR developer-friendly installer provides you with a few installation options, including the fully customized installation. This option is mostly used when deploying FindFace CIBR in a highly distributed environment and requires a high level of knowledge and experience.
To initiate the fully customized installation, do the following:
Download the installer file
findface-*.run.Put the
.runfile into some directory on the designated host (for example,/home/username).From this directory, make the
.runfile executable.Note
Be sure to specify the actual file name instead of
findface-*.chmod +x findface-*.run
Execute the
.runfile.sudo ./findface-*.run
The installer will ask you a few questions and perform several automated checks to ensure that the host meets the system requirements. After filling out each prompt, press Enter. The questions and answers are the following:
Q:
Which product should be installed?A:
1Which product should be installed? - 1 [cibr ] FindFace CIBR - 2 [video-worker] FindFace Video Worker (default: cibr) product> 1
Q:
Please choose installation type:A:
4Please choose installation type: - 1 [stand-alone ] Single Server - 2 [multi-worker] Single Server, Multiple video workers - 3 [images ] Don't configure or start anything, just load the images and copy the models - 4 [custom ] Fully customized installation (default: stand-alone) type> 4
Q:
Directory to install into:A: Specify the FindFace CIBR installation directory. The default suggestion is
/opt/findface-cibr. Press Enter to confirm it. Otherwise, specify the directory of your choice and press Enter.Directory to install into: (default: /opt/findface-cibr) dest_dir>
Q:
Please enter path to docker-compose binary:A: Specify the actual path to the
docker-composebinary. The default suggestion is/usr/local/bin/docker-composeand it is the path you get when you installdocker-composeduring Ubuntu / CentOS / Debian server preparation. Press Enter to confirm it. Otherwise, specify another path and press Enter.Please enter path to docker-compose binary (default: /usr/local/bin/docker-compose) docker_compose>
Q:
Found X interface(s). Which one should we announce as our external address?A: Choose the interface that you are going to use as the instance IP address.
Found 2 interface(s). Which one should we announce as our external address? - 1 [lo ] 127.0.0.1 - 2 [ens3 ] 192.168.112.254 (default: 192.168.112.254) ext_ip.advertised> 2
Q:
Found X interface(s). Which one should we announce as our inter-service communication address?A: Choose the interface for inter-service communication.
Found 2 interface(s). Which one should we announce as our inter-service communication address? - 1 [lo ] 127.0.0.1 - 2 [ens3 ] 192.168.112.254 (default: 192.168.112.254) inter_ip.advertised> 2
Q:
Please select FindFace CIBR components to install:A: Choose FindFace CIBR components to install. By default, all components are subject to installation. You can leave it as is by entering
done, or select specific components. Whenever you have to make a selection, first, deselect all the listed components by entering-*in the command line, then select required components by entering their sequence number (keyword), for example:1 7 13, etc. Enterdoneto save your selection and proceed to another step.Warning
The
pausecomponent hosts a network namespace for other components. We do not recommend excluding it from installation, as this will leave the remaining components without a network namespace.If you exclude the
pausecomponent intentionally, make sure to edit the/opt/findface-cibr/docker-compose.yamlfile and provide a host name for each service in thenetwork_modeparameter.Please select FindFace CIBR components to install: - 1 [v] findface-data - Recognition models ... ... Enter keyword to select matching choices or -keyword to clear selection. Enter "done" to save your selection and proceed to another step. components> done
Specific questions related to the selected components: acceleration type, the required number of component instances, neural network models, etc. If you are experiencing a difficulty answering them, try to find an answer in this documentation, or submit your question to support@ntechlab.com.
Q:
Please set findface-cibr admin passwordA: Set the Super Administrator (
superuser) password.Please set findface-cibr admin password findface-multi-admin-password> admin
The installer will pull the FindFace CIBR images from the Ntechlab registry and start the associated services in Docker containers.
Perform the post-deployment procedures.
Tip
To install the same configuration of FindFace CIBR on a different host, use the automatic deployment from the installation file. In this case, you won’t have to answer the installation questions again. The exact path to the installation file is displayed right after the last question, before the installer starts active progress:
[I 2023-10-29 14:19:27,189 main:142] Your answers were saved to /tmp/findface-installer-8upq3abq.json
Be sure to remove fields *.config, exp_ip, and int_ip before installing FindFace CIBR on a host with a different IP address.
To launch the automatic deployment from the /tmp/<findface-installer-*>.json file, execute:
sudo ./<findface-*>.run -f /tmp/<findface-installer-*>.json
Installation of Neural Network Models
To detect and recognize faces and face attributes, findface-extraction-api uses neural networks.
If you want to manually initiate the installation of neural network models, use the console installer as follows:
Execute the
findface-*.runfile.Note
Be sure to specify the actual file name instead of
findface-*.sudo ./findface-*.run
Product to install:
FindFace CIBRSelect the installation type:
Fully customized installation.Select a FindFace CIBR component to install:
findface-data. To do so, first, deselect all the listed components by entering-*in the command line, then select the required component by entering its sequence number (keyword). Enterdoneto save your selection and proceed to the next step.In the same manner, select models to install. After that, the installation process will automatically begin.
You can find installed models for the face and face attribute recognition at /opt/findface-cibr/models/. See Neural Networks Summary.
Post-deployment Procedures and How-to’s
After you are finished with the FindFace CIBR deployment, perform the procedures below.
In this section:
Specify Time Zone
The time zone on the FindFace CIBR server determines the time in reports, logs, and names of such FindFace CIBR artifacts as detection full frames and thumbnails, etc.
The time zone is specified in the /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py configuration file, either in the Region/Country/City or Etc/GMT+H format. The best way to do so is to copy/paste your time zone from this table on Wikipedia.
sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py
# time zone
TIME_ZONE = 'America/Argentina/Buenos_Aires'
Restart the findface-cibr-findface-multi-legacy-1 container.
sudo docker container restart findface-cibr-findface-multi-legacy-1
License Instance
FindFace CIBR provides several licensing options. Whichever option you choose, you upload the FindFace CIBR license file via the main web interface http://<Host_IP_address>/#/license. To access the web interface, use the superuser credentials.
Important
Do not disclose the superuser (Super Administrator) credentials to others. To administer the system, create a new user with administrator privileges. Whatever the role, the Super Administrator cannot be deprived of its rights.
Refer to the Licensing section to learn about the licensing options available.
Configure Logging
By default, the FindFace CIBR processes are logged to Docker container logs, which can be accessed via the docker logs and docker service logs commands. In addition, Docker uses the json-file logging driver, which caches container logs in JSON. You can configure Docker to use another logging driver, choosing from the multiple logging mechanisms available. See Logging to learn how to do it.
Useful Docker Commands
In order to efficiently and easily administer FindFace CIBR, you must have extensive knowledge and skills with Docker. If you’re new to Docker, get started with the commands below. Then explore the Docker documentation for additional skills.
View all Docker containers, including the stopped ones:
docker ps -a
To get a more compact and understandable output, execute:
docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.State}}"
To extend the previous output, execute:
docker ps --format='{{json .}}' | jq
Restart the Docker service:
sudo systemctl restart docker
View a container log if the
journaldlogging driver is enabled:journalctl CONTAINER_NAME=findface-cibr-findface-multi-legacy-1 -f
Stop a Docker container:
sudo docker container stop <container_name>/<container_id>
Stop all Docker containers:
sudo docker container stop $(sudo docker ps -a -q)
Start a Docker container:
sudo docker container start <container_name>/<container_id>
Start all Docker containers:
sudo docker container start $(sudo docker ps -a -q)
The FindFace CIBR
docker-compose.yamlfile can be viewed as such:cat /opt/findface-cibr/docker-compose.yaml
FindFace CIBR configuration files can be found here:
cd /opt/findface-cibr/configs/
Once you made changes to a configuration file, restart a relevant container by executing:
sudo docker container restart <container_name>/<container_id>
Enter a running Docker container to execute a command in it:
sudo docker container exec -it <container_name> /bin/bash
Stop and remove all FindFace CIBR containers:
cd /opt/findface-cibr/ sudo docker-compose down
Build, recreate, and start FindFace CIBR containers:
cd /opt/findface-cibr/ sudo docker-compose up -d
Remove FindFace CIBR Instance
If you deployed FindFace CIBR standalone from the installer, use the uninstall.sh script integrated into the installer file to remove your instance.
Important
Make sure to back up your instance before uninstalling it if you plan to restore FindFace CIBR and its data later on.
Run the uninstall.sh script from the /opt/findface-cibr/ folder:
cd /opt/findface-cibr/
sudo /opt/findface-cibr/uninstall.sh /opt/findface-cibr/
You will be asked a question:
Q: This script will remove all docker containers, images, volumes, config files and directory "/opt/findface-cibr/?". Do you want to proceed(y/n)?:
A: Answer y to remove the instance.
In case your FindFace CIBR deployment is not typical, and you are unable to use the automatic uninstaller script, remove all product components manually. The following command replicates the uninstall.sh script behavior:
sudo docker-compose -f /opt/findface-cibr/docker-compose.yaml down -v --rmi all
sudo rm -rf /opt/findface-cibr/
Administration and Configuration
Licensing
In this chapter:
Licensing Principles
The overall number of extracted feature vectors.
Note
The feature vectors are extracted from objects detected in the video, from images in the record index, and user photos, and when building so-called cluster centroids.
The licensing scheme is the following:
Events: 1 event of video object detection = 1 object in a license.
Record Index: 1 photo in a record = 1 object in a license.
Clusters: 1 person = 1 object in a license.
Users: 1 photo of a user = 1 object in a license.
The number of video sources currently in use (i.e., active video processing jobs for video files).
The number of model instances in use in the
findface-extraction-apiservice.Face attribute recognition: gender/age/emotions/glasses/beard/face mask/etc.
You can choose between the following licensing methods:
The online licensing is provided by interaction with the NtechLab Global License Manager
license.ntechlab.comand requires a stable internet connection, DNS, and open port 443 TCP. Upon being disconnected from the internet, the system will continue working off-grid for 4 hours.
Note
It is possible to prolongate the off-grid period for up to 2 days. Inform your manager if you need that.
The offline licensing via a USB dongle requires a USB port on the physical server with the
findface-ntlsservice (license server in the FindFace core).The offline licensing via hardware fingerprint requires Sentinel drivers installed on the physical server with the
findface-ntlsservice.
Important
For the system to function, a single instance of findface-ntls should be enough. If your system requires more license servers, contact your NtechLab manager beforehand to prevent your system from being blocked.
View and Update License
After installing FindFace CIBR, upload the license file you obtained from the manager into the system. To do so, navigate to .
Use the same tab to consult current licensing information and upgrade your license.
Offline Licensing via USB dongle
To implement the licensing via a USB dongle, do the following:
Inform your manager that you intend to apply this licensing method and request your USB dongle and a license file.
Open the
/opt/findface-cibr/docker-compose.yamlconfiguration file.sudo vi /opt/findface-cibr/docker-compose.yaml
Add the line
privileged: true. Mount the/devdirectory into thefindface-cibr-findface-ntls-1container by listing it in the volumes of thefindface-ntlssection. As a result, the entire section will look as follows:findface-ntls: command: [--config=/etc/findface-ntls.cfg] image: docker.int.ntl/ntech/universe/ntls:ffserver-9.230407.1 network_mode: service:pause privileged: true restart: always user: root volumes: ['./configs/findface-ntls/findface-ntls.yaml:/etc/findface-ntls.cfg:ro', './data/findface-ntls:/ntech/license', '/dev:/dev']
Rebuild all FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose down sudo docker-compose up -d
Insert the USB dongle into a USB port.
Upload the license file on the License tab.
Offline Licensing via Hardware Fingerprint
Note
Sentinel is a type of offline licenses that, unlike guardant licenses, do not require any physical media for its work.
Glossary:
Sentinel is a software protection and licensing system by Thales. It allows you to implement offline licensing without access to a global server.
The C2V file is a file, containing data about a hardware fingerprint of the client’s machine, for binding the license only to this machine. This file is generated by the sentinel library. The C2V file is generated on the client’s machine where the license key will be installed later.
To implement the fingerprint licensing, do the following:
Inform your manager that you intend to apply this licensing method and request your unique license id. The manager will also supply you with the
findface-sentinel-lib_*.debpackage necessary for the FindFace CIBR and Sentinel integration.Install the Sentinel drivers on the physical server with the
findface-ntlscomponent.Do the following:
Download Sentinel drivers from the official website.
Unzip the downloaded archive and browse to it.
tar -xvzf Sentinel_LDK_Linux_Runtime_Installer_script.tar.gz cd Sentinel_LDK_Linux_Runtime_Installer_script/
There is another archive
aksusbd-*.tar.gzinside the archive. Unzip it and browse to the resulting directory.tar -xvzf aksusbd-*.tar.gz cd aksusbd-*/
Run the installation command.
sudo ./dinst
Run and check the statuses of the Sentinel services.
sudo systemctl start aksusbd.service hasplmd.service sudo systemctl status aksusbd.service hasplmd.service
Mount the
/var/hasplmand/etc/hasplmdirectories into thefindface-cibr-findface-ntls-1container. To do so, open the/opt/findface-cibr/docker-compose.yamlconfiguration file and list them in the volumes of thefindface-ntlssection.sudo vi /opt/findface-cibr/docker-compose.yaml findface-ntls: ... volumes: ['./configs/findface-ntls/findface-ntls.yaml:/etc/findface-ntls.cfg:ro', './data/findface-ntls:/ntech/license', '/var/hasplm:/var/hasplm', '/etc/hasplm:/etc/hasplm']
Rebuild all FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose down sudo docker-compose up -d
Put the
findface-sentinel-lib_*.debpackage received from your manager into some directory on the same host. Install the package.sudo dpkg -i /path/to/findface-sentinel-lib_*.deb
In the FindFace CIBR web interface, navigate to . Take a hardware fingerprint (C2V file) by clicking the Download C2V for activation button.
Tip
If you prefer working with the console, you can send the following API request to
findface-ntlsinstead:curl <findface-ntls-server-ip>:3185/c2v >my_pc.c2v
Send the License ID and the C2V file to your manager and receive your license file in return.
Upload the license file on the License tab.
General Settings
The FindFace CIBR general settings, such as generic confidence thresholds for face recognition and thumbnail JPEG quality, determine your system functioning and resource consumption.
To configure the general settings, navigate Settings → General. After you are finished with adjustments, click Update. Find the detailed explanation of each general setting below.
In this section:
Generic Confidence Threshold
FindFace CIBR verifies that selected faces belong to the same person (i.e. match), based on the pre-defined confidence threshold. The default threshold is set to the optimum value. If necessary, you can change it.
Note
The higher the threshold, the less a chance that a wrong person will be positively verified, however, some valid photos may also fail verification.
Tip
You can configure the confidence thresholds individually for each watch list.
Important
The default generic confidence threshold is optimal for the majority of recognition cases. We do not recommend changing it on your own. Be sure to consult with our technical experts prior (support@ntechlab.com).
Thumbnail JPEG Quality
Subject to JPEG quality, thumbnails may take up a significant amount of disc volume. Use the General tab to configure the parameter.
User Management and System Security
Important
Although FindFace CIBR provides tools to ensure its protection from unauthorized access, they are not replacing a properly configured firewall. Be sure to use a firewall to heighten the FindFace CIBR network protection.
Role and User Management
In this chapter:
Predefined Roles
FindFace CIBR provides the following predefined roles:
Administrator is granted full access to the FindFace CIBR functionality, integrative and administrative tools.
Important
Whatever the role, the first administrator (Super Administrator) cannot be deprived of its rights.
Operator is granted full access to the FindFace CIBR functionality.
User is granted rights to modify their profile and manage cases. The other functions are available read-only.
You can change the predefined roles privileges, as well as create various custom roles.
Create Custom Role in UI
To create a custom role in the web interface, do the following:
Navigate Settings -> Roles.
Click + Add new role.
On the Information tab, specify the role name. Save the role.
After saving the role, you will see the following tabs appear next to the Information tab:
Watch Lists: role privileges for specific watch lists
Permissions: role privileges for entire system functions and entities
Set role privileges, subject to your needs. Note that there is a distinction between role privileges for a specific watch list and a system entity with the name
watchlist. For example, if you setOfffor a certain watch list on the Watch lists tab, users with this role won’t be able to work with this very watch list. Deselecting all checkboxes for thewatchlistentity on the Permissions tab will prevent users from viewing and working with all watch lists.The full list of the FindFace CIBR entities which are used in the current version is as follows:
all_own_sessions: all sessions of the current user on different devicesNote
If relevant permissions for this entity are set, users will be able to view (
view) and close (delete) all their sessions on different devices. Otherwise, users will be only allowed to view and close their session on the current device. Working with sessions takes place on the Sessions tab (Settings).case: case filedailysearchevent: daily searchdeviceblacklistrecord: blocklistfaceobject: face photo in a recordgroup: roleshumancard: record of an individualremotemonitoringrecord: remote monitoringreport: reportsearchrequest: remote searchupload: item (photo) in batch photo uploaduploadlist: list of photos in batch uploaduser: uservideoarchive: object identification in video fileswatchlist: watch list
You can also enable and disable rights for the following functionality:
batchupload_cards: bulk record uploadchange_runtimesetting: changing the FindFace CIBR general settingsview_auditlog: viewing and working with the audit logsconfigure_ntls: configuration of thefindface-ntlslicense serverview_runtimesetting: viewing the FindFace CIBR general settings
Save the changes.
Primary and Additional User Privileges
You can assign privileges to a user by using roles:
Primary role: main user role, mandatory for assignment. You can assign only one primary role to a user.
An additional user role, optional for assignment. You can assign several roles to one user. The rights associated with the additional roles will be added to the primary privileges.
All users belonging to a particular primary role automatically get access to video archives within the group and watch lists (and records in the watch list) created by a user with the same primary role, subject to the privileges defined by their additional role(s).
See also
Create User Account Manually
To create a user account manually, do the following:
Navigate Settings -> Users.
Click + Add new user.
On the Information tab, specify user data such as name, login, and password. If necessary, add a comment.
Note
When setting a password, mind password requirements:
at least 8 characters long
not only numerals
not within the list of 20000 commonly used passwords
not similar to other user attributes
only Latin letters, numerals, and special characters are allowed
From the Roles drop-down menu, select one or several user roles. Set one of them as the Primary role.
On the Photos tab, attach user’s photo(s).
Save the user account.
Work with Roles and Users via Console
In case predefined roles have been removed from the system, use the following command to create them:
sudo docker exec -it findface-cibr-findface-multi-identity-provider-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py create_groups
To create a user with Super Administrator rights (superuser), execute the following command, mind that password is a required argument:
sudo docker exec -it findface-cibr-findface-multi-identity-provider-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py create_default_user --password <password>
Deactivate or Delete Users
In order to deactivate a user, move the Active slider to inactive position on the user list (Settings -> Users).
If you are going to deactivate multiple users, select them on the user list and then click Deactivate selected.
To delete users from FindFace CIBR, select them on the user list and then click Delete selected.
Enable Data Encryption
To ensure data security, we recommend enabling SSL encryption. Do the following:
On the host system, create the nginx configuration directory with the subdirectory that will be used to store all the SSL data:
sudo mkdir -p /etc/nginx/ssl/
Create the SSL key and certificate files. When using self-signed certificate, use the following command:
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/my-example-domain.com.key -out /etc/nginx/ssl/my-example-domain.com.crt
You will be asked a few questions about your server in order to embed the information correctly in the certificate. Fill out the prompts appropriately. The most important line is the one that requests the
Common Name. You need to enter the domain name or public IP address that you want to be associated with your server. Both of the files you created (my-example-domain.com.keyandmy-example-domain.com.crt) will be placed in the/etc/nginx/ssl/directory.When using CA-certificate, add the certificate path to volumes for the
findface-video-workerservice, add the CA-certificates installation and update the root certificate store in the service container.Open the
/opt/findface-cibr/docker-compose.yamlfile:sudo vi /opt/findface-cibr/docker-compose.yaml
Locate the
findface-video-workersection and adjust it to make sure it looks as follows.For CPU:
findface-video-worker: entrypoint: ["sh", "-c", "apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends --yes ca-certificates && update-ca-certificates && exec /tini -- /findface-video-worker-cpu --config=/etc/findface-video-worker.yaml"] depends_on: [findface-video-manager, findface-ntls, mongodb] image: docker.int.ntl/ntech/universe/video-worker-cpu:ffserver-9.230407.1 logging: {driver: journald} network_mode: service:pause restart: always volumes: ['./configs/findface-video-worker/findface-video-worker.yaml:/etc/findface-video-worker.yaml:ro', './models:/usr/share/findface-data/models:ro', './cache/findface-video-worker/models:/var/cache/findface/models_cache', './cache/findface-video-worker/recorder:/var/cache/findface/video-worker-recorder', '/etc/nginx/ssl/my-example-domain.crt:/usr/local/share/ca-certificates/my-example-domain.crt:ro']
For GPU, it will be enough to add the path to the certificate and update the root certificate store:
findface-video-worker: entrypoint: ["sh", "-c", "update-ca-certificates && exec /tini -- /findface-video-worker-gpu --config=/etc/findface-video-worker.yaml"] depends_on: [findface-video-manager, findface-ntls, mongodb] environment: [CUDA_VISIBLE_DEVICES=0] image: docker.int.ntl/ntech/universe/video-worker-gpu:ffserver-9.230407.1 logging: {driver: journald} network_mode: service:pause restart: always runtime: nvidia volumes: ['./configs/findface-video-worker/findface-video-worker.yaml:/etc/findface-video-worker.yaml:ro', './models:/usr/share/findface-data/models:ro', './cache/findface-video-worker/models:/var/cache/findface/models_cache', './cache/findface-video-worker/recorder:/var/cache/findface/video-worker-recorder', '/etc/nginx/ssl/my-example-domain.crt:/usr/local/share/ca-certificates/my-example-domain.crt:ro']
Important
For CPU version, the configuration requires internet access. If there is no access, please, contact our support team (support@ntechlab.com).
Warning
For CPU version, the startup time will increase by ~15 seconds for the
findface-video-workercontainer.Rebuild all FindFace CIBR containers.
cd /opt/findface-cibr/ docker-compose down docker-compose up -d
Configure nginx to use SSL. Open the nginx configuration file
/opt/findface-cibr/configs/findface-multi-ui/nginx-site.conf. Apply the following modifications to the file:Add the new
server {...}section that contains the URL replacement rule. In therewrite ^(.*) https://…line, replaceip_address_server_ffcibrwith IP address of the server where FindFace CIBR is installed.server { listen 80; server_name my-example-domain.com www.my-example-domain.com; rewrite ^(.*) https://ip_address_server_ffcibr$1 permanent; access_log off; }Comment out the following lines in the existing
server {...}section:# listen 80 default_server; # listen [::]:80 default_server;
Add the following lines, including the paths to the certificate and the key, to the existing
server {...}section:listen 443 ssl; ssl_certificate /etc/nginx/ssl/my-example-domain.com.crt; ssl_certificate_key /etc/nginx/ssl/my-example-domain.com.key;
The example of the configuration file
/opt/findface-cibr/configs/findface-multi-ui/nginx-site.confwith correctly configured SSL settings is shown below:upstream ffsecurity { server 127.0.0.1:8002; } upstream ffsecurity-ws { server 127.0.0.1:8003; } upstream ffsecurity-django { server 127.0.0.1:8004; } upstream audit { server 127.0.0.1:8012; } upstream identity-provider { server 127.0.0.1:8022; } map $http_upgrade $ffsec_upstream { default "http://ffsecurity-ws"; "" "http://ffsecurity"; } server { listen 80; server_name my-example-domain.com www.my-example-domain.com; rewrite ^(.*) https://my-example-domain.com$1 permanent; access_log off; } server { # listen 80 default_server; # listen [::]:80 default_server; listen 443 ssl; ssl_certificate /etc/nginx/ssl/my-example-domain.com.crt; ssl_certificate_key /etc/nginx/ssl/my-example-domain.com.key; root /var/lib/findface-security; autoindex off; server_name _; location = / { alias /usr/share/findface-security-ui/; try_files /index.html =404; } location /static/ { } location /uploads/ { # internal; # uncomment if you intend to enable OVERPROTECT_MEDIA add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' '*'; add_header 'Access-Control-Allow-Headers' '*'; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range'; add_header 'Access-Control-Max-Age' 2592000; location ~ /card/(?<card_type>[a-zA-Z]+)/(?<card_id>[0-9]+)/attachments/(.*)$ { add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' '*'; add_header 'Access-Control-Allow-Headers' '*'; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range'; add_header 'Access-Control-Max-Age' 2592000; add_header 'Content-Disposition' 'attachment'; add_header 'Content-Security-Policy' 'sandbox'; } } location /ui-static/ { alias /usr/share/findface-security-ui/ui-static/; } location /doc/ { alias /opt/findface-security/doc/; } location /api-docs { alias /opt/findface-security/rapidoc; index index.html; } location /api-docs/ { alias /opt/findface-security/rapidoc/; try_files $uri index.html =404; } location ~ /videos/(?<video_id>[0-9]+)/upload/(.*)$ { client_max_body_size 15g; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://ffsecurity; } location @django { internal; client_max_body_size 1g; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_read_timeout 5m; proxy_pass http://ffsecurity-django; } # location /v1/video-liveness { # add_header Access-Control-Allow-Headers "*" always; # add_header Access-Control-Allow-Methods "*" always; # add_header Access-Control-Allow-Origin "*" always; # # if ($request_method = 'OPTIONS') { # return 204; # } # # client_max_body_size 300m; # proxy_set_header Host $http_host; # proxy_set_header X-Forwarded-For $remote_addr; # proxy_set_header X-Forwarded-Proto $scheme; # proxy_pass http://127.0.0.1:18301; # proxy_read_timeout 5m; # } location / { client_max_body_size 1g; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_pass $ffsec_upstream; proxy_read_timeout 5m; location ~ ^/(cameras|videos|vms|external-vms).*/stream/?$ { proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://ffsecurity; } location ~ ^/streams/(.*)$ { internal; proxy_pass $1$is_args$args; } location /audit-logs { proxy_pass http://audit; } location ~ ^/(auth|ad_groups|cproauth|groups|permissions|sessions|users|user-face|device-blacklist-records) { proxy_pass http://identity-provider; } } # location /users/me/ad { # # proxy_pass <FFmulti_address>/auth/ad_login/; e.g http://127.0.0.1/auth/ad_login/; # proxy_method POST; # # proxy_set_header X-Real-IP $remote_addr; # proxy_set_header Host $http_host; # proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # proxy_set_header Authorization $http_authorization; # proxy_pass_header Authorization; # proxy_no_cache 1; # proxy_cache_bypass 1; # # auth_gss on; # auth_gss_realm <REALM>; # e.g. TESTNTL.LOCAL; # auth_gss_keytab <path/to/file.keytab>; # e.g. /var/lib/web.keytab # auth_gss_service_name <service_name>; # e.g. HTTP/web.testntl.local; # auth_gss_allow_basic_fallback on; # } }Copy the generic nginx configuration file
nginx.conffrom thefindface-cibr-findface-multi-ui-1container to the/etc/nginx/directory:sudo docker cp findface-cibr-findface-multi-ui-1:/etc/nginx/nginx.conf /etc/nginx/nginx.conf
In the configuration file
/etc/nginx/nginx.conf, find theSSL Settingssection and append the following lines:ssl_session_cache shared:SSL:10m; ssl_session_timeout 1h;
In the
/opt/findface-cibr/docker-compose.yamlfile, mount the SSL-encryption data directory/etc/nginx/ssl/and the configuration file/etc/nginx/nginx.confof the host system into thefindface-cibr-findface-multi-ui-1container:Open the
/opt/findface-cibr/docker-compose.yamlfile:sudo vi /opt/findface-cibr/docker-compose.yaml
Locate the
findface-multi-uisection and adjust it to make sure it looks like this:findface-multi-ui: depends_on: [findface-multi-legacy] image: docker.int.ntl/ntech/multi/multi/ui-cibr:ffcibr-2.1.1 network_mode: service:pause restart: always volumes: ['./configs/findface-multi-ui/nginx-site.conf:/etc/nginx/conf.d/default.conf:ro', './data/findface-multi-legacy/uploads:/var/lib/findface-security/uploads', '/etc/nginx/ssl:/etc/nginx/ssl', '/etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro']
Edit the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file.In the
ROUTER_URLandIMAGE_CROP_URLparameters, substitute thehttp://prefix withhttps://.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py ... 'ROUTER_URL': 'https://127.0.0.1', 'IMAGE_CROP_URL': 'https://127.0.0.1', ...
If you use a CA-certificate, specify in the
ROUTER_URLparameter the domain for which the certificate was created:'ROUTER_URL': 'https://my-example-domain.com'
Add
https://my-example-domain.comaddress to theEXTERNAL_ADDRESSparameter:... EXTERNAL_ADDRESS = 'https://my-example-domain.com' ...
Open the
/etc/hostsfile on the server where FindFace CIBR is installed and add the following line:sudo vi /etc/hosts ... 127.0.0.1 my-example-domain.com
In the system where you use a browser to interact with FindFace CIBR navigate to the
hostsfile. Add IP address of the server that hosts FindFace CIBR instead of theip_address_server_ffcibr. Replacemy-example-domain.comwith your domain address - the same way you did it in the previous steps.For Linux OS do the following:
sudo vi /etc/hosts ... *ip_address_server_ffcibr* my-example-domain.com
If you use Windows OS, run
C:\Windows\System32\drivers\etc\hostsas an administrator. Add the following line to thehostsfile:*ip_address_server_ffcibr* my-example-domain.com
Restart the containers:
cd /opt/findface-cibr/ sudo docker-compose down sudo docker-compose up -d
If you use self-signed certificate, disable SSL certificate verification for uploaded videos:
Navigate to the Videos within a case.
Click on the uploaded video.
On the Advanced tab, deselect Verify SSL certificate.
List of User Sessions. Blocklist
In this chapter:
FindFace CIBR allows you to monitor user sessions and learn associated data, such as the connected device UUID, type of user interface, IP address, last ping time, and so on.
If necessary, you can add a device to the blocklist without deactivating the user account. The device block may come in handy in various situations. For example, if you want users to access the system only from their workplaces. Use the blocklist functionality to take your system safety to the next level.
Grant Permissions to Work with Sessions
A user’s access to the list of sessions depends on the granted permissions:
Administrator: can view and close sessions of all users
User with the
all_own_sessionspermissions: can view/close all sessions initiated with their usernameUser without the
all_own_sessionspermissions: can only view/close their current session
View User Sessions
To view the list of user sessions, navigate Settings -> Sessions.
Each session record provides the following data:
device UUID
username
type of the user interface (mobile/web)
device information
IP address
status (online, offline, blocked)
last ping time
Use the filter panel above the list of sessions to set up the search conditions.
To close a session, select it in the list and click Terminate.
Block Device
The list of blocked devices is available on the Blocklist Records tab.
You can add a device to the blocklist on the Sessions tab. Blocking a device leads to the user’s automatic log-out.
To block a device, do the following:
Select the relevant session record(s).
Click Block.
Specify the reason for the device to be blocked (mandatory) and the block expiry date (optional). If an expiration date is not specified, the block will be permanent.
Click Save.
Allowed File Extensions in Records
By default, you can attach a file of any extension to a record. It is possible to strengthen your system safety by creating the allowlist of file extensions. It will prevent your users from uploading files of unwanted formats, including those that might contain hidden malicious code, such as .js, .swf, and such.
To create the allowlist of file extensions, do the following:
Open the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py
In the
FFSECURITYsection, find theCARD_ATTACHMENTS_FILENAME_REGEXPparameter. Set an expression with the allowed file extensions. Any valid Python regular expression will do.Examples:
r'.*\.png': allows only files with the.pngextensionr'.*\(png|jpg)': allows the.pngand.jpgextensionsr'.*': allows all file extensionsNone: allows all file extensions'XXXXXX': uploading files of any extension is prohibited
FFSECURITY = { ... 'CARD_ATTACHMENTS_FILENAME_REGEXP': r'.*\.txt', ... }
Tip
Commenting out the
CARD_ATTACHMENTS_FILENAME_REGEXPparameter also allows all file extensions.Restart the
findface-cibr-findface-multi-legacy-1container.sudo docker container restart findface-cibr-findface-multi-legacy-1
Watch Lists
The appearance of specific individuals in the video is monitored with a set of default and custom watch lists.
Records of individuals are assigned to watch lists. Once a watch list is activated, the system will be looking for each person on it during video processing or remote monitoring.
You can create as many custom watch lists as necessary: wanted, suspects, etc. — subject to your needs.
In this section:
Monitoring Unmatched Faces
FindFace CIBR features a special pre-configured watch list used for monitoring only unmatched faces (faces that do not match any record). This watch list cannot be removed from the system. To edit its settings, navigate to the Settings tab. Click Watch Lists and then click Unmatched.
Create Watch List
To create a custom watch list, do the following:
Navigate Settings → Watch Lists.
Click + Add new watch list.
On the Information tab, specify the watch list name.
From the Color palette, select a color which will be shown in notifications for this list.
Describe the watch list in a comment, if needed.
By default, the generic confidence threshold is applied in all watch lists in the system. To set an individual threshold for the watch list, check Confidence threshold and specify the threshold value.
Important
The default generic confidence threshold is optimal for the majority of recognition cases. We do not recommend changing it on your own. Be sure to consult with our technical experts prior (support@ntechlab.com).
Enable Require acknowledgment if it is mandatory that events associated with the list be manually acknowledged.
Enable Enable sound alert to turn on sound notifications for the list if needed.
(Optional) If you have enabled a daily search, check Collect data location, so all records associated to this watch list may receive daily search events.
On the Permissions tab, assign privileges on the watch list, specifying which user roles are allowed to change/view the watch list settings.
Activate and save the watch list.
Remove Watch List
To remove a custom watch list, delete records associated with it first. Otherwise, the system will return an error and will not delete the watch list.
Default Watch List and Unmatched watch list cannot be removed from the system.
Custom Tabs, Fields, and Filters in Record Index
See also
To create custom fields in the feature vector database, refer to Custom Metadata in Tarantool.
To add custom tabs and fields to the records of individuals, do the following:
Prepare the list of custom tabs and fields you want to add to the records.
Open the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py
Customize the records of individuals. To do so, uncomment the
FFSECURITY->CUSTOM_FIELDS->human_cardsection and modify the exemplary content, considering the following:'items': the list of fields in a record. Describe each field with the following parameters:'name': field’s internal name, string.'default': field’s default value. If a default value exceeds1e14 - 1, use a string data type to specify it, for example,"123123.."instead of123123...'label': field’s label in a record, string.'tab': tab that features the field.'display': display format (formorlist), string or array.'description': field’s description, string.'editable': field’s editability, boolean.'type': field data type, string. Possible values:list: requiresitems, additional parameter for lists (see below), expects objects {id, name} in dictionaries;valuelist: expects elements of primitive types.objectlist: allows for creating arrays of objects of required types.datetime: primitive data type displayed as a datetime list.date: primitive data type displayed as a date picker.boolean: primitive data type displayed as a checkbox.string: primitive data typestring.
additional parameters for lists (type=list, type=valuelist):
multiple: possibility of selecting several items in the list, boolean.items: dictionary used as a data source for the list.allow_create: possibility of adding new items to the list.custom_id: custom field for id (type=list).
additional parameters for object lists (type=objectlist).
object: objects used as a data source for the object list.simple: indicator that the field expects data of a primitive type instead of objects, for example, expects strings with phone numbers.
'filters': the list of search filters associated with the custom fields. Parameters:'name': filter’s internal name,'label': filter’s label in the web interface,'field': associated field in the format[field name].
'tabs': the list of tabs in a record.
FFSECURITY = { ... # -- Custom model fields -- # Edit CUSTOM_FIELDS -> `human_card` section to customize human card fields. ... 'CUSTOM_FIELDS': { 'human_card': { ... 'items': [ { 'name': 'personid', 'default': '', 'label': 'PersonID', 'display': ['list', 'form'], 'description': 'Sigur person ID', 'editable': False }, { 'name': 'firstname', 'default': '', 'label': 'First Name', 'display': ['list', 'form'], 'description': 'Sigur first name', 'editable': False }, { 'name': 'lastname', 'default': '', 'label': 'Last Name', 'display': ['list', 'form'], 'description': 'Sigur last name', 'editable': False }, { 'name': 'version', 'default': '', 'label': 'Version', 'display': ['list', 'form'], 'description': 'Sigur photo version', 'editable': False } ], 'filters': [ { 'name': 'personid', 'label': 'Sigur person ID filter', 'field': 'personid' } ] }, ... }, }
Restart the
findface-cibr-findface-multi-legacy-1container.sudo docker container restart findface-cibr-findface-multi-legacy-1
You will see the custom content appear in the records.
Custom Metadata in Tarantool
It is often necessary to assign additional metadata to the faces extracted from images uploaded to the record index and now stored in the feature vector database.
Customize Meta Fields of Face Objects
To assign custom meta fields to the face objects, do the following:
Prepare the list of custom meta fields to assign.
Open the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py
In the
FFSECURITYsection, uncomment theCUSTOM_FIELDS->face_objectsection and modify the exemplary content, considering the following:field_name: field’s name;type: data type;default: field’s default value. If a default value exceeds1e14 – 1, use a string data type to specify it, for example,"123123.."instead of123123...
FFSECURITY = { ... # -- Custom model fields -- ... # Edit CUSTOM_FIELDS -> `face_object` section to customize face object fields. ... # 'CUSTOM_FIELDS': { ... 'face_object': { 'items': [ { "field_name": "tag_name_1", "type": "string", "default": "change_me" }, { "field_name": "tag_name_2", "type": "uint", "default": 123 }, { "field_name": "tag_name_3", "type": "bool", "default": True }, ] } }, }
Add the new meta fields to the feature vector database structure.
Restart the
findface-cibr-findface-multi-legacy-1container.sudo docker container restart findface-cibr-findface-multi-legacy-1
You can work with the new meta fields through HTTP API using the
objects/faces/methods.
See also
To create custom tabs, fields, and filters in records, refer to Custom Tabs, Fields, and Filters in Record Index.
Enable Face Attribute Recognition
Face attributes, such as age, gender, emotions, etc., are present in the filter set for detected face analysis during a case investigation.
Face attribute recognition can be automatically enabled and configured during the FindFace CIBR installation. If you skip this step, you can manually do it later. Face attribute recognition works on both GPU- and CPU-acceleration.
Do the following:
Open the
/opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yamlconfiguration file.sudo vi /opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml
Specify the relevant recognition models in the
extractorssection, as shown in the example below. Be sure to indicate the right acceleration type for each model, matching the acceleration type offindface-extraction-api: CPU or GPU. Be aware thatfindface-extraction-apion CPU can work only with CPU-models, whilefindface-extraction-apion GPU supports both CPU- and GPU-models.GPU
extractors: ... models: face_age: faceattr/age.v2.gpu.fnk face_beard: faceattr/beard.v0.gpu.fnk face_beard4: '' face_countries47: '' face_emben: face/mango_320.gpu.fnk face_emotions: faceattr/emotions.v1.gpu.fnk face_eyes_attrs: '' face_eyes_openness: '' face_gender: faceattr/gender.v2.gpu.fnk face_glasses3: faceattr/glasses3.v0.gpu.fnk face_glasses4: '' face_hair: '' face_headpose: '' face_headwear: '' face_highlight: '' face_liveness: faceattr/liveness.web.v0.gpu.fnk face_luminance_overexposure: '' face_luminance_underexposure: '' face_luminance_uniformity: '' face_medmask3: faceattr/medmask3.v2.gpu.fnk face_medmask4: '' face_mouth_attrs: '' face_quality: faceattr/quality_fast.v1.gpu.fnk face_scar: '' face_sharpness: '' face_tattoo: '' face_validity: ''
CPU
extractors: ... models: face_age: faceattr/age.v2.cpu.fnk face_beard: faceattr/beard.v0.cpu.fnk face_beard4: '' face_countries47: '' face_emben: face/mango_320.cpu.fnk face_emotions: faceattr/emotions.v1.cpu.fnk face_eyes_attrs: '' face_eyes_openness: '' face_gender: faceattr/gender.v2.cpu.fnk face_glasses3: faceattr/glasses3.v0.cpu.fnk face_glasses4: '' face_hair: '' face_headpose: '' face_headwear: '' face_highlight: '' face_liveness: faceattr/liveness.web.v0.cpu.fnk face_luminance_overexposure: '' face_luminance_underexposure: '' face_luminance_uniformity: '' face_medmask3: faceattr/medmask3.v2.cpu.fnk face_medmask4: '' face_mouth_attrs: '' face_quality: faceattr/quality_fast.v1.cpu.fnk face_scar: '' face_sharpness: '' face_tattoo: '' face_validity: ''
The following extraction models are available:
Extractor
Acceleration
Configure as follows
age
CPU
face_age: faceattr/age.v2.cpu.fnkGPU
face_age: faceattr/age.v2.gpu.fnkbeard
CPU
face_beard: faceattr/beard.v0.cpu.fnkGPU
face_beard: faceattr/beard.v0.gpu.fnkface feature vector
CPU
face_emben: face/mango_320.cpu.fnkGPU
face_emben: face/mango_320.gpu.fnkgender
CPU
face_gender: faceattr/gender.v2.cpu.fnkGPU
face_gender: faceattr/gender.v2.gpu.fnkemotions
CPU
face_emotions: faceattr/emotions.v1.cpu.fnkGPU
face_emotions: faceattr/emotions.v1.gpu.fnkglasses
CPU
face_glasses3: faceattr/glasses3.v0.cpu.fnkGPU
face_glasses3: faceattr/glasses3.v0.gpu.fnkface liveness
CPU
face_liveness: faceattr/liveness.web.v0.cpu.fnkGPU
face_liveness: faceattr/liveness.web.v0.gpu.fnkface mask
CPU
face_medmask3: faceattr/medmask3.v2.cpu.fnkGPU
face_medmask3: faceattr/medmask3.v2.gpu.fnkface quality
CPU
face_quality: faceattr/quality_fast.v1.cpu.fnkGPU
face_quality: faceattr/quality_fast.v1.gpu.fnkTip
To leave a model disabled, pass the empty value
''to the relevant parameter. Do not remove the parameter itself. Otherwise, the system will be searching for the default model. E.g., to disable emotions and face mask recognition, pass the empty value to the corresponding extraction models:extractors: ... models: ... face_emotions: '' face_medmask3: ''
Note
You can find face attribute recognition models at
/opt/findface-cibr/models/faceattr/.ls /opt/findface-cibr/models/faceattr/ age.v2.cpu.fnk emotions.v1.cpu.fnk glasses3.v0.cpu.fnk medmask3.v2.cpu.fnk age.v2.gpu.fnk emotions.v1.gpu.fnk glasses3.v0.gpu.fnk medmask3.v2.gpu.fnk beard.v0.cpu.fnk gender.v2.cpu.fnk liveness.web.v0.cpu.fnk quality_fast.v1.cpu.fnk beard.v0.gpu.fnk gender.v2.gpu.fnk liveness.web.v0.gpu.fnk quality_fast.v1.gpu.fnk
Restart the
findface-cibr-findface-extraction-api-1container.sudo docker container restart findface-cibr-findface-extraction-api-1
Enable recognition of face attributes in the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file. In theFFSECURITYsection, specify the face attributes that you want to display for the face recognition events.# make sure that corresponding extractors are licensed # and enabled at findface-extraction-api config file # available features: age, beard, emotions, gender, glasses, medmask 'FACE_EVENTS_FEATURES': ['emotions', 'beard', 'gender', 'age', 'medmask', 'glasses'],
Restart the
findface-cibr-findface-multi-legacy-1container.sudo docker container restart findface-cibr-findface-multi-legacy-1
Integration with Remote Facial Recognition Systems
You can integrate your FindFace CIBR instance with remote facial recognition systems. In this case, the server known as a puppeteer will be pushing records designated for remote alerting to remote servers known as puppets. In return, it will be receiving recognition events matching with those records. You can set up a daily search that allows the puppeteer to receive scheduled events.
This functionality has a large scope of possible applications. One course is tracking offenders’ location and routes and detecting alleged accomplices. Another one is finding missing people. The results are especially great if applied to Public and Transport Safety systems with thousands of cameras.
The current version supports only integration with facial recognition systems from the FindFace family.
In this section:
Sync Schedule
The data between a puppeteer and a puppet are synced in the following way:
The puppeteer delivers designated records to the puppet with an interval specified in the
REMOTE_MONITORING_SYNC_INTERVALparameter (see configuration below).The puppet delivers matching recognition events to the puppeteer as soon as they appear.
Configure Puppeteer
To configure your FindFace CIBR instance to be a puppeteer, do the following:
Open the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file. Make sure that theEXTERNAL_ADDRESSparameter is filled.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py EXTERNAL_ADDRESS = 'http://192.168.0.4'
Note
The value of
EXTERNAL_ADDRESSis defined during deployment.Find the
Puppeteersection.# ============== Puppeteer =============== # INSTALLED_APPS.append('ffsecurity_puppeteer') # PUPPETEER_CONFIG = { # 'UNSAVED_RESULTS_DELETION_TIMEOUT': 3600, # maximum lifetime of search results not saved involuntarily # 'REMOTE_MONITORING_SYNC_INTERVAL': 600, # monitoring data synchronization interval, seconds # 'REMOTE_MONITORING_EVENTS_MAX_AGE': 30*24*60*60, # monitoring events older than this number of days will be # # automatically deleted (every night at 1:17 am by default) # 'ENABLE_DAILY_SEARCH': False, # daily search activation (default False) # 'DAILY_SEARCH_PUSH_HOUR': 2, # daily search cards synchronization hour # 'DAILY_SEARCH_PULL_HOUR': 6, # hour in which results of daily search will be obtained # 'puppets': [ # { # 'id': 'first_puppet', # puppet ID # 'url': 'http://1.1.1.1:8010/', # puppet URL # 'token': 'first_puppet_token', # use pwgen -s 64 1 (should match the token in puppet) # 'facen_model': 'mango_320' # face model in puppet # }, # { # 'id': 'second_puppet', # 'url': 'http://1.1.1.1:8010/', # 'token': 'second_puppet_token', # # # if remote installation has a different face model than the one used in FFSecurity - # # you need to specify its name and ExtractionAPI URL where the corresponding face model is specified # 'facen_model': 'grapefruit_480', # 'extractor': 'http://127.0.0.1:18667', # }, # ] # } #
Uncomment the section as shown in the example below and specify the following parameters:
REMOTE_MONITORING_SYNC_INTERVAL: interval in seconds with which the puppeteer sends designated records to a puppet.REMOTE_MONITORING_EVENTS_MAX_AGE: remote alerts older than this number of days will be automatically deleted on the puppeteer (every night at 1:17 a.m. by default).puppets→id: a puppet ID.puppets→url: IP address and port of a puppet’s principal server.Specify the port as follows:
Leave the default port as is if the puppet represents a public or transport safety system (i.e., it has the
public-securityservice at its core).Switch the default port to
80or do not specify it at all if the puppet is based on thefindface-securityservice (i.e., with FindFace Security or FindFace Multi installed).
puppets→token: token for mutual authentication between the puppeteer and a puppet.Tip
Use the following command to generate a random token.
pwgen -s 64 1
puppets→facen_model: neural network model used on a puppet for face recognition.puppets→extractor: IP address and port of the biometric data extraction service on a puppet if the neural network model for face recognition on the puppet differs from that on the puppeteer.
Leave other parameters in the section commented out.
# ============== Puppeteer =============== INSTALLED_APPS.append('ffsecurity_puppeteer') PUPPETEER_CONFIG = { # 'UNSAVED_RESULTS_DELETION_TIMEOUT': 3600, # maximum lifetime of search results not saved involuntarily 'REMOTE_MONITORING_SYNC_INTERVAL': 600, # monitoring data synchronization interval, seconds 'REMOTE_MONITORING_EVENTS_MAX_AGE': 30*24*60*60, # monitoring events older than this number of days will be # # automatically deleted (every night at 1:17 am by default) # 'ENABLE_DAILY_SEARCH': False, # daily search activation (default False) # 'DAILY_SEARCH_PUSH_HOUR': 2, # daily search cards synchronization hour # 'DAILY_SEARCH_PULL_HOUR': 6, # hour in which results of daily search will be obtained 'puppets': [ { 'id': '1', # puppet ID 'url': 'http://192.168.0.5:8010/', # puppet URL 'token': '1234567890', # use pwgen -s 64 1 (should match the token in puppet) 'facen_model': 'mango_320' # face model in puppet }, { 'id': '2', 'url': 'http://192.168.0.6:8010/', 'token': '0987654321', 'facen_model': 'grapefruit_480', 'extractor': 'http://192.168.0.6:18667', # # # if remote installation has a different face model than the one used in FFSecurity - # # you need to specify its name and ExtractionAPI URL where the corresponding face model is specified }, ] }
If necessary, enable the daily searching by uncommenting and setting
'ENABLE_DAILY_SEARCH': True. Set the schedule for sending records to the puppet and receiving events that matched the records that have been sent.PUPPETEER_CONFIG = { ... 'ENABLE_DAILY_SEARCH': True, # daily search activation (default False) 'DAILY_SEARCH_PUSH_HOUR': 2, # daily search cards synchronization hour 'DAILY_SEARCH_PULL_HOUR': 6, # hour in which results of daily search will be obtained ...
Navigate to the Watch list tab and check
Collect location datafor the watch list of your interest.Restart the
findface-multi-findface-multi-legacy-1container.sudo docker container restart findface-cibr-findface-multi-legacy-1
Configure Puppet
To configure a remote FindFace Multi 2.0+ instance to be a puppet, do the following:
Open the
/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file. Make sure that theEXTERNAL_ADDRESSparameter is filled.sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py EXTERNAL_ADDRESS = 'http://192.168.0.5'
Find the
Vnssection.# ================= Vns ================== # A plugin for using FindFace Security as a puppeteer server # INSTALLED_APPS.append('ffsecurity_vns') # VNS_CONFIG = { # 'USERS': { # 'user1': 'token1', # 'user2': 'token2' # }, # 'MONITORING_THRESHOLD': 0.75, # 'DAILY': { # 'ENABLED': False, # 'THRESHOLD': 0.75, # 'START_TIME': "00:00:00" # } # }
Uncomment the section as shown in the example below and specify the following parameters:
token: token for mutual authentication between the puppet and a puppeteer. You can specify several users and tokens if the puppet is communicating with several puppeteers. You can leave the user names as is.MONITORING_THRESHOLD: confidence threshold in face recognition events sent to a puppeteer.
Leave other parameters in the section commented out.
# ================= Vns ================== # A plugin for using FindFace Security as a puppeteer server INSTALLED_APPS.append('ffsecurity_vns') VNS_CONFIG = { 'USERS': { 'user1': '1234567890' }, 'MONITORING_THRESHOLD': 0.75, # 'DAILY': { # 'ENABLED': False, # 'THRESHOLD': 0.75, # 'START_TIME': "00:00:00" # } }
If you have enabled the daily search in the Puppeteer (see step #4 above), uncomment and enable
'DAILY'parameters. Specify the time for matching the events with the records that were received from the puppeteer.================= Vns ================== A plugin for using FindFace Security as a puppeteer server INSTALLED_APPS.append('ffsecurity_vns') VNS_CONFIG = { ... 'DAILY': { 'ENABLED': True, 'THRESHOLD': 0.75, 'START_TIME': "00:00:00" } }
Restart the
findface-multi-findface-multi-legacy-1container.sudo docker container restart findface-multi-findface-multi-legacy-1
To configure a remote FindFace Multi instance version 1.2 and early to be a puppet, do the following:
Open the
/etc/findface-security/config.pyconfiguration file. Make sure that theEXTERNAL_ADDRESSparameter is filled.sudo vi /etc/findface-security/config.py EXTERNAL_ADDRESS = 'http://192.168.0.5'
Find the
Vnssection.Uncomment the section as shown in the example and specify
tokenandMONITORING_THRESHOLDparameters.If you have enabled the daily search in the Puppeteer, uncomment and enable
'DAILY'parameters. Specify the time for matching the events with the records that were received from the puppeteer.Restart the
findface-securityservice.sudo systemctl restart findface-security.service
Perform migration to sync with puppeteers.
sudo findface-security migrate
See also
Configure Saving Images in Reports
When building reports, you will be able to choose to save the report images as links, thumbnails, or full frames. It is possible to configure the image parameters. To do so, open the /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py configuration file and alter the default JPEG quality and the maximum height of thumbnails and full frames, subject to your free disc space.
sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py
# reports image saving options
'REPORT_THUMBNAIL_JPEG_QUALITY': 75,
'REPORT_THUMBNAIL_MAX_HEIGHT': 100,
'REPORT_FULLFRAME_JPEG_QUALITY': 75,
'REPORT_FULLFRAME_MAX_HEIGHT': 250,
Restart the findface-cibr-findface-multi-legacy-1 container.
sudo docker container restart findface-cibr-findface-multi-legacy-1
Console Bulk Record Upload
In addition to the web interface upload, you can bulk-upload records to the record index via the uploader.py console utility. We recommend preferring this utility over the web interface if the number of uploaded photos is more than 10,000.
Tip
To view the uploader.py help, execute:
docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py --help
Usage: uploader.py [OPTIONS] COMMAND [ARGS]...
Options:
--job FILE Job file (default: enroll-job.db)
--log-level TEXT Log level
--fsync BOOLEAN Call fsync() to prevent data loss on power failure
--help Show this message and exit.
Commands:
add Add items from CSV or TSV file to job
print Print contents of job file as JSON
run Run upload job
docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py add --help
Usage: uploader.py add [OPTIONS] FILES...
Options:
--format [csv|tsv] Input file format - CSV or TSV
--delimiter TEXT Field delimiter - by default it's "\t" for TSV and ","
for CSV
--help Show this message and exit.
docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py print --help
Usage: uploader.py print [OPTIONS]
Print contents of job file as JSON
Options:
--failed Show only failed images
--noface Show only images without detection
--help Show this message and exit.
docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py run --help
Usage: uploader.py run [OPTIONS]
Run upload job
Options:
--parallel INTEGER Number of enroll threads (default: 10)
--api TEXT API url (default: http://127.0.0.1:80/)
[required]
--user TEXT API username [required]
--password TEXT API password [required]
--watch-lists TEXT Comma-separated list of card list ids [required]
--inactive Mark new cards as inactive
--failed Include failed images
--noface Include images without detection
--all-faces Enroll all found faces on each image
--detect-timeout INTEGER Request timeout for detect photos
--logging-delta INTEGER Logging period delta
--help Show this message and exit.
Do the following:
Write the list of photos and metastrings to a CSV or TSV file.
Important
The file used as a metadata source must have the following format:
path to photo | metastring.To prepare a TSV file, you can use a
script, or generate it with python or other utility.Note
Both the script and the command in the examples below create the
images.tsvfile. Each image in the list will be associated with a metastring coinciding with the image file name in the formatpath to photo | metastring.To build a TSV file listing photos, upload the script to your home directory, for example
/home/ubuntu, and run the following command:sudo docker run -it --rm --network host --volume ${PWD}:/home/ubuntu/create_cards --volume /home/ubuntu/photos:/home/ubuntu/photos docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 sh -c "cd /home/ubuntu/create_cards && /opt/findface-security/bin/python3 tsv_builder.py /home/ubuntu/photos"where
/home/ubuntu/photosis a directory with your photos.A TSV file may also be generated using the following command:
python3 tsv_builder.py /home/ubuntu/photos/
You can use a
images.tsvfile as example.Create a job file out of a CSV or TSV file by using the
addutility command. As a result, a fileenroll-job.dbwill be created and saved in a current directory.sudo docker run -it --rm --network host --volume ${PWD}:/home/ubuntu/create_cards docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 sh -c "cd /home/ubuntu/create_cards && /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py add /home/ubuntu/create_cards/images.tsv"The
addutility options:--format: input file format, tsv by default,--delimiter: field delimiter, by default"\t"for TSV, and","for CSV.
Note
A job file represents a sqlite database which can be opened on the sqlite3 console.
Process the job file by specifying the path to the photos (for example,
/home/ubuntu/photos) and passing the necessary arguments. Use the following command:sudo docker run -it --rm --network host --volume ${PWD}:/home/ubuntu/create_cards --volume /home/ubuntu/photos:/home/ubuntu/photos docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 sh -c "cd /home/ubuntu/create_cards && /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py run --user admin --password password --watch-lists 1"The
runutility options:--parallel: the number of photo upload threads, 10 by default. The more threads you use, the faster the bulk upload is completed, however it requires more resources too.--api:findface-securityAPI URL,http://127.0.0.1:80/by default. Mandatory option.--user: login. Mandatory option.--password: password. Mandatory option.--watch-lists: comma-separated list of the watch lists id’s. Mandatory option.--inactive: mark new records as inactive.--failed: should an error occur during the job file processing, correct the mistake and try again with this option.--noface: by default, images classified as having no faces will be assigned theNOFACEstatus and automatically excluded from the upload. To attempt re-detecting faces in such images, re-run the job file with this option. If the re-detection gives a negative result again, an image will be skipped and a relevant record will appear in the upload log.--all-faces: upload all faces from a photo if it features several faces.--detect-timeout: request timeout for detect photos.--logging-delta: logging period delta.
(Optional) Print the job processing results as JSON. If necessary, you can print only failed images/ images without detected faces. Use the following command:
sudo docker run -it --rm --network host --volume ${PWD}:/home/ubuntu/create_cards --volume /home/ubuntu/NTL_impersonated:/home/ubuntu/NTL_impersonated docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 sh -c "cd /home/ubuntu/create_cards && /opt/findface-security/bin/python3 /tigre_prototype/ffsecurity/uploader.py print --noface --failed"The
printutility options:--failed: show only failed images.--noface: show only images without detection.
Maintenance and Troubleshooting
Update to FindFace CIBR 2.1.1
Important
If you have changed the neural network model in FindFace CIBR 1.3, and this neural network model is not included in FindFace CIBR 2.1.1, then it is needed to change it back before upgrading to FindFace CIBR 2.1.1.
To update FindFace CIBR 1.3 to FindFace CIBR 2.1.1, do the following:
Create a backup copy of the old schema of the Tarantool-based feature vector database:
sudo cp /etc/findface-security/tnt_schema.lua /etc/findface-security/old_tnt_schema.lua
Starting from version 2.1.1, one of the most significant differences between FindFace CIBR and earlier versions of the product is the structure of the Tarantool biometric database (so called meta-schema). The new structure is created as a set of spaces, while in previous versions of the product there was only one space by default in the structure of the Tarantool-based database.
Open the
/etc/findface-security/config.pyconfiguration file. Save the values of the following parameters for later use:EXTERNAL_ADDRESS,SECRET_KEY,VIDEO_DETECTOR_TOKEN,ROUTER_URL,CUSTOM_FIELDS.sudo vi /etc/findface-security/config.py EXTERNAL_ADDRESS = "http://172.20.77.58" ... # use pwgen -sncy 50 1|tr "'" "." to generate your own unique key SECRET_KEY = 'c8b533847bbf7142102de1349d33a1f6' FFSECURITY = { 'VIDEO_DETECTOR_TOKEN': '381b0f4a20495227d04185ab02f5085f', ... 'ROUTER_URL': 'http://172.20.77.58', ... # -- Custom model fields -- # Edit CUSTOM_FIELDS -> `human_card` section to customize human card fields. # Edit CUSTOM_FIELDS -> `face_object` section to customize face object fields. # Below is an example with every field type possible. # 'CUSTOM_FIELDS': { # 'human_card': { # 'items': [ # { # 'name': 'personid', # 'default': '', # 'label': 'PersonID', # 'display': ['list', 'form'], # 'description': 'Sigur person ID', # 'editable': False # }, # { # 'name': 'firstname', # 'default': '', # 'label': 'First Name', # 'display': ['list', 'form'], # 'description': 'Sigur first name', # 'editable': False # }, # { # 'name': 'lastname', # 'default': '', # 'label': 'Last Name', # 'display': ['list', 'form'], # 'description': 'Sigur last name', # 'editable': False # }, # { # 'name': 'version', # 'default': '', # 'label': 'Version', # 'display': ['list', 'form'], # 'description': 'Sigur photo version', # 'editable': False # } # ], # 'filters': [ # { # 'name': 'personid', # 'label': 'Sigur person ID filter', # 'field': 'personid' # } # ] # }, # 'face_object': { # 'items': [ # { # "field_name": "tag_name_1", # "type": "string", # "default": "change_me" # }, # { # "field_name": "tag_name_2", # "type": "uint", # "default": 123 # }, # { # "field_name": "tag_name_3", # "type": "bool", # "default": True # }, # ] # } # }, }
Stop the
findface-securityservice.sudo systemctl stop findface-security.service
Create a backup of the Tarantool-based feature vector database in any directory of your choice, for example,
/etc/findface_dump.sudo mkdir -p /etc/findface_dump cd /etc/findface_dump sudo findface-storage-api-dump -config /etc/findface-sf-api.ini
To avoid port conflicts, stop and disable all services before installing a new version.
Note
There are eight shards in the example below. If it differs with the number of shards in your system, adjust the below command accordingly. E.g., for the system with sixteen shards, replace
tarantool@shard-00{1..8}.servicewithtarantool@shard-0{01..16}.service. Get the list of active shards with thels /etc/tarantool/instances.enabled/command.You may stop and disable the services one by one:
sudo systemctl stop postgresql.service sudo systemctl stop postgresql@10-main sudo systemctl stop findface-*.service sudo systemctl stop pgbouncer.service sudo systemctl stop tarantool@shard-00{1..8}.service sudo systemctl stop nats-server.service sudo systemctl stop etcd.service sudo systemctl stop mongod.service sudo systemctl stop mongodb.service sudo systemctl stop memcached.service sudo systemctl stop nginx.service sudo systemctl disable postgresql.service sudo systemctl disable postgresql@10-main sudo systemctl disable pgbouncer.service sudo systemctl disable findface-extraction-api.service sudo systemctl disable findface-security.service sudo systemctl disable findface-security-onvif.service sudo systemctl disable findface-sf-api.service sudo systemctl disable findface-ntls.service sudo systemctl disable findface-video-manager.service sudo systemctl disable findface-video-worker-cpu.service sudo systemctl disable findface-video-worker-gpu.service sudo systemctl disable findface-counter.service sudo systemctl disable findface-liveness-api.service sudo systemctl disable findface-video-streamer-cpu.service sudo systemctl disable findface-video-streamer-gpu.service sudo systemctl disable findface-video-storage.service sudo systemctl disable tarantool@shard-00{1..8}.service sudo systemctl disable nats-server.service sudo systemctl disable etcd.service sudo systemctl disable mongod.service sudo systemctl disable mongodb.service sudo systemctl disable memcached.service sudo systemctl disable nginx.service
Or you may use the following compact commands instead:
sudo systemctl stop postgresql.service postgresql@10-main findface-*.service pgbouncer.service tarantool@shard-00{1..8}.service nats-server.service etcd.service mongod.service mongodb.service memcached.service nginx.service sudo systemctl disable postgresql.service postgresql@10-main pgbouncer.service findface-extraction-api.service findface-security.service findface-security-onvif.service findface-sf-api.service findface-ntls.service findface-video-manager.service findface-video-worker-cpu.service findface-video-worker-gpu.service findface-counter.service findface-liveness-api.service findface-video-streamer-cpu.service findface-video-streamer-gpu.service findface-video-storage.service tarantool@shard-00{1..8}.service nats-server.service etcd.service mongod.service mongodb.service memcached.service nginx.service
Install the FindFace CIBR 2.1.1 instance. Don’t forget to prepare a server first:
See:
After FindFace CIBR installation, stop all containers from the
/opt/findface-cibr/directory.cd /opt/findface-cibr/ sudo docker-compose stop
Open the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file and paste saved on step #2 values for the parametersEXTERNAL_ADDRESS,SECRET_KEY,VIDEO_DETECTOR_TOKEN,ROUTER_URL, andCUSTOM_FIELDSinto it.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py ... # Use pwgen -sncy 50 1|tr "'" "." to generate your own unique key SECRET_KEY = '002231ccb690586f4d33e98322c591bb' ... SERVICE_EXTERNAL_ADDRESS = 'http://172.20.77.58' # EXTERNAL_ADDRESS is used to access objects created inside FFSecurity via external links. EXTERNAL_ADDRESS = 'http://172.20.77.58' ... # findface-video-worker authorization token 'VIDEO_DETECTOR_TOKEN': '8977e1b0067d43f6c908d0bf60363255', ... # findface-video-worker face posting address, # it must be set to either FFSecurity EXTERNAL_ADDRESS (by default) # or findface-facerouter url (in some specific cases) 'ROUTER_URL': 'http://127.0.0.1:80',
Open the old version of the
findface-ntlsconfiguration file available at/etc/findface-ntls.cfgand check it against the new version/opt/findface-cibr/configs/findface-ntls/findface-ntls.yaml. Move all the custom parameters from the old version to the new one. Do the same for other components, e.g., forfindface-extract-api, check/etc/findface-extract-api.iniagainst/opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml, forfindface-sf-api, check/etc/findface-sf-api.iniagainst/opt/findface-cibr/configs/findface-sf-api/findface-sf-api.yaml, etc.sudo vi /etc/findface-ntls.cfg sudo vi /opt/findface-cibr/configs/findface-ntls/findface-ntls.yaml sudo vi /etc/findface-extraction-api.ini sudo vi /opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml sudo vi /etc/findface-sf-api.ini sudo vi /opt/findface-cibr/configs/findface-sf-api/findface-sf-api.yaml
Important
Follow these rules to transfer parameters from the old configuration file to the new one:
The new version 2.1.1 doesn’t support migration of the cluster gallery, so please, use only neural network models that are included in FindFace CIBR 2.1.1.
If a parameter had an empty value in the old configuration file, but has a certain value in the new configuration file, delete its value in the new configuration file.
Keep as is those parameters that were not included in the old configuration file, but are present in the new configuration file.
Modify the Tarantool database structure by applying the
tnt_schema.luaschema from FindFace CIBR 2.1.1.sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 make-tnt-schema | sudo tee /etc/findface-security/tnt_schema.lua
Purge data from all the directories relevant to active shards.
sudo rm /opt/ntech/var/lib/tarantool/shard-*/{index,snapshots,xlogs}/*
Copy the meta-schema of the
face_clusters_spacespace from theold_tnt_schema.luaconfiguration file to the newtnt_schema.luaconfiguration file. An easy way to do it is to follow these steps:12.1. In the new configuration file
/etc/findface-security/tnt_schema.lua, replace the following line at the beginning of the file:cfg_spaces = {
with this one:
spaces = {
12.2. Copy and add
face_clusters_spacespace from theold_tnt_schema.luaold configuration file:face_clusters_space = { meta_scheme = { -- <class 'ffsecurity.entities.cluster.face.models.FaceCluster'>.normalized_id: { default = '', field_type = 'string', id = 1, name = 'normalized_id', }, -- <class 'ffsecurity.entities.cluster.face.models.FaceCluster'>.feat: { default = '', field_type = 'string', id = 2, name = 'feat', }, -- <class 'ffsecurity.entities.cluster.face.models.FaceCluster'>.m:nonnormalized_emben: { default = '', field_type = 'string', id = 3, name = 'm:nonnormalized_emben', }, -- <class 'ffsecurity.entities.cluster.face.models.FaceCluster'>.m:case: { default = '0', field_type = 'unsigned', id = 4, name = 'm:case', }, }, meta_indexes = {'m:case'} },Remove the default configuration file
FindFace.lua, generated by thefindface-tarantool-serverpackage, as it will block the restart, required on the next step.sudo rm -rf /etc/tarantool/instances*/FindFace.lua
Restart the
findface-tarantool-servershards.TNT=$(ls /etc/tarantool/instances.enabled/ | cut -c 7,8,9) for i in $TNT; do sudo systemctl restart tarantool@shard-$i.service ; done
Upon completion of the above steps, the shards will still keep the old galleries created within the
defaultspace, but new spaces (e.g.,ffsec_face_case_events,ffsec_face_case_clustersand so on) will also become available.Restore old data from the backup. The data will be restored as it existed previously: all galleries will stay within the
defaultspace.sudo systemctl start findface-ntls.service cd /etc/findface_dump for x in *.json; do sudo findface-storage-api-restore -config /etc/findface-sf-api.ini < "$x"; done
Start old services
findface-sf-api.service,nginx.service, they will be required during postgresql migration.sudo systemctl start findface-sf-api.service sudo systemctl start nginx.service
Perform PostgreSQL database migrations for FindFace CIBR 2.1.1 compatibility. Do the following:
17.1. Navigate to the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file. In theDATABASES -> defaultsection, temporarily replacePASSWORDwith the old one, used in the/etc/findface-security/config.pyconfiguration file.Important
Make sure to write down the password from the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file. You will need it later.sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'DISABLE_SERVER_SIDE_CURSORS': True, 'NAME': 'ffsecurity', 'HOST': '127.0.0.1', 'PORT': 5439, 'USER': 'ntech', 'PASSWORD': 'XXXXXXXXXXXXXXXX' } }
17.2. On the host system, perform the database migration:
sudo systemctl start postgresql.service sudo systemctl start pgbouncer.service sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py migrate
17.3. Back up an existing database with PostgreSQL, installed on the host system.
cd /opt/findface-cibr/ sudo -u postgres pg_dump --verbose --disable-triggers ffsecurity | sudo tee dump_ffsecurity.sql sudo -u postgres pg_dump -t auth_group -t ffsecurity_adgroupguid -t ffsecurity_deviceblacklistrecord -t ffsecurity_ffsecauthsession -t ffsecurity_grouppermission -t ffsecurity_runtimesetting -t ffsecurity_user -t ffsecurity_user_groups -t ffsecurity_user_user_permissions -t ffsecurity_userkeyvalue -t knox_authtoken -t ffsecurity_watchlistpermission -t ffsecurity_cameragrouppermission -t ffsecurity_casepermission --data-only --verbose --no-acl --no-owner --disable-triggers ffsecurity | sudo tee dump_identity_provider.sql
17.4. Back up role permissions.
sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py dump_permissions | sudo tee permissions.csv
17.5. Change back the password, replaced in step #17.1
17.6. Stop all the services.
sudo systemctl stop findface-sf-api.service nginx.service tarantool@shard-00{1..8}.service postgresql.service pgbouncer.service
17.7. Open the
/opt/findface-cibr/docker-compose.yamlfile and copyPOSTGRES_PASSWORDvalue to use it in further commands.17.8. Recreate the
ffsecuritydatabase to clean it up from the default data. Paste{POSTGRES_PASSWORD}value that you previously copied in step #17.7 into the command below:sudo docker-compose up -d postgresql sudo docker exec -it -u postgres findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} dropdb ffsecurity" sudo docker exec -it -u postgres findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} createdb -O ntech --encoding=UTF-8 --lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --template=template0 ffsecurity"
17.9. Restore data into the recreated
ffsecuritydatabase. Paste{POSTGRES_PASSWORD}value that you previously copied in step #17.7 into the command below:sudo docker exec -i findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres ffsecurity" < dump_ffsecurity.sql
17.10. Recreate the
ffsecurity_identity_providerdatabase to clean it up from the default data. Paste{POSTGRES_PASSWORD}value that you previously copied in step #17.7 into the command below:sudo docker exec -it -u postgres findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} dropdb ffsecurity_identity_provider" sudo docker exec -it -u postgres findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} createdb -O ntech --encoding=UTF-8 --lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --template=template0 ffsecurity_identity_provider"
17.11. Run migration.
sudo docker-compose up -d pgbouncer sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-identity-provider/findface-multi-identity-provider.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/identity-provider:ffcibr-2.1.1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py migrate
17.12. Restore data into the recreated
ffsecurity_identity_providerdatabase. Paste{POSTGRES_PASSWORD}value that you previously copied in step #17.7 into the command below:sudo docker exec -i findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres ffsecurity_identity_provider" < dump_identity_provider.sql
17.13. Start all the services.
sudo docker-compose up -d
17.14. Run the command to create records in the outbox table for watch lists, camera groups, and cases. Paste
{POSTGRES_PASSWORD}value that you previously copied in step #17.7 into the command below:sudo docker exec -i findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} pg_dump --username postgres -f permissions.sql -t ffsecurity_cameragrouppermission -t ffsecurity_watchlistpermission -t ffsecurity_casepermission --data-only ffsecurity_identity_provider" sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py export_to_outbox --watchlists --cameragroups --cases sudo docker exec -i findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres -c 'TRUNCATE ffsecurity_cameragrouppermission, ffsecurity_watchlistpermission, ffsecurity_casepermission RESTART IDENTITY;' ffsecurity_identity_provider" sudo docker exec -i findface-cibr-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres ffsecurity_identity_provider < permissions.sql"
17.15. Before you restore role permissions into the
identity_providerservice, examine the/opt/findface-cibr/permissions.csvfile. Make sure to replace*_ffsecauthtokenwith*_authtokenif any. This is mostly applicable to those cases when FindFace CIBR 1.3 installation was an upgrade from earlier versions of the product.After that, restore role permissions into the
identity_providerservice.sudo docker run --rm --network host -v /opt/findface-cibr/configs/findface-multi-identity-provider/findface-multi-identity-provider.py:/etc/findface-security/config.py:ro -v $(pwd)/permissions.csv:/var/permissions.csv:ro docker.int.ntl/ntech/multi/multi/identity-provider:ffcibr-2.1.1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py load_permissions /var/permissions.csv
17.16. Copy full frame photos, normalized images, and the license file. Copy files from the
/opt/ntech/license/folder into the/opt/findface-cibr/data/findface-ntls/folder, from the/var/lib/findface-security/uploads/folder into the/opt/findface-cibr/data/findface-multi-legacy/uploads/folder, from the/var/lib/ffupload/uploads/folder into the/opt/findface-cibr/data/findface-upload/uploads/folder.sudo cp -r /opt/ntech/license/* /opt/findface-cibr/data/findface-ntls/ sudo cp -r /var/lib/findface-security/uploads/* /opt/findface-cibr/data/findface-multi-legacy/uploads/ sudo cp -r /var/lib/ffupload/uploads/* /opt/findface-cibr/data/findface-upload/uploads/ sudo chmod 777 -R /opt/findface-cibr/data/findface-upload/uploads/ sudo chown www-data:www-data -R /opt/findface-cibr/data/findface-upload/uploads/*
Alternatively, the above folders can be directly mounted into the relevant docker containers via the
docker-compose.yamlfile, like in the example below:sudo vi /opt/findface-cibr/docker-compose.yaml findface-upload: image: docker.int.ntl/ntech/universe/upload:ffserver-9.230407.1 logging: {driver: journald} network_mode: service:pause restart: always volumes: ['./configs/findface-upload/40-ffupload.sh:/docker-entrypoint.d/40-ffupload.sh:ro', '/var/lib/ffupload:/var/lib/ffupload'] findface-multi-identity-provider: depends_on: [pgbouncer, nats, findface-sf-api, findface-liveness-api, etcd] environment: {ADMIN_PASSWORD: <ADMIN_PASSWORD>} image: docker.int.ntl/ntech/multi/multi/identity-provider:ffcibr-2.1.1 logging: {driver: journald} network_mode: service:pause restart: always volumes: ['./configs/findface-multi-identity-provider/findface-multi-identity-provider.py:/etc/findface-security/config.py:ro', '/var/lib/findface-security/uploads:/var/lib/findface-security/uploads'] findface-multi-legacy: depends_on: [pgbouncer, nats, findface-sf-api, findface-counter, findface-liveness-api, etcd] environment: {ADMIN_PASSWORD: <ADMIN_PASSWORD>} image: docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 logging: {driver: journald} network_mode: service:pause restart: always volumes: ['./configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro', '/var/lib/findface-security/uploads:/var/lib/findface-security/uploads'] findface-multi-ui: depends_on: [findface-multi-legacy] image: docker.int.ntl/ntech/multi/multi/ui:ffcibr-2.1.1 logging: {driver: journald} network_mode: service:pause restart: always volumes: ['./configs/findface-multi-ui/nginx-site.conf:/etc/nginx/conf.d/default.conf:ro', '/var/lib/findface-security/uploads:/var/lib/findface-security/uploads']
17.17. To move Tarantool data, do the following:
Stop all FindFace CIBR containers:
sudo docker-compose down
Start the old shards and the
findface-sf-apiservice again:sudo systemctl start tarantool@shard-00{1..8}.service findface-sf-api.service
Create a new backup of the feature vector database:
sudo mkdir -p /etc/findface_dump_final sudo findface-storage-api-dump -output-dir=/etc/findface_dump_final -config /etc/findface-sf-api.ini
Stop the rest of the services, clear the
instances.enableddirectory, start the containers again, and perform the storage-api-restore operation:sudo systemctl stop tarantool@shard-00{1..8}.service findface-sf-api.service findface-ntls.service sudo rm /etc/tarantool/instances.enabled/* sudo docker-compose up -d sudo findface-storage-api-restore -config /opt/findface-cibr/configs/findface-sf-api/findface-sf-api.yaml /etc/findface_dump_final/*.json
The update has been completed. The new version includes new neural network models, but the migration of feature vectors to a different neural network model is not required. You can use old neural network models by moving them from the /usr/share/findface-data/models/ directory to the /opt/findface-cibr/models/ directory, specifying them in the /opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml file, if they are included in FindFace CIBR 2.1.1.
Note that face detection models in FindFace CIBR 1.3 are stored in the /usr/share/findface-data/models/facedet/ directory. In FindFace CIBR 2.1.1 all face detection models can be found in the /opt/findface-cibr/models/detector/ directory. When moving old neural network models from the /usr/share/findface-data/models/ directory to the /opt/findface-cibr/models/ directory, make sure to place all face detection models (facedet) to the /opt/findface-cibr/models/detector/ directory.
See for reference:
$ ls -lash /usr/share/findface-data/models
total 52K
4.0K drwxr-xr-x 2 root root 4.0K Jul 15 14:48 face
4.0K drwxr-xr-x 2 root root 4.0K Jul 15 14:48 faceattr
4.0K drwxr-xr-x 2 root root 4.0K Jul 15 14:48 facedet
4.0K drwxr-xr-x 2 root root 4.0K Jul 15 14:48 facenorm
$ ls -lash /opt/findface-cibr/models/
total 44K
4.0K drwxr-xr-x 2 root root 4.0K Jul 17 16:20 detector
4.0K drwxr-xr-x 2 root root 4.0K Jul 17 16:24 face
4.0K drwxr-xr-x 2 root root 4.0K Jul 17 16:24 faceattr
4.0K drwxr-xr-x 2 root root 4.0K Jul 17 13:37 facenorm
Important
We highly recommend disabling the Ubuntu automatic update to preserve the FindFace CIBR compatibility with the installation environment. In this case, you will be able to update your OS manually, fully controlling which packages to update.
To disable the Ubuntu automatic update, execute the following commands:
sudo apt-get remove unattended-upgrades
sudo systemctl stop apt-daily.timer
sudo systemctl disable apt-daily.timer
sudo systemctl disable apt-daily.service
sudo systemctl daemon-reload
Back Up and Recover FindFace CIBR and Its Data
You can back up FindFace CIBR before uninstalling it to recover the product and its data later on.
In this section:
Back up FindFace CIBR
To back up your FindFace CIBR instance and its data, run the following commands:
sudo tar -cvzf ~/configs.tar.gz -C /opt/findface-cibr/ configs
sudo tar -cvzf ~/data.tar.gz -C /opt/findface-cibr/ data
sudo cp /opt/findface-cibr/docker-compose.yaml ~/
Recover FindFace CIBR and Its Data
To restore FindFace CIBR and its data from the backup, do the following:
Download the installer file
findface-*.run.Put the
.runfile into some directory on the designated host (for example,/home/username).From this directory, make the
.runfile executable.Note
Be sure to specify the actual file name instead of
findface-*.chmod +x findface-*.run
Execute the
.runfile.sudo ./findface-*.run
Go through the installation process as described here.
After you have finished the installation, to restore FindFace CIBR, its data and configuration files, stop all FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose stop
Remove new configuration files and data generated and created by the installer and restore them from the backup.
Important
Compare your old
~/docker-compose.yamlfile that you have copied during the backup process against the new one/opt/findface-cibr/docker-compose.yaml. You may need to apply changes to the old~/docker-compose.yamlfile if you previously configured it to bring or exclude services or made any other changes. You must be fully aware of what you are doing by replacing the newdocker-compose.yamlfile with the old one.sudo rm -r /opt/findface-cibr/configs/* sudo tar -xvf ~/configs.tar.gz -C /opt/findface-cibr/ sudo rm -r /opt/findface-cibr/data/* sudo tar -xvf ~/data.tar.gz -C /opt/findface-cibr/ sudo cp ~/docker-compose.yaml /opt/findface-cibr/
Restart FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose up -d
Modify Feature Vector Database Structure
Sometimes it may be necessary to apply a new structural schema to your Tarantool-based feature vector database, for example, when updating to the latest version of the product, or when you want to enhance the default database structure with additional parameters, advanced face metadata, and so on.
In this section:
About Database Structure
In FindFace CIBR, the database structure is set via the /opt/findface-cibr/configs/findface-tarantool-server/tnt-schema.lua file.
The structure is created as a set of spaces and fields. Each field is described with the following parameters:
id: field id;
name: field name, must be the same as the name of a relevant object parameter;
field_type: data type;
default: field default value. If a default value exceeds
1e14 – 1, use a string data type to specify it, for example,"123123.."instead of123123...
You can find the default tnt-schema.lua file here.
Structure Modification
To modify the database structure, do the following:
Create a backup of the Tarantool-based feature vector database in any directory of your choice, for example,
/etc/ffcibr_dump.sudo docker exec -it findface-cibr-findface-sf-api-1 bash -c "mkdir ffcibr_dump; cd ffcibr_dump && /storage-api-dump -config /etc/findface-sf-api.ini" sudo docker cp findface-cibr-findface-sf-api-1:/ffcibr_dump /etc
Modify the database structure by applying the new schema to the
tnt-schema.luafile.sudo docker run --rm --network host --volume '/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py:/etc/findface-security/config.py:ro' docker.int.ntl/ntech/multi/multi/legacy:ffcibr-2.1.1 make-tnt-schema | sudo tee /opt/findface-cibr/configs/findface-tarantool-server/tnt-schema.lua
Open the
docker-compose.yamlfile. Make sure each Tarantool shard service contains defined variableCFG_EXTRA_LUA: loadfile("/tnt_schema.lua")in theenvironmentsection.sudo vi /opt/findface-cibr/docker-compose.yaml ... findface-tarantool-server-shard-001: depends_on: [findface-ntls] environment: {CFG_EXTRA_LUA: loadfile("/tnt_schema.lua")()... ...
Purge data from all the directories relevant to active shards.
sudo rm /opt/findface-cibr/data/findface-tarantool-server/shard-*/{index,snapshots,xlogs}/*
Restart the
findface-tarantool-servershards.docker restart findface-cibr-findface-tarantool-server-shard-001-1 findface-cibr-findface-tarantool-server-shard-002-1 findface-cibr-findface-tarantool-server-shard-003-1 findface-cibr-findface-tarantool-server-shard-004-1 findface-cibr-findface-tarantool-server-shard-005-1 findface-cibr-findface-tarantool-server-shard-006-1 findface-cibr-findface-tarantool-server-shard-007-1 findface-cibr-findface-tarantool-server-shard-008-1
Restore the Tarantool database from the backup.
sudo docker exec -it findface-cibr-findface-sf-api-1 bash -c 'cd ffcibr_dump && for x in *.json; do /storage-api-restore -config /etc/findface-sf-api.ini < "$x"; done;'
Important
If some fields were removed from the new database structure, you have to first manually delete the corresponding data from the backup copy.
See also
Check Component Status
Check the status of containers once you have encountered a system problem, using the following commands:
docker ps
sudo docker container inspect <container_id>/<container_name>
sudo docker container stats <container_id>/<container_name>
Logging
Consulting logs is one of the first things you should do to identify a cause of a problem. By default, the FindFace CIBR processes are logged to Docker container logs, which can be accessed via the docker logs and docker service logs commands. In addition, Docker uses the json-file logging driver, which caches container logs in JSON. You can configure Docker to use another logging driver, choosing from the multiple logging mechanisms available.
This section describes how to set up Docker to use the journald logging driver, which sends container logs to the systemd journal. In this case, log entries are retrieved using the journalctl command, through the journal API, or the docker logs command. You can configure the systemd journal as well by using the instructions below.
In this section:
Configure Journald
To configure the systemd-journal service, do the following:
Check whether the
/var/log/journaldirectory already exists. If not, create it by executing the following command:sudo mkdir /var/log/journal sudo chmod 2755 /var/log/journal
Open the
/etc/systemd/journald.confconfiguration file. Enable savingjournaldlogs to your hard drive by uncommenting theStorageparameter and changing its value topersistent. Disable filtering insystemd-journalas well:sudo vi /etc/systemd/journald.conf [Journal] ... Storage=persistent ... RateLimitInterval=0 RateLimitBurst=0 ...
If necessary, uncomment and edit the
SystemMaxUseparameter. This parameter determines the maximum volume of log files on your hard drive. Specify its value in bytes or use K, M, G, T, P, E as units for the specified size (equal to \(1024\), \(1024^2\), … bytes).... SystemMaxUse=3G
Restart the
journaldservice.sudo systemctl restart systemd-journald.service
Enabling Journald Logging Driver
To enable Docker to use the journald logging driver, do the following:
Add the following line to the
/etc/docker/daemon.jsonconfiguration file.Tip
This file may not be present on your system. Check whether it exists and if it does not, create the
/etc/dockerdirectory first and then the file.sudo mkdir /etc/docker sudo touch /etc/docker/daemon.json
sudo vi /etc/docker/daemon.json { "log-driver": "journald" }
Stop all Docker containers.
sudo docker stop $(sudo docker ps -a -q)
Restart the Docker service.
sudo systemctl restart docker
Start all Docker containers.
sudo docker start $(sudo docker ps -a -q)
Consult Logs
Use any convenient method to work with the journald logs. The following commands are a good place to start:
Display all logs:
journalctl -fa
Display logs by container ID:
journalctl CONTAINER_ID=<container_id> -f
Display logs by container name:
journalctl CONTAINER_NAME=<container-name> -f
See also
Troubleshoot Licensing and findface-ntls
When troubleshooting licensing and findface-ntls (see Licensing), the first step is to retrieve the licensing information and findface-ntls status. You can do so by sending an API request to findface-ntls. Necessary actions are then to be undertaken, subject to the response content.
Tip
Please do not hesitate to contact our experts on troubleshooting by support@ntechlab.com.
Note
The online licensing is done via the NtechLab Global License Manager license.ntechlab.com. Check its availability. A stable internet connection and DNS are required.
To retrieve the FindFace CIBR licensing information and findface-ntls status, execute on the findface-ntls host console:
curl http://localhost:3185/license.json -s | jq
The response will be given in JSON. One of the most significant parameters is last_updated. It indicates in seconds how long ago the local license has been checked for the last time.
Interpret the last_updated value as follows:
[0, 5] — everything is alright.
(5, 30] — there may be some problems with connection, or with the local drive where the license file is stored.
(30; 120] — almost certainly something bad happened.
(120; ∞) — the licensing source response has been timed out. Take action.
"valid" -> "value": false: connection with the licensing source was never established.
curl http://localhost:3185/license.json -s | jq
{
"name": "NTLS",
"time": 1565186356,
"type": "online",
"license_id": "61063ce4b86945e1b70c3bdbedea453b",
"generated": 1514467939,
"last_updated": 5,
"valid": {
"value": true,
"description": ""
},
"source": "/opt/ntech/license/import_b68d7b7ec9a7310d18832035318cff0c9ddf11e3a9ab0ae962fbe48645e196d1.lic",
"limits": [
{
"type": "time",
"name": "end",
"value": 1609161621
},
{
"type": "number",
"name": "faces",
"value": 9007199254740991,
"current": 0
},
{
"type": "number",
"name": "cameras",
"value": 4294967295,
"current": 0
},
{
"type": "number",
"name": "extraction_api",
"value": 256,
"current": 0
},
{
"type": "boolean",
"name": "gender",
"value": true
},
{
"type": "boolean",
"name": "age",
"value": true
},
{
"type": "boolean",
"name": "emotions",
"value": true
},
{
"type": "boolean",
"name": "fast-index",
"value": true
},
{
"type": "boolean",
"name": "sec-genetec",
"value": false
},
{
"type": "boolean",
"name": "beard",
"value": false
},
{
"type": "boolean",
"name": "glasses",
"value": false
},
{
"type": "boolean",
"name": "liveness",
"value": false
}
],
"services": [
{
"name": "video-worker",
"ip": "127.0.0.1:53276"
},
{
"name": "FindFace-tarantool",
"ip": "127.0.0.1:53284"
},
{
"name": "FindFace-tarantool",
"ip": "127.0.0.1:53288"
}
]
}
Manually Purge Old Data from Database
To manually remove old data from the FindFace CIBR database, use the cleanup utility. You can separately remove the following data:
audit-logs,
remote monitoring events (applicable only if the Integration with Remote Facial Recognition Systems is enabled).
The cleanup utility runs in the findface-cibr-findface-multi-legacy-1 container. To invoke the cleanup help message, execute:
sudo docker exec -it findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py cleanup --help
usage: manage.py cleanup [-h] [--as-configured]
[--face-events-max-fullframe-unmatched-age FACE_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE]
[--face-events-max-fullframe-matched-age FACE_EVENTS_MAX_FULLFRAME_MATCHED_AGE]
[--face-events-max-unmatched-age FACE_EVENTS_MAX_UNMATCHED_AGE]
[--face-events-max-matched-age FACE_EVENTS_MAX_MATCHED_AGE]
[--body-events-max-fullframe-unmatched-age BODY_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE]
[--body-events-max-fullframe-matched-age BODY_EVENTS_MAX_FULLFRAME_MATCHED_AGE]
[--body-events-max-unmatched-age BODY_EVENTS_MAX_UNMATCHED_AGE]
[--body-events-max-matched-age BODY_EVENTS_MAX_MATCHED_AGE]
[--car-events-max-fullframe-unmatched-age CAR_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE]
[--car-events-max-fullframe-matched-age CAR_EVENTS_MAX_FULLFRAME_MATCHED_AGE]
[--car-events-max-unmatched-age CAR_EVENTS_MAX_UNMATCHED_AGE]
[--car-events-max-matched-age CAR_EVENTS_MAX_MATCHED_AGE]
[--car-cluster-events-max-age CAR_CLUSTER_EVENTS_MAX_AGE]
[--body-cluster-events-max-age BODY_CLUSTER_EVENTS_MAX_AGE]
[--face-cluster-events-max-age FACE_CLUSTER_EVENTS_MAX_AGE]
[--car-cluster-events-keep-best-max-age CAR_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE]
[--body-cluster-events-keep-best-max-age BODY_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE]
[--face-cluster-events-keep-best-max-age FACE_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE]
[--area-activations-max-age AREA_ACTIVATIONS_MAX_AGE]
[--audit-logs-max-age AUDIT_LOGS_MAX_AGE]
[--counter-records-max-age COUNTER_RECORDS_MAX_AGE]
[--external-vms-events-max-age EXTERNAL_VMS_EVENTS_MAX_AGE]
[--external-vms-send-events-status-max-age EXTERNAL_VMS_SEND_EVENTS_STATUS_MAX_AGE]
[--remote-monitoring-events-max-age REMOTE_MONITORING_EVENTS_MAX_AGE]
[--configuration CONFIGURATION] [--version]
[-v {0,1,2,3}] [--settings SETTINGS]
[--pythonpath PYTHONPATH] [--traceback] [--no-color]
[--force-color] [--skip-checks]
Delete FFSecurity entities
optional arguments:
-h, --help show this help message and exit
--as-configured Apply config age options for events, counter records
and clusters. Can't be used with other arguments.
--face-events-max-fullframe-unmatched-age FACE_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE
face events max fullframe unmatched age to clean up
(in seconds)
--face-events-max-fullframe-matched-age FACE_EVENTS_MAX_FULLFRAME_MATCHED_AGE
face events max fullframe matched age to clean up (in
seconds)
--face-events-max-unmatched-age FACE_EVENTS_MAX_UNMATCHED_AGE
face events max unmatched age to clean up (in seconds)
--face-events-max-matched-age FACE_EVENTS_MAX_MATCHED_AGE
face events max matched age to clean up (in seconds)
--body-events-max-fullframe-unmatched-age BODY_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE
body events max fullframe unmatched age to clean up
(in seconds)
--body-events-max-fullframe-matched-age BODY_EVENTS_MAX_FULLFRAME_MATCHED_AGE
body events max fullframe matched age to clean up (in
seconds)
--body-events-max-unmatched-age BODY_EVENTS_MAX_UNMATCHED_AGE
body events max unmatched age to clean up (in seconds)
--body-events-max-matched-age BODY_EVENTS_MAX_MATCHED_AGE
body events max matched age to clean up (in seconds)
--car-events-max-fullframe-unmatched-age CAR_EVENTS_MAX_FULLFRAME_UNMATCHED_AGE
car events max fullframe unmatched age to clean up (in
seconds)
--car-events-max-fullframe-matched-age CAR_EVENTS_MAX_FULLFRAME_MATCHED_AGE
car events max fullframe matched age to clean up (in
seconds)
--car-events-max-unmatched-age CAR_EVENTS_MAX_UNMATCHED_AGE
car events max unmatched age to clean up (in seconds)
--car-events-max-matched-age CAR_EVENTS_MAX_MATCHED_AGE
car events max matched age to clean up (in seconds)
--car-cluster-events-max-age CAR_CLUSTER_EVENTS_MAX_AGE
car cluster events max age to clean up (in seconds)
--body-cluster-events-max-age BODY_CLUSTER_EVENTS_MAX_AGE
body cluster events max age to clean up (in seconds)
--face-cluster-events-max-age FACE_CLUSTER_EVENTS_MAX_AGE
face cluster events max age to clean up (in seconds)
--car-cluster-events-keep-best-max-age CAR_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE
car cluster events keep best max age to clean up (in
seconds)
--body-cluster-events-keep-best-max-age BODY_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE
body cluster events keep best max age to clean up (in
seconds)
--face-cluster-events-keep-best-max-age FACE_CLUSTER_EVENTS_KEEP_BEST_MAX_AGE
face cluster events keep best max age to clean up (in
seconds)
--area-activations-max-age AREA_ACTIVATIONS_MAX_AGE
area activations max age to clean up (in seconds)
--audit-logs-max-age AUDIT_LOGS_MAX_AGE
audit logs max age to clean up (in seconds)
--counter-records-max-age COUNTER_RECORDS_MAX_AGE
counter records max age to clean up (in seconds)
--external-vms-events-max-age EXTERNAL_VMS_EVENTS_MAX_AGE
external vms events max age to clean up (in seconds)
--external-vms-send-events-status-max-age EXTERNAL_VMS_SEND_EVENTS_STATUS_MAX_AGE
external vms send events status max age to clean up
(in seconds)
--remote-monitoring-events-max-age REMOTE_MONITORING_EVENTS_MAX_AGE
remote monitoring events max age to clean up (in
seconds)
--configuration CONFIGURATION
The name of the configuration class to load, e.g.
"Development". If this isn't provided, the
DJANGO_CONFIGURATION environment variable will be
used.
--version show program's version number and exit
-v {0,1,2,3}, --verbosity {0,1,2,3}
Verbosity level; 0=minimal output, 1=normal output,
2=verbose output, 3=very verbose output
--settings SETTINGS The Python path to a settings module, e.g.
"myproject.settings.main". If this isn't provided, the
DJANGO_SETTINGS_MODULE environment variable will be
used.
--pythonpath PYTHONPATH
A directory to add to the Python path, e.g.
"/home/djangoprojects/myproject".
--traceback Raise on CommandError exceptions
--no-color Don't colorize the command output.
--force-color Force colorization of the command output.
--skip-checks Skip system checks.
To remove audit logs, older than a given number of seconds, use the --audit-logs-max-age option. For example, to remove audit logs older than 5 days (432000 seconds), execute:
sudo docker exec -it findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py cleanup --audit-logs-max-age 432000
To remove remote monitoring events older than 5 days (432000 seconds), execute:
sudo docker exec -it findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py cleanup --remote-monitoring-events-max-age 432000
Important
You must provide at least one of the mentioned arguments.
Reset Password
To reset a user password to the FindFace CIBR web interface, execute the following command:
sudo docker exec -it findface-cibr-findface-multi-identity-provider-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py changepassword <username>
Migrate Data to Another Disk
High disk load may lead to delays in event arrivals. In severe cases, it might result in complete inoperability of FindFace CIBR. One of the means for reducing the disk load is to migrate the FindFace CIBR data storages to another disk.
In this section:
Prepare Disk
To prepare a disk for the data migration, do the following:
Create a new mount point (
/mnt/ffdatain our example).sudo mkdir /mnt/ffdata
Create a partition.
sudo parted /dev/sdb mklabel gpt mkpart primary ext4 1MiB 100% q sudo mkfs.ext4 /dev/sdb1
Learn the UUID of the partition (
sdb1in our example).sudo blkid | grep sdb1 /dev/sdb1: LABEL="data" UUID="0638ebe0-853e-43ea-8f35-bfae305695d1" TYPE="ext4" PARTUUID="8cebaacc-77d7-4757-b4c6-14147e92646c"
Add the partition to fstab to make it automatically mount on booting.
sudo vi /etc/fstab ------------ #DATA mount UUID=0638ebe0-853e-43ea-8f35-bfae305695d1 /mnt/ffdata/ ext4 auto,user,rw 0 2 -------------
Mount all the filesystems.
sudo mount -a
Migrate Photo Storage
To migrate the FindFace CIBR photo storage, do the following:
Inside the mount point, create a directory to store photos.
sudo mkdir /mnt/ffdata/ffupload -p
Mount the created directory (
/mnt/ffdata/ffuploadin the example) into thefindface-cibr-findface-upload-1container. To do so, open the/opt/findface-cibr/docker-compose.yamlconfiguration file and list it in the volumes of thefindface-uploadsection instead of the default/opt/findface-cibr/data/findface-uploaddirectory.sudo vi /opt/findface-cibr/docker-compose.yaml findface-upload: ... volumes: ['./configs/findface-upload/40-ffupload.sh:/docker-entrypoint.d/40-ffupload.sh:ro', '/mnt/ffdata/ffupload:/var/lib/ffupload']
Rebuild all FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose down sudo docker-compose up -d
Migrate Main Database (PostgreSQL)
To migrate the PostgreSQL database, do the following:
Inside the mount point, create a directory to store the PostgreSQL data.
sudo mkdir /mnt/ffdata/postgresql -p
Mount the created directory (
/mnt/ffdata/postgresqlin the example) into thefindface-cibr-postgresql-1container. To do so, open the/opt/findface-cibr/docker-compose.yamlconfiguration file and list it in the volumes of thepostgresqlsection instead of the default/opt/findface-cibr/data/postgresqldirectory.sudo vi /opt/findface-cibr/docker-compose.yaml postgresql: ... volumes: ['./configs/postgresql/40-init.sql:/docker-entrypoint-initdb.d/40-init.sql:ro', '/mnt/ffdata/postgresql:/bitnami/postgresql/data']
Rebuild all FindFace CIBR containers.
cd /opt/findface-cibr sudo docker-compose down sudo docker-compose up -d
Appendices
Installation File
FindFace CIBR installation configuration is automatically saved to a file /tmp/<findface-installer-*>.json. You can edit this file and use it to install FindFace CIBR on other hosts without having to answer the installation questions again.
Tip
See FindFace CIBR Standalone Automated Deployment to learn more about the FindFace CIBR installer.
Important
Be sure to remove fields *.config, exp_ip, and int_ip before installing FindFace CIBR on a host with a different IP address.
Here is an example of the installation file.
Neural Networks Summary
Here you can find a summary of neural network models created by our Lab and used in FindFace CIBR.
Find installed models at /opt/findface-cibr/models/.
Important
The default face biometrics model upon a clean install is mango_320.
Face detection
ls /opt/findface-cibr/models/detector/
face.jasmine_fast.003.cpu.fnk face.jasmine_fast.003.gpu.fnk
Face image normalization
ls /opt/findface-cibr/models/facenorm/
bee.v3.cpu.fnk crop2x.v2_maxsize400.cpu.fnk facenorm.multicrop_full_center_size400.cpu.fnk
bee.v3.gpu.fnk crop2x.v2_maxsize400.gpu.fnk facenorm.multicrop_full_center_size400.gpu.fnk
bee_fast.cpu.fnk crop2x.v2_no_maxsize.cpu.fnk facenorm.multicrop_full_crop2x_size400.cpu.fnk
bee_fast.gpu.fnk crop2x.v2_no_maxsize.gpu.fnk facenorm.multicrop_full_crop2x_size400.gpu.fnk
crop1x.v2_maxsize400.cpu.fnk cropbbox.v2.cpu.fnk
crop1x.v2_maxsize400.gpu.fnk cropbbox.v2.gpu.fnk
Face recognition
ls /opt/findface-cibr/models/face/
mango_320.cpu.fnk nectarine_m_160.cpu.fnk nectarine_xs_320.cpu.fnk
mango_320.gpu.fnk nectarine_m_160.gpu.fnk nectarine_xs_320.gpu.fnk
Face attribute recognition
ls /opt/findface-cibr/models/faceattr/
age.v2.cpu.fnk emotions.v1.cpu.fnk glasses3.v0.cpu.fnk medmask3.v2.cpu.fnk
age.v2.gpu.fnk emotions.v1.gpu.fnk glasses3.v0.gpu.fnk medmask3.v2.gpu.fnk
beard.v0.cpu.fnk gender.v2.cpu.fnk liveness.web.v0.cpu.fnk quality_fast.v1.cpu.fnk
beard.v0.gpu.fnk gender.v2.gpu.fnk liveness.web.v0.gpu.fnk quality_fast.v1.gpu.fnk
FindFace CIBR Data Storages
In this section:
List of Storages
FindFace CIBR uses the following data storages:
Tarantool-based feature vector database that stores face feature vectors and recognition events:
/opt/findface-cibr/data/findface-tarantool-server.PostgreSQL-based main system database
ffsecuritythat stores internal system data, records, and user accounts:/opt/findface-cibr/data/postgresql.The
/opt/findface-cibr/data/findface-upload/uploadsdirectory that stores normalized face images.The
/opt/findface-cibr/data/findface-multi-legacy/uploadsdirectory that stores photos uploaded to records, photos uploaded to user profiles, video and photo files uploaded to cases, full frames and thumbnails of clusters and remote monitoring events.
Feature Vector Database Galleries
There are the following FindFace CIBR-specific galleries in the Tarantool-based feature vector database:
ffsec_face_case_events: feature vectors extracted from faces detected in the video or photo uploaded to a case.ffsec_face_case_clusters: centroids of case face clusters.
User’s Guide
This chapter describes how to work with the FindFace CIBR web interface, including its advanced possibilities, and will be of interest to administrators, operators, and other users.
Getting Started
Once you have successfully deployed and configured FindFace CIBR, it’s time to open the web interface, and get started. In this chapter, you can find a recommended sequence of steps that will help you harness your system’s complete functionality.
Organize Watch Lists and Global Record Index
Create a new watch list or use the default one. A watch list is an entity that allows you to classify individuals by arbitrary criteria, e.g., wanted, suspects, etc.
Upload records of individuals to the global record index and add them to watch lists. See Record Index.
Connect FindFace CIBR to Remote Systems
Integrate FindFace CIBR with remote facial recognition systems. In this case, the server known as a puppeteer will be pushing record index data to remote servers known as puppets. In return, it will be pulling recognition events matching with the records.
FindFace CIBR in Action
Create case files and process video footages and photo files from crime scenes to define participants.
Search for faces across the system.
Compare two faces and verify that they belong to the same individual.
Build detailed reports on search results and record index.
Harness the FindFace CIBR comprehensive and searchable audit log to enhance your system protection.
View alerts from remote facial recognition systems and search remote systems for specific individuals. See Remote Alerting and Remote Search.
Basic Maintenance
Go Further
Harness the FindFace CIBR functions through HTTP API.
Web Interface Basics
Use the web interface to interact with FindFace CIBR. To open the web interface, enter its basic address in the address bar of your browser, and log in.
Note
The basic address is set during deployment.
Important
To log in for the first time, use the admin account created during deployment. To create more users, refer to Role and User Management.
Navigation
There is a different number of items in the navigation bar depending on the user’s role.
Web Interface Language and Theme
To change the system language and a theme, click 
on a top panel.
Record Index
Record index stores records of individuals, including their biometric data, related documents, links to relevant cases, and other important data.
To create records in bulk, use the console bulk record upload functionality.
In this section:
Create Record
To create a record manually, do the following:
Navigate to the Record Index tab.
Click + Add new record.
Specify the record name. If necessary, add a comment.
From the Watch lists drop-down menu, select a watch list for the record (or several watch lists, one by one).
Check Record active. If a record is inactive, it is excluded from the case analysis, remote alerting and search.
Save the record. You will see additional tabs appear.
On the tab Info, attach related files.
On the Faces tab, upload images of the individual’s face. Supported formats: WEBP, JPG, BMP, PNG, HEIC.
On the Case Cluster tab, Related Cases tab and Related Records tab, the data will be displayed after the record has an automatch with the case cluster, or the connection is set manually during people analyse.
Batch Record Upload
If there are too many records to create, you can batch load records into the record index. Do the following:
Navigate to the Record Index tab.
Click + Add new record → Try batch record upload.
Select files or folder to drop and drag to upload.
Specify a name prefix and postfix. If necessary, add a comment prefix and postfix.
Select a watch list (or several watch lists, one by one) from the drop-down menu.
Click Start.
Autopopulation with Criminal Investigation Artifacts
While you are performing your duties using FindFace CIBR, investigating cases and analyzing CSI footage, a record is automatically populated with the case data.
If the record has an automatch with the face from the photo or video, uploaded in the case, then a sign 
will be displayed on the record thumbnail. If the connection is set manually, then a sign 
will be displayed.
Click it to navigate to the Case Clusters tab or Related Cases of the record.
If the selected case cluster isn’t a case participant, navigate to the connections wizard by clicking the face. See Detected People Analysis.
If the selected case cluster is a case participant, navigate to the case participant record by clicking the face.
On the Info tab you can modify participant information, if needed.
On the Cluster events tab you can view detected face images of the participant and other face images of the case cluster.
On the Connections tab you can view connections of a participant with persons from other clusters.
Filter Records
The most frequently used filters for the record index are available in the upper part of the window.
To display the entire set of filters, click the More filters button. Here it is:
Watch lists: display records from selected watch lists.
Faces: filter records by presence of a face biometric data.
Filling: display only empty records, only filled or any records.
Name contains: filter records by name.
ID: display a record with a given ID.
Status: filter records by status.
Match type: filter records by match type (Any/Related/Auto matched/Any type).
You can sort out records on the list by ID.
Purge Record Index
You can purge the record index entirely or by watch lists in one click. Do the following:
Navigate Settings → Watch Lists.
Select one or several watch lists.
Click Delete records in selected.
Case Files
FindFace CIBR allows for conducting case management and performing investigation by analyzing associated video footage and photo files. This functionality is available on the Case Files tab.
In this section:
Video File Formats
Video footage used for case investigations is accepted in a wide variety of formats. Click here for listing.
Case Investigation Workflow
Case investigation is conducted in the following way:
Create a new case file. Specify the incident date and name, the case ID in a registry, and the incident date.
Specify case details and set up access permissions for it.
Upload a video footage and photo files from the criminal scene. Set up video processing parameters if needed. Process the video. The system will return human faces detected in it.
Parse the detected faces. Figure out which individual is likely to be a suspect, a victim, or a witness. Other individuals will be considered not relevant to the case. Link faces to matching records in the global record index and participants of other cases.
Fill in case participant records. Specify their names and attach related documents.
Keep returning to the case file to supplement it with new materials, as the investigation progresses.
Create Case File
To create a case file, do the following:
Navigate to Case Files.
Click + Add case file.
Enter the descriptive name of the case. Specify the incident date.
Add a comment, if needed.
Specify the case ID and date in the registry, if needed.
Click Add >. As a result, the case file will be added to the case list.
Case Access Permissions and Related Documents
After you create a case, specify its details and set up access permissions. Do the following:
Click the case on the case list to open it.
Click Set access permissions to modify the default access permissions.
Attach one or several files relevant to the case.
Click Save.
Upload and Process Video File
To upload and process a CSI video footage, do the following:
Navigate to the Case files tab.
Click the case on the case list to open it.
Navigate to the Videos tab.
Click the + Add video button.
Specify a URL or select a file. Click Upload.
The video file will be added to the case video uploads. Click Upload to upload another video file.
Click the video on the list to open the processing configuration wizard. Set up the video processing parameters.
Video processing parameters
For each video, you will be provided with complete statistics such as current session duration, the number of objects processed with errors after the last job restart, the number of frame drops, and other data. To consult these data, click the name of the video on the list and go to the Info tab.
On the General tab, you can change name if needed.
On the Advanced tab, fine-tune the video:
If needed, change the video orientation.
Important
Be aware that the
findface-multi-legacyserver rotates the video using post-processing tools. It can negatively affect performance. Rotate the video via the camera functionality wherever possible.Timeout: Specify the timeout in milliseconds for posting detected objects.
Verify SSL certificate: Select to enable verification of the server SSL certificate when the object tracker posts objects to the server over https. Deselect the option if you use a self-signed certificate.
Retrieve timestamps from stream: Select to retrieve and post timestamps from the video stream. Deselect the option to post the current date and time.
Add to timestamps: Add the specified number of seconds to timestamps from the stream.
FFMPEG parameters: FFMPEG options for the video stream in the key-value format, for example, [“rtsp_transpotr=tcp”, “ss=00:20:00”].
Play speed limit: If less than zero, the speed is not limited. In other cases, the stream is read with the given
play_speed. Not applicable for live-streaming.Force input format: Pass FFMPEG format (mxg, flv, etc.) if it cannot be detected automatically.
Minimum motion intensity: Minimum motion intensity to be detected by the motion detector.
Read frames from source without drops: If
findface-video-workerdoes not have enough resources to process all frames with objects, it drops some of them. If this option is active (true)findface-video-workerputs excessive frames on a waiting list to process them later.Router URL (router_url): IP address for posting detected objects to external video workers from
findface-video-worker. By default,'http://127.0.0.1'.
Specify the region of tracking within the camera field and region of interest (Zones). Click Save.
The region of tracking enables detecting and tracking faces only inside a clipping rectangle. You can use this option to reduce the video object detector load. The region of interest enables posting objects detected only within its boundaries.
On the Faces tab, specify settings for face detection.
Size: Minimum object size in pixels to post and maximum object size in pixels to post.
Quality: The minimum quality of the object image for detection. The allowed range is from 0 to 1. The recommended reference value is 0.5, which corresponds to object images of satisfying quality. Do not change the default value without consulting with our technical experts (support@ntechlab.com).
JPEG quality: Full frame compression quality.
Full frame in PNG: Send full frames in PNG and not in JPEG as set by default. Do not enable this parameter without consulting with our technical experts (support@ntechlab.com) as it can affect the entire system functioning.
Overlap threshold: The percentage of overlap of bboxes between two serial frames so that these bboxes are considered as one track. The range of values is from 0 to 1. Do not change the default value without consulting with our technical experts (support@ntechlab.com).
Track maximum duration: The maximum approximate number of frames in a track, after which the track is forcefully completed. Enable it to forcefully terminate endless tracks, for example, tracks with objects from advertising media.
Forced termination interval: Terminate the track if no new object has been detected within the specified time (in seconds).
Send track history: Send array of bbox coordinates along with the event. May be applicable for external integrations to map the path of an object.
Crop full frame: Select to crop the full frame to the size of the ROT area before sending it for recognition. The size of the full frame will be equal to the size of the ROT area.
Offline mode (overall_only): By default, the system uses the offline mode to process the video, i.e., it posts one snapshot of the best quality per track to save disk space. Disable it to receive more object snapshots if needed. If the offline mode is on, the parameters of the real-time mode are off.
Real-time mode parameters:
Note
These parameters are non-functional if the offline mode is on.
Interval: Time interval in seconds (integer or decimal) within which the object tracker picks up the best snapshot in the real-time mode.
Post first object immediately: Select to post the first object from a track immediately after it passes through the quality, size, and ROI filters, without waiting for the first
realtime_post_intervalto complete in real-time mode. Deselect the option to post the first object after the firstrealtime_post_intervalcompletes.Post track first frame: At the end of the track, the first frame of the track will be additionally sent complimentary to the overall frame of the track. May be applicable for external integrations.
Post in every interval: Select to post the best snapshot within each time interval (
realtime_post_interval) in real-time mode. Deselect the option to post the best snapshot only if its quality has improved comparing to the posted snapshot.Post track last frame: At the end of the track, the last frame of the track will be additionally sent complimentary to the overall frame of the track. May be applicable for external integrations.
On the list of video uploads, click three dots → Process to start object identification.
The processing results will be available on the Clusters tab and on the Cluster events tab of the participant.
Upload and Process Photo File
To upload and process a CSI photo file, do the following:
Navigate to Case Files.
Click + Add photo.
Select photos to upload.
Click Add and process. As a result, the photo file will be added to the list of photo uploads and processed.
To restart object identification on the photo file, click three dots → Process.
Click the name of image in a list to see cluster events and modify a name of the photo file or add a comment, if needed.
Detected People Analysis
The clusters of faces, once detected in the video and photo files, are shown on the Clusters tab. Here you need to parse them subject to the role a person plays in the incident and establish links to relevant global records, other case files, participants of the same case, and other clusters.
If a detected object has a match in the card index, a case cluster thumbnail contains the following information:
normalized object image
record name
the similarity between matched objects
watch list(s)
Acknowledge button
Click the Acknowledge button to acknowledge case cluster.
Note
The sign 
on the case list indicates that there is an unacknowledged case cluster in the case.
To analyse detected people, do the following:
Click on a face on the list.
Tip
With the large number of clusters, use filters. Click the More filters button in the upper-right corner to display them.
Note
Some filters from the list below may be hidden, depending on which recognition features are enabled.
Participant: display only case clusters/only participants or any.
Acknowledged: display only unacknowledged clusters/only acknowledged clusters or any.
Matches: display case clusters only with/without matching the record, or all events.
Watch lists: display case clusters only for a selected watch list.
Date and time: display only case clusters formed within a certain period.
ID: display a case cluster with a given ID.
Specific filters for face clusters
Age: display case clusters with people of a given age.
Beard: filter case clusters by the fact of having a beard.
Emotions: display case clusters with given emotions.
Gender: display case clusters with people of a given gender.
Glasses: filter case clusters by the fact of wearing glasses.
Face mask: filter case clusters by the fact of wearing a face mask.
Link the face to a matching record in the global record index and matching participants of other case files. Do so by clicking the Add button that appears when you hover over the photo. You can also link the face to participants of the same case and other clusters.
Click the face in section Clusters to see detected faces in full screen and split some of them from a cluster, if needed.
Click Mark as participant.
Specify the participant name and type, and add a comment if necessary. This will create a new case participant record that you will be able to view on the Participants tab.
A participant can be one of the following types:
victim
witness
suspect
Click Save and close.
As a result, the information will be added to a case cluster thumbnail and the face image will have a round frame. The number of cluster events is shown by the number in the upper right corner of the case cluster thumbnail. Click the number to view full screen of the image in the new window. You can split the face from a cluster, if needed.
You can reopen the connections wizard on the Clusters tab by clicking on the participant’s face again.
To access the participant record, navigate to the Participants tab.
Case Participant Records
The Participants tab provides access to all participant data collected so far.
To view a case participant record, click the relevant face on the list.
On the Info tab you can modify participant information, if needed.
On the Cluster events tab you can view detected face images of the participant and other face images of the case cluster.
On the Connections tab you can view connections of a participant with persons from other clusters.
FindFace CIBR allows you to search detected objects from the case participant records. To navigate from the case participant record to the search tab, click three dots → Search.
If during a case investigation it is necessary to reset the participant record, click three dots → Reset participant.
With the large number of participants, use filters. Click the More filters button in the upper-right corner to display them.
Name contains: display participants by name.
Role: display participants for a selected role (Any/Victim/Witness/Suspect).
Date and time: display participants by case date within a certain period.
Case File Archive
It’s possible to label a case file as archived to indicate that the case is closed, or for another reason.
To archive/unarchive case files, do the following:
On the Case Files tab, select one or several case files.
Click Archive selected to archive the case files. Click Delete selected to delete them.
If a case has been archived, you cannot change it anymore. To add photos and video footage or modify participants, open the case again by checking it and clicking Open selected.
You can filter the case file list by archived status: All, Opened, Archived or use additional filter by clicking More filters:
Unacknowledged status: display cases by acknowledged status.
Date and time: display cases by date within a certain period.
ID: display a case with a given ID.
Search Faces in System
FindFace CIBR allows you to search for individuals throughout the entire system.
To find an individual, do the following:
Navigate to the Search tab.
Specify an object to search for in one of the following ways:
by record’s URL or ID
by case cluster’s URL or ID
by uploading a photo file
If you specified a record URL or ID, select a photo from it. If there are multiple photos, you can select some or all of them. Click the Apply button. When you select several objects from the record index, the search range will narrow. The search results will only contain the objects similar to those on the selected photos and within the preset search threshold.
If you specified a case cluster URL or ID, the search results will only contain the objects similar to those on the selected case cluster and within the preset search threshold.
If you uploaded a photo file, it will be displayed in the new window. If there are multiple objects in the image, select the one of your interest. Click Search.
Define the search section – Record or Case cluster.
You will see the search results appear. If necessary, you can narrow down your search by specifying filters or lowering a similarity threshold.
The following filters are available for records:
Watch lists: display records from selected watch lists.
Filling: display only empty records, only filled or any records.
Name contains: filter records by name.
ID: display a record with a given ID.
Status: filter records by status.
Match type: filter records by match type (Any/Related/Auto matched/Any type).
Limit: display records within the specified limit.
The following filters are available for case cluster:
Participant: display only clusters/participants, or any.
Acknowledged: display only acknowledged/unacknowledged case clusters, or all clusters.
Matches: display case clusters only with/without matching the record, or all events.
Watch lists: display case clusters with record from a selected watch lists.
Date and time: display only case clusters that occurred within a certain period.
ID: display a case cluster with a given ID.
The following specific filters are available for case cluster:
Note
Some filters from the list below may be hidden, subject to enabled recognition features.
Age: display case clusters with people of a given age.
Beard: filter case clusters by the fact of having a beard.
Emotions: display case clusters with given emotions.
Gender: display case clusters with people of a given gender.
Glasses: filter case clusters by the fact of wearing glasses.
Face mask: filter case clusters by the fact of wearing a face mask.
Limit: display case clusters within the specified limit.
You can sort out results of a search by the following parameters:
most similar first
the newest first
the oldest first
Compare Two Faces
FindFace CIBR allows you to compare two objects and verify that they match. Do the following:
Navigate to the Verify tab.
Specify two faces to verify in one of the following ways:
by event’s URL
by uploading a photo
If there are multiple objects in the image, select the one of your interest.
You will see the match probability.
Reports
FindFace CIBR provides a possibility of building reports on the following system entities:
In this section:
Build Report
To build a report on a system entity, do the following:
Navigate to the tab associated with the required entity: Search, Record Index or Audit Log.
Perform the search if you are on the Search tab. See Search Faces in System. Click the
button to build the report, or the More filters button to set filters first.
If you are on the Record index tab, click the
button to build the report, or the More filters button to set filters first.
If you are on the Audit Log tab, click the
button to build the report, or the More filters button to set filters first.
Set filters for the report. Filters are different for each system entities.
Click Apply and create report.
Specify the report name.
Check one or several report formats: XLS, JSON, CSV.
Choose whether to save the report images as links, thumbnails, or full frames. (Only for search results and global records).
Click Add. The report will be available for download on the Reports tab.
Work with Reports
You can access reports previously created in the system on the Reports tab. The following operations are available:
Download selected reported.
Update selected reports.
Delete selected reports.
See also
Audit Log
The FindFace CIBR comprehensive and searchable audit log is an excellent complementary tool for user management that provides you with a thorough audit of the user actions and strengthens your system protection. You can access this functionality on the Audit Logs tab.
Each record provides the following data:
username of the user who performed the action
IP address where the request came from
device id: the unique identifier of the client device
action type such as authorization, search, object modification, restart, and so on
object type to which the action applies, for example, a record or a case
object identifier
details, subject to the action type
timestamp
Use the filter panel above to set up the search conditions.
You can create a report by clicking the button or setting filters → Apply and create report.
The report will be available for download on the Reports tab.
Remote Alerting and Remote Search
This section covers an additional but very useful functionality which is a possibility of pulling face recognition events, matching with records on the local server, from remote facial recognition systems. This functionality has a large scope of possible applications. One course is tracking offenders’ location and routes and detecting alleged accomplices. Another one is finding missing people. The results are especially great if applied to Public and Transport Safety systems with thousands of cameras.
The remote alerting is disabled by default, so if you haven’t configured it yet, click here for instructions.
In this section:
Turn On/Off Remote Alerts for Individuals
To turn on/off remote alerts for a specific individual, do the following:
Navigate to Record Index.
Open the individual’s record.
Click three dots → Turn on remote alerts to enable remote alerting.
In the case you are turning on remote alerts, specify the reason for that. Click Turn on remote alerts.
Click three dots → Turn off remote alerts to disable remote alerting.
View Remote Alerts
You can view alerts from remote facial recognition systems on the Remote Alerting tab on the navigation bar. When a new event occurs an audio alert is triggered, and after the event is acknowledged the alert stops. You also can navigate to remote monitoring events by clicking the bell on a top panel, then Show events. You can turn off the alert sound by clicking Mute.
Do the following:
Navigate to the Remote Alerting tab.
Filter the alerts by date and time and a record name by clicking More filter, if needed.
Click the face to navigate to the sidebar of matched event.
Click the text bar of the thumbnail to navigate to the face record.
Click Acknowledge to acknowledge the event.
Search Individuals in Remote Systems
To search an individual in remote systems, do the following:
Navigate to Record Index.
Open the individual’s record.
Click three dots → Remote search.
Specify the search conditions, such as search reason, the confidence threshold, date and time of the individual’s appearance, and the maximum number of search results. Click Done.
The search results will be shown on the Remote Search tab.
If you click the left part with information of the event, you will navigate to the puppet events.
The following information is available on the results of searching:
puppet event date
puppet camera name
puppet name
event’s ID
thumbnail of face event
record that was turned on remote alerts
the match probability
You can filter search results by date and time, a record name and a user who initiated the search.
Daily Search
Daily search allows the puppeteer to receive scheduled events from the puppet with the matching of the records.
To use this functionality, see integration with remote facial recognition systems and do the following:
Enable daily search in the
/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.pyconfiguration file of the puppeteer.Enable
'DAILY'parameters and specify the time for matching the events with the records that were received from the puppeteer in the configuration file of the puppet.Navigate to the Watch list tab and check
Collect location datafor the watch list of your interest. For all records included in this list, all connected puppets return location data of objects of interest for the last 24 hours daily according to a set schedule, and if the flag is unchecked the puppets stop daily monitoring of the records in this list.The results will be shown on the Location Data tab of the individual’s record.
Integrations
This chapter is all about integration with FindFace. In the current version of FindFace, you can only integrate your system via HTTP API.
HTTP API
Detailed interactive documentation on the FindFace HTTP API is available after installation at http://<findface-ip:port>/api-docs. Learn and try it out.
Tip
You can also find it by navigating to in the web interface.