.. _external-vms: ******************************* 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. .. rubric:: In this section: .. contents:: :local: 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. Creating 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: .. code:: adduser --system --disabled-password --disabled-login --home /var/empty \ --no-create-home --quiet --force-badname --group ntech FindFace Multi ---------------------- #. Open the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` and locate ``External VMS Integration settings`` section. #. Change the ``ENABLED`` parameter to ``True``. #. Take a note of the ``TOKEN`` value, as you will need it to configure the plugin later. (The default value is ``VmsPluginToken PLUGIN_TOKEN``). .. 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://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 the case of using the separate machine, please consider specifying the proper address of the server where the VMS integration plugin resides in the ``PLUGIN_ADDRESS`` field. .. note:: If you need to send the events to VMS, please also set the ENABLED value to ``True`` in the ``EVENT_SENDER`` section. #. Restart the ``findface-multi-findface-multi-legacy-1`` container. .. code:: 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 | 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: PostgreSQL ----------------- #. Open the file ``/opt/findface-multi/docker-compose.yaml`` and take a note of ``POSTGRES_PASSWORD`` value. We will need this for the next step. .. code:: sudo vi /opt/findface-multi/docker-compose.yaml ... postgresql: environment: {POSTGRESQL_ALLOW_REMOTE_CONNECTIONS: 'no', POSTGRES_PASSWORD: POSTGRES_PASSWORD} ... #. Sign in to 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 signed in successfully, use the ``\l`` command to view the list of databases: |wms_databases_en| .. |wms_databases_en| image:: /_static/wms_databases_en.png :scale: 35% #. 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. |wms_exit_postgreSQL_en| .. |wms_exit_postgreSQL_en| image:: /_static/wms_exit_postgreSQL_en.png :scale: 35% .. _installing_plugin: Installing and configuring FindFace VMS Integration Plugin ------------------------------------------------------------------- #. Open the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` file and locate ``DATABASES`` section. Take a note of the ``PASSWORD`` value for user ``ntech``: .. code:: 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' } } #. Download FindFace plugin installation file (.deb) using the link from NtechLab representative. #. Install it using the command: .. code:: sudo dpkg -i findface-vms-integration-plugin_0.1.0_amd64.deb #. Open the config file of the plugin, located at ``/etc/findface-vms-integration-plugin.conf``. Uncomment and insert the following data here: .. code:: sudo vi /etc/findface-vms-integration-plugin.conf * POSTGRES_SERVER (specify the server, where postgresql container is running) * POSTGRES_PORT (use the value different from the one specified in config.py, for example, use ``5432``) * POSTGRES_USER (specify ``ntech``) * POSTGRES_PASSWORD (use the ``PASSWORD`` value for user ``ntech`` from the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` file, see :ref:`1.`) * POSTGRES_DB (specify ``ffsintegration``) * PUBLIC_URL (default: http://127.0.0.1:18333) * FFS_PUBLIC_URL (default: http://127.0.0.1) * FFS_TOKEN (specify the token as in the section ``EXTERNAL_VMS`` → ``TOKEN`` in ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` without prefix ``VmsPluginToken``) The resulting configuration file will look :download:`as follows <_scripts/findface-vms-integration-plugin.conf.txt>`: .. 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, please consider specifying the proper address of FindFace Multi server in the ``POSTGRES_SERVER`` field and the FindFace Multi URL in the ``FFS_PUBLIC_URL`` field. The rest parameters are optional and not required for the initial configuration. #. Update the database using the following command: .. code:: sudo /opt/findface-vms-integration-plugin/bin/vms-integration-plugin-alembic upgrade head In case of success, the output will look as follows: |wms_update_database_en| .. |wms_update_database_en| image:: /_static/wms_update_database_en.png :scale: 35% #. To start the plugin service and ensure the service is launching automatically, execute the following command: .. code:: sudo systemctl start findface-vms-integration-plugin && sudo systemctl enable findface-vms-integration-plugin && sudo systemctl status findface-vms-integration-plugin |wms_start_plugin_en| .. |wms_start_plugin_en| image:: /_static/wms_start_plugin_en.png :scale: 35% .. 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: Adding External VMS in FindFace Multi ------------------------------------------ #. Sign in to FindFace Multi in your web browser, go to :guilabel:`Settings` -> :guilabel:`External VMS` section. Click on the :guilabel:`Add new VMS` button. |wms_add_en| .. |wms_add_en| image:: /_static/wms_add_en.png :scale: 50% .. |wms_add_ru| image:: /_static/wms_add_ru.png :scale: 50% #. 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 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. |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% #. 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: |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% #. 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% 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.