External VMS

On the FindFace Multi side, a mechanism of integration with third-party VMS is implemented, allowing you to add cameras from the latter to FindFace Multi and perform their processing. When a camera from a VMS is added, all the actions available for a regular FindFace Multi camera become available for it.

Integration with third-party VMS is possible through a plug-in layer. Interaction between the plugin and FindFace Multi is performed via HTTP. The plugin interacts with the VMS, FindFace Multi interacts with the plugin.

In this section:

This is the step-by-step configuration guide for installing and configuring External VMS feature in FindFace Multi. The reader should have strong experience of administering Linux OS and Docker containers.

Create a Service Account for VMS Integration Plugin

Create a user (username: ntech) with specific set of permissions. This will be used as the service account for the integration plugin. To do so, execute the command below:

adduser --system --disabled-password --disabled-login --home /var/empty \
                --no-create-home --quiet --force-badname --group ntech

Configure FindFace Multi to Enable External VMS Integration Plugin

1. Open the /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py file and locate the External VMS Integration settings section.

2. Change the 'ENABLED' parameter to True.

3. Write down the TOKEN value, as you will need it to configure the plugin later. (The default value is VmsPluginToken PLUGIN_TOKEN).

   ...
   # -- External VMS integration settings --
      # cleanup settings
      'EXTERNAL_VMS_EVENTS_MAX_AGE': 0,
      'EXTERNAL_VMS_SEND_EVENTS_STATUS_MAX_AGE': 0,
      'EXTERNAL_VMS': {
          'ENABLED': True,
          'PLUGIN_ADDRESS': 'http://127.0.0.1:18333',
          'TOKEN': 'VmsPluginToken PLUGIN_TOKEN',
          'EVENT_SENDER': {
              'ENABLED': True,
              'ALLOWED_TYPES': ['face'],
              'SENDER_TASKS': 1,
              'MAX_SEND_ATTEMPTS': 1,
              'MIN_EVENT_SEND_TIMEOUT': 0.1,
              'MAX_EVENT_SEND_TIMEOUT': 100,
              'RESPONSE_TIMEOUT': 10,
          },
      },
   ...
   

   Tip

   In our example, we are installing the plugin on the same host where FindFace Multi installation resides. In case of using the separate machine to install the plugin, please consider specifying the proper address of the server where the VMS integration plugin resides in the PLUGIN_ADDRESS parameter.

   Note

   If you need to send the events to VMS, please also set the 'ENABLED' value to True in the EVENT_SENDER section.

4. Restart the findface-multi-findface-multi-legacy-1 container.

   sudo docker container restart findface-multi-findface-multi-legacy-1
   

Brief description of the parameters available below:

Parameter	Description
EXTERNAL_VMS_EVENTS_MAX_AGE	Time to store the events received from an external VMS system (days). 0 – unlimited.
EXTERNAL_VMS_SEND_EVENTS_STATUS_AGE	Time to store the events sent to an external VMS system (days). 0 – unlimited.
EXTERNAL_VMS: ENABLED	The status of FindFace VMS Integration module. If enabled, the External VMS option will appear in the user interface.
PLUGIN_ADDRESS	Plugin IP address.
TOKEN	Token required for VMS Integration plugin to authenticate in Findface Multi (it must match the token in the plugin configuration file).
EVENT_SENDER:ENABLED	If True, all matched events in Findface Multi will be sent to an external VMS.
ALLOWED_TYPES	Objects types to send. At present, only face objects supported.
SENDER_TASKS	The number of simultaneous tasks to send events to the plugin. Default value = 1. It can be increased if required, please consult NtechLab Support Team (support@ntechlab.com).
MAX_SEND_ATTEMPTS	The number of attempts to send before it is considered unsuccessful.
MIN_EVENT_SEND_TIMEOUT MAX_EVENT_SEND_TIMEOUT	The time between sending attempts, if a failed sending occurs. It will grow exponentially from minimum to maximum as long as the number of attempts MAX_SEND_ATTEMPTS is increasing.
RESPONSE_TIMEOUT	Time to wait for a response from the plugin when sending an event.

Create New Database in PostgreSQL

1. Open the file /opt/findface-multi/docker-compose.yaml and write down the POSTGRES_PASSWORD value. You will need it for the next step.

   sudo vi /opt/findface-multi/docker-compose.yaml
   ...
    postgresql:
      environment: {POSTGRESQL_ALLOW_REMOTE_CONNECTIONS: 'no', POSTGRES_PASSWORD: POSTGRES_PASSWORD}
   ...
   

2. Enter the findface-multi-postresql-1 container via executing the following command:

   sudo docker exec -i findface-multi-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres"
   

   To ensure you’ve signed in successfully, use the \l command to view the list of databases:

   

3. Run the following command to create the new database required for external VMS functionality:

   CREATE DATABASE ffsintegration WITH OWNER ntech ;
   

4. Validate the database creation via executing \l again. Once completed, use \q parameter to exit PostgreSQL.

   

Install and Configure FindFace VMS Integration Plugin

