Configuration

EyesOnIt reads configuration files from a designated configuration folder. These files control deployment-specific behavior outside the per-request REST payloads documented in the rest of this section.

Configuration Folder

The config folder needs to be created on the host and mapped to the container. To do that, create a folder on the host like /usr/local/EyesOnIt/input, and add the following to the docker run command:

-v /usr/local/EyesOnIt/input:/home/eyesonit_user/input

A complete docker run command would look like this:

docker run --name "eyesonit_v4.5" -d --label "eyesonit_v4.5" \
  --gpus all \
  --mount type=volume,source=eyesonit_output,target="/home/eyesonit_user/output" \
  --mount type=tmpfs,target=/tmp,tmpfs-size=128m \
  --cap-drop=ALL \
  --security-opt no-new-privileges \
  -p 8000:8000 \
  --restart unless-stopped \
  -e EOI_LICENSE_KEY=<EyesOnIt license key> \
  -e EOI_AUTHORIZATION_TOKEN=<EyesOnIt auth token> \
  -e "America/Los_Angeles" \
  -v "/usr/local/EyesOnIt/input:/home/eyesonit_user/input" \
  "eyesonit/eyesonit_v4.5:latest"

Under the /usr/local/EyesOnIt/input folder, create another folder named config. Create your config files within this folder.

Configuration Files

EyesOnIt will read .yml files from the config folder as follows:

vms_config.yml - Video Management System configuration file

This file contains configuration for Video Management System integrations and generic REST notification integrations. The file is optional, but Genetec event generation and generic REST notifications require it.

Complete Example

genetec:
    web_sdk_ip: genetec-websdk.customer.local
    web_sdk_port: 4590
    web_sdk_base_uri: WebSdk
    use_ssl: True
    verify_ssl: True
    ssl_certificate: input/config/genetec-websdk-ca.pem
    genetec_username: my_username
    genetec_password: my_password
    development_mode: False
    default_event_value: 8

rest:
    ssl_certificate:
    auth_type: none
    username:
    password:
    bearer_token:

Genetec Configuration

EyesOnIt sends Genetec detection notifications by calling the Genetec Web-based SDK RaiseCustomEvent endpoint. The genetec section controls how EyesOnIt reaches and authenticates to the Web-based SDK role.

genetec:
    web_sdk_ip: <Genetec Web-based SDK host name, IP address, or localhost>
    web_sdk_port: <Genetec Web-based SDK port number>
    web_sdk_base_uri: <Genetec Web-based SDK base URI>
    use_ssl: <True or False>
    verify_ssl: <True or False>
    ssl_certificate: <CA/root certificate file used to verify the Web-based SDK HTTPS certificate>
    genetec_username: <Genetec Web-based SDK username>
    genetec_password: <Genetec Web-based SDK password>
    development_mode: <True or False>
    default_event_value: <default Genetec custom event value>

Name	Required	Description
web_sdk_ip	Yes	Host used to connect to the Genetec Web-based SDK role. This may be an IP address, DNS host name, or localhost. For verify_ssl: True, this value must match a Subject Alternative Name on the Web-based SDK HTTPS certificate. In production, use a stable DNS name whenever possible.
web_sdk_port	Yes	Port for the Genetec Web-based SDK role. The default Genetec Web-based SDK port is commonly 4590, but use the value configured in Genetec.
web_sdk_base_uri	Yes	Base URI configured on the Genetec Web-based SDK role, usually WebSdk. Do not include a leading slash.
use_ssl	Yes	When True, EyesOnIt uses https://. When False, EyesOnIt uses http://. Production deployments should use True.
verify_ssl	No	Controls HTTPS certificate verification when use_ssl is True. Defaults to True. Set to False only for temporary development or troubleshooting.
ssl_certificate	No	Certificate file used by EyesOnIt to verify the Genetec Web-based SDK HTTPS certificate when use_ssl: True and verify_ssl: True. Leave blank only when the EyesOnIt runtime already trusts the Web-based SDK certificate chain. If provided, the file should be a PEM/Base-64 X.509 CA or self-signed root certificate and must not contain a private key. Absolute paths, input/... paths, and config-folder-relative filenames are supported.
genetec_username	Yes	Genetec user name used for Web-based SDK authentication. Use a dedicated EyesOnIt service account instead of a shared administrator account.
genetec_password	Yes	Password for genetec_username. Leave blank only if the Genetec account is configured to allow it. This value is a secret and vms_config.yml must be protected accordingly.
development_mode	No	Selects the EyesOnIt development Genetec SDK application certificate when True; selects the production EyesOnIt Genetec SDK application certificate when False. This is not the Web-based SDK HTTPS/TLS certificate; TLS verification is controlled by use_ssl, verify_ssl, and ssl_certificate. Production deployments should normally use False unless EyesOnIt support instructs otherwise.
default_event_value	No	Default Genetec custom event value to raise when a stream or detection rule does not provide a specific webhook_event_id. If no event value is available, EyesOnIt does not send the Genetec notification.

