.. _external-vms: ******************************* External VMS ******************************* FindFace Multi includes built‑in integration with external video management systems (VMS), allowing you to import VMS cameras into FindFace Multi for processing. Once a VMS camera has been added, it supports exactly the same actions as any native FindFace Multi camera. Integration with External 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. .. rubric:: In this section: .. contents:: :local: This is the step-by-step configuration guide for installing and configuring the External VMS feature in FindFace Multi. The user should have strong experience administering Linux OS and Docker containers. Create a Service Account for VMS Integration Plugin --------------------------------------------------------------- Create a user (username: **ntech**) with a specific set of permissions. This will be used as the service account for the integration plugin. To do so, execute the command below: .. code:: 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 --------------------------------------------------------------------- #. Open the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` file and locate the ``External VMS Integration settings`` section. #. Change the ``'ENABLED'`` parameter to ``True``. #. Write down the ``TOKEN`` value, as you will need it to configure the plugin later. The default value is ``PLUGIN_TOKEN``. Please note that the ``VmsPluginToken`` token prefix should only be in the ``findface-multi-legacy.py`` configuration file. If the plugin is installed on the same host as FindFace Multi, use the container name and port ``http://findface-vms-integration-plugin:18333`` as the plugin address. .. code:: ... # -- 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://findface-vms-integration-plugin: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 this example, the plugin is installed on the same host as FindFace Multi. If the plugin is installed on a separate host, specify the server’s address in the ``PLUGIN_ADDRESS`` parameter. .. note:: If you need to send events to VMS, set the ``'ENABLED'`` value to ``True`` in the ``EVENT_SENDER`` section. #. Restart all FindFace Multi containers. .. code:: cd /opt/findface-multi/ sudo docker-compose restart 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 are sent to an external VMS. | +---------------------------------------------------+-------------------------------------------------------------------------------------------------+ | ``ALLOWED_TYPES`` | Object types to send ``['face', 'body', 'car']``. | +---------------------------------------------------+-------------------------------------------------------------------------------------------------+ | ``SENDER_TASKS`` | The number of simultaneous tasks to send events to the plugin. Default value = 1. | | | If necessary, it can be increased. 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`` | The time between sending attempts, if a failed sending occurs. It will grow | | ``MAX_EVENT_SEND_TIMEOUT`` | 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. | +---------------------------------------------------+-------------------------------------------------------------------------------------------------+ .. _postgreSQL: Create New Database in PostgreSQL -------------------------------------- #. Open the file ``/opt/findface-multi/docker-compose.yaml`` and write down the ``POSTGRES_PASSWORD`` value. You will need it for the next step. .. code:: sudo vi /opt/findface-multi/docker-compose.yaml ... postgresql: environment: {POSTGRES_PASSWORD: POSTGRES_PASSWORD} ... #. Enter the ``findface-multi-postgresql-1`` container via executing the following command: .. code:: sudo docker exec -i findface-multi-postgresql-1 /bin/bash -c "PGPASSWORD={POSTGRES_PASSWORD} psql --username postgres" To ensure you’ve successfully shelled into a container, use the ``\l`` command to view the list of databases: .. code:: List of databases Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges ------------------------------+----------+----------+-----------------+-------------+-------------+------------+-----------+----------------------- alerts | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity_audit | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity_identity_provider | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | postgres | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | replication_receiver | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | replication_sender | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | superset | superset | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | template0 | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | =c/postgres + | | | | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | =c/postgres + | | | | | | | | postgres=CTc/postgres (10 rows) #. Run the following command to create the new database required for external VMS functionality: .. code:: CREATE DATABASE ffsintegration WITH OWNER ntech ; #. Validate the database creation via executing ``\l`` again. Once completed, use ``\q`` parameter to exit PostgreSQL. .. code:: CREATE DATABASE ffsintegration WITH OWNER ntech ; CREATE DATABASE \l List of databases Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges ------------------------------+----------+----------+-----------------+-------------+-------------+------------+-----------+----------------------- alerts | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity_audit | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsecurity_identity_provider | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | ffsintegration | ntech | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | postgres | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | replication_receiver | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | replication_sender | ntech | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | superset | superset | UTF8 | libc | C.UTF-8 | C.UTF-8 | | | template0 | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | =c/postgres + | | | | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | | =c/postgres + | | | | | | | | postgres=CTc/postgres (11 rows) \q .. _installing_plugin: Install and Configure FindFace VMS Integration Plugin ------------------------------------------------------------------- #. 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``: .. code:: sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py ... # Database is used to store cameras, 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': 'pgbouncer', 'PORT': 6432, 'USER': 'ntech', 'PASSWORD': 'PASSWORD' } } #. Request the plugin ``findface-vms-integration-plugin.img`` from an NtechLab representative. #. Load the plugin into the system. .. code:: docker load < findface-vms-integration-plugin.img #. Configure the ``/opt/findface-multi/docker-compose.yaml`` file to add the ``findface-vms-integration-plugin`` section. .. code:: sudo vi /opt/findface-multi/docker-compose.yaml Add the ``findface-vms-integration-plugin`` section to the end of the ``/opt/findface-multi/docker-compose.yaml`` file. .. code:: findface-vms-integration-plugin: depends_on: [findface-ntls, postgresql, findface-multi-legacy] image: findface-vms-integration-plugin:latest networks: [product-network] volumes: ['./configs/findface-vms-integration-plugin/findface-vms-integration-plugin.conf:/etc/findface-vms-integration-plugin.conf'] restart: always .. tip:: The plugin version might differ from that listed in this documentation. For the latest version, contact technical support by support@ntechlab.com. #. Create the configuration file for the plugin. .. code:: sudo mkdir configs/findface-vms-integration-plugin/ sudo vi configs/findface-vms-integration-plugin/findface-vms-integration-plugin.conf There is an example of the ``findface-vms-integration-plugin.conf`` configuration file below. .. code:: # 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: 0.0.0.0 # 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://172.23.218.85 # Replace 172.23.218.85 with your FindFace Multi IP address. # 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: postgresql # name of the postgresql container # Database port number # POSTGRES_PORT: 5432 # Database user # POSTGRES_USER: ntech # Database user password # POSTGRES_PASSWORD: POSTGRES_PASSWORD # the PostgreSQL password for the ``ntech`` user from the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file # 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: DEBUG # 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 this example, the plugin is installed on the same host as FindFace Multi. If the plugin is installed on a separate host, specify the FindFace Multi server’s address in the ``POSTGRES_SERVER`` parameter and the FindFace Multi URL in the ``FFS_PUBLIC_URL`` parameter. #. If you installed the plugin on the FindFace Multi host, you only need to configure the login and password to the local PostgreSQL database. .. code:: 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. #. To enable the external VMS plugin in FindFace Multi start all FindFace Multi containers from the ``/opt/findface-multi`` directory. .. code:: sudo docker-compose up -d #. Open FindFace Multi in a web browser. You will see the :guilabel:`Settings` → :guilabel:`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: Add External VMS in FindFace Multi -------------------------------------------- #. In the :guilabel:`Settings` → :guilabel:`External VMS` section, click on the :guilabel:`+ New VMS` button. |wms_add_en| .. |wms_add_en| image:: /_static/wms_add_en.png :scale: 65% .. |wms_add_ru| image:: /_static/wms_add_ru.png :scale: 65% #. Specify your VMS parameters in the opened windows and click on the :guilabel:`Save` button once ready: |wms_info_en| .. |wms_info_en| image:: /_static/wms_info_en.png :scale: 65% .. |wms_info_ru| image:: /_static/wms_info_ru.png :scale: 65% #. Once completed, you can manage the streams from your VMS on the :guilabel:`Cameras` tab. For instance, you may add all or selected cameras in FindFace Multi instantly. |wms_cameras_en| .. |wms_cameras_en| image:: /_static/wms_cameras_en.png :scale: 55% .. |wms_cameras_ru| image:: /_static/wms_cameras_ru.png :scale: 55% #. If you need to send events to an external VMS, check the camera settings imported from the VMS to ensure they are configured to forward the events to the external VMS: |wms_general_en| .. |wms_general_en| image:: /_static/wms_general_en.png :scale: 65% .. |wms_general_ru| image:: /_static/wms_general_ru.png :scale: 65% #. When you click the |ellipsis_button| button on the processing configuration wizard for a created camera, the following actions are available: .. |ellipsis_button| image:: /_static/ellipsis_button.png :scale: 50% * Filer events * Activate/Deactivate * Delete * Restart * Reset to default * Duplicate #. In the required watch list properties, activate the checkbox ``Send mapping events to VMS`` and click on :guilabel:`Save` button to apply the changes. |wms_watch_list_prop_en| .. |wms_watch_list_prop_en| image:: /_static/wms_watch_list_prop_en.png :scale: 65% .. |wms_watch_list_prop_ru| image:: /_static/wms_watch_list_prop_ru.png :scale: 65% #. Sent and received messages can be viewed in the corresponding tabs of the target VMS: |wms_messages_en| .. |wms_messages_en| image:: /_static/wms_messages_en.png :scale: 65% .. |wms_messages_ru| image:: /_static/wms_messages_ru.png :scale: 65% #. If a Video Recorder is :ref:`deployed ` and :ref:`configured `, you can play the video archives of the external VMS (Axxon, Trassir) through it. To use this functionality, first check the camera added from VMS is active. Then navigate to the :guilabel:`Episodes & Events` tab and hover over the event or episode of your interest. The play button will display on the thumbnail of the object (face/body or vehicle). Press it to start playing the video from the time when the event/episode was recorded from the camera. |wms_player_event_en| .. |wms_player_event_en| image:: /_static/wms_player_event_en.png :scale: 70% .. |wms_player_event_ru| image:: /_static/wms_player_event_ru.png :scale: 70% You can also play the video archive through the camera by clicking play on the camera thumbnail in the camera list on the :guilabel:`Video Sources` tab. As a result, the video from the external VMS camera will be displayed in the Video Recorder. If there is a recorded video archive in FindFace Multi at the specified time, then it will be played in the Video Recorder instead of the video from an external VMS. |wms_player_camera_en| .. |wms_player_camera_en| image:: /_static/wms_player_camera_en.png :scale: 60% .. |wms_player_camera_ru| image:: /_static/wms_player_camera_ru.png :scale: 60% Now, your FindFace Multi installation is enhanced by external VMS support. You may connect as many VMS systems as required and add existing video streams in FindFace seamlessly within just a few clicks.