Configuration Script

Configuration script mmid-ctl.sh has a set of configuration and deployment actions. Each of them will be described in this document.

Some actions require options to be passed. If no options are passed, default values are used/configured.

To print all available actions and options, script should be run directly:

./mmid-ctl.sh

In other cases action and where needed options should be passed:

./mmid-ctl.sh <action> [options]

Actions

Currently the configuration script supports these actions:

Action	Options	Glossary
config	installation and config	used to reconfigure the server after installation
apply-config	none	after config action used to stop the server and load new configuration
load-images	none	used to load docker images from disk to docker engine
install	installation	used to configure and install the server
update	none	used when updated MegaMatcher ID server is released and an update is desired
start	none	used to start the servers docker containers
stop	none	used to stop the servers docker containers
remove	none	used to remove servers docker containers
restart	none	used to restart servers docker containers
backup-db	backup	used to back up the database
restore-db	restore	used to restore the database backup
print-default-config	none	prints default config values
print-current-config	none	prints how server is currently configured

Installation

This action is used to install MegaMatcher ID Web Service on a new OS meeting requirements. Implying the installation files are already unziped, the configuration script can be used for installation:

./mmid-ctl.sh install

This will install face verification server with options. If non-default options should be used, an option for configuration should be passed. For example, when wanting to install a new MegaMatcher ID server with debug logging level, url licensing mode and other default options this install command should be used:

./mmid-ctl.sh install --log-level --licensing-mode

After installing the server, docker containers should be started:

./mmid-ctl.sh start

From this point the server should be running. Please refer to getting started for sending your first biometric transaction.

Config

After installation server can be reconfigured if needed. Most common scenario would be turning off development properties before going to production environment. Implying the installation files are already unziped, the configuration script can be used for reconfiguration:

./mmid-ctl.sh config

When running the config action without options, only the ip address of the server can be configured. For example, when wanting to turn off database clear in development properties and change log level verbosity, this config command should be used:

./mmid-ctl.sh config --log-level --development-properties

After configuring the server, the configuration has to by applied to the current config files with apply-config action:

./mmid-ctl.sh apply-config

This command will print what configuration files have been changed, and they should be reviewed manually before proceeding. Notice: old configuration files are saves with .bak extension. When configuration files are reviewed, services can be started once again:

./mmid-ctl.sh start

Update

When new MegaMatcher ID server version is released, update command should be used to update existing installation.

Before proceeding it is advised to make a database backup.

New installation zip should be extracted and the configuration script (./mmid-ctl.sh) from the new directory can be used for update:

./mmid-ctl.sh update

The command will stop the server, load configurations and new docker containers. This command will print if any configuration files have been changed, and they should be reviewed manually before proceeding.

Notice: old configuration files are saves with .bak extension.

When configuration files are reviewed, services can be started once again:

./mmid-ctl.sh start

Docker containers will be recreated using new images and services will be started.

Database backup

Configuration script can be used for database backuping:

./mmid-ctl.sh backup-db

The command will backup the database, and log will contain filepath for the backup:

<...>
[00] 2021-10-23 10:27:56 Last binlog file , position 0
[00] 2021-10-23 10:27:56 completed OK!
Preparing backup mmid-db-backup-2021-10-23-062754...
Backup of FV database completed successfully.
Backup file: /opt/megamatcherid/megamatcherid-server/db/backup/mmid-db-backup-2021-10-23-062754.tar

During the backup services can be running. The backup script will not turn off the server.

Database restore

Configuration script can be used to restore a database backup:

./mmid-ctl.sh restore-db --backup-file <backup-file>

<backup-file> should be replaced by an archive generated by backup-db action:

./mmid-ctl.sh restore-db --backup-file /opt/megamatcherid/megamatcherid-server/db/backup/mmid-db-backup-2021-10-23-062754.tar

If current database contains any data, it will be erased! Database restore stops services during the procedure, therefore services should be started once restore is finished:

./mmid-ctl.sh start

Options

For actions that support options, multiple options can be passed:

./mmid-ctl.sh config --licensing-mode --log-level

Notice that when passing options, each option should begin with --, for example --licensing-mode.

Installation and config

Option	Glossary
licensing-mode	configures licensing mode
keep-images	configures log image keeping policy
ports	configures service ports used in installation
log-level	configures log level
development-properties	configures properties helpful in development
gpu	configures GPU usage properties
db	configure database settings
ssl	configures ssl certificates for web containers
mmabis	configures enrollment to MMABIS
timeout	configures timeouts
janus	configure janus settings
network-mode	configure container network mode
auth-mode	configure authorization mode