1. Open the /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py file and locate the DATABASES section. Write down the PASSWORD value for user ntech:

   sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py
   
   ...
   # camera groups, watchlists and so on. Only PostgreSQL is supported.
   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.postgresql',
           'DISABLE_SERVER_SIDE_CURSORS': True,
           'NAME': 'ffsecurity', 'HOST': '127.0.0.1', 'PORT': 5439, 'USER': 'ntech', 'PASSWORD': 'PASSWORD'
       }
   }
   

2. Request the plugin findface-vms-integration-plugin.img from an NtechLab representative.

3. Load the plugin into the system.

   docker load < findface-vms-integration-plugin.img
   

4. Configure the /opt/findface-multi/docker-compose.yaml file to add the findface-vms-integration-plugin section.

   cd /opt/findface-multi/
   
   sudo vi docker-compose.yaml
   

   Add the findface-vms-integration-plugin section to the end of the docker-compose.yaml file.

   findface-vms-integration-plugin:
     depends_on: [findface-ntls, postgresql, findface-multi-legacy]
     image: findface-vms-integration-plugin:latest
     network_mode: service:pause
     volumes: ['./configs/findface-vms-integration-plugin/findface-vms-integration-plugin.conf:/etc/findface-vms-integration-plugin.conf']
     restart: always
   

5. Create the configuration file for the plugin.

   sudo mkdir configs/findface-vms-integration-plugin/
   sudo vi configs/findface-vms-integration-plugin/findface-vms-integration-plugin.conf
   

   Below is a sample of the findface-vms-integration-plugin.conf configuration file.

   # URL prefix for API version 1 endpoints
   # Default: /api/v1
   #
   API_V1_STR: /v1
   
   # App listens on this interface. Set it to 0.0.0.0 to listen on all available interfaces
   # Default: 127.0.0.1
   #
   # HOST: 127.0.0.1
   
   # App accepts HTTP connections on this port
   # Default: 18333
   #
   # PORT: 18333
   
   # Public URL for App
   # Default: http://127.0.0.1:18333
   #
   # PUBLIC_URL: http://127.0.0.1:18333
   
   # Public URL for FFS
   # Default: http://127.0.0.1
   #
   # FFS_PUBLIC_URL: http://127.0.0.1:18333
   
   # Full database URL dialect+driver://username:password@host:port/database.
   # Alternatively, connection parameters can be specified one by one (see below).
   #
   # SQLALCHEMY_DATABASE_URI:
   
   # Database host
   #
   POSTGRES_SERVER: 127.0.0.1
   
   # Database port number
   #
   POSTGRES_PORT: 5432
   
   # Database user
   #
   POSTGRES_USER: ntech
   
   # Database user password
   #
   POSTGRES_PASSWORD: POSTGRES_PASSWORD
   
   # Database name
   #
   POSTGRES_DB: ffsintegration
   
   # Log SQL statements
   # Default: FALSE
   #
   # LOG_QUERIES: FALSE
   
   # Secret token used to validate requests made by FindFace Security
   # Required: yes
   #
   FFS_TOKEN: PLUGIN_TOKEN
   
   # Include traceback information in error responses
   # Default: FALSE
   #
   RESP_TRACEBACK: True
   
   # Logging level
   # Default: INFO
   #
   # LOG_LEVEL:
   
   # Enable journald log handler.
   # Default: TRUE
   #
   # LOG_TO_JOURNALD: TRUE
   
   # Timeout for requests to VMS
   # Default: 10
   #
   # VMS_REQUEST_TIMEOUT_SEC: 10
   
   # Timeout for requests to FindFace
   # Default: 10
   #
   # FF_REQUEST_TIMEOUT_SEC: 10
   

   Tip

   In our example, we are installing the plugin on the same host where FindFace Multi installation resides. In case of using a separate machine, please consider specifying the proper address of FindFace Multi server in the POSTGRES_SERVER parameter and the FindFace Multi URL in the FFS_PUBLIC_URL parameter.

6. If you installed the plugin on the FindFace Multi host, you only need to configure the login and password to the local PostgreSQL database.

   POSTGRES_USER: ntech
   POSTGRES_PASSWORD: POSTGRES_PASSWORD
   

   The POSTGRES_PASSWORD value can be obtained from the /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py file.

7. To enable the external VMS plugin in FindFace Multi start all FindFace Multi containers from the /opt/findface-multi directory.

   sudo docker-compose up -d
   

8. Open FindFace Multi in a web browser. You will see the Settings -> External VMS section.

Warning

It is necessary to set the same time zone on the external VMS server as on the FindFace Multi server for correct playback of video archives from the external VMS.

Add External VMS in FindFace Multi

1. In the Settings -> External VMS section, click on the Add new VMS button.

   

2. Specify your VMS parameters in the opened windows and click on the Save button once ready:

   

3. Once completed now you can manage the streams from your VMS in the Cameras tab. For instance, you may add all or selected cameras in FindFace Multi instantly.

   

4. Should you need to send the events to an external VMS, In the Camera settings added from VMS, check if it configured to send the events to the external VMS:

   

5. In the required watch list properties, activate the checkbox Send mapping events to VMS and click on Save button to apply the changes.

   

6. Sent and received messages can be viewed in the corresponding tabs of the target VMS:

   

Now, your FindFace Multi installation is enhanced by external VMS support. You may connect as many VMS systems and required and add existing video streams in FindFace seamlessly within just a few clicks.