Genetec Credential Handling

genetec_username and genetec_password are used only to authenticate EyesOnIt to the Genetec Web-based SDK. They should belong to a dedicated Genetec service account created for EyesOnIt.

Recommended practice:

1. Create a Genetec user specifically for EyesOnIt.
2. Grant only the permissions required for Web-based SDK access and custom event generation.
3. Do not use the built-in Admin account for production deployments.
4. Keep vms_config.yml out of source control.
5. Store the mounted input/config folder on a protected host path with permissions limited to the EyesOnIt service administrator.
6. Use use_ssl: True and verify_ssl: True so the credentials are sent only to a verified Genetec Web-based SDK endpoint.

The current vms_config.yml format stores the Genetec password directly in the file. Treat this file as a secrets file.

When EyesOnIt sends an alert to Genetec, it combines the Genetec connection fields with the webhook_event_id and webhook_camera_uuid fields provided to the add_stream method, or with values configured by the EyesOnIt Genetec plugin. The resulting URL is:

<http-or-https>://<web_sdk_ip>:<web_sdk_port>/<web_sdk_base_uri>/events/RaiseCustomEvent/<webhook_event_id>/<webhook_camera_uuid>

For example:

https://genetec-websdk.customer.local:4590/WebSdk/events/RaiseCustomEvent/8/00000001-0000-babe-0000-0002d193c792

Genetec SSL Certificate Setup

For secure deployments, configure the Genetec Web-based SDK role to use HTTPS and configure EyesOnIt with use_ssl: True and verify_ssl: True.

The certificate used by the Genetec Web-based SDK is configured in Genetec Server Admin, not in Config Tool. Config Tool can show Web-based SDK SSL status and certificate information, but current Genetec versions may not provide certificate selection in the Web-based SDK role page.

The recommended production setup is:

1. Create or select a DNS name for the Genetec Web-based SDK server, such as genetec-websdk.customer.local.
2. Install a server certificate in Genetec Server Admin whose Subject Alternative Name includes that DNS name.
3. Configure the Genetec Web-based SDK role to use SSL.
4. Export the public CA/root certificate that issued the Web-based SDK server certificate as Base-64 X.509/PEM.
5. Place that certificate file in the EyesOnIt input/config folder.
6. Configure vms_config.yml with use_ssl: True, verify_ssl: True, and ssl_certificate pointing to that exported CA/root certificate.

Example:

genetec:
    web_sdk_ip: genetec-websdk.customer.local
    web_sdk_port: 4590
    web_sdk_base_uri: WebSdk
    use_ssl: True
    verify_ssl: True
    ssl_certificate: input/config/genetec-websdk-ca.pem
    genetec_username: my_username
    genetec_password: my_password
    development_mode: False
    default_event_value: 8

For a local development system where EyesOnIt connects to the Genetec Web-based SDK on the same machine, the Web-based SDK certificate must include DNS:localhost if web_sdk_ip: localhost is used with verify_ssl: True.

genetec:
    web_sdk_ip: localhost
    web_sdk_port: 4590
    web_sdk_base_uri: WebSdk
    use_ssl: True
    verify_ssl: True
    ssl_certificate: input/config/localhost-genetec-root.pem
    genetec_username: my_username
    genetec_password: my_password
    development_mode: True
    default_event_value: 8

Do not use verify_ssl: False in production. It disables certificate validation and allows EyesOnIt to connect to an HTTPS endpoint without proving that the endpoint is the intended Genetec server.

Genetec Custom Event Setup

You must configure Genetec to handle events from EyesOnIt by creating custom events through Genetec Config Tool. The settings for custom events are in Config Tool > System > General Settings > Events. The event number assigned to the custom event is the value EyesOnIt sends as webhook_event_id or default_event_value.

Generic REST API Configuration

EyesOnIt can also make generic REST notification calls. For these calls, the rest section in vms_config.yml controls authentication and HTTPS certificate verification.

rest:
    ssl_certificate: <certificate .pem file if needed>
    auth_type: <none, basic, digest, or bearer>
    username: <username for basic or digest auth>
    password: <password for basic or digest auth>
    bearer_token: <bearer token for bearer auth>

Name	Required	Description
ssl_certificate	No	Certificate file used to verify HTTPS REST endpoints. Leave blank to use the default system trust store. If provided, the path must exist inside the EyesOnIt runtime.
auth_type	Yes	Authentication type for generic REST notifications. Valid values are none, basic, digest, and bearer.
username	Conditional	User name for basic or digest authentication. Ignored for none and bearer.
password	Conditional	Password for basic or digest authentication. Ignored for none and bearer.
bearer_token	Conditional	Token used for bearer authentication. Ignored for none, basic, and digest.