Licensing mode

Allows to configure non default licensing mode during install or config actions. Three licensing modes are supported:

• trial (default) - Neurotechnology trial licensing service will be used in this case
• url - user will be asked to enter his own licensing service address. This option should be used when MegaMatcher ID License server is installed during separate installation.
• local-server - used when user has purchased three-dongle set for MegaMatcher ID server licensing and the licensing service is installed during this installation. Application and installation ids (comes with the dongles) will be asked to enter if this licensing mode is selected.
• internet-license - used when user has purchased internet license for MegaMatcher ID server licensing and the licensing service is installed during this installation. Application id, installation id and the location of license private key and license certificate (comes with the internet license).

Keep images

Allows to configure log image keeping policy. Three modes are supported:

• temporary (default) - images and token images are saved temporarily (10 minutes) to db after doing a successful operation after which they are deleted. Template saving is not affected.
• always - images, token images and templates are all saved to db after doing a successful operation.
• never - only templates are saved to db after doing a successful operation.

Ports

Allows to configure service ports during install or config actions. Currently services are using these ports (not all are used externally):

Name	Default	Used externally	Glossary
Janus	40001	-	Used by Management for registering new connections
Management	40002	+	Used by Manager web and Web services
Management GRPC	40003	-	Used by Biostream to return operation results
Management web	40004	+/-	Used for Management configuration. Can be used externally
Web	40005	+	Main entry point for accessing Web service
Biostream	40006	-	Gets image stream from Janus
Data service	40007	-	Used by Management to access data in the database
Licensing service	40008	-	Used only if local licensing service is configured

Log level

Allows to configure log level during install or config actions. Currently there are three log levels supported:

• info (default) - logging informational events
• debug - verbose logging for debugging purposes
• trace - very verbose logging including network events and dumping image stream. Should not be used on production or multiple connections as produces large amounts of log and may slow down the services.

Development properties

Allows to configure development properties during install or config actions. These properties are recommended to be turned off during production.

Purpose	Default	Glossary
Save images from biostream service	no	Saves captured images for debugging purposes in /opt/megamatcherid/megamatcherid-server/images. Should not be used in production and may require a lot of storage.
Allow management settings override	no	Allows to send operation settings (liveness mode, matching threshold, etc.) from user rather then using ones configured in management. Should be turned off in production.
Allow clear database	no	Allows to clear the database from Management web service. Useful in development but should be turned off during production.

GPU

Allows to configure GPU usage during install or config actions. When this option is specified, you will be asked if GPU should be used for stream decoding and/or for the processing of biometric operations during configuration or installation.

To use this option some prerequisites have to be met:

• docker compose v1.28 or newer. You can check the version with the docker compose version --short or docker-compose version --short command.
• nvidia-cuda-toolkit must be installed. You can check if it's installed with the nvcc --version command.
• proper nvidia drivers must be installed. You can check the drivers using the nvidia-smi command.

Database

Allows to configure the database during install or config actions. When this option is specified, you will be asked whether you want to change the database password, whether you want the mmid-ctl to install all MMID services, only the database service (for high availability) or only the database (usually on 4th or later node as 3 databases can be enough for database synchronization). Note that high availability is achieved using MariaDB Galera Cluster.

SSL

Allows to configure SSL certificates during install or config actions. When this option is specified, you will be asked to specify the locations for SSL certificate and SSL private key used for the certificate. There values will be used in mmid-management-web and mmid-web-server docker containers to support SSL.

MMABIS

Allows to configure MMABIS integraton during install or config actions. When this option is specified, you will be asked to enter MMABIS server, MMABIS username and password during configuration or installation.

Timeout

Allows to configure timeouts during install or config actions. When this option is specified, you will be asked to enter max session duration and management cleanup time during configuration or installation.

Janus

Allows to configure janus during install or config actions. When you select this option, you can configure the range of UDP ports that Janus will use, change the STUN server and set up NAT mapping.

Network mode

Allows to configure network mode during install or config actions. When you select this option, you will be asked what network mode to use: bridge or host.

Authorization mode

Allows to configure authorization mode during install or config actions. When you select this option, you will be prompted to choose an authorization mode: either basic or oauth. The default mode is basic. If you select oauth, you will also be asked to configure the OAuth secret and redirect URL.

Config

Option	Glossary
force	overwrite configuration files without additional confirmation
conf	pass configuration file with configuration options

Backup

Option	Glossary
skip-compress	do not compress database backup

Backup restore

Option	Glossary
backup-file	file from which to restore the database