Example:

rest:
    ssl_certificate:
    auth_type: digest
    username: my_username
    password: my_password
    bearer_token:

When EyesOnIt sends a generic REST alert, it uses the POST method to send data to the rest_url provided in the notification parameters of the add_stream method. The body of the request follows the same structure returned by the get_last_detection_info endpoint.

{
    "detections": [
        {
            "stream_url": "rtsp://<username>:<password>@<camera-ip>/live0",
            "region": "Doorway",
            "time": "2025-03-17T22:27:33Z",
            "frame_num": 75,
            "class_name": "person",
            "condition": {
                "type": "count_greater_than",
                "count": 0,
                "line_name": null,
                "alert_direction": null,
                "objects": [
                    {
                        "detection_type": "class_name",
                        "class_name": "person",
                        "class_confidence": 99,
                        "object_descriptions": [
                            {
                                "text": "person",
                                "confidence": 99,
                                "over_threshold": true
                            }
                        ],
                        "bounds": {
                            "left": 837,
                            "top": 15,
                            "width": 581,
                            "height": 1072
                        }
                    }
                ]
            }
        }
    ],
    "image": "<base64-encoded image string>"
}

REST POST Body Attributes

Name	Type	Description
stream_url	string	the RTSP URL for the stream where the detection occurred
region	string	the friendly name for the region where the detection occurred
time	string	the time (UTC) when the detection occurred
class_name	string	the common object type associated with the detection, or null if no common object type was used.
condition	Detection Condition	the detection condition that triggered the detection

eoi_streams.json - Stream definition JSON file

The config folder can contain a eoi_streams.json file. This file can contain the definition of one or more streams to load automatically when EyesOnIt runs. The format of the eoi_streams.json file exactly matches the JSON sent to the add_stream method of the REST API. Here is an example of a eoi_streams.json file:

{
    "rtsp://username:password@192.168.1.14/live": {
        "name": "Back Alley Camera",
        "stream_url": "rtsp://username:password@192.168.1.14/live0",
        "frame_rate": 15,
        "regions": [
            {
                "enabled": true,
                "name": "Back Alley",
                "polygon": [
                    {
                        "x": 528,
                        "y": 175
                    },
                    {
                        "x": 876,
                        "y": 166
                    },
                    {
                        "x": 896,
                        "y": 285
                    },
                    {
                        "x": 506,
                        "y": 279
                    },
                    {
                        "x": 528,
                        "y": 175
                    }
                ],
                "motion_detection": {
                    "enabled": true,
                    "detection_threshold": 300,
                    "regular_check_frame_interval": 1,
                    "backup_check_frame_interval": null
                },
                "detection_configs": [
                    {
                        "class_name": "vehicle",
                        "class_threshold": 10,
                        "object_size": 150,
                        "object_descriptions": [
                            {
                                "text": "black sedan",
                                "threshold": 90,
                                "alert": true,
                                "background_prompt": false
                            },
                            {
                                "text": "vehicle",
                                "threshold": 90,
                                "alert": false,
                                "background_prompt": false
                            },
                            {
                                "text": "street building",
                                "threshold": null,
                                "alert": false,
                                "background_prompt": true
                            }
                        ],
                        "conditions": [
                            {
                                "type": "count_greater_than",
                                "count": 0,
                                "line_name": null,
                                "alert_direction": null
                            }
                        ],
                        "alert_seconds": 0.3,
                        "reset_seconds": 2.0
                    }
                ]
            },
        ],
        "lines": [
            {
                "name": "loading zone entrance",
                "vertices": [
                    {
                        "x": 1302,
                        "y": 159
                    },
                    {
                        "x": 1047,
                        "y": 480
                    }
                ]
            }
        ],
        "notification": {
            "phone_number": null,
            "include_image": false,
            "rest_url": null
        }
    },
        "rtsp://username:password@192.168.1.15/live": {
        "name": "Back Alley Camera2",
        ...
    }
}

JSON Format Description

The json in eoi_streams.json is a dictionary. The key for each entry is the stream URL. The value for each entry has the following fields:

Name	Type	Description
name	string	a friendly name for the stream used in the EyesOnIt Web UI and in alerts
stream_url	string	the RTSP URL for the stream including credentials required to connect to the stream
frame_rate	integer	the frame rate for this stream. This attribute is optional. The default value is 5.
regions	Region[]	an array of detection regions
lines	Line[]	an array of boundary lines
notification	Notification	the notification settings for this